Sandbox observability: a run-scoped live view of a running agent, with optional takeover #1533

Closed
opened 2026-10-27 13:40:47 +00:00 by sam · 1 comment
Owner

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

  • Nothing attaches to a container. The only ExecAttach is container.ExecIn for hooks, AttachStdout/AttachStderr and no Tty (internal/container/kit.go).
  • There is no task-to-container lookup. Kit containers carry only the label archie-daemon=true (internal/container/pool.go), and kitrun.Run holds the container handle with no registry or contract a peer service could query.
  • The only PTY-shaped surface is the setup terminal's webui interface, which is profile-scoped and has no backend (archie-core-h3s0).

Scope

Reuse h3s0's session contract, addressed by task and attempt rather than by Kit profile.

  1. Peek first, read-only. A live view of the running sandbox. The cheapest useful shape is a live tail of the existing per-attempt logs and events in the dashboard; a read-only attach with no stdin is the richer option if the tty view is wanted. This needs no new authority.
  2. Takeover second, write. An interactive PTY into the running container: authorised against the task, audited, bounded by the task's life, revoked when it ends. This depends on the dangerous-command authority tracked in archie-core-sod1; do not ship takeover without it.

Constraints

  • Design doc first, extending h3s0's session contract. Do not implement in a UI lane: the dashboard binary must not link internal/container, internal/app/archied or internal/agentexec.
  • Egress: a run-scoped session runs at the runtime phase, the container holds sentinels, and the proxy injects real credentials per granted service (internal/infrastructure/egress/oauth.go). State this in the design doc rather than assuming it, since it is what keeps a takeover shell from holding real credentials.
  • The one writer of a harness secret is the egress proxy, so this bead does not touch credential capture. h3s0 owns the setup session.

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-08

## 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 - Nothing attaches to a container. The only ExecAttach is container.ExecIn for hooks, AttachStdout/AttachStderr and no Tty (internal/container/kit.go). - There is no task-to-container lookup. Kit containers carry only the label archie-daemon=true (internal/container/pool.go), and kitrun.Run holds the container handle with no registry or contract a peer service could query. - The only PTY-shaped surface is the setup terminal's webui interface, which is profile-scoped and has no backend (archie-core-h3s0). ## Scope Reuse h3s0's session contract, addressed by task and attempt rather than by Kit profile. 1. Peek first, read-only. A live view of the running sandbox. The cheapest useful shape is a live tail of the existing per-attempt logs and events in the dashboard; a read-only attach with no stdin is the richer option if the tty view is wanted. This needs no new authority. 2. Takeover second, write. An interactive PTY into the running container: authorised against the task, audited, bounded by the task's life, revoked when it ends. This depends on the dangerous-command authority tracked in archie-core-sod1; do not ship takeover without it. ## Constraints - Design doc first, extending h3s0's session contract. Do not implement in a UI lane: the dashboard binary must not link internal/container, internal/app/archied or internal/agentexec. - Egress: a run-scoped session runs at the runtime phase, the container holds sentinels, and the proxy injects real credentials per granted service (internal/infrastructure/egress/oauth.go). State this in the design doc rather than assuming it, since it is what keeps a takeover shell from holding real credentials. - The one writer of a harness secret is the egress proxy, so this bead does not touch credential capture. h3s0 owns the setup session. ### 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-08_
sam added the mediumtask labels 2026-10-27 13:40:47 +00:00
sam self-assigned this 2026-10-27 13:40:47 +00:00
Author
Owner

