Files
pipelines/docs/notes/background-task-output-api.md

41 lines
2.6 KiB
Markdown

# Background task output API
Changed: 2026-10-18. The chat websocket now has `chat_shells` for current,
operator-session-owned running shells and `chat_shell_output` for a selected,
bounded (64 KiB) absolute-byte output page. Ownership requires both the
operator-session registry and provider shell metadata `sessionID`; a shared cwd
is not evidence. Output reads first verify provider detail and explicitly mark
removed/provider-unavailable shells unavailable. This is not completed-task
history or restart retention.
Stale shared documentation: the packaged OpenCode operational references under
`internal/author/skill/references/` need a later docs-fold update describing the
two additive websocket messages, 64 KiB maximum page, and current-only history.
Fixture evidence (2026-10-18): `go build -o <scratch>/pipelines-large-chat-fixture
./cmd/pipelines-large-chat-fixture`; then `<scratch>/pipelines-large-chat-fixture
-scratch-dir <scratch>/run -shell-exited`, stopped with SIGTERM and awaited. The
foreground run exercised authenticated `chat_sessions`, three reconnecting history
pages, `chat_shells`, bounded `chat_shell_output`, and four executable negative
readbacks (`foreign-list`, `unknown-list`, `foreign-output`, `unknown-output`) against
scratch DB/workspace only. Its JSON contains `clean_shutdown: true` and
`shutdown_exit_status: 0`, plus the selected exited shell's `exit: 0` readback.
The evidence revision was `ded79277783b6ccdc25eb4ea25fe55d8632b89c7`; session
`ses_large_chat_fixture`, shell `sh_large_chat_fixture`, and fixed marker
`fixture shell output marker\n`. The current list remains running-shell discovery.
Integration coverage added: `TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider`,
`TestChatShellOutputRealHandlerWebsocketOwnedAndForeign`, and
`TestChatShellOutputRealHandlerExitedReadback`,
`TestChatShellOutputRealHandlerUnavailableAndReconnect`, and
`TestChatShellOutputRejectsMalformedAndOversizedProviderPages`, and
`TestChatShellOutputRealHandlerCancellationStopsProvider` in
`internal/server/chat_shell_output_test.go`. Run with
`go test ./internal/server -run 'TestChatShellOutput' -count=1 -v` and
`go test -race ./internal/server -run 'TestChatShellOutput(RealHandler|RejectsBounds)' -count=1 -v`.
These tests use an authenticated in-process HTTP provider, a scratch SQLite operator
registry, and real `/connect` websocket traffic. The fixture executes foreign
session/shell refusal requests and records positive/negative JSON readbacks under
`shell_readbacks`; it remains scratch-only evidence, not evidence of a real provider,
model, production workspace, or device.