@pellux/goodvibes-tui 1.23.0 → 1.24.0

package/src/cluster/remote-daemon-target.ts

@@ -0,0 +1,225 @@
+/**
+ * remote-daemon-target.ts — how a subcommand reaches a daemon.
+ *
+ * Lives under src/cluster/ rather than src/daemon/ so the TUI can use it too:
+ * `/cluster` and the `cluster` subcommands must reach the same daemon the same
+ * way, and the architecture rules (rightly) forbid the input layer from
+ * importing a CLI entrypoint.
+ *
+ * ── THE CONVENTION ────────────────────────────────────────────────────────
+ *
+ * This is the first daemon subcommand that talks to a RUNNING daemon rather
+ * than to systemd, so it establishes the pattern every later one should follow.
+ * If you are adding `goodvibes-daemon <something>` that needs the daemon
+ * itself, use this module rather than inventing a second way.
+ *
+ *   --host <name>   default: the control plane's configured host, which for a
+ *                   default install is 127.0.0.1
+ *   --port <n>      default: the control plane's configured port
+ *   --token <t>     default: this machine's operator token, read from
+ *                   <daemon home>/operator-tokens.json
+ *
+ * Authentication is `Authorization: Bearer <operator token>` against the
+ * control plane — the same credential the TUI and the web UI already use.
+ *
+ * The defaults are the whole point. A homelab box is headless: the operator has
+ * SSHed into it and wants `cluster status` to work with no flags at all. Flags
+ * exist for the other case — driving a machine in the next room from a laptop —
+ * and for scripting.
+ *
+ * What this module deliberately does NOT do: hold any knowledge of what the
+ * verbs mean. It resolves a target, makes a request, and returns the parsed
+ * body. Every decision about what the answer MEANS belongs to the daemon.
+ */
+import { readControlPlaneBinding } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { readOperatorTokenFile } from '@pellux/goodvibes-sdk/platform/workspace';
+
+/** Where to send a verb, and what to authenticate with. */
+export interface RemoteDaemonTarget {
+  readonly baseUrl: string;
+  readonly token: string;
+  /** True when the target is this machine's own daemon, for message wording. */
+  readonly isLocal: boolean;
+}
+
+/** The flags every remote-capable daemon subcommand accepts. */
+export interface RemoteTargetFlags {
+  readonly host?: string | undefined;
+  readonly port?: number | undefined;
+  readonly token?: string | undefined;
+}
+
+export type RemoteTargetResolution =
+  | { readonly ok: true; readonly target: RemoteDaemonTarget }
+  | { readonly ok: false; readonly error: string; readonly fix: string };
+
+export interface ResolveRemoteTargetInput {
+  readonly flags: RemoteTargetFlags;
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly daemonHomeDir: string;
+  /** Injectable so tests never read a real token file. */
+  readonly readToken?: ((daemonHomeDir: string) => string | undefined) | undefined;
+}
+
+/**
+ * Pull the token out of the operator-token file's contents.
+ *
+ * `readOperatorTokenFile` hands back the FILE, and the file is a JSON record —
+ * `{ token, peerId, createdAt }` — not a bare token. Sending the whole document
+ * as a bearer credential produces a 401 that looks exactly like a stale token,
+ * which is a genuinely confusing way to fail. A file that is not JSON is
+ * treated as a bare token, which is what a hand-written one would be.
+ */
+export function extractOperatorToken(contents: string | undefined): string | undefined {
+  const trimmed = contents?.trim();
+  if (!trimmed) return undefined;
+  if (!trimmed.startsWith('{')) return trimmed;
+  try {
+    const parsed = JSON.parse(trimmed) as { token?: unknown };
+    return typeof parsed.token === 'string' && parsed.token.length > 0 ? parsed.token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Work out which daemon to talk to.
+ *
+ * A missing token is a refusal rather than an anonymous attempt: sending an
+ * unauthenticated request would come back 401 and the operator would be left
+ * guessing whether the daemon was down or the credential was missing.
+ */
+export function resolveRemoteDaemonTarget(input: ResolveRemoteTargetInput): RemoteTargetResolution {
+  const binding = readControlPlaneBinding((key) => input.configManager.get(key as never));
+  const host = input.flags.host?.trim() || binding.host;
+  const port = input.flags.port ?? binding.port;
+  if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+    return {
+      ok: false,
+      error: `'${String(port)}' is not a usable port`,
+      fix: 'pass --port with a number between 1 and 65535',
+    };
+  }
+
+  const isLocal = host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '0.0.0.0';
+  const explicitToken = input.flags.token?.trim();
+  const token = explicitToken
+    || extractOperatorToken((input.readToken ?? readOperatorTokenFile)(input.daemonHomeDir));
+  if (!token) {
+    return {
+      ok: false,
+      error: 'no operator token was found for this machine',
+      fix: isLocal
+        ? 'start the daemon once so it creates its operator token, or pass --token'
+        : 'pass --token with the operator token from the machine you are trying to reach',
+    };
+  }
+
+  return { ok: true, target: { baseUrl: buildBaseUrl(host, port, binding.tlsMode), token, isLocal } };
+}
+
+/**
+ * Build the URL to CALL.
+ *
+ * Deliberately not `deriveControlPlaneBaseUrl`. That function answers a
+ * different question — where a daemon should BIND — and it applies the
+ * `hostMode` policy while doing so: with the default `local` mode it forces
+ * 127.0.0.1 and discards the host it was given. For a client that is precisely
+ * wrong, and it silently turned `--host 10.0.0.7` into a call to this machine.
+ *
+ * Here the host the operator typed is the host, full stop. Only the scheme
+ * comes from configuration.
+ */
+function buildBaseUrl(host: string, port: number, tlsMode: string | undefined): string {
+  const scheme = tlsMode && tlsMode !== 'off' && tlsMode !== 'none' ? 'https' : 'http';
+  // An IPv6 literal has to be bracketed or the port reads as part of the address.
+  const authority = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  return `${scheme}://${authority}:${port}`;
+}
+
+/**
+ * The one thing this module needs from `fetch`.
+ *
+ * Narrower than `typeof fetch` on purpose: the global carries runtime-specific
+ * extras (Bun adds `preconnect`) that a test double has no business
+ * implementing, and requiring them would push every test into an `any`.
+ */
+export type DaemonFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** What a verb call came back with. */
+export type DaemonVerbOutcome<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: string; readonly fix: string };
+
+/**
+ * Call a daemon verb.
+ *
+ * Every failure shape becomes an `error`/`fix` pair in plain language, because
+ * this is the layer where "ECONNREFUSED" has to turn into something an operator
+ * can act on. The daemon's OWN refusals already carry a fix and are passed
+ * through unchanged rather than being reworded here.
+ */
+export async function callDaemonVerb<T>(
+  target: RemoteDaemonTarget,
+  path: string,
+  init: { method: 'GET' | 'POST'; body?: unknown } = { method: 'GET' },
+  fetchImpl: DaemonFetch = fetch,
+): Promise<DaemonVerbOutcome<T>> {
+  const where = target.isLocal ? 'the daemon on this machine' : `the daemon at ${target.baseUrl}`;
+  let response: Response;
+  try {
+    response = await fetchImpl(`${target.baseUrl}${path}`, {
+      method: init.method,
+      headers: {
+        Authorization: `Bearer ${target.token}`,
+        ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: `could not reach ${where}`,
+      fix: target.isLocal
+        ? 'check the daemon is running: goodvibes-daemon service-status'
+        : `check that machine is switched on and reachable, and that its daemon is listening on ${target.baseUrl} `
+          + `(${error instanceof Error ? error.message : 'no further detail'})`,
+    };
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    return {
+      ok: false,
+      error: `${where} refused the operator token`,
+      fix: target.isLocal
+        ? 'the token may be stale — restart the daemon, or pass --token'
+        : 'pass --token with the operator token from that machine (its <daemon home>/operator-tokens.json)',
+    };
+  }
+  if (response.status === 404) {
+    return {
+      ok: false,
+      error: `${where} does not know this command`,
+      fix: 'that daemon is running an older build — update it, then try again',
+    };
+  }
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch {
+    return {
+      ok: false,
+      error: `${where} sent a reply this build could not read`,
+      fix: 'check that both machines are running the same version',
+    };
+  }
+  const body = payload as { ok?: unknown; data?: unknown; error?: unknown; fix?: unknown };
+  if (body.ok === true) return { ok: true, data: body.data as T };
+  return {
+    ok: false,
+    error: typeof body.error === 'string' ? body.error : `${where} refused the request`,
+    fix: typeof body.fix === 'string' ? body.fix : 'run `cluster status` to see the current state',
+  };
+}

package/src/cluster/render.ts

@@ -0,0 +1,268 @@
+/**
+ * render.ts — turning the daemon's answers into lines a person reads.
+ *
+ * Every function here is pure: structured data in, strings out. The verb layer
+ * decided what is true; this decides how to say it. That split is what lets
+ * `--json` print the same data with no second code path, and what lets the TUI
+ * and a web UI render the same answers their own way.
+ */
+import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
+import type {
+  RotateKeyResult,
+  CreateGroupResult,
+  DiscoveredGroup,
+  ForgetNodeResult,
+  GroupStatusReport,
+  JoinGroupResult,
+  JoinKeyResult,
+  NodesResult,
+} from '@pellux/goodvibes-sdk/platform/cluster';
+
+/** How long ago, in words. Never a raw timestamp — nobody reads epoch millis. */
+export function describeAge(at: number, now: number): string {
+  const seconds = Math.max(0, Math.round((now - at) / 1_000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + ' '.repeat(width - value.length);
+}
+
+/**
+ * `cluster status`.
+ *
+ * Leads with the thing the operator came for — the role of THIS machine and
+ * which surfaces it holds — and finishes with the one sentence of advice, if
+ * there is anything to do.
+ */
+export function renderStatus(report: GroupStatusReport, now: number): string[] {
+  if (report.membership !== 'member') {
+    return [
+      report.membership === 'no-group'
+        ? 'this machine is not in a group'
+        : 'this machine has group key material that could not be read',
+      `machine: ${report.nodeName} (${report.nodeId})`,
+      `version: ${report.version}`,
+      ...(report.advice ? ['', report.advice] : []),
+    ];
+  }
+  const lines = [
+    `group:    ${report.groupName ?? '(unnamed)'}  [${report.groupId ?? 'unknown'}]`,
+    `machine:  ${report.nodeName} (${report.nodeId})`,
+    `members:  ${report.memberCount}`,
+    `version:  ${report.version}`,
+  ];
+
+  if (report.surfaces === null) {
+    lines.push('surfaces: not reported by this daemon');
+  } else if (report.surfaces.length === 0) {
+    lines.push('surfaces: none held by this machine right now');
+  } else {
+    lines.push('surfaces held by this machine:');
+    for (const holding of report.surfaces) {
+      lines.push(`  ${holding.surfaceId}  — ${holding.reason}`);
+    }
+  }
+
+  lines.push(
+    '',
+    `group key: generation ${report.keyGeneration ?? 0}, rotates every ${report.rotationHours}h`,
+    `           ${report.keyGenerationsHeld} of at most ${report.keyGenerationCap} generations kept; `
+      + `accepting ${report.acceptedGenerations.join(' and ') || 'none'}`,
+  );
+  if (report.removedNodeCount > 0) {
+    lines.push(`removed machines on record: ${report.removedNodeCount}`);
+  }
+  if (report.replication) {
+    const replication = report.replication;
+    lines.push(
+      '',
+      `shared settings: ${replication.entries} setting${replication.entries === 1 ? '' : 's'} and `
+        + `${replication.secrets} credential${replication.secrets === 1 ? '' : 's'} at revision ${replication.revision}`,
+    );
+    if (replication.tombstones > 0) {
+      lines.push(`                 ${replication.tombstones} deleted setting(s) still on record`);
+    }
+    if (replication.lastAppliedFrom) {
+      lines.push(
+        `                 last change from ${replication.lastAppliedFrom}`
+          + (replication.lastAppliedAt ? ` ${describeAge(replication.lastAppliedAt, now)}` : ''),
+      );
+    }
+    if (replication.pendingProposals > 0) {
+      lines.push(`                 ${replication.pendingProposals} change(s) waiting for the responsible machine`);
+    }
+  }
+  if (report.wire) {
+    lines.push(
+      `traffic:   ${report.wire.sent} sent, ${report.wire.received} received; dropped `
+        + `${report.wire.droppedOtherGroup} from other groups, ${report.wire.droppedBadSignature} unverified, `
+        + `${report.wire.droppedOldGeneration} on an old key, ${report.wire.droppedMalformed} malformed`
+        + (report.wire.droppedNoGroup > 0
+          ? `; ${report.wire.droppedNoGroup} not sent because this machine is in no group`
+          : ''),
+    );
+  }
+  if (report.advice) lines.push('', report.advice);
+  // Deliberately absent, and it should stay absent: the join key, the group
+  // key, any generation of it, this machine's private keys, and the VALUE of
+  // any replicated credential. `cluster key` is the only path to the join key
+  // and nothing shows the rest at all.
+  return lines;
+}
+
+/** `cluster nodes`. */
+export function renderNodes(result: NodesResult, now: number): string[] {
+  const lines = [`group: ${result.groupName}  [${result.groupId}]`, ''];
+  if (result.members.length === 0) {
+    lines.push('no machines in this group yet');
+  } else {
+    const width = Math.max(...result.members.map((member) => member.displayName.length), 12);
+    lines.push(`${pad('MACHINE', width)}  ${pad('NODE ID', 38)}  LAST SEEN`);
+    for (const member of result.members) {
+      const suffix = member.isThisMachine ? '  (this machine)' : '';
+      lines.push(
+        `${pad(member.displayName, width)}  ${pad(member.nodeId, 38)}  ${describeAge(member.lastSeenAt, now)}${suffix}`,
+      );
+    }
+  }
+  if (result.removed.length > 0) {
+    lines.push('', 'removed from this group:');
+    for (const entry of result.removed) {
+      lines.push(`  ${entry.nodeId}  ${describeAge(entry.removedAt, now)}  (${entry.reason})`);
+    }
+  }
+  return lines;
+}
+
+/** `cluster create`. */
+export function renderCreated(result: CreateGroupResult): string[] {
+  return [
+    `created the group "${result.groupName}"  [${result.groupId}]`,
+    '',
+    result.generatedKey
+      ? 'a join key was generated for you. Run `cluster key` on this machine at any'
+      : 'your join phrase is in use. Run `cluster key` on this machine at any',
+    'time to see it again — it is not a one-time reveal.',
+    '',
+    'to add another machine: run `cluster join` on it and give it this key.',
+    '',
+    `the group name ("${result.groupName}") is visible to anything on this network that`,
+    'is listening for goodvibes groups. Change it any time with `cluster rename`.',
+  ];
+}
+
+/** `cluster join`. */
+export function renderJoined(result: JoinGroupResult): string[] {
+  return [
+    `joined "${result.groupName}"  [${result.groupId}]`,
+    `the group now has ${result.memberCount} machine${result.memberCount === 1 ? '' : 's'}.`,
+  ];
+}
+
+/** `cluster forget`. */
+export function renderForgotten(result: ForgetNodeResult): string[] {
+  return [
+    `removed ${result.displayName} (${result.nodeId}) from the group`,
+    `the group key was replaced immediately, so that machine's copy no longer works.`,
+    `${result.memberCount} machine${result.memberCount === 1 ? '' : 's'} remain${result.memberCount === 1 ? 's' : ''}.`,
+  ];
+}
+
+/** The groups seen advertising themselves on this network. */
+export function renderDiscovered(groups: readonly DiscoveredGroup[], now: number): string[] {
+  if (groups.length === 0) {
+    return [
+      'no goodvibes groups are advertising themselves on this network',
+      '',
+      'if the machine you want to join is switched on and has clustering enabled,',
+      'check that both machines are on the same network and that it is not blocking',
+      'multicast. You can also join by id directly: cluster join --group <id> --key <key>',
+    ];
+  }
+  const width = Math.max(...groups.map((group) => group.displayName.length), 10);
+  const lines = [`${pad('GROUP', width)}  ${pad('ID', 18)}  MACHINES  VERSION  SEEN`];
+  for (const group of groups) {
+    lines.push(
+      `${pad(group.displayName, width)}  ${pad(group.groupId, 18)}  ${pad(String(group.nodeCount), 8)}  `
+        + `${pad(group.version, 7)}  ${describeAge(group.lastSeenAt, now)}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Ask the terminal to put the join key on the clipboard, using OSC 52.
+ *
+ * OSC 52 is the only clipboard mechanism that works through SSH, which is the
+ * case that matters: the operator is on a headless box in a cupboard. It is
+ * also not universally supported and gives no acknowledgement, so this NEVER
+ * claims success — it says what it attempted, and the key is printed either
+ * way. Silently doing nothing would be the worst of the three options.
+ */
+export function clipboardEscapeSequence(value: string): string {
+  return `]52;c;${Buffer.from(value, 'utf8').toString('base64')}`;
+}
+
+export interface JoinKeyRendering {
+  /** Lines to print. */
+  readonly lines: string[];
+  /** The raw escape sequence to write, or null when the output is not a terminal. */
+  readonly clipboardSequence: string | null;
+}
+
+export function renderJoinKey(result: JoinKeyResult, isTerminal: boolean): JoinKeyRendering {
+  return {
+    lines: [
+      `join key for "${result.groupName}"  [${result.groupId}]`,
+      '',
+      `  ${result.joinKey}`,
+      '',
+      ...(isTerminal
+        ? ['copied to the clipboard, if this terminal accepts clipboard writes over its connection.',
+          'if nothing was copied, the key is printed above.']
+        : ['(not a terminal, so no clipboard copy was attempted)']),
+      '',
+      `to add a machine: run  cluster join --group ${result.groupId} --key <the key above>`,
+    ],
+    clipboardSequence: isTerminal ? clipboardEscapeSequence(result.joinKey) : null,
+  };
+}
+
+/** `cluster rotate`. */
+export function renderRotated(result: RotateKeyResult): string[] {
+  return [
+    `the group key is now generation ${result.keyGeneration}`,
+    result.immediate
+      ? 'the previous key stopped being accepted immediately, and the key the group signs with'
+      : 'the previous key stays accepted for a few minutes so nothing is interrupted while',
+    result.immediate
+      ? 'was replaced too. A machine that is asleep right now will ask to come back when it wakes.'
+      : `the other ${Math.max(0, result.memberCount - 1)} machine(s) pick the new one up.`,
+    '',
+    `accepting generation${result.acceptedGenerations.length === 1 ? '' : 's'} `
+      + `${result.acceptedGenerations.join(' and ')}`,
+  ];
+}
+
+/**
+ * The join key as a QR code, for typing it into a phone or a second terminal.
+ *
+ * This reuses the daemon's existing QR renderer verbatim — the same one the
+ * pairing flow already prints to a terminal — rather than introducing any new
+ * machinery for it. Opt-in behind `--qr`, because a QR block is tall and most
+ * of the time the operator is copying the key with the mouse or the clipboard.
+ */
+export function renderJoinKeyQr(joinKey: string): string[] {
+  return [renderQrToString(generateQrMatrix(joinKey))];
+}
+
+/** A refusal, in the shape every failing subcommand prints. */
+export function renderFailure(error: string, fix: string): string[] {
+  return [`cluster: ${error}`, `  ${fix}`];
+}

package/src/core/conversation-line-cache.ts

@@ -54,8 +54,9 @@ import {
   renderConversationToolCallNode,
   renderConversationToolMessage,
   renderConversationUserMessage,
-  collectCompletedToolCallIds,
+  collectToolCallOutcomes,
   isTurnCollapsed,
+  type ToolCallOutcome,
 } from './conversation-rendering.ts';
 import {
   buildRenderPlan,
@@ -149,10 +150,12 @@ interface KeyMeta {
  * invalidate the entry, rather than waiting for every call in the message to
  * complete before any of them re-renders as done.
  */
-function pendingToolKeyOf(m: Message, completed: ReadonlySet<string>): string | undefined {
+function pendingToolKeyOf(m: Message, outcomes: ReadonlyMap<string, ToolCallOutcome>): string | undefined {
   if (m.role !== 'assistant' || !m.toolCalls || m.toolCalls.length === 0) return undefined;
+  // The OUTCOME, not merely ran/not-ran: a call whose result turns out to be a
+  // failure must repaint its glyph from ◌ to ✗, which a boolean would miss.
   return m.toolCalls
-    .map((tc) => `${tc.id ?? ''}:${tc.id !== undefined && completed.has(tc.id) ? 1 : 0}`)
+    .map((tc) => `${tc.id ?? ''}:${(tc.id !== undefined && outcomes.get(tc.id)) || 'pending'}`)
     .join('|');
 }
 
@@ -338,7 +341,8 @@ export class MessageLineCache {
 
     // Tool calls with no matching tool-result message are still pending; the
     // render context and the cache key both depend on this. (item 2c.)
-    const completedToolCallIds = collectCompletedToolCallIds(messages);
+    const toolCallOutcomes = collectToolCallOutcomes(messages);
+    const completedToolCallIds = new Set(toolCallOutcomes.keys());
     const assistantTurns = computeAssistantTurns(messages, msgIndexOffset);
     // Structural plan: a permutation of the slice (results lifted under their
     // calls, spawned agents spliced under the call that spawned them), rebuilt
@@ -346,7 +350,7 @@ export class MessageLineCache {
     const plan = buildRenderPlan(messages, msgIndexOffset, {
       resolveAgentSnapshot: context.resolveAgentSnapshot,
     });
-    const renderContext: ConversationRenderContext = { ...context, completedToolCallIds, assistantTurns };
+    const renderContext: ConversationRenderContext = { ...context, completedToolCallIds, toolCallOutcomes, assistantTurns };
 
     const touched = new Set<string>();
     const turnHeaderLines = new Map<string, number>();
@@ -373,7 +377,7 @@ export class MessageLineCache {
       const trailingBlank = !next || next.depth === 0;
       const uncacheable = isRoot && node.kind === 'message' && node.absIdx === streamingPlaceholderAbsIdx;
       const kind = isRoot ? context.messageKindRegistry.get(node.absIdx) : undefined;
-      const pendingToolKey = pendingToolKeyOf(node.message, completedToolCallIds);
+      const pendingToolKey = pendingToolKeyOf(node.message, toolCallOutcomes);
 
       if (!uncacheable) {
         const existing = this.entries.get(node.id);
@@ -482,6 +486,7 @@ export class MessageLineCache {
       configManager: context.configManager,
       splashOptions: context.splashOptions,
       completedToolCallIds: context.completedToolCallIds,
+      toolCallOutcomes: context.toolCallOutcomes,
       assistantTurns: context.assistantTurns,
       resolveAgentSnapshot: context.resolveAgentSnapshot,
     };

package/src/core/conversation-render-context.ts

@@ -0,0 +1,122 @@
+/**
+ * conversation-render-context.ts — the inputs a transcript row render reads,
+ * and the small pure derivations over them.
+ *
+ * Kept apart from conversation-rendering.ts (which draws) so that both the
+ * drawing module and the per-row modules that hang off it can depend on the
+ * SHAPE of a render without depending on each other. Every import here is
+ * type-only, which is what makes this a leaf of the import graph.
+ */
+
+import type { Line } from '../types/grid.ts';
+import type { BlockMeta } from './conversation-types.ts';
+import type { AssistantTurnMembership } from './conversation-turn-structure.ts';
+import type { SplashOptions } from '../utils/splash-lines.ts';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+// SystemMessageKind imported from runtime directly to avoid cycle:
+//   conversation-rendering.ts → system-message-router.ts → conversation.ts → conversation-rendering.ts
+import type { SystemMessageKind } from '@/runtime/index.ts';
+
+type Message = ConversationMessageSnapshot;
+
+/**
+ * How a tool call settled, as read from the result message it produced.
+ *
+ * The transcript stores a failure as content leading with `Error: ` (see the
+ * SDK's ConversationManager.addToolResults), and a per-call user cancellation
+ * as the more specific `Error: cancelled by user`. Reading the outcome —
+ * rather than only "did a result arrive" — is what lets the CALL row show
+ * ✓ / ✕ / ⊘ honestly instead of a ✓ that means nothing more than "it finished".
+ */
+export type ToolCallOutcome = 'ok' | 'error' | 'cancelled';
+
+function outcomeOfToolContent(content: string): ToolCallOutcome {
+  if (/^Error: cancelled by user\b/.test(content)) return 'cancelled';
+  if (/^Error: /.test(content)) return 'error';
+  return 'ok';
+}
+
+/**
+ * Collect, per tool-call id, how that call settled — for the calls that have a
+ * matching tool-result message in the given slice. A call absent from the map
+ * has not run yet (e.g. it is still awaiting an approval decision) and renders
+ * with the pending glyph. (item 2c.)
+ */
+export function collectToolCallOutcomes(messages: readonly Message[]): Map<string, ToolCallOutcome> {
+  const outcomes = new Map<string, ToolCallOutcome>();
+  for (const message of messages) {
+    if (message.role === 'tool' && message.callId) {
+      outcomes.set(message.callId, outcomeOfToolContent(message.content));
+    }
+  }
+  return outcomes;
+}
+
+/**
+ * Ids of tool calls that have a matching tool-result message — i.e. the tools
+ * that actually ran, regardless of how they settled. Derived from
+ * collectToolCallOutcomes so the two can never disagree about what "ran" means.
+ */
+export function collectCompletedToolCallIds(messages: readonly Message[]): Set<string> {
+  return new Set(collectToolCallOutcomes(messages).keys());
+}
+
+export interface ConversationRenderContext {
+  readonly history: {
+    addLine: (line: Line) => void;
+    addLines: (lines: Line[]) => void;
+    getLineCount: () => number;
+  };
+  readonly blockRegistry: BlockMeta[];
+  readonly collapseState: Map<string, boolean>;
+  readonly errorLineRegistry: number[];
+  /** Maps message index → SystemMessageKind for typed system messages. */
+  readonly messageKindRegistry: ReadonlyMap<number, SystemMessageKind>;
+  readonly configManager: ConfigManager | null;
+  readonly splashOptions: SplashOptions;
+  /**
+   * Tool-call ids that have a corresponding tool-result message (i.e. the tool
+   * actually ran). An assistant tool call whose id is NOT in this set is still
+   * awaiting a decision (e.g. an approval prompt) and renders with a pending
+   * glyph instead of the completed ✓. When undefined (single-message callers
+   * without sibling context), every tool call renders as done — the prior
+   * behaviour. (item 2c.)
+   */
+  readonly completedToolCallIds?: ReadonlySet<string>;
+  /**
+   * How each settled tool call turned out, keyed by call id (see
+   * collectToolCallOutcomes). Lets a call row show ✕ for a failure and ⊘ for a
+   * cancellation instead of a blanket ✓ the moment any result arrives. When
+   * undefined the row falls back to completedToolCallIds' ran/not-ran split.
+   */
+  readonly toolCallOutcomes?: ReadonlyMap<string, ToolCallOutcome>;
+  /**
+   * Which assistant messages share one `● assistant` header, and what that
+   * header must say (see conversation-turn-structure.ts). Keyed by absolute
+   * index for every assistant message in a run AND every tool-result message
+   * the run's calls produced, so a collapsed turn can hide its results too.
+   * A message absent from this map (or an undefined map) renders standalone,
+   * exactly as it did before turn merging.
+   */
+  readonly assistantTurns?: ReadonlyMap<number, AssistantTurnMembership>;
+  /**
+   * Live snapshot reader for a spawned agent's own conversation, used to
+   * splice that agent's rows in beneath the call that spawned it (see
+   * conversation-turn-structure.ts). Undefined disables nesting entirely and
+   * the transcript renders exactly as it would without subagents.
+   */
+  readonly resolveAgentSnapshot?: (agentId: string) => readonly Message[] | null;
+}
+
+/**
+ * Whether a turn's branches are hidden. Turns default to EXPANDED (unlike
+ * every other collapsible block here, which defaults to collapsed): a turn
+ * collapsed by default would hide the activity the transcript exists to show.
+ */
+export function isTurnCollapsed(
+  turn: AssistantTurnMembership | undefined,
+  collapseState: ReadonlyMap<string, boolean>,
+): boolean {
+  return turn !== undefined && (collapseState.get(turn.turnKey) ?? false);
+}