feat(maestro): render the structured view in the web client (#140)

Adds a transcript surface for a Structured-view session alongside the
existing xterm attach view: a WS /api/structured/:id connection
(structured.ts) mounted by ConnectionPool whenever a session's `view`
is `"Structured"`, and pure per-row/rail renderers (structuredRender.ts,
structuredDiff.ts) covering all eight transcript row kinds.

Hierarchy follows the design reference (artifact 88ecd690): the
approval is the only lifted, card-like element; a user turn is a
tinted block with an accent rail; agent prose is plain text; tool
calls are compact bordered rows expanding to output or a coloured,
horizontally-scrolling diff computed from ACP's full old/new text.
The client renders `reduced_state` and rows exactly as received, with
no raw-event folding or turn tracking of its own.

Extracted attach.ts's pane-header title building into paneTitle.ts and
its connection interface into pane.ts (PaneConnection) so both
connection kinds share one contract and one header.
This commit is contained in:
Miguel Palhas
2026-09-05 06:10:40 +01:00
parent 32d4058c96
commit a50f098c8a
16 changed files with 2609 additions and 61 deletions
+190
View File
@@ -60,8 +60,15 @@ export interface Session {
* `session/new` (#134). Only a `Structured` session whose handshake
* succeeded has one; a respawn passes it to `session/load` (#135). */
acp_session_id?: string | null;
/** Terminal (PTY bytes) or structured (ACP rows) (#133). Fixed at spawn and
* immutable for the session's life. Defaults to `"Terminal"` on the wire, so
* absent means terminal. */
view?: SessionView;
}
/** A session's process shape (#133): mirrors `maestro_protocol::SessionView`. */
export type SessionView = "Terminal" | "Structured";
/** A session's daemon-created worktree (`SessionWorktree` on the wire). */
export interface SessionWorktree {
path: string;
@@ -367,6 +374,189 @@ export function abbreviateCwd(cwd: string, home?: string): string {
return cwd;
}
// ---------------------------------------------------------------------------
// Structured-session projections (#133/#140). Mirror of
// `maestro_protocol`'s "Structured-session projections" section. `data`,
// `ReducedState.plan/usage/context/pending_approval` and every `Acp*` type
// below are the daemon's opaque ACP payloads (`serde_json::Value` on the
// wire) — shaped to `claude-code-acp`'s ACP v1 schema, not covered by
// maestro-protocol's own compatibility guarantee. Treat every field as
// optional and degrade gracefully rather than trust this shape exactly.
// ---------------------------------------------------------------------------
/** `maestro_protocol::TranscriptRowKind`, snake_case on the wire. */
export type TranscriptRowKind =
| "user"
| "agent_text"
| "agent_thought"
| "tool_call"
| "tool_diff"
| "approval"
| "plan"
| "notice";
/** One row of a structured session's transcript. */
export interface TranscriptRow {
id: string;
kind: TranscriptRowKind;
data: unknown;
}
/** The complete transcript at a durable event-log position (`WS
* /api/structured/:id`'s first message, and every replay page). */
export interface TranscriptSnapshot {
cursor: number;
rows: TranscriptRow[];
}
/** A change to one transcript row, addressed by `id`. */
export type TranscriptDelta =
| { type: "append"; row: TranscriptRow }
| { type: "patch"; row: TranscriptRow }
| { type: "remove"; id: string };
/** Per-turn indicators derived from the ACP stream — read verbatim, never
* re-derived client-side (docs/STRUCTURED-VIEW.md). */
export interface TurnState {
responding: boolean;
thinking: boolean;
active_tool_calls: string[];
}
/** A whole-session view derived from ACP notifications. `plan`/`usage`/
* `context`/`pending_approval` are opaque ACP JSON — see the module note
* above. `pending_approval` is `{nonce, request: AcpRequestPermissionRequest}`
* while a permission request is live, absent otherwise. */
export interface ReducedState {
turn: TurnState;
pending_approval?: { nonce: string; request: AcpRequestPermissionRequest } | null;
plan?: AcpPlan | null;
usage?: AcpUsage | null;
context?: AcpUsage | null;
model?: string | null;
mode?: string | null;
}
/** Server messages on `WS /api/structured/:id`. */
export type StructuredEvent =
| { type: "transcript_snapshot"; snapshot: TranscriptSnapshot }
| { type: "reduced_state"; state: ReducedState }
| { type: "projection_update"; transcript?: TranscriptDelta | null; state: ReducedState };
/** `POST /api/sessions/:id/structured/prompt` body. */
export interface StructuredPromptRequest {
prompt: string;
}
/** `POST /api/sessions/:id/structured/approvals/:nonce` body — a bare JSON
* string (a bracketless Rust enum), not `{decision: ...}`. */
export type StructuredApprovalDecision = "allow_once" | "allow_for_session" | "deny";
// ---- ACP v1 payload shapes (agent-client-protocol schema, camelCase) ----
/** `ContentBlock`. Only `text` is common in practice; the rest degrade to a
* generic placeholder rather than being dropped silently. */
export type AcpContentBlock =
| { type: "text"; text: string }
| { type: "image"; mimeType?: string }
| { type: "audio"; mimeType?: string }
| { type: "resource_link"; uri?: string; name?: string }
| { type: "resource"; resource?: unknown };
/** `ContentChunk` — the payload of a `User`/`AgentText`/`AgentThought` row. */
export interface AcpContentChunk {
content: AcpContentBlock;
messageId?: string | null;
}
/** `ToolKind`, snake_case on the wire. */
export type AcpToolKind =
| "read"
| "edit"
| "delete"
| "move"
| "search"
| "execute"
| "think"
| "fetch"
| "switch_mode"
| "other";
/** `ToolCallStatus`, snake_case on the wire. */
export type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
/** `Diff` — a file modification. `oldText` absent means a new file. */
export interface AcpDiff {
path: string;
oldText?: string | null;
newText: string;
}
/** `ToolCallContent`. */
export type AcpToolCallContent =
| { type: "content"; content: AcpContentBlock }
| ({ type: "diff" } & AcpDiff)
| { type: "terminal"; terminalId?: string };
export interface AcpToolCallLocation {
path: string;
line?: number | null;
}
/** `ToolCall` (a `ToolCall`/`ToolDiff` row's `data`) and, loosely, the
* flattened `ToolCallUpdate` an approval's `toolCall` field carries — the
* two share every field below, just with different subsets required. */
export interface AcpToolCallLike {
toolCallId?: string;
title?: string;
/** Unstable ACP capability; absent when the adapter doesn't send one. */
name?: string | null;
kind?: AcpToolKind;
status?: AcpToolCallStatus;
content?: AcpToolCallContent[];
locations?: AcpToolCallLocation[];
rawInput?: unknown;
rawOutput?: unknown;
}
/** `PlanEntryPriority` / `PlanEntryStatus`, snake_case on the wire. */
export type AcpPlanPriority = "high" | "medium" | "low";
export type AcpPlanEntryStatus = "pending" | "in_progress" | "completed";
export interface AcpPlanEntry {
content: string;
priority: AcpPlanPriority;
status: AcpPlanEntryStatus;
}
/** `Plan` — `ReducedState.plan`. */
export interface AcpPlan {
entries: AcpPlanEntry[];
}
/** `UsageUpdate` — `ReducedState.usage`/`.context` (the daemon folds one
* update into both fields). */
export interface AcpUsage {
used: number;
size: number;
cost?: { amount: number; currency: string } | null;
}
export interface AcpPermissionOption {
optionId: string;
name: string;
kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
}
/** `RequestPermissionRequest`, serialized without its nonce (the nonce lives
* only in `ReducedState.pending_approval.nonce`) — an `Approval` row's `data`,
* and `ReducedState.pending_approval.request`. */
export interface AcpRequestPermissionRequest {
sessionId: string;
toolCall: AcpToolCallLike;
options: AcpPermissionOption[];
}
/** `~/git.naps.pt/naps62/maestro` → `~/g/n/maestro`: keep the last segment
* verbatim, collapse every earlier one to its first character. Two-or-fewer
* segments are left alone (nothing to gain). Returns escaped HTML with the