Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
14.3 KB
Raw Blame
//! Delegation schemas, shared by the root catalog and SDK generation.
const ToolSpec = @import("schema.zig").ToolSpec;

pub const subagent_spec = ToolSpec{
    .name = "subagent",
    .desc = "Delegate a sidecar task with file, shell, codedb and skill tools; children cannot spawn children. Default context is the user's request; fork_from opts into full history. Brief once with context, prompt, established_facts, scope and deliverable. Keep critical-path work local; use disjoint write sets for parallel tasks. Do not set model without a user request or task-specific reason. agent selects a persona; system_prompt overrides it. retained=true preserves history and workspace for follow-up; otherwise the worker is ephemeral. Interactive calls run in background by default; run_in_background=false waits for the child's report on every surface. Headless calls wait by default. agent_message queues feedback without starting a turn; subagent_resume continues a completed worker. agent_output fetches background results; wait_ms>0 waits in headless mode. Do not poll.",
    .schema =
    \\{"type": "object", "properties": {"description": {"type": "string", "description": "Short label for logs, 3-5 words"}, "prompt": {"type": "string", "description": "Numbered steps and search hints; the complete task. Optional context/established_facts/scope/deliverable render as headed sections around this"}, "context": {"type": "string", "description": "Optional: repo and hard constraints the child must not re-derive"}, "established_facts": {"type": "string", "description": "Optional: observed facts, paths, and line numbers the child must treat as given"}, "scope": {"type": "string", "description": "Optional: what not to touch or broaden into"}, "deliverable": {"type": "string", "description": "Optional: required report shape; default is files changed, verified, skipped, open questions"}, "agent": {"type": "string", "description": "Optional: a named agent type (reviewer, researcher, implementer, skeptic, or a .harness/agents/ name) whose persona the child runs with"}, "system_prompt": {"type": "string", "description": "Optional: replace the child's system prompt with a custom one (overrides agent)"}, "model": {"type": "string", "description": "Optional: run THIS child on an exact model name available on the current provider (e.g. \"gpt-6-luna\"). Highest precedence — beats the persona's own pin and the session default. Ignored (spawn still runs on the session default, with a trace note) if the name is unknown, ambiguous, or not served by this provider — except that a logged-in flat-rate subscription serving the exact name honors it (sub-first routing; the login is the standing consent). For a portable 'cheapest seat' ask, tier is still the better lever."}, "tier": {"type": "string", "enum": ["frontier", "mid", "small"], "description": "Optional: run THIS child on a rung of the current provider's model ladder instead of an exact name — frontier (planner/judge class), mid (reviewers, implementers, researchers), small (mechanical transform/extract/label). Prefer this over model: it stays correct when the root model changes. If the provider has no ladder or no model at that rung, sub-first routing seats the child on a logged-in flat-rate subscription's rung when one exists (no login → the pin is ignored); model wins if both are given."}, "effort": {"type": "string", "enum": ["low", "medium", "high", "xhigh", "max", "none"], "description": "Optional: reasoning effort for THIS child — beats the persona's effort: frontmatter; unpinned children run at medium. An axis independent of model/tier: an effort-only override keeps the persona's model pin. none disables thinking only on supported binary-thinking routes and is rejected before child inference elsewhere. An off-vocabulary value is ignored with a trace note."}, "isolation": {"type": "string", "enum": ["shared_cwd", "worktree"], "description": "Optional: independent / fan-out children default to \"worktree\" (own branch + checkout; clean unchanged trees are removed unless retained=true; dirty or uniquely committed trees are kept + reported). Use \"shared_cwd\" only for same-branch collaboration (review + fix, a pipeline). isolation_fallback:true is the only way a failed git worktree add may share the caller tree."}, "isolation_fallback": {"type": "boolean", "description": "Optional: if isolation:\"worktree\" fails to set up (not a git repo, git error), run in the shared working tree instead of failing the spawn. Default false (fails the spawn on setup failure)."}, "fork_from": {"type": "string", "description": "Optional: fork conversation history from current, session:<project-local saved name>, or worker:<owned retained task_id>. Source stays unchanged. Child keeps its own tools, instructions and selected workspace. Cross-wire text/tool evidence transfers; opaque compaction requires the original model and images require the original wire. Use retained:true to continue the new child later."}, "retained": {"type": "boolean", "description": "Optional: persist conversation and workspace for subagent_resume (default false)."}, "run_in_background": {"type": "boolean", "description": "Optional: true starts asynchronously and immediately returns an agent id; false explicitly waits for the child report on every surface. Defaults to true in interactive sessions and false in headless sessions. Do not poll; agent_output(wait_ms>0) blocks until it finishes. A spawn at the live concurrency cap is refused; do not spawn a child to clean up a finished worktree."}}, "required": ["description", "prompt"]}
    ,
};

