# Diagrams Below are exportable ASCII diagrams (copy/paste) covering architecture, runtime flow, context packing, skill flow, tool policy approvals, telemetry, and V2 multi-agent slots. *** ### 1) System overview (modules + boundaries) ``` +------------------------------+ | Channels / Inputs | | CLI | Telegram | Others | +--------------+---------------+ | v +--------------------------+ | openminion-controlplane | | adapters + routing | +------------+-------------+ | v +-------------------------------------------------------------------+ | openminion-runtime | | orchestrates turn: session -> context -> llm -> policy -> tool | +----+-----------+-----------+------------+------------+-------------+ | | | | | v v v v v +---------+ +---------+ +--------+ +---------+ +--------+ | session | | context | | llm | | policy | | tool | +----+----+ +----+----+ +---+----+ +----+----+ +---+----+ | | | | | | | | | +-------------------+ | | | | | | | | | +---------v---------+ | | | | | tool plugins | | | | | | exec/browser/... | | | | | +-------------------+ | | | +--------------------+ | | v v +---------+ +-----------+ +-----------+ +-----------+ | compress| | skill | | memory | | identity | +---------+ +-----------+ +-----------+ +-----------+ (optional sidecar) +-------------------+ | openminion-telemetry | +-------------------+ ``` *** ### 2) Runtime “turn” flow (single turn, potentially multiple packs) ``` User Input | v controlplane.receive() | v runtime.run_turn(session_id, agent_id) | +--> session.next_turn_id() -> turn_id +--> trace_id = uuid() +--> session.append(user.message) | +--> (optional) identity.get_capsule() +--> (optional) memory.retrieve() +--> (optional) skill.shortlist() +--> (optional) skill.select + skill.expand() | v PACK LOOP (pack_id = t{turn_id}-pN) | +--> context.build_pack(...) | | | +--> (optional) telemetry.emit(context.pack) | +--> llm.complete(prompt_view) | | | +--> (optional) telemetry.emit(llm.usage) | +--> if LLM returns TOOL_CALL: | session.append(tool.request) | policy.authorize() | | | +--> NEEDS_APPROVAL --> return PendingAction to controlplane | | | +--> ALLOW --> tool.execute() --> session.append(tool.result) --> loop | | | +--> DENY --> session.append(tool.result: denied) --> (loop or stop) | +--> else FINAL_ANSWER: session.append(agent.message) compress.maybe_summarize() telemetry.emit(turn.outcome) return response ``` *** ### 3) Context packing (how PromptView is assembled under budget) ``` Inputs: - identity capsule (small) - session summary (small) - recent messages (bounded K) - memory snippets (bounded top-N) - skill cards shortlist (bounded top-N) - selected skill excerpt (optional, bounded) - tool digest (minimal) context.build_pack() | v [1] establish budgets total_budget reserved_budget (system + tool overhead) available_budget | v [2] build sections in priority order 1 system 2 identity 3 task directive (latest user intent) 4 summary 5 recent messages 6 memory snippets 7 skill cards 8 selected skill excerpt (if any) 9 tool digest | v [3] enforce caps - trim sections by rules - drop low priority sections if needed - record truncations/drops | v PromptView (bounded) -> sent to LLM | +--> telemetry: ContextPackReport (tokens, drops, truncations, composition) ``` *** ### 4) Skill integration flow (many skills → shortlist → one expanded) ``` All skills (many SKILL.md) | v openminion-skill.index -> SkillCards (tiny metadata) | v skill.shortlist(query=intent, tools_available, N) -> top SkillCards | v context.attach_skill_cards(SkillCards) (bounded) | v brain/runtime selects skill_id or NONE | +--> if selected: | skill.expand(skill_id, goal, max_tokens=M) | context.attach_selected_skill(excerpt) (bounded) | session.append(skill.selected) | v LLM uses skill excerpt to plan + call tools reliably ``` *** ### 5) Tool execution + policy approvals (approve once / window / forever) ``` LLM TOOL_CALL (tool_name, args) | v runtime -> session.append(tool.request) | v policy.authorize(tool_name, risk, scopes, args_summary) | +--> ALLOW | | | v | runtime -> tool.execute() | | | v | session.append(tool.result) | | | v | back to pack loop | +--> NEEDS_APPROVAL | | | v | return PendingAction: | - approve once | - approve for time window | - approve until revoked | - deny | +--> DENY | v session.append(tool.result: denied) (runtime loops for alternative plan OR stops based on config) ``` *** ### 6) Telemetry flow (context-focused, per pack + per turn) ``` context.build_pack(pack_id) | +--> emit: context.pack | - token budget + usage estimate | - section breakdown | - drops/truncations + reasons | llm.complete(pack_id) | +--> emit: llm.usage | - actual tokens (if provided) | - latency, model/provider | runtime ends turn | +--> emit: turn.outcome - packs used - tool calls count - status ok/retry/error/blocked - total latency Sinks: - sqlite (default) - jsonl (debug) - otel (future) ``` *** ### 7) Session durability (full history preserved; prompt stays compact) ``` Session Store (SQLite, append-only) - stores ALL events forever (or retention policy) - user/agent messages - tool req/result - skill selection refs - summaries - memory refs PromptView (context output) - only selected subset: identity + summary + recent window + top memory + skill card(s) + tool digest - bounded by token budget => Full history is preserved in session, but only compact view is sent to LLM. ``` *** ### 8) V2 slots (daemon + registry + local/remote + multi-agent) ``` +---------------------+ | openminion-registry | | discover agents | +----------+----------+ | +-----------+-----------+ | | v v +-------------------+ +-------------------+ | agent daemon A | | agent daemon B | | openminion-runtime| | openminion-runtime| +---------+---------+ +---------+---------+ | | +----------+------------+ | v openminion-a2a (V2) - local queue (V1) - remote RPC/MCP (V2) - auth/signing (V2) ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortensor.network/community-and-ecosystem/products-and-agents/pyclaw/diagrams.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.