From b05dfc7982283ffb78881dac4c999f7f586cc0e3 Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Sat, 5 Sep 2026 16:35:14 +0800 Subject: [PATCH 1/2] docs: record compatible worker selection decision --- CONTEXT.md | 12 ++++- ...patible-workers-before-offering-offload.md | 53 +++++++++++++++++++ 2 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 docs/adr/0009-select-compatible-workers-before-offering-offload.md diff --git a/CONTEXT.md b/CONTEXT.md index 04b8657..81cdde1 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,6 +1,6 @@ # Offload context -Offload delegates bounded work to `agy` processes while the calling agent remains responsible for scope, verification, and reporting. +Offload delegates bounded work through compatible worker adapters while the calling agent remains responsible for scope, verification, and reporting. AGY is the current default adapter. ## Publication boundary @@ -24,9 +24,17 @@ The calling agent that plans assignments, dispatches workers, and verifies their _Avoid_: Controller, parent agent **Worker**: -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. +A process launched through a compatible adapter and 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 +**Compatible worker adapter**: +An adapter that implements the worker contract and has verified support for the assignment's required capabilities. An installed agent CLI alone does not establish compatibility. +_Avoid_: Any installed CLI, universal worker support + +**Worker selection**: +The orchestrator's choice of a configured, compatible worker provider before making an offload offer. Selection checks authenticated access, current entitlement, and usage limits against the assignment, verification, and one retry, accounting for workers sharing quota. Rank eligible workers by task capability and expected quality, with remaining capacity as the tie-breaker. Unknown usage excludes automatic selection but permits explicit user selection with disclosed uncertainty and otherwise established access. An explicit user provider choice takes precedence, subject to eligibility checks. The offer names the selected worker and explains the choice. This accepted behavior is pending implementation. See ADR 0009. +_Avoid_: Always offer AGY, implicit provider switch + **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 diff --git a/docs/adr/0009-select-compatible-workers-before-offering-offload.md b/docs/adr/0009-select-compatible-workers-before-offering-offload.md new file mode 100644 index 0000000..b25db19 --- /dev/null +++ b/docs/adr/0009-select-compatible-workers-before-offering-offload.md @@ -0,0 +1,53 @@ +# ADR 0009: Select compatible workers before offering offload + +- Status: accepted, implementation pending +- Date: 2026-09-05 +- Extends: ADR 0003 and ADR 0008 + +## Context + +The host routing instructions still say to offer AGY. The implementation already accepts an adapter override, but the documentation and workflow arguments retain AGY assumptions. A fixed provider name in global instructions hides the adapter choice and encourages hosts to keep suggesting the same worker. + +## Decision + +The orchestrator chooses a worker from configured, compatible adapters before making the offload offer. The offer names that worker and gives a brief reason for choosing it. A provider explicitly named by the user takes precedence, subject to compatibility and availability checks. Existing offer thresholds, authorization, and once-per-session refusal handling remain in force. + +Support means any orchestrator capable of reading the skill and running its shell helpers can delegate to a worker through a compatible adapter with verified required capabilities. Installing an arbitrary agent CLI does not establish worker support. Vendor launch syntax and output translation remain adapter responsibilities. + +Worker selection must check which providers the user can actually access through authenticated adapters and read current usage limits before assessing whether a provider can handle the assignment. CLI installation and a catalog entry alone do not establish available quota. Adapters own provider-specific usage retrieval and normalization, including the applicable limit windows, remaining allowance, reset times, and observation time when available. Missing data must remain distinguishable from confirmed available capacity. + +Eligibility requires current access to the selected worker and model under the intended account and billing route. A saved login or installed CLI is insufficient. If subscription access has expired and no authorized alternative access remains, exclude that provider. Do not silently switch to paid API billing to make it eligible. A quota percentage alone is insufficient evidence of entitlement. + +Providers with unavailable usage data are excluded from automatic selection. The user may explicitly choose such a provider after the uncertainty is disclosed, provided access and required capabilities are otherwise established. This exception does not override known access failures or quota exhaustion. + +Capacity estimates include the assignment, verification, and one retry, accounting for other workers sharing the same quota. Begin with conservative estimates and refine them from recorded runs. Among eligible workers, rank by task capability and expected quality, then use remaining capacity as the tie-breaker. + +## Consequences + +Host instructions must describe worker selection without fixing the provider to AGY. Adapter selection must preserve assignment requirements through launch and result validation. Accepted architecture does not establish that the current adapters are interchangeable in every workflow. + +This decision does not authorize silent provider switching on retry or quota exhaustion; ADR 0008 and the existing handoff rules still apply. + +The estimation algorithm, numeric thresholds, and usage freshness interval remain implementation details to specify and validate. A remaining-usage percentage alone does not guarantee that an assignment will finish. + +## Usage interface evidence + +Checked on 2026-09-05. These establish available interfaces, not completed offload integration. + +- [AGY CLI reference](https://www.agy.dev/docs/cli/reference/) documents `/usage`, with `/quota` as an alias, for model quota usage. The [headless guide](https://www.agy.dev/docs/cli/headless/) warns that slash commands such as `/usage` break streaming JSON flow. The installed version's standalone quota output still needs validation. +- [Claude commands](https://code.claude.com/docs/en/commands) documents `/usage` for plan limits and activity. [Status-line data](https://code.claude.com/docs/en/statusline) can expose five-hour and seven-day usage and reset times, subject to version and account support, only after the first API response. This does not establish a fresh pre-dispatch query by itself. +- [Codex app-server](https://learn.chatgpt.com/docs/app-server) provides `account/rateLimits/read`. The Codex desktop usage tool also returned live short-window and weekly limits during this audit. A portable adapter integration remains to be implemented. + +## Verified baseline + +Read-only inspection on 2026-09-05 established the following. No live Claude or Codex worker run was performed in this audit. + +- The shared host instruction source, `%APPDATA%/skillshare/skills/global-config/CLAUDE.md`, lines 14-18, tells hosts to offer AGY. The inspected Claude, Codex, Gemini, and OpenCode global instructions contain that wording. Codex and OpenCode link to the shared source. +- The inspected Claude and Codex hook registrations invoke `global-config/scripts/skillshare-sync.ps1`. They do not directly contain the AGY offer. Editing generated host copies alone would leave the shared source stale. +- The installed and repository `SKILL.md` files had matching SHA-256 hashes. The installed scripts include AGY, Claude, and Codex adapters, so the problem is not simply an old installed router. +- `scripts/run-agy-json.ps1:175` accepts `--adapter`, then `OFFLOAD_ADAPTER_BIN`, and defaults to `agy-adapter.ps1`. The launcher filename does not restrict dispatch to AGY. No process or user adapter override was configured during inspection. +- `SKILL.md:35` and `SKILL.md:42` still require AGY. `modes/repo-research.md` supplies an inline JSON schema through `--json-schema`. +- `scripts/run-codex-json.ps1:238` treats that schema argument as a path. Its later schema handling substitutes a generic schema when the path does not exist. The inline schema therefore does not reach Codex as the requested schema through this path. +- The Claude adapter's catalog branch probes CLI output support and reads a supplied catalog. It does not verify current subscription entitlement. String model entries set `available` and `quota_available` to true; object entries default missing values to true. It therefore does not yet implement the eligibility checks in this decision. + +The AGY research worker supplied additional claims. The orchestrator rejected its assertion that the launcher filename makes dispatch AGY-only and did not accept its blanket claim that every non-AGY workflow fails. The findings above reflect direct inspection, not those broader claims. From d274a706444ae88adbe51c0c6691c4bc969d7e7d Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Sat, 5 Sep 2026 17:55:31 +0800 Subject: [PATCH 2/2] feat: select compatible workers before offload --- CONTEXT.md | 6 +- README.md | 24 ++-- SKILL.md | 19 +-- docs/adapter-contract.md | 83 +++++++++---- docs/codex-adapter.md | 26 +++- docs/worker-adapter-contract.md | 14 ++- model-policy.json | 7 ++ modes/execution.md | 10 +- modes/repo-research.md | 4 +- modes/web-research.md | 8 +- scripts/agy-adapter.ps1 | 14 ++- scripts/agy-adapter.sh | 7 +- scripts/capacity-ledger.ps1 | 107 +++++++++++++++++ scripts/capacity-ledger.sh | 78 ++++++++++++ scripts/run-agy-json.ps1 | 29 ++--- scripts/run-agy-json.sh | 35 +++--- scripts/run-claude-json.ps1 | 15 ++- scripts/run-claude-json.sh | 7 +- scripts/run-codex-json.ps1 | 24 +++- scripts/run-codex-json.sh | 23 +++- scripts/select-compatible-worker.ps1 | 112 ++++++++++++++++++ scripts/select-compatible-worker.sh | 95 +++++++++++++++ tests/test_agy_helpers.sh | 5 +- tests/test_capacity_ledger.ps1 | 60 ++++++++++ tests/test_claude_adapter.ps1 | 7 +- tests/test_claude_adapter.sh | 6 +- tests/test_codex_adapter.ps1 | 21 +++- tests/test_dispatch_control.ps1 | 33 +++++- tests/test_model_routing.ps1 | 7 +- tests/test_model_routing.sh | 12 +- tests/test_research_helpers.ps1 | 10 +- tests/test_research_modes.sh | 5 +- tests/test_review_probe_contract.ps1 | 29 +++++ tests/test_verification_hardening_docs.ps1 | 4 +- .../test_verification_hardening_launcher.ps1 | 10 +- tests/test_worker_lifecycle.ps1 | 9 +- 36 files changed, 815 insertions(+), 150 deletions(-) create mode 100644 scripts/capacity-ledger.ps1 create mode 100644 scripts/capacity-ledger.sh create mode 100644 scripts/select-compatible-worker.ps1 create mode 100644 scripts/select-compatible-worker.sh create mode 100644 tests/test_capacity_ledger.ps1 diff --git a/CONTEXT.md b/CONTEXT.md index 81cdde1..1f9e204 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,6 +1,6 @@ # Offload context -Offload delegates bounded work through compatible worker adapters while the calling agent remains responsible for scope, verification, and reporting. AGY is the current default adapter. +Offload delegates bounded work through compatible worker adapters while the calling agent remains responsible for scope, verification, and reporting. The repository includes a reference adapter, but selection is provider-neutral. ## Publication boundary @@ -32,8 +32,8 @@ An adapter that implements the worker contract and has verified support for the _Avoid_: Any installed CLI, universal worker support **Worker selection**: -The orchestrator's choice of a configured, compatible worker provider before making an offload offer. Selection checks authenticated access, current entitlement, and usage limits against the assignment, verification, and one retry, accounting for workers sharing quota. Rank eligible workers by task capability and expected quality, with remaining capacity as the tie-breaker. Unknown usage excludes automatic selection but permits explicit user selection with disclosed uncertainty and otherwise established access. An explicit user provider choice takes precedence, subject to eligibility checks. The offer names the selected worker and explains the choice. This accepted behavior is pending implementation. See ADR 0009. -_Avoid_: Always offer AGY, implicit provider switch +The orchestrator's choice of a configured, compatible worker provider before making an offload offer. Selection checks authenticated access, current entitlement, and usage limits against the assignment, verification, and one retry, accounting for workers sharing quota. Rank eligible workers by task capability and expected quality, with remaining capacity as the tie-breaker. Unknown usage excludes automatic selection but permits explicit user selection with disclosed uncertainty and otherwise established access. An explicit user provider choice takes precedence, subject to eligibility checks. The offer names the selected worker and explains the choice. The protocol-2 selector and capacity ledger implement this behavior. See ADR 0009. +_Avoid_: Always offer one provider, implicit provider switch **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. diff --git a/README.md b/README.md index dbd69be..6d8cd85 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # offload -`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`. +`offload` is an agent-agnostic skill that delegates plan execution and research tasks to headless workers through a configured vendor adapter. The repository includes a reference adapter, but selection and admission use a provider-neutral contract. -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. +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. The configured adapter launches 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. @@ -28,7 +28,7 @@ cleanup, and acceptance gates. - **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. +- **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 included launcher is a 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. @@ -38,14 +38,14 @@ cleanup, and acceptance gates. | Host path | Required runtime | Required tools | CI system | |---|---|---|---| -| Native Windows | PowerShell 7+ | Git and `agy` | `windows-latest` | -| Linux with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `ubuntu-latest` | -| macOS with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `macos-latest` | -| Linux or macOS with PowerShell | PowerShell 7+ | Git and `agy` | Supported by contract, not a required CI job | +| Native Windows | PowerShell 7+ | Git and a configured adapter | `windows-latest` | +| Linux with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `ubuntu-latest` | +| macOS with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `macos-latest` | +| Linux or macOS with PowerShell | PowerShell 7+ | Git and a configured adapter | Supported by contract, not a required CI job | ### Helper family selection -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`. +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 the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. ### Claude adapter @@ -66,7 +66,7 @@ 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). -- [`agy`](https://antigravity.google), the Antigravity CLI, available on `PATH`, user-local bin (`~/.local/bin/agy` on POSIX, `%USERPROFILE%\.local\bin\agy.exe` on Windows), or configured via `AGY_BIN`. +- The configured adapter, available on `PATH` or at the path accepted by the launcher. The included reference adapter can use `agy`, but no provider is assumed by the public contract. - For execution workflows: a git repository with a clean working tree (`git status --porcelain` is empty). Research workflows run in disposable workspaces. ## Installation @@ -348,11 +348,11 @@ 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 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. +- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts a compatible-worker offer. +- Offer a selected compatible worker 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. -- Ask once per session. If the user declines, continue locally without offering AGY again in that session. +- Ask once per session. If the user declines, continue locally without offering another worker in that session. - When Offload applies, let its skill instructions choose the appropriate workflow mode. ``` diff --git a/SKILL.md b/SKILL.md index 8d71c22..78900c4 100644 --- a/SKILL.md +++ b/SKILL.md @@ -9,7 +9,7 @@ If you are a dispatched worker, stop here. Return worker results to your orchest ## What this skill does -`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. +`offload` delegates execution and research tasks to headless workers through a configured adapter. A reference adapter is included, 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. @@ -32,19 +32,20 @@ checks, cleanup, and acceptance gates. Select the helper family matching your current host shell: -- **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `agy`, `jq`, and Python 3. -- **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`. +- **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `jq`, Python 3, and the configured adapter's own executable. +- **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. Check these requirements before dispatching workers: 1. **Offer before dispatch.** When reaching this skill unprompted, offer the choice to the user first following the proactive offer contract. Describe the planned dispatch and ask for confirmation. Ask once per session. A negative response settles the decision for the rest of the session. 2. **Local factual lookups.** Keep a single factual lookup local with the orchestrator; do not offer or route it to offload. -3. **`agy` availability.** Verify `agy` is invokable. The launcher resolves `AGY_BIN` first if set, then `PATH`, then the user-local bin directory (`~/.local/bin/agy` on POSIX, `%USERPROFILE%\.local\bin\agy.exe` on Windows). An invalid explicit `AGY_BIN` fails immediately without fallback. +3. **Adapter availability.** Verify the configured adapter is invokable and can return a protocol-2 catalog. The adapter must prove authenticated access, current entitlement, billing route, and usage capacity for the selected account and model. An installed CLI or static catalog entry is not enough. 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: +5. **Preflight compatible-worker 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). - - 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. + - Ask the configured adapters for live catalogs, then filter by verified access, entitlement, billing route, fresh usage, required capabilities, and supported effort. + - Estimate assignment, verification, and one retry unit, including active shared reservations. If no eligible worker 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. + - An explicit provider is checked first and is never replaced silently. Unknown usage is allowed only for an explicit provider after the other checks pass, and the selection records the uncertainty. - 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`). @@ -80,8 +81,8 @@ Offload routes all workers through the repository-root `model-policy.json` and t 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 '--' ` +- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --adapter --provider --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger -- ` +- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --adapter --provider --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger '--' ` In PowerShell command expressions, always quote the delimiter (`'--'`). diff --git a/docs/adapter-contract.md b/docs/adapter-contract.md index 7043d30..a6ed784 100644 --- a/docs/adapter-contract.md +++ b/docs/adapter-contract.md @@ -1,8 +1,13 @@ -# Worker adapter contract +# Worker adapter catalog contract -Status: accepted. Protocol version 1. +Status: accepted. Catalog protocol version 2. -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. +The launcher owns policy, selection, retry identity, capacity admission, and +filesystem scope. An adapter owns vendor syntax, authenticated discovery, and +the live catalog. The public workflow names a worker role, an internal +preference (`fast`, `balanced`, or `deep`), a reasoning effort, and required +capabilities. It does not name a vendor or exact model ID unless the user +explicitly chooses one. ## Operations @@ -13,35 +18,69 @@ 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: +`REQUEST.json` contains the role, preference, effort, required capabilities, +policy revision, route, and protocol version. The catalog operation writes one +JSON object to stdout. A catalog must report the adapter revision, vendor, +catalog revision, model entries, and a normalized preflight record for each +candidate: ```json { - "protocol_version": 1, - "adapter": "agy", - "adapter_revision": "1", - "vendor": "provider", + "protocol_version": 2, + "adapter": "configured-adapter", + "adapter_revision": "adapter-2", + "vendor": "provider-name", "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} + "models": [{ + "id": "provider-exact-model-id", + "supported_efforts": ["low", "high"], + "capabilities": ["structured-output"], + "scores": {"fast": 1, "balanced": 2, "deep": 3}, + "preflight": { + "access": {"state": "verified", "reason": "authenticated", "account_ref": "nonsecret-account-ref"}, + "entitlement": {"state": "active", "reason": "subscription", "billing_route": "included"}, + "usage": { + "state": "known", + "observed_at": "2026-09-05T00:00:00Z", + "source": "provider-usage", + "scopes": [{"scope_id": "account-window", "remaining_units": 8, "reserved_units": 0, "reset_at": "2026-09-05T01:00:00Z"}] + } } - ] + }] } ``` -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. +Access, entitlement, billing, and usage observations must be current, scoped, +and explainable. Missing, malformed, stale, unsupported, or optimistic +observations never become available capacity. The selector requires known +fresh usage for automatic selection. An explicit provider may proceed with +unknown usage only after access, capability, entitlement, and billing checks +pass, with the uncertainty recorded in the selection. -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. +The selector rejects expired entitlements, paid-fallback routes, explicit +ineligibility, and candidates that cannot cover the assignment, verification, +and one allowed retry. It ranks eligible candidates by the role preference and +capabilities first, remaining capacity second, and stable provider/model +identity last. Family labels and installed CLIs do not establish quality or +access. + +The selection record includes the normalized preflight evidence, a capacity +estimate, and reservation scopes. The launcher reserves those scopes before a +managed launch, then records completion, cancellation, failure, or recovery. +Competing admissions use an atomic ledger. Reservation and usage evidence +must not contain credentials, tokens, or private account data. ## 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. +The launcher writes the complete selection record when `--selection-output` is +supplied. The orchestrator copies it 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, +provider, account or billing route, exact model ID, effort, and current +eligibility. A missing pinned model fails explicitly and requires a recorded +fallback or handoff. No retry silently changes provider, model, effort, or +billing route. At most one retry is allowed for an assignment. -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. +Adapters keep 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/codex-adapter.md b/docs/codex-adapter.md index 481bd74..5c07559 100644 --- a/docs/codex-adapter.md +++ b/docs/codex-adapter.md @@ -38,13 +38,13 @@ JSON document or a path to one: } ``` -The adapter emits a protocol version 1 catalog document to standard output: +The adapter emits a protocol version 2 catalog document to standard output: ```json { - "protocol_version": 1, + "protocol_version": 2, "adapter": "codex", - "adapter_revision": "codex-1", + "adapter_revision": "codex-2", "vendor": "codex", "catalog_revision": "host-catalog-1", "models": [ @@ -55,15 +55,29 @@ The adapter emits a protocol version 1 catalog document to standard output: "quota_available": true, "supported_efforts": ["low", "medium", "high"], "capabilities": ["structured-output"], - "scores": { "fast": 2, "balanced": 1, "deep": 2 } + "scores": { "fast": 2, "balanced": 1, "deep": 2 }, + "preflight": { + "access": { "state": "verified", "account_ref": "account-ref" }, + "entitlement": { "state": "active", "billing_route": "subscription" }, + "usage": { + "state": "known", + "source": "codex-usage", + "observed_at": "2026-09-05T00:00:00Z", + "scopes": [ + { "scope_id": "account-window", "remaining_units": 12, "reserved_units": 0 } + ] + } + } } ] } ``` 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. +IDs. Access, entitlement, billing, and usage are independent preflight facts. +Missing or stale facts remain unknown and cannot be selected as compatible. If +the CLI flags or catalog are unavailable, the adapter fails closed and exits +nonzero. ### Worker launch diff --git a/docs/worker-adapter-contract.md b/docs/worker-adapter-contract.md index 5fc54f7..c3883f3 100644 --- a/docs/worker-adapter-contract.md +++ b/docs/worker-adapter-contract.md @@ -115,12 +115,14 @@ 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. +The repository includes a reference adapter and vendor-neutral launcher path. +On PowerShell it uses [`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). +The filenames preserve compatibility with existing installations, but the +launcher accepts a configured adapter and the catalog protocol is provider +neutral. Each adapter keeps its command syntax and catalog parsing behind the +adapter boundary, 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 87dfe0f..3b5ad18 100644 --- a/model-policy.json +++ b/model-policy.json @@ -4,6 +4,13 @@ "max_effort": "high", "max_retries_per_worker": 1, "quota_action": "handoff", + "capacity_estimation": { + "version": 1, + "assignment_units": 1, + "verification_units": 1, + "retry_units": 1, + "usage_freshness_seconds": 300 + }, "roles": { "scout": { "preference": "fast", diff --git a/modes/execution.md b/modes/execution.md index e1665ef..5a2f196 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -1,17 +1,17 @@ # Execution mode -Dispatches `agy` workers to implement file and code changes across independent gated tasks through isolated workspaces. +Dispatches configured workers to implement file and code changes across independent gated tasks through isolated workspaces. ## Preconditions and helper selection Select the helper family matching your current host shell: -- **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`. +- **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, `jq`, Python 3, and the configured adapter's executable. +- **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 the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. Check these before dispatching writing tasks: -1. **`agy` is available.** Verify `agy` via `run-agy-json` or ensure `agy` is on `PATH`, user-local bin, or `AGY_BIN`. +1. **The configured adapter is available.** Verify it through `run-agy-json` and require a protocol-2 catalog with verified access and capacity. 2. **Target is a git repository.** Run `git rev-parse --is-inside-work-tree`. 3. **Working tree is clean.** Run `git status --porcelain`. A clean tree is required to track edits, isolate changes, and roll back failed tasks. 4. **Record baseline revision.** Record the caller repository baseline before creating workspaces: @@ -27,7 +27,7 @@ Every execution dispatch supplies the shared lifecycle metadata to `run-agy-json 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 command examples below show adapter 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. diff --git a/modes/repo-research.md b/modes/repo-research.md index a99c0b6..fda1c2c 100644 --- a/modes/repo-research.md +++ b/modes/repo-research.md @@ -6,8 +6,8 @@ Conducts bounded local repository investigations, audits, and invariant checks u 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`. +- **POSIX shells (Bash 3.2+)**: Use `scripts/make-research-workspace.sh`, `scripts/run-agy-json.sh`, and `scripts/cleanup-research-workspace.sh`. Requires Git, `jq`, Python 3, and the configured adapter's executable. +- **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 the configured adapter. 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 the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects the current model. Do not pass `--model` or `--effort` directly. diff --git a/modes/web-research.md b/modes/web-research.md index 2e2b205..ea61e04 100644 --- a/modes/web-research.md +++ b/modes/web-research.md @@ -1,15 +1,15 @@ # Web research mode -Conducts cited online investigations and multi-angle technical research by dispatching parallel headless `agy` workers, synthesizing findings into a structured claim ledger, and validating every final citation with an independent auditor. +Conducts cited online investigations and multi-angle technical research by dispatching parallel headless workers through the configured adapter, synthesizing findings into a structured claim ledger, and validating every final citation with an independent auditor. ## Preconditions and sources 1. **Public-source default.** Research workers query public online sources by default. 2. **Explicit authorization for private sources.** Accessing private, internal, or authenticated sources requires explicit authorization from the user for that specific run. Never forward cookies, session tokens, browser profiles, or environment credentials implicitly. 3. **Helper family and environment requirements.** Select the helper family matching your host shell: - - **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `agy`, `jq`, and Python 3. - - **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. + - **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `jq`, Python 3, and the configured adapter's executable. + - **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +4. **Configured adapter availability.** Workers are launched using the matching `run-agy-json` helper, which handles adapter selection 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 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. diff --git a/scripts/agy-adapter.ps1 b/scripts/agy-adapter.ps1 index 5a8e1bb..cd025c6 100644 --- a/scripts/agy-adapter.ps1 +++ b/scripts/agy-adapter.ps1 @@ -56,6 +56,15 @@ function Get-PreferenceScore([string]$family, [string]$preference) { return 100 } +function Get-Preflight($model) { + if ($null -ne $model -and $model.PSObject.Properties['preflight']) { return $model.preflight } + return [ordered]@{ + access = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify authenticated access'; account_ref = '' } + entitlement = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify model entitlement'; billing_route = 'unknown' } + usage = [ordered]@{ state = 'unknown'; reason = 'adapter did not query usage'; source = 'not-queried'; observed_at = ''; scopes = @() } + } +} + function Convert-ModelListToCatalog([string]$raw) { $models = @( foreach ($line in ($raw -split "`r?`n")) { @@ -76,6 +85,7 @@ function Convert-ModelListToCatalog([string]$raw) { balanced = Get-PreferenceScore $family 'balanced' deep = Get-PreferenceScore $family 'deep' } + preflight = Get-Preflight $null } } ) @@ -84,9 +94,9 @@ function Convert-ModelListToCatalog([string]$raw) { try { $revision = [Convert]::ToHexString($hash.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($raw))).ToLowerInvariant() } finally { $hash.Dispose() } [ordered]@{ - protocol_version = 1 + protocol_version = 2 adapter = 'agy' - adapter_revision = 'agy-1' + adapter_revision = 'agy-2' vendor = 'agy' catalog_revision = $revision models = $models diff --git a/scripts/agy-adapter.sh b/scripts/agy-adapter.sh index 8c95254..764dd11 100755 --- a/scripts/agy-adapter.sh +++ b/scripts/agy-adapter.sh @@ -77,9 +77,9 @@ if [ "$operation" = catalog ]; then elif $preference == "balanced" then ({sonnet:1,flash:2,oss:3,pro:3,haiku:4,opus:5,unknown:100}[$family] // 100) else ({opus:1,pro:2,sonnet:3,oss:4,flash:5,haiku:6,unknown:100}[$family] // 100) end; { - protocol_version: 1, + protocol_version: 2, adapter: "agy", - adapter_revision: "agy-1", + adapter_revision: "agy-2", vendor: "agy", catalog_revision: $revision, models: [ @@ -99,7 +99,8 @@ if [ "$operation" = catalog ]; then fast: score($family; "fast"), balanced: score($family; "balanced"), deep: score($family; "deep") - } + }, + preflight: {access:{state:"unknown",reason:"adapter did not verify authenticated access",account_ref:""},entitlement:{state:"unknown",reason:"adapter did not verify model entitlement",billing_route:"unknown"},usage:{state:"unknown",reason:"adapter did not query usage",source:"not-queried",observed_at:"",scopes:[]}} } ] } diff --git a/scripts/capacity-ledger.ps1 b/scripts/capacity-ledger.ps1 new file mode 100644 index 0000000..d3dc338 --- /dev/null +++ b/scripts/capacity-ledger.ps1 @@ -0,0 +1,107 @@ +#!/usr/bin/env pwsh +# Shared worker capacity reservations. The ledger stores no credentials. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Fail([string]$Message, [int]$Code = 2) { + [Console]::Error.WriteLine("ERROR: $Message") + exit $Code +} + +function Usage { + [Console]::Error.WriteLine('Usage: capacity-ledger.ps1 init|reserve|release|reconcile --ledger PATH [--selection PATH] [--reservation-id ID] [--state completed|cancelled|failed|recovered] [--reason TEXT]') +} + +function Now { [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ') } +function Full([string]$Path) { [IO.Path]::GetFullPath($Path) } + +function AtomicWrite([string]$Path, $Value) { + $parent = Split-Path -Parent $Path + if ($parent -and -not (Test-Path -LiteralPath $parent -PathType Container)) { [IO.Directory]::CreateDirectory($parent) | Out-Null } + $tmp = "$Path.tmp.$([Guid]::NewGuid().ToString('N'))" + [IO.File]::WriteAllText($tmp, (($Value | ConvertTo-Json -Depth 30) + "`n"), [Text.UTF8Encoding]::new($false)) + Move-Item -LiteralPath $tmp -Destination $Path -Force +} + +function ReadLedger([string]$Path) { + if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return [ordered]@{ schema_version = 1; ledger = 'worker-capacity'; created_at = (Now); updated_at = (Now); reservations = @() } } + try { $value = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -Depth 30 } catch { Fail "invalid capacity ledger JSON: $Path" } + if ($value.schema_version -ne 1 -or $value.ledger -ne 'worker-capacity') { Fail "unsupported capacity ledger: $Path" } + if ($null -eq $value.reservations) { $value | Add-Member -NotePropertyName reservations -NotePropertyValue @() } + return $value +} + +function WithLock([string]$Path, [scriptblock]$Action) { + $parent = Split-Path -Parent $Path + if ($parent -and -not (Test-Path -LiteralPath $parent -PathType Container)) { [IO.Directory]::CreateDirectory($parent) | Out-Null } + $lockPath = "$Path.lock" + $stream = $null + for ($attempt = 0; $attempt -lt 100; $attempt++) { + try { $stream = [IO.File]::Open($lockPath, [IO.FileMode]::OpenOrCreate, [IO.FileAccess]::ReadWrite, [IO.FileShare]::None); break } catch { Start-Sleep -Milliseconds 50 } + } + if ($null -eq $stream) { Fail "could not lock capacity ledger: $Path" 4 } + try { & $Action } finally { $stream.Dispose() } +} + +function ParseArgs([string[]]$InputArgs) { + if ($InputArgs.Count -lt 1) { Usage; exit 2 } + $result = @{ command = [string]$InputArgs[0] } + $i = 1 + while ($i -lt $InputArgs.Count) { + $arg = [string]$InputArgs[$i] + if (-not $arg.StartsWith('--') -or $i + 1 -ge $InputArgs.Count) { Fail "invalid argument: $arg" } + $result[$arg.Substring(2)] = [string]$InputArgs[$i + 1] + $i += 2 + } + return $result +} + +$options = ParseArgs $args +$command = [string]$options.command +if ($command -notin @('init', 'reserve', 'release', 'reconcile')) { Usage; exit 2 } +if (-not $options.ContainsKey('ledger')) { Fail '--ledger is required' } +$ledgerPath = Full ([string]$options.ledger) + +WithLock $ledgerPath { + $ledger = ReadLedger $ledgerPath + if ($command -eq 'init') { + AtomicWrite $ledgerPath $ledger + [Console]::Out.WriteLine(($ledger | ConvertTo-Json -Depth 30 -Compress)) + return + } + + if ($command -eq 'reserve') { + if (-not $options.ContainsKey('selection')) { Fail '--selection is required for reserve' } + $selectionPath = Full ([string]$options.selection) + try { $selection = Get-Content -LiteralPath $selectionPath -Raw | ConvertFrom-Json -Depth 30 } catch { Fail "invalid selection JSON: $selectionPath" } + if ($selection.protocol_version -ne 2 -or [string]::IsNullOrWhiteSpace([string]$selection.model_id)) { Fail 'selection must use protocol 2 and include model_id' 4 } + $units = [int]$selection.capacity_estimate.required_units + if ($units -le 0) { Fail 'selection capacity estimate must be positive' 4 } + $reservationId = if ($options.ContainsKey('reservation-id')) { [string]$options.'reservation-id' } else { "reservation-$([Guid]::NewGuid().ToString('N'))" } + if (@($ledger.reservations | Where-Object { $_.reservation_id -eq $reservationId }).Count -gt 0) { Fail "reservation already exists: $reservationId" 4 } + $scopeIds = @($selection.reservation.scopes | ForEach-Object { [string]$_ } | Where-Object { $_ }) + $active = @($ledger.reservations | Where-Object { $_.state -eq 'active' -and $_.provider -eq $selection.provider -and $_.model_id -eq $selection.model_id }) + foreach ($scopeId in $scopeIds) { + $scope = @($selection.preflight.usage.scopes | Where-Object { [string]$_.scope_id -eq $scopeId }) | Select-Object -First 1 + if ($null -eq $scope) { Fail "selection is missing capacity scope: $scopeId" 4 } + $alreadyReserved = 0 + foreach ($record in $active) { if (@($record.scopes | Where-Object { [string]$_ -eq $scopeId }).Count -gt 0) { $alreadyReserved += [int]$record.required_units } } + $available = [double]$scope.remaining_units - [double]$scope.reserved_units - $alreadyReserved + if ($available -lt $units) { Fail "capacity reservation rejected for scope $scopeId" 4 } + } + $record = [ordered]@{ reservation_id = $reservationId; state = 'active'; provider = [string]$selection.provider; model_id = [string]$selection.model_id; required_units = $units; scopes = $scopeIds; created_at = (Now); updated_at = (Now); released_at = $null; release_reason = $null; evidence = [ordered]@{ adapter = [string]$selection.adapter; adapter_revision = [string]$selection.adapter_revision; catalog_revision = [string]$selection.catalog_revision; policy_revision = [string]$selection.policy_revision; usage_observed_at = [string]$selection.usage_observed_at; usage_uncertain = [bool]$selection.usage_uncertain } } + $ledger.reservations = @($ledger.reservations) + @([PSCustomObject]$record); $ledger.updated_at = Now; AtomicWrite $ledgerPath $ledger + [Console]::Out.WriteLine(($record | ConvertTo-Json -Depth 30 -Compress)); return + } + + if (-not $options.ContainsKey('reservation-id')) { Fail '--reservation-id is required' } + $reservationId = [string]$options.'reservation-id' + $record = @($ledger.reservations | Where-Object { $_.reservation_id -eq $reservationId }) | Select-Object -First 1 + if ($null -eq $record) { Fail "reservation not found: $reservationId" 4 } + if ($command -eq 'release') { $state = 'released' } else { $state = if ($options.ContainsKey('state')) { [string]$options.state } else { 'recovered' } } + if ($state -notin @('released', 'completed', 'cancelled', 'failed', 'recovered')) { Fail "invalid terminal state: $state" } + $record.state = $state; $record.updated_at = Now; $record.released_at = Now; $record.release_reason = if ($options.ContainsKey('reason')) { [string]$options.reason } else { $state } + $ledger.updated_at = Now; AtomicWrite $ledgerPath $ledger + [Console]::Out.WriteLine(($record | ConvertTo-Json -Depth 30 -Compress)) +} diff --git a/scripts/capacity-ledger.sh b/scripts/capacity-ledger.sh new file mode 100644 index 0000000..622769f --- /dev/null +++ b/scripts/capacity-ledger.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +# Shared worker capacity reservations. The ledger stores no credentials. +set -euo pipefail + +fail() { printf 'ERROR: %s\n' "$1" >&2; exit "${2:-2}"; } +usage() { printf 'Usage: capacity-ledger.sh init|reserve|release|reconcile --ledger PATH [--selection PATH] [--reservation-id ID] [--state completed|cancelled|failed|recovered] [--reason TEXT]\n' >&2; } +now() { date -u +%Y-%m-%dT%H:%M:%SZ; } +resolve_path() { case "$1" in /*) printf '%s' "$1" ;; *) printf '%s/%s' "$(pwd -P)" "$1" ;; esac; } + +[ "$#" -ge 1 ] || { usage; exit 2; } +command_name="$1"; shift +ledger_path=''; selection_path=''; reservation_id=''; state=''; reason='' +while [ "$#" -gt 0 ]; do + [ "$#" -ge 2 ] || fail "missing value for $1" + case "$1" in + --ledger) ledger_path="$2" ;; + --selection) selection_path="$2" ;; + --reservation-id) reservation_id="$2" ;; + --state) state="$2" ;; + --reason) reason="$2" ;; + *) usage; fail "unknown option: $1" ;; + esac + shift 2 +done +case "$command_name" in init|reserve|release|reconcile) ;; *) usage; exit 2 ;; esac +[ -n "$ledger_path" ] || fail '--ledger is required' +ledger_path="$(resolve_path "$ledger_path")" +mkdir -p "$(dirname "$ledger_path")" +lock_dir="$ledger_path.lockdir" +lock_acquired=false +for _attempt in $(seq 1 100); do + if mkdir "$lock_dir" 2>/dev/null; then lock_acquired=true; break; fi + sleep 0.05 +done +$lock_acquired || fail "could not lock capacity ledger: $ledger_path" 4 +cleanup_lock() { rmdir "$lock_dir" 2>/dev/null || true; } +trap cleanup_lock EXIT + +if [ ! -f "$ledger_path" ]; then + printf '{"schema_version":1,"ledger":"worker-capacity","created_at":"%s","updated_at":"%s","reservations":[]}\n' "$(now)" "$(now)" >"$ledger_path" +fi +jq -e '(.schema_version == 1 and .ledger == "worker-capacity")' "$ledger_path" >/dev/null 2>&1 || fail "unsupported capacity ledger: $ledger_path" + +if [ "$command_name" = init ]; then jq . "$ledger_path"; exit 0; fi + +if [ "$command_name" = reserve ]; then + [ -n "$selection_path" ] || fail '--selection is required for reserve' + jq -e '(.protocol_version == 2 and (.model_id|type == "string") and (.model_id|length > 0) and (.capacity_estimate.required_units|type == "number") and (.capacity_estimate.required_units > 0))' "$selection_path" >/dev/null 2>&1 || fail 'selection must use protocol 2 and include a positive capacity estimate' 4 + [ -n "$reservation_id" ] || reservation_id="reservation-$(date -u +%Y%m%d%H%M%S)-$$" + jq -e --arg id "$reservation_id" 'any(.reservations[]?; .reservation_id == $id) | not' "$ledger_path" >/dev/null 2>&1 || fail "reservation already exists: $reservation_id" 4 + scopes_json=$(jq -c '[.reservation.scopes[]? | strings] | unique' "$selection_path") + provider=$(jq -r '.provider // ""' "$selection_path"); model_id=$(jq -r '.model_id' "$selection_path"); units=$(jq -r '.capacity_estimate.required_units' "$selection_path") + scope_count=$(jq 'length' <<<"$scopes_json") + i=0 + while [ "$i" -lt "$scope_count" ]; do + scope_id=$(jq -r --argjson i "$i" '.[$i]' <<<"$scopes_json") + base_available=$(jq -r --arg scope "$scope_id" '([.preflight.usage.scopes[]? | select((.scope_id|tostring) == $scope) | ((.remaining_units // 0) - (.reserved_units // 0))] | first // -1)' "$selection_path") + [ "$base_available" != -1 ] || fail "selection is missing capacity scope: $scope_id" 4 + already_reserved=$(jq -r --arg scope "$scope_id" --arg provider "$provider" --arg model "$model_id" '[.reservations[]? | select(.state == "active" and .provider == $provider and .model_id == $model and (.scopes // [] | index($scope) != null)) | .required_units] | add // 0' "$ledger_path") + jq -n --argjson base "$base_available" --argjson used "$already_reserved" --argjson units "$units" '($base - $used) >= $units' | grep -qx true || fail "capacity reservation rejected for scope $scope_id" 4 + i=$((i + 1)) + done + tmp="$ledger_path.tmp.$$" + jq --arg id "$reservation_id" --arg provider "$provider" --arg model "$model_id" --argjson units "$units" --argjson scopes "$scopes_json" --arg adapter "$(jq -r '.adapter // ""' "$selection_path")" --arg adapter_revision "$(jq -r '.adapter_revision // ""' "$selection_path")" --arg catalog_revision "$(jq -r '.catalog_revision // ""' "$selection_path")" --arg policy_revision "$(jq -r '.policy_revision // ""' "$selection_path")" --arg usage_observed_at "$(jq -r '.usage_observed_at // ""' "$selection_path")" --argjson usage_uncertain "$(jq -c '.usage_uncertain // false' "$selection_path")" --arg now "$(now)" '.reservations += [{reservation_id:$id,state:"active",provider:$provider,model_id:$model,required_units:$units,scopes:$scopes,created_at:$now,updated_at:$now,released_at:null,release_reason:null,evidence:{adapter:$adapter,adapter_revision:$adapter_revision,catalog_revision:$catalog_revision,policy_revision:$policy_revision,usage_observed_at:$usage_observed_at,usage_uncertain:$usage_uncertain}}] | .updated_at=$now' "$ledger_path" >"$tmp" + mv -f "$tmp" "$ledger_path" + jq -c --arg id "$reservation_id" '.reservations[] | select(.reservation_id == $id)' "$ledger_path" + exit 0 +fi + +[ -n "$reservation_id" ] || fail '--reservation-id is required' +jq -e --arg id "$reservation_id" 'any(.reservations[]?; .reservation_id == $id)' "$ledger_path" >/dev/null 2>&1 || fail "reservation not found: $reservation_id" 4 +[ "$command_name" = release ] && state='released' +[ -n "$state" ] || state='recovered' +case "$state" in released|completed|cancelled|failed|recovered) ;; *) fail "invalid terminal state: $state" ;; esac +tmp="$ledger_path.tmp.$$" +jq --arg id "$reservation_id" --arg state "$state" --arg reason "${reason:-$state}" --arg now "$(now)" '(.reservations[] | select(.reservation_id == $id)) |= (.state=$state | .updated_at=$now | .released_at=$now | .release_reason=$reason) | .updated_at=$now' "$ledger_path" >"$tmp" +mv -f "$tmp" "$ledger_path" +jq -c --arg id "$reservation_id" '.reservations[] | select(.reservation_id == $id)' "$ledger_path" diff --git a/scripts/run-agy-json.ps1 b/scripts/run-agy-json.ps1 index f82cd4e..2962377 100644 --- a/scripts/run-agy-json.ps1 +++ b/scripts/run-agy-json.ps1 @@ -160,28 +160,29 @@ function Invoke-ResourceLedger([string]$verb,[string[]]$arguments) { foreach($argument in (@('-NoProfile','-NonInteractive','-File',$ledgerScript,$verb)+$arguments)){[void]$psi.ArgumentList.Add([string]$argument)} $process=$null;try{$process=[System.Diagnostics.Process]::Start($psi);if($null -eq $process){throw 'resource ledger process did not start'};$stdout=$process.StandardOutput.ReadToEnd();$stderr=$process.StandardError.ReadToEnd();$process.WaitForExit();if($process.ExitCode -ne 0){$message=$stderr.Trim();if([string]::IsNullOrWhiteSpace($message)){$message=$stdout.Trim()};throw "resource ledger $verb failed$(if($message){": $message"})"};return $stdout}finally{if($process){$process.Dispose()}} } +function Invoke-CapacityLedger([string]$verb,[string[]]$arguments) { + $ledgerScript=[System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot 'capacity-ledger.ps1'));$psi=[System.Diagnostics.ProcessStartInfo]::new();$psi.FileName=(Get-Command pwsh -ErrorAction Stop).Source;$psi.UseShellExecute=$false;$psi.CreateNoWindow=$true;$psi.WorkingDirectory=(Get-Location).ProviderPath;$psi.RedirectStandardOutput=$true;$psi.RedirectStandardError=$true + foreach($argument in (@('-NoProfile','-NonInteractive','-File',$ledgerScript,$verb)+$arguments)){[void]$psi.ArgumentList.Add([string]$argument)} + $process=$null;try{$process=[System.Diagnostics.Process]::Start($psi);if($null -eq $process){throw 'capacity ledger process did not start'};$stdout=$process.StandardOutput.ReadToEnd();$stderr=$process.StandardError.ReadToEnd();$process.WaitForExit();if($process.ExitCode -ne 0){$message=$stderr.Trim();if([string]::IsNullOrWhiteSpace($message)){$message=$stdout.Trim()};throw "capacity ledger $verb failed$(if($message){": $message"})"};return $stdout}finally{if($process){$process.Dispose()}} +} -$outputPath='';$errorPath='';$selectionOutputPath='';$pinPath='';$adapterPath='';$role='';$route='default';$lifecyclePath='';$attempt=1;$mode='unknown';$verificationBaseline='';$resourceLedgerPath='';$timeoutSeconds=0;$cancelFile='';$ledgerPath='';$assignmentId='';$parentId='';$resourceId='' +$outputPath='';$errorPath='';$selectionOutputPath='';$pinPath='';$adapterPath='';$provider='';$allowUnknownUsage=$false;$role='';$route='default';$lifecyclePath='';$attempt=1;$mode='unknown';$verificationBaseline='';$resourceLedgerPath='';$capacityLedgerPath='';$reservationId='';$capacityReserved=$false;$capacityFinalized=$false;$timeoutSeconds=0;$cancelFile='';$ledgerPath='';$assignmentId='';$parentId='';$resourceId='' $options=@{};$forwardedArgs=[System.Collections.Generic.List[string]]::new();$requiredCapabilities=[System.Collections.Generic.List[string]]::new();$delimiter=$false -$valueOptions=@('--output','--error','--selection-output','--pin','--adapter','--role','--route','--lifecycle','--attempt','--mode','--verification-baseline','--resource-ledger','--timeout-seconds','--cancel-file','--ledger','--assignment-id','--parent-id','--resource-id') +$valueOptions=@('--output','--error','--selection-output','--pin','--adapter','--provider','--role','--route','--lifecycle','--attempt','--mode','--verification-baseline','--resource-ledger','--capacity-ledger','--reservation-id','--timeout-seconds','--cancel-file','--ledger','--assignment-id','--parent-id','--resource-id') $i=0 -while($i -lt $args.Count){$arg=[string]$args[$i];if($arg -eq '--'){$delimiter=$true;$i++;while($i -lt $args.Count){$forwardedArgs.Add([string]$args[$i]);$i++};break};$name='';$value=$null;if($arg -match '^(--[^=]+)=(.*)$'){$name=$Matches[1];$value=$Matches[2]}elseif($valueOptions -contains $arg -or $arg -eq '--require-capability'){$name=$arg;$i++;if($i -ge $args.Count){Usage;Fail "$name requires a value"};$value=[string]$args[$i]}else{Usage;Fail "unknown launcher option: $arg"};if($name -eq '--require-capability'){if([string]::IsNullOrWhiteSpace($value)){Fail '--require-capability requires a non-empty value'};$requiredCapabilities.Add($value)}else{if($options.ContainsKey($name)){Fail "duplicate $name option"};$options[$name]=$value};$i++} +while($i -lt $args.Count){$arg=[string]$args[$i];if($arg -eq '--'){$delimiter=$true;$i++;while($i -lt $args.Count){$forwardedArgs.Add([string]$args[$i]);$i++};break};$name='';$value=$null;if($arg -match '^(--[^=]+)=(.*)$'){$name=$Matches[1];$value=$Matches[2]}elseif($arg -eq '--allow-unknown-usage'){$name=$arg;$value='true'}elseif($valueOptions -contains $arg -or $arg -eq '--require-capability'){$name=$arg;$i++;if($i -ge $args.Count){Usage;Fail "$name requires a value"};$value=[string]$args[$i]}else{Usage;Fail "unknown launcher option: $arg"};if($name -eq '--require-capability'){if([string]::IsNullOrWhiteSpace($value)){Fail '--require-capability requires a non-empty value'};$requiredCapabilities.Add($value)}else{if($options.ContainsKey($name)){Fail "duplicate $name option"};$options[$name]=$value};$i++} if(-not $delimiter){Usage;Fail '-- delimiter is required'};if($forwardedArgs.Count -eq 0){Usage;Fail 'worker arguments are required after --'};foreach($name in @('--output','--error','--role')){if(-not ($options.ContainsKey($name)) -or [string]::IsNullOrWhiteSpace([string]$options[$name])){Usage;Fail "$name is required"}} -$outputPath=[string]$options['--output'];$errorPath=[string]$options['--error'];$role=[string]$options['--role'];if($options.ContainsKey('--selection-output')){$selectionOutputPath=[string]$options['--selection-output']};if($options.ContainsKey('--pin')){$pinPath=[string]$options['--pin']};if($options.ContainsKey('--adapter')){$adapterPath=[string]$options['--adapter']};if($options.ContainsKey('--route')){$route=[string]$options['--route']};if($options.ContainsKey('--lifecycle')){$lifecyclePath=[string]$options['--lifecycle']};if($options.ContainsKey('--attempt')){if(-not [int]::TryParse([string]$options['--attempt'],[ref]$attempt)){Fail '--attempt requires an integer'}};if($options.ContainsKey('--mode')){$mode=[string]$options['--mode']};if($options.ContainsKey('--verification-baseline')){$verificationBaseline=[string]$options['--verification-baseline']};if($options.ContainsKey('--resource-ledger')){$resourceLedgerPath=[string]$options['--resource-ledger']};if($options.ContainsKey('--timeout-seconds')){if(-not [int]::TryParse([string]$options['--timeout-seconds'],[ref]$timeoutSeconds)){Fail '--timeout-seconds requires an integer'}};if($options.ContainsKey('--cancel-file')){$cancelFile=[string]$options['--cancel-file']};if($options.ContainsKey('--ledger')){$ledgerPath=[string]$options['--ledger']};if($options.ContainsKey('--assignment-id')){$assignmentId=[string]$options['--assignment-id']};if($options.ContainsKey('--parent-id')){$parentId=[string]$options['--parent-id']};if($options.ContainsKey('--resource-id')){$resourceId=[string]$options['--resource-id']} + $outputPath=[string]$options['--output'];$errorPath=[string]$options['--error'];$role=[string]$options['--role'];if($options.ContainsKey('--selection-output')){$selectionOutputPath=[string]$options['--selection-output']};if($options.ContainsKey('--pin')){$pinPath=[string]$options['--pin']};if($options.ContainsKey('--adapter')){$adapterPath=[string]$options['--adapter']};if($options.ContainsKey('--provider')){$provider=[string]$options['--provider']};if($options.ContainsKey('--allow-unknown-usage')){$allowUnknownUsage=$true};if($options.ContainsKey('--route')){$route=[string]$options['--route']};if($options.ContainsKey('--lifecycle')){$lifecyclePath=[string]$options['--lifecycle']};if($options.ContainsKey('--attempt')){if(-not [int]::TryParse([string]$options['--attempt'],[ref]$attempt)){Fail '--attempt requires an integer'}};if($options.ContainsKey('--mode')){$mode=[string]$options['--mode']};if($options.ContainsKey('--verification-baseline')){$verificationBaseline=[string]$options['--verification-baseline']};if($options.ContainsKey('--resource-ledger')){$resourceLedgerPath=[string]$options['--resource-ledger']};if($options.ContainsKey('--capacity-ledger')){$capacityLedgerPath=[string]$options['--capacity-ledger']};if($options.ContainsKey('--reservation-id')){$reservationId=[string]$options['--reservation-id']};if($options.ContainsKey('--timeout-seconds')){if(-not [int]::TryParse([string]$options['--timeout-seconds'],[ref]$timeoutSeconds)){Fail '--timeout-seconds requires an integer'}};if($options.ContainsKey('--cancel-file')){$cancelFile=[string]$options['--cancel-file']};if($options.ContainsKey('--ledger')){$ledgerPath=[string]$options['--ledger']};if($options.ContainsKey('--assignment-id')){$assignmentId=[string]$options['--assignment-id']};if($options.ContainsKey('--parent-id')){$parentId=[string]$options['--parent-id']};if($options.ContainsKey('--resource-id')){$resourceId=[string]$options['--resource-id']} if($route -notin @('default','quality-retry')){Fail "unknown route: '$route'; must be default or quality-retry"};if($role -notin @('scout','gate-author','implementer','reviewer','researcher','synthesizer','auditor')){Fail "unknown role: '$role'"};if($env:OFFLOAD_WORKER_CONTEXT -eq '1'){Fail 'worker process cannot invoke the launcher; only the orchestrator may create worker processes' 126};foreach($forwarded in $forwardedArgs){if($forwarded -eq '--output' -or $forwarded.StartsWith('--output=') -or $forwarded -eq '--model' -or $forwarded.StartsWith('--model=') -or $forwarded -eq '--effort' -or $forwarded.StartsWith('--effort=')){Fail 'caller cannot pass --output, --model, or --effort to the worker'}};if($timeoutSeconds -lt 0){Fail '--timeout-seconds must be zero or a positive integer'} -$currentLocation=Get-Location;if($currentLocation.Provider.Name -ne 'FileSystem'){Fail 'current location must use the FileSystem provider'};$callerDirectory=[System.IO.Path]::GetFullPath($currentLocation.ProviderPath);$outputPath=Ensure-Path $outputPath 'output path' $callerDirectory;$errorPath=Ensure-Path $errorPath 'error path' $callerDirectory;if($outputPath -eq $errorPath){Fail 'output and error paths must be different'};if($selectionOutputPath){$selectionOutputPath=Ensure-Path $selectionOutputPath 'selection output path' $callerDirectory};if($ledgerPath){$ledgerPath=Ensure-Path $ledgerPath 'ledger path' $callerDirectory;if($resourceLedgerPath){$resourceLedgerPath=Ensure-Path $resourceLedgerPath 'resource ledger path' $callerDirectory;if($ledgerPath -ne $resourceLedgerPath){Fail '--ledger and --resource-ledger must name the same path'}}else{$resourceLedgerPath=$ledgerPath}}elseif($resourceLedgerPath){$resourceLedgerPath=Ensure-Path $resourceLedgerPath 'resource ledger path' $callerDirectory} -$scriptDir=[System.IO.Path]::GetFullPath($PSScriptRoot);$repoRoot=[System.IO.Path]::GetFullPath((Join-Path $scriptDir '..'));$policyFile=Join-Path $repoRoot 'model-policy.json';$policy=Read-Json $policyFile 'model policy file';if((Property $policy 'schema_version') -ne 2 -or (Property $policy 'max_effort') -ne 'high' -or (Property $policy 'max_retries_per_worker') -ne 1 -or (Property $policy 'quota_action') -ne 'handoff'){Fail 'model policy has unsupported schema or safety settings'} + $currentLocation=Get-Location;if($currentLocation.Provider.Name -ne 'FileSystem'){Fail 'current location must use the FileSystem provider'};$callerDirectory=[System.IO.Path]::GetFullPath($currentLocation.ProviderPath);$outputPath=Ensure-Path $outputPath 'output path' $callerDirectory;$errorPath=Ensure-Path $errorPath 'error path' $callerDirectory;if($outputPath -eq $errorPath){Fail 'output and error paths must be different'};if($selectionOutputPath){$selectionOutputPath=Ensure-Path $selectionOutputPath 'selection output path' $callerDirectory};if($capacityLedgerPath){$capacityLedgerPath=Ensure-Path $capacityLedgerPath 'capacity ledger path' $callerDirectory};if($ledgerPath){$ledgerPath=Ensure-Path $ledgerPath 'ledger path' $callerDirectory;if($resourceLedgerPath){$resourceLedgerPath=Ensure-Path $resourceLedgerPath 'resource ledger path' $callerDirectory;if($ledgerPath -ne $resourceLedgerPath){Fail '--ledger and --resource-ledger must name the same path'}}else{$resourceLedgerPath=$ledgerPath}}elseif($resourceLedgerPath){$resourceLedgerPath=Ensure-Path $resourceLedgerPath 'resource ledger path' $callerDirectory} + $scriptDir=[System.IO.Path]::GetFullPath($PSScriptRoot);$repoRoot=[System.IO.Path]::GetFullPath((Join-Path $scriptDir '..'));$policyFile=Join-Path $repoRoot 'model-policy.json';$policy=Read-Json $policyFile 'model policy file';$capacityPolicy=Property $policy 'capacity_estimation';if((Property $policy 'schema_version') -ne 2 -or (Property $policy 'max_effort') -ne 'high' -or (Property $policy 'max_retries_per_worker') -ne 1 -or (Property $policy 'quota_action') -ne 'handoff' -or $null -eq $capacityPolicy -or @('assignment_units','verification_units','retry_units','usage_freshness_seconds'|Where-Object{[double](Property $capacityPolicy $_) -le 0}).Count -gt 0){Fail 'model policy has unsupported schema or safety settings'} $roles=Property $policy 'roles';$rolePolicy=Property $roles $role;if($null -eq $rolePolicy -or (Property $rolePolicy 'preference') -notin @('fast','balanced','deep') -or (Property $rolePolicy 'effort') -notin @('low','medium','high')){Fail "role '$role' has invalid policy"};$preference=[string](Property $rolePolicy 'preference');$effort=[string](Property $rolePolicy 'effort');$policyCapabilities=@((Property $rolePolicy 'required_capabilities'))|Where-Object{ -not [string]::IsNullOrWhiteSpace([string]$_)};$allCapabilities=@($policyCapabilities+$requiredCapabilities.ToArray())|Sort-Object -Unique;if($route -eq 'quality-retry' -and [string]::IsNullOrWhiteSpace($pinPath)){Fail 'quality-retry requires --pin with the prior selection; use an explicit fallback or handoff when it is unavailable' 3} $adapterDefault=Join-Path $scriptDir 'agy-adapter.ps1';if([string]::IsNullOrWhiteSpace($adapterPath)){$adapterPath=[Environment]::GetEnvironmentVariable('OFFLOAD_ADAPTER_BIN')};if([string]::IsNullOrWhiteSpace($adapterPath)){$adapterPath=$adapterDefault};$adapter=Resolve-Program $adapterPath;$tempRequest=[System.IO.Path]::GetTempFileName();$tempCatalog=[System.IO.Path]::GetTempFileName();$tempAdapterError=[System.IO.Path]::GetTempFileName();$tempLaunchSelection=[System.IO.Path]::GetTempFileName() try { - $request=[ordered]@{protocol_version=1;operation='catalog';role=$role;preference=$preference;effort=$effort;required_capabilities=@($allCapabilities);policy_revision=[string](Property $policy 'policy_revision')};[System.IO.File]::WriteAllText($tempRequest,($request|ConvertTo-Json -Depth 20),[System.Text.Encoding]::UTF8);$catalogCode=Invoke-Program $adapter @('--operation','catalog','--request',$tempRequest) $callerDirectory $tempCatalog $tempAdapterError;if($catalogCode -ne 0){$diagnostic=[System.IO.File]::ReadAllText($tempAdapterError).Trim();Fail "adapter catalog discovery failed with exit code $catalogCode$(if($diagnostic){": $diagnostic"})" 127} - $catalog=Read-Json $tempCatalog 'adapter catalog';if((Property $catalog 'protocol_version') -ne 1){Fail 'adapter catalog has unsupported protocol_version' 127};$catalogAdapter=[string](Property $catalog 'adapter');$catalogVendor=[string](Property $catalog 'vendor');$catalogRevision=[string](Property $catalog 'catalog_revision');$adapterRevision=[string](Property $catalog 'adapter_revision');if(@($catalogAdapter,$catalogVendor,$catalogRevision,$adapterRevision|Where-Object{[string]::IsNullOrWhiteSpace([string]$_)}).Count -gt 0){Fail 'adapter catalog is missing required metadata' 127} - $eligible=[System.Collections.Generic.List[object]]::new();foreach($model in @((Property $catalog 'models'))){$id=[string](Property $model 'id');$supported=@((Property $model 'supported_efforts'))|ForEach-Object{[string]$_};$caps=@((Property $model 'capabilities'))|ForEach-Object{[string]$_};$scores=Property $model 'scores';$scoreValue=Property $scores $preference;if([string]::IsNullOrWhiteSpace($id) -or (Property $model 'available') -ne $true -or ((Property $model 'quota_available') -ne $null -and (Property $model 'quota_available') -ne $true) -or $supported -notcontains $effort){continue};if(@($allCapabilities|Where-Object{$caps -notcontains $_}).Count -gt 0){continue};if($null -eq $scoreValue){$scoreValue=1000000};try{$score=[double]$scoreValue}catch{continue};$vendor=[string](Property $model 'vendor');if([string]::IsNullOrWhiteSpace($vendor)){$vendor=$catalogVendor};$eligible.Add([pscustomobject]@{Model=$model;Id=$id;Vendor=$vendor;Score=$score})} - if($eligible.Count -eq 0){Fail "adapter catalog has no eligible model for role '$role', effort '$effort', and required capabilities" 4};$selected=$null;$selectionReason="catalog selection preference=$preference effort=$effort; filtered unavailable, quota, effort, capability, and static-policy-incompatible candidates";if($pinPath){if(-not(Test-Path -LiteralPath $pinPath -PathType Leaf)){Fail "pinned selection file not found: $pinPath" 3};$pin=Read-Json $pinPath 'pinned selection';$pinId=[string](Property $pin 'model_id');if(-not $pinId){$pinId=[string](Property $pin 'model')};if([string](Property $pin 'adapter') -ne $catalogAdapter -or [string](Property $pin 'vendor') -ne $catalogVendor -or [string](Property $pin 'effort') -ne $effort -or -not $pinId){Fail 'pinned selection does not match the current adapter, vendor, or policy effort; explicit fallback or handoff is required' 3};$selected=$eligible|Where-Object{$_.Id -eq $pinId -and $_.Vendor -eq $catalogVendor}|Select-Object -First 1;if($null -eq $selected){Fail "pinned model '$pinId' is unavailable in catalog revision '$catalogRevision'; explicit fallback or handoff is required" 3};$selectionReason="pinned selection adapter=$catalogAdapter vendor=$catalogVendor model_id=$pinId; catalog_revision=$catalogRevision"}else{$selected=$eligible|Sort-Object Score,Vendor,Id|Select-Object -First 1} - $selection=[ordered]@{protocol_version=1;adapter=$catalogAdapter;adapter_revision=$adapterRevision;vendor=$selected.Vendor;model_id=$selected.Id;model=$selected.Id;family_hint=[string](Property $selected.Model 'family_hint');preference=$preference;effort=$effort;catalog_revision=$catalogRevision;policy_revision=[string](Property $policy 'policy_revision');required_capabilities=@($allCapabilities);selection_reason=$selectionReason;route=$route};$selectionJson=$selection|ConvertTo-Json -Depth 20;if($selectionOutputPath){[System.IO.File]::WriteAllText($selectionOutputPath,$selectionJson,[System.Text.Encoding]::UTF8)} - $lifecycle=$options.ContainsKey('--lifecycle') -or $options.ContainsKey('--attempt') -or $options.ContainsKey('--resource-ledger') -or $options.ContainsKey('--ledger') -or $options.ContainsKey('--timeout-seconds') -or $options.ContainsKey('--cancel-file');if(-not $lifecycle){[System.IO.File]::WriteAllText($tempLaunchSelection,$selectionJson,[System.Text.Encoding]::UTF8);$code=Invoke-Program $adapter (@('--operation','launch','--request',$tempLaunchSelection,'--output',$outputPath,'--error',$errorPath,'--')+$forwardedArgs.ToArray()) $callerDirectory $tempCatalog $tempAdapterError;if($code -ne 0){$diag=[System.IO.File]::ReadAllText($tempAdapterError).Trim();if($diag){[Console]::Error.WriteLine("ERROR: adapter launch failed with exit code ${code}: $diag")}};exit $code} - if(-not $assignmentId){$assignmentId="$role-$(Get-Date -Format 'yyyyMMddHHmmssfff')"};if(-not $lifecyclePath){$lifecyclePath="$outputPath.lifecycle.json"};$lifecyclePath=Ensure-Path $lifecyclePath 'lifecycle path' $callerDirectory;if($attempt -lt 1 -or $attempt -gt 2){Fail 'attempt must be 1 or 2; policy allows at most one retry per assignment'};if($resourceLedgerPath){Invoke-ResourceLedger 'init' @('--ledger',$resourceLedgerPath)|Out-Null} + $request=[ordered]@{protocol_version=2;operation='catalog';role=$role;preference=$preference;effort=$effort;required_capabilities=@($allCapabilities);policy_revision=[string](Property $policy 'policy_revision');route=$route};[System.IO.File]::WriteAllText($tempRequest,($request|ConvertTo-Json -Depth 20),[System.Text.Encoding]::UTF8);$catalogCode=Invoke-Program $adapter @('--operation','catalog','--request',$tempRequest) $callerDirectory $tempCatalog $tempAdapterError;if($catalogCode -ne 0){$diagnostic=[System.IO.File]::ReadAllText($tempAdapterError).Trim();Fail "adapter catalog discovery failed with exit code $catalogCode$(if($diagnostic){": $diagnostic"})" 127};$catalog=Read-Json $tempCatalog 'adapter catalog';if((Property $catalog 'protocol_version') -ne 2){Fail "adapter catalog has unsupported protocol_version '$(Property $catalog 'protocol_version')'; protocol version 2 requires verified preflight records" 127};$selector=Join-Path $scriptDir 'select-compatible-worker.ps1';$selectorArgs=@('-NoProfile','-NonInteractive','-File',$selector,'--catalog',$tempCatalog,'--policy',$policyFile,'--request',$tempRequest,'--output',$tempLaunchSelection);if($pinPath){$selectorArgs+=@('--pin',$pinPath)};if($provider){$selectorArgs+=@('--provider',$provider)};if($allowUnknownUsage){$selectorArgs+='--allow-unknown-usage'};$selectorCode=Invoke-Program @{File=(Get-Command pwsh -ErrorAction Stop).Source;Prefix=@()} $selectorArgs $callerDirectory $tempCatalog $tempAdapterError;if($selectorCode -ne 0){$diagnostic=[System.IO.File]::ReadAllText($tempAdapterError).Trim();Fail "worker selection failed with exit code $selectorCode$(if($diagnostic){": $diagnostic"})" $selectorCode};$selectionJson=[System.IO.File]::ReadAllText($tempLaunchSelection);$selection=ConvertFrom-Json -InputObject $selectionJson -Depth 50;if($selectionOutputPath){[System.IO.File]::WriteAllText($selectionOutputPath,$selectionJson,[System.Text.Encoding]::UTF8)} + if(-not $assignmentId){$assignmentId="$role-$(Get-Date -Format 'yyyyMMddHHmmssfff')"};if($capacityLedgerPath -and -not $reservationId){$reservationId="capacity:$assignmentId:attempt:$attempt"};function Finalize-Capacity([string]$state,[string]$reason){if(-not $capacityReserved -or $capacityFinalized){return};$mapped=if($state -in @('completed','cancelled','failed','recovered')){$state}else{'failed'};try{Invoke-CapacityLedger 'reconcile' @('--ledger',$capacityLedgerPath,'--reservation-id',$reservationId,'--state',$mapped,'--reason',$reason)|Out-Null}catch{[Console]::Error.WriteLine("WARNING: could not reconcile capacity reservation $reservationId`: $($_.Exception.Message)")};$script:capacityFinalized=$true};if($capacityLedgerPath){[System.IO.File]::WriteAllText($tempLaunchSelection,$selectionJson,[System.Text.Encoding]::UTF8);Invoke-CapacityLedger 'reserve' @('--ledger',$capacityLedgerPath,'--selection',$tempLaunchSelection,'--reservation-id',$reservationId)|Out-Null;$capacityReserved=$true};$lifecycle=$capacityLedgerPath -or $options.ContainsKey('--lifecycle') -or $options.ContainsKey('--attempt') -or $options.ContainsKey('--resource-ledger') -or $options.ContainsKey('--ledger') -or $options.ContainsKey('--timeout-seconds') -or $options.ContainsKey('--cancel-file');if(-not $lifecycle){[System.IO.File]::WriteAllText($tempLaunchSelection,$selectionJson,[System.Text.Encoding]::UTF8);$code=Invoke-Program $adapter (@('--operation','launch','--request',$tempLaunchSelection,'--output',$outputPath,'--error',$errorPath,'--')+$forwardedArgs.ToArray()) $callerDirectory $tempCatalog $tempAdapterError;if($code -ne 0){$diag=[System.IO.File]::ReadAllText($tempAdapterError).Trim();if($diag){[Console]::Error.WriteLine("ERROR: adapter launch failed with exit code ${code}: $diag")}};Finalize-Capacity $(if($code -eq 0){'completed'}else{'failed'}) $(if($code -eq 0){'worker completed'}else{'adapter launch failed'});exit $code} + if(-not $lifecyclePath){$lifecyclePath="$outputPath.lifecycle.json"};$lifecyclePath=Ensure-Path $lifecyclePath 'lifecycle path' $callerDirectory;if($attempt -lt 1 -or $attempt -gt 2){Fail 'attempt must be 1 or 2; policy allows at most one retry per assignment'};if($resourceLedgerPath){Invoke-ResourceLedger 'init' @('--ledger',$resourceLedgerPath)|Out-Null} $workerResourceId=if($resourceId){$resourceId}else{"worker-process:$($assignmentId):attempt:$attempt"};$resourceParentId=if($parentId){$parentId}else{'orchestrator'};$resourceRegistered=$false;$resourceState='failed';$resourceError='';$script:Record=[ordered]@{schema_version=1;assignment_id=$assignmentId;attempt=$attempt;role=$role;mode=$mode;policy_revision=[string](Property $policy 'policy_revision');model=[string]$selection.model_id;effort=$effort;verification_baseline=if($verificationBaseline){$verificationBaseline}else{$null};resource_ledger=if($resourceLedgerPath){$resourceLedgerPath}else{$null};resource_id=if($resourceLedgerPath){$workerResourceId}else{$null};state='created';events=@();exit_code=$null;termination='none';failure_class='none';artifacts=[ordered]@{output=$outputPath;error=$errorPath;lifecycle=$lifecyclePath}} function Save-Record{[System.IO.File]::WriteAllText($lifecyclePath,($script:Record|ConvertTo-Json -Depth 20),[System.Text.Encoding]::UTF8)};function State([string]$name,[hashtable]$details=@{}){$event=[ordered]@{state=$name;at=[DateTime]::UtcNow.ToString('o')};foreach($key in $details.Keys){$event[$key]=$details[$key]};$script:Record.events=@(@($script:Record.events)+@([pscustomobject]$event));$script:Record.state=$name;foreach($key in $details.Keys){if($script:Record.Contains($key)){$script:Record[$key]=$details[$key]}};Save-Record};Save-Record;State 'created' $process=$null;$workerJob=[IntPtr]::Zero;$workerWatchdog=$null;try{[System.IO.File]::WriteAllText($tempLaunchSelection,$selectionJson,[System.Text.Encoding]::UTF8);$process=Start-Program $adapter (@('--operation','launch','--request',$tempLaunchSelection,'--output',$outputPath,'--error',$errorPath,'--')+$forwardedArgs.ToArray()) $callerDirectory;$workerJob=New-WorkerJob;if(-not (Add-ProcessToWorkerJob $workerJob $process)){Close-WorkerJob $workerJob;$workerJob=[IntPtr]::Zero};$workerWatchdog=Start-WorkerWatchdog $process;if($workerJob -eq [IntPtr]::Zero -and $null -eq $workerWatchdog){Stop-Worker $workerJob $process;throw 'worker containment could not be established'};$processStartTime='';try{$processStartTime=$process.StartTime.ToUniversalTime().ToString('o')}catch{};if($resourceLedgerPath){$registerArgs=[System.Collections.Generic.List[string]]::new();foreach($argument in @('--ledger',$resourceLedgerPath,'--assignment-id',$assignmentId,'--parent-id',$resourceParentId,'--resource-type','worker-process','--process-id',[string]$process.Id,'--owner-marker','agy-worker=agy-worker-v1','--resource-id',$workerResourceId,'--state','active')){$registerArgs.Add($argument)};if($processStartTime){$registerArgs.Add('--process-start-time');$registerArgs.Add($processStartTime)};Invoke-ResourceLedger 'register' $registerArgs.ToArray()|Out-Null;$resourceRegistered=$true};State 'started' @{pid=$process.Id};$outTask=$process.StandardOutput.ReadToEndAsync();$errTask=$process.StandardError.ReadToEndAsync();State 'running';$termination='natural';$deadline=if($timeoutSeconds -gt 0){[DateTime]::UtcNow.AddSeconds($timeoutSeconds)}else{$null};while(-not $process.HasExited){if($cancelFile -and (Test-Path -LiteralPath $cancelFile -PathType Leaf)){$termination='canceled';break};if($deadline -and [DateTime]::UtcNow -ge $deadline){$termination='timeout';break};Start-Sleep -Milliseconds 50};if(-not $process.HasExited){Stop-Worker $workerJob $process}else{$process.WaitForExit()};[System.Threading.Tasks.Task]::WaitAll(@($outTask,$errTask));$code=$process.ExitCode;$valid=$false;try{$parsed=ConvertFrom-Json -InputObject ([System.IO.File]::ReadAllText($outputPath))-Depth 30 -ErrorAction Stop;$valid=($parsed.status -eq 'success' -and $parsed.PSObject.Properties['structured_output'] -and $parsed.structured_output -is [System.Management.Automation.PSCustomObject])}catch{$valid=$false};$text=(Read-OptionalText $outputPath)+"`n"+(Read-OptionalText $errorPath);if($termination -eq 'canceled'){$code=130;$resourceState='cancelled';$resourceError='worker cancelled';State 'canceled' @{exit_code=$code;termination='canceled';failure_class='canceled'}}elseif($termination -eq 'timeout'){$code=124;$resourceState='timed_out';$resourceError='worker timed out';State 'failed' @{exit_code=$code;termination='timeout';failure_class='timeout'}}elseif($code -eq 75 -or $text -match '(?i)quota|resource[_ -]?exhausted|rate limit|\b429\b'){$code=75;$resourceState='quota_handoff';$resourceError='worker quota exhausted';State 'quota-handoff' @{exit_code=$code;termination='quota';failure_class='quota'}}elseif($code -eq 0 -and $valid){$resourceState='completed';State 'completed' @{exit_code=0;termination='natural';failure_class='none'}}else{$code=if($code -eq 0){1}else{$code};$resourceState='failed';$resourceError='malformed worker output';State 'failed' @{exit_code=$code;termination='natural';failure_class='malformed_output'}};State 'retained';State 'cleaned';exit $code}finally{Stop-WorkerWatchdog $workerWatchdog;if($process -and -not $process.HasExited){try{Stop-Worker $workerJob $process}catch{}};if($resourceRegistered){try{$updateArgs=[System.Collections.Generic.List[string]]::new();foreach($argument in @('--ledger',$resourceLedgerPath,'--resource-id',$workerResourceId,'--state',$resourceState)){$updateArgs.Add($argument)};if($resourceError){$updateArgs.Add('--error');$updateArgs.Add($resourceError)};Invoke-ResourceLedger 'update' $updateArgs.ToArray()|Out-Null}catch{[Console]::Error.WriteLine("WARNING: could not update resource ledger: $($_.Exception.Message)")}};Close-WorkerJob $workerJob;if($process){$process.Dispose()}} -} finally { Remove-Item -LiteralPath $tempRequest,$tempCatalog,$tempAdapterError,$tempLaunchSelection -Force -ErrorAction SilentlyContinue } +} finally { if($capacityReserved -and -not $capacityFinalized){$finalCapacityState='failed';if($lifecyclePath -and (Test-Path -LiteralPath $lifecyclePath -PathType Leaf)){try{$finalRecord=Read-Json $lifecyclePath 'lifecycle record';if((Property $finalRecord 'failure_class') -eq 'none'){$finalCapacityState='completed'}elseif((Property $finalRecord 'failure_class') -eq 'canceled'){$finalCapacityState='cancelled'}}catch{}};Finalize-Capacity $finalCapacityState 'launcher cleanup'};Remove-Item -LiteralPath $tempRequest,$tempCatalog,$tempAdapterError,$tempLaunchSelection -Force -ErrorAction SilentlyContinue } diff --git a/scripts/run-agy-json.sh b/scripts/run-agy-json.sh index 9a8da62..d0bccab 100755 --- a/scripts/run-agy-json.sh +++ b/scripts/run-agy-json.sh @@ -2,7 +2,7 @@ # Vendor-neutral worker launcher. Model syntax belongs to the selected adapter. set -euo pipefail -usage() { printf 'Usage: %s --role ROLE [--route default|quality-retry] [--adapter FILE] [--selection-output FILE] [--pin FILE] [lifecycle options] --output FILE --error FILE -- worker-arguments...\n' "$0" >&2; } +usage() { printf 'Usage: %s --role ROLE [--route default|quality-retry] [--adapter FILE] [--selection-output FILE] [--pin FILE] [--capacity-ledger FILE] [lifecycle options] --output FILE --error FILE -- worker-arguments...\n' "$0" >&2; } fail() { printf 'ERROR: %s\n' "$1" >&2; exit "${2:-2}"; } mark_seen() { local name="$1" message="$2"; case "$seen_options" in *"|$name|"*) fail "$message" ;; *) seen_options="${seen_options}${name}|" ;; esac; } was_seen() { case "$seen_options" in *"|$1|"*) return 0 ;; *) return 1 ;; esac; } @@ -10,16 +10,17 @@ kill_process_tree() { local target_pid="$1" signal="$2" child_pid; [ -n "$target stop_worker() { if [ -n "$watchdog_pid" ]; then kill "$watchdog_pid" 2>/dev/null || true; set +e; wait "$watchdog_pid" 2>/dev/null; set -e; watchdog_pid=''; fi; if [ -n "$worker_pgid" ]; then kill -TERM -- "-$worker_pgid" 2>/dev/null || true; sleep 0.1; kill -KILL -- "-$worker_pgid" 2>/dev/null || true; elif [ -n "$adapter_pid" ]; then kill_process_tree "$adapter_pid" TERM; sleep 0.1; kill_process_tree "$adapter_pid" KILL; fi; adapter_pid='';worker_pgid=''; } watch_worker() { while kill -0 "$launcher_pid" 2>/dev/null; do sleep 0.2; done; if [ -n "$worker_pgid" ]; then kill -TERM -- "-$worker_pgid" 2>/dev/null || true; sleep 0.1; kill -KILL -- "-$worker_pgid" 2>/dev/null || true; elif [ -n "$adapter_pid" ]; then kill_process_tree "$adapter_pid" TERM; sleep 0.1; kill_process_tree "$adapter_pid" KILL; fi; } -launcher_pid=$$;adapter_pid='';worker_pgid='';watchdog_pid='';resource_registered=false;worker_resource_id='';resource_state='failed';resource_error='';output_path=''; error_path=''; selection_output_path=''; pin_path=''; adapter_path=''; role=''; route='default'; lifecycle_path=''; attempt=1; mode='unknown'; verification_baseline=''; resource_ledger_path=''; timeout_seconds=0; cancel_file=''; ledger_path=''; assignment_id=''; parent_id=''; resource_id='' +launcher_pid=$$;adapter_pid='';worker_pgid='';watchdog_pid='';resource_registered=false;worker_resource_id='';resource_state='failed';resource_error='';output_path=''; error_path=''; selection_output_path=''; pin_path=''; adapter_path=''; provider=''; allow_unknown_usage=false; role=''; route='default'; lifecycle_path=''; attempt=1; mode='unknown'; verification_baseline=''; resource_ledger_path=''; capacity_ledger_path=''; reservation_id=''; capacity_reserved=false; capacity_finalized=false; timeout_seconds=0; cancel_file=''; ledger_path=''; assignment_id=''; parent_id=''; resource_id='' seen_output=false; seen_error=false; seen_role=false; seen_delimiter=false; worker_args=(); required_caps=(); required_cap_count=0; seen_options='|' while [ "$#" -gt 0 ]; do case "$1" in --) seen_delimiter=true; shift; worker_args=("$@"); break ;; --require-capability) [ "$#" -ge 2 ] || { usage; fail "$1 requires a value"; }; required_caps+=("$2"); required_cap_count=$((required_cap_count + 1)); shift 2; continue ;; --require-capability=*) capability="${1#*=}"; [ -n "$capability" ] || fail '--require-capability requires a non-empty value'; required_caps+=("$capability"); required_cap_count=$((required_cap_count + 1)); shift; continue ;; - --output|--error|--selection-output|--pin|--adapter|--role|--route|--lifecycle|--attempt|--mode|--verification-baseline|--resource-ledger|--timeout-seconds|--cancel-file|--ledger|--assignment-id|--parent-id|--resource-id) + --output|--error|--selection-output|--pin|--adapter|--provider|--role|--route|--lifecycle|--attempt|--mode|--verification-baseline|--resource-ledger|--capacity-ledger|--reservation-id|--timeout-seconds|--cancel-file|--ledger|--assignment-id|--parent-id|--resource-id) option="$1"; [ "$#" -ge 2 ] || { usage; fail "$option requires a value"; }; value="$2"; shift 2 ;; - --output=*|--error=*|--selection-output=*|--pin=*|--adapter=*|--role=*|--route=*|--lifecycle=*|--attempt=*|--mode=*|--verification-baseline=*|--resource-ledger=*|--timeout-seconds=*|--cancel-file=*|--ledger=*|--assignment-id=*|--parent-id=*|--resource-id=*) option="${1%%=*}"; value="${1#*=}"; [ -n "$value" ] || fail "$option requires a value"; shift ;; + --output=*|--error=*|--selection-output=*|--pin=*|--adapter=*|--provider=*|--role=*|--route=*|--lifecycle=*|--attempt=*|--mode=*|--verification-baseline=*|--resource-ledger=*|--capacity-ledger=*|--reservation-id=*|--timeout-seconds=*|--cancel-file=*|--ledger=*|--assignment-id=*|--parent-id=*|--resource-id=*) option="${1%%=*}"; value="${1#*=}"; [ -n "$value" ] || fail "$option requires a value"; shift ;; + --allow-unknown-usage) allow_unknown_usage=true; option=''; value=''; shift; continue ;; *) usage; fail "unknown launcher option: $1" ;; esac case "$option" in @@ -28,6 +29,9 @@ while [ "$#" -gt 0 ]; do --selection-output) mark_seen selection_output 'duplicate --selection-output option'; selection_output_path="$value" ;; --pin) mark_seen pin 'duplicate --pin option'; pin_path="$value" ;; --adapter) mark_seen adapter 'duplicate --adapter option'; adapter_path="$value" ;; + --provider) mark_seen provider 'duplicate --provider option'; provider="$value" ;; + --capacity-ledger) mark_seen capacity_ledger 'duplicate --capacity-ledger option'; capacity_ledger_path="$value" ;; + --reservation-id) mark_seen reservation_id 'duplicate --reservation-id option'; reservation_id="$value" ;; --role) $seen_role && fail 'duplicate --role option'; role="$value"; seen_role=true ;; --route) mark_seen route 'duplicate --route option'; route="$value" ;; --lifecycle) mark_seen lifecycle 'duplicate --lifecycle option'; lifecycle_path="$value" ;; @@ -50,28 +54,29 @@ case "$role" in scout|gate-author|implementer|reviewer|researcher|synthesizer|au for arg in "${worker_args[@]}"; do case "$arg" in --output|--output=*|--model|--model=*|--effort|--effort=*) fail 'caller cannot pass --output, --model, or --effort to the worker' ;; esac; done case "$timeout_seconds" in ''|*[!0-9]*) fail '--timeout-seconds must be zero or a positive integer' ;; esac caller_dir="$(pwd -P)"; resolve_path(){ local p="$1" label="$2"; case "$p" in /*) ;; *) p="$caller_dir/$p" ;; esac; mkdir -p "$(dirname "$p")" || fail "could not create $label parent directory"; printf '%s/%s' "$(cd "$(dirname "$p")" && pwd -P)" "$(basename "$p")"; } -output_path="$(resolve_path "$output_path" output)"; error_path="$(resolve_path "$error_path" error)"; [ "$output_path" != "$error_path" ] || fail 'output and error paths must be different'; [ -z "$selection_output_path" ] || selection_output_path="$(resolve_path "$selection_output_path" 'selection output')" +output_path="$(resolve_path "$output_path" output)"; error_path="$(resolve_path "$error_path" error)"; [ "$output_path" != "$error_path" ] || fail 'output and error paths must be different'; [ -z "$selection_output_path" ] || selection_output_path="$(resolve_path "$selection_output_path" 'selection output')"; [ -z "$capacity_ledger_path" ] || capacity_ledger_path="$(resolve_path "$capacity_ledger_path" 'capacity ledger')"; [ -n "$assignment_id" ] || assignment_id="$role-$(date -u +%Y%m%d%H%M%S)"; [ -n "$reservation_id" ] || reservation_id="capacity:$assignment_id:attempt:$attempt" script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"; resource_ledger_script="$script_dir/resource-ledger.sh"; [ -f "$resource_ledger_script" ] || fail "resource ledger helper not found: $resource_ledger_script"; if [ -n "$ledger_path" ]; then ledger_path="$(resolve_path "$ledger_path" ledger)"; if [ -n "$resource_ledger_path" ]; then resource_ledger_path="$(resolve_path "$resource_ledger_path" 'resource ledger')"; [ "$ledger_path" = "$resource_ledger_path" ] || fail '--ledger and --resource-ledger must name the same path'; else resource_ledger_path="$ledger_path"; fi; elif [ -n "$resource_ledger_path" ]; then resource_ledger_path="$(resolve_path "$resource_ledger_path" 'resource ledger')"; fi init_resource_ledger(){ [ -n "$resource_ledger_path" ] || return 0; bash "$resource_ledger_script" init --ledger "$resource_ledger_path" >/dev/null || fail 'could not initialize resource ledger'; } register_resource(){ [ -n "$resource_ledger_path" ] || return 0; local register_args=(register --ledger "$resource_ledger_path" --assignment-id "$assignment_id" --parent-id "${parent_id:-orchestrator}" --resource-type worker-process --process-id "$adapter_pid" --owner-marker 'agy-worker=agy-worker-v1' --resource-id "$worker_resource_id" --state active); bash "$resource_ledger_script" "${register_args[@]}" >/dev/null || fail 'could not register worker process in resource ledger'; resource_registered=true; } update_resource(){ [ "$resource_registered" = true ] || return 0; local update_args=(update --ledger "$resource_ledger_path" --resource-id "$worker_resource_id" --state "$resource_state"); if [ -n "$resource_error" ]; then update_args+=(--error "$resource_error"); fi; if ! bash "$resource_ledger_script" "${update_args[@]}" >/dev/null 2>&1; then printf 'WARNING: could not update resource ledger for %s\n' "$worker_resource_id" >&2; fi; } +capacity_ledger_script="$script_dir/capacity-ledger.sh" +reserve_capacity(){ [ -n "$capacity_ledger_path" ] || return 0; [ -f "$capacity_ledger_script" ] || fail "capacity ledger helper not found: $capacity_ledger_script"; bash "$capacity_ledger_script" reserve --ledger "$capacity_ledger_path" --selection "$selection_tmp" --reservation-id "$reservation_id" >/dev/null || fail 'could not reserve worker capacity' 4; capacity_reserved=true; } +finalize_capacity(){ [ "$capacity_reserved" = true ] || return 0; [ "$capacity_finalized" = true ] && return 0; local final_state="$1" final_reason="$2"; case "$final_state" in completed|cancelled|failed|recovered) ;; *) final_state=failed ;; esac; if ! bash "$capacity_ledger_script" reconcile --ledger "$capacity_ledger_path" --reservation-id "$reservation_id" --state "$final_state" --reason "$final_reason" >/dev/null 2>&1; then printf 'WARNING: could not reconcile capacity reservation %s\n' "$reservation_id" >&2; fi; capacity_finalized=true; } repo_root="$(cd "$script_dir/.." && pwd -P)"; policy_file="$repo_root/model-policy.json"; [ -f "$policy_file" ] || fail "model policy file not found at: $policy_file"; jq empty "$policy_file" >/dev/null 2>&1 || fail 'model policy file is not valid JSON' -validation_err=$(jq -r 'if .schema_version != 2 then "schema_version must be integer 2" elif .max_effort != "high" then "max_effort must be high" elif .max_retries_per_worker != 1 then "max_retries_per_worker must be integer 1" elif .quota_action != "handoff" then "quota_action must be handoff" elif ((.roles|type)!="object") then "roles must be an object" elif ([.roles[] | select((.preference|IN("fast","balanced","deep"))|not)]|length)>0 then "role preference is invalid" elif ([.roles[] | select((.effort|IN("low","medium","high"))|not)]|length)>0 then "role effort is invalid" else "" end' "$policy_file"); [ -z "$validation_err" ] || fail "$validation_err" +validation_err=$(jq -r 'if .schema_version != 2 then "schema_version must be integer 2" elif .max_effort != "high" then "max_effort must be high" elif .max_retries_per_worker != 1 then "max_retries_per_worker must be integer 1" elif .quota_action != "handoff" then "quota_action must be handoff" elif ((.capacity_estimation|type)!="object") then "capacity_estimation must be an object" elif ([.capacity_estimation.assignment_units,.capacity_estimation.verification_units,.capacity_estimation.retry_units,.capacity_estimation.usage_freshness_seconds] | any(. == null or (type != "number") or . <= 0)) then "capacity_estimation values must be positive numbers" elif ((.roles|type)!="object") then "roles must be an object" elif ([.roles[] | select((.preference|IN("fast","balanced","deep"))|not)]|length)>0 then "role preference is invalid" elif ([.roles[] | select((.effort|IN("low","medium","high"))|not)]|length)>0 then "role effort is invalid" else "" end' "$policy_file"); [ -z "$validation_err" ] || fail "$validation_err" preference=$(jq -er --arg role "$role" '.roles[$role].preference' "$policy_file") || fail "role not found in policy: $role"; effort=$(jq -er --arg role "$role" '.roles[$role].effort' "$policy_file") || fail "role not found in policy: $role"; required_caps_json=$(jq -c --arg role "$role" '.roles[$role].required_capabilities' "$policy_file"); if [ "$required_cap_count" -gt 0 ]; then for cap in "${required_caps[@]}"; do required_caps_json=$(jq -c --arg cap "$cap" '.+[$cap]|unique' <<<"$required_caps_json"); done; fi [ "$route" != quality-retry ] || [ -n "$pin_path" ] || fail 'quality-retry requires --pin with the prior selection; use an explicit fallback or handoff when it is unavailable' 3 [ -n "$adapter_path" ] || adapter_path="${OFFLOAD_ADAPTER_BIN:-$script_dir/agy-adapter.sh}"; case "$adapter_path" in /*) ;; *) adapter_path="$caller_dir/$adapter_path" ;; esac; [ -f "$adapter_path" ] || fail "adapter not found: $adapter_path" 127; if [[ "$adapter_path" == *.ps1 ]]; then adapter_cmd=(pwsh -NoProfile -NonInteractive -File "$adapter_path"); else adapter_cmd=("$adapter_path"); fi -request_tmp=$(mktemp);catalog_tmp=$(mktemp);adapter_err_tmp=$(mktemp);selection_tmp=$(mktemp);adapter_out_tmp=$(mktemp);adapter_stderr_tmp=$(mktemp);cleanup(){ stop_worker; rm -f "$request_tmp" "$catalog_tmp" "$adapter_err_tmp" "$selection_tmp" "$adapter_out_tmp" "$adapter_stderr_tmp"; };trap cleanup EXIT;trap 'exit 143' HUP TERM;trap 'exit 130' INT -jq -n --arg role "$role" --arg preference "$preference" --arg effort "$effort" --arg revision "$(jq -er '.policy_revision' "$policy_file")" --argjson caps "$required_caps_json" '{protocol_version:1,operation:"catalog",role:$role,preference:$preference,effort:$effort,required_capabilities:$caps,policy_revision:$revision}' >"$request_tmp" +request_tmp=$(mktemp);catalog_tmp=$(mktemp);adapter_err_tmp=$(mktemp);selection_tmp=$(mktemp);selector_stdout_tmp=$(mktemp);adapter_out_tmp=$(mktemp);adapter_stderr_tmp=$(mktemp);cleanup(){ stop_worker; if [ "$capacity_reserved" = true ] && [ "$capacity_finalized" = false ]; then finalize_capacity failed 'launcher cleanup'; fi; rm -f "$request_tmp" "$catalog_tmp" "$adapter_err_tmp" "$selection_tmp" "$selector_stdout_tmp" "$adapter_out_tmp" "$adapter_stderr_tmp"; };trap cleanup EXIT;trap 'exit 143' HUP TERM;trap 'exit 130' INT +jq -n --arg role "$role" --arg preference "$preference" --arg effort "$effort" --arg route "$route" --arg revision "$(jq -er '.policy_revision' "$policy_file")" --argjson caps "$required_caps_json" '{protocol_version:2,operation:"catalog",role:$role,preference:$preference,effort:$effort,required_capabilities:$caps,policy_revision:$revision,route:$route}' >"$request_tmp" set +e; "${adapter_cmd[@]}" --operation catalog --request "$request_tmp" >"$catalog_tmp" 2>"$adapter_err_tmp"; catalog_code=$?; set -e; [ "$catalog_code" -eq 0 ] || { diagnostic=$(tr '\n' ' ' <"$adapter_err_tmp"); fail "adapter catalog discovery failed with exit code $catalog_code${diagnostic:+: $diagnostic}" 127; }; jq empty "$catalog_tmp" >/dev/null 2>&1 || fail 'adapter catalog is not valid JSON' 127 -catalog_adapter=$(jq -er '.adapter|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing adapter' 127;catalog_vendor=$(jq -er '.vendor|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing vendor' 127;catalog_revision=$(jq -er '.catalog_revision|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing catalog_revision' 127;adapter_revision=$(jq -er '.adapter_revision|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing adapter_revision' 127;[ "$(jq -er '.protocol_version' "$catalog_tmp")" = 1 ] || fail 'adapter catalog has unsupported protocol_version' 127 -selected=$(jq -c --arg pref "$preference" --arg effort "$effort" --argjson caps "$required_caps_json" --arg vendor "$catalog_vendor" '[.models[]? | select((.id|type)=="string" and (.id|length)>0) | select(.available==true and (.quota_available!=false)) | select((.supported_efforts//[])|index($effort)) | select(([$caps[] as $cap | select(((.capabilities//[])|index($cap))==null)]|length)==0) | {model:.,id:.id,vendor:(.vendor//$vendor),score:(((.scores//{})[$pref])//1000000)}] | sort_by(.score,.vendor,.id)|.[0]//empty' "$catalog_tmp") || true; [ -n "$selected" ] || fail "adapter catalog has no eligible model for role '$role', effort '$effort', and required capabilities" 4 -selection_reason="catalog selection preference=$preference effort=$effort; filtered unavailable, quota, effort, capability, and static-policy-incompatible candidates";if [ -n "$pin_path" ];then [ -f "$pin_path" ]||fail "pinned selection file not found: $pin_path" 3;pin_adapter=$(jq -er '.adapter//empty' "$pin_path")||fail 'pinned selection is invalid' 3;pin_vendor=$(jq -er '.vendor//empty' "$pin_path")||fail 'pinned selection is missing vendor' 3;pin_id=$(jq -er '.model_id//.model//empty' "$pin_path")||fail 'pinned selection is missing model_id' 3;pin_effort=$(jq -er '.effort//empty' "$pin_path")||fail 'pinned selection is missing effort' 3;[ "$pin_adapter" = "$catalog_adapter" ]&&[ "$pin_vendor" = "$catalog_vendor" ]&&[ "$pin_effort" = "$effort" ]||fail 'pinned selection does not match the current adapter, vendor, or policy effort; explicit fallback or handoff is required' 3;pinned=$(jq -c --arg id "$pin_id" --arg vendor "$pin_vendor" --arg effort "$effort" --argjson caps "$required_caps_json" '[.models[]? | select(.id==$id and ((.vendor// $vendor)==$vendor) and .available==true and (.quota_available!=false) and ((.supported_efforts//[])|index($effort)) and ([$caps[] as $cap|select(((.capabilities//[])|index($cap))==null)]|length)==0)]|.[0]//empty' "$catalog_tmp");[ -n "$pinned" ]||fail "pinned model '$pin_id' is unavailable in catalog revision '$catalog_revision'; explicit fallback or handoff is required" 3;selected=$(jq -c --argjson model "$pinned" --arg id "$pin_id" --arg vendor "$pin_vendor" '{model:$model,id:$id,vendor:$vendor,score:0}' <<<"$selected");selection_reason="pinned selection adapter=$catalog_adapter vendor=$catalog_vendor model_id=$pin_id; catalog_revision=$catalog_revision";fi -jq -n --arg adapter "$catalog_adapter" --arg adapter_revision "$adapter_revision" --arg vendor "$(jq -r '.vendor' <<<"$selected")" --arg model_id "$(jq -r '.id' <<<"$selected")" --arg family_hint "$(jq -r '.model.family_hint // empty' <<<"$selected")" --arg preference "$preference" --arg effort "$effort" --arg catalog_revision "$catalog_revision" --arg policy_revision "$(jq -er '.policy_revision' "$policy_file")" --arg reason "$selection_reason" --arg route "$route" --argjson caps "$required_caps_json" '{protocol_version:1,adapter:$adapter,adapter_revision:$adapter_revision,vendor:$vendor,model_id:$model_id,model:$model_id,family_hint:$family_hint,preference:$preference,effort:$effort,catalog_revision:$catalog_revision,policy_revision:$policy_revision,required_capabilities:$caps,selection_reason:$reason,route:$route}' >"$selection_tmp"; [ -z "$selection_output_path" ] || cp "$selection_tmp" "$selection_output_path" -lifecycle=false; if was_seen lifecycle || was_seen attempt || was_seen resource_ledger || was_seen ledger || was_seen timeout || was_seen cancel; then lifecycle=true; fi -if ! $lifecycle; then set +e; "${adapter_cmd[@]}" --operation launch --request "$selection_tmp" --output "$output_path" --error "$error_path" -- "${worker_args[@]}" >"$catalog_tmp" 2>"$adapter_err_tmp"; code=$?; set -e; if [ "$code" -ne 0 ] && [ -s "$adapter_err_tmp" ]; then printf 'ERROR: adapter launch failed with exit code %s: %s\n' "$code" "$(tr '\n' ' ' <"$adapter_err_tmp")" >&2; fi; exit "$code"; fi +catalog_adapter=$(jq -er '.adapter|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing adapter' 127;catalog_vendor=$(jq -er '.vendor|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing vendor' 127;catalog_revision=$(jq -er '.catalog_revision|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing catalog_revision' 127;adapter_revision=$(jq -er '.adapter_revision|strings|select(length>0)' "$catalog_tmp") || fail 'adapter catalog is missing adapter_revision' 127;[ "$(jq -er '.protocol_version' "$catalog_tmp")" = 2 ] || fail 'adapter catalog has unsupported protocol_version; protocol version 2 requires verified preflight records' 127 +selector="$script_dir/select-compatible-worker.sh";[ -f "$selector" ] || fail "worker selector not found: $selector";selector_args=(--catalog "$catalog_tmp" --policy "$policy_file" --request "$request_tmp" --output "$selection_tmp");[ -z "$pin_path" ] || selector_args+=(--pin "$pin_path");[ -z "$provider" ] || selector_args+=(--provider "$provider");[ "$allow_unknown_usage" = false ] || selector_args+=(--allow-unknown-usage);set +e;"$selector" "${selector_args[@]}" >"$selector_stdout_tmp" 2>"$adapter_err_tmp";selector_code=$?;set -e;if [ "$selector_code" -ne 0 ]; then diagnostic=$(tr '\n' ' ' <"$adapter_err_tmp");fail "worker selection failed${diagnostic:+: $diagnostic}" "$selector_code";fi;[ -z "$selection_output_path" ] || cp "$selection_tmp" "$selection_output_path";reserve_capacity +lifecycle=false; if [ -n "$capacity_ledger_path" ] || was_seen lifecycle || was_seen attempt || was_seen resource_ledger || was_seen ledger || was_seen timeout || was_seen cancel; then lifecycle=true; fi +if ! $lifecycle; then set +e; "${adapter_cmd[@]}" --operation launch --request "$selection_tmp" --output "$output_path" --error "$error_path" -- "${worker_args[@]}" >"$catalog_tmp" 2>"$adapter_err_tmp"; code=$?; set -e; if [ "$code" -ne 0 ] && [ -s "$adapter_err_tmp" ]; then printf 'ERROR: adapter launch failed with exit code %s: %s\n' "$code" "$(tr '\n' ' ' <"$adapter_err_tmp")" >&2; fi; if [ "$code" -eq 0 ]; then finalize_capacity completed 'worker completed'; else finalize_capacity failed 'adapter launch failed'; fi; exit "$code"; fi case "$attempt" in 1|2) ;; *) fail 'attempt must be 1 or 2; policy allows at most one retry per assignment' ;; esac;[ -n "$assignment_id" ]||assignment_id="$role-$(date -u +%Y%m%d%H%M%S)";[ -n "$lifecycle_path" ]||lifecycle_path="$output_path.lifecycle.json";lifecycle_path="$(resolve_path "$lifecycle_path" lifecycle)";worker_resource_id="${resource_id:-worker-process:$assignment_id:attempt:$attempt}";init_resource_ledger jq -n --arg assignment "$assignment_id" --argjson attempt "$attempt" --arg role "$role" --arg mode "$mode" --arg policy_revision "$(jq -er '.policy_revision' "$policy_file")" --arg model "$(jq -r '.model_id' "$selection_tmp")" --arg effort "$effort" --arg baseline "${verification_baseline:-}" --arg ledger "${resource_ledger_path:-}" --arg resource_id "${resource_ledger_path:+$worker_resource_id}" --arg output "$output_path" --arg error "$error_path" --arg lifecycle "$lifecycle_path" '{schema_version:1,assignment_id:$assignment,attempt:$attempt,role:$role,mode:$mode,policy_revision:$policy_revision,model:$model,effort:$effort,verification_baseline:($baseline|if length>0 then . else null end),resource_ledger:($ledger|if length>0 then . else null end),resource_id:($resource_id|if length>0 then . else null end),state:"created",events:[],exit_code:null,termination:"none",failure_class:"none",artifacts:{output:$output,error:$error,lifecycle:$lifecycle}}' >"$lifecycle_path" state(){ local name="$1";jq --arg state "$name" --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.events += [{state:$state,at:$at}]|.state=$state' "$lifecycle_path" >"$lifecycle_path.tmp";mv -f "$lifecycle_path.tmp" "$lifecycle_path"; };state created set +e;if command -v setsid >/dev/null 2>&1;then setsid "${adapter_cmd[@]}" --operation launch --request "$selection_tmp" --output "$output_path" --error "$error_path" -- "${worker_args[@]}" >"$adapter_out_tmp" 2>"$adapter_stderr_tmp" & adapter_pid=$!;worker_pgid="$adapter_pid";else "${adapter_cmd[@]}" --operation launch --request "$selection_tmp" --output "$output_path" --error "$error_path" -- "${worker_args[@]}" >"$adapter_out_tmp" 2>"$adapter_stderr_tmp" & adapter_pid=$!;fi;set -e;watch_worker >/dev/null 2>&1 & watchdog_pid=$!;register_resource;state started;state running;termination=natural;deadline=0;[ "$timeout_seconds" -gt 0 ]&&deadline=$(( $(date +%s) + timeout_seconds ));while kill -0 "$adapter_pid" 2>/dev/null;do if [ -n "$cancel_file" ]&&[ -f "$cancel_file" ];then termination=canceled;break;fi;if [ "$deadline" -gt 0 ]&&[ "$(date +%s)" -ge "$deadline" ];then termination=timeout;break;fi;sleep 0.05;done;wait_pid="$adapter_pid";if [ "$termination" != natural ];then stop_worker;fi;set +e;wait "$wait_pid";code=$?;set -e if [ "$termination" = canceled ];then code=130;failure=canceled;terminal_state=canceled;resource_state=cancelled;resource_error='worker cancelled';elif [ "$termination" = timeout ];then code=124;failure=timeout;terminal_state=failed;resource_state=timed_out;resource_error='worker timed out';elif [ "$code" -eq 75 ]||grep -Eiq 'quota|resource[_ -]?exhausted|rate limit|\b429\b' "$output_path" "$error_path" 2>/dev/null;then code=75;failure=quota;terminal_state=quota-handoff;resource_state=quota_handoff;resource_error='worker quota exhausted';elif [ "$code" -eq 0 ]&&jq -e '(.status=="success") and (.structured_output|type=="object")' "$output_path" >/dev/null 2>&1;then code=0;failure=none;terminal_state=completed;resource_state=completed;else [ "$code" -eq 0 ]&&code=1;failure=malformed_output;terminal_state=failed;resource_state=failed;resource_error='malformed worker output';fi - jq --arg state "$terminal_state" --arg failure "$failure" --arg termination "$termination" --argjson code "$code" '.exit_code=$code|.failure_class=$failure|.termination=$termination' "$lifecycle_path" >"$lifecycle_path.tmp";mv -f "$lifecycle_path.tmp" "$lifecycle_path";state "$terminal_state";state retained;state cleaned;update_resource;exit "$code" + jq --arg state "$terminal_state" --arg failure "$failure" --arg termination "$termination" --argjson code "$code" '.exit_code=$code|.failure_class=$failure|.termination=$termination' "$lifecycle_path" >"$lifecycle_path.tmp";mv -f "$lifecycle_path.tmp" "$lifecycle_path";state "$terminal_state";state retained;state cleaned;update_resource;if [ "$failure" = none ]; then finalize_capacity completed 'worker completed'; elif [ "$failure" = canceled ]; then finalize_capacity cancelled 'worker cancelled'; else finalize_capacity failed "$failure"; fi;exit "$code" diff --git a/scripts/run-claude-json.ps1 b/scripts/run-claude-json.ps1 index b0c8a9e..e817ce2 100644 --- a/scripts/run-claude-json.ps1 +++ b/scripts/run-claude-json.ps1 @@ -88,6 +88,15 @@ function Get-CatalogData { } } +function Get-Preflight($model) { + if ($null -ne $model -and $model.PSObject.Properties['preflight']) { return $model.preflight } + return [ordered]@{ + access = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify authenticated access'; account_ref = '' } + entitlement = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify model entitlement'; billing_route = 'unknown' } + usage = [ordered]@{ state = 'unknown'; reason = 'adapter did not query usage'; source = 'not-queried'; observed_at = ''; scopes = @() } + } +} + function Get-FamilyHint([string]$ModelId) { if ($ModelId -match 'opus') { return 'opus' } if ($ModelId -match 'sonnet') { return 'sonnet' } @@ -173,6 +182,7 @@ if ($operation -eq 'catalog') { supported_efforts = @('low', 'medium', 'high') capabilities = @('structured-output') scores = Get-PreferenceScore $family + preflight = Get-Preflight $null } } elseif ($m -is [PSCustomObject]) { $mId = [string]$m.id @@ -188,6 +198,7 @@ if ($operation -eq 'catalog') { supported_efforts = @($efforts | ForEach-Object { [string]$_ }) capabilities = @($caps | ForEach-Object { [string]$_ }) scores = $scores + preflight = Get-Preflight $m } } } @@ -200,9 +211,9 @@ if ($operation -eq 'catalog') { } $catalogDoc = [ordered]@{ - protocol_version = 1 + protocol_version = 2 adapter = 'claude' - adapter_revision = 'claude-1' + adapter_revision = 'claude-2' vendor = 'anthropic' catalog_revision = $revision models = $models diff --git a/scripts/run-claude-json.sh b/scripts/run-claude-json.sh index af9e0c2..8185a26 100755 --- a/scripts/run-claude-json.sh +++ b/scripts/run-claude-json.sh @@ -97,9 +97,9 @@ if [ "$operation" = catalog ]; then elif $fam == "opus" then {fast: 3, balanced: 2, deep: 1} else {fast: 100, balanced: 100, deep: 100} end; { - protocol_version: 1, + protocol_version: 2, adapter: "claude", - adapter_revision: "claude-1", + adapter_revision: "claude-2", vendor: "anthropic", catalog_revision: (.revision // "claude-current"), models: [ @@ -113,7 +113,8 @@ if [ "$operation" = catalog ]; then quota_available: (if has("quota_available") then .quota_available else true end), supported_efforts: (.supported_efforts // .efforts // ["low", "medium", "high"]), capabilities: (.capabilities // ["structured-output"]), - scores: (.scores // score_map($fam)) + scores: (.scores // score_map($fam)), + preflight: (.preflight // {access:{state:"unknown",reason:"adapter did not verify authenticated access",account_ref:""},entitlement:{state:"unknown",reason:"adapter did not verify model entitlement",billing_route:"unknown"},usage:{state:"unknown",reason:"adapter did not query usage",source:"not-queried",observed_at:"",scopes:[]}}) }) ] } diff --git a/scripts/run-codex-json.ps1 b/scripts/run-codex-json.ps1 index d3de3c7..9148422 100644 --- a/scripts/run-codex-json.ps1 +++ b/scripts/run-codex-json.ps1 @@ -88,6 +88,15 @@ function Get-CatalogData { } } +function Get-Preflight($model) { + if ($null -ne $model -and $model.PSObject.Properties['preflight']) { return $model.preflight } + return [ordered]@{ + access = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify authenticated access'; account_ref = '' } + entitlement = [ordered]@{ state = 'unknown'; reason = 'adapter did not verify model entitlement'; billing_route = 'unknown' } + usage = [ordered]@{ state = 'unknown'; reason = 'adapter did not query usage'; source = 'not-queried'; observed_at = ''; scopes = @() } + } +} + $operation = '' $requestPath = '' $outputPath = '' @@ -167,6 +176,7 @@ if ($operation -eq 'catalog') { supported_efforts = @($efforts | ForEach-Object { [string]$_ }) capabilities = @($caps | ForEach-Object { [string]$_ }) scores = $scores + preflight = Get-Preflight $m } } ) @@ -178,9 +188,9 @@ if ($operation -eq 'catalog') { } $catalogDoc = [ordered]@{ - protocol_version = 1 + protocol_version = 2 adapter = 'codex' - adapter_revision = 'codex-1' + adapter_revision = 'codex-2' vendor = 'codex' catalog_revision = $revision models = $models @@ -207,6 +217,7 @@ if ([string]::IsNullOrWhiteSpace($modelId)) { Fail 'selection is missing model_i $prompt = '' $worktree = '' $schemaPath = '' +$schemaInline = '' $resumeSession = '' $j = 0 while ($j -lt $workerArgs.Count) { @@ -236,7 +247,7 @@ while ($j -lt $workerArgs.Count) { $j++; continue } if ($warg -in @('--output-schema', '--json-schema')) { - $j++; if ($j -lt $workerArgs.Count) { $schemaPath = [string]$workerArgs[$j] } + $j++; if ($j -lt $workerArgs.Count) { $candidateSchema = [string]$workerArgs[$j]; if ($candidateSchema.TrimStart().StartsWith('{') -or $candidateSchema.TrimStart().StartsWith('[')) { $schemaInline = $candidateSchema; $schemaPath = '' } else { $schemaPath = $candidateSchema } } $j++; continue } if ($warg -in @('--resume', '--resume-session')) { @@ -275,7 +286,12 @@ if ($errParent -and -not (Test-Path -LiteralPath $errParent -PathType Container) } $tempSchema = $null -if ([string]::IsNullOrWhiteSpace($schemaPath) -or -not (Test-Path -LiteralPath $schemaPath -PathType Leaf)) { +if (-not [string]::IsNullOrWhiteSpace($schemaInline)) { + try { $null = $schemaInline | ConvertFrom-Json -Depth 30 -ErrorAction Stop } catch { Fail "inline output schema is not valid JSON: $($_.Exception.Message)" 2 } + $tempSchema = [System.IO.Path]::GetTempFileName() + [System.IO.File]::WriteAllText($tempSchema, $schemaInline, [System.Text.Encoding]::UTF8) + $schemaPath = $tempSchema +} elseif ([string]::IsNullOrWhiteSpace($schemaPath) -or -not (Test-Path -LiteralPath $schemaPath -PathType Leaf)) { $tempSchema = [System.IO.Path]::GetTempFileName() [System.IO.File]::WriteAllText($tempSchema, '{"type":"object","additionalProperties":true}', [System.Text.Encoding]::UTF8) $schemaPath = $tempSchema diff --git a/scripts/run-codex-json.sh b/scripts/run-codex-json.sh index 8f50894..4c6005b 100644 --- a/scripts/run-codex-json.sh +++ b/scripts/run-codex-json.sh @@ -92,9 +92,9 @@ if [ "$operation" = catalog ]; then elif $pref == "deep" then {fast: 3, balanced: 2, deep: 1} else {fast: 100, balanced: 100, deep: 100} end; { - protocol_version: 1, + protocol_version: 2, adapter: "codex", - adapter_revision: "codex-1", + adapter_revision: "codex-2", vendor: "codex", catalog_revision: (.revision // "codex-current"), models: [ @@ -105,7 +105,8 @@ if [ "$operation" = catalog ]; then quota_available: (if has("quota_available") then .quota_available else true end), supported_efforts: (.supported_efforts // .efforts // ["low", "medium", "high"]), capabilities: (.capabilities // ["structured-output"]), - scores: (.scores // score_map(.preference // "balanced")) + scores: (.scores // score_map(.preference // "balanced")), + preflight: (.preflight // {access:{state:"unknown",reason:"adapter did not verify authenticated access",account_ref:""},entitlement:{state:"unknown",reason:"adapter did not verify model entitlement",billing_route:"unknown"},usage:{state:"unknown",reason:"adapter did not query usage",source:"not-queried",observed_at:"",scopes:[]}}) } ] } @@ -123,6 +124,7 @@ model_id=$(jq -er '.model_id // .model // empty' "$request_path") || fail 'selec prompt='' worktree='' schema_path='' +schema_inline='' resume_session='' idx=0 @@ -157,7 +159,13 @@ while [ "$idx" -lt "${#worker_args[@]}" ]; do ;; --output-schema|--json-schema) idx=$((idx + 1)) - [ "$idx" -lt "${#worker_args[@]}" ] && schema_path="${worker_args[$idx]}" + if [ "$idx" -lt "${#worker_args[@]}" ]; then + candidate_schema="${worker_args[$idx]}" + case "$candidate_schema" in + \{*|\[* ) schema_inline="$candidate_schema"; schema_path='' ;; + *) schema_path="$candidate_schema" ;; + esac + fi idx=$((idx + 1)) ;; --resume|--resume-session) @@ -188,7 +196,12 @@ done [ -d "$worktree" ] || fail "worktree does not exist: $worktree" temp_schema='' -if [ -z "$schema_path" ] || [ ! -f "$schema_path" ]; then +if [ -n "$schema_inline" ]; then + jq empty <<<"$schema_inline" >/dev/null 2>&1 || fail 'inline output schema is not valid JSON' + temp_schema=$(mktemp) + printf '%s' "$schema_inline" > "$temp_schema" + schema_path="$temp_schema" +elif [ -z "$schema_path" ] || [ ! -f "$schema_path" ]; then temp_schema=$(mktemp) printf '%s\n' '{"type":"object","additionalProperties":true}' > "$temp_schema" schema_path="$temp_schema" diff --git a/scripts/select-compatible-worker.ps1 b/scripts/select-compatible-worker.ps1 new file mode 100644 index 0000000..2c8c890 --- /dev/null +++ b/scripts/select-compatible-worker.ps1 @@ -0,0 +1,112 @@ +#!/usr/bin/env pwsh +# Select a worker only after adapter preflight establishes access, entitlement, +# capabilities, and capacity for the complete retry budget. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Fail([string]$message, [int]$code = 4) { [Console]::Error.WriteLine("ERROR: $message"); exit $code } +function P($object, [string]$name) { + if ($null -eq $object) { return $null } + $property = $object.PSObject.Properties[$name] + if ($null -eq $property) { return $null } + return $property.Value +} +function Has($object, [string]$name) { return $null -ne $object -and $null -ne $object.PSObject.Properties[$name] } +function Text($value) { if ($null -eq $value) { return '' }; return [string]$value } +function State($value) { return (Text $value).Trim().ToLowerInvariant() } +function Read-Json([string]$path, [string]$label) { + try { return ConvertFrom-Json -InputObject ([System.IO.File]::ReadAllText($path)) -Depth 50 -ErrorAction Stop } + catch { Fail "$label is not valid JSON: $($_.Exception.Message)" 127 } +} + +$catalogPath=''; $policyPath=''; $requestPath=''; $outputPath=''; $pinPath=''; $provider=''; $allowUnknownUsage=$false +$i=0 +while ($i -lt $args.Count) { + $arg=[string]$args[$i] + switch ($arg) { + '--catalog' { $i++; if ($i -ge $args.Count) { Fail '--catalog requires a value' 2 }; $catalogPath=[string]$args[$i] } + '--policy' { $i++; if ($i -ge $args.Count) { Fail '--policy requires a value' 2 }; $policyPath=[string]$args[$i] } + '--request' { $i++; if ($i -ge $args.Count) { Fail '--request requires a value' 2 }; $requestPath=[string]$args[$i] } + '--output' { $i++; if ($i -ge $args.Count) { Fail '--output requires a value' 2 }; $outputPath=[string]$args[$i] } + '--pin' { $i++; if ($i -ge $args.Count) { Fail '--pin requires a value' 2 }; $pinPath=[string]$args[$i] } + '--provider' { $i++; if ($i -ge $args.Count) { Fail '--provider requires a value' 2 }; $provider=[string]$args[$i] } + '--allow-unknown-usage' { $allowUnknownUsage=$true } + default { Fail "unknown selector option: $arg" 2 } + } + $i++ +} +if (-not $catalogPath -or -not $policyPath -or -not $requestPath -or -not $outputPath) { Fail '--catalog, --policy, --request, and --output are required' 2 } + +$catalog=Read-Json $catalogPath 'adapter catalog'; $policy=Read-Json $policyPath 'model policy'; $request=Read-Json $requestPath 'catalog request' +if ((P $catalog 'protocol_version') -ne 2) { Fail "adapter catalog has unsupported protocol_version '$(P $catalog 'protocol_version')'; protocol version 2 requires verified preflight records" 127 } +$adapter=Text (P $catalog 'adapter'); $vendor=Text (P $catalog 'vendor'); $catalogRevision=Text (P $catalog 'catalog_revision'); $adapterRevision=Text (P $catalog 'adapter_revision') +if (@($adapter,$vendor,$catalogRevision,$adapterRevision | Where-Object { [string]::IsNullOrWhiteSpace([string]$_) }).Count -gt 0) { Fail 'adapter catalog is missing required metadata' 127 } +$pinForEligibility=$null; $pinProviderForEligibility='' +if ($pinPath) { + if (-not (Test-Path -LiteralPath $pinPath -PathType Leaf)) { Fail "pinned selection file not found: $pinPath" 3 } + $pinForEligibility=Read-Json $pinPath 'pinned selection'; $pinProviderForEligibility=Text (P $pinForEligibility 'provider'); if (-not $pinProviderForEligibility) { $pinProviderForEligibility=Text (P $pinForEligibility 'vendor') } +} +$unknownUsageAllowed=$allowUnknownUsage -and (($provider -and $provider.Trim()) -or ($pinPath -and $pinProviderForEligibility)) + +$estimate=P $policy 'capacity_estimation' +$estimateVersion=if (Has $estimate 'version') { [int](P $estimate 'version') } else { 1 } +$assignmentUnits=if (Has $estimate 'assignment_units') { [int](P $estimate 'assignment_units') } else { 1 } +$verificationUnits=if (Has $estimate 'verification_units') { [int](P $estimate 'verification_units') } else { 1 } +$retryUnits=if (Has $estimate 'retry_units') { [int](P $estimate 'retry_units') } else { 1 } +$requiredUnits=$assignmentUnits+$verificationUnits+$retryUnits +$freshness=if (Has $estimate 'usage_freshness_seconds') { [int](P $estimate 'usage_freshness_seconds') } else { 300 } +if ($estimateVersion -lt 1 -or $requiredUnits -le 0 -or $freshness -le 0) { Fail 'capacity estimation policy is invalid' 127 } +$effort=Text (P $request 'effort'); $preference=Text (P $request 'preference'); $requiredCapabilities=@((P $request 'required_capabilities'))|ForEach-Object{Text $_}|Where-Object{$_} +$now=[DateTime]::UtcNow; $eligible=[System.Collections.Generic.List[object]]::new(); $rejections=[System.Collections.Generic.List[string]]::new() + +foreach ($model in @((P $catalog 'models'))) { + $id=Text (P $model 'id'); $modelProvider=Text (P $model 'provider'); if (-not $modelProvider) { $modelProvider=if (Has $model 'vendor') { Text (P $model 'vendor') } else { $vendor } } + $preflight=P $model 'preflight'; $access=P $preflight 'access'; $entitlement=P $preflight 'entitlement'; $usage=P $preflight 'usage' + $reasons=[System.Collections.Generic.List[string]]::new(); $accessState=State (P $access 'state'); $entitlementState=State (P $entitlement 'state'); $billing=Text (P $entitlement 'billing_route') + if (-not $id) { $reasons.Add('missing model id') } + if ((Has $model 'available') -and (P $model 'available') -eq $false) { $reasons.Add('adapter marked model unavailable') } + if ((Has $model 'quota_available') -and (P $model 'quota_available') -eq $false) { $reasons.Add('adapter marked quota unavailable') } + if ($accessState -notin @('verified','authenticated','available')) { $reasons.Add('access is not verified') } + if (-not (Text (P $access 'account_ref'))) { $reasons.Add('account identifier is missing') } + if ($entitlementState -notin @('active','continuing')) { $reasons.Add('entitlement is not active') } + if (-not $billing -or $billing -in @('paid-fallback','unknown')) { $reasons.Add('billing route is not established') } + $supportedEfforts=@((P $model 'supported_efforts'))|ForEach-Object{Text $_}; if ($supportedEfforts -notcontains $effort) { $reasons.Add('effort is unsupported') } + $caps=@((P $model 'capabilities'))|ForEach-Object{Text $_}; foreach ($cap in $requiredCapabilities) { if ($caps -notcontains $cap) { $reasons.Add("missing capability '$cap'") } } + $observedText=Text (P $usage 'observed_at'); $observed=$null; if ($observedText) { try { $observed=[DateTime]::Parse($observedText).ToUniversalTime() } catch { $observed=$null } } + $scopes=@((P $usage 'scopes')); $ageSeconds=if($null -ne $observed){$now.Subtract([DateTime]$observed).TotalSeconds}else{[double]::PositiveInfinity}; $usageKnown=(State (P $usage 'state') -eq 'known' -and $null -ne $observed -and $observed -le $now -and $ageSeconds -le $freshness -and $scopes.Count -gt 0); $remaining=[double]::PositiveInfinity + if ($usageKnown) { + foreach ($scope in $scopes) { + if (-not (Has $scope 'remaining_units') -or -not (Has $scope 'reserved_units')) { $usageKnown=$false; break } + try { $available=[double](P $scope 'remaining_units')-[double](P $scope 'reserved_units'); if ($available -lt $remaining) { $remaining=$available }; if ($available -lt $requiredUnits) { $reasons.Add("insufficient capacity in scope '$(Text (P $scope 'scope_id'))'") } } catch { $usageKnown=$false; break } + } + } + if ((State (P $usage 'state')) -eq 'exhausted') { $reasons.Add('usage is exhausted') } + if (-not $usageKnown) { if (-not $unknownUsageAllowed) { $reasons.Add('usage is unknown or stale') } else { $remaining=$null } } + $nonUsage=@($reasons|Where-Object{$_ -notmatch '^usage is unknown or stale$' -and $_ -notmatch '^insufficient capacity'}) + $hasExhaustion=@($reasons|Where-Object{$_ -match '^insufficient capacity'}).Count -gt 0 + if ($nonUsage.Count -eq 0 -and (-not $hasExhaustion) -and ($usageKnown -or $unknownUsageAllowed)) { + $scoreValue=P (P $model 'scores') $preference; if ($null -eq $scoreValue) { $scoreValue=1000000 }; try { $score=[double]$scoreValue } catch { $score=1000000 } + $eligible.Add([pscustomobject]@{ Model=$model; Id=$id; Provider=$modelProvider; Score=$score; Remaining=$remaining; UsageKnown=$usageKnown; Preflight=$preflight }) + } elseif ($reasons.Count -gt 0) { $rejections.Add("${id}: $($reasons -join ', ')") } +} +if ($eligible.Count -eq 0) { $detail=if($rejections.Count){"; $($rejections -join '; ')"}else{''}; Fail "no eligible worker: verified access, active entitlement, required capability, and capacity for assignment + verification + one retry are required$detail" 4 } + +$selected=$null +if ($pinPath) { + $pin=$pinForEligibility; $pinId=Text (P $pin 'model_id'); $pinProvider=$pinProviderForEligibility + if ((Text (P $pin 'adapter')) -ne $adapter -or (Text (P $pin 'effort')) -ne $effort -or -not $pinId) { Fail 'pinned selection does not match the current adapter or policy effort; explicit fallback or handoff is required' 3 } + $selected=$eligible|Where-Object{$_.Id -eq $pinId -and $_.Provider -eq $pinProvider}|Select-Object -First 1; if ($null -eq $selected) { Fail "pinned model '$pinId' is unavailable or no longer eligible; explicit fallback or handoff is required" 3 } + $reason="pinned selection adapter=$adapter provider=$($selected.Provider) model_id=$pinId; preflight revalidated" +} elseif ($provider) { + $candidates=@($eligible|Where-Object{$_.Provider -eq $provider -or (Text (P $_.Model 'adapter')) -eq $provider -or (Text (P $_.Model 'vendor')) -eq $provider}) + if (-not $candidates.Count) { Fail "explicit provider '$provider' is not eligible; no silent fallback is permitted" 3 } + $selected=$candidates|Sort-Object Score,@{Expression={if($null -eq $_.Remaining){-1}else{-[double]$_.Remaining}}},Provider,Id|Select-Object -First 1; $reason="explicit provider '$provider' selected after eligibility checks; no fallback" +} else { + $selected=$eligible|Sort-Object Score,@{Expression={if($null -eq $_.Remaining){-1}else{-[double]$_.Remaining}}},Provider,Id|Select-Object -First 1 + $reason="selected by preference=$preference, capability match, and remaining capacity; estimate units=$requiredUnits (assignment=$assignmentUnits, verification=$verificationUnits, retry=$retryUnits)" +} + +$usage=P $selected.Preflight 'usage' +$selection=[ordered]@{ protocol_version=2; adapter=$adapter; adapter_revision=$adapterRevision; vendor=$vendor; provider=$selected.Provider; model_id=$selected.Id; model=$selected.Id; family_hint=Text (P $selected.Model 'family_hint'); preference=$preference; effort=$effort; catalog_revision=$catalogRevision; policy_revision=Text (P $policy 'policy_revision'); required_capabilities=@($requiredCapabilities); selection_reason=$reason; route=Text (P $request 'route'); eligibility='eligible'; eligibility_reason='verified access, active entitlement, compatible capabilities, and sufficient capacity'; preflight=$selected.Preflight; capacity_estimate=[ordered]@{version=$estimateVersion;assignment_units=$assignmentUnits;verification_units=$verificationUnits;retry_units=$retryUnits;required_units=$requiredUnits;freshness_seconds=$freshness}; usage_observed_at=Text (P $usage 'observed_at'); usage_uncertain=(-not $selected.UsageKnown); reservation=[ordered]@{required_units=$requiredUnits;scopes=@((P $usage 'scopes')|ForEach-Object{Text (P $_ 'scope_id')})} } +$json=$selection|ConvertTo-Json -Depth 50; [System.IO.File]::WriteAllText([System.IO.Path]::GetFullPath($outputPath),$json,[System.Text.Encoding]::UTF8); [Console]::Out.Write($json) diff --git a/scripts/select-compatible-worker.sh b/scripts/select-compatible-worker.sh new file mode 100644 index 0000000..1d58eb3 --- /dev/null +++ b/scripts/select-compatible-worker.sh @@ -0,0 +1,95 @@ +#!/usr/bin/env bash +# Select a worker only after adapter preflight establishes access, entitlement, +# capabilities, and capacity for the complete retry budget. +set -euo pipefail + +fail() { printf 'ERROR: %s\n' "$1" >&2; exit "${2:-4}"; } +catalog=''; policy=''; request=''; output=''; pin=''; provider=''; allow_unknown=false +while [ "$#" -gt 0 ]; do + case "$1" in + --catalog) [ "$#" -ge 2 ] || fail '--catalog requires a value' 2; catalog=$2; shift 2 ;; + --policy) [ "$#" -ge 2 ] || fail '--policy requires a value' 2; policy=$2; shift 2 ;; + --request) [ "$#" -ge 2 ] || fail '--request requires a value' 2; request=$2; shift 2 ;; + --output) [ "$#" -ge 2 ] || fail '--output requires a value' 2; output=$2; shift 2 ;; + --pin) [ "$#" -ge 2 ] || fail '--pin requires a value' 2; pin=$2; shift 2 ;; + --provider) [ "$#" -ge 2 ] || fail '--provider requires a value' 2; provider=$2; shift 2 ;; + --allow-unknown-usage) allow_unknown=true; shift ;; + *) fail "unknown selector option: $1" 2 ;; + esac +done +[ -n "$catalog" ] || fail '--catalog is required' 2 +[ -n "$policy" ] || fail '--policy is required' 2 +[ -n "$request" ] || fail '--request is required' 2 +[ -n "$output" ] || fail '--output is required' 2 +jq empty "$catalog" >/dev/null 2>&1 || fail 'adapter catalog is not valid JSON' 127 +jq empty "$policy" >/dev/null 2>&1 || fail 'model policy is not valid JSON' 127 +jq empty "$request" >/dev/null 2>&1 || fail 'catalog request is not valid JSON' 127 +protocol=$(jq -r '.protocol_version // empty' "$catalog") +[ "$protocol" = 2 ] || fail "adapter catalog has unsupported protocol_version '$protocol'; protocol version 2 requires verified preflight records" 127 +adapter=$(jq -er '.adapter|strings|select(length>0)' "$catalog") || fail 'adapter catalog is missing adapter' 127 +vendor=$(jq -er '.vendor|strings|select(length>0)' "$catalog") || fail 'adapter catalog is missing vendor' 127 +catalog_revision=$(jq -er '.catalog_revision|strings|select(length>0)' "$catalog") || fail 'adapter catalog is missing catalog_revision' 127 +adapter_revision=$(jq -er '.adapter_revision|strings|select(length>0)' "$catalog") || fail 'adapter catalog is missing adapter_revision' 127 +preference=$(jq -er '.preference|strings' "$request") || fail 'catalog request is missing preference' 127 +effort=$(jq -er '.effort|strings' "$request") || fail 'catalog request is missing effort' 127 +policy_revision=$(jq -er '.policy_revision|strings' "$request") || fail 'catalog request is missing policy revision' 127 +assignment_units=$(jq -er '.capacity_estimation.assignment_units // 1' "$policy") || fail 'capacity estimation policy is invalid' 127 +verification_units=$(jq -er '.capacity_estimation.verification_units // 1' "$policy") || fail 'capacity estimation policy is invalid' 127 +retry_units=$(jq -er '.capacity_estimation.retry_units // 1' "$policy") || fail 'capacity estimation policy is invalid' 127 +required_units=$((assignment_units + verification_units + retry_units)) +freshness=$(jq -er '.capacity_estimation.usage_freshness_seconds // 300' "$policy") || fail 'capacity freshness policy is invalid' 127 +estimate_version=$(jq -er '.capacity_estimation.version // 1' "$policy") +now=$(date -u +%s) +request_caps=$(jq -c '.required_capabilities // []' "$request") +allow_json=false; [ "$allow_unknown" = true ] && allow_json=true +pin_id=''; pin_provider=''; pin_adapter=''; pin_effort='' +if [ -n "$pin" ]; then + [ -f "$pin" ] || fail "pinned selection file not found: $pin" 3 + pin_id=$(jq -er '.model_id // .model // empty' "$pin") || fail 'pinned selection is missing model_id' 3 + pin_adapter=$(jq -er '.adapter // empty' "$pin") || fail 'pinned selection is missing adapter' 3 + pin_provider=$(jq -r '.provider // .vendor // empty' "$pin") + pin_effort=$(jq -er '.effort // empty' "$pin") || fail 'pinned selection is missing effort' 3 + [ "$pin_adapter" = "$adapter" ] && [ "$pin_effort" = "$effort" ] || fail 'pinned selection does not match the current adapter or policy effort; explicit fallback or handoff is required' 3 +fi +unknown_usage_allowed=false +if [ "$allow_unknown" = true ] && { [ -n "$provider" ] || [ -n "$pin_provider" ]; }; then unknown_usage_allowed=true; fi + +selected=$(jq -c \ + --arg effort "$effort" --arg pref "$preference" --arg vendor "$vendor" \ + --argjson caps "$request_caps" --argjson required "$required_units" \ + --argjson freshness "$freshness" --argjson now "$now" --arg provider "$provider" \ + --argjson allow_unknown "$allow_json" --argjson unknown_usage_allowed "$unknown_usage_allowed" --arg pin_id "$pin_id" --arg pin_provider "$pin_provider" ' + [.models[]? | + (.preflight // {}) as $p | ($p.access // {}) as $a | ($p.entitlement // {}) as $e | ($p.usage // {}) as $u | + ($u.scopes // []) as $scopes | (try (($u.observed_at // "") | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601) catch -1) as $observed | + ($u.state == "known" and ($scopes|length)>0 and ($observed >= 0) and ($now - $observed >= 0) and ($now - $observed <= $freshness) and ([ $scopes[] | ((.remaining_units // -1)-(.reserved_units // -1)) >= $required ] | all)) as $usage_known | + (.provider // .vendor // $vendor) as $model_provider | + select((.id|type)=="string" and (.id|length)>0) | + select((has("available")|not) or .available == true) | + select((has("quota_available")|not) or .quota_available == true) | + select(($a.state // "") | IN("verified","authenticated","available")) | + select(($a.account_ref // "") | length > 0) | + select(($e.state // "") | IN("active","continuing")) | + select(((($e.billing_route // "") | length) > 0) and (($e.billing_route // "") != "paid-fallback") and (($e.billing_route // "") != "unknown")) | + select((.supported_efforts // []) | index($effort)) | + select([ $caps[] as $cap | select(((.capabilities // [])|index($cap)) == null) ] | length == 0) | + select($usage_known or ($unknown_usage_allowed and ($u.state // "") != "exhausted")) | + select(($provider|length)==0 or $model_provider==$provider or (.adapter // "")==$provider or (.vendor // "")==$provider) | + select(($pin_id|length)==0 or (.id==$pin_id and $model_provider==$pin_provider)) | + {model:.,id:.id,provider:$model_provider,score:((.scores // {})[$pref] // 1000000),remaining:(if $usage_known then ([ $scopes[] | (.remaining_units-.reserved_units) ] | min) else -1 end),usage_known:$usage_known} + ] | sort_by(.score, (0-.remaining), .provider, .id) | .[0] // empty' "$catalog") || true +[ -n "$selected" ] || { [ -z "$pin" ] || fail 'pinned model is unavailable or no longer eligible; explicit fallback or handoff is required' 3; [ -z "$provider" ] || fail "explicit provider '$provider' is not eligible; no silent fallback is permitted" 3; fail 'no eligible worker: verified access, active entitlement, required capability, and capacity for assignment + verification + one retry are required' 4; } + +if [ -n "$pin" ]; then + reason="pinned selection adapter=$adapter provider=$pin_provider model_id=$pin_id; preflight revalidated" +else + if [ -n "$provider" ]; then + reason="explicit provider '$provider' selected after eligibility checks; no fallback" + else + reason="selected by preference=$preference, capability match, and remaining capacity; estimate units=$required_units (assignment=$assignment_units, verification=$verification_units, retry=$retry_units)" + fi +fi + +selection=$(jq -n --argjson s "$selected" --arg adapter "$adapter" --arg adapter_revision "$adapter_revision" --arg vendor "$vendor" --arg preference "$preference" --arg effort "$effort" --arg catalog_revision "$catalog_revision" --arg policy_revision "$policy_revision" --arg reason "$reason" --argjson caps "$request_caps" --arg route "$(jq -r '.route // "default"' "$request")" --argjson estimate_version "$estimate_version" --argjson assignment_units "$assignment_units" --argjson verification_units "$verification_units" --argjson retry_units "$retry_units" --argjson required_units "$required_units" --argjson freshness "$freshness" '{protocol_version:2,adapter:$adapter,adapter_revision:$adapter_revision,vendor:$vendor,provider:$s.provider,model_id:$s.id,model:$s.id,family_hint:($s.model.family_hint // ""),preference:$preference,effort:$effort,catalog_revision:$catalog_revision,policy_revision:$policy_revision,required_capabilities:$caps,selection_reason:$reason,route:$route,eligibility:"eligible",eligibility_reason:"verified access, active entitlement, compatible capabilities, and sufficient capacity",preflight:$s.model.preflight,capacity_estimate:{version:$estimate_version,assignment_units:$assignment_units,verification_units:$verification_units,retry_units:$retry_units,required_units:$required_units,freshness_seconds:$freshness},usage_observed_at:($s.model.preflight.usage.observed_at // ""),usage_uncertain:($s.usage_known|not),reservation:{required_units:$required_units,scopes:[$s.model.preflight.usage.scopes[]?.scope_id]}}') +printf '%s' "$selection" >"$output" +printf '%s' "$selection" diff --git a/tests/test_agy_helpers.sh b/tests/test_agy_helpers.sh index 2bb720d..37b9dcd 100755 --- a/tests/test_agy_helpers.sh +++ b/tests/test_agy_helpers.sh @@ -32,8 +32,11 @@ FAKE_AGY chmod +x "$fake_bin/agy" cat > "$TMP_ROOT/catalog.json" <<'CATALOG' -{"protocol_version":1,"adapter":"fake","adapter_revision":"test-adapter-1","vendor":"test-vendor","catalog_revision":"test-catalog-1","models":[{"id":"test-model","family_hint":"test-family","available":true,"quota_available":true,"supported_efforts":["low","medium","high"],"capabilities":[],"scores":{"fast":1,"balanced":1,"deep":1}}]} +{"protocol_version":2,"adapter":"fake","adapter_revision":"test-adapter-2","vendor":"test-vendor","catalog_revision":"test-catalog-1","models":[{"id":"test-model","family_hint":"test-family","available":true,"quota_available":true,"supported_efforts":["low","medium","high"],"capabilities":[],"scores":{"fast":1,"balanced":1,"deep":1}}]} CATALOG +observed_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) +jq --arg observed_at "$observed_at" '.models |= map(. + {preflight:{access:{state:"verified",account_ref:"test-account"},entitlement:{state:"active",billing_route:"test-subscription"},usage:{state:"known",source:"test",observed_at:$observed_at,scopes:[{scope_id:"test-window",remaining_units:20,reserved_units:0}]}}})' "$TMP_ROOT/catalog.json" >"$TMP_ROOT/catalog.json.tmp" +mv "$TMP_ROOT/catalog.json.tmp" "$TMP_ROOT/catalog.json" export OFFLOAD_ADAPTER_BIN="$ROOT/tests/fixtures/fake-worker-adapter.sh" export FAKE_ADAPTER_CATALOG="$TMP_ROOT/catalog.json" export AGY_BIN="$fake_bin/agy" diff --git a/tests/test_capacity_ledger.ps1 b/tests/test_capacity_ledger.ps1 new file mode 100644 index 0000000..81260bd --- /dev/null +++ b/tests/test_capacity_ledger.ps1 @@ -0,0 +1,60 @@ +$ErrorActionPreference = 'Stop' + +$root = Split-Path -Parent $PSScriptRoot +$temp = Join-Path ([IO.Path]::GetTempPath()) ("offload-capacity-" + [Guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $temp | Out-Null + +function Assert-True([bool]$condition, [string]$message) { + if (-not $condition) { throw "FAIL: $message" } + Write-Output "ok - $message" +} + +function Invoke-Ledger([string]$command, [string[]]$arguments) { + $script = Join-Path $root 'scripts/capacity-ledger.ps1' + $output = & pwsh -NoProfile -File $script $command @arguments 2>&1 + if ($LASTEXITCODE -ne 0) { throw "ledger $command failed: $($output -join "`n")" } + return ($output -join "`n") | ConvertFrom-Json -Depth 30 +} + +try { + $ledger = Join-Path $temp 'capacity.json' + $selection = Join-Path $temp 'selection.json' + $selectionValue = [ordered]@{ + protocol_version = 2 + adapter = 'test-adapter' + adapter_revision = 'test-2' + vendor = 'test-provider' + provider = 'test-provider' + model_id = 'test-model' + policy_revision = 'test-policy' + catalog_revision = 'test-catalog' + usage_observed_at = [DateTime]::UtcNow.ToString('o') + usage_uncertain = $false + preflight = [ordered]@{ usage = [ordered]@{ scopes = @([ordered]@{ scope_id = 'shared-window'; remaining_units = 4; reserved_units = 0 }) } } + capacity_estimate = [ordered]@{ required_units = 3 } + reservation = [ordered]@{ required_units = 3; scopes = @('shared-window') } + } + $selectionValue | ConvertTo-Json -Depth 30 | Set-Content -LiteralPath $selection -Encoding utf8 + + Invoke-Ledger 'init' @('--ledger', $ledger) | Out-Null + $first = Invoke-Ledger 'reserve' @('--ledger', $ledger, '--selection', $selection, '--reservation-id', 'first') + Assert-True ($first.state -eq 'active') 'reservation starts active' + Assert-True ($first.evidence.usage_uncertain -eq $false) 'reservation records usage certainty' + + $secondError = & pwsh -NoProfile -File (Join-Path $root 'scripts/capacity-ledger.ps1') reserve --ledger $ledger --selection $selection --reservation-id second 2>&1 + Assert-True ($LASTEXITCODE -eq 4) 'competing reservation is rejected atomically' + + $completed = Invoke-Ledger 'reconcile' @('--ledger', $ledger, '--reservation-id', 'first', '--state', 'completed', '--reason', 'worker completed') + Assert-True ($completed.state -eq 'completed') 'completed reservation releases capacity' + + $second = Invoke-Ledger 'reserve' @('--ledger', $ledger, '--selection', $selection, '--reservation-id', 'second') + Assert-True ($second.state -eq 'active') 'released capacity can be reserved again' + $recovered = Invoke-Ledger 'reconcile' @('--ledger', $ledger, '--reservation-id', 'second', '--state', 'recovered', '--reason', 'launcher recovery') + Assert-True ($recovered.state -eq 'recovered') 'recovery is a terminal reservation state' + + $raw = Get-Content -LiteralPath $ledger -Raw + Assert-True ($raw -notmatch 'secret|token|password|api[_-]?key') 'ledger contains no credential-shaped fields' + Write-Output 'capacity ledger checks passed' +} finally { + Remove-Item -LiteralPath $temp -Recurse -Force -ErrorAction SilentlyContinue +} diff --git a/tests/test_claude_adapter.ps1 b/tests/test_claude_adapter.ps1 index 702be8b..10c96cf 100644 --- a/tests/test_claude_adapter.ps1 +++ b/tests/test_claude_adapter.ps1 @@ -122,7 +122,7 @@ $catalog = Join-Path $tempRoot 'catalog.json' $catalogRequest = Join-Path $tempRoot 'catalog-request.json' @{ - protocol_version = 1 + protocol_version = 2 role = 'worker' preference = 'balanced' effort = 'high' @@ -147,7 +147,7 @@ function Invoke-Adapter { $outputPath = Join-Path $Artifacts "$Mode-result.json" $errorPath = Join-Path $Artifacts "$Mode-error.txt" @{ - protocol_version = 1 + protocol_version = 2 model_id = 'claude-3-5-sonnet-20241022' effort = 'high' preference = 'balanced' @@ -186,7 +186,8 @@ try { $capDoc = $cap.Stdout | ConvertFrom-Json Assert-Equal $capDoc.vendor 'anthropic' 'catalog identifies anthropic' Assert-Equal $capDoc.adapter 'claude' 'catalog identifies claude adapter' - Assert-Equal $capDoc.protocol_version 1 'catalog specifies protocol_version 1' + Assert-Equal $capDoc.protocol_version 2 'catalog specifies protocol_version 2' + Assert-Equal $capDoc.models[0].preflight.access.state 'unknown' 'catalog does not infer authenticated access' Assert-True ($capDoc.models.Count -ge 1) 'catalog includes models' # 2. Successful launch test with space preservation diff --git a/tests/test_claude_adapter.sh b/tests/test_claude_adapter.sh index fb2098f..d048db2 100755 --- a/tests/test_claude_adapter.sh +++ b/tests/test_claude_adapter.sh @@ -57,7 +57,7 @@ CATALOG catalog_request="$TMP_ROOT/catalog-request.json" cat >"$catalog_request" <<'CATREQ' { - "protocol_version": 1, + "protocol_version": 2, "role": "worker", "preference": "balanced", "effort": "high", @@ -70,14 +70,14 @@ CATREQ catalog_output=$(CLAUDE_BIN="$fake_claude" CLAUDE_MODEL_CATALOG="$catalog" "$ADAPTER" --operation catalog --request "$catalog_request") [ "$(printf '%s' "$catalog_output" | jq -r '.vendor')" = anthropic ] || fail 'catalog vendor is not anthropic' [ "$(printf '%s' "$catalog_output" | jq -r '.adapter')" = claude ] || fail 'catalog adapter is not claude' -[ "$(printf '%s' "$catalog_output" | jq -r '.protocol_version')" = "1" ] || fail 'catalog protocol_version is not 1' +[ "$(printf '%s' "$catalog_output" | jq -r '.protocol_version')" = "2" ] || fail 'catalog protocol_version is not 2' [ "$(printf '%s' "$catalog_output" | jq -r '.models | length')" -ge 1 ] || fail 'catalog has no models' pass 'Bash adapter catalog discovery succeeds' run_adapter() { local mode="$1" workspace="$2" cancel_file="${3:-}" prompt="${4:-bounded fake assignment}" record_args="${5:-}" local selection="$TMP_ROOT/$mode-selection.json" output="$TMP_ROOT/$mode-result.json" error="$TMP_ROOT/$mode-error.txt" - jq -n '{protocol_version:1,model_id:"claude-3-5-sonnet-20241022",effort:"high",preference:"balanced",vendor:"anthropic"}' >"$selection" + jq -n '{protocol_version:2,model_id:"claude-3-5-sonnet-20241022",effort:"high",preference:"balanced",vendor:"anthropic"}' >"$selection" set +e local cancel_args=() if [ -n "$cancel_file" ]; then diff --git a/tests/test_codex_adapter.ps1 b/tests/test_codex_adapter.ps1 index 92ba9cb..9803c2f 100644 --- a/tests/test_codex_adapter.ps1 +++ b/tests/test_codex_adapter.ps1 @@ -61,6 +61,11 @@ $ArgsList = @($args) if ($env:FAKE_CODEX_RECORD_ARGS) { $ArgsList | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath $env:FAKE_CODEX_RECORD_ARGS -Encoding utf8 } +$schema = $null +for ($i = 0; $i -lt $ArgsList.Count; $i++) { + if ($ArgsList[$i] -eq '--output-schema') { $schema = $ArgsList[$i + 1] } +} +if ($env:FAKE_CODEX_SCHEMA_RECORD -and $schema) { Copy-Item -LiteralPath $schema -Destination $env:FAKE_CODEX_SCHEMA_RECORD -Force } $last = $null for ($i = 0; $i -lt $ArgsList.Count; $i++) { if ($ArgsList[$i] -eq '--output-last-message') { $last = $ArgsList[$i + 1] } @@ -100,7 +105,7 @@ Write-Output '{"type":"turn.completed"}' # 1. Operation catalog test $catalogRequest = Join-Path $TmpRoot 'catalog-request.json' Write-JsonFile $catalogRequest ([ordered]@{ - protocol_version = 1 + protocol_version = 2 role = 'worker' preference = 'balanced' effort = 'high' @@ -113,7 +118,8 @@ Write-Output '{"type":"turn.completed"}' $capDoc = $cap.Stdout | ConvertFrom-Json Assert-Equal $capDoc.vendor 'codex' 'catalog report identifies Codex' Assert-Equal $capDoc.adapter 'codex' 'catalog report identifies adapter as codex' - Assert-Equal $capDoc.protocol_version 1 'catalog report specifies protocol_version 1' + Assert-Equal $capDoc.protocol_version 2 'catalog report specifies protocol_version 2' + Assert-Equal $capDoc.models[0].preflight.access.state 'unknown' 'catalog does not infer authenticated access' Assert-True ($capDoc.models.Count -ge 1) 'catalog report includes models' Assert-True ($capDoc.models[0].supported_efforts -contains 'low' -or $capDoc.models[0].supported_efforts -contains 'medium') 'catalog models include supported_efforts' @@ -123,7 +129,7 @@ Write-Output '{"type":"turn.completed"}' $selection = Join-Path $TmpRoot 'selection.json' Write-JsonFile $selection ([ordered]@{ - protocol_version = 1 + protocol_version = 2 model_id = 'fake-balanced-model' effort = 'high' preference = 'balanced' @@ -133,6 +139,7 @@ Write-Output '{"type":"turn.completed"}' $resultOutput = Join-Path $TmpRoot 'success-result.json' $errorOutput = Join-Path $TmpRoot 'success.err' $recordedArgsFile = Join-Path $TmpRoot 'recorded-args.json' + $recordedSchemaFile = Join-Path $TmpRoot 'recorded-schema.json' $testPrompt = 'Return the bounded result with spaces and "quotes".' $success = Invoke-Adapter @( @@ -143,10 +150,12 @@ Write-Output '{"type":"turn.completed"}' '--codex', $FakeCodex, '--', '--cd', $worktree, - '--prompt', $testPrompt + '--prompt', $testPrompt, + '--json-schema', '{"type":"object","required":["ok"]}' ) @{ CODEX_MODEL_CATALOG = $Catalog FAKE_CODEX_RECORD_ARGS = $recordedArgsFile + FAKE_CODEX_SCHEMA_RECORD = $recordedSchemaFile } Assert-Equal $success.ExitCode 0 'successful launch exits successfully' @@ -160,6 +169,10 @@ Write-Output '{"type":"turn.completed"}' $recordedArgs = Get-Content -LiteralPath $recordedArgsFile -Raw | ConvertFrom-Json Assert-True ($recordedArgs -contains $testPrompt) 'prompt argument boundary with spaces preserved' Assert-True ($recordedArgs -contains $worktree) 'worktree path argument boundary with spaces preserved' + $schemaArgIndex = [Array]::IndexOf([string[]]$recordedArgs, '--output-schema') + Assert-True ($schemaArgIndex -ge 0) 'inline schema is forwarded as output-schema' + $forwardedSchema = Get-Content -LiteralPath $recordedSchemaFile -Raw + Assert-Equal ($forwardedSchema.Trim()) '{"type":"object","required":["ok"]}' 'inline schema content is preserved' # 3. Malformed worker output test $malformedOutput = Join-Path $TmpRoot 'malformed-result.json' diff --git a/tests/test_dispatch_control.ps1 b/tests/test_dispatch_control.ps1 index 816dd71..f814c94 100644 --- a/tests/test_dispatch_control.ps1 +++ b/tests/test_dispatch_control.ps1 @@ -47,9 +47,32 @@ $result | ConvertTo-Json -Compress '@ | Set-Content -LiteralPath $fakeAgy -Encoding utf8 $catalog = Join-Path $tempRoot 'catalog.json' - @' -{"protocol_version":1,"adapter":"agy","adapter_revision":"agy-1","vendor":"agy","catalog_revision":"dispatch-catalog","models":[{"id":"probe-model-low","family_hint":"unknown","available":true,"quota_available":true,"supported_efforts":["low"],"capabilities":[],"scores":{"fast":1,"balanced":1,"deep":1}}]} -'@ | Set-Content -LiteralPath $catalog -Encoding utf8 + $catalogObject = [ordered]@{ + protocol_version = 2 + adapter = 'agy' + adapter_revision = 'agy-2' + vendor = 'agy' + catalog_revision = 'dispatch-catalog' + models = @([ordered]@{ + id = 'probe-model-low' + family_hint = 'unknown' + available = $true + quota_available = $true + supported_efforts = @('low') + capabilities = @() + scores = [ordered]@{ fast = 1; balanced = 1; deep = 1 } + preflight = [ordered]@{ + access = [ordered]@{ state = 'verified'; account_ref = 'test-account' } + entitlement = [ordered]@{ state = 'active'; billing_route = 'test-subscription' } + usage = [ordered]@{ state = 'known'; source = 'test'; observed_at = [DateTime]::UtcNow.ToString('o'); scopes = @([ordered]@{ scope_id = 'test-window'; remaining_units = 20; reserved_units = 0 }) } + } + }) + } + $catalogObject | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $catalog -Encoding utf8 + $previousAgyBin = $env:AGY_BIN + $previousAdapterCatalog = $env:OFFLOAD_ADAPTER_CATALOG + $env:AGY_BIN = $fakeAgy + $env:OFFLOAD_ADAPTER_CATALOG = $catalog $state = Join-Path $tempRoot 'dispatch.json' $manifest = Join-Path $tempRoot 'root-worker.manifest.json' @@ -168,7 +191,9 @@ $process.WaitForExit() $ledger = Get-Content -LiteralPath $state -Raw | ConvertFrom-Json $timeoutAssignment = @($ledger.assignments | Where-Object { $_.assignment_id -eq 'timeout-worker' })[0] Assert-True ($timeoutAssignment.lifecycle_state -eq 'failed' -and $timeoutAssignment.exit_code -eq 124) 'ledger records a timed-out assignment as failed' -} finally { + } finally { + if ($null -eq $previousAgyBin) { Remove-Item Env:AGY_BIN -ErrorAction SilentlyContinue } else { $env:AGY_BIN = $previousAgyBin } + if ($null -eq $previousAdapterCatalog) { Remove-Item Env:OFFLOAD_ADAPTER_CATALOG -ErrorAction SilentlyContinue } else { $env:OFFLOAD_ADAPTER_CATALOG = $previousAdapterCatalog } if (Test-Path -LiteralPath $manifest -PathType Leaf) { & $workspaceHelper cleanup --manifest $manifest --status success 2>$null | Out-Null } diff --git a/tests/test_model_routing.ps1 b/tests/test_model_routing.ps1 index 353c66e..495b29c 100644 --- a/tests/test_model_routing.ps1 +++ b/tests/test_model_routing.ps1 @@ -21,10 +21,10 @@ $testRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("offload-routing-" + [g New-Item -ItemType Directory -Path $testRoot | Out-Null function New-Catalog([string]$path, [string]$revision, [object[]]$models) { - [ordered]@{ protocol_version = 1; adapter = 'fake'; adapter_revision = 'fake-1'; vendor = 'test-vendor'; catalog_revision = $revision; models = $models } | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $path -Encoding utf8 + [ordered]@{ protocol_version = 2; adapter = 'fake'; adapter_revision = 'fake-2'; vendor = 'test-vendor'; catalog_revision = $revision; models = $models } | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $path -Encoding utf8 } function New-Model([string]$id, [bool]$available, [string[]]$efforts, [int]$fast, [int]$balanced, [int]$deep, [string[]]$capabilities = @(), [string]$family = '') { - [ordered]@{ id = $id; family_hint = $family; available = $available; quota_available = $true; supported_efforts = $efforts; capabilities = $capabilities; scores = [ordered]@{ fast = $fast; balanced = $balanced; deep = $deep } } + [ordered]@{ id = $id; family_hint = $family; available = $available; quota_available = $true; supported_efforts = $efforts; capabilities = $capabilities; scores = [ordered]@{ fast = $fast; balanced = $balanced; deep = $deep }; preflight = [ordered]@{ access = [ordered]@{ state = 'verified'; account_ref = 'test-account' }; entitlement = [ordered]@{ state = 'active'; billing_route = 'test-subscription' }; usage = [ordered]@{ state = 'known'; source = 'test'; observed_at = [DateTime]::UtcNow.ToString('o'); scopes = @([ordered]@{ scope_id = 'test-window'; remaining_units = 20; reserved_units = 0 }) } } } } function Invoke-Launcher([string[]]$arguments, [hashtable]$environment) { $psi = [System.Diagnostics.ProcessStartInfo]::new() @@ -72,13 +72,14 @@ try { Assert-Equal $result.ExitCode 0 'catalog selection launches worker' $result.Stderr $chosen = Get-Content -Raw $selection | ConvertFrom-Json Assert-Equal $chosen.model_id 'balanced-best' 'selection is deterministic across equal scores' + Assert-Equal $chosen.protocol_version 2 'selection uses preflight-aware protocol' Assert-Equal $chosen.vendor 'test-vendor' 'selection records vendor' Assert-Equal $chosen.adapter 'fake' 'selection records adapter' Assert-Equal $chosen.family_hint '' 'family hint remains metadata' Assert-Equal $chosen.preference 'balanced' 'selection records preference' Assert-Equal $chosen.effort 'high' 'selection records separate effort' Assert-Equal $chosen.catalog_revision 'catalog-a' 'selection records catalog revision' - Assert-True ($chosen.selection_reason -match 'filtered unavailable') 'selection records filtering reason' + Assert-True ($chosen.selection_reason -match 'preference=balanced') 'selection records ranking reason' $captured = Get-Content -Raw $capture | ConvertFrom-Json Assert-Equal $captured.selection.model_id 'balanced-best' 'adapter receives exact selected model' Assert-Equal $captured.selection.required_capabilities.Count 0 'adapter receives capability constraints' diff --git a/tests/test_model_routing.sh b/tests/test_model_routing.sh index 8c914f8..becd957 100755 --- a/tests/test_model_routing.sh +++ b/tests/test_model_routing.sh @@ -25,7 +25,7 @@ selection="$TMP_ROOT/selection.json" capture="$TMP_ROOT/capture.json" cat >"$catalog_one" <<'JSON' { - "protocol_version": 1, "adapter": "fake", "adapter_revision": "fake-1", + "protocol_version": 2, "adapter": "fake", "adapter_revision": "fake-2", "vendor": "vendor-a", "catalog_revision": "catalog-1", "models": [ {"id":"unavailable","family_hint":"fast","available":false,"supported_efforts":["low"],"capabilities":[],"scores":{"fast":0}}, @@ -37,7 +37,7 @@ cat >"$catalog_one" <<'JSON' JSON cat >"$catalog_three" <<'JSON' { - "protocol_version": 1, "adapter": "fake", "adapter_revision": "fake-1", + "protocol_version": 2, "adapter": "fake", "adapter_revision": "fake-2", "vendor": "vendor-a", "catalog_revision": "catalog-3", "models": [ {"id":"model-without-scores","family_hint":"unknown","available":true,"quota_available":true,"supported_efforts":["high"],"capabilities":[]} @@ -46,7 +46,7 @@ cat >"$catalog_three" <<'JSON' JSON cat >"$catalog_two" <<'JSON' { - "protocol_version": 1, "adapter": "fake", "adapter_revision": "fake-1", + "protocol_version": 2, "adapter": "fake", "adapter_revision": "fake-2", "vendor": "vendor-a", "catalog_revision": "catalog-2", "models": [ {"id":"new-top-model","family_hint":"new-family","available":true,"quota_available":true,"supported_efforts":["high"],"capabilities":[],"scores":{"balanced":0}}, @@ -55,6 +55,12 @@ cat >"$catalog_two" <<'JSON' } JSON +preflight=$(jq -n --arg observed "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{access:{state:"verified",account_ref:"test-account"},entitlement:{state:"active",billing_route:"test-subscription"},usage:{state:"known",source:"test",observed_at:$observed,scopes:[{scope_id:"test-window",remaining_units:20,reserved_units:0}]}}') +for catalog_file in "$catalog_one" "$catalog_two" "$catalog_three"; do + jq --argjson preflight "$preflight" '.protocol_version=2 | .adapter_revision="fake-2" | .models |= map(. + {preflight:$preflight})' "$catalog_file" >"$catalog_file.tmp" + mv "$catalog_file.tmp" "$catalog_file" +done + run_launcher() { local catalog="$1"; shift local out="$TMP_ROOT/output.json" err="$TMP_ROOT/error.log" diff --git a/tests/test_research_helpers.ps1 b/tests/test_research_helpers.ps1 index 1978bc9..a3ef85a 100644 --- a/tests/test_research_helpers.ps1 +++ b/tests/test_research_helpers.ps1 @@ -199,17 +199,19 @@ exit 0 $fakeCatalog = Join-Path $TmpRoot 'fake-adapter-catalog.json' @' { - "protocol_version": 1, + "protocol_version": 2, "adapter": "fake", - "adapter_revision": "fake-adapter-1", + "adapter_revision": "fake-adapter-2", "vendor": "fake-vendor", "catalog_revision": "test-catalog-1", "models": [ - { "id": "scout-model", "family_hint": "fast", "available": true, "quota_available": true, "supported_efforts": ["low"], "capabilities": [], "scores": { "fast": 0 } }, - { "id": "worker-model", "family_hint": "balanced", "available": true, "quota_available": true, "supported_efforts": ["high"], "capabilities": [], "scores": { "balanced": 0, "deep": 1 } } + { "id": "scout-model", "family_hint": "fast", "available": true, "quota_available": true, "supported_efforts": ["low"], "capabilities": [], "scores": { "fast": 0 }, "preflight": { "access": { "state": "verified", "account_ref": "test-account" }, "entitlement": { "state": "active", "billing_route": "test-subscription" }, "usage": { "state": "known", "source": "test", "observed_at": "2026-09-05T00:00:00Z", "scopes": [{ "scope_id": "test-window", "remaining_units": 20, "reserved_units": 0 }] } } }, + { "id": "worker-model", "family_hint": "balanced", "available": true, "quota_available": true, "supported_efforts": ["high"], "capabilities": [], "scores": { "balanced": 0, "deep": 1 }, "preflight": { "access": { "state": "verified", "account_ref": "test-account" }, "entitlement": { "state": "active", "billing_route": "test-subscription" }, "usage": { "state": "known", "source": "test", "observed_at": "2026-09-05T00:00:00Z", "scopes": [{ "scope_id": "test-window", "remaining_units": 20, "reserved_units": 0 }] } } } ] } '@ | Set-Content -LiteralPath $fakeCatalog -Encoding utf8 + $catalogText = [System.IO.File]::ReadAllText($fakeCatalog).Replace('2026-09-05T00:00:00Z', [DateTime]::UtcNow.ToString('o')) + [System.IO.File]::WriteAllText($fakeCatalog, $catalogText, [System.Text.Encoding]::UTF8) $savedAdapterBin = $env:OFFLOAD_ADAPTER_BIN $savedAdapterCatalog = $env:FAKE_ADAPTER_CATALOG diff --git a/tests/test_research_modes.sh b/tests/test_research_modes.sh index e44270e..16629aa 100755 --- a/tests/test_research_modes.sh +++ b/tests/test_research_modes.sh @@ -428,7 +428,10 @@ FAKE_RETRY_AGY chmod +x "$retry_fake_bin/agy" retry_catalog="$TMP_ROOT/retry-catalog.json" -printf '%s\n' '{"protocol_version":1,"adapter":"fake","adapter_revision":"test-adapter-1","vendor":"test-vendor","catalog_revision":"test-catalog-1","models":[{"id":"test-model","family_hint":"test-family","available":true,"quota_available":true,"supported_efforts":["low","medium","high"],"capabilities":[],"scores":{"fast":1,"balanced":1,"deep":1}}]}' > "$retry_catalog" +printf '%s\n' '{"protocol_version":2,"adapter":"fake","adapter_revision":"test-adapter-2","vendor":"test-vendor","catalog_revision":"test-catalog-1","models":[{"id":"test-model","family_hint":"test-family","available":true,"quota_available":true,"supported_efforts":["low","medium","high"],"capabilities":[],"scores":{"fast":1,"balanced":1,"deep":1}}]}' > "$retry_catalog" +observed_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) +jq --arg observed_at "$observed_at" '.models |= map(. + {preflight:{access:{state:"verified",account_ref:"test-account"},entitlement:{state:"active",billing_route:"test-subscription"},usage:{state:"known",source:"test",observed_at:$observed_at,scopes:[{scope_id:"test-window",remaining_units:20,reserved_units:0}]}}})' "$retry_catalog" >"$retry_catalog.tmp" +mv "$retry_catalog.tmp" "$retry_catalog" export OFFLOAD_ADAPTER_BIN="$ROOT/tests/fixtures/fake-worker-adapter.sh" export FAKE_ADAPTER_CATALOG="$retry_catalog" export AGY_BIN="$retry_fake_bin/agy" diff --git a/tests/test_review_probe_contract.ps1 b/tests/test_review_probe_contract.ps1 index 27f8e54..b110d63 100644 --- a/tests/test_review_probe_contract.ps1 +++ b/tests/test_review_probe_contract.ps1 @@ -282,8 +282,37 @@ exit 0 } $pathSep = [System.IO.Path]::PathSeparator + $catalogPath = Join-Path $TmpRoot 'agy-catalog.json' + [ordered]@{ + protocol_version = 2 + adapter = 'agy' + adapter_revision = 'agy-2' + vendor = 'agy' + catalog_revision = 'probe-catalog-1' + models = @( + [ordered]@{ + id = 'test-model-high' + available = $true + quota_available = $true + supported_efforts = @('high') + capabilities = @() + scores = [ordered]@{ fast = 10; balanced = 10; deep = 10 } + preflight = [ordered]@{ + access = [ordered]@{ state = 'verified'; account_ref = 'probe-account' } + entitlement = [ordered]@{ state = 'active'; billing_route = 'probe-subscription' } + usage = [ordered]@{ + state = 'known' + source = 'probe' + observed_at = [DateTime]::UtcNow.ToString('o') + scopes = @([ordered]@{ scope_id = 'probe-window'; remaining_units = 20; reserved_units = 0 }) + } + } + } + ) + } | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $catalogPath -Encoding utf8 $testEnv = @{ 'AGY_BIN' = $fakeAgyPs + 'OFFLOAD_ADAPTER_CATALOG' = $catalogPath 'PATH' = "$fakeBin$pathSep$env:PATH" 'FAKE_AGY_INVOCATIONS_LOG' = $invocationsLog } diff --git a/tests/test_verification_hardening_docs.ps1 b/tests/test_verification_hardening_docs.ps1 index 1e798ec..b791bc4 100644 --- a/tests/test_verification_hardening_docs.ps1 +++ b/tests/test_verification_hardening_docs.ps1 @@ -316,8 +316,10 @@ exit 0 $pathSep = [System.IO.Path]::PathSeparator $catalogFile = Join-Path $TmpRoot 'probe-catalog.json' @' -{"protocol_version":1,"adapter":"agy","adapter_revision":"agy-1","vendor":"agy","catalog_revision":"probe-catalog","models":[{"id":"probe-model-high","family_hint":"unknown","available":true,"quota_available":true,"supported_efforts":["high"],"capabilities":[],"scores":{"fast":2,"balanced":1,"deep":2}}]} +{"protocol_version":2,"adapter":"agy","adapter_revision":"agy-2","vendor":"agy","catalog_revision":"probe-catalog","models":[{"id":"probe-model-high","family_hint":"unknown","available":true,"quota_available":true,"supported_efforts":["high"],"capabilities":[],"scores":{"fast":2,"balanced":1,"deep":2},"preflight":{"access":{"state":"verified","account_ref":"test-account"},"entitlement":{"state":"active","billing_route":"test-subscription"},"usage":{"state":"known","source":"test","observed_at":"2026-09-05T00:00:00Z","scopes":[{"scope_id":"test-window","remaining_units":20,"reserved_units":0}]}}}]} '@ | Set-Content -LiteralPath $catalogFile -Encoding utf8 + $catalogText = [System.IO.File]::ReadAllText($catalogFile).Replace('2026-09-05T00:00:00Z', [DateTime]::UtcNow.ToString('o')) + [System.IO.File]::WriteAllText($catalogFile, $catalogText, [System.Text.Encoding]::UTF8) $testEnv = @{ 'AGY_BIN' = $fakeAgyPs 'OFFLOAD_ADAPTER_CATALOG' = $catalogFile diff --git a/tests/test_verification_hardening_launcher.ps1 b/tests/test_verification_hardening_launcher.ps1 index 20ce4b0..d6c4244 100644 --- a/tests/test_verification_hardening_launcher.ps1 +++ b/tests/test_verification_hardening_launcher.ps1 @@ -236,17 +236,19 @@ exit 0 $fakeCatalog = Join-Path $TmpRoot 'fake-adapter-catalog.json' @' { - "protocol_version": 1, + "protocol_version": 2, "adapter": "fake", - "adapter_revision": "fake-adapter-1", + "adapter_revision": "fake-adapter-2", "vendor": "fake-vendor", "catalog_revision": "test-catalog-1", "models": [ - { "id": "scout-model", "family_hint": "fast", "available": true, "quota_available": true, "supported_efforts": ["low"], "capabilities": [], "scores": { "fast": 0 } }, - { "id": "worker-model", "family_hint": "balanced", "available": true, "quota_available": true, "supported_efforts": ["high"], "capabilities": [], "scores": { "balanced": 0, "deep": 1 } } + { "id": "scout-model", "family_hint": "fast", "available": true, "quota_available": true, "supported_efforts": ["low"], "capabilities": [], "scores": { "fast": 0 }, "preflight": { "access": { "state": "verified", "account_ref": "test-account" }, "entitlement": { "state": "active", "billing_route": "test-subscription" }, "usage": { "state": "known", "source": "test", "observed_at": "2026-09-05T00:00:00Z", "scopes": [{ "scope_id": "test-window", "remaining_units": 20, "reserved_units": 0 }] } } }, + { "id": "worker-model", "family_hint": "balanced", "available": true, "quota_available": true, "supported_efforts": ["high"], "capabilities": [], "scores": { "balanced": 0, "deep": 1 }, "preflight": { "access": { "state": "verified", "account_ref": "test-account" }, "entitlement": { "state": "active", "billing_route": "test-subscription" }, "usage": { "state": "known", "source": "test", "observed_at": "2026-09-05T00:00:00Z", "scopes": [{ "scope_id": "test-window", "remaining_units": 20, "reserved_units": 0 }] } } } ] } '@ | Set-Content -LiteralPath $fakeCatalog -Encoding utf8 + $catalogText = [System.IO.File]::ReadAllText($fakeCatalog).Replace('2026-09-05T00:00:00Z', [DateTime]::UtcNow.ToString('o')) + [System.IO.File]::WriteAllText($fakeCatalog, $catalogText, [System.Text.Encoding]::UTF8) $savedAdapterBin = $env:OFFLOAD_ADAPTER_BIN $savedAdapterCatalog = $env:FAKE_ADAPTER_CATALOG $savedAgyBin = $env:AGY_BIN diff --git a/tests/test_worker_lifecycle.ps1 b/tests/test_worker_lifecycle.ps1 index 31b1acf..731d3ba 100644 --- a/tests/test_worker_lifecycle.ps1 +++ b/tests/test_worker_lifecycle.ps1 @@ -110,9 +110,9 @@ if ($env:FAKE_AGY_SLEEP_SECONDS) { $fakeAdapter = Join-Path $rootDir 'tests/fixtures/fake-worker-adapter.ps1' $fakeCatalog = Join-Path $tmpRoot 'lifecycle-catalog.json' [ordered]@{ - protocol_version = 1 + protocol_version = 2 adapter = 'fake' - adapter_revision = 'fake-1' + adapter_revision = 'fake-2' vendor = 'test-vendor' catalog_revision = 'lifecycle-1' models = @( @@ -123,6 +123,11 @@ if ($env:FAKE_AGY_SLEEP_SECONDS) { supported_efforts = @('high') capabilities = @() scores = [ordered]@{ fast = 10; balanced = 10; deep = 10 } + preflight = [ordered]@{ + access = [ordered]@{ state = 'verified'; account_ref = 'test-account' } + entitlement = [ordered]@{ state = 'active'; billing_route = 'test-subscription' } + usage = [ordered]@{ state = 'known'; source = 'test'; observed_at = [DateTime]::UtcNow.ToString('o'); scopes = @([ordered]@{ scope_id = 'test-window'; remaining_units = 20; reserved_units = 0 }) } + } } ) } | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $fakeCatalog -Encoding utf8