@dynamicagents/plugins 0.12.0 → 0.14.0

package/README.md

@@ -18,24 +18,32 @@ npm install @dynamicagents/plugins
 
 ## The one file you edit
 
+An agent installs plugins by listing them in `getPlugins()`, on a `StepAgent` from
+`@dynamicagents/core/agent` or a `SubAgent` from `@dynamicagents/core/subagent`:
+
 ```ts
-// src/plugins.ts
-import { arcAgi } from "@dynamicagents/plugins/arc-agi";
+// src/agents/coder/agent.ts
+import { StepAgent } from "@dynamicagents/core/agent";
 import { browser } from "@dynamicagents/plugins/browser";
-import { recall } from "@dynamicagents/plugins/recall";
-
-export interface PluginHost {
-  env: Env;
-  storage: DurableObjectStorage;
-  /** The verified caller this Durable Object belongs to. See below. */
-  callerKey: () => string;
+import { computer, computerWorkspace } from "@dynamicagents/plugins/computer";
+// `workspaceConfig` names the `/workspace` object this agent works in.
+import { repo } from "@dynamicagents/plugins/repo";
+
+export class Coder extends StepAgent<Env> {
+  // `computer` runs commands in a container, so the agent's own workspace —
+  // what Think's `read` and `write` work on — has to be that container's.
+  override workspace = computerWorkspace(workspaceConfig(this.env), () =>
+    this.pluginContext().runtime()
+  );
+
+  override getPlugins() {
+    return [
+      browser({ binding: this.env.BROWSER }),
+      computer(workspaceConfig(this.env)),
+      repo(repoConfig(this.env))
+    ];
+  }
 }
-
-export const plugins = ({ env, storage, callerKey }: PluginHost) => [
-  arcAgi({ apiKey: env.ARC_API_KEY, storage }),
-  browser({ binding: env.BROWSER }),
-  recall({ ai: env.AI, index: env.VECTORIZE, namespace: callerKey })
-];
 ```
 
 Delete a line and that module leaves your bundle entirely. Nothing in core imports a plugin,
@@ -43,54 +51,27 @@ and there is **no root barrel** — `@dynamicagents/plugins` on its own does not
 guarantee is structural rather than a tree-shaker's opinion. `npm run verify:exports` asserts
 it on the built graph before every publish.
 
-`plugins` is a function, not a module-level array: on Workers `env` does not exist at module
-scope, and core's registry is built per Durable Object instance in `onStart()`.
-
-```ts
-export class MyAgent extends Agent<Env> {
-  /** Set on the first verified request; constant thereafter. See below. */
-  private identity?: string;
-
-  async onStart() {
-    this.runtime = createAgentRuntime({
-      config,
-      plugins: plugins({
-        env: this.env,
-        storage: this.ctx.storage,
-        // A thunk, not a value: `onStart` runs before any request, so the caller
-        // is not known yet. The DO is keyed 1:1 by that caller, so it is constant
-        // once it is — this just defers reading it until it exists.
-        callerKey: () => this.identity ?? ""
-      }),
-      env: this.env // verify every plugin's declared bindings exist, at startup
-    });
-  }
-
-  async onTurn(turn: AgentTurn, identity: GatekeeperIdentity) {
-    this.identity ??= identity.key!;
-    // …
-  }
-}
-```
+`getPlugins()` is a method, not a module-level array: on Workers `env` does not exist at
+module scope. Core checks the list when the agent starts — every declared binding present,
+every tool name offered once — so a wiring fault fails the start with a sentence naming the
+plugin, not the first turn.
 
-That deferral is the whole reason `/recall` takes `namespace` as a function. Anything else
-needing per-caller state takes it the same way.
+A plugin's tools are the same wherever it is installed, so what a sub-agent must not have is
+left out of its own `getPlugins()`, and `restrictTools` from `@dynamicagents/core` narrows a
+plugin to the tools an install names.
 
 ---
 
 ## The plugins
 
