From 1198cddf635cfa57767386c734cb91e7c1f52b93 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Thu, 22 Oct 2026 07:53:47 +0700 Subject: [PATCH] Document cross-host agent workflows in the Paseo skill (#7593) * docs(skills): explain cross-host agent workflows * docs(skills): shorten subagent waiting guidance --- skills/paseo/SKILL.md | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/skills/paseo/SKILL.md b/skills/paseo/SKILL.md index e92bdf91ee..cb08f49aa4 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. @@ -106,13 +127,9 @@ Schedules have the full list/inspect/update/pause/resume/run-once/log/delete sur ## Waiting -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. - -With finish notifications enabled, don't poll `list_agents` or `get_agent_status` to "check on" a running agent. The notification will tell you. +When you create or prompt a subagent, `notifyOnFinish` defaults to `true` and reports completion, errors, or permission requests, including across hosts. +Finish your turn and wait for that notification instead of polling. +If you want an explicit reply with `send_agent_prompt`, have the sender check `list_hosts` for the recipient’s server before setting `notifyOnFinish: false`. ## CLI semantics