Module facade 

Narrow workspace-state surface the workers MCP Tool impls consume. Trait + mock for unit-testing the Tool impls without spinning up a real Workspace. Mirrors crate::mcp::peers::facade.

The production impl is ProdWorkerFacade (below).

Re-exports

use std::sync::Arc; 🔒

use std::sync::Weak; 🔒

use forge_agent::client::SpawnFailureKind; 🔒

use forge_primitives::WorkerStatus; 🔒

use crate::SessionSlot; 🔒

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

use crate::protocol::Command; 🔒

use crate::protocol::SessionChoice; 🔒

use crate::protocol::WorkerSpawnReply; 🔒

use crate::workspace::ResumeTarget; 🔒

use crate::workspace::Workspace; 🔒

Structs

CallerProject

Caller’s project + lead-or-not flag. Returned by WorkerFacade::caller_project.

MockWorkerFacade

Mock for unit-testing the four Tool impls. Captures every dispatched call into a Vec so tests can assert “tool X dispatched spawn with these args” without spinning up a real Workspace.

ProdWorkerFacade

Production impl. Holds a Weak<Workspace> so construction doesn’t close a strong cycle through the Workspace -> bridge -> MCP -> Tool -> facade -> Workspace path. Every method starts with upgrade() and short-circuits when the workspace has been dropped (only possible during shutdown).

RecordedProjectDelivery

One captured deliver_worker_prompt_to_project call: the address it was given, and the prompt it carried.

WorkerCapacity

Point-in-time worker-capacity read for the caller’s project: the cap the spawn path enforces, how many workers are live under it, and where the cap came from. Produced by WorkerFacade::capacity.

Enums

DespawnOutcome

Synchronous outcome of despawn_worker - the success-shaped half of a Command::DespawnWorker. Gating + dispatch errors are the Err arm of the result; these two variants are what the agents__despawn Tool renders as status: "despawned" | "blocked".

WorkerCapSource

Whether a project’s worker cap came from its [[orgs.projects]] max_workers override or the built-in default.

WorkerDeliverError

Error from deliver_worker_prompt. A prompt not yet taken is not one: a worker that never finishes connecting leaves a parked message that Workspace::expire_parked_for_slot acknowledges back to its sender.

WorkerDespawnError

Synchronous error from despawn_worker. Gating (lead-only, non-empty label) happens before dispatch; UnknownLabel is surfaced from the handler’s NotFound, and DispatchFailed from its Failed.

WorkerLeadDeliverError

Error from deliver_prompt_to_lead. The caller wants to send a prompt back to its lead via the reserved "lead" addressing keyword.

WorkerSpawnError

Synchronous error from spawn_worker. All gating happens before the workspace dispatch is even issued.

WorkerTargetStatus

A delivery’s own answer, and it has one shape: the prompt was accepted (handed to the target’s session queue, held for its turn end, or parked for its connect). A prompt that reached no session is an error instead, so “accepted” is the whole of what this claims.

WorkerUpdateError

Synchronous error from update_worker. Gating (lead-only, non-empty label, at least one supplied field) happens in the tool before the call, so these are the outcomes only the store can decide.

Constants

LEAD_LABEL

The label reserved for a project’s own agent. A caller addresses it as the label of an agents__send_message target; agents__spawn rejects the label so no live worker can shadow the keyword. Reserved label for a project’s own agent, addressed as the label of an agents__send_message target. agents__spawn rejects it so no live worker can shadow the keyword.

Traits

WorkerFacade

The narrow workspace-state surface workers MCP Tool impls depend on.

Functions

await_delivery 🔒

Await a delivery’s acceptance answer, mapping it to the caller’s ack. The handler answers Ok(()) once the prompt was accepted and Err(reason) when nothing could take it, so this is the one place the ack is decided.

classify_worker_spawn_failure

Heuristic mapping from a raw spawn-error message + the worker’s is_git_repo_at_spawn flag to a typed WorkerSpawnError.

discard_refused_worktree 🔒

Undo the worktree a refused spawn’s ensure_worker_worktree step created, so a refusal strands neither worktree nor branch. ensured is None when this spawn never touched a worktree.

refused_delivery 🔒

The refusal for a label that cannot take a delivery: None when a live worker matches, else the error naming which absence this is - a label that is not in the project’s pool at all, or a row kept because the worker crashed. The two read very differently to the sender: one says “check the label”, the other “respawn it”.

validate_worker_label 🔒

The label rules a spawn must pass wherever it enters: empty, the reserved lead, and a slash. Shared by the tool’s validation and the spawn handler so the MCP tool, the command bus and the socket cannot disagree about which labels mint a worker.

validate_worker_spawn 🔒

Validation chain shared by the production and mock spawn_worker impls so tests exercise the real rules rather than a hand-copied duplicate. is_lead is the resolved caller role.

Type Aliases

RecordedSpawnCall 🔒

A captured MockWorkerFacade::spawn_worker call: (caller, label, resolved charter, kick, resume_kick, interactive, resume_session, mcp_families, cwd).

RecordedUpdateCall 🔒

A captured MockWorkerFacade::update_worker call: (caller, label, charter, kick, resume_kick).