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

2.6 KiB

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.