my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-sdk/src/transcript.ts

@@ -0,0 +1,291 @@
+// Normalize pi-durable entries + live generation state into renderable transcript items.
+// The web UI, the TUI and the backend's /transcript endpoint all use this, so every
+// interface stitches tool calls, results and live output the same way.
+import type {
+  WireAssistantMessage,
+  WireEntry,
+  WireMessage,
+  WireToolResultMessage,
+  WireToolSlot,
+  WireUsage,
+  WireUsageState,
+} from "./api.js";
+
+export type ToolStatus = "pending" | "running" | "done" | "error";
+
+export interface ToolCallView {
+  callId: string;
+  name: string;
+  args: unknown;
+  status: ToolStatus;
+  /** Live output while running. */
+  output?: string;
+  /** Result text once the result entry exists, or once a nested call returns its result. */
+  result?: string;
+  resultEntryId?: number;
+  /** Nested call metadata: the parent call that made it, and the call's own task. */
+  nested?: { parentCallId: string; parentTaskId: number; taskId: number };
+  /** One-line summary of how a nested call ended (duration, spend, error). */
+  summary?: string;
+}
+
+export type AssistantBlockView =
+  | { type: "text"; text: string }
+  | { type: "thinking"; text: string }
+  | { type: "tool"; call: ToolCallView };
+
+export type TranscriptItem =
+  | { kind: "user"; id: number; text: string }
+  | {
+      kind: "assistant";
+      id: number | "live";
+      streaming: boolean;
+      blocks: AssistantBlockView[];
+      error?: string;
+      model?: string;
+    }
+  | { kind: "tool-result"; id: number; name: string; text: string; isError: boolean }
+  | { kind: "tool"; id: string; call: ToolCallView }
+  | { kind: "event"; id: number; entryKind: string; text: string; note?: string; data?: unknown };
+
+export interface LiveTool {
+  name: string;
+  status: "pending" | "running" | "done";
+  output: string;
+  args?: unknown;
+  /** Set for a nested call (one a running tool made through `executeTool()`). */
+  nested?: { parentCallId: string; parentTaskId: number; taskId: number };
+  /** A nested result kept for display when no transcript entry holds it. */
+  result?: { text: string; isError: boolean };
+  /** How a nested call ended, for a status line (`NestedToolSummary`). */
+  summary?: { isError: boolean; durationMs?: number; usage?: unknown; error?: string };
+}
+
+const isAssistant = (m: WireMessage): m is WireAssistantMessage => m.role === "assistant";
+const isToolResult = (m: WireMessage): m is WireToolResultMessage => m.role === "toolResult";
+
+export function messageText(message: WireMessage): string {
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block: { type?: string; text?: string }) => (block.type === "text" ? (block.text ?? "") : ""))
+    .join("");
+}
+
+export function assistantError(message: WireAssistantMessage): string | undefined {
+  if (message.errorMessage) return message.errorMessage;
+  if (message.stopReason === "aborted") return "Interrupted. Partial response preserved.";
+  if (message.stopReason === "error") return "Provider request failed.";
+  return undefined;
+}
+
+function eventText(entry: WireEntry): string {
+  const data = entry.data as { text?: unknown } | undefined;
+  if (typeof data?.text === "string") return data.text;
+  if (entry.kind === "pi.reset") return "New context started. Earlier entries remain stored.";
+  if (entry.kind === "pi.compaction") return "Context compacted. Earlier entries remain stored.";
+  return entry.kind;
+}
+
+export function toTranscript(
+  entries: readonly WireEntry[],
+  live?: WireAssistantMessage,
+  tools: ReadonlyMap<string, LiveTool> = new Map(),
+): TranscriptItem[] {
+  const results = new Map<string, { entryId: number; message: WireToolResultMessage }>();
+  const callIds = new Set<string>();
+  for (const entry of entries) {
+    for (const message of entry.model ?? []) {
+      if (entry.kind === "pi.tool-result" && isToolResult(message))
+        results.set(message.toolCallId, { entryId: entry.id, message });
+      if (entry.kind === "pi.assistant" && isAssistant(message))
+        for (const block of message.content) if (block.type === "toolCall") callIds.add(block.id);
+    }
+  }
+  if (live) for (const block of live.content) if (block.type === "toolCall") callIds.add(block.id);
+
+  const toolView = (id: string, name: string, args: unknown): ToolCallView => {
+    const result = results.get(id);
+    const running = tools.get(id);
+    const nested = running?.nested;
+    if (result)
+      return {
+        callId: id,
+        name,
+        args,
+        status: result.message.isError ? "error" : "done",
+        result: messageText(result.message),
+        resultEntryId: result.entryId,
+        ...(nested ? { nested } : {}),
+      };
+    // A nested call's result lives in its caller's document, not the transcript: render it from the live slot.
+    if (running?.result)
+      return {
+        callId: id,
+        name,
+        args,
+        status: running.result.isError ? "error" : "done",
+        result: running.result.text,
+        ...(nested ? { nested } : {}),
+        ...(running.summary ? { summary: summaryLine(running.summary) } : {}),
+      };
+    return {
+      callId: id,
+      name,
+      args,
+      status: running?.status ?? "pending",
+      output: running?.output || undefined,
+      ...(nested ? { nested } : {}),
+      ...(running?.summary ? { summary: summaryLine(running.summary) } : {}),
+    };
+  };
+
+  const assistantBlocks = (message: WireAssistantMessage): AssistantBlockView[] =>
+    message.content.flatMap((block): AssistantBlockView[] => {
+      if (block.type === "text") return block.text ? [{ type: "text", text: block.text }] : [];
+      if (block.type === "thinking")
+        return block.thinking ? [{ type: "thinking", text: block.thinking }] : [];
+      return [{ type: "tool", call: toolView(block.id, block.name, block.arguments) }];
+    });
+
+  const items: TranscriptItem[] = [];
+  for (const entry of entries) {
+    if (entry.kind === "pi.system") continue;
+    if (entry.kind === "pi.user") {
+      items.push({
+        kind: "user",
+        id: entry.id,
+        text: (entry.model ?? []).map(messageText).join("\n"),
+      });
+    } else if (entry.kind === "pi.assistant") {
+      const messages = (entry.model ?? []).filter(isAssistant);
+      items.push({
+        kind: "assistant",
+        id: entry.id,
+        streaming: false,
+        blocks: messages.flatMap(assistantBlocks),
+        error: messages.map(assistantError).find(Boolean),
+        model: messages[0]?.model,
+      });
+    } else if (entry.kind === "pi.tool-result") {
+      for (const message of (entry.model ?? []).filter(isToolResult)) {
+        if (callIds.has(message.toolCallId)) continue;
+        items.push({
+          kind: "tool-result",
+          id: entry.id,
+          name: message.toolName,
+          text: messageText(message),
+          isError: message.isError,
+        });
+      }
+    } else {
+      items.push({
+        kind: "event",
+        id: entry.id,
+        entryKind: entry.kind,
+        text: eventText(entry),
+        note: entry.model?.length ? (entry.model ?? []).map(messageText).join("\n") : undefined,
+        ...(entry.data !== undefined ? { data: entry.data } : {}),
+      });
+    }
+  }
+  if (live)
+    items.push({
+      kind: "assistant",
+      id: "live",
+      streaming: true,
+      blocks: assistantBlocks(live),
+      model: live.model,
+    });
+  for (const [callId, tool] of tools)
+    // A nested call is presentation of the running tool round: render it even once done (its result is not in the
+    // transcript). A model-issued call renders from its result entry instead, so its stale slot is dropped.
+    if ((tool.status !== "done" || tool.result || tool.nested) && !callIds.has(callId))
+      items.push({ kind: "tool", id: callId, call: toolView(callId, tool.name, tool.args) });
+  return items;
+}
+
+/** "1.2s · error text" style one-liner from a nested call's summary. */
+function summaryLine(summary: { isError: boolean; durationMs?: number; error?: string }): string {
+  const parts: string[] = [];
+  if (summary.durationMs !== undefined) parts.push(`${(summary.durationMs / 1000).toFixed(1)}s`);
+  if (summary.error) parts.push(summary.error);
+  return parts.join(" · ");
+}
+
+export function toMarkdown(items: readonly TranscriptItem[]): string {
+  const out: string[] = [];
+  for (const item of items) {
+    if (item.kind === "user") out.push(`### You (#${item.id})\n\n${item.text}`);
+    else if (item.kind === "assistant") {
+      const parts = item.blocks.map((block) =>
+        block.type === "text"
+          ? block.text
+          : block.type === "thinking"
+            ? `> _thinking:_ ${block.text.replaceAll("\n", " ").slice(0, 400)}`
+            : `- \`${block.call.name}\` ${block.call.status}${block.call.result ? `\n\n\`\`\`\n${block.call.result.slice(0, 2000)}\n\`\`\`` : ""}`,
+      );
+      if (item.error) parts.push(`> ${item.error}`);
+      out.push(`### Agent (${item.id === "live" ? "working" : `#${item.id}`})\n\n${parts.join("\n\n")}`);
+    } else if (item.kind === "tool-result")
+      out.push(`- \`${item.name}\` ${item.isError ? "error" : "result"}\n\n\`\`\`\n${item.text.slice(0, 2000)}\n\`\`\``);
+    else if (item.kind === "tool") out.push(`- \`${item.call.name}\` ${item.call.status}`);
+    else out.push(`_${item.text}_`);
+  }
+  return out.join("\n\n") + "\n";
+}
+
+/** Text of the last assistant entry, for previews and simple clients. */
+export function lastAssistantText(entries: readonly WireEntry[]): string | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.kind !== "pi.assistant") continue;
+    const text = (entry.model ?? []).filter(isAssistant).map(messageText).join("").trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
+export interface UsageSummary {
+  tokens: number;
+  cost: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  inputCost: number;
+  outputCost: number;
+  cacheReadCost: number;
+  cacheWriteCost: number;
+}
+
+export function sumUsage(state?: Pick<WireUsageState, "models"> | { models: Record<string, WireUsage> }): UsageSummary {
+  const total: UsageSummary = {
+    tokens: 0,
+    cost: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    inputCost: 0,
+    outputCost: 0,
+    cacheReadCost: 0,
+    cacheWriteCost: 0,
+  };
+  for (const u of Object.values(state?.models ?? {})) {
+    total.tokens += u.totalTokens ?? u.input + u.output + u.cacheRead + u.cacheWrite;
+    total.cost += u.cost?.total ?? 0;
+    total.input += u.input ?? 0;
+    total.output += u.output ?? 0;
+    total.cacheRead += u.cacheRead ?? 0;
+    total.cacheWrite += u.cacheWrite ?? 0;
+    total.inputCost += u.cost?.input ?? 0;
+    total.outputCost += u.cost?.output ?? 0;
+    total.cacheReadCost += u.cost?.cacheRead ?? 0;
+    total.cacheWriteCost += u.cost?.cacheWrite ?? 0;
+  }
+  return total;
+}
+
+export type { WireToolSlot };

