Sandbox observability: a run-scoped live view of a running agent, with optional takeover #1533
Notifications
Due Date
No due date set.
Blocks
Depends on
Reference: sam/archie#1533
Reference in new issue
Block a user
Why
An operator can see archie's structured per-attempt logs and the distilled steps and events for a run (internal/webui/api_tasks_logs.go, api_tasks_debug.go, internal/agentexec/harness_adapters.go), but cannot see or reach the agent's sandbox itself. A run that stalls gives the operator a transcript, not a foothold.
archie-core-h3s0 builds the session contract and the ephemeral setup session (OAuth credential seeding). This bead reuses that same contract for a run-scoped session over a running task's container.
What is missing
Scope
Reuse h3s0's session contract, addressed by task and attempt rather than by Kit profile.
Constraints
Acceptance criteria
the dashboard shows a running task's sandbox activity live, for a task the caller may read; opening a run-scoped session for a finished or unknown task is refused with a stated reason; takeover either ships behind the archie-core-sod1 authority with an audit record, or is explicitly declared out of scope in this bead's design doc.
Notes
h3s0 left room: proto/harness/v1 HarnessService.Open's OpenTarget oneof already carries RunTarget{task_id, attempt}, and the daemon answers codes.Unimplemented for it (internal/app/archied/harness.go). Session lifetime, grant, teardown and the dashboard bridge are shared; qi91 adds a task-to-container lookup and the runtime-phase grant, not a second contract.
Imported from beads
archie-core-qi91· GitHub #1557 · type task · priority P2 · created 2026-10-08Triaged: no code change is needed for this. No code change is needed: every acceptance criterion in this bead is already implemented and shipped on the current tree, and the one deferred half (takeover) is explicitly declared out of scope in the approved design doc.
What I verified by reading the tree:
Design doc exists and is approved.
docs/prds/external-agent-harness.md("Session contract", status Approved) already defines the run session addressed by{org, task, attempt}, its container, lifetime and authorisation. Its "Run target" bullet is the design this bead asks for, written out:RunTarget{task_id, attempt}opens a read-only view, the daemon resolves the pair itself viakitrun.TaskContainer(task_id, attempt), finished/unknown/non-running/wrong-attempt/gone-container isNotFoundwith the reason in the message, the view follows stdout and stderr with no stdin and no exec and ends with the container. It states the refusal-precedence rule (unreachable store or engine isUnavailable), theread-logs-on-task authorisation, the grants position (no grant of its own; the run's egress session is revoked byLauncher.Release), and the credentials position (container holds onlyegress.Sentineland sentinelised OAuth; the proxy does the swap). Takeover is explicitly "out of scope for this issue", with the reason (#1574 dangerous-command authority not wired: no approval step on the harness listener,ToolSetOptions.Approvalnever set) and the shape it would take later.The contract carries the run target.
proto/harness/v1/harness.protohasOpenTarget_Run{RunTarget{task_id, attempt}}; the generated client/server are ininternal/contracts/harness/v1. The issue's claim that the daemon answerscodes.Unimplementedfor it is stale — nothing in the tree returns Unimplemented for a run target (the only Unimplemented hits are unrelated generated stubs).Daemon side is implemented.
internal/app/archied/harness.godispatches*pb.OpenTarget_RuntoopenRun, which streamscontainer.FollowLogs(ctx, cli, kitrun.TaskContainer(instance, taskID, attempt), 200);internal/app/archied/harness_run.goholdsrunView.openwith the refusal cases (unknown/other-org taskNotFound, non-running taskNotFoundnaming its status, wrong attemptNotFoundnaming the running attempt, missing containerNotFound, task store or Docker failureUnavailable), ignores client frames (no stdin, no exec), and logs open/close with task and attempt (internal/container/logs.gofor the read-only follow;kitrun.TaskContaineratinternal/infrastructure/kitrun/launcher.go:257). Wired inboot.runView()only when the task store and container pool exist.Dashboard side is implemented without linking container code.
internal/webui/tasks_sandbox.goservesGET /api/tasks/{id}/sandboxas a WebSocket, streams the view, discards browser input, and writes the daemon's stated reason to the socket;internal/webui/authorize.go:306decides that route asActionReadLogsonKindTask.internal/infrastructure/harnessrpc/harnessrpc.goOpenRunmaps the refusal status back to the caller, andinternal/app/archieui/run.gowireHarnesssetssrv.SandboxView = harness(the dashboard depends on the harness gRPC contract, notinternal/container,internal/app/archiedorinternal/agentexec).UI is implemented.
ui/src/tasks/task-run.tslists aSandboxtab,TaskRunPanels.vuerendersSandboxView.vuescoped to the selected attempt, andSandboxView.vueis a read-only xterm (disableStdin: true, no input sent) that displays the refusal text on the socket and closes when the sandbox ends.Tests cover the refusals and the stream lifetime:
internal/app/archied/harness_run_test.go(TestRunViewOpencovers running attempt, unknown task, finished task, earlier attempt, container gone, store down, other org, docker down, asserting both code and stated reason) andinternal/webui/tasks_sandbox_test.go(TestSandboxStreamLifetime), plus the route appearing inauthorization_surfaces_test.go.CHANGELOG.md:146lists it as shipped: "a running task has a read-only Sandbox tab that follows its container."Not verified: I could not run
go testortask(this mission is read-only, no exec tool), so the passing state of those tests is inferred from the source, not observed.Residual work, deliberately not part of this bead: interactive takeover, which the PRD defers behind the #1574 dangerous-command authority and an audit record. It should stay tracked there rather than being re-queued here.