-| Subpath                            | What it adds                                                                                                        | Needs                                              |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| [`/arc-agi`](src/arc-agi/)         | Play ARC-AGI-3 games — a delegable subtask type, a catalogue tool, a scorecard ledger                               | `ARC_API_KEY`                                      |
-| [`/browser`](src/browser/)         | Read web pages via Browser Rendering Quick Actions                                                                  | `BROWSER` (paid plan)                              |
-| [`/claude-code`](src/claude-code/) | Delegate a coding task to a Claude Code session in the workspace container                                          | one or more `claude setup-token` credentials       |
-| [`/computer`](src/computer/)       | A Linux container whose filesystem outlives it — shell, package manager, network, and the Durable Object it runs in | `@cloudflare/computer`, `@platformatic/vfs` (paid) |
-| [`/recall`](src/recall/)           | Episodic memory over Vectorize — search history that compaction folded away                                         | `VECTORIZE` (1024-dim/cosine)                      |
-| [`/repo`](src/repo/)               | Clone, commit, push a branch, open a pull request — over any container                                              | `GITHUB_TOKEN`                                     |
-| [`/scratch`](src/scratch/)         | A throwaway git repository with no remote, for work that needs a container but no checkout                          | —                                                  |
-| [`/triage`](src/triage/)           | A pre-turn gate: is this message even for me?                                                                       | —                                                  |
-| [`/workspace`](src/workspace/)     | A durable file store for long subagent runs, plus tools over it                                                     | `@cloudflare/shell`                                |
+| Subpath                            | What it adds                                                                                                     | Needs                                              |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| [`/browser`](src/browser/)         | Read web pages via Browser Rendering Quick Actions                                                               | `BROWSER` (paid plan)                              |
+| [`/claude-code`](src/claude-code/) | Sub-agents whose model is a Claude Code session in the workspace container                                       | one or more `claude setup-token` credentials       |
+| [`/computer`](src/computer/)       | An agent's tools over a workspace — `bash`, `grep`, `edit` — and the workspace Think's file tools use            | a `/workspace` object                              |
+| [`/repo`](src/repo/)               | Clone, commit, push a branch, open a pull request — over any container                                           | `GITHUB_TOKEN`                                     |
+| [`/scratch`](src/scratch/)         | A throwaway git repository with no remote, for work that needs a container but no checkout                       | —                                                  |
+| [`/workspace`](src/workspace/)     | The Durable Object a container workspace lives in — its container, credentialed git, dependency install and sync | `@cloudflare/computer`, `@platformatic/vfs` (paid) |
 
 Each directory has its own README with the config shape and a paste-ready `wrangler.jsonc`
 snippet — a plugin cannot add its own binding, which is why it declares what it needs.
@@ -101,18 +82,21 @@ snippet — a plugin cannot add its own binding, which is why it declares what i
 
 ```ts
 import { definePlugin, type AgentPlugin } from "@dynamicagents/core";
+import { tool } from "ai";
 
-export function scraper(config: { apiKey: string }): AgentPlugin {
+export function scraper(config: { apiKey: () => string }): AgentPlugin {
   return definePlugin({
-    key: "scraper",
-    mainAgentTools: () => ({ fetchPage: /* … */ }),
-    capability: "You can fetch and summarize a page.",
+    name: "scraper",
+    tools: (ctx) => ({ fetch_page: tool({/* … */}) }),
+    context: [
+      { provider: { get: async () => "You can fetch and summarize a page." } }
+    ],
     requires: { secrets: ["SCRAPER_API_KEY"] }
   });
 }
 ```
 
-Three rules the whole design rests on:
+The rules the whole design rests on:
 
 - **Never name a consumer's `Env`.** It is an ambient interface `wrangler types` generates
   into _their_ app. Take bindings and secrets as config, which is also the only thing that
@@ -120,8 +104,17 @@ Three rules the whole design rests on:
 - **`definePlugin` sets `contractVersion`** from the core you compiled against. Never write
   that number as a literal — the point is that it moves, so a version train that leaves one
   repo behind fails at startup with a sentence instead of a structural-type error.
-- **Declare a capability block in exactly one place.** If your plugin has a `subtaskType`, put
-  it there; otherwise on the plugin. Both are rendered, by different call sites.
+- **Give a context block a get-only provider.** A block with no provider is wired as a
+  writable one, which the model can overwrite with `set_context`.
+- **Read `ctx.runtime()` inside `execute`, never while building tools.** It is what a
+  sub-agent's spec prepared for the running dispatch, and it belongs to the turn.
+
+A write that must not happen twice — a comment, a reply — is a Think `action()` in
+`actions(ctx)`, with an idempotency key, so a recovered turn replays it rather than
+repeating it. [`/repo`](src/repo/) has two.
+
+A plugin that owns a domain some work is delegated into exports a `SubAgentSpec` as data,
+and the agent binds it to a `SubAgent` class — see [`/claude-code`](src/claude-code/).
 
 ## Testing
 