Triaged: 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:

  1. 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 via kitrun.TaskContainer(task_id, attempt), finished/unknown/non-running/wrong-attempt/gone-container is NotFound with 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 is Unavailable), the read-logs-on-task authorisation, the grants position (no grant of its own; the run's egress session is revoked by Launcher.Release), and the credentials position (container holds only egress.Sentinel and 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.Approval never set) and the shape it would take later.

  2. The contract carries the run target. proto/harness/v1/harness.proto has OpenTarget_Run{RunTarget{task_id, attempt}}; the generated client/server are in internal/contracts/harness/v1. The issue's claim that the daemon answers codes.Unimplemented for it is stale — nothing in the tree returns Unimplemented for a run target (the only Unimplemented hits are unrelated generated stubs).

  3. Daemon side is implemented. internal/app/archied/harness.go dispatches *pb.OpenTarget_Run to openRun, which streams container.FollowLogs(ctx, cli, kitrun.TaskContainer(instance, taskID, attempt), 200); internal/app/archied/harness_run.go holds runView.open with the refusal cases (unknown/other-org task NotFound, non-running task NotFound naming its status, wrong attempt NotFound naming the running attempt, missing container NotFound, task store or Docker failure Unavailable), ignores client frames (no stdin, no exec), and logs open/close with task and attempt (internal/container/logs.go for the read-only follow; kitrun.TaskContainer at internal/infrastructure/kitrun/launcher.go:257). Wired in boot.runView() only when the task store and container pool exist.

  4. Dashboard side is implemented without linking container code. internal/webui/tasks_sandbox.go serves GET /api/tasks/{id}/sandbox as a WebSocket, streams the view, discards browser input, and writes the daemon's stated reason to the socket; internal/webui/authorize.go:306 decides that route as ActionReadLogs on KindTask. internal/infrastructure/harnessrpc/harnessrpc.go OpenRun maps the refusal status back to the caller, and internal/app/archieui/run.go wireHarness sets srv.SandboxView = harness (the dashboard depends on the harness gRPC contract, not internal/container, internal/app/archied or internal/agentexec).

  5. UI is implemented. ui/src/tasks/task-run.ts lists a Sandbox tab, TaskRunPanels.vue renders SandboxView.vue scoped to the selected attempt, and SandboxView.vue is a read-only xterm (disableStdin: true, no input sent) that displays the refusal text on the socket and closes when the sandbox ends.

  6. Tests cover the refusals and the stream lifetime: internal/app/archied/harness_run_test.go (TestRunViewOpen covers running attempt, unknown task, finished task, earlier attempt, container gone, store down, other org, docker down, asserting both code and stated reason) and internal/webui/tasks_sandbox_test.go (TestSandboxStreamLifetime), plus the route appearing in authorization_surfaces_test.go.

  7. CHANGELOG.md:146 lists it as shipped: "a running task has a read-only Sandbox tab that follows its container."

Not verified: I could not run go test or task (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.

Triaged: 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: 1. 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 via `kitrun.TaskContainer(task_id, attempt)`, finished/unknown/non-running/wrong-attempt/gone-container is `NotFound` with 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 is `Unavailable`), the `read-logs`-on-task authorisation, the grants position (no grant of its own; the run's egress session is revoked by `Launcher.Release`), and the credentials position (container holds only `egress.Sentinel` and 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.Approval` never set) and the shape it would take later. 2. The contract carries the run target. `proto/harness/v1/harness.proto` has `OpenTarget_Run{RunTarget{task_id, attempt}}`; the generated client/server are in `internal/contracts/harness/v1`. The issue's claim that the daemon answers `codes.Unimplemented` for it is stale — nothing in the tree returns Unimplemented for a run target (the only Unimplemented hits are unrelated generated stubs). 3. Daemon side is implemented. `internal/app/archied/harness.go` dispatches `*pb.OpenTarget_Run` to `openRun`, which streams `container.FollowLogs(ctx, cli, kitrun.TaskContainer(instance, taskID, attempt), 200)`; `internal/app/archied/harness_run.go` holds `runView.open` with the refusal cases (unknown/other-org task `NotFound`, non-running task `NotFound` naming its status, wrong attempt `NotFound` naming the running attempt, missing container `NotFound`, task store or Docker failure `Unavailable`), ignores client frames (no stdin, no exec), and logs open/close with task and attempt (`internal/container/logs.go` for the read-only follow; `kitrun.TaskContainer` at `internal/infrastructure/kitrun/launcher.go:257`). Wired in `boot.runView()` only when the task store and container pool exist. 4. Dashboard side is implemented without linking container code. `internal/webui/tasks_sandbox.go` serves `GET /api/tasks/{id}/sandbox` as a WebSocket, streams the view, discards browser input, and writes the daemon's stated reason to the socket; `internal/webui/authorize.go:306` decides that route as `ActionReadLogs` on `KindTask`. `internal/infrastructure/harnessrpc/harnessrpc.go` `OpenRun` maps the refusal status back to the caller, and `internal/app/archieui/run.go` `wireHarness` sets `srv.SandboxView = harness` (the dashboard depends on the harness gRPC contract, not `internal/container`, `internal/app/archied` or `internal/agentexec`). 5. UI is implemented. `ui/src/tasks/task-run.ts` lists a `Sandbox` tab, `TaskRunPanels.vue` renders `SandboxView.vue` scoped to the selected attempt, and `SandboxView.vue` is a read-only xterm (`disableStdin: true`, no input sent) that displays the refusal text on the socket and closes when the sandbox ends. 6. Tests cover the refusals and the stream lifetime: `internal/app/archied/harness_run_test.go` (`TestRunViewOpen` covers running attempt, unknown task, finished task, earlier attempt, container gone, store down, other org, docker down, asserting both code and stated reason) and `internal/webui/tasks_sandbox_test.go` (`TestSandboxStreamLifetime`), plus the route appearing in `authorization_surfaces_test.go`. 7. `CHANGELOG.md:146` lists it as shipped: "a running task has a read-only Sandbox tab that follows its container." Not verified: I could not run `go test` or `task` (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.
sam closed this issue 2026-11-08 12:10:22 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1533