Carlos Florêncio
54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
---
|
|
id: "01-backend-normalization"
|
|
title: "Backend shell output normalization"
|
|
status: done
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
spec: "../../specs/ui/requirements/acp-shell-command-output.md"
|
|
---
|
|
|
|
# Task 01: Backend Shell Output Normalization
|
|
|
|
## Acceptance
|
|
|
|
- The normalized shell contract distinguishes explicit exit `0`, nonzero exit, and unknown exit, and bounds each output field to 256 KiB with valid UTF-8 tail retention.
|
|
- Table-driven tests cover final Codex, Claude, OpenCode, and Auggie shapes, including precedence and malformed/absent exits.
|
|
- Append, cumulative replace, final replace, final-without-output, and truncation behavior cannot duplicate or silently discard retained output.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
make -C apps/backend fmt
|
|
(cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp -run 'Test.*Shell|TestNormalizerResult')
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/internal/agentctl/types/streams/tool_payload.go`
|
|
- `apps/backend/internal/agentctl/server/adapter/transport/acp/normalize.go`
|
|
- `apps/backend/internal/agentctl/server/adapter/transport/acp/normalize_test.go`
|
|
- `apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output.go` (new, if needed)
|
|
- `apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output_test.go` (new, if needed)
|
|
|
|
## Dependencies
|
|
|
|
None.
|
|
|
|
## Inputs
|
|
|
|
- Spec sections `What`, `Data model`, and `Failure modes`.
|
|
- Existing `NormalizeToolResult` and `extractRawOutput` patterns in `normalize.go`, plus the checked-in provider cases in `shell_output_test.go`.
|
|
- Provider mappings and captured-shape summaries pinned in the feature spec; raw ACP captures were investigation artifacts, not repository fixtures.
|
|
|
|
## Output contract
|
|
|
|
Report the normalization API chosen, provider precedence, truncation behavior, tests run, files changed, blockers, and follow-up risks. Set this task to `done` and update `plan.md` only after targeted tests pass.
|
|
|
|
## Completion Report
|
|
|
|
- Added `NormalizeShellToolUpdate` and final-result normalization with independent stdout/stderr presence and truncation state, explicit-field precedence, optional exit codes, and 256 KiB UTF-8 tail retention.
|
|
- Covered Codex, Claude, OpenCode, and Auggie final shapes, malformed/absent exits, precedence, live append/replace behavior, partial stream merges, and truncation.
|
|
- Changed `shell_output.go`, `shell_output_test.go`, `normalize.go`, `normalize_test.go`, and the normalized stream payload type.
|
|
- Targeted ACP adapter tests, full backend tests, formatting, and backend lint passed. No blockers remain; new provider-specific shapes require new fixtures.
|