Skill: guytogay/session-coordinator (version 3.0.1)

--- name: session-coordinator version: 3.0.1 description: "Async Process Pattern for OpenClaw agents. Core rule: main process must never block. Use when: (1) agent should stay responsive to user dialog at all times, (2) long/uncertain operations must not block the main session, (3) multi-node coordination requires clear separation between dialog/dispatch (main) vs execution (subagent). Triggers on: async mode, main process blocking, spawn decision, long operation handling. --- # Session Coordinator Skill v3.0.1 — Main Process Never Blocks ## Core Principle **Main process = dialog + dispatch. Never block.** The main goal is responsiveness — the main process must never be blocked, stalled, or made unresponsive. This is not "never execute." It is "never block." A blocked main process shows as: typing indicator disappears, user cannot get a response, session appears frozen. ## Decision Framework ### Spawn when (blocks or uncertain): - Remote operations (SSH, remote API calls) - git push/pull/clone operations - Any operation involving network I/O - Operations with unknown duration - Operations that need isolation (fail without affecting main session) - **State-modifying operations**: file write, git commit, package publish, deploy, or any operation that changes persistent state on disk or remote - Anything requiring waiting for external result - **Spawn must always include a `label` parameter** (see Spawn Label Convention below) ### Execute directly when (fast, non-blocking AND same topic): - Local scripts that run in <1 second - Reading files, writing docs, writing code - Dialog, judgment, approval, reasoning - Quick system calls (RAM, disk, process status) - Must NOT involve network I/O (SSH, HTTP, remote calls) - Must be same topic as current conversation ### Self-check signal: "If my typing indicator disappeared, am I being blocked right now?" If a question or request is on a DIFFERENT topic, spawn it — do not handle it directly even if it seems fast. Different topic = different subagent. --- ## Spawn Mode v3 — Default: session thread **Default spawn mode is `mode="session"` with `thread=true`.** - Use `mode="session"`, `thread=true` for most tasks (interactive, multi-step, or uncertain duration) - Use `mode="one-shot"` only when explicitly instructed or when the task is trivial and guaranteed single-turn - Never assume `mode="run"` (run = detached, no result push = unreliable) ```python # ✅ Default: session thread (most tasks) spawn(task="task-description", mode="session", thread=true, label="task-label") # ✅ Explicit one-shot: only when scope is trivially bounded spawn(task="task-description", mode="one-shot", label="task-label") # ❌ Don't use run unless you explicitly need detached/no-result spawn(task="task-description", mode="run") ``` --- ## Timeout Guidelines Use these as a guide to set `runtime` when spawning: | Tier | Duration | Examples | |------|----------|----------| | **fast** | ~5 min | file ops, single API call, config check, quick test | | **medium** | ~15 min | git operations, moderate build, moderate data processing | | **long** | 60 min+ | large clones, heavy builds, multi-step deployments, data migration | ```python # Fast task — 5 min timeout spawn(task="check service status", runtime="fast", label="service-status-check") # Medium task — 15 min timeout spawn(task="clone repository and run tests", runtime="medium", label="repo-test") # Long task — 60 min timeout spawn(task="full deployment pipeline", runtime="long", label="deploy-pipeline") ``` --- ## Spawn Label Convention When spawning a subagent, **always include a descriptive `label` parameter**: - Use dashes, not spaces (e.g., `project-config-sync` not `project config sync`) - Use generic, descriptive names only — never specific project names, IPs, hostnames, or user names - Label should reflect the actual task category or action **Generic placeholder examples:** - `project-name` → `repo-name` or `project-alfa` - `192.168.x.x` → `remote-host` or `node-alpha` - `user@host` → `admin-user` or `service-account` ```python # ✅ Good: generic, dashes, descriptive spawn(task="sync config to remote node", label="config-sync") spawn(task="run test suite for module", label="test-suite") spawn(task="deploy service to environment", label="service-deploy") # ❌ Bad: spaces, specific names, cryptic spawn(task="...", label="proj1") # too short, no dashes spawn(task="...", label="192-168-1-1") # specific IP — not allowed spawn(task="...", label="johns-task") # specific user name — not allowed spawn(task="...", label="foo-bar-v2") # specific project codename — not allowed ``` When the user says "stop that thing", look at `subagents list` and match the label to find the right subagent to stop. --- ## Lifecycle Management ### Auto-Timeout - Subagents run with a defined `runtime` timeout (fast/medium/long) - If the subagent exceeds its timeout without a result, it is considered stalled - Do NOT manually extend timeouts unless user explicitly asks ### Done Signals A subagent can be safely let timeout (or can terminate early) when: 1. **user says "done"** — user has indicated the task is complete or no longer needed 2. **Context switches** — user has moved to a different topic or task; the previous subagent is no longer relevant 3. **Explicit cancel** — user says "stop", "cancel", "forget it" ### What to do when done signal fires: - Do NOT try to salvage a timed-out subagent - Do NOT restart the same task unless user explicitly asks - Acknowledge the signal and move on --- ## Result Writing ### Important results → MEMORY.md After a subagent completes, if the result is **significant** (decision made, lesson learned, important output, state change), write it to `MEMORY.md` in the main session. ```markdown ## [Date] Task Result - Task: task-description - Outcome: what happened - Key decision/learning: ... ``` ### Daily logs → memory/YYYY-MM-DD.md Routine subagent work should be logged in the daily memory file: ```bash # Create/update daily log memory/2026-04-06.md ``` Include: task label, what was done, key result. Keep it concise. --- ## Spawn Is Transparent **Do not announce to user when you are spawning a subagent.** - Do NOT say "I'm spawning a subagent to handle this..." - Do NOT say "Let me dispatch this to a background agent..." - Just spawn it and continue the dialog naturally user does not need to know the execution architecture. The subagent handles the work; you handle the conversation. --- ## Role Definition | Responsibility | Main Process | Subagent | |----------------|-------------|----------| | User dialog | ✅ | ❌ | | Task dispatch | ✅ | ❌ | | Result production | ❌ | ✅ | | Result delivery to user | ✅ | ❌ | | Decision making | ✅ | ❌ | | Status coordination | ✅ | ❌ | | Fast local operations | ✅ | ❌ | | Blocking operations | ❌ | ✅ | --- ## Execution Model ### Blocked = Wrong If the main process blocks, the pattern has failed — regardless of whether the task eventually completes. ### Spawn and Continue ```python # ❌ Wrong — blocks main process, typing disappears exec("ssh remote-host ...") subprocess.run(...) # ✅ Correct — non-blocking, typing stays active spawn(task="remote operation description", runtime="medium", mode="session", thread=true, label="remote-task") ``` After spawning: continue dialog with user. Do NOT wait. Results arrive via push event. ### Fire-and-Forget - Spawn with full task description and runtime estimate - Do NOT estimate how long it takes - Do NOT poll for status - Continue dialog - Report result when delivered --- ## Multi-Node Coordination Each node runs its own subagents. Nodes do not delegate to each other's subagents. Coordination between nodes goes through whatever inter-node protocol is configured for that setup. --- ## Anti-Patterns | Anti-Pattern | Why Wrong | Correct | |-------------|---------|---------| | "Let me check..." + exec in main | Blocks typing | Spawn subagent | | Waiting for subagent result before responding | Blocks dialog | Continue, report later | | Direct remote operations in main process | Blocks | Spawn | | Spawning to avoid doing work (not to avoid blocking) | Misuse of pattern | Execute directly if fast | | All work spawn, nothing direct | Over-interpretation | Fast ops = direct | | Announcing the spawn to user | Noise, breaks flow | Spawn silently, continue | | Using specific IPs/hostnames in labels | Privacy leak | Use generic names | --- ## Workflow Summary 1. **User request arrives** 2. **Assess: will this block?** (slow / uncertain / remote = spawn; fast / local / dialog = direct) 3. **If spawn → spawn with session thread + appropriate runtime + generic label** 4. **If direct → execute and respond now** 5. **Result arrives via push → report to user** 6. **If result is significant → write to MEMORY.md or daily log** 7. **Self-check: is typing indicator still showing?** --- ## Key Insight "Never block" is the rule. "Never execute" is a misreading of the rule — fast operations should be direct because they do not block. The typing indicator is the visible signal: if it disappears, something is blocking. --- ## Privacy Notes All examples in this skill use **generic placeholders only**. No specific project names, IPs, hostnames, user names, service names, or AI names appear in any example. This protects both operational security and privacy.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)