From 880cfb0b570eed34f010717d1ee094f4fedb5a2b Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 16:56:48 +0800 Subject: [PATCH 01/11] Define vendor-neutral publication compatibility --- .github/workflows/ci.yml | 9 + CONTEXT.md | 15 ++ README.md | 15 ++ SKILL.md | 15 ++ ...07-cross-library-publication-boundaries.md | 37 ++++ docs/contracts/publication-compatibility.md | 143 +++++++++++++++ scripts/check-publication-compatibility.ps1 | 170 ++++++++++++++++++ scripts/check-publication-compatibility.sh | 108 +++++++++++ tests/test_publication_compatibility.ps1 | 119 ++++++++++++ tests/test_publication_compatibility.sh | 118 ++++++++++++ tests/test_workflow_static.ps1 | 19 +- 11 files changed, 767 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0007-cross-library-publication-boundaries.md create mode 100644 docs/contracts/publication-compatibility.md create mode 100644 scripts/check-publication-compatibility.ps1 create mode 100644 scripts/check-publication-compatibility.sh create mode 100644 tests/test_publication_compatibility.ps1 create mode 100644 tests/test_publication_compatibility.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 05e7e7b..396c92e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,6 +20,9 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Run publication compatibility suite + run: bash tests/test_publication_compatibility.sh + macos-bash: name: macOS Bash contract suite runs-on: macos-latest @@ -33,6 +36,9 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Run publication compatibility suite + run: bash tests/test_publication_compatibility.sh + windows-powershell: name: Windows PowerShell contract suite runs-on: windows-latest @@ -48,3 +54,6 @@ jobs: - name: Run execution scope suite run: pwsh -File tests/test_execution_scope.ps1 + + - name: Run publication compatibility suite + run: pwsh -File tests/test_publication_compatibility.ps1 diff --git a/CONTEXT.md b/CONTEXT.md index ac2a59d..c0fafe1 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -2,6 +2,21 @@ Offload delegates bounded work to `agy` processes while the calling agent remains responsible for scope, verification, and reporting. +## Publication boundary + +Published source skills remain vendor-neutral. `grill-with-docs` owns its +interview and documentation workflow and can run without offload. Offload is +an optional delegation layer, while adapters own vendor launch syntax, model +catalogs, capability probes, and output parsing. Consumers depend on stable +capabilities, model preferences, separate reasoning effort, and normalized +results, not vendor names or exact model IDs. + +Capability support does not enforce security. The orchestrator remains +responsible for isolation, ownership, cleanup, execution scope checks, and +acceptance gates. The source repository is authoritative; generated and +installed copies are release outputs. See +`docs/contracts/publication-compatibility.md` and ADR 0007. + ## Language **Orchestrator**: diff --git a/README.md b/README.md index 2436edb..dca54ae 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,21 @@ Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Co Offload's online-research workflow is adapted from Asa by Achibukz, used with permission. Do not publish a private repository URL, branch, commit, screenshots, or copied text. +## Publication boundary + +Published source skills use the vendor-neutral contract in +[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). +`grill-with-docs` owns its interview and documentation workflow and can run +without offload. Offload is an explicit optional delegation layer. Adapters own +vendor command syntax, model catalogs, capability probes, and output parsing. + +Published consumers use stable capabilities and internal model preferences, +with reasoning effort kept separate. They do not depend on vendor names, family +labels, or exact model IDs. The compatibility checker rejects unavailable +adapters and vendor-specific references. Capability support does not enforce +security. The orchestrator still owns isolation, execution scope checks, +cleanup, and acceptance gates. + ## Worker safety and containment - **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. Never rely on it alone to protect live repository files. diff --git a/SKILL.md b/SKILL.md index 76de7d3..c7862c9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -13,6 +13,21 @@ If you are `agy`, stop here. Return worker results to your orchestrator. `agy` i You never accept worker claims at face value. You verify output through mechanical checks, test execution, diff inspections, or secondary reviews. +## Publication boundary + +Published source skills use the vendor-neutral contract in +[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). +`grill-with-docs` owns its interview and documentation workflow and can run +without offload. Offload is an explicit optional delegation layer. Adapters own +vendor command syntax, model catalogs, capability probes, and output parsing. + +Published consumers use capabilities, internal model preferences, separate +reasoning effort, and normalized results. They do not depend on vendor names, +family labels, or exact model IDs. The compatibility checker rejects +unavailable adapters and vendor-specific references. Capability support does not +enforce security. The orchestrator still owns isolation, execution scope +checks, cleanup, and acceptance gates. + ## Preconditions and helper selection Select the helper family matching your current host shell: diff --git a/docs/adr/0007-cross-library-publication-boundaries.md b/docs/adr/0007-cross-library-publication-boundaries.md new file mode 100644 index 0000000..4768d99 --- /dev/null +++ b/docs/adr/0007-cross-library-publication-boundaries.md @@ -0,0 +1,37 @@ +--- +status: accepted +--- + +# Keep published skills vendor-neutral + +Decision date: 2026-09-04. + +`grill-with-docs` and `offload` have different responsibilities. The source +skill owns its interview and documentation workflow. Offload is an optional +delegation layer. Adapters contain vendor launch syntax, output parsing, model +catalog handling, and capability probes. This boundary prevents a published +source skill from importing one worker vendor's assumptions. + +Published consumers use the versioned vendor-neutral publication contract and +capability names. They do not require exact model IDs, family names, or vendor +features. The orchestrator records adapter and model metadata internally so +retries and resume can pin the same choice. That metadata does not become a +consumer dependency. + +The Bash and PowerShell helper families keep equivalent observable contracts, +with separate native implementations. The compatibility checker validates a +published skill's manifest against an adapter catalog and rejects unavailable +required adapters, incompatible versions, missing capabilities, vendor-feature +declarations, and vendor names in published Markdown. + +Capability support is descriptive. Security enforcement remains with the +orchestrator and its filesystem, ownership, cleanup, execution scope, and gate +checks. A worker or adapter cannot widen those constraints. + +The repository is the source of truth. Generated archives, installed copies, +and copied catalogs are release outputs and must not be edited directly. A +source skill release changes the workflow contract. An adapter release handles +vendor model or command changes without requiring a source skill release. + +See [`publication-compatibility.md`](../contracts/publication-compatibility.md) +for the manifest, version rules, release steps, and AGY-only migration note. diff --git a/docs/contracts/publication-compatibility.md b/docs/contracts/publication-compatibility.md new file mode 100644 index 0000000..9a93b6c --- /dev/null +++ b/docs/contracts/publication-compatibility.md @@ -0,0 +1,143 @@ +# Publication compatibility contract + +This contract keeps a published source skill independent from worker vendors. +It applies to `grill-with-docs` and to any other skill that may use offload. + +## Ownership boundary + +`grill-with-docs` owns the interview workflow and the documentation workflow. It +must run with no offload, AGY, Codex, Claude, or vendor-model installation. Its +published instructions may describe an optional offload integration, but they +must not require that integration to run the interview. + +`offload` owns optional worker delegation, the orchestrator lifecycle, artifact +verification, and the execution scope check. An adapter owns one vendor's +launch syntax, output parsing, model catalog, capability probe, cancellation, +and resource identity details. The adapter receives the assignment's static +constraints. It cannot widen tool permissions, path scope, worktree scope, or +cleanup obligations. + +Capability support is not security enforcement. An adapter can report that a +worker supports structured output or cancellation. The orchestrator still +enforces filesystem isolation, frozen paths, execution scope checks, cleanup +ownership, and acceptance gates. A vendor's permission feature is never a +substitute for those checks. + +## Stable consumer contract + +Published skills depend on these stable concepts: + +- `orchestrator`, `worker`, and `adapter` roles. +- Assignment requirements and static security constraints. +- Internal model preferences: `fast`, `balanced`, and `deep`. +- Reasoning effort as a separate setting. +- Adapter-reported capabilities and a normalized result. +- Artifact, process, worktree, and resource ownership records. + +They must not depend on a vendor name, a vendor family label, an exact model +ID, or a vendor-specific feature. Exact model IDs and family hints may appear +in adapter-owned runtime records. They are metadata, not a cross-library +contract or a quality guarantee. + +## Manifest and catalog versions + +A published skill carries `publication.json` beside `SKILL.md`: + +```json +{ + "schema_version": 1, + "publication_contract_version": 1, + "skill": "grill-with-docs", + "contract": "vendor-neutral", + "imports": [], + "optional_adapters": [ + { "name": "offload", "min_version": "1.0.0" } + ], + "required_capabilities": [], + "vendor_features": [] +} +``` + +`imports` are required adapters. The compatibility check fails when an import +is absent or older than `min_version`. `optional_adapters` may be absent. A +missing optional adapter produces a warning and does not stop the source skill +from running. `required_capabilities` names a capability supplied by a named +adapter. `vendor_features` must stay empty in a published source skill. + +An adapter catalog records the available adapter contract and its capabilities: + +```json +{ + "schema_version": 1, + "adapter_contract_version": 1, + "adapters": [ + { + "name": "offload", + "version": "1.2.0", + "capabilities": ["worker-delegation", "structured-results"], + "vendor_features": ["adapter-owned-feature"] + } + ] +} +``` + +The contract version changes for incompatible manifest, adapter, helper-family, +or normalized-result changes. A minor version adds optional fields or +capabilities without changing existing meaning. A patch version fixes behavior +without changing the contract. Consumers pin the contract major and set a +minimum adapter version. Adapters may release vendor model changes within that +adapter version line. The orchestrator records the selected adapter, model +metadata, catalog revision, and every attempt for retry and resume. + +## Helper-family compatibility + +The Bash and PowerShell helper families implement equivalent observable +contracts. Each family must preserve argument order, structured-result capture, +output and error separation, ownership records, cleanup rules, and failure +classification. Their implementations may differ. + +There is no universal launcher. Select the helper family from the host shell. +Vendor command syntax stays in the adapter package. A published source skill +may link to the helper-family contract, but it must not copy a vendor command or +assume that one shell is installed. + +Run the compatibility check against a published skill and the adapter catalog: + +```bash +scripts/check-publication-compatibility.sh \ + --skill-root /path/to/published-skill \ + --catalog /path/to/adapter-catalog.json +``` + +```powershell +& scripts/check-publication-compatibility.ps1 ` + --skill-root C:\path\to\published-skill ` + --catalog C:\path\to\adapter-catalog.json +``` + +The check fails for a missing required adapter, an incompatible version, a +missing capability, a vendor feature declaration, or a vendor-specific name in +published Markdown. CI runs both helper-family checks. The check does not prove +that a worker is safe. Runtime verification remains the orchestrator's job. + +## Release and migration guidance + +The source repository is the source of truth. Edit the source skill, +`publication.json`, adapter contract, and helper-family documents there. Do not +edit generated release archives, installed skill copies, or copied adapter +catalogs directly. Regenerate or reinstall them, then run the compatibility +checks and the full contract suite before publishing. + +Release an adapter when its vendor command syntax, model catalog, or capability +probe changes. Release the source skill only when its interview or +documentation workflow changes. A vendor model release therefore updates one +adapter and its catalog record. It does not require a pull request to every +consumer skill. + +Existing AGY-only consumers migrate by removing vendor model IDs and command +examples from their source skill, adding `publication.json`, and declaring the +offload adapter as optional unless delegation is required for the workflow. +Replace vendor-specific settings with a model preference, separate effort, +required capabilities, and the normalized result fields. Keep the old AGY +adapter installed during the migration, run the compatibility checker, and +move any vendor-specific routing or security text into the adapter package. diff --git a/scripts/check-publication-compatibility.ps1 b/scripts/check-publication-compatibility.ps1 new file mode 100644 index 0000000..c5932e1 --- /dev/null +++ b/scripts/check-publication-compatibility.ps1 @@ -0,0 +1,170 @@ +#!/usr/bin/env pwsh +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Stop-Check([string]$message) { + [Console]::Error.WriteLine("compatibility error: $message") + exit 1 +} + +function Get-RequiredProperty($object, [string]$name, [string]$location) { + $property = $object.PSObject.Properties[$name] + if ($null -eq $property -or $null -eq $property.Value) { + Stop-Check "$location is missing '$name'" + } + return $property.Value +} + +function Get-Items($object, [string]$name) { + $property = $object.PSObject.Properties[$name] + if ($null -eq $property -or $null -eq $property.Value) { return @() } + return @($property.Value) +} + +function Compare-Version([string]$left, [string]$right) { + $leftMatch = [regex]::Match($left, '^(?\d+)\.(?\d+)\.(?\d+)$') + $rightMatch = [regex]::Match($right, '^(?\d+)\.(?\d+)\.(?\d+)$') + if (-not $leftMatch.Success -or -not $rightMatch.Success) { + Stop-Check "versions must use MAJOR.MINOR.PATCH, got '$left' and '$right'" + } + + foreach ($part in @('major', 'minor', 'patch')) { + $leftNumber = [int]$leftMatch.Groups[$part].Value + $rightNumber = [int]$rightMatch.Groups[$part].Value + if ($leftNumber -lt $rightNumber) { return -1 } + if ($leftNumber -gt $rightNumber) { return 1 } + } + return 0 +} + +$SkillRoot = '' +$Catalog = '' +$i = 0 +while ($i -lt $args.Count) { + $arg = [string]$args[$i] + if ($arg -eq '--skill-root' -or $arg -eq '-skill-root') { + if ($i + 1 -ge $args.Count) { Stop-Check '--skill-root requires a value' } + $SkillRoot = [string]$args[$i + 1] + $i += 2 + continue + } + if ($arg -eq '--catalog' -or $arg -eq '-catalog') { + if ($i + 1 -ge $args.Count) { Stop-Check '--catalog requires a value' } + $Catalog = [string]$args[$i + 1] + $i += 2 + continue + } + Stop-Check "unknown argument '$arg'" +} +if ([string]::IsNullOrWhiteSpace($SkillRoot) -or [string]::IsNullOrWhiteSpace($Catalog)) { + Stop-Check 'usage: check-publication-compatibility.ps1 --skill-root DIR --catalog FILE' +} + +if (-not (Test-Path -LiteralPath $SkillRoot -PathType Container)) { + Stop-Check "skill root does not exist: $SkillRoot" +} +if (-not (Test-Path -LiteralPath $Catalog -PathType Leaf)) { + Stop-Check "adapter catalog does not exist: $Catalog" +} + +$manifestPath = Join-Path $SkillRoot 'publication.json' +if (-not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) { + Stop-Check 'published skill is missing publication.json' +} +if (-not (Test-Path -LiteralPath (Join-Path $SkillRoot 'SKILL.md') -PathType Leaf)) { + Stop-Check 'published skill is missing SKILL.md' +} + +try { + $manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json + $catalogData = Get-Content -LiteralPath $Catalog -Raw | ConvertFrom-Json +} catch { + Stop-Check "invalid JSON: $($_.Exception.Message)" +} + +if ((Get-RequiredProperty $manifest 'schema_version' 'publication.json') -ne 1) { + Stop-Check 'publication.json schema_version must be 1' +} +if ((Get-RequiredProperty $manifest 'publication_contract_version' 'publication.json') -ne 1) { + Stop-Check 'publication contract version 1 is required' +} +if ((Get-RequiredProperty $manifest 'contract' 'publication.json') -ne 'vendor-neutral') { + Stop-Check 'published skills must use the vendor-neutral contract' +} +if ((Get-RequiredProperty $catalogData 'schema_version' 'adapter catalog') -ne 1) { + Stop-Check 'adapter catalog schema_version must be 1' +} +if ((Get-RequiredProperty $catalogData 'adapter_contract_version' 'adapter catalog') -ne 1) { + Stop-Check 'adapter contract version 1 is required' +} + +$adapters = @{} +foreach ($adapter in (Get-Items $catalogData 'adapters')) { + $name = [string](Get-RequiredProperty $adapter 'name' 'adapter catalog entry') + if ($adapters.ContainsKey($name)) { Stop-Check "adapter catalog repeats '$name'" } + $adapters[$name] = $adapter +} + +$requiredImports = @(Get-Items $manifest 'imports') +$optionalImports = @(Get-Items $manifest 'optional_adapters') +$importNames = @{} + +foreach ($import in $requiredImports) { + $name = [string](Get-RequiredProperty $import 'name' 'publication import') + if ($importNames.ContainsKey($name)) { Stop-Check "publication imports repeat '$name'" } + $importNames[$name] = $true + if (-not $adapters.ContainsKey($name)) { + Stop-Check "required adapter '$name' is unavailable" + } + $adapter = $adapters[$name] + $minimum = [string](Get-RequiredProperty $import 'min_version' "publication import '$name'") + $available = [string](Get-RequiredProperty $adapter 'version' "adapter '$name'") + if ((Compare-Version $available $minimum) -lt 0) { + Stop-Check "adapter '$name' version '$available' does not satisfy minimum '$minimum'" + } +} + +foreach ($import in $optionalImports) { + $name = [string](Get-RequiredProperty $import 'name' 'optional adapter') + if ($importNames.ContainsKey($name)) { Stop-Check "adapter '$name' is both required and optional" } + $importNames[$name] = $true + if (-not $adapters.ContainsKey($name)) { + Write-Output "warning: optional adapter '$name' is unavailable" + continue + } + $adapter = $adapters[$name] + $minimum = [string](Get-RequiredProperty $import 'min_version' "optional adapter '$name'") + $available = [string](Get-RequiredProperty $adapter 'version' "adapter '$name'") + if ((Compare-Version $available $minimum) -lt 0) { + Stop-Check "optional adapter '$name' version '$available' does not satisfy minimum '$minimum'" + } +} + +foreach ($requirement in (Get-Items $manifest 'required_capabilities')) { + $adapterName = [string](Get-RequiredProperty $requirement 'adapter' 'capability requirement') + $capability = [string](Get-RequiredProperty $requirement 'name' 'capability requirement') + if (-not $adapters.ContainsKey($adapterName)) { + Stop-Check "capability '$capability' requires unavailable adapter '$adapterName'" + } + $availableCapabilities = @((Get-Items $adapters[$adapterName] 'capabilities') | ForEach-Object { [string]$_ }) + if ($availableCapabilities -notcontains $capability) { + Stop-Check "adapter '$adapterName' does not provide capability '$capability'" + } +} + +$vendorFeatures = @(Get-Items $manifest 'vendor_features') +if ($vendorFeatures.Count -gt 0) { + Stop-Check "vendor-specific feature declarations are not allowed in a published skill: $($vendorFeatures -join ', ')" +} + +$vendorPattern = '(?i)(?&2 + exit 2 +} + +fail() { + printf 'compatibility error: %s\n' "$1" >&2 + exit 1 +} + +skill_root='' +catalog='' +while [ "$#" -gt 0 ]; do + case "$1" in + --skill-root) [ "$#" -ge 2 ] || usage; skill_root=$2; shift 2 ;; + --catalog) [ "$#" -ge 2 ] || usage; catalog=$2; shift 2 ;; + *) usage ;; + esac +done + +[ -n "$skill_root" ] || usage +[ -n "$catalog" ] || usage +[ -d "$skill_root" ] || fail "skill root does not exist: $skill_root" +[ -f "$catalog" ] || fail "adapter catalog does not exist: $catalog" +[ -f "$skill_root/publication.json" ] || fail 'published skill is missing publication.json' +[ -f "$skill_root/SKILL.md" ] || fail 'published skill is missing SKILL.md' + +command -v jq >/dev/null 2>&1 || fail 'jq is required' +jq empty "$skill_root/publication.json" >/dev/null 2>&1 || fail 'invalid publication JSON' +jq empty "$catalog" >/dev/null 2>&1 || fail 'invalid adapter catalog JSON' + +manifest="$skill_root/publication.json" +[ "$(jq -r '.schema_version // empty' "$manifest")" = '1' ] || fail 'publication.json schema_version must be 1' +[ "$(jq -r '.publication_contract_version // empty' "$manifest")" = '1' ] || fail 'publication contract version 1 is required' +[ "$(jq -r '.contract // empty' "$manifest")" = 'vendor-neutral' ] || fail 'published skills must use the vendor-neutral contract' +[ "$(jq -r '.schema_version // empty' "$catalog")" = '1' ] || fail 'adapter catalog schema_version must be 1' +[ "$(jq -r '.adapter_contract_version // empty' "$catalog")" = '1' ] || fail 'adapter contract version 1 is required' + +version_at_least() { + local available=$1 minimum=$2 + local available_major available_minor available_patch + local minimum_major minimum_minor minimum_patch + IFS=. read -r available_major available_minor available_patch <<< "$available" + IFS=. read -r minimum_major minimum_minor minimum_patch <<< "$minimum" + [[ "$available_major" =~ ^[0-9]+$ && "$available_minor" =~ ^[0-9]+$ && "$available_patch" =~ ^[0-9]+$ ]] || return 1 + [[ "$minimum_major" =~ ^[0-9]+$ && "$minimum_minor" =~ ^[0-9]+$ && "$minimum_patch" =~ ^[0-9]+$ ]] || return 1 + if [ "$available_major" -ne "$minimum_major" ]; then + [ "$available_major" -gt "$minimum_major" ] + elif [ "$available_minor" -ne "$minimum_minor" ]; then + [ "$available_minor" -gt "$minimum_minor" ] + else + [ "$available_patch" -ge "$minimum_patch" ] + fi +} + +while IFS= read -r import; do + name=$(jq -r '.name // empty' <<<"$import") + minimum=$(jq -r '.min_version // empty' <<<"$import") + [ -n "$name" ] || fail 'publication import is missing name' + [ -n "$minimum" ] || fail "publication import '$name' is missing min_version" + count=$(jq --arg name "$name" '[.adapters[] | select(.name == $name)] | length' "$catalog") + [ "$count" = '1' ] || fail "required adapter '$name' is unavailable" + available=$(jq -r --arg name "$name" '.adapters[] | select(.name == $name) | .version' "$catalog") + version_at_least "$available" "$minimum" || fail "adapter '$name' version '$available' does not satisfy minimum '$minimum'" +done < <(jq -c '.imports // [] | .[]' "$manifest") + +while IFS= read -r import; do + name=$(jq -r '.name // empty' <<<"$import") + minimum=$(jq -r '.min_version // empty' <<<"$import") + [ -n "$name" ] || fail 'optional adapter is missing name' + [ -n "$minimum" ] || fail "optional adapter '$name' is missing min_version" + count=$(jq --arg name "$name" '[.adapters[] | select(.name == $name)] | length' "$catalog") + if [ "$count" = '0' ]; then + printf "warning: optional adapter '%s' is unavailable\n" "$name" + continue + fi + [ "$count" = '1' ] || fail "adapter catalog repeats '$name'" + available=$(jq -r --arg name "$name" '.adapters[] | select(.name == $name) | .version' "$catalog") + version_at_least "$available" "$minimum" || fail "optional adapter '$name' version '$available' does not satisfy minimum '$minimum'" +done < <(jq -c '.optional_adapters // [] | .[]' "$manifest") + +while IFS= read -r requirement; do + adapter=$(jq -r '.adapter // empty' <<<"$requirement") + capability=$(jq -r '.name // empty' <<<"$requirement") + [ -n "$adapter" ] || fail 'capability requirement is missing adapter' + [ -n "$capability" ] || fail 'capability requirement is missing name' + adapter_count=$(jq --arg adapter "$adapter" '[.adapters[] | select(.name == $adapter)] | length' "$catalog") + [ "$adapter_count" = '1' ] || fail "capability '$capability' requires unavailable adapter '$adapter'" + jq -e --arg adapter "$adapter" --arg capability "$capability" \ + '.adapters[] | select(.name == $adapter) | (.capabilities // []) | index($capability) != null' \ + "$catalog" >/dev/null || fail "adapter '$adapter' does not provide capability '$capability'" +done < <(jq -c '.required_capabilities // [] | .[]' "$manifest") + +[ "$(jq '(.vendor_features // []) | length' "$manifest")" = '0' ] || \ + fail 'vendor-specific feature declarations are not allowed in a published skill' + +vendor_matches=$(mktemp "${TMPDIR:-/tmp}/offload-publication.XXXXXX") +trap 'rm -f "$vendor_matches"' EXIT +vendor_pattern='(^|[^[:alnum:]_-])(AGY|Gemini|Antigravity|Codex|Claude)($|[^[:alnum:]_-])' +if find "$skill_root" -type f -name '*.md' -exec grep -HniE "$vendor_pattern" {} + >"$vendor_matches"; then + first_match=$(head -n 1 "$vendor_matches") + fail "vendor-specific reference in published skill: $first_match" +fi + +printf '%s\n' 'publication compatibility: pass' diff --git a/tests/test_publication_compatibility.ps1 b/tests/test_publication_compatibility.ps1 new file mode 100644 index 0000000..6d85124 --- /dev/null +++ b/tests/test_publication_compatibility.ps1 @@ -0,0 +1,119 @@ +#!/usr/bin/env pwsh +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$scriptRoot = Split-Path -Parent $PSScriptRoot +$checker = Join-Path $scriptRoot 'scripts/check-publication-compatibility.ps1' +$tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("offload-publication-" + [Guid]::NewGuid().ToString('N')) + +function Write-JsonFile([string]$path, $value) { + $value | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $path -Encoding utf8NoBOM +} + +function Invoke-Checker([string]$skillRoot, [string]$catalogPath) { + $output = & pwsh -NoProfile -File $checker --skill-root $skillRoot --catalog $catalogPath 2>&1 | Out-String + [pscustomobject]@{ ExitCode = $LASTEXITCODE; Output = $output } +} + +function Assert-True([bool]$condition, [string]$message) { + if (-not $condition) { throw "FAIL: $message" } + Write-Output "ok - $message" +} + +New-Item -ItemType Directory -Path $tempRoot -Force | Out-Null +try { + $catalogPath = Join-Path $tempRoot 'catalog.json' + Write-JsonFile $catalogPath @{ + schema_version = 1 + adapter_contract_version = 1 + adapters = @( + @{ + name = 'offload' + version = '1.2.0' + capabilities = @('worker-delegation', 'structured-results') + vendor_features = @('agy-launch') + } + ) + } + + $validSkill = Join-Path $tempRoot 'valid-skill' + New-Item -ItemType Directory -Path $validSkill -Force | Out-Null + Set-Content -LiteralPath (Join-Path $validSkill 'SKILL.md') -Value '# grill-with-docs`n`nInterview and documentation workflow.' -Encoding utf8NoBOM + Write-JsonFile (Join-Path $validSkill 'publication.json') @{ + schema_version = 1 + publication_contract_version = 1 + skill = 'grill-with-docs' + contract = 'vendor-neutral' + imports = @() + optional_adapters = @(@{ name = 'offload'; min_version = '1.0.0' }) + required_capabilities = @() + vendor_features = @() + } + $result = Invoke-Checker $validSkill $catalogPath + Assert-True ($result.ExitCode -eq 0) 'vendor-neutral skill with optional adapter passes' + + $emptyCatalogPath = Join-Path $tempRoot 'empty-catalog.json' + Write-JsonFile $emptyCatalogPath @{ + schema_version = 1 + adapter_contract_version = 1 + adapters = @() + } + $result = Invoke-Checker $validSkill $emptyCatalogPath + Assert-True ($result.ExitCode -eq 0 -and $result.Output -match 'optional adapter.*unavailable') 'skill runs without optional adapter' + + $missingSkill = Join-Path $tempRoot 'missing-skill' + Copy-Item -Recurse $validSkill $missingSkill + Write-JsonFile (Join-Path $missingSkill 'publication.json') @{ + schema_version = 1 + publication_contract_version = 1 + skill = 'grill-with-docs' + contract = 'vendor-neutral' + imports = @(@{ name = 'missing-adapter'; min_version = '1.0.0' }) + optional_adapters = @() + required_capabilities = @() + vendor_features = @() + } + $result = Invoke-Checker $missingSkill $catalogPath + Assert-True ($result.ExitCode -ne 0 -and $result.Output -match 'missing-adapter.*unavailable') 'required unavailable adapter fails' + + $featureSkill = Join-Path $tempRoot 'feature-skill' + Copy-Item -Recurse $validSkill $featureSkill + Write-JsonFile (Join-Path $featureSkill 'publication.json') @{ + schema_version = 1 + publication_contract_version = 1 + skill = 'grill-with-docs' + contract = 'vendor-neutral' + imports = @() + optional_adapters = @() + required_capabilities = @() + vendor_features = @('agy-launch') + } + $result = Invoke-Checker $featureSkill $catalogPath + Assert-True ($result.ExitCode -ne 0 -and $result.Output -match 'vendor-specific feature') 'vendor-specific feature declaration fails' + + $textSkill = Join-Path $tempRoot 'text-skill' + Copy-Item -Recurse $validSkill $textSkill + Set-Content -LiteralPath (Join-Path $textSkill 'SKILL.md') -Value '# grill-with-docs`n`nRequires Gemini model routing.' -Encoding utf8NoBOM + $result = Invoke-Checker $textSkill $catalogPath + Assert-True ($result.ExitCode -ne 0 -and $result.Output -match 'vendor-specific reference') 'vendor-specific text reference fails' + + $capabilitySkill = Join-Path $tempRoot 'capability-skill' + Copy-Item -Recurse $validSkill $capabilitySkill + Write-JsonFile (Join-Path $capabilitySkill 'publication.json') @{ + schema_version = 1 + publication_contract_version = 1 + skill = 'grill-with-docs' + contract = 'vendor-neutral' + imports = @(@{ name = 'offload'; min_version = '1.0.0' }) + optional_adapters = @() + required_capabilities = @(@{ adapter = 'offload'; name = 'missing-capability' }) + vendor_features = @() + } + $result = Invoke-Checker $capabilitySkill $catalogPath + Assert-True ($result.ExitCode -ne 0 -and $result.Output -match 'capability.*missing-capability') 'missing adapter capability fails' + + Write-Output 'all publication compatibility checks passed' +} +finally { + if (Test-Path -LiteralPath $tempRoot) { Remove-Item -LiteralPath $tempRoot -Recurse -Force } +} diff --git a/tests/test_publication_compatibility.sh b/tests/test_publication_compatibility.sh new file mode 100644 index 0000000..23dcc47 --- /dev/null +++ b/tests/test_publication_compatibility.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +CHECKER="$ROOT_DIR/scripts/check-publication-compatibility.sh" +TMP_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/offload-publication.XXXXXX") +trap 'rm -rf "$TMP_ROOT"' EXIT + +fail() { + printf 'FAIL: %s\n' "$1" >&2 + exit 1 +} + +pass() { printf 'ok - %s\n' "$1"; } + +run_checker() { + set +e + CHECKER_OUTPUT=$("$CHECKER" --skill-root "$1" --catalog "$2" 2>&1) + CHECKER_EXIT=$? + set -e +} + +cat > "$TMP_ROOT/catalog.json" <<'JSON' +{ + "schema_version": 1, + "adapter_contract_version": 1, + "adapters": [ + { + "name": "offload", + "version": "1.2.0", + "capabilities": ["worker-delegation", "structured-results"], + "vendor_features": ["agy-launch"] + } + ] +} +JSON + +make_valid_skill() { + mkdir -p "$1" + printf '%s\n' '# grill-with-docs' '' 'Interview and documentation workflow.' > "$1/SKILL.md" + cat > "$1/publication.json" <<'JSON' +{ + "schema_version": 1, + "publication_contract_version": 1, + "skill": "grill-with-docs", + "contract": "vendor-neutral", + "imports": [], + "optional_adapters": [{"name": "offload", "min_version": "1.0.0"}], + "required_capabilities": [], + "vendor_features": [] +} +JSON +} + +make_valid_skill "$TMP_ROOT/valid-skill" +run_checker "$TMP_ROOT/valid-skill" "$TMP_ROOT/catalog.json" +[ "$CHECKER_EXIT" -eq 0 ] || fail 'vendor-neutral skill with optional adapter passes' +pass 'vendor-neutral skill with optional adapter passes' + +cat > "$TMP_ROOT/empty-catalog.json" <<'JSON' +{ + "schema_version": 1, + "adapter_contract_version": 1, + "adapters": [] +} +JSON +run_checker "$TMP_ROOT/valid-skill" "$TMP_ROOT/empty-catalog.json" +if [ "$CHECKER_EXIT" -eq 0 ] && [[ "$CHECKER_OUTPUT" == *'optional adapter'*'unavailable'* ]]; then + : +else + fail 'skill runs without optional adapter' +fi +pass 'skill runs without optional adapter' + +make_valid_skill "$TMP_ROOT/missing-skill" +sed -i.bak 's/"imports": \[\]/"imports": [{"name": "missing-adapter", "min_version": "1.0.0"}]/' "$TMP_ROOT/missing-skill/publication.json" +rm -f "$TMP_ROOT/missing-skill/publication.json.bak" +run_checker "$TMP_ROOT/missing-skill" "$TMP_ROOT/catalog.json" +if [ "$CHECKER_EXIT" -ne 0 ] && [[ "$CHECKER_OUTPUT" == *"missing-adapter"*"unavailable"* ]]; then + : +else + fail 'required unavailable adapter fails' +fi +pass 'required unavailable adapter fails' + +make_valid_skill "$TMP_ROOT/feature-skill" +sed -i.bak 's/"vendor_features": \[\]/"vendor_features": ["agy-launch"]/' "$TMP_ROOT/feature-skill/publication.json" +rm -f "$TMP_ROOT/feature-skill/publication.json.bak" +run_checker "$TMP_ROOT/feature-skill" "$TMP_ROOT/catalog.json" +if [ "$CHECKER_EXIT" -ne 0 ] && [[ "$CHECKER_OUTPUT" == *'vendor-specific feature'* ]]; then + : +else + fail 'vendor-specific feature declaration fails' +fi +pass 'vendor-specific feature declaration fails' + +make_valid_skill "$TMP_ROOT/text-skill" +printf '%s\n' '# grill-with-docs' '' 'Requires Gemini model routing.' > "$TMP_ROOT/text-skill/SKILL.md" +run_checker "$TMP_ROOT/text-skill" "$TMP_ROOT/catalog.json" +if [ "$CHECKER_EXIT" -ne 0 ] && [[ "$CHECKER_OUTPUT" == *'vendor-specific reference'* ]]; then + : +else + fail 'vendor-specific text reference fails' +fi +pass 'vendor-specific text reference fails' + +make_valid_skill "$TMP_ROOT/capability-skill" +sed -i.bak 's/"required_capabilities": \[\]/"required_capabilities": [{"adapter": "offload", "name": "missing-capability"}]/' "$TMP_ROOT/capability-skill/publication.json" +rm -f "$TMP_ROOT/capability-skill/publication.json.bak" +run_checker "$TMP_ROOT/capability-skill" "$TMP_ROOT/catalog.json" +if [ "$CHECKER_EXIT" -ne 0 ] && [[ "$CHECKER_OUTPUT" == *'missing-capability'* ]]; then + : +else + fail 'missing adapter capability fails' +fi +pass 'missing adapter capability fails' + +printf '%s\n' 'all publication compatibility checks passed' diff --git a/tests/test_workflow_static.ps1 b/tests/test_workflow_static.ps1 index 808960e..767c7b9 100644 --- a/tests/test_workflow_static.ps1 +++ b/tests/test_workflow_static.ps1 @@ -38,6 +38,10 @@ $WebMd = Join-Path $RootDir 'modes/web-research.md' $ReadmeMd = Join-Path $RootDir 'README.md' $AgentsMd = Join-Path $RootDir 'AGENTS.md' $PolicyJson = Join-Path $RootDir 'model-policy.json' +$PublicationMd = Join-Path $RootDir 'docs/contracts/publication-compatibility.md' +$PublicationAdr = Join-Path $RootDir 'docs/adr/0007-cross-library-publication-boundaries.md' +$PublicationPs1 = Join-Path $RootDir 'scripts/check-publication-compatibility.ps1' +$PublicationSh = Join-Path $RootDir 'scripts/check-publication-compatibility.sh' # 1. Line count check: SKILL.md must remain strictly under 500 lines $skillLines = (Get-Content -LiteralPath $SkillMd).Count @@ -192,7 +196,20 @@ foreach ($mode in @( Assert-False ($webContent -match 'synthesizer\.json') "web-research.md does not reuse synthesizer.json" Assert-False ($webContent -match 'auditor\.json') "web-research.md does not reuse auditor.json" -# 11. Routing provenance fixture and documentation alignment (Issue #13) +# 11. Published skills use the vendor-neutral publication boundary. +Assert-True (Test-Path -LiteralPath $PublicationMd -PathType Leaf) "publication contract document exists" +Assert-True (Test-Path -LiteralPath $PublicationAdr -PathType Leaf) "publication boundary ADR exists" +Assert-True (Test-Path -LiteralPath $PublicationPs1 -PathType Leaf) "PowerShell publication checker exists" +Assert-True (Test-Path -LiteralPath $PublicationSh -PathType Leaf) "Bash publication checker exists" +$publicationContent = Get-Content -LiteralPath $PublicationMd -Raw +Assert-True ($publicationContent -match 'grill-with-docs' -and $publicationContent -match 'vendor-neutral') "publication contract names the source skill and neutral contract" +Assert-True ($publicationContent -match 'optional adapter' -and $publicationContent -match 'execution scope check') "publication contract separates optional delegation and verification" +Assert-True ($publicationContent -match 'capability support' -and $publicationContent -match 'security enforcement') "publication contract separates capability support from security enforcement" +Assert-True ($publicationContent -match 'source of truth' -and $publicationContent -match 'generated|installed copies') "publication contract documents release ownership" +Assert-True ($skillContent -match 'publication boundary' -and $skillContent -match 'vendor-neutral') "SKILL.md links the publication boundary" +Assert-True ((Get-Content -LiteralPath $ReadmeMd -Raw) -match 'publication boundary') "README links the publication boundary" + +# 12. Routing provenance fixture and documentation alignment (Issue #13) $FixtureJson = Join-Path $RootDir 'tests/fixtures/routing-worker.json' Assert-True (Test-Path -LiteralPath $FixtureJson -PathType Leaf) "workflow-static: routing fixture exists" Assert-True ($skillContent -match 'tests/fixtures/routing-worker\.json') "SKILL.md links to routing fixture" From 6c4ea20fd17f5242bbe1de97ba251a5ee4f74352 Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 17:10:41 +0800 Subject: [PATCH 02/11] Standardize worker lifecycle handling --- SKILL.md | 18 +- modes/execution.md | 2 + modes/repo-research.md | 2 + modes/web-research.md | 2 + scripts/run-agy-json.ps1 | 366 +++++++++++++++++++++++++++++++- scripts/run-agy-json.sh | 313 ++++++++++++++++++++++++++- tests/test_worker_lifecycle.ps1 | 363 +++++++++++++++++++++++++++++++ 7 files changed, 1050 insertions(+), 16 deletions(-) create mode 100644 tests/test_worker_lifecycle.ps1 diff --git a/SKILL.md b/SKILL.md index 76de7d3..e166aa8 100644 --- a/SKILL.md +++ b/SKILL.md @@ -63,8 +63,8 @@ Offload routes all workers through the repository-root `model-policy.json`. Laun ### Launcher invocation -- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --output --error -- ` -- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --output --error '--' ` +- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger -- ` +- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger '--' ` In PowerShell command expressions, always quote the delimiter (`'--'`). @@ -87,6 +87,18 @@ In PowerShell command expressions, always quote the delimiter (`'--'`). ## Shared recovery, retry accounting, and failure handling +### Worker lifecycle contract + +Both native launchers write the same lifecycle artifact for every dispatched worker. The state machine is: + +`created -> started -> running -> completed|failed|canceled|quota-handoff -> retained -> cleaned` + +`started` includes the child process ID. The launcher waits for the child to exit, records its exit code, and only then records `retained` and `cleaned`. Timeout uses `failed` with `failure_class: "timeout"`; cancellation uses `canceled`; explicit quota diagnostics use `quota-handoff`. Output, error, lifecycle, and resource-ledger paths remain available as diagnosis evidence for every non-success terminal state. + +The launcher accepts `--timeout-seconds` and a testable `--cancel-file`. A timeout or cancellation terminates the worker, waits for exit, flushes both streams, and finalizes the lifecycle artifact before returning. A zero-exit worker advances to `completed` only when its output is a successful JSON envelope with `structured_output`; malformed output is recorded as `failed` with `failure_class: "malformed_output"`. + +`--resource-ledger` records the stable assignment, pinned model, effort, verification baseline, and attempt artifacts. Attempt 2 must use the same assignment and pinned model/effort as attempt 1. Attempt 3 is rejected before dispatch. Resume and retry consumers must read the ledger and select an explicit accepted attempt; they must not infer the latest artifact by wildcard. + ### Stable worker IDs and retry ceiling - A worker represents one logical assignment, not a single process run. @@ -143,7 +155,7 @@ The orchestrator maintains `routing-outcomes.json` in each run's scratch workspa - `duration_seconds`: Observed elapsed time (null while running). - `exit_code`: Worker process exit code (null while running). - `state`: `"running"`, `"completed"`, `"failed"`, or `"interrupted"`. - - `failure_class`: `"none"`, `"quality"`, `"timeout"`, `"tool_error"`, `"quota"`, `"unrunnable"`, or `"unknown"`. + - `failure_class`: `"none"`, `"quality"`, `"timeout"`, `"tool_error"`, `"malformed_output"`, `"quota"`, `"unrunnable"`, or `"unknown"`. - `verification`: `"pending"`, `"passed"`, `"failed"`, or `"not_performed"`. - `evidence_paths`: Array of output, error, gate, review, or audit artifact paths. - `usage`: Source-attributed reported usage object with explicit units, or null when unavailable. diff --git a/modes/execution.md b/modes/execution.md index e714dcf..2c7655b 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -20,6 +20,8 @@ Check these before dispatching writing tasks: 5. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching the first worker. All workers route through `model-policy.json`. 6. **Workspace isolation principle.** Writing workers are never dispatched directly into the caller's main checkout (``). All candidate mutations occur in isolated candidate worktrees created at the recorded baseline revision via `execution-workspace create`. +Every execution dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode execution`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records the common state machine, waits for the worker to exit before cleanup, and records the exit result. Timeout and cancellation terminate the worker before cleanup; quota exhaustion hands off unfinished work immediately. Retries and resume read the resource ledger and preserve the pinned assignment, model, effort, verification baseline, and attempt limit. + ## Roles and models Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. diff --git a/modes/repo-research.md b/modes/repo-research.md index 21619e0..d4655bd 100644 --- a/modes/repo-research.md +++ b/modes/repo-research.md @@ -11,6 +11,8 @@ Select the helper family matching your current host shell: Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +Every research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode repo-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records worker exit results and retains diagnosis artifacts for failed, canceled, timed-out, malformed, or quota-handoff runs. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. + ## Assignment requirements Every repository research assignment must define four fields: diff --git a/modes/web-research.md b/modes/web-research.md index 9105c01..63da8d9 100644 --- a/modes/web-research.md +++ b/modes/web-research.md @@ -13,6 +13,8 @@ Conducts cited online investigations and multi-angle technical research by dispa 5. **Filesystem isolation.** Every research run operates in a disposable workspace outside the live repository. 6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +Every web-research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode web-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher waits for worker exit before cleanup, preserves diagnosis evidence for non-successful runs, and hands off quota-exhausted work without waiting for sibling workers. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. + ## Worker isolation and mixed repositories `--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but exposed tools and commands mean this is not a guarantee. Similarly, `--add-dir` grants directory access without confining worker writes. Safety and containment rely on strict filesystem isolation: diff --git a/scripts/run-agy-json.ps1 b/scripts/run-agy-json.ps1 index 8bca72f..db1904e 100644 --- a/scripts/run-agy-json.ps1 +++ b/scripts/run-agy-json.ps1 @@ -7,7 +7,7 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version 3.0 function Show-Usage { - [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] --output FILE --error FILE '--' agy-arguments...") + [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] --output FILE --error FILE [lifecycle options] '--' agy-arguments...") [Console]::Error.WriteLine("In PowerShell command expressions, quote '--' because PowerShell consumes the bare delimiter before the helper receives it.") } @@ -20,10 +20,26 @@ $outputPath = "" $errorPath = "" $role = "" $route = "" +$lifecyclePath = "" +$assignmentId = "" +$attempt = 1 +$mode = "unknown" +$verificationBaseline = "" +$resourceLedgerPath = "" +$timeoutSeconds = 0 +$cancelFile = "" $seenOutput = $false $seenError = $false $seenRole = $false $seenRoute = $false +$seenLifecycle = $false +$seenAssignmentId = $false +$seenAttempt = $false +$seenMode = $false +$seenVerificationBaseline = $false +$seenResourceLedger = $false +$seenTimeout = $false +$seenCancelFile = $false $seenDashDash = $false $forwardedArgs = [System.Collections.Generic.List[string]]::new() @@ -122,6 +138,92 @@ while ($i -lt $args.Count) { Fail "--route requires a route name" } $seenRoute = $true + } elseif ($arg -eq '--lifecycle') { + if ($seenLifecycle) { Fail "duplicate --lifecycle option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--lifecycle requires a path" } + $lifecyclePath = [string]$args[$i] + $seenLifecycle = $true + } elseif ($arg.StartsWith('--lifecycle=')) { + if ($seenLifecycle) { Fail "duplicate --lifecycle option" } + $lifecyclePath = $arg.Substring(12) + if ([string]::IsNullOrWhiteSpace($lifecyclePath)) { Show-Usage; Fail "--lifecycle requires a path" } + $seenLifecycle = $true + } elseif ($arg -eq '--assignment-id') { + if ($seenAssignmentId) { Fail "duplicate --assignment-id option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--assignment-id requires an identifier" } + $assignmentId = [string]$args[$i] + $seenAssignmentId = $true + } elseif ($arg.StartsWith('--assignment-id=')) { + if ($seenAssignmentId) { Fail "duplicate --assignment-id option" } + $assignmentId = $arg.Substring(16) + if ([string]::IsNullOrWhiteSpace($assignmentId)) { Show-Usage; Fail "--assignment-id requires an identifier" } + $seenAssignmentId = $true + } elseif ($arg -eq '--attempt') { + if ($seenAttempt) { Fail "duplicate --attempt option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--attempt requires an integer" } + if (-not [int]::TryParse([string]$args[$i], [ref]$attempt)) { Fail "--attempt requires an integer" } + $seenAttempt = $true + } elseif ($arg.StartsWith('--attempt=')) { + if ($seenAttempt) { Fail "duplicate --attempt option" } + if (-not [int]::TryParse($arg.Substring(10), [ref]$attempt)) { Fail "--attempt requires an integer" } + $seenAttempt = $true + } elseif ($arg -eq '--mode') { + if ($seenMode) { Fail "duplicate --mode option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--mode requires a mode name" } + $mode = [string]$args[$i] + $seenMode = $true + } elseif ($arg.StartsWith('--mode=')) { + if ($seenMode) { Fail "duplicate --mode option" } + $mode = $arg.Substring(7) + if ([string]::IsNullOrWhiteSpace($mode)) { Show-Usage; Fail "--mode requires a mode name" } + $seenMode = $true + } elseif ($arg -eq '--verification-baseline') { + if ($seenVerificationBaseline) { Fail "duplicate --verification-baseline option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--verification-baseline requires a value" } + $verificationBaseline = [string]$args[$i] + $seenVerificationBaseline = $true + } elseif ($arg.StartsWith('--verification-baseline=')) { + if ($seenVerificationBaseline) { Fail "duplicate --verification-baseline option" } + $verificationBaseline = $arg.Substring(24) + if ([string]::IsNullOrWhiteSpace($verificationBaseline)) { Show-Usage; Fail "--verification-baseline requires a value" } + $seenVerificationBaseline = $true + } elseif ($arg -eq '--resource-ledger') { + if ($seenResourceLedger) { Fail "duplicate --resource-ledger option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--resource-ledger requires a path" } + $resourceLedgerPath = [string]$args[$i] + $seenResourceLedger = $true + } elseif ($arg.StartsWith('--resource-ledger=')) { + if ($seenResourceLedger) { Fail "duplicate --resource-ledger option" } + $resourceLedgerPath = $arg.Substring(18) + if ([string]::IsNullOrWhiteSpace($resourceLedgerPath)) { Show-Usage; Fail "--resource-ledger requires a path" } + $seenResourceLedger = $true + } elseif ($arg -eq '--timeout-seconds') { + if ($seenTimeout) { Fail "duplicate --timeout-seconds option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--timeout-seconds requires a positive number" } + if (-not [int]::TryParse([string]$args[$i], [ref]$timeoutSeconds)) { Fail "--timeout-seconds requires a positive number" } + $seenTimeout = $true + } elseif ($arg.StartsWith('--timeout-seconds=')) { + if ($seenTimeout) { Fail "duplicate --timeout-seconds option" } + if (-not [int]::TryParse($arg.Substring(18), [ref]$timeoutSeconds)) { Fail "--timeout-seconds requires a positive number" } + $seenTimeout = $true + } elseif ($arg -eq '--cancel-file') { + if ($seenCancelFile) { Fail "duplicate --cancel-file option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--cancel-file requires a path" } + $cancelFile = [string]$args[$i] + $seenCancelFile = $true + } elseif ($arg.StartsWith('--cancel-file=')) { + if ($seenCancelFile) { Fail "duplicate --cancel-file option" } + $cancelFile = $arg.Substring(14) + if ([string]::IsNullOrWhiteSpace($cancelFile)) { Show-Usage; Fail "--cancel-file requires a path" } + $seenCancelFile = $true } else { Show-Usage Fail "unknown launcher option: $arg" @@ -338,6 +440,19 @@ if ([string]::IsNullOrWhiteSpace($resolvedModel)) { Fail "failed to resolve model for role '$role' and route '$route'" } +if ($attempt -lt 1 -or $attempt -gt 2) { + Fail "attempt must be 1 or 2; policy allows at most one retry per assignment" +} +if ($timeoutSeconds -lt 0) { + Fail "--timeout-seconds must be zero or a positive integer" +} +if ([string]::IsNullOrWhiteSpace($assignmentId)) { + $assignmentId = "$role-$(Get-Date -Format 'yyyyMMddHHmmssfff')" +} +if ([string]::IsNullOrWhiteSpace($lifecyclePath)) { + $lifecyclePath = "$outputPath.lifecycle.json" +} + # Resolve agy executable $resolvedAgy = $null @@ -382,6 +497,8 @@ if (-not $resolvedAgy) { # Resolve paths and validate output/error destinations $resolvedOutputPath = [System.IO.Path]::GetFullPath($outputPath) $resolvedErrorPath = [System.IO.Path]::GetFullPath($errorPath) +$resolvedLifecyclePath = [System.IO.Path]::GetFullPath($lifecyclePath) +$resolvedLedgerPath = if ([string]::IsNullOrWhiteSpace($resourceLedgerPath)) { "" } else { [System.IO.Path]::GetFullPath($resourceLedgerPath) } $pathComparison = if ($IsWindows) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal } @@ -397,6 +514,149 @@ if ([System.IO.Directory]::Exists($resolvedErrorPath)) { Fail "error destination is an existing directory: $resolvedErrorPath" } +if ([System.IO.Directory]::Exists($resolvedLifecyclePath)) { + Fail "lifecycle destination is an existing directory: $resolvedLifecyclePath" +} +if ($resolvedLedgerPath -and [System.IO.Directory]::Exists($resolvedLedgerPath)) { + Fail "resource ledger destination is an existing directory: $resolvedLedgerPath" +} + +$effort = if ($resolvedModel -match '-(low|medium|high)$') { $Matches[1] } else { 'unknown' } +$script:Lifecycle = [ordered]@{ + schema_version = 1 + assignment_id = $assignmentId + attempt = $attempt + role = $role + mode = $mode + policy_revision = [string]$policy.PSObject.Properties['policy_revision'].Value + model = $resolvedModel + effort = $effort + verification_baseline = if ($verificationBaseline) { $verificationBaseline } else { $null } + resource_ledger = if ($resolvedLedgerPath) { $resolvedLedgerPath } else { $null } + state = 'created' + events = @() + exit_code = $null + termination = 'none' + failure_class = 'none' + artifacts = [ordered]@{ + output = $resolvedOutputPath + error = $resolvedErrorPath + lifecycle = $resolvedLifecyclePath + } +} + +function Save-Lifecycle { + $json = $script:Lifecycle | ConvertTo-Json -Depth 12 + [System.IO.File]::WriteAllText($resolvedLifecyclePath, $json, [System.Text.Encoding]::UTF8) +} + +function Set-LifecycleState([string]$state, [hashtable]$details = @{}) { + $event = [ordered]@{ + state = $state + at = [DateTime]::UtcNow.ToString('o') + } + foreach ($key in $details.Keys) { $event[$key] = $details[$key] } + $events = [System.Collections.Generic.List[object]]::new() + foreach ($existing in @($script:Lifecycle.events)) { $events.Add($existing) } + $events.Add([PSCustomObject]$event) + $script:Lifecycle.events = @($events) + $script:Lifecycle.state = $state + foreach ($key in $details.Keys) { + if ($script:Lifecycle.Contains($key)) { $script:Lifecycle[$key] = $details[$key] } + } + Save-Lifecycle +} + +function Test-WorkerOutput { + try { + $rawOutput = [System.IO.File]::ReadAllText($resolvedOutputPath, [System.Text.Encoding]::UTF8) + $parsedOutput = ConvertFrom-Json -InputObject $rawOutput -Depth 20 -ErrorAction Stop + $structuredOutputProperty = $parsedOutput.PSObject.Properties['structured_output'] + return ($parsedOutput -is [System.Management.Automation.PSCustomObject] -and + $parsedOutput.status -eq 'success' -and + $null -ne $structuredOutputProperty -and + $structuredOutputProperty.Value -is [System.Management.Automation.PSCustomObject]) + } catch { + return $false + } +} + +function Test-QuotaSignal { + try { + $outputText = [System.IO.File]::ReadAllText($resolvedOutputPath, [System.Text.Encoding]::UTF8) + $errorText = [System.IO.File]::ReadAllText($resolvedErrorPath, [System.Text.Encoding]::UTF8) + return (($outputText + "`n" + $errorText) -match '(?i)quota|resource[_ -]?exhausted|rate limit|\b429\b') + } catch { + return $false + } +} + +try { + $lifecycleDir = [System.IO.Path]::GetDirectoryName($resolvedLifecyclePath) + if ($lifecycleDir -and -not [System.IO.Directory]::Exists($lifecycleDir)) { + [System.IO.Directory]::CreateDirectory($lifecycleDir) | Out-Null + } + Save-Lifecycle + Set-LifecycleState 'created' +} catch { + Fail "failed to create lifecycle artifact '$resolvedLifecyclePath': $($_.Exception.Message)" 1 +} + +if ($resolvedLedgerPath) { + try { + $ledgerDir = [System.IO.Path]::GetDirectoryName($resolvedLedgerPath) + if ($ledgerDir -and -not [System.IO.Directory]::Exists($ledgerDir)) { + [System.IO.Directory]::CreateDirectory($ledgerDir) | Out-Null + } + if (Test-Path -LiteralPath $resolvedLedgerPath -PathType Leaf) { + $ledger = ConvertFrom-Json -InputObject ([System.IO.File]::ReadAllText($resolvedLedgerPath, [System.Text.Encoding]::UTF8)) -Depth 12 -ErrorAction Stop + if ($ledger.assignment_id -ne $assignmentId -or $ledger.model -ne $resolvedModel -or $ledger.effort -ne $effort) { + Fail "resource ledger is pinned to a different assignment, model, or effort" + } + $ledgerBaselineProperty = $ledger.PSObject.Properties['verification_baseline'] + if ($ledgerBaselineProperty -and $ledgerBaselineProperty.Value) { + if ($verificationBaseline -and $ledgerBaselineProperty.Value -ne $verificationBaseline) { + Fail "resource ledger is pinned to a different verification baseline" + } + if (-not $verificationBaseline) { + $verificationBaseline = [string]$ledgerBaselineProperty.Value + $script:Lifecycle.verification_baseline = $verificationBaseline + Save-Lifecycle + } + } + } else { + $ledger = [ordered]@{ + schema_version = 1 + assignment_id = $assignmentId + model = $resolvedModel + effort = $effort + verification_baseline = if ($verificationBaseline) { $verificationBaseline } else { $null } + attempts = @() + } + } + $attemptEntry = [ordered]@{ + attempt = $attempt + model = $resolvedModel + effort = $effort + verification_baseline = if ($verificationBaseline) { $verificationBaseline } else { $null } + lifecycle = $resolvedLifecyclePath + } + $ledgerAttempts = [System.Collections.Generic.List[object]]::new() + if ($ledger.PSObject.Properties['attempts']) { + foreach ($existingAttempt in @($ledger.attempts)) { $ledgerAttempts.Add($existingAttempt) } + } + if (@($ledgerAttempts | Where-Object { $_.attempt -eq $attempt }).Count -gt 0) { + Fail "resource ledger already contains attempt $attempt" + } + $ledgerAttempts.Add([PSCustomObject]$attemptEntry) + $ledger.attempts = @($ledgerAttempts) + [System.IO.File]::WriteAllText($resolvedLedgerPath, ($ledger | ConvertTo-Json -Depth 12), [System.Text.Encoding]::UTF8) + } catch { + if ($_.Exception.Message -like 'resource ledger*') { throw } + Fail "failed to read or write resource ledger '$resolvedLedgerPath': $($_.Exception.Message)" 1 + } +} + try { $outDir = [System.IO.Path]::GetDirectoryName($resolvedOutputPath) if (-not [string]::IsNullOrEmpty($outDir) -and -not [System.IO.Directory]::Exists($outDir)) { @@ -414,8 +674,9 @@ try { $outFs = $null $errFs = $null $proc = $null -$launcherSuccess = $false +$processStarted = $false $workerExitCode = 1 +$terminalStateRecorded = $false try { try { @@ -456,8 +717,13 @@ try { } catch { Fail "failed to start agy: $($_.Exception.Message)" 1 } + $processStarted = $true + Set-LifecycleState 'started' @{ pid = $proc.Id } try { + $outTask = $proc.StandardOutput.BaseStream.CopyToAsync($outFs) + $errTask = $proc.StandardError.BaseStream.CopyToAsync($errFs) + Set-LifecycleState 'running' if ($env:FAKE_LAUNCHER_FAIL_POST_START -or $env:OFFLOAD_TEST_FAIL_POST_START) { if ($env:FAKE_AGY_STARTED_MARKER) { $sw = [System.Diagnostics.Stopwatch]::StartNew() @@ -467,18 +733,91 @@ try { } throw "simulated post-start failure" } - - $outTask = $proc.StandardOutput.BaseStream.CopyToAsync($outFs) - $errTask = $proc.StandardError.BaseStream.CopyToAsync($errFs) - $proc.WaitForExit() + $deadline = if ($timeoutSeconds -gt 0) { [DateTime]::UtcNow.AddSeconds($timeoutSeconds) } else { $null } + $termination = 'natural' + while (-not $proc.HasExited) { + if ($cancelFile -and (Test-Path -LiteralPath $cancelFile -PathType Leaf)) { + $termination = 'canceled' + break + } + if ($deadline -and [DateTime]::UtcNow -ge $deadline) { + $termination = 'timeout' + break + } + [System.Threading.Thread]::Sleep(50) + } + if (-not $proc.HasExited) { + $proc.Kill($true) + $proc.WaitForExit() + } else { + $proc.WaitForExit() + } [System.Threading.Tasks.Task]::WaitAll(@($outTask, $errTask)) $workerExitCode = $proc.ExitCode - $launcherSuccess = $true + $outFs.Flush() + $errFs.Flush() + $outFs.Dispose() + $outFs = $null + $errFs.Dispose() + $errFs = $null + + $script:Lifecycle.exit_code = $workerExitCode + if ($termination -eq 'canceled') { + $script:Lifecycle.termination = 'canceled' + $script:Lifecycle.failure_class = 'canceled' + Set-LifecycleState 'canceled' + $terminalStateRecorded = $true + $workerExitCode = 130 + } elseif ($termination -eq 'timeout') { + $script:Lifecycle.termination = 'timeout' + $script:Lifecycle.failure_class = 'timeout' + Set-LifecycleState 'failed' + $terminalStateRecorded = $true + $workerExitCode = 124 + } elseif (Test-QuotaSignal) { + $script:Lifecycle.termination = 'quota-handoff' + $script:Lifecycle.failure_class = 'quota' + Set-LifecycleState 'quota-handoff' + $terminalStateRecorded = $true + $workerExitCode = 75 + } elseif ($workerExitCode -ne 0) { + $script:Lifecycle.termination = 'worker-exit' + $script:Lifecycle.failure_class = 'tool_error' + Set-LifecycleState 'failed' + $terminalStateRecorded = $true + } elseif (-not (Test-WorkerOutput)) { + $script:Lifecycle.termination = 'malformed-output' + $script:Lifecycle.failure_class = 'malformed_output' + Set-LifecycleState 'failed' @{ error = 'worker output is not a successful JSON object with structured_output' } + $terminalStateRecorded = $true + $workerExitCode = 1 + } else { + $script:Lifecycle.termination = 'natural' + Set-LifecycleState 'completed' + $terminalStateRecorded = $true + } + $script:Lifecycle.exit_code = $workerExitCode + Save-Lifecycle } catch { - Fail "launcher failed after starting worker: $($_.Exception.Message)" 1 + if ($processStarted -and $null -ne $proc) { + try { + if (-not $proc.HasExited) { + $proc.Kill($true) + $proc.WaitForExit() + } + } catch { } + } + $script:Lifecycle.exit_code = if ($null -ne $proc -and $proc.HasExited) { $proc.ExitCode } else { $null } + $script:Lifecycle.termination = 'launcher-error' + $script:Lifecycle.failure_class = 'tool_error' + if (-not $terminalStateRecorded) { + Set-LifecycleState 'failed' @{ error = $_.Exception.Message } + $terminalStateRecorded = $true + } + $workerExitCode = 1 } } finally { - if ($null -ne $proc -and -not $launcherSuccess) { + if ($null -ne $proc -and -not $terminalStateRecorded) { try { if (-not $proc.HasExited) { $proc.Kill($true) @@ -489,6 +828,9 @@ try { } catch { # Best effort kill } + $script:Lifecycle.termination = 'launcher-error' + $script:Lifecycle.failure_class = 'tool_error' + try { Set-LifecycleState 'failed' } catch { } } if ($null -ne $outFs) { try { @@ -505,6 +847,12 @@ try { $proc.Dispose() } catch { } } + try { + if ($script:Lifecycle.state -in @('completed', 'failed', 'canceled', 'quota-handoff')) { + Set-LifecycleState 'retained' + Set-LifecycleState 'cleaned' + } + } catch { } } exit $workerExitCode diff --git a/scripts/run-agy-json.sh b/scripts/run-agy-json.sh index d9ad2b4..fca7477 100755 --- a/scripts/run-agy-json.sh +++ b/scripts/run-agy-json.sh @@ -2,7 +2,7 @@ set -euo pipefail usage() { - printf 'Usage: %s --role ROLE [--route default|quality-retry] --output FILE --error FILE -- agy-arguments...\n' "$0" >&2 + printf 'Usage: %s --role ROLE [--route default|quality-retry] --output FILE --error FILE [lifecycle options] -- agy-arguments...\n' "$0" >&2 } fail() { @@ -14,11 +14,27 @@ output_path='' error_path='' role='' route='' +lifecycle_path='' +assignment_id='' +attempt=1 +mode='unknown' +verification_baseline='' +resource_ledger_path='' +timeout_seconds=0 +cancel_file='' seen_output=false seen_error=false seen_role=false seen_route=false +seen_lifecycle=false +seen_assignment_id=false +seen_attempt=false +seen_mode=false +seen_verification_baseline=false +seen_resource_ledger=false +seen_timeout=false +seen_cancel_file=false seen_delimiter=false worker_args=() @@ -80,6 +96,116 @@ while [ "$#" -gt 0 ]; do seen_route=true shift ;; + --lifecycle) + $seen_lifecycle && fail 'duplicate --lifecycle option' + [ "$#" -ge 2 ] || { usage; fail '--lifecycle requires a path'; } + lifecycle_path="$2" + seen_lifecycle=true + shift 2 + ;; + --lifecycle=*) + $seen_lifecycle && fail 'duplicate --lifecycle option' + lifecycle_path="${1#--lifecycle=}" + [ -n "$lifecycle_path" ] || { usage; fail '--lifecycle requires a path'; } + seen_lifecycle=true + shift + ;; + --assignment-id) + $seen_assignment_id && fail 'duplicate --assignment-id option' + [ "$#" -ge 2 ] || { usage; fail '--assignment-id requires an identifier'; } + assignment_id="$2" + seen_assignment_id=true + shift 2 + ;; + --assignment-id=*) + $seen_assignment_id && fail 'duplicate --assignment-id option' + assignment_id="${1#--assignment-id=}" + [ -n "$assignment_id" ] || { usage; fail '--assignment-id requires an identifier'; } + seen_assignment_id=true + shift + ;; + --attempt) + $seen_attempt && fail 'duplicate --attempt option' + [ "$#" -ge 2 ] || { usage; fail '--attempt requires an integer'; } + attempt="$2" + seen_attempt=true + shift 2 + ;; + --attempt=*) + $seen_attempt && fail 'duplicate --attempt option' + attempt="${1#--attempt=}" + seen_attempt=true + shift + ;; + --mode) + $seen_mode && fail 'duplicate --mode option' + [ "$#" -ge 2 ] || { usage; fail '--mode requires a mode name'; } + mode="$2" + seen_mode=true + shift 2 + ;; + --mode=*) + $seen_mode && fail 'duplicate --mode option' + mode="${1#--mode=}" + [ -n "$mode" ] || { usage; fail '--mode requires a mode name'; } + seen_mode=true + shift + ;; + --verification-baseline) + $seen_verification_baseline && fail 'duplicate --verification-baseline option' + [ "$#" -ge 2 ] || { usage; fail '--verification-baseline requires a value'; } + verification_baseline="$2" + seen_verification_baseline=true + shift 2 + ;; + --verification-baseline=*) + $seen_verification_baseline && fail 'duplicate --verification-baseline option' + verification_baseline="${1#--verification-baseline=}" + [ -n "$verification_baseline" ] || { usage; fail '--verification-baseline requires a value'; } + seen_verification_baseline=true + shift + ;; + --resource-ledger) + $seen_resource_ledger && fail 'duplicate --resource-ledger option' + [ "$#" -ge 2 ] || { usage; fail '--resource-ledger requires a path'; } + resource_ledger_path="$2" + seen_resource_ledger=true + shift 2 + ;; + --resource-ledger=*) + $seen_resource_ledger && fail 'duplicate --resource-ledger option' + resource_ledger_path="${1#--resource-ledger=}" + [ -n "$resource_ledger_path" ] || { usage; fail '--resource-ledger requires a path'; } + seen_resource_ledger=true + shift + ;; + --timeout-seconds) + $seen_timeout && fail 'duplicate --timeout-seconds option' + [ "$#" -ge 2 ] || { usage; fail '--timeout-seconds requires a positive number'; } + timeout_seconds="$2" + seen_timeout=true + shift 2 + ;; + --timeout-seconds=*) + $seen_timeout && fail 'duplicate --timeout-seconds option' + timeout_seconds="${1#--timeout-seconds=}" + seen_timeout=true + shift + ;; + --cancel-file) + $seen_cancel_file && fail 'duplicate --cancel-file option' + [ "$#" -ge 2 ] || { usage; fail '--cancel-file requires a path'; } + cancel_file="$2" + seen_cancel_file=true + shift 2 + ;; + --cancel-file=*) + $seen_cancel_file && fail 'duplicate --cancel-file option' + cancel_file="${1#--cancel-file=}" + [ -n "$cancel_file" ] || { usage; fail '--cancel-file requires a path'; } + seen_cancel_file=true + shift + ;; --) seen_delimiter=true shift @@ -258,6 +384,17 @@ fi [ -n "$resolved_model" ] || fail "failed to resolve model for role '$role' and route '$route'" +case "$attempt" in + 1|2) ;; + *) fail 'attempt must be 1 or 2; policy allows at most one retry per assignment' ;; +esac +case "$timeout_seconds" in + ''|*[!0-9]*) fail '--timeout-seconds must be zero or a positive integer' ;; +esac +assignment_id="${assignment_id:-$role-$(date -u +%Y%m%d%H%M%S)}" +lifecycle_path="${lifecycle_path:-$output_path.lifecycle.json}" +effort="${resolved_model##*-}" + # Resolve agy executable if [ -n "${AGY_BIN:-}" ]; then agy_bin=$AGY_BIN @@ -271,11 +408,179 @@ fi [ -x "$agy_bin" ] || fail "agy is not executable: $agy_bin" 1 -mkdir -p "$(dirname "$output_path")" "$(dirname "$error_path")" +mkdir -p "$(dirname "$output_path")" "$(dirname "$error_path")" "$(dirname "$lifecycle_path")" + +if [ -e "$lifecycle_path" ] && [ -d "$lifecycle_path" ]; then + fail "lifecycle destination is an existing directory: $lifecycle_path" +fi +if [ -e "$resource_ledger_path" ] && [ -d "$resource_ledger_path" ]; then + fail "resource ledger destination is an existing directory: $resource_ledger_path" +fi + +verification_baseline_json() { + if [ -n "$verification_baseline" ]; then + jq -Rn --arg value "$verification_baseline" '$value' + else + printf 'null\n' + fi +} + +write_lifecycle() { + baseline_json=$(verification_baseline_json) + jq -n \ + --arg assignment_id "$assignment_id" \ + --argjson attempt "$attempt" \ + --arg role "$role" \ + --arg mode "$mode" \ + --arg policy_revision "$(jq -r '.policy_revision' "$policy_file")" \ + --arg model "$resolved_model" \ + --arg effort "$effort" \ + --argjson verification_baseline "$baseline_json" \ + --arg resource_ledger "${resource_ledger_path:-}" \ + --arg output "$output_path" \ + --arg error "$error_path" \ + --arg lifecycle "$lifecycle_path" \ + '{schema_version:1, assignment_id:$assignment_id, attempt:$attempt, role:$role, mode:$mode, + policy_revision:$policy_revision, model:$model, effort:$effort, + verification_baseline:$verification_baseline, + resource_ledger:($resource_ledger | 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" +} + +record_state() { + local state="$1" + local event_time + event_time=$(date -u +%Y-%m-%dT%H:%M:%SZ) + jq --arg state "$state" --arg at "$event_time" \ + '.events += [{state:$state, at:$at}] | .state=$state' "$lifecycle_path" > "$lifecycle_path.tmp" + mv -f "$lifecycle_path.tmp" "$lifecycle_path" +} + +update_lifecycle() { + local exit_code="$1" + local termination="$2" + local failure_class="$3" + jq --arg termination "$termination" --arg failure_class "$failure_class" \ + --argjson exit_code "$exit_code" \ + '.exit_code=$exit_code | .termination=$termination | .failure_class=$failure_class' \ + "$lifecycle_path" > "$lifecycle_path.tmp" + mv -f "$lifecycle_path.tmp" "$lifecycle_path" +} + +write_lifecycle +record_state created + +if [ -n "$resource_ledger_path" ]; then + mkdir -p "$(dirname "$resource_ledger_path")" + if [ -f "$resource_ledger_path" ]; then + jq -e --arg assignment_id "$assignment_id" --arg model "$resolved_model" --arg effort "$effort" \ + '.assignment_id == $assignment_id and .model == $model and .effort == $effort' \ + "$resource_ledger_path" >/dev/null || fail 'resource ledger is pinned to a different assignment, model, or effort' + ledger_baseline=$(jq -r '.verification_baseline // empty' "$resource_ledger_path") + if [ -n "$ledger_baseline" ]; then + [ -z "$verification_baseline" ] || [ "$ledger_baseline" = "$verification_baseline" ] || \ + fail 'resource ledger is pinned to a different verification baseline' + verification_baseline="$ledger_baseline" + jq --arg baseline "$verification_baseline" '.verification_baseline=$baseline' \ + "$lifecycle_path" > "$lifecycle_path.tmp" + mv -f "$lifecycle_path.tmp" "$lifecycle_path" + fi + jq -e --argjson attempt "$attempt" 'any(.attempts[]?; .attempt == $attempt) | not' "$resource_ledger_path" >/dev/null || \ + fail "resource ledger already contains attempt $attempt" + else + jq -n --arg assignment_id "$assignment_id" --arg model "$resolved_model" --arg effort "$effort" \ + --argjson verification_baseline "$(verification_baseline_json)" \ + '{schema_version:1, assignment_id:$assignment_id, model:$model, effort:$effort, + verification_baseline:$verification_baseline, attempts:[]}' > "$resource_ledger_path" + fi + jq --argjson attempt "$attempt" --arg model "$resolved_model" --arg effort "$effort" \ + --argjson verification_baseline "$(verification_baseline_json)" --arg lifecycle "$lifecycle_path" \ + '.attempts += [{attempt:$attempt, model:$model, effort:$effort, + verification_baseline:$verification_baseline, lifecycle:$lifecycle}]' \ + "$resource_ledger_path" > "$resource_ledger_path.tmp" + mv -f "$resource_ledger_path.tmp" "$resource_ledger_path" +fi + +: > "$output_path" +: > "$error_path" + +finalize_lifecycle() { + if [ -f "$lifecycle_path" ]; then + local state + state=$(jq -r '.state' "$lifecycle_path" 2>/dev/null || true) + case "$state" in + completed|failed|canceled|quota-handoff) + record_state retained + record_state cleaned + ;; + retained) + record_state cleaned + ;; + esac + fi +} +trap finalize_lifecycle EXIT + +if [ -n "$cancel_file" ] && [ -f "$cancel_file" ]; then + update_lifecycle 130 canceled canceled + record_state canceled + exit 130 +fi set +e -"$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" +"$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" & +worker_pid=$! +set -e +record_state started +record_state running +termination='natural' +trap 'termination=canceled; kill "$worker_pid" 2>/dev/null || true' INT TERM +start_time=$(date +%s) +while kill -0 "$worker_pid" 2>/dev/null; do + if [ -n "$cancel_file" ] && [ -f "$cancel_file" ]; then + termination='canceled' + kill "$worker_pid" 2>/dev/null || true + break + fi + if [ "$timeout_seconds" -gt 0 ] && [ $(( $(date +%s) - start_time )) -ge "$timeout_seconds" ]; then + termination='timeout' + kill "$worker_pid" 2>/dev/null || true + break + fi + sleep 0.05 +done +set +e +wait "$worker_pid" worker_exit=$? set -e -exit "$worker_exit" +if [ "$termination" = 'canceled' ]; then + update_lifecycle 130 canceled canceled + record_state canceled + exit 130 +fi +if [ "$termination" = 'timeout' ]; then + update_lifecycle 124 timeout timeout + record_state failed + exit 124 +fi +if grep -Eiq 'quota|resource[_ -]?exhausted|rate limit|(^|[^0-9])429([^0-9]|$)' "$output_path" "$error_path" 2>/dev/null; then + update_lifecycle 75 quota-handoff quota + record_state quota-handoff + exit 75 +fi +if [ "$worker_exit" -ne 0 ]; then + update_lifecycle "$worker_exit" worker-exit tool_error + record_state failed + exit "$worker_exit" +fi +if ! jq -e 'type == "object" and .status == "success" and (.structured_output | type) == "object"' "$output_path" >/dev/null 2>&1; then + update_lifecycle 1 malformed-output malformed_output + record_state failed + exit 1 +fi +update_lifecycle 0 natural none +record_state completed + +exit 0 diff --git a/tests/test_worker_lifecycle.ps1 b/tests/test_worker_lifecycle.ps1 new file mode 100644 index 0000000..736099e --- /dev/null +++ b/tests/test_worker_lifecycle.ps1 @@ -0,0 +1,363 @@ +#!/usr/bin/env pwsh +# Acceptance tests for the shared worker lifecycle contract. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$script:TotalTests = 0 +$script:FailedTests = 0 + +function Pass([string]$name) { + $script:TotalTests++ + [Console]::Out.WriteLine("ok - $name") +} + +function Fail([string]$name, [string]$reason = "") { + $script:TotalTests++ + $script:FailedTests++ + $detail = if ($reason) { " - $reason" } else { "" } + [Console]::Error.WriteLine("FAIL: $name$detail") + exit 1 +} + +function Assert-Equal($actual, $expected, [string]$name) { + if ($actual -eq $expected) { + Pass $name + } else { + Fail $name "Expected '$expected', got '$actual'" + } +} + +function Assert-True([bool]$condition, [string]$name, [string]$reason = "") { + if ($condition) { + Pass $name + } else { + Fail $name $(if ($reason) { $reason } else { "Condition was false" }) + } +} + +function Invoke-Process { + param( + [Parameter(Mandatory=$true)][string]$FilePath, + [string[]]$ArgumentList = @(), + [hashtable]$Environment = @{} + ) + + $psi = [System.Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $FilePath + $psi.UseShellExecute = $false + $psi.CreateNoWindow = $true + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + foreach ($arg in $ArgumentList) { $psi.ArgumentList.Add($arg) } + foreach ($key in $Environment.Keys) { $psi.Environment[$key] = [string]$Environment[$key] } + $proc = [System.Diagnostics.Process]::Start($psi) + $stdout = $proc.StandardOutput.ReadToEndAsync() + $stderr = $proc.StandardError.ReadToEndAsync() + $proc.WaitForExit() + return [PSCustomObject]@{ + ExitCode = $proc.ExitCode + Stdout = $stdout.GetAwaiter().GetResult() + Stderr = $stderr.GetAwaiter().GetResult() + } +} + +$rootDir = Split-Path -Parent $PSScriptRoot +$launcher = Join-Path $rootDir 'scripts/run-agy-json.ps1' +$shLauncher = Join-Path $rootDir 'scripts/run-agy-json.sh' +$tmpRoot = Join-Path ([System.IO.Path]::GetTempPath()) "offload-worker-lifecycle-$([System.Guid]::NewGuid().ToString('N'))" +[System.IO.Directory]::CreateDirectory($tmpRoot) | Out-Null + +try { + $fakeDir = Join-Path $tmpRoot 'bin' + [System.IO.Directory]::CreateDirectory($fakeDir) | Out-Null +$fakeAgy = Join-Path $fakeDir 'fake-agy.ps1' +@' +[Console]::Error.WriteLine('fake worker stderr') +if ($env:FAKE_AGY_QUOTA) { + [Console]::Error.WriteLine('quota exhausted') + [Console]::Out.WriteLine('{"status":"error","error":"quota exhausted"}') + exit 75 +} +if ($env:FAKE_AGY_MALFORMED) { + [Console]::Out.WriteLine('{not-json') + exit 0 +} +if ($env:FAKE_AGY_SCALAR) { + [Console]::Out.WriteLine('{"status":"success","structured_output":"not-an-object"}') + exit 0 +} +if ($env:FAKE_AGY_SLEEP_SECONDS) { + Start-Sleep -Seconds ([int]$env:FAKE_AGY_SLEEP_SECONDS) +} +[Console]::Out.WriteLine('{"status":"success","response":"ok","structured_output":{"ok":true}}') +'@ | Set-Content -LiteralPath $fakeAgy -Encoding utf8 + + $outputPath = Join-Path $tmpRoot 'attempt-1.json' + $errorPath = Join-Path $tmpRoot 'attempt-1.err' + $lifecyclePath = Join-Path $tmpRoot 'attempt-1.lifecycle.json' + $ledgerPath = Join-Path $tmpRoot 'resource-ledger.json' + $result = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', + '--output', $outputPath, + '--error', $errorPath, + '--lifecycle', $lifecyclePath, + '--assignment-id', 'assignment-1', + '--attempt', '1', + '--mode', 'execution', + '--verification-baseline', 'baseline-1', + '--resource-ledger', $ledgerPath, + '--', '-p', 'lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy } + + Assert-Equal $result.ExitCode 0 'normal worker exits successfully' + $lifecycle = Get-Content -LiteralPath $lifecyclePath -Raw | ConvertFrom-Json + $states = @($lifecycle.events | ForEach-Object { $_.state }) -join ',' + Assert-Equal $states 'created,started,running,completed,retained,cleaned' 'normal worker records the shared lifecycle' + Assert-Equal $lifecycle.state 'cleaned' 'normal worker ends in cleaned state' + Assert-Equal $lifecycle.assignment_id 'assignment-1' 'lifecycle records assignment identity' + Assert-Equal $lifecycle.attempt 1 'lifecycle records attempt number' + Assert-Equal $lifecycle.verification_baseline 'baseline-1' 'lifecycle records verification baseline' + Assert-Equal $lifecycle.model 'gemini-3.8-flash-high' 'lifecycle records pinned model' + Assert-Equal $lifecycle.effort 'high' 'lifecycle records pinned effort' + Assert-Equal $lifecycle.exit_code 0 'lifecycle records worker exit result' + Assert-True (Test-Path -LiteralPath $outputPath) 'normal worker retains stdout artifact' + Assert-True (Test-Path -LiteralPath $errorPath) 'normal worker retains stderr artifact' + Assert-True (Test-Path -LiteralPath $ledgerPath) 'normal worker records resource ledger' + + $retryOutput = Join-Path $tmpRoot 'attempt-2.json' + $retryError = Join-Path $tmpRoot 'attempt-2.err' + $retryLifecycle = Join-Path $tmpRoot 'attempt-2.lifecycle.json' + $retry = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $retryOutput, '--error', $retryError, + '--lifecycle', $retryLifecycle, '--assignment-id', 'assignment-1', '--attempt', '2', + '--resource-ledger', $ledgerPath, '--', '-p', 'retry lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy } + Assert-Equal $retry.ExitCode 0 'retry worker exits successfully' + $retryRecord = Get-Content -LiteralPath $retryLifecycle -Raw | ConvertFrom-Json + Assert-Equal $retryRecord.model $lifecycle.model 'retry uses the ledger pinned model' + Assert-Equal $retryRecord.verification_baseline $lifecycle.verification_baseline 'retry inherits the ledger verification baseline' + $ledger = Get-Content -LiteralPath $ledgerPath -Raw | ConvertFrom-Json + Assert-Equal @($ledger.attempts).Count 2 'resource ledger records both attempts' + + $thirdOutput = Join-Path $tmpRoot 'attempt-3.json' + $third = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $thirdOutput, '--error', (Join-Path $tmpRoot 'attempt-3.err'), + '--lifecycle', (Join-Path $tmpRoot 'attempt-3.lifecycle.json'), '--assignment-id', 'assignment-1', '--attempt', '3', + '--resource-ledger', $ledgerPath, '--', '-p', 'third attempt must be rejected' + ) -Environment @{ AGY_BIN = $fakeAgy } + Assert-True ($third.ExitCode -ne 0) 'third attempt is rejected by the retry limit' + + $malformedOutput = Join-Path $tmpRoot 'malformed.json' + $malformedError = Join-Path $tmpRoot 'malformed.err' + $malformedLifecycle = Join-Path $tmpRoot 'malformed.lifecycle.json' + $malformed = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $malformedOutput, '--error', $malformedError, + '--lifecycle', $malformedLifecycle, '--assignment-id', 'assignment-malformed', '--attempt', '1', + '--', '-p', 'malformed lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy; FAKE_AGY_MALFORMED = '1' } + Assert-True ($malformed.ExitCode -ne 0) 'malformed worker exits unsuccessfully' + $malformedRecord = Get-Content -LiteralPath $malformedLifecycle -Raw | ConvertFrom-Json + Assert-Equal $malformedRecord.state 'cleaned' 'malformed worker still closes lifecycle' + Assert-Equal ((@($malformedRecord.events | ForEach-Object { $_.state }) -join ',')) 'created,started,running,failed,retained,cleaned' 'malformed output cannot complete assignment' + Assert-Equal $malformedRecord.failure_class 'malformed_output' 'malformed output records diagnosis' + + $scalarLifecycle = Join-Path $tmpRoot 'scalar.lifecycle.json' + $scalar = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', (Join-Path $tmpRoot 'scalar.json'), '--error', (Join-Path $tmpRoot 'scalar.err'), + '--lifecycle', $scalarLifecycle, '--assignment-id', 'assignment-scalar', '--attempt', '1', + '--', '-p', 'scalar lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy; FAKE_AGY_SCALAR = '1' } + Assert-True ($scalar.ExitCode -ne 0) 'scalar structured output exits unsuccessfully' + $scalarRecord = Get-Content -LiteralPath $scalarLifecycle -Raw | ConvertFrom-Json + Assert-Equal $scalarRecord.failure_class 'malformed_output' 'scalar structured output records diagnosis' + + $timeoutOutput = Join-Path $tmpRoot 'timeout.json' + $timeoutError = Join-Path $tmpRoot 'timeout.err' + $timeoutLifecycle = Join-Path $tmpRoot 'timeout.lifecycle.json' + $timedOut = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $timeoutOutput, '--error', $timeoutError, + '--lifecycle', $timeoutLifecycle, '--assignment-id', 'assignment-timeout', '--attempt', '1', + '--timeout-seconds', '1', '--', '-p', 'timeout lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy; FAKE_AGY_SLEEP_SECONDS = '10' } + Assert-Equal $timedOut.ExitCode 124 'timed out worker returns canonical timeout code' + $timeoutRecord = Get-Content -LiteralPath $timeoutLifecycle -Raw | ConvertFrom-Json + Assert-Equal $timeoutRecord.exit_code 124 'timeout lifecycle records canonical launcher exit result' + Assert-Equal $timeoutRecord.failure_class 'timeout' 'timeout records diagnosis' + Assert-Equal ((@($timeoutRecord.events | ForEach-Object { $_.state }) -join ',')) 'created,started,running,failed,retained,cleaned' 'timeout retains evidence after stopping worker' + + $quotaOutput = Join-Path $tmpRoot 'quota.json' + $quotaError = Join-Path $tmpRoot 'quota.err' + $quotaLifecycle = Join-Path $tmpRoot 'quota.lifecycle.json' + $quota = Invoke-Process -FilePath 'pwsh' -ArgumentList @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $quotaOutput, '--error', $quotaError, + '--lifecycle', $quotaLifecycle, '--assignment-id', 'assignment-quota', '--attempt', '1', + '--', '-p', 'quota lifecycle test' + ) -Environment @{ AGY_BIN = $fakeAgy; FAKE_AGY_QUOTA = '1' } + Assert-Equal $quota.ExitCode 75 'quota exhaustion returns handoff code' + $quotaRecord = Get-Content -LiteralPath $quotaLifecycle -Raw | ConvertFrom-Json + Assert-Equal $quotaRecord.state 'cleaned' 'quota handoff closes lifecycle' + Assert-Equal $quotaRecord.failure_class 'quota' 'quota handoff records diagnosis' + Assert-True ((@($quotaRecord.events | ForEach-Object { $_.state }) -contains 'quota-handoff')) 'quota exhaustion records quota-handoff state' + + $cancelOutput = Join-Path $tmpRoot 'cancel.json' + $cancelError = Join-Path $tmpRoot 'cancel.err' + $cancelLifecycle = Join-Path $tmpRoot 'cancel.lifecycle.json' + $cancelFile = Join-Path $tmpRoot 'cancel.request' + $cancelArgs = @( + '-NoProfile', '-NonInteractive', '-File', $launcher, + '--role', 'implementer', '--output', $cancelOutput, '--error', $cancelError, + '--lifecycle', $cancelLifecycle, '--assignment-id', 'assignment-cancel', '--attempt', '1', + '--cancel-file', $cancelFile, '--', '-p', 'cancel lifecycle test' + ) + $cancelPsi = [System.Diagnostics.ProcessStartInfo]::new() + $cancelPsi.FileName = 'pwsh' + $cancelPsi.UseShellExecute = $false + $cancelPsi.CreateNoWindow = $true + $cancelPsi.RedirectStandardOutput = $true + $cancelPsi.RedirectStandardError = $true + foreach ($arg in $cancelArgs) { $cancelPsi.ArgumentList.Add($arg) } + $cancelPsi.Environment['AGY_BIN'] = $fakeAgy + $cancelPsi.Environment['FAKE_AGY_SLEEP_SECONDS'] = '10' + $cancelProc = [System.Diagnostics.Process]::Start($cancelPsi) + $cancelDeadline = [DateTime]::UtcNow.AddSeconds(5) + while (-not (Test-Path -LiteralPath $cancelLifecycle) -and [DateTime]::UtcNow -lt $cancelDeadline) { + Start-Sleep -Milliseconds 20 + } + while ((Get-Content -LiteralPath $cancelLifecycle -Raw | ConvertFrom-Json).state -ne 'running' -and [DateTime]::UtcNow -lt $cancelDeadline) { + Start-Sleep -Milliseconds 20 + } + [System.IO.File]::WriteAllText($cancelFile, 'cancel') + $cancelProc.WaitForExit() + $cancelProc.StandardOutput.ReadToEnd() | Out-Null + $cancelProc.StandardError.ReadToEnd() | Out-Null + $cancelExitCode = $cancelProc.ExitCode + $cancelProc.Dispose() + Assert-Equal $cancelExitCode 130 'canceled worker returns canonical cancellation code' + $cancelRecord = Get-Content -LiteralPath $cancelLifecycle -Raw | ConvertFrom-Json + Assert-Equal $cancelRecord.exit_code 130 'cancellation lifecycle records canonical launcher exit result' + Assert-Equal $cancelRecord.state 'cleaned' 'canceled worker closes lifecycle' + Assert-Equal $cancelRecord.failure_class 'canceled' 'cancellation records diagnosis' + Assert-Equal ((@($cancelRecord.events | ForEach-Object { $_.state }) -join ',')) 'created,started,running,canceled,retained,cleaned' 'canceled worker is stopped before cleanup' + + $bashCommand = $null + if ($IsWindows) { + if (Test-Path -LiteralPath 'C:\Program Files\Git\bin\bash.exe' -PathType Leaf) { + $bashCommand = 'C:\Program Files\Git\bin\bash.exe' + } elseif (Test-Path -LiteralPath 'C:\Program Files\Git\usr\bin\bash.exe' -PathType Leaf) { + $bashCommand = 'C:\Program Files\Git\usr\bin\bash.exe' + } + } + if (-not $bashCommand) { + $bashCandidate = Get-Command bash -ErrorAction SilentlyContinue + if ($bashCandidate) { + $candidateSource = if ($bashCandidate.Source) { $bashCandidate.Source } else { $bashCandidate.Name } + if (-not $IsWindows -or -not $candidateSource.StartsWith($env:SystemRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + $bashCommand = $candidateSource + } + } + } + if ($bashCommand -and (Test-Path -LiteralPath $shLauncher -PathType Leaf)) { + $bashAgy = Join-Path $fakeDir 'fake-agy-bash' + @' +#!/usr/bin/env bash +set -euo pipefail +printf 'fake bash stderr\n' >&2 +if [ "${FAKE_BASH_MODE:-}" = quota ]; then + printf 'quota exhausted\n' >&2 + printf '{"status":"error","error":"quota exhausted"}\n' + exit 75 +fi +if [ "${FAKE_BASH_MODE:-}" = malformed ]; then + printf '{not-json\n' + exit 0 +fi +if [ "${FAKE_BASH_MODE:-}" = scalar ]; then + printf '{"status":"success","structured_output":"not-an-object"}\n' + exit 0 +fi +printf '{"status":"success","response":"ok","structured_output":{"ok":true}}\n' +'@ | Set-Content -LiteralPath $bashAgy -Encoding utf8 + $bashRunner = Join-Path $tmpRoot 'run-bash-lifecycle.sh' + @' +#!/usr/bin/env bash +set -euo pipefail +export AGY_BIN="$1" +launcher="$2" +out_file="$3" +err_file="$4" +lifecycle_file="$5" +ledger_file="$6" +"$launcher" --role implementer --output "$out_file" --error "$err_file" --lifecycle "$lifecycle_file" --assignment-id assignment-bash --attempt 1 --mode execution --verification-baseline baseline-bash --resource-ledger "$ledger_file" -- -p 'bash lifecycle test' +'@ | Set-Content -LiteralPath $bashRunner -Encoding utf8 + if (-not $IsWindows) { + [System.IO.File]::SetUnixFileMode($bashAgy, [System.IO.UnixFileMode]509) + [System.IO.File]::SetUnixFileMode($bashRunner, [System.IO.UnixFileMode]509) + } + $bashOut = Join-Path $tmpRoot 'bash.json' + $bashErr = Join-Path $tmpRoot 'bash.err' + $bashLifecycle = Join-Path $tmpRoot 'bash.lifecycle.json' + $bashLedger = Join-Path $tmpRoot 'bash.ledger.json' + $bashResult = Invoke-Process -FilePath $bashCommand -ArgumentList @( + ($bashRunner -replace '\\', '/'), ($bashAgy -replace '\\', '/'), ($shLauncher -replace '\\', '/'), + ($bashOut -replace '\\', '/'), ($bashErr -replace '\\', '/'), ($bashLifecycle -replace '\\', '/'), + ($bashLedger -replace '\\', '/') + ) + Assert-Equal $bashResult.ExitCode 0 'bash worker exits successfully' + $bashRecord = Get-Content -LiteralPath $bashLifecycle -Raw | ConvertFrom-Json + Assert-Equal ((@($bashRecord.events | ForEach-Object { $_.state }) -join ',')) 'created,started,running,completed,retained,cleaned' 'bash records the same shared lifecycle' + Assert-Equal $bashRecord.model 'gemini-3.8-flash-high' 'bash records pinned model' + + $bashMalformedLifecycle = Join-Path $tmpRoot 'bash-malformed.lifecycle.json' + $bashMalformed = Invoke-Process -FilePath $bashCommand -ArgumentList @( + ($bashRunner -replace '\\', '/'), ($bashAgy -replace '\\', '/'), ($shLauncher -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-malformed.json') -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-malformed.err') -replace '\\', '/'), ($bashMalformedLifecycle -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-malformed.ledger.json') -replace '\\', '/') + ) -Environment @{ FAKE_BASH_MODE = 'malformed' } + Assert-True ($bashMalformed.ExitCode -ne 0) 'bash malformed worker exits unsuccessfully' + $bashMalformedRecord = Get-Content -LiteralPath $bashMalformedLifecycle -Raw | ConvertFrom-Json + Assert-Equal $bashMalformedRecord.failure_class 'malformed_output' 'bash malformed output records diagnosis' + Assert-Equal ((@($bashMalformedRecord.events | ForEach-Object { $_.state }) -join ',')) 'created,started,running,failed,retained,cleaned' 'bash malformed output cannot complete assignment' + + $bashScalarLifecycle = Join-Path $tmpRoot 'bash-scalar.lifecycle.json' + $bashScalar = Invoke-Process -FilePath $bashCommand -ArgumentList @( + ($bashRunner -replace '\\', '/'), ($bashAgy -replace '\\', '/'), ($shLauncher -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-scalar.json') -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-scalar.err') -replace '\\', '/'), ($bashScalarLifecycle -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-scalar.ledger.json') -replace '\\', '/') + ) -Environment @{ FAKE_BASH_MODE = 'scalar' } + Assert-True ($bashScalar.ExitCode -ne 0) 'bash scalar structured output exits unsuccessfully' + $bashScalarRecord = Get-Content -LiteralPath $bashScalarLifecycle -Raw | ConvertFrom-Json + Assert-Equal $bashScalarRecord.failure_class 'malformed_output' 'bash scalar structured output records diagnosis' + + $bashQuotaLifecycle = Join-Path $tmpRoot 'bash-quota.lifecycle.json' + $bashQuota = Invoke-Process -FilePath $bashCommand -ArgumentList @( + ($bashRunner -replace '\\', '/'), ($bashAgy -replace '\\', '/'), ($shLauncher -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-quota.json') -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-quota.err') -replace '\\', '/'), ($bashQuotaLifecycle -replace '\\', '/'), + ((Join-Path $tmpRoot 'bash-quota.ledger.json') -replace '\\', '/') + ) -Environment @{ FAKE_BASH_MODE = 'quota' } + Assert-Equal $bashQuota.ExitCode 75 'bash quota exhaustion returns handoff code' + $bashQuotaRecord = Get-Content -LiteralPath $bashQuotaLifecycle -Raw | ConvertFrom-Json + Assert-Equal $bashQuotaRecord.failure_class 'quota' 'bash quota handoff records diagnosis' + Assert-True ((@($bashQuotaRecord.events | ForEach-Object { $_.state }) -contains 'quota-handoff')) 'bash quota exhaustion records quota-handoff state' + } else { + [Console]::Out.WriteLine('skip - bash not found on host; skipping worker lifecycle parity') + } +} finally { + if (Test-Path -LiteralPath $tmpRoot) { + Remove-Item -LiteralPath $tmpRoot -Recurse -Force + } +} + +if ($script:FailedTests -gt 0) { exit 1 } +[Console]::Out.WriteLine("$($script:TotalTests) tests passed") +exit 0 From 453c14df68994df33f91978f41666b54a5f67796 Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 17:11:28 +0800 Subject: [PATCH 03/11] feat: define vendor-neutral worker adapter contract --- README.md | 3 + SKILL.md | 11 ++ docs/worker-adapter-contract.md | 126 +++++++++++++++++ modes/execution.md | 8 ++ scripts/check-worker-adapter.ps1 | 188 +++++++++++++++++++++++++ scripts/check-worker-adapter.sh | 99 +++++++++++++ tests/test_worker_adapter_contract.ps1 | 151 ++++++++++++++++++++ tests/test_worker_adapter_contract.sh | 108 ++++++++++++++ tests/test_workflow_static.ps1 | 26 ++++ 9 files changed, 720 insertions(+) create mode 100644 docs/worker-adapter-contract.md create mode 100644 scripts/check-worker-adapter.ps1 create mode 100644 scripts/check-worker-adapter.sh create mode 100644 tests/test_worker_adapter_contract.ps1 create mode 100644 tests/test_worker_adapter_contract.sh diff --git a/README.md b/README.md index 2436edb..9124d01 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ Offload's online-research workflow is adapted from Asa by Achibukz, used with pe - **Filesystem isolation.** Research workflows run inside disposable workspaces outside the live repository. Workers receive only scoped snapshots of declared files, keeping live repository files untouched. - **Mechanical verification.** Execution workflows require a clean git working tree, execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path checks, and automated test gates. - **Prohibition on nested dispatch.** Assignments instruct workers not to dispatch nested workers. +- **Vendor-neutral worker adapters.** [`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md) defines the assignment, lifecycle, capability/model discovery, ownership, and normalized-result boundary. The current AGY launcher is the reference adapter; verification and cleanup remain with the orchestrator. ## Supported environments @@ -324,12 +325,14 @@ Run the automated acceptance suite to verify contracts across supported helper f ```bash bash tests/test_research_modes.sh bash tests/test_execution_scope.sh +bash tests/test_worker_adapter_contract.sh ``` #### PowerShell ```powershell pwsh -File tests/test_research_helpers.ps1 pwsh -File tests/test_execution_scope.ps1 +pwsh -File tests/test_worker_adapter_contract.ps1 ``` ## Findings about agy diff --git a/SKILL.md b/SKILL.md index 76de7d3..680c778 100644 --- a/SKILL.md +++ b/SKILL.md @@ -85,6 +85,17 @@ In PowerShell command expressions, always quote the delimiter (`'--'`). - `--route default` (default): Resolves `default_model` for the specified role. - `--route quality-retry`: Resolves `quality_escalation.model` for that role. If `quality_escalation` is `null` or unconfigured, the launcher rejects the request with exit code 2 before starting `agy`. Never infer an escalation model or replace the route. +## Worker adapter contract + +The vendor-neutral boundary for one bounded worker assignment is defined in +[`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md). The +orchestrator owns assignment constraints, verification, publication, and +cleanup decisions. An adapter owns vendor command syntax, output parsing, +capability discovery, and model catalog handling, then returns the normalized +result described by that contract. Validate adapter results with +`scripts/check-worker-adapter.ps1` or `scripts/check-worker-adapter.sh` before +running the existing execution scope check and gates. + ## Shared recovery, retry accounting, and failure handling ### Stable worker IDs and retry ceiling diff --git a/docs/worker-adapter-contract.md b/docs/worker-adapter-contract.md new file mode 100644 index 0000000..5fc54f7 --- /dev/null +++ b/docs/worker-adapter-contract.md @@ -0,0 +1,126 @@ +# Worker adapter contract + +This document defines the boundary between the `orchestrator` and a vendor +`adapter`. An adapter runs one bounded `worker` assignment. It does not decide +the assignment, verify the result, or own cleanup outside the resources it +reports. + +The contract is versioned independently from a vendor command line. Vendor +syntax, output parsing, process handles, capability catalogs, and model +catalogs stay inside the adapter. The orchestrator only consumes the records +defined here and runs the `execution scope check` and other existing gates. + +## Assignment + +The orchestrator gives the adapter an immutable JSON assignment: + +```json +{ + "contract_version": 1, + "assignment_id": "task-17", + "request": { "prompt": "..." }, + "constraints": { + "tools": ["read", "write"], + "permissions": ["repo.read", "repo.write"], + "owned_paths": ["src"], + "frozen_paths": ["tests"], + "worktree": { "id": "worktree-17", "path": "..." }, + "artifact_root": "...", + "cleanup_resource_ids": ["process:17", "worktree:17"] + } +} +``` + +`assignment_id` must be stable across retries. `owned_paths` and +`frozen_paths` are repository-relative paths. The adapter may use fewer tools, +permissions, or paths than the assignment grants, but it cannot widen them. +The worktree and artifact root are exact identities. A result that reports a +different worktree, artifact root, or cleanup resource is rejected. + +The adapter must treat `constraints` as read-only input. It must not turn a +missing permission into an allowed permission, reinterpret a path as a parent +directory, or transfer cleanup to the orchestrator for an unreported resource. + +## Adapter operations + +Every adapter exposes these operations, whether as functions, a command +protocol, or a host-language object: + +| Operation | Required behavior | +| --- | --- | +| `discover-capabilities` | Return the adapter's available tools and permissions, without changing the assignment. | +| `discover-models` | Return model identifiers and capabilities known by this vendor. The adapter owns catalog syntax and authentication. | +| `launch` | Start exactly one worker for the assignment and return a process/job identity plus the worktree and artifact-root identities. | +| `wait` | Wait for completion up to the requested timeout and return a lifecycle state. | +| `cancel` | Request cancellation for the reported process/job identity and return its final lifecycle state. | +| `exit-status` | Return the process exit code or signal, including a still-running state when no exit exists. | +| `capture-result` | Parse the worker output into the normalized result below. Raw vendor output never crosses this boundary. | +| `ownership` | Return the process/job, worktree, and artifact resources the adapter created and can identify. | + +`launch` may not widen the static assignment. `wait`, `cancel`, and +`exit-status` may only address the identity returned by `launch`. The adapter +reports ownership; the orchestrator decides whether cleanup is safe. This +prevents an adapter from deleting a resource outside its ownership record. + +## Normalized result + +`capture-result` returns this shape: + +```json +{ + "contract_version": 1, + "assignment_id": "task-17", + "status": "succeeded", + "artifacts": [ + { "path": "...", "kind": "worker-output", "sha256": "...", "verified": false } + ], + "resources": [ + { "type": "process", "id": "process:17" }, + { "type": "worktree", "id": "worktree:17", "path": "..." } + ], + "ownership": { "resource_ids": ["process:17", "worktree:17"] }, + "constraint_snapshot": { + "tools": ["read"], + "permissions": ["repo.read"], + "owned_paths": ["src"], + "frozen_paths": ["tests"], + "worktree": { "id": "worktree-17", "path": "..." }, + "artifact_root": "...", + "cleanup_resource_ids": ["process:17", "worktree:17"] + }, + "model_selection": { + "provider": "vendor-name", + "model_id": "vendor-model-id", + "selection_reason": "matched required capability" + }, + "exit": { "code": 0, "signal": null }, + "publication": { "status": "unpublished" } +} +``` + +`status` is one of `succeeded`, `failed`, `cancelled`, or `malformed`. +`malformed` describes a worker response that the adapter could classify. An +unparseable adapter result is a contract failure instead. + +The adapter must keep every artifact below `artifact_root`, report every +resource in `ownership.resource_ids`, and set `verified` to `false`. +`publication.status` must be `unpublished`. Verification, publication, and +the final `accepted_attempt` belong to the orchestrator after the +`execution scope check` and gate commands pass. + +The normalized result always carries model-selection metadata. The +`provider`, model identifier, and selection reason are opaque to the +orchestrator. The orchestrator may compare them with its own policy, but it +does not parse vendor model catalogs. + +## Reference adapter + +The current AGY path is the reference adapter. On PowerShell it launches +through [`scripts/run-agy-json.ps1`](../scripts/run-agy-json.ps1); on POSIX +hosts it uses [`scripts/run-agy-json.sh`](../scripts/run-agy-json.sh). Those +files contain AGY argument syntax and model routing. A future adapter keeps +its own command syntax and catalog parsing in its own directory, then emits +the same assignment and normalized-result records. + +`grill-with-docs` and other host skills should depend only on this contract. +They must not contain adapter names, vendor commands, or vendor model names. diff --git a/modes/execution.md b/modes/execution.md index e714dcf..dec06c5 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -35,6 +35,14 @@ Workers are dispatched by role using `run-agy-json` with `--role `. The la Acceptance is distinct from process completion: exit 0, a top-level success status, or prose is insufficient. Require a parsed envelope, valid substantive structured output, execution-scope and gate evidence, and an explicit accepted attempt. A gate exit 126 or 127 is classified as `unrunnable` with `verification: not_performed`; preserve the command, exit code, and diagnostic evidence, and do not schedule a quality retry. +Worker processes run through the vendor-neutral adapter boundary in +[`docs/worker-adapter-contract.md`](../docs/worker-adapter-contract.md). +Validate its normalized result with `scripts/check-worker-adapter.sh` or +`scripts/check-worker-adapter.ps1`, using the helper matching the host, before +accepting artifacts. The adapter reports process, worktree, and artifact +ownership. The orchestrator alone decides whether verification, publication, +or cleanup is allowed. + ## Step 1: Split and scout ### Provisional split diff --git a/scripts/check-worker-adapter.ps1 b/scripts/check-worker-adapter.ps1 new file mode 100644 index 0000000..1559cd2 --- /dev/null +++ b/scripts/check-worker-adapter.ps1 @@ -0,0 +1,188 @@ +#!/usr/bin/env pwsh +# Validate the vendor-neutral worker adapter assignment/result boundary. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Fail([string]$message) { + [Console]::Error.WriteLine("ERROR: $message") + exit 2 +} + +function Read-Object([string]$path, [string]$label) { + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { Fail "$label does not exist: $path" } + try { + $value = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json + } catch { + Fail "$label is not valid JSON: $($_.Exception.Message)" + } + if ($null -eq $value -or $value -isnot [PSCustomObject]) { Fail "$label must be a JSON object" } + return $value +} + +function Property($object, [string]$name, [string]$label) { + $property = $object.PSObject.Properties[$name] + if ($null -eq $property) { Fail "$label is missing '$name'" } + return $property.Value +} + +function String-Value($value, [string]$label) { + if ($value -isnot [string] -or [string]::IsNullOrWhiteSpace($value)) { Fail "$label must be a non-empty string" } + return [string]$value +} + +function String-Array($value, [string]$label) { + # ConvertFrom-Json unwraps empty and one-item arrays. Assert-Json-Arrays + # validates the source JSON shape; here null represents a valid empty array. + if ($null -eq $value) { return @() } + $items = @($value) + foreach ($item in $items) { [void](String-Value $item $label) } + return $items | ForEach-Object { [string]$_ } +} + +function Assert-Json-Arrays([string]$json, [string]$label, [string[]]$paths) { + try { $document = [System.Text.Json.JsonDocument]::Parse($json) } + catch { Fail "$label is not valid JSON: $($_.Exception.Message)" } + try { + foreach ($path in $paths) { + $element = $document.RootElement + foreach ($name in $path.Split('.')) { $element = $element.GetProperty($name) } + if ($element.ValueKind -ne [System.Text.Json.JsonValueKind]::Array) { Fail "$label.$path must be an array" } + } + } catch [System.Collections.Generic.KeyNotFoundException] { + Fail "$label array property is missing" + } finally { + $document.Dispose() + } +} + +function Canonical([string]$path) { + try { return [IO.Path]::GetFullPath($path).TrimEnd([IO.Path]::DirectorySeparatorChar, [IO.Path]::AltDirectorySeparatorChar) } + catch { Fail "invalid path '$path'" } +} + +function Is-Within([string]$child, [string]$parent) { + $childPath = Canonical $child + $parentPath = Canonical $parent + return [string]::Equals($childPath, $parentPath, [StringComparison]::OrdinalIgnoreCase) -or + $childPath.StartsWith("$parentPath$([IO.Path]::DirectorySeparatorChar)", [StringComparison]::OrdinalIgnoreCase) +} + +function Contains-String([string[]]$allowed, [string]$value) { + return $allowed -contains $value +} + +function Check-Subset([string[]]$actual, [string[]]$allowed, [string]$label) { + foreach ($item in $actual) { + if (-not (Contains-String $allowed $item)) { Fail "$label widens the assignment with '$item'" } + } +} + +function Check-Path-Subset([string[]]$actual, [string[]]$allowed, [string]$label) { + foreach ($item in $actual) { + $covered = $false + foreach ($grant in $allowed) { + if ($item -eq $grant -or $item.StartsWith("$grant/", [StringComparison]::OrdinalIgnoreCase)) { $covered = $true; break } + } + if (-not $covered) { Fail "$label widens the assignment with '$item'" } + } +} + +function Check-Constraints($assignment, $result) { + $grants = Property $assignment 'constraints' 'assignment' + $used = Property $result 'constraint_snapshot' 'result' + + $grantTools = String-Array (Property $grants 'tools' 'assignment.constraints') 'assignment.constraints.tools' + $grantPermissions = String-Array (Property $grants 'permissions' 'assignment.constraints') 'assignment.constraints.permissions' + $grantOwned = String-Array (Property $grants 'owned_paths' 'assignment.constraints') 'assignment.constraints.owned_paths' + $grantFrozen = String-Array (Property $grants 'frozen_paths' 'assignment.constraints') 'assignment.constraints.frozen_paths' + $grantCleanup = String-Array (Property $grants 'cleanup_resource_ids' 'assignment.constraints') 'assignment.constraints.cleanup_resource_ids' + + Check-Subset (String-Array (Property $used 'tools' 'result.constraint_snapshot') 'result.constraint_snapshot.tools') $grantTools 'tools' + Check-Subset (String-Array (Property $used 'permissions' 'result.constraint_snapshot') 'result.constraint_snapshot.permissions') $grantPermissions 'permissions' + Check-Path-Subset (String-Array (Property $used 'owned_paths' 'result.constraint_snapshot') 'result.constraint_snapshot.owned_paths') $grantOwned 'owned_paths' + Check-Path-Subset (String-Array (Property $used 'frozen_paths' 'result.constraint_snapshot') 'result.constraint_snapshot.frozen_paths') $grantFrozen 'frozen_paths' + Check-Subset (String-Array (Property $used 'cleanup_resource_ids' 'result.constraint_snapshot') 'result.constraint_snapshot.cleanup_resource_ids') $grantCleanup 'cleanup_resource_ids' + + $grantWorktree = Property $grants 'worktree' 'assignment.constraints' + $usedWorktree = Property $used 'worktree' 'result.constraint_snapshot' + $grantWorktreeId = String-Value (Property $grantWorktree 'id' 'assignment.constraints.worktree') 'assignment worktree id' + $usedWorktreeId = String-Value (Property $usedWorktree 'id' 'result.constraint_snapshot.worktree') 'result worktree id' + if ($grantWorktreeId -ne $usedWorktreeId) { Fail 'result changes the worktree id' } + $grantWorktreePath = Canonical (String-Value (Property $grantWorktree 'path' 'assignment.constraints.worktree') 'assignment worktree path') + $usedWorktreePath = Canonical (String-Value (Property $usedWorktree 'path' 'result.constraint_snapshot.worktree') 'result worktree path') + if ($grantWorktreePath -ne $usedWorktreePath) { Fail 'result changes the worktree path' } + + $grantArtifactRoot = Canonical (String-Value (Property $grants 'artifact_root' 'assignment.constraints') 'assignment artifact root') + $usedArtifactRoot = Canonical (String-Value (Property $used 'artifact_root' 'result.constraint_snapshot') 'result artifact root') + if ($grantArtifactRoot -ne $usedArtifactRoot) { Fail 'result changes the artifact root' } + return $grantArtifactRoot +} + +if ($args.Count -ne 4 -or $args[0] -ne '--assignment' -or $args[2] -ne '--result') { + [Console]::Error.WriteLine('Usage: check-worker-adapter.ps1 --assignment FILE --result FILE') + exit 2 +} + +$assignment = Read-Object ([string]$args[1]) 'assignment' +$result = Read-Object ([string]$args[3]) 'result' +Assert-Json-Arrays (Get-Content -LiteralPath ([string]$args[1]) -Raw) 'assignment' @( + 'constraints.tools', 'constraints.permissions', 'constraints.owned_paths', + 'constraints.frozen_paths', 'constraints.cleanup_resource_ids' +) +Assert-Json-Arrays (Get-Content -LiteralPath ([string]$args[3]) -Raw) 'result' @( + 'constraint_snapshot.tools', 'constraint_snapshot.permissions', + 'constraint_snapshot.owned_paths', 'constraint_snapshot.frozen_paths', + 'constraint_snapshot.cleanup_resource_ids', 'ownership.resource_ids', + 'resources', 'artifacts' +) + +if ((Property $assignment 'contract_version' 'assignment') -ne 1) { Fail 'assignment contract_version must be 1' } +if ((Property $result 'contract_version' 'result') -ne 1) { Fail 'result contract_version must be 1' } +$assignmentId = String-Value (Property $assignment 'assignment_id' 'assignment') 'assignment_id' +if ((String-Value (Property $result 'assignment_id' 'result') 'result.assignment_id') -ne $assignmentId) { Fail 'result assignment_id does not match assignment' } +[void](String-Value (Property (Property $assignment 'request' 'assignment') 'prompt' 'assignment.request') 'assignment.request.prompt') +$artifactRoot = Check-Constraints $assignment $result + +$allowedStatuses = @('succeeded', 'failed', 'cancelled', 'malformed') +$status = String-Value (Property $result 'status' 'result') 'result.status' +if ($allowedStatuses -notcontains $status) { Fail "result.status '$status' is not supported" } + +$ownership = Property $result 'ownership' 'result' +$ownedResourceIds = String-Array (Property $ownership 'resource_ids' 'result.ownership') 'result.ownership.resource_ids' +$resources = @((Property $result 'resources' 'result')) +foreach ($resource in $resources) { + if ($null -eq $resource -or $resource -isnot [PSCustomObject]) { Fail 'result.resources entries must be objects' } + $resourceId = String-Value (Property $resource 'id' 'result.resources entry') 'result resource id' + if ($ownedResourceIds -notcontains $resourceId) { Fail "resource '$resourceId' is outside the adapter ownership record" } + [void](String-Value (Property $resource 'type' 'result.resources entry') 'result resource type') + $resourcePathProperty = $resource.PSObject.Properties['path'] + if ($null -ne $resourcePathProperty) { + if (-not (Is-Within (String-Value $resourcePathProperty.Value 'result resource path') (String-Value (Property $assignment.constraints.worktree 'path' 'assignment worktree') 'assignment worktree path'))) { + Fail "resource '$resourceId' path is outside the worktree" + } + } +} + +$artifacts = @((Property $result 'artifacts' 'result')) +foreach ($artifact in $artifacts) { + if ($null -eq $artifact -or $artifact -isnot [PSCustomObject]) { Fail 'result.artifacts entries must be objects' } + $path = String-Value (Property $artifact 'path' 'result.artifact') 'result artifact path' + if (-not (Is-Within $path $artifactRoot)) { Fail "artifact path is outside artifact_root: $path" } + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { Fail "artifact does not exist: $path" } + if ((Property $artifact 'verified' 'result.artifact') -ne $false) { Fail 'adapter cannot claim an artifact is verified' } + [void](String-Value (Property $artifact 'kind' 'result.artifact') 'result artifact kind') + [void](String-Value (Property $artifact 'sha256' 'result.artifact') 'result artifact sha256') +} + +$model = Property $result 'model_selection' 'result' +[void](String-Value (Property $model 'provider' 'result.model_selection') 'result model provider') +[void](String-Value (Property $model 'model_id' 'result.model_selection') 'result model id') +[void](String-Value (Property $model 'selection_reason' 'result.model_selection') 'result model selection reason') +$exit = Property $result 'exit' 'result' +if ((Property $exit 'code' 'result.exit') -isnot [int] -and (Property $exit 'code' 'result.exit') -isnot [long]) { Fail 'result.exit.code must be an integer' } +$publication = Property $result 'publication' 'result' +if ((String-Value (Property $publication 'status' 'result.publication') 'result publication status') -ne 'unpublished') { Fail 'adapter cannot publish a result' } + +@{ contract_version = 1; status = 'accepted-for-orchestrator-verification'; assignment_id = $assignmentId } | ConvertTo-Json -Compress +exit 0 diff --git a/scripts/check-worker-adapter.sh b/scripts/check-worker-adapter.sh new file mode 100644 index 0000000..f22c84a --- /dev/null +++ b/scripts/check-worker-adapter.sh @@ -0,0 +1,99 @@ +#!/usr/bin/env bash +# Validate the vendor-neutral worker adapter assignment/result boundary. + +set -euo pipefail + +fail() { + printf 'ERROR: %s\n' "$1" >&2 + exit 2 +} + +if [ "$#" -ne 4 ] || [ "$1" != '--assignment' ] || [ "$3" != '--result' ]; then + printf 'Usage: check-worker-adapter.sh --assignment FILE --result FILE\n' >&2 + exit 2 +fi + +assignment_path=$2 +result_path=$4 +[ -f "$assignment_path" ] || fail "assignment does not exist: $assignment_path" +[ -f "$result_path" ] || fail "result does not exist: $result_path" +jq -e 'type == "object"' "$assignment_path" >/dev/null 2>&1 || fail 'assignment is not a JSON object' +jq -e 'type == "object"' "$result_path" >/dev/null 2>&1 || fail 'result is not a JSON object' + +contract_version=$(jq -r '.contract_version // empty' "$assignment_path") +[ "$contract_version" = '1' ] || fail 'assignment contract_version must be 1' +result_version=$(jq -r '.contract_version // empty' "$result_path") +[ "$result_version" = '1' ] || fail 'result contract_version must be 1' + +assignment_id=$(jq -r '.assignment_id // empty' "$assignment_path") +[ -n "$assignment_id" ] || fail 'assignment.assignment_id must be a non-empty string' +[ "$(jq -r '.assignment_id // empty' "$result_path")" = "$assignment_id" ] || fail 'result assignment_id does not match assignment' +jq -e '(.request.prompt | type == "string" and length > 0)' "$assignment_path" >/dev/null || fail 'assignment.request.prompt must be a non-empty string' + +jq -e ' + (.constraints | type == "object") and + (.constraints.tools | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraints.permissions | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraints.owned_paths | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraints.frozen_paths | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraints.cleanup_resource_ids | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraints.worktree | type == "object" and (.id | type == "string" and length > 0) and (.path | type == "string" and length > 0)) and + (.constraints.artifact_root | type == "string" and length > 0) +' "$assignment_path" >/dev/null || fail 'assignment constraints are incomplete or malformed' + +jq -e ' + (.constraint_snapshot | type == "object") and + (.constraint_snapshot.tools | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraint_snapshot.permissions | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraint_snapshot.owned_paths | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraint_snapshot.frozen_paths | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraint_snapshot.cleanup_resource_ids | type == "array" and all(.[]; type == "string" and length > 0)) and + (.constraint_snapshot.worktree | type == "object" and (.id | type == "string" and length > 0) and (.path | type == "string" and length > 0)) and + (.constraint_snapshot.artifact_root | type == "string" and length > 0) +' "$result_path" >/dev/null || fail 'result constraint_snapshot is incomplete or malformed' + +jq -e -s ' + .[0] as $a | .[1] as $r | + ($a.constraints) as $g | ($r.constraint_snapshot) as $u | + (all($u.tools[]; . as $item | ($g.tools | index($item)) != null)) and + (all($u.permissions[]; . as $item | ($g.permissions | index($item)) != null)) and + (all($u.owned_paths[]; . as $item | any($g.owned_paths[]; . as $grant | $item == $grant or ($item | startswith($grant + "/"))))) and + (all($u.frozen_paths[]; . as $item | any($g.frozen_paths[]; . as $grant | $item == $grant or ($item | startswith($grant + "/"))))) and + (all($u.cleanup_resource_ids[]; . as $item | ($g.cleanup_resource_ids | index($item)) != null)) and + ($u.worktree.id == $g.worktree.id) and ($u.worktree.path == $g.worktree.path) and + ($u.artifact_root == $g.artifact_root) +' "$assignment_path" "$result_path" >/dev/null || fail 'result widens or changes assignment constraints' + +status=$(jq -r '.status // empty' "$result_path") +case "$status" in succeeded|failed|cancelled|malformed) ;; *) fail "result.status '$status' is not supported" ;; esac + +ownership_ids=$(jq -r '.ownership.resource_ids[]? // empty' "$result_path" | tr -d '\r') +jq -e '.ownership.resource_ids | type == "array" and all(.[]; type == "string" and length > 0)' "$result_path" >/dev/null || fail 'result.ownership.resource_ids is malformed' +jq -e '.resources | type == "array" and all(.[]; type == "object" and (.type | type == "string" and length > 0) and (.id | type == "string" and length > 0))' "$result_path" >/dev/null || fail 'result.resources is malformed' +worktree_path=$(jq -r '.constraints.worktree.path' "$assignment_path") +while IFS= read -r resource_id; do + resource_id=${resource_id//$'\r'/} + [ -z "$resource_id" ] && continue + grep -Fqx "$resource_id" <<<"$ownership_ids" || fail "resource '$resource_id' is outside the adapter ownership record" +done < <(jq -r '.resources[].id' "$result_path") +while IFS= read -r resource_path; do + resource_path=${resource_path//$'\r'/} + [ -z "$resource_path" ] && continue + case "$resource_path" in + "$worktree_path"|"$worktree_path"/*) ;; + *) fail "resource path is outside the worktree: $resource_path" ;; + esac +done < <(jq -r '.resources[] | .path? // empty' "$result_path") + +artifact_root=$(jq -r '.constraints.artifact_root' "$assignment_path") +while IFS= read -r artifact; do + artifact=${artifact//$'\r'/} + [ -n "$artifact" ] || fail 'result artifact path must be a non-empty string' + case "$artifact" in "$artifact_root"|"$artifact_root"/*) ;; *) fail "artifact path is outside artifact_root: $artifact" ;; esac + [ -f "$artifact" ] || fail "artifact does not exist: $artifact" +done < <(jq -r '.artifacts[] | .path // empty' "$result_path") +jq -e '.artifacts | type == "array" and all(.[]; type == "object" and (.path | type == "string" and length > 0) and (.kind | type == "string" and length > 0) and (.sha256 | type == "string" and length > 0) and (.verified == false))' "$result_path" >/dev/null || fail 'result.artifacts is malformed or claims adapter verification' + +jq -e '(.model_selection | type == "object" and (.provider | type == "string" and length > 0) and (.model_id | type == "string" and length > 0) and (.selection_reason | type == "string" and length > 0)) and (.exit.code | type == "number" and floor == .) and (.publication.status == "unpublished")' "$result_path" >/dev/null || fail 'result model, exit, or publication metadata is malformed' + +jq -cn --arg id "$assignment_id" '{contract_version: 1, status: "accepted-for-orchestrator-verification", assignment_id: $id}' diff --git a/tests/test_worker_adapter_contract.ps1 b/tests/test_worker_adapter_contract.ps1 new file mode 100644 index 0000000..4cf57e8 --- /dev/null +++ b/tests/test_worker_adapter_contract.ps1 @@ -0,0 +1,151 @@ +#!/usr/bin/env pwsh +# Acceptance coverage for the vendor-neutral worker adapter contract. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$root = Split-Path -Parent $PSScriptRoot +$contract = Join-Path $root 'docs/worker-adapter-contract.md' +$checker = Join-Path $root 'scripts/check-worker-adapter.ps1' + +if (-not (Test-Path -LiteralPath $contract -PathType Leaf)) { + throw 'worker adapter contract document is missing' +} +if (-not (Test-Path -LiteralPath $checker -PathType Leaf)) { + throw 'worker adapter result checker is missing' +} + +$scratch = Join-Path ([IO.Path]::GetTempPath()) ('offload-adapter-test-' + [Guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $scratch -Force | Out-Null +try { + $artifactRoot = Join-Path $scratch 'artifacts' + New-Item -ItemType Directory -Path $artifactRoot -Force | Out-Null + $artifact = Join-Path $artifactRoot 'result.json' + [IO.File]::WriteAllText($artifact, '{"ok":true}') + + $assignmentPath = Join-Path $scratch 'assignment.json' + $resultPath = Join-Path $scratch 'result.json' + @{ + contract_version = 1 + assignment_id = 'fake-success' + request = @{ prompt = 'return the fixture' } + constraints = @{ + tools = @('read') + permissions = @('repo.read') + owned_paths = @('src') + frozen_paths = @('tests/test_worker_adapter_contract.ps1') + worktree = @{ id = 'fake-worktree'; path = $scratch } + artifact_root = $artifactRoot + cleanup_resource_ids = @('process:fake-success', 'worktree:fake-worktree') + } + } | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $assignmentPath + @{ + contract_version = 1 + assignment_id = 'fake-success' + status = 'succeeded' + artifacts = @(@{ path = $artifact; kind = 'result'; sha256 = 'not-checked-by-adapter'; verified = $false }) + resources = @( + @{ type = 'process'; id = 'process:fake-success' } + @{ type = 'worktree'; id = 'worktree:fake-worktree'; path = $scratch } + ) + ownership = @{ resource_ids = @('process:fake-success', 'worktree:fake-worktree') } + model_selection = @{ provider = 'fake'; model_id = 'fake-model'; selection_reason = 'fixture' } + constraint_snapshot = @{ + tools = @('read') + permissions = @('repo.read') + owned_paths = @('src') + frozen_paths = @('tests/test_worker_adapter_contract.ps1') + worktree = @{ id = 'fake-worktree'; path = $scratch } + artifact_root = $artifactRoot + cleanup_resource_ids = @('process:fake-success', 'worktree:fake-worktree') + } + exit = @{ code = 0; signal = $null } + publication = @{ status = 'unpublished' } + } | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + + function Invoke-Case([string]$name, [scriptblock]$writeResult, [bool]$expectedPass) { + & $writeResult + & pwsh -NoProfile -NonInteractive -File $checker --assignment $assignmentPath --result $resultPath *> $null + $actualPass = $LASTEXITCODE -eq 0 + if ($actualPass -ne $expectedPass) { + throw "$name expected pass=$expectedPass, got pass=$actualPass" + } + Write-Output "ok - $name" + } + + $valid = Get-Content -LiteralPath $resultPath -Raw | ConvertFrom-Json + Invoke-Case 'fake adapter success result satisfies the contract' { + $valid | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $true + + foreach ($status in @('failed', 'cancelled', 'malformed')) { + Invoke-Case "fake adapter $status result is normalized" { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.status = $status + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $true + } + + Invoke-Case 'empty result collections are valid' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.status = 'failed' + $case.artifacts = @() + $case.resources = @() + $case.ownership.resource_ids = @() + $case.constraint_snapshot.tools = @() + $case.constraint_snapshot.permissions = @() + $case.constraint_snapshot.owned_paths = @() + $case.constraint_snapshot.frozen_paths = @() + $case.constraint_snapshot.cleanup_resource_ids = @() + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $true + + Invoke-Case 'scalar result collection is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.constraint_snapshot.tools = 'read' + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'malformed adapter output is rejected' { + Set-Content -LiteralPath $resultPath -Value '{not-json' + } $false + + Invoke-Case 'execution-scope artifact violation is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.artifacts[0].path = Join-Path $scratch 'outside.json' + Set-Content -LiteralPath $case.artifacts[0].path -Value 'outside' + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'tool widening is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.constraint_snapshot.tools = @('read', 'execute') + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'unowned resource is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.resources[0].id = 'process:outside' + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'resource outside worktree is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.resources[1].path = Join-Path ([IO.Path]::GetTempPath()) 'outside-worktree' + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'verified artifact claim is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.artifacts[0].verified = $true + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false + + Invoke-Case 'adapter publication claim is rejected' { + $case = $valid | ConvertTo-Json -Depth 8 | ConvertFrom-Json + $case.publication.status = 'published' + $case | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $resultPath + } $false +} finally { + Remove-Item -LiteralPath $scratch -Recurse -Force -ErrorAction SilentlyContinue +} diff --git a/tests/test_worker_adapter_contract.sh b/tests/test_worker_adapter_contract.sh new file mode 100644 index 0000000..1995c0c --- /dev/null +++ b/tests/test_worker_adapter_contract.sh @@ -0,0 +1,108 @@ +#!/usr/bin/env bash +# Acceptance coverage for the vendor-neutral worker adapter contract. + +set -euo pipefail + +ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +CHECKER="$ROOT/scripts/check-worker-adapter.sh" +TMP_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/offload-adapter-test.XXXXXX") +trap 'rm -rf "$TMP_ROOT"' EXIT + +fail() { printf 'FAIL: %s\n' "$1" >&2; exit 1; } +pass() { printf 'ok - %s\n' "$1"; } + +[ -f "$ROOT/docs/worker-adapter-contract.md" ] || fail 'worker adapter contract document is missing' +[ -x "$CHECKER" ] || fail 'worker adapter result checker is not executable' + +ARTIFACT_ROOT="$TMP_ROOT/artifacts" +mkdir -p "$ARTIFACT_ROOT" +ARTIFACT="$ARTIFACT_ROOT/result.json" +printf '%s\n' '{"ok":true}' > "$ARTIFACT" +ASSIGNMENT="$TMP_ROOT/assignment.json" +RESULT="$TMP_ROOT/result.json" +VALID_RESULT="$TMP_ROOT/valid-result.json" + +jq -n --arg worktree "$TMP_ROOT" --arg root "$ARTIFACT_ROOT" ' + {contract_version: 1, assignment_id: "fake-success", request: {prompt: "return the fixture"}, constraints: { + tools: ["read"], permissions: ["repo.read"], owned_paths: ["src"], + frozen_paths: ["tests/test_worker_adapter_contract.sh"], + worktree: {id: "fake-worktree", path: $worktree}, artifact_root: $root, + cleanup_resource_ids: ["process:fake-success", "worktree:fake-worktree"] + }} +' > "$ASSIGNMENT" + +jq -n --arg artifact "$ARTIFACT" --arg worktree "$TMP_ROOT" --arg root "$ARTIFACT_ROOT" ' + {contract_version: 1, assignment_id: "fake-success", status: "succeeded", + artifacts: [{path: $artifact, kind: "result", sha256: "not-checked-by-adapter", verified: false}], + resources: [{type: "process", id: "process:fake-success"}, {type: "worktree", id: "worktree:fake-worktree", path: $worktree}], + ownership: {resource_ids: ["process:fake-success", "worktree:fake-worktree"]}, + constraint_snapshot: {tools: ["read"], permissions: ["repo.read"], owned_paths: ["src"], + frozen_paths: ["tests/test_worker_adapter_contract.sh"], worktree: {id: "fake-worktree", path: $worktree}, + artifact_root: $root, cleanup_resource_ids: ["process:fake-success", "worktree:fake-worktree"]}, + model_selection: {provider: "fake", model_id: "fake-model", selection_reason: "fixture"}, + exit: {code: 0, signal: null}, publication: {status: "unpublished"}} +' > "$RESULT" +cp "$RESULT" "$VALID_RESULT" + +run_case() { + local name=$1 expected=$2 + local diagnostic="$TMP_ROOT/diagnostic" + set +e + "$CHECKER" --assignment "$ASSIGNMENT" --result "$RESULT" >"$diagnostic" 2>&1 + local actual=$? + set -e + [ "$actual" -eq "$expected" ] || fail "$name expected exit $expected, got $actual: $(tr '\n' ' ' < "$diagnostic")" + pass "$name" +} + +run_case 'fake adapter success result satisfies the contract' 0 +for status in failed cancelled malformed; do + cp "$VALID_RESULT" "$RESULT" + jq --arg status "$status" '.status = $status' "$RESULT" > "$RESULT.tmp" + mv "$RESULT.tmp" "$RESULT" + run_case "fake adapter $status result is normalized" 0 +done + +cp "$VALID_RESULT" "$RESULT" +jq '.status = "failed" | .artifacts = [] | .resources = [] | .ownership.resource_ids = [] | .constraint_snapshot.tools = [] | .constraint_snapshot.permissions = [] | .constraint_snapshot.owned_paths = [] | .constraint_snapshot.frozen_paths = [] | .constraint_snapshot.cleanup_resource_ids = []' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'empty result collections are valid' 0 + +cp "$VALID_RESULT" "$RESULT" +jq '.constraint_snapshot.tools = "read"' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'scalar result collection is rejected' 2 + +printf '%s\n' '{not-json' > "$RESULT" +run_case 'malformed adapter output is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq -n --arg artifact "$TMP_ROOT/outside.json" --arg worktree "$TMP_ROOT" --arg root "$ARTIFACT_ROOT" ' + {contract_version: 1, assignment_id: "fake-success", status: "succeeded", artifacts: [{path: $artifact, kind: "result", sha256: "x", verified: false}], + resources: [], ownership: {resource_ids: []}, constraint_snapshot: {tools: ["read"], permissions: ["repo.read"], owned_paths: ["src"], frozen_paths: ["tests/test_worker_adapter_contract.sh"], worktree: {id: "fake-worktree", path: $worktree}, artifact_root: $root, cleanup_resource_ids: []}, model_selection: {provider: "fake", model_id: "fake", selection_reason: "fixture"}, exit: {code: 0}, publication: {status: "unpublished"}} +' > "$RESULT" +run_case 'execution-scope artifact violation is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq --argjson tools '["read", "execute"]' '.constraint_snapshot.tools = $tools' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'tool widening is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq --argjson cleanup '["process:fake-success", "worktree:fake-worktree", "process:outside"]' '.constraint_snapshot.cleanup_resource_ids = $cleanup' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'cleanup ownership widening is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq '.resources = [{type: "process", id: "process:outside"}] | .ownership.resource_ids = ["process:fake-success"]' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'unowned resource is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq --arg outside "$(dirname "$TMP_ROOT")/outside-worktree" '.resources[1].path = $outside' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'resource outside worktree is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq '.artifacts[0].verified = true' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'verified artifact claim is rejected' 2 + +cp "$VALID_RESULT" "$RESULT" +jq '.publication.status = "published"' "$RESULT" > "$RESULT.tmp" && mv "$RESULT.tmp" "$RESULT" +run_case 'adapter publication claim is rejected' 2 + +pass 'bash fake adapter contract cases completed' diff --git a/tests/test_workflow_static.ps1 b/tests/test_workflow_static.ps1 index 808960e..5521049 100644 --- a/tests/test_workflow_static.ps1 +++ b/tests/test_workflow_static.ps1 @@ -200,5 +200,31 @@ Assert-True ($skillContent -match 'schema_version: 1, attempts:') "SKILL.md docu Assert-True ($webContent -match 'tests/fixtures/routing-worker\.json') "web-research.md links to routing fixture" Assert-True ($webContent -match 'schema_version: 1, attempts:') "web-research.md documents routing container contract" +# 12. Vendor-neutral worker adapter boundary (Issue #31) +$AdapterDoc = Join-Path $RootDir 'docs/worker-adapter-contract.md' +$AdapterCheckerPs = Join-Path $RootDir 'scripts/check-worker-adapter.ps1' +$AdapterCheckerSh = Join-Path $RootDir 'scripts/check-worker-adapter.sh' +Assert-True (Test-Path -LiteralPath $AdapterDoc -PathType Leaf) "adapter: contract document exists" +Assert-True (Test-Path -LiteralPath $AdapterCheckerPs -PathType Leaf) "adapter: PowerShell checker exists" +Assert-True (Test-Path -LiteralPath $AdapterCheckerSh -PathType Leaf) "adapter: Bash checker exists" +$adapterContent = Get-Content -LiteralPath $AdapterDoc -Raw +foreach ($term in @('orchestrator', 'worker', 'adapter', 'execution scope check')) { + Assert-True ($adapterContent -match [regex]::Escape($term)) "adapter: contract uses '$term'" +} +foreach ($phrase in @( + 'discover-capabilities', + 'discover-models', + 'constraint_snapshot', + 'model_selection', + 'ownership', + 'unpublished', + 'cannot widen' +)) { + Assert-True ($adapterContent -match [regex]::Escape($phrase)) "adapter: contract documents '$phrase'" +} +Assert-True ($skillContent -match 'worker-adapter-contract\.md') "skill: links to worker adapter contract" +Assert-True ($execContent -match 'check-worker-adapter\.ps1' -and $execContent -match 'check-worker-adapter\.sh') "execution.md validates normalized adapter results" +Assert-False ($adapterContent -match '(?i)grill-with-docs[^\n]*(agy|gemini|codex|claude)') "adapter: host skill guidance is vendor-neutral" + [Console]::Out.WriteLine("all workflow static checks passed ($script:TotalTests tests)") exit 0 From 0dcbbf39e2186ca978f999b00edc74b07f3eb78f Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 17:24:18 +0800 Subject: [PATCH 04/11] Add Codex worker adapter --- .github/workflows/ci.yml | 9 + README.md | 6 + docs/codex-adapter.md | 90 ++++++++++ scripts/run-codex-json.ps1 | 307 +++++++++++++++++++++++++++++++++++ scripts/run-codex-json.sh | 200 +++++++++++++++++++++++ tests/test_codex_adapter.ps1 | 239 +++++++++++++++++++++++++++ 6 files changed, 851 insertions(+) create mode 100644 docs/codex-adapter.md create mode 100644 scripts/run-codex-json.ps1 create mode 100644 scripts/run-codex-json.sh create mode 100644 tests/test_codex_adapter.ps1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 05e7e7b..41f3c51 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,6 +20,9 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Check Codex adapter syntax + run: bash -n scripts/run-codex-json.sh + macos-bash: name: macOS Bash contract suite runs-on: macos-latest @@ -33,6 +36,9 @@ jobs: - name: Run execution scope suite run: bash tests/test_execution_scope.sh + - name: Check Codex adapter syntax + run: bash -n scripts/run-codex-json.sh + windows-powershell: name: Windows PowerShell contract suite runs-on: windows-latest @@ -48,3 +54,6 @@ jobs: - name: Run execution scope suite run: pwsh -File tests/test_execution_scope.ps1 + + - name: Run Codex adapter suite + run: pwsh -File tests/test_codex_adapter.ps1 diff --git a/README.md b/README.md index 2436edb..daa44fd 100644 --- a/README.md +++ b/README.md @@ -330,8 +330,14 @@ bash tests/test_execution_scope.sh ```powershell pwsh -File tests/test_research_helpers.ps1 pwsh -File tests/test_execution_scope.ps1 +pwsh -File tests/test_codex_adapter.ps1 ``` +The Codex worker boundary is documented in docs/codex-adapter.md. It discovers +the installed CLI structured-output support and selects models from the +host-provided CODEX_MODEL_CATALOG. It fails closed when either capability is +unavailable. + ## Findings about agy - **`agy` default `--print-timeout` is 5 minutes.** On expiry it writes no output at all. `offload` passes `--print-timeout 20m`. diff --git a/docs/codex-adapter.md b/docs/codex-adapter.md new file mode 100644 index 0000000..bcdd4ab --- /dev/null +++ b/docs/codex-adapter.md @@ -0,0 +1,90 @@ +# Codex adapter + +The Codex adapter is a vendor-neutral worker boundary for hosts that provide the +Codex CLI. It has PowerShell and Bash entry points: + +```text +scripts/run-codex-json.ps1 capabilities --output +scripts/run-codex-json.ps1 run --assignment --output --error + +bash scripts/run-codex-json.sh capabilities --output +bash scripts/run-codex-json.sh run --assignment --output --error +``` + +The Bash entry point requires Bash 3.2 or newer and `jq`; the PowerShell entry +point requires PowerShell 7 or newer. + +The adapter accepts an assignment document with `schema_version: 1`, +`assignment_id`, `prompt`, `worktree`, `preference`, `effort`, `timeout_seconds`, +`scope_check`, and `final_gate`. The optional +`parent_assignment_id`, `depth`, `attempt`, `resume_session_id`, `model_id`, and +`resource_ledger` fields carry lifecycle and ownership state from the caller. + +## Capability discovery + +`capabilities` probes the installed Codex CLI for the structured execution flags +used by the adapter: `--json`, `--output-schema`, and `--output-last-message`. It also reads the +host-provided `CODEX_MODEL_CATALOG` environment variable. The variable may contain a JSON +document or a path to one: + +```json +{ + "revision": "host-catalog-1", + "models": [ + { + "id": "host-selected-model", + "preference": "balanced", + "efforts": ["low", "medium", "high"] + } + ] +} +``` + +The catalog is deliberately supplied by the host. The adapter does not publish +or embed model IDs. `fast`, `balanced`, and `deep` are the stable internal preferences; the adapter +selects a matching available model deterministically. If the CLI flags or +catalog are unavailable, the adapter writes a normalized unsupported result and +exits nonzero. + +## Security and lifecycle boundary + +The adapter owns the native Codex invocation and always supplies these fixed +constraints: + +- `exec --json --ephemeral` +- `--cd ` +- `--sandbox workspace-write` +- `--ask-for-approval never` +- `--output-schema ` +- `--output-last-message ` + +Callers cannot inject native worker flags through the assignment. A worker +response containing a child-assignment request is recorded under +`orchestrator_requests`; the adapter never dispatches it. Assignment depth +and attempt values are validated before launch. + +Every worktree, process, and adapter artifact is appended to the JSONL resource +ledger with the assignment ID and an ownership marker. The normalized result +records process identity, selected model, artifacts, cancellation, timeout, +quota handoff, malformed output, scope-check, and final-gate outcomes. +Cancellation and timeout stop the native process. Retry, quota handoff, and +resume scheduling remain decisions of the shared lifecycle coordinator, which +passes the next attempt or resume session back to this adapter. + +The adapter only returns `completed` after both the declared scope check and +final gate pass. Scope failure and gate failure are caller-visible failures and +do not expose the worker's structured result as a successful result. + +## Tested and unavailable features + +The deterministic PowerShell acceptance test covers capability discovery, +successful structured output, malformed output, cancellation, scope failure, +quota handoff, and fail-closed capability discovery. The Bash entry point is +syntax-checked in CI and uses the same assignment and result contract. + +The Codex CLI does not provide a portable model-catalog command for this +adapter, so hosts must provide `CODEX_MODEL_CATALOG`. The adapter does not +offer concurrency, nested dispatch, or independent worktree cleanup. Those +operations belong to the shared lifecycle and resource-ledger services. A +missing service or unsupported host capability is reported as an explicit +failure instead of being inferred or silently widened. diff --git a/scripts/run-codex-json.ps1 b/scripts/run-codex-json.ps1 new file mode 100644 index 0000000..2c72087 --- /dev/null +++ b/scripts/run-codex-json.ps1 @@ -0,0 +1,307 @@ +#!/usr/bin/env pwsh +# scripts/run-codex-json.ps1 +# Secure Codex adapter. The orchestrator owns assignment limits and verification. + +$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: run-codex-json.ps1 capabilities --output FILE [--error FILE] [--codex PATH]") + [Console]::Error.WriteLine(" run-codex-json.ps1 run --assignment FILE --output FILE --error FILE [--codex PATH] [--cancel-file FILE]") +} + +function FullPath([string]$Path) { + return [System.IO.Path]::GetFullPath($Path) +} + +function Ensure-Parent([string]$Path) { + $parent = [System.IO.Path]::GetDirectoryName((FullPath $Path)) + if (-not [string]::IsNullOrWhiteSpace($parent) -and -not [System.IO.Directory]::Exists($parent)) { + [System.IO.Directory]::CreateDirectory($parent) | Out-Null + } +} + +function Write-Json([string]$Path, $Value) { + Ensure-Parent $Path + $json = $Value | ConvertTo-Json -Depth 30 + [System.IO.File]::WriteAllText((FullPath $Path), "$json`n", [System.Text.UTF8Encoding]::new($false)) +} + +function Read-Json([string]$Path) { + if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { throw "JSON file does not exist: $Path" } + return Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -Depth 30 -ErrorAction Stop +} + +function Resolve-Executable([string]$Requested) { + if (-not [string]::IsNullOrWhiteSpace($Requested)) { + $cmd = Get-Command $Requested -ErrorAction SilentlyContinue + if ($cmd) { + if ($cmd.Source) { return $cmd.Source } + return $cmd.Name + } + if (Test-Path -LiteralPath $Requested -PathType Leaf) { return (Resolve-Path -LiteralPath $Requested).Path } + throw "Codex executable does not exist: $Requested" + } + $cmd = Get-Command codex -ErrorAction SilentlyContinue + if ($cmd) { + if ($cmd.Source) { return $cmd.Source } + return $cmd.Name + } + throw 'Codex executable was not found on PATH' +} + +function Invoke-Process([string]$FilePath, [string[]]$Arguments, [string]$WorkingDirectory, [int]$TimeoutSeconds = 30, [string]$CancelFile = '') { + $psi = [System.Diagnostics.ProcessStartInfo]::new() + if ($FilePath.EndsWith('.ps1', [System.StringComparison]::OrdinalIgnoreCase)) { + $psi.FileName = (Get-Process -Id $PID).Path + $psi.ArgumentList.Add('-NoProfile') + $psi.ArgumentList.Add('-File') + $psi.ArgumentList.Add($FilePath) + } else { + $psi.FileName = $FilePath + } + foreach ($arg in $Arguments) { $psi.ArgumentList.Add([string]$arg) } + $psi.WorkingDirectory = $WorkingDirectory + $psi.UseShellExecute = $false + $psi.CreateNoWindow = $true + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + $proc = [System.Diagnostics.Process]::Start($psi) + $stdoutTask = $proc.StandardOutput.ReadToEndAsync() + $stderrTask = $proc.StandardError.ReadToEndAsync() + $watch = [System.Diagnostics.Stopwatch]::StartNew() + $reason = 'completed' + while (-not $proc.HasExited) { + if (-not [string]::IsNullOrWhiteSpace($CancelFile) -and (Test-Path -LiteralPath $CancelFile -PathType Leaf)) { + $reason = 'canceled' + try { $proc.Kill($true) } catch { } + break + } + if ($TimeoutSeconds -gt 0 -and $watch.Elapsed.TotalSeconds -ge $TimeoutSeconds) { + $reason = 'timeout' + try { $proc.Kill($true) } catch { } + break + } + Start-Sleep -Milliseconds 25 + } + try { $proc.WaitForExit() } catch { } + [System.Threading.Tasks.Task]::WaitAll(@($stdoutTask, $stderrTask)) + $result = [pscustomobject]@{ + pid = $proc.Id + exit_code = $proc.ExitCode + stdout = $stdoutTask.Result + stderr = $stderrTask.Result + reason = $reason + } + $proc.Dispose() + return $result +} + +function Get-Catalog { + $source = $env:CODEX_MODEL_CATALOG + if ([string]::IsNullOrWhiteSpace($source)) { return $null } + try { + if (Test-Path -LiteralPath $source -PathType Leaf) { return Read-Json $source } + return $source | ConvertFrom-Json -Depth 20 -ErrorAction Stop + } catch { + return $null + } +} + +function Get-Capabilities([string]$CodexPath, [string]$OutputPath, [string]$ErrorPath) { + $probe = Invoke-Process $CodexPath @('--help') (Get-Location).Path 30 + Ensure-Parent $ErrorPath + [System.IO.File]::WriteAllText((FullPath $ErrorPath), $probe.stderr, [System.Text.UTF8Encoding]::new($false)) + $catalog = Get-Catalog + $models = @() + if ($null -ne $catalog -and $null -ne $catalog.models) { $models = @($catalog.models) } + $efforts = @($models | ForEach-Object { @($_.efforts) } | Where-Object { -not [string]::IsNullOrWhiteSpace([string]$_) } | Sort-Object -Unique) + $help = [string]$probe.stdout + $supported = @('exec') + $structured = $help.Contains('--json') -and $help.Contains('--output-schema') -and $help.Contains('--output-last-message') + if ($probe.exit_code -ne 0 -or -not $structured) { + $reason = if ($probe.exit_code -ne 0) { 'Codex capability probe failed' } else { 'host lacks required structured-output flags' } + $doc = [ordered]@{ + schema_version = 1; vendor = 'codex'; adapter = 'run-codex-json'; supported_tools = $supported + structured_output = [ordered]@{ supported = $false; reason = $reason } + model_availability = [ordered]@{ available = $false; reason = $reason; revision = $null; models = @() } + effort_levels = @(); process_identity = $null; artifacts = @($ErrorPath) + } + Write-Json $OutputPath $doc + return [pscustomobject]@{ document = $doc; exit_code = 1 } + } + $modelAvailable = $models.Count -gt 0 + $modelReason = if ($modelAvailable) { 'host-provided model catalog' } else { 'host does not expose a model catalog' } + $catalogRevision = if ($catalog -and $catalog.PSObject.Properties.Name -contains 'revision') { [string]$catalog.revision } else { $null } + $doc = [ordered]@{ + schema_version = 1; vendor = 'codex'; adapter = 'run-codex-json'; supported_tools = $supported + structured_output = [ordered]@{ supported = $true; format = 'json'; schema = 'orchestrator-assignment-result' } + model_availability = [ordered]@{ available = $modelAvailable; reason = $modelReason; revision = $catalogRevision; models = $models } + effort_levels = $efforts; process_identity = $null; artifacts = @($ErrorPath) + } + Write-Json $OutputPath $doc + return [pscustomobject]@{ document = $doc; exit_code = if ($modelAvailable) { 0 } else { 1 } } +} + +function Select-Model($Catalog, $Assignment) { + $models = @($Catalog.models) + $preference = [string]$Assignment.preference + if ($preference -notin @('fast', 'balanced', 'deep')) { throw "preference must be fast, balanced, or deep: $preference" } + $requestedEffort = if ($Assignment.PSObject.Properties.Name -contains 'effort') { [string]$Assignment.effort } else { '' } + $pinned = '' + if ($Assignment.PSObject.Properties.Name -contains 'model_id') { $pinned = [string]$Assignment.model_id } + if ([string]::IsNullOrWhiteSpace($pinned) -and ($Assignment.PSObject.Properties.Name -contains 'model_selection') -and $Assignment.model_selection) { + if ($Assignment.model_selection.PSObject.Properties.Name -contains 'model_id') { $pinned = [string]$Assignment.model_selection.model_id } + } + $candidates = if ($pinned) { @($models | Where-Object { $_.id -eq $pinned }) } else { @($models | Where-Object { $_.preference -eq $preference }) } + if ($requestedEffort) { $candidates = @($candidates | Where-Object { @($_.efforts) -contains $requestedEffort }) } + if ($candidates.Count -eq 0) { throw "no available Codex model satisfies preference '$preference' and effort '$requestedEffort'" } + $selected = @($candidates | Sort-Object id)[0] + $familyHint = if ($selected.PSObject.Properties.Name -contains 'family_hint') { [string]$selected.family_hint } else { $null } + $catalogRevision = if ($Catalog.PSObject.Properties.Name -contains 'revision') { [string]$Catalog.revision } else { $null } + return [ordered]@{ + vendor = 'codex'; adapter = 'run-codex-json'; model_id = [string]$selected.id; family_hint = $familyHint + preference = $preference; effort = if ($requestedEffort) { $requestedEffort } else { [string]$selected.efforts[0] }; catalog_revision = $catalogRevision + reason = if ($pinned) { 'pinned assignment model' } else { "first deterministic catalog match for $preference" } + } +} + +function Invoke-CommandArray([object[]]$Command, [string]$WorkingDirectory) { + if ($null -eq $Command -or $Command.Count -eq 0) { throw 'verification command is required' } + $path = [string]$Command[0] + $args = @($Command | Select-Object -Skip 1 | ForEach-Object { [string]$_ }) + $res = Invoke-Process (Resolve-Executable $path) $args $WorkingDirectory 0 + return $res +} + +function Add-LedgerRecords([string]$Path, $Assignment, $Resources, [string]$State) { + Ensure-Parent $Path + $parent = if ($Assignment.PSObject.Properties.Name -contains 'parent_assignment_id') { $Assignment.parent_assignment_id } else { $null } + $records = @($Resources | ForEach-Object { + [ordered]@{ schema_version = 1; assignment_id = [string]$Assignment.assignment_id; parent_assignment_id = $parent; resource_type = $_.type; identity = $_.identity; owner_marker = $_.owner_marker; state = $State; timestamp = [DateTime]::UtcNow.ToString('o') } + }) + foreach ($record in $records) { + $line = $record | ConvertTo-Json -Compress -Depth 12 + Add-Content -LiteralPath (FullPath $Path) -Value $line -Encoding utf8 + } +} + +function Run-Assignment([string]$AssignmentPath, [string]$OutputPath, [string]$ErrorPath, [string]$CodexPath, [string]$CancelFile) { + $assignment = Read-Json $AssignmentPath + $worktree = FullPath ([string]$assignment.worktree) + if (-not (Test-Path -LiteralPath $worktree -PathType Container)) { throw "assignment worktree does not exist: $worktree" } + if ([string]$assignment.schema_version -ne '1') { throw 'assignment schema_version must be 1' } + if ([string]$assignment.assignment_id -notmatch '^[A-Za-z0-9._-]+$') { throw 'assignment_id is invalid' } + $depth = if ($assignment.PSObject.Properties.Name -contains 'depth') { [int]$assignment.depth } else { 0 } + if ($depth -lt 0) { throw 'assignment depth cannot be negative' } + $attempt = if ($assignment.PSObject.Properties.Name -contains 'attempt') { [int]$assignment.attempt } else { 1 } + if ($attempt -notin @(1, 2)) { throw 'adapter accepts at most attempt 1 or attempt 2' } + Ensure-Parent $ErrorPath + [System.IO.File]::WriteAllText((FullPath $ErrorPath), '', [System.Text.UTF8Encoding]::new($false)) + $catalog = Get-Catalog + if ($null -eq $catalog -or @($catalog.models).Count -eq 0) { + $doc = [ordered]@{ schema_version = 1; status = 'unsupported'; lifecycle = 'failed'; assignment_id = $assignment.assignment_id; vendor = 'codex'; adapter = 'run-codex-json'; failure = [ordered]@{ kind = 'unsupported-capability'; reason = 'host does not expose a model catalog' }; artifacts = @($ErrorPath); resources = [ordered]@{ process = $null; worktree = $worktree; artifacts = @($ErrorPath) } } + Write-Json $OutputPath $doc + return 1 + } + $probe = Invoke-Process $CodexPath @('--help') $worktree 30 + $structured = [string]$probe.stdout + if ($probe.exit_code -ne 0 -or -not ($structured.Contains('--json') -and $structured.Contains('--output-schema') -and $structured.Contains('--output-last-message'))) { + $reason = if ($probe.exit_code -ne 0) { 'Codex capability probe failed' } else { 'host lacks required structured-output flags' } + [System.IO.File]::WriteAllText((FullPath $ErrorPath), [string]$probe.stderr, [System.Text.UTF8Encoding]::new($false)) + $doc = [ordered]@{ schema_version = 1; status = 'unsupported'; lifecycle = 'failed'; assignment_id = $assignment.assignment_id; vendor = 'codex'; adapter = 'run-codex-json'; failure = [ordered]@{ kind = 'unsupported-capability'; reason = $reason }; artifacts = @($ErrorPath); resources = [ordered]@{ process = $null; worktree = $worktree; artifacts = @($ErrorPath) } } + Write-Json $OutputPath $doc + return 1 + } + $selection = Select-Model $catalog $assignment + $rawOutput = "$OutputPath.raw.jsonl" + $lastMessage = "$OutputPath.last-message.json" + $schemaFile = "$OutputPath.output-schema.json" + $schema = [ordered]@{ type = 'object'; additionalProperties = $true } + Write-Json $schemaFile $schema + $resources = @( + [ordered]@{ type = 'worktree'; identity = $worktree; owner_marker = "offload-assignment:$($assignment.assignment_id)" } + [ordered]@{ type = 'artifact'; identity = (FullPath $rawOutput); owner_marker = "offload-assignment:$($assignment.assignment_id)" } + [ordered]@{ type = 'artifact'; identity = (FullPath $ErrorPath); owner_marker = "offload-assignment:$($assignment.assignment_id)" } + [ordered]@{ type = 'artifact'; identity = (FullPath $lastMessage); owner_marker = "offload-assignment:$($assignment.assignment_id)" } + [ordered]@{ type = 'artifact'; identity = (FullPath $schemaFile); owner_marker = "offload-assignment:$($assignment.assignment_id)" } + ) + Ensure-Parent $rawOutput + $execArgs = @('exec', '--json', '--ephemeral', '--cd', $worktree, '--sandbox', 'workspace-write', '--ask-for-approval', 'never', '--output-schema', (FullPath $schemaFile), '--output-last-message', (FullPath $lastMessage), '--model', $selection.model_id, '--', [string]$assignment.prompt) + $resume = if ($assignment.PSObject.Properties.Name -contains 'resume_session_id') { [string]$assignment.resume_session_id } else { '' } + if ($resume) { $execArgs = @('-C', $worktree, '--sandbox', 'workspace-write', '--ask-for-approval', 'never', 'exec', 'resume', $resume, '--json', '--ephemeral', '--output-schema', (FullPath $schemaFile), '--output-last-message', (FullPath $lastMessage), '--model', $selection.model_id, '--', [string]$assignment.prompt) } + $timeout = if ($assignment.PSObject.Properties.Name -contains 'timeout_seconds') { [int]$assignment.timeout_seconds } else { 30 } + $process = Invoke-Process $CodexPath $execArgs $worktree $timeout $CancelFile + [System.IO.File]::WriteAllText((FullPath $rawOutput), $process.stdout, [System.Text.UTF8Encoding]::new($false)) + Ensure-Parent $ErrorPath + [System.IO.File]::WriteAllText((FullPath $ErrorPath), $process.stderr, [System.Text.UTF8Encoding]::new($false)) + $ledgerPath = if ($assignment.PSObject.Properties.Name -contains 'resource_ledger' -and $assignment.resource_ledger) { FullPath ([string]$assignment.resource_ledger) } else { "$OutputPath.resource-ledger.jsonl" } + $resources += [ordered]@{ type = 'process'; identity = "pid:$($process.pid)"; owner_marker = "offload-assignment:$($assignment.assignment_id)" } + Add-LedgerRecords $ledgerPath $assignment $resources 'running' + $parent = if ($assignment.PSObject.Properties.Name -contains 'parent_assignment_id') { $assignment.parent_assignment_id } else { $null } + $base = [ordered]@{ schema_version = 1; assignment_id = $assignment.assignment_id; parent_assignment_id = $parent; vendor = 'codex'; adapter = 'run-codex-json'; attempt = $attempt; lifecycle = 'running'; model_selection = $selection; process = [ordered]@{ pid = $process.pid; exit_code = $process.exit_code }; resources = [ordered]@{ process = "pid:$($process.pid)"; worktree = $worktree; artifacts = @($resources | Where-Object type -eq 'artifact' | ForEach-Object identity) }; artifacts = @($resources | Where-Object type -eq 'artifact' | ForEach-Object identity); verification = [ordered]@{ scope_check = 'not-run'; final_gate = 'not-run' } } + if ($process.reason -eq 'canceled') { $base.status = 'canceled'; $base.lifecycle = 'canceled'; $base.failure = [ordered]@{ kind = 'canceled'; reason = 'cancel file requested termination' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'canceled'; return 1 } + if ($process.reason -eq 'timeout') { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'timeout'; reason = 'assignment timeout exceeded' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + if ($process.stdout -match '(?i)quota|rate.?limit' -or $process.stderr -match '(?i)quota|rate.?limit') { $base.status = 'quota-handoff'; $base.lifecycle = 'quota-handoff'; $base.failure = [ordered]@{ kind = 'quota'; reason = 'Codex reported quota or rate limit exhaustion' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'quota-handoff'; return 1 } + if (-not (Test-Path -LiteralPath $lastMessage -PathType Leaf)) { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'malformed-output'; reason = 'Codex did not produce the required last-message artifact' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + try { $worker = Read-Json $lastMessage } catch { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'malformed-output'; reason = $_.Exception.Message }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + if ($null -eq $worker -or $worker -isnot [pscustomobject]) { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'malformed-output'; reason = 'last-message artifact must contain a JSON object' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + $workerStatus = if ($worker.PSObject.Properties.Name -contains 'status') { [string]$worker.status } else { '' } + $workerError = if ($worker.PSObject.Properties.Name -contains 'error') { [string]$worker.error } else { '' } + if ($workerStatus -match '(?i)quota|rate.?limit' -or $workerError -match '(?i)quota|rate.?limit') { $base.status = 'quota-handoff'; $base.lifecycle = 'quota-handoff'; $base.failure = [ordered]@{ kind = 'quota'; reason = 'Codex reported quota or rate limit exhaustion' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'quota-handoff'; return 1 } + if ($worker.PSObject.Properties.Name -notcontains 'structured_output' -or $null -eq $worker.structured_output) { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'malformed-output'; reason = 'last-message lacks structured_output' }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + $scope = Invoke-CommandArray @($assignment.scope_check) $worktree + $base.verification.scope_check = if ($scope.exit_code -eq 0) { 'passed' } else { 'failed' } + if ($scope.exit_code -ne 0) { $base.status = 'scope-failure'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'execution-scope'; reason = 'execution scope check failed'; exit_code = $scope.exit_code }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + $gate = Invoke-CommandArray @($assignment.final_gate) $worktree + $base.verification.final_gate = if ($gate.exit_code -eq 0) { 'passed' } else { 'failed' } + if ($gate.exit_code -ne 0) { $base.status = 'failed'; $base.lifecycle = 'failed'; $base.failure = [ordered]@{ kind = 'final-gate'; reason = 'final gate failed'; exit_code = $gate.exit_code }; Write-Json $OutputPath $base; Add-LedgerRecords $ledgerPath $assignment $resources 'failed'; return 1 } + $base.status = 'completed'; $base.lifecycle = 'completed'; $base.structured_output = $worker.structured_output + if ($worker.structured_output.PSObject.Properties.Name -contains 'child_assignment_request') { $base.orchestrator_requests = @($worker.structured_output.child_assignment_request) } + Write-Json $OutputPath $base + Add-LedgerRecords $ledgerPath $assignment $resources 'completed' + return 0 +} + +$mode = '' +$outputPath = '' +$errorPath = '' +$assignmentPath = '' +$codexPath = '' +$cancelFile = '' +$i = 0 +while ($i -lt $args.Count) { + $arg = [string]$args[$i] + if ($arg -in @('capabilities', 'run')) { if ($mode) { Fail 'mode specified more than once' }; $mode = $arg } + elseif ($arg -eq '--output') { $i++; if ($i -ge $args.Count) { Fail '--output requires a path' }; $outputPath = [string]$args[$i] } + elseif ($arg -eq '--error') { $i++; if ($i -ge $args.Count) { Fail '--error requires a path' }; $errorPath = [string]$args[$i] } + elseif ($arg -eq '--assignment') { $i++; if ($i -ge $args.Count) { Fail '--assignment requires a path' }; $assignmentPath = [string]$args[$i] } + elseif ($arg -eq '--codex') { $i++; if ($i -ge $args.Count) { Fail '--codex requires a path' }; $codexPath = [string]$args[$i] } + elseif ($arg -eq '--cancel-file') { $i++; if ($i -ge $args.Count) { Fail '--cancel-file requires a path' }; $cancelFile = [string]$args[$i] } + elseif ($arg -in @('-h', '--help')) { Usage; exit 0 } + else { Fail "unknown option: $arg" } + $i++ +} +if (-not $mode) { Usage; Fail 'mode is required' } +if (-not $outputPath) { Usage; Fail '--output is required' } +if (-not $errorPath) { $errorPath = "$outputPath.err" } +try { + $resolvedCodex = Resolve-Executable $codexPath + if ($mode -eq 'capabilities') { + $cap = Get-Capabilities $resolvedCodex $outputPath $errorPath + exit $cap.exit_code + } + if (-not $assignmentPath) { Fail '--assignment is required for run' } + exit (Run-Assignment $assignmentPath $outputPath $errorPath $resolvedCodex $cancelFile) +} catch { + if ($outputPath) { + $doc = [ordered]@{ schema_version = 1; status = 'failed'; lifecycle = 'failed'; vendor = 'codex'; adapter = 'run-codex-json'; failure = [ordered]@{ kind = 'adapter-error'; reason = $_.Exception.Message }; artifacts = @($errorPath) } + try { Write-Json $outputPath $doc } catch { } + } + Fail $_.Exception.Message 1 +} diff --git a/scripts/run-codex-json.sh b/scripts/run-codex-json.sh new file mode 100644 index 0000000..d252fa7 --- /dev/null +++ b/scripts/run-codex-json.sh @@ -0,0 +1,200 @@ +#!/usr/bin/env bash +set -euo pipefail +fail() { printf 'ERROR: %s\n' "$1" >&2; exit "${2:-2}"; } +usage() { + printf 'Usage: %s capabilities --output FILE [--error FILE] [--codex PATH]\n' "$0" >&2 + printf ' %s run --assignment FILE --output FILE --error FILE [--codex PATH] [--cancel-file FILE]\n' "$0" >&2 +} + +run_assignment() { + local assignment_path="$1" output_path="$2" error_path="$3" codex_path="$4" cancel_file="$5" + local assignment worktree timeout selection raw_output last_message schema_file ledger marker help_probe help_exit=0 + assignment=$(cat "$assignment_path") + jq -e 'type == "object" and .schema_version == 1 and (.assignment_id | type == "string" and test("^[A-Za-z0-9._-]+$")) and ((.depth // 0) >= 0) and (((.attempt // 1) == 1) or ((.attempt // 1) == 2))' <<<"$assignment" >/dev/null || fail 'assignment does not satisfy the adapter contract' 1 + worktree=$(jq -r '.worktree' <<<"$assignment") + [ -d "$worktree" ] || fail "assignment worktree does not exist: $worktree" + timeout=$(jq -r '.timeout_seconds // 30' <<<"$assignment") + marker="offload-assignment:$(jq -r '.assignment_id' <<<"$assignment")" + ensure_parent "$error_path"; : >"$error_path" + if ! valid_catalog; then + write_json "$output_path" "$(jq -cn --arg id "$(jq -r '.assignment_id' <<<"$assignment")" --arg worktree "$worktree" --arg error "$(full_path "$error_path")" '{schema_version:1,status:"unsupported",lifecycle:"failed",assignment_id:$id,vendor:"codex",adapter:"run-codex-json",failure:{kind:"unsupported-capability",reason:"host does not expose a model catalog"},resources:{process:null,worktree:$worktree,artifacts:[$error]},artifacts:[$error]}')" + return 1 + fi + help_probe=$("$codex_path" --help 2>"$error_path") || help_exit="$?" + if [ "$help_exit" -ne 0 ] || [[ "$help_probe" != *--json* ]] || [[ "$help_probe" != *--output-schema* ]] || [[ "$help_probe" != *--output-last-message* ]]; then + local help_reason='host lacks required structured-output flags' + [ "$help_exit" -eq 0 ] || help_reason='Codex capability probe failed' + write_json "$output_path" "$(jq -cn --arg id "$(jq -r '.assignment_id' <<<"$assignment")" --arg worktree "$worktree" --arg error "$(full_path "$error_path")" --arg reason "$help_reason" '{schema_version:1,status:"unsupported",lifecycle:"failed",assignment_id:$id,vendor:"codex",adapter:"run-codex-json",failure:{kind:"unsupported-capability",reason:$reason},resources:{process:null,worktree:$worktree,artifacts:[$error]},artifacts:[$error]}')" + return 1 + fi + selection=$(select_model "$assignment") + raw_output="$output_path.raw.jsonl" + last_message="$output_path.last-message.json" + schema_file="$output_path.output-schema.json" + ledger=$(jq -r '.resource_ledger // empty' <<<"$assignment") + [ -n "$ledger" ] || ledger="$output_path.resource-ledger.jsonl" + write_json "$schema_file" '{"type":"object","additionalProperties":true}' + ensure_parent "$raw_output"; : >"$raw_output"; : >"$error_path" + ledger_record "$ledger" "$assignment" worktree "$worktree" "$marker" running + ledger_record "$ledger" "$assignment" artifact "$(full_path "$raw_output")" "$marker" running + ledger_record "$ledger" "$assignment" artifact "$(full_path "$error_path")" "$marker" running + ledger_record "$ledger" "$assignment" artifact "$(full_path "$last_message")" "$marker" running + ledger_record "$ledger" "$assignment" artifact "$(full_path "$schema_file")" "$marker" running + local model_id prompt resume args + model_id=$(jq -r '.model_id' <<<"$selection") + prompt=$(jq -r '.prompt' <<<"$assignment") + resume=$(jq -r '.resume_session_id // empty' <<<"$assignment") + if [ -n "$resume" ]; then + args=(-C "$worktree" --sandbox workspace-write --ask-for-approval never exec resume "$resume" --json --ephemeral --output-schema "$(full_path "$schema_file")" --output-last-message "$(full_path "$last_message")" --model "$model_id" -- "$prompt") + else + args=(exec --json --ephemeral --cd "$worktree" --sandbox workspace-write --ask-for-approval never --output-schema "$(full_path "$schema_file")" --output-last-message "$(full_path "$last_message")" --model "$model_id" -- "$prompt") + fi + + local process_reason=completed process_exit=0 start now worker_pid + start=$(date +%s) + set +e + (cd "$worktree" && "$codex_path" "${args[@]}") >"$raw_output" 2>"$error_path" & + worker_pid="$!" + set -e + while kill -0 "$worker_pid" >/dev/null 2>&1; do + if [ -n "$cancel_file" ] && [ -f "$cancel_file" ]; then + process_reason=canceled; kill "$worker_pid" >/dev/null 2>&1 || true; break + fi + now=$(date +%s) + if [ "$timeout" -gt 0 ] && [ $((now - start)) -ge "$timeout" ]; then + process_reason=timeout; kill "$worker_pid" >/dev/null 2>&1 || true; break + fi + sleep 0.05 + done + wait "$worker_pid" || process_exit="$?" + ledger_record "$ledger" "$assignment" process "pid:$worker_pid" "$marker" "$process_reason" + local base assignment_id parent_json attempt raw_path error_path_abs last_path schema_path + assignment_id=$(jq -r '.assignment_id' <<<"$assignment") + parent_json=$(jq -c '.parent_assignment_id // null' <<<"$assignment") + attempt=$(jq -r '.attempt // 1' <<<"$assignment") + raw_path=$(full_path "$raw_output"); error_path_abs=$(full_path "$error_path"); last_path=$(full_path "$last_message"); schema_path=$(full_path "$schema_file") + base=$(jq -cn --arg id "$assignment_id" --argjson parent "$parent_json" --argjson selection "$selection" --argjson pid "$worker_pid" --argjson exit "$process_exit" --argjson attempt "$attempt" --arg worktree "$worktree" --arg raw "$raw_path" --arg error "$error_path_abs" --arg last "$last_path" --arg schema "$schema_path" '{schema_version:1,assignment_id:$id,parent_assignment_id:$parent,vendor:"codex",adapter:"run-codex-json",attempt:$attempt,lifecycle:"running",model_selection:$selection,process:{pid:$pid,exit_code:$exit},resources:{process:("pid:" + ($pid|tostring)),worktree:$worktree,artifacts:[$raw,$error,$last,$schema]},artifacts:[$raw,$error,$last,$schema],verification:{scope_check:"not-run",final_gate:"not-run"}}') + if [ "$process_reason" = canceled ]; then + write_json "$output_path" "$(jq '.status="canceled" | .lifecycle="canceled" | .failure={kind:"canceled",reason:"cancel file requested termination"}' <<<"$base")"; return 1 + fi + if [ "$process_reason" = timeout ]; then + write_json "$output_path" "$(jq '.status="failed" | .lifecycle="failed" | .failure={kind:"timeout",reason:"assignment timeout exceeded"}' <<<"$base")"; return 1 + fi + if grep -Eiq 'quota|rate.?limit' "$raw_output" "$error_path"; then + write_json "$output_path" "$(jq '.status="quota-handoff" | .lifecycle="quota-handoff" | .failure={kind:"quota",reason:"Codex reported quota or rate limit exhaustion"}' <<<"$base")"; return 1 + fi + if [ ! -f "$last_message" ] || ! jq -e 'type == "object" and has("structured_output")' "$last_message" >/dev/null 2>&1; then + write_json "$output_path" "$(jq '.status="failed" | .lifecycle="failed" | .failure={kind:"malformed-output",reason:"Codex did not produce a valid structured-output artifact"}' <<<"$base")"; return 1 + fi + + local scope_exit=0 gate_exit=0 + set +e + run_command_array "$(jq -c '.scope_check // []' <<<"$assignment")" "$worktree" + scope_exit="$?" + set -e + if [ "$scope_exit" -eq 0 ]; then base=$(jq '.verification.scope_check="passed"' <<<"$base"); else base=$(jq '.verification.scope_check="failed"' <<<"$base"); fi + if [ "$scope_exit" -ne 0 ]; then + write_json "$output_path" "$(jq --argjson code "$scope_exit" '.status="scope-failure" | .lifecycle="failed" | .failure={kind:"execution-scope",reason:"execution scope check failed",exit_code:$code}' <<<"$base")"; return 1 + fi + set +e + run_command_array "$(jq -c '.final_gate // []' <<<"$assignment")" "$worktree" + gate_exit="$?" + set -e + if [ "$gate_exit" -eq 0 ]; then base=$(jq '.verification.final_gate="passed"' <<<"$base"); else base=$(jq '.verification.final_gate="failed"' <<<"$base"); fi + if [ "$gate_exit" -ne 0 ]; then + write_json "$output_path" "$(jq --argjson code "$gate_exit" '.status="failed" | .lifecycle="failed" | .failure={kind:"final-gate",reason:"final gate failed",exit_code:$code}' <<<"$base")"; return 1 + fi + write_json "$output_path" "$(jq --slurpfile worker "$last_message" '.status="completed" | .lifecycle="completed" | .structured_output=$worker[0].structured_output | if (.structured_output | has("child_assignment_request")) then .orchestrator_requests=[.structured_output.child_assignment_request] else . end' <<<"$base")" +} + +run_command_array() { + local command_json="$1" worktree="$2" arg + local command_args=() + while IFS= read -r arg; do command_args+=("$arg"); done < <(jq -r '.[] | tostring' <<<"$command_json") + [ "${#command_args[@]}" -gt 0 ] || return 2 + (cd "$worktree" && "${command_args[@]}") +} + + +ledger_record() { + local ledger="$1" assignment="$2" type="$3" identity="$4" marker="$5" state="$6" + ensure_parent "$ledger" + jq -cn --arg id "$(jq -r '.assignment_id' <<<"$assignment")" --argjson parent "$(jq -c '.parent_assignment_id // null' <<<"$assignment")" --arg type "$type" --arg identity "$identity" --arg marker "$marker" --arg state "$state" '{schema_version:1,assignment_id:$id,parent_assignment_id:$parent,resource_type:$type,identity:$identity,owner_marker:$marker,state:$state,timestamp:(now | todateiso8601)}' >>"$ledger" +} + + +select_model() { + local assignment="$1" catalog pref effort pinned + catalog=$(catalog_json) || fail 'host does not expose a model catalog' 1 + pref=$(jq -r '.preference // empty' <<<"$assignment") + effort=$(jq -r '.effort // empty' <<<"$assignment") + pinned=$(jq -r '.model_id // .model_selection.model_id // empty' <<<"$assignment") + jq -e --arg p "$pref" --arg e "$effort" --arg m "$pinned" '($p | IN("fast","balanced","deep")) and ([.models[] | select((if $m != "" then .id == $m else .preference == $p end) and ($e == "" or ((.efforts // []) | index($e))))] | length > 0)' <<<"$catalog" >/dev/null || fail 'no available Codex model satisfies assignment preference and effort' 1 + jq -c --arg p "$pref" --arg e "$effort" --arg m "$pinned" '([.models[] | select(if $m != "" then .id == $m else .preference == $p end) | select($e == "" or ((.efforts // []) | index($e)))] | sort_by(.id) | .[0]) as $model | {vendor:"codex",adapter:"run-codex-json",model_id:$model.id,family_hint:($model.family_hint // null),preference:$p,effort:(if $e != "" then $e else ($model.efforts[0] // null) end),catalog_revision:(.revision // null),reason:(if $m != "" then "pinned assignment model" else "first deterministic catalog match for " + $p end)}' <<<"$catalog" +} + +full_path() { + case "$1" in + /*) printf '%s\n' "$1" ;; + *) printf '%s/%s\n' "$(cd "$(dirname "$1")" && pwd)" "$(basename "$1")" ;; + esac +} +ensure_parent() { mkdir -p "$(dirname "$1")"; } +resolve_codex() { + if [ -n "$1" ] && [ -x "$1" ]; then full_path "$1" + elif [ -n "$1" ] && command -v "$1" >/dev/null 2>&1; then command -v "$1" + elif [ -z "$1" ] && command -v codex >/dev/null 2>&1; then command -v codex + else fail 'Codex executable was not found or is not executable' 1 + fi +} +catalog_json() { + [ -n "${CODEX_MODEL_CATALOG:-}" ] || return 1 + if [ -f "$CODEX_MODEL_CATALOG" ]; then cat "$CODEX_MODEL_CATALOG"; else printf '%s\n' "$CODEX_MODEL_CATALOG"; fi +} +valid_catalog() { + catalog_json 2>/dev/null | jq -e 'type == "object" and (.models | type == "array") and (.models | length > 0)' >/dev/null 2>&1 +} +write_json() { ensure_parent "$1"; printf '%s\n' "$2" >"$1"; } + +capabilities() { + local output="$1" error="$2" codex="$3" help_file error_file probe_exit=0 help_text catalog='' models='[]' efforts='[]' available=false reason document + help_file=$(mktemp "${TMPDIR:-/tmp}/offload-codex-help.XXXXXX") + error_file=$(mktemp "${TMPDIR:-/tmp}/offload-codex-help-error.XXXXXX") + "$codex" --help >"$help_file" 2>"$error_file" || probe_exit="$?" + help_text=$(<"$help_file"); ensure_parent "$error"; cat "$error_file" >"$error" + if valid_catalog; then + catalog=$(catalog_json); models=$(jq -c '.models' <<<"$catalog"); efforts=$(jq -c '[.models[].efforts[]?] | unique' <<<"$catalog") + available=true; reason='host-provided model catalog' + else reason='host does not expose a model catalog'; fi + if [ "$probe_exit" -ne 0 ] || [[ "$help_text" != *--json* ]] || [[ "$help_text" != *--output-schema* ]] || [[ "$help_text" != *--output-last-message* ]]; then + [ "$probe_exit" -eq 0 ] && reason='host lacks required structured-output flags' || reason='Codex capability probe failed' + document=$(jq -cn --arg reason "$reason" --arg error "$error" '{schema_version:1,vendor:"codex",adapter:"run-codex-json",supported_tools:["exec"],structured_output:{supported:false,reason:$reason},model_availability:{available:false,reason:$reason,revision:null,models:[]},effort_levels:[],process_identity:null,artifacts:[$error]}') + write_json "$output" "$document"; rm -f "$help_file" "$error_file"; return 1 + fi + document=$(jq -cn --argjson models "$models" --argjson efforts "$efforts" --arg reason "$reason" --arg revision "$(jq -r '.revision // empty' <<<"${catalog:-{}}")" --arg error "$error" --argjson available "$available" '{schema_version:1,vendor:"codex",adapter:"run-codex-json",supported_tools:["exec"],structured_output:{supported:true,format:"json",schema:"orchestrator-assignment-result"},model_availability:{available:$available,reason:$reason,revision:($revision // null),models:$models},effort_levels:$efforts,process_identity:null,artifacts:[$error]}') + write_json "$output" "$document"; rm -f "$help_file" "$error_file"; [ "$available" = true ] +} + +mode='' output_path='' error_path='' assignment_path='' codex_path='' cancel_file='' +while [ "$#" -gt 0 ]; do + case "$1" in + capabilities|run) [ -z "$mode" ] || fail 'mode specified more than once'; mode="$1"; shift ;; + --output) [ "$#" -ge 2 ] || fail '--output requires a path'; output_path="$2"; shift 2 ;; + --error) [ "$#" -ge 2 ] || fail '--error requires a path'; error_path="$2"; shift 2 ;; + --assignment) [ "$#" -ge 2 ] || fail '--assignment requires a path'; assignment_path="$2"; shift 2 ;; + --codex) [ "$#" -ge 2 ] || fail '--codex requires a path'; codex_path="$2"; shift 2 ;; + --cancel-file) [ "$#" -ge 2 ] || fail '--cancel-file requires a path'; cancel_file="$2"; shift 2 ;; + -h|--help) usage; exit 0 ;; + *) usage; fail "unknown option: $1" ;; + esac +done +[ -n "$mode" ] || { usage; fail 'mode is required'; } +[ -n "$output_path" ] || { usage; fail '--output is required'; } +error_path="${error_path:-$output_path.err}" +codex_path=$(resolve_codex "$codex_path") +if [ "$mode" = capabilities ]; then + capabilities "$output_path" "$error_path" "$codex_path" +else + [ -n "$assignment_path" ] || fail '--assignment is required for run' + run_assignment "$assignment_path" "$output_path" "$error_path" "$codex_path" "$cancel_file" +fi diff --git a/tests/test_codex_adapter.ps1 b/tests/test_codex_adapter.ps1 new file mode 100644 index 0000000..624ca2e --- /dev/null +++ b/tests/test_codex_adapter.ps1 @@ -0,0 +1,239 @@ +#!/usr/bin/env pwsh +# tests/test_codex_adapter.ps1 +# Contract tests for the Codex worker adapter. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$Root = Split-Path -Parent $PSScriptRoot +$Adapter = Join-Path $Root 'scripts/run-codex-json.ps1' +$TmpRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("offload-codex-adapter-" + [guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $TmpRoot | Out-Null + +function Fail([string]$Message) { + throw "FAIL: $Message" +} + +function Assert-True([bool]$Condition, [string]$Message) { + if (-not $Condition) { Fail $Message } + Write-Output "ok - $Message" +} + +function Assert-Equal($Actual, $Expected, [string]$Message) { + if ($Actual -ne $Expected) { + Fail "$Message (expected '$Expected', got '$Actual')" + } + Write-Output "ok - $Message" +} + +function Write-JsonFile([string]$Path, $Value) { + $Value | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $Path -Encoding utf8 +} + +function Invoke-Tool([string]$FilePath, [string[]]$ArgumentList, [hashtable]$Environment = @{}, [string]$WorkingDirectory = $TmpRoot) { + $psi = [System.Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $FilePath + $psi.WorkingDirectory = $WorkingDirectory + $psi.UseShellExecute = $false + $psi.CreateNoWindow = $true + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + foreach ($arg in $ArgumentList) { $psi.ArgumentList.Add($arg) } + foreach ($entry in $Environment.GetEnumerator()) { + $psi.Environment[$entry.Key] = [string]$entry.Value + } + $proc = [System.Diagnostics.Process]::Start($psi) + $stdout = $proc.StandardOutput.ReadToEnd() + $stderr = $proc.StandardError.ReadToEnd() + $proc.WaitForExit() + return [pscustomobject]@{ ExitCode = $proc.ExitCode; Stdout = $stdout; Stderr = $stderr } +} + +function Invoke-Adapter([string[]]$ArgumentList, [hashtable]$Environment = @{}, [string]$WorkingDirectory = $TmpRoot) { + $pwsh = (Get-Command pwsh).Source + return Invoke-Tool $pwsh (@('-NoProfile', '-NonInteractive', '-File', $Adapter) + $ArgumentList) $Environment $WorkingDirectory +} + +try { + $FakeCodex = Join-Path $TmpRoot 'fake-codex.ps1' + @' +$ArgsList = @($args) +$last = $null +for ($i = 0; $i -lt $ArgsList.Count; $i++) { + if ($ArgsList[$i] -eq '--output-last-message') { $last = $ArgsList[$i + 1] } +} +if ($ArgsList -contains '--help' -or $ArgsList -contains '-h') { + Write-Output 'Codex exec --json --output-schema --output-last-message --sandbox --ask-for-approval --cd' + exit 0 +} +if ($env:FAKE_CODEX_MODE -eq 'sleep') { + while ($true) { Start-Sleep -Milliseconds 50 } +} +if ($env:FAKE_CODEX_MODE -eq 'malformed') { + Set-Content -LiteralPath $last -Value '{not-json' -Encoding utf8 + Write-Output '{"type":"malformed"}' + exit 0 +} +if ($env:FAKE_CODEX_MODE -eq 'quota') { + Set-Content -LiteralPath $last -Value '{"error":"quota exhausted"}' -Encoding utf8 + exit 0 +} +$result = [ordered]@{ status = 'success'; structured_output = [ordered]@{ ok = $true; child_assignment_request = [ordered]@{ prompt = 'do more' } } } +$result | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $last -Encoding utf8 +Write-Output '{"type":"turn.completed"}' +'@ | Set-Content -LiteralPath $FakeCodex -Encoding utf8 + + $FakeScope = Join-Path $TmpRoot 'fake-scope.ps1' + @' +if ($env:FAKE_SCOPE_RESULT -eq 'fail') { exit 1 } +Set-Content -LiteralPath $env:FAKE_SCOPE_MARKER -Value 'scope checked' -Encoding utf8 +exit 0 +'@ | Set-Content -LiteralPath $FakeScope -Encoding utf8 + + $FakeGate = Join-Path $TmpRoot 'fake-gate.ps1' + @' +Set-Content -LiteralPath $env:FAKE_GATE_MARKER -Value 'gate checked' -Encoding utf8 +exit 0 +'@ | Set-Content -LiteralPath $FakeGate -Encoding utf8 + + $pwsh = (Get-Command pwsh).Source + + $Catalog = Join-Path $TmpRoot 'catalog.json' + Write-JsonFile $Catalog ([ordered]@{ + schema_version = 1 + revision = 'fake-catalog-1' + models = @( + [ordered]@{ id = 'fake-fast-model'; preference = 'fast'; efforts = @('low', 'medium') } + [ordered]@{ id = 'fake-balanced-model'; preference = 'balanced'; efforts = @('medium', 'high') } + [ordered]@{ id = 'fake-deep-model'; preference = 'deep'; efforts = @('high') } + ) + }) + + $capOutput = Join-Path $TmpRoot 'capabilities.json' + $cap = Invoke-Adapter @('capabilities', '--output', $capOutput, '--codex', $FakeCodex) @{ CODEX_MODEL_CATALOG = $Catalog } + Assert-Equal $cap.ExitCode 0 'capabilities discovery exits successfully' + $capDoc = Get-Content -LiteralPath $capOutput -Raw | ConvertFrom-Json + Assert-Equal $capDoc.vendor 'codex' 'capabilities report identifies Codex' + Assert-True ($capDoc.supported_tools -contains 'exec') 'capabilities report includes exec tool' + Assert-True ($capDoc.structured_output.supported) 'capabilities report includes structured output support' + Assert-True ($capDoc.model_availability.available) 'capabilities report includes live model availability' + Assert-True ($capDoc.effort_levels -contains 'high') 'capabilities report includes effort levels' + + $worktree = Join-Path $TmpRoot 'worktree' + New-Item -ItemType Directory -Path $worktree | Out-Null + $scopeMarker = Join-Path $TmpRoot 'scope.marker' + $gateMarker = Join-Path $TmpRoot 'gate.marker' + $assignment = Join-Path $TmpRoot 'success-assignment.json' + Write-JsonFile $assignment ([ordered]@{ + schema_version = 1 + assignment_id = 'codex-success-1' + parent_assignment_id = $null + depth = 0 + prompt = 'Return the bounded result.' + worktree = $worktree + owned_paths = @('owned.txt') + frozen_paths = @('tests/test_codex_adapter.ps1') + baseline = 'HEAD' + preference = 'balanced' + effort = 'high' + timeout_seconds = 10 + scope_check = @($pwsh, '-NoProfile', '-File', $FakeScope) + final_gate = @($pwsh, '-NoProfile', '-File', $FakeGate) + artifacts = @() + }) + $resultOutput = Join-Path $TmpRoot 'success-result.json' + $success = Invoke-Adapter @('run', '--assignment', $assignment, '--output', $resultOutput, '--error', (Join-Path $TmpRoot 'success.err'), '--codex', $FakeCodex) @{ + CODEX_MODEL_CATALOG = $Catalog + FAKE_SCOPE_MARKER = $scopeMarker + FAKE_GATE_MARKER = $gateMarker + } $worktree + Assert-Equal $success.ExitCode 0 'successful assignment exits successfully' + $successDoc = Get-Content -LiteralPath $resultOutput -Raw | ConvertFrom-Json + Assert-Equal $successDoc.status 'completed' 'successful assignment returns completed status' + Assert-Equal $successDoc.model_selection.preference 'balanced' 'assignment keeps internal model preference' + Assert-Equal $successDoc.model_selection.model_id 'fake-balanced-model' 'adapter selects catalog model for preference' + Assert-True $successDoc.structured_output.ok 'successful assignment returns structured output' + Assert-True ($successDoc.process.pid -gt 0) 'successful assignment reports process identity' + Assert-Equal $successDoc.verification.scope_check 'passed' 'scope check runs before returning result' + Assert-Equal $successDoc.verification.final_gate 'passed' 'final gate runs before returning result' + Assert-True (Test-Path -LiteralPath $scopeMarker) 'scope check marker proves scope check ran' + Assert-True (Test-Path -LiteralPath $gateMarker) 'final gate marker proves final gate ran' + Assert-True ($successDoc.resources.artifacts.Count -ge 2) 'resource ledger reports worker artifacts' + Assert-True (-not $successDoc.PSObject.Properties.Name.Contains('child_assignment')) 'nested dispatch is not promoted to an assignment' + + $malformedAssignment = Join-Path $TmpRoot 'malformed-assignment.json' + Write-JsonFile $malformedAssignment ((Get-Content -LiteralPath $assignment -Raw | ConvertFrom-Json) | ForEach-Object { $_.assignment_id = 'codex-malformed-1'; $_ }) + $malformedOutput = Join-Path $TmpRoot 'malformed-result.json' + $malformed = Invoke-Adapter @('run', '--assignment', $malformedAssignment, '--output', $malformedOutput, '--error', (Join-Path $TmpRoot 'malformed.err'), '--codex', $FakeCodex) @{ + CODEX_MODEL_CATALOG = $Catalog + FAKE_CODEX_MODE = 'malformed' + FAKE_SCOPE_MARKER = (Join-Path $TmpRoot 'malformed-scope.marker') + FAKE_GATE_MARKER = (Join-Path $TmpRoot 'malformed-gate.marker') + } $worktree + Assert-True ($malformed.ExitCode -ne 0) 'malformed worker output exits nonzero' + $malformedDoc = Get-Content -LiteralPath $malformedOutput -Raw | ConvertFrom-Json + Assert-Equal $malformedDoc.status 'failed' 'malformed worker output is failed' + Assert-Equal $malformedDoc.failure.kind 'malformed-output' 'malformed worker output records failure reason' + Assert-True (-not (Test-Path -LiteralPath (Join-Path $TmpRoot 'malformed-gate.marker'))) 'malformed output cannot reach final gate' + + $scopeFailAssignment = Join-Path $TmpRoot 'scope-fail-assignment.json' + Write-JsonFile $scopeFailAssignment ((Get-Content -LiteralPath $assignment -Raw | ConvertFrom-Json) | ForEach-Object { $_.assignment_id = 'codex-scope-fail-1'; $_ }) + $scopeFailOutput = Join-Path $TmpRoot 'scope-fail-result.json' + $scopeFail = Invoke-Adapter @('run', '--assignment', $scopeFailAssignment, '--output', $scopeFailOutput, '--error', (Join-Path $TmpRoot 'scope-fail.err'), '--codex', $FakeCodex) @{ + CODEX_MODEL_CATALOG = $Catalog + FAKE_SCOPE_RESULT = 'fail' + FAKE_SCOPE_MARKER = (Join-Path $TmpRoot 'scope-fail-scope.marker') + FAKE_GATE_MARKER = (Join-Path $TmpRoot 'scope-fail-gate.marker') + } $worktree + Assert-True ($scopeFail.ExitCode -ne 0) 'scope failure exits nonzero' + $scopeFailDoc = Get-Content -LiteralPath $scopeFailOutput -Raw | ConvertFrom-Json + Assert-Equal $scopeFailDoc.status 'scope-failure' 'scope failure is returned as scope-failure' + Assert-True (-not (Test-Path -LiteralPath (Join-Path $TmpRoot 'scope-fail-gate.marker'))) 'scope failure blocks final gate' + + $unsupportedOutput = Join-Path $TmpRoot 'unsupported-result.json' + $unsupported = Invoke-Adapter @('run', '--assignment', $assignment, '--output', $unsupportedOutput, '--error', (Join-Path $TmpRoot 'unsupported.err'), '--codex', $FakeCodex) @{ + FAKE_SCOPE_MARKER = (Join-Path $TmpRoot 'unsupported-scope.marker') + FAKE_GATE_MARKER = (Join-Path $TmpRoot 'unsupported-gate.marker') + } $worktree + Assert-True ($unsupported.ExitCode -ne 0) 'unsupported host capability exits nonzero' + $unsupportedDoc = Get-Content -LiteralPath $unsupportedOutput -Raw | ConvertFrom-Json + Assert-Equal $unsupportedDoc.status 'unsupported' 'unsupported host capability fails closed' + Assert-True ($unsupportedDoc.failure.reason -match 'model catalog') 'unsupported capability records a reason' + + $quotaAssignment = Join-Path $TmpRoot 'quota-assignment.json' + Write-JsonFile $quotaAssignment ((Get-Content -LiteralPath $assignment -Raw | ConvertFrom-Json) | ForEach-Object { $_.assignment_id = 'codex-quota-1'; $_ }) + $quotaOutput = Join-Path $TmpRoot 'quota-result.json' + $quota = Invoke-Adapter @('run', '--assignment', $quotaAssignment, '--output', $quotaOutput, '--error', (Join-Path $TmpRoot 'quota.err'), '--codex', $FakeCodex) @{ + CODEX_MODEL_CATALOG = $Catalog + FAKE_CODEX_MODE = 'quota' + FAKE_SCOPE_MARKER = (Join-Path $TmpRoot 'quota-scope.marker') + FAKE_GATE_MARKER = (Join-Path $TmpRoot 'quota-gate.marker') + } $worktree + Assert-True ($quota.ExitCode -ne 0) 'quota exhaustion exits nonzero' + $quotaDoc = Get-Content -LiteralPath $quotaOutput -Raw | ConvertFrom-Json + Assert-Equal $quotaDoc.status 'quota-handoff' 'quota exhaustion is handed off' + Assert-Equal $quotaDoc.failure.kind 'quota' 'quota exhaustion records failure reason' + Assert-True (-not (Test-Path -LiteralPath (Join-Path $TmpRoot 'quota-gate.marker'))) 'quota exhaustion blocks final gate' + + $cancelFile = Join-Path $TmpRoot 'cancel.request' + $cancelAssignment = Join-Path $TmpRoot 'cancel-assignment.json' + Write-JsonFile $cancelAssignment ((Get-Content -LiteralPath $assignment -Raw | ConvertFrom-Json) | ForEach-Object { $_.assignment_id = 'codex-cancel-1'; $_; }) + $cancelOutput = Join-Path $TmpRoot 'cancel-result.json' + New-Item -ItemType File -Path $cancelFile | Out-Null + $canceled = Invoke-Adapter @('run', '--assignment', $cancelAssignment, '--output', $cancelOutput, '--error', (Join-Path $TmpRoot 'cancel.err'), '--codex', $FakeCodex, '--cancel-file', $cancelFile) @{ + CODEX_MODEL_CATALOG = $Catalog + FAKE_CODEX_MODE = 'sleep' + FAKE_SCOPE_MARKER = (Join-Path $TmpRoot 'cancel-scope.marker') + FAKE_GATE_MARKER = (Join-Path $TmpRoot 'cancel-gate.marker') + } $worktree + Assert-True ($canceled.ExitCode -ne 0) 'cancellation exits nonzero' + $canceledDoc = Get-Content -LiteralPath $cancelOutput -Raw | ConvertFrom-Json + Assert-Equal $canceledDoc.status 'canceled' 'cancellation is recorded as canceled' + Assert-True ($canceledDoc.process.exit_code -ne $null) 'cancellation records worker exit result' + + Write-Output 'all Codex adapter contract checks passed' +} finally { + if (Test-Path -LiteralPath $TmpRoot) { + Remove-Item -LiteralPath $TmpRoot -Recurse -Force + } +} From 4a5dc666e5c80d8211fbf95d6f1d94144b28b8de Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 17:26:02 +0800 Subject: [PATCH 05/11] feat: restrict worker dispatch to orchestrator --- AGENTS.md | 4 +- CONTEXT.md | 6 +- README.md | 11 +- SKILL.md | 11 +- modes/execution.md | 167 +++++++++---- scripts/dispatch-worker.ps1 | 408 ++++++++++++++++++++++++++++++++ scripts/dispatch-worker.sh | 362 ++++++++++++++++++++++++++++ scripts/execution-workspace.ps1 | 4 + scripts/execution-workspace.sh | 8 + scripts/run-agy-json.ps1 | 58 ++++- scripts/run-agy-json.sh | 63 ++++- tests/test_dispatch_control.ps1 | 175 ++++++++++++++ 12 files changed, 1216 insertions(+), 61 deletions(-) create mode 100644 scripts/dispatch-worker.ps1 create mode 100644 scripts/dispatch-worker.sh create mode 100644 tests/test_dispatch_control.ps1 diff --git a/AGENTS.md b/AGENTS.md index e997b11..ccda099 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,9 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy ## Key decisions and architecture -- **Orchestrator-agnostic, worker-fixed**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. `agy` is reserved for the worker role. The self-guard stops an `agy` process that loads this skill. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. +Dispatch control: `dispatch-worker.sh` and `dispatch-worker.ps1` are orchestrator-owned admission interfaces. They record bounded assignment parentage and budgets, create worktrees, and start workers. Worker-context calls to dispatch, launch, or execution-workspace lifecycle helpers fail closed and are recorded; worker follow-up requests remain data until the orchestrator admits them. + +- **Orchestrator-agnostic, worker-fixed**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. `agy` is reserved for the worker role. The self-guard stops an `agy` process that loads this skill. Every assignment instructs workers not to dispatch nested workers, and the dispatcher plus worker-context guards enforce that workflow boundary. - **Modular mode architecture**: Root `SKILL.md` is a lightweight router under 500 lines owning shared preconditions, mode inference, explicit overrides, mode loading, and the shared report contract. Workflows are isolated into dedicated mode documents: `modes/execution.md` (code and file mutations), `modes/repo-research.md` (bounded local investigations and audits), and `modes/web-research.md` (online research, synthesis, and citation auditing). - **Routing hierarchy**: Once invoked, the router resolves mode in this order: 1. Honor explicit mode override. diff --git a/CONTEXT.md b/CONTEXT.md index ac2a59d..0909717 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -9,9 +9,13 @@ The calling agent that plans assignments, dispatches workers, and verifies their _Avoid_: Controller, parent agent **Worker**: -An `agy` process assigned one bounded role and prohibited from dispatching more workers. +An `agy` process assigned one bounded role. Its process environment is marked as worker context, so the dispatch, launcher, and execution-workspace lifecycle interfaces reject nested assignment, process, or worktree creation. _Avoid_: Subagent, child agent +**Dispatch ledger**: +The orchestrator-owned `offload-dispatch-state-v1` record for admitted assignments. It records parentage, depth, child IDs, budgets, owned and frozen paths, lifecycle state, artifacts, and rejected nested-dispatch events. +_Avoid_: Worker tree, implicit scheduler state + **Helper family**: A shell-native set of scripts that implements the same offload operations and command contracts for one supported shell. _Avoid_: Port, rewrite diff --git a/README.md b/README.md index 2436edb..e601e42 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,10 @@ Offload's online-research workflow is adapted from Asa by Achibukz, used with pe - **`--add-dir` grants directory access without confining writes.** A worker can edit files outside its assignment if pointed at a live repository tree. - **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. +- **Orchestrator-owned dispatch.** `dispatch-worker.sh` or `dispatch-worker.ps1` is the only workflow entry point that admits an assignment, creates its worktree, and starts its worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1` for the worker. Worker-context calls to the dispatcher, launcher, or execution-workspace lifecycle helpers fail closed and record a `nested_dispatch_rejected` event. +- **Structured follow-up requests.** A worker may return a request for more work in `structured_output`, but that request is data for the orchestrator to review. It never starts a process automatically. +- **Bounded assignment ledger.** The dispatcher records assignment ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle timestamps, output and error paths, worktree manifest, and timeout/resource budget in an `offload-dispatch-state-v1` ledger. Root limits for depth, child width, timeout, and total resource units are immutable for descendants; admission rejects attempts that would exceed them. +- **Defense in depth.** Vendor sandbox behavior, including `agy --mode plan`, is a useful additional boundary but is not treated as enforcement. The workflow verifies the worker context, assignment ledger, worktree lifecycle, frozen paths, execution scope, and test gates mechanically. ## Supported environments @@ -95,11 +98,11 @@ A historical live smoke comparison against Gemini 3.7 retained Flash for every r Used for code and file modifications across independent gated tasks. -1. **Split and scout.** Break work into provisional tasks. Dispatch parallel scouts under `--mode plan` via `run-agy-json` with a JSON schema to identify touched files. If tasks overlap on files, serialize them. +1. **Split and scout.** Break work into provisional tasks. Dispatch parallel scouts under `--mode plan` via `dispatch-worker`, which wraps `run-agy-json`, with a JSON schema to identify touched files. If tasks overlap on files, serialize them. 2. **Assign gates.** Every task receives exactly one gate: - **Machine gate.** An automated test command exiting 0 on success. A gate-author worker writes the test. The orchestrator runs a red check against the untouched tree to verify failure, reads the test code to confirm intent, and commits the test to freeze it. - **Diff gate.** Plain-text criteria for tasks without test commands (such as documentation or configuration changes) receive stable IDs. A reviewer worker evaluates the immutable review artifact and returns exactly one verdict per ID. The orchestrator accepts only complete all-pass coverage whose evidence lines match the same artifact. -3. **Dispatch implementers.** Dispatch implementers in parallel from a clean git tree with explicit owned files, frozen paths, and gate commands via `run-agy-json`. +3. **Dispatch implementers.** Dispatch implementers in parallel from a clean git tree with explicit owned files, frozen paths, gate commands, and bounded budgets via `dispatch-worker`. The dispatcher wraps `execution-workspace` and `run-agy-json`; workers never call those lifecycle or launch interfaces directly. 4. **Mechanical verification.** - Execution scope check: verify touched paths against assigned owned and frozen paths using `check-execution-scope`: #### Bash @@ -337,7 +340,7 @@ pwsh -File tests/test_execution_scope.ps1 - **`agy` default `--print-timeout` is 5 minutes.** On expiry it writes no output at all. `offload` passes `--print-timeout 20m`. - **`--output-format json` returns one flat JSON object.** Parse top-level fields `status`, `response`, `duration_seconds`, `num_turns`, and `usage`. - **`--json-schema` outputs validated JSON in `structured_output`.** Parse `structured_output` rather than `response`. -- **Use the bundled launcher helpers (`run-agy-json.sh` or `run-agy-json.ps1`) for worker calls.** They own result and error paths and reject the unsupported `agy --output` flag. +- **Use `dispatch-worker.sh` or `dispatch-worker.ps1` for execution assignments.** They own assignment admission, worktree creation, result and error paths, and the bounded launch. The dispatcher wraps the lower-level `run-agy-json` helper, which rejects the unsupported `agy --output` flag. - **Use structured output extractors (`extract-structured-output.sh` or `extract-structured-output.ps1`) between research stages.** They forward only validated `structured_output`, keeping verbose worker prose out of later prompts. - **Model routing is governed by `model-policy.json`.** Launchers inject the policy-selected Gemini 3.8 Flash model (`gemini-3.8-flash-low` or `gemini-3.8-flash-high`) via `--role `. Reasoning effort is encoded directly in the model ID; callers must not pass `--model` or `--effort`. - **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted probe on `agy 1.1.25` blocked the tested direct write outside the permitted artifact area, but this observation is not a guarantee. `--add-dir` grants access without confining writes. Security relies on filesystem isolation and mechanical verification. diff --git a/SKILL.md b/SKILL.md index 76de7d3..ab3da39 100644 --- a/SKILL.md +++ b/SKILL.md @@ -5,7 +5,7 @@ description: Use when the user wants execution or research handed to another ven # offload -If you are `agy`, stop here. Return worker results to your orchestrator. `agy` is the worker role this skill dispatches. Any other agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, but the skill cannot enforce that rule if a worker ignores it. +If you are `agy`, stop here. Return worker results to your orchestrator. `agy` is the worker role this skill dispatches. Any other agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, and the workflow enforces that boundary with an orchestrator-owned dispatcher and worker-context guards. ## What this skill does @@ -63,6 +63,8 @@ Offload routes all workers through the repository-root `model-policy.json`. Laun ### Launcher invocation +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 -- ` - **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --output --error '--' ` @@ -208,8 +210,11 @@ Sample recorded: 1/1 high checked, 1/2 med/low sampled. - **`--add-dir` grants directory access without confining writes.** A worker can edit files outside its assignment if pointed at the live tree. - **Filesystem isolation.** Research modes run in disposable workspaces with scoped file snapshots. Live repository files are never exposed directly to research workers. - **Execution safety.** Execution mode requires a clean git baseline, mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path diffs, and test gates. -- **Prohibition on nested dispatch.** Workers are instructed not to dispatch nested workers. +- **Orchestrator-owned dispatch.** Use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1` for every execution assignment. It is the only workflow interface that creates an assignment record, execution worktree, and worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1`; worker-context calls to the dispatcher, `run-agy-json`, or `execution-workspace` fail with exit 126. +- **Structured follow-up requests.** Workers may return a structured request for more work. The orchestrator records and evaluates that data explicitly. No worker response can automatically create a child assignment. +- **Assignment ledger.** Every admitted assignment records its ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle state and timestamps, output/error paths, worktree manifest, and timeout/resource budget. The root fixes maximum depth, child width, per-assignment timeout, and total resource units. Admission rejects a request before worktree or process creation when it would exceed any limit. +- **Vendor boundary versus workflow verification.** `agy --mode plan` and any vendor sandbox are defense in depth. The workflow does not treat prompts or sandbox hints as its sole control; it verifies caller context, ledger admission, worktree lifecycle, scope, frozen paths, and gates. - **Bounded scope requirement.** Open-ended research without a bounded question, declared scope, and evidence expectations is out of scope. -- **Worker timeout.** Every worker runs with a bounded timeout (`--print-timeout 20m`). +- **Worker timeout.** Every dispatched worker has a bounded dispatcher timeout and forwards the normal AGY output deadline (`--print-timeout 20m`). Result acceptance is separate from process completion: a parsed envelope, substantive structured output, evidence/scope/gate checks, and (where applicable) review or citation checks must all pass before an explicit `accepted_attempt` is recorded. Exit code 0 alone does not establish verified success. Gate exits 126 or 127 are `unrunnable`, retain their command and diagnostic evidence, use `verification: not_performed`, and do not consume a model retry. diff --git a/modes/execution.md b/modes/execution.md index e714dcf..33801ff 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -6,8 +6,8 @@ Dispatches `agy` workers to implement file and code changes across independent g Select the helper family matching your current host shell: -- **POSIX shells (Bash 3.2+)**: Use `scripts/run-agy-json.sh`, `scripts/check-execution-scope.sh`, `scripts/execute-gate.sh`, and `scripts/execution-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. -- **PowerShell (PowerShell 7+)**: Use `scripts/run-agy-json.ps1`, `scripts/check-execution-scope.ps1`, `scripts/execute-gate.ps1`, and `scripts/execution-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +- **POSIX shells (Bash 3.2+)**: Use `scripts/dispatch-worker.sh`, `scripts/run-agy-json.sh`, `scripts/check-execution-scope.sh`, `scripts/execute-gate.sh`, and `scripts/execution-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. +- **PowerShell (PowerShell 7+)**: Use `scripts/dispatch-worker.ps1`, `scripts/run-agy-json.ps1`, `scripts/check-execution-scope.ps1`, `scripts/execute-gate.ps1`, and `scripts/execution-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. Check these before dispatching writing tasks: @@ -19,10 +19,15 @@ Check these before dispatching writing tasks: - PowerShell: `$Baseline = (git rev-parse HEAD).Trim()` 5. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching the first worker. All workers route through `model-policy.json`. 6. **Workspace isolation principle.** Writing workers are never dispatched directly into the caller's main checkout (``). All candidate mutations occur in isolated candidate worktrees created at the recorded baseline revision via `execution-workspace create`. +7. **Orchestrator-owned admission.** Route every worker launch through `dispatch-worker` with a dispatch ledger and explicit `--max-depth`, `--max-width`, `--max-timeout-seconds`, and `--max-resource-units` on the root assignment. The dispatcher creates the worktree and invokes the launcher. A worker's structured request for more work remains data until the orchestrator deliberately admits it as a new bounded assignment. ## Roles and models -Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. +Workers are admitted by role using `dispatch-worker` with `--role ` and a bounded budget. The dispatcher invokes `run-agy-json`, which resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. + +The command examples below show the `agy` arguments passed after the dispatcher's `--` delimiter. In a real run, put the state path, assignment identity, parent identity when applicable, source revision, owned and frozen paths, output and error paths, workspace path, budget, and root limits on the `dispatch-worker` invocation. Do not invoke `run-agy-json` directly for an execution assignment. + +The examples use one assignment per ledger. For a parallel wave, share the ledger and set its root child-width and total resource limits to cover the whole wave. | Role | Wave | Default model | Effort | Mode | Job | |---|---|---|---|---|---| @@ -50,16 +55,28 @@ Assign each task exactly one gate: ### Scout -For provisional writing tasks, dispatch scouts in parallel using the matching launcher helper with `--role scout`. Scouts run in an isolated worktree at the recorded baseline: +For provisional writing tasks, dispatch scouts in parallel through `dispatch-worker` with `--role scout`. Scouts run in an isolated worktree at the recorded baseline: #### Bash ```bash OFFLOAD_ROOT="" +DISPATCH_STATE="/offload/dispatch.json" SCOUT_WORKSPACE="/offload/scout" -git worktree add --detach "$SCOUT_WORKSPACE" "$BASELINE" SCOUT_SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "$DISPATCH_STATE" \ + --assignment-id "scout-" \ --role scout \ + --source-repo "" \ + --baseline "$BASELINE" \ + --owned "README.md" \ + --workspace-dir "$SCOUT_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --output "/offload/.attempt1.scout.json" \ --error "/offload/.attempt1.scout.err" \ -- \ @@ -74,11 +91,23 @@ SCOUT_SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"t #### PowerShell ```powershell $OffloadRoot = "" +$DispatchState = "/offload/dispatch.json" $ScoutWorkspace = "/offload/scout" -git worktree add --detach $ScoutWorkspace $Baseline $ScoutSchema = '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -& "$OffloadRoot/scripts/run-agy-json.ps1" ` +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state $DispatchState ` + --assignment-id "scout-" ` --role scout ` + --source-repo "" ` + --baseline $Baseline ` + --owned "README.md" ` + --workspace-dir $ScoutWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --output "/offload/.attempt1.scout.json" ` --error "/offload/.attempt1.scout.err" ` '--' ` @@ -108,16 +137,22 @@ For each machine-gated task, create an isolated candidate worktree at the record #### Bash ```bash -GATE_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ +GATE_WORKSPACE="/offload/gate-" +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "gate-" \ --source-repo "" \ - --task-id "gate-" \ --baseline "$BASELINE" \ --owned "" \ --frozen "" \ --frozen "" \ - --manifest "/offload/gate-.manifest.json") - -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ + --workspace-dir "$GATE_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --role gate-author \ --output "/offload/.attempt1.gate.json" \ --error "/offload/.attempt1.gate.err" \ @@ -131,16 +166,22 @@ GATE_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ #### PowerShell ```powershell -$GateWorkspace = (& "$OffloadRoot/scripts/execution-workspace.ps1" create ` +$GateWorkspace = "/offload/gate-" +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "gate-" ` --source-repo "" ` - --task-id "gate-" ` --baseline $Baseline ` --owned "" ` --frozen "" ` --frozen "" ` - --manifest "/offload/gate-.manifest.json").Trim() - -& "$OffloadRoot/scripts/run-agy-json.ps1" ` + --workspace-dir $GateWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --role gate-author ` --output "/offload/.attempt1.gate.json" ` --error "/offload/.attempt1.gate.err" ` @@ -180,16 +221,22 @@ For each task, create an isolated candidate worktree from the approved `$GATE_BA #### Bash ```bash -TASK_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ +TASK_WORKSPACE="/offload/" +"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "" \ --source-repo "" \ - --task-id "" \ --baseline "$GATE_BASELINE" \ --owned "" \ --owned "" \ --frozen "" \ - --manifest "/offload/.manifest.json") - -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ + --workspace-dir "$TASK_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --role implementer \ --output "/offload/.attempt1.json" \ --error "/offload/.attempt1.err" \ @@ -203,16 +250,22 @@ TASK_WORKSPACE=$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" create \ #### PowerShell ```powershell -$TaskWorkspace = (& "$OffloadRoot/scripts/execution-workspace.ps1" create ` +$TaskWorkspace = "/offload/" +& "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "" ` --source-repo "" ` - --task-id "" ` --baseline $GateBaseline ` --owned "" ` --owned "" ` --frozen "" ` - --manifest "/offload/.manifest.json").Trim() - -& "$OffloadRoot/scripts/run-agy-json.ps1" ` + --workspace-dir $TaskWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --role implementer ` --output "/offload/.attempt1.json" ` --error "/offload/.attempt1.err" ` @@ -306,34 +359,60 @@ Verify every worker reporting `SUCCESS`: - `failure_class: "quality"` (`verification_status: "failed"`, `allow_retry: true`, other non-zero exit codes): The test assertions failed. Record the diagnostic artifact path and schedule a quality retry if attempt budget remains. - Diff gate: Dispatch an adversarial reviewer worker to inspect the recorded artifact using `--role reviewer`: - #### Bash - ```bash - REVIEW_SCHEMA='{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - "$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ - --role reviewer \ + #### Bash + ```bash + REVIEW_SCHEMA='{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' + REVIEW_WORKSPACE="/offload/-reviewer" + "$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ + --state "/offload/dispatch.json" \ + --assignment-id "-reviewer" \ + --role reviewer \ + --source-repo "" \ + --baseline "$GATE_BASELINE" \ + --owned "README.md" \ + --workspace-dir "$REVIEW_WORKSPACE" \ + --max-depth 0 \ + --max-width 1 \ + --max-timeout-seconds 1200 \ + --max-resource-units 1 \ + --timeout-seconds 1200 \ + --resource-units 1 \ --output "/offload/.attempt1.review.json" \ --error "/offload/.attempt1.review.err" \ - -- \ + -- \ -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " \ - --output-format json \ - --mode plan \ + --output-format json \ + --mode plan \ --json-schema "$REVIEW_SCHEMA" \ --add-dir "" \ --add-dir "" \ --print-timeout 20m ``` - #### PowerShell - ```powershell - $ReviewSchema = '{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - & "$OffloadRoot/scripts/run-agy-json.ps1" ` - --role reviewer ` + #### PowerShell + ```powershell + $ReviewSchema = '{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' + $ReviewWorkspace = "/offload/-reviewer" + & "$OffloadRoot/scripts/dispatch-worker.ps1" ` + --state "/offload/dispatch.json" ` + --assignment-id "-reviewer" ` + --role reviewer ` + --source-repo "" ` + --baseline $GateBaseline ` + --owned "README.md" ` + --workspace-dir $ReviewWorkspace ` + --max-depth 0 ` + --max-width 1 ` + --max-timeout-seconds 1200 ` + --max-resource-units 1 ` + --timeout-seconds 1200 ` + --resource-units 1 ` --output "/offload/.attempt1.review.json" ` --error "/offload/.attempt1.review.err" ` - '--' ` + '--' ` -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " ` - --output-format json ` - --mode plan ` + --output-format json ` + --mode plan ` --json-schema $ReviewSchema ` --add-dir "" ` diff --git a/scripts/dispatch-worker.ps1 b/scripts/dispatch-worker.ps1 new file mode 100644 index 0000000..962341d --- /dev/null +++ b/scripts/dispatch-worker.ps1 @@ -0,0 +1,408 @@ +#!/usr/bin/env pwsh +# scripts/dispatch-worker.ps1 +# Orchestrator-only assignment admission, worktree creation, and worker launch. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$script:StateMarker = 'offload-dispatch-state-v1' +$script:ScriptDir = Split-Path -Parent $PSCommandPath +$script:RootDir = Split-Path -Parent $script:ScriptDir +$script:Launcher = Join-Path $script:ScriptDir 'run-agy-json.ps1' +$script:WorkspaceHelper = Join-Path $script:ScriptDir 'execution-workspace.ps1' + +function Fail([string]$message, [int]$exitCode = 2) { + [Console]::Error.WriteLine("Error: $message") + exit $exitCode +} + +function Usage { + [Console]::Error.WriteLine(@" +Usage: + dispatch-worker.ps1 --state FILE --assignment-id ID [--parent-assignment-id ID] + --role ROLE --source-repo DIR --baseline REV --owned PATH [--owned PATH ...] + --output FILE --error FILE --timeout-seconds N --resource-units N + [--max-depth N --max-width N --max-timeout-seconds N --max-resource-units N] + [--frozen PATH ...] [--workspace-dir DIR] [--workspace-manifest FILE] -- agy-arguments... +"@) +} + +function Get-Now { + return [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ') +} + +function Write-JsonFile([string]$path, $value) { + $parent = Split-Path -Parent $path + if ($parent -and -not (Test-Path -LiteralPath $parent -PathType Container)) { + [System.IO.Directory]::CreateDirectory($parent) | Out-Null + } + $tmp = "$path.$PID.tmp" + $json = $value | ConvertTo-Json -Depth 30 + [System.IO.File]::WriteAllText($tmp, "$json`n", [System.Text.UTF8Encoding]::new($false)) + Move-Item -LiteralPath $tmp -Destination $path -Force +} + +function Acquire-StateLock([string]$statePath) { + $lockPath = "$statePath.lock" + $parent = Split-Path -Parent $statePath + if ($parent -and -not (Test-Path -LiteralPath $parent -PathType Container)) { + [System.IO.Directory]::CreateDirectory($parent) | Out-Null + } + $started = [DateTime]::UtcNow + while ($true) { + try { + $lockStream = [System.IO.File]::Open($lockPath, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::None) + $lockStream.Dispose() + return $lockPath + } catch [System.IO.IOException] { + if (([DateTime]::UtcNow - $started).TotalSeconds -ge 15) { + Fail "timed out acquiring dispatch ledger lock: $statePath" 1 + } + Start-Sleep -Milliseconds 25 + } + } +} + +function Release-StateLock([string]$lockPath) { + if ($lockPath -and (Test-Path -LiteralPath $lockPath -PathType Leaf)) { + Remove-Item -LiteralPath $lockPath -Force -ErrorAction SilentlyContinue + } +} + +function New-State([int]$maxDepth, [int]$maxWidth, [int]$maxTimeout, [int]$maxResources) { + return [ordered]@{ + schema_version = 1 + marker = $script:StateMarker + limits = [ordered]@{ + max_depth = $maxDepth + max_width = $maxWidth + max_timeout_seconds = $maxTimeout + max_resource_units = $maxResources + } + assignments = @() + events = @() + created_at = Get-Now + } +} + +function Read-State([string]$statePath, [bool]$create, [int]$maxDepth, [int]$maxWidth, [int]$maxTimeout, [int]$maxResources) { + if (-not (Test-Path -LiteralPath $statePath -PathType Leaf)) { + if (-not $create) { Fail "dispatch ledger does not exist: $statePath" } + return New-State $maxDepth $maxWidth $maxTimeout $maxResources + } + try { + $state = Get-Content -LiteralPath $statePath -Raw | ConvertFrom-Json + } catch { + Fail "dispatch ledger is not valid JSON: $statePath" + } + if ($null -eq $state -or $state.marker -ne $script:StateMarker -or $state.schema_version -ne 1) { + Fail "invalid dispatch ledger: $statePath" + } + if ($null -eq $state.limits -or $null -eq $state.assignments -or $null -eq $state.events) { + Fail "dispatch ledger is missing limits, assignments, or events: $statePath" + } + return $state +} + +function Record-Rejection([string]$statePath, [string]$assignmentId, [string]$reason, [hashtable]$request) { + if ([string]::IsNullOrWhiteSpace($statePath) -or -not (Test-Path -LiteralPath $statePath -PathType Leaf)) { return } + $lock = Acquire-StateLock $statePath + try { + $state = Read-State $statePath $false 0 0 0 0 + $event = [ordered]@{ + type = 'nested_dispatch_rejected' + actor = if ($env:OFFLOAD_WORKER_CONTEXT -eq '1') { 'worker' } else { 'orchestrator' } + assignment_id = $assignmentId + reason = $reason + request = $request + recorded_at = Get-Now + } + $state.events = @($state.events) + $event + Write-JsonFile $statePath $state + } finally { + Release-StateLock $lock + } +} + +function Parse-PositiveInt([string]$name, [string]$value, [bool]$allowZero = $false) { + $number = 0 + if (-not [int]::TryParse($value, [Globalization.NumberStyles]::Integer, [Globalization.CultureInfo]::InvariantCulture, [ref]$number)) { + Fail "$name must be an integer: $value" + } + if (($allowZero -and $number -lt 0) -or (-not $allowZero -and $number -le 0)) { + $kind = if ($allowZero) { 'non-negative' } else { 'positive' } + Fail "$name must be $kind" + } + return $number +} + +$statePath = '' +$assignmentId = '' +$parentId = '' +$role = '' +$sourceRepo = '' +$baseline = '' +$outputPath = '' +$errorPath = '' +$workspaceDir = '' +$workspaceManifest = '' +$owned = [System.Collections.Generic.List[string]]::new() +$frozen = [System.Collections.Generic.List[string]]::new() +$workerArgs = [System.Collections.Generic.List[string]]::new() +$maxDepthArg = $null +$maxWidthArg = $null +$maxTimeoutArg = $null +$maxResourcesArg = $null +$depthArg = $null +$timeoutArg = $null +$resourcesArg = $null +$afterDelimiter = $false + +$i = 0 +while ($i -lt $args.Count) { + $arg = [string]$args[$i] + if ($afterDelimiter) { + $workerArgs.Add($arg) + $i++ + continue + } + if ($arg -eq '--') { $afterDelimiter = $true; $i++; continue } + $value = $null + $name = $arg + if ($arg -match '^([^=]+)=(.*)$') { $name = $Matches[1]; $value = $Matches[2] } + $takesValue = @('--state','--assignment-id','--parent-assignment-id','--role','--source-repo','--baseline','--owned','--frozen','--output','--error','--workspace-dir','--workspace-manifest','--max-depth','--max-width','--max-timeout-seconds','--max-resource-units','--depth','--timeout-seconds','--resource-units') -contains $name + if (-not $takesValue) { Usage; Fail "unknown dispatcher option: $arg" } + if ($null -eq $value) { + if ($i + 1 -ge $args.Count) { Usage; Fail "$name requires a value" } + $i++ + $value = [string]$args[$i] + } + switch ($name) { + '--state' { $statePath = $value } + '--assignment-id' { $assignmentId = $value } + '--parent-assignment-id' { $parentId = $value } + '--role' { $role = $value } + '--source-repo' { $sourceRepo = $value } + '--baseline' { $baseline = $value } + '--owned' { $owned.Add($value) } + '--frozen' { $frozen.Add($value) } + '--output' { $outputPath = $value } + '--error' { $errorPath = $value } + '--workspace-dir' { $workspaceDir = $value } + '--workspace-manifest' { $workspaceManifest = $value } + '--max-depth' { $maxDepthArg = Parse-PositiveInt $name $value $true } + '--max-width' { $maxWidthArg = Parse-PositiveInt $name $value $false } + '--max-timeout-seconds' { $maxTimeoutArg = Parse-PositiveInt $name $value $false } + '--max-resource-units' { $maxResourcesArg = Parse-PositiveInt $name $value $false } + '--depth' { $depthArg = Parse-PositiveInt $name $value $true } + '--timeout-seconds' { $timeoutArg = Parse-PositiveInt $name $value $false } + '--resource-units' { $resourcesArg = Parse-PositiveInt $name $value $false } + } + $i++ +} + +if (-not $afterDelimiter) { Usage; Fail "-- delimiter is required" } +if ($workerArgs.Count -eq 0) { Usage; Fail "agy arguments are required after --" } +foreach ($required in @(@{n='--state';v=$statePath}, @{n='--assignment-id';v=$assignmentId}, @{n='--role';v=$role}, @{n='--source-repo';v=$sourceRepo}, @{n='--baseline';v=$baseline}, @{n='--output';v=$outputPath}, @{n='--error';v=$errorPath})) { + if ([string]::IsNullOrWhiteSpace($required.v)) { Usage; Fail "$($required.n) is required" } +} +if ($owned.Count -eq 0) { Fail 'at least one --owned path is required' } +if ($null -eq $timeoutArg) { Fail '--timeout-seconds is required' } +if ($null -eq $resourcesArg) { Fail '--resource-units is required' } +if ($assignmentId -match '[\\/\s]') { Fail '--assignment-id cannot contain whitespace or path separators' } + +if ($env:OFFLOAD_WORKER_CONTEXT -eq '1') { + Record-Rejection $statePath $assignmentId 'worker context cannot create assignments, processes, or worktrees' @{ + role = $role + parent_assignment_id = if ($parentId) { $parentId } else { $null } + owned_paths = @($owned) + } + Fail 'worker dispatch rejected: only the orchestrator may create assignments, processes, or worktrees' 126 +} + +$statePath = [System.IO.Path]::GetFullPath($statePath) +$sourceRepo = [System.IO.Path]::GetFullPath($sourceRepo) +$outputPath = [System.IO.Path]::GetFullPath($outputPath) +$errorPath = [System.IO.Path]::GetFullPath($errorPath) +if ($workspaceDir) { $workspaceDir = [System.IO.Path]::GetFullPath($workspaceDir) } +if ($workspaceManifest) { $workspaceManifest = [System.IO.Path]::GetFullPath($workspaceManifest) } +if (-not $workspaceManifest) { + $workspaceManifest = Join-Path ([System.IO.Path]::GetDirectoryName($statePath)) "$assignmentId.manifest.json" +} +$lock = Acquire-StateLock $statePath +$state = $null +$assignment = $null +try { + $isRoot = [string]::IsNullOrWhiteSpace($parentId) + if ($isRoot -and ($null -eq $maxDepthArg -or $null -eq $maxWidthArg -or $null -eq $maxTimeoutArg -or $null -eq $maxResourcesArg)) { + Fail 'root dispatch requires --max-depth, --max-width, --max-timeout-seconds, and --max-resource-units' + } + $state = Read-State $statePath $isRoot ([int]($maxDepthArg ?? 0)) ([int]($maxWidthArg ?? 0)) ([int]($maxTimeoutArg ?? 0)) ([int]($maxResourcesArg ?? 0)) + if (-not $isRoot) { + foreach ($pair in @( + @{n='max-depth';v=$maxDepthArg;actual=$state.limits.max_depth}, + @{n='max-width';v=$maxWidthArg;actual=$state.limits.max_width}, + @{n='max-timeout-seconds';v=$maxTimeoutArg;actual=$state.limits.max_timeout_seconds}, + @{n='max-resource-units';v=$maxResourcesArg;actual=$state.limits.max_resource_units} + )) { + if ($null -ne $pair.v -and $pair.v -ne $pair.actual) { + $request = @{ parent_assignment_id = $parentId; limit = $pair.n; requested = $pair.v; allowed = $pair.actual } + $state.events = @($state.events) + [ordered]@{ type='nested_dispatch_rejected'; actor='orchestrator'; assignment_id=$assignmentId; reason='child attempted to widen an immutable dispatch limit'; request=$request; recorded_at=(Get-Now) } + Write-JsonFile $statePath $state + Fail "child cannot change dispatch limit --$($pair.n)" 126 + } + } + } + $parent = $null + if (-not $isRoot) { + $parents = @($state.assignments | Where-Object { $_.assignment_id -eq $parentId }) + if ($parents.Count -ne 1) { Fail "parent assignment does not exist uniquely: $parentId" } + $parent = $parents[0] + } + $depth = if ($isRoot) { 0 } else { [int]$parent.depth + 1 } + if ($null -ne $depthArg -and [int]$depthArg -ne $depth) { Fail "--depth does not match parent depth" } + if ($depth -gt [int]$state.limits.max_depth) { + $state.events = @($state.events) + [ordered]@{ type='nested_dispatch_rejected'; actor='orchestrator'; assignment_id=$assignmentId; reason='maximum dispatch depth exceeded'; request=@{ parent_assignment_id=$parentId; depth=$depth; max_depth=$state.limits.max_depth }; recorded_at=(Get-Now) } + Write-JsonFile $statePath $state + Fail 'dispatch rejected: maximum depth exceeded' 126 + } + if (-not $isRoot) { + $childCount = @($state.assignments | Where-Object { $_.parent_assignment_id -eq $parentId }).Count + if ($childCount -ge [int]$state.limits.max_width) { + $state.events = @($state.events) + [ordered]@{ type='nested_dispatch_rejected'; actor='orchestrator'; assignment_id=$assignmentId; reason='maximum child width exceeded'; request=@{ parent_assignment_id=$parentId; width=$childCount + 1; max_width=$state.limits.max_width }; recorded_at=(Get-Now) } + Write-JsonFile $statePath $state + Fail 'dispatch rejected: maximum child width exceeded' 126 + } + } + if ([int]$timeoutArg -gt [int]$state.limits.max_timeout_seconds) { + $state.events = @($state.events) + [ordered]@{ type='nested_dispatch_rejected'; actor='orchestrator'; assignment_id=$assignmentId; reason='assignment timeout exceeds maximum'; request=@{ timeout_seconds=$timeoutArg; max_timeout_seconds=$state.limits.max_timeout_seconds }; recorded_at=(Get-Now) } + Write-JsonFile $statePath $state + Fail 'dispatch rejected: timeout exceeds maximum' 126 + } + $usedResources = 0 + foreach ($existingAssignment in @($state.assignments)) { + $usedResources += [int]$existingAssignment.budget.resource_units + } + if ([int]$usedResources + [int]$resourcesArg -gt [int]$state.limits.max_resource_units) { + $state.events = @($state.events) + [ordered]@{ type='nested_dispatch_rejected'; actor='orchestrator'; assignment_id=$assignmentId; reason='maximum resource budget exceeded'; request=@{ resource_units=$resourcesArg; used_resource_units=$usedResources; max_resource_units=$state.limits.max_resource_units }; recorded_at=(Get-Now) } + Write-JsonFile $statePath $state + Fail 'dispatch rejected: resource budget exceeded' 126 + } + if (@($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId }).Count -ne 0) { Fail "assignment id already exists: $assignmentId" } + + $assignment = [ordered]@{ + assignment_id = $assignmentId + parent_assignment_id = if ($isRoot) { $null } else { $parentId } + child_assignment_ids = @() + depth = $depth + budget = [ordered]@{ timeout_seconds = [int]$timeoutArg; resource_units = [int]$resourcesArg } + owned_paths = @($owned) + frozen_paths = @($frozen) + role = $role + lifecycle_state = 'created' + source_repo = [System.IO.Path]::GetFullPath($sourceRepo) + baseline = $baseline + output_path = [System.IO.Path]::GetFullPath($outputPath) + error_path = [System.IO.Path]::GetFullPath($errorPath) + workspace_manifest = if ($workspaceManifest) { [System.IO.Path]::GetFullPath($workspaceManifest) } else { $null } + workspace_dir = if ($workspaceDir) { [System.IO.Path]::GetFullPath($workspaceDir) } else { $null } + created_at = Get-Now + started_at = $null + ended_at = $null + exit_code = $null + } + $state.assignments = @($state.assignments) + $assignment + if ($parent) { + $parent.child_assignment_ids = @($parent.child_assignment_ids) + $assignmentId + } + Write-JsonFile $statePath $state +} finally { + Release-StateLock $lock +} + +$workspaceArgs = @('create', '--source-repo', $sourceRepo, '--task-id', $assignmentId, '--baseline', $baseline) +foreach ($path in $owned) { $workspaceArgs += @('--owned', $path) } +foreach ($path in $frozen) { $workspaceArgs += @('--frozen', $path) } +if ($workspaceManifest) { $workspaceArgs += @('--manifest', $workspaceManifest) } +if ($workspaceDir) { $workspaceArgs += @('--workspace-dir', $workspaceDir) } +$global:LASTEXITCODE = 0 +$workspaceOutput = & $script:WorkspaceHelper @workspaceArgs 2>&1 | Out-String +$workspaceExitCode = $LASTEXITCODE +if ($workspaceExitCode -ne 0) { + $lock = Acquire-StateLock $statePath + try { + $state = Read-State $statePath $false 0 0 0 0 + $record = @($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId })[0] + $record.lifecycle_state = 'failed' + $record.ended_at = Get-Now + $record.failure = "worktree creation failed: $($workspaceOutput.Trim())" + Write-JsonFile $statePath $state + } finally { Release-StateLock $lock } + Fail "failed to create worker worktree: $($workspaceOutput.Trim())" 1 +} +if ($workspaceDir) { + $workspacePath = [System.IO.Path]::GetFullPath($workspaceDir) +} else { + if (-not $workspaceManifest -or -not (Test-Path -LiteralPath $workspaceManifest -PathType Leaf)) { + $lock = Acquire-StateLock $statePath + try { + $state = Read-State $statePath $false 0 0 0 0 + $record = @($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId })[0] + $record.lifecycle_state = 'failed' + $record.ended_at = Get-Now + $record.exit_code = 1 + $record.failure = 'workspace helper did not produce a manifest for the assigned worker' + Write-JsonFile $statePath $state + } finally { Release-StateLock $lock } + Fail 'workspace helper did not produce a manifest for the assigned worker' + } + $workspaceRecord = Get-Content -LiteralPath $workspaceManifest -Raw | ConvertFrom-Json + $workspacePath = [string]$workspaceRecord.workspace_dir +} +if (-not (Test-Path -LiteralPath $workspacePath -PathType Container)) { + $lock = Acquire-StateLock $statePath + try { + $state = Read-State $statePath $false 0 0 0 0 + $record = @($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId })[0] + $record.lifecycle_state = 'failed' + $record.ended_at = Get-Now + $record.exit_code = 1 + $record.failure = "assigned worker worktree does not exist: $workspacePath" + Write-JsonFile $statePath $state + } finally { Release-StateLock $lock } + Fail "assigned worker worktree does not exist: $workspacePath" 1 +} + +$lock = Acquire-StateLock $statePath +try { + $state = Read-State $statePath $false 0 0 0 0 + $record = @($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId })[0] + $record.workspace_dir = $workspacePath + $record.workspace_manifest = if ($workspaceManifest) { [System.IO.Path]::GetFullPath($workspaceManifest) } else { $record.workspace_manifest } + $record.lifecycle_state = 'running' + $record.started_at = Get-Now + Write-JsonFile $statePath $state +} finally { Release-StateLock $lock } + +$launcherArgs = @('--role', $role, '--timeout-seconds', [string]$timeoutArg, '--output', $outputPath, '--error', $errorPath, '--') + @($workerArgs) +$workerExitCode = 0 +Push-Location -LiteralPath $workspacePath +try { + & $script:Launcher @launcherArgs + $workerExitCode = $LASTEXITCODE +} finally { + Pop-Location +} + +$lock = Acquire-StateLock $statePath +try { + $state = Read-State $statePath $false 0 0 0 0 + $record = @($state.assignments | Where-Object { $_.assignment_id -eq $assignmentId })[0] + $record.lifecycle_state = if ($workerExitCode -eq 0) { 'completed' } else { 'failed' } + $record.ended_at = Get-Now + $record.exit_code = $workerExitCode + Write-JsonFile $statePath $state +} finally { Release-StateLock $lock } + +[ordered]@{ assignment_id = $assignmentId; parent_assignment_id = $assignment.parent_assignment_id; depth = $assignment.depth; lifecycle_state = if ($workerExitCode -eq 0) { 'completed' } else { 'failed' }; workspace_dir = $workspacePath; output_path = [System.IO.Path]::GetFullPath($outputPath); error_path = [System.IO.Path]::GetFullPath($errorPath) } | ConvertTo-Json -Compress +exit $workerExitCode diff --git a/scripts/dispatch-worker.sh b/scripts/dispatch-worker.sh new file mode 100644 index 0000000..a0ad1b8 --- /dev/null +++ b/scripts/dispatch-worker.sh @@ -0,0 +1,362 @@ +#!/usr/bin/env bash +# Orchestrator-only assignment admission, worktree creation, and worker launch. + +set -euo pipefail + +STATE_MARKER='offload-dispatch-state-v1' +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" +LAUNCHER="$SCRIPT_DIR/run-agy-json.sh" +WORKSPACE_HELPER="$SCRIPT_DIR/execution-workspace.sh" + +fail() { + printf 'Error: %s\n' "$1" >&2 + exit "${2:-2}" +} + +usage() { + cat >&2 <<'EOF' +Usage: + dispatch-worker.sh --state FILE --assignment-id ID [--parent-assignment-id ID] + --role ROLE --source-repo DIR --baseline REV --owned PATH [--owned PATH ...] + --output FILE --error FILE --timeout-seconds N --resource-units N + [--max-depth N --max-width N --max-timeout-seconds N --max-resource-units N] + [--frozen PATH ...] [--workspace-dir DIR] [--workspace-manifest FILE] -- agy-arguments... +EOF +} + +require_jq() { + command -v jq >/dev/null 2>&1 || fail 'jq is required by dispatch-worker.sh' 1 +} + +now() { + date -u '+%Y-%m-%dT%H:%M:%SZ' +} + +canonical_path() { + local value="$1" + local dir base cwd + if [ -d "$value" ]; then + (cd "$value" && pwd -P) + return + fi + dir=$(dirname "$value") + base=$(basename "$value") + if [ -d "$dir" ]; then + printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base" + else + cwd=$(pwd -P) + case "$value" in + /*) printf '%s\n' "$value" ;; + *) printf '%s/%s\n' "$cwd" "$value" ;; + esac + fi +} + +write_state() { + local state_file="$1" + local tmp_file="${state_file}.$$.tmp" + jq '.' "$state_file" >"$tmp_file" || { rm -f "$tmp_file"; fail "failed to serialize dispatch ledger: $state_file" 1; } + mv -f "$tmp_file" "$state_file" +} + +acquire_lock() { + local state_file="$1" + local lock_dir="${state_file}.lock" + local start + mkdir -p "$(dirname "$state_file")" + start=$(date +%s) + while ! mkdir "$lock_dir" 2>/dev/null; do + if [ $(( $(date +%s) - start )) -ge 15 ]; then + fail "timed out acquiring dispatch ledger lock: $state_file" 1 + fi + sleep 0.025 + done + printf '%s\n' "$lock_dir" +} + +release_lock() { + local lock_dir="$1" + rmdir "$lock_dir" 2>/dev/null || true +} + +record_rejection() { + local state_file="$1" assignment_id="$2" reason="$3" role_value="$4" parent_value="$5" + [ -f "$state_file" ] || return 0 + local lock + lock=$(acquire_lock "$state_file") + local actor='orchestrator' + [ "${OFFLOAD_WORKER_CONTEXT:-}" = '1' ] && actor='worker' + jq --arg marker "$STATE_MARKER" \ + --arg actor "$actor" \ + --arg assignment "$assignment_id" \ + --arg reason_value "$reason" \ + --arg role_value "$role_value" \ + --arg parent_value "$parent_value" \ + --arg recorded "$(now)" \ + '. as $state | + .events += [{type:"nested_dispatch_rejected", actor:$actor, assignment_id:$assignment, + reason:$reason_value, request:{role:$role_value, parent_assignment_id:(if $parent_value == "" then null else $parent_value end)}, + recorded_at:$recorded}]' "$state_file" >"${state_file}.$$.tmp" + mv -f "${state_file}.$$.tmp" "$state_file" + release_lock "$lock" +} + +append_rejection_locked() { + local state_file="$1" assignment_id="$2" reason="$3" request_json="$4" + jq --arg actor orchestrator --arg assignment "$assignment_id" --arg reason_value "$reason" --arg recorded "$(now)" --argjson request "$request_json" \ + '.events += [{type:"nested_dispatch_rejected",actor:$actor,assignment_id:$assignment,reason:$reason_value,request:$request,recorded_at:$recorded}]' \ + "$state_file" >"${state_file}.$$.tmp" + mv -f "${state_file}.$$.tmp" "$state_file" +} + +parse_positive_int() { + local name="$1" value="$2" allow_zero="$3" + case "$value" in ''|*[!0-9]*) fail "$name must be an integer: $value" ;; esac + if [ "$allow_zero" = true ]; then + [ "$value" -ge 0 ] || fail "$name must be non-negative" + else + [ "$value" -gt 0 ] || fail "$name must be positive" + fi +} + +require_jq + +state_file='' +assignment_id='' +parent_id='' +role='' +source_repo='' +baseline='' +output_path='' +error_path='' +workspace_dir='' +workspace_manifest='' +max_depth='' +max_width='' +max_timeout='' +max_resources='' +depth_arg='' +timeout_arg='' +resources_arg='' +owned_paths=() +frozen_paths=() +worker_args=() +seen_delimiter=false + +while [ "$#" -gt 0 ]; do + if $seen_delimiter; then + worker_args+=("$1") + shift + continue + fi + case "$1" in + --) + seen_delimiter=true; shift ;; + --state|--assignment-id|--parent-assignment-id|--role|--source-repo|--baseline|--owned|--frozen|--output|--error|--workspace-dir|--workspace-manifest|--max-depth|--max-width|--max-timeout-seconds|--max-resource-units|--depth|--timeout-seconds|--resource-units) + option="$1" + [ "$#" -ge 2 ] || { usage; fail "$option requires a value"; } + value="$2" + shift 2 + case "$option" in + --state) state_file="$value" ;; + --assignment-id) assignment_id="$value" ;; + --parent-assignment-id) parent_id="$value" ;; + --role) role="$value" ;; + --source-repo) source_repo="$value" ;; + --baseline) baseline="$value" ;; + --owned) owned_paths+=("$value") ;; + --frozen) frozen_paths+=("$value") ;; + --output) output_path="$value" ;; + --error) error_path="$value" ;; + --workspace-dir) workspace_dir="$value" ;; + --workspace-manifest) workspace_manifest="$value" ;; + --max-depth) max_depth="$value" ;; + --max-width) max_width="$value" ;; + --max-timeout-seconds) max_timeout="$value" ;; + --max-resource-units) max_resources="$value" ;; + --depth) depth_arg="$value" ;; + --timeout-seconds) timeout_arg="$value" ;; + --resource-units) resources_arg="$value" ;; + esac + ;; + --state=*|--assignment-id=*|--parent-assignment-id=*|--role=*|--source-repo=*|--baseline=*|--owned=*|--frozen=*|--output=*|--error=*|--workspace-dir=*|--workspace-manifest=*|--max-depth=*|--max-width=*|--max-timeout-seconds=*|--max-resource-units=*|--depth=*|--timeout-seconds=*|--resource-units=*) + option="${1%%=*}"; value="${1#*=}"; shift + [ -n "$value" ] || fail "$option requires a value" + case "$option" in + --state) state_file="$value" ;; --assignment-id) assignment_id="$value" ;; + --parent-assignment-id) parent_id="$value" ;; --role) role="$value" ;; + --source-repo) source_repo="$value" ;; --baseline) baseline="$value" ;; + --owned) owned_paths+=("$value") ;; --frozen) frozen_paths+=("$value") ;; + --output) output_path="$value" ;; --error) error_path="$value" ;; + --workspace-dir) workspace_dir="$value" ;; --workspace-manifest) workspace_manifest="$value" ;; + --max-depth) max_depth="$value" ;; --max-width) max_width="$value" ;; + --max-timeout-seconds) max_timeout="$value" ;; --max-resource-units) max_resources="$value" ;; + --depth) depth_arg="$value" ;; --timeout-seconds) timeout_arg="$value" ;; + --resource-units) resources_arg="$value" ;; + esac + ;; + -h|--help) usage; exit 0 ;; + *) usage; fail "unknown dispatcher option: $1" ;; + esac +done + +$seen_delimiter || { usage; fail '-- delimiter is required'; } +[ "${#worker_args[@]}" -gt 0 ] || { usage; fail 'agy arguments are required after --'; } +[ -n "$state_file" ] || { usage; fail '--state is required'; } +[ -n "$assignment_id" ] || { usage; fail '--assignment-id is required'; } +[ -n "$role" ] || { usage; fail '--role is required'; } +[ -n "$source_repo" ] || { usage; fail '--source-repo is required'; } +[ -n "$baseline" ] || { usage; fail '--baseline is required'; } +[ -n "$output_path" ] || { usage; fail '--output is required'; } +[ -n "$error_path" ] || { usage; fail '--error is required'; } +[ "${#owned_paths[@]}" -gt 0 ] || fail 'at least one --owned path is required' +[ -n "$timeout_arg" ] || fail '--timeout-seconds is required' +[ -n "$resources_arg" ] || fail '--resource-units is required' +[[ "$assignment_id" != *[[:space:]/\\]* ]] || fail '--assignment-id cannot contain whitespace or path separators' +parse_positive_int '--timeout-seconds' "$timeout_arg" false +parse_positive_int '--resource-units' "$resources_arg" false + +if [ -n "$max_depth" ]; then parse_positive_int '--max-depth' "$max_depth" true; fi +if [ -n "$max_width" ]; then parse_positive_int '--max-width' "$max_width" false; fi +if [ -n "$max_timeout" ]; then parse_positive_int '--max-timeout-seconds' "$max_timeout" false; fi +if [ -n "$max_resources" ]; then parse_positive_int '--max-resource-units' "$max_resources" false; fi +if [ -n "$depth_arg" ]; then parse_positive_int '--depth' "$depth_arg" true; fi + +if [ "${OFFLOAD_WORKER_CONTEXT:-}" = '1' ]; then + record_rejection "$state_file" "$assignment_id" 'worker context cannot create assignments, processes, or worktrees' "$role" "$parent_id" + fail 'worker dispatch rejected: only the orchestrator may create assignments, processes, or worktrees' 126 +fi + +state_file=$(canonical_path "$state_file") +if [ -z "$workspace_manifest" ]; then + workspace_manifest="$(dirname "$state_file")/${assignment_id}.manifest.json" +fi +lock=$(acquire_lock "$state_file") +if [ -z "$parent_id" ]; then + [ -n "$max_depth" ] && [ -n "$max_width" ] && [ -n "$max_timeout" ] && [ -n "$max_resources" ] || { release_lock "$lock"; fail 'root dispatch requires all maximum limits'; } +elif [ ! -f "$state_file" ]; then + release_lock "$lock" + fail "dispatch ledger does not exist: $state_file" +fi + +if [ ! -f "$state_file" ]; then + jq -n --argjson md "$max_depth" --argjson mw "$max_width" --argjson mt "$max_timeout" --argjson mr "$max_resources" --arg marker "$STATE_MARKER" --arg created "$(now)" \ + '{schema_version:1, marker:$marker, limits:{max_depth:$md,max_width:$mw,max_timeout_seconds:$mt,max_resource_units:$mr}, assignments:[], events:[], created_at:$created}' >"$state_file" +fi +jq -e --arg marker "$STATE_MARKER" '(.marker == $marker and .schema_version == 1 and (.limits and .assignments and .events))' "$state_file" >/dev/null || { release_lock "$lock"; fail "invalid dispatch ledger: $state_file"; } + +if [ -n "$parent_id" ]; then + for pair in max_depth max_width max_timeout max_resources; do + value="${!pair}" + limit_key="$pair" + [ "$pair" = max_timeout ] && limit_key=max_timeout_seconds + [ "$pair" = max_resources ] && limit_key=max_resource_units + if [ -n "$value" ]; then + actual_limit=$(jq -r ".limits.$limit_key" "$state_file") + if [ "$value" -ne "$actual_limit" ]; then + request_json=$(jq -cn --arg parent "$parent_id" --arg limit "$limit_key" --argjson requested "$value" --argjson allowed "$actual_limit" '{parent_assignment_id:$parent,limit:$limit,requested:$requested,allowed:$allowed}') + append_rejection_locked "$state_file" "$assignment_id" 'child attempted to widen an immutable dispatch limit' "$request_json" + release_lock "$lock" + fail "child cannot change dispatch limit --$limit_key" 126 + fi + fi + done + parent_count=$(jq --arg p "$parent_id" '[.assignments[] | select(.assignment_id == $p)] | length' "$state_file") + [ "$parent_count" -eq 1 ] || { release_lock "$lock"; fail "parent assignment does not exist uniquely: $parent_id"; } + parent_depth=$(jq -r --arg p "$parent_id" '.assignments[] | select(.assignment_id == $p) | .depth' "$state_file") + depth=$((parent_depth + 1)) +else + depth=0 +fi +[ -z "$depth_arg" ] || [ "$depth_arg" -eq "$depth" ] || { release_lock "$lock"; fail '--depth does not match parent depth'; } +max_depth_value=$(jq -r '.limits.max_depth' "$state_file") +max_width_value=$(jq -r '.limits.max_width' "$state_file") +max_timeout_value=$(jq -r '.limits.max_timeout_seconds' "$state_file") +max_resources_value=$(jq -r '.limits.max_resource_units' "$state_file") +[ "$depth" -le "$max_depth_value" ] || { append_rejection_locked "$state_file" "$assignment_id" 'maximum dispatch depth exceeded' "$(jq -cn --arg parent "$parent_id" --argjson depth "$depth" --argjson max_depth "$max_depth_value" '{parent_assignment_id:(if $parent == "" then null else $parent end),depth:$depth,max_depth:$max_depth}')"; release_lock "$lock"; fail 'dispatch rejected: maximum depth exceeded' 126; } +if [ -n "$parent_id" ]; then + child_count=$(jq --arg p "$parent_id" '[.assignments[] | select(.parent_assignment_id == $p)] | length' "$state_file") + [ "$child_count" -lt "$max_width_value" ] || { append_rejection_locked "$state_file" "$assignment_id" 'maximum child width exceeded' "$(jq -cn --arg parent "$parent_id" --argjson width "$((child_count + 1))" --argjson max_width "$max_width_value" '{parent_assignment_id:$parent,width:$width,max_width:$max_width}')"; release_lock "$lock"; fail 'dispatch rejected: maximum child width exceeded' 126; } +fi +[ "$timeout_arg" -le "$max_timeout_value" ] || { append_rejection_locked "$state_file" "$assignment_id" 'assignment timeout exceeds maximum' "$(jq -cn --argjson timeout_seconds "$timeout_arg" --argjson max_timeout_seconds "$max_timeout_value" '{timeout_seconds:$timeout_seconds,max_timeout_seconds:$max_timeout_seconds}')"; release_lock "$lock"; fail 'dispatch rejected: timeout exceeds maximum' 126; } +used_resources=$(jq '[.assignments[].budget.resource_units] | add // 0' "$state_file") +[ $((used_resources + resources_arg)) -le "$max_resources_value" ] || { append_rejection_locked "$state_file" "$assignment_id" 'maximum resource budget exceeded' "$(jq -cn --argjson resource_units "$resources_arg" --argjson used_resource_units "$used_resources" --argjson max_resource_units "$max_resources_value" '{resource_units:$resource_units,used_resource_units:$used_resource_units,max_resource_units:$max_resource_units}')"; release_lock "$lock"; fail 'dispatch rejected: resource budget exceeded' 126; } +duplicate_count=$(jq --arg id "$assignment_id" '[.assignments[] | select(.assignment_id == $id)] | length' "$state_file") +[ "$duplicate_count" -eq 0 ] || { release_lock "$lock"; fail "assignment id already exists: $assignment_id"; } + +source_repo_abs=$(canonical_path "$source_repo") +output_abs=$(canonical_path "$output_path") +error_abs=$(canonical_path "$error_path") +[ -n "$source_repo_abs" ] && source_repo="$source_repo_abs" +output_path="$output_abs" +error_path="$error_abs" +if [ -n "$workspace_dir" ]; then workspace_dir=$(canonical_path "$workspace_dir"); fi +if [ -n "$workspace_manifest" ]; then workspace_manifest=$(canonical_path "$workspace_manifest"); fi +manifest_abs='null'; [ -n "$workspace_manifest" ] && manifest_abs=$(printf '%s' "$(canonical_path "$workspace_manifest")" | jq -R .) +workspace_abs='null'; [ -n "$workspace_dir" ] && workspace_abs=$(printf '%s' "$(canonical_path "$workspace_dir")" | jq -R .) +owned_json=$(printf '%s\n' "${owned_paths[@]}" | jq -R . | jq -s .) +frozen_json=$(if [ "${#frozen_paths[@]}" -gt 0 ]; then printf '%s\n' "${frozen_paths[@]}" | jq -R . | jq -s .; else printf '[]'; fi) +jq --arg id "$assignment_id" --arg parent "$parent_id" --arg role_value "$role" --arg repo "$source_repo_abs" --arg base "$baseline" \ + --arg out "$output_abs" --arg err "$error_abs" --argjson manifest "$manifest_abs" --argjson workspace "$workspace_abs" \ + --argjson owned "$owned_json" --argjson frozen "$frozen_json" --argjson depth "$depth" --argjson timeout "$timeout_arg" --argjson resources "$resources_arg" --arg created "$(now)" \ + '.assignments += [{assignment_id:$id,parent_assignment_id:(if $parent == "" then null else $parent end),child_assignment_ids:[],depth:$depth,budget:{timeout_seconds:$timeout,resource_units:$resources},owned_paths:$owned,frozen_paths:$frozen,role:$role_value,lifecycle_state:"created",source_repo:$repo,baseline:$base,output_path:$out,error_path:$err,workspace_manifest:$manifest,workspace_dir:$workspace,created_at:$created,started_at:null,ended_at:null,exit_code:null}] | + if $parent == "" then . else .assignments |= map(if .assignment_id == $parent then .child_assignment_ids += [$id] else . end) end' "$state_file" >"${state_file}.$$.tmp" +mv -f "${state_file}.$$.tmp" "$state_file" +release_lock "$lock" + +mark_assignment_failed() { + local assignment="$1" exit_code="$2" failure_message="$3" lock + lock=$(acquire_lock "$state_file") + jq --arg id "$assignment" --arg ended "$(now)" --arg message "$failure_message" --argjson exit_code "$exit_code" \ + '(.assignments[] | select(.assignment_id == $id)) |= (.lifecycle_state="failed" | .ended_at=$ended | .exit_code=$exit_code | .failure=$message)' \ + "$state_file" >"${state_file}.$$.tmp" + mv -f "${state_file}.$$.tmp" "$state_file" + release_lock "$lock" +} + +workspace_args=(create --source-repo "$source_repo" --task-id "$assignment_id" --baseline "$baseline") +for path in "${owned_paths[@]}"; do workspace_args+=(--owned "$path"); done +for path in "${frozen_paths[@]}"; do workspace_args+=(--frozen "$path"); done +[ -n "$workspace_manifest" ] && workspace_args+=(--manifest "$workspace_manifest") +[ -n "$workspace_dir" ] && workspace_args+=(--workspace-dir "$workspace_dir") +set +e +workspace_output=$("$WORKSPACE_HELPER" "${workspace_args[@]}" 2>&1) +workspace_exit=$? +set -e +if [ "$workspace_exit" -ne 0 ]; then + mark_assignment_failed "$assignment_id" 1 "worktree creation failed: $workspace_output" + fail "failed to create worker worktree: $workspace_output" 1 +fi +if [ -n "$workspace_dir" ]; then + workspace_path=$(canonical_path "$workspace_dir") +else + if [ ! -f "$workspace_manifest" ]; then + mark_assignment_failed "$assignment_id" 1 'workspace helper did not produce a manifest for the assigned worker' + fail 'workspace helper did not produce a manifest for the assigned worker' 1 + fi + workspace_path=$(jq -r '.workspace_dir' "$workspace_manifest") +fi +if [ ! -d "$workspace_path" ]; then + mark_assignment_failed "$assignment_id" 1 "assigned worker worktree does not exist: $workspace_path" + fail "assigned worker worktree does not exist: $workspace_path" 1 +fi + +lock=$(acquire_lock "$state_file") +jq --arg id "$assignment_id" --arg workspace "$workspace_path" --arg manifest "$workspace_manifest" --arg started "$(now)" \ + '(.assignments[] | select(.assignment_id == $id)) |= (.workspace_dir=$workspace | .workspace_manifest=(if $manifest == "" then .workspace_manifest else $manifest end) | .lifecycle_state="running" | .started_at=$started)' "$state_file" >"${state_file}.$$.tmp" +mv -f "${state_file}.$$.tmp" "$state_file" +release_lock "$lock" + +set +e +(cd "$workspace_path" && "$LAUNCHER" --role "$role" --timeout-seconds "$timeout_arg" --output "$output_path" --error "$error_path" -- "${worker_args[@]}") +worker_exit=$? +set -e + +lock=$(acquire_lock "$state_file") +jq --arg id "$assignment_id" --arg ended "$(now)" --argjson exit_code "$worker_exit" \ + '(.assignments[] | select(.assignment_id == $id)) |= (.lifecycle_state=(if $exit_code == 0 then "completed" else "failed" end) | .ended_at=$ended | .exit_code=$exit_code)' "$state_file" >"${state_file}.$$.tmp" +mv -f "${state_file}.$$.tmp" "$state_file" +release_lock "$lock" + +jq -c --arg id "$assignment_id" '.assignments[] | select(.assignment_id == $id)' "$state_file" +exit "$worker_exit" diff --git a/scripts/execution-workspace.ps1 b/scripts/execution-workspace.ps1 index edeb082..8398fb6 100644 --- a/scripts/execution-workspace.ps1 +++ b/scripts/execution-workspace.ps1 @@ -865,6 +865,10 @@ if ($args.Count -eq 0) { $commandVerb = [string]$args[0] $restArgs = if ($args.Count -gt 1) { [string[]]$args[1..($args.Count - 1)] } else { @() } +if ($env:OFFLOAD_WORKER_CONTEXT -eq '1' -and $commandVerb -in @('create', 'verify-export', 'export', 'integrate', 'cleanup')) { + Fail 'worker context cannot create or mutate execution worktrees; only the orchestrator may invoke this lifecycle helper' 126 +} + switch ($commandVerb) { 'create' { Cmd-Create $restArgs diff --git a/scripts/execution-workspace.sh b/scripts/execution-workspace.sh index c624098..a00a6cc 100644 --- a/scripts/execution-workspace.sh +++ b/scripts/execution-workspace.sh @@ -941,6 +941,14 @@ cmd_cleanup() { command_verb="$1" shift +case "$command_verb" in + create|verify-export|export|integrate|cleanup) + if [ "${OFFLOAD_WORKER_CONTEXT:-}" = '1' ]; then + fail 'worker context cannot create or mutate execution worktrees; only the orchestrator may invoke this lifecycle helper' 126 + fi + ;; +esac + case "$command_verb" in create) cmd_create "$@" diff --git a/scripts/run-agy-json.ps1 b/scripts/run-agy-json.ps1 index 8bca72f..4b16a39 100644 --- a/scripts/run-agy-json.ps1 +++ b/scripts/run-agy-json.ps1 @@ -7,7 +7,7 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version 3.0 function Show-Usage { - [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] --output FILE --error FILE '--' agy-arguments...") + [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] [--timeout-seconds N] --output FILE --error FILE '--' agy-arguments...") [Console]::Error.WriteLine("In PowerShell command expressions, quote '--' because PowerShell consumes the bare delimiter before the helper receives it.") } @@ -20,10 +20,12 @@ $outputPath = "" $errorPath = "" $role = "" $route = "" +$timeoutSeconds = $null $seenOutput = $false $seenError = $false $seenRole = $false $seenRoute = $false +$seenTimeout = $false $seenDashDash = $false $forwardedArgs = [System.Collections.Generic.List[string]]::new() @@ -122,6 +124,27 @@ while ($i -lt $args.Count) { Fail "--route requires a route name" } $seenRoute = $true + } elseif ($arg -eq '--timeout-seconds') { + if ($seenTimeout) { + Fail "duplicate --timeout-seconds option" + } + $i++ + if ($i -ge $args.Count) { + Show-Usage + Fail "--timeout-seconds requires a positive integer" + } + $timeoutSeconds = [string]$args[$i] + $seenTimeout = $true + } elseif ($arg.StartsWith('--timeout-seconds=')) { + if ($seenTimeout) { + Fail "duplicate --timeout-seconds option" + } + $timeoutSeconds = $arg.Substring('--timeout-seconds='.Length) + if ([string]::IsNullOrWhiteSpace($timeoutSeconds)) { + Show-Usage + Fail "--timeout-seconds requires a positive integer" + } + $seenTimeout = $true } else { Show-Usage Fail "unknown launcher option: $arg" @@ -146,6 +169,18 @@ if (-not $seenRole -or [string]::IsNullOrWhiteSpace($role)) { Fail "--role is required; specify a role and remove any caller --model flag" } +if ($env:OFFLOAD_WORKER_CONTEXT -eq '1') { + Fail 'worker process cannot invoke the launcher; only the orchestrator may create worker processes' 126 +} + +if ($seenTimeout) { + $parsedTimeout = 0 + if (-not [int]::TryParse($timeoutSeconds, [Globalization.NumberStyles]::Integer, [Globalization.CultureInfo]::InvariantCulture, [ref]$parsedTimeout) -or $parsedTimeout -le 0) { + Fail '--timeout-seconds must be a positive integer' + } + $timeoutSeconds = $parsedTimeout +} + $knownRoles = @('scout', 'gate-author', 'implementer', 'reviewer', 'researcher', 'synthesizer', 'auditor') if ($knownRoles -notcontains $role) { Fail "unknown role: '$role'; must be one of $($knownRoles -join ', ')" @@ -445,6 +480,7 @@ try { $psi.WorkingDirectory = $callerWorkingDirectory $psi.RedirectStandardOutput = $true $psi.RedirectStandardError = $true + $psi.EnvironmentVariables['OFFLOAD_WORKER_CONTEXT'] = '1' $psi.ArgumentList.Add('--model') $psi.ArgumentList.Add($resolvedModel) foreach ($arg in $forwardedArgs) { @@ -470,9 +506,25 @@ try { $outTask = $proc.StandardOutput.BaseStream.CopyToAsync($outFs) $errTask = $proc.StandardError.BaseStream.CopyToAsync($errFs) - $proc.WaitForExit() + $timedOut = $false + if ($null -eq $timeoutSeconds) { + $proc.WaitForExit() + } elseif (-not $proc.WaitForExit([int]$timeoutSeconds * 1000)) { + $timedOut = $true + try { + $proc.Kill($true) + } catch [System.InvalidOperationException] { + # Process exited during the timeout check. + } + $proc.WaitForExit() + } [System.Threading.Tasks.Task]::WaitAll(@($outTask, $errTask)) - $workerExitCode = $proc.ExitCode + $workerExitCode = if ($timedOut) { 124 } else { $proc.ExitCode } + if ($timedOut) { + $timeoutMessage = [System.Text.UTF8Encoding]::new($false).GetBytes("worker exceeded timeout of $timeoutSeconds seconds`n") + $errFs.Write($timeoutMessage, 0, $timeoutMessage.Length) + $errFs.Flush() + } $launcherSuccess = $true } catch { Fail "launcher failed after starting worker: $($_.Exception.Message)" 1 diff --git a/scripts/run-agy-json.sh b/scripts/run-agy-json.sh index d9ad2b4..9892ca0 100755 --- a/scripts/run-agy-json.sh +++ b/scripts/run-agy-json.sh @@ -2,7 +2,7 @@ set -euo pipefail usage() { - printf 'Usage: %s --role ROLE [--route default|quality-retry] --output FILE --error FILE -- agy-arguments...\n' "$0" >&2 + printf 'Usage: %s --role ROLE [--route default|quality-retry] [--timeout-seconds N] --output FILE --error FILE -- agy-arguments...\n' "$0" >&2 } fail() { @@ -14,11 +14,13 @@ output_path='' error_path='' role='' route='' +timeout_seconds='' seen_output=false seen_error=false seen_role=false seen_route=false +seen_timeout=false seen_delimiter=false worker_args=() @@ -80,6 +82,20 @@ while [ "$#" -gt 0 ]; do seen_route=true shift ;; + --timeout-seconds) + $seen_timeout && fail 'duplicate --timeout-seconds option' + [ "$#" -ge 2 ] || { usage; fail '--timeout-seconds requires a positive integer'; } + timeout_seconds="$2" + seen_timeout=true + shift 2 + ;; + --timeout-seconds=*) + $seen_timeout && fail 'duplicate --timeout-seconds option' + timeout_seconds="${1#--timeout-seconds=}" + [ -n "$timeout_seconds" ] || { usage; fail '--timeout-seconds requires a positive integer'; } + seen_timeout=true + shift + ;; --) seen_delimiter=true shift @@ -113,6 +129,17 @@ if ! $seen_role || [ -z "$role" ]; then fail '--role is required; specify a role and remove any caller --model flag' fi +if [ "${OFFLOAD_WORKER_CONTEXT:-}" = '1' ]; then + fail 'worker process cannot invoke the launcher; only the orchestrator may create worker processes' 126 +fi + +if $seen_timeout; then + case "$timeout_seconds" in + ''|*[!0-9]*) fail '--timeout-seconds must be a positive integer' ;; + esac + [ "$timeout_seconds" -gt 0 ] || fail '--timeout-seconds must be a positive integer' +fi + case "$role" in scout|gate-author|implementer|reviewer|researcher|synthesizer|auditor) ;; *) @@ -273,9 +300,35 @@ fi mkdir -p "$(dirname "$output_path")" "$(dirname "$error_path")" -set +e -"$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" -worker_exit=$? -set -e +if ! $seen_timeout; then + set +e + OFFLOAD_WORKER_CONTEXT=1 "$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" + worker_exit=$? + set -e +else + set +e + OFFLOAD_WORKER_CONTEXT=1 "$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" & + worker_pid=$! + start_epoch=$(date +%s) + timed_out=false + while kill -0 "$worker_pid" 2>/dev/null; do + now_epoch=$(date +%s) + if [ $((now_epoch - start_epoch)) -ge "$timeout_seconds" ]; then + timed_out=true + kill "$worker_pid" 2>/dev/null || true + break + fi + sleep 0.1 + done + wait "$worker_pid" 2>/dev/null + child_exit=$? + if $timed_out; then + printf 'worker exceeded timeout of %s seconds\n' "$timeout_seconds" >>"$error_path" + worker_exit=124 + else + worker_exit=$child_exit + fi + set -e +fi exit "$worker_exit" diff --git a/tests/test_dispatch_control.ps1 b/tests/test_dispatch_control.ps1 new file mode 100644 index 0000000..9c1ebb1 --- /dev/null +++ b/tests/test_dispatch_control.ps1 @@ -0,0 +1,175 @@ +#!/usr/bin/env pwsh +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Assert-True([bool]$condition, [string]$message) { + if (-not $condition) { throw "FAIL: $message" } + [Console]::Out.WriteLine("ok - $message") +} + +$root = Split-Path -Parent $PSScriptRoot +$dispatch = Join-Path $root 'scripts/dispatch-worker.ps1' +$workspaceHelper = Join-Path $root 'scripts/execution-workspace.ps1' +$pwsh = (Get-Command pwsh).Source +$tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) "offload-dispatch-$([guid]::NewGuid().ToString('N'))" +[System.IO.Directory]::CreateDirectory($tempRoot) | Out-Null + +try { + $fakeAgy = Join-Path $tempRoot 'fake-agy.ps1' + @' +$nestedOutput = Join-Path $env:DISPATCH_TEST_ROOT 'nested.json' +$nestedError = Join-Path $env:DISPATCH_TEST_ROOT 'nested.err' +& $env:PWsh_BIN -NoProfile -File $env:DISPATCH_SCRIPT ` + --state $env:DISPATCH_STATE ` + --assignment-id nested-worker ` + --parent-assignment-id root-worker ` + --role scout ` + --source-repo $env:DISPATCH_SOURCE_REPO ` + --baseline $env:DISPATCH_BASELINE ` + --owned README.md ` + --output $nestedOutput ` + --error $nestedError ` + --timeout-seconds 10 ` + --resource-units 1 ` + -- -p 'nested attempt' +$nestedExit = $LASTEXITCODE +if ($env:DISPATCH_TIMEOUT_TEST -eq '1') { Start-Sleep -Seconds 10 } +$result = [ordered]@{ + status = 'success' + response = 'fake worker' + structured_output = [ordered]@{ + request_more_work = [ordered]@{ role = 'scout'; prompt = 'inspect README.md' } + nested_dispatch_exit = $nestedExit + working_directory = (Get-Location).Path + } +} +$result | ConvertTo-Json -Compress +'@ | Set-Content -LiteralPath $fakeAgy -Encoding utf8 + + $state = Join-Path $tempRoot 'dispatch.json' + $manifest = Join-Path $tempRoot 'root-worker.manifest.json' + $timeoutManifest = Join-Path $tempRoot 'timeout-worker.manifest.json' + $output = Join-Path $tempRoot 'root.json' + $errorPath = Join-Path $tempRoot 'root.err' + $workspace = Join-Path $tempRoot 'root-worktree' + $baseline = (& git -C $root rev-parse HEAD).Trim() + $envForWorker = @{ + AGY_BIN = $fakeAgy + DISPATCH_SCRIPT = $dispatch + DISPATCH_STATE = $state + DISPATCH_SOURCE_REPO = $root + DISPATCH_BASELINE = $baseline + DISPATCH_TEST_ROOT = $tempRoot + PWsh_BIN = $pwsh + } + + $psi = [System.Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $pwsh + @('-NoProfile', '-File', $dispatch, + '--state', $state, + '--assignment-id', 'root-worker', + '--role', 'scout', + '--max-depth', '2', + '--max-width', '2', + '--max-timeout-seconds', '30', + '--max-resource-units', '4', + '--resource-units', '1', + '--timeout-seconds', '10', + '--source-repo', $root, + '--baseline', $baseline, + '--owned', 'README.md', + '--workspace-dir', $workspace, + '--output', $output, + '--error', $errorPath, + '--', '-p', 'root attempt') | ForEach-Object { $psi.ArgumentList.Add($_) } +$psi.UseShellExecute = $false +$psi.RedirectStandardOutput = $true +$psi.RedirectStandardError = $true +foreach ($key in $envForWorker.Keys) { $psi.Environment[$key] = $envForWorker[$key] } +$process = [System.Diagnostics.Process]::Start($psi) +$stdout = $process.StandardOutput.ReadToEnd() +$stderr = $process.StandardError.ReadToEnd() +$process.WaitForExit() + + Assert-True ($process.ExitCode -eq 0) "root dispatch succeeds: $stderr" + Assert-True (Test-Path -LiteralPath $workspace -PathType Container) 'root dispatch creates the worker worktree' + Assert-True (Test-Path -LiteralPath $state -PathType Leaf) 'root dispatch writes a dispatch ledger' + $ledger = Get-Content -LiteralPath $state -Raw | ConvertFrom-Json + Assert-True ($ledger.assignments.Count -eq 1) 'nested worker does not create a tracked child assignment' + $assignment = $ledger.assignments[0] + Assert-True ($assignment.assignment_id -eq 'root-worker' -and $null -eq $assignment.parent_assignment_id -and $assignment.depth -eq 0) 'root assignment records its identity, parent, and depth' + Assert-True ($assignment.budget.timeout_seconds -eq 10 -and $assignment.budget.resource_units -eq 1) 'assignment records its bounded budget' + Assert-True ($assignment.owned_paths[0] -eq 'README.md' -and $assignment.lifecycle_state -eq 'completed') 'assignment records owned paths and lifecycle state' + Assert-True (@($ledger.events | Where-Object { $_.type -eq 'nested_dispatch_rejected' -and $_.assignment_id -eq 'nested-worker' -and $_.request.parent_assignment_id -eq 'root-worker' }).Count -eq 1) 'ledger records the rejected nested-dispatch attempt' + $workerResult = Get-Content -LiteralPath $output -Raw | ConvertFrom-Json + Assert-True ($workerResult.structured_output.request_more_work.role -eq 'scout') 'worker requests remain structured result data' + Assert-True ($workerResult.structured_output.nested_dispatch_exit -ne 0) 'worker nested dispatch does not start a process' + Assert-True ([System.IO.Path]::GetFullPath($workerResult.structured_output.working_directory) -eq [System.IO.Path]::GetFullPath($workspace)) 'worker starts inside its admitted worktree' + + $rejectedOutput = Join-Path $tempRoot 'rejected.json' + $rejectedError = Join-Path $tempRoot 'rejected.err' + & $pwsh -NoProfile -File $dispatch ` + --state $state ` + --assignment-id over-budget-worker ` + --parent-assignment-id root-worker ` + --role scout ` + --max-depth 2 ` + --max-width 2 ` + --max-timeout-seconds 30 ` + --max-resource-units 4 ` + --resource-units 4 ` + --timeout-seconds 10 ` + --source-repo $root ` + --baseline $baseline ` + --owned README.md ` + --output $rejectedOutput ` + --error $rejectedError ` + -- -p 'over budget attempt' 2>$rejectedError 1>$rejectedOutput + $rejectedExit = $LASTEXITCODE + Assert-True ($rejectedExit -eq 126) 'dispatcher rejects assignments before exceeding resource budget' + Assert-True (-not (Test-Path -LiteralPath (Join-Path $tempRoot 'over-budget-worker.manifest.json'))) 'rejected assignment does not create a worktree manifest' + $ledger = Get-Content -LiteralPath $state -Raw | ConvertFrom-Json + Assert-True (@($ledger.events | Where-Object { $_.assignment_id -eq 'over-budget-worker' -and $_.reason -eq 'maximum resource budget exceeded' }).Count -eq 1) 'ledger records the resource-budget rejection' + + $timeoutOutput = Join-Path $tempRoot 'timeout-worker.json' + $timeoutError = Join-Path $tempRoot 'timeout-worker.err' + $previousTimeoutFlag = $env:DISPATCH_TIMEOUT_TEST + try { + $env:DISPATCH_TIMEOUT_TEST = '1' + & $pwsh -NoProfile -File $dispatch ` + --state $state ` + --assignment-id timeout-worker ` + --parent-assignment-id root-worker ` + --role scout ` + --max-depth 2 ` + --max-width 2 ` + --max-timeout-seconds 30 ` + --max-resource-units 4 ` + --resource-units 1 ` + --timeout-seconds 2 ` + --source-repo $root ` + --baseline $baseline ` + --owned README.md ` + --output $timeoutOutput ` + --error $timeoutError ` + -- -p 'timeout attempt' + $timeoutExit = $LASTEXITCODE + } finally { + if ($null -eq $previousTimeoutFlag) { Remove-Item Env:DISPATCH_TIMEOUT_TEST -ErrorAction SilentlyContinue } else { $env:DISPATCH_TIMEOUT_TEST = $previousTimeoutFlag } + } + $timeoutDiagnostic = if (Test-Path -LiteralPath $timeoutError -PathType Leaf) { Get-Content -LiteralPath $timeoutError -Raw } else { '' } + Assert-True ($timeoutExit -eq 124) "dispatcher stops a worker before its timeout budget is exceeded (exit $timeoutExit; $timeoutDiagnostic)" + $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 { + if (Test-Path -LiteralPath $manifest -PathType Leaf) { + & $workspaceHelper cleanup --manifest $manifest --status success 2>$null | Out-Null + } + if (Test-Path -LiteralPath $timeoutManifest -PathType Leaf) { + & $workspaceHelper cleanup --manifest $timeoutManifest --status success 2>$null | Out-Null + } + if (Test-Path -LiteralPath $tempRoot) { Remove-Item -LiteralPath $tempRoot -Recurse -Force } +} + +[Console]::Out.WriteLine('dispatch control checks passed') From c8a704a512be69024469e5c8f65ff8b6b651a07c Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 17:37:00 +0800 Subject: [PATCH 06/11] feat: add Claude worker adapter --- README.md | 16 + docs/specs/0004-claude-adapter.md | 61 ++++ scripts/run-claude-json.ps1 | 506 ++++++++++++++++++++++++++++++ scripts/run-claude-json.sh | 278 ++++++++++++++++ tests/test_claude_adapter.ps1 | 203 ++++++++++++ tests/test_claude_adapter.sh | 104 ++++++ 6 files changed, 1168 insertions(+) create mode 100644 docs/specs/0004-claude-adapter.md create mode 100644 scripts/run-claude-json.ps1 create mode 100755 scripts/run-claude-json.sh create mode 100644 tests/test_claude_adapter.ps1 create mode 100755 tests/test_claude_adapter.sh diff --git a/README.md b/README.md index 2436edb..230e8d7 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,22 @@ Offload's online-research workflow is adapted from Asa by Achibukz, used with pe Orchestrators select helper scripts based on their current shell (`.sh` for Bash, `.ps1` for PowerShell), never by host operating system detection or universal launchers. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +### Claude adapter + +The bounded Claude Code adapter is available as `scripts/run-claude-json.ps1` and +`scripts/run-claude-json.sh`. It accepts the versioned assignment contract in +[`docs/specs/0004-claude-adapter.md`](docs/specs/0004-claude-adapter.md), probes +the installed Claude CLI, forwards only the assignment's bounded prompt and +tool policy, and returns a normalized result with raw artifacts, process and +worktree ledger records, and scope and gate verification. + +Set `CLAUDE_BIN` when Claude is not on `PATH`. The adapter accepts internal +`fast`, `balanced`, and `deep` preferences without mapping them to published +model IDs. A pinned model requires a caller-provided live catalog. Unsupported +or unmarked sandboxes fail closed. On Windows, use an isolated runtime such as +WSL, Git for Windows, or the supported native Claude binary; the adapter does +not turn the caller checkout into a sandbox. + ## Requirements - A CLI coding agent that can read skills and run shell commands (Claude Code, Codex CLI, or similar). diff --git a/docs/specs/0004-claude-adapter.md b/docs/specs/0004-claude-adapter.md new file mode 100644 index 0000000..0b9e349 --- /dev/null +++ b/docs/specs/0004-claude-adapter.md @@ -0,0 +1,61 @@ +# Claude adapter contract + +The Claude adapter is one adapter for one bounded worker assignment. The +orchestrator owns assignment constraints, verification, lifecycle, and cleanup. +The adapter owns only Claude Code command syntax and response parsing. + +## Assignment + +An assignment is a JSON object with `schema_version: 1` and these fields: + +- `assignment_id`, `prompt`, and `working_directory` are required. +- `owned_paths`, `frozen_paths`, `baseline`, and `gate_command` describe the + execution scope and final gate. They are required for an execution run. +- `preference` is `fast`, `balanced`, or `deep`. It is an internal preference, + not a Claude model name. +- `model` and `effort` are optional pinned choices selected by the + orchestrator. The adapter never publishes a model ID or maps a family hint + to a permission. +- `allowed_tools` and `disallowed_tools` are static assignment constraints. + The adapter always adds Claude's child-assignment tools to the denied set. +- `timeout_seconds`, `resume_session_id`, `cancel_file`, and `ledger_path` are + optional lifecycle and ownership data. + +The working directory must contain an `.offload-execution-workspace` or +`.offload-research-workspace` marker. The adapter rejects the caller checkout, +an unmarked directory, unsafe permission mode, path escapes, arbitrary Claude +arguments, and attempts to pass `--model`, `--effort`, or permission flags from +the caller. + +## Normalized result + +The adapter writes a JSON result with `schema_version`, `assignment_id`, +`adapter`, `status`, `lifecycle`, `exit_code`, `response`, `structured_output`, +`session_id`, `capabilities`, `model_selection`, `resources`, `artifacts`, and +`verification`. A result reaches the caller as `completed` only after the +execution scope check and final gate both pass. + +The adapter reports capability discovery from `claude --version` and +`claude --help`. A host-provided catalog may be supplied through +`CLAUDE_MODEL_CATALOG` or `model_catalog_path`; when neither exists, model +availability is `unknown`. A pinned model cannot run while availability is +unknown. This fails closed instead of guessing. + +## Lifecycle and resources + +The lifecycle is `created`, `started`, `running`, `completed`, `failed`, +`canceled`, `quota-handoff`, `retained`, or `cleaned`. Cancellation and timeout +terminate Claude, wait for process exit, and preserve stdout and stderr. + +Before launch, the adapter registers the worktree, process placeholder, raw +output, raw error, normalized result, and verification artifacts in the +orchestrator-owned ledger. It updates the process identity and terminal state. +The adapter never deletes ledger resources. Cleanup and reconciliation remain +orchestrator responsibilities. + +Claude Code features tested by the fake suite are print mode, JSON output, +model and permission flags, allowed and denied tools, resume IDs, process +termination, malformed JSON handling, and post-run scope/gate verification. +Native Windows Claude Code hosts need WSL, Git for Windows, or the supported +native binary. Any host that cannot provide a marked isolated runtime must be +rejected or run in a separately provisioned isolated environment. diff --git a/scripts/run-claude-json.ps1 b/scripts/run-claude-json.ps1 new file mode 100644 index 0000000..6d35180 --- /dev/null +++ b/scripts/run-claude-json.ps1 @@ -0,0 +1,506 @@ +#!/usr/bin/env pwsh +# Launch one bounded Claude Code assignment and return an orchestrator-verifiable result. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 +$script:FailureOutputPath = '' + +function Full([string]$Path) { + return [System.IO.Path]::GetFullPath($Path) +} + +function Same([string]$A, [string]$B) { + $left = (Full $A).TrimEnd('\', '/') + $right = (Full $B).TrimEnd('\', '/') + return [string]::Equals($left, $right, [System.StringComparison]::OrdinalIgnoreCase) +} + +function Within([string]$Child, [string]$Parent) { + $childPath = (Full $Child).TrimEnd('\', '/') + $parentPath = (Full $Parent).TrimEnd('\', '/') + return (Same $childPath $parentPath) -or + $childPath.StartsWith("$parentPath\", [System.StringComparison]::OrdinalIgnoreCase) -or + $childPath.StartsWith("$parentPath/", [System.StringComparison]::OrdinalIgnoreCase) +} + +function Iso { + return [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ') +} + +function Write-Json([string]$Path, $Value) { + $fullPath = Full $Path + $directory = Split-Path -Parent $fullPath + if ($directory -and -not (Test-Path -LiteralPath $directory -PathType Container)) { + [IO.Directory]::CreateDirectory($directory) | Out-Null + } + $temporaryPath = "$fullPath.tmp.$([Guid]::NewGuid().ToString('N'))" + try { + $json = ($Value | ConvertTo-Json -Depth 30) + "`n" + [IO.File]::WriteAllText($temporaryPath, $json, [Text.UTF8Encoding]::new($false)) + Move-Item -LiteralPath $temporaryPath -Destination $fullPath -Force + } finally { + if (Test-Path -LiteralPath $temporaryPath -PathType Leaf) { + Remove-Item -LiteralPath $temporaryPath -Force + } + } +} + +function Fail([string]$Message, [int]$Code = 2) { + [Console]::Error.WriteLine("ERROR: $Message") + if ($script:FailureOutputPath) { + try { + Write-Json $script:FailureOutputPath ([ordered]@{ + schema_version = 1 + adapter = 'claude' + status = 'failed' + lifecycle = 'failed' + error = $Message + }) + } catch { + # Preserve the original diagnostic if the result path is unusable. + } + } + exit $Code +} + +function Read-Json([string]$Path) { + if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { + Fail "JSON file does not exist: $Path" + } + try { + return Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -Depth 30 -ErrorAction Stop + } catch { + Fail "invalid JSON in $Path" + } +} + +function Has-Property($Object, [string]$Name) { + return $null -ne $Object -and ($Object.PSObject.Properties.Name -contains $Name) +} + +function Optional-String($Object, [string]$Name, [string]$Default = '') { + if ($null -ne $Object -and (Has-Property $Object $Name) -and $null -ne $Object.$Name) { + return [string]$Object.$Name + } + return $Default +} + +function Optional-Array($Object, [string]$Name) { + if ($null -ne $Object -and (Has-Property $Object $Name) -and $null -ne $Object.$Name) { + return @($Object.$Name | ForEach-Object { [string]$_ }) + } + return @() +} + +function Resolve-Claude { + $requested = if ($env:CLAUDE_BIN) { [string]$env:CLAUDE_BIN } else { '' } + if ($requested) { + $command = Get-Command $requested -ErrorAction SilentlyContinue + if ($command) { + return $(if ($command.Source) { $command.Source } else { $command.Name }) + } + if (Test-Path -LiteralPath $requested -PathType Leaf) { + return (Resolve-Path -LiteralPath $requested).Path + } + Fail "CLAUDE_BIN does not resolve to an executable: $requested" 1 + } + + $command = Get-Command claude -ErrorAction SilentlyContinue + if ($command) { + return $(if ($command.Source) { $command.Source } else { $command.Name }) + } + Fail 'claude was not found; set CLAUDE_BIN or add claude to PATH' 1 +} + +function New-ProcessInfo([string]$Executable, [string[]]$Arguments, [string]$WorkingDirectory = '') { + $psi = [Diagnostics.ProcessStartInfo]::new() + $isPowerShellScript = $Executable.EndsWith('.ps1', [System.StringComparison]::OrdinalIgnoreCase) + if ($isPowerShellScript) { + $pwsh = (Get-Command pwsh -ErrorAction SilentlyContinue)?.Source + if (-not $pwsh) { $pwsh = (Get-Process -Id $PID).Path } + $psi.FileName = $pwsh + $psi.ArgumentList.Add('-NoProfile') + $psi.ArgumentList.Add('-NonInteractive') + $psi.ArgumentList.Add('-File') + $psi.ArgumentList.Add($Executable) + } else { + $psi.FileName = $Executable + } + foreach ($argument in $Arguments) { $psi.ArgumentList.Add($argument) } + if ($WorkingDirectory) { $psi.WorkingDirectory = $WorkingDirectory } + $psi.UseShellExecute = $false + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + $psi.CreateNoWindow = $true + $psi.StandardOutputEncoding = [Text.Encoding]::UTF8 + $psi.StandardErrorEncoding = [Text.Encoding]::UTF8 + return $psi +} + +function Invoke-Probe([string]$Executable, [string[]]$Arguments, [string]$WorkingDirectory = '') { + try { + $process = [Diagnostics.Process]::Start((New-ProcessInfo $Executable $Arguments $WorkingDirectory)) + $stdout = $process.StandardOutput.ReadToEnd() + $stderr = $process.StandardError.ReadToEnd() + $process.WaitForExit() + return [pscustomobject]@{ exit_code = $process.ExitCode; stdout = $stdout; stderr = $stderr } + } catch { + return [pscustomobject]@{ exit_code = 127; stdout = ''; stderr = $_.Exception.Message } + } +} + +function Discover([string]$Executable, $Assignment) { + $version = Invoke-Probe $Executable @('--version') + $help = Invoke-Probe $Executable @('--help') + $helpText = "$($help.stdout)`n$($help.stderr)" + $knownFlags = @('print', 'output-format', 'input-format', 'model', 'permission-mode', 'allowedTools', 'disallowedTools', 'resume', 'max-turns', 'add-dir', 'effort') + $flags = @($knownFlags | Where-Object { $helpText -match "--$([regex]::Escape($_))(\s|=|$)" }) + + $catalog = [System.Collections.Generic.List[string]]::new() + $catalogSource = 'unavailable' + $catalogStatus = 'unknown' + $catalogFallback = if ($env:CLAUDE_MODEL_CATALOG) { [string]$env:CLAUDE_MODEL_CATALOG } else { '' } + $catalogPath = Optional-String $Assignment 'model_catalog_path' $catalogFallback + if ($catalogPath) { + $catalogDocument = Read-Json $catalogPath + if (-not (Has-Property $catalogDocument 'models')) { + Fail "model catalog has no models array: $catalogPath" + } + foreach ($model in @($catalogDocument.models)) { [void]$catalog.Add([string]$model) } + $catalogSource = Full $catalogPath + $catalogStatus = 'available' + } + + $assignmentAllowed = [System.Collections.Generic.List[string]]::new() + foreach ($tool in @(Optional-Array $Assignment 'allowed_tools')) { [void]$assignmentAllowed.Add($tool) } + $assignmentDenied = [System.Collections.Generic.List[string]]::new() + foreach ($tool in @(Optional-Array $Assignment 'disallowed_tools')) { [void]$assignmentDenied.Add($tool) } + [void]$assignmentDenied.Add('Task') + [void]$assignmentDenied.Add('Agent') + $effortLevels = [System.Collections.Generic.List[string]]::new() + if ($flags -contains 'effort') { + [void]$effortLevels.Add('low') + [void]$effortLevels.Add('balanced') + [void]$effortLevels.Add('deep') + } + + return [ordered]@{ + version = $version.stdout.Trim() + version_exit_code = $version.exit_code + cli_exit_code = $help.exit_code + supported_flags = $flags + tools = [ordered]@{ + discovered = @('Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Task') + assignment_allowed = $assignmentAllowed + assignment_denied = $assignmentDenied + } + structured_output = [ordered]@{ + supported = ($flags -contains 'output-format') + formats = if ($flags -contains 'output-format') { @('json', 'stream-json', 'text') } else { [System.Collections.Generic.List[string]]::new() } + } + model_catalog = [ordered]@{ source = $catalogSource; status = $catalogStatus; models = $catalog } + effort_levels = $effortLevels + } +} + +function Add-Record($Ledger, [string]$Id, [string]$Type, [string]$Identity, [string]$State) { + $record = [pscustomobject]@{ + resource_id = $Id + assignment_id = [string]$Ledger.assignment_id + parent_id = [string]$Ledger.assignment_id + resource_type = $Type + identity = $Identity + owner_marker = 'offload-claude-adapter-v1' + state = $State + created_at = Iso + updated_at = Iso + } + $Ledger.records = @($Ledger.records) + $record +} + +function Update-Records($Ledger, [string]$Id, [string]$State, [hashtable]$Extra = @{}) { + foreach ($record in @($Ledger.records)) { + if ($record.resource_id -eq $Id) { + $record.state = $State + $record.updated_at = Iso + foreach ($key in $Extra.Keys) { + if ($record.PSObject.Properties.Name -contains $key) { + $record.$key = $Extra[$key] + } else { + $record | Add-Member -NotePropertyName $key -NotePropertyValue $Extra[$key] + } + } + } + } +} + +function Run-Verification($Assignment, [string]$Workdir) { + $pwsh = (Get-Command pwsh -ErrorAction SilentlyContinue)?.Source + if (-not $pwsh) { $pwsh = (Get-Process -Id $PID).Path } + + $scopeScript = Join-Path $PSScriptRoot 'check-execution-scope.ps1' + $scopeArguments = @('-NoProfile', '-NonInteractive', '-File', $scopeScript, '--baseline', [string]$Assignment.baseline) + foreach ($path in (Optional-Array $Assignment 'owned_paths')) { $scopeArguments += @('--owned', $path) } + foreach ($path in (Optional-Array $Assignment 'frozen_paths')) { $scopeArguments += @('--frozen', $path) } + $scope = Invoke-Probe $pwsh $scopeArguments $Workdir + if ($scope.exit_code -ne 0) { + return [ordered]@{ scope = 'failed'; gate = 'not-run'; reason = 'execution scope check failed'; detail = "$($scope.stdout)`n$($scope.stderr)" } + } + + $gateScript = Join-Path $PSScriptRoot 'execute-gate.ps1' + $gate = Invoke-Probe $pwsh @('-NoProfile', '-NonInteractive', '-File', $gateScript, '--command', [string]$Assignment.gate_command, '--workspace', $Workdir) $Workdir + if ($gate.exit_code -ne 0) { + return [ordered]@{ scope = 'passed'; gate = 'failed'; reason = 'final gate failed'; detail = "$($gate.stdout)`n$($gate.stderr)" } + } + try { + $gateReport = $gate.stdout | ConvertFrom-Json -Depth 20 -ErrorAction Stop + if ($gateReport.verification_status -ne 'passed') { + return [ordered]@{ scope = 'passed'; gate = 'failed'; reason = 'final gate did not pass'; detail = $gate.stdout } + } + } catch { + return [ordered]@{ scope = 'passed'; gate = 'failed'; reason = 'final gate returned malformed report'; detail = $gate.stdout } + } + return [ordered]@{ scope = 'passed'; gate = 'passed'; reason = 'scope and final gate passed' } +} + +$assignmentPath = '' +$outputPath = '' +$errorPath = '' +$capabilitiesOnly = $false +for ($i = 0; $i -lt $args.Count; $i++) { + switch ([string]$args[$i]) { + '--assignment' { $i++; if ($i -ge $args.Count) { Fail '--assignment requires a path' }; $assignmentPath = [string]$args[$i] } + '--output' { $i++; if ($i -ge $args.Count) { Fail '--output requires a path' }; $outputPath = [string]$args[$i]; $script:FailureOutputPath = $outputPath } + '--error' { $i++; if ($i -ge $args.Count) { Fail '--error requires a path' }; $errorPath = [string]$args[$i] } + '--capabilities' { $capabilitiesOnly = $true } + '-h' { Write-Output 'Usage: run-claude-json.ps1 --assignment FILE --output FILE --error FILE'; exit 0 } + '--help' { Write-Output 'Usage: run-claude-json.ps1 --assignment FILE --output FILE --error FILE'; exit 0 } + default { Fail "unknown option: $($args[$i])" } + } +} +if (-not $assignmentPath) { Fail '--assignment is required' } +if (-not $outputPath) { Fail '--output is required' } +if (-not $errorPath) { Fail '--error is required' } + +$assignment = Read-Json $assignmentPath +if ($assignment.schema_version -ne 1) { Fail 'assignment schema_version must be 1' } +foreach ($name in @('assignment_id', 'prompt', 'working_directory', 'baseline', 'gate_command', 'preference')) { + if (-not (Has-Property $assignment $name) -or [string]::IsNullOrWhiteSpace([string]$assignment.$name)) { + Fail "assignment field is required: $name" + } +} +foreach ($name in @('owned_paths', 'frozen_paths')) { + if (-not (Has-Property $assignment $name) -or $null -eq $assignment.$name) { + Fail "assignment field is required: $name" + } +} +if ([string]$assignment.preference -notin @('fast', 'balanced', 'deep')) { Fail 'preference must be fast, balanced, or deep' } + +$workdir = Full ([string]$assignment.working_directory) +if (-not (Test-Path -LiteralPath $workdir -PathType Container)) { Fail "working directory does not exist: $workdir" } +$markerPath = Join-Path $workdir '.offload-execution-workspace' +$markerValue = 'offload-execution-workspace-v1' +if (-not (Test-Path -LiteralPath $markerPath -PathType Leaf)) { + $markerPath = Join-Path $workdir '.offload-research-workspace' + $markerValue = 'offload-research-workspace-v1' +} +if (-not (Test-Path -LiteralPath $markerPath -PathType Leaf)) { Fail 'unsupported or unmarked sandbox; use an isolated offload workspace' } +try { + if (([IO.File]::ReadAllText($markerPath)).Trim() -ne $markerValue) { Fail 'invalid isolated workspace marker' } +} catch { + Fail 'could not read isolated workspace marker' +} +if (Same $workdir (Get-Location).Path) { Fail 'working directory cannot be the caller current directory' } + +foreach ($path in (Optional-Array $assignment 'owned_paths') + (Optional-Array $assignment 'frozen_paths')) { + $normalized = $path.Replace('\', '/') + if ([IO.Path]::IsPathRooted($path) -or $normalized.Split('/') -contains '..') { + Fail "assignment path escapes repository: $path" + } +} +$permissionMode = Optional-String $assignment 'permission_mode' 'acceptEdits' +if ($permissionMode -eq 'bypassPermissions') { Fail 'bypassPermissions is not allowed' } +$requestedTools = @(Optional-Array $assignment 'allowed_tools') +if ($requestedTools -contains 'Task' -or $requestedTools -contains 'Agent') { + Fail 'child assignment tools cannot be allowed' +} + +$out = Full $outputPath +$err = Full $errorPath +if (Within $out $workdir -or Within $err $workdir) { Fail 'result and error artifacts must be outside the worker directory' } + +$executable = Resolve-Claude +$capabilities = Discover $executable $assignment +if ($capabilitiesOnly) { + Write-Json $out ([ordered]@{ schema_version = 1; adapter = 'claude'; status = 'capabilities'; capabilities = $capabilities }) + exit 0 +} +if (-not $capabilities.structured_output.supported) { Fail 'Claude CLI does not advertise structured JSON output' } + +$models = @($capabilities.model_catalog.models) +$pinnedModel = Optional-String $assignment 'model' +if ($pinnedModel -and ($capabilities.model_catalog.status -ne 'available' -or $models -notcontains $pinnedModel)) { + Fail 'pinned model is unavailable or model availability is unknown' +} +$requestedEffort = Optional-String $assignment 'effort' 'default' +if ($requestedEffort -ne 'default' -and @($capabilities.effort_levels) -notcontains $requestedEffort) { + Fail 'requested effort is not supported by Claude host' +} + +$ledgerPath = Optional-String $assignment 'ledger_path' +if ($ledgerPath) { $ledgerPath = Full $ledgerPath } else { $ledgerPath = Join-Path (Split-Path -Parent $out) 'resource-ledger.json' } +if (Within $ledgerPath $workdir) { Fail 'resource ledger must be outside the worker directory' } +$ledger = if (Test-Path -LiteralPath $ledgerPath -PathType Leaf) { + Read-Json $ledgerPath +} else { + [pscustomobject]@{ schema_version = 1; owner = 'orchestrator'; assignment_id = [string]$assignment.assignment_id; records = @() } +} +if ($ledger.schema_version -ne 1 -or $ledger.owner -ne 'orchestrator') { Fail 'invalid resource ledger' } +$ledger.assignment_id = [string]$assignment.assignment_id +if ($null -eq $ledger.records) { $ledger.records = @() } + +$rawOut = "$out.raw.json" +$rawErr = "$err.raw.txt" +$timeoutText = Optional-String $assignment 'timeout_seconds' '1200' +$timeout = 0 +if (-not [int]::TryParse($timeoutText, [ref]$timeout) -or $timeout -lt 1) { Fail 'timeout_seconds must be a positive integer' } +Add-Record $ledger 'worktree' 'worktree' $workdir 'created' +Add-Record $ledger 'process' 'process' 'pending' 'created' +Add-Record $ledger 'raw-output' 'artifact' $rawOut 'created' +Add-Record $ledger 'raw-error' 'artifact' $rawErr 'created' +Add-Record $ledger 'result' 'artifact' $out 'created' +Add-Record $ledger 'verification' 'verification' 'scope-and-gate' 'created' +Write-Json $ledgerPath $ledger + +$modelForResult = if ($pinnedModel) { $pinnedModel } else { $null } +$result = [ordered]@{ + schema_version = 1 + assignment_id = [string]$assignment.assignment_id + adapter = 'claude' + status = 'failed' + lifecycle = 'created' + exit_code = $null + response = $null + structured_output = $null + session_id = $null + capabilities = $capabilities + model_selection = [ordered]@{ + preference = [string]$assignment.preference + model = $modelForResult + effort = $requestedEffort + reason = 'selection is owned by the orchestrator; the adapter does not map preferences' + } + resources = [ordered]@{ ledger = $ledgerPath; worktree = $workdir; process = $null } + artifacts = [ordered]@{ raw_output = $rawOut; raw_error = $rawErr; result = $out } + verification = $null + error = $null +} + +$runArguments = @('-p', [string]$assignment.prompt, '--output-format', 'json', '--permission-mode', $permissionMode, '--disallowedTools', 'Task', '--disallowedTools', 'Agent') +foreach ($tool in (Optional-Array $assignment 'allowed_tools')) { $runArguments += @('--allowedTools', $tool) } +foreach ($tool in (Optional-Array $assignment 'disallowed_tools')) { $runArguments += @('--disallowedTools', $tool) } +if ($pinnedModel) { $runArguments += @('--model', $pinnedModel) } +$resumeSession = Optional-String $assignment 'resume_session_id' +if ($resumeSession) { $runArguments += @('--resume', $resumeSession) } + +$process = $null +$timedOut = $false +$canceled = $false +try { + $process = [Diagnostics.Process]::Start((New-ProcessInfo $executable $runArguments $workdir)) + Update-Records $ledger 'process' 'started' @{ identity = "pid:$($process.Id)" } + $result.resources.process = "pid:$($process.Id)" + Update-Records $ledger 'worktree' 'running' + Update-Records $ledger 'raw-output' 'running' + Update-Records $ledger 'raw-error' 'running' + Write-Json $ledgerPath $ledger + + $stdoutTask = $process.StandardOutput.ReadToEndAsync() + $stderrTask = $process.StandardError.ReadToEndAsync() + $stopwatch = [Diagnostics.Stopwatch]::StartNew() + while (-not $process.HasExited) { + $cancelFile = Optional-String $assignment 'cancel_file' + if ($cancelFile -and (Test-Path -LiteralPath $cancelFile)) { + $canceled = $true + $process.Kill($true) + break + } + if ($stopwatch.Elapsed.TotalSeconds -ge $timeout) { + $timedOut = $true + $process.Kill($true) + break + } + Start-Sleep -Milliseconds 50 + } + $process.WaitForExit() + $rawStdout = $stdoutTask.GetAwaiter().GetResult() + $rawStderr = $stderrTask.GetAwaiter().GetResult() + [IO.File]::WriteAllText($rawOut, $rawStdout, [Text.UTF8Encoding]::new($false)) + [IO.File]::WriteAllText($rawErr, $rawStderr, [Text.UTF8Encoding]::new($false)) + [IO.File]::WriteAllText($err, $rawStderr, [Text.UTF8Encoding]::new($false)) + + $result.exit_code = $process.ExitCode + if ($canceled) { + $result.lifecycle = 'canceled' + $result.error = 'canceled' + } elseif ($timedOut) { + $result.lifecycle = 'failed' + $result.error = 'timeout' + } elseif ("$rawStdout`n$rawStderr" -match '(?i)quota|rate limit|too many requests|429') { + $result.lifecycle = 'quota-handoff' + $result.error = 'quota exhausted' + } elseif ($process.ExitCode -eq 0) { + try { + $document = $rawStdout | ConvertFrom-Json -Depth 30 -ErrorAction Stop + if ($document.subtype -eq 'success' -or $document.status -eq 'success') { + $result.response = if ($document.result) { [string]$document.result } elseif ($document.response) { [string]$document.response } else { $null } + $result.structured_output = $document + $result.session_id = if ($document.session_id) { [string]$document.session_id } else { $null } + $result.lifecycle = 'running' + } else { + $result.lifecycle = 'failed' + $result.error = 'Claude returned a non-success result' + } + } catch { + $result.lifecycle = 'failed' + $result.error = 'malformed Claude JSON output' + } + } else { + $result.lifecycle = 'failed' + $result.error = "Claude exited with code $($process.ExitCode)" + } + + if ($result.lifecycle -eq 'running') { + Update-Records $ledger 'verification' 'running' + $result.verification = Run-Verification $assignment $workdir + if ($result.verification.scope -eq 'passed' -and $result.verification.gate -eq 'passed') { + $result.status = 'completed' + $result.lifecycle = 'completed' + Update-Records $ledger 'verification' 'completed' + } else { + $result.error = $result.verification.reason + Update-Records $ledger 'verification' 'failed' + } + } +} catch { + $result.error = $_.Exception.Message + $result.lifecycle = 'failed' +} finally { + if ($null -ne $process -and -not $process.HasExited) { + try { $process.Kill($true); $process.WaitForExit() } catch { } + } + Write-Json $out $result + Update-Records $ledger 'process' $result.lifecycle + Update-Records $ledger 'worktree' $(if ($result.status -eq 'completed') { 'completed' } else { 'retained' }) + Update-Records $ledger 'raw-output' 'retained' + Update-Records $ledger 'raw-error' 'retained' + Update-Records $ledger 'result' 'completed' + if ($null -eq $result.verification) { Update-Records $ledger 'verification' 'not-run' } + Write-Json $ledgerPath $ledger + if ($null -ne $process) { $process.Dispose() } +} + +if ($result.status -eq 'completed') { exit 0 } +if ($result.lifecycle -eq 'quota-handoff') { exit 75 } +if ($result.lifecycle -eq 'canceled') { exit 130 } +exit 1 diff --git a/scripts/run-claude-json.sh b/scripts/run-claude-json.sh new file mode 100755 index 0000000..188ec53 --- /dev/null +++ b/scripts/run-claude-json.sh @@ -0,0 +1,278 @@ +#!/usr/bin/env bash +# Launch one bounded Claude Code assignment and return an orchestrator-verifiable result. +set -u + +fail() { + printf 'ERROR: %s\n' "$1" >&2 + if [ -n "${failure_output_path:-}" ] && command -v jq >/dev/null 2>&1; then + jq -n --arg error "$1" '{schema_version:1,adapter:"claude",status:"failed",lifecycle:"failed",error:$error}' >"$failure_output_path" 2>/dev/null || true + fi + exit "${2:-2}" +} +usage() { printf 'Usage: run-claude-json.sh --assignment FILE --output FILE --error FILE\n'; } +full_path() { local p="$1"; printf '%s/%s\n' "$(cd -- "$(dirname -- "$p")" 2>/dev/null && pwd -P)" "$(basename -- "$p")"; } +same_path() { [ "$(full_path "$1")" = "$(full_path "$2")" ]; } +within_path() { local c p; c=$(full_path "$1") || return 1; p=$(full_path "$2") || return 1; case "$c" in "$p"|"$p"/*) return 0 ;; *) return 1 ;; esac; } +json_value() { jq -r "$1" "$assignment_path" 2>/dev/null; } +optional() { local v; v=$(jq -r "$1 // empty" "$assignment_path" 2>/dev/null) || fail 'invalid assignment JSON'; [ -n "$v" ] && printf '%s\n' "$v" || printf '%s\n' "$2"; } +now_utc() { date -u '+%Y-%m-%dT%H:%M:%SZ'; } + +ledger_add() { + local id="$1" type="$2" identity="$3" state="$4" temp; temp="$ledger_path.tmp.$$" + jq --arg id "$id" --arg aid "$assignment_id" --arg type "$type" --arg identity "$identity" --arg state "$state" --arg now "$(now_utc)" \ + '.records += [{resource_id:$id,assignment_id:$aid,parent_id:$aid,resource_type:$type,identity:$identity,owner_marker:"offload-claude-adapter-v1",state:$state,created_at:$now,updated_at:$now}]' "$ledger_path" >"$temp" || fail 'could not register resource in ledger' + mv -- "$temp" "$ledger_path" || fail 'could not replace resource ledger' +} +ledger_update() { + local id="$1" state="$2" key="${3:-}" value="${4:-}" temp; temp="$ledger_path.tmp.$$" + jq --arg id "$id" --arg state "$state" --arg key "$key" --arg value "$value" \ + '(.records[] | select(.resource_id == $id)) |= (.state=$state | .updated_at=(now|todateiso8601) | if $key != "" then .[$key]=$value else . end)' "$ledger_path" >"$temp" || fail 'could not update resource ledger' + mv -- "$temp" "$ledger_path" || fail 'could not replace resource ledger' +} + +require_jq() { command -v jq >/dev/null 2>&1 || fail 'jq is required by the Claude adapter' 1; } +require_jq +assignment_path=''; output_path=''; error_path=''; failure_output_path=''; capabilities_only=false +while [ "$#" -gt 0 ]; do + case "$1" in + --assignment) [ "$#" -ge 2 ] || fail '--assignment requires a path'; assignment_path="$2"; shift 2 ;; + --output) [ "$#" -ge 2 ] || fail '--output requires a path'; output_path="$2"; failure_output_path="$2"; shift 2 ;; + --error) [ "$#" -ge 2 ] || fail '--error requires a path'; error_path="$2"; shift 2 ;; + --capabilities) capabilities_only=true; shift ;; + -h|--help) usage; exit 0 ;; + *) fail "unknown option: $1" ;; + esac +done +[ -n "$assignment_path" ] || fail '--assignment is required' +[ -n "$output_path" ] || fail '--output is required' +[ -n "$error_path" ] || fail '--error is required' +[ -f "$assignment_path" ] || fail "JSON file does not exist: $assignment_path" +schema=$(json_value '.schema_version') || fail 'invalid assignment JSON' +[ "$schema" = 1 ] || fail 'assignment schema_version must be 1' +assignment_id=$(json_value '.assignment_id') || fail 'invalid assignment JSON' +prompt=$(json_value '.prompt') || fail 'invalid assignment JSON' +workdir_raw=$(json_value '.working_directory') || fail 'invalid assignment JSON' +baseline=$(json_value '.baseline') || fail 'invalid assignment JSON' +gate_command=$(json_value '.gate_command') || fail 'invalid assignment JSON' +preference=$(json_value '.preference') || fail 'invalid assignment JSON' +[ -n "$assignment_id" ] || fail 'assignment field is required: assignment_id' +[ -n "$prompt" ] || fail 'assignment field is required: prompt' +[ -n "$workdir_raw" ] || fail 'assignment field is required: working_directory' +[ -n "$baseline" ] || fail 'assignment field is required: baseline' +[ -n "$gate_command" ] || fail 'assignment field is required: gate_command' +[ -n "$preference" ] || fail 'assignment field is required: preference' +jq -e '(.owned_paths|type=="array") and (.frozen_paths|type=="array")' "$assignment_path" >/dev/null || fail 'owned_paths and frozen_paths must be arrays' +case "$preference" in fast|balanced|deep) ;; *) fail 'preference must be fast, balanced, or deep' ;; esac +workdir=$(full_path "$workdir_raw") || fail 'could not resolve working directory' +[ -d "$workdir" ] || fail "working directory does not exist: $workdir" +marker_file="$workdir/.offload-execution-workspace" +marker_value='offload-execution-workspace-v1' +if [ ! -f "$marker_file" ]; then + marker_file="$workdir/.offload-research-workspace" + marker_value='offload-research-workspace-v1' +fi +[ -f "$marker_file" ] || fail 'unsupported or unmarked sandbox; use an isolated offload workspace' +[ "$(tr -d '\r\n' <"$marker_file")" = "$marker_value" ] || fail 'invalid isolated workspace marker' +same_path "$workdir" "$PWD" && fail 'working directory cannot be the caller current directory' +while IFS= read -r path; do + normalized=${path//\\/\/} + case "$normalized" in /*|..|../*|*/../*|*/..) fail "assignment path escapes repository: $path" ;; esac +done < <(jq -r '.owned_paths[]?, .frozen_paths[]?' "$assignment_path") +permission_mode=$(optional '.permission_mode' 'acceptEdits') +[ "$permission_mode" != bypassPermissions ] || fail 'bypassPermissions is not allowed' +if jq -e '.allowed_tools[]? | select(. == "Task" or . == "Agent")' "$assignment_path" >/dev/null 2>&1; then + fail 'child assignment tools cannot be allowed' +fi +mkdir -p -- "$(dirname -- "$output_path")" "$(dirname -- "$error_path")" || fail 'could not create artifact directories' +out=$(full_path "$output_path") || fail 'could not resolve output path' +err=$(full_path "$error_path") || fail 'could not resolve error path' +within_path "$out" "$workdir" && fail 'result artifact must be outside the worker directory' +within_path "$err" "$workdir" && fail 'error artifact must be outside the worker directory' +repo_root=$(cd -- "$(dirname -- "$0")/.." && pwd -P) || fail 'could not resolve repository root' +claude_bin="${CLAUDE_BIN:-claude}" +command -v "$claude_bin" >/dev/null 2>&1 || [ -x "$claude_bin" ] || fail 'claude was not found; set CLAUDE_BIN or add claude to PATH' 1 +version_output=$("$claude_bin" --version 2>&1); version_exit_code=$? +help_output=$("$claude_bin" --help 2>&1); cli_exit_code=$? +supported_flags='[]' +for flag in print output-format input-format model permission-mode allowedTools disallowedTools resume max-turns add-dir effort; do + if printf '%s\n' "$help_output" | grep -Eq -- "--${flag}([[:space:]=]|$)"; then supported_flags=$(jq --arg flag "$flag" '. + [$flag]' <<<"$supported_flags"); fi +done +catalog_path=$(optional '.model_catalog_path' "${CLAUDE_MODEL_CATALOG:-}") +catalog_status=unknown; catalog_source=unavailable; catalog_models='[]' +if [ -n "$catalog_path" ]; then + [ -f "$catalog_path" ] || fail "model catalog does not exist: $catalog_path" + jq -e '.models|type=="array"' "$catalog_path" >/dev/null || fail 'model catalog has no models array' + catalog_models=$(jq -c '.models|map(tostring)' "$catalog_path") + catalog_status=available; catalog_source=$(full_path "$catalog_path") || fail 'could not resolve model catalog' +fi +effort_levels='[]'; jq -e 'index("effort") != null' <<<"$supported_flags" >/dev/null && effort_levels='["low","balanced","deep"]' +capabilities=$(jq -n -c --arg version "$version_output" --argjson version_exit_code "$version_exit_code" --argjson cli_exit_code "$cli_exit_code" --argjson flags "$supported_flags" --arg source "$catalog_source" --arg cstatus "$catalog_status" --argjson models "$catalog_models" --argjson efforts "$effort_levels" \ + --argjson allowed "$(jq -c '[.allowed_tools[]?|tostring]' "$assignment_path")" --argjson denied "$(jq -c '[.disallowed_tools[]?|tostring]+["Task","Agent"]' "$assignment_path")" \ + '{version:($version|rtrimstr("\n")),version_exit_code:$version_exit_code,cli_exit_code:$cli_exit_code,supported_flags:$flags,tools:{discovered:["Read","Write","Edit","Bash","Glob","Grep","Task"],assignment_allowed:$allowed,assignment_denied:$denied},structured_output:{supported:(($flags|index("output-format"))!=null),formats:(if (($flags|index("output-format"))!=null) then ["json","stream-json","text"] else [] end)},model_catalog:{source:$source,status:$cstatus,models:$models},effort_levels:$efforts}') +if [ "$capabilities_only" = true ]; then jq -n --argjson capabilities "$capabilities" '{schema_version:1,adapter:"claude",status:"capabilities",capabilities:$capabilities}' >"$out"; exit 0; fi +jq -e '.structured_output.supported == true' <<<"$capabilities" >/dev/null || fail 'Claude CLI does not advertise structured JSON output' +pinned_model=$(optional '.model' '') +if [ -n "$pinned_model" ]; then jq -e --arg model "$pinned_model" '.model_catalog.status=="available" and (.model_catalog.models|index($model)!=null)' <<<"$capabilities" >/dev/null || fail 'pinned model is unavailable or model availability is unknown'; fi +requested_effort=$(optional '.effort' default) +if [ "$requested_effort" != default ]; then jq -e --arg effort "$requested_effort" '.effort_levels|index($effort)!=null' <<<"$capabilities" >/dev/null || fail 'requested effort is not supported by Claude host'; fi +ledger_path=$(optional '.ledger_path' '') +if [ -n "$ledger_path" ]; then + ledger_path=$(full_path "$ledger_path") || fail 'could not resolve ledger path' +else + ledger_path="$(dirname -- "$out")/resource-ledger.json" +fi +within_path "$ledger_path" "$workdir" && fail 'resource ledger must be outside the worker directory' +if [ -f "$ledger_path" ]; then + jq -e '.schema_version == 1 and .owner == "orchestrator"' "$ledger_path" >/dev/null || fail 'invalid resource ledger' +else + mkdir -p -- "$(dirname -- "$ledger_path")" || fail 'could not create ledger directory' + jq -n --arg aid "$assignment_id" '{schema_version:1,owner:"orchestrator",assignment_id:$aid,records:[]}' >"$ledger_path" || fail 'could not create resource ledger' +fi +jq --arg aid "$assignment_id" '.assignment_id=$aid' "$ledger_path" >"$ledger_path.tmp.$$" || fail 'could not initialize resource ledger' +mv -- "$ledger_path.tmp.$$" "$ledger_path" || fail 'could not replace resource ledger' + +raw_out="$out.raw.json" +raw_err="$err.raw.txt" +ledger_add worktree worktree "$workdir" created +ledger_add process process pending created +ledger_add raw-output artifact "$raw_out" created +ledger_add raw-error artifact "$raw_err" created +ledger_add result artifact "$out" created +ledger_add verification verification scope-and-gate created + +timeout_text=$(optional '.timeout_seconds' 1200) +case "$timeout_text" in ''|*[!0-9]*) fail 'timeout_seconds must be a positive integer' ;; esac +[ "$timeout_text" -gt 0 ] || fail 'timeout_seconds must be a positive integer' + +model_json=null +if [ -n "$pinned_model" ]; then model_json=$(jq -n --arg model "$pinned_model" '$model'); fi + jq -n -c --arg aid "$assignment_id" --arg preference "$preference" --arg effort "$requested_effort" \ + --arg workdir "$workdir" --arg ledger "$ledger_path" --arg raw_out "$raw_out" --arg raw_err "$raw_err" --arg out "$out" \ + --argjson capabilities "$capabilities" --argjson model "$model_json" \ + '{schema_version:1,assignment_id:$aid,adapter:"claude",status:"failed",lifecycle:"created",exit_code:null,response:null,structured_output:null,session_id:null,capabilities:$capabilities,model_selection:{preference:$preference,model:$model,effort:$effort,reason:"selection is owned by the orchestrator; the adapter does not map preferences"},resources:{ledger:$ledger,worktree:$workdir,process:null},artifacts:{raw_output:$raw_out,raw_error:$raw_err,result:$out},verification:null,error:null}' >"$out" || fail 'could not initialize result artifact' + +run_args=(-p "$prompt" --output-format json --permission-mode "$permission_mode" --disallowedTools Task --disallowedTools Agent) +while IFS= read -r tool; do + [ -n "$tool" ] && run_args+=(--allowedTools "$tool") +done < <(jq -r '.allowed_tools[]? | tostring' "$assignment_path") +while IFS= read -r tool; do + [ -n "$tool" ] && run_args+=(--disallowedTools "$tool") +done < <(jq -r '.disallowed_tools[]? | tostring' "$assignment_path") +[ -n "$pinned_model" ] && run_args+=(--model "$pinned_model") +resume_session=$(optional '.resume_session_id' '') +[ -n "$resume_session" ] && run_args+=(--resume "$resume_session") + +ledger_update process started identity pending +ledger_update worktree running +ledger_update raw-output running +ledger_update raw-error running +( + cd -- "$workdir" || exit 126 + exec "$claude_bin" "${run_args[@]}" +) >"$raw_out" 2>"$raw_err" & +process_id=$! +ledger_update process started identity "pid:$process_id" +cancel_file=$(optional '.cancel_file' '') +timed_out=false +canceled=false +terminate_worker() { + if command -v pkill >/dev/null 2>&1; then + pkill -TERM -P "$process_id" 2>/dev/null || true + fi + kill -TERM "$process_id" 2>/dev/null || true +} +worker_running() { + if command -v ps >/dev/null 2>&1; then + local state + state=$(ps -o stat= -p "$process_id" 2>/dev/null | tr -d '[:space:]') + case "$state" in ''|Z*) return 1 ;; *) return 0 ;; esac + fi + kill -0 "$process_id" 2>/dev/null +} +started_at=$(date +%s) +while worker_running; do + if [ -n "$cancel_file" ] && [ -f "$cancel_file" ]; then + canceled=true + terminate_worker + break + fi + if [ $(( $(date +%s) - started_at )) -ge "$timeout_text" ]; then + timed_out=true + terminate_worker + break + fi + sleep 0.05 +done +wait "$process_id" 2>/dev/null +exit_code=$? +cp -- "$raw_err" "$err" || fail 'could not write error artifact' + +status=failed +lifecycle=failed +error_message='' +response=null +structured=null +session_id=null +verification=null +gate_output='' +if [ "$canceled" = true ]; then + lifecycle=canceled; error_message=canceled +elif [ "$timed_out" = true ]; then + error_message=timeout +elif grep -Eiq 'quota|rate limit|too many requests|429' "$raw_out" "$raw_err"; then + lifecycle=quota-handoff; error_message='quota exhausted' +elif [ "$exit_code" -eq 0 ]; then + if jq -e '(.subtype == "success") or (.status == "success")' "$raw_out" >/dev/null 2>&1; then + response=$(jq -c 'if .result != null then .result elif .response != null then .response else null end' "$raw_out") + session_id=$(jq -c 'if .session_id != null then .session_id else null end' "$raw_out") + structured=$(jq -c '.' "$raw_out") + verification='' + scope_args=(--baseline "$baseline") + while IFS= read -r path; do scope_args+=(--owned "$path"); done < <(jq -r '.owned_paths[]' "$assignment_path") + while IFS= read -r path; do scope_args+=(--frozen "$path"); done < <(jq -r '.frozen_paths[]' "$assignment_path") + scope_output=$(cd -- "$workdir" && bash "$repo_root/scripts/check-execution-scope.sh" "${scope_args[@]}" 2>&1) || { + verification=$(jq -n --arg detail "$scope_output" '{scope:"failed",gate:"not-run",reason:"execution scope check failed",detail:$detail}') + } + if [ -n "$verification" ]; then + : + else + verification='' + gate_output=$(bash "$repo_root/scripts/execute-gate.sh" --command "$gate_command" --workspace "$workdir" 2>&1) || { + verification=$(jq -n --arg detail "$gate_output" '{scope:"passed",gate:"failed",reason:"final gate failed",detail:$detail}') + } + if [ -z "$verification" ] && jq -e '.verification_status == "passed"' <<<"$gate_output" >/dev/null 2>&1; then + verification='{"scope":"passed","gate":"passed","reason":"scope and final gate passed"}' + elif [ -z "$verification" ]; then + verification=$(jq -n --arg detail "$gate_output" '{scope:"passed",gate:"failed",reason:"final gate did not pass",detail:$detail}') + fi + fi + if jq -e '.scope == "passed" and .gate == "passed"' <<<"$verification" >/dev/null 2>&1; then + status=completed; lifecycle=completed + else + error_message=$(jq -r '.reason' <<<"$verification") + fi + else + error_message='malformed Claude JSON output' + fi +else + error_message="Claude exited with code $exit_code" +fi + + jq --arg status "$status" --arg lifecycle "$lifecycle" --argjson exit_code "$exit_code" \ + --arg process_id "pid:$process_id" \ + --arg error "$error_message" --argjson response "$response" --argjson structured_output "$structured" \ + --argjson session_id "$session_id" --argjson verification "$verification" \ + '.status=$status | .lifecycle=$lifecycle | .exit_code=$exit_code | .response=$response | .structured_output=$structured_output | .session_id=$session_id | .resources.process=$process_id | .verification=$verification | .error=(if $error == "" then null else $error end)' \ + "$out" >"$out.tmp.$$" || fail 'could not finalize result artifact' +mv -- "$out.tmp.$$" "$out" || fail 'could not replace result artifact' +ledger_update process "$lifecycle" +if [ "$status" = completed ]; then ledger_update worktree completed; else ledger_update worktree retained; fi + ledger_update raw-output retained + ledger_update raw-error retained + ledger_update result completed + if [ "$verification" = null ]; then ledger_update verification not-run; elif jq -e '.scope == "passed" and .gate == "passed"' <<<"$verification" >/dev/null 2>&1; then ledger_update verification completed; else ledger_update verification failed; fi + +if [ "$status" = completed ]; then exit 0; fi +if [ "$lifecycle" = quota-handoff ]; then exit 75; fi +if [ "$lifecycle" = canceled ]; then exit 130; fi +exit 1 diff --git a/tests/test_claude_adapter.ps1 b/tests/test_claude_adapter.ps1 new file mode 100644 index 0000000..d4d322f --- /dev/null +++ b/tests/test_claude_adapter.ps1 @@ -0,0 +1,203 @@ +#!/usr/bin/env pwsh +# Acceptance tests for the bounded Claude adapter. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$script:TotalTests = 0 +$script:FailedTests = 0 + +function Pass([string]$Name) { + $script:TotalTests++ + [Console]::Out.WriteLine("ok - $Name") +} + +function Fail([string]$Name, [string]$Reason = '') { + $script:TotalTests++ + $script:FailedTests++ + if ($Reason) { [Console]::Error.WriteLine("FAIL: $Name - $Reason") } + else { [Console]::Error.WriteLine("FAIL: $Name") } + throw "test failed: $Name" +} + +function Assert-True([bool]$Condition, [string]$Name, [string]$Reason = '') { + if ($Condition) { Pass $Name } else { Fail $Name (if ($Reason) { $Reason } else { 'condition was false' }) } +} + +function Assert-Equal($Actual, $Expected, [string]$Name) { + if ($Actual -eq $Expected) { Pass $Name } + else { Fail $Name "expected '$Expected', got '$Actual'" } +} + +function Assert-NotEqual($Actual, $Expected, [string]$Name) { + if ($Actual -ne $Expected) { Pass $Name } + else { Fail $Name "expected a value other than '$Expected'" } +} + +function Invoke-ToolProcess { + param( + [Parameter(Mandatory = $true)][string]$FilePath, + [string[]]$ArgumentList = @(), + [hashtable]$Environment = @{}, + [string]$WorkingDirectory = '' + ) + $psi = [Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $FilePath + foreach ($argument in $ArgumentList) { $psi.ArgumentList.Add($argument) } + if ($WorkingDirectory) { $psi.WorkingDirectory = $WorkingDirectory } + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + $psi.UseShellExecute = $false + $psi.CreateNoWindow = $true + foreach ($key in $Environment.Keys) { $psi.EnvironmentVariables[$key] = [string]$Environment[$key] } + $process = [Diagnostics.Process]::Start($psi) + $stdoutTask = $process.StandardOutput.ReadToEndAsync() + $stderrTask = $process.StandardError.ReadToEndAsync() + $process.WaitForExit() + return [pscustomobject]@{ + ExitCode = $process.ExitCode + Stdout = $stdoutTask.GetAwaiter().GetResult() + Stderr = $stderrTask.GetAwaiter().GetResult() + } +} + +function Invoke-Git([string]$WorkingDirectory, [string[]]$Arguments) { + $result = Invoke-ToolProcess -FilePath 'git' -ArgumentList (@('-C', $WorkingDirectory) + $Arguments) + if ($result.ExitCode -ne 0) { throw "git failed: $($result.Stderr)" } + return $result.Stdout.Trim() +} + +function New-Workspace([string]$Root) { + $workspace = Join-Path $Root ([Guid]::NewGuid().ToString('N')) + [IO.Directory]::CreateDirectory($workspace) | Out-Null + Invoke-Git $workspace @('init', '-q') | Out-Null + Invoke-Git $workspace @('config', 'user.email', 'claude-adapter@test.invalid') | Out-Null + Invoke-Git $workspace @('config', 'user.name', 'Claude adapter test') | Out-Null + [IO.File]::WriteAllText((Join-Path $workspace 'owned.txt'), "baseline`n") + [IO.File]::WriteAllText((Join-Path $workspace 'frozen.txt'), "frozen`n") + [IO.Directory]::CreateDirectory((Join-Path $workspace '.git/info')) | Out-Null + [IO.File]::WriteAllText((Join-Path $workspace '.git/info/exclude'), ".offload-execution-workspace`n") + [IO.File]::WriteAllText((Join-Path $workspace '.offload-execution-workspace'), "offload-execution-workspace-v1`n") + Invoke-Git $workspace @('add', 'owned.txt', 'frozen.txt') | Out-Null + Invoke-Git $workspace @('commit', '-qm', 'baseline') | Out-Null + return $workspace +} + +function New-Assignment([string]$Workspace, [string]$Path, [string]$CancelFile = '', [int]$Timeout = 10) { + $baseline = Invoke-Git $Workspace @('rev-parse', 'HEAD') + $assignment = [ordered]@{ + schema_version = 1 + assignment_id = "test-$([Guid]::NewGuid().ToString('N'))" + prompt = 'Return a structured result without dispatching a child assignment.' + working_directory = $Workspace + owned_paths = @('owned.txt') + frozen_paths = @('frozen.txt') + baseline = $baseline + gate_command = 'Test-Path -LiteralPath owned.txt' + preference = 'balanced' + timeout_seconds = $Timeout + } + if ($CancelFile) { $assignment.cancel_file = $CancelFile } + $assignment | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $Path -Encoding utf8 + return $assignment +} + +function Invoke-Adapter { + param( + [Parameter(Mandatory = $true)][string]$Workspace, + [Parameter(Mandatory = $true)][string]$Adapter, + [Parameter(Mandatory = $true)][string]$Pwsh, + [Parameter(Mandatory = $true)][string]$FakeClaude, + [Parameter(Mandatory = $true)][string]$Artifacts, + [string]$Mode = 'success', + [string]$CancelFile = '', + [int]$Timeout = 10 + ) + $assignmentPath = Join-Path $Artifacts "$Mode-assignment.json" + $outputPath = Join-Path $Artifacts "$Mode-result.json" + $errorPath = Join-Path $Artifacts "$Mode-error.txt" + $assignment = New-Assignment $Workspace $assignmentPath $CancelFile $Timeout + $environment = @{ CLAUDE_BIN = $FakeClaude; FAKE_CLAUDE_MODE = $Mode } + $arguments = @('-NoProfile', '-NonInteractive', '-File', $Adapter, '--assignment', $assignmentPath, '--output', $outputPath, '--error', $errorPath) + $processResult = Invoke-ToolProcess $Pwsh $arguments $environment + $document = Get-Content -LiteralPath $outputPath -Raw | ConvertFrom-Json -Depth 30 + return [pscustomobject]@{ Process = $processResult; Result = $document; OutputPath = $outputPath; ErrorPath = $errorPath; Assignment = $assignment } +} + +$root = Split-Path -Parent $PSScriptRoot +$adapter = Join-Path $root 'scripts/run-claude-json.ps1' +$pwsh = (Get-Command pwsh -ErrorAction SilentlyContinue)?.Source +if (-not $pwsh) { $pwsh = (Get-Process -Id $PID).Path } +$tempRoot = Join-Path ([IO.Path]::GetTempPath()) "offload-claude-adapter-$([Guid]::NewGuid().ToString('N'))" +[IO.Directory]::CreateDirectory($tempRoot) | Out-Null +$fakeClaude = Join-Path $tempRoot 'fake-claude.ps1' +$fakeScript = @' +$ErrorActionPreference = 'Stop' +if ($args -contains '--version') { Write-Output 'claude-fake 1.0'; exit 0 } +if ($args -contains '--help') { + Write-Output '--output-format --permission-mode --allowedTools --disallowedTools --resume' + exit 0 +} +switch ($env:FAKE_CLAUDE_MODE) { + 'malformed' { Write-Output 'not-json'; exit 0 } + 'cancel' { Start-Sleep -Seconds 30; exit 0 } + 'scope-failure' { Set-Content -LiteralPath (Join-Path (Get-Location) 'unowned.txt') -Value 'unexpected'; } + 'quota' { Write-Error 'quota exhausted'; exit 75 } +} +Write-Output '{"type":"result","subtype":"success","result":"ok","session_id":"s1"}' +'@ +[IO.File]::WriteAllText($fakeClaude, $fakeScript) + +try { + $successWorkspace = New-Workspace $tempRoot + $success = Invoke-Adapter $successWorkspace $adapter $pwsh $fakeClaude $tempRoot + Assert-Equal $success.Process.ExitCode 0 'success returns zero' + Assert-Equal $success.Result.status 'completed' 'success is completed' + Assert-Equal $success.Result.lifecycle 'completed' 'success lifecycle completes' + Assert-Equal $success.Result.response 'ok' 'success response is normalized' + Assert-Equal $success.Result.session_id 's1' 'session id is normalized' + Assert-True ($success.Result.capabilities.tools.assignment_denied -contains 'Task') 'child assignment tool is denied' + Assert-True ($success.Result.capabilities.tools.assignment_denied -contains 'Agent') 'alternate child assignment tool is denied' + Assert-True (Test-Path -LiteralPath $success.ErrorPath -PathType Leaf) 'error artifact is written' + $ledger = Get-Content -LiteralPath (Join-Path $tempRoot 'resource-ledger.json') -Raw | ConvertFrom-Json -Depth 30 + Assert-True (@($ledger.records).resource_type -contains 'process') 'process is registered' + Assert-True (@($ledger.records).resource_type -contains 'worktree') 'worktree is registered' + Assert-True (@($ledger.records).resource_type -contains 'artifact') 'artifacts are registered' + Assert-Equal ((@($ledger.records) | Where-Object resource_id -eq 'process').state) 'completed' 'process is reconciled' + + $malformedWorkspace = New-Workspace $tempRoot + $malformed = Invoke-Adapter $malformedWorkspace $adapter $pwsh $fakeClaude $tempRoot 'malformed' + Assert-Equal $malformed.Process.ExitCode 1 'malformed output returns failure' + Assert-Equal $malformed.Result.lifecycle 'failed' 'malformed output has failed lifecycle' + Assert-Equal $malformed.Result.error 'malformed Claude JSON output' 'malformed output is classified' + Assert-True ((Get-Content -LiteralPath "$($malformed.OutputPath).raw.json" -Raw) -match 'not-json') 'raw malformed output is retained' + + $cancelFile = Join-Path $tempRoot 'cancel.request' + [IO.File]::WriteAllText($cancelFile, 'cancel') + $cancelWorkspace = New-Workspace $tempRoot + $canceled = Invoke-Adapter $cancelWorkspace $adapter $pwsh $fakeClaude $tempRoot 'cancel' $cancelFile + Assert-Equal $canceled.Process.ExitCode 130 'cancellation returns normalized exit code' + Assert-Equal $canceled.Result.lifecycle 'canceled' 'cancellation lifecycle is recorded' + Assert-Equal $canceled.Result.error 'canceled' 'cancellation reason is recorded' + + $scopeWorkspace = New-Workspace $tempRoot + $scopeFailure = Invoke-Adapter $scopeWorkspace $adapter $pwsh $fakeClaude $tempRoot 'scope-failure' + Assert-Equal $scopeFailure.Process.ExitCode 1 'scope failure returns failure' + Assert-Equal $scopeFailure.Result.verification.scope 'failed' 'scope failure is verified' + Assert-Equal $scopeFailure.Result.verification.gate 'not-run' 'gate is withheld after scope failure' + Assert-Equal $scopeFailure.Result.error 'execution scope check failed' 'scope failure reason is recorded' + + $unmarkedWorkspace = New-Workspace $tempRoot + Remove-Item -LiteralPath (Join-Path $unmarkedWorkspace '.offload-execution-workspace') -Force + $unmarkedAssignment = Join-Path $tempRoot 'unmarked-assignment.json' + $null = New-Assignment $unmarkedWorkspace $unmarkedAssignment + $unmarkedOutput = Join-Path $tempRoot 'unmarked-result.json' + $unmarkedError = Join-Path $tempRoot 'unmarked-error.txt' + $unmarkedRun = Invoke-ToolProcess $pwsh @('-NoProfile', '-NonInteractive', '-File', $adapter, '--assignment', $unmarkedAssignment, '--output', $unmarkedOutput, '--error', $unmarkedError) @{ CLAUDE_BIN = $fakeClaude; FAKE_CLAUDE_MODE = 'success' } + Assert-NotEqual $unmarkedRun.ExitCode 0 'unmarked workspace fails closed' + Assert-True ($unmarkedRun.Stderr -match 'unmarked sandbox') 'unmarked failure explains isolation requirement' +} finally { + if (Test-Path -LiteralPath $tempRoot) { Remove-Item -LiteralPath $tempRoot -Recurse -Force } +} + +[Console]::Out.WriteLine("$script:TotalTests tests passed") diff --git a/tests/test_claude_adapter.sh b/tests/test_claude_adapter.sh new file mode 100755 index 0000000..fc13036 --- /dev/null +++ b/tests/test_claude_adapter.sh @@ -0,0 +1,104 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +ADAPTER="$ROOT/scripts/run-claude-json.sh" +TMP_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/offload-claude-adapter.XXXXXX") +trap 'rm -rf "$TMP_ROOT"' EXIT + +fail() { printf 'FAIL: %s\n' "$1" >&2; exit 1; } +pass() { printf 'ok - %s\n' "$1"; } + +init_workspace() { + local workspace="$1" + mkdir -p "$workspace/.git/info" + git -C "$workspace" init -q + git -C "$workspace" config user.name 'Claude adapter test' + git -C "$workspace" config user.email 'claude-adapter@test.invalid' + printf 'baseline\n' >"$workspace/owned.txt" + printf 'frozen\n' >"$workspace/frozen.txt" + printf '.offload-execution-workspace\n' >"$workspace/.git/info/exclude" + printf 'offload-execution-workspace-v1\n' >"$workspace/.offload-execution-workspace" + git -C "$workspace" add owned.txt frozen.txt + git -C "$workspace" commit -q -m baseline +} + +fake_claude="$TMP_ROOT/fake-claude" +cat >"$fake_claude" <<'FAKE_CLAUDE' +#!/usr/bin/env bash +set -u +case "${1:-}" in + --version) printf 'claude-fake 1.0\n'; exit 0 ;; + --help) printf '%s\n' '--output-format --permission-mode --allowedTools --disallowedTools --resume'; exit 0 ;; +esac +case "${FAKE_CLAUDE_MODE:-success}" in + malformed) printf 'not-json\n'; exit 0 ;; + cancel) while :; do :; done ;; + scope-failure) printf 'unexpected\n' >unowned.txt ;; + quota) printf 'quota exhausted\n' >&2; exit 75 ;; +esac +printf '%s\n' '{"type":"result","subtype":"success","result":"ok","session_id":"s1"}' +FAKE_CLAUDE +chmod +x "$fake_claude" + +run_adapter() { + local mode="$1" workspace="$2" cancel_file="${3:-}" + local assignment="$TMP_ROOT/$mode-assignment.json" output="$TMP_ROOT/$mode-result.json" error="$TMP_ROOT/$mode-error.txt" + local baseline; baseline=$(git -C "$workspace" rev-parse HEAD) + jq -n --arg id "test-$mode" --arg prompt 'bounded fake assignment' --arg workdir "$workspace" --arg baseline "$baseline" --arg cancel "$cancel_file" \ + '{schema_version:1,assignment_id:$id,prompt:$prompt,working_directory:$workdir,owned_paths:["owned.txt"],frozen_paths:["frozen.txt"],baseline:$baseline,gate_command:"test -f owned.txt",preference:"balanced",timeout_seconds:10} | if $cancel != "" then .cancel_file=$cancel else . end' >"$assignment" + set +e + FAKE_CLAUDE_MODE="$mode" CLAUDE_BIN="$fake_claude" "$ADAPTER" --assignment "$assignment" --output "$output" --error "$error" + RUN_EXIT=$? + set -e + RUN_OUTPUT="$output" + RUN_ERROR="$error" +} + +workspace="$TMP_ROOT/success" +init_workspace "$workspace" +run_adapter success "$workspace" +[ "$RUN_EXIT" -eq 0 ] || fail 'success did not return zero' +[ "$(jq -r '.status' "$RUN_OUTPUT")" = completed ] || fail 'success was not completed' +[ "$(jq -r '.response' "$RUN_OUTPUT")" = ok ] || fail 'success response was not normalized' +[ "$(jq -r '.session_id' "$RUN_OUTPUT")" = s1 ] || fail 'session id was not normalized' +[ "$(jq -r '.resources.process' "$RUN_OUTPUT")" != null ] || fail 'process identity was not reported' +[ -f "$RUN_ERROR" ] || fail 'error artifact was not written' +[ "$(jq -r '[.records[] | select(.resource_type == "process")][0].state' "$TMP_ROOT/resource-ledger.json")" = completed ] || fail 'process was not reconciled' +pass 'Bash adapter returns verified normalized success and ledger records' + +workspace="$TMP_ROOT/malformed" +init_workspace "$workspace" +run_adapter malformed "$workspace" +[ "$RUN_EXIT" -eq 1 ] || fail 'malformed output did not return failure' +[ "$(jq -r '.lifecycle' "$RUN_OUTPUT")" = failed ] || fail 'malformed output lifecycle was not failed' +pass 'Bash adapter classifies malformed output' + +cancel_file="$TMP_ROOT/cancel.request" +touch "$cancel_file" +workspace="$TMP_ROOT/cancel" +init_workspace "$workspace" +case "$(uname -s)" in + MINGW*|MSYS*|CYGWIN*) pass 'Bash cancellation process-tree test skipped on Windows compatibility runtime' ;; + *) + run_adapter cancel "$workspace" "$cancel_file" + [ "$RUN_EXIT" -eq 130 ] || fail 'cancellation did not return normalized exit code' + [ "$(jq -r '.lifecycle' "$RUN_OUTPUT")" = canceled ] || fail 'cancellation lifecycle was not recorded' + pass 'Bash adapter cancels bounded workers' + ;; +esac + +workspace="$TMP_ROOT/scope-failure" +init_workspace "$workspace" +run_adapter scope-failure "$workspace" +[ "$RUN_EXIT" -eq 1 ] || fail 'scope failure did not return failure' +[ "$(jq -r '.verification.scope' "$RUN_OUTPUT")" = failed ] || fail 'scope failure was not recorded' +[ "$(jq -r '.verification.gate' "$RUN_OUTPUT")" = not-run ] || fail 'gate ran after scope failure' +pass 'Bash adapter withholds the gate after scope failure' + +workspace="$TMP_ROOT/unmarked" +init_workspace "$workspace" +rm -f "$workspace/.offload-execution-workspace" +run_adapter success "$workspace" +[ "$RUN_EXIT" -ne 0 ] || fail 'unmarked workspace was accepted' +pass 'Bash adapter fails closed for unmarked workspaces' From d67649427459abf430a8481a55b342be9bc8d95d Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 18:04:56 +0800 Subject: [PATCH 07/11] feat: add durable resource ownership ledger --- README.md | 13 ++ modes/execution.md | 5 + scripts/cleanup-research-workspace.ps1 | 34 ++- scripts/cleanup-research-workspace.sh | 30 ++- scripts/execution-workspace.ps1 | 61 +++++- scripts/execution-workspace.sh | 54 ++++- scripts/make-research-workspace.ps1 | 36 +++- scripts/make-research-workspace.sh | 33 ++- scripts/resource-ledger.ps1 | 284 +++++++++++++++++++++++++ scripts/resource-ledger.sh | 86 ++++++++ scripts/run-agy-json.ps1 | 81 ++++++- scripts/run-agy-json.sh | 134 +++++++++++- tests/test_resource_ledger.ps1 | 107 ++++++++++ tests/test_resource_ledger.sh | 103 +++++++++ 14 files changed, 1050 insertions(+), 11 deletions(-) create mode 100644 scripts/resource-ledger.ps1 create mode 100644 scripts/resource-ledger.sh create mode 100644 tests/test_resource_ledger.ps1 create mode 100644 tests/test_resource_ledger.sh diff --git a/README.md b/README.md index 2436edb..0e9a35e 100644 --- a/README.md +++ b/README.md @@ -250,6 +250,19 @@ After generating provenance, `cleanup-research-workspace` cleans the temporary w - On `success`, the helper removes intermediate worker files and snapshot directories while preserving `final.md`, `provenance.json` when present, `routing-outcomes.json`, the workspace marker, and `evidence-disposition.json`. The disposition manifest records each routing evidence path, its pre-cleanup existence, a SHA-256 hash for existing regular files, and whether it was retained, pruned, missing, or left uninspected for safety. - On `partial` or failure, the helper retains all raw artifacts and logs. +### Crash recovery and resource ownership + +The adapters maintain a durable, orchestrator-owned resource ledger outside worker checkouts. Pass the same ledger, assignment ID, and parent ID to workspace and worker helpers when coordinating a run: + +```bash +LEDGER="$SCRATCH/offload-resource-ledger.json" +WORKSPACE=$(./scripts/make-research-workspace.sh --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --source-repo "$PWD" --path src/auth) +./scripts/run-agy-json.sh --role researcher --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --output "$WORKSPACE/worker.json" --error "$WORKSPACE/worker.err" -- --prompt '...' +./scripts/cleanup-research-workspace.sh --workspace "$WORKSPACE" --status success --ledger "$LEDGER" --resource-id "research-workspace:$ASSIGNMENT" +``` + +If the orchestrator crashes, reconcile the ledger on its next run. Reconciliation terminates recorded worker processes before cleaning their resources and discovers AGY-native Git worktrees that were never registered as `unknown`. It never deletes dirty, unmerged, unowned, ambiguous, or otherwise unprovable resources. + ### Shared report format All modes format results into a consistent summary: diff --git a/modes/execution.md b/modes/execution.md index e714dcf..78ac6da 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -375,3 +375,8 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - Bash: `"$OFFLOAD_ROOT/scripts/execution-workspace.sh" cleanup --manifest "" --status success|failed|retain` - PowerShell: `& "$OffloadRoot/scripts/execution-workspace.ps1" cleanup --manifest "" --status success|failed|retain` Wait for active worker processes to terminate before calling cleanup. Pass `--status retain` if preserving a candidate workspace for orchestrator inspection. + +- **Ownership ledger and crash recovery.** Candidate worktrees, research workspaces, and worker processes are recorded in an orchestrator-owned ledger outside their resource paths. Register a resource before or immediately after creation, update it as the lifecycle changes (`active`, `failed`, `timed_out`, `cancelled`, `quota_handoff`, `cleanup_pending`, or `completed`), and run reconciliation at the start of a later run: + - Bash: `"$OFFLOAD_ROOT/scripts/resource-ledger.sh" reconcile --ledger "" --source-repo ""` + - PowerShell: `& "$OffloadRoot/scripts/resource-ledger.ps1" reconcile --ledger "" --source-repo ""` + Cleanup terminates and waits for an owned worker process before touching its resources. It removes only records whose owner marker, parent relationship, and Git/worktree safety checks pass. Dirty, unmerged, unknown, ambiguous, or otherwise unprovable resources remain on disk and in the ledger for review. Never place the ledger inside a worker checkout. diff --git a/scripts/cleanup-research-workspace.ps1 b/scripts/cleanup-research-workspace.ps1 index b0ed1b7..e8cc63d 100644 --- a/scripts/cleanup-research-workspace.ps1 +++ b/scripts/cleanup-research-workspace.ps1 @@ -6,16 +6,26 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version 3.0 function Show-Usage { - [Console]::Error.WriteLine("Usage: cleanup-research-workspace.ps1 --workspace --status ") + [Console]::Error.WriteLine("Usage: cleanup-research-workspace.ps1 --workspace --status [--ledger --resource-id ]") } +$script:LedgerPath = "" +$script:ResourceId = "" + function Fail([string]$message, [int]$exitCode = 1) { [Console]::Error.WriteLine("Error: $message") + if ($script:LedgerPath -and $script:ResourceId -and (Test-Path -LiteralPath $script:LedgerPath -PathType Leaf)) { + try { + & pwsh -NoProfile -NonInteractive -File (Join-Path $PSScriptRoot 'resource-ledger.ps1') update --ledger $script:LedgerPath --resource-id $script:ResourceId --state failed --error $message | Out-Null + } catch { } + } exit $exitCode } $workspace = "" $status = "" +$ledgerPath = "" +$resourceId = "" $i = 0 while ($i -lt $args.Count) { @@ -34,6 +44,14 @@ while ($i -lt $args.Count) { Fail "--status requires a value" } $status = [string]$args[$i] + } elseif ($arg -eq '--ledger') { + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--ledger requires a path" } + $ledgerPath = [string]$args[$i] + } elseif ($arg -eq '--resource-id') { + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--resource-id requires a value" } + $resourceId = [string]$args[$i] } elseif ($arg -eq '-h' -or $arg -eq '--help') { Show-Usage exit 0 @@ -44,6 +62,12 @@ while ($i -lt $args.Count) { $i++ } +if (($ledgerPath -and -not $resourceId) -or ($resourceId -and -not $ledgerPath)) { + Fail "--ledger and --resource-id must be supplied together" +} +$script:LedgerPath = if ($ledgerPath) { [System.IO.Path]::GetFullPath($ledgerPath) } else { "" } +$script:ResourceId = $resourceId + if ([string]::IsNullOrWhiteSpace($workspace) -or [string]::IsNullOrWhiteSpace($status)) { Show-Usage Fail "--workspace and --status are required" @@ -459,4 +483,12 @@ if ($status -eq 'success') { } } +if ($script:LedgerPath -and $script:ResourceId) { + try { + & pwsh -NoProfile -NonInteractive -File (Join-Path $PSScriptRoot 'resource-ledger.ps1') update --ledger $script:LedgerPath --resource-id $script:ResourceId --state retained --error "research workspace retained as evidence" | Out-Null + } catch { + Fail "could not update resource ledger: $($_.Exception.Message)" + } +} + exit 0 diff --git a/scripts/cleanup-research-workspace.sh b/scripts/cleanup-research-workspace.sh index 18719a7..8b07518 100755 --- a/scripts/cleanup-research-workspace.sh +++ b/scripts/cleanup-research-workspace.sh @@ -3,6 +3,10 @@ set -euo pipefail workspace="" status="" +ledger_path="" +resource_id="" +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" +resource_ledger="$script_dir/resource-ledger.sh" while [[ $# -gt 0 ]]; do case "$1" in @@ -14,8 +18,16 @@ while [[ $# -gt 0 ]]; do status="$2" shift 2 ;; + --ledger) + ledger_path="$2" + shift 2 + ;; + --resource-id) + resource_id="$2" + shift 2 + ;; -h|--help) - printf 'Usage: %s --workspace --status \n' "$0" >&2 + printf 'Usage: %s --workspace --status [--ledger --resource-id ]\n' "$0" >&2 exit 0 ;; *) @@ -25,6 +37,19 @@ while [[ $# -gt 0 ]]; do esac done +if [[ -n "$ledger_path" && -z "$resource_id" ]] || [[ -z "$ledger_path" && -n "$resource_id" ]]; then + printf 'Error: --ledger and --resource-id must be supplied together\n' >&2 + exit 1 +fi + +ledger_update() { + local state="$1" + local error_message="${2:-}" + if [[ -n "$ledger_path" && -n "$resource_id" && -f "$ledger_path" ]]; then + bash "$resource_ledger" update --ledger "$ledger_path" --resource-id "$resource_id" --state "$state" --error "$error_message" >/dev/null 2>&1 || true + fi +} + if [[ -z "$workspace" || -z "$status" ]]; then printf 'Error: --workspace and --status are required\n' >&2 exit 1 @@ -116,6 +141,7 @@ fi # For partial and failed, all validation passed, preserve all contents if [[ "$status" == "partial" || "$status" == "failed" ]]; then + ledger_update retained 'research workspace retained as evidence' exit 0 fi @@ -355,3 +381,5 @@ if [[ "$status" == "success" ]]; then done shopt -u nullglob dotglob fi + +ledger_update retained 'research workspace retained as evidence' diff --git a/scripts/execution-workspace.ps1 b/scripts/execution-workspace.ps1 index edeb082..ae087a8 100644 --- a/scripts/execution-workspace.ps1 +++ b/scripts/execution-workspace.ps1 @@ -13,11 +13,12 @@ $script:ManifestMarker = 'offload-execution-manifest-v1' $script:ScriptDir = Split-Path -Parent $PSCommandPath $script:RootDir = Split-Path -Parent $script:ScriptDir $script:ScopeChecker = Join-Path $script:ScriptDir 'check-execution-scope.ps1' +$script:ResourceLedger = Join-Path $script:ScriptDir 'resource-ledger.ps1' function Show-Usage { [Console]::Error.WriteLine(@" Usage: - execution-workspace.ps1 create --source-repo --task-id --baseline --owned [--owned ...] [--frozen ...] [--manifest ] [--workspace-dir ] + execution-workspace.ps1 create --source-repo --task-id --baseline --owned [--owned ...] [--frozen ...] [--manifest ] [--workspace-dir ] [--ledger ] execution-workspace.ps1 verify-export --manifest [--patch-output ] execution-workspace.ps1 integrate --manifest [--target-repo ] execution-workspace.ps1 cleanup --manifest [--status ] @@ -130,6 +131,7 @@ function Cmd-Create([string[]]$cmdArgs) { $frozen = [System.Collections.Generic.List[string]]::new() $manifestPath = "" $workspaceDir = "" + $ledgerPath = "" $i = 0 while ($i -lt $cmdArgs.Count) { @@ -176,6 +178,12 @@ function Cmd-Create([string[]]$cmdArgs) { $workspaceDir = [string]$cmdArgs[$i] } elseif ($arg.StartsWith('--workspace-dir=')) { $workspaceDir = $arg.Substring('--workspace-dir='.Length) + } elseif ($arg -eq '--ledger') { + $i++ + if ($i -ge $cmdArgs.Count) { Fail "--ledger requires a path" } + $ledgerPath = [string]$cmdArgs[$i] + } elseif ($arg.StartsWith('--ledger=')) { + $ledgerPath = $arg.Substring('--ledger='.Length) } elseif ($arg -eq '-h' -or $arg -eq '--help') { Show-Usage exit 0 @@ -265,6 +273,14 @@ function Cmd-Create([string[]]$cmdArgs) { Fail "manifest path must be outside the worker checkout: $manifestPath" } + if ([string]::IsNullOrWhiteSpace($ledgerPath)) { + $ledgerPath = [System.IO.Path]::Combine((Split-Path -Parent $canonManifest), 'resource-ledger.json') + } + $canonLedger = Canonicalize-Path $ledgerPath + if (Test-PathWithin $canonLedger $canonWorkspace) { + Fail "ledger path must be outside the worker checkout: $ledgerPath" + } + $manifestDir = Split-Path -Parent $canonManifest if (-not (Test-Path -LiteralPath $manifestDir -PathType Container)) { [System.IO.Directory]::CreateDirectory($manifestDir) | Out-Null @@ -281,6 +297,10 @@ function Cmd-Create([string[]]$cmdArgs) { } } + $resourceId = "worktree:$taskId" + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger register --ledger $canonLedger --assignment-id $taskId --parent-id $canonRepo --parent-path $canonRepo --resource-type git-worktree --path $canonWorkspace --owner-marker "$($script:MarkerName)=$($script:MarkerContent)" --resource-id $resourceId --state registered | Out-Null + if ($LASTEXITCODE -ne 0) { Fail "failed to register execution workspace in resource ledger" } + # Add git worktree $resAdd = Run-GitCommand -WorkingDir $canonRepo -GitArgs @('worktree', 'add', '--detach', $canonWorkspace, $resolvedBaseline) if ($resAdd.ExitCode -ne 0) { @@ -318,6 +338,9 @@ function Cmd-Create([string[]]$cmdArgs) { [System.IO.File]::AppendAllText($excludePath, "`n$($script:MarkerName)`n", [System.Text.UTF8Encoding]::new($false)) } + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger update --ledger $canonLedger --resource-id $resourceId --state active | Out-Null + if ($LASTEXITCODE -ne 0) { Fail "failed to activate execution workspace in resource ledger" } + $manifestData = [ordered]@{ schema_version = 1 marker = $script:ManifestMarker @@ -328,6 +351,8 @@ function Cmd-Create([string[]]$cmdArgs) { baseline = $resolvedBaseline owned_paths = @($normOwned) frozen_paths = @($normFrozen) + ledger_path = $canonLedger + resource_id = $resourceId status = "created" created_at = Get-IsoTimestamp } @@ -547,6 +572,8 @@ function Cmd-VerifyExport([string[]]$cmdArgs) { baseline = $manifest.baseline owned_paths = @($manifest.owned_paths) frozen_paths = @($manifest.frozen_paths) + ledger_path = if ($manifest.PSObject.Properties['ledger_path']) { $manifest.ledger_path } else { $null } + resource_id = if ($manifest.PSObject.Properties['resource_id']) { $manifest.resource_id } else { $null } status = "exported" patch_file = $canonPatch patch_digest = $patchDigest @@ -608,6 +635,8 @@ function Cmd-Integrate([string[]]$cmdArgs) { $patchDigest = [string]$manifest.patch_digest $sourceRepo = Canonicalize-Path $manifest.source_repo $taskId = [string]$manifest.task_id + $ledgerPath = if ($manifest.PSObject.Properties['ledger_path']) { [string]$manifest.ledger_path } else { "" } + $resourceId = if ($manifest.PSObject.Properties['resource_id']) { [string]$manifest.resource_id } else { "" } if ([string]::IsNullOrWhiteSpace($patchFile) -or [string]::IsNullOrWhiteSpace($patchDigest)) { Fail "manifest does not record an exported patch file or digest; run verify-export first" @@ -685,6 +714,8 @@ function Cmd-Integrate([string[]]$cmdArgs) { baseline = $manifest.baseline owned_paths = @($manifest.owned_paths) frozen_paths = @($manifest.frozen_paths) + ledger_path = if ($manifest.PSObject.Properties['ledger_path']) { $manifest.ledger_path } else { $null } + resource_id = if ($manifest.PSObject.Properties['resource_id']) { $manifest.resource_id } else { $null } status = "integrated" patch_file = $manifest.patch_file patch_digest = $manifest.patch_digest @@ -696,6 +727,11 @@ function Cmd-Integrate([string[]]$cmdArgs) { $manifestJson = $manifestData | ConvertTo-Json -Depth 5 [System.IO.File]::WriteAllText($canonManifest, "$manifestJson`n", [System.Text.UTF8Encoding]::new($false)) + if ($ledgerPath -and $resourceId) { + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger update --ledger $ledgerPath --resource-id $resourceId --state completed --allow-dirty true | Out-Null + if ($LASTEXITCODE -ne 0) { Fail "failed to mark integrated execution workspace in resource ledger" } + } + [Console]::Out.WriteLine("Successfully integrated candidate $taskId into $canonTarget") } @@ -747,6 +783,8 @@ function Cmd-Cleanup([string[]]$cmdArgs) { $sourceRepo = [string]$manifest.source_repo $taskId = [string]$manifest.task_id $patchFile = if ($manifest.PSObject.Properties['patch_file']) { [string]$manifest.patch_file } else { "" } + $ledgerPath = if ($manifest.PSObject.Properties['ledger_path']) { [string]$manifest.ledger_path } else { "" } + $resourceId = if ($manifest.PSObject.Properties['resource_id']) { [string]$manifest.resource_id } else { "" } if ([string]::IsNullOrWhiteSpace($workspaceDir)) { Fail "manifest does not specify workspace_dir" } if ([string]::IsNullOrWhiteSpace($sourceRepo)) { Fail "manifest does not specify source_repo" } @@ -756,11 +794,17 @@ function Cmd-Cleanup([string[]]$cmdArgs) { } if ($status -in @('failed', 'retain')) { + if ($ledgerPath -and $resourceId) { + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger update --ledger $ledgerPath --resource-id $resourceId --state retained | Out-Null + } [Console]::Out.WriteLine("Candidate $taskId marked $status; retaining workspace at $workspaceDir") exit 0 } if (-not (Test-Path -LiteralPath $workspaceDir -PathType Container)) { + if ($ledgerPath -and $resourceId) { + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger cleanup --ledger $ledgerPath --resource-id $resourceId | Out-Null + } Run-GitCommand -WorkingDir $sourceRepo -GitArgs @('worktree', 'prune') | Out-Null Remove-Item -LiteralPath $canonManifest -Force -ErrorAction SilentlyContinue if (-not [string]::IsNullOrWhiteSpace($patchFile)) { @@ -773,6 +817,21 @@ function Cmd-Cleanup([string[]]$cmdArgs) { $canonWorkspace = Canonicalize-Path $workspaceDir $canonSource = Canonicalize-Path $sourceRepo + if ($ledgerPath -and $resourceId) { + & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger update --ledger $ledgerPath --resource-id $resourceId --state cleanup_pending | Out-Null + if ($LASTEXITCODE -ne 0) { Fail "failed to mark execution workspace cleanup-pending in resource ledger" } + $ledgerResult = & pwsh -NoProfile -NonInteractive -File $script:ResourceLedger cleanup --ledger $ledgerPath --resource-id $resourceId | ConvertFrom-Json + if ($ledgerResult.retained -eq $true) { + Fail "execution workspace retained for review: $canonWorkspace" + } + if ($ledgerResult.removed -eq $true) { + if (Test-Path -LiteralPath $canonManifest) { Remove-Item -LiteralPath $canonManifest -Force -ErrorAction SilentlyContinue } + if ($patchFile -and (Test-Path -LiteralPath $patchFile)) { Remove-Item -LiteralPath $patchFile -Force -ErrorAction SilentlyContinue } + [Console]::Out.WriteLine("Cleaned up manifest-owned workspace: $canonWorkspace") + exit 0 + } + } + # Safety bounds $pathRoot = [System.IO.Path]::GetPathRoot($canonWorkspace) $trimmedRoot = Canonicalize-Path $pathRoot diff --git a/scripts/execution-workspace.sh b/scripts/execution-workspace.sh index c624098..91261f7 100644 --- a/scripts/execution-workspace.sh +++ b/scripts/execution-workspace.sh @@ -12,6 +12,7 @@ MANIFEST_MARKER="offload-execution-manifest-v1" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" OFFLOAD_ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" SCOPE_CHECKER="$SCRIPT_DIR/check-execution-scope.sh" +RESOURCE_LEDGER="$SCRIPT_DIR/resource-ledger.sh" fail() { printf 'Error: %s\n' "$1" >&2 @@ -21,7 +22,7 @@ fail() { usage() { cat <<'EOF' >&2 Usage: - execution-workspace.sh create --source-repo --task-id --baseline --owned [--owned ...] [--frozen ...] [--manifest ] [--workspace-dir ] + execution-workspace.sh create --source-repo --task-id --baseline --owned [--owned ...] [--frozen ...] [--manifest ] [--workspace-dir ] [--ledger ] execution-workspace.sh verify-export --manifest [--patch-output ] execution-workspace.sh integrate --manifest [--target-repo ] execution-workspace.sh cleanup --manifest [--status ] @@ -150,6 +151,7 @@ cmd_create() { local frozen=() local manifest_path="" local workspace_dir="" + local ledger_path="" while [ $# -gt 0 ]; do case "$1" in @@ -216,6 +218,15 @@ cmd_create() { workspace_dir="${1#*=}" shift ;; + --ledger) + [ $# -ge 2 ] || fail "--ledger requires a path" + ledger_path="$2" + shift 2 + ;; + --ledger=*) + ledger_path="${1#*=}" + shift + ;; -h|--help) usage exit 0 @@ -319,6 +330,15 @@ cmd_create() { fail "manifest path must be outside the worker checkout: $manifest_path" fi + if [ -z "$ledger_path" ]; then + ledger_path="$(dirname "$canon_manifest")/resource-ledger.json" + fi + local canon_ledger + canon_ledger="$(canonicalize_path "$ledger_path")" + if [[ "$canon_ledger" == "$canon_workspace/"* || "$canon_ledger" == "$canon_workspace" ]]; then + fail "ledger path must be outside the worker checkout: $ledger_path" + fi + mkdir -p "$(dirname "$canon_manifest")" mkdir -p "$(dirname "$canon_workspace")" @@ -327,6 +347,9 @@ cmd_create() { fail "workspace directory already exists and is not empty: $workspace_dir" fi + local resource_id="worktree:$task_id" + bash "$RESOURCE_LEDGER" register --ledger "$canon_ledger" --assignment-id "$task_id" --parent-id "$canon_repo" --parent-path "$canon_repo" --resource-type git-worktree --path "$canon_workspace" --owner-marker "$MARKER_NAME=$MARKER_CONTENT" --resource-id "$resource_id" --state registered >/dev/null + # Create Git worktree if ! git -C "$canon_repo" worktree add --detach "$canon_workspace" "$resolved_baseline" >/dev/null 2>&1; then fail "failed to create git worktree at $canon_workspace from baseline $resolved_baseline" @@ -348,6 +371,8 @@ cmd_create() { fi fi + bash "$RESOURCE_LEDGER" update --ledger "$canon_ledger" --resource-id "$resource_id" --state active >/dev/null + # Build JSON manifest local created_at created_at="$(get_iso_timestamp)" @@ -387,6 +412,8 @@ cmd_create() { "baseline": "$resolved_baseline", "owned_paths": [$owned_json], "frozen_paths": [$frozen_json], + "ledger_path": "$canon_ledger", + "resource_id": "$resource_id", "status": "created", "created_at": "$created_at" } @@ -684,12 +711,14 @@ cmd_integrate() { marker="$(json_extract_string "$canon_manifest" "marker")" [ "$marker" = "$MANIFEST_MARKER" ] || fail "invalid manifest marker in $manifest_path" - local status patch_file patch_digest source_repo task_id + local status patch_file patch_digest source_repo task_id ledger_path resource_id status="$(json_extract_string "$canon_manifest" "status")" patch_file="$(json_extract_string "$canon_manifest" "patch_file")" patch_digest="$(json_extract_string "$canon_manifest" "patch_digest")" source_repo="$(json_extract_string "$canon_manifest" "source_repo")" task_id="$(json_extract_string "$canon_manifest" "task_id")" + ledger_path="$(json_extract_string "$canon_manifest" "ledger_path")" + resource_id="$(json_extract_string "$canon_manifest" "resource_id")" [ -n "$patch_file" ] || fail "manifest does not record an exported patch file; run verify-export first" [ -n "$patch_digest" ] || fail "manifest does not record a patch digest; run verify-export first" @@ -769,6 +798,10 @@ cmd_integrate() { rm -f "$canon_manifest.bak" fi + if [ -n "$ledger_path" ] && [ -n "$resource_id" ]; then + bash "$RESOURCE_LEDGER" update --ledger "$ledger_path" --resource-id "$resource_id" --state completed --allow-dirty true >/dev/null + fi + printf 'Successfully integrated candidate %s into %s\n' "$task_id" "$canon_target" } @@ -818,11 +851,13 @@ cmd_cleanup() { marker="$(json_extract_string "$canon_manifest" "marker")" [ "$marker" = "$MANIFEST_MARKER" ] || fail "invalid manifest marker in $manifest_path" - local workspace_dir source_repo task_id patch_file + local workspace_dir source_repo task_id patch_file ledger_path resource_id workspace_dir="$(json_extract_string "$canon_manifest" "workspace_dir")" source_repo="$(json_extract_string "$canon_manifest" "source_repo")" task_id="$(json_extract_string "$canon_manifest" "task_id")" patch_file="$(json_extract_string "$canon_manifest" "patch_file")" + ledger_path="$(json_extract_string "$canon_manifest" "ledger_path")" + resource_id="$(json_extract_string "$canon_manifest" "resource_id")" [ -n "$workspace_dir" ] || fail "manifest does not specify workspace_dir" [ -n "$source_repo" ] || fail "manifest does not specify source_repo" @@ -831,6 +866,9 @@ cmd_cleanup() { success) ;; failed|retain) + if [ -n "$ledger_path" ] && [ -n "$resource_id" ]; then + bash "$RESOURCE_LEDGER" update --ledger "$ledger_path" --resource-id "$resource_id" --state retained >/dev/null + fi printf 'Candidate %s marked %s; retaining workspace at %s\n' "$task_id" "$status" "$workspace_dir" exit 0 ;; @@ -839,6 +877,16 @@ cmd_cleanup() { ;; esac + if [ -n "$ledger_path" ] && [ -n "$resource_id" ]; then + bash "$RESOURCE_LEDGER" update --ledger "$ledger_path" --resource-id "$resource_id" --state cleanup_pending >/dev/null + local ledger_result + ledger_result="$(bash "$RESOURCE_LEDGER" cleanup --ledger "$ledger_path" --resource-id "$resource_id")" + if command -v jq >/dev/null 2>&1 && jq -e '.retained == true' <<<"$ledger_result" >/dev/null; then + printf 'Retained execution workspace for review: %s\n' "$workspace_dir" >&2 + exit 1 + fi + fi + # If workspace directory is already gone, prune and remove manifest if [ ! -d "$workspace_dir" ]; then git -C "$source_repo" worktree prune >/dev/null 2>&1 || true diff --git a/scripts/make-research-workspace.ps1 b/scripts/make-research-workspace.ps1 index e215168..ff2443c 100644 --- a/scripts/make-research-workspace.ps1 +++ b/scripts/make-research-workspace.ps1 @@ -6,11 +6,19 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version 3.0 function Show-Usage { - [Console]::Error.WriteLine("Usage: make-research-workspace.ps1 [--source-repo ] [--path ...]") + [Console]::Error.WriteLine("Usage: make-research-workspace.ps1 [--source-repo ] [--path ...] [--ledger ] [--assignment-id ] [--parent-id ]") +} + +function Fail([string]$message, [int]$exitCode = 1) { + [Console]::Error.WriteLine("Error: $message") + exit $exitCode } function Cleanup-And-Fail([string]$ws, [string]$message, [int]$exitCode = 1) { [Console]::Error.WriteLine("Error: $message") + if ($script:LedgerPath -and $script:ResourceId -and (Test-Path -LiteralPath $script:LedgerPath -PathType Leaf)) { + & pwsh -NoProfile -NonInteractive -File (Join-Path $PSScriptRoot 'resource-ledger.ps1') update --ledger $script:LedgerPath --resource-id $script:ResourceId --state failed --error $message | Out-Null + } if ($ws -and (Test-Path -LiteralPath $ws)) { Remove-Item -LiteralPath $ws -Recurse -Force -ErrorAction SilentlyContinue } @@ -19,6 +27,11 @@ function Cleanup-And-Fail([string]$ws, [string]$message, [int]$exitCode = 1) { $sourceRepo = "" $declaredPaths = [System.Collections.Generic.List[string]]::new() +$ledgerPath = "" +$assignmentId = "" +$parentId = "" +$script:LedgerPath = "" +$script:ResourceId = "" $i = 0 while ($i -lt $args.Count) { @@ -39,6 +52,18 @@ while ($i -lt $args.Count) { exit 1 } $declaredPaths.Add([string]$args[$i]) + } elseif ($arg -eq '--ledger') { + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--ledger requires a path" } + $ledgerPath = [string]$args[$i] + } elseif ($arg -eq '--assignment-id') { + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--assignment-id requires a value" } + $assignmentId = [string]$args[$i] + } elseif ($arg -eq '--parent-id') { + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--parent-id requires a value" } + $parentId = [string]$args[$i] } elseif ($arg -eq '-h' -or $arg -eq '--help') { Show-Usage exit 0 @@ -63,6 +88,15 @@ try { Cleanup-And-Fail $workspace "failed to initialize workspace: $($_.Exception.Message)" } +if ([string]::IsNullOrWhiteSpace($ledgerPath)) { $ledgerPath = [System.IO.Path]::Combine($tempDir, 'offload-resource-ledger.json') } +if ([string]::IsNullOrWhiteSpace($assignmentId)) { $assignmentId = $workspaceName } +if ([string]::IsNullOrWhiteSpace($parentId)) { $parentId = if ($sourceRepo) { $sourceRepo } else { 'orchestrator' } } +$script:LedgerPath = [System.IO.Path]::GetFullPath($ledgerPath) +$script:ResourceId = "research-workspace:$assignmentId" +$ledgerScript = Join-Path $PSScriptRoot 'resource-ledger.ps1' +& pwsh -NoProfile -NonInteractive -File $ledgerScript register --ledger $script:LedgerPath --assignment-id $assignmentId --parent-id $parentId --resource-type research-workspace --path $workspace --owner-marker '.offload-research-workspace=offload-research-workspace-v1' --resource-id $script:ResourceId --state active | Out-Null +if ($LASTEXITCODE -ne 0) { Cleanup-And-Fail $workspace 'failed to register research workspace in resource ledger' } + if (-not [string]::IsNullOrEmpty($sourceRepo)) { if (-not (Test-Path -LiteralPath $sourceRepo -PathType Container)) { Cleanup-And-Fail $workspace "source repository does not exist: $sourceRepo" diff --git a/scripts/make-research-workspace.sh b/scripts/make-research-workspace.sh index 0b6efbc..68be023 100755 --- a/scripts/make-research-workspace.sh +++ b/scripts/make-research-workspace.sh @@ -3,6 +3,11 @@ set -euo pipefail source_repo="" paths=() +ledger_path="" +assignment_id="" +parent_id="" +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" +resource_ledger="$script_dir/resource-ledger.sh" while [[ $# -gt 0 ]]; do case "$1" in @@ -14,8 +19,20 @@ while [[ $# -gt 0 ]]; do paths+=("$2") shift 2 ;; + --ledger) + ledger_path="$2" + shift 2 + ;; + --assignment-id) + assignment_id="$2" + shift 2 + ;; + --parent-id) + parent_id="$2" + shift 2 + ;; -h|--help) - printf 'Usage: %s [--source-repo ] [--path ...]\n' "$0" >&2 + printf 'Usage: %s [--source-repo ] [--path ...] [--ledger ] [--assignment-id ] [--parent-id ]\n' "$0" >&2 exit 0 ;; *) @@ -28,9 +45,21 @@ done workspace=$(mktemp -d "${TMPDIR:-/tmp}/offload-research.XXXXXX") workspace=$(cd "$workspace" && pwd -P) +if [[ -z "$ledger_path" ]]; then + ledger_path="${TMPDIR:-/tmp}/offload-resource-ledger.json" +fi +if [[ -z "$assignment_id" ]]; then + assignment_id="$(basename "$workspace")" +fi +if [[ -z "$parent_id" ]]; then + parent_id="${source_repo:-orchestrator}" +fi +resource_id="research-workspace:$assignment_id" + success=false cleanup() { if [[ "$success" != "true" && -n "${workspace:-}" && -d "${workspace:-}" ]]; then + bash "$resource_ledger" update --ledger "$ledger_path" --resource-id "$resource_id" --state failed --error 'research workspace creation failed' >/dev/null 2>&1 || true rm -rf "$workspace" fi } @@ -38,6 +67,8 @@ trap cleanup EXIT printf 'offload-research-workspace-v1\n' > "$workspace/.offload-research-workspace" +bash "$resource_ledger" register --ledger "$ledger_path" --assignment-id "$assignment_id" --parent-id "$parent_id" --resource-type research-workspace --path "$workspace" --owner-marker '.offload-research-workspace=offload-research-workspace-v1' --resource-id "$resource_id" --state active >/dev/null + if [[ -n "$source_repo" ]]; then if [[ ! -d "$source_repo" ]]; then printf 'Error: source repository does not exist: %s\n' "$source_repo" >&2 diff --git a/scripts/resource-ledger.ps1 b/scripts/resource-ledger.ps1 new file mode 100644 index 0000000..2ac1440 --- /dev/null +++ b/scripts/resource-ledger.ps1 @@ -0,0 +1,284 @@ +#!/usr/bin/env pwsh +# scripts/resource-ledger.ps1 +# Durable, orchestrator-owned ownership ledger for worker resources. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$script:LedgerMarker = 'offload-resource-ledger-v1' +$script:KnownStates = @('registered', 'active', 'completed', 'failed', 'timed_out', 'cancelled', 'quota_handoff', 'cleanup_pending', 'removed', 'retained', 'unknown', 'dirty', 'unmerged', 'ambiguous') + +function Fail([string]$message, [int]$exitCode = 1) { + [Console]::Error.WriteLine("Error: $message") + exit $exitCode +} + +function Usage { + [Console]::Error.WriteLine(@" +Usage: + resource-ledger.ps1 init --ledger PATH + resource-ledger.ps1 register --ledger PATH --assignment-id ID --parent-id ID --resource-type TYPE --owner-marker NAME=VALUE (--path PATH | --process-id PID) [--parent-path PATH] [--resource-id ID] [--state STATE] + resource-ledger.ps1 update --ledger PATH --resource-id ID --state STATE [--allow-dirty true|false] [--error MESSAGE] + resource-ledger.ps1 cleanup --ledger PATH --resource-id ID + resource-ledger.ps1 reconcile --ledger PATH [--source-repo PATH ...] +"@) +} + +function Canonical([string]$Path) { + if ([string]::IsNullOrWhiteSpace($Path)) { return '' } + return [System.IO.Path]::GetFullPath($Path).TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) +} + +function IsoNow { return [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ') } + +function Ensure-Parent([string]$Path) { + $parent = Split-Path -Parent $Path + if (-not [string]::IsNullOrWhiteSpace($parent) -and -not (Test-Path -LiteralPath $parent -PathType Container)) { + [System.IO.Directory]::CreateDirectory($parent) | Out-Null + } +} + +function Atomic-Write([string]$Path, $Value) { + Ensure-Parent $Path + $tmp = "$Path.tmp.$([Guid]::NewGuid().ToString('N'))" + $json = $Value | ConvertTo-Json -Depth 12 + [System.IO.File]::WriteAllText($tmp, "$json`n", [Text.UTF8Encoding]::new($false)) + Move-Item -LiteralPath $tmp -Destination $Path -Force +} + +function Read-Ledger([string]$Path) { + $canon = Canonical $Path + if (-not (Test-Path -LiteralPath $canon -PathType Leaf)) { Fail "ledger file does not exist: $Path" } + try { $ledger = Get-Content -LiteralPath $canon -Raw | ConvertFrom-Json -Depth 20 } catch { Fail "invalid ledger JSON: $Path ($($_.Exception.Message))" } + if ($null -eq $ledger -or $ledger.marker -ne $script:LedgerMarker -or $ledger.schema_version -ne 1) { Fail "invalid resource ledger marker or schema: $Path" } + if ($null -eq $ledger.resources) { $ledger | Add-Member -NotePropertyName resources -NotePropertyValue @() } + return $ledger +} + +function Write-Ledger([string]$Path, $Ledger) { + $Ledger.updated_at = IsoNow + Atomic-Write (Canonical $Path) $Ledger +} + +function Test-Within([string]$Child, [string]$Parent) { + $c = Canonical $Child; $p = Canonical $Parent + if ([string]::IsNullOrWhiteSpace($c) -or [string]::IsNullOrWhiteSpace($p)) { return $false } + if ([string]::Equals($c, $p, [StringComparison]::OrdinalIgnoreCase)) { return $true } + return $c.StartsWith("$p$([IO.Path]::DirectorySeparatorChar)", [StringComparison]::OrdinalIgnoreCase) +} + +function Assert-Ledger-Outside([string]$Ledger, [string]$ResourcePath) { + if ([string]::IsNullOrWhiteSpace($ResourcePath)) { return } + if (Test-Within (Canonical $Ledger) (Canonical $ResourcePath)) { Fail "ledger must be outside the resource path: $Ledger" } +} + +function Get-OwnerMarker($Record) { + if ($null -eq $Record.owner_marker) { return $null } + $name = [string]$Record.owner_marker.name + $value = [string]$Record.owner_marker.value + if ([string]::IsNullOrWhiteSpace($name) -or [string]::IsNullOrWhiteSpace($value)) { return $null } + return @{ name = $name; value = $value } +} + +function Test-ReparseTree([string]$Path) { + $root = Get-Item -LiteralPath $Path -Force + if ($root.Attributes.HasFlag([IO.FileAttributes]::ReparsePoint)) { return $true } + foreach ($item in @(Get-ChildItem -LiteralPath $Path -Force -ErrorAction Stop)) { + if ($item.Attributes.HasFlag([IO.FileAttributes]::ReparsePoint)) { return $true } + if ($item.PSIsContainer -and (Test-ReparseTree $item.FullName)) { return $true } + } + return $false +} + +function Run-Git([string]$WorkingDir, [string[]]$GitArgs) { + $psi = [Diagnostics.ProcessStartInfo]::new() + $psi.FileName = 'git'; $psi.WorkingDirectory = $WorkingDir; $psi.UseShellExecute = $false + $psi.RedirectStandardOutput = $true; $psi.RedirectStandardError = $true; $psi.CreateNoWindow = $true + foreach ($a in $GitArgs) { $psi.ArgumentList.Add($a) } + $p = [Diagnostics.Process]::Start($psi) + $o = $p.StandardOutput.ReadToEnd(); $e = $p.StandardError.ReadToEnd(); $p.WaitForExit() + return [PSCustomObject]@{ ExitCode = $p.ExitCode; Stdout = $o; Stderr = $e } +} + +function Get-Resource($Ledger, [string]$Id) { + return @($Ledger.resources | Where-Object { $_.resource_id -eq $Id }) | Select-Object -First 1 +} + +function New-Ledger([string]$Path) { + $canon = Canonical $Path + if (Test-Path -LiteralPath $canon -PathType Leaf) { Read-Ledger $canon | Out-Null; return } + Atomic-Write $canon ([ordered]@{ schema_version = 1; marker = $script:LedgerMarker; ledger_id = [Guid]::NewGuid().ToString('N'); created_at = IsoNow; updated_at = IsoNow; resources = @() }) +} + +function Parse-Args([string[]]$InputArgs) { + $v = @{}; $pos = @{}; $i = 0 + while ($i -lt $InputArgs.Count) { + $a = [string]$InputArgs[$i] + if (-not $a.StartsWith('--')) { Fail "unexpected argument: $a" } + if ($a.Contains('=')) { $parts = $a.Substring(2).Split('=', 2); $v[$parts[0]] = $parts[1] } + else { $key = $a.Substring(2); $i++; if ($i -ge $InputArgs.Count) { Fail "--$key requires a value" }; $v[$key] = [string]$InputArgs[$i] } + $i++ + } + return $v +} + +function Require($Options, [string]$Name) { + if (-not $Options.ContainsKey($Name) -or [string]::IsNullOrWhiteSpace([string]$Options[$Name])) { Fail "--$Name is required" } + return [string]$Options[$Name] +} + +function Cmd-Register($o) { + $ledgerPath = Canonical (Require $o 'ledger'); $assignment = Require $o 'assignment-id'; $parent = Require $o 'parent-id'; $type = Require $o 'resource-type'; $markerRaw = Require $o 'owner-marker' + $markerParts = $markerRaw.Split('=', 2); if ($markerParts.Count -ne 2 -or [string]::IsNullOrWhiteSpace($markerParts[0]) -or [string]::IsNullOrWhiteSpace($markerParts[1])) { Fail '--owner-marker must be NAME=VALUE' } + $resourcePath = if ($o.ContainsKey('path')) { Canonical ([string]$o['path']) } else { '' } + $processId = if ($o.ContainsKey('process-id')) { [int]$o['process-id'] } else { 0 } + if ([string]::IsNullOrWhiteSpace($resourcePath) -and $processId -le 0) { Fail 'one of --path or --process-id is required' } + Assert-Ledger-Outside $ledgerPath $resourcePath + $state = if ($o.ContainsKey('state')) { [string]$o['state'] } else { 'registered' } + if ($script:KnownStates -notcontains $state) { Fail "invalid resource state: $state" } + $ledger = if (Test-Path -LiteralPath $ledgerPath -PathType Leaf) { Read-Ledger $ledgerPath } else { New-Ledger $ledgerPath; Read-Ledger $ledgerPath } + $id = if ($o.ContainsKey('resource-id')) { [string]$o['resource-id'] } else { "${type}:$([Guid]::NewGuid().ToString('N'))" } + $existing = Get-Resource $ledger $id + $now = IsoNow + $record = [ordered]@{ resource_id = $id; assignment_id = $assignment; parent_id = $parent; parent_path = if ($o.ContainsKey('parent-path')) { Canonical ([string]$o['parent-path']) } else { $null }; resource_type = $type; path = if ($resourcePath) { $resourcePath } else { $null }; process_identity = if ($processId -gt 0) { [ordered]@{ pid = $processId; start_time = if ($o.ContainsKey('process-start-time')) { [string]$o['process-start-time'] } else { $null } } } else { $null }; owner_marker = [ordered]@{ name = $markerParts[0]; value = $markerParts[1] }; state = $state; allow_dirty = $false; created_at = $now; updated_at = $now; cleanup_attempts = 0; last_error = $null } + if ($null -ne $existing) { foreach ($p in $record.Keys) { $existing | Add-Member -Force -NotePropertyName $p -NotePropertyValue $record[$p] } } else { $ledger.resources = @($ledger.resources) + @([PSCustomObject]$record) } + Write-Ledger $ledgerPath $ledger + [Console]::Out.WriteLine(($record | ConvertTo-Json -Depth 8 -Compress)) +} + +function Cmd-Update($o) { + $ledgerPath = Canonical (Require $o 'ledger'); $id = Require $o 'resource-id'; $state = Require $o 'state' + if ($script:KnownStates -notcontains $state) { Fail "invalid resource state: $state" } + $ledger = Read-Ledger $ledgerPath; $record = Get-Resource $ledger $id + if ($null -eq $record) { Fail "resource not found in ledger: $id" } + $record.state = $state; $record.updated_at = IsoNow + if ($o.ContainsKey('allow-dirty')) { $record.allow_dirty = ([string]$o['allow-dirty']).ToLowerInvariant() -eq 'true' } + if ($o.ContainsKey('error')) { $record.last_error = [string]$o['error'] } + Write-Ledger $ledgerPath $ledger + [Console]::Out.WriteLine(($record | ConvertTo-Json -Depth 8 -Compress)) +} + +function Test-ProcessIdentity($Record) { + if ($null -eq $Record.process_identity -or [int]$Record.process_identity.pid -le 0) { return $false } + try { + $p = Get-Process -Id ([int]$Record.process_identity.pid) -ErrorAction Stop + if ($null -ne $Record.process_identity.start_time -and -not [string]::IsNullOrWhiteSpace([string]$Record.process_identity.start_time)) { + $storedStart = $Record.process_identity.start_time + if ($storedStart -is [DateTime]) { + $expected = ([DateTime]$storedStart).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss') + } else { + $expected = [DateTimeOffset]::Parse([string]$storedStart).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss') + } + $actual = $p.StartTime.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss') + return $actual -eq $expected + } + return $true + } catch { return $false } +} + +function Stop-OwnedProcess($Record) { + if ($null -eq $Record.process_identity -or [int]$Record.process_identity.pid -le 0) { return $true } + $processId = [int]$Record.process_identity.pid + if ($processId -eq $PID) { return $false } + $p = Get-Process -Id $processId -ErrorAction SilentlyContinue + if ($null -eq $p) { return $true } + if ($null -ne $Record.process_identity.start_time -and -not [string]::IsNullOrWhiteSpace([string]$Record.process_identity.start_time) -and -not (Test-ProcessIdentity $Record)) { return $false } + try { Stop-Process -Id $processId -Force -ErrorAction Stop } catch { try { $p.Kill($true) } catch { } } + $deadline = [DateTime]::UtcNow.AddSeconds(10) + do { + Start-Sleep -Milliseconds 100 + $remaining = Get-Process -Id $processId -ErrorAction SilentlyContinue + if ($null -eq $remaining) { return $true } + if ($IsWindows) { try { & taskkill.exe /PID $processId /T /F | Out-Null } catch { } } + } while ([DateTime]::UtcNow -lt $deadline) + return ($null -eq (Get-Process -Id $processId -ErrorAction SilentlyContinue)) +} + +function Get-WorktreeRegistered([string]$Repo, [string]$Path) { + $result = Run-Git $Repo @('worktree', 'list', '--porcelain') + if ($result.ExitCode -ne 0) { return $false } + foreach ($line in $result.Stdout -split "`n") { if ($line.Trim().StartsWith('worktree ')) { if ([string]::Equals((Canonical $line.Trim().Substring(9)), (Canonical $Path), [StringComparison]::OrdinalIgnoreCase)) { return $true } } } + return $false +} + +function Get-GitRoot([string]$Path) { + $result = Run-Git $Path @('rev-parse', '--show-toplevel') + if ($result.ExitCode -ne 0) { return '' } + return Canonical $result.Stdout.Trim() +} + +function Classify-And-Cleanup($Ledger, $Record, [string]$LedgerPath) { + $result = [ordered]@{ resource_id = $Record.resource_id; state = [string]$Record.state; removed = $false; retained = $false; reason = $null } + if ($Record.state -in @('removed', 'retained', 'unknown', 'dirty', 'unmerged', 'ambiguous')) { $result.retained = $Record.state -ne 'removed'; $result.reason = "already-$($Record.state)"; return $result } + $Record.updated_at = IsoNow + if ($null -ne $Record.process_identity -and [int]$Record.process_identity.pid -gt 0 -and [int]$Record.process_identity.pid -ne $PID -and -not (Test-ProcessIdentity $Record)) { $result.retained = $true; $result.reason = 'process identity does not match'; $Record.state = 'retained'; $result.state = 'retained'; $Record.last_error = $result.reason; return $result } + if (-not (Stop-OwnedProcess $Record)) { $result.retained = $true; $result.reason = 'owned process is still running or could not be terminated'; $Record.state = 'retained'; $result.state = 'retained'; $Record.last_error = $result.reason; return $result } + $path = [string]$Record.path + if ([string]::IsNullOrWhiteSpace($path)) { $Record.state = 'removed'; $result.state = 'removed'; $result.removed = $true; return $result } + $canon = Canonical $path + if (-not (Test-Path -LiteralPath $canon -PathType Container)) { $Record.state = 'removed'; $result.state = 'removed'; $result.removed = $true; $result.reason = 'path already absent'; return $result } + $root = Canonical ([IO.Path]::GetPathRoot($canon)); $cwd = Canonical (Get-Location).Path + $protectedHomes = @($env:USERPROFILE, $env:HOME) | Where-Object { $_ } | ForEach-Object { Canonical $_ } + if ([string]::Equals($canon, $root, [StringComparison]::OrdinalIgnoreCase) -or [string]::Equals($canon, $cwd, [StringComparison]::OrdinalIgnoreCase) -or $protectedHomes -contains $canon) { $result.retained = $true; $result.reason = 'protected path'; $Record.state = 'ambiguous'; $result.state = 'ambiguous'; $Record.last_error = $result.reason; return $result } + if ($null -eq (Get-OwnerMarker $Record)) { $result.retained = $true; $result.reason = 'owner marker is missing or invalid'; $Record.state = 'unknown'; $result.state = 'unknown'; $Record.last_error = $result.reason; return $result } + $marker = Get-OwnerMarker $Record; $markerFile = Join-Path $canon $marker.name + if (-not (Test-Path -LiteralPath $markerFile -PathType Leaf) -or ([IO.File]::ReadAllText($markerFile)).Trim() -ne $marker.value) { $result.retained = $true; $result.reason = 'owner marker does not match'; $Record.state = 'unknown'; $result.state = 'unknown'; $Record.last_error = $result.reason; return $result } + if (Test-ReparseTree $canon) { $result.retained = $true; $result.reason = 'resource contains a reparse point'; $Record.state = 'ambiguous'; $result.state = 'ambiguous'; $Record.last_error = $result.reason; return $result } + if (-not [string]::IsNullOrWhiteSpace([string]$Record.parent_path)) { + $parent = Canonical ([string]$Record.parent_path) + if ([string]::Equals($canon, $parent, [StringComparison]::OrdinalIgnoreCase) -or -not (Test-Path -LiteralPath $parent -PathType Container)) { $result.retained = $true; $result.reason = 'invalid parent repository'; $Record.state = 'ambiguous'; $result.state = 'ambiguous'; $Record.last_error = $result.reason; return $result } + if ($Record.resource_type -eq 'git-worktree' -and -not (Get-WorktreeRegistered $parent $canon)) { $result.retained = $true; $result.reason = 'worktree is not registered with its parent repository'; $Record.state = 'ambiguous'; $result.state = 'ambiguous'; $Record.last_error = $result.reason; return $result } + if ($Record.resource_type -eq 'git-worktree' -and -not $Record.allow_dirty) { + $dirty = Run-Git $canon @('status', '--porcelain'); $unmerged = Run-Git $canon @('ls-files', '-u') + if (-not [string]::IsNullOrWhiteSpace($dirty.Stdout)) { $result.retained = $true; $result.reason = 'worktree is dirty'; $Record.state = 'dirty'; $result.state = 'dirty'; $Record.last_error = $result.reason; return $result } + if (-not [string]::IsNullOrWhiteSpace($unmerged.Stdout) -or (Test-Path -LiteralPath (Join-Path $canon '.git\MERGE_HEAD'))) { $result.retained = $true; $result.reason = 'worktree has an unmerged state'; $Record.state = 'unmerged'; $result.state = 'unmerged'; $Record.last_error = $result.reason; return $result } + } + } + if ($Record.resource_type -ne 'git-worktree' -and [string]::Equals((Get-GitRoot $canon), $canon, [StringComparison]::OrdinalIgnoreCase)) { $result.retained = $true; $result.reason = 'resource is a git checkout'; $Record.state = 'ambiguous'; $result.state = 'ambiguous'; $Record.last_error = $result.reason; return $result } + try { + if ($Record.resource_type -eq 'git-worktree') { Run-Git (Canonical $Record.parent_path) @('worktree', 'remove', '--force', $canon) | Out-Null; Run-Git (Canonical $Record.parent_path) @('worktree', 'prune') | Out-Null } else { Remove-Item -LiteralPath $canon -Recurse -Force } + $Record.state = 'removed'; $Record.updated_at = IsoNow; $result.state = 'removed'; $result.removed = $true + } catch { $result.retained = $true; $result.reason = $_.Exception.Message; $Record.state = 'retained'; $result.state = 'retained'; $Record.last_error = $result.reason } + return $result +} + +function Cmd-Cleanup($o) { + $ledgerPath = Canonical (Require $o 'ledger'); $id = Require $o 'resource-id'; $ledger = Read-Ledger $ledgerPath; $record = Get-Resource $ledger $id + if ($null -eq $record) { Fail "resource not found in ledger: $id" } + $record.cleanup_attempts = [int]$record.cleanup_attempts + 1 + $result = Classify-And-Cleanup $ledger $record $ledgerPath; Write-Ledger $ledgerPath $ledger; [Console]::Out.WriteLine(($result | ConvertTo-Json -Depth 8 -Compress)) +} + +function Cmd-Reconcile($o) { + $ledgerPath = Canonical (Require $o 'ledger'); $ledger = Read-Ledger $ledgerPath; $results = [System.Collections.Generic.List[object]]::new() + $repos = @(); foreach ($key in $o.Keys) { if ($key -eq 'source-repo') { $repos += Canonical ([string]$o[$key]) } } + foreach ($repo in $repos) { + if (-not (Test-Path -LiteralPath $repo -PathType Container)) { continue } + $wt = Run-Git $repo @('worktree', 'list', '--porcelain'); if ($wt.ExitCode -ne 0) { continue } + foreach ($line in $wt.Stdout -split "`n") { + if (-not $line.Trim().StartsWith('worktree ')) { continue } + $path = Canonical $line.Trim().Substring(9); if ([string]::Equals($path, $repo, [StringComparison]::OrdinalIgnoreCase)) { continue } + $known = @($ledger.resources | Where-Object { [string]::Equals([string]$_.path, $path, [StringComparison]::OrdinalIgnoreCase) }) + if ($known.Count -eq 0) { + $ledger.resources = @($ledger.resources) + @([PSCustomObject][ordered]@{ resource_id = "unknown-worktree:$([Guid]::NewGuid().ToString('N'))"; assignment_id = 'unknown'; parent_id = $repo; parent_path = $repo; resource_type = 'git-worktree'; path = $path; process_identity = $null; owner_marker = [ordered]@{ name = ''; value = '' }; state = 'unknown'; allow_dirty = $false; created_at = IsoNow; updated_at = IsoNow; cleanup_attempts = 0; last_error = 'worktree was not present in the ownership ledger' }) + $results.Add([ordered]@{ path = $path; state = 'unknown'; retained = $true; removed = $false }) + } + } + } + $pending = @($ledger.resources | Where-Object { $_.state -notin @('removed', 'retained', 'unknown', 'dirty', 'unmerged', 'ambiguous') }) + foreach ($record in @($pending | Where-Object { $_.resource_type -eq 'worker-process' }) + @($pending | Where-Object { $_.resource_type -ne 'worker-process' })) { $record.cleanup_attempts = [int]$record.cleanup_attempts + 1; $results.Add((Classify-And-Cleanup $ledger $record $ledgerPath)) } + Write-Ledger $ledgerPath $ledger; [Console]::Out.WriteLine((@($results) | ConvertTo-Json -Depth 8 -Compress)) +} + +if ($args.Count -eq 0) { Usage; exit 1 } +$verb = [string]$args[0]; $options = if ($args.Count -gt 1) { Parse-Args ([string[]]$args[1..($args.Count - 1)]) } else { @{} } +switch ($verb) { + 'init' { New-Ledger (Require $options 'ledger'); [Console]::Out.WriteLine((@{ ledger = Canonical (Require $options 'ledger'); state = 'ready' } | ConvertTo-Json -Compress)) } + 'register' { Cmd-Register $options } + 'update' { Cmd-Update $options } + 'cleanup' { Cmd-Cleanup $options } + 'reconcile' { Cmd-Reconcile $options } + '-h' { Usage; exit 0 } + '--help' { Usage; exit 0 } + default { Fail "unrecognized command: $verb" } +} diff --git a/scripts/resource-ledger.sh b/scripts/resource-ledger.sh new file mode 100644 index 0000000..5ff16c1 --- /dev/null +++ b/scripts/resource-ledger.sh @@ -0,0 +1,86 @@ +#!/usr/bin/env bash +# scripts/resource-ledger.sh +# Durable, orchestrator-owned ownership ledger for worker resources. + +set -euo pipefail + +LEDGER_MARKER='offload-resource-ledger-v1' + +die() { printf 'Error: %s\n' "$1" >&2; exit "${2:-1}"; } +usage() { cat >&2 <<'EOF' +Usage: + resource-ledger.sh init --ledger PATH + resource-ledger.sh register --ledger PATH --assignment-id ID --parent-id ID --resource-type TYPE --owner-marker NAME=VALUE (--path PATH | --process-id PID) [--parent-path PATH] [--resource-id ID] [--state STATE] + resource-ledger.sh update --ledger PATH --resource-id ID --state STATE [--allow-dirty true|false] [--error MESSAGE] + resource-ledger.sh cleanup --ledger PATH --resource-id ID + resource-ledger.sh reconcile --ledger PATH [--source-repo PATH ...] +EOF +} +need_jq() { command -v jq >/dev/null 2>&1 || die 'jq is required by resource-ledger.sh'; } +canon() { (cd "$(dirname "$1")" 2>/dev/null && printf '%s/%s\n' "$PWD" "$(basename "$1")") || die "cannot resolve path: $1"; } +now() { date -u '+%Y-%m-%dT%H:%M:%SZ'; } +atomic_write() { local path=$1; local tmp="${path}.tmp.$$.$RANDOM"; mkdir -p "$(dirname "$path")"; cat >"$tmp"; mv -f -- "$tmp" "$path"; } +init_ledger() { local path; path=$(canon "$1"); if [[ -f $path ]]; then jq -e --arg m "$LEDGER_MARKER" '.schema_version == 1 and .marker == $m' "$path" >/dev/null || die "invalid resource ledger: $path"; else atomic_write "$path" </dev/null 2>&1; } + +cmd_register() { + local ledger assignment parent type markerRaw resourcePath processId parentPath resourceId state markerName markerValue + ledger=$(canon "$(required --ledger "$@")"); assignment=$(required --assignment-id "$@"); parent=$(required --parent-id "$@"); type=$(required --resource-type "$@"); markerRaw=$(required --owner-marker "$@") + resourcePath=$(getopt_value --path "$@" || true); processId=$(getopt_value --process-id "$@" || true); parentPath=$(getopt_value --parent-path "$@" || true); resourceId=$(getopt_value --resource-id "$@" || true); state=$(getopt_value --state "$@" || printf registered) + [[ -n $resourcePath || -n $processId ]] || die 'one of --path or --process-id is required' + [[ -z $resourcePath || -z $processId ]] || die '--path and --process-id cannot be combined' + [[ -z $resourcePath || $resourcePath = /* || $resourcePath = [A-Za-z]:* ]] || die '--path must be absolute' + [[ -z $resourcePath ]] || { resourcePath=$(canon "$resourcePath"); within "$ledger" "$resourcePath" && die 'ledger must be outside the resource path'; } + [[ $state =~ ^(registered|active|completed|failed|timed_out|cancelled|quota_handoff|cleanup_pending|removed|retained|unknown|dirty|unmerged|ambiguous)$ ]] || die "invalid resource state: $state" + read -r markerName markerValue < <(marker_parts "$markerRaw" | paste -sd ' ' -) + [[ -z ${parentPath:-} ]] || parentPath=$(canon "$parentPath") + init_ledger "$ledger"; resourceId=${resourceId:-$type:$(date +%s%N)} + local startTime=''; [[ -n $processId ]] && startTime=$(ps -o lstart= -p "$processId" 2>/dev/null | sed 's/^ *//' || true) + local record; record=$(jq -n --arg id "$resourceId" --arg a "$assignment" --arg p "$parent" --arg pp "${parentPath:-}" --arg t "$type" --arg path "${resourcePath:-}" --arg pn "${processId:-}" --arg st "$startTime" --arg mn "$markerName" --arg mv "$markerValue" --arg state "$state" --arg now "$(now)" '{resource_id:$id,assignment_id:$a,parent_id:$p,parent_path:(if $pp=="" then null else $pp end),resource_type:$t,path:(if $path=="" then null else $path end),process_identity:(if $pn=="" then null else {pid:($pn|tonumber),start_time:(if $st=="" then null else $st end)} end),owner_marker:{name:$mn,value:$mv},state:$state,allow_dirty:false,created_at:$now,updated_at:$now,cleanup_attempts:0,last_error:null}') + jq --arg id "$resourceId" --argjson record "$record" '.resources = ((.resources // []) | map(select(.resource_id != $id)) + [$record]) | .updated_at = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))' "$ledger" | atomic_write "$ledger" + printf '%s\n' "$record" +} + +cmd_update() { + local ledger id state allowDirty error; ledger=$(canon "$(required --ledger "$@")"); id=$(required --resource-id "$@"); state=$(required --state "$@"); allowDirty=$(getopt_value --allow-dirty "$@" || true); error=$(getopt_value --error "$@" || true) + [[ $state =~ ^(registered|active|completed|failed|timed_out|cancelled|quota_handoff|cleanup_pending|removed|retained|unknown|dirty|unmerged|ambiguous)$ ]] || die "invalid resource state: $state"; init_ledger "$ledger"; resource_filter "$ledger" "$id" || die "resource not found in ledger: $id" + jq --arg id "$id" --arg state "$state" --arg allow "$allowDirty" --arg error "$error" '(.resources[] | select(.resource_id == $id)) |= (.state=$state | if $allow=="" then . else .allow_dirty=($allow=="true") end | if $error=="" then . else .last_error=$error end | .updated_at=(now|strftime("%Y-%m-%dT%H:%M:%SZ"))) | .updated_at=(now|strftime("%Y-%m-%dT%H:%M:%SZ"))' "$ledger" | atomic_write "$ledger"; jq -c --arg id "$id" '.resources[]|select(.resource_id==$id)' "$ledger" +} + +process_alive() { local pid=$1 state; kill -0 "$pid" 2>/dev/null || return 1; state=$(ps -o stat= -p "$pid" 2>/dev/null | sed 's/^ *//'); [[ $state != Z* ]]; } +process_identity_matches() { local pid=$1 expected=$2 actual; [[ -z $expected ]] && return 0; actual=$(ps -o lstart= -p "$pid" 2>/dev/null | sed 's/^ *//' || true); [[ -n $actual && $actual == "$expected" ]]; } +stop_process() { local pid=$1 expected=${2:-}; [[ $pid -ne $$ ]] || return 1; if process_alive "$pid"; then process_identity_matches "$pid" "$expected" || return 1; kill -TERM "$pid" 2>/dev/null || return 1; for _ in {1..100}; do process_alive "$pid" || return 0; sleep 0.1; done; kill -KILL "$pid" 2>/dev/null || true; ! process_alive "$pid"; else return 0; fi; } +registered_worktree() { git -C "$1" worktree list --porcelain 2>/dev/null | awk -v p="$2" '$1=="worktree" && substr($0,10)==p {found=1} END {exit found?0:1}'; } +protected_path() { local p=$1; [[ $p == / || $p == "$PWD" || $p == "$HOME" || $p == "$(canon /tmp)" ]]; } + +classify_cleanup() { + local ledger=$1 id=$2; local record path parent markerName markerValue pid processStart result dirty unmerged state + record=$(jq -c --arg id "$id" '.resources[]|select(.resource_id==$id)' "$ledger") || die "resource not found in ledger: $id" + state=$(jq -r '.state' <<<"$record"); if [[ $state == removed || $state == retained || $state == unknown || $state == dirty || $state == unmerged || $state == ambiguous ]]; then jq -n --arg id "$id" --arg s "$state" '{resource_id:$id,state:$s,removed:false,retained:($s!="removed"),reason:"already-classified"}'; return; fi + pid=$(jq -r '.process_identity.pid // empty' <<<"$record"); processStart=$(jq -r '.process_identity.start_time // empty' <<<"$record") + if [[ -n $pid ]] && process_alive "$pid" && ! process_identity_matches "$pid" "$processStart"; then result=$(jq -n --arg id "$id" '{resource_id:$id,state:"unknown",removed:false,retained:true,reason:"process identity no longer matches"}'); printf '%s\n' "$result"; return; fi + if [[ -n $pid ]] && ! stop_process "$pid" "$processStart"; then result=$(jq -n --arg id "$id" '{resource_id:$id,state:"retained",removed:false,retained:true,reason:"owned process could not be terminated"}'); printf '%s\n' "$result"; return; fi + path=$(jq -r '.path // empty' <<<"$record"); if [[ -z $path || ! -e $path ]]; then jq --arg id "$id" '.resources[]|select(.resource_id==$id)|.state="removed"' "$ledger" >/dev/null; jq -n --arg id "$id" '{resource_id:$id,state:"removed",removed:true,retained:false,reason:"path already absent"}'; return; fi + markerName=$(jq -r '.owner_marker.name // empty' <<<"$record"); markerValue=$(jq -r '.owner_marker.value // empty' <<<"$record"); parent=$(jq -r '.parent_path // empty' <<<"$record") + if protected_path "$path" || [[ -z $markerName || ! -f "$path/$markerName" || $(tr -d '\r\n' <"$path/$markerName") != "$markerValue" ]] || [[ -L $path ]]; then jq -n --arg id "$id" '{resource_id:$id,state:"unknown",removed:false,retained:true,reason:"protected, unowned, or reparse path"}'; return; fi + parent=$(canon "$parent") + if [[ $(jq -r '.resource_type' <<<"$record") == git-worktree ]]; then + registered_worktree "$parent" "$path" || { jq -n --arg id "$id" '{resource_id:$id,state:"ambiguous",removed:false,retained:true,reason:"worktree is not registered with its parent repository"}'; return; } + if [[ $(jq -r '.allow_dirty' <<<"$record") != true ]]; then dirty=$(git -C "$path" status --porcelain 2>/dev/null || true); unmerged=$(git -C "$path" ls-files -u 2>/dev/null || true); if [[ -n $dirty ]]; then jq -n --arg id "$id" '{resource_id:$id,state:"dirty",removed:false,retained:true,reason:"worktree is dirty"}'; return; fi; if [[ -n $unmerged || -f "$path/.git/MERGE_HEAD" ]]; then jq -n --arg id "$id" '{resource_id:$id,state:"unmerged",removed:false,retained:true,reason:"worktree has an unmerged state"}'; return; fi; fi + git -C "$parent" worktree remove --force "$path" >/dev/null 2>&1 || { jq -n --arg id "$id" '{resource_id:$id,state:"retained",removed:false,retained:true,reason:"git worktree removal failed"}'; return; }; git -C "$parent" worktree prune >/dev/null 2>&1 || true + else [[ -d $path ]] || { jq -n --arg id "$id" '{resource_id:$id,state:"ambiguous",removed:false,retained:true,reason:"resource is not a directory"}'; return; }; [[ $(git -C "$path" rev-parse --show-toplevel 2>/dev/null || true) != "$path" ]] || { jq -n --arg id "$id" '{resource_id:$id,state:"ambiguous",removed:false,retained:true,reason:"resource is a git checkout"}'; return; }; find -P "$path" -type l -print -quit | grep -q . && { jq -n --arg id "$id" '{resource_id:$id,state:"ambiguous",removed:false,retained:true,reason:"resource contains a reparse or symlink"}'; return; }; rm -rf -- "$path"; fi + jq -n --arg id "$id" '{resource_id:$id,state:"removed",removed:true,retained:false,reason:null}' +} + +cmd_cleanup() { local ledger id result nextState reason; ledger=$(canon "$(required --ledger "$@")"); id=$(required --resource-id "$@"); init_ledger "$ledger"; jq --arg id "$id" '(.resources[]|select(.resource_id==$id)).cleanup_attempts += 1' "$ledger" | atomic_write "$ledger"; result=$(classify_cleanup "$ledger" "$id"); nextState=$(jq -r '.state' <<<"$result"); reason=$(jq -r '.reason // empty' <<<"$result"); jq --arg id "$id" --arg state "$nextState" --arg reason "$reason" '(.resources[]|select(.resource_id==$id)) |= (.state=$state|.last_error=(if $reason=="" then null else $reason end)|.updated_at=(now|strftime("%Y-%m-%dT%H:%M:%SZ"))) | .updated_at=(now|strftime("%Y-%m-%dT%H:%M:%SZ"))' "$ledger" | atomic_write "$ledger"; printf '%s\n' "$result"; } + +cmd_reconcile() { local ledger repo line path known id; ledger=$(canon "$(required --ledger "$@")"); init_ledger "$ledger"; local repos=(); while (($#)); do case "$1" in --source-repo) shift; (($#)) || die '--source-repo requires a path'; repos+=("$1");; --source-repo=*) repos+=("${1#*=}");; esac; shift; done; for repo in "${repos[@]}"; do repo=$(canon "$repo"); while IFS= read -r line; do [[ $line == worktree\ * ]] || continue; path=${line#worktree }; [[ $(canon "$path") == "$repo" ]] && continue; known=$(jq -e --arg p "$(canon "$path")" '.resources[]|select(.path==$p)' "$ledger" >/dev/null 2>&1; echo $?); if [[ $known -ne 0 ]]; then jq --arg path "$(canon "$path")" --arg repo "$repo" '.resources += [{resource_id:("unknown-worktree:" + (now|tostring)),assignment_id:"unknown",parent_id:$repo,parent_path:$repo,resource_type:"git-worktree",path:$path,process_identity:null,owner_marker:{name:"",value:""},state:"unknown",allow_dirty:false,created_at:(now|strftime("%Y-%m-%dT%H:%M:%SZ")),updated_at:(now|strftime("%Y-%m-%dT%H:%M:%SZ")),cleanup_attempts:0,last_error:"worktree was not present in the ownership ledger"}]' "$ledger" | atomic_write "$ledger"; fi; done < <(git -C "$repo" worktree list --porcelain 2>/dev/null); done; for id in $(jq -r '.resources[]|select(.state|IN("registered","active","failed","timed_out","cancelled","quota_handoff","cleanup_pending","completed"))|select(.resource_type=="worker-process")|.resource_id' "$ledger"); do cmd_cleanup --ledger "$ledger" --resource-id "$id"; done; for id in $(jq -r '.resources[]|select(.state|IN("registered","active","failed","timed_out","cancelled","quota_handoff","cleanup_pending","completed"))|select(.resource_type!="worker-process")|.resource_id' "$ledger"); do cmd_cleanup --ledger "$ledger" --resource-id "$id"; done; } + +need_jq; (($# > 0)) || { usage; exit 1; }; command=$1; shift; case "$command" in init) ledger=$(canon "$(required --ledger "$@")"); init_ledger "$ledger"; jq -n --arg l "$ledger" '{ledger:$l,state:"ready"}';; register) cmd_register "$@";; update) cmd_update "$@";; cleanup) cmd_cleanup "$@";; reconcile) cmd_reconcile "$@";; -h|--help) usage;; *) die "unrecognized command: $command";; esac diff --git a/scripts/run-agy-json.ps1 b/scripts/run-agy-json.ps1 index 8bca72f..ee0591f 100644 --- a/scripts/run-agy-json.ps1 +++ b/scripts/run-agy-json.ps1 @@ -7,7 +7,7 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version 3.0 function Show-Usage { - [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] --output FILE --error FILE '--' agy-arguments...") + [Console]::Error.WriteLine("Usage: run-agy-json.ps1 --role ROLE [--route default|quality-retry] --output FILE --error FILE [--ledger FILE --assignment-id ID --parent-id ID [--resource-id ID]] '--' agy-arguments...") [Console]::Error.WriteLine("In PowerShell command expressions, quote '--' because PowerShell consumes the bare delimiter before the helper receives it.") } @@ -20,11 +20,19 @@ $outputPath = "" $errorPath = "" $role = "" $route = "" +$ledgerPath = "" +$assignmentId = "" +$parentId = "" +$resourceId = "" $seenOutput = $false $seenError = $false $seenRole = $false $seenRoute = $false $seenDashDash = $false +$seenLedger = $false +$seenAssignment = $false +$seenParent = $false +$seenResource = $false $forwardedArgs = [System.Collections.Generic.List[string]]::new() $i = 0 @@ -122,6 +130,50 @@ while ($i -lt $args.Count) { Fail "--route requires a route name" } $seenRoute = $true + } elseif ($arg -eq '--ledger') { + if ($seenLedger) { Fail "duplicate --ledger option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--ledger requires a path" } + $ledgerPath = [string]$args[$i] + $seenLedger = $true + } elseif ($arg.StartsWith('--ledger=')) { + if ($seenLedger) { Fail "duplicate --ledger option" } + $ledgerPath = $arg.Substring(9) + if ([string]::IsNullOrWhiteSpace($ledgerPath)) { Show-Usage; Fail "--ledger requires a path" } + $seenLedger = $true + } elseif ($arg -eq '--assignment-id') { + if ($seenAssignment) { Fail "duplicate --assignment-id option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--assignment-id requires a value" } + $assignmentId = [string]$args[$i] + $seenAssignment = $true + } elseif ($arg.StartsWith('--assignment-id=')) { + if ($seenAssignment) { Fail "duplicate --assignment-id option" } + $assignmentId = $arg.Substring(16) + if ([string]::IsNullOrWhiteSpace($assignmentId)) { Show-Usage; Fail "--assignment-id requires a value" } + $seenAssignment = $true + } elseif ($arg -eq '--parent-id') { + if ($seenParent) { Fail "duplicate --parent-id option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--parent-id requires a value" } + $parentId = [string]$args[$i] + $seenParent = $true + } elseif ($arg.StartsWith('--parent-id=')) { + if ($seenParent) { Fail "duplicate --parent-id option" } + $parentId = $arg.Substring(12) + if ([string]::IsNullOrWhiteSpace($parentId)) { Show-Usage; Fail "--parent-id requires a value" } + $seenParent = $true + } elseif ($arg -eq '--resource-id') { + if ($seenResource) { Fail "duplicate --resource-id option" } + $i++ + if ($i -ge $args.Count) { Show-Usage; Fail "--resource-id requires a value" } + $resourceId = [string]$args[$i] + $seenResource = $true + } elseif ($arg.StartsWith('--resource-id=')) { + if ($seenResource) { Fail "duplicate --resource-id option" } + $resourceId = $arg.Substring(14) + if ([string]::IsNullOrWhiteSpace($resourceId)) { Show-Usage; Fail "--resource-id requires a value" } + $seenResource = $true } else { Show-Usage Fail "unknown launcher option: $arg" @@ -146,6 +198,13 @@ if (-not $seenRole -or [string]::IsNullOrWhiteSpace($role)) { Fail "--role is required; specify a role and remove any caller --model flag" } +if ($seenLedger -or $seenAssignment -or $seenParent -or $seenResource) { + if (-not $seenLedger -or [string]::IsNullOrWhiteSpace($ledgerPath)) { Fail "--ledger is required when resource ledger registration is enabled" } + if (-not $seenAssignment -or [string]::IsNullOrWhiteSpace($assignmentId)) { Fail "--assignment-id is required when resource ledger registration is enabled" } + if (-not $seenParent -or [string]::IsNullOrWhiteSpace($parentId)) { Fail "--parent-id is required when resource ledger registration is enabled" } + if ([string]::IsNullOrWhiteSpace($resourceId)) { $resourceId = "worker:$assignmentId" } +} + $knownRoles = @('scout', 'gate-author', 'implementer', 'reviewer', 'researcher', 'synthesizer', 'auditor') if ($knownRoles -notcontains $role) { Fail "unknown role: '$role'; must be one of $($knownRoles -join ', ')" @@ -416,6 +475,8 @@ $errFs = $null $proc = $null $launcherSuccess = $false $workerExitCode = 1 +$ledgerRegistered = $false +$ledgerScript = Join-Path $PSScriptRoot 'resource-ledger.ps1' try { try { @@ -457,6 +518,16 @@ try { Fail "failed to start agy: $($_.Exception.Message)" 1 } + if ($seenLedger) { + $startTime = $null + try { $startTime = $proc.StartTime.ToUniversalTime().ToString('o') } catch { } + $ledgerArgs = @('register', '--ledger', $ledgerPath, '--assignment-id', $assignmentId, '--parent-id', $parentId, '--resource-type', 'worker-process', '--process-id', [string]$proc.Id, '--owner-marker', 'agy-worker=agy-worker-v1', '--resource-id', $resourceId, '--state', 'active') + if ($null -ne $startTime) { $ledgerArgs += @('--process-start-time', $startTime) } + & pwsh -NoProfile -NonInteractive -File $ledgerScript @ledgerArgs | Out-Null + if ($LASTEXITCODE -ne 0) { throw "failed to register worker process in resource ledger" } + $ledgerRegistered = $true + } + try { if ($env:FAKE_LAUNCHER_FAIL_POST_START -or $env:OFFLOAD_TEST_FAIL_POST_START) { if ($env:FAKE_AGY_STARTED_MARKER) { @@ -490,6 +561,14 @@ try { # Best effort kill } } + if ($ledgerRegistered) { + $ledgerState = if ($launcherSuccess -and $workerExitCode -eq 0) { 'completed' } elseif ($launcherSuccess -and $workerExitCode -ne 0) { 'failed' } else { 'failed' } + try { + & pwsh -NoProfile -NonInteractive -File $ledgerScript update --ledger $ledgerPath --resource-id $resourceId --state $ledgerState --error (if ($ledgerState -eq 'failed') { 'worker or launcher failed' } else { '' }) | Out-Null + } catch { + # The worker result remains authoritative; reconciliation can repair a failed ledger update. + } + } if ($null -ne $outFs) { try { $outFs.Dispose() diff --git a/scripts/run-agy-json.sh b/scripts/run-agy-json.sh index d9ad2b4..5c33145 100755 --- a/scripts/run-agy-json.sh +++ b/scripts/run-agy-json.sh @@ -2,7 +2,7 @@ set -euo pipefail usage() { - printf 'Usage: %s --role ROLE [--route default|quality-retry] --output FILE --error FILE -- agy-arguments...\n' "$0" >&2 + printf 'Usage: %s --role ROLE [--route default|quality-retry] --output FILE --error FILE [--ledger FILE --assignment-id ID --parent-id ID [--resource-id ID]] -- agy-arguments...\n' "$0" >&2 } fail() { @@ -14,11 +14,19 @@ output_path='' error_path='' role='' route='' +ledger_path='' +assignment_id='' +parent_id='' +resource_id='' seen_output=false seen_error=false seen_role=false seen_route=false +seen_ledger=false +seen_assignment=false +seen_parent=false +seen_resource=false seen_delimiter=false worker_args=() @@ -80,6 +88,62 @@ while [ "$#" -gt 0 ]; do seen_route=true shift ;; + --ledger) + $seen_ledger && fail 'duplicate --ledger option' + [ "$#" -ge 2 ] || { usage; fail '--ledger requires a path'; } + ledger_path="$2" + seen_ledger=true + shift 2 + ;; + --ledger=*) + $seen_ledger && fail 'duplicate --ledger option' + ledger_path="${1#--ledger=}" + [ -n "$ledger_path" ] || { usage; fail '--ledger requires a path'; } + seen_ledger=true + shift + ;; + --assignment-id) + $seen_assignment && fail 'duplicate --assignment-id option' + [ "$#" -ge 2 ] || { usage; fail '--assignment-id requires a value'; } + assignment_id="$2" + seen_assignment=true + shift 2 + ;; + --assignment-id=*) + $seen_assignment && fail 'duplicate --assignment-id option' + assignment_id="${1#--assignment-id=}" + [ -n "$assignment_id" ] || { usage; fail '--assignment-id requires a value'; } + seen_assignment=true + shift + ;; + --parent-id) + $seen_parent && fail 'duplicate --parent-id option' + [ "$#" -ge 2 ] || { usage; fail '--parent-id requires a value'; } + parent_id="$2" + seen_parent=true + shift 2 + ;; + --parent-id=*) + $seen_parent && fail 'duplicate --parent-id option' + parent_id="${1#--parent-id=}" + [ -n "$parent_id" ] || { usage; fail '--parent-id requires a value'; } + seen_parent=true + shift + ;; + --resource-id) + $seen_resource && fail 'duplicate --resource-id option' + [ "$#" -ge 2 ] || { usage; fail '--resource-id requires a value'; } + resource_id="$2" + seen_resource=true + shift 2 + ;; + --resource-id=*) + $seen_resource && fail 'duplicate --resource-id option' + resource_id="${1#--resource-id=}" + [ -n "$resource_id" ] || { usage; fail '--resource-id requires a value'; } + seen_resource=true + shift + ;; --) seen_delimiter=true shift @@ -113,6 +177,15 @@ if ! $seen_role || [ -z "$role" ]; then fail '--role is required; specify a role and remove any caller --model flag' fi +if $seen_ledger || $seen_assignment || $seen_parent || $seen_resource; then + $seen_ledger && [ -n "$ledger_path" ] || fail '--ledger is required when resource ledger registration is enabled' + $seen_assignment && [ -n "$assignment_id" ] || fail '--assignment-id is required when resource ledger registration is enabled' + $seen_parent && [ -n "$parent_id" ] || fail '--parent-id is required when resource ledger registration is enabled' + if ! $seen_resource; then + resource_id="worker:$assignment_id" + fi +fi + case "$role" in scout|gate-author|implementer|reviewer|researcher|synthesizer|auditor) ;; *) @@ -161,6 +234,7 @@ done script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" repo_root="$(cd "$script_dir/.." && pwd)" policy_file="$repo_root/model-policy.json" +resource_ledger="$script_dir/resource-ledger.sh" if [ ! -f "$policy_file" ]; then fail "model policy file not found at: $policy_file" @@ -273,9 +347,65 @@ fi mkdir -p "$(dirname "$output_path")" "$(dirname "$error_path")" +worker_pid='' +worker_done=false +ledger_registered=false + +update_ledger() { + local state="$1" + local error_message="${2:-}" + if $ledger_registered; then + if [ -n "$error_message" ]; then + "$resource_ledger" update --ledger "$ledger_path" --resource-id "$resource_id" --state "$state" --error "$error_message" >/dev/null 2>&1 || true + else + "$resource_ledger" update --ledger "$ledger_path" --resource-id "$resource_id" --state "$state" >/dev/null 2>&1 || true + fi + ledger_registered=false + fi +} + +cleanup_worker() { + if [ -n "$worker_pid" ] && ! $worker_done && kill -0 "$worker_pid" 2>/dev/null; then + kill "$worker_pid" 2>/dev/null || true + wait "$worker_pid" 2>/dev/null || true + fi + if $ledger_registered; then + update_ledger failed 'worker or launcher was interrupted' + fi +} +trap cleanup_worker EXIT + +set +e +"$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" & +worker_pid=$! +set -e + +if $seen_ledger; then + process_start='' + if process_start=$(ps -o lstart= -p "$worker_pid" 2>/dev/null); then + process_start="$(printf '%s' "$process_start" | sed 's/^ *//;s/ *$//')" + else + process_start='' + fi + register_args=(register --ledger "$ledger_path" --assignment-id "$assignment_id" --parent-id "$parent_id" --resource-type worker-process --process-id "$worker_pid" --owner-marker agy-worker=agy-worker-v1 --resource-id "$resource_id" --state active) + [ -n "$process_start" ] && register_args+=(--process-start-time "$process_start") + if ! "$resource_ledger" "${register_args[@]}" >/dev/null; then + cleanup_worker + fail 'failed to register worker process in resource ledger' 1 + fi + ledger_registered=true +fi + set +e -"$agy_bin" --model "$resolved_model" "${worker_args[@]}" >"$output_path" 2>"$error_path" +wait "$worker_pid" worker_exit=$? set -e +worker_done=true + +if [ "$worker_exit" -eq 0 ]; then + update_ledger completed +else + update_ledger failed 'worker or launcher failed' +fi exit "$worker_exit" diff --git a/tests/test_resource_ledger.ps1 b/tests/test_resource_ledger.ps1 new file mode 100644 index 0000000..7f86c77 --- /dev/null +++ b/tests/test_resource_ledger.ps1 @@ -0,0 +1,107 @@ +#!/usr/bin/env pwsh +# tests/test_resource_ledger.ps1 +# Focused acceptance tests for the durable resource ledger and reconciliation. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +$script:TotalTests = 0 +function Pass([string]$name) { $script:TotalTests++; [Console]::Out.WriteLine("ok - $name") } +function Fail([string]$name, [string]$reason = '') { $script:TotalTests++; [Console]::Error.WriteLine("FAIL: $name - $reason"); exit 1 } +function Assert-True([bool]$value, [string]$name, [string]$reason = '') { if ($value) { Pass $name } else { $failure = if ($reason) { $reason } else { 'condition was false' }; Fail $name $failure } } +function Assert-False([bool]$value, [string]$name, [string]$reason = '') { $failure = if ($reason) { $reason } else { 'condition was true' }; Assert-True (-not $value) $name $failure } +function Assert-Equal($actual, $expected, [string]$name) { if ($actual -eq $expected) { Pass $name } else { Fail $name "expected '$expected', got '$actual'" } } +function Assert-NotEqual($actual, $expected, [string]$name) { if ($actual -ne $expected) { Pass $name } else { Fail $name "expected a value other than '$expected'" } } + +$ledgerScript = Join-Path (Split-Path -Parent $PSScriptRoot) 'scripts/resource-ledger.ps1' +$pwsh = (Get-Command pwsh).Source +$tmpRoot = Join-Path ([IO.Path]::GetTempPath()) ('offload-test-ledger-ps-' + [Guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $tmpRoot | Out-Null + +function Invoke-Ledger([string[]]$Arguments) { + $psi = [Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $pwsh; $psi.WorkingDirectory = $tmpRoot; $psi.UseShellExecute = $false; $psi.CreateNoWindow = $true + $psi.RedirectStandardOutput = $true; $psi.RedirectStandardError = $true + $psi.ArgumentList.Add('-NoProfile'); $psi.ArgumentList.Add('-NonInteractive'); $psi.ArgumentList.Add('-File'); $psi.ArgumentList.Add($ledgerScript) + foreach ($argument in $Arguments) { $psi.ArgumentList.Add($argument) } + $process = [Diagnostics.Process]::Start($psi) + $stdout = $process.StandardOutput.ReadToEnd(); $stderr = $process.StandardError.ReadToEnd(); $process.WaitForExit() + [PSCustomObject]@{ ExitCode = $process.ExitCode; Stdout = $stdout; Stderr = $stderr } +} + +function Init-Repo([string]$path) { + New-Item -ItemType Directory -Path $path | Out-Null + & git -C $path init -q; & git -C $path config user.name Test; & git -C $path config user.email test@example.com + Set-Content -LiteralPath (Join-Path $path 'tracked.txt') -Value 'base' + & git -C $path add .; & git -C $path commit -q -m init +} + +try { + $ledger = Join-Path $tmpRoot 'ledger.json' + $resource = Join-Path $tmpRoot 'owned' + New-Item -ItemType Directory -Path $resource | Out-Null + Set-Content -LiteralPath (Join-Path $resource '.owner') -Value 'owned-v1' -NoNewline + + $result = Invoke-Ledger @('init', '--ledger', $ledger) + Assert-Equal $result.ExitCode 0 'ledger initializes' + $result = Invoke-Ledger @('register', '--ledger', $ledger, '--assignment-id', 'a1', '--parent-id', 'orchestrator', '--resource-type', 'directory', '--path', $resource, '--owner-marker', '.owner=owned-v1', '--resource-id', 'dir:1', '--state', 'active') + Assert-Equal $result.ExitCode 0 'resource registers before cleanup' + $record = (Get-Content -LiteralPath $ledger -Raw | ConvertFrom-Json).resources[0] + Assert-Equal $record.assignment_id 'a1' 'record stores assignment identity' + Assert-Equal $record.parent_id 'orchestrator' 'record stores parent identity' + Assert-Equal $record.resource_type 'directory' 'record stores resource type' + Assert-True ([IO.Path]::IsPathFullyQualified($record.path)) 'record stores absolute path' + Assert-Equal $record.owner_marker.name '.owner' 'record stores owner marker' + Assert-True (-not [string]::IsNullOrWhiteSpace($record.created_at)) 'record stores creation timestamp' + + $result = Invoke-Ledger @('cleanup', '--ledger', $ledger, '--resource-id', 'dir:1') + Assert-Equal $result.ExitCode 0 'owned directory cleanup succeeds' + Assert-False (Test-Path -LiteralPath $resource) 'owned directory is removed' + $result = Invoke-Ledger @('cleanup', '--ledger', $ledger, '--resource-id', 'dir:1') + $repeat = $result.Stdout | ConvertFrom-Json + Assert-Equal $repeat.state 'removed' 'repeat cleanup is idempotent' + + $retained = Join-Path $tmpRoot 'retained' + New-Item -ItemType Directory -Path $retained | Out-Null + Set-Content -LiteralPath (Join-Path $retained '.owner') -Value 'different' -NoNewline + Invoke-Ledger @('register', '--ledger', $ledger, '--assignment-id', 'a2', '--parent-id', 'orchestrator', '--resource-type', 'directory', '--path', $retained, '--owner-marker', '.owner=owned-v1', '--resource-id', 'dir:2', '--state', 'active') | Out-Null + $result = Invoke-Ledger @('cleanup', '--ledger', $ledger, '--resource-id', 'dir:2') + $classification = $result.Stdout | ConvertFrom-Json + Assert-True ($classification.retained -eq $true) 'unowned directory is retained' + Assert-Equal $classification.state 'unknown' 'unowned directory is classified unknown' + Assert-True (Test-Path -LiteralPath $retained) 'unowned evidence remains on disk' + + $process = Start-Process -FilePath $pwsh -ArgumentList @('-NoProfile', '-NonInteractive', '-Command', 'Start-Sleep -Seconds 30') -PassThru -WindowStyle Hidden + try { + $start = $process.StartTime.ToUniversalTime().ToString('o') + Invoke-Ledger @('register', '--ledger', $ledger, '--assignment-id', 'a3', '--parent-id', 'orchestrator', '--resource-type', 'worker-process', '--process-id', "$($process.Id)", '--process-start-time', $start, '--owner-marker', 'agy-worker=agy-worker-v1', '--resource-id', 'worker:3', '--state', 'active') | Out-Null + $processRecord = @((Get-Content -LiteralPath $ledger -Raw | ConvertFrom-Json).resources | Where-Object { $_.resource_id -eq 'worker:3' })[0] + Assert-True (-not [string]::IsNullOrWhiteSpace($processRecord.process_identity.start_time)) 'process record stores process start timestamp' + $result = Invoke-Ledger @('cleanup', '--ledger', $ledger, '--resource-id', 'worker:3') + $classification = $result.Stdout | ConvertFrom-Json + Assert-True ($classification.removed -eq $true) 'owned worker process cleanup succeeds' + $null = $process.WaitForExit(10000) + $process.Refresh() + Assert-True $process.HasExited 'worker process is terminated before cleanup completes' + } finally { if (-not $process.HasExited) { $process.Kill(); $process.WaitForExit() } } + + $repo = Join-Path $tmpRoot 'repo'; Init-Repo $repo + $baseline = (git -C $repo rev-parse HEAD).Trim() + $unknownWorktree = Join-Path $tmpRoot 'unknown-worktree' + & git -C $repo worktree add --detach $unknownWorktree $baseline | Out-Null + try { + $result = Invoke-Ledger @('reconcile', '--ledger', $ledger, '--source-repo', $repo) + Assert-Equal $result.ExitCode 0 'reconciliation completes' + $unknown = @((Get-Content -LiteralPath $ledger -Raw | ConvertFrom-Json).resources | Where-Object { $_.assignment_id -eq 'unknown' }) + Assert-Equal $unknown.Count 1 'reconciliation records unknown worktree' + Assert-Equal $unknown[0].state 'unknown' 'unknown worktree is retained for review' + Assert-True (Test-Path -LiteralPath $unknownWorktree) 'unknown worktree remains on disk' + } finally { & git -C $repo worktree remove --force $unknownWorktree | Out-Null; & git -C $repo worktree prune | Out-Null } + + $badLedger = Join-Path $resource 'ledger.json' + $result = Invoke-Ledger @('register', '--ledger', $badLedger, '--assignment-id', 'a4', '--parent-id', 'orchestrator', '--resource-type', 'directory', '--path', $resource, '--owner-marker', '.owner=owned-v1') + Assert-NotEqual $result.ExitCode 0 'ledger inside resource is rejected' + [Console]::Out.WriteLine("all resource ledger powershell tests passed ($($script:TotalTests) tests)") +} finally { + if (Test-Path -LiteralPath $tmpRoot) { Remove-Item -LiteralPath $tmpRoot -Recurse -Force -ErrorAction SilentlyContinue } +} diff --git a/tests/test_resource_ledger.sh b/tests/test_resource_ledger.sh new file mode 100644 index 0000000..2698b6b --- /dev/null +++ b/tests/test_resource_ledger.sh @@ -0,0 +1,103 @@ +#!/usr/bin/env bash +# Acceptance tests for the orchestrator-owned resource ledger. + +set -euo pipefail + +ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +LEDGER="$ROOT/scripts/resource-ledger.sh" + +fail() { + printf 'FAIL: %s\n' "$1" >&2 + exit 1 +} + +pass() { + printf 'ok - %s\n' "$1" +} + +[ -f "$LEDGER" ] || fail "resource ledger does not exist at $LEDGER" +bash -n "$LEDGER" || fail 'resource ledger does not parse' +command -v jq >/dev/null 2>&1 || fail 'jq is required for resource ledger tests' + +TMP_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/offload-test-ledger.XXXXXX") +TMP_ROOT=$(cd "$TMP_ROOT" && pwd -P) +trap 'rm -rf "$TMP_ROOT"' EXIT + +LEDGER_PATH="$TMP_ROOT/ledger.json" +RESOURCE="$TMP_ROOT/resource" +mkdir -p "$RESOURCE" +printf 'offload-resource-v1\n' > "$RESOURCE/.owner" +RESOURCE_CANON=$(cygpath -m "$RESOURCE") + +"$LEDGER" init --ledger "$LEDGER_PATH" >/dev/null +pass 'ledger initializes' + +"$LEDGER" register \ + --ledger "$LEDGER_PATH" \ + --assignment-id assignment-shell \ + --parent-id parent-shell \ + --resource-type research-workspace \ + --path "$RESOURCE" \ + --owner-marker '.owner=offload-resource-v1' \ + --resource-id resource-shell \ + --state active >/dev/null + +record=$(jq -c '.resources[] | select(.resource_id == "resource-shell")' "$LEDGER_PATH") +[ "$(jq -r '.assignment_id' <<<"$record")" = 'assignment-shell' ] || fail 'assignment identity not stored' +[ "$(jq -r '.parent_id' <<<"$record")" = 'parent-shell' ] || fail 'parent identity not stored' +[ "$(jq -r '.resource_type' <<<"$record")" = 'research-workspace' ] || fail 'resource type not stored' +[ "$(jq -r '.path' <<<"$record")" = "$RESOURCE_CANON" ] || fail 'absolute resource path not stored' +[ "$(jq -r '.owner_marker.name + "=" + .owner_marker.value' <<<"$record")" = '.owner=offload-resource-v1' ] || fail 'owner marker not stored' +pass 'resource record stores ownership fields' + +"$LEDGER" cleanup --ledger "$LEDGER_PATH" --resource-id resource-shell >/dev/null +[ ! -e "$RESOURCE" ] || fail 'owned resource was not removed' +pass 'owned resource cleanup succeeds' + +"$LEDGER" cleanup --ledger "$LEDGER_PATH" --resource-id resource-shell >/dev/null +[ "$(jq -r '.resources[0].state' "$LEDGER_PATH")" = 'removed' ] || fail 'repeat cleanup changed terminal state' +pass 'repeat cleanup is idempotent' + +UNOWNED="$TMP_ROOT/unowned" +mkdir -p "$UNOWNED" +printf 'different-owner\n' > "$UNOWNED/.owner" +"$LEDGER" register --ledger "$LEDGER_PATH" --assignment-id assignment-unowned --parent-id parent-shell --resource-type research-workspace --path "$UNOWNED" --owner-marker '.owner=expected-owner' --resource-id resource-unowned --state active >/dev/null +"$LEDGER" cleanup --ledger "$LEDGER_PATH" --resource-id resource-unowned >/dev/null +[ -d "$UNOWNED" ] || fail 'unowned evidence was removed' +[ "$(jq -r '.resources[] | select(.resource_id == "resource-unowned") | .state' "$LEDGER_PATH")" = 'unknown' ] || fail 'unowned resource was not classified unknown' +pass 'unowned resource is retained as unknown' + +sleep 30 & +worker_pid=$! +"$LEDGER" register --ledger "$LEDGER_PATH" --assignment-id assignment-worker --parent-id parent-shell --resource-type worker-process --process-id "$worker_pid" --owner-marker 'agy-worker=agy-worker-v1' --resource-id worker-shell --state active >/dev/null +"$LEDGER" cleanup --ledger "$LEDGER_PATH" --resource-id worker-shell >/dev/null +if kill -0 "$worker_pid" 2>/dev/null; then + kill "$worker_pid" 2>/dev/null || true + wait "$worker_pid" 2>/dev/null || true + fail 'owned worker process was not terminated' +fi +pass 'owned worker process is terminated before cleanup completes' + +GIT_REPO="$TMP_ROOT/repo" +mkdir -p "$GIT_REPO" +git -C "$GIT_REPO" init -q +git -C "$GIT_REPO" config user.name 'Ledger Test' +git -C "$GIT_REPO" config user.email 'ledger@example.com' +printf 'base\n' > "$GIT_REPO/base.txt" +git -C "$GIT_REPO" add base.txt +git -C "$GIT_REPO" commit -q -m base +UNKNOWN_WT="$TMP_ROOT/unknown-worktree" +git -C "$GIT_REPO" worktree add --detach -q "$UNKNOWN_WT" +UNKNOWN_WT_CANON=$(cygpath -m "$UNKNOWN_WT") +"$LEDGER" reconcile --ledger "$LEDGER_PATH" --source-repo "$GIT_REPO" >/dev/null +[ "$(jq -r --arg path "$UNKNOWN_WT_CANON" '.resources[] | select(.path == $path) | .state' "$LEDGER_PATH")" = 'unknown' ] || fail 'unknown worktree was not recorded' +[ -d "$UNKNOWN_WT" ] || fail 'unknown worktree was removed' +git -C "$GIT_REPO" worktree remove --force "$UNKNOWN_WT" >/dev/null +pass 'unknown worktree is retained for review' + +if "$LEDGER" register --ledger "$TMP_ROOT/inside.json" --assignment-id a --parent-id p --resource-type research-workspace --path "$TMP_ROOT" --owner-marker '.owner=value' >/dev/null 2>&1; then + fail 'ledger inside resource path was accepted' +fi +pass 'ledger inside resource path is rejected' + +printf 'all resource ledger shell tests passed (8 tests)\n' From 77e0f2e57e48b0ca2f758874e19d9891975daa0e Mon Sep 17 00:00:00 2001 From: dreiiiiiiiiiii Date: Fri, 4 Sep 2026 18:55:53 +0800 Subject: [PATCH 08/11] feat: select worker models through adapters --- AGENTS.md | 18 +- CONTEXT.md | 4 +- README.md | 30 +- SKILL.md | 60 +- docs/adapter-contract.md | 47 + ...untime-model-selection-through-adapters.md | 15 + model-policy.json | 39 +- modes/execution.md | 16 +- modes/repo-research.md | 6 +- modes/web-research.md | 36 +- scripts/agy-adapter.ps1 | 165 ++ scripts/agy-adapter.sh | 119 ++ scripts/cleanup-research-workspace.ps1 | 18 +- scripts/cleanup-research-workspace.sh | 8 +- scripts/collect-provenance.ps1 | 27 +- scripts/collect-provenance.sh | 26 +- scripts/probe-agy-compatibility.ps1 | 28 +- scripts/probe-agy-compatibility.sh | 42 +- scripts/run-agy-json.ps1 | 708 +++---- scripts/run-agy-json.sh | 373 ++-- tests/fixtures/fake-worker-adapter.ps1 | 54 + tests/fixtures/fake-worker-adapter.sh | 46 + tests/fixtures/routing-worker.json | 24 +- tests/test_agy_helpers.sh | 7 + tests/test_model_routing.ps1 | 1802 +---------------- tests/test_model_routing.sh | 823 +------- tests/test_research_helpers.ps1 | 34 +- tests/test_research_modes.sh | 6 + tests/test_review_probe_contract.ps1 | 8 +- tests/test_routing_provenance.ps1 | 19 +- tests/test_verification_hardening_docs.ps1 | 18 +- .../test_verification_hardening_launcher.ps1 | 50 +- tests/test_verification_hardening_routing.ps1 | 2 +- tests/test_workflow_static.ps1 | 32 +- 34 files changed, 1438 insertions(+), 3272 deletions(-) create mode 100644 docs/adapter-contract.md create mode 100644 docs/adr/0007-runtime-model-selection-through-adapters.md create mode 100644 scripts/agy-adapter.ps1 create mode 100755 scripts/agy-adapter.sh create mode 100644 tests/fixtures/fake-worker-adapter.ps1 create mode 100755 tests/fixtures/fake-worker-adapter.sh mode change 100644 => 100755 tests/test_model_routing.sh diff --git a/AGENTS.md b/AGENTS.md index e997b11..f3c27cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy ## Key decisions and architecture -- **Orchestrator-agnostic, worker-fixed**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. `agy` is reserved for the worker role. The self-guard stops an `agy` process that loads this skill. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. +- **Orchestrator-agnostic, adapter-backed workers**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Worker execution runs through the adapter contract, with `agy` as the reference adapter. The self-guard stops a dispatched worker that loads this skill. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. - **Modular mode architecture**: Root `SKILL.md` is a lightweight router under 500 lines owning shared preconditions, mode inference, explicit overrides, mode loading, and the shared report contract. Workflows are isolated into dedicated mode documents: `modes/execution.md` (code and file mutations), `modes/repo-research.md` (bounded local investigations and audits), and `modes/web-research.md` (online research, synthesis, and citation auditing). - **Routing hierarchy**: Once invoked, the router resolves mode in this order: 1. Honor explicit mode override. @@ -15,21 +15,15 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy 6. Route mixed local and external questions to `web-research` with a scoped snapshot. Single factual lookups stay local with the orchestrator. - **Shell-native helper families with platform parity**: Offload maintains two shell-native helper families: Bash 3.2+ for POSIX shells and PowerShell 7+ for PowerShell orchestrators. Orchestrators select the helper family for their current shell. Native workflows on Windows require only PowerShell 7+, Git, and `agy` without WSL, Git Bash, Python, or `jq`. Platform parity ensures equivalent workflow behavior, workspace isolation, provenance artifacts, and safety checks across supported shells. -- **Worker roles, models, and modes**: - - Worker routing is governed centrally by `model-policy.json` targeting the Gemini 3.8 Flash baseline: - - `scout` (`gemini-3.8-flash-low`, `--mode plan`): Discovers file paths for provisional tasks. - - `gate-author` (`gemini-3.8-flash-high`, `accept-edits`): Generates automated test files from acceptance criteria. - - `implementer` (`gemini-3.8-flash-high`, `accept-edits`): Modifies owned code files. - - `reviewer` (`gemini-3.8-flash-high`, `--mode plan`): Evaluates recorded review artifacts adversarially against criteria. - - `researcher` (`gemini-3.8-flash-high`, `--mode plan`): Collects structured findings for bounded questions within assigned scopes. - - `synthesizer` and `auditor` (`gemini-3.8-flash-high`, `--mode plan`): Synthesizes claim ledgers and audits citation veracity for web research. - - A historical live smoke comparison against Gemini 3.7 retained Flash for every role because the proposed Pro split did not complete its mandatory synthesis stage. +- **Worker roles, preferences, and modes**: + - Worker routing is governed centrally by `model-policy.json` and a vendor adapter. The policy stores each role's internal preference, independent effort, and required capabilities. The adapter provides the live catalog and translates the selected model into worker arguments. + - Selection is deterministic after filtering for availability, quota, effort, capabilities, and static security constraints. Family hints are descriptive only. - **Model routing policy and recovery accounting**: - Preflight model availability check against the resolved `agy` installation before first dispatch. - Launchers take `--role ` and optional `--route default|quality-retry`, resolving models dynamically and rejecting caller `--model` or `--effort` arguments. - Stable assignment identity across attempts with a strict ceiling of at most one retry (maximum two attempts per worker). - - Operational failures (crashes, timeouts, unparsable output) trigger at most one same-model retry (`--route default`). Quality failures (gate failures, scope violations, audit rejections) may use `--route quality-retry` only when an evidence-backed escalation target is configured in policy. - - Explicit Gemini quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers. + - Operational failures (crashes, timeouts, unparsable output) trigger at most one retry of the pinned selection (`--route default`). Quality failures (gate failures, scope violations, audit rejections) retry the pinned selection or require an explicit fallback or handoff when the pin is unavailable. + - Explicit quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers. - The orchestrator records all attempts and verification verdicts in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt records in `provenance.json`. - **Corrected worker guarantees**: `--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. `--add-dir` grants access without confining writes. Security and containment rely on filesystem isolation (disposable workspaces with scoped file snapshots for research) and mechanical verification (clean git working trees, execution scope checks, frozen path diffs, and test gates for execution). - **Verification over claims**: Worker JSON status (`SUCCESS`/`ERROR`) is not trusted alone. Implementers are verified via mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen paths, and gate commands. Reviewers are verified against the recorded artifact digest and verbatim quote matching. Research findings are verified against the live repository with read-only orchestrator commands after scope validation, with direct checks on high-priority claims and sampling on lower-priority claims. diff --git a/CONTEXT.md b/CONTEXT.md index ac2a59d..161843c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -37,11 +37,11 @@ The host-independent rule that defines when an orchestrator offers offloading, h _Avoid_: Hook, Claude hook **Model routing**: -The policy that selects a Gemini model and reasoning effort for an offload worker assignment. It uses role defaults and explicit escalation rules, prioritizing verified task success, then elapsed time and quota use. +The policy and adapter process that selects an available model and independent reasoning effort for an offload worker assignment. It uses a role preference, task capabilities, live availability, static security rules, and quota state. _Avoid_: Mode routing, unrestricted model selection **Role default**: -The model and reasoning effort assigned to an offload role unless a documented escalation rule applies. +The internal preference, reasoning effort, and required capabilities assigned to an offload role. The adapter resolves those requirements to a current model. _Avoid_: Best model, permanent model assignment **Model policy**: diff --git a/README.md b/README.md index 2436edb..55df7a0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # offload -`offload` is an agent-agnostic skill that delegates plan execution and research tasks to headless `agy` workers (the Antigravity CLI, running Gemini models). +`offload` is an agent-agnostic skill that delegates plan execution and research tasks to headless workers through a vendor adapter. The reference adapter launches `agy`. Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Code, Codex CLI, or any agent that can read instructions and run shell commands. `agy` is the worker, not the orchestrator. The orchestrator never accepts worker claims at face value. It verifies work mechanically through test gates, execution scope checks, verbatim quote matching, independent citation auditing, and direct repository checks. @@ -75,17 +75,17 @@ Single factual lookups stay local with the orchestrator and are not offloaded. ## Worker roles -| Role | Mode | Default model | Job | +| Role | Mode | Preference | Job | |---|---|---|---| -| scout | Execution | `gemini-3.8-flash-low` | Discovers repository-relative file paths touched by provisional tasks. | -| gate-author | Execution | `gemini-3.8-flash-high` | Authors executable test files from acceptance criteria. | -| implementer | Execution | `gemini-3.8-flash-high` | Modifies owned code files to satisfy gates. | -| reviewer | Execution | `gemini-3.8-flash-high` | Evaluates diffs adversarially against criteria for diff-gated tasks. | -| researcher | Research | `gemini-3.8-flash-high` | Collects structured findings for assigned evidence angles or bounded local scopes. | -| synthesizer | Web research | `gemini-3.8-flash-high` | Builds claim ledgers, resolves conflicts, and drafts answers. | -| auditor | Web research | `gemini-3.8-flash-high` | Independently verifies citation URLs and claims against live sources. | +| scout | Execution | fast | Discovers repository-relative file paths touched by provisional tasks. | +| gate-author | Execution | balanced | Authors executable test files from acceptance criteria. | +| implementer | Execution | balanced | Modifies owned code files to satisfy gates. | +| reviewer | Execution | deep | Evaluates diffs adversarially against criteria for diff-gated tasks. | +| researcher | Research | balanced | Collects structured findings for assigned evidence angles or bounded local scopes. | +| synthesizer | Web research | deep | Builds claim ledgers, resolves conflicts, and drafts answers. | +| auditor | Web research | deep | Independently verifies citation URLs and claims against live sources. | -Worker routing is governed by repository-root `model-policy.json`. Launchers accept `--role ` (and optional `--route default|quality-retry`) and resolve models dynamically. Callers must not supply `--model` or `--effort` flags. +Worker routing is governed by repository-root `model-policy.json` and [`docs/adapter-contract.md`](docs/adapter-contract.md). Launchers accept `--role ` and select a current eligible catalog entry. Callers must not supply `--model` or `--effort` flags. A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. The recorded comparison is in [`tests/live-smoke-comparison.md`](tests/live-smoke-comparison.md). @@ -183,8 +183,8 @@ The script copies only declared paths into `/repo/` and creates the ` Follow the shared recovery rules in `SKILL.md`: - **Stable worker IDs and retry ceiling.** Each assignment retains a stable identifier across attempts. Attempt 1 is initial dispatch; attempt 2 is the only permitted retry (maximum two attempts per task). -- **Quality versus operational failures.** Failing a machine gate, scope check, or citation audit is a quality failure; operational failures include crashes, timeouts (20m), and unparsable output. Operational failures retry with `--route default` (no model escalation). Quality failures retry with `--route quality-retry` only when an evidence-backed target is configured in `model-policy.json`. -- **Immediate quota handoff.** If Gemini quota is exhausted, stop dispatching immediately and hand all unfinished work back to the calling orchestrator while preserving completed artifacts. +- **Quality versus operational failures.** Failing a machine gate, scope check, or citation audit is a quality failure; operational failures include crashes, timeouts (20m), and unparsable output. Operational failures retry with `--route default` using the recorded selection. Quality failures retry with `--route quality-retry` using the recorded pin; if it is unavailable, record an explicit fallback or handoff instead of switching silently. +- **Immediate quota handoff.** If adapter-reported quota is exhausted, stop dispatching immediately and hand all unfinished work back to the calling orchestrator while preserving completed artifacts. - **Outcome tracking.** Every attempt and verification verdict is recorded in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt data in `provenance.json`. - **Implementer failures.** If an implementer fails its gate or violates execution scope, retry once with the error output. If the retry fails, halt that task. - **Researcher failures.** If a researcher crashes or times out, retry once. If the retry fails, synthesis proceeds as long as at least two independent evidence angles remain. The final report explicitly names any omitted angle. @@ -264,7 +264,7 @@ All modes format results into a consistent summary: | docs | diff | agy+grep | △ judged | as assigned (scout) | | auth-audit | audit (isolated) | orchestrator+checked (high) + orchestrator+sampled (med/low) | complete | 3 findings (2 verified, 1 unverified) | -### Claimed by Gemini, not verified +### Claimed by worker, not verified - "also improved error messages" - "Legacy endpoints may be affected" ``` @@ -299,7 +299,7 @@ Place this instruction block in your agent's project context file (`AGENTS.md`, ```markdown ## Offload delegation -- Use Offload when the user asks to offload, run work on AGY, use Gemini subagents, or accepts an AGY offer. +- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts an AGY offer. - Offer AGY once, before starting, when implementation splits into three or more independently gated tasks in a clean Git repository, or when a read-only audit or external research requires multiple distinct work lanes. Count research lanes by distinct questions or evidence responsibilities, not browser tabs. - Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. - Ask before dispatching. @@ -339,7 +339,7 @@ pwsh -File tests/test_execution_scope.ps1 - **`--json-schema` outputs validated JSON in `structured_output`.** Parse `structured_output` rather than `response`. - **Use the bundled launcher helpers (`run-agy-json.sh` or `run-agy-json.ps1`) for worker calls.** They own result and error paths and reject the unsupported `agy --output` flag. - **Use structured output extractors (`extract-structured-output.sh` or `extract-structured-output.ps1`) between research stages.** They forward only validated `structured_output`, keeping verbose worker prose out of later prompts. -- **Model routing is governed by `model-policy.json`.** Launchers inject the policy-selected Gemini 3.8 Flash model (`gemini-3.8-flash-low` or `gemini-3.8-flash-high`) via `--role `. Reasoning effort is encoded directly in the model ID; callers must not pass `--model` or `--effort`. +- **Model routing is governed by `model-policy.json` and the adapter contract.** Launchers select a live eligible model using the role preference, effort, required capabilities, quota, and static security rules. The adapter receives the exact selection and translates it for its vendor. Reasoning effort stays separate from model identity, and callers must not pass `--model` or `--effort`. - **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted probe on `agy 1.1.25` blocked the tested direct write outside the permitted artifact area, but this observation is not a guarantee. `--add-dir` grants access without confining writes. Security relies on filesystem isolation and mechanical verification. Run the maintainer-only compatibility probe when the installed `agy` behavior needs a refresh (never as a deterministic CI gate): diff --git a/SKILL.md b/SKILL.md index 76de7d3..9a10a62 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,15 +1,15 @@ --- name: offload -description: Use when the user wants execution or research handed to another vendor's CLI agents instead of running it here. Triggers include "offload this", "run this on agy", "use gemini subagents", or after answering yes to the offload offer. Also offer unprompted when implementation splits into three or more independently gated tasks in a clean git repository, or when a read-only audit or online research fans out across multiple angles or files. Dispatches parallel headless agy workers, gates their output, and reports what was proven versus claimed. +description: Use when the user wants execution or research handed to another CLI agent instead of running it here. Triggers include "offload this", "run this on a worker", or after answering yes to the offload offer. Also offer unprompted when implementation splits into three or more independently gated tasks in a clean git repository, or when a read-only audit or online research fans out across multiple angles or files. Dispatches parallel headless workers through an adapter, gates their output, and reports what was proven versus claimed. --- # offload -If you are `agy`, stop here. Return worker results to your orchestrator. `agy` is the worker role this skill dispatches. Any other agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, but the skill cannot enforce that rule if a worker ignores it. +If you are a dispatched worker, stop here. Return worker results to your orchestrator. Workers do not dispatch nested workers. Any agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, but the skill cannot enforce that rule if a worker ignores it. ## What this skill does -`offload` delegates execution and research tasks to headless `agy` workers (the Antigravity CLI running Gemini models routed via `model-policy.json`). You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection. +`offload` delegates execution and research tasks to headless workers through a vendor adapter. The reference adapter launches `agy`, but the workflow contract does not depend on a vendor or exact model ID. You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection. You never accept worker claims at face value. You verify output through mechanical checks, test execution, diff inspections, or secondary reviews. @@ -28,15 +28,15 @@ Check these requirements before dispatching workers: 4. **Git working tree.** Writing workflows (`modes/execution.md`) require a clean git repository (`git rev-parse --is-inside-work-tree` and empty `git status --porcelain`). Research workflows (`modes/repo-research.md`, `modes/web-research.md`) operate in isolated disposable workspaces. 5. **Preflight model availability check.** Before dispatching the first worker in a run: - Read repository-root `model-policy.json` (resolved relative to helper scripts, never the caller's working directory). - - Check selected default models against available Gemini model IDs reported by the resolved `agy` installation. - - If a required model is absent or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently downgrade to 3.7, fall back to AGY's unverified default, or pick a similarly named model. - - When a quality-retry escalation model is used, check its availability before dispatch as well. - - Avoid repeating catalog discovery for every worker in the same run unless AGY reports that availability changed. + - Ask the configured adapter for its live catalog, then filter by availability, quota, required capabilities, and supported effort. + - If no eligible model exists or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently switch providers or fall back to an unverified default. + - Avoid repeating catalog discovery for every worker in the same run unless the adapter reports that availability changed. 6. **Policy installation, updates, and revert.** - `model-policy.json` is located at repository root alongside helper scripts. Installation must copy the entire skill directory (including `model-policy.json`). - - The policy enforces `schema_version: 1`, a non-empty `policy_revision` (e.g. `"2026-09-03.1"`), `max_effort: "high"`, `max_retries_per_worker: 1`, `quota_action: "handoff"`, and exactly seven role mappings: `scout`, `gate-author`, `implementer`, `reviewer`, `researcher`, `synthesizer`, and `auditor`. + - The policy enforces `schema_version: 2`, a non-empty `policy_revision`, `max_effort: "high"`, `max_retries_per_worker: 1`, `quota_action: "handoff"`, and exactly seven role mappings: `scout`, `gate-author`, `implementer`, `reviewer`, `researcher`, `synthesizer`, and `auditor`. + - Each role declares an internal preference (`fast`, `balanced`, or `deep`), an independent effort (`low`, `medium`, or `high`), and required capabilities. It does not publish vendor names or exact model IDs. - To update policy: edit `model-policy.json` in the skill root and update `policy_revision`. To revert: restore the prior revision. Launchers validate the entire policy on every invocation. Missing or invalid policy fails closed before launching workers. - - A non-null `quality_escalation` entry must specify an eligible Gemini model and a valid, non-escaping repo-relative `evidence_path` pointing to an existing evaluation document inside the skill directory. + - There is no policy-level model escalation target. Quality retries use the pinned selection when one exists. A missing pin requires an explicit fallback or handoff record. ## Routing @@ -59,7 +59,7 @@ Load the matching mode document for the selected route and shell-specific comman ## Shared model routing and launcher contract -Offload routes all workers through the repository-root `model-policy.json`. Launchers resolve model IDs and inject `--model` before launching `agy`. Callers must never pass `--model` or `--effort` after `--`. +Offload routes all workers through the repository-root `model-policy.json` and the adapter contract in [`docs/adapter-contract.md`](docs/adapter-contract.md). The launcher selects an eligible current catalog entry. The adapter translates that exact selection into vendor-specific arguments. Callers must never pass `--model` or `--effort` after `--`. ### Launcher invocation @@ -68,22 +68,22 @@ Offload routes all workers through the repository-root `model-policy.json`. Laun In PowerShell command expressions, always quote the delimiter (`'--'`). -### Roles and default models +### Roles and preferences -| Role | Default model | Effort | Primary mode | +| Role | Preference | Effort | Primary mode | |---|---|---|---| -| `scout` | `gemini-3.8-flash-low` | low | Execution | -| `gate-author` | `gemini-3.8-flash-high` | high | Execution | -| `implementer` | `gemini-3.8-flash-high` | high | Execution | -| `reviewer` | `gemini-3.8-flash-high` | high | Execution | -| `researcher` | `gemini-3.8-flash-high` | high | Repo research / Web research | -| `synthesizer` | `gemini-3.8-flash-high` | high | Web research | -| `auditor` | `gemini-3.8-flash-high` | high | Web research | +| `scout` | fast | low | Execution | +| `gate-author` | balanced | high | Execution | +| `implementer` | balanced | high | Execution | +| `reviewer` | deep | high | Execution | +| `researcher` | balanced | high | Repo research / Web research | +| `synthesizer` | deep | high | Web research | +| `auditor` | deep | high | Web research | ### Routes -- `--route default` (default): Resolves `default_model` for the specified role. -- `--route quality-retry`: Resolves `quality_escalation.model` for that role. If `quality_escalation` is `null` or unconfigured, the launcher rejects the request with exit code 2 before starting `agy`. Never infer an escalation model or replace the route. +- `--route default` (default): Selects the best eligible catalog entry for the role's preference, effort, and capabilities. +- `--route quality-retry`: Requires a pin from the prior attempt and reuses that exact adapter, vendor, model ID, and effort. If the pin is missing or unavailable, the launcher records an explicit fallback or handoff condition and does not switch silently. ## Shared recovery, retry accounting, and failure handling @@ -106,17 +106,17 @@ In PowerShell command expressions, always quote the delimiter (`'--'`). 1. **Verified success**: Output passes mechanical gates and verification checks. Accept result; no retry. 2. **Quality failure**: The worker completed with a parsable response (exit code 0), but the output fails verification (e.g. machine gate failure normalized to `quality` via `execute-gate.sh` or `execute-gate.ps1`, execution scope violation, reviewer quote mismatch, unsupported synthesis claim, or audit rejection). - - If retry budget remains and mode permits correction: retry once (attempt 2) with concrete verification feedback. Use `--route quality-retry` only when an evidence-backed escalation target is configured in policy; otherwise use `--route default`. + - If retry budget remains and mode permits correction: retry once (attempt 2) with concrete verification feedback. Use `--route quality-retry` with the recorded pin; if the pin is unavailable, record an explicit fallback or handoff instead of selecting a replacement silently. - If attempt 2 fails or the mode requires immediate fallback: stop retrying and follow that mode's halt, partial-result, or orchestrator fallback path. 3. **Unrunnable failure**: Gate execution exited 126 or 127, normalized to `failure_class: "unrunnable"` with `verification: not_performed`. Preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json`. Exits 126 and 127 are not quality retries; do not schedule or spend a model retry. 4. **Operational failure**: Process crash (nonzero exit code), timeout (20 minutes with no output), unparsable JSON, or tool failure. - Follow mode's recovery rule with at most one same-model retry (`--route default`) where permitted. Never escalate models for operational failures. 5. **Unknown failure**: Record uncertainty and follow the operational-failure path. Do not assume a quality failure or quota issue. -6. **Quota exhaustion**: Explicit Gemini quota error reported by `agy` structured output or diagnostics. Trigger immediate quota handoff. +6. **Quota exhaustion**: Explicit quota exhaustion reported by the adapter or worker diagnostics. Trigger immediate quota handoff. ### Immediate quota handoff -When explicit Gemini quota exhaustion is detected: +When explicit quota exhaustion is detected: - Stop dispatching new workers immediately. - Return unfinished work to the calling orchestrator without waiting for running siblings. - Do not retry automatically, wait for reset, switch models, or activate paid credits. @@ -135,8 +135,14 @@ The orchestrator maintains `routing-outcomes.json` in each run's scratch workspa - `attempt`: Integer 1 or 2. - `policy_revision`: Policy revision string. - `route`: `"default"` or `"quality-retry"`. - - `model`: Resolved AGY model ID. - - `effort`: Derived effort suffix (`low`, `medium`, `high`). + - `adapter`: Adapter name and `adapter_revision`. + - `vendor`: Adapter-reported vendor family. + - `model_id`: Exact selected model ID. `model` may repeat it for compatibility with older records. + - `family_hint`: Descriptive adapter metadata. It never grants permissions or promises cross-vendor quality. + - `preference`: Internal policy preference (`fast`, `balanced`, or `deep`). + - `effort`: Selected reasoning effort (`low`, `medium`, or `high`), kept separate from model identity. + - `catalog_revision`: Adapter catalog or probe revision used for selection. + - `selection_reason`: Deterministic filtering and ranking reason. - `reason`: Initial dispatch or observed failure and recovery decision authorizing attempt 2. - `started_at`: ISO 8601 UTC timestamp. - `ended_at`: ISO 8601 UTC timestamp (null while running). @@ -178,7 +184,7 @@ pass: 3/3 criteria, all quotes matched verbatim. No escalation. - [LOW] [agy+unverified] "Legacy endpoints may be affected" — unverified (no location cited). Sample recorded: 1/1 high checked, 1/2 med/low sampled. -### Claimed by Gemini, not verified +### Claimed by worker, not verified - "also improved error messages" - "Legacy endpoints may be affected" ``` diff --git a/docs/adapter-contract.md b/docs/adapter-contract.md new file mode 100644 index 0000000..7043d30 --- /dev/null +++ b/docs/adapter-contract.md @@ -0,0 +1,47 @@ +# Worker adapter contract + +Status: accepted. Protocol version 1. + +The launcher owns policy, selection, retry identity, and filesystem scope. An adapter owns vendor syntax and the live model catalog. The public workflow contract names a worker role, an internal preference (`fast`, `balanced`, or `deep`), and a reasoning effort. It does not name a vendor or an exact model ID. + +## Operations + +The launcher invokes an adapter with one of these operations: + +```text +adapter --operation catalog --request REQUEST.json +adapter --operation launch --request SELECTION.json --output OUTPUT --error ERROR -- WORKER_ARGS... +``` + +`REQUEST.json` contains the role, preference, effort, required capabilities, policy revision, and a protocol version. The catalog operation writes one JSON object to stdout. A catalog contains an adapter revision, vendor, catalog revision, capabilities, and model entries: + +```json +{ + "protocol_version": 1, + "adapter": "agy", + "adapter_revision": "1", + "vendor": "provider", + "catalog_revision": "provider-current", + "models": [ + { + "id": "provider-exact-model-id", + "family_hint": "flash", + "available": true, + "quota_available": true, + "supported_efforts": ["low", "high"], + "capabilities": ["structured-output"], + "scores": {"fast": 1, "balanced": 2, "deep": 3} + } + ] +} +``` + +The launcher filters unavailable, quota-exhausted, effort-incompatible, and capability-incompatible candidates. It then sorts the remaining candidates by the requested preference score and stable `(vendor, id)` tie-breakers. `family_hint` is descriptive metadata only. It cannot grant permissions, widen filesystem access, or make a cross-vendor quality claim. + +The launch operation receives the selected exact ID and effort in the selection JSON. It translates those values into vendor-specific arguments, captures worker stdout and stderr at the supplied paths, and exits with the worker's exit code. Adapter failures are operational failures, not permission to select another provider. + +## Pinning and retries + +The launcher writes the complete selection record when `--selection-output` is supplied. The orchestrator copies that record into every `routing-outcomes.json` attempt together with the attempt number and verification result. A retry or resume supplies the same record with `--pin`. The launcher checks the pinned adapter, vendor, exact model ID, and effort against the current catalog. A changed catalog is acceptable when the pinned model is still available; a missing pinned model fails explicitly and requires a recorded fallback or handoff. No retry silently changes provider, model, or effort. + +Adapters must keep their own discovery, quota, cancellation, wait, and exit-code details behind this protocol. They must not widen the permissions, tools, path scope, or resource ownership granted by the orchestrator. diff --git a/docs/adr/0007-runtime-model-selection-through-adapters.md b/docs/adr/0007-runtime-model-selection-through-adapters.md new file mode 100644 index 0000000..517153c --- /dev/null +++ b/docs/adr/0007-runtime-model-selection-through-adapters.md @@ -0,0 +1,15 @@ +# ADR 0007: Select models at runtime through worker adapters + +- Status: accepted +- Date: 2026-09-04 +- Supersedes: [ADR 0005](0005-bound-model-routing-to-gemini-and-explicit-rules.md) + +## Decision + +Worker policy publishes only the internal preferences `fast`, `balanced`, and `deep`, a separate reasoning effort, and required capabilities. The launcher asks a vendor-neutral worker adapter for a live catalog, filters it using static policy and task requirements, and deterministically selects a current candidate. The adapter translates the selected vendor and exact model ID into its own CLI or API syntax. AGY remains the reference adapter. + +Every selection is recorded with the adapter, vendor, exact model ID, family hint, preference, effort, catalog and adapter revisions, selection reason, and each attempt. Retries and resumes use the recorded selection as a pin. A missing pinned model causes an explicit fallback or handoff; it never causes an implicit provider or model switch. + +## Consequences + +Workflows survive vendor catalog changes without publishing vendor-specific IDs. Catalog availability and quota can be evaluated at launch time. Exact model IDs still exist in operational evidence, where they are needed for reproducibility, but they are not a permission boundary or a quality guarantee. Historical ADR 0005 remains available as the record of the superseded decision. diff --git a/model-policy.json b/model-policy.json index 95f54a9..87dfe0f 100644 --- a/model-policy.json +++ b/model-policy.json @@ -1,37 +1,44 @@ { - "schema_version": 1, - "policy_revision": "2026-09-03.1", + "schema_version": 2, + "policy_revision": "2026-09-04.1", "max_effort": "high", "max_retries_per_worker": 1, "quota_action": "handoff", "roles": { "scout": { - "default_model": "gemini-3.8-flash-low", - "quality_escalation": null + "preference": "fast", + "effort": "low", + "required_capabilities": [] }, "gate-author": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "implementer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "reviewer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] }, "researcher": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "balanced", + "effort": "high", + "required_capabilities": [] }, "synthesizer": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] }, "auditor": { - "default_model": "gemini-3.8-flash-high", - "quality_escalation": null + "preference": "deep", + "effort": "high", + "required_capabilities": [] } } } diff --git a/modes/execution.md b/modes/execution.md index e714dcf..128f0f8 100644 --- a/modes/execution.md +++ b/modes/execution.md @@ -24,12 +24,12 @@ Check these before dispatching writing tasks: Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. -| Role | Wave | Default model | Effort | Mode | Job | +| Role | Wave | Preference | Effort | Mode | Job | |---|---|---|---|---|---| -| scout | 1 | `gemini-3.8-flash-low` | low | `plan` | Report repository-relative file paths a task touches. | -| gate-author | 2 | `gemini-3.8-flash-high` | high | `accept-edits` | Author an executable test file from acceptance criteria. | -| implementer | 3 | `gemini-3.8-flash-high` | high | `accept-edits` | Implement the task within owned files in candidate workspace. | -| reviewer | 4 | `gemini-3.8-flash-high` | high | `plan` | Evaluate the recorded review artifact against criteria for diff-gated tasks. | +| scout | 1 | fast | low | `plan` | Report repository-relative file paths a task touches. | +| gate-author | 2 | balanced | high | `accept-edits` | Author an executable test file from acceptance criteria. | +| implementer | 3 | balanced | high | `accept-edits` | Implement the task within owned files in candidate workspace. | +| reviewer | 4 | deep | high | `plan` | Evaluate the recorded review artifact against criteria for diff-gated tasks. | `--mode plan` is a version-sensitive behavioral hint, not a write barrier. On `agy 1.1.25`, the compatibility probe blocked the tested direct write outside the permitted artifact area, but this is not a guarantee. `--add-dir` grants access without confining writes. Protection relies on isolated candidate worktrees, mechanical execution scope checks with explicit baselines, frozen path checks, and test gates. @@ -235,7 +235,7 @@ Read worker JSON responses and record outcomes in `routing-outcomes.json`: - `status: SUCCESS`: Worker completed execution. Proceed to verification in Step 5. - Non-zero exit code or unparsable output: Worker crashed or encountered an operational failure. Record the attempt and follow Step 6. - Timeout (no output written before 20m timeout): Operational failure. Record the timeout and follow Step 6. -- **Immediate quota handoff**: If explicit Gemini quota exhaustion is detected on any worker, record still-running candidates and all existing artifacts in `routing-outcomes.json` immediately without waiting for sibling completion, and hand off unfinished work directly to the calling orchestrator. +- **Immediate quota handoff**: If explicit adapter-reported quota exhaustion is detected on any worker, record still-running candidates and all existing artifacts in `routing-outcomes.json` immediately without waiting for sibling completion, and hand off unfinished work directly to the calling orchestrator. ## Step 5: Verify and integrate @@ -366,11 +366,11 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Stable worker IDs and retry ceiling.** Assign a stable `worker_id` to each logical task. Attempt 1 is initial dispatch; attempt 2 is its only possible retry. Maximum two attempts total per task. - **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. - **Baseline retention on retry.** Retries must retain the original verification baseline for that writing stage (e.g. `$GATE_BASELINE`). A failed attempt never becomes an implicitly trusted baseline. Create a fresh candidate worktree at the original baseline for attempt 2. -- **Implementer quality failure.** If an execution scope check violation occurs or a machine gate normalizes to `failure_class: "quality"` (non-zero exit code other than 126/127), this constitutes a quality failure. If a retry remains (attempt 2), redispatch once with the specific failure output and diagnostic evidence. Use `--route quality-retry` only if an evidence-backed escalation target is configured for `implementer` in `model-policy.json`; otherwise use `--route default`. If attempt 2 fails, halt that task. +- **Implementer quality failure.** If an execution scope check violation occurs or a machine gate normalizes to `failure_class: "quality"` (non-zero exit code other than 126/127), this constitutes a quality failure. If a retry remains (attempt 2), redispatch once with the specific failure output and diagnostic evidence using the pinned selection. If the pinned model is unavailable, record the explicit fallback or handoff and do not switch silently. If attempt 2 fails, halt that task. - **Unrunnable gate execution.** If a gate command exits 126 or 127, it normalizes to `failure_class: "unrunnable"` with `verification_status: "not_performed"` and `allow_retry: false`. Gate exits 126 and 127 are not quality retries; preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json` without spending or scheduling a quality retry. - **Scout or gate-author operational failure.** If a scout or gate-author crashes, times out, or produces unparsable output, retry once using `--route default`. If the retry fails, complete that step directly as the orchestrator (`orchestrator (fallback)`). - **Reviewer failure.** If reviewer output is unparsable or fails digest or quote verification, inspect the recorded artifact directly as the orchestrator (`agy→orchestrator`). -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Record still-running candidates immediately without waiting for siblings, preserve completed artifacts, and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Record still-running candidates immediately without waiting for siblings, preserve completed artifacts, and return unfinished work to the calling orchestrator. - **Workspace cleanup.** After workers have terminated, clean up candidate worktrees: - Bash: `"$OFFLOAD_ROOT/scripts/execution-workspace.sh" cleanup --manifest "" --status success|failed|retain` - PowerShell: `& "$OffloadRoot/scripts/execution-workspace.ps1" cleanup --manifest "" --status success|failed|retain` diff --git a/modes/repo-research.md b/modes/repo-research.md index 21619e0..539dd8a 100644 --- a/modes/repo-research.md +++ b/modes/repo-research.md @@ -9,7 +9,7 @@ Select the helper family matching your current host shell: - **POSIX shells (Bash 3.2+)**: Use `scripts/make-research-workspace.sh`, `scripts/run-agy-json.sh`, and `scripts/cleanup-research-workspace.sh`. Requires Git, `agy`, `jq`, and Python 3. - **PowerShell (PowerShell 7+)**: Use `scripts/make-research-workspace.ps1`, `scripts/run-agy-json.ps1`, and `scripts/cleanup-research-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. -Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects the current model. Do not pass `--model` or `--effort` directly. ## Assignment requirements @@ -44,7 +44,7 @@ The workspace helper creates a unique temporary directory, writes the `.offload- ## Worker dispatch -Dispatch researchers in parallel using role `researcher` with a structured schema and the matching launcher helper. The launcher resolves `gemini-3.8-flash-high` from `model-policy.json`: +Dispatch researchers in parallel using role `researcher` with a structured schema and the matching launcher helper. The launcher asks the adapter to select a current eligible model: #### Bash ```bash @@ -103,7 +103,7 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. - **Operational failure.** If a worker crashes, times out, or produces unparsable output, redispatch once using `--route default`. No model escalation for operational failure. - **Orchestrator fallback.** If the second attempt fails or findings remain inconclusive, complete the investigation directly as the orchestrator (`orchestrator (fallback)`). -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. ## Cleanup diff --git a/modes/web-research.md b/modes/web-research.md index 9105c01..62471ea 100644 --- a/modes/web-research.md +++ b/modes/web-research.md @@ -11,7 +11,7 @@ Conducts cited online investigations and multi-angle technical research by dispa - **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. 4. **`agy` availability.** Workers are launched using the matching `run-agy-json` helper, which handles `AGY_BIN` precedence and output capture. 5. **Filesystem isolation.** Every research run operates in a disposable workspace outside the live repository. -6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through `model-policy.json` (`gemini-3.8-flash-high` default). Do not pass `--model` or `--effort` directly. +6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects a current eligible model. Do not pass `--model` or `--effort` directly. ## Worker isolation and mixed repositories @@ -60,11 +60,11 @@ Record the specific deep trigger in the final report and in `provenance.json`. I Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. -| Role | Stage | Default model | Effort | Alternative model | Mode | Job | +| Role | Stage | Preference | Effort | Alternative model | Mode | Job | |---|---|---|---|---|---|---| -| researcher | 1 | `gemini-3.8-flash-high` | high | — | `plan` | Gathers structured claims and citations for an assigned evidence angle. | -| synthesizer | 2 | `gemini-3.8-flash-high` | high | — | `plan` | Builds claim ledger, resolves agreements/conflicts, and drafts synthesis. | -| auditor | 3 | `gemini-3.8-flash-high` | high | — | `plan` | Independently verifies every citation in the proposed final answer. | +| researcher | 1 | balanced | high | adapter catalog | `plan` | Gathers structured claims and citations for an assigned evidence angle. | +| synthesizer | 2 | deep | high | adapter catalog | `plan` | Builds claim ledger, resolves agreements/conflicts, and drafts synthesis. | +| auditor | 3 | deep | high | adapter catalog | `plan` | Independently verifies every citation in the proposed final answer. | A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro synthesizer and auditor split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. See [`tests/live-smoke-comparison.md`](../tests/live-smoke-comparison.md) for the recorded judgment. @@ -385,7 +385,7 @@ Follow the shared recovery, retry accounting, and failure handling rules in [`SK - **Researcher failure.** If a researcher crashes, times out, or produces unparsable output, retry once with the error details using `--route default`. The selection gate admits only the verified accepted attempt for each assignment. If a retry fails, synthesis proceeds as long as at least two distinct `angle_id` values remain; otherwise use the partial-result fallback. The final report explicitly names any omitted angle. - **Synthesis or audit failure.** Synthesis and citation audit are mandatory stages. The allowed synthesizer revision pass consumes the synthesizer's second attempt. The subsequent audit consumes the auditor's second attempt. If either stage crashes, times out, returns unparsable JSON, or fails to resolve citations after exhausting its 2-attempt budget, the run transitions to `partial` status. - **Partial result contract.** A `partial` run returns audited claims and raw findings collected up to the point of failure, but strictly withholds a firm synthesis or recommendation. State the failed stage explicitly and retain all raw artifacts for debugging. -- **Quota exhaustion.** Explicit Gemini quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. +- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. ## Provenance and cleanup @@ -410,10 +410,18 @@ At the conclusion of the research run: "role": "researcher", "mode": "web-research", "attempt": 1, - "policy_revision": "2026-09-03.1", + "policy_revision": "2026-09-04.1", "route": "default", - "model": "gemini-3.8-flash-high", + "adapter": "agy", + "adapter_revision": "adapter-revision", + "vendor": "vendor-family", + "model_id": "exact-model-id", + "model": "exact-model-id", + "family_hint": "family-hint", + "preference": "balanced", "effort": "high", + "catalog_revision": "catalog-revision", + "selection_reason": "Eligible catalog candidate ranked highest for the role preference", "reason": "Initial default dispatch", "started_at": "2026-09-03T00:00:00Z", "ended_at": "2026-09-03T00:01:30Z", @@ -437,10 +445,18 @@ At the conclusion of the research run: "role": "researcher", "mode": "web-research", "attempt": 2, - "policy_revision": "2026-09-03.1", + "policy_revision": "2026-09-04.1", "route": "default", - "model": "gemini-3.8-flash-high", + "adapter": "agy", + "adapter_revision": "adapter-revision", + "vendor": "vendor-family", + "model_id": "exact-model-id", + "model": "exact-model-id", + "family_hint": "family-hint", + "preference": "balanced", "effort": "high", + "catalog_revision": "catalog-revision", + "selection_reason": "Pinned selection retained after a retry", "reason": "Retry authorized after quality gate failure on attempt 1", "started_at": "2026-09-03T00:02:00Z", "ended_at": "2026-09-03T00:03:30Z", diff --git a/scripts/agy-adapter.ps1 b/scripts/agy-adapter.ps1 new file mode 100644 index 0000000..5a8e1bb --- /dev/null +++ b/scripts/agy-adapter.ps1 @@ -0,0 +1,165 @@ +#!/usr/bin/env pwsh +# Reference worker adapter. Vendor-specific AGY syntax lives here, not in the launcher. + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version 3.0 + +function Fail([string]$message, [int]$exitCode = 2) { + [Console]::Error.WriteLine("ERROR: $message") + exit $exitCode +} + +function Resolve-Program([string]$path) { + if ([string]::IsNullOrWhiteSpace($path)) { Fail 'AGY_BIN is empty' } + if ($path.EndsWith('.ps1', [System.StringComparison]::OrdinalIgnoreCase)) { + return @{ File = (Get-Command pwsh -ErrorAction Stop).Source; Prefix = @('-NoProfile', '-NonInteractive', '-File', $path) } + } + return @{ File = $path; Prefix = @() } +} + +function Invoke-Captured([string]$file, [string[]]$arguments, [string]$stdoutPath, [string]$stderrPath) { + $psi = [System.Diagnostics.ProcessStartInfo]::new() + $psi.FileName = $file + $psi.UseShellExecute = $false + $psi.RedirectStandardOutput = $true + $psi.RedirectStandardError = $true + foreach ($argument in $arguments) { [void]$psi.ArgumentList.Add($argument) } + $process = [System.Diagnostics.Process]::new() + $process.StartInfo = $psi + try { + if (-not $process.Start()) { Fail "failed to start adapter command: $file" 127 } + $stdoutTask = $process.StandardOutput.ReadToEndAsync() + $stderrTask = $process.StandardError.ReadToEndAsync() + $process.WaitForExit() + [System.IO.File]::WriteAllText($stdoutPath, $stdoutTask.Result, [System.Text.Encoding]::UTF8) + [System.IO.File]::WriteAllText($stderrPath, $stderrTask.Result, [System.Text.Encoding]::UTF8) + return $process.ExitCode + } finally { + $process.Dispose() + } +} + +function Get-FamilyHint([string]$modelId) { + if ($modelId -match '^gemini-[^-]+-(?flash|pro)-') { return $Matches.family } + if ($modelId -match '^claude-[^-]+-(?opus|sonnet|haiku)') { return $Matches.family } + if ($modelId -match '^gpt-oss-') { return 'oss' } + return 'unknown' +} + +function Get-PreferenceScore([string]$family, [string]$preference) { + $scores = @{ + fast = @{ flash = 1; haiku = 2; oss = 2; sonnet = 3; pro = 4; opus = 5; unknown = 100 } + balanced = @{ sonnet = 1; flash = 2; oss = 3; pro = 3; haiku = 4; opus = 5; unknown = 100 } + deep = @{ opus = 1; pro = 2; sonnet = 3; oss = 4; flash = 5; haiku = 6; unknown = 100 } + } + if ($scores.ContainsKey($preference) -and $scores[$preference].ContainsKey($family)) { return $scores[$preference][$family] } + return 100 +} + +function Convert-ModelListToCatalog([string]$raw) { + $models = @( + foreach ($line in ($raw -split "`r?`n")) { + if ($line -notmatch '^\s*(?\S+)\s+(?