@@ -152,18 +145,6 @@ gives it its own copy of every peer. Two copies of `agents` in one bundle breaks
 `Session` types and every `instanceof`, at runtime rather than at the type level.
 Nothing is written to `package.json`, so CI never builds against a local checkout.
 
-`test/arc-agi/recorded.spec.ts` drives the **real** ARC API and replays a committed
-cassette, so it needs no key either. Re-record it against the live API with:
-
-```bash
-npm run test:record   # real ARC_API_KEY in .env.test (see .env.test.example)
-```
-
-The key reaches the live ARC API and nothing else: the recorder excludes the auth header, so
-it never lands in the committed cassette. It reaches the spec only as a Miniflare binding —
-`.env.test` is loaded into **Node's** `process.env`, which a spec running in workerd cannot
-see, so `vitest.config.ts` hands it across explicitly.
-
 ## License
 
-GPL-3.0-only
+Apache-2.0

package/dist/browser/index.d.ts

@@ -1,8 +1,6 @@
 import type { AgentPlugin } from "@dynamicagents/core";
 import type { QuickActionToolName } from "agents/browser/ai";
 import type { QuickActionBinding, QuickActionCommonOptions } from "agents/browser";
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export declare const BROWSER_FAMILY = "browser";
 export interface BrowserConfig {
     /**
      * The `BROWSER` binding. Browser Rendering is a **paid-plan** feature, and

package/dist/browser/index.js

@@ -5,41 +5,35 @@ import { createQuickActionTools } from "agents/browser/ai";
  * Quick Actions.
  *
  * Four tools (`browser_markdown`, `browser_extract`, `browser_links`,
- * `browser_scrape`), offered to the **main agent** and available to a subagent
- * recipe as the `browser` tool family. Both, because both wanted them: a main
- * agent reads a page to answer a question directly, and a delegated research
- * subtask reads a dozen of them. Nothing about the tools differs between the two
- * — only who is holding them.
+ * `browser_scrape`), the same for whichever agent installs the plugin: a parent
+ * reads a page to answer a question directly, and a research sub-agent reads a
+ * dozen of them.
  *
  * The binding is closed over at instantiation, so it is never model input.
  */
 /** How many characters of a page result the model is allowed to see. */
 const DEFAULT_MAX_CHARS = 20_000;
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export const BROWSER_FAMILY = "browser";
+const CONTEXT = [
+    "You can read web pages directly:",
+    "- `browser_markdown` fetches a page and returns it as Markdown. This is the default — use it first.",
+    "- `browser_extract` pulls structured fields out of a page when you know what you are looking for.",
+    "- `browser_links` lists a page's links, for following a trail.",
+    "- `browser_scrape` returns the text of specific CSS selectors.",
+    "Results are truncated to protect your context window, so prefer a specific page over a search-results page, and extract rather than reading in full when you already know the fields you need."
+].join("\n");
 export function browser(config) {
     const { binding, maxChars = DEFAULT_MAX_CHARS, actions, options } = config;
-    // One builder, called per surface rather than once here. The SDK returns a
-    // fresh ToolSet each call and a tool object is not obviously safe to share
-    // across two concurrent executions; building twice costs nothing.
-    const tools = () => createQuickActionTools({
-        browser: binding,
-        maxChars,
-        ...(actions ? { actions } : {}),
-        ...(options ? { options } : {})
-    });
     return definePlugin({
-        key: "browser",
-        mainAgentTools: () => tools(),
-        toolFamilies: { [BROWSER_FAMILY]: () => ({ tools: tools() }) },
-        capability: [
-            "You can read web pages directly:",
-            "- `browser_markdown` fetches a page and returns it as Markdown. This is the default — use it first.",
-            "- `browser_extract` pulls structured fields out of a page when you know what you are looking for.",
-            "- `browser_links` lists a page's links, for following a trail.",
-            "- `browser_scrape` returns the text of specific CSS selectors.",
-            "Results are truncated to protect your context window, so prefer a specific page over a search-results page, and extract rather than reading in full when you already know the fields you need."
-        ].join("\n"),
+        name: "browser",
+        // Built per call: the SDK returns a fresh ToolSet each time, and a tool
+        // object is not obviously safe to share across two concurrent executions.
+        tools: () => createQuickActionTools({
+            browser: binding,
+            maxChars,
+            ...(actions ? { actions } : {}),
+            ...(options ? { options } : {})
+        }),
+        context: [{ provider: { get: async () => CONTEXT } }],
         // A plugin cannot add its own wrangler binding, so declaring it turns a
         // missing one into a startup error naming this plugin, rather than a failed
         // tool call inside a request someone is waiting on.

package/dist/claude-code/cards.d.ts

@@ -0,0 +1,55 @@
+import { type ArtifactEntryDetail } from "@dynamicagents/core/artifacts";
+import type { ClaudeCodeEvent, ClaudeCodeResult } from "./events.js";
+/**
+ * A Claude Code session's stream as cards on its parent's transcript — the
+ * only place in this package that knows what each of the CLI's tools is.
+ *
+ * Modelled on how the CLI shows them itself: a tool and the thing it acted on
+ * on one line, the input and the output folded beneath. A tool's call and its
+ * result are two cards sharing the tool-use id as their `ref`, and the
+ * transcript folds the second into the first — see core's
+ * `ArtifactEntryDetail`. Both are pure functions of one event, because the
+ * drain that calls them is re-entrant (see `./events.ts`): a result is
+ * formatted from its own line, never from the call it answers.
+ *
+ * Every section is clipped here, before the note is persisted anywhere — see
+ * core's `ENTRY_SECTION_MAX_CHARS` for the ceiling that protects.
+ */
+/** A note's text and its card. */
+export interface Card {
+    text: string;
+    detail: ArtifactEntryDetail;
+}
+type ToolResultEvent = Extract<ClaudeCodeEvent, {
+    kind: "toolResult";
+}>;
+type InitEvent = Extract<ClaudeCodeEvent, {
+    kind: "init";
+}>;
+/** A tool call: the card its result will complete. */
+export declare function toolCallCard(id: string, name: string, raw: unknown): Card;
+/**
+ * A tool's result: the half that completes its call's card.
+ *
+ * Read off the tool's own record (`structured`) where it has one, and off the
+ * text the model was given where it does not. The record's shape is what
+ * names the tool — the result line carries only the call's id.
+ */
+export declare function toolResultCard(event: ToolResultEvent): Card;
+/**
+ * A thinking block, as the CLI says it: "Thought for 5s", or "Thought" when it
+ * was not timed. What it thought is never on the card — see the `thinking`
+ * event in `./events.ts`.
+ *
+ * Its message is its `ref`, so a message's blocks are one card: a message
+ * that thinks twice ends on a second block of a few milliseconds, and the CLI
+ * shows the two as one thought.
+ */
+export declare function thinkingCard(durationMs: number | undefined, messageId: string | undefined): Card;
+/** A session starting — every exec, a resume or a follow-up included. */
+export declare function initCard(event: InitEvent): Card;
+/** A session's end, with what its `result` line says about it. */
+export declare function resultCard(result: ClaudeCodeResult): Card;
+/** A session its run gave up on before reading its end, and why. */
+export declare function lostCard(why: string): Card;
+export {};

package/dist/claude-code/cards.js

@@ -0,0 +1,283 @@
+import { clipEntryBody } from "@dynamicagents/core/artifacts";
+/** The most of a summary line a card's head shows. */
+const SUMMARY_MAX_CHARS = 120;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function str(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+/** The first line of `text`, clipped to a card's head. */
+function oneLine(text) {
+    const line = text.trim().split("\n")[0]?.trim() ?? "";
+    return line.length <= SUMMARY_MAX_CHARS
+        ? line
+        : `${line.slice(0, SUMMARY_MAX_CHARS - 1)}…`;
+}
+/** The most of a path's end a card's head keeps. */
+const PATH_SEGMENTS = 3;
+/**
+ * A path as a card's head shows it: its last segments, since the head is one
+ * line and clips at its end — where the file's name is. A checkout's absolute
+ * prefix is the same on every card and tells a reader nothing.
+ */
+function shortPath(path) {
+    if (!path?.startsWith("/"))
+        return path;
+    const parts = path.split("/").filter(Boolean);
+    return parts.length > PATH_SEGMENTS + 1
+        ? `…/${parts.slice(-PATH_SEGMENTS).join("/")}`
+        : path;
+}
+function section(label, body, format) {
+    return { label, body: clipEntryBody(body), ...(format ? { format } : {}) };
+}
+function json(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** The input, minus fields already on the head, or nothing when that is all. */
+function rest(input, shown) {
+    const left = Object.fromEntries(Object.entries(input).filter(([key]) => !shown.includes(key)));
+    return Object.keys(left).length > 0 ? json(left) : "";
+}
+/** `old` replaced by `next`, as the lines a diff section colours. */
+function replacement(old, next) {
+    const minus = old ? old.split("\n").map((line) => `-${line}`) : [];
+    const plus = next ? next.split("\n").map((line) => `+${line}`) : [];
+    return [...minus, ...plus].join("\n");
+}
+const TODO_STATES = {
+    completed: "done",
+    in_progress: "active",
+    pending: "pending"
+};
+/** A `TodoWrite` list as a checklist. The active item reads as its `activeForm`. */
+function todos(input) {
+    const list = Array.isArray(input.todos) ? input.todos : [];
+    const items = [];
+    for (const raw of list) {
+        const todo = record(raw);
+        const state = TODO_STATES[str(todo.status) ?? ""];
+        const text = (state === "active" ? str(todo.activeForm) : undefined) ??
+            str(todo.content);
+        if (state && text)
+            items.push({ text, state });
+    }
+    return items;
+}
+/** A tool call: the card its result will complete. */
+export function toolCallCard(id, name, raw) {
+    const input = record(raw);
+    const open = (title, text, extra = {}) => ({
+        text: oneLine(text ?? "") || title,
+        detail: { ref: id, status: "running", title, ...extra }
+    });
+    const path = shortPath(str(input.file_path) ?? str(input.notebook_path));
+    switch (name) {
+        case "Bash": {
+            const command = str(input.command) ?? "";
+            return open("Bash", str(input.description) ?? command, {
+                sections: [section("Command", command, "code")]
+            });
+        }
+        case "Read": {
+            const offset = typeof input.offset === "number" ? input.offset : 0;
+            const limit = typeof input.limit === "number" ? input.limit : 0;
+            const range = offset || limit
+                ? ` · lines ${offset || 1}–${limit ? (offset || 1) + limit - 1 : "end"}`
+                : "";
+            return open("Read", path && `${path}${range}`);
+        }
+        case "Edit":
+            return open("Update", path, {
+                sections: [
+                    section("Diff", replacement(str(input.old_string) ?? "", str(input.new_string) ?? ""), "diff")
+                ]
+            });
+        case "MultiEdit": {
+            const edits = Array.isArray(input.edits) ? input.edits : [];
+            const diff = edits
+                .map((edit, n) => {
+                const one = record(edit);
+                return `@@ edit ${n + 1} @@\n${replacement(str(one.old_string) ?? "", str(one.new_string) ?? "")}`;
+            })
+                .join("\n");
+            return open("Update", path, {
+                sections: [section("Diff", diff, "diff")]
+            });
+        }
+        case "Write":
+            return open("Write", path, {
+                sections: [section("Content", str(input.content) ?? "", "code")]
+            });
+        case "NotebookEdit":
+            return open("NotebookEdit", path, {
+                sections: [section("Source", str(input.new_source) ?? "", "code")]
+            });
+        case "Grep":
+        case "Glob": {
+            const pattern = str(input.pattern) ?? "";
+            const where = shortPath(str(input.path));
+            const extra = rest(input, ["pattern", "path"]);
+            return open(name === "Grep" ? "Search" : "Glob", `${pattern}${where ? ` in ${where}` : ""}`, extra ? { sections: [section("Options", extra, "code")] } : {});
+        }
+        case "WebFetch":
+            return open("Fetch", str(input.url), {
+                sections: [section("Prompt", str(input.prompt) ?? "", "text")]
+            });
+        case "WebSearch":
+            return open("Web Search", str(input.query));
+        case "Task":
+        case "Agent":
+            return open(str(input.subagent_type) ?? "Task", str(input.description), {
+                sections: [section("Prompt", str(input.prompt) ?? "", "markdown")]
+            });
+        case "TodoWrite": {
+            const items = todos(input);
+            const done = items.filter((item) => item.state === "done").length;
+            const active = items.find((item) => item.state === "active");
+            return open("Todos", `${active ? `${active.text} · ` : ""}${done}/${items.length} done`, { checklist: items });
+        }
+        case "ExitPlanMode":
+            return open("Plan", "the plan, for approval", {
+                sections: [section("Plan", str(input.plan) ?? "", "markdown")]
+            });
+        default: {
+            const first = Object.values(input).find((value) => typeof value === "string");
+            const body = Object.keys(input).length > 0 ? json(input) : "";
+            return open(name, first, {
+                ...(body ? { sections: [section("Input", body, "code")] } : {})
+            });
+        }
+    }
+}
+/**
+ * A tool's result: the half that completes its call's card.
+ *
+ * Read off the tool's own record (`structured`) where it has one, and off the
+ * text the model was given where it does not. The record's shape is what
+ * names the tool — the result line carries only the call's id.
+ */
+export function toolResultCard(event) {
+    const done = (sections) => ({
+        text: oneLine(event.content) || "result",
+        detail: {
+            ref: event.id,
+            status: event.isError ? "error" : "ok",
+            ...(sections.length > 0 ? { sections } : {})
+        }
+    });
+    if (event.isError)
+        return done([section("Error", event.content, "text")]);
+    const result = record(event.structured);
+    // Bash.
+    if ("stdout" in result || "stderr" in result) {
+        const stdout = str(result.stdout) ?? "";
+        const stderr = str(result.stderr) ?? "";
+        const sections = [];
+        if (stdout)
+            sections.push(section("Output", stdout, "code"));
+        if (stderr)
+            sections.push(section("Stderr", stderr, "code"));
+        if (result.interrupted === true)
+            sections.push(section("Note", "interrupted", "text"));
+        return done(sections.length > 0
+            ? sections
+            : [section("Output", "(no output)", "text")]);
+    }
+    // Read.
+    const file = record(result.file);
+    if (typeof file.content === "string") {
+        const lines = typeof file.numLines === "number"
+            ? `${file.numLines} line${file.numLines === 1 ? "" : "s"}`
+            : "Output";
+        return done([section(lines, file.content, "code")]);
+    }
+    // Edit, MultiEdit, Write and TodoWrite: the call's card already shows what
+    // changed, and the result only says that it did.
+    if ("structuredPatch" in result || "newTodos" in result)
+        return done([]);
+    // Task: the subagent's answer.
+    if (Array.isArray(result.content)) {
+        const text = result.content
+            .map((block) => str(record(block).text) ?? "")
+            .filter(Boolean)
+            .join("\n\n");
+        if (text)
+            return done([section("Result", text, "markdown")]);
+    }
+    return done(event.content ? [section("Output", event.content, "text")] : []);
+}
+/**
+ * A thinking block, as the CLI says it: "Thought for 5s", or "Thought" when it
+ * was not timed. What it thought is never on the card — see the `thinking`
+ * event in `./events.ts`.
+ *
+ * Its message is its `ref`, so a message's blocks are one card: a message
+ * that thinks twice ends on a second block of a few milliseconds, and the CLI
+ * shows the two as one thought.
+ */
+export function thinkingCard(durationMs, messageId) {
+    return {
+        text: durationMs === undefined
+            ? "Thought"
+            : `Thought for ${duration(Math.max(durationMs, 1000))}`,
+        detail: { title: "Thinking", ...(messageId ? { ref: messageId } : {}) }
+    };
+}
+/** A session starting — every exec, a resume or a follow-up included. */
+export function initCard(event) {
+    const parts = [
+        "Session started",
+        event.model,
+        event.permissionMode && `${event.permissionMode} mode`
+    ].filter(Boolean);
+    return { text: parts.join(" · "), detail: { title: "Session" } };
+}
+/** A session's end, with what its `result` line says about it. */
+export function resultCard(result) {
+    const failed = result.isError || result.subtype !== "success";
+    const parts = [
+        failed ? `Session failed (${result.subtype})` : "Session finished",
+        result.numTurns
+            ? `${result.numTurns} turn${result.numTurns === 1 ? "" : "s"}`
+            : undefined,
+        result.durationMs ? duration(result.durationMs) : undefined
+    ].filter(Boolean);
+    const errors = result.errors?.join("\n");
+    return {
+        text: parts.join(" · "),
+        detail: {
+            title: "Session",
+            status: failed ? "error" : "ok",
+            ...(errors ? { sections: [section("Errors", errors, "text")] } : {})
+        }
+    };
+}
+/** A session its run gave up on before reading its end, and why. */
+export function lostCard(why) {
+    return {
+        text: "Session ended before its run read it to the end",
+        detail: {
+            title: "Session",
+            status: "error",
+            sections: [section("Why", why, "text")]
+        }
+    };
+}
+function duration(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    return `${Math.floor(m / 60)}h ${m % 60}m`;
+}