diff --git a/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G04.md b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G04.md new file mode 100644 index 00000000..8bc84d55 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G04.md @@ -0,0 +1,121 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/01_preset_config, plan=2, tag=API + +## Archive Evidence Snapshot + +- Split parent pair: `plan_local_G07_1.log`, `code_review_cloud_G07_1.log`. +- The split parent contained no implementation evidence or review verdict; implementation has not started. +- This child retains only the typed schema, validation, and clone-isolation slice. Refresh classification and documentation moved to packet 04. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G04.md` → `code_review_cloud_G04_2.log` and `PLAN-local-G04.md` → `plan_local_G04_2.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/01_preset_config/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=preset-binding` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Add the typed fixed single-request policy | [ ] | + +## Implementation Checklist + +- [ ] Add and validate the optional fixed single-request preset policy, deep-clone it, and prove valid, boundary, invalid, legacy, and clone-isolation cases. +- [ ] Run targeted config, package, vet, full package regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G04_2.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G04_2.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/01_preset_config/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=preset-binding` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Unmarked direct/light presets remain source- and behavior-compatible. +- Marked presets fail closed for dynamic modes, malformed stage sets, option leakage, and legacy caller tools. +- Policy and nested stage maps are defensive copies. +- No endpoint, credential, Node id, or raw path is added. + +## Verification Results + +### Config policy + +Command: `go test ./packages/go/config -run 'Test(LoadEdgeSingleRequestExecutionPreset|CloneExecutionPresetSingleRequestIsolation|LoadEdgeExecutionPresetCatalog|LoadEdgeExecutionPresetRejectsInvalidShape)$' -count=1` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./packages/go/config -count=1` +- `go vet ./packages/go/...` +- `go test ./packages/go/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/PLAN-local-G04.md b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/PLAN-local-G04.md new file mode 100644 index 00000000..43e2c2ec --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/PLAN-local-G04.md @@ -0,0 +1,132 @@ + + +# Fixed Single-request Preset Policy + +## For the Implementing Agent + +Implement this plan exactly within the listed write boundary. Run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G04.md` with actual notes and stdout/stderr, keep both active files in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record the exact blocker, attempted commands/output, and resume condition in implementation-owned evidence fields; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Split parent pair: `plan_local_G07_1.log`, `code_review_cloud_G07_1.log`. +- The split parent contained no implementation evidence or review verdict; implementation has not started. +- This child retains only the typed schema, validation, and clone-isolation slice. Refresh classification and documentation moved to packet 04. + +## Background + +The execution-preset schema has generic `direct` and caller-continuation `light` forms but no operator-owned marker for the approved fixed single-request path. SDD S02 requires an opaque workspace capability and immutable request/stage limits while preserving existing preset compatibility. + +## Analysis + +### Files Read + +- `packages/go/config/execution_preset_types.go` +- `packages/go/config/execution_preset_config_test.go` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` + +### SDD Criteria + +- SDD status is approved and its implementation lock is released. +- First-line Milestone task: `preset-binding`; targeted Acceptance Scenario: S02. +- This child supplies fixed-light decode, validation, cloning, and compatibility evidence. Runtime authorization/model echo stays in packet 02, and refresh/schema publication stays in packet 04. + +### Verification Context + +- The parent packet selected repository-native focused/package config tests, package vet/regression, and `git diff --check`; this child preserves the config-owned subset. +- Preconditions: none. Ordinary presets remain compatible, and no external runner/provider is used. + +### Test Coverage Gaps + +- Existing config tests do not cover a fixed single-request marker, typed limits, legacy workspace-tool exclusion, dynamic-mode rejection, or deep-clone isolation. + +### Symbol References + +- No symbol is renamed or removed. `ExecutionPreset.Clone` and `CloneExecutionPresetCatalog` are existing consumers extended by this child. + +### Split Judgment + +- Stable result: a validated and deeply cloned typed preset independently passes config tests. +- Refresh classification and published schema form a second production slice after packet 02, avoiding concurrent edits to its config-refresh spec. + +### Scope Rationale + +- Exclude refresh classification, route resolution, handlers, provider execution, Node/workspace execution, protobuf, SSE, contract, and spec updates. +- Keep unmarked direct/light presets compatible. `workspace_ref` stays opaque; add no endpoint, credential, Node id, raw path, dynamic selection, or silent default. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures scope/context/verification/evidence/ownership/decision are true; scores 1/0/1/1/1 = G04; base/final route `local-fit`; lane `local`; canonical filename `PLAN-local-G04.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `boundary_contract`, `structured_interpretation`, `variant_product` (3); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 1/0/1/1/1 = G04; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G04.md`. + +## Implementation Checklist + +- [ ] Add and validate the optional fixed single-request preset policy, deep-clone it, and prove valid, boundary, invalid, legacy, and clone-isolation cases. +- [ ] Run targeted config, package, vet, full package regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Add the typed fixed single-request policy + +**Problem** + +- `packages/go/config/execution_preset_types.go:13` defines no marker that distinguishes operator-owned single-request execution from generic caller-continuation light presets. +- `packages/go/config/execution_preset_types.go:61` has no policy pointer/nested map to clone, and `packages/go/config/execution_preset_types.go:281` cannot enforce the approved fixed shape. + +**Solution** + +Before (`packages/go/config/execution_preset_types.go:15`): + +```go +ID string `mapstructure:"id" yaml:"id"` +Selector ExecutionModelBinding `mapstructure:"selector" yaml:"selector"` +AllowedModes []string `mapstructure:"allowed_modes" yaml:"allowed_modes"` +Routes map[string]ExecutionRoute `mapstructure:"routes" yaml:"routes"` +``` + +After: + +```go +// Existing fields stay source-compatible. +SingleRequest *ExecutionSingleRequestPolicy `mapstructure:"single_request" yaml:"single_request,omitempty"` +``` + +Add typed workspace/limit structs and server-owned absolute caps: wall clock 30 minutes, each stage timeout 10 minutes, 64 tool iterations per stage, and 16 MiB output per stage. Require every configured value in `1..cap`, each stage timeout not to exceed the request wall clock, and the stage map to contain exactly `plan`, `work`, and `review`. A marked preset allows only `light`, binds selector/review to high reasoning, rejects high reasoning on work, and rejects legacy caller `workspace_tools`. Preserve unmarked validation. Deep-copy the pointer and nested stage map. + +**Modified Files and Checklist** + +- [ ] `packages/go/config/execution_preset_types.go` — add typed policy, named absolute caps, normalization, fail-closed validation, and deep cloning. +- [ ] `packages/go/config/single_request_execution_preset_config_test.go` — cover valid decode, cap/cap+1 and timeout-vs-wall-clock boundaries, missing/extra stages, dynamic modes, option leakage, legacy tools, unknown fields, and clone isolation. + +**Test Strategy** + +- Add `TestLoadEdgeSingleRequestExecutionPreset`, `TestLoadEdgeSingleRequestExecutionPresetRejectsInvalidShape`, and `TestCloneExecutionPresetSingleRequestIsolation` using Gemini plan/review, ornith-fast work, an opaque workspace ref, and explicit positive bounded limits. +- Include zero, exact cap, cap+1, and stage-timeout-greater-than-wall-clock rows for every limit family, then rerun existing generic catalog/rejection tests. + +**Verification** + +- `go test ./packages/go/config -run 'Test(LoadEdgeSingleRequestExecutionPreset|CloneExecutionPresetSingleRequestIsolation|LoadEdgeExecutionPresetCatalog|LoadEdgeExecutionPresetRejectsInvalidShape)$' -count=1` +- Expected: valid/exact-cap and legacy cases pass; zero/cap+1/cross-limit/malformed shapes fail; clone mutation cannot affect the source. + +## Modified Files Summary + +| File | Item | +|------|------| +| `packages/go/config/execution_preset_types.go` | API-1 | +| `packages/go/config/single_request_execution_preset_config_test.go` | API-1 | +| `agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G04.md` | API-1 | + +## Final Verification + +1. `go test ./packages/go/config -run 'Test(LoadEdgeSingleRequestExecutionPreset|CloneExecutionPresetSingleRequestIsolation|LoadEdgeExecutionPresetCatalog|LoadEdgeExecutionPresetRejectsInvalidShape)$' -count=1` +2. `go test ./packages/go/config -count=1` +3. `go vet ./packages/go/...` +4. `go test ./packages/go/... -count=1` +5. `git diff --check` + +Expected: all commands exit 0; ordinary presets stay compatible; invalid marked shapes fail closed; policy clones are isolated. Refresh classification and schema publication remain packet 04. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/code_review_cloud_G07_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/CODE_REVIEW-cloud-G07.md rename to agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/code_review_cloud_G07_1.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/PLAN-local-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/plan_local_G07_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/PLAN-local-G07.md rename to agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/plan_local_G07_1.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/CODE_REVIEW-cloud-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/CODE_REVIEW-cloud-G07.md index 7d71017b..baff9697 100644 --- a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/CODE_REVIEW-cloud-G07.md +++ b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/CODE_REVIEW-cloud-G07.md @@ -1,4 +1,4 @@ - + # Code Review Reference - API @@ -15,13 +15,13 @@ ## Overview date=2026-08-06 -task=m-iop-owned-single-request-agent-execution/02+01_preset_binding, plan=1, tag=API +task=m-iop-owned-single-request-agent-execution/02+01_preset_binding, plan=2, tag=API ## Archive Evidence Snapshot -- Superseded pair: `plan_local_G06_0.log`, `code_review_cloud_G07_0.log`. +- Superseded pair: `plan_local_G06_1.log`, `code_review_cloud_G07_1.log`. - The superseded pair contained no implementation evidence or review verdict; implementation has not started. -- Self-review correction: the immutable binding is a surface-neutral service DTO, not an OpenAI-private type. Route resolution may populate it, but the coordinator must consume it without importing an endpoint package. Edge vet coverage is also restored. +- Fresh-review correction: preserve the surface-neutral immutable binding scope, and replace the broad archive scan with the exact predecessor candidate pattern required by the split dependency protocol. ## For the Review Agent @@ -31,7 +31,7 @@ Compare implementation of each item against source files and verify that output Review completion means the following steps are finished: 1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. -2. Archive `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_1.log` and `PLAN-local-G06.md` → `plan_local_G06_1.log`. +2. Archive `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_2.log` and `PLAN-local-G06.md` → `plan_local_G06_2.log`. 3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/02+01_preset_binding/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. 4. If PASS, preserve `milestone-task=preset-binding` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. 5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. @@ -61,8 +61,8 @@ Review completion means the following steps are finished: - [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. - [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. -- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G07_1.log`. -- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G06_1.log`. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G07_2.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G06_2.log`. - [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. - [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. - [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/02+01_preset_binding/` and update this checklist at the final archive path. @@ -90,7 +90,7 @@ _Record key design decisions here._ ### Dependency -Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' -print | sort | grep -q .` +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' | wc -l)" -eq 1` _Actual output/status:_ diff --git a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/PLAN-local-G06.md b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/PLAN-local-G06.md index 5480f92b..8b0b2a63 100644 --- a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/PLAN-local-G06.md +++ b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/PLAN-local-G06.md @@ -1,4 +1,4 @@ - + # Immutable Single-request Runtime Binding @@ -8,9 +8,9 @@ Do not start until packet 01 has `complete.log`. Implement this plan exactly wit ## Archive Evidence Snapshot -- Superseded pair: `plan_local_G06_0.log`, `code_review_cloud_G07_0.log`. +- Superseded pair: `plan_local_G06_1.log`, `code_review_cloud_G07_1.log`. - The superseded pair contained no implementation evidence or review verdict; implementation has not started. -- Self-review correction: the immutable binding is a surface-neutral service DTO, not an OpenAI-private type. Route resolution may populate it, but the coordinator must consume it without importing an endpoint package. Edge vet coverage is also restored. +- Fresh-review correction: preserve the surface-neutral immutable binding scope, and replace the broad archive scan with the exact predecessor candidate pattern required by the split dependency protocol. ## Background @@ -98,7 +98,7 @@ Generic route resolution returns a cloned preset and canonical authorized routes **Problem** - `apps/edge/internal/openai/route_resolution.go:52` owns `routeDispatch`, but packet 03's coordinator must be surface-neutral and therefore cannot consume an OpenAI-private binding DTO. -- `apps/edge/internal/service` has no immutable type for requested identity, authorized stage routes, workspace capability, and copied limits. +- `apps/edge/internal/service/service.go:28` has no immutable type for requested identity, authorized stage routes, workspace capability, and copied limits. **Solution** @@ -193,11 +193,30 @@ When and only when the policy is present, compile `plan` from selector authority **Problem** -- The Anthropic contract and current specs describe generic preset resolution but not a service-owned, request-generation single-request binding. +- `agent-contract/outer/anthropic-compatible-api.md:55` defines generic preset authorization but not a service-owned, request-generation single-request binding. +- `agent-spec/input/openai-compatible-surface.md:132` and `agent-spec/runtime/provider-pool-config-refresh.md:93` do not define marked admission or request-start binding isolation. **Solution** -Add a marked-preset subsection to the existing virtual-preset contract and corresponding specs. Document one-generation snapshot semantics, compilation only after principal authorization, requested public identity, and surface-neutral ownership. Explicitly defer coordinator, provider/workspace execution, and HTTP/SSE completion. +Before (`agent-contract/outer/anthropic-compatible-api.md:61`): + +```markdown +Authentication and route resolution retain one immutable projection generation for a +request. A public `route_id` resolves only inside the verified managed gate to one +internal model group and selector-compatible provider resource set; it is distinct from +the provider resource and from `credential_slot_ref`. +``` + +After, add a separate marked-preset subsection and matching spec rows: + +```markdown +An authorized fixed single-request preset compiles one service-owned admission value at +request start: requested public model, canonical plan/work/review bindings, opaque +workspace capability, limits, and projection/config generation. Later refresh cannot +mutate that value, and no private binding is echoed to the caller. +``` + +Document compilation only after principal authorization and surface-neutral ownership. Explicitly defer coordinator, provider/workspace execution, and HTTP/SSE completion. **Modified Files and Checklist** @@ -207,7 +226,7 @@ Add a marked-preset subsection to the existing virtual-preset contract and corre **Test Strategy** -- No standalone documentation test. API-2's authorization/model-echo/refresh-isolation tests are the executable oracle; review compares prose to those named tests. +- Skip a standalone documentation-only test because API-2's authorization/model-echo/refresh-isolation tests are the executable oracle; review compares prose to those named tests. **Verification** @@ -231,7 +250,7 @@ Add a marked-preset subsection to the existing virtual-preset contract and corre ## Final Verification -1. `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' -print | sort | grep -q .` +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' | wc -l)" -eq 1` 2. `go test ./apps/edge/internal/service -run 'TestSingleRequestBinding' -count=1` 3. `go test ./apps/edge/internal/openai -run 'Test(SingleRequestPresetBinding|VirtualPresetModelAuthorizationMatrix)' -count=1` 4. `rg --sort path -n 'single-request|immutable|public model|refresh' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/provider-pool-config-refresh.md` diff --git a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/code_review_cloud_G07_1.log b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/code_review_cloud_G07_1.log new file mode 100644 index 00000000..7d71017b --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/code_review_cloud_G07_1.log @@ -0,0 +1,144 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/02+01_preset_binding, plan=1, tag=API + +## Archive Evidence Snapshot + +- Superseded pair: `plan_local_G06_0.log`, `code_review_cloud_G07_0.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Self-review correction: the immutable binding is a surface-neutral service DTO, not an OpenAI-private type. Route resolution may populate it, but the coordinator must consume it without importing an endpoint package. Edge vet coverage is also restored. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_1.log` and `PLAN-local-G06.md` → `plan_local_G06_1.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/02+01_preset_binding/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=preset-binding` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Own the immutable admission DTO in service | [ ] | +| API-2 Compile only an authorized fixed binding at route resolution | [ ] | +| API-3 Synchronize the admission boundary | [ ] | + +## Implementation Checklist + +- [ ] Define the surface-neutral immutable single-request binding and compile fixed plan/work/review routes, public identity, workspace capability, and copied limits at route admission. +- [ ] Fail closed on missing or inconsistent authorization, preserve ordinary routes, and prove managed/unmanaged, option, model-echo, and refresh-isolation behavior. +- [ ] Synchronize the Anthropic boundary and current specs without claiming coordinator, workspace execution, or provider completion. +- [ ] Run dependency, targeted, package, vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G07_1.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G06_1.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/02+01_preset_binding/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=preset-binding` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 01 completion evidence existed before implementation. +- `service` owns the binding and imports no endpoint package. +- Managed and unmanaged routes authorize every stage before compilation. +- Public model identity is retained while canonical/provider/credential/workspace details stay private. +- Refresh or caller mutation cannot alter an admitted request. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' -print | sort | grep -q .` + +_Actual output/status:_ + +### Service DTO + +Command: `go test ./apps/edge/internal/service -run 'TestSingleRequestBinding' -count=1` + +_Actual output:_ + +### Route compiler + +Command: `go test ./apps/edge/internal/openai -run 'Test(SingleRequestPresetBinding|VirtualPresetModelAuthorizationMatrix)' -count=1` + +_Actual output:_ + +### Documentation + +Command: `rg --sort path -n 'single-request|immutable|public model|refresh' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/provider-pool-config-refresh.md` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/service ./apps/edge/internal/openai -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/plan_local_G06_1.log b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/plan_local_G06_1.log new file mode 100644 index 00000000..5480f92b --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/plan_local_G06_1.log @@ -0,0 +1,245 @@ + + +# Immutable Single-request Runtime Binding + +## For the Implementing Agent + +Do not start until packet 01 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G07.md` with actual notes and stdout/stderr, keep the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Superseded pair: `plan_local_G06_0.log`, `code_review_cloud_G07_0.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Self-review correction: the immutable binding is a surface-neutral service DTO, not an OpenAI-private type. Route resolution may populate it, but the coordinator must consume it without importing an endpoint package. Edge vet coverage is also restored. + +## Background + +Generic route resolution returns a cloned preset and canonical authorized routes but leaves downstream code to reinterpret selector/local/review semantics. SDD S02 requires a single request-start value that freezes public identity, the fixed stage routes, workspace capability, and limits without refresh mutation or dynamic fallback. + +## Analysis + +### Files Read + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `agent-ops/rules/common/rules-roadmap.md` +- `agent-ops/rules/common/rules-agent-spec.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` +- `packages/go/config/execution_preset_types.go` +- `apps/edge/internal/service/service.go` +- `apps/edge/internal/service/run_types.go` +- `apps/edge/internal/openai/route_resolution.go` +- `apps/edge/internal/openai/principal_routes.go` +- `apps/edge/internal/openai/principal_routes_test.go` +- `apps/edge/internal/openai/server.go` +- `agent-contract/outer/anthropic-compatible-api.md` +- `agent-spec/input/openai-compatible-surface.md` +- `agent-spec/runtime/provider-pool-config-refresh.md` + +### SDD Criteria + +- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md`; status approved and implementation lock released. +- First-line Milestone task: `preset-binding`; targeted Acceptance Scenario: S02. +- Evidence Map: fixed-light authorization, public-model echo, workspace snapshot, and refresh isolation. Those rows require the managed/unmanaged authorization and copy-isolation checks in the checklist and Final Verification. + +### Verification Context + +- No separate verification handoff was supplied. Repository-native fallback came from managed-principal authorization tests, generic route resolution, clone-on-config behavior, the Edge test profile, and the approved SDD. +- Precondition: packet 01 completion evidence. Constraints: no external runner/provider, no concrete workspace execution, and generic routing compatibility. Gap: the coordinator begins in packet 03. +- Final commands use fresh focused/package tests, `go vet ./apps/edge/...`, full Edge regression, and `git diff --check`. Confidence is high because both managed and unmanaged resolution already produce authorized canonical routes. + +### Test Coverage Gaps + +- Existing managed/unmanaged virtual-preset tests cover route authorization and public identity, but not the fixed plan/work/review compiler, workspace/limit copies, fail-closed defenses, or refresh isolation of a compiled admission. + +### Symbol References + +- No symbol is renamed or removed. `routeDispatch` is produced by `resolveRouteDispatch` and `resolveVirtualPresetModelForPrincipal`; adding one optional field preserves ordinary consumers. + +### Split Judgment + +- Stable child contract: packet 01's validated config is compiled into an endpoint-neutral immutable admission value and independently passes service/openai tests. +- Predecessor index 01 resolves to `agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/`; its `complete.log` is currently missing, so implementation remains pending and unambiguous. + +### Scope Rationale + +- Exclude HTTP admission, provider stages, concrete workspace authorization, Node wire, and SSE because this packet ends at route admission. +- Preserve generic direct/light behavior and public requested-model identity. Never expose canonical route/provider/credential/endpoint/raw workspace data. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures are true; scores 2/1/1/1/1 = G06; base/final route `local-fit`; lane `local`; canonical filename `PLAN-local-G06.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `boundary_contract`, `concurrent_consistency`, `variant_product` (3); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/1/1/1/2 = G07; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G07.md`. + +## Dependencies and Execution Order + +1. Verify packet 01 completion evidence. +2. Define the endpoint-neutral DTO in `service`, then compile it in route resolution. +3. Prove managed/unmanaged authorization, public identity, and snapshot isolation before updating documents. + +## Implementation Checklist + +- [ ] Define the surface-neutral immutable single-request binding and compile fixed plan/work/review routes, public identity, workspace capability, and copied limits at route admission. +- [ ] Fail closed on missing or inconsistent authorization, preserve ordinary routes, and prove managed/unmanaged, option, model-echo, and refresh-isolation behavior. +- [ ] Synchronize the Anthropic boundary and current specs without claiming coordinator, workspace execution, or provider completion. +- [ ] Run dependency, targeted, package, vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Own the immutable admission DTO in service + +**Problem** + +- `apps/edge/internal/openai/route_resolution.go:52` owns `routeDispatch`, but packet 03's coordinator must be surface-neutral and therefore cannot consume an OpenAI-private binding DTO. +- `apps/edge/internal/service` has no immutable type for requested identity, authorized stage routes, workspace capability, and copied limits. + +**Solution** + +Before (`apps/edge/internal/service/run_types.go:11`): + +```go +type SubmitRunRequest struct { + NodeRef string + RunID string + ModelGroupKey string +} +``` + +After, in a separate additive file: + +```go +package service + +type SingleRequestBinding struct { + PublicModel string + WorkspaceRef string + Plan, Work, Review SingleRequestStageBinding + Limits SingleRequestLimits +} +``` + +Use service-package DTOs for the binding and stages. Store only frozen runtime inputs and provide constructors/copy helpers that reject incomplete stage sets and prevent retention of mutable config maps/slices. The service package must not import `openai` or endpoint wire types. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/service/single_request_types.go` — define the surface-neutral immutable binding and defensive copy/validation helpers. +- [ ] `apps/edge/internal/service/single_request_types_test.go` — prove copy isolation and fail-closed stage/limit invariants. + +**Test Strategy** + +- Add `TestSingleRequestBindingValid`, boundary/invalid table cases, and `TestSingleRequestBindingCloneIsolation` with nested option/limit mutation assertions. +- New service DTO tests are required because this is a new cross-component API. + +**Verification** + +- `go test ./apps/edge/internal/service -run 'TestSingleRequestBinding' -count=1` +- Expected: complete immutable bindings pass; missing/invalid stage facts fail closed; caller mutation is isolated. + +### [API-2] Compile only an authorized fixed binding at route resolution + +**Problem** + +- `apps/edge/internal/openai/route_resolution.go:52` returns cloned preset/routes but no compiled single-request admission. +- `apps/edge/internal/openai/principal_routes.go:95` resolves principal-authorized canonical models, yet downstream reinterpretation could select a missing/unauthorized stage or observe later mutation. + +**Solution** + +Before (`apps/edge/internal/openai/route_resolution.go:76`): + +```go +IsPreset bool +PresetID string +ExternalModelID string +Preset config.ExecutionPreset +PresetResolvedBindings map[string]routeDispatch +``` + +After: + +```go +type routeDispatch struct { + // Existing fields remain. + SingleRequest *edgeservice.SingleRequestBinding +} +``` + +When and only when the policy is present, compile `plan` from selector authority, `work` from the local route, and `review` from the review route already authorized for the principal. Reject missing, duplicate, unauthorized, dynamically selected, or option-inconsistent inputs without generic fallback. Keep external model echo equal to the requested public model. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/route_resolution.go` — attach the optional service binding on unmanaged authorized resolution. +- [ ] `apps/edge/internal/openai/principal_routes.go` — attach it after managed-principal canonical authorization. +- [ ] `apps/edge/internal/openai/single_request_preset_binding.go` — compile validated config/routes into the service DTO without exposing private route data. +- [ ] `apps/edge/internal/openai/single_request_preset_binding_test.go` — cover managed/unmanaged authorization, fixed roles/options, public-model echo, defensive copies, refresh isolation, and invalid defense-in-depth cases. + +**Test Strategy** + +- Add `TestSingleRequestPresetBindingManaged`, `...Unmanaged`, `...RejectsInvalidDefenseInDepth`, and `...RefreshIsolation` using the existing principal/virtual-model fixtures. +- Rerun `TestVirtualPresetModelAuthorizationMatrix` unchanged for generic authorization regression. + +**Verification** + +- `go test ./apps/edge/internal/openai -run 'Test(SingleRequestPresetBinding|VirtualPresetModelAuthorizationMatrix)' -count=1` +- Expected: only authorized fixed bindings compile and public identity/snapshot isolation hold. + +### [API-3] Synchronize the admission boundary + +**Problem** + +- The Anthropic contract and current specs describe generic preset resolution but not a service-owned, request-generation single-request binding. + +**Solution** + +Add a marked-preset subsection to the existing virtual-preset contract and corresponding specs. Document one-generation snapshot semantics, compilation only after principal authorization, requested public identity, and surface-neutral ownership. Explicitly defer coordinator, provider/workspace execution, and HTTP/SSE completion. + +**Modified Files and Checklist** + +- [ ] `agent-contract/outer/anthropic-compatible-api.md` — define marked admission and public/private identity boundaries. +- [ ] `agent-spec/input/openai-compatible-surface.md` — synchronize route-dispatch behavior and tests. +- [ ] `agent-spec/runtime/provider-pool-config-refresh.md` — record request-start snapshot isolation across refresh. + +**Test Strategy** + +- No standalone documentation test. API-2's authorization/model-echo/refresh-isolation tests are the executable oracle; review compares prose to those named tests. + +**Verification** + +- `rg --sort path -n 'single-request|immutable|public model|refresh' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/provider-pool-config-refresh.md` +- Expected: the service-owned admission and its exclusions are explicit without private values. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/service/single_request_types.go` | API-1 | +| `apps/edge/internal/service/single_request_types_test.go` | API-1 | +| `apps/edge/internal/openai/route_resolution.go` | API-2 | +| `apps/edge/internal/openai/principal_routes.go` | API-2 | +| `apps/edge/internal/openai/single_request_preset_binding.go` | API-2 | +| `apps/edge/internal/openai/single_request_preset_binding_test.go` | API-2 | +| `agent-contract/outer/anthropic-compatible-api.md` | API-3 | +| `agent-spec/input/openai-compatible-surface.md` | API-3 | +| `agent-spec/runtime/provider-pool-config-refresh.md` | API-3 | +| `agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/CODE_REVIEW-cloud-G07.md` | API-1, API-2, API-3 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/01_preset_config/complete.log' -print | sort | grep -q .` +2. `go test ./apps/edge/internal/service -run 'TestSingleRequestBinding' -count=1` +3. `go test ./apps/edge/internal/openai -run 'Test(SingleRequestPresetBinding|VirtualPresetModelAuthorizationMatrix)' -count=1` +4. `rg --sort path -n 'single-request|immutable|public model|refresh' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/provider-pool-config-refresh.md` +5. `go test ./apps/edge/internal/service ./apps/edge/internal/openai -count=1` +6. `go vet ./apps/edge/...` +7. `go test ./apps/edge/... -count=1` +8. `git diff --check` + +Expected: predecessor evidence exists; only authorized fixed bindings compile; mutable config/refresh changes cannot affect an admitted request; generic dispatch regressions pass. No coordinator or execution completion is claimed. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/CODE_REVIEW-cloud-G08.md b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/CODE_REVIEW-cloud-G08.md new file mode 100644 index 00000000..2352bedd --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/CODE_REVIEW-cloud-G08.md @@ -0,0 +1,140 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator, plan=3, tag=API + +## Archive Evidence Snapshot + +- Refined parent: `plan_cloud_G09_2.log`, `code_review_cloud_G10_2.log`; earlier intent remains in sibling logs `0` and `1`. +- The parent pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction preserved in the parent: runtime Edge ingress-counter evidence and exact dependency lookup were added before this one-time split. +- Split allocation: this child owns the surface-neutral coordinator, state/terminal ownership, service tests, and coordinator runtime spec. Packet 05 owns HTTP admission, the ingress counter, endpoint tests, and outer/input documentation. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G08.md` → `code_review_cloud_G08_3.log` and `PLAN-local-G07.md` → `plan_local_G07_3.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=single-ingress` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Implement the coordinator in service | [ ] | +| API-2 Synchronize the coordinator runtime boundary | [ ] | + +## Implementation Checklist + +- [ ] Implement the surface-neutral request-local coordinator and executor port with copied immutable admission and the complete approved state graph, including repair and saved-stage internal-tool resume. +- [ ] Enforce cancellation, executor shutdown, fail-closed envelopes, one terminal outcome, and one-shot endpoint acknowledgement before `completed`. +- [ ] Synchronize the Edge runtime spec without claiming HTTP integration, concrete Node/workspace/provider execution, or real Claude smoke. +- [ ] Run exact dependency, targeted race, documentation, package, vet, full Edge, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G08_3.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G07_3.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=single-ingress` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 02 completion evidence existed before implementation. +- Coordinator/state ownership is in `service`; no endpoint wire type crosses into it. +- All approved states, especially `repairing` and saved-stage `internal_tool`, are tested. +- Immutable request/binding inputs cannot change after admission; invalid or stale envelopes fail closed. +- Success remains `finalizing` until one endpoint acknowledgement; duplicate/write-failure/cancel races cannot also complete. +- Exactly one outcome wins and all executor work is cancelled and joined. +- The runtime spec does not claim HTTP admission, concrete workspace/provider execution, or actual Claude evidence. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` + +_Actual output/status:_ + +### Coordinator race and state graph + +Command: `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` + +_Actual output:_ + +### Runtime specification + +Command: `rg --sort path -n 'single-request|repairing|internal_tool|finalizing|acknowledg|defer' agent-spec/runtime/edge-node-execution.md` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/service -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/PLAN-local-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/PLAN-local-G07.md new file mode 100644 index 00000000..631678b4 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/PLAN-local-G07.md @@ -0,0 +1,235 @@ + + +# Surface-neutral Single-request Coordinator + +## For the Implementing Agent + +Do not start until packet 02 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G08.md` with actual notes and stdout/stderr, keep the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Refined parent: `plan_cloud_G09_2.log`, `code_review_cloud_G10_2.log`; earlier intent remains in sibling logs `0` and `1`. +- The parent pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction preserved in the parent: runtime Edge ingress-counter evidence and exact dependency lookup were added before this one-time split. +- Split allocation: this child owns the surface-neutral coordinator, state/terminal ownership, service tests, and coordinator runtime spec. Packet 05 owns HTTP admission, the ingress counter, endpoint tests, and outer/input documentation. + +## Background + +The marked Anthropic path needs one request-local coordinator that freezes identity and binding, drives approved internal stages, and selects one terminal without importing HTTP or Anthropic wire types. This packet establishes that independently testable service boundary before endpoint admission is added. + +## Analysis + +### Files Read + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `agent-ops/rules/common/rules-roadmap.md` +- `agent-ops/rules/common/rules-agent-spec.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` +- `apps/edge/internal/service/service.go` +- `apps/edge/internal/service/run_types.go` +- `apps/edge/internal/service/provider_pool.go` +- `agent-spec/runtime/edge-node-execution.md` + +### SDD Criteria + +- SDD status is approved and its implementation lock is released. +- First-line Milestone task: `single-ingress`; this child supplies S01's immutable coordinator/API foundation. Packet 05 supplies the actual one-POST Edge ingress evidence. +- Approved states are `accepted`, `planning`, `working`, `reviewing`, `repairing`, `internal_tool`, `finalizing`, `completed`, `failed`, and `cancelled`. + +### Verification Context + +- No separate verification handoff was supplied. Repository-native fallback is the service lifecycle code, approved SDD state graph, Edge test profile, and current runtime spec. +- Precondition: packet 02 completion. Constraints: current checkout only; an injected executor replaces external Node/workspace/provider infrastructure. +- Race-enabled service tests are the primary oracle for immutable admission, legal transitions, cancellation, and one-terminal ownership. + +### State and Concurrency Findings + +- `internal_tool` returns only to its saved active stage; `repairing` is a first-class approved state. +- Stale, duplicate, identity-mismatched, or illegal envelopes fail closed. +- A successful candidate remains `finalizing` until the surface acknowledges a successful terminal write. Completion, failure, cancellation, and acknowledgement races must select one outcome and stop executor work. + +### Test Coverage Gaps + +- No service test exercises the complete state graph, repair path, saved-stage internal-tool detour, immutable admission, cancellation, acknowledgement, or terminal races. +- `service.Service` has no optional fixed single-request executor/coordinator API. + +### Symbol References + +- No existing symbol is renamed or removed. +- The coordinator remains in `service`; it must not import endpoint wire types or widen the widely faked OpenAI `runService` interface. + +### Refine Judgment + +- This is the stable foundation child produced by the one-time refinement of the corrected parent. +- Further splitting would separate the executor contract from the state/terminal invariant it exists to enforce, so this child remains atomic and independently PASS-capable. + +### Scope Rationale + +- Include only the service-owned request/executor/envelope API, state graph, terminal acknowledgement, tests, and its runtime spec. +- Exclude HTTP admission, ingress metrics, Anthropic translation, streaming projection, concrete Node/workspace/provider protocol, and real Claude smoke. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures are true; scores 1/2/1/1/2 = G07; base/final route `local-fit`; lane `local`; canonical filename `PLAN-local-G07.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `temporal_state`, `concurrent_consistency`, `boundary_contract` (3); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 1/2/1/2/2 = G08; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G08.md`. + +## Dependencies and Execution Order + +1. Verify exactly one packet 02 completion candidate, preferring the active path. +2. Define the service-owned immutable request, executor envelopes, and request-scoped execution handle. +3. Implement and race-test the complete state graph and terminal acknowledgement. +4. Synchronize the coordinator runtime spec and run Edge regressions. + +## Implementation Checklist + +- [ ] Implement the surface-neutral request-local coordinator and executor port with copied immutable admission and the complete approved state graph, including repair and saved-stage internal-tool resume. +- [ ] Enforce cancellation, executor shutdown, fail-closed envelopes, one terminal outcome, and one-shot endpoint acknowledgement before `completed`. +- [ ] Synchronize the Edge runtime spec without claiming HTTP integration, concrete Node/workspace/provider execution, or real Claude smoke. +- [ ] Run exact dependency, targeted race, documentation, package, vet, full Edge, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Implement the coordinator in service + +**Problem** + +- `apps/edge/internal/service/service.go:28` owns Edge runtime state but exposes no fixed single-request executor/coordinator API. +- `agent-spec/runtime/edge-node-execution.md:57` documents normalized execution but has no surface-neutral single-request state or terminal-acknowledgement boundary. + +**Solution** + +Before (`apps/edge/internal/service/service.go:28`): + +```go +type Service struct { + mu sync.RWMutex + registry *edgenode.Registry + events *edgeevents.Bus + nodeStore *edgenode.NodeStore + queue *modelQueueManager + modelCatalog []config.ModelCatalogEntry + providerPoolPolicy groupPolicy + tunnels *providerTunnelRouter + credentialLeases CredentialLeaseProvider + credentialLeaseSlots chan struct{} +} +``` + +After: + +```go +type Service struct { + // Existing fields remain. + singleRequestExecutor SingleRequestExecutor +} + +func (s *Service) SetSingleRequestExecutor(executor SingleRequestExecutor) { + s.mu.Lock() + defer s.mu.Unlock() + s.singleRequestExecutor = executor +} + +func (s *Service) StartSingleRequest( + ctx context.Context, + req SingleRequestRequest, +) (SingleRequestExecution, error) { + s.mu.RLock() + executor := s.singleRequestExecutor + s.mu.RUnlock() + return startSingleRequest(ctx, executor, req) +} +``` + +Define the new service types in `single_request.go` with the required standard-library imports and no endpoint import: + +```go +import ( + "context" + "sync" +) +``` + +The setter updates the optional executor under `Service.mu`; `StartSingleRequest` snapshots it under the same lock and fails closed when absent. The request copies its immutable input/binding. Typed internal envelopes carry request/stage identity and closed stage/terminal values. Validate the full state graph, saved-stage `internal_tool` return, ordering, duplicates, and identity. Hold a successful candidate in `finalizing` until the endpoint handle receives one successful terminal acknowledgement; failure, cancellation, or write-failure acknowledgement selects the sole alternative terminal. Cancel and join executor work on every exit. Do not implement concrete Node/tool transport. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/service/service.go` — configure the optional executor and expose the surface-neutral request API. +- [ ] `apps/edge/internal/service/single_request.go` — implement executor/envelope types, immutable admission, state validation, redacted progress, cancellation, and terminal ownership. +- [ ] `apps/edge/internal/service/single_request_test.go` — cover success/ack, repair, internal-tool resume, invalid envelopes, cancellation, unavailability, and terminal races under `-race`. + +**Test Strategy** + +- Use a channel-driven fake executor. +- Cover success held in `finalizing`, duplicate and write-failure acknowledgement, repair flow, internal-tool resume, illegal/stale/duplicate/identity-mismatched envelopes, immutable admission, unavailable executor, cancellation, and competing terminals. + +**Verification** + +- `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` +- Expected: all legal paths pass, invalid envelopes fail closed, success cannot complete before acknowledgement, and exactly one terminal wins without races or surviving work. + +### [API-2] Synchronize the coordinator runtime boundary + +**Problem** + +- `agent-spec/runtime/edge-node-execution.md:57` has only the generic normalized-execution row and no surface-neutral coordinator/executor port or explicit deferral boundary. + +**Solution** + +Before (`agent-spec/runtime/edge-node-execution.md:57`): + +```markdown +| normalized execution | `adapter + target`으로 provider 실행을 선택하고 ordered `RunEvent` stream을 반환한다. | +``` + +After, add a separate current-runtime row/section: + +```markdown +| single-request coordinator | Immutable admission과 closed stage envelope을 service-owned state graph로 처리하고 surface terminal acknowledgement 뒤에만 completed로 전이한다. | +``` + +Document executor-envelope privacy and the deferral of HTTP wiring plus concrete Node/workspace/provider execution. Do not claim S01's ingress counter or real-provider evidence here. + +**Modified Files and Checklist** + +- [ ] `agent-spec/runtime/edge-node-execution.md` — record the coordinator port, state/terminal ownership, privacy boundary, and explicit deferrals. + +**Test Strategy** + +- Skip a standalone documentation-only test because API-1's named race tests are the executable oracle; deterministic search checks the synchronized state and deferral language. + +**Verification** + +- `rg --sort path -n 'single-request|repairing|internal_tool|finalizing|acknowledg|defer' agent-spec/runtime/edge-node-execution.md` +- Expected: the service boundary and deferrals are explicit without claiming endpoint or provider completion. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/service/service.go` | API-1 | +| `apps/edge/internal/service/single_request.go` | API-1 | +| `apps/edge/internal/service/single_request_test.go` | API-1 | +| `agent-spec/runtime/edge-node-execution.md` | API-2 | +| `agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/CODE_REVIEW-cloud-G08.md` | API-1, API-2 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` +2. `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` +3. `rg --sort path -n 'single-request|repairing|internal_tool|finalizing|acknowledg|defer' agent-spec/runtime/edge-node-execution.md` +4. `go test ./apps/edge/internal/service -count=1` +5. `go vet ./apps/edge/...` +6. `go test ./apps/edge/... -count=1` +7. `git diff --check` + +Expected: exactly one predecessor completion candidate exists; the surface-neutral state graph and acknowledgement invariant pass under race testing; the runtime spec matches; all Edge checks pass. HTTP ingress, streaming projection, concrete workspace execution, and actual Claude smoke remain unclaimed. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/code_review_cloud_G10_0.log b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/code_review_cloud_G10_0.log rename to agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/CODE_REVIEW-cloud-G10.md b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/CODE_REVIEW-cloud-G10.md rename to agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_1.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_2.log b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_2.log new file mode 100644 index 00000000..c787b520 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/code_review_cloud_G10_2.log @@ -0,0 +1,146 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/03+02_single_ingress, plan=2, tag=API + +## Archive Evidence Snapshot + +- Superseded refined pair: `plan_cloud_G09_1.log`, `code_review_cloud_G10_1.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction: S01 now has a runtime Edge ingress counter and a real HTTP POST counter-delta assertion, and dependency evidence uses the exact active-or-single-archive candidate rule. Coordinator/state ownership remains in the surface-neutral `service` package, `repairing` remains in the approved state machine, and endpoint integration keeps a separate optional interface instead of widening the legacy `runService` contract. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G10.md` → `code_review_cloud_G10_2.log` and `PLAN-cloud-G09.md` → `plan_cloud_G09_2.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/03+02_single_ingress/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=single-ingress` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Implement the coordinator in service | [ ] | +| API-2 Admit marked Anthropic requests exactly once | [ ] | +| API-3 Synchronize the coordinator boundary | [ ] | + +## Implementation Checklist + +- [ ] Implement the surface-neutral request-local coordinator, executor port, complete approved state graph including repair/internal-tool resume, immutable admission, cancellation, and one-shot endpoint terminal acknowledgement before `completed`. +- [ ] Route marked Anthropic Messages requests through a separate optional service capability before legacy admission, increment one bounded runtime Edge ingress counter, keep one HTTP lifetime, and prove one real POST plus counter delta `+1` with a multi-stage fake. +- [ ] Preserve unmarked Anthropic, Chat, and count-tokens behavior; expose only sanitized progress/final/error values and synchronize the boundary documents. +- [ ] Run dependency, targeted race, package, vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G10_2.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_cloud_G09_2.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/03+02_single_ingress/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=single-ingress` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 02 completion evidence existed before implementation. +- Coordinator/state ownership is in `service`; no endpoint wire type crosses into it. +- All approved states, especially `repairing` and saved-stage `internal_tool`, are tested. +- Success remains `finalizing` until one endpoint terminal acknowledgement; duplicate/write-failure/cancel races cannot also complete. +- Exactly one outcome wins and all executor work is cancelled/joined. +- Marked routing precedes legacy pool/continuation; one real HTTP POST increments the bounded runtime Edge ingress counter exactly once, regardless of internal stage count. +- Public output has no reasoning, tool wire, provider/route/credential/workspace data, or caller `tool_use` continuation. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` + +_Actual output/status:_ + +### Coordinator race and state graph + +Command: `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` + +_Actual output:_ + +### One runtime-counted ingress and compatibility + +Command: `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` + +_Actual output:_ + +### Documentation + +Command: `rg --sort path -n 'single-request|one POST|repairing|tool_use|count_tokens' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/service ./apps/edge/internal/openai -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/plan_cloud_G09_0.log b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/plan_cloud_G09_0.log rename to agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/PLAN-cloud-G09.md b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/PLAN-cloud-G09.md rename to agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_1.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_2.log b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_2.log new file mode 100644 index 00000000..a8191e93 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/plan_cloud_G09_2.log @@ -0,0 +1,264 @@ + + +# Surface-neutral Single-request Coordinator and Ingress + +## For the Implementing Agent + +Do not start until packet 02 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G10.md` with actual notes and stdout/stderr, keep the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Superseded refined pair: `plan_cloud_G09_1.log`, `code_review_cloud_G10_1.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction: S01 now has a runtime Edge ingress counter and a real HTTP POST counter-delta assertion, and dependency evidence uses the exact active-or-single-archive candidate rule. Coordinator/state ownership remains in the surface-neutral `service` package, `repairing` remains in the approved state machine, and endpoint integration keeps a separate optional interface instead of widening the legacy `runService` contract. + +## Background + +The current Anthropic path may expose caller-mediated preset/tool continuations across turns. The marked path needs exactly one accepted `/v1/messages` request whose immutable binding drives a request-local coordinator through all internal stages and yields one sanitized result or failure. The endpoint package owns translation only; coordinator semantics must remain reusable by other surfaces. + +## Analysis + +### Files Read + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `agent-ops/rules/common/rules-roadmap.md` +- `agent-ops/rules/common/rules-agent-spec.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` +- `apps/edge/internal/service/service.go` +- `apps/edge/internal/service/run_types.go` +- `apps/edge/internal/service/provider_pool.go` +- `apps/edge/internal/openai/server.go` +- `apps/edge/internal/openai/route_resolution.go` +- `apps/edge/internal/openai/anthropic_handler.go` +- `apps/edge/internal/openai/request_identity_ingress.go` +- `apps/edge/internal/openai/hot_path_direct.go` +- `apps/edge/internal/openai/hot_path_metrics.go` +- `apps/edge/internal/openai/anthropic_surface_test.go` +- `apps/edge/internal/openai/request_identity_handler_test.go` +- `apps/edge/internal/openai/provider_test_support_test.go` +- `agent-contract/outer/anthropic-compatible-api.md` +- `agent-spec/input/openai-compatible-surface.md` +- `agent-spec/runtime/edge-node-execution.md` + +### SDD Criteria + +- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md`; status approved and implementation lock released. +- First-line Milestone task: `single-ingress`; targeted Acceptance Scenario: S01. +- Evidence Map row S01 requires one actual `/v1/messages` POST, an Edge ingress counter, immutable identity, complete internal multi-stage execution via the coordinator/API boundary, and one final/error. Those facts directly produce API-1/API-2 and the runtime counter-delta, POST-count, and race commands in Final Verification. + +### Verification Context + +- No separate verification handoff was supplied. Repository-native fallback came from the service lifecycle code, Anthropic handler/identity regressions, test fake interface shape, Edge test profile, and approved SDD. +- Precondition: packet 02 completion. Constraints: current checkout only; no external runner/provider; concrete Node/workspace executor stays deferred. Gap: streamed SSE projection is packet 04 and actual Claude smoke is later Milestone evidence. +- Commands use service race tests, a real `httptest.Server` POST with a runtime ingress-counter delta, endpoint compatibility tests, deterministic doc search, `go vet`, full Edge regression, and `git diff --check`. Confidence is high for coordinator/ingress behavior with an injected multi-stage fake. + +### State and Concurrency Findings + +- Approved states: `accepted`, `planning`, `working`, `reviewing`, `repairing`, `internal_tool`, `finalizing`, `completed`, `failed`, `cancelled`. +- `internal_tool` must return only to its saved active stage. Stage sequence and retries are validated from internal envelopes; stale, duplicate, or illegal transitions fail closed. +- One terminal wins under completion, failure, cancellation, and duplicate/racing internal events. No goroutine or stage survives request termination. + +### Test Coverage Gaps + +- No service test exercises the full state graph, repair path, temporary internal-tool state, immutable admission, cancellation, or terminal races. +- Existing endpoint tests do not expose a runtime counter for accepted marked ingress, count one real HTTP POST across a multi-stage executor, or prove that the marked branch bypasses legacy caller continuation. + +### Symbol References + +- No existing symbol is renamed or removed. +- `runService` is implemented by `*service.Service` and multiple OpenAI test fakes. It must not gain the new method; the marked handler uses a separate narrow optional interface. +- `routeDispatch` is the call-site carrier for packet 02's binding; `handleAnthropicMessages` is the endpoint branch point. + +### Split Judgment + +- Stable child contracts: the surface-neutral coordinator/state machine is independently testable behind its executor port; the subsequent HTTP ingress integration can then prove the S01 runtime counter and one-POST boundary without depending on SSE projection. +- Predecessor index 02 resolves to `agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/`; its `complete.log` is currently missing, so implementation remains pending and unambiguous. + +### Scope Rationale + +- Exclude generic Anthropic relay, Chat bridge, count-tokens, unmarked preset continuation, and streaming projection because they have separate compatibility/packet ownership. +- Exclude concrete provider/Node/workspace protocol and actual Claude smoke. Do not expose reasoning, tool protocol, route/provider/credential/workspace data, or internal terminals. +- Add only the S01 ingress counter required by the Evidence Map. It must have no request-derived labels; latency, outcome, cleanup, and stage metrics remain outside this packet. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures are true; scores 2/2/2/1/2 = G09; base/final route `grade-boundary`; lane `cloud`; canonical filename `PLAN-cloud-G09.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `temporal_state`, `concurrent_consistency`, `boundary_contract`, `structured_interpretation`, `variant_product` (5); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/2/2/2/2 = G10; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G10.md`. + +## Dependencies and Execution Order + +1. Verify packet 02 completion evidence. +2. Implement and race-test the service coordinator before endpoint integration. +3. Add the marked handler branch before legacy pool/continuation admission. +4. Prove one HTTP POST and generic path compatibility, then synchronize contracts/specs. + +## Implementation Checklist + +- [ ] Implement the surface-neutral request-local coordinator, executor port, complete approved state graph including repair/internal-tool resume, immutable admission, cancellation, and one-shot endpoint terminal acknowledgement before `completed`. +- [ ] Route marked Anthropic Messages requests through a separate optional service capability before legacy admission, increment one bounded runtime Edge ingress counter, keep one HTTP lifetime, and prove one real POST plus counter delta `+1` with a multi-stage fake. +- [ ] Preserve unmarked Anthropic, Chat, and count-tokens behavior; expose only sanitized progress/final/error values and synchronize the boundary documents. +- [ ] Run dependency, targeted race, package, vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Implement the coordinator in service + +**Problem** + +- `apps/edge/internal/service/service.go:28` owns Edge request/runtime state but exposes no fixed single-request executor/coordinator API. +- The superseded plan placed state in the endpoint server and omitted approved `repairing`, which would violate the surface-neutral domain boundary and reject a valid SDD transition. + +**Solution** + +Before (`apps/edge/internal/service/service.go:28`): + +```go +type Service struct { + mu sync.RWMutex + registry *edgenode.Registry + events *edgeevents.Bus + nodeStore *edgenode.NodeStore +} +``` + +After: + +```go +type Service struct { + // Existing fields remain. + singleRequestExecutor SingleRequestExecutor +} + +func (s *Service) StartSingleRequest(ctx context.Context, req SingleRequestRequest) (SingleRequestExecution, error) +``` + +Define a service-owned executor that accepts a frozen binding/input and emits typed internal envelopes. Validate request/stage identity and the full state graph, including the repair loop and saved-stage `internal_tool` detour. Copy mutable inputs and expose only closed progress/result enums. Return a request-scoped execution handle that holds a successful terminal candidate in `finalizing`; it may enter `completed` only after the endpoint calls a one-shot success acknowledgement after its terminal write. Duplicate/stale acknowledgement fails closed; write failure or caller cancellation selects `failed`/`cancelled`. Serialize outcome/ack selection, cancel the executor on exit, and fail within-request if unavailable. Do not import endpoint wire types or implement Node/tool wire. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/service/service.go` — configure the optional executor and expose the surface-neutral request API. +- [ ] `apps/edge/internal/service/single_request.go` — implement executor/envelope types, state validation, redacted progress, cancellation, and terminal ownership. +- [ ] `apps/edge/internal/service/single_request_test.go` — cover success held in finalizing until ack, duplicate/write-failure ack, repair, internal-tool resume, illegal/stale/duplicate events, immutable admission, unavailable executor, cancel, and terminal races under `-race`. + +**Test Strategy** + +- Add `TestSingleRequestSuccessWaitsForTerminalAck`, duplicate/write-failure acknowledgement cases, `...RepairFlow`, `...InternalToolResumesSavedStage`, invalid envelope/transition tables, `...ImmutableAdmission`, `...ExecutorUnavailable`, `...Cancel`, and terminal race cases. +- Use an injected channel-driven fake executor and run all `TestSingleRequest` cases under the race detector. + +**Verification** + +- `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` +- Expected: all approved paths including repair pass, success cannot reach completed before endpoint acknowledgement, invalid/stale events fail closed, and exactly one outcome/ack wins without races. + +### [API-2] Admit marked Anthropic requests exactly once + +**Problem** + +- `apps/edge/internal/openai/anthropic_handler.go:66` reaches `anthropicPoolRequest`/legacy continuation after dispatch resolution and has no marked one-request branch. +- `apps/edge/internal/openai/server.go:23` defines a widely faked `runService`; widening it would break unrelated test implementations and couple the new capability to generic endpoints. +- No runtime metric currently records accepted marked `/v1/messages` ingress, so a test-local handler call count cannot satisfy SDD S01's Edge ingress-counter evidence. + +**Solution** + +Before (`apps/edge/internal/openai/server.go:23`): + +```go +type runService interface { + SubmitRun(context.Context, edgeservice.SubmitRunRequest) (edgeservice.RunResult, error) + SubmitProviderTunnel(context.Context, edgeservice.SubmitProviderTunnelRequest) (edgeservice.ProviderTunnelResult, error) + SubmitProviderPool(context.Context, edgeservice.ProviderPoolDispatchRequest) (*edgeservice.ProviderPoolDispatchResult, error) + OllamaAPI(context.Context, edgeservice.OllamaAPIRequest) (edgeservice.OllamaAPIView, error) + CancelRun(context.Context, edgeservice.CancelRunRequest) (edgeservice.CommandResult, error) +} +``` + +After, without changing that interface: + +```go +type singleRequestService interface { + StartSingleRequest(context.Context, service.SingleRequestRequest) (service.SingleRequestExecution, error) +} +``` + +Assert the separate capability only for a marked dispatch. Branch after request validation/authorization but before pool/legacy continuation, copy request input, preserve the public model, and translate one buffered sanitized final/error. Record exactly one accepted ingress in a dedicated Prometheus counter with no request-derived labels; do not increment it per internal stage or retry. Acknowledge success only after the endpoint terminal is written; propagate write failure/cancellation to the handle. Never return caller `tool_use` or re-enter the generic branch. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/server.go` — declare/wire the separate optional single-request capability without expanding `runService`. +- [ ] `apps/edge/internal/openai/anthropic_handler.go` — branch marked admission before legacy execution and translate buffered final/error output. +- [ ] `apps/edge/internal/openai/single_request_metrics.go` — own the bounded registered Edge ingress counter without request-derived labels. +- [ ] `apps/edge/internal/openai/single_request_handler_test.go` — send one real POST through `httptest.Server`, assert the runtime counter delta is exactly `+1`, drive multi-stage/repair fake events, assert one response terminal and private-value absence, and cover missing capability/failure/cancellation. + +**Test Strategy** + +- Add `TestAnthropicSingleRequestUsesOnePost`, which snapshots the runtime counter, sends one real HTTP POST through `httptest.Server`, and asserts delta `+1` after multi-stage completion; add repair success, terminal-write acknowledgement/failure, unavailable capability/failure/cancel, public-model, and private-sentinel assertions in the dedicated test file. +- Rerun `TestPresetRequestIdentityAcrossAnthropicTurns` and `TestPresetRequestIdentityAnthropicCountTokensBypassesCoordinator` unchanged from their existing test file. + +**Verification** + +- `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` +- Expected: a marked multi-stage fake is admitted by one real HTTP POST, increments the registered Edge ingress counter exactly once, and returns one sanitized terminal; generic continuation/count-tokens behavior is unchanged. + +### [API-3] Synchronize the coordinator boundary + +**Problem** + +- The current outer contract describes caller replay/tool continuation for generic compatibility, and the specs do not distinguish the marked service coordinator boundary. + +**Solution** + +Add a marked-path exception to the existing virtual-preset Hot Path contract and corresponding specs. Document immutable service admission, one Messages POST, no caller continuation tool wire, public model retention, same-request sanitized failure, and unchanged generic/Chat/count-tokens behavior. Describe the executor as an internal port without claiming concrete workspace/Node implementation or real-provider smoke. + +**Modified Files and Checklist** + +- [ ] `agent-contract/outer/anthropic-compatible-api.md` — define one-ingress semantics, compatibility, and private/public boundaries. +- [ ] `agent-spec/input/openai-compatible-surface.md` — synchronize marked handler behavior and executable evidence. +- [ ] `agent-spec/runtime/edge-node-execution.md` — record the surface-neutral coordinator port and explicit implementation deferral. + +**Test Strategy** + +- No standalone documentation test. API-2's named one-POST/privacy/compatibility tests are the executable contract oracle. + +**Verification** + +- `rg --sort path -n 'single-request|one POST|repairing|tool_use|count_tokens' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` +- Expected: marked behavior and deferrals are explicit, while generic compatibility remains documented. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/service/service.go` | API-1 | +| `apps/edge/internal/service/single_request.go` | API-1 | +| `apps/edge/internal/service/single_request_test.go` | API-1 | +| `apps/edge/internal/openai/server.go` | API-2 | +| `apps/edge/internal/openai/anthropic_handler.go` | API-2 | +| `apps/edge/internal/openai/single_request_metrics.go` | API-2 | +| `apps/edge/internal/openai/single_request_handler_test.go` | API-2 | +| `agent-contract/outer/anthropic-compatible-api.md` | API-3 | +| `agent-spec/input/openai-compatible-surface.md` | API-3 | +| `agent-spec/runtime/edge-node-execution.md` | API-3 | +| `agent-task/m-iop-owned-single-request-agent-execution/03+02_single_ingress/CODE_REVIEW-cloud-G10.md` | API-1, API-2, API-3 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` +2. `go test -race ./apps/edge/internal/service -run 'TestSingleRequest' -count=1` +3. `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` +4. `rg --sort path -n 'single-request|one POST|repairing|tool_use|count_tokens' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` +5. `go test ./apps/edge/internal/service ./apps/edge/internal/openai -count=1` +6. `go vet ./apps/edge/...` +7. `go test ./apps/edge/... -count=1` +8. `git diff --check` + +Expected: exactly one predecessor evidence candidate exists; service race/state tests pass; one real marked handler POST increments the runtime Edge ingress counter by exactly one and yields one sanitized final/error without caller continuation; generic regressions pass. Concrete workspace execution and actual Claude smoke remain unclaimed. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/CODE_REVIEW-cloud-G06.md b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/CODE_REVIEW-cloud-G06.md new file mode 100644 index 00000000..cee7dcc5 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/CODE_REVIEW-cloud-G06.md @@ -0,0 +1,128 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/04+02_preset_refresh, plan=1, tag=API + +## Archive Evidence Snapshot + +- Superseded refined pair: `plan_local_G05_0.log`, `code_review_cloud_G06_0.log`. +- The superseded pair and its split parent contained no implementation evidence or review verdict; implementation has not started. +- Fresh-review correction: retain live-refresh/schema ownership, use the exact predecessor archive candidate pattern, and restore the required Edge vet baseline. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_1.log` and `PLAN-local-G05.md` → `plan_local_G05_1.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=preset-binding` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-2 Preserve refresh semantics and publish the schema | [ ] | + +## Implementation Checklist + +- [ ] Classify fixed single-request policy changes as live-applied, add a secret-free commented config example, and synchronize the config contract and current implementation spec. +- [ ] Run dependency, targeted config-refresh, Edge vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G06_1.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G05_1.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=preset-binding` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 02 completion evidence existed before implementation and transitively includes packet 01. +- Policy changes are reported at the exact `single_request` path as live-applied. +- Refresh affects only new request snapshots; admitted requests keep their generation. +- YAML/docs contain no secret, endpoint, credential, Node id, or raw path. +- Documents do not claim coordinator, workspace execution, or provider completion. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` + +_Actual output/status:_ + +### Refresh classification + +Command: `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/configrefresh -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/PLAN-local-G05.md b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/PLAN-local-G05.md new file mode 100644 index 00000000..83cb03ba --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/PLAN-local-G05.md @@ -0,0 +1,149 @@ + + +# Fixed Single-request Preset Refresh and Schema + +## For the Implementing Agent + +Do not start until packet 02 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G06.md` with actual notes and stdout/stderr, keep both active files in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Superseded refined pair: `plan_local_G05_0.log`, `code_review_cloud_G06_0.log`. +- The superseded pair and its split parent contained no implementation evidence or review verdict; implementation has not started. +- Fresh-review correction: retain live-refresh/schema ownership, use the exact predecessor archive candidate pattern, and restore the required Edge vet baseline. + +## Background + +Packet 01 introduces the operator-owned fixed single-request policy. SDD S02 also requires live-refresh generation isolation and an operator-visible schema without leaking endpoint, credential, Node, or raw workspace values. + +## Analysis + +### Files Read + +- `apps/edge/internal/configrefresh/classify.go` +- `apps/edge/internal/configrefresh/execution_preset_classify_test.go` +- `configs/edge.yaml` +- `agent-contract/inner/edge-config-runtime-refresh.md` +- `agent-spec/runtime/provider-pool-config-refresh.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` + +### SDD Criteria + +- SDD status is approved and its implementation lock is released. +- First-line Milestone task: `preset-binding`; targeted Acceptance Scenario: S02. +- This child supplies refresh-path and published-schema evidence. Packet 01 owns decode/validation/cloning, while packet 02 owns authorization/model echo and request-start binding isolation. + +### Verification Context + +- The parent packet selected focused config-refresh tests, Edge regression, and `git diff --check`; the Edge profile also requires `go vet ./apps/edge/...`, restored here. +- Precondition: packet 02 completion. This sequencing avoids concurrent writes to `agent-spec/runtime/provider-pool-config-refresh.md` while retaining packet 01 transitively. + +### Test Coverage Gaps + +- Existing refresh tests do not report the fixed single-request policy as its own live-applied path or prove deterministic previous/next value capture. + +### Symbol References + +- No symbol is renamed or removed. `appendExecutionPresetChanges` is the existing classifier extended by this child. + +### Split Judgment + +- Stable result: the typed policy is classified as a live-applied request-generation change and published without claiming runtime execution. +- The production classifier and its executable test remain together; the config example, contract, and spec describe that same behavior. + +### Scope Rationale + +- Exclude config type/validation, route authorization, handlers, provider execution, Node/workspace execution, protobuf, and SSE. +- Document exact absolute caps and new-request snapshot semantics only. Do not claim coordinator or real-provider execution. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures scope/context/verification/evidence/ownership/decision are true; scores 1/1/1/1/1 = G05; base/final route `local-fit`; lane `local`; canonical filename `PLAN-local-G05.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `boundary_contract`, `concurrent_consistency`, `variant_product` (3); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/1/1/1/1 = G06; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G06.md`. + +## Dependencies and Execution Order + +1. Verify packet 02 completion evidence; it transitively includes packet 01's typed policy and serializes the shared refresh spec write. +2. Add the classifier path and focused test. +3. Publish the secret-free example, contract, and current spec, then run Edge regression. + +## Implementation Checklist + +- [ ] Classify fixed single-request policy changes as live-applied, add a secret-free commented config example, and synchronize the config contract and current implementation spec. +- [ ] Run dependency, targeted config-refresh, Edge vet, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-2] Preserve refresh semantics and publish the schema + +**Problem** + +- `apps/edge/internal/configrefresh/classify.go:371` compares selector, modes, routes, and workspace tools but cannot report the fixed single-request policy independently. +- `configs/edge.yaml:340`, `agent-contract/inner/edge-config-runtime-refresh.md:62`, and `agent-spec/runtime/provider-pool-config-refresh.md:93` publish generic model/preset refresh only and do not describe a secret-free fixed single-request generation. + +**Solution** + +Before (`apps/edge/internal/configrefresh/classify.go:383`): + +```go +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].routes", id), StatusApplied, cur.Routes, next.Routes) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].workspace_tools", id), StatusApplied, cur.WorkspaceTools, next.WorkspaceTools) +``` + +After: + +```go +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].routes", id), StatusApplied, cur.Routes, next.Routes) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].single_request", id), StatusApplied, cur.SingleRequest, next.SingleRequest) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].workspace_tools", id), StatusApplied, cur.WorkspaceTools, next.WorkspaceTools) +``` + +Classify the policy as live-applied and document the exact absolute caps plus the rule that refresh affects only new request snapshots. Add only a commented, secret-free YAML example; synchronize contract/spec without claiming runtime execution. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/configrefresh/classify.go` — emit the precise single-request change path. +- [ ] `apps/edge/internal/configrefresh/execution_preset_classify_test.go` — prove value capture and deterministic ordering. +- [ ] `configs/edge.yaml` — add a commented fixed-light example only. +- [ ] `agent-contract/inner/edge-config-runtime-refresh.md` — define validation, compatibility, refresh generation, and secret rules. +- [ ] `agent-spec/runtime/provider-pool-config-refresh.md` — synchronize current schema and executable evidence. + +**Test Strategy** + +- Extend `TestClassifyExecutionPresetLiveApply` with differing policy snapshots and assert the exact sorted change path plus previous/next values. +- Use packet 01's config loader tests as the decoder/validator oracle; no external config smoke is needed. + +**Verification** + +- `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` +- Expected: the classifier reports the policy path as applied with deterministic ordering. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/configrefresh/classify.go` | API-2 | +| `apps/edge/internal/configrefresh/execution_preset_classify_test.go` | API-2 | +| `configs/edge.yaml` | API-2 | +| `agent-contract/inner/edge-config-runtime-refresh.md` | API-2 | +| `agent-spec/runtime/provider-pool-config-refresh.md` | API-2 | +| `agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/CODE_REVIEW-cloud-G06.md` | API-2 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' | wc -l)" -eq 1` +2. `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` +3. `go test ./apps/edge/internal/configrefresh -count=1` +4. `go vet ./apps/edge/...` +5. `go test ./apps/edge/... -count=1` +6. `git diff --check` + +Expected: all commands exit 0; predecessor evidence exists; refresh reports the fixed policy path with deterministic values; the example and documents remain secret-free. Runtime authorization and coordinator execution remain outside this child. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/code_review_cloud_G06_0.log b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/code_review_cloud_G06_0.log new file mode 100644 index 00000000..132aa316 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/code_review_cloud_G06_0.log @@ -0,0 +1,127 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/05+02_preset_refresh, plan=0, tag=API + +## Archive Evidence Snapshot + +- Split parent pair: `../01_preset_config/plan_local_G07_1.log`, `../01_preset_config/code_review_cloud_G07_1.log`. +- The split parent contained no implementation evidence or review verdict; implementation has not started. +- This child retains only live-refresh classification, the secret-free example, and config contract/spec synchronization. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_0.log` and `PLAN-local-G05.md` → `plan_local_G05_0.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/05+02_preset_refresh/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=preset-binding` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-2 Preserve refresh semantics and publish the schema | [ ] | + +## Implementation Checklist + +- [ ] Classify fixed single-request policy changes as live-applied, add a secret-free commented config example, and synchronize the config contract and current implementation spec. +- [ ] Run dependency, targeted config-refresh, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G06_0.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_local_G05_0.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/05+02_preset_refresh/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/05+02_preset_refresh/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=preset-binding` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 02 completion evidence existed before implementation and transitively includes packet 01. +- Policy changes are reported at the exact `single_request` path as live-applied. +- Refresh affects only new request snapshots; admitted requests keep their generation. +- YAML/docs contain no secret, endpoint, credential, Node id, or raw path. +- Documents do not claim coordinator, workspace execution, or provider completion. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' -print | sort | grep -q .` + +_Actual output/status:_ + +### Refresh classification + +Command: `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/configrefresh -count=1` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/plan_local_G05_0.log b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/plan_local_G05_0.log new file mode 100644 index 00000000..3dd821cd --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/04+02_preset_refresh/plan_local_G05_0.log @@ -0,0 +1,146 @@ + + +# Fixed Single-request Preset Refresh and Schema + +## For the Implementing Agent + +Do not start until packet 02 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G06.md` with actual notes and stdout/stderr, keep both active files in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Split parent pair: `../01_preset_config/plan_local_G07_1.log`, `../01_preset_config/code_review_cloud_G07_1.log`. +- The split parent contained no implementation evidence or review verdict; implementation has not started. +- This child retains only live-refresh classification, the secret-free example, and config contract/spec synchronization. + +## Background + +Packet 01 introduces the operator-owned fixed single-request policy. SDD S02 also requires live-refresh generation isolation and an operator-visible schema without leaking endpoint, credential, Node, or raw workspace values. + +## Analysis + +### Files Read + +- `apps/edge/internal/configrefresh/classify.go` +- `apps/edge/internal/configrefresh/execution_preset_classify_test.go` +- `configs/edge.yaml` +- `agent-contract/inner/edge-config-runtime-refresh.md` +- `agent-spec/runtime/provider-pool-config-refresh.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` + +### SDD Criteria + +- SDD status is approved and its implementation lock is released. +- First-line Milestone task: `preset-binding`; targeted Acceptance Scenario: S02. +- This child supplies refresh-path and published-schema evidence. Packet 01 owns decode/validation/cloning, while packet 02 owns authorization/model echo and request-start binding isolation. + +### Verification Context + +- The parent packet selected focused config-refresh tests, Edge regression, and `git diff --check`; this child preserves that subset. +- Precondition: packet 02 completion. This sequencing avoids concurrent writes to `agent-spec/runtime/provider-pool-config-refresh.md` while retaining packet 01 transitively. + +### Test Coverage Gaps + +- Existing refresh tests do not report the fixed single-request policy as its own live-applied path or prove deterministic previous/next value capture. + +### Symbol References + +- No symbol is renamed or removed. `appendExecutionPresetChanges` is the existing classifier extended by this child. + +### Split Judgment + +- Stable result: the typed policy is classified as a live-applied request-generation change and published without claiming runtime execution. +- The production classifier and its executable test remain together; the config example, contract, and spec describe that same behavior. + +### Scope Rationale + +- Exclude config type/validation, route authorization, handlers, provider execution, Node/workspace execution, protobuf, and SSE. +- Document exact absolute caps and new-request snapshot semantics only. Do not claim coordinator or real-provider execution. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures scope/context/verification/evidence/ownership/decision are true; scores 1/1/1/1/1 = G05; base/final route `local-fit`; lane `local`; canonical filename `PLAN-local-G05.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `boundary_contract`, `concurrent_consistency`, `variant_product` (3); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/1/1/1/1 = G06; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G06.md`. + +## Dependencies and Execution Order + +1. Verify packet 02 completion evidence; it transitively includes packet 01's typed policy and serializes the shared refresh spec write. +2. Add the classifier path and focused test. +3. Publish the secret-free example, contract, and current spec, then run Edge regression. + +## Implementation Checklist + +- [ ] Classify fixed single-request policy changes as live-applied, add a secret-free commented config example, and synchronize the config contract and current implementation spec. +- [ ] Run dependency, targeted config-refresh, full Edge regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-2] Preserve refresh semantics and publish the schema + +**Problem** + +- `apps/edge/internal/configrefresh/classify.go:371` compares selector, modes, routes, and workspace tools but cannot report the fixed single-request policy independently. +- `configs/edge.yaml` and the refresh contract/spec do not describe a secret-free fixed single-request generation. + +**Solution** + +Before (`apps/edge/internal/configrefresh/classify.go:383`): + +```go +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].routes", id), StatusApplied, cur.Routes, next.Routes) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].workspace_tools", id), StatusApplied, cur.WorkspaceTools, next.WorkspaceTools) +``` + +After: + +```go +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].routes", id), StatusApplied, cur.Routes, next.Routes) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].single_request", id), StatusApplied, cur.SingleRequest, next.SingleRequest) +appendDeepIfChanged(changes, fmt.Sprintf("execution_presets[%q].workspace_tools", id), StatusApplied, cur.WorkspaceTools, next.WorkspaceTools) +``` + +Classify the policy as live-applied and document the exact absolute caps plus the rule that refresh affects only new request snapshots. Add only a commented, secret-free YAML example; synchronize contract/spec without claiming runtime execution. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/configrefresh/classify.go` — emit the precise single-request change path. +- [ ] `apps/edge/internal/configrefresh/execution_preset_classify_test.go` — prove value capture and deterministic ordering. +- [ ] `configs/edge.yaml` — add a commented fixed-light example only. +- [ ] `agent-contract/inner/edge-config-runtime-refresh.md` — define validation, compatibility, refresh generation, and secret rules. +- [ ] `agent-spec/runtime/provider-pool-config-refresh.md` — synchronize current schema and executable evidence. + +**Test Strategy** + +- Extend `TestClassifyExecutionPresetLiveApply` with differing policy snapshots and assert the exact sorted change path plus previous/next values. +- Use packet 01's config loader tests as the decoder/validator oracle; no external config smoke is needed. + +**Verification** + +- `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` +- Expected: the classifier reports the policy path as applied with deterministic ordering. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/configrefresh/classify.go` | API-2 | +| `apps/edge/internal/configrefresh/execution_preset_classify_test.go` | API-2 | +| `configs/edge.yaml` | API-2 | +| `agent-contract/inner/edge-config-runtime-refresh.md` | API-2 | +| `agent-spec/runtime/provider-pool-config-refresh.md` | API-2 | +| `agent-task/m-iop-owned-single-request-agent-execution/05+02_preset_refresh/CODE_REVIEW-cloud-G06.md` | API-2 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log || find agent-task/archive -type f -path '*/m-iop-owned-single-request-agent-execution/02+01_preset_binding/complete.log' -print | sort | grep -q .` +2. `go test ./apps/edge/internal/configrefresh -run 'TestClassifyExecutionPresetLiveApply$' -count=1` +3. `go test ./apps/edge/internal/configrefresh -count=1` +4. `go test ./apps/edge/... -count=1` +5. `git diff --check` + +Expected: all commands exit 0; predecessor evidence exists; refresh reports the fixed policy path with deterministic values; the example and documents remain secret-free. Runtime authorization and coordinator execution remain outside this child. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/CODE_REVIEW-cloud-G10.md b/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/CODE_REVIEW-cloud-G10.md new file mode 100644 index 00000000..103c5c80 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/CODE_REVIEW-cloud-G10.md @@ -0,0 +1,142 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/05+03_single_ingress, plan=0, tag=API + +## Archive Evidence Snapshot + +- Refined parent evidence is retained in packet 03 as `plan_cloud_G09_2.log` and `code_review_cloud_G10_2.log`; earlier intent remains in its sibling logs `0` and `1`. +- The parent pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction preserved here: S01 requires a runtime Edge ingress counter plus a real HTTP POST counter-delta assertion, not only a test-local handler count. +- Split allocation: packet 03 owns the surface-neutral coordinator/state machine and runtime spec. This child owns marked HTTP admission, bounded ingress observation, endpoint integration tests, and outer/input documentation. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G10.md` → `code_review_cloud_G10_0.log` and `PLAN-cloud-G09.md` → `plan_cloud_G09_0.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/05+03_single_ingress/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=single-ingress` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Admit and observe one marked Anthropic request | [ ] | +| API-2 Synchronize the marked HTTP boundary | [ ] | + +## Implementation Checklist + +- [ ] Route marked Anthropic Messages requests through packet 03's separate service capability before legacy admission, while preserving immutable binding and public model echo. +- [ ] Record exactly one accepted marked ingress in a registered bounded Edge counter with no request-derived labels and never increment per internal stage. +- [ ] Prove one real HTTP POST, runtime counter delta `+1`, one sanitized terminal, acknowledgement behavior, privacy, and unmarked/count-tokens compatibility. +- [ ] Synchronize the outer contract and input spec without claiming streaming projection, concrete workspace/provider execution, or actual Claude smoke. +- [ ] Run exact dependency, focused endpoint, documentation, package, vet, full Edge, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G10_0.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_cloud_G09_0.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/05+03_single_ingress/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=single-ingress` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 03 completion evidence existed before implementation. +- Marked admission occurs after validation/authorization and before legacy pool/caller continuation. +- `runService` is unchanged; only marked dispatch requires the narrow optional capability. +- Exactly one real HTTP POST increments the registered runtime Edge ingress counter by exactly one across all internal stages. +- The counter has no request-derived labels and is not incremented per stage, retry, event, or terminal. +- Public model echo is preserved; output has no reasoning, tool wire, provider/route/credential/workspace values, or caller `tool_use` continuation. +- Success acknowledgement follows the terminal write; failure and cancellation notify the execution handle. +- Unmarked Anthropic, Chat, and count-tokens compatibility remains unchanged. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/complete.log' | wc -l)" -eq 1` + +_Actual output/status:_ + +### One runtime-counted ingress and compatibility + +Command: `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` + +_Actual output:_ + +### Documentation + +Command: `rg --sort path -n 'single-request|one POST|ingress|tool_use|count_tokens|defer' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test ./apps/edge/internal/openai -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/PLAN-cloud-G09.md b/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/PLAN-cloud-G09.md new file mode 100644 index 00000000..88168849 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/PLAN-cloud-G09.md @@ -0,0 +1,267 @@ + + +# Single-request Anthropic Ingress and Runtime Evidence + +## For the Implementing Agent + +Do not start until packet 03 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G10.md` with actual notes and stdout/stderr, keep the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Refined parent evidence is retained in packet 03 as `plan_cloud_G09_2.log` and `code_review_cloud_G10_2.log`; earlier intent remains in its sibling logs `0` and `1`. +- The parent pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-context correction preserved here: S01 requires a runtime Edge ingress counter plus a real HTTP POST counter-delta assertion, not only a test-local handler count. +- Split allocation: packet 03 owns the surface-neutral coordinator/state machine and runtime spec. This child owns marked HTTP admission, bounded ingress observation, endpoint integration tests, and outer/input documentation. + +## Background + +After packet 03 exposes the surface-neutral coordinator, the marked Anthropic path must admit exactly one `/v1/messages` request, bypass legacy caller continuation, drive every internal stage through that coordinator, and return one sanitized buffered result or failure. S01 requires the real HTTP boundary and a runtime Edge ingress counter as evidence. + +## Analysis + +### Files Read + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `agent-ops/rules/common/rules-roadmap.md` +- `agent-ops/rules/common/rules-agent-spec.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` +- `apps/edge/internal/openai/server.go` +- `apps/edge/internal/openai/route_resolution.go` +- `apps/edge/internal/openai/anthropic_handler.go` +- `apps/edge/internal/openai/anthropic_types.go` +- `apps/edge/internal/openai/request_identity_ingress.go` +- `apps/edge/internal/openai/hot_path_direct.go` +- `apps/edge/internal/openai/hot_path_metrics.go` +- `apps/edge/internal/openai/anthropic_surface_test.go` +- `apps/edge/internal/openai/request_identity_handler_test.go` +- `apps/edge/internal/openai/provider_test_support_test.go` +- `agent-contract/outer/anthropic-compatible-api.md` +- `agent-spec/input/openai-compatible-surface.md` + +### SDD Criteria + +- SDD status is approved and its implementation lock is released. +- First-line Milestone task: `single-ingress`; targeted Acceptance Scenario: S01. +- S01 requires one actual `/v1/messages` POST, a runtime Edge ingress counter, immutable identity, full internal multi-stage execution behind the coordinator/API boundary, and one final/error. This packet supplies the HTTP/counter evidence on packet 03's coordinator foundation. + +### Verification Context + +- No separate verification handoff was supplied. Repository-native fallback is the Anthropic handler/identity suite, existing bounded metric pattern, Edge smoke profile, outer contract, input spec, and approved SDD. +- Precondition: packet 03 completion. Constraints: current checkout only; no external provider/runner; a deterministic multi-stage fake drives the coordinator. +- A real `httptest.Server` request and runtime Prometheus counter delta are the direct one-ingress oracle. Endpoint regressions, vet, and full Edge tests guard compatibility. + +### State and Concurrency Findings + +- Marked admission must occur after validation/authorization and before legacy pool/caller-continuation execution. +- The handler writes one sanitized terminal and acknowledges success only after that write; write failure or cancellation must notify the request-scoped execution handle. +- The ingress counter records accepted marked HTTP admission once, never per stage, retry, event, or terminal. + +### Test Coverage Gaps + +- Existing endpoint tests do not send one real marked POST through an HTTP server across a multi-stage fake. +- No registered runtime metric records accepted single-request ingress, and a test-local call count cannot satisfy S01. +- No endpoint test proves the marked branch avoids caller `tool_use` continuation while preserving unmarked Anthropic, Chat, and count-tokens behavior. + +### Symbol References + +- `runService` is implemented by `*service.Service` and multiple OpenAI test fakes; do not widen it. +- `routeDispatch` carries packet 02's immutable binding; `handleAnthropicMessages` is the marked branch point. +- Use packet 03's separate single-request service capability only for marked dispatch. + +### Refine Judgment + +- This is the ingress integration child produced by the one-time refinement of the corrected parent. +- Its handler, runtime counter, real-POST test, and public contract form one boundary-verification unit; further splitting would leave no independently PASS-capable HTTP claim. + +### Scope Rationale + +- Include marked Anthropic admission, the no-request-label runtime ingress counter, buffered result/failure translation, endpoint tests, and outer/input documentation. +- Exclude service coordinator internals, SSE projection, generic relay changes, concrete Node/workspace/provider protocol, latency/outcome metrics, and actual Claude smoke. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures are true; scores 2/2/2/1/2 = G09; base/final route `grade-boundary`; lane `cloud`; canonical filename `PLAN-cloud-G09.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `temporal_state`, `concurrent_consistency`, `boundary_contract`, `variant_product` (4); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/2/2/2/2 = G10; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G10.md`. + +## Dependencies and Execution Order + +1. Verify exactly one packet 03 completion candidate, preferring the active path. +2. Wire a separate optional single-request capability without widening `runService`. +3. Add marked HTTP admission and the bounded runtime ingress counter before legacy continuation. +4. Prove one real POST and counter delta `+1`, then synchronize outer/input documentation and run regressions. + +## Implementation Checklist + +- [ ] Route marked Anthropic Messages requests through packet 03's separate service capability before legacy admission, while preserving immutable binding and public model echo. +- [ ] Record exactly one accepted marked ingress in a registered bounded Edge counter with no request-derived labels and never increment per internal stage. +- [ ] Prove one real HTTP POST, runtime counter delta `+1`, one sanitized terminal, acknowledgement behavior, privacy, and unmarked/count-tokens compatibility. +- [ ] Synchronize the outer contract and input spec without claiming streaming projection, concrete workspace/provider execution, or actual Claude smoke. +- [ ] Run exact dependency, focused endpoint, documentation, package, vet, full Edge, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Admit and observe one marked Anthropic request + +**Problem** + +- `apps/edge/internal/openai/anthropic_handler.go:101` resolves dispatch and then reaches the legacy pool/caller-continuation path at line 108 without a marked one-request branch. +- `apps/edge/internal/openai/server.go:23` defines the widely faked `runService`; widening it would break unrelated fakes and couple the capability to every endpoint. +- `apps/edge/internal/openai/hot_path_metrics.go:112` owns current Hot Path collectors but has no runtime Edge counter for accepted marked ingress, so a handler-local count cannot satisfy S01. + +**Solution** + +Before (`apps/edge/internal/openai/server.go:23`): + +```go +type runService interface { + SubmitRun(context.Context, edgeservice.SubmitRunRequest) (edgeservice.RunResult, error) + SubmitProviderTunnel(context.Context, edgeservice.SubmitProviderTunnelRequest) (edgeservice.ProviderTunnelResult, error) + SubmitProviderPool(context.Context, edgeservice.ProviderPoolDispatchRequest) (*edgeservice.ProviderPoolDispatchResult, error) + OllamaAPI(context.Context, edgeservice.OllamaAPIRequest) (edgeservice.OllamaAPIView, error) + CancelRun(context.Context, edgeservice.CancelRunRequest) (edgeservice.CommandResult, error) +} +``` + +After, without changing `runService`: + +```go +type singleRequestService interface { + StartSingleRequest(context.Context, edgeservice.SingleRequestRequest) (edgeservice.SingleRequestExecution, error) +} +``` + +Before (`apps/edge/internal/openai/anthropic_handler.go:101`): + +```go +dispatch, err := s.resolveRouteDispatchForPrincipal(r.Context(), envelope.Model) +if err != nil || !dispatch.ProviderPool { + s.writeAnthropicRouteError(w, err) + return +} + +needsTools := anthropicRequestNeedsTools(body) +poolReq, presetIngress, err := s.anthropicPoolRequest(r, dispatch, envelope, body, config.OperationMessages, needsTools) +``` + +After: + +```go +dispatch, err := s.resolveRouteDispatchForPrincipal(r.Context(), envelope.Model) +// Existing authorization failure remains fail-closed. +if dispatch.SingleRequest != nil { + capability, ok := s.service.(singleRequestService) + if !ok { + s.writeSingleRequestUnavailable(w) + return + } + recordSingleRequestIngress() + s.handleAnthropicSingleRequest(w, r, capability, dispatch, envelope, body) + return +} +// Existing generic pool path remains unchanged below. +``` + +In `single_request_metrics.go`, declare complete imports for the already-present Prometheus dependency: + +```go +import ( + "github.com/prometheus/client_golang/prometheus" + "github.com/prometheus/client_golang/prometheus/promauto" +) + +var singleRequestIngressTotal = promauto.NewCounter(prometheus.CounterOpts{ + Name: "iop_anthropic_single_request_ingress_total", + Help: "Accepted marked Anthropic single-request ingress.", +}) +``` + +For marked dispatch only, branch after validation/authorization and before pool/legacy continuation; copy request input and binding, preserve the public model, and translate one buffered sanitized final/error. Increment the counter exactly once when the marked request is accepted, not per internal stage or retry. Acknowledge success only after the dedicated response encoder reports that the terminal write succeeded; propagate write failure/cancellation to the handle. Never return caller `tool_use` or re-enter the generic branch. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/server.go` — declare/wire the separate optional single-request capability without expanding `runService`. +- [ ] `apps/edge/internal/openai/anthropic_handler.go` — branch marked admission before legacy execution and translate buffered final/error output. +- [ ] `apps/edge/internal/openai/single_request_metrics.go` — own the registered bounded Edge ingress counter without request-derived labels. +- [ ] `apps/edge/internal/openai/single_request_handler_test.go` — send one real POST through `httptest.Server`, assert counter delta `+1`, drive multi-stage/repair events, and cover acknowledgement, privacy, unavailability, failure, and cancellation. + +**Test Strategy** + +- `TestAnthropicSingleRequestUsesOnePost` snapshots the registered counter, sends one real HTTP POST through `httptest.Server`, drives multiple internal stages, and asserts a delta of exactly one plus one response terminal. +- Add repair success, terminal-write acknowledgement/failure, missing capability, executor failure/cancel, public-model, private-sentinel, and no-caller-`tool_use` cases. +- Rerun existing preset identity and count-tokens tests unchanged. + +**Verification** + +- `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` +- Expected: one real marked POST increments the runtime ingress counter exactly once across multi-stage execution and returns one sanitized terminal; generic continuation/count-tokens behavior is unchanged. + +### [API-2] Synchronize the marked HTTP boundary + +**Problem** + +- `agent-contract/outer/anthropic-compatible-api.md:24` scopes the generic Anthropic-compatible boundary but has no marked single-request exception. +- `agent-spec/input/openai-compatible-surface.md:132` describes shared Messages ingress but does not distinguish the coordinator-backed path or its runtime evidence. + +**Solution** + +Before (`agent-spec/input/openai-compatible-surface.md:132`): + +```markdown +| Anthropic ingress | `POST /v1/messages` and `POST /anthropic/v1/messages` share one handler; the corresponding count-tokens paths share another. `/anthropic/v1/models`, and `/v1/models` with `anthropic-version`, return the Anthropic model-list shape. Wrong methods return `405 invalid_request_error`. | +``` + +After, add a separate marked-path row and matching outer-contract subsection: + +```markdown +| marked single-request ingress | One authorized Messages POST freezes the coordinator binding, increments one Edge ingress counter, never returns caller `tool_use`, and commits one sanitized terminal on the same request. | +``` + +Document public model retention, same-request sanitized failure, terminal acknowledgement, and unchanged generic Anthropic/Chat/count-tokens behavior. Keep SSE projection and concrete workspace/provider integration explicitly deferred. + +**Modified Files and Checklist** + +- [ ] `agent-contract/outer/anthropic-compatible-api.md` — define one-ingress semantics, compatibility, runtime evidence, and private/public boundaries. +- [ ] `agent-spec/input/openai-compatible-surface.md` — synchronize marked handler behavior, counter evidence, and explicit deferrals. + +**Test Strategy** + +- Skip a standalone documentation-only test because API-1's named real-POST/counter/privacy/compatibility cases are the executable contract oracle. + +**Verification** + +- `rg --sort path -n 'single-request|one POST|ingress|tool_use|count_tokens|defer' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md` +- Expected: marked one-ingress behavior and deferrals are explicit while generic compatibility remains documented. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/openai/server.go` | API-1 | +| `apps/edge/internal/openai/anthropic_handler.go` | API-1 | +| `apps/edge/internal/openai/single_request_metrics.go` | API-1 | +| `apps/edge/internal/openai/single_request_handler_test.go` | API-1 | +| `agent-contract/outer/anthropic-compatible-api.md` | API-2 | +| `agent-spec/input/openai-compatible-surface.md` | API-2 | +| `agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/CODE_REVIEW-cloud-G10.md` | API-1, API-2 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/03+02_single_request_coordinator/complete.log' | wc -l)" -eq 1` +2. `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequest|PresetRequestIdentityAcrossAnthropicTurns|PresetRequestIdentityAnthropicCountTokensBypassesCoordinator)' -count=1` +3. `rg --sort path -n 'single-request|one POST|ingress|tool_use|count_tokens|defer' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md` +4. `go test ./apps/edge/internal/openai -count=1` +5. `go vet ./apps/edge/...` +6. `go test ./apps/edge/... -count=1` +7. `git diff --check` + +Expected: exactly one packet 03 completion candidate exists; one real marked POST increments the registered runtime Edge ingress counter by exactly one and yields one sanitized terminal without caller continuation; compatibility and all Edge checks pass. Streaming projection, concrete workspace execution, and actual Claude smoke remain unclaimed. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/CODE_REVIEW-cloud-G10.md b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/CODE_REVIEW-cloud-G10.md new file mode 100644 index 00000000..f4ef2efa --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/CODE_REVIEW-cloud-G10.md @@ -0,0 +1,146 @@ + + +# Code Review Reference - API + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. +> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. +> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. +> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## Overview + +date=2026-08-06 +task=m-iop-owned-single-request-agent-execution/06+05_stream_terminal, plan=2, tag=API + +## Archive Evidence Snapshot + +- Superseded pair: `plan_cloud_G09_1.log`, `code_review_cloud_G10_1.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-review correction: preserve the closed repair-aware projector scope, and replace the broad archive scan with the exact predecessor candidate pattern required by the split dependency protocol. + +## For the Review Agent + +> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section. + +Compare implementation of each item against source files and verify that output in `Verification Results` matches code. +Review completion means the following steps are finished: + +1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals. +2. Archive `CODE_REVIEW-cloud-G10.md` → `code_review_cloud_G10_2.log` and `PLAN-cloud-G09.md` → `plan_cloud_G09_2.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve `milestone-task=stream-terminal` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`. +5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting. + +--- + +## Implementation Item Completion + +| Item | Status | +|------|--------| +| API-1 Add a privacy-closed Anthropic stream projector | [ ] | +| API-2 Pump coordinator progress and liveness on the same request | [ ] | +| API-3 Synchronize SSE and compatibility contracts | [ ] | + +## Implementation Checklist + +- [ ] Implement a serialized single-request Anthropic SSE projector with one envelope, fixed plan/work/review/repair summaries, liveness ping, final text/error, and exactly-once terminal ownership. +- [ ] Integrate it only with the marked coordinator stream, stop and join liveness before terminal/return, acknowledge service completion only after the one wire terminal succeeds, and prove one POST plus no private wire across fragmented multi-stage and repair events. +- [ ] Preserve ordinary Anthropic/Hot Path behavior and synchronize the outer contract and current specs without expanding generic Stream Evidence Gate semantics. +- [ ] Run dependency, exact-wire race, package, vet, full Edge/streamgate regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent. +> Implementing agents must not modify or check this section. + +- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`. +- [ ] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match. +- [ ] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G10_2.log`. +- [ ] Archive active `PLAN-*-G??.md` to `plan_cloud_G09_2.log`. +- [ ] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`. +- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files. +- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/` and update this checklist at the final archive path. +- [ ] If PASS, preserve and report `milestone-task=stream-terminal` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`. +- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files. +- [ ] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`. + +## Deviations from Plan + +_Record any deviations from the plan and the rationale here._ + +## Key Design Decisions + +_Record key design decisions here._ + +## Reviewer Checkpoints + +- Packet 05 completion evidence existed before implementation; packet 03's transitive public event types were reused. +- Closed progress includes defect/repair and rejects unknown/arbitrary strings. +- One lock owns block indices, pings, flushes, and terminal selection. +- Ping worker is stopped and joined before terminal/return; post-terminal bytes never change. +- Service completion is acknowledged only after `message_stop`; write failure/disconnect cannot also complete. +- Exact wire contains no reasoning, tool/provider/route/credential/workspace/raw-command sentinels. +- Ordinary Anthropic/Hot Path and Stream Evidence Gate behavior is unchanged. + +## Verification Results + +### Dependency + +Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log' | wc -l)" -eq 1` + +_Actual output/status:_ + +### Exact-wire and terminal race + +Command: `go test -race ./apps/edge/internal/openai -run 'TestSingleRequestAnthropicStream' -count=1` + +_Actual output:_ + +### Integration and compatibility + +Command: `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequestStreaming|AnthropicSingleRequestStream|HotPathAnthropic)' -count=1` + +_Actual output:_ + +### Documentation + +Command: `rg --sort path -n 'single-request|repair|event: ping|message_start|message_stop|private|tool_use' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/stream-evidence-gate.md` + +_Actual output:_ + +### Final regression + +Commands: + +- `go test -race ./apps/edge/internal/openai -count=1` +- `go vet ./apps/edge/...` +- `go test ./apps/edge/... ./packages/go/streamgate/... -count=1` +- `git diff --check` + +_Actual output:_ + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## Section Ownership + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only | +| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section | +| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content | +| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan | +| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry | +| Code Review Result | Review agent appends | Not included in stub | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/PLAN-cloud-G09.md b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/PLAN-cloud-G09.md new file mode 100644 index 00000000..fdcbfcea --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/PLAN-cloud-G09.md @@ -0,0 +1,269 @@ + + +# Single-request Anthropic SSE Projection + +## For the Implementing Agent + +Do not start until packet 05 has `complete.log`. Implement this plan exactly within the listed write boundary, run every verification command, fill all implementation-owned sections of `CODE_REVIEW-cloud-G10.md` with actual notes and stdout/stderr, keep the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and the resume condition; do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`. + +## Archive Evidence Snapshot + +- Superseded pair: `plan_cloud_G09_1.log`, `code_review_cloud_G10_1.log`. +- The superseded pair contained no implementation evidence or review verdict; implementation has not started. +- Fresh-review correction: preserve the closed repair-aware projector scope, and replace the broad archive scan with the exact predecessor candidate pattern required by the split dependency protocol. + +## Background + +The generic Anthropic Hot Path codec can expose normalized reasoning and tool blocks and is scoped to a caller turn. SDD S03 requires a stricter endpoint projector for the single-request coordinator: one envelope, fixed redacted plan/work/review/repair progress, liveness ping, no private internal wire, and exactly one endpoint-native terminal after all internal work. + +## Analysis + +### Files Read + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `agent-ops/rules/common/rules-roadmap.md` +- `agent-ops/rules/common/rules-agent-spec.md` +- `agent-ops/rules/project/domain/edge/rules.md` +- `agent-ops/rules/project/domain/platform-common/rules.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-test/local/platform-common-smoke.md` +- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md` +- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md` +- `apps/edge/internal/openai/anthropic_handler.go` +- `apps/edge/internal/openai/anthropic_stream.go` +- `apps/edge/internal/openai/hot_path_direct.go` +- `apps/edge/internal/openai/hot_path_anthropic_gate_test.go` +- `apps/edge/internal/openai/request_identity_handler_test.go` +- `agent-contract/outer/anthropic-compatible-api.md` +- `agent-spec/input/openai-compatible-surface.md` +- `agent-spec/runtime/stream-evidence-gate.md` + +### SDD Criteria + +- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md`; status approved and implementation lock released. +- First-line Milestone task: `stream-terminal`; targeted Acceptance Scenario: S03. +- Evidence Map row S03 requires fragmented multi-stage SSE with fixed redacted progress/ping, one envelope, collision-free blocks, forbidden-private-value absence, and exactly one terminal. Those facts directly shape API-1/API-2 and the exact-wire/race commands in Final Verification. + +### Verification Context + +- No separate verification handoff was supplied. Repository-native fallback came from the current Anthropic codec/framing helper, Hot Path exact-wire and terminal race tests, Edge/platform test profiles, outer contract, and approved SDD. +- Precondition: packet 05 completion, which transitively includes packet 03's coordinator. Constraints: in-process deterministic writer/manual tick verification only; no external provider/runner. Gap: real Claude liveness remains later Milestone smoke evidence. +- Commands use exact-wire race tests, marked/generic endpoint regressions, deterministic doc search, `go vet`, full Edge/streamgate regression, and `git diff --check`. Confidence is high for framing/privacy/concurrency; real network latency remains outside scope. + +### Wire and Concurrency Findings + +- One `message_start` uses the coordinator message id and requested public model. +- Fixed Edge-owned summaries may represent plan, work, review, and detected defect/repair (`repairing`). `finalizing`/cleanup remains internal, and arbitrary internal strings cannot become progress. +- `event: ping` is permitted only before terminal and does not open content blocks. +- Success emits ordered final text, one `message_delta` with `end_turn`, then one `message_stop`. Streamed error/cancel emits one sanitized `error` and never a success terminal. +- One serialized writer/terminal lock owns every content index, ping, flush, and terminal decision. Ticker shutdown is joined before handler return. + +### Test Coverage Gaps + +- Existing generic codec tests intentionally permit reasoning/tool deltas and therefore cannot prove this closed privacy boundary. +- No test covers repair progress, pings across delayed stages, one envelope, forbidden sentinels, monotonic indices, or ping/final/cancel races. + +### Symbol References + +- No symbol is renamed or removed. `writeDirectAnthropicEvent` is reused for framing only. `anthropicHotPathCodec` remains the generic codec and is not a valid projector for closed single-request events. + +### Split Judgment + +- Indivisible invariant: one serialized projector owns envelope, content indices, pings, flushes, and terminal. Splitting ping and terminal ownership would permit post-terminal writes. +- Predecessor index 05 resolves to `agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/`; its `complete.log` is currently missing, so implementation remains pending and unambiguous. Packet 03's coordinator is a transitive prerequisite. + +### Scope Rationale + +- Exclude ordinary Anthropic relay, Chat bridge, generic Hot Path codec, Stream Evidence Gate filters, provider decoding, Node wire, and workspace/tool execution because this packet projects already-classified service events only. +- Never emit provider reasoning, tool names/arguments/results, route/provider/credential ids, workspace paths, raw commands, or internal stage terminals. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; finalizer `finalize-task-policy.sh` in `pair` mode. +- Build closures are true; scores 2/2/2/1/2 = G09; base/final route `grade-boundary`; lane `cloud`; canonical filename `PLAN-cloud-G09.md`. +- Build signals: `large_indivisible_context=false`; positive loop risks `temporal_state`, `concurrent_consistency`, `boundary_contract`, `structured_interpretation`, `variant_product` (5); `review_rework_count=0`; `evidence_integrity_failure=false`; no capability gap. +- Review closures are true; scores 2/2/2/2/2 = G10; route `official-review`; lane `cloud`; canonical filename `CODE_REVIEW-cloud-G10.md`. + +## Dependencies and Execution Order + +1. Verify packet 05 completion evidence and use the marked endpoint plus packet 03's exact public progress/result types. +2. Build and race-test the isolated projector. +3. Integrate the projector/ticker into marked streaming only. +4. Prove exact wire privacy and ordinary path compatibility before updating docs/specs. + +## Implementation Checklist + +- [ ] Implement a serialized single-request Anthropic SSE projector with one envelope, fixed plan/work/review/repair summaries, liveness ping, final text/error, and exactly-once terminal ownership. +- [ ] Integrate it only with the marked coordinator stream, stop and join liveness before terminal/return, acknowledge service completion only after the one wire terminal succeeds, and prove one POST plus no private wire across fragmented multi-stage and repair events. +- [ ] Preserve ordinary Anthropic/Hot Path behavior and synchronize the outer contract and current specs without expanding generic Stream Evidence Gate semantics. +- [ ] Run dependency, exact-wire race, package, vet, full Edge/streamgate regression, and `git diff --check` verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Add a privacy-closed Anthropic stream projector + +**Problem** + +- `apps/edge/internal/openai/anthropic_stream.go:339` owns a generic codec that can accept reasoning and tool fragments, which is too permissive for the fixed single-request privacy boundary. +- `apps/edge/internal/openai/hot_path_direct.go:474` provides framing but no closed progress vocabulary, liveness ping, or unified ping/terminal lock. + +**Solution** + +Before (`apps/edge/internal/openai/anthropic_stream.go:339`): + +```go +type anthropicHotPathCodec struct { + mu sync.Mutex + + w http.ResponseWriter + model string + stream bool + requestID string +} +``` + +After, in an isolated file: + +```go +type singleRequestAnthropicStream struct { + mu sync.Mutex + started bool + terminal bool + nextBlock int +} +``` + +Accept only predecessor-defined public enums/results. Reuse `writeDirectAnthropicEvent` for framing only. Map plan/work/review/repair to fixed Edge summaries, keep finalizing/cleanup internal, reject unknown phases, serialize block indices/pings/flush/terminal, and make every post-terminal call a no-op returning the established result. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/single_request_anthropic_stream.go` — implement the closed projector, fixed phase map including repair, ping, final/error, and serialized terminal state. +- [ ] `apps/edge/internal/openai/single_request_anthropic_stream_test.go` — parse exact wire and cover one envelope/terminal, monotonic blocks, repair summary, ping ordering, forbidden sentinels, and concurrent terminal races. + +**Test Strategy** + +- Add `TestSingleRequestAnthropicStreamOneEnvelopeOneTerminal`, `...PingAndProgressOrdering`, `...RepairSummary`, `...RedactsPrivateEvents`, and `...ErrorTerminalRace` with a deterministic flushing recorder and sentinel fixtures. +- Run this test prefix under the race detector because every writer/terminal path is concurrent-sensitive. + +**Verification** + +- `go test -race ./apps/edge/internal/openai -run 'TestSingleRequestAnthropicStream' -count=1` +- Expected: exact event counts/order and privacy assertions pass with no race or duplicate terminal. + +### [API-2] Pump coordinator progress and liveness on the same request + +**Problem** + +- `apps/edge/internal/openai/anthropic_handler.go:66` has no marked-stream pump spanning all internal stages. +- `apps/edge/internal/openai/anthropic_handler.go:66` owns the `ResponseWriter` lifetime, so a standalone ticker could write after final/cancel or handler return unless shutdown and terminal ownership are explicitly joined there. + +**Solution** + +Before (`apps/edge/internal/openai/anthropic_handler.go:66`): + +```go +func (s *Server) handleAnthropicMessages(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost { + writeAnthropicError(w, http.StatusMethodNotAllowed, "invalid_request_error", "method not allowed") + return + } +} +``` + +After, inside the packet 05 marked branch: + +```go +if dispatch.SingleRequest != nil && request.Stream { + return s.handleAnthropicSingleRequestStream(w, r, dispatch, request) +} +``` + +Start the closed projector and execute the coordinator with its public progress callback. Use an injectable ticker factory/manual channel. Stop, signal, and join the ping worker before final/error and before handler return. Acknowledge the predecessor execution handle as completed only after `message_stop` is written successfully; terminal write failure or caller disconnect selects failure/cancellation and cannot synthesize success. Marked non-stream behavior stays unchanged. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/anthropic_handler.go` — select the projector for marked streaming and own coordinator/ticker lifetime. +- [ ] `apps/edge/internal/openai/single_request_anthropic_stream.go` — add the deterministic progress/ticker pump and shutdown join. +- [ ] `apps/edge/internal/openai/single_request_anthropic_stream_test.go` — cover delayed fragmented stages, repair, manual pings, success acknowledgement after stop, terminal write failure, disconnect, terminal order, and one real handler POST. + +**Test Strategy** + +- Add `TestAnthropicSingleRequestStreamingUsesOnePost`, `...AcknowledgesAfterMessageStop`, `...TerminalWriteFailureDoesNotComplete`, `...StopsPingBeforeTerminal`, and `...DisconnectStopsWriter` using packet 05's fake single-request capability plus manual ticks. +- Rerun `TestHotPathAnthropic*` unchanged to prove generic codec behavior is not weakened. + +**Verification** + +- `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequestStreaming|AnthropicSingleRequestStream|HotPathAnthropic)' -count=1` +- Expected: one handler POST holds the stream across delayed stages; pings cease before terminal/return; generic tests remain unchanged. + +### [API-3] Synchronize SSE and compatibility contracts + +**Problem** + +- `agent-contract/outer/anthropic-compatible-api.md:211` permits generic thinking and `tool_use` response blocks without a closed marked subset. +- `agent-spec/input/openai-compatible-surface.md:132` and `agent-spec/runtime/stream-evidence-gate.md:97` do not define marked repair progress, ping ownership, or terminal/privacy exclusivity. + +**Solution** + +Before (`agent-contract/outer/anthropic-compatible-api.md:211`): + +```markdown +- `model`: Authorized virtual presets echo the requested virtual model. Ordinary native responses preserve the provider response model, while Chat bridge responses use the converted Anthropic request model. +- `content`: text, thinking, tool_use block array. +- `stop_reason`: `end_turn`, `max_tokens`, `tool_use`, `stop_sequence` 중 하나. +``` + +After, add a separate marked SSE subsection and matching spec rows: + +```markdown +The marked single-request stream keeps one message envelope, emits only fixed +plan/work/review/repair summaries and `event: ping`, excludes private reasoning/tool +wire, and commits exactly one success or sanitized error terminal. +``` + +Document exact event/order rules, requested model retention, ping shutdown, forbidden private values, exclusive success/error terminal, and generic Stream Evidence Gate non-expansion. Do not claim real-provider/Claude smoke. + +**Modified Files and Checklist** + +- [ ] `agent-contract/outer/anthropic-compatible-api.md` — define the marked SSE subset, repair progress, privacy, and terminal/error rules. +- [ ] `agent-spec/input/openai-compatible-surface.md` — synchronize endpoint integration and tests. +- [ ] `agent-spec/runtime/stream-evidence-gate.md` — record the separate service-to-endpoint projection boundary and generic-filter non-expansion. + +**Test Strategy** + +- No standalone documentation test. API-1/API-2 exact-wire parser and forbidden-sentinel assertions are the executable oracle. + +**Verification** + +- `rg --sort path -n 'single-request|repair|event: ping|message_start|message_stop|private|tool_use' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/stream-evidence-gate.md` +- Expected: allowed/forbidden wire behavior is explicit and matches the exact-wire tests. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/openai/single_request_anthropic_stream.go` | API-1, API-2 | +| `apps/edge/internal/openai/single_request_anthropic_stream_test.go` | API-1, API-2 | +| `apps/edge/internal/openai/anthropic_handler.go` | API-2 | +| `agent-contract/outer/anthropic-compatible-api.md` | API-3 | +| `agent-spec/input/openai-compatible-surface.md` | API-3 | +| `agent-spec/runtime/stream-evidence-gate.md` | API-3 | +| `agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/CODE_REVIEW-cloud-G10.md` | API-1, API-2, API-3 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log' | wc -l)" -eq 1` +2. `go test -race ./apps/edge/internal/openai -run 'TestSingleRequestAnthropicStream' -count=1` +3. `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequestStreaming|AnthropicSingleRequestStream|HotPathAnthropic)' -count=1` +4. `rg --sort path -n 'single-request|repair|event: ping|message_start|message_stop|private|tool_use' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/stream-evidence-gate.md` +5. `go test -race ./apps/edge/internal/openai -count=1` +6. `go vet ./apps/edge/...` +7. `go test ./apps/edge/... ./packages/go/streamgate/... -count=1` +8. `git diff --check` + +Expected: predecessor evidence exists; exact-wire/race/privacy tests pass; pings stop before one terminal; ordinary Anthropic/Hot Path regressions pass. Actual Claude/provider smoke remains outside this packet. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/code_review_cloud_G10_0.log b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/code_review_cloud_G10_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/code_review_cloud_G10_0.log rename to agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/code_review_cloud_G10_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/CODE_REVIEW-cloud-G10.md b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/code_review_cloud_G10_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/CODE_REVIEW-cloud-G10.md rename to agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/code_review_cloud_G10_1.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/plan_cloud_G09_0.log b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/plan_cloud_G09_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/plan_cloud_G09_0.log rename to agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/plan_cloud_G09_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/PLAN-cloud-G09.md b/agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/plan_cloud_G09_1.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/04+03_stream_terminal/PLAN-cloud-G09.md rename to agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/plan_cloud_G09_1.log