feat(sdk): expose terminal agent lifecycle status

TO
2mo ago
+115-8

FOR TODD — 1 decision, 0 actions

Decision: expose the existing normalized lifecycle record on terminals.list, rather than add a second status endpoint.

I recommend this because the terminal is already the public CLI/SDK object consumers use to read and send messages, while the host service remains the single owner of agent-state normalization.

What & why

Superset already knows when Claude, Codex, and other supported agents are working or waiting for attention, and the workspace board renders that state. CLI and SDK consumers could only see that the PTY existed, though, so they could not distinguish a working agent from one waiting for input.

This adds an optional agentStatus field to each live terminal returned by terminal.list / terminals.list(). It exposes agent/session identity, timestamps, and the latest normalized lifecycle event. In particular, PermissionRequest gives integrations the same needs-attention signal used by the workspace board.

The response is joined from the existing TerminalAgentStore; this does not introduce another detector or status model. The CLI and SDK reference docs describe the additive field.

Downstream context: todd-studio/workstation#252

How I tested it

  • bun test test/integration/terminal.integration.test.ts --test-name-pattern "createSession uses the configured shell and list includes live agent status" — passed
  • Full terminal integration file — 8 passed; the process-group disposal test timed out once and passed when rerun alone
  • bun run typecheck in packages/host-service — passed
  • bun run typecheck in packages/sdk — passed
  • bun run build in packages/sdk — passed
  • bun run lint — passed
  • bun run typecheck — passed
  • bun run test — not fully green: two dynamic-import tests in the untouched @superset/agent-setup package could not find their shared temporary module after another suite removed it; the same failures remained under the repository-pinned Bun 1.3.14

Checklist

  • PR title follows conventional commits (type(scope): subject)
  • bun run lint and bun run typecheck pass (CI fails on lint warnings too)
  • "Allow edits from maintainers" is checked on fork PRs

Summary by cubic

Exposes the terminal agent's lifecycle status on terminals.list responses, so SDK and CLI consumers can tell when a supported agent is working or waiting for input instead of only knowing the PTY exists.

  • Adds an optional agentStatus field with agent identity, timestamps, and the latest normalized lifecycle event, populated only when listing a specific workspace; workspace-wide listings still return just PTY presence.
  • PermissionRequest signals the agent needs attention, matching what the workspace board displays.
  • Reads from the existing TerminalAgentStore; no new detector or status model is introduced.
  • Exports TerminalAgentStatus and TerminalAgentLifecycleEventType from the SDK and documents the field in the CLI and SDK reference docs.

Summary by CodeRabbit

  • New Features

    • Terminal listings now include live agent status when an agent is detected, including identity, session details, lifecycle state, and timestamps.
    • Permission requests are clearly identified when an agent needs input or approval.
    • SDK users can access new terminal-agent status types and lifecycle event values.

  • Documentation

    • Updated CLI and SDK references to describe agent status fields.
    • Added an example showing how to detect terminals awaiting permission and identify the agent involved.