| name | pi-agent-dispatch |
| description | Sibling Pi extension that registers in-pi agent-as-tool dispatch, capability composition, real-check execution, attested commits, and the bounded north-star work-order loop. Use when authoring agent specs, granting tool capabilities, running deterministic checks, committing with writer attestation, loading config-declared composite operations, or driving end-to-end work-orders through their bounded retry loop.
|
<tools_reference>
Write a new .agent.yaml spec to the agents tier. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer. The written file is AJV-validated against AgentSpec before persisting.
Author a privileged JIT-agent spec — declares input, prompts, tools grant, output schema, contextBlocks.
| Parameter | Type | Required | Description |
|---|
name | string | yes | Agent name (becomes .agent.yaml filename + AgentSpec.name). |
spec | unknown | yes | AgentSpec object body (will be serialized to YAML). Must conform to AgentSpec shape. |
writer | object | yes | DispatchContext.writer payload; see pi-context/src/dispatch-context.ts for the discriminated union. |
Dispatch a privileged JIT-agent as a typed tool call. Loads the named .agent.yaml, compiles with input, composes the tool grant (intersection of caller's parentGrant and the agent's requestedGrant), and executes via pi-jit-agents executeAgent (clamp enforces child ⊆ parent at dispatch boundary).
Dispatch a typed sub-agent with scoped capability grant.
| Parameter | Type | Required | Description |
|---|
spec_name | string | yes | Name of the agent spec to load (resolves to .agent.yaml searched across the substrate agents/ dir, then ~/.pi/agent/agents/, then the bundled pi-workflows agents). |
input | unknown | yes | Typed input passed to the agent's compileAgent context. |
parent_grant | array | no | The caller's own tool grant. Default-empty. |
requested_grant | array | no | The grant requested for the dispatched sub-agent. Will be clamped to the intersection with parent_grant. |
max_tokens | number | no | Max tokens for the LLM call. Defaults to 1024. |
Run the deterministic real-checks declared on a work-order (build/check/test exit + runtime-demo + adversarial-probe). Returns a structured RealCheckResult. NEVER LLM self-report; verdict is the actual exit code.
Run a work-order's declared real-checks for verdict gating.
| Parameter | Type | Required | Description |
|---|
work_order_id | string | yes | ID of the work-order whose real_check_criteria to run (e.g. 'WO-NNN'). |
max_check_time_ms | number | no | Max total time per check in milliseconds. Defaults to 600000 (10 minutes). |
Stage declared files + invoke git commit with DispatchContext writer.kind=agent attestation footer. Husky pre-commit runs as backup gate; never bypass (--no-verify forbidden per feedback_no_destructive_git_ops). The primary gate is run-real-checks called BEFORE this tool.
Commit agent-authored work-product files with attestation footer.
| Parameter | Type | Required | Description |
|---|
files | array | yes | Files to stage + commit. Empty array refused. |
message | string | yes | Commit message body (the attestation footer is appended automatically). |
agent_id | string | yes | Agent id for writer.kind=agent attestation (e.g. 'spec-implementer-001'). |
work_order_id | string | no | Optional work-order id for the attestation footer. |
Add or remove an entry in config.tool_operations[] or config.tool_operations_forbidden[]. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer. Refuses any attempt to register a framework-forbidden wholesale token.
Author a config tool-grant entry (operation registration or project-forbidden token).
| Parameter | Type | Required | Description |
|---|
target | unknown | yes | Which config registry to mutate. |
operation | unknown | yes | amendConfigEntry operation. |
key | string | yes | For tool_operations: the canonical_id (must match entry.canonical_id). For tool_operations_forbidden: the token string. |
entry | unknown | no | ToolOperationDecl object — required for target=tool_operations + operation=add. |
writer | object | yes | DispatchContext.writer payload; see pi-context/src/dispatch-context.ts for the discriminated union. |
Execute the bounded work-order loop: dispatch target_agent (via direct pi-jit-agents library) → run-real-checks (deterministic verdict — the actual exit code, never an LLM self-report) → on-pass commit-attested → on-fail human-OK retry at the iteration boundary. Bounded iterations (default 3); human-OK gate governs retry.
Execute the end-to-end work-order loop for a declared spec.
| Parameter | Type | Required | Description |
|---|
work_order_id | string | yes | ID of the work-order to execute (loads from the substrate's work-orders block). |
max_iterations | number | no | Max iteration count before fail-final. Default 3. |
agent_grant | array | no | Tool grant for the dispatched privileged agent (capability composition). Default empty. |
</tools_reference>
`tool_call`, `tool_result`
pi-agent-dispatch is the harness-confined orchestrator's in-pi surface. It registers Pi tools the orchestrator agent invokes to dispatch sub-agents, author specs and tool grants, run deterministic checks the executive cannot fake, commit with writer attestation, and drive bounded work-order loops. It is the sibling-consumer registration site; pi-jit-agents stays a library consumed directly by this package and by pi-workflows.
<dispatch_tools>
| Tool | Purpose |
|---|
call-agent | Dispatch a declared agent spec with a composed tool grant (parent ∩ requested ∩ spec.tools). |
author-agent-spec | Write an .agent.yaml spec to the substrate. Human-authorized via auth-gate confirm at the pi-dispatch layer; the verified terminal-operator identity is stamped as writer on confirm. |
run-work-order-loop | Execute the bounded work-order loop: dispatch → run-real-checks → on-pass commit-attested → on-fail human-OK retry. |
| </dispatch_tools> | |
<real_check_tools>
| Tool | Purpose |
|---|
run-real-checks | Execute declared deterministic checks (build/check/test exit codes, schema validations, git diff probes, runtime event probes). Verdict is the actual exit code, never an LLM self-report. |
commit-attested | Stage + commit with writer-identity footer. Refuses on missing agent_id, files, or message. |
| </real_check_tools> | |
<capability_authoring>
Tool grants are config-declared (bounded composites) and authored only via the author-tool-grant Pi tool, which is human-authorized at the pi-dispatch auth-gate (interactive confirmation; on confirm the verified terminal-operator identity is stamped as writer). Default grant is empty; widening goes through the auth-gate. The FORBIDDEN_WHOLESALE_OPERATIONS set blocks shipping wholesale L1 surfaces (bash, write, edit) as a single composite token; the L1 ∪ L5 forbidden union check refuses tokens that already appear on the L1 wholesale-forbidden list.
</capability_authoring>
<composite_loader>
On extension load, composite-loader reads the active substrate's config.tool_operations[] and dynamically registers each declared bounded composite as a Pi tool. Config-absent (no pointer or unbootstrapped substrate) degrades gracefully: extension still registers the 6 static tools; the absence is observed via the extension_load_warning TraceEntry and (when available) surfaced through pi.ui.notify. The substrate is the single source of truth — no parallel ungated path widens capability outside the loader.
</composite_loader>
<canonical_intention>
Anchors:
- Harness-confined orchestrator (positive clause: substrate-write + call-agent + author-agent-spec + run-real-checks + commit-attested + author-tool-grant + run-work-order-loop + declared composites; negative clause: NO bash/edit/write).
- Sibling-consumer scope; pi-jit-agents stays a library.
- Human-authorized authoring at the pi-dispatch auth-gate; default empty; terminal verdict = real deterministic checks.
- Capability composition + end-to-end work-order loop + bounded-composite vocabulary + launch-chain integration.
- Orchestrator uses jit-agents directly; capability composition lives in the dispatch layer.
</canonical_intention>
<success_criteria>
- 6 static tools register on every load: call-agent, author-agent-spec, author-tool-grant, run-real-checks, commit-attested, run-work-order-loop.
- Composite tools register from config.tool_operations[] when present; load proceeds with warning when absent.
- Every write-bearing tool routes through the pi-dispatch auth-gate; the verified terminal-operator identity is stamped as writer on confirm.
- Work-order loop honors max_iterations + human-OK retry gate + on-pass attested commit.
</success_criteria>
Generated from source by scripts/generate-skills.js — do not edit by hand.