package/apps/dpi-sdk/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

package/apps/dpi-sdk/w

@@ -0,0 +1,20 @@
+{
+  "name": "dpi-sdk",
+  "private": true,
+  "type": "module",
+  "description": "Durable Agent Network contract, client, models and device registry. Browser-safe core; src/node needs yaml; src/protocol needs @sinclair/typebox (browser-safe, no Node builtins).",
+  "scripts": {
+    "check": "tsc --noEmit -p .",
+    "test": "tsx --test tests/*.test.ts",
+    "net": "tsx scripts/net.ts"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.52",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "5.9.3"
+  }
+}

package/apps/dpi-tui/README.md

@@ -0,0 +1,54 @@
+# dpi-tui
+
+A pi-like terminal client for one Durable Agent Network device. It talks straight to a device's `dpi-backend` over the [v1 API](../dpi-backend/API.md) with the device's bearer token, and renders the same transcript items as the web client (`AgentModel` + `toTranscript` from [`dpi-sdk`](../dpi-sdk)). Closing it never stops the agent.
+
+```bash
+just tui attach mac-mini                   # pick a session on mac-mini (or create one in any directory)
+just tui attach mac-mini:triage            # session by name or id; its root agent
+just tui attach mac-mini:triage:alt-path   # a specific agent (id, "main" or name)
+just tui new vm-1 review                   # in the device's first start dir; --cwd takes a path on the device
+cd apps/dpi-tui && npm start -- --url https://my-vm.exe.xyz --token $DPI_TOKEN --save my-vm
+```
+
+Device ids come from `~/.dpi/network.sqlite`, seeded from the repo's `dpi-network.yaml` (created from `dpi-network.example.yaml`). Tokens come from `just net register <id>`. `--url/--token` connects to any backend, and `--save <id>` stores it.
+
+`-s/--session` and `-a/--agent` pick a session and agent. `--new <name>` creates a session, with `--cwd <dir>` on the device and `--model <id>`. `DPI_URL` and `DPI_TOKEN` stand in for `--url` and `--token`, and `DPI_DEVICE` names the default device. `--help` lists every option.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| Enter | send; while the agent works it steers (joins after the current tool round) |
+| Alt+Enter | queue as a follow-up |
+| Esc | interrupt foreground work (background jobs continue) |
+| Shift+Tab | cycle thinking level |
+| Ctrl+L | model picker |
+| Ctrl+O | expand tool output and thinking |
+| Ctrl+C | close an open picker or panel, else clear the input; on an empty input, exit and print the reattach command (session and agent by name when unique, else ids) |
+| Ctrl+D | exit (on an empty input) |
+
+Commands: `/sessions`, `/agents`, `/model`, `/devices`, `/new [name]`, `/fork [entryId] [name]`, `/thinking <level>`, `/compact [instructions]`, `/reset [note]`, `/name <name>`, `/tasks`, `/help`, `/quit`. Any other text starting with `/` goes to the agent.
+
+A send that fails on the network retries with the same `requestId`, so the device admits it once. A failed send keeps the editor text.
+
+## Layout
+
+```
+src/main.ts      args, device resolution, --new
+src/app.ts       TuiAltScreen layout, agent + session streams (SDK follow), keys, submit
+src/render.ts    transcript items → components, cached by item id
+src/pickers.ts   sessions (+ new session with a remote directory walk), agents, models, devices
+src/commands.ts  slash commands
+src/theme.ts     colors and pi-tui themes
+bin/dpi-tui.mjs  runs src/main.ts through tsx, for npm link or npx dpi-tui
+```
+
+## Tests
+
+```bash
+npm run check && npm test   # types; every item kind fits widths 40/80/200 (CJK, emoji, long args)
+tests/smoke.sh faux         # tmux end to end against a faux-provider backend: streaming, steer, Esc, fork, reattach by name
+tests/smoke.sh <device>     # real model on a device: streaming, exit mid-tool, reattach
+```
+
+From the repo root, `just tui check` and `just test smoke [faux|<id>]` run the same. The smoke script needs tmux, curl and openssl. The device run archives its session through the hub at `http://localhost:4781`, so start the hub first or archive the session yourself.

package/apps/dpi-tui/bin/dpi-tui.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Run the TypeScript entry through tsx so `npm link` / `npx dpi-tui` work without a build step.
+import { register } from "tsx/esm/api";
+register();
+await import("../src/main.ts");

package/apps/dpi-tui/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "dpi-tui",
+  "private": true,
+  "type": "module",
+  "bin": { "dpi-tui": "./bin/dpi-tui.mjs" },
+  "scripts": {
+    "start": "tsx src/main.ts",
+    "check": "tsc --noEmit -p .",
+    "test": "tsx --test tests/*.test.ts"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "1.3.0",
+    "tsx": "^4.20.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "5.9.3"
+  }
+}