Module agents 

The agents__* family - one address space for every forge session.

A target is a slot: (org, project, label), with lead reserved for a project’s own agent. Three verbs reach any slot from any session; the rest act on the caller’s own project and are lead-only.

Re-exports

use std::sync::Arc; 🔒

use forge_sdk::mcp::tool::Tool; 🔒

use forge_sdk::mcp::tool::ToolInput; 🔒

use forge_sdk::mcp::tool::ToolOutput; 🔒

use crate::SessionSlot; 🔒

use crate::mcp::agents::facade::AgentDispatcher; 🔒

use crate::mcp::agents::target::AgentTarget; 🔒

use crate::mcp::agents::target::TargetError; 🔒

use crate::mcp::peers::facade::WorkspaceFacade; 🔒

use crate::mcp::peers::types::MessageId; 🔒

use crate::mcp::peers::types::PeerStatus; 🔒

use crate::mcp::peers::types::WrappedKind; 🔒

use crate::mcp::peers::types::WrappedPrompt; 🔒

use crate::mcp::workers::facade::DespawnOutcome; 🔒

use crate::mcp::workers::facade::WorkerCapSource; 🔒

use crate::mcp::workers::facade::WorkerDespawnError; 🔒

use crate::mcp::workers::facade::WorkerFacade; 🔒

use crate::mcp::workers::facade::WorkerSpawnError; 🔒

use crate::mcp::workers::facade::WorkerUpdateError; 🔒

use crate::protocol::SessionChoice; 🔒

Modules

facade

The seam between the merged agents__* family and the two engines it drives. Every verb that takes a target resolves it here, so the routing rule lives in one place rather than at each call site.

target

The address an agents__* call names.

Structs

Capacity 🔒

agents__capacity - lead-only aggregate read of the caller’s project worker capacity. One JSON object rather than the per-worker snapshots agents__list returns.

Despawn 🔒

agents__despawn - lead-only. Closes a worker by label and cleans up its git worktree. A clean worktree is removed; a dirty one (uncommitted/untracked or unpushed commits) blocks the despawn unless force.

DespawnArgs 🔒

Handoff 🔒

agents__handoff - hand this seat over to a fresh session, from the session itself.

HandoffArgs 🔒

List 🔒

agents__list - every seat you can address, optionally narrowed to one project. No target args.

ListArgs 🔒

SendMessage 🔒

agents__send_message - one verb for every send, to any seat.

SendMessageArgs 🔒

Spawn 🔒

agents__spawn - lead-only. Allocates a new session in the caller’s project, threading charter through the new session’s system-prompt addendum, then returns the assigned session_id and tag (forge:worker:<label>).

SpawnArgs 🔒

TargetArgs 🔒

Update 🔒

agents__update - lead-only. Revises the stored charter, kick and resume_kick of an EXISTING worker, keyed by (project_key, label) exactly as agents__spawn persisted it.

UpdateArgs 🔒

Whoami 🔒

agents__whoami - the caller’s own slot and identity. No args.

Functions

add_lead_tools 🔒

Attach the four lead-only verbs to an existing McpServerBuilder. Each acts on the caller’s own project, so a worker has no project to act on and is not offered the surface.

add_shared_tools 🔒

Attach the three any-caller verbs to an existing McpServerBuilder.

build_server

Build a standalone forge MCP server carrying the whole agents__* family as a lead sees it. The wire-conformance harness drives the surface through this against mock facades.

canonical_spawn_families 🔒

Validate and canonicalise a spawn or update mcp_families argument: names in wire order, de-duplicated; an empty list resolves to None (every family) for a spawn.

format_despawn_error 🔒

format_spawn_error 🔒

format_update_error 🔒

json_output 🔒

row 🔒

A snapshot row: the address to pass back to agents__send_message, then whatever the engine that produced the snapshot knows about the seat.

sender_identity 🔒

The name and org an envelope carries for the session that sent it, derived from that session’s own slot: the project for a project’s own agent, project/label for a worker, with the org beside it.

slot_json 🔒

The slot an agent is addressed by, which is the shape every row and every response carries.

target_error_message 🔒

LLM-facing explanation of a target that did not resolve. Names the reachable set, because a target that refuses is usually a typo.

tool_error 🔒