feat(sdk): expose terminal agent lifecycle status

[toddagent01]

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.

^{Written for commit da713eb. Summary will update on new commits.}

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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e20a829-8655-4b20-a625-11bef9106a2d

📥 Commits

Reviewing files that changed from the base of the PR and between cfa8b5a and da713eb.

📒 Files selected for processing (1)

• packages/host-service/src/trpc/router/terminal/terminal.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The terminal listing now enriches sessions with optional normalized agent lifecycle status. The SDK exports the new status types, integration tests cover permission requests, and CLI and SDK documentation describe the updated response shape.

Changes

Terminal agent status

Layer / File(s)	Summary
Agent status contract packages/sdk/src/resources/terminals.ts, packages/sdk/src/resources/index.ts, packages/sdk/src/index.ts, packages/sdk/src/client.ts	TerminalSummary now supports agentStatus. The SDK exports TerminalAgentStatus and TerminalAgentLifecycleEventType.
Terminal list enrichment packages/host-service/src/trpc/router/terminal/terminal.ts, packages/host-service/test/integration/terminal.integration.test.ts	The terminal list scopes agent bindings by workspace and returns lifecycle metadata. Integration coverage validates PermissionRequest, agent identity, and timestamps.
CLI and SDK documentation apps/docs/content/docs/cli/cli-reference.mdx, apps/docs/content/docs/sdk/reference.mdx	The documentation describes agentStatus, lifecycle events, and permission requests requiring attention.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to da713

The PR adds agent identity and lifecycle timestamps and events to workspace-scoped terminal listings. If a caller can reach a host service outside its authorized workspace, the response could disclose another workspace’s terminal and agent state; the change is otherwise additive and mergeable with explicit owner awareness that this isolation is enforced upstream.

Sequence Diagram(s)

sequenceDiagram
  participant notifications.hook
  participant terminal.list
  participant SDK consumer
  notifications.hook->>terminal.list: Store request_user_input event
  SDK consumer->>terminal.list: List terminal sessions
  terminal.list-->>SDK consumer: Return session with agentStatus

Loading

Suggested reviewers: kitenite

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses conventional commit format and clearly identifies the main change: exposing terminal agent lifecycle status through the SDK.
Description check	✅ Passed	The description includes the required What & why, How I tested it, and Checklist sections. It explains the change, links the related issue, lists validation results, and marks the checklist items. It …
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 6…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description includes the required What & why, How I tested it, and Checklist sections. It explains the change, links the related issue, lists validation results, and marks the checklist items. It also clearly documents the known partial test-suite failure.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 6 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[toddagent01]

Exact pending question/choice transport is intentionally kept out of this lifecycle-only PR and tracked as follow-up #7009. That contract needs provider-neutral semantics and explicit payload minimization; this PR remains the small prerequisite that exposes the existing normalized state.