pub const agent_output_spec = ToolSpec{
    .name = "agent_output",
    .desc = "Fetch a background subagent's status/result (one started with subagent run_in_background:true). Running: a brief status line. Completed: the full report — the same text a synchronous subagent call would have returned, including any kept-worktree note — plus a usage summary (duration, tool-call count, context tokens, cache-read tokens). Failed: an is_error result explaining why; failures are always reported, never silent. wait_ms=0 returns an immediate snapshot; in the prompt-based interactive REPL it yields the parent for an automatic completion wake, while ACP/headless callers remain in the turn. wait_ms>0 waits for completion (up to 10h) on every surface; cancellation interrupts the wait. ids in place of id waits for several agents in one call and returns every report. Do not poll. Calling again after completion re-returns the same result — nothing is consumed.",
    .schema =
    \\{"type": "object", "properties": {"id": {"type": "integer", "description": "Agent id returned by subagent with run_in_background:true"}, "ids": {"type": "array", "items": {"type": "integer"}, "description": "Several agent ids, in place of id: one call returns every report, waiting for all of them when wait_ms>0"}, "wait_ms": {"type": "integer", "description": "0 = snapshot now. >0 = block until the agent finishes (capped at 10 hours). Do not poll every 30s."}}}
    ,
};

pub const workflow_spec = ToolSpec{
    .name = "workflow",
    .desc = "Run a workflow of parallel subagents (dynamic workflows as data). Two shapes. PHASES (fan-out + synthesis): phases run sequentially; tasks inside a phase run in parallel as isolated subagents. Optional fork_from gives each a private copy of current, session:<name>, or worker:<task_id> history; retained:true saves each worker for later continuation. Otherwise every prompt must be self-contained; from phase 2 on, {{prev}} in a task prompt is replaced with the labeled results of the previous phase (appended if omitted); a phase may carry `when` to run only if a substring appears in {{prev}} (conditional / early-exit). Returns the final phase results. A synthesize phase or stage gets eight evidence requests, then one report-only request; if it fails, earlier evidence returns as incomplete rather than restarting synthesis. Use for audits, multi-perspective review, parallel research. Tasks may carry their own system_prompt to run prompt variants side by side; when the fleet is on, a phase with 2+ variants is auto-scored by an LLM judge and each variant's fitness feeds back to the fleet (a tournament doubles as a DGM scoring round). PIPELINE (no barrier): pass {pipeline:{items,stages}} instead to map each item through the stages independently — item A can reach stage 3 while item B is still on stage 1; {{item}} is the item and {{prev}} is this item's previous-stage result. Use for per-item work like transform/verify each file. Optional top-level \"context\" (also settable on the pipeline object): one shared string prepended once, plus a blank line, to every task/stage prompt before {{prev}} substitution, so repo/task boilerplate is stated once instead of repeated in every task.",
    .schema =
    \\{"type":"object","properties":{"fork_from":{"type":"string","description":"Optional: snapshot current, session:<project-local saved name>, or worker:<owned retained task_id> once for all phase or pipeline workers. Source stays unchanged; each child owns its history, tools and workspace selection. Same rules as subagent.fork_from."},"retained":{"type":"boolean","description":"Optional: retain each phase/pipeline worker and workspace; reports include task_id for subagent_resume or further forks. Default false."},"phases":{"type":"array","description":"Fan-out + synthesis mode (barrier between phases).","items":{"type":"object","properties":{"title":{"type":"string","description":"Short phase label for logs"},"when":{"type":"string","description":"Optional (phase 2+): run this phase only if this substring appears (case-insensitive) in the previous phase's results \u2014 gate a synthesis/exit phase on a sentinel"},"tasks":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Short label, 3-5 words"},"prompt":{"type":"string","description":"Complete, self-contained task; may contain {{prev}}"},"agent":{"type":"string","description":"Optional: a named agent type (reviewer, researcher, implementer, skeptic, or a .harness/agents/ name)"},"system_prompt":{"type":"string","description":"Optional: replace this task's system prompt (overrides agent)"},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Optional: fan-out tasks default to \"worktree\" (own branch + checkout). Use \"shared_cwd\" only when this task must share the same branch and files. isolation_fallback:true is the only way a failed git worktree add may share the caller tree."},"isolation_fallback":{"type":"boolean","description":"Optional: if isolation:\"worktree\" fails to set up, run in the shared working tree instead of failing this task. Default false."}},"required":["description","prompt"]}}},"required":["tasks"]}},"context":{"type":"string","description":"Optional: prepended once, plus a blank line, to every task prompt before {{prev}} substitution."},"pipeline":{"type":"object","description":"No-barrier mode: map each item through the stages independently.","properties":{"items":{"type":"array","items":{"type":"string"},"description":"Things to process, one independent chain each (e.g. file paths)"},"stages":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Short stage label"},"prompt":{"type":"string","description":"Self-contained; {{item}} = the item, {{prev}} = this item's previous-stage result"},"agent":{"type":"string","description":"Optional named agent type"},"system_prompt":{"type":"string","description":"Optional: replace this stage's system prompt"},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Optional: pipeline stages default to \"shared_cwd\" so later stages see earlier edits. Stage 0 may set \"worktree\". isolation_fallback:true is the only way a failed git worktree add may share the caller tree."},"isolation_fallback":{"type":"boolean","description":"Optional: if isolation:\"worktree\" fails to set up, run in the shared working tree instead of failing this stage. Default false."}},"required":["description","prompt"]}},"context":{"type":"string","description":"Optional: prepended once, plus a blank line, to every stage prompt before {{item}}/{{prev}} substitution."},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Create one worktree per item and reuse it across all stages; preserve changes and return the path/branch."}},"required":["items","stages"]},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"For phases, share one retained worktree across all dependent stages; results include its path and branch for explicit delivery. For pipeline isolation set this on pipeline instead."}}}
    ,
};

pub const agent_message_spec = ToolSpec{
    .name = "agent_message",
    .desc = "Send additional task instructions to a live background subagent by its numeric agent id. Parent-only. Queues feedback without interrupting its current tool or model request; the child reads it before a later model step. Queued children receive it when they start. A receipt means queued, not yet applied. Numeric completed ids are rejected; task_id queues feedback durably for a retained worker without restarting it. Use subagent_resume to trigger continuation. Use agent_output to collect the final report. Limits: 16 KiB per message, 32 pending messages and 64 KiB pending total. Live feedback is in-memory; queued retained-worker feedback persists.",
    .schema =
    \\{"type":"object","properties":{"id":{"type":"integer","minimum":1,"description":"Background agent id returned by subagent"},"task_id":{"type":"string","description":"Stable retained worker id; use instead of id"},"message":{"type":"string","description":"Additional task instructions for this child"}},"required":["message"]}
    ,
};

pub const subagent_resume_spec = ToolSpec{
    .name = "subagent_resume",
    .desc = "Continue a completed retained worker on its original conversation and workspace. Parent-only; task_id comes from subagent. Unlike agent_message, this starts a model turn and shares the parent run budget. Returns a background agent handle. A running worker cannot be resumed concurrently; queue feedback instead. Finite budgets cannot be renewed after process restart. Forget tombstones its checkpoint without deleting the workspace.",
    .schema =
    \\{"type":"object","properties":{"task_id":{"type":"string"},"message":{"type":"string"},"action":{"type":"string","enum":["resume","forget"]}},"required":["task_id"]}
    ,
};