diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 05e7e7b..a6094bc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,6 +20,12 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Run publication compatibility suite + run: bash tests/test_publication_compatibility.sh + + - name: Check Codex adapter syntax + run: bash -n scripts/run-codex-json.sh + macos-bash: name: macOS Bash contract suite runs-on: macos-latest @@ -33,6 +39,12 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Run publication compatibility suite + run: bash tests/test_publication_compatibility.sh + + - name: Check Codex adapter syntax + run: bash -n scripts/run-codex-json.sh + windows-powershell: name: Windows PowerShell contract suite runs-on: windows-latest @@ -48,3 +60,9 @@ jobs: - name: Run execution scope suite run: pwsh -File tests/test_execution_scope.ps1 + + - name: Run publication compatibility suite + run: pwsh -File tests/test_publication_compatibility.ps1 + + - name: Run Codex adapter suite + run: pwsh -File tests/test_codex_adapter.ps1 diff --git a/AGENTS.md b/AGENTS.md index e997b11..c541c0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,9 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy ## Key decisions and architecture -- **Orchestrator-agnostic, worker-fixed**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. `agy` is reserved for the worker role. The self-guard stops an `agy` process that loads this skill. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. +Dispatch control: `dispatch-worker.sh` and `dispatch-worker.ps1` are orchestrator-owned admission interfaces. They record bounded assignment parentage and budgets, create worktrees, and start workers. Worker-context calls to dispatch, launch, or execution-workspace lifecycle helpers fail closed and are recorded; worker follow-up requests remain data until the orchestrator admits them. + +- **Orchestrator-agnostic, adapter-backed workers**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Worker execution runs through the adapter contract, with `agy` as the reference adapter. The self-guard stops a dispatched worker that loads this skill, and the dispatcher plus worker-context guards enforce that workflow boundary. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. - **Modular mode architecture**: Root `SKILL.md` is a lightweight router under 500 lines owning shared preconditions, mode inference, explicit overrides, mode loading, and the shared report contract. Workflows are isolated into dedicated mode documents: `modes/execution.md` (code and file mutations), `modes/repo-research.md` (bounded local investigations and audits), and `modes/web-research.md` (online research, synthesis, and citation auditing). - **Routing hierarchy**: Once invoked, the router resolves mode in this order: 1. Honor explicit mode override. @@ -15,21 +17,15 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy 6. Route mixed local and external questions to `web-research` with a scoped snapshot. Single factual lookups stay local with the orchestrator. - **Shell-native helper families with platform parity**: Offload maintains two shell-native helper families: Bash 3.2+ for POSIX shells and PowerShell 7+ for PowerShell orchestrators. Orchestrators select the helper family for their current shell. Native workflows on Windows require only PowerShell 7+, Git, and `agy` without WSL, Git Bash, Python, or `jq`. Platform parity ensures equivalent workflow behavior, workspace isolation, provenance artifacts, and safety checks across supported shells. -- **Worker roles, models, and modes**: - - Worker routing is governed centrally by `model-policy.json` targeting the Gemini 3.8 Flash baseline: - - `scout` (`gemini-3.8-flash-low`, `--mode plan`): Discovers file paths for provisional tasks. - - `gate-author` (`gemini-3.8-flash-high`, `accept-edits`): Generates automated test files from acceptance criteria. - - `implementer` (`gemini-3.8-flash-high`, `accept-edits`): Modifies owned code files. - - `reviewer` (`gemini-3.8-flash-high`, `--mode plan`): Evaluates recorded review artifacts adversarially against criteria. - - `researcher` (`gemini-3.8-flash-high`, `--mode plan`): Collects structured findings for bounded questions within assigned scopes. - - `synthesizer` and `auditor` (`gemini-3.8-flash-high`, `--mode plan`): Synthesizes claim ledgers and audits citation veracity for web research. - - A historical live smoke comparison against Gemini 3.7 retained Flash for every role because the proposed Pro split did not complete its mandatory synthesis stage. +- **Worker roles, preferences, and modes**: + - Worker routing is governed centrally by `model-policy.json` and a vendor adapter. The policy stores each role's internal preference, independent effort, and required capabilities. The adapter provides the live catalog and translates the selected model into worker arguments. + - Selection is deterministic after filtering for availability, quota, effort, capabilities, and static security constraints. Family hints are descriptive only. - **Model routing policy and recovery accounting**: - Preflight model availability check against the resolved `agy` installation before first dispatch. - Launchers take `--role ` and optional `--route default|quality-retry`, resolving models dynamically and rejecting caller `--model` or `--effort` arguments. - Stable assignment identity across attempts with a strict ceiling of at most one retry (maximum two attempts per worker). - - Operational failures (crashes, timeouts, unparsable output) trigger at most one same-model retry (`--route default`). Quality failures (gate failures, scope violations, audit rejections) may use `--route quality-retry` only when an evidence-backed escalation target is configured in policy. - - Explicit Gemini quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers. + - Operational failures (crashes, timeouts, unparsable output) trigger at most one retry of the pinned selection (`--route default`). Quality failures (gate failures, scope violations, audit rejections) retry the pinned selection or require an explicit fallback or handoff when the pin is unavailable. + - Explicit quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers. - The orchestrator records all attempts and verification verdicts in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt records in `provenance.json`. - **Corrected worker guarantees**: `--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. `--add-dir` grants access without confining writes. Security and containment rely on filesystem isolation (disposable workspaces with scoped file snapshots for research) and mechanical verification (clean git working trees, execution scope checks, frozen path diffs, and test gates for execution). - **Verification over claims**: Worker JSON status (`SUCCESS`/`ERROR`) is not trusted alone. Implementers are verified via mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen paths, and gate commands. Reviewers are verified against the recorded artifact digest and verbatim quote matching. Research findings are verified against the live repository with read-only orchestrator commands after scope validation, with direct checks on high-priority claims and sampling on lower-priority claims. diff --git a/CONTEXT.md b/CONTEXT.md index ac2a59d..04b8657 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -2,6 +2,21 @@ Offload delegates bounded work to `agy` processes while the calling agent remains responsible for scope, verification, and reporting. +## Publication boundary + +Published source skills remain vendor-neutral. `grill-with-docs` owns its +interview and documentation workflow and can run without offload. Offload is +an optional delegation layer, while adapters own vendor launch syntax, model +catalogs, capability probes, and output parsing. Consumers depend on stable +capabilities, model preferences, separate reasoning effort, and normalized +results, not vendor names or exact model IDs. + +Capability support does not enforce security. The orchestrator remains +responsible for isolation, ownership, cleanup, execution scope checks, and +acceptance gates. The source repository is authoritative; generated and +installed copies are release outputs. See +`docs/contracts/publication-compatibility.md` and ADR 0007. + ## Language **Orchestrator**: @@ -9,9 +24,13 @@ The calling agent that plans assignments, dispatches workers, and verifies their _Avoid_: Controller, parent agent **Worker**: -An `agy` process assigned one bounded role and prohibited from dispatching more workers. +An `agy` process assigned one bounded role. Its process environment is marked as worker context, so the dispatch, launcher, and execution-workspace lifecycle interfaces reject nested assignment, process, or worktree creation. _Avoid_: Subagent, child agent +**Dispatch ledger**: +The orchestrator-owned `offload-dispatch-state-v1` record for admitted assignments. It records parentage, depth, child IDs, budgets, owned and frozen paths, lifecycle state, artifacts, and rejected nested-dispatch events. +_Avoid_: Worker tree, implicit scheduler state + **Helper family**: A shell-native set of scripts that implements the same offload operations and command contracts for one supported shell. _Avoid_: Port, rewrite @@ -37,11 +56,11 @@ The host-independent rule that defines when an orchestrator offers offloading, h _Avoid_: Hook, Claude hook **Model routing**: -The policy that selects a Gemini model and reasoning effort for an offload worker assignment. It uses role defaults and explicit escalation rules, prioritizing verified task success, then elapsed time and quota use. +The policy and adapter process that selects an available model and independent reasoning effort for an offload worker assignment. It uses a role preference, task capabilities, live availability, static security rules, and quota state. _Avoid_: Mode routing, unrestricted model selection **Role default**: -The model and reasoning effort assigned to an offload role unless a documented escalation rule applies. +The internal preference, reasoning effort, and required capabilities assigned to an offload role. The adapter resolves those requirements to a current model. _Avoid_: Best model, permanent model assignment **Model policy**: diff --git a/README.md b/README.md index 2436edb..dbd69be 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,26 @@ # offload -`offload` is an agent-agnostic skill that delegates plan execution and research tasks to headless `agy` workers (the Antigravity CLI, running Gemini models). +`offload` is an agent-agnostic skill that delegates plan execution and research tasks to headless workers through a vendor adapter. The reference adapter launches `agy`. Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Code, Codex CLI, or any agent that can read instructions and run shell commands. `agy` is the worker, not the orchestrator. The orchestrator never accepts worker claims at face value. It verifies work mechanically through test gates, execution scope checks, verbatim quote matching, independent citation auditing, and direct repository checks. Offload's online-research workflow is adapted from Asa by Achibukz, used with permission. Do not publish a private repository URL, branch, commit, screenshots, or copied text. +## Publication boundary + +Published source skills use the vendor-neutral contract in +[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). +`grill-with-docs` owns its interview and documentation workflow and can run +without offload. Offload is an explicit optional delegation layer. Adapters own +vendor command syntax, model catalogs, capability probes, and output parsing. + +Published consumers use stable capabilities and internal model preferences, +with reasoning effort kept separate. They do not depend on vendor names, family +labels, or exact model IDs. The compatibility checker rejects unavailable +adapters and vendor-specific references. Capability support does not enforce +security. The orchestrator still owns isolation, execution scope checks, +cleanup, and acceptance gates. + ## Worker safety and containment - **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. Never rely on it alone to protect live repository files. @@ -13,6 +28,11 @@ Offload's online-research workflow is adapted from Asa by Achibukz, used with pe - **Filesystem isolation.** Research workflows run inside disposable workspaces outside the live repository. Workers receive only scoped snapshots of declared files, keeping live repository files untouched. - **Mechanical verification.** Execution workflows require a clean git working tree, execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path checks, and automated test gates. - **Prohibition on nested dispatch.** Assignments instruct workers not to dispatch nested workers. +- **Vendor-neutral worker adapters.** [`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md) defines the assignment, lifecycle, capability/model discovery, ownership, and normalized-result boundary. The current AGY launcher is the reference adapter; verification and cleanup remain with the orchestrator. +- **Orchestrator-owned dispatch.** `dispatch-worker.sh` or `dispatch-worker.ps1` is the only workflow entry point that admits an assignment, creates its worktree, and starts its worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1` for the worker. Worker-context calls to the dispatcher, launcher, or execution-workspace lifecycle helpers fail closed and record a `nested_dispatch_rejected` event. +- **Structured follow-up requests.** A worker may return a request for more work in `structured_output`, but that request is data for the orchestrator to review. It never starts a process automatically. +- **Bounded assignment ledger.** The dispatcher records assignment ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle timestamps, output and error paths, worktree manifest, and timeout/resource budget in an `offload-dispatch-state-v1` ledger. Root limits for depth, child width, timeout, and total resource units are immutable for descendants; admission rejects attempts that would exceed them. +- **Defense in depth.** Vendor sandbox behavior, including `agy --mode plan`, is a useful additional boundary but is not treated as enforcement. The workflow verifies the worker context, assignment ledger, worktree lifecycle, frozen paths, execution scope, and test gates mechanically. ## Supported environments @@ -27,6 +47,22 @@ Offload's online-research workflow is adapted from Asa by Achibukz, used with pe Orchestrators select helper scripts based on their current shell (`.sh` for Bash, `.ps1` for PowerShell), never by host operating system detection or universal launchers. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +### Claude adapter + +The bounded Claude Code adapter is available as `scripts/run-claude-json.ps1` and +`scripts/run-claude-json.sh`. It accepts the versioned assignment contract in +[`docs/specs/0004-claude-adapter.md`](docs/specs/0004-claude-adapter.md), probes +the installed Claude CLI, forwards only the bounded prompt and tool policy, +and returns a normalized result while preserving orchestrator ownership of +verification and ledgers. + +Set `CLAUDE_BIN` when Claude is not on `PATH`. The adapter accepts internal +`fast`, `balanced`, and `deep` preferences without mapping them to published +model IDs. A pinned model requires a caller-provided live catalog. Unsupported +or unmarked sandboxes fail closed. On Windows, use an isolated runtime such as +WSL, Git for Windows, or the supported native Claude binary; the adapter does +not turn the caller checkout into a sandbox. + ## Requirements - A CLI coding agent that can read skills and run shell commands (Claude Code, Codex CLI, or similar). @@ -75,17 +111,17 @@ Single factual lookups stay local with the orchestrator and are not offloaded. ## Worker roles -| Role | Mode | Default model | Job | +| Role | Mode | Preference | Job | |---|---|---|---| -| scout | Execution | `gemini-3.8-flash-low` | Discovers repository-relative file paths touched by provisional tasks. | -| gate-author | Execution | `gemini-3.8-flash-high` | Authors executable test files from acceptance criteria. | -| implementer | Execution | `gemini-3.8-flash-high` | Modifies owned code files to satisfy gates. | -| reviewer | Execution | `gemini-3.8-flash-high` | Evaluates diffs adversarially against criteria for diff-gated tasks. | -| researcher | Research | `gemini-3.8-flash-high` | Collects structured findings for assigned evidence angles or bounded local scopes. | -| synthesizer | Web research | `gemini-3.8-flash-high` | Builds claim ledgers, resolves conflicts, and drafts answers. | -| auditor | Web research | `gemini-3.8-flash-high` | Independently verifies citation URLs and claims against live sources. | +| scout | Execution | fast | Discovers repository-relative file paths touched by provisional tasks. | +| gate-author | Execution | balanced | Authors executable test files from acceptance criteria. | +| implementer | Execution | balanced | Modifies owned code files to satisfy gates. | +| reviewer | Execution | deep | Evaluates diffs adversarially against criteria for diff-gated tasks. | +| researcher | Research | balanced | Collects structured findings for assigned evidence angles or bounded local scopes. | +| synthesizer | Web research | deep | Builds claim ledgers, resolves conflicts, and drafts answers. | +| auditor | Web research | deep | Independently verifies citation URLs and claims against live sources. | -Worker routing is governed by repository-root `model-policy.json`. Launchers accept `--role ` (and optional `--route default|quality-retry`) and resolve models dynamically. Callers must not supply `--model` or `--effort` flags. +Worker routing is governed by repository-root `model-policy.json` and [`docs/adapter-contract.md`](docs/adapter-contract.md). Launchers accept `--role ` and select a current eligible catalog entry. Callers must not supply `--model` or `--effort` flags. A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. The recorded comparison is in [`tests/live-smoke-comparison.md`](tests/live-smoke-comparison.md). @@ -95,11 +131,11 @@ A historical live smoke comparison against Gemini 3.7 retained Flash for every r Used for code and file modifications across independent gated tasks. -1. **Split and scout.** Break work into provisional tasks. Dispatch parallel scouts under `--mode plan` via `run-agy-json` with a JSON schema to identify touched files. If tasks overlap on files, serialize them. +1. **Split and scout.** Break work into provisional tasks. Dispatch parallel scouts under `--mode plan` via `dispatch-worker`, which wraps `run-agy-json`, with a JSON schema to identify touched files. If tasks overlap on files, serialize them. 2. **Assign gates.** Every task receives exactly one gate: - **Machine gate.** An automated test command exiting 0 on success. A gate-author worker writes the test. The orchestrator runs a red check against the untouched tree to verify failure, reads the test code to confirm intent, and commits the test to freeze it. - **Diff gate.** Plain-text criteria for tasks without test commands (such as documentation or configuration changes) receive stable IDs. A reviewer worker evaluates the immutable review artifact and returns exactly one verdict per ID. The orchestrator accepts only complete all-pass coverage whose evidence lines match the same artifact. -3. **Dispatch implementers.** Dispatch implementers in parallel from a clean git tree with explicit owned files, frozen paths, and gate commands via `run-agy-json`. +3. **Dispatch implementers.** Dispatch implementers in parallel from a clean git tree with explicit owned files, frozen paths, gate commands, and bounded budgets via `dispatch-worker`. The dispatcher wraps `execution-workspace` and `run-agy-json`; workers never call those lifecycle or launch interfaces directly. 4. **Mechanical verification.** - Execution scope check: verify touched paths against assigned owned and frozen paths using `check-execution-scope`: #### Bash @@ -183,8 +219,8 @@ The script copies only declared paths into `/repo/` and creates the ` Follow the shared recovery rules in `SKILL.md`: - **Stable worker IDs and retry ceiling.** Each assignment retains a stable identifier across attempts. Attempt 1 is initial dispatch; attempt 2 is the only permitted retry (maximum two attempts per task). -- **Quality versus operational failures.** Failing a machine gate, scope check, or citation audit is a quality failure; operational failures include crashes, timeouts (20m), and unparsable output. Operational failures retry with `--route default` (no model escalation). Quality failures retry with `--route quality-retry` only when an evidence-backed target is configured in `model-policy.json`. -- **Immediate quota handoff.** If Gemini quota is exhausted, stop dispatching immediately and hand all unfinished work back to the calling orchestrator while preserving completed artifacts. +- **Quality versus operational failures.** Failing a machine gate, scope check, or citation audit is a quality failure; operational failures include crashes, timeouts (20m), and unparsable output. Operational failures retry with `--route default` using the recorded selection. Quality failures retry with `--route quality-retry` using the recorded pin; if it is unavailable, record an explicit fallback or handoff instead of switching silently. +- **Immediate quota handoff.** If adapter-reported quota is exhausted, stop dispatching immediately and hand all unfinished work back to the calling orchestrator while preserving completed artifacts. - **Outcome tracking.** Every attempt and verification verdict is recorded in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt data in `provenance.json`. - **Implementer failures.** If an implementer fails its gate or violates execution scope, retry once with the error output. If the retry fails, halt that task. - **Researcher failures.** If a researcher crashes or times out, retry once. If the retry fails, synthesis proceeds as long as at least two independent evidence angles remain. The final report explicitly names any omitted angle. @@ -250,6 +286,19 @@ After generating provenance, `cleanup-research-workspace` cleans the temporary w - On `success`, the helper removes intermediate worker files and snapshot directories while preserving `final.md`, `provenance.json` when present, `routing-outcomes.json`, the workspace marker, and `evidence-disposition.json`. The disposition manifest records each routing evidence path, its pre-cleanup existence, a SHA-256 hash for existing regular files, and whether it was retained, pruned, missing, or left uninspected for safety. - On `partial` or failure, the helper retains all raw artifacts and logs. +### Crash recovery and resource ownership + +The adapters maintain a durable, orchestrator-owned resource ledger outside worker checkouts. Pass the same ledger, assignment ID, and parent ID to workspace and worker helpers when coordinating a run: + +```bash +LEDGER="$SCRATCH/offload-resource-ledger.json" +WORKSPACE=$(./scripts/make-research-workspace.sh --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --source-repo "$PWD" --path src/auth) +./scripts/run-agy-json.sh --role researcher --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --output "$WORKSPACE/worker.json" --error "$WORKSPACE/worker.err" -- --prompt '...' +./scripts/cleanup-research-workspace.sh --workspace "$WORKSPACE" --status success --ledger "$LEDGER" --resource-id "research-workspace:$ASSIGNMENT" +``` + +If the orchestrator crashes, reconcile the ledger on its next run. Reconciliation terminates recorded worker processes before cleaning their resources and discovers AGY-native Git worktrees that were never registered as `unknown`. It never deletes dirty, unmerged, unowned, ambiguous, or otherwise unprovable resources. + ### Shared report format All modes format results into a consistent summary: @@ -264,7 +313,7 @@ All modes format results into a consistent summary: | docs | diff | agy+grep | △ judged | as assigned (scout) | | auth-audit | audit (isolated) | orchestrator+checked (high) + orchestrator+sampled (med/low) | complete | 3 findings (2 verified, 1 unverified) | -### Claimed by Gemini, not verified +### Claimed by worker, not verified - "also improved error messages" - "Legacy endpoints may be affected" ``` @@ -299,7 +348,7 @@ Place this instruction block in your agent's project context file (`AGENTS.md`, ```markdown ## Offload delegation -- Use Offload when the user asks to offload, run work on AGY, use Gemini subagents, or accepts an AGY offer. +- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts an AGY offer. - Offer AGY once, before starting, when implementation splits into three or more independently gated tasks in a clean Git repository, or when a read-only audit or external research requires multiple distinct work lanes. Count research lanes by distinct questions or evidence responsibilities, not browser tabs. - Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. - Ask before dispatching. @@ -324,22 +373,30 @@ Run the automated acceptance suite to verify contracts across supported helper f ```bash bash tests/test_research_modes.sh bash tests/test_execution_scope.sh +bash tests/test_worker_adapter_contract.sh ``` #### PowerShell ```powershell pwsh -File tests/test_research_helpers.ps1 pwsh -File tests/test_execution_scope.ps1 +pwsh -File tests/test_worker_adapter_contract.ps1 +pwsh -File tests/test_codex_adapter.ps1 ``` +The Codex worker boundary is documented in docs/codex-adapter.md. It discovers +the installed CLI structured-output support and selects models from the +host-provided CODEX_MODEL_CATALOG. It fails closed when either capability is +unavailable. + ## Findings about agy - **`agy` default `--print-timeout` is 5 minutes.** On expiry it writes no output at all. `offload` passes `--print-timeout 20m`. - **`--output-format json` returns one flat JSON object.** Parse top-level fields `status`, `response`, `duration_seconds`, `num_turns`, and `usage`. - **`--json-schema` outputs validated JSON in `structured_output`.** Parse `structured_output` rather than `response`. -- **Use the bundled launcher helpers (`run-agy-json.sh` or `run-agy-json.ps1`) for worker calls.** They own result and error paths and reject the unsupported `agy --output` flag. +- **Use `dispatch-worker.sh` or `dispatch-worker.ps1` for execution assignments.** They own assignment admission, worktree creation, result and error paths, and the bounded launch. The dispatcher wraps the lower-level `run-agy-json` helper, which rejects the unsupported `agy --output` flag. - **Use structured output extractors (`extract-structured-output.sh` or `extract-structured-output.ps1`) between research stages.** They forward only validated `structured_output`, keeping verbose worker prose out of later prompts. -- **Model routing is governed by `model-policy.json`.** Launchers inject the policy-selected Gemini 3.8 Flash model (`gemini-3.8-flash-low` or `gemini-3.8-flash-high`) via `--role `. Reasoning effort is encoded directly in the model ID; callers must not pass `--model` or `--effort`. +- **Model routing is governed by `model-policy.json` and the adapter contract.** Launchers select a live eligible model using the role preference, effort, required capabilities, quota, and static security rules. The adapter receives the exact selection and translates it for its vendor. Reasoning effort stays separate from model identity, and callers must not pass `--model` or `--effort`. - **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted probe on `agy 1.1.25` blocked the tested direct write outside the permitted artifact area, but this observation is not a guarantee. `--add-dir` grants access without confining writes. Security relies on filesystem isolation and mechanical verification. Run the maintainer-only compatibility probe when the installed `agy` behavior needs a refresh (never as a deterministic CI gate): diff --git a/SKILL.md b/SKILL.md index 76de7d3..8d71c22 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,18 +1,33 @@ --- name: offload -description: Use when the user wants execution or research handed to another vendor's CLI agents instead of running it here. Triggers include "offload this", "run this on agy", "use gemini subagents", or after answering yes to the offload offer. Also offer unprompted when implementation splits into three or more independently gated tasks in a clean git repository, or when a read-only audit or online research fans out across multiple angles or files. Dispatches parallel headless agy workers, gates their output, and reports what was proven versus claimed. +description: Use when the user wants execution or research handed to another CLI agent instead of running it here. Triggers include "offload this", "run this on a worker", or after answering yes to the offload offer. Also offer unprompted when implementation splits into three or more independently gated tasks in a clean git repository, or when a read-only audit or online research fans out across multiple angles or files. Dispatches parallel headless workers through an adapter, gates their output, and reports what was proven versus claimed. --- # offload -If you are `agy`, stop here. Return worker results to your orchestrator. `agy` is the worker role this skill dispatches. Any other agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, but the skill cannot enforce that rule if a worker ignores it. +If you are a dispatched worker, stop here. Return worker results to your orchestrator. Workers do not dispatch nested workers. Any agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, and the workflow enforces that boundary with an orchestrator-owned dispatcher and worker-context guards. ## What this skill does -`offload` delegates execution and research tasks to headless `agy` workers (the Antigravity CLI running Gemini models routed via `model-policy.json`). You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection. +`offload` delegates execution and research tasks to headless workers through a vendor adapter. The reference adapter launches `agy`, but the workflow contract does not depend on a vendor or exact model ID. You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection. You never accept worker claims at face value. You verify output through mechanical checks, test execution, diff inspections, or secondary reviews. +## Publication boundary + +Published source skills use the vendor-neutral contract in +[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). +`grill-with-docs` owns its interview and documentation workflow and can run +without offload. Offload is an explicit optional delegation layer. Adapters own +vendor command syntax, model catalogs, capability probes, and output parsing. + +Published consumers use capabilities, internal model preferences, separate +reasoning effort, and normalized results. They do not depend on vendor names, +family labels, or exact model IDs. The compatibility checker rejects +unavailable adapters and vendor-specific references. Capability support does not +enforce security. The orchestrator still owns isolation, execution scope +checks, cleanup, and acceptance gates. + ## Preconditions and helper selection Select the helper family matching your current host shell: @@ -28,15 +43,15 @@ Check these requirements before dispatching workers: 4. **Git working tree.** Writing workflows (`modes/execution.md`) require a clean git repository (`git rev-parse --is-inside-work-tree` and empty `git status --porcelain`). Research workflows (`modes/repo-research.md`, `modes/web-research.md`) operate in isolated disposable workspaces. 5. **Preflight model availability check.** Before dispatching the first worker in a run: - Read repository-root `model-policy.json` (resolved relative to helper scripts, never the caller's working directory). - - Check selected default models against available Gemini model IDs reported by the resolved `agy` installation. - - If a required model is absent or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently downgrade to 3.7, fall back to AGY's unverified default, or pick a similarly named model. - - When a quality-retry escalation model is used, check its availability before dispatch as well. - - Avoid repeating catalog discovery for every worker in the same run unless AGY reports that availability changed. + - Ask the configured adapter for its live catalog, then filter by availability, quota, required capabilities, and supported effort. + - If no eligible model exists or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently switch providers or fall back to an unverified default. + - Avoid repeating catalog discovery for every worker in the same run unless the adapter reports that availability changed. 6. **Policy installation, updates, and revert.** - `model-policy.json` is located at repository root alongside helper scripts. Installation must copy the entire skill directory (including `model-policy.json`). - - The policy enforces `schema_version: 1`, a non-empty `policy_revision` (e.g. `"2026-09-03.1"`), `max_effort: "high"`, `max_retries_per_worker: 1`, `quota_action: "handoff"`, and exactly seven role mappings: `scout`, `gate-author`, `implementer`, `reviewer`, `researcher`, `synthesizer`, and `auditor`. + - The policy enforces `schema_version: 2`, a non-empty `policy_revision`, `max_effort: "high"`, `max_retries_per_worker: 1`, `quota_action: "handoff"`, and exactly seven role mappings: `scout`, `gate-author`, `implementer`, `reviewer`, `researcher`, `synthesizer`, and `auditor`. + - Each role declares an internal preference (`fast`, `balanced`, or `deep`), an independent effort (`low`, `medium`, or `high`), and required capabilities. It does not publish vendor names or exact model IDs. - To update policy: edit `model-policy.json` in the skill root and update `policy_revision`. To revert: restore the prior revision. Launchers validate the entire policy on every invocation. Missing or invalid policy fails closed before launching workers. - - A non-null `quality_escalation` entry must specify an eligible Gemini model and a valid, non-escaping repo-relative `evidence_path` pointing to an existing evaluation document inside the skill directory. + - There is no policy-level model escalation target. Quality retries use the pinned selection when one exists. A missing pin requires an explicit fallback or handoff record. ## Routing @@ -59,34 +74,59 @@ Load the matching mode document for the selected route and shell-specific comman ## Shared model routing and launcher contract -Offload routes all workers through the repository-root `model-policy.json`. Launchers resolve model IDs and inject `--model` before launching `agy`. Callers must never pass `--model` or `--effort` after `--`. +Offload routes all workers through the repository-root `model-policy.json` and the adapter contract in [`docs/adapter-contract.md`](docs/adapter-contract.md). The launcher selects an eligible current catalog entry. The adapter translates that exact selection into vendor-specific arguments. Callers must never pass `--model` or `--effort` after `--`. ### Launcher invocation -- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --output --error -- ` -- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --output --error '--' ` +Execution workers must use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1`, which calls this lower-level launcher after admission. The direct forms below are for the isolated research stages described in the research mode documents. + +- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger -- ` +- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger '--' ` In PowerShell command expressions, always quote the delimiter (`'--'`). -### Roles and default models +### Roles and preferences -| Role | Default model | Effort | Primary mode | +| Role | Preference | Effort | Primary mode | |---|---|---|---| -| `scout` | `gemini-3.8-flash-low` | low | Execution | -| `gate-author` | `gemini-3.8-flash-high` | high | Execution | -| `implementer` | `gemini-3.8-flash-high` | high | Execution | -| `reviewer` | `gemini-3.8-flash-high` | high | Execution | -| `researcher` | `gemini-3.8-flash-high` | high | Repo research / Web research | -| `synthesizer` | `gemini-3.8-flash-high` | high | Web research | -| `auditor` | `gemini-3.8-flash-high` | high | Web research | +| `scout` | fast | low | Execution | +| `gate-author` | balanced | high | Execution | +| `implementer` | balanced | high | Execution | +| `reviewer` | deep | high | Execution | +| `researcher` | balanced | high | Repo research / Web research | +| `synthesizer` | deep | high | Web research | +| `auditor` | deep | high | Web research | ### Routes -- `--route default` (default): Resolves `default_model` for the specified role. -- `--route quality-retry`: Resolves `quality_escalation.model` for that role. If `quality_escalation` is `null` or unconfigured, the launcher rejects the request with exit code 2 before starting `agy`. Never infer an escalation model or replace the route. +- `--route default` (default): Selects the best eligible catalog entry for the role's preference, effort, and capabilities. +- `--route quality-retry`: Requires a pin from the prior attempt and reuses that exact adapter, vendor, model ID, and effort. If the pin is missing or unavailable, the launcher records an explicit fallback or handoff condition and does not switch silently. + +## Worker adapter contract + +The vendor-neutral boundary for one bounded worker assignment is defined in +[`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md). The +orchestrator owns assignment constraints, verification, publication, and +cleanup decisions. An adapter owns vendor command syntax, output parsing, +capability discovery, and model catalog handling, then returns the normalized +result described by that contract. Validate adapter results with +`scripts/check-worker-adapter.ps1` or `scripts/check-worker-adapter.sh` before +running the existing execution scope check and gates. ## Shared recovery, retry accounting, and failure handling +### Worker lifecycle contract + +Both native launchers write the same lifecycle artifact for every dispatched worker. The state machine is: + +`created -> started -> running -> completed|failed|canceled|quota-handoff -> retained -> cleaned` + +`started` includes the child process ID. The launcher waits for the child to exit, records its exit code, and only then records `retained` and `cleaned`. Timeout uses `failed` with `failure_class: "timeout"`; cancellation uses `canceled`; explicit quota diagnostics use `quota-handoff`. Output, error, lifecycle, and resource-ledger paths remain available as diagnosis evidence for every non-success terminal state. + +The launcher accepts `--timeout-seconds` and a testable `--cancel-file`. A timeout or cancellation terminates the worker, waits for exit, flushes both streams, and finalizes the lifecycle artifact before returning. A zero-exit worker advances to `completed` only when its output is a successful JSON envelope with `structured_output`; malformed output is recorded as `failed` with `failure_class: "malformed_output"`. + +`--resource-ledger` records the stable assignment, pinned model, effort, verification baseline, and attempt artifacts. Attempt 2 must use the same assignment and pinned model/effort as attempt 1. Attempt 3 is rejected before dispatch. Resume and retry consumers must read the ledger and select an explicit accepted attempt; they must not infer the latest artifact by wildcard. + ### Stable worker IDs and retry ceiling - A worker represents one logical assignment, not a single process run. @@ -106,17 +146,17 @@ In PowerShell command expressions, always quote the delimiter (`'--'`). 1. **Verified success**: Output passes mechanical gates and verification checks. Accept result; no retry. 2. **Quality failure**: The worker completed with a parsable response (exit code 0), but the output fails verification (e.g. machine gate failure normalized to `quality` via `execute-gate.sh` or `execute-gate.ps1`, execution scope violation, reviewer quote mismatch, unsupported synthesis claim, or audit rejection). - - If retry budget remains and mode permits correction: retry once (attempt 2) with concrete verification feedback. Use `--route quality-retry` only when an evidence-backed escalation target is configured in policy; otherwise use `--route default`. + - If retry budget remains and mode permits correction: retry once (attempt 2) with concrete verification feedback. Use `--route quality-retry` with the recorded pin; if the pin is unavailable, record an explicit fallback or handoff instead of selecting a replacement silently. - If attempt 2 fails or the mode requires immediate fallback: stop retrying and follow that mode's halt, partial-result, or orchestrator fallback path. 3. **Unrunnable failure**: Gate execution exited 126 or 127, normalized to `failure_class: "unrunnable"` with `verification: not_performed`. Preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json`. Exits 126 and 127 are not quality retries; do not schedule or spend a model retry. 4. **Operational failure**: Process crash (nonzero exit code), timeout (20 minutes with no output), unparsable JSON, or tool failure. - Follow mode's recovery rule with at most one same-model retry (`--route default`) where permitted. Never escalate models for operational failures. 5. **Unknown failure**: Record uncertainty and follow the operational-failure path. Do not assume a quality failure or quota issue. -6. **Quota exhaustion**: Explicit Gemini quota error reported by `agy` structured output or diagnostics. Trigger immediate quota handoff. +6. **Quota exhaustion**: Explicit quota exhaustion reported by the adapter or worker diagnostics. Trigger immediate quota handoff. ### Immediate quota handoff -When explicit Gemini quota exhaustion is detected: +When explicit quota exhaustion is detected: - Stop dispatching new workers immediately. - Return unfinished work to the calling orchestrator without waiting for running siblings. - Do not retry automatically, wait for reset, switch models, or activate paid credits. @@ -135,15 +175,21 @@ The orchestrator maintains `routing-outcomes.json` in each run's scratch workspa - `attempt`: Integer 1 or 2. - `policy_revision`: Policy revision string. - `route`: `"default"` or `"quality-retry"`. - - `model`: Resolved AGY model ID. - - `effort`: Derived effort suffix (`low`, `medium`, `high`). + - `adapter`: Adapter name and `adapter_revision`. + - `vendor`: Adapter-reported vendor family. + - `model_id`: Exact selected model ID. `model` may repeat it for compatibility with older records. + - `family_hint`: Descriptive adapter metadata. It never grants permissions or promises cross-vendor quality. + - `preference`: Internal policy preference (`fast`, `balanced`, or `deep`). + - `effort`: Selected reasoning effort (`low`, `medium`, or `high`), kept separate from model identity. + - `catalog_revision`: Adapter catalog or probe revision used for selection. + - `selection_reason`: Deterministic filtering and ranking reason. - `reason`: Initial dispatch or observed failure and recovery decision authorizing attempt 2. - `started_at`: ISO 8601 UTC timestamp. - `ended_at`: ISO 8601 UTC timestamp (null while running). - `duration_seconds`: Observed elapsed time (null while running). - `exit_code`: Worker process exit code (null while running). - `state`: `"running"`, `"completed"`, `"failed"`, or `"interrupted"`. - - `failure_class`: `"none"`, `"quality"`, `"timeout"`, `"tool_error"`, `"quota"`, `"unrunnable"`, or `"unknown"`. + - `failure_class`: `"none"`, `"quality"`, `"timeout"`, `"tool_error"`, `"malformed_output"`, `"quota"`, `"unrunnable"`, or `"unknown"`. - `verification`: `"pending"`, `"passed"`, `"failed"`, or `"not_performed"`. - `evidence_paths`: Array of output, error, gate, review, or audit artifact paths. - `usage`: Source-attributed reported usage object with explicit units, or null when unavailable. @@ -178,7 +224,7 @@ pass: 3/3 criteria, all quotes matched verbatim. No escalation. - [LOW] [agy+unverified] "Legacy endpoints may be affected" — unverified (no location cited). Sample recorded: 1/1 high checked, 1/2 med/low sampled. -### Claimed by Gemini, not verified +### Claimed by worker, not verified - "also improved error messages" - "Legacy endpoints may be affected" ``` @@ -208,8 +254,11 @@ Sample recorded: 1/1 high checked, 1/2 med/low sampled. - **`--add-dir` grants directory access without confining writes.** A worker can edit files outside its assignment if pointed at the live tree. - **Filesystem isolation.** Research modes run in disposable workspaces with scoped file snapshots. Live repository files are never exposed directly to research workers. - **Execution safety.** Execution mode requires a clean git baseline, mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path diffs, and test gates. -- **Prohibition on nested dispatch.** Workers are instructed not to dispatch nested workers. +- **Orchestrator-owned dispatch.** Use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1` for every execution assignment. It is the only workflow interface that creates an assignment record, execution worktree, and worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1`; worker-context calls to the dispatcher, `run-agy-json`, or `execution-workspace` fail with exit 126. +- **Structured follow-up requests.** Workers may return a structured request for more work. The orchestrator records and evaluates that data explicitly. No worker response can automatically create a child assignment. +- **Assignment ledger.** Every admitted assignment records its ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle state and timestamps, output/error paths, worktree manifest, and timeout/resource budget. The root fixes maximum depth, child width, per-assignment timeout, and total resource units. Admission rejects a request before worktree or process creation when it would exceed any limit. +- **Vendor boundary versus workflow verification.** `agy --mode plan` and any vendor sandbox are defense in depth. The workflow does not treat prompts or sandbox hints as its sole control; it verifies caller context, ledger admission, worktree lifecycle, scope, frozen paths, and gates. - **Bounded scope requirement.** Open-ended research without a bounded question, declared scope, and evidence expectations is out of scope. -- **Worker timeout.** Every worker runs with a bounded timeout (`--print-timeout 20m`). +- **Worker timeout.** Every dispatched worker has a bounded dispatcher timeout and forwards the normal AGY output deadline (`--print-timeout 20m`). Result acceptance is separate from process completion: a parsed envelope, substantive structured output, evidence/scope/gate checks, and (where applicable) review or citation checks must all pass before an explicit `accepted_attempt` is recorded. Exit code 0 alone does not establish verified success. Gate exits 126 or 127 are `unrunnable`, retain their command and diagnostic evidence, use `verification: not_performed`, and do not consume a model retry. diff --git a/docs/adapter-contract.md b/docs/adapter-contract.md new file mode 100644 index 0000000..7043d30 --- /dev/null +++ b/docs/adapter-contract.md @@ -0,0 +1,47 @@ +# Worker adapter contract + +Status: accepted. Protocol version 1. + +The launcher owns policy, selection, retry identity, and filesystem scope. An adapter owns vendor syntax and the live model catalog. The public workflow contract names a worker role, an internal preference (`fast`, `balanced`, or `deep`), and a reasoning effort. It does not name a vendor or an exact model ID. + +## Operations + +The launcher invokes an adapter with one of these operations: + +```text +adapter --operation catalog --request REQUEST.json +adapter --operation launch --request SELECTION.json --output OUTPUT --error ERROR -- WORKER_ARGS... +``` + +`REQUEST.json` contains the role, preference, effort, required capabilities, policy revision, and a protocol version. The catalog operation writes one JSON object to stdout. A catalog contains an adapter revision, vendor, catalog revision, capabilities, and model entries: + +```json +{ + "protocol_version": 1, + "adapter": "agy", + "adapter_revision": "1", + "vendor": "provider", + "catalog_revision": "provider-current", + "models": [ + { + "id": "provider-exact-model-id", + "family_hint": "flash", + "available": true, + "quota_available": true, + "supported_efforts": ["low", "high"], + "capabilities": ["structured-output"], + "scores": {"fast": 1, "balanced": 2, "deep": 3} + } + ] +} +``` + +The launcher filters unavailable, quota-exhausted, effort-incompatible, and capability-incompatible candidates. It then sorts the remaining candidates by the requested preference score and stable `(vendor, id)` tie-breakers. `family_hint` is descriptive metadata only. It cannot grant permissions, widen filesystem access, or make a cross-vendor quality claim. + +The launch operation receives the selected exact ID and effort in the selection JSON. It translates those values into vendor-specific arguments, captures worker stdout and stderr at the supplied paths, and exits with the worker's exit code. Adapter failures are operational failures, not permission to select another provider. + +## Pinning and retries + +The launcher writes the complete selection record when `--selection-output` is supplied. The orchestrator copies that record into every `routing-outcomes.json` attempt together with the attempt number and verification result. A retry or resume supplies the same record with `--pin`. The launcher checks the pinned adapter, vendor, exact model ID, and effort against the current catalog. A changed catalog is acceptable when the pinned model is still available; a missing pinned model fails explicitly and requires a recorded fallback or handoff. No retry silently changes provider, model, or effort. + +Adapters must keep their own discovery, quota, cancellation, wait, and exit-code details behind this protocol. They must not widen the permissions, tools, path scope, or resource ownership granted by the orchestrator. diff --git a/docs/adr/0007-cross-library-publication-boundaries.md b/docs/adr/0007-cross-library-publication-boundaries.md new file mode 100644 index 0000000..4768d99 --- /dev/null +++ b/docs/adr/0007-cross-library-publication-boundaries.md @@ -0,0 +1,37 @@ +--- +status: accepted +--- + +# Keep published skills vendor-neutral + +Decision date: 2026-09-04. + +`grill-with-docs` and `offload` have different responsibilities. The source +skill owns its interview and documentation workflow. Offload is an optional +delegation layer. Adapters contain vendor launch syntax, output parsing, model +catalog handling, and capability probes. This boundary prevents a published +source skill from importing one worker vendor's assumptions. + +Published consumers use the versioned vendor-neutral publication contract and +capability names. They do not require exact model IDs, family names, or vendor +features. The orchestrator records adapter and model metadata internally so +retries and resume can pin the same choice. That metadata does not become a +consumer dependency. + +The Bash and PowerShell helper families keep equivalent observable contracts, +with separate native implementations. The compatibility checker validates a +published skill's manifest against an adapter catalog and rejects unavailable +required adapters, incompatible versions, missing capabilities, vendor-feature +declarations, and vendor names in published Markdown. + +Capability support is descriptive. Security enforcement remains with the +orchestrator and its filesystem, ownership, cleanup, execution scope, and gate +checks. A worker or adapter cannot widen those constraints. + +The repository is the source of truth. Generated archives, installed copies, +and copied catalogs are release outputs and must not be edited directly. A +source skill release changes the workflow contract. An adapter release handles +vendor model or command changes without requiring a source skill release. + +See [`publication-compatibility.md`](../contracts/publication-compatibility.md) +for the manifest, version rules, release steps, and AGY-only migration note. diff --git a/docs/adr/0008-runtime-model-selection-through-adapters.md b/docs/adr/0008-runtime-model-selection-through-adapters.md new file mode 100644 index 0000000..bb55eb1 --- /dev/null +++ b/docs/adr/0008-runtime-model-selection-through-adapters.md @@ -0,0 +1,15 @@ +# ADR 0008: Select models at runtime through worker adapters + +- Status: accepted +- Date: 2026-09-04 +- Supersedes: [ADR 0005](0005-bound-model-routing-to-gemini-and-explicit-rules.md) + +## Decision + +Worker policy publishes only the internal preferences `fast`, `balanced`, and `deep`, a separate reasoning effort, and required capabilities. The launcher asks a vendor-neutral worker adapter for a live catalog, filters it using static policy and task requirements, and deterministically selects a current candidate. The adapter translates the selected vendor and exact model ID into its own CLI or API syntax. AGY remains the reference adapter. + +Every selection is recorded with the adapter, vendor, exact model ID, family hint, preference, effort, catalog and adapter revisions, selection reason, and each attempt. Retries and resumes use the recorded selection as a pin. A missing pinned model causes an explicit fallback or handoff; it never causes an implicit provider or model switch. + +## Consequences + +Workflows survive vendor catalog changes without publishing vendor-specific IDs. Catalog availability and quota can be evaluated at launch time. Exact model IDs still exist in operational evidence, where they are needed for reproducibility, but they are not a permission boundary or a quality guarantee. Historical ADR 0005 remains available as the record of the superseded decision. diff --git a/docs/codex-adapter.md b/docs/codex-adapter.md new file mode 100644 index 0000000..481bd74 --- /dev/null +++ b/docs/codex-adapter.md @@ -0,0 +1,109 @@ +# Codex adapter + +The Codex adapter is a vendor-neutral worker boundary for hosts that provide the +Codex CLI. It conforms to the worker adapter contract (`docs/adapter-contract.md`) +and has PowerShell and Bash entry points: + +```text +scripts/run-codex-json.ps1 --operation catalog --request +scripts/run-codex-json.ps1 --operation launch --request --output --error -- + +bash scripts/run-codex-json.sh --operation catalog --request +bash scripts/run-codex-json.sh --operation launch --request --output --error -- +``` + +The Bash entry point requires Bash 3.2 or newer and `jq`; the PowerShell entry +point requires PowerShell 7 or newer. + +## Operations + +### Catalog discovery + +`--operation catalog --request ` probes the installed Codex CLI for +the structured execution flags used by the adapter: `--json`, `--output-schema`, +and `--output-last-message`. It also reads the host-provided `CODEX_MODEL_CATALOG` +(or `OFFLOAD_ADAPTER_CATALOG`) environment variable. The variable may contain a +JSON document or a path to one: + +```json +{ + "revision": "host-catalog-1", + "models": [ + { + "id": "host-selected-model", + "preference": "balanced", + "efforts": ["low", "medium", "high"] + } + ] +} +``` + +The adapter emits a protocol version 1 catalog document to standard output: + +```json +{ + "protocol_version": 1, + "adapter": "codex", + "adapter_revision": "codex-1", + "vendor": "codex", + "catalog_revision": "host-catalog-1", + "models": [ + { + "id": "host-selected-model", + "family_hint": "unknown", + "available": true, + "quota_available": true, + "supported_efforts": ["low", "medium", "high"], + "capabilities": ["structured-output"], + "scores": { "fast": 2, "balanced": 1, "deep": 2 } + } + ] +} +``` + +The catalog is supplied by the host; the adapter does not hardcode vendor model +IDs. If the CLI flags or catalog are unavailable, the adapter fails closed and +exits nonzero. + +### Worker launch + +`--operation launch --request --output --error -- ` +launches Codex with the exact model selected by the orchestrator. The adapter +parses worker arguments following the `--` delimiter (such as `--prompt`, `--cd`, +`--cancel-file`, and `--timeout-seconds`), preserving argument and path +boundaries when values contain spaces. + +The adapter owns the native Codex invocation syntax, supplying fixed +constraints: + +- `exec --json --ephemeral` +- `--cd ` +- `--sandbox workspace-write` +- `--ask-for-approval never` +- `--output-schema ` +- `--output-last-message ` +- `--model ` +- `-- ` + +The adapter captures process standard output and standard error, writing the +normalized result to the designated output path: + +```json +{ + "status": "success", + "structured_output": { ... }, + "model_id": "host-selected-model" +} +``` + +## Security and responsibility boundary + +The orchestrator owns assignment constraints, execution-scope verification, +final acceptance gates, resource ledgers, and cleanup. The adapter does not run +adapter-owned scope checks or acceptance gates, nor does it maintain a competing +private ledger schema. + +Cancellation (signal or cancel file) terminates the process and exits with code +130. Timeout terminates the process and exits with code 124. Quota exhaustion +exits with code 75 for caller handoff. Malformed output exits with code 1, +preserving the raw output for diagnosis. diff --git a/docs/contracts/publication-compatibility.md b/docs/contracts/publication-compatibility.md new file mode 100644 index 0000000..9a93b6c --- /dev/null +++ b/docs/contracts/publication-compatibility.md @@ -0,0 +1,143 @@ +# Publication compatibility contract + +This contract keeps a published source skill independent from worker vendors. +It applies to `grill-with-docs` and to any other skill that may use offload. + +## Ownership boundary + +`grill-with-docs` owns the interview workflow and the documentation workflow. It +must run with no offload, AGY, Codex, Claude, or vendor-model installation. Its +published instructions may describe an optional offload integration, but they +must not require that integration to run the interview. + +`offload` owns optional worker delegation, the orchestrator lifecycle, artifact +verification, and the execution scope check. An adapter owns one vendor's +launch syntax, output parsing, model catalog, capability probe, cancellation, +and resource identity details. The adapter receives the assignment's static +constraints. It cannot widen tool permissions, path scope, worktree scope, or +cleanup obligations. + +Capability support is not security enforcement. An adapter can report that a +worker supports structured output or cancellation. The orchestrator still +enforces filesystem isolation, frozen paths, execution scope checks, cleanup +ownership, and acceptance gates. A vendor's permission feature is never a +substitute for those checks. + +## Stable consumer contract + +Published skills depend on these stable concepts: + +- `orchestrator`, `worker`, and `adapter` roles. +- Assignment requirements and static security constraints. +- Internal model preferences: `fast`, `balanced`, and `deep`. +- Reasoning effort as a separate setting. +- Adapter-reported capabilities and a normalized result. +- Artifact, process, worktree, and resource ownership records. + +They must not depend on a vendor name, a vendor family label, an exact model +ID, or a vendor-specific feature. Exact model IDs and family hints may appear +in adapter-owned runtime records. They are metadata, not a cross-library +contract or a quality guarantee. + +## Manifest and catalog versions + +A published skill carries `publication.json` beside `SKILL.md`: + +```json +{ + "schema_version": 1, + "publication_contract_version": 1, + "skill": "grill-with-docs", + "contract": "vendor-neutral", + "imports": [], + "optional_adapters": [ + { "name": "offload", "min_version": "1.0.0" } + ], + "required_capabilities": [], + "vendor_features": [] +} +``` + +`imports` are required adapters. The compatibility check fails when an import +is absent or older than `min_version`. `optional_adapters` may be absent. A +missing optional adapter produces a warning and does not stop the source skill +from running. `required_capabilities` names a capability supplied by a named +adapter. `vendor_features` must stay empty in a published source skill. + +An adapter catalog records the available adapter contract and its capabilities: + +```json +{ + "schema_version": 1, + "adapter_contract_version": 1, + "adapters": [ + { + "name": "offload", + "version": "1.2.0", + "capabilities": ["worker-delegation", "structured-results"], + "vendor_features": ["adapter-owned-feature"] + } + ] +} +``` + +The contract version changes for incompatible manifest, adapter, helper-family, +or normalized-result changes. A minor version adds optional fields or +capabilities without changing existing meaning. A patch version fixes behavior +without changing the contract. Consumers pin the contract major and set a +minimum adapter version. Adapters may release vendor model changes within that +adapter version line. The orchestrator records the selected adapter, model +metadata, catalog revision, and every attempt for retry and resume. + +## Helper-family compatibility + +The Bash and PowerShell helper families implement equivalent observable +contracts. Each family must preserve argument order, structured-result capture, +output and error separation, ownership records, cleanup rules, and failure +classification. Their implementations may differ. + +There is no universal launcher. Select the helper family from the host shell. +Vendor command syntax stays in the adapter package. A published source skill +may link to the helper-family contract, but it must not copy a vendor command or +assume that one shell is installed. + +Run the compatibility check against a published skill and the adapter catalog: + +```bash +scripts/check-publication-compatibility.sh \ + --skill-root /path/to/published-skill \ + --catalog /path/to/adapter-catalog.json +``` + +```powershell +& scripts/check-publication-compatibility.ps1 ` + --skill-root C:\path\to\published-skill ` + --catalog C:\path\to\adapter-catalog.json +``` + +The check fails for a missing required adapter, an incompatible version, a +missing capability, a vendor feature declaration, or a vendor-specific name in +published Markdown. CI runs both helper-family checks. The check does not prove +that a worker is safe. Runtime verification remains the orchestrator's job. + +## Release and migration guidance + +The source repository is the source of truth. Edit the source skill, +`publication.json`, adapter contract, and helper-family documents there. Do not +edit generated release archives, installed skill copies, or copied adapter +catalogs directly. Regenerate or reinstall them, then run the compatibility +checks and the full contract suite before publishing. + +Release an adapter when its vendor command syntax, model catalog, or capability +probe changes. Release the source skill only when its interview or +documentation workflow changes. A vendor model release therefore updates one +adapter and its catalog record. It does not require a pull request to every +consumer skill. + +Existing AGY-only consumers migrate by removing vendor model IDs and command +examples from their source skill, adding `publication.json`, and declaring the +offload adapter as optional unless delegation is required for the workflow. +Replace vendor-specific settings with a model preference, separate effort, +required capabilities, and the normalized result fields. Keep the old AGY +adapter installed during the migration, run the compatibility checker, and +move any vendor-specific routing or security text into the adapter package. diff --git a/docs/specs/0004-claude-adapter.md b/docs/specs/0004-claude-adapter.md new file mode 100644 index 0000000..f90ca66 --- /dev/null +++ b/docs/specs/0004-claude-adapter.md @@ -0,0 +1,92 @@ +# Claude adapter contract + +The Claude adapter is a vendor-neutral worker boundary for hosts that provide the +Claude Code CLI (`claude`). It conforms to the worker adapter contract +(`docs/adapter-contract.md`) and has PowerShell and Bash entry points: + +```text +scripts/run-claude-json.ps1 --operation catalog --request +scripts/run-claude-json.ps1 --operation launch --request --output --error -- + +bash scripts/run-claude-json.sh --operation catalog --request +bash scripts/run-claude-json.sh --operation launch --request --output --error -- +``` + +The orchestrator owns assignment constraints, execution-scope verification, +final acceptance gates, resource ledgers, and lifecycle management. The adapter +owns Claude Code command syntax and response normalization. + +## Operations + +### Catalog discovery + +`--operation catalog --request ` verifies that the Claude CLI is +available and advertises structured output support via `claude --help`. It reads +model metadata from `CLAUDE_MODEL_CATALOG` or `OFFLOAD_ADAPTER_CATALOG` (or +host-provided model list) and outputs a protocol version 1 catalog JSON document +to standard output: + +```json +{ + "protocol_version": 1, + "adapter": "claude", + "adapter_revision": "claude-1", + "vendor": "anthropic", + "catalog_revision": "catalog-revision-id", + "models": [ + { + "id": "claude-3-5-sonnet-20241022", + "family_hint": "sonnet", + "available": true, + "quota_available": true, + "supported_efforts": ["low", "medium", "high"], + "capabilities": ["structured-output"], + "scores": { "fast": 2, "balanced": 1, "deep": 2 } + } + ] +} +``` + +If the CLI or catalog is unavailable, the adapter fails closed and exits +nonzero. + +### Worker launch + +`--operation launch --request --output --error -- ` +launches Claude Code with the exact model selected by the orchestrator. The +adapter parses worker arguments following the `--` delimiter (such as +`--prompt`, `--cd`, `--cancel-file`, `--timeout-seconds`, `--allowedTools`, and +`--disallowedTools`), preserving argument and path boundaries when values +contain spaces. + +The adapter enforces isolated execution: +- The working directory must contain an `.offload-execution-workspace` or + `.offload-research-workspace` marker. Unmarked workspaces fail closed. +- Nested dispatch tools `Task` and `Agent` are automatically added to + `--disallowedTools`. +- `--permission-mode` defaults to `acceptEdits`; `bypassPermissions` is rejected. +- Structured JSON output is requested via `-p --output-format json`. + +The normalized output written to `` follows the launcher result +contract: + +```json +{ + "status": "success", + "response": "ok", + "session_id": "s1", + "structured_output": { ... }, + "model_id": "claude-3-5-sonnet-20241022" +} +``` + +## Security and responsibility boundary + +The orchestrator owns assignment verification, execution scope checks, final +gates, and resource ledgers. The adapter does not run adapter-owned scope checks +or acceptance gates, nor does it generate competing private ledger schemas. + +Cancellation (signal or cancel file) terminates the process and exits with code +130. Timeout terminates the process and exits with code 124. Quota exhaustion +exits with code 75 for caller handoff. Malformed output exits with code 1, +preserving the raw output for diagnosis. diff --git a/docs/worker-adapter-contract.md b/docs/worker-adapter-contract.md new file mode 100644 index 0000000..5fc54f7 --- /dev/null +++ b/docs/worker-adapter-contract.md @@ -0,0 +1,126 @@ +# Worker adapter contract + +This document defines the boundary between the `orchestrator` and a vendor +`adapter`. An adapter runs one bounded `worker` assignment. It does not decide +the assignment, verify the result, or own cleanup outside the resources it +reports. + +The contract is versioned independently from a vendor command line. Vendor +syntax, output parsing, process handles, capability catalogs, and model +catalogs stay inside the adapter. The orchestrator only consumes the records +defined here and runs the `execution scope check` and other existing gates. + +## Assignment + +The orchestrator gives the adapter an immutable JSON assignment: + +```json +{ + "contract_version": 1, + "assignment_id": "task-17", + "request": { "prompt": "..." }, + "constraints": { + "tools": ["read", "write"], + "permissions": ["repo.read", "repo.write"], + "owned_paths": ["src"], + "frozen_paths": ["tests"], + "worktree": { "id": "worktree-17", "path": "..." }, + "artifact_root": "...", + "cleanup_resource_ids": ["process:17", "worktree:17"] + } +} +``` + +`assignment_id` must be stable across retries. `owned_paths` and +`frozen_paths` are repository-relative paths. The adapter may use fewer tools, +permissions, or paths than the assignment grants, but it cannot widen them. +The worktree and artifact root are exact identities. A result that reports a +different worktree, artifact root, or cleanup resource is rejected. + +The adapter must treat `constraints` as read-only input. It must not turn a +missing permission into an allowed permission, reinterpret a path as a parent +directory, or transfer cleanup to the orchestrator for an unreported resource. + +## Adapter operations + +Every adapter exposes these operations, whether as functions, a command +protocol, or a host-language object: + +| Operation | Required behavior | +| --- | --- | +| `discover-capabilities` | Return the adapter's available tools and permissions, without changing the assignment. | +| `discover-models` | Return model identifiers and capabilities known by this vendor. The adapter owns catalog syntax and authentication. | +| `launch` | Start exactly one worker for the assignment and return a process/job identity plus the worktree and artifact-root identities. | +| `wait` | Wait for completion up to the requested timeout and return a lifecycle state. | +| `cancel` | Request cancellation for the reported process/job identity and return its final lifecycle state. | +| `exit-status` | Return the process exit code or signal, including a still-running state when no exit exists. | +| `capture-result` | Parse the worker output into the normalized result below. Raw vendor output never crosses this boundary. | +| `ownership` | Return the process/job, worktree, and artifact resources the adapter created and can identify. | + +`launch` may not widen the static assignment. `wait`, `cancel`, and +`exit-status` may only address the identity returned by `launch`. The adapter +reports ownership; the orchestrator decides whether cleanup is safe. This +prevents an adapter from deleting a resource outside its ownership record. + +## Normalized result + +`capture-result` returns this shape: + +```json +{ + "contract_version": 1, + "assignment_id": "task-17", + "status": "succeeded", + "artifacts": [ + { "path": "...", "kind": "worker-output", "sha256": "...", "verified": false } + ], + "resources": [ + { "type": "process", "id": "process:17" }, + { "type": "worktree", "id": "worktree:17", "path": "..." } + ], + "ownership": { "resource_ids": ["process:17", "worktree:17"] }, + "constraint_snapshot": { + "tools": ["read"], + "permissions": ["repo.read"], + "owned_paths": ["src"], + "frozen_paths": ["tests"], + "worktree": { "id": "worktree-17", "path": "..." }, + "artifact_root": "...", + "cleanup_resource_ids": ["process:17", "worktree:17"] + }, + "model_selection": { + "provider": "vendor-name", + "model_id": "vendor-model-id", + "selection_reason": "matched required capability" + }, + "exit": { "code": 0, "signal": null }, + "publication": { "status": "unpublished" } +} +``` + +`status` is one of `succeeded`, `failed`, `cancelled`, or `malformed`. +`malformed` describes a worker response that the adapter could classify. An +unparseable adapter result is a contract failure instead. + +The adapter must keep every artifact below `artifact_root`, report every +resource in `ownership.resource_ids`, and set `verified` to `false`. +`publication.status` must be `unpublished`. Verification, publication, and +the final `accepted_attempt` belong to the orchestrator after the +`execution scope check` and gate commands pass. + +The normalized result always carries model-selection metadata. The +`provider`, model identifier, and selection reason are opaque to the +orchestrator. The orchestrator may compare them with its own policy, but it +does not parse vendor model catalogs. + +## Reference adapter + +The current AGY path is the reference adapter. On PowerShell it launches +through [`scripts/run-agy-json.ps1`](../scripts/run-agy-json.ps1); on POSIX +hosts it uses [`scripts/run-agy-json.sh`](../scripts/run-agy-json.sh). Those +files contain AGY argument syntax and model routing. A future adapter keeps +its own command syntax and catalog parsing in its own directory, then emits +the same assignment and normalized-result records. + +`grill-with-docs` and other host skills should depend only on this contract. +They must not contain adapter names, vendor commands, or vendor model names. diff --git a/model-policy.json b/model-policy.json index 95f54a9..87dfe0f 100644 --- a/model-policy.json +++ b/model-policy.json @@ -1,37 +1,44 @@ { - "schema_version": 1, - "policy_revision": "2026-09-03.1", + "schema_version": 2, + "policy_revision": "2026-09-04.1", "max_effort": "high", "max_retries_per_worker": 1, "quota_action": "handoff", "roles": { "scout": { - "default_model": "gemini-3.8-flash-low", - "quality_escalation": null + "preference": "fast", + "effort": "low", + "required_capabilities": [] }, "gate-author": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "implementer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "reviewer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] }, "researcher": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "synthesizer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] }, "auditor": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] } } } diff --git a/modes/execution.md b/modes/execution.md index e714dcf..e1665ef 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -6,8 +6,8 @@ Dispatches `agy` workers to implement file and code changes across independent g Select the helper family matching your current host shell: -- **POSIX shells (Bash 3.2+)**: Use `scripts/run-agy-json.sh`, `scripts/check-execution-scope.sh`, `scripts/execute-gate.sh`, and `scripts/execution-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. -- **PowerShell (PowerShell 7+)**: Use `scripts/run-agy-json.ps1`, `scripts/check-execution-scope.ps1`, `scripts/execute-gate.ps1`, and `scripts/execution-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +- **POSIX shells (Bash 3.2+)**: Use `scripts/dispatch-worker.sh`, `scripts/run-agy-json.sh`, `scripts/check-execution-scope.sh`, `scripts/execute-gate.sh`, and `scripts/execution-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. +- **PowerShell (PowerShell 7+)**: Use `scripts/dispatch-worker.ps1`, `scripts/run-agy-json.ps1`, `scripts/check-execution-scope.ps1`, `scripts/execute-gate.ps1`, and `scripts/execution-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. Check these before dispatching writing tasks: @@ -19,22 +19,37 @@ Check these before dispatching writing tasks: - PowerShell: `$Baseline = (git rev-parse HEAD).Trim()` 5. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching the first worker. All workers route through `model-policy.json`. 6. **Workspace isolation principle.** Writing workers are never dispatched directly into the caller's main checkout (``). All candidate mutations occur in isolated candidate worktrees created at the recorded baseline revision via `execution-workspace create`. +7. **Orchestrator-owned admission.** Route every worker launch through `dispatch-worker` with a dispatch ledger and explicit `--max-depth`, `--max-width`, `--max-timeout-seconds`, and `--max-resource-units` on the root assignment. The dispatcher creates the worktree and invokes the launcher. A worker's structured request for more work remains data until the orchestrator deliberately admits it as a new bounded assignment. + +Every execution dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode execution`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records the common state machine, waits for the worker to exit before cleanup, and records the exit result. Timeout and cancellation terminate the worker before cleanup; quota exhaustion hands off unfinished work immediately. Retries and resume read the resource ledger and preserve the pinned assignment, model, effort, verification baseline, and attempt limit. ## Roles and models -Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. +Workers are admitted by role using `dispatch-worker` with `--role ` and a bounded budget. The dispatcher invokes `run-agy-json`, which resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. + +The command examples below show the `agy` arguments passed after the dispatcher's `--` delimiter. In a real run, put the state path, assignment identity, parent identity when applicable, source revision, owned and frozen paths, output and error paths, workspace path, budget, and root limits on the `dispatch-worker` invocation. Do not invoke `run-agy-json` directly for an execution assignment. + +The examples use one assignment per ledger. For a parallel wave, share the ledger and set its root child-width and total resource limits to cover the whole wave. -| Role | Wave | Default model | Effort | Mode | Job | +| Role | Wave | Preference | Effort | Mode | Job | |---|---|---|---|---|---| -| scout | 1 | `gemini-3.8-flash-low` | low | `plan` | Report repository-relative file paths a task touches. | -| gate-author | 2 | `gemini-3.8-flash-high` | high | `accept-edits` | Author an executable test file from acceptance criteria. | -| implementer | 3 | `gemini-3.8-flash-high` | high | `accept-edits` | Implement the task within owned files in candidate workspace. | -| reviewer | 4 | `gemini-3.8-flash-high` | high | `plan` | Evaluate the recorded review artifact against criteria for diff-gated tasks. | +| scout | 1 | fast | low | `plan` | Report repository-relative file paths a task touches. | +| gate-author | 2 | balanced | high | `accept-edits` | Author an executable test file from acceptance criteria. | +| implementer | 3 | balanced | high | `accept-edits` | Implement the task within owned files in candidate workspace. | +| reviewer | 4 | deep | high | `plan` | Evaluate the recorded review artifact against criteria for diff-gated tasks. | `--mode plan` is a version-sensitive behavioral hint, not a write barrier. On `agy 1.1.25`, the compatibility probe blocked the tested direct write outside the permitted artifact area, but this is not a guarantee. `--add-dir` grants access without confining writes. Protection relies on isolated candidate worktrees, mechanical execution scope checks with explicit baselines, frozen path checks, and test gates. Acceptance is distinct from process completion: exit 0, a top-level success status, or prose is insufficient. Require a parsed envelope, valid substantive structured output, execution-scope and gate evidence, and an explicit accepted attempt. A gate exit 126 or 127 is classified as `unrunnable` with `verification: not_performed`; preserve the command, exit code, and diagnostic evidence, and do not schedule a quality retry. +Worker processes run through the vendor-neutral adapter boundary in +[`docs/worker-adapter-contract.md`](../docs/worker-adapter-contract.md). +Validate its normalized result with `scripts/check-worker-adapter.sh` or +`scripts/check-worker-adapter.ps1`, using the helper matching the host, before +accepting artifacts. The adapter reports process, worktree, and artifact +ownership. The orchestrator alone decides whether verification, publication, +or cleanup is allowed. + ## Step 1: Split and scout ### Provisional split @@ -50,16 +65,28 @@ Assign each task exactly one gate: ### Scout -For provisional writing tasks, dispatch scouts in parallel using the matching launcher helper with `--role scout`. Scouts run in an isolated worktree at the recorded baseline: +For provisional writing tasks, dispatch scouts in parallel through `dispatch-worker` with `--role scout`. Scouts run in an isolated worktree at the recorded baseline: #### Bash ```bash OFFLOAD_ROOT="" +DISPATCH_STATE="/offload/dispatch.json" SCOUT_WORKSPACE="/offload/scout" -git worktree add --detach "$SCOUT_WORKSPACE" "$BASELINE" SCOUT_SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "$DISPATCH_STATE" \ + --assignment-id "scout-" \ --role scout \ + --source-repo "" \ + --baseline "$BASELINE" \ + --owned "README.md" \ + --workspace-dir "$SCOUT_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --output "/offload/.attempt1.scout.json" \ --error "/offload/.attempt1.scout.err" \ -- \ @@ -74,11 +101,23 @@ SCOUT_SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"t #### PowerShell ```powershell $OffloadRoot = "" +$DispatchState = "/offload/dispatch.json" $ScoutWorkspace = "/offload/scout" -git worktree add --detach $ScoutWorkspace $Baseline $ScoutSchema = '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -& "$OffloadRoot/scripts/run-agy-json.ps1" ` +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state $DispatchState ` + --assignment-id "scout-" ` --role scout ` + --source-repo "" ` + --baseline $Baseline ` + --owned "README.md" ` + --workspace-dir $ScoutWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --output "/offload/.attempt1.scout.json" ` --error "/offload/.attempt1.scout.err" ` '--' ` @@ -108,16 +147,22 @@ For each machine-gated task, create an isolated candidate worktree at the record #### Bash ```bash -GATE_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ +GATE_WORKSPACE="/offload/gate-" +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "gate-" \ --source-repo "" \ - --task-id "gate-" \ --baseline "$BASELINE" \ --owned "" \ --frozen "" \ --frozen "" \ - --manifest "/offload/gate-.manifest.json") - -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ + --workspace-dir "$GATE_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --role gate-author \ --output "/offload/.attempt1.gate.json" \ --error "/offload/.attempt1.gate.err" \ @@ -131,16 +176,22 @@ GATE_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ #### PowerShell ```powershell -$GateWorkspace = (& "$OffloadRoot/scripts/execution-workspace.ps1" create ` +$GateWorkspace = "/offload/gate-" +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "gate-" ` --source-repo "" ` - --task-id "gate-" ` --baseline $Baseline ` --owned "" ` --frozen "" ` --frozen "" ` - --manifest "/offload/gate-.manifest.json").Trim() - -& "$OffloadRoot/scripts/run-agy-json.ps1" ` + --workspace-dir $GateWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --role gate-author ` --output "/offload/.attempt1.gate.json" ` --error "/offload/.attempt1.gate.err" ` @@ -180,16 +231,22 @@ For each task, create an isolated candidate worktree from the approved `$GATE_BA #### Bash ```bash -TASK_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ +TASK_WORKSPACE="/offload/" +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "" \ --source-repo "" \ - --task-id "" \ --baseline "$GATE_BASELINE" \ --owned "" \ --owned "" \ --frozen "" \ - --manifest "/offload/.manifest.json") - -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ + --workspace-dir "$TASK_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --role implementer \ --output "/offload/.attempt1.json" \ --error "/offload/.attempt1.err" \ @@ -203,16 +260,22 @@ TASK_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ #### PowerShell ```powershell -$TaskWorkspace = (& "$OffloadRoot/scripts/execution-workspace.ps1" create ` +$TaskWorkspace = "/offload/" +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "" ` --source-repo "" ` - --task-id "" ` --baseline $GateBaseline ` --owned "" ` --owned "" ` --frozen "" ` - --manifest "/offload/.manifest.json").Trim() - -& "$OffloadRoot/scripts/run-agy-json.ps1" ` + --workspace-dir $TaskWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --role implementer ` --output "/offload/.attempt1.json" ` --error "/offload/.attempt1.err" ` @@ -235,7 +298,7 @@ Read worker JSON responses and record outcomes in `routing-outcomes.json`: - `status: SUCCESS`: Worker completed execution. Proceed to verification in Step 5. - Non-zero exit code or unparsable output: Worker crashed or encountered an operational failure. Record the attempt and follow Step 6. - Timeout (no output written before 20m timeout): Operational failure. Record the timeout and follow Step 6. -- **Immediate quota handoff**: If explicit Gemini quota exhaustion is detected on any worker, record still-running candidates and all existing artifacts in `routing-outcomes.json` immediately without waiting for sibling completion, and hand off unfinished work directly to the calling orchestrator. +- **Immediate quota handoff**: If explicit adapter-reported quota exhaustion is detected on any worker, record still-running candidates and all existing artifacts in `routing-outcomes.json` immediately without waiting for sibling completion, and hand off unfinished work directly to the calling orchestrator. ## Step 5: Verify and integrate @@ -306,34 +369,60 @@ Verify every worker reporting `SUCCESS`: - `failure_class: "quality"` (`verification_status: "failed"`, `allow_retry: true`, other non-zero exit codes): The test assertions failed. Record the diagnostic artifact path and schedule a quality retry if attempt budget remains. - Diff gate: Dispatch an adversarial reviewer worker to inspect the recorded artifact using `--role reviewer`: - #### Bash - ```bash - REVIEW_SCHEMA='{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - "$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ - --role reviewer \ + #### Bash + ```bash + REVIEW_SCHEMA='{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' + REVIEW_WORKSPACE="/offload/-reviewer" + "$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "-reviewer" \ + --role reviewer \ + --source-repo "" \ + --baseline "$GATE_BASELINE" \ + --owned "README.md" \ + --workspace-dir "$REVIEW_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --output "/offload/.attempt1.review.json" \ --error "/offload/.attempt1.review.err" \ - -- \ + -- \ -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " \ - --output-format json \ - --mode plan \ + --output-format json \ + --mode plan \ --json-schema "$REVIEW_SCHEMA" \ --add-dir "" \ --add-dir "" \ --print-timeout 20m ``` - #### PowerShell - ```powershell - $ReviewSchema = '{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - & "$OffloadRoot/scripts/run-agy-json.ps1" ` - --role reviewer ` + #### PowerShell + ```powershell + $ReviewSchema = '{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' + $ReviewWorkspace = "/offload/-reviewer" + & "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "-reviewer" ` + --role reviewer ` + --source-repo "" ` + --baseline $GateBaseline ` + --owned "README.md" ` + --workspace-dir $ReviewWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --output "/offload/.attempt1.review.json" ` --error "/offload/.attempt1.review.err" ` - '--' ` + '--' ` -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " ` - --output-format json ` - --mode plan ` + --output-format json ` + --mode plan ` --json-schema $ReviewSchema ` --add-dir "" ` @@ -366,12 +455,17 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Stable worker IDs and retry ceiling.** Assign a stable `worker_id` to each logical task. Attempt 1 is initial dispatch; attempt 2 is its only possible retry. Maximum two attempts total per task. - **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. - **Baseline retention on retry.** Retries must retain the original verification baseline for that writing stage (e.g. `$GATE_BASELINE`). A failed attempt never becomes an implicitly trusted baseline. Create a fresh candidate worktree at the original baseline for attempt 2. -- **Implementer quality failure.** If an execution scope check violation occurs or a machine gate normalizes to `failure_class: "quality"` (non-zero exit code other than 126/127), this constitutes a quality failure. If a retry remains (attempt 2), redispatch once with the specific failure output and diagnostic evidence. Use `--route quality-retry` only if an evidence-backed escalation target is configured for `implementer` in `model-policy.json`; otherwise use `--route default`. If attempt 2 fails, halt that task. +- **Implementer quality failure.** If an execution scope check violation occurs or a machine gate normalizes to `failure_class: "quality"` (non-zero exit code other than 126/127), this constitutes a quality failure. If a retry remains (attempt 2), redispatch once with the specific failure output and diagnostic evidence using the pinned selection. If the pinned model is unavailable, record the explicit fallback or handoff and do not switch silently. If attempt 2 fails, halt that task. - **Unrunnable gate execution.** If a gate command exits 126 or 127, it normalizes to `failure_class: "unrunnable"` with `verification_status: "not_performed"` and `allow_retry: false`. Gate exits 126 and 127 are not quality retries; preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json` without spending or scheduling a quality retry. - **Scout or gate-author operational failure.** If a scout or gate-author crashes, times out, or produces unparsable output, retry once using `--route default`. If the retry fails, complete that step directly as the orchestrator (`orchestrator (fallback)`). - **Reviewer failure.** If reviewer output is unparsable or fails digest or quote verification, inspect the recorded artifact directly as the orchestrator (`agy→orchestrator`). -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Record still-running candidates immediately without waiting for siblings, preserve completed artifacts, and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Record still-running candidates immediately without waiting for siblings, preserve completed artifacts, and return unfinished work to the calling orchestrator. - **Workspace cleanup.** After workers have terminated, clean up candidate worktrees: - Bash: `"$OFFLOAD_ROOT/scripts/execution-workspace.sh" cleanup --manifest "" --status success|failed|retain` - PowerShell: `& "$OffloadRoot/scripts/execution-workspace.ps1" cleanup --manifest "" --status success|failed|retain` Wait for active worker processes to terminate before calling cleanup. Pass `--status retain` if preserving a candidate workspace for orchestrator inspection. + +- **Ownership ledger and crash recovery.** Candidate worktrees, research workspaces, and worker processes are recorded in an orchestrator-owned ledger outside their resource paths. Register a resource before or immediately after creation, update it as the lifecycle changes (`active`, `failed`, `timed_out`, `cancelled`, `quota_handoff`, `cleanup_pending`, or `completed`), and run reconciliation at the start of a later run: + - Bash: `"$OFFLOAD_ROOT/scripts/resource-ledger.sh" reconcile --ledger "" --source-repo ""` + - PowerShell: `& "$OffloadRoot/scripts/resource-ledger.ps1" reconcile --ledger "" --source-repo ""` + Cleanup terminates and waits for an owned worker process before touching its resources. It removes only records whose owner marker, parent relationship, and Git/worktree safety checks pass. Dirty, unmerged, unknown, ambiguous, or otherwise unprovable resources remain on disk and in the ledger for review. Never place the ledger inside a worker checkout. diff --git a/modes/repo-research.md b/modes/repo-research.md index 21619e0..a99c0b6 100644 --- a/modes/repo-research.md +++ b/modes/repo-research.md @@ -9,7 +9,9 @@ Select the helper family matching your current host shell: - **POSIX shells (Bash 3.2+)**: Use `scripts/make-research-workspace.sh`, `scripts/run-agy-json.sh`, and `scripts/cleanup-research-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. - **PowerShell (PowerShell 7+)**: Use `scripts/make-research-workspace.ps1`, `scripts/run-agy-json.ps1`, and `scripts/cleanup-research-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. -Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects the current model. Do not pass `--model` or `--effort` directly. + +Every research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode repo-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records worker exit results and retains diagnosis artifacts for failed, canceled, timed-out, malformed, or quota-handoff runs. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. ## Assignment requirements @@ -44,7 +46,7 @@ The workspace helper creates a unique temporary directory, writes the `.offload- ## Worker dispatch -Dispatch researchers in parallel using role `researcher` with a structured schema and the matching launcher helper. The launcher resolves `gemini-3.8-flash-high` from `model-policy.json`: +Dispatch researchers in parallel using role `researcher` with a structured schema and the matching launcher helper. The launcher asks the adapter to select a current eligible model: #### Bash ```bash @@ -103,7 +105,7 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. - **Operational failure.** If a worker crashes, times out, or produces unparsable output, redispatch once using `--route default`. No model escalation for operational failure. - **Orchestrator fallback.** If the second attempt fails or findings remain inconclusive, complete the investigation directly as the orchestrator (`orchestrator (fallback)`). -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. ## Cleanup diff --git a/modes/web-research.md b/modes/web-research.md index 9105c01..2e2b205 100644 --- a/modes/web-research.md +++ b/modes/web-research.md @@ -11,7 +11,9 @@ Conducts cited online investigations and multi-angle technical research by dispa - **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. 4. **`agy` availability.** Workers are launched using the matching `run-agy-json` helper, which handles `AGY_BIN` precedence and output capture. 5. **Filesystem isolation.** Every research run operates in a disposable workspace outside the live repository. -6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects a current eligible model. Do not pass `--model` or `--effort` directly. + +Every web-research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode web-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher waits for worker exit before cleanup, preserves diagnosis evidence for non-successful runs, and hands off quota-exhausted work without waiting for sibling workers. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. ## Worker isolation and mixed repositories @@ -60,11 +62,11 @@ Record the specific deep trigger in the final report and in `provenance.json`. I Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. -| Role | Stage | Default model | Effort | Alternative model | Mode | Job | +| Role | Stage | Preference | Effort | Alternative model | Mode | Job | |---|---|---|---|---|---|---| -| researcher | 1 | `gemini-3.8-flash-high` | high | — | `plan` | Gathers structured claims and citations for an assigned evidence angle. | -| synthesizer | 2 | `gemini-3.8-flash-high` | high | — | `plan` | Builds claim ledger, resolves agreements/conflicts, and drafts synthesis. | -| auditor | 3 | `gemini-3.8-flash-high` | high | — | `plan` | Independently verifies every citation in the proposed final answer. | +| researcher | 1 | balanced | high | adapter catalog | `plan` | Gathers structured claims and citations for an assigned evidence angle. | +| synthesizer | 2 | deep | high | adapter catalog | `plan` | Builds claim ledger, resolves agreements/conflicts, and drafts synthesis. | +| auditor | 3 | deep | high | adapter catalog | `plan` | Independently verifies every citation in the proposed final answer. | A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro synthesizer and auditor split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. See [`tests/live-smoke-comparison.md`](../tests/live-smoke-comparison.md) for the recorded judgment. @@ -385,7 +387,7 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Researcher failure.** If a researcher crashes, times out, or produces unparsable output, retry once with the error details using `--route default`. The selection gate admits only the verified accepted attempt for each assignment. If a retry fails, synthesis proceeds as long as at least two distinct `angle_id` values remain; otherwise use the partial-result fallback. The final report explicitly names any omitted angle. - **Synthesis or audit failure.** Synthesis and citation audit are mandatory stages. The allowed synthesizer revision pass consumes the synthesizer's second attempt. The subsequent audit consumes the auditor's second attempt. If either stage crashes, times out, returns unparsable JSON, or fails to resolve citations after exhausting its 2-attempt budget, the run transitions to `partial` status. - **Partial result contract.** A `partial` run returns audited claims and raw findings collected up to the point of failure, but strictly withholds a firm synthesis or recommendation. State the failed stage explicitly and retain all raw artifacts for debugging. -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. ## Provenance and cleanup @@ -410,10 +412,18 @@ At the conclusion of the research run: "role": "researcher", "mode": "web-research", "attempt": 1, - "policy_revision": "2026-09-03.1", + "policy_revision": "2026-09-04.1", "route": "default", - "model": "gemini-3.8-flash-high", + "adapter": "agy", + "adapter_revision": "adapter-revision", + "vendor": "vendor-family", + "model_id": "exact-model-id", + "model": "exact-model-id", + "family_hint": "family-hint", + "preference": "balanced", "effort": "high", + "catalog_revision": "catalog-revision", + "selection_reason": "Eligible catalog candidate ranked highest for the role preference", "reason": "Initial default dispatch", "started_at": "2026-09-03T00:00:00Z", "ended_at": "2026-09-03T00:01:30Z", @@ -437,10 +447,18 @@ At the conclusion of the research run: "role": "researcher", "mode": "web-research", "attempt": 2, - "policy_revision": "2026-09-03.1", + "policy_revision": "2026-09-04.1", "route": "default", - "model": "gemini-3.8-flash-high", + "adapter": "agy", + "adapter_revision": "adapter-revision", + "vendor": "vendor-family", + "model_id": "exact-model-id", + "model": "exact-model-id", + "family_hint": "family-hint", + "preference": "balanced", "effort": "high", + "catalog_revision": "catalog-revision", + "selection_reason": "Pinned selection retained after a retry", "reason": "Retry authorized after quality gate failure on attempt 1", "started_at": "2026-09-03T00:02:00Z", "ended_at": "2026-09-03T00:03:30Z", diff --git a/scripts/agy-adapter.ps1 b/scripts/agy-adapter.ps1 new file mode 100644 index 0000000..5a8e1bb --- /dev/null +++ b/scripts/agy-adapter.ps1 @@ -0,0 +1,165 @@ +#!/usr/bin/env pwsh +# Reference worker adapter. Vendor-specific AGY syntax lives here, not in the launcher. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Fail([string]$message, [int]$exitCode = 2) { + [Console]::Error.WriteLine("ERROR: $message") + exit $exitCode +} + +function Resolve-Program([string]$path) { + if ([string]::IsNullOrWhiteSpace($path)) { Fail 'AGY_BIN is empty' } + if ($path.EndsWith('.ps1', [System.StringComparison]::OrdinalIgnoreCase)) { + return @{ File = (Get-Command pwsh -ErrorAction Stop).Source; Prefix = @('-NoProfile', '-NonInteractive', '-File', $path) } + } + return @{ File = $path; Prefix = @() } +} + +function Invoke-Captured([string]$file, [string[]]$arguments, [string]$stdoutPath, [string]$stderrPath) { + $psi = [System.Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $file + $psi.UseShellExecute = $false + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + foreach ($argument in $arguments) { [void]$psi.ArgumentList.Add($argument) } + $process = [System.Diagnostics.Process]::new() + $process.StartInfo = $psi + try { + if (-not $process.Start()) { Fail "failed to start adapter command: $file" 127 } + $stdoutTask = $process.StandardOutput.ReadToEndAsync() + $stderrTask = $process.StandardError.ReadToEndAsync() + $process.WaitForExit() + [System.IO.File]::WriteAllText($stdoutPath, $stdoutTask.Result, [System.Text.Encoding]::UTF8) + [System.IO.File]::WriteAllText($stderrPath, $stderrTask.Result, [System.Text.Encoding]::UTF8) + return $process.ExitCode + } finally { + $process.Dispose() + } +} + +function Get-FamilyHint([string]$modelId) { + if ($modelId -match '^gemini-[^-]+-(?flash|pro)-') { return $Matches.family } + if ($modelId -match '^claude-[^-]+-(?opus|sonnet|haiku)') { return $Matches.family } + if ($modelId -match '^gpt-oss-') { return 'oss' } + return 'unknown' +} + +function Get-PreferenceScore([string]$family, [string]$preference) { + $scores = @{ + fast = @{ flash = 1; haiku = 2; oss = 2; sonnet = 3; pro = 4; opus = 5; unknown = 100 } + balanced = @{ sonnet = 1; flash = 2; oss = 3; pro = 3; haiku = 4; opus = 5; unknown = 100 } + deep = @{ opus = 1; pro = 2; sonnet = 3; oss = 4; flash = 5; haiku = 6; unknown = 100 } + } + if ($scores.ContainsKey($preference) -and $scores[$preference].ContainsKey($family)) { return $scores[$preference][$family] } + return 100 +} + +function Convert-ModelListToCatalog([string]$raw) { + $models = @( + foreach ($line in ($raw -split "`r?`n")) { + if ($line -notmatch '^\s*(?\S+)\s+(?