puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-10-24 02:02:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0147edaaac705df00a9145fbaacc2cdfda54f49e
paseo/public-docs/mcp.md
T
Gustavo AmbrozioClaudemarvin-ambrozioMohamed Boudra
 0009a7e717 feat(workspaces): add background visibility (#5039) 
* 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>
2026-10-09 09:31:50 +01:00

202 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: MCP reference
description: Reference for the Paseo tools agents use to manage agents, workspaces, scripts, terminals, and schedules.
nav: MCP reference
order: 34
category: Orchestration
---
# MCP reference
[Enable Paseo tools](/docs/orchestration#get-started) to give agents this catalog. Ask for an outcome in natural language, or use the tool interfaces below.
## Configuration
| Setting | Default | Purpose |
| ----------------------------- | ------- | -------------------------------------------------- |
| `daemon.mcp.enabled` | `true` | Run the MCP server. |
| `daemon.mcp.injectIntoAgents` | `false` | Give agents launched by Paseo access to its tools. |
Depending on the provider, Paseo delivers tools through its native tool interface or MCP. The capabilities are the same. Start a new agent or reload an existing one after changing injection settings.
## Limit Paseo tools by provider
Use provider policies when different agent profiles should receive different Paseo tools. Enable
tool injection globally, then add `paseoTools` to the exact provider IDs you launch:
```json
{
"$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
"version": 1,
"daemon": {
"mcp": {
"enabled": true,
"injectIntoAgents": true
}
},
"agents": {
"providers": {
"codex-lead": {
"extends": "codex",
"label": "Codex Lead"
},
"codex-worker": {
"extends": "codex",
"label": "Codex Worker",
"paseoTools": {
"disabledTools": ["create_agent", "send_agent_prompt", "kill_agent"]
}
},
"codex-isolated": {
"extends": "codex",
"label": "Codex Isolated",
"paseoTools": {
"enabled": false
}
}
}
}
}
```
Run `paseo reload` after editing `~/.paseo/config.json`, then start a new agent or reload an
existing one. A running session keeps the catalog it received at launch.
Omitting `paseoTools` enables the complete catalog. Set `enabled` to `false` to remove the catalog,
or list exact tool IDs in `disabledTools` to remove selected tools. Custom profiles do not inherit
this policy from `extends`; configure each custom provider ID separately.
Browser tools still require browser tools to be enabled and a connected browser host. The
voice-only `speak` tool is separate from this policy.
This setting limits the catalog presented to an agent. It is not a security boundary for an agent
that can access the host through a shell.
## Mental model
Workspaces decide where work happens; agent parentage decides who owns the work.
- An agent that calls `create_agent` without a `workspaceId` gets a subagent in its own workspace.
- Passing a `workspaceId` places that subagent in another workspace without detaching it from its parent.
- A top-level MCP caller without a workspace gets a new local workspace.
- Create a workspace first when you need worktree isolation, a specific branch, or a pull request checkout.
MCP does not expose an agent-detach tool. Detaching is a manual user action in the app or CLI.
## Tools
### Agents
| Tool | Function |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_agent` | Create an agent, optionally placing it in an existing workspace with `workspaceId`. Use `initialPrompt` to start work; returns without waiting for completion. |
| `send_agent_prompt` | Send a prompt using `agentId` and `prompt`; returns without waiting for completion. |
| `get_agent_status` | Return the latest snapshot for an agent. |
| `list_agents` | List recent agents as compact metadata; `includeBackground: true` includes background work. |
| `cancel_agent` | Abort an agent's current run but keep the agent alive. |
| `archive_agent` | Soft-delete an agent and remove it from the active list. |
| `kill_agent` | Terminate an agent session permanently. |
| `update_agent` | Update an agent name, labels, or runtime settings such as mode/model/thinking/features. |
| `get_agent_activity` | Return recent agent timeline entries as a curated summary. |
| `set_agent_mode` | Switch an agent's session mode. |
Paseo agents receive finish, error, and permission notifications by default; set `notifyOnFinish: false` to disable them. External MCP clients use `get_agent_status` and `get_agent_activity` to check results.
### Workspaces
| Tool | Function |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_workspace` | Create a local or worktree-isolated workspace. Worktrees can branch off, check out a branch, or a PR. `background: true` hides it from default lists and the sidebar while preserving history and access by ID. Omission inherits the calling agent’s workspace setting, or defaults to false without a caller. |
| `list_workspaces` | List active workspaces and their directories and isolation. Use `includeBackground: true` to include background workspaces. |
| `rename_workspace` | Change the user-visible name of the current or specified workspace. |
| `archive_workspace` | Archive a workspace and the sessions it owns. |
For worktree isolation, `create_workspace` accepts the same useful choices as the app: branch off from a base, check out an existing branch, or check out a pull request. The worktree remains an implementation detail of the workspace lifecycle.
### Workspace scripts
These tools manage scripts configured in a workspace's `paseo.json`. Each requires an explicit `workspaceId`; start and stop also require the configured `scriptName`.
| Tool | Function |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `list_workspace_scripts` | List configured scripts with lifecycle, terminal, port, proxy URL, and health metadata. |
| `start_workspace_script` | Start a configured script through Paseo's managed launcher. |
| `stop_workspace_script` | Stop a running script through its supervised terminal. |
See [Git worktrees](/docs/worktrees#scripts-and-services) for `paseo.json` configuration.
### Terminals
| Tool | Function |
| -------------------- | ---------------------------------------------------------------------------- |
| `list_terminals` | List terminal sessions for one working directory or all working directories. |
| `create_terminal` | Create a terminal session for a working directory. |
| `kill_terminal` | Kill a terminal session. |
| `capture_terminal` | Capture plain-text output from a terminal session. |
| `send_terminal_keys` | Send text or special key tokens to a terminal session. |
### Schedules and heartbeats
Both use the same cron engine, but they have deliberately different interfaces.
| Tool | Function |
| ------------------- | ---------------------------------------------------------------------------- |
| `create_schedule` | Create a cron schedule that starts a new agent for each run. |
| `list_schedules` | List new-agent schedules managed by the daemon. |
| `inspect_schedule` | Inspect a schedule and its run history. |
| `pause_schedule` | Pause an active schedule. |
| `resume_schedule` | Resume a paused schedule. |
| `update_schedule` | Change a schedule's cron, prompt, agent settings, limits, or other settings. |
| `schedule_logs` | Return recent runs and output for a schedule. |
| `run_schedule_once` | Start one new-agent schedule run without changing its cron. |
| `delete_schedule` | Delete a new-agent schedule permanently. |
| `create_heartbeat` | Send a recurring cron-backed prompt into the current agent. |
| `delete_heartbeat` | Delete one of the current agent's heartbeats. |
MCP heartbeats are ephemeral: create or delete them. To change one, delete it and create a replacement. Pause, resume, update, inspect, logs, and run-once apply to new-agent schedules only.
### Agent profiles
| Tool | Function |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `list_profiles` | Return the host's saved agent profiles, including their notes and launch settings. Returns an empty list when none are configured. |
Before delegating, read each profile's `notes` and choose the profile the user named or the one that fits the task. See [Agent profiles](/docs/agent-profiles) for setup and example notes.
`create_agent` has no profile parameter and requires a `provider/model` pair. If the profile has no model, call `list_models` for its provider and choose an available model for the task before launching. Apply the chosen profile's values to the launch request:
| Profile field | `create_agent` field |
| ------------------------------- | --------------------------------------------------------------------------- |
| `provider` and optional `model` | `provider` as `provider/model`, using the saved or discovered model ID |
| `modeId` | `settings.modeId` |
| `thinkingOptionId` | `settings.thinkingOptionId` |
| `featureValues` | `settings.features` |
| `notes` | Selection guidance for the orchestrator; supply the task in `initialPrompt` |
Omit absent optional settings. If no profile fits, use provider discovery to choose available settings.
### Providers
| Tool | Function |
| ------------------ | ----------------------------------------------------------------- |
| `list_providers` | List configured agent providers, availability, and modes. |
| `list_models` | List models for an agent provider. |
| `inspect_provider` | Inspect compact provider capabilities and draft feature settings. |
### Permissions
| Tool | Function |
| -------------------------- | ------------------------------------------------- |
| `list_pending_permissions` | Return pending permission requests across agents. |
| `respond_to_permission` | Approve or deny a pending permission request. |
### Browser
Browser automation is opt-in and adds tools for opening tabs, reading pages, clicking, typing, and taking screenshots. See the [Browser tools reference](/docs/browser-tools).
### Voice
| Tool | Function |
| ------- | ----------------------------------------------------------------------------------------- |
| `speak` | Speak text through daemon-managed voice output. Available only in voice-enabled sessions. |
Reference in New Issue View Git Blame Copy Permalink