From 808aa7d7b1e068e7ea02b4cfe3d5c090aa94cc0a Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 21 Oct 2026 18:30:06 +0200 Subject: [PATCH] docs(skills): explain cross-host agent workflows --- skills/paseo/SKILL.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/skills/paseo/SKILL.md b/skills/paseo/SKILL.md index e92bdf91ee..0125715b47 100644 --- a/skills/paseo/SKILL.md +++ b/skills/paseo/SKILL.md @@ -1,10 +1,31 @@ --- name: paseo -description: Paseo reference for managing projects, workspaces, workspace scripts, agents, schedules, and heartbeats. +description: Paseo reference for managing hosts, projects, workspaces, workspace scripts, agents, schedules, and heartbeats. --- Paseo is a remote daemon that manages coding agents, terminals. Control it through MCP tools or the CLI. +## Connected hosts + +Call `list_hosts` to discover the calling daemon (`self`) and its registered destinations (`hosts`). Use a destination's `serverId` for tool calls; labels are display names. + +`create_workspace`, `list_workspaces`, `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, and `list_agents` accept `serverId`. Omit it for the calling daemon. Other MCP tools operate on the calling daemon. + +Keep an agent's `{ serverId, agentId }` together. For example, call `send_agent_prompt` with: + +```json +{ "serverId": "srv_build", "agentId": "agent_123", "prompt": "Continue", "notifyOnFinish": true } +``` + +Remote paths and workspace IDs belong to the destination. Remote `list_agents` has no caller-directory default; pass `cwd` to filter it. + +Manage registrations through the CLI; use the returned `registrationId` for updates and removal: + +```bash +paseo --host localhost:6768 host add localhost:6779 --label build +paseo --host localhost:6768 host ls --json +``` + ## Projects Manage the daemon's project registry through the CLI: @@ -57,7 +78,7 @@ paseo script stop [--cwd | --workspace ] Initial runtime settings live under `settings`: `modeId`, `thinkingOptionId`, and provider-specific `features`. Agent profiles are the preferred source for these values. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }` when creating the agent. -Agent-scoped creation always creates your subagent. Omit `workspaceId` to use your current workspace; pass a workspace returned by `create_workspace` for isolated delegation. Placement never changes parentage. +Agent-scoped creation always creates your subagent. On your own host, omit `workspaceId` to use your current workspace. On another host, first list or create a workspace with that `serverId`, then pass its `workspaceId` and the same `serverId` to `create_agent`. Placement never changes parentage. Detach is an explicit user action in the subagents track, not an agent tool. A cross-workspace child remains your subagent even though it also appears as a normal tab in its workspace. @@ -110,7 +131,11 @@ Agents take time — 10–30+ minutes is routine. Favor asynchronous workflows. `create_agent` returns after startup. Agent-scoped `send_agent_prompt` returns after queue admission; provider dispatch follows after two quiet seconds. Top-level sends return after dispatch acknowledgement. Top-level callers have no parent callback; observe completion through status/activity tools or SDK/RPC subscriptions and wait APIs. -For agent-scoped `create_agent` and `send_agent_prompt`, `notifyOnFinish` defaults to `true`. The caller receives the target’s completion, error, or permission report automatically, including its last response. Finish your turn with the result for automatic reporting. For a workflow that reports explicitly with `send_agent_prompt`, set `notifyOnFinish: false` when assigning the task. Paseo supplies caller identity for agent-scoped tools and CLI agent context; use that supplied identity. +For agent-scoped `create_agent` and `send_agent_prompt`, `notifyOnFinish` defaults to `true`. The caller receives the target’s completion, error, or permission report automatically, including its last response. Finish your turn with the result for automatic reporting. Paseo supplies caller identity for agent-scoped tools and CLI agent context; use that supplied identity. + +Completion notifications return across hosts without a reverse registration. Explicit cross-host `send_agent_prompt` messages need the recipient's host registered on the sender's daemon. Registering A → B does not let B address A over that connection; reverse connection reuse is not implemented. Before assigning explicit reporting with `notifyOnFinish: false`, have the sender check `list_hosts` for the recipient's server. + +Remote finish notifications report idle, not an exact turn. A caller-daemon restart or route loss ends the pending wait; query the child’s status or activity before deciding whether to send another prompt. With finish notifications enabled, don't poll `list_agents` or `get_agent_status` to "check on" a running agent. The notification will tell you.