0009a7e717
* feat(server): let clients create internal agents The daemon's own branch-name and commit-message generators run as internal agents: never persisted, listed, flagged, announced, or seen by plugin lifecycle hooks. Nothing outside the daemon could ask for one, because the wire config schema strips `internal` and the agent.create transform re-pins it. A plugin that runs a one-turn helper per event therefore left an archived session in History every time. Add an optional `internal` flag to `create_agent_request` (inherited by `agent.create.request`), copy it onto the config in the session's create path, and skip provider session persistence for it like the generators do. The client SDK forwards the flag on both creation paths and gates it once on `server_info.features.internalAgents`. Two daemon paths assumed every agent is public and had to follow: `resolveAgentIdentifier` now accepts a live agent by exact id, since the id set it matched against came from listings that exclude internal agents and left `wait_for_finish` answering "Agent not found"; and archiving an internal agent now closes it without writing the record that `registry.applySnapshot` used to leave behind, so `autoArchive` does not accumulate hidden files on disk. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(server): keep internal agents whole through failure, archive, and wait Review follow-ups for internal agents: - A create that fails after the runtime is registered now closes the internal agent before rethrowing, so a hidden runtime cannot outlive the failed request. Public agents keep today's behaviour. - Archiving an internal agent cascades to attached children like any parent. cascadeArchiveChildren takes the parent record instead of reading it back from storage, where an internal agent never is. - The archived snapshot and last message of an internal agent stay readable by exact id for ten minutes, so create-then-waitForFinish returns the finished turn whether the wait lands before or after an auto-archive. Storage plays that role for public agents. - The internal-agent e2e scenarios live in the existing create_agent_request lifecycle suite rather than a new file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(server): cascade to live internal children and keep a failed internal create's worktree until it closes Internal children never reach storage, so the parent archive cascade scans live agents for them as well. A failed internal create now clears the created id only after the runtime is archived, so worktree cleanup cannot delete the directory under a runtime that would not close. Stored agent payloads carry lastError, so a retained failed helper reports its error through wait_for_finish instead of the generic message. * feat(cli,mcp): expose internal agents and document --no-wait paseo run gains --internal and create_agent gains internal, both forwarded to the create request. --no-wait becomes the documented spelling for returning immediately, matching paseo send; --background and --detach stay as hidden aliases under COMPAT tags. * test: follow the --no-wait rename and stub getRetiredInternalAgent * feat: list internal agents on request and add internal workspaces Internal agents stay hidden by default, but a caller can now ask for them: `fetch_agents_request` takes `filter.includeInternal`, snapshots carry `internal: true`, and `paseo ls --internal` shows them in an INTERNAL column. The app never passes the flag. Workspaces get the same flag. `workspace.create.request` with `internal: true` persists a hidden workspace: listings, update subscriptions, sync reads, empty-project counting, open-by-path, MCP `list_workspaces`, and plugin workspace hooks all skip it unless the caller opts in with `filter.includeInternal`. Every agent created inside an internal workspace is internal and unpersisted; AgentManager applies that from the workspace id before the plugin hook so creators cannot opt out. Archive and shutdown enumerate internal agents so nothing inside an internal workspace outlives it. Surfaces: `paseo workspace create --internal`, `paseo workspace ls --internal`, `paseo run --internal --new-workspace`, MCP `create_workspace({ internal })`, SDK `workspaces.create({ internal })` and `list({ filter: { includeInternal } })`. Clients gate on `features.internalWorkspaces`. Co-Authored-By: Claude <noreply@anthropic.com> * feat(workspaces): add background visibility with inherited creation defaults * fix(cli): resolve workspace callers on the selected daemon * test(workspaces): keep caller integration coverage in server suite * test(cli): exercise workspace callers through CLI integration harness * test(mcp): remove obsolete execution flags from browser fixtures --------- Co-authored-by: marvin-ambrozio <marvin@gustavo.eng.br> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>
4.2 KiB
title, description, nav, order, category
| title | description | nav | order | category |
|---|---|---|---|---|
| Orchestration | Coordinate agents across providers and machines, delegate work, and keep tasks moving with schedules and heartbeats. | Overview | 30 | Orchestration |
Orchestration
Paseo lets your coding agents coordinate other agents, split work across providers and machines, and keep tasks moving automatically.
You can also start and supervise each task yourself in the desktop app. Run parallel tasks in separate worktrees, inspect their diffs, and test each app in a terminal and browser before choosing what to merge.
What your agents can do
- Choose providers and models: launch other agents using any provider and model configured on the host.
- Delegate and parallelize: split research, implementation, and review between agents, including agents from different providers.
- Communicate with each other: agents can send prompts to other agents by ID to ask questions, share findings, or request work.
- Coordinate ongoing work: check progress, stop tasks, and collect results.
- Create workspaces and worktrees: give independent changes their own working directories.
- Work across machines: use the CLI to launch and manage agents on another reachable Paseo host.
- Choose by specialty: use agent profiles and their notes to select settings for UI work, planning, or reviews.
- Create schedules: run a prompt in a new agent at specified times.
- Create heartbeats: prompt the same agent periodically to continue its task.
Get started
Use built-in Paseo tools or the CLI. Both let an agent launch and coordinate workers.
Built-in Paseo tools (MCP)
Enable Paseo tools so agents running inside Paseo can manage agents and workspaces on their host directly.
- Open Settings → your host → Agents.
- Turn on Enable Paseo tools. Tool injection is off by default.
- Start a new agent, or reload an existing agent so it receives the tools.
- Ask:
Use Paseo to launch a second agent to review this branch. Have it report potential bugs without changing files, then summarize its findings.
The worker appears in the Subagents track near the composer. Open it to follow the conversation. Your main agent receives a notification when the worker finishes, and you can keep talking while it works.
See the MCP reference for tool configuration and the full catalog. Orchestration skills are optional reusable workflows.
CLI
Agents with shell access can also use the Paseo CLI. This route does not require enabling tool injection. With Paseo installed, a running host, and Codex configured:
paseo run --provider codex --no-wait \
"Review this branch without changing files"
paseo ls -a
The first command starts a worker and returns immediately; the second lists archived and background agents as well. When a Paseo agent runs the command, the worker becomes its subagent in the same workspace. From your own terminal, it starts in a new local workspace.
See the CLI reference for follow-ups, output, worktrees, and remote hosts.
Pick settings once with profiles
Save a provider, model, thinking level, mode, and available feature settings as an agent profile, then select it in one click when creating an agent.
Add When to use notes so an orchestrating agent can choose a profile for the task: UI work, planning, or independent review. Create profiles and write delegation notes.