feat: surface OpenCode provider limit errors (#2167)
This commit is contained in:
@@ -0,0 +1,267 @@
|
||||
---
|
||||
spec: docs/specs/agent-stall-recovery/spec.md
|
||||
decision: docs/decisions/2026-08-02-agent-terminal-diagnostics-over-stderr.md
|
||||
created: 2026-08-02
|
||||
status: done
|
||||
---
|
||||
|
||||
# Implementation Plan: OpenCode Terminal Error Surfacing
|
||||
|
||||
## Overview
|
||||
|
||||
Enable OpenCode's error-only stderr output, normalize only session-correlated
|
||||
foreground `stream error` records inside agentctl, and use that terminal signal
|
||||
to release a prompt whose ACP request never returns. Carry a bounded safe
|
||||
provider-error record through the existing lifecycle, classify usage-limit
|
||||
messages, and render a localized recovery card with collapsed technical details
|
||||
on desktop and mobile. Ambiguous silence continues to use the shipped advisory
|
||||
stall notice.
|
||||
|
||||
---
|
||||
|
||||
## Backend
|
||||
|
||||
### Managed OpenCode diagnostic output
|
||||
|
||||
- Change `OpenCodeACP.ManagedNPMRuntime` in
|
||||
`apps/backend/internal/agent/agents/opencode_acp.go` so every managed OpenCode
|
||||
ACP entry point uses `acp --print-logs --log-level ERROR`. Because normal
|
||||
launch, capability probes, and one-shot inference all consume this shared
|
||||
runtime spec, none may construct a divergent OpenCode command.
|
||||
- Update the command contracts in
|
||||
`apps/backend/internal/agent/agents/opencode_acp_test.go`,
|
||||
`apps/backend/internal/agent/agents/managed_npm_runtime_test.go`,
|
||||
`apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go`, and
|
||||
`apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`.
|
||||
|
||||
### Non-blocking stderr observation
|
||||
|
||||
- Add an optional `StderrLineConsumer` interface beside `StderrProvider` in
|
||||
`apps/backend/internal/agentctl/server/adapter/adapter.go`. The interface
|
||||
receives an ANSI-stripped line as it is appended to the existing bounded
|
||||
stderr ring; it is not a browser API and does not expose historical files.
|
||||
- Update `Manager.readStderr` in
|
||||
`apps/backend/internal/agentctl/server/process/manager.go` to deliver each
|
||||
cleaned line to an installed consumer without allowing parsing or channel
|
||||
backpressure to block draining the child process. For OpenCode, apply a
|
||||
protocol-specific safe projection before generic logging, the recent-stderr
|
||||
ring, or process-exit events; malformed or unrelated records are excluded.
|
||||
Other managed agents retain their existing stderr behavior.
|
||||
- Add focused process-manager regressions proving delivery, ANSI stripping,
|
||||
non-consumer behavior, and that a nonzero OpenCode exit cannot expose raw
|
||||
workspace URLs or identifiers through logs or exit events.
|
||||
|
||||
### OpenCode diagnostic normalization and prompt correlation
|
||||
|
||||
- Add `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
|
||||
with a narrow key/value parser for OpenCode's emitted error records. Accept a
|
||||
record only when `level=ERROR`, `message="stream error"`, `small` is not
|
||||
`true`, `session.id` is present, and `error.error` is non-empty. Parse the
|
||||
timestamp, provider ID, and model ID; strip URLs and identifier-bearing
|
||||
suffixes from the error text before constructing the normalized record.
|
||||
- Add a protocol-neutral safe record in
|
||||
`apps/backend/internal/agentctl/types/streams/provider_error.go` and attach it
|
||||
optionally to `streams.AgentEvent`. Fields are limited to `source`,
|
||||
`provider_id`, `model_id`, `message`, `occurred_at`, and `reset_at`.
|
||||
- Let the ACP adapter implement `StderrLineConsumer` only for
|
||||
`agentID == "opencode-acp"`. Route a validated diagnostic to the current
|
||||
prompt only when its provider session ID equals the adapter's active ACP
|
||||
session and a foreground prompt turn is still pending. The delivery path must
|
||||
be non-blocking and must discard stale lines after the prompt settles.
|
||||
- Extend the prompt-turn wait in
|
||||
`apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt.go`
|
||||
so a correlated terminal diagnostic competes with the ACP RPC and user
|
||||
cancellation. Whichever terminal path claims the prompt first cancels the
|
||||
losing operation, preserves generation ownership, and emits one outcome.
|
||||
- Return a typed prompt error carrying the safe provider-error record. Update
|
||||
`handleWSPrompt` and `Manager.SendErrorEvent` in
|
||||
`apps/backend/internal/agentctl/server/api/agent.go` and
|
||||
`apps/backend/internal/agentctl/server/process/manager.go` so the existing
|
||||
error event includes those structured details. Do not send a second error if
|
||||
the ACP RPC loses the race after the diagnostic has settled the prompt.
|
||||
|
||||
### Lifecycle propagation and quota classification
|
||||
|
||||
- Add the optional safe provider-error record to `AgentExecution`,
|
||||
`AgentEventPayload`, and `watcher.AgentEventData` in
|
||||
`apps/backend/internal/agent/runtime/lifecycle/types.go`,
|
||||
`apps/backend/internal/agent/runtime/lifecycle/event_types.go`,
|
||||
`apps/backend/internal/agent/runtime/lifecycle/events.go`, and
|
||||
`apps/backend/internal/orchestrator/watcher/watcher.go`. Also add `AgentID` to
|
||||
the lifecycle payload so downstream classification uses `opencode-acp`
|
||||
rather than inferring an agent from prose.
|
||||
- In `manager_events.go`, copy structured details from the winning generation's
|
||||
error event before `MarkCompleted` publishes `agent.failed`. Do not retain
|
||||
details from a stale generation or a later duplicate terminal event.
|
||||
- Extend `apps/backend/internal/agent/runtime/routingerr/rules.go` so OpenCode's
|
||||
exact `usage limit reached` signature classifies as high-confidence
|
||||
`quota_limited`. Preserve the existing sanitizer and ensure account/workspace
|
||||
URLs and long identifiers never enter `RawExcerpt`.
|
||||
- In `createRecoveryStatusMessage` in
|
||||
`apps/backend/internal/orchestrator/event_handlers_agent.go`, classify the
|
||||
failure using the event's `AgentID`, validate the structured provider record,
|
||||
and persist the existing recovery actions with metadata:
|
||||
`failure_kind: provider_quota_limited`, safe `provider_name`, optional
|
||||
`model_id`, optional RFC3339 `reset_at`, and bounded sanitized `error_output`.
|
||||
Fall back to the generic recoverable-error card when classification or
|
||||
structured correlation is absent.
|
||||
- Continue using the current `MarkCompleted` -> `agent.failed` ->
|
||||
`handleRecoverableFailure` path. Non-Office sessions become
|
||||
`WAITING_FOR_INPUT`; Office sessions keep their existing `FAILED` behavior.
|
||||
This feature does not invent a second lifecycle state or retry loop.
|
||||
|
||||
---
|
||||
|
||||
## Frontend
|
||||
|
||||
### Localized provider-limit recovery
|
||||
|
||||
- Extend `ActionMeta` / `MessageAction` metadata typing in
|
||||
`apps/web/components/task/chat/types.ts` and
|
||||
`apps/web/components/task/chat/messages/action-message.tsx` for the safe
|
||||
provider-limit fields.
|
||||
- Add a `ProviderQuotaRecovery` branch beside `MissingBranchRecovery`. It uses
|
||||
`failure_kind`, not string matching, to render a localized heading naming the
|
||||
model when available, localized reset guidance when `reset_at` is present,
|
||||
the existing recovery actions, and the existing collapsed **Technical
|
||||
details** disclosure for sanitized `error_output`.
|
||||
- Add all new copy to `apps/web/src/locales/en/chat.json` and
|
||||
`apps/web/src/locales/pseudo/chat.json`; resolve chat keys through
|
||||
`useTranslation` at render time. Do not translate tokens that are compared
|
||||
in control flow.
|
||||
- Keep the generic settled-error behavior unchanged for unknown provider
|
||||
failures and keep the existing neutral running-stall notice unchanged.
|
||||
|
||||
### Mobile design contract
|
||||
|
||||
- **Desktop outcome:** the active spinner disappears when the correlated error
|
||||
settles the turn. A compact error card identifies the affected model and
|
||||
reset timing, keeps sanitized technical details collapsed, and exposes the
|
||||
existing recovery actions.
|
||||
- **Mobile entry point and outcome:** the same card appears inline in the task
|
||||
chat. No drawer or route is added; quota recovery is short, contextual
|
||||
content already owned by the chat transcript.
|
||||
- **Nearest shipped exemplars:** `MissingBranchRecovery` supplies the localized
|
||||
alert-card/details composition, while
|
||||
`mobile-transient-retry.spec.ts` and
|
||||
`mobile-pause-resume-recovery.spec.ts` supply the phone recovery-action and
|
||||
geometry patterns.
|
||||
- **Hierarchy and geometry:** heading, reset guidance, collapsed details, then
|
||||
recovery actions. Chat remains the single scroll owner; technical output has
|
||||
its own bounded vertical overflow only when expanded. Mobile actions retain
|
||||
the existing full-width 44px touch geometry, and the page gains no horizontal
|
||||
overflow.
|
||||
- **Shared logic:** metadata interpretation, reset-time formatting, details,
|
||||
and action handlers are shared across viewports; only responsive classes
|
||||
control layout.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
- **What:** every managed OpenCode ACP command enables error-only stderr while
|
||||
other managed agents remain unchanged.
|
||||
**Files:** `apps/backend/internal/agent/agents/opencode_acp_test.go`,
|
||||
`managed_npm_runtime_test.go`, and lifecycle launch tests.
|
||||
**How:** exact argv assertions across runtime, probe, and inference builders.
|
||||
- **What:** process stderr reaches an optional consumer as cleaned live lines
|
||||
without changing the bounded recent-stderr contract.
|
||||
**File:** `apps/backend/internal/agentctl/server/process/manager_test.go` or a
|
||||
focused sibling test.
|
||||
**How:** fixture process writes ANSI stderr; assertions cover ordered delivery,
|
||||
no consumer, bounded ring behavior, a backlogged diagnostic channel that does
|
||||
not block the drain loop, and a nonzero OpenCode exit whose log, ring, and
|
||||
exit event contain only the safe projection.
|
||||
- **What:** only a main-session OpenCode stream error is normalized.
|
||||
**File:** `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`.
|
||||
**How:** table tests cover the observed quota line, quoted fields, URL
|
||||
sanitization, `small=true`, wrong level/message, missing fields, malformed
|
||||
input, and unrelated session IDs.
|
||||
- **What:** a correlated diagnostic releases a held prompt exactly once while
|
||||
stale/background/wrong-session diagnostics do not.
|
||||
**File:** `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_test.go`.
|
||||
**How:** fake ACP agent holds `session/prompt`; inject stderr through the
|
||||
consumer and race it against RPC completion and cancellation.
|
||||
- **What:** structured provider details survive the lifecycle event boundary
|
||||
only for the winning prompt generation.
|
||||
**Files:** lifecycle `manager_events_test.go`, event publisher tests, and
|
||||
orchestrator watcher tests.
|
||||
**How:** direct error events with matching and stale generations.
|
||||
- **What:** `usage limit reached` becomes high-confidence `quota_limited`, raw
|
||||
excerpts are sanitized, and recovery metadata contains only safe model/reset
|
||||
fields plus existing actions.
|
||||
**Files:** `routingerr/classify_test.go` and
|
||||
`orchestrator/event_handlers_test.go` or a focused provider-failure test.
|
||||
**How:** table classifier tests plus direct recoverable-failure handler tests.
|
||||
- **What:** provider quota metadata renders localized model/reset copy,
|
||||
collapsed sanitized details, and 44px recovery actions without changing
|
||||
generic errors or running stall notices.
|
||||
**File:** `apps/web/components/task/chat/messages/action-message.test.tsx`.
|
||||
**How:** store-backed rendered component tests using English and pseudo
|
||||
locale fixtures.
|
||||
|
||||
## E2E Tests
|
||||
|
||||
- **Scenario:** given a settled OpenCode quota failure, opening the task shows
|
||||
model/reset guidance rather than a running spinner; expanding technical
|
||||
details reveals the sanitized message but no OpenCode workspace URL or ID.
|
||||
**File:** `apps/web/e2e/tests/session/provider-quota-recovery.spec.ts`.
|
||||
- **Scenario:** the same provider-limit explanation, details disclosure, and
|
||||
recovery actions are usable by touch with no horizontal overflow.
|
||||
**File:** `apps/web/e2e/tests/session/mobile-provider-quota-recovery.spec.ts`.
|
||||
- Seed the settled session and persisted status-message metadata through the
|
||||
existing E2E-only task/session/message helpers. Do not require a live quota
|
||||
exhaustion or write provider credentials; the real stderr-to-error boundary
|
||||
is covered by the agentctl and lifecycle integration tests.
|
||||
|
||||
## Verification Results
|
||||
|
||||
- Task 01: `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ParseOpenCode)' -count=1` — 24 tests passed.
|
||||
- Task 02: `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(OpenCodeDiagnostic|Prompt.*Diagnostic|HandleWSPrompt.*ProviderError|SendErrorEvent)' -count=1` — 3 tests passed.
|
||||
- Task 03: `cd apps/backend && go test ./internal/agent/runtime/lifecycle ./internal/agent/runtime/routingerr ./internal/orchestrator ./internal/orchestrator/watcher -run 'Test(.*ProviderError|.*OpenCode.*UsageLimit|HandleRecoverableFailure.*Quota|CreateRecoveryStatusMessage.*Quota)' -count=1` — 13 tests passed.
|
||||
- Task 04: `cd apps && pnpm --filter @kandev/web test -- --run components/task/chat/messages/action-message.test.tsx` — 17 tests passed; `cd apps/web && pnpm run typecheck`, `pnpm run i18n:check`, and `pnpm run i18n:ratchet` passed.
|
||||
- Task 05: managed desktop and mobile Playwright runs passed after the E2E seed was corrected to include `completed_at`: one Chromium test and one `mobile-chrome` test passed.
|
||||
- Fixup: `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ManagerProcessExit|ParseOpenCode)' -count=1` — 26 tests passed; `go test ./...` passed with 10,237 tests.
|
||||
|
||||
## Implementation Waves And Parallel Candidates
|
||||
|
||||
Execution is sequential in the primary conversation. Each task consumes a
|
||||
contract introduced by the previous task, so none is marked parallel-safe.
|
||||
|
||||
Wave 1:
|
||||
|
||||
- [x] [Task 01: Capture OpenCode error diagnostics](task-01-capture-opencode-error-diagnostics.md)
|
||||
|
||||
Wave 2:
|
||||
|
||||
- [x] [Task 02: Settle prompts from correlated diagnostics](task-02-settle-correlated-opencode-prompt.md)
|
||||
|
||||
Wave 3:
|
||||
|
||||
- [x] [Task 03: Classify and persist provider failures](task-03-classify-provider-failure.md)
|
||||
|
||||
Wave 4:
|
||||
|
||||
- [x] [Task 04: Render localized quota recovery](task-04-render-provider-quota-recovery.md)
|
||||
|
||||
Wave 5:
|
||||
|
||||
- [x] [Task 05: Prove desktop and mobile recovery](task-05-e2e-provider-quota-recovery.md)
|
||||
|
||||
## Risks and non-goals
|
||||
|
||||
- OpenCode's stderr record is an agent compatibility dialect. Parsing fails
|
||||
closed: a format change loses the immediate error but cannot fail an
|
||||
unrelated turn.
|
||||
- The stderr reader must never block, because blocking it can deadlock the
|
||||
supervised process; the OpenCode diagnostic channel is bounded and its
|
||||
consumer drops records when backlogged.
|
||||
- Prompt RPC completion, user cancellation, and the diagnostic may race; prompt
|
||||
generation ownership and a single terminal claim are correctness boundaries.
|
||||
- Only the sanitized normalized provider record crosses agentctl. OpenCode raw
|
||||
stderr is inspected in memory by its parser but is never written to generic
|
||||
logs, the recent-stderr ring, process-exit events, persisted recovery
|
||||
metadata, or browser payloads.
|
||||
- The plan does not read OpenCode log files, add an automatic model switch,
|
||||
schedule reset-time retries, change Office routing, or replace the upstream
|
||||
ACP fix.
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: "01-capture-opencode-error-diagnostics"
|
||||
title: "Capture OpenCode error diagnostics"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agent-stall-recovery/spec.md"
|
||||
---
|
||||
|
||||
# Task 01: Capture OpenCode error diagnostics
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Every managed OpenCode ACP command enables `--print-logs --log-level ERROR`,
|
||||
while other managed agent commands remain unchanged.
|
||||
- Agentctl delivers cleaned live stderr lines to an optional consumer without
|
||||
blocking child-process drainage or changing the bounded recent-stderr API.
|
||||
- For OpenCode, generic logs, recent-stderr, and nonzero-exit events contain
|
||||
only the parser's safe provider-message projection; unrecognized records are
|
||||
excluded so workspace URLs and identifiers cannot leak through the fallback
|
||||
error path.
|
||||
- The OpenCode parser accepts only foreground `stream error` records and
|
||||
returns allowlisted, URL-free provider/model/message/timestamp/reset fields;
|
||||
background, malformed, and unrelated records are rejected.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ManagerProcessExit|ParseOpenCode)'`
|
||||
|
||||
Use TDD: command-contract, stderr-delivery, and parser tests must fail before
|
||||
their production changes are added.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agent/agents/opencode_acp.go`
|
||||
- `apps/backend/internal/agent/agents/opencode_acp_test.go`
|
||||
- `apps/backend/internal/agent/agents/managed_npm_runtime_test.go`
|
||||
- `apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/adapter.go`
|
||||
- `apps/backend/internal/agentctl/server/process/manager.go`
|
||||
- `apps/backend/internal/agentctl/server/process/manager_test.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`
|
||||
- `apps/backend/internal/agentctl/types/streams/provider_error.go`
|
||||
- `apps/backend/internal/agentctl/types/streams/agent.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential. Task 02 consumes the parser, consumer, and safe provider-error
|
||||
contract introduced here.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec sections `Correlated terminal diagnostics`, `Diagnostic contract`, and
|
||||
diagnostic failure-mode scenarios
|
||||
- ADR-2026-08-02 stderr ownership, correlation, and sanitization rules
|
||||
- Existing `Manager.readStderr`, `StderrProvider`, `ManagedNPMRuntimeSpec`, and
|
||||
ACP adapter construction patterns
|
||||
|
||||
## Risks
|
||||
|
||||
- `readStderr` is a process-liveness boundary; consumer delivery must remain
|
||||
non-blocking, including when the bounded provider-diagnostic channel is full.
|
||||
- The parser must not preserve the OpenCode workspace URL or identifiers found
|
||||
in the observed `error.error` suffix.
|
||||
- The generic process-exit path must consume only the safe OpenCode projection;
|
||||
raw stderr must never appear in logs, the recent-stderr ring, or exit events.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED assertions, exact argv, normalized field allowlist, rejected record
|
||||
cases, test results, files changed, blockers, and risks. Mark this task `done`
|
||||
and update its plan checkbox in the same conversation.
|
||||
|
||||
## Results
|
||||
|
||||
The managed command contract, optional stderr consumer, parser privacy,
|
||||
bounded-channel, and nonzero-exit projection cases all have focused
|
||||
regressions. OpenCode now uses `acp --print-logs --log-level ERROR`; the parser
|
||||
keeps only the validated foreground
|
||||
session/provider/model/message/timestamp/reset fields and rejects title,
|
||||
`small=true`, malformed, unrelated, or incomplete records. The focused
|
||||
verification passed with 26 tests across three packages; the full backend
|
||||
suite also passed.
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
---
|
||||
id: "02-settle-correlated-opencode-prompt"
|
||||
title: "Settle correlated OpenCode prompts"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: ["01-capture-opencode-error-diagnostics"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agent-stall-recovery/spec.md"
|
||||
---
|
||||
|
||||
# Task 02: Settle Prompts From Correlated Diagnostics
|
||||
|
||||
## Acceptance
|
||||
|
||||
- A validated OpenCode diagnostic settles only the pending foreground prompt
|
||||
whose active ACP session ID matches the diagnostic.
|
||||
- Diagnostic, ACP response, and user-cancel races emit exactly one terminal
|
||||
result for the owning prompt generation and release the losing operation.
|
||||
- The resulting agent error event carries the safe provider-error record;
|
||||
wrong-session, background, stale, post-settlement, and non-OpenCode lines do
|
||||
not affect the prompt.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(OpenCodeDiagnostic|Prompt.*Diagnostic|HandleWSPrompt.*ProviderError|SendErrorEvent)'`
|
||||
|
||||
Use a fake ACP agent that intentionally holds `session/prompt`; do not call a
|
||||
real provider or depend on wall-clock stall detection.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_cancel.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`
|
||||
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_test.go`
|
||||
- `apps/backend/internal/agentctl/server/api/agent.go`
|
||||
- `apps/backend/internal/agentctl/server/api/agent_test.go`
|
||||
- `apps/backend/internal/agentctl/server/process/manager.go`
|
||||
- `apps/backend/internal/agentctl/server/process/manager_test.go`
|
||||
- `apps/backend/internal/agentctl/types/streams/provider_error.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 01.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential. Task 03 consumes the structured terminal event created here.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec scenarios for active, wrong-session, background, stale, and racing
|
||||
diagnostics
|
||||
- Plan section `OpenCode diagnostic normalization and prompt correlation`
|
||||
- Existing prompt-turn gate, generation claim, cancel acknowledgement, async
|
||||
`handleWSPrompt`, and `SendErrorEvent` paths
|
||||
|
||||
## Risks
|
||||
|
||||
- A losing `conn.Prompt` goroutine must receive cancellation and cannot retain a
|
||||
prompt gate, trace span, or later error delivery.
|
||||
- Stderr delivery cannot block on the prompt consumer channel.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED race assertions, correlation rules, single-terminal proof, exact
|
||||
tests, files changed, blockers, and risks. Mark this task `done` and update its
|
||||
plan checkbox in the same conversation.
|
||||
|
||||
## Results
|
||||
|
||||
The ACP adapter correlates diagnostics to the active ACP session and prompt
|
||||
turn, cancels the held RPC through its context cause, and forwards one typed
|
||||
provider error through the existing async prompt event. Wrong-session and
|
||||
post-settlement diagnostics are ignored; duplicate lifecycle terminal events
|
||||
are guarded by prompt generation. The exact verification command passed with
|
||||
3 tests across three packages.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
id: "03-classify-provider-failure"
|
||||
title: "Classify and persist provider failures"
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: ["02-settle-correlated-opencode-prompt"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agent-stall-recovery/spec.md"
|
||||
---
|
||||
|
||||
# Task 03: Classify and Persist Provider Failures
|
||||
|
||||
## Acceptance
|
||||
|
||||
- The winning generation's safe provider-error record and concrete agent ID
|
||||
reach `agent.failed`; stale or duplicate terminal events cannot replace them.
|
||||
- OpenCode `usage limit reached` classifies as high-confidence
|
||||
`quota_limited`, with the existing sanitizer removing URLs and long
|
||||
identifiers from every persisted excerpt.
|
||||
- Non-Office recovery messages persist `provider_quota_limited` metadata with
|
||||
only safe provider/model/reset/details fields and existing recovery actions;
|
||||
absent or unrecognized details use the generic error card.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps/backend && go test ./internal/agent/runtime/lifecycle ./internal/agent/runtime/routingerr ./internal/orchestrator ./internal/orchestrator/watcher -run 'Test(.*ProviderError|.*OpenCode.*UsageLimit|HandleRecoverableFailure.*Quota|CreateRecoveryStatusMessage.*Quota)'`
|
||||
|
||||
Use TDD at the lifecycle event, classifier, watcher, and persisted-message
|
||||
boundaries. Assert the observed OpenCode workspace URL and identifier are
|
||||
absent from error messages, raw excerpts, and message metadata.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/types.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/event_types.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/events.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/manager_events.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/manager_events_test.go`
|
||||
- `apps/backend/internal/agent/runtime/routingerr/rules.go`
|
||||
- `apps/backend/internal/agent/runtime/routingerr/classify_test.go`
|
||||
- `apps/backend/internal/orchestrator/watcher/watcher.go`
|
||||
- `apps/backend/internal/orchestrator/watcher/watcher_test.go`
|
||||
- `apps/backend/internal/orchestrator/event_handlers_agent.go`
|
||||
- `apps/backend/internal/orchestrator/event_handlers_test.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 02.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential. Task 04 consumes the persisted metadata contract defined here.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec `Diagnostic contract`, persistence guarantees, and quota scenarios
|
||||
- Plan sections `Lifecycle propagation and quota classification` and Tests
|
||||
- Existing `MarkCompleted`, `newAgentEventPayload`, `routingerr.Classify`,
|
||||
`handleRecoverableFailure`, and `createRecoveryStatusMessage` paths
|
||||
|
||||
## Risks
|
||||
|
||||
- Provider classification must use the concrete `opencode-acp` agent ID and
|
||||
must not infer trust from arbitrary error prose.
|
||||
- Raw recent stderr remains outside the persisted safe record.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED assertions, event and metadata shapes, classification rule and
|
||||
confidence, sanitization proof, exact tests, files changed, blockers, and
|
||||
risks. Mark this task `done` and update its plan checkbox in the same
|
||||
conversation.
|
||||
|
||||
## Results
|
||||
|
||||
The safe provider record and concrete `opencode-acp` ID now reach
|
||||
`agent.failed`. The exact five-hour usage-limit signature is high-confidence
|
||||
`quota_limited`; URL/session/workspace identifiers are redacted before
|
||||
persistence. Non-Office recovery metadata includes only the specialized
|
||||
failure kind, provider/model/reset values, sanitized details, and existing
|
||||
actions. The exact verification command passed with 13 tests across four
|
||||
packages.
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
---
|
||||
id: "04-render-provider-quota-recovery"
|
||||
title: "Render localized quota recovery"
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: ["03-classify-provider-failure"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agent-stall-recovery/spec.md"
|
||||
---
|
||||
|
||||
# Task 04: Render Localized Quota Recovery
|
||||
|
||||
## Acceptance
|
||||
|
||||
- `provider_quota_limited` metadata renders localized model/reset guidance,
|
||||
existing recovery actions, and sanitized technical details collapsed by
|
||||
default; no raw OpenCode URL or identifier is displayed.
|
||||
- Unknown provider failures retain the generic settled-error card, and running
|
||||
inactivity notices retain their neutral compact behavior.
|
||||
- Desktop and phone use the same logic; phone actions remain at least 44px,
|
||||
expanded details stay within the chat width, and no workflow depends on
|
||||
hover.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps && pnpm install --frozen-lockfile`
|
||||
- `cd apps && pnpm --filter @kandev/web test -- --run components/task/chat/messages/action-message.test.tsx`
|
||||
- `cd apps/web && pnpm run typecheck`
|
||||
|
||||
Use TDD for provider metadata, missing model/reset fallbacks, details
|
||||
disclosure, generic-error preservation, and pseudo-locale rendering.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/components/task/chat/types.ts`
|
||||
- `apps/web/components/task/chat/messages/action-message.tsx`
|
||||
- `apps/web/components/task/chat/messages/action-message.test.tsx`
|
||||
- `apps/web/src/locales/en/chat.json`
|
||||
- `apps/web/src/locales/pseudo/chat.json`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 03.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential. Task 05 validates this presentation and its backend metadata.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec provider-limit desktop/mobile scenarios
|
||||
- Plan `Localized provider-limit recovery` and mobile design contract
|
||||
- Existing `MissingBranchRecovery`, `TechnicalDetails`, `ActionButtons`, and
|
||||
`useTranslation("chat")` patterns
|
||||
|
||||
## Risks
|
||||
|
||||
- Reset timestamps must be formatted at render time and must not call `t()` at
|
||||
module scope.
|
||||
- The safe technical string is display-only; control flow must use
|
||||
`failure_kind` rather than translated copy or substring matching.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED assertions, translation keys, desktop/mobile hierarchy, technical
|
||||
details behavior, exact test/typecheck results, files changed, blockers, and
|
||||
risks. Mark this task `done` and update its plan checkbox in the same
|
||||
conversation.
|
||||
|
||||
## Results
|
||||
|
||||
Added the localized `ProviderQuotaRecovery` inline card with model/reset
|
||||
fallbacks, collapsed technical details, existing recovery actions, and shared
|
||||
desktop/mobile layout. Unknown failures and running stall notices retain their
|
||||
existing renderers. The focused component suite passed all 17 tests; web
|
||||
typecheck, i18n key/pseudo checks, and the new-code ratchet passed.
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: "05-e2e-provider-quota-recovery"
|
||||
title: "Prove desktop and mobile quota recovery"
|
||||
status: done
|
||||
wave: 5
|
||||
depends_on:
|
||||
- "03-classify-provider-failure"
|
||||
- "04-render-provider-quota-recovery"
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agent-stall-recovery/spec.md"
|
||||
---
|
||||
|
||||
# Task 05: Prove Desktop and Mobile Recovery
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Desktop Playwright proves a settled OpenCode quota failure replaces the
|
||||
running status with model/reset guidance, keeps technical details collapsed,
|
||||
and reveals no workspace URL or identifier when expanded.
|
||||
- Mobile Playwright proves the same information and recovery actions are
|
||||
reachable by touch, actions are at least 44px, expanded details remain
|
||||
viewport-contained, and the document has no horizontal overflow.
|
||||
- Tests use E2E-only session/message seeding and never exhaust real provider
|
||||
quota, read a developer's OpenCode log, or add a production test hook.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps && pnpm install --frozen-lockfile`
|
||||
- `cd apps/web && pnpm e2e:run --no-build tests/session/provider-quota-recovery.spec.ts`
|
||||
- `cd apps/web && pnpm e2e:run --no-build --project mobile-chrome tests/session/mobile-provider-quota-recovery.spec.ts`
|
||||
|
||||
Run against freshly built backend and Vite artifacts through the managed E2E
|
||||
runner. Inspect the rendered phone viewport in addition to assertions.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/e2e/pages/session-page.ts`
|
||||
- `apps/web/e2e/tests/session/provider-quota-recovery.spec.ts`
|
||||
- `apps/web/e2e/tests/session/mobile-provider-quota-recovery.spec.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 03 and 04.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential. This is the integrated user-visible proof for the completed
|
||||
backend and frontend contracts.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec desktop/mobile quota scenarios and privacy guarantees
|
||||
- Plan E2E section and mobile design contract
|
||||
- Existing `seedTaskSession`, `seedSessionMessage`, missing-branch technical
|
||||
details, transient-retry, and mobile pause/recovery patterns
|
||||
|
||||
## Risks
|
||||
|
||||
- Seed only the safe normalized metadata contract; do not copy the real
|
||||
OpenCode workspace URL or account identifier into fixtures.
|
||||
- A passing seeded UI test does not replace Task 02's real prompt-boundary
|
||||
integration regression.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED failures, exact desktop/mobile results, rendered mobile inspection,
|
||||
privacy assertions, files changed, blockers, risks, and teardown evidence.
|
||||
Mark this task `done`, update its plan checkbox, and synchronize the plan's
|
||||
verification results in the same conversation.
|
||||
|
||||
## Results
|
||||
|
||||
Added E2E-only seeded desktop and mobile specs. Both managed production-build
|
||||
runs passed: Chromium verifies the localized card, collapsed/expanded privacy
|
||||
details, and recovery actions; `mobile-chrome` verifies touch disclosure,
|
||||
44px actions, viewport containment, and no horizontal overflow. The first run
|
||||
found and fixed a fixture requirement for `completed_at`; no provider quota or
|
||||
developer log was used.
|
||||
Reference in New Issue
Block a user