@getorrery/protocol 0.0.0-stage → 0.2.1

package/protocol.d.ts

@@ -0,0 +1,3751 @@
+/* eslint-disable */
+/**
+ * Generated by `cargo xtask typegen` from harness/core/crates/orrery-proto.
+ * Do not edit by hand: CI regenerates this file and fails on a diff.
+ */
+
+export type CatalogNode = {
+  /**
+   * A stable handle for client-local state (the selected tab, open, scroll) and for `ui.intent.node`.
+   */
+  key?: string | null;
+  /**
+   * Inside a `row` or a `column`: this node's share of the space.
+   */
+  weight?: number | null;
+  [k: string]: unknown;
+} & CatalogNode1;
+export type CatalogNode1 =
+  | {
+      /**
+       * The contents.
+       */
+      children?: CatalogNode[];
+      /**
+       * Cells between children.
+       */
+      gap?: number | null;
+      /**
+       * The most lines a wrapped row takes.
+       */
+      maxRows?: number | null;
+      type: "row";
+      /**
+       * Wrap onto the next line when narrow.
+       */
+      wrap?: boolean;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The contents.
+       */
+      children?: CatalogNode[];
+      /**
+       * Cells between children.
+       */
+      gap?: number | null;
+      /**
+       * The most rows it takes.
+       */
+      maxRows?: number | null;
+      type: "column";
+      /**
+       * Wrap when narrow.
+       */
+      wrap?: boolean;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The contents.
+       */
+      children?: CatalogNode[];
+      /**
+       * Its title.
+       */
+      title?: string | null;
+      type: "box";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The tab shown first, by key.
+       */
+      selected?: string | null;
+      /**
+       * The tabs.
+       */
+      tabs: Tab[];
+      type: "tabs";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The contents.
+       */
+      children?: CatalogNode[];
+      /**
+       * Whether it starts open.
+       */
+      open?: boolean;
+      /**
+       * Its title.
+       */
+      title: string;
+      type: "collapsible";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Its label.
+       */
+      label?: string | null;
+      type: "divider";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The contents.
+       */
+      children?: CatalogNode[];
+      /**
+       * Whether it starts folded.
+       */
+      collapsed?: boolean;
+      /**
+       * Which way.
+       */
+      dir: StackDir;
+      /**
+       * A heading.
+       */
+      title?: string | null;
+      type: "stack";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Inline runs.
+       */
+      spans?: Span[];
+      /**
+       * How it is meant.
+       */
+      style?: TextStyle | null;
+      type: "text";
+      /**
+       * The text; `spans` replace it when present.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * 1, 2 or 3.
+       */
+      level?: number | null;
+      /**
+       * Its text.
+       */
+      text: string;
+      type: "heading";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Where it goes.
+       */
+      href: string;
+      /**
+       * What it says.
+       */
+      label: string;
+      type: "link";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The word.
+       */
+      text: string;
+      /**
+       * How it is meant.
+       */
+      tone?: Tone | null;
+      type: "badge";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it says.
+       */
+      text: string;
+      /**
+       * Its title.
+       */
+      title?: string | null;
+      /**
+       * Info, warning, error or success; never neutral.
+       */
+      tone: Tone;
+      type: "callout";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * The pairs.
+       */
+      items: KvItem[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      type: "kv";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The source.
+       */
+      code: string;
+      /**
+       * Lines to highlight, by number.
+       */
+      highlight?: number[];
+      /**
+       * Its language, for highlighting.
+       */
+      language?: string | null;
+      /**
+       * Show line numbers.
+       */
+      lineNumbers?: boolean;
+      /**
+       * The first line's number.
+       */
+      start?: number | null;
+      type: "code";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * False while it still streams. Absent reads as complete.
+       */
+      complete?: boolean;
+      type: "markdown";
+      /**
+       * The source.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The header row.
+       */
+      columns: Column[];
+      /**
+       * Shown when there are no rows.
+       */
+      empty?: string | null;
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * What choosing a row sends; the value is its `key`, else its index.
+       */
+      rowAction?: string | null;
+      /**
+       * The body.
+       */
+      rows?: TableRow[];
+      type: "table";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What choosing sends; the value is the item's.
+       */
+      action?: string | null;
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * The entries.
+       */
+      items: ListItem[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * The value the cursor starts on.
+       */
+      selected?: string | null;
+      /**
+       * How it is drawn.
+       */
+      style?: ListStyle | null;
+      type: "list";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What choosing a node sends; the value is its `id`.
+       */
+      action?: string | null;
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * The roots.
+       */
+      nodes: TreeNode[];
+      type: "tree";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * Which channel.
+       */
+      id: string;
+      /**
+       * The lines so far.
+       */
+      lines?: StreamLine[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      type: "stream";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Shown when there are no values.
+       */
+      empty?: string | null;
+      /**
+       * Which chart.
+       */
+      kind: ChartKind;
+      /**
+       * What each value is.
+       */
+      labels?: string[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * The series.
+       */
+      series: Series[];
+      /**
+       * A heading.
+       */
+      title?: string | null;
+      type: "chart";
+      /**
+       * The values' unit.
+       */
+      unit?: string | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How it moved: `+12%`.
+       */
+      change?: string | null;
+      /**
+       * Shown when `value` is empty.
+       */
+      empty?: string | null;
+      /**
+       * What it is.
+       */
+      label: string;
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * How it is meant.
+       */
+      tone?: Tone | null;
+      type: "stat";
+      /**
+       * The value, already formatted.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * The entries.
+       */
+      items: TaskItem[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      /**
+       * How it is drawn.
+       */
+      style?: TaskStyle | null;
+      type: "task";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What pressing it sends.
+       */
+      action: string;
+      /**
+       * Shown, but cannot be pressed.
+       */
+      disabled?: boolean;
+      /**
+       * What it says.
+       */
+      label: string;
+      /**
+       * How it is meant.
+       */
+      tone?: ButtonTone | null;
+      type: "button";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What submitting sends.
+       */
+      action?: string | null;
+      /**
+       * The inputs.
+       */
+      fields: FormField[];
+      /**
+       * The submit button's label.
+       */
+      submit: string;
+      type: "form";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What submitting sends.
+       */
+      action: string;
+      /**
+       * What is shown next to it.
+       */
+      label?: string | null;
+      /**
+       * The key its value is sent under.
+       */
+      name: string;
+      /**
+       * What the empty box says.
+       */
+      placeholder?: string | null;
+      /**
+       * How many lines tall.
+       */
+      rows?: number | null;
+      type: "textarea";
+      /**
+       * What it starts as.
+       */
+      value?: string | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The offered answers.
+       */
+      choices?: Choice[];
+      /**
+       * How long there is to answer.
+       */
+      deadline_ms?: number | null;
+      /**
+       * Used if the deadline passes.
+       */
+      default?: string | null;
+      /**
+       * An answer outside `choices` is accepted.
+       */
+      free?: boolean;
+      /**
+       * More than one may be picked.
+       */
+      multi?: boolean;
+      /**
+       * What is asked.
+       */
+      prompt: string;
+      type: "question";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How much is done.
+       */
+      done?: number | null;
+      /**
+       * What is happening.
+       */
+      label: string;
+      /**
+       * How much there is.
+       */
+      total?: number | null;
+      type: "progress";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it shows, in words.
+       */
+      alt: string;
+      /**
+       * The bytes, base64.
+       */
+      data: string;
+      /**
+       * Height in pixels.
+       */
+      h?: number | null;
+      /**
+       * `image/png`, …
+       */
+      mime: string;
+      /**
+       * A caption.
+       */
+      title?: string | null;
+      type: "image";
+      /**
+       * Width in pixels.
+       */
+      w?: number | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it shows, in words.
+       */
+      alt: string;
+      /**
+       * `w * h` colours, row by row, `0xRRGGBB`.
+       */
+      cells: number[];
+      /**
+       * Height, in cells.
+       */
+      h: number;
+      /**
+       * Row and column names.
+       */
+      labels?: RasterLabels | null;
+      /**
+       * What the colours mean.
+       */
+      legend?: LegendItem[] | null;
+      type: "raster";
+      /**
+       * Width, in cells.
+       */
+      w: number;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What choosing sends.
+       */
+      action?: string | null;
+      /**
+       * Shown when there are none.
+       */
+      empty?: string | null;
+      /**
+       * The files.
+       */
+      files: FileEntry[];
+      /**
+       * Still arriving.
+       */
+      loading?: boolean;
+      type: "files";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The changed regions.
+       */
+      hunks?: Hunk[];
+      /**
+       * The file.
+       */
+      path: string;
+      type: "diff";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Its exit code.
+       */
+      exit?: number | null;
+      /**
+       * What was run.
+       */
+      line: string;
+      /**
+       * What it printed.
+       */
+      output?: string;
+      /**
+       * How far along.
+       */
+      status?: Status | null;
+      type: "command";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What to show instead: a catalog node.
+       */
+      fallback?: CatalogNode | null;
+      /**
+       * `<ext>.<name>`.
+       */
+      kind: string;
+      /**
+       * Whatever that renderer needs.
+       */
+      props?: {
+        [k: string]: unknown;
+      };
+      type: "custom";
+      [k: string]: unknown;
+    };
+/**
+ * Which way a [`SurfaceKind::Stack`] lays its children out.
+ */
+export type StackDir = "row" | "column";
+/**
+ * How a run inside a `text`'s `spans` is meant.
+ */
+export type SpanStyle = "bold" | "dim" | "code" | "kbd" | "file" | "elapsed";
+/**
+ * A hint about how a run of text is meant, never a colour.
+ */
+export type TextStyle = "plain" | "muted" | "emphasis" | "code" | "error" | "success" | "warning";
+/**
+ * A tone: how a badge, a stat or a callout is meant, never a colour.
+ */
+export type Tone = "neutral" | "info" | "success" | "warning" | "error";
+/**
+ * A `table` column: a title, or a title with its alignment and priority.
+ */
+export type Column =
+  | string
+  | {
+      /**
+       * How its cells align.
+       */
+      align?: Align | null;
+      /**
+       * Lower priority is dropped first when narrow.
+       */
+      priority?: number | null;
+      /**
+       * Its title.
+       */
+      title: string;
+      [k: string]: unknown;
+    };
+/**
+ * A column's alignment.
+ */
+export type Align = "left" | "right" | "center";
+/**
+ * A `table` row: its cells, or its cells with a key that names it.
+ */
+export type TableRow =
+  | TableCell[]
+  | {
+      /**
+       * Its cells.
+       */
+      cells: TableCell[];
+      /**
+       * What names the row: sent as `value` when it is chosen.
+       */
+      key: string;
+      [k: string]: unknown;
+    };
+/**
+ * A `table` cell: a string, or a [`Cell`] with its style.
+ */
+export type TableCell = string | Cell;
+/**
+ * How a `list` draws its items.
+ */
+export type ListStyle = "bullet" | "number" | "select";
+/**
+ * A log line's level.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Which chart a [`SurfaceKind::Chart`] is (decision 0090).
+ */
+export type ChartKind = "bars" | "columns" | "stacked" | "line" | "area" | "scatter" | "sparkline" | "donut" | "gauge";
+/**
+ * How far along whatever produced this surface is.
+ */
+export type Status = "pending" | "running" | "done" | "failed" | "cancelled";
+/**
+ * How a `task` is drawn.
+ */
+export type TaskStyle = "list" | "pipeline";
+/**
+ * A button's tone.
+ */
+export type ButtonTone = "default" | "primary" | "danger";
+/**
+ * What a [`Field`] collects.
+ */
+export type FieldKind =
+  | {
+      t: "text";
+      [k: string]: unknown;
+    }
+  | {
+      t: "secret";
+      [k: string]: unknown;
+    }
+  | {
+      t: "number";
+      [k: string]: unknown;
+    }
+  | {
+      t: "bool";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The options.
+       */
+      choices: Choice[];
+      t: "choice";
+      [k: string]: unknown;
+    };
+/**
+ * How a form field is drawn: `select`/`radio` for a choice, `check`/`toggle` for a bool.
+ */
+export type FieldStyle = "select" | "radio" | "check" | "toggle";
+/**
+ * A changed file's status in a `files`.
+ */
+export type FileStatus = "added" | "modified" | "deleted" | "renamed";
+/**
+ * What a line of a diff is.
+ */
+export type DiffLineKind = "context" | "add" | "remove";
+/**
+ * Kernel to client.
+ *
+ * Every variant carries a `seq`: a client detects a gap by arithmetic and re-attaches with `since`, which is only possible if the ordering is on the frame rather than implied by the transport.
+ */
+export type Event =
+  | {
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "turn.started";
+      /**
+       * Which turn.
+       */
+      turn: TurnId;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How it changed.
+       */
+      patch: SurfacePatch;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      /**
+       * Which surface.
+       */
+      surface: SurfaceId;
+      t: "delta";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which call.
+       */
+      call: CallId;
+      /**
+       * Which tool.
+       */
+      ref: ToolRef;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "tool.started";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which call.
+       */
+      call: CallId;
+      /**
+       * How it went.
+       */
+      outcome: Outcome;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "tool.settled";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How long there is to answer before the default applies.
+       */
+      deadline_ms: number;
+      /**
+       * The question.
+       */
+      prompt: ConsentPrompt;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "consent.request";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "turn.settled";
+      /**
+       * Which turn.
+       */
+      turn: TurnId;
+      /**
+       * What it cost.
+       */
+      usage: Usage;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What went wrong.
+       */
+      detail: ErrorDetail;
+      /**
+       * How far it reaches.
+       */
+      scope: ErrorScope;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "error";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * When it was produced, on the host's clock.
+       */
+      at_ms: number;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "reasoning";
+      /**
+       * The text.
+       */
+      text: string;
+      /**
+       * Which turn is thinking.
+       */
+      turn: TurnId;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * When it ended, on the host's clock.
+       */
+      at_ms: number;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "reasoning.end";
+      /**
+       * Which turn.
+       */
+      turn: TurnId;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Why.
+       */
+      reason: CancelReason;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "turn.cancelled";
+      /**
+       * Which turn.
+       */
+      turn: TurnId;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Each component instance's data (decision 0092 §4), by owner then id: AG-UI's `/data`, a sibling of `/ui`. Absent when empty, so a stream from before components parses.
+       */
+      data?: {
+        [k: string]: unknown;
+      };
+      /**
+       * The document.
+       */
+      doc: UiDoc;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "ui.snapshot";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The ops.
+       */
+      ops: UiOp[];
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "ui";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The ops.
+       */
+      ops: UiOp[];
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "data";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The extension.
+       */
+      ext: string;
+      /**
+       * The key.
+       */
+      key: string;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "state.changed";
+      /**
+       * Its new value.
+       */
+      value: {
+        [k: string]: unknown;
+      };
+      /**
+       * The watch, as `state.watch` answered.
+       */
+      watch: number;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Who asked: the extension's id (`[extension] id` in its `orrery.toml`).
+       */
+      ext: string;
+      /**
+       * How loud.
+       */
+      level: NoticeLevel;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "notice";
+      /**
+       * What it says.
+       */
+      text: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Where it is, who placed it, its fallback.
+       */
+      placed: Placed;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      /**
+       * What it shows.
+       */
+      surface: Surface;
+      t: "ui.placed";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The id its owner gave it.
+       */
+      id: string;
+      /**
+       * Who placed it: `ext:<id>`, `agent` or `config`.
+       */
+      owner: string;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "ui.unplaced";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "task.changed";
+      /**
+       * The task, now.
+       */
+      task: TaskInfo;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which extension (`[extension] id` in its `orrery.toml`).
+       */
+      ext: ExtId;
+      /**
+       * The segment's handle: AG-UI's `subagentRunId`.
+       */
+      id: string;
+      /**
+       * The tool call that caused it, when one did.
+       */
+      parent_call?: CallId | null;
+      /**
+       * The turn that caused it, when no call did.
+       */
+      parent_turn?: TurnId | null;
+      /**
+       * What it was asked, shortened for display.
+       */
+      prompt?: string;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "ext.segment.started";
+      /**
+       * A model it called or an agent it ran.
+       */
+      via: Via;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which segment.
+       */
+      id: string;
+      /**
+       * How it went.
+       */
+      outcome: Outcome;
+      /**
+       * Where this sits in the session's order.
+       */
+      seq: Seq;
+      t: "ext.segment.settled";
+      /**
+       * What it cost.
+       */
+      usage?: Usage;
+      [k: string]: unknown;
+    };
+export type Seq = number;
+export type TurnId = string;
+/**
+ * A change to a surface already on screen.
+ *
+ * The whole point of the surface protocol: a streaming tool sends one [`SurfacePatch::Append`] per chunk rather than a whole new surface, so the hot path is a string and not a tree.
+ */
+export type SurfacePatch =
+  | {
+      /**
+       * Which surface.
+       */
+      id: SurfaceId;
+      op: "replace";
+      /**
+       * What it becomes.
+       */
+      value: Surface;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which surface.
+       */
+      id: SurfaceId;
+      op: "append";
+      /**
+       * What to add.
+       */
+      text: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which surface.
+       */
+      id: SurfaceId;
+      op: "set";
+      /**
+       * The path from the surface's root to the field.
+       */
+      path: string[];
+      /**
+       * The new value.
+       */
+      value: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which surface.
+       */
+      id: SurfaceId;
+      op: "remove";
+      [k: string]: unknown;
+    };
+export type SurfaceId = string;
+/**
+ * What a surface *is*.
+ */
+export type SurfaceKind =
+  | {
+      /**
+       * How it is meant.
+       */
+      style?: TextStyle | null;
+      t: "text";
+      /**
+       * The text.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The header row.
+       */
+      columns: string[];
+      /**
+       * The body. Every row is expected to be `columns.len()` long.
+       */
+      rows?: Cell[][];
+      t: "table";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The roots.
+       */
+      nodes?: TreeNode[];
+      t: "tree";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The changed regions.
+       */
+      hunks?: Hunk[];
+      /**
+       * The file.
+       */
+      path: string;
+      t: "diff";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How much is done.
+       */
+      done?: number | null;
+      /**
+       * What is happening.
+       */
+      label: string;
+      t: "progress";
+      /**
+       * How much there is.
+       */
+      total?: number | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which channel: `stdout`, `stderr`, a log name.
+       */
+      id: string;
+      t: "stream";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The entries.
+       */
+      items?: TaskItem[];
+      t: "task";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The offered answers.
+       */
+      choices?: Choice[];
+      /**
+       * How long there is to answer.
+       */
+      deadline_ms?: number | null;
+      /**
+       * What is used if the deadline passes.
+       */
+      default?: string | null;
+      /**
+       * Whether an answer outside `choices` is accepted.
+       */
+      free: boolean;
+      /**
+       * Whether more than one may be picked.
+       */
+      multi: boolean;
+      /**
+       * What is being asked.
+       */
+      prompt: string;
+      t: "question";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The inputs.
+       */
+      fields?: Field[];
+      /**
+       * The submit button's label.
+       */
+      submit: string;
+      t: "form";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The contents.
+       */
+      children?: Surface[];
+      /**
+       * Whether it starts folded.
+       */
+      collapsed: boolean;
+      /**
+       * Which way.
+       */
+      dir: StackDir;
+      t: "stack";
+      /**
+       * An optional heading.
+       */
+      title?: string | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Whether the last patch has arrived.
+       */
+      complete: boolean;
+      t: "markdown";
+      /**
+       * The source.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What to show instead, for a client that has no such renderer: core kinds only. Without one, a client draws the payload as text, one `key value` line each (decision 0086).
+       */
+      fallback?: Surface | null;
+      /**
+       * `<ext>.<name>`, so two extensions cannot claim one renderer.
+       */
+      kind: string;
+      /**
+       * Whatever that renderer needs.
+       */
+      payload: {
+        [k: string]: unknown;
+      };
+      t: "custom";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which chart.
+       */
+      kind: ChartKind;
+      /**
+       * What each value is, in order.
+       */
+      labels?: string[];
+      /**
+       * The series.
+       */
+      series: Series[];
+      t: "chart";
+      /**
+       * A heading.
+       */
+      title?: string | null;
+      /**
+       * The values' unit: `ms`, `%`.
+       */
+      unit?: string | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it shows, in words: drawn where it cannot be.
+       */
+      alt: string;
+      /**
+       * `w * h` colours, row by row, each packed `0xRRGGBB`.
+       */
+      cells: number[];
+      /**
+       * Its height, in cells.
+       */
+      h: number;
+      /**
+       * The names of its rows and columns.
+       */
+      labels?: RasterLabels | null;
+      /**
+       * What its colours mean, in order.
+       */
+      legend?: LegendItem[] | null;
+      t: "raster";
+      /**
+       * Its width, in cells.
+       */
+      w: number;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it shows, in words: drawn where it cannot be.
+       */
+      alt: string;
+      /**
+       * The file's bytes, base64.
+       */
+      data: string;
+      /**
+       * Its height in pixels, when known.
+       */
+      h?: number | null;
+      /**
+       * `image/png`, `image/jpeg`, …
+       */
+      mime: string;
+      t: "image";
+      /**
+       * A caption.
+       */
+      title?: string | null;
+      /**
+       * Its width in pixels, when known.
+       */
+      w?: number | null;
+      [k: string]: unknown;
+    };
+export type CallId = string;
+export type ToolRef = string;
+/**
+ * How something turned out.
+ *
+ * The type that makes "a denial is a value" real at every layer: the tool registry returns it, the transcript stores it, the wire carries it, the renderer draws it. Nothing anywhere raises a denial as an error, because an error would have to be rendered by whoever caught it, and then two layers would be describing the same refusal in two different ways.
+ */
+export type Outcome =
+  | {
+      /**
+       * What to show, when there is something to show.
+       */
+      surface?: Surface | null;
+      t: "ok";
+      /**
+       * What to feed back to the model, when that differs from what is shown.
+       */
+      value?: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Why, in words a person can act on.
+       */
+      reason: string;
+      /**
+       * Which rule.
+       */
+      rule: RuleId;
+      t: "denied";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * How much was produced.
+       */
+      bytes_emitted: number;
+      /**
+       * How much was allowed.
+       */
+      limit: number;
+      /**
+       * What there is of it.
+       */
+      surface?: Surface | null;
+      t: "truncated";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Why.
+       */
+      reason: CancelReason;
+      t: "cancelled";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which extension.
+       */
+      ext: ExtId;
+      t: "unloaded";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * A stable, machine-readable code.
+       */
+      code: string;
+      /**
+       * What went wrong, in words.
+       */
+      message: string;
+      t: "failed";
+      [k: string]: unknown;
+    };
+export type RuleId = string;
+/**
+ * Why something stopped early.
+ */
+export type CancelReason = "user" | "budget" | "timeout" | "shutdown" | "parent";
+export type ExtId = string;
+/**
+ * What a capability is *about*.
+ *
+ * The wire names are pinned per variant rather than derived where they are dotted (`mem.read`, `run.send`, `session.read`, ...), because no `rename_all` rule produces a dot.
+ */
+export type Aspect =
+  | "tool"
+  | "mcp"
+  | "skill"
+  | "ext"
+  | "mode"
+  | "read"
+  | "write"
+  | "spawn"
+  | "net"
+  | "creds"
+  | "ui"
+  | "render"
+  | "mem.read"
+  | "mem.write"
+  | "model"
+  | "run.send"
+  | "session.read"
+  | "session.write"
+  | "intercept";
+export type PromptId = string;
+export type Subject = string;
+/**
+ * How far an error reaches.
+ */
+export type ErrorScope = "transport" | "session" | "turn" | "tool" | "ext";
+/**
+ * A node: what it is, and its children by id.
+ */
+export type Node = {
+  /**
+   * Its children, in order.
+   */
+  children?: string[];
+  [k: string]: unknown;
+} & Node1;
+export type Node1 =
+  | {
+      /**
+       * The left pane's placed surfaces, stacked in arrival order: a full-height column beside the thread (decision 0087).
+       */
+      left?: string[];
+      /**
+       * Which arrangement.
+       */
+      mode: LayoutMode;
+      /**
+       * The right pane's, likewise.
+       */
+      right?: string[];
+      type: "layout";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The workspace's git branch.
+       */
+      branch?: string | null;
+      /**
+       * What failed, ending with what fixes it.
+       */
+      error?: string | null;
+      /**
+       * The harness running, by name (decision 0007).
+       */
+      harness?: string | null;
+      /**
+       * A logo, by URL or a client-known name (`orrery`).
+       */
+      logo?: string | null;
+      /**
+       * The model in use, when there is one.
+       */
+      model?: string | null;
+      /**
+       * The product's name.
+       */
+      name: string;
+      /**
+       * The model's provider.
+       */
+      provider?: string | null;
+      /**
+       * The session's id: what `orrery --resume <id>` takes, which the exit summary prints (decision 0019).
+       */
+      session?: string | null;
+      /**
+       * `loading` while the model resolves, `error` when the harness failed to load; idle otherwise.
+       */
+      state?: AgentState | null;
+      /**
+       * Whether that workspace's own configuration is in force.
+       */
+      trusted: boolean;
+      type: "banner";
+      /**
+       * Its version.
+       */
+      version: string;
+      /**
+       * The workspace the session runs in.
+       */
+      workspace: string;
+      [k: string]: unknown;
+    }
+  | {
+      type: "thread";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The band: placed surfaces drawn as rows above the input, in arrival order (decision 0087).
+       */
+      band?: string[];
+      type: "dock";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What `/` completes.
+       */
+      commands?: CommandSpec[];
+      /**
+       * A line under the box: what to type or paste, and what the keys do.
+       */
+      hint?: string | null;
+      /**
+       * Keys bound to commands (decision 0083 §4): a client sends the `command` when the key is pressed at the prompt. Never one of [`RESERVED_KEYS`].
+       */
+      keys?: KeyBinding[];
+      /**
+       * What is being typed, drawn in the box before the value: `API key ›` (decision 0004). `None` is a plain prompt.
+       */
+      label?: string | null;
+      /**
+       * What it is for.
+       */
+      mode: InputMode;
+      /**
+       * The answer may span lines (an extension's `text` ask with `multiline`, decision 0083): Enter adds a line, and the client's own submit chord sends it.
+       */
+      multiline?: boolean;
+      /**
+       * What the empty box says: what the keys do right now.
+       */
+      placeholder: string;
+      type: "input";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Agents running, attached ones included (decision 0031): the indicator's `2 agents`. Absent at none.
+       */
+      agents?: number | null;
+      /**
+       * How full the context window is, when the limit is known.
+       */
+      context?: ContextUse | null;
+      /**
+       * Segments extensions set on the status line (`ui.status`, decision 0083 §3), in the order they were first set: latest text only, one per `(ext, key)`, gone once cleared.
+       */
+      ext_status?: ExtStatus[];
+      /**
+       * What this session cost, in micro-USD, when the provider says.
+       */
+      micro_usd?: number | null;
+      /**
+       * The permission mode: `default`, `accept`, `plan`, `bypass`.
+       */
+      mode?: string | null;
+      /**
+       * The model.
+       */
+      model?: string | null;
+      /**
+       * The model cannot be reached.
+       */
+      model_error?: boolean;
+      /**
+       * The status line the user declared (`ui.statusline`), in order.
+       */
+      slots?: string[];
+      /**
+       * Background tasks running (decision 0027): processes, by kind since decision 0031. Absent at none, so the count is hidden.
+       */
+      tasks?: number | null;
+      /**
+       * Tokens used this session.
+       */
+      tokens?: number | null;
+      type: "footer";
+      /**
+       * The view on screen, one of `views`; absent on main's.
+       */
+      view?: string | null;
+      /**
+       * How each view but main's is doing (decision 0033 §2), by name: the switcher draws `running` plain, `done` green, `failed` red, `stopped` dim. A view missing here is running.
+       */
+      view_states?: {
+        [k: string]: ViewState;
+      };
+      /**
+       * The views a person can switch between (decisions 0031 §4, 0033 §1): `main`, then each agent that runs, and the view on screen — a finished agent, a process's log — while it is open. Absent while there is only main's, so the switcher is hidden.
+       */
+      views?: string[];
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * A dimmer line under it.
+       */
+      detail?: string | null;
+      /**
+       * When the state began, in milliseconds on the host's session clock, so a client can count the seconds without a patch per second.
+       */
+      since_ms?: number;
+      /**
+       * Which state.
+       */
+      state: AgentState;
+      /**
+       * What it is doing: `thinking · 3s` is drawn from this and `since_ms`.
+       */
+      title: string;
+      /**
+       * Tokens sent so far in this turn.
+       */
+      tokens_in?: number | null;
+      /**
+       * Tokens received so far in this turn.
+       */
+      tokens_out?: number | null;
+      type: "status";
+      [k: string]: unknown;
+    }
+  | {
+      type: "overlay";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The surface.
+       */
+      surface: Surface;
+      type: "surface";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What choosing sends. `None` is a list to read, not to choose from.
+       */
+      action?: string | null;
+      /**
+       * The entries.
+       */
+      items: ListItem[];
+      /**
+       * The value the cursor starts on.
+       */
+      selected?: string | null;
+      type: "list";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What pressing it sends.
+       */
+      action: string;
+      /**
+       * What it says.
+       */
+      label: string;
+      type: "button";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Its exit code, once it has one.
+       */
+      exit?: number | null;
+      /**
+       * What was run.
+       */
+      line: string;
+      /**
+       * What it printed so far.
+       */
+      output?: string;
+      /**
+       * How far along it is.
+       */
+      status: Status;
+      type: "command";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Whether its children are shown.
+       */
+      open: boolean;
+      /**
+       * Its title.
+       */
+      title: string;
+      type: "collapsible";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The element's id.
+       */
+      el: string;
+      /**
+       * Its view model.
+       */
+      props?: {
+        [k: string]: unknown;
+      };
+      type: "element";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The structure's name: `<ext>.<name>`, or `<owner>#<id>` for one shown inline. A key of [`UiDoc::components`].
+       */
+      component: string;
+      /**
+       * A JSON Pointer from the AG-UI state root to the instance's data: `/data/<owner>/<id>` (under [`DATA_ROOT`]).
+       */
+      data: string;
+      type: "component";
+      [k: string]: unknown;
+    };
+/**
+ * How the screen is laid out. Declared by the host; every client implements every mode.
+ */
+export type LayoutMode = "fullscreen";
+/**
+ * What the agent is doing, as the design's states name it.
+ */
+export type AgentState = "idle" | "loading" | "thinking" | "executing" | "waiting" | "done" | "error";
+/**
+ * What the input box is for right now.
+ */
+export type InputMode = "prompt" | "secret" | "answer" | "disabled";
+/**
+ * How a view in the footer's switcher is doing (decision 0033 §2): running is drawn plain, done green (`name ✓`), failed red (`name ✗`), stopped dim (`name ■`).
+ */
+export type ViewState = "running" | "done" | "failed" | "stopped";
+/**
+ * Where a surface goes.
+ */
+export type Placement = "inline" | "footer" | "band" | "pane.left" | "pane.right" | "hidden";
+/**
+ * How a placed surface is doing.
+ */
+export type PlacedState = "live" | "loading" | "stopped";
+/**
+ * One change to the UI document: RFC 6902, with paths relative to `/ui`.
+ *
+ * `/nodes/<id>` adds, swaps or removes a node; `/nodes/<id>/<field>` changes one prop; `/nodes/<id>/children` swaps the child list, and `/nodes/<id>/children/-` appends one child.
+ */
+export type UiOp =
+  | {
+      op: "add";
+      /**
+       * A JSON Pointer, relative to `/ui`.
+       */
+      path: string;
+      /**
+       * What to add.
+       */
+      value: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      op: "replace";
+      /**
+       * A JSON Pointer, relative to `/ui`.
+       */
+      path: string;
+      /**
+       * What it becomes.
+       */
+      value: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      op: "remove";
+      /**
+       * A JSON Pointer, relative to `/ui`.
+       */
+      path: string;
+      [k: string]: unknown;
+    };
+/**
+ * How loud a notice is.
+ */
+export type NoticeLevel = "info" | "warn" | "error";
+/**
+ * What a task is.
+ */
+export type TaskKind = "agent" | "process";
+/**
+ * Where a task stands.
+ */
+export type TaskState = "running" | "done" | "stopped" | "killed" | "failed" | "exited" | "lost";
+/**
+ * How an extension produced a message (decision 0076).
+ */
+export type Via = "input" | "model" | "agent";
+/**
+ * How often the user has to be asked.
+ *
+ * Ordered `Never < Once < Always`, and narrowing takes the minimum: a child that asks every time cannot be promoted to a child that never asks.
+ */
+export type Consent = "always" | "once" | "never";
+/**
+ * The result of trying to load one extension.
+ */
+export type LoadOutcome =
+  | {
+      /**
+       * What it added.
+       */
+      contributions?: Contribution[];
+      /**
+       * Which extension.
+       */
+      ext: ExtId;
+      /**
+       * How long it took.
+       */
+      ms: number;
+      status: "ok";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it did add.
+       */
+      contributions?: Contribution[];
+      /**
+       * Which extension.
+       */
+      ext: ExtId;
+      /**
+       * How long it took.
+       */
+      ms: number;
+      /**
+       * What is missing, in words a person can act on.
+       */
+      problems?: string[];
+      status: "degraded";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which extension.
+       */
+      ext: ExtId;
+      /**
+       * Why not.
+       */
+      reason: SkipReason;
+      status: "skipped";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which extension.
+       */
+      ext: ExtId;
+      /**
+       * What went wrong.
+       */
+      message: string;
+      /**
+       * How far it got.
+       */
+      stage: LoadStage;
+      status: "failed";
+      [k: string]: unknown;
+    };
+/**
+ * The kinds of thing an extension can contribute.
+ */
+export type ContributionKind =
+  | "tool"
+  | "provider"
+  | "renderer"
+  | "command"
+  | "skill"
+  | "memory"
+  | "grader"
+  | "router"
+  | "session-store"
+  | "mode"
+  | "view"
+  | "agent"
+  | "workflow"
+  | "interceptor"
+  | "lifecycle"
+  | "permissions"
+  | "mcp";
+/**
+ * Why an extension was not loaded at all.
+ *
+ * A **closed** set. "It did not load" is a thing a user has to be able to act on, and free text cannot be grouped, counted or matched against a rule.
+ */
+export type SkipReason = "disabled" | "unsupported" | "dependency-missing" | "policy-denied" | "already-loaded";
+/**
+ * How far loading got before it stopped.
+ */
+export type LoadStage = "manifest" | "resolve" | "link" | "activate" | "contribute";
+/**
+ * One piece of a message.
+ */
+export type ContentBlock =
+  | {
+      t: "text";
+      /**
+       * The text.
+       */
+      text: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Base64, without a data-URL prefix.
+       */
+      data: string;
+      /**
+       * The IANA media type, e.g. `image/png`.
+       */
+      media_type: string;
+      t: "image";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The call this block opens.
+       */
+      call: CallId;
+      /**
+       * The arguments, already validated against the tool's schema.
+       */
+      input: {
+        [k: string]: unknown;
+      };
+      /**
+       * The fully-qualified tool name, `<ext>.<name>`.
+       */
+      name: string;
+      t: "tool-use";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The call this block closes.
+       */
+      call: CallId;
+      /**
+       * How it went.
+       */
+      outcome: Outcome;
+      t: "tool-result";
+      [k: string]: unknown;
+    }
+  | {
+      t: "thinking";
+      /**
+       * The reasoning text.
+       */
+      text: string;
+      [k: string]: unknown;
+    };
+/**
+ * Who said it.
+ */
+export type MessageRole = "system" | "user" | "assistant";
+/**
+ * Client to kernel.
+ *
+ * Every variant carries an `id`, because every response has to name what it is answering. It is repeated per variant rather than lifted to a struct field because serde cannot express a struct-level field alongside an internally tagged enum — a test asserts that no variant lost it.
+ *
+ * The tags are **dotted** and spelled out one by one. No `rename_all` rule produces a dot, so an added variant without an explicit `rename` would show up as `turn-submit` instead of `turn.submit`; the tag test catches exactly that.
+ */
+export type Request =
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which profile to build it from.
+       */
+      profile: string;
+      t: "session.create";
+      /**
+       * The workspace root.
+       */
+      workspace: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      /**
+       * Replay from just after this. Absent means from the start.
+       */
+      since?: Seq | null;
+      t: "session.attach";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * What was submitted.
+       */
+      input: UserInput;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "turn.submit";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * What was sent.
+       */
+      input: UserInput;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "run.send";
+      /**
+       * Where it lands in a busy run. Absent means `steer`.
+       */
+      target?: SendTarget & string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The extension.
+       */
+      ext: string;
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * The key.
+       */
+      key: string;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "state.watch";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "state.unwatch";
+      /**
+       * The watch.
+       */
+      watch: number;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "turn.cancel";
+      /**
+       * Which turn.
+       */
+      turn: TurnId;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      /**
+       * Which surface.
+       */
+      surface: SurfaceId;
+      t: "intent";
+      /**
+       * What the surface produced.
+       */
+      value: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which of its actions.
+       */
+      action: string;
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which node.
+       */
+      node: string;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "ui.intent";
+      /**
+       * What it carries: the chosen item's value, or null.
+       */
+      value?: {
+        [k: string]: unknown;
+      };
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The answer.
+       */
+      answer: ConsentAnswerKind;
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which prompt.
+       */
+      prompt: PromptId;
+      t: "consent.answer";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Its arguments.
+       */
+      args?: {
+        [k: string]: unknown;
+      };
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * The command's name.
+       */
+      name: string;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "command";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "session.handoff";
+      /**
+       * The machine to move to: its id or its name on the account.
+       */
+      to: string;
+      /**
+       * A turn is running: `wait` for it, or `cancel` it. Absent: refused with `turn_running`.
+       */
+      turn?: string | null;
+      /**
+       * The untracked files: `include` or `skip`. Absent: `[handoff] untracked` decides (`ask` asks the requester).
+       */
+      untracked?: string | null;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request id.
+       */
+      id: ReqId;
+      /**
+       * What is being asked about.
+       */
+      of: QueryOf;
+      t: "query";
+      [k: string]: unknown;
+    };
+export type ReqId = string;
+export type SessionId = string;
+export type BranchId = string;
+/**
+ * One part of what a person attached to a message: AG-UI 1.0's `ContentPart`, verbatim (decision 0050).
+ *
+ * What a client **sends**, not what a model is shown: the kernel resolves each part into [`ContentBlock`]s before the turn runs (text inline, an image as an image block where the provider reads images) and refuses the rest by name. A file's name rides in `metadata.filename`.
+ */
+export type ContentPart =
+  | {
+      /**
+       * Identifies this part within its message.
+       */
+      id?: string | null;
+      /**
+       * Anything else about it.
+       */
+      metadata?: {
+        [k: string]: unknown;
+      };
+      /**
+       * The text.
+       */
+      text: string;
+      type: "text";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Identifies this part within its message.
+       */
+      id?: string | null;
+      /**
+       * Anything else about it: `filename`.
+       */
+      metadata?: {
+        [k: string]: unknown;
+      };
+      /**
+       * Where its bytes are.
+       */
+      source: PartSource;
+      type: "image";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Identifies this part within its message.
+       */
+      id?: string | null;
+      /**
+       * Anything else about it: `filename`.
+       */
+      metadata?: {
+        [k: string]: unknown;
+      };
+      /**
+       * Where its bytes are.
+       */
+      source: PartSource;
+      type: "audio";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Identifies this part within its message.
+       */
+      id?: string | null;
+      /**
+       * Anything else about it: `filename`.
+       */
+      metadata?: {
+        [k: string]: unknown;
+      };
+      /**
+       * Where its bytes are.
+       */
+      source: PartSource;
+      type: "video";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Identifies this part within its message.
+       */
+      id?: string | null;
+      /**
+       * Anything else about it: `filename`.
+       */
+      metadata?: {
+        [k: string]: unknown;
+      };
+      /**
+       * Where its bytes are.
+       */
+      source: PartSource;
+      type: "document";
+      [k: string]: unknown;
+    };
+/**
+ * Where a media part's bytes are: AG-UI 1.0's `PartSource`.
+ */
+export type PartSource =
+  | {
+      /**
+       * What they are.
+       */
+      mimeType: string;
+      type: "data";
+      /**
+       * The bytes, base64.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it is, when known.
+       */
+      mimeType?: string | null;
+      type: "url";
+      /**
+       * The URL.
+       */
+      value: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * What it is, when known.
+       */
+      mimeType?: string | null;
+      /**
+       * Who issued it.
+       */
+      provider?: string | null;
+      type: "file";
+      /**
+       * The handle, opaque.
+       */
+      value: string;
+      [k: string]: unknown;
+    };
+/**
+ * Where input sent to a busy run lands.
+ *
+ * `steer`, `queue` and `inject` are one `send` with three targets, not three paths (the DeepSeek harness's `followup` / `steer` / `inject`).
+ */
+export type SendTarget = "steer" | "queue" | "inject";
+/**
+ * The answer to a [`ConsentPrompt`].
+ *
+ * Four answers, not two: "yes" and "yes, and stop asking" are different decisions, and so are "no" and "no, ever".
+ */
+export type ConsentAnswerKind = "allow-once" | "allow-always" | "deny" | "deny-always";
+/**
+ * What a [`Request::Query`] is asking about.
+ */
+export type QueryOf =
+  | {
+      t: "sessions";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which one.
+       */
+      session: SessionId;
+      t: "session";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Which session.
+       */
+      session: SessionId;
+      t: "tools";
+      [k: string]: unknown;
+    }
+  | {
+      t: "extensions";
+      [k: string]: unknown;
+    }
+  | {
+      t: "profiles";
+      [k: string]: unknown;
+    };
+/**
+ * How a file differs from the index.
+ */
+export type ChangeKind = "added" | "modified" | "deleted" | "clean";
+/**
+ * Why a workspace request was refused: stable, for a client to branch on.
+ */
+export type WorkspaceErrorCode =
+  | "bad_request"
+  | "no_session"
+  | "no_workspace"
+  | "unavailable"
+  | "outside_workspace"
+  | "not_found"
+  | "not_a_file"
+  | "too_large"
+  | "binary"
+  | "not_a_repository"
+  | "nothing_to_commit"
+  | "no_identity"
+  | "no_remote"
+  | "git_missing"
+  | "git"
+  | "io";
+/**
+ * A request on a session's workspace (module docs).
+ */
+export type WorkspaceRequest =
+  | {
+      /**
+       * Read the file as git's index holds it — what the live changes (`orrery.session.changes`) are measured against — instead of the disk (harness decision 0056). Not in the index: `not_found`.
+       */
+      base?: boolean;
+      /**
+       * The request's id, echoed as the reply's `reqId`.
+       */
+      id?: string;
+      /**
+       * The file, relative to the workspace (an absolute path inside it is taken too). Never outside it.
+       */
+      path: string;
+      /**
+       * The session whose workspace it reads.
+       */
+      session: string;
+      t: "workspace.read";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request's id.
+       */
+      id?: string;
+      /**
+       * The commit message.
+       */
+      message: string;
+      /**
+       * Only these paths, relative to the workspace. Absent: every change (new, modified and deleted files).
+       */
+      paths?: string[] | null;
+      /**
+       * The session whose workspace it commits.
+       */
+      session: string;
+      t: "workspace.commit";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The request's id.
+       */
+      id?: string;
+      /**
+       * The session whose workspace it pushes.
+       */
+      session: string;
+      t: "workspace.push";
+      [k: string]: unknown;
+    };
+
+/**
+ * The root the schema is generated from.
+ *
+ * Every type a client has to name, reachable from one place. schemars walks it and emits each reachable type once, under `definitions`, so the field names here are an index and nothing ever serialises as a `Protocol`.
+ */
+export interface Protocol {
+  anim: AnimDef;
+  budget: Budget;
+  /**
+   * A bound catalog node (decision 0094): what a client draws for a `component` node once its structure is bound to its data.
+   */
+  catalog: CatalogNode;
+  event: Event;
+  grant: Grant;
+  load_outcome: LoadOutcome;
+  message: Message;
+  request: Request;
+  session_changes: SessionChanges;
+  surface: Surface;
+  surface_patch: SurfacePatch;
+  tool_descriptor: ToolDescriptor;
+  ui: UiDoc;
+  usage: Usage;
+  workspace_committed: WorkspaceCommitted;
+  workspace_failure: WorkspaceFailure;
+  workspace_file: WorkspaceFile;
+  workspace_pushed: WorkspacePushed;
+  workspace_request: WorkspaceRequest;
+  [k: string]: unknown;
+}
+/**
+ * An animation the host sends once, at attach, as the AG-UI `CUSTOM` event `orrery.ui.anim` (decision 0043): an SVG as a template plus the values that change per frame, and the fallbacks a terminal that cannot show an image draws instead. Nothing in it is specific to the Orrery mark.
+ *
+ * Every optional field is additive: a client ignores what it does not know. Nodes refer to a definition by `id` and a state name (`orrery`, `thinking`).
+ */
+export interface AnimDef {
+  /**
+   * What a terminal without truecolor draws, per state.
+   */
+  glyphs?: {
+    [k: string]: AnimGlyphs;
+  };
+  /**
+   * What nodes call it: `orrery`.
+   */
+  id: string;
+  /**
+   * What a truecolor terminal without images draws.
+   */
+  pixel?: AnimPixel | null;
+  /**
+   * Values that depend on the size it is drawn at (thicker strokes, no glow when small). The first entry whose `below` exceeds the size in CSS px applies; the last has no `below`.
+   */
+  sizes?: AnimSize[];
+  /**
+   * The per-frame slot names, in the order a frame lists its values.
+   */
+  slots: string[];
+  /**
+   * Per state (`idle`, `loading`, `thinking`, `executing`, `waiting`, `done`, `error` for the mark): how its frames play.
+   */
+  states: {
+    [k: string]: AnimState;
+  };
+  /**
+   * The SVG, with `{{name}}` where a value comes in. It has no width or height: the drawer scales it to its box.
+   */
+  template: string;
+  /**
+   * Per theme (`graphite`, `paper`): its colours, resolved, and every frame.
+   */
+  themes: {
+    [k: string]: AnimTheme;
+  };
+  /**
+   * The SVG's view box: `[x, y, width, height]`.
+   *
+   * @minItems 4
+   * @maxItems 4
+   */
+  viewBox: [number, number, number, number];
+  [k: string]: unknown;
+}
+/**
+ * The glyph fallback for one state.
+ */
+export interface AnimGlyphs {
+  /**
+   * The glyphs, repeating.
+   */
+  frames: string[];
+  /**
+   * Milliseconds each glyph shows.
+   */
+  ms: number;
+  [k: string]: unknown;
+}
+/**
+ * The pixel fallback: a sprite per state, per theme.
+ */
+export interface AnimPixel {
+  /**
+   * The sprite's width and height in pixels.
+   */
+  size: number;
+  /**
+   * Theme, then state, to its frames.
+   */
+  themes: {
+    [k: string]: {
+      [k: string]: AnimPixelState;
+    };
+  };
+  [k: string]: unknown;
+}
+/**
+ * One state's pixel frames.
+ */
+export interface AnimPixelState {
+  /**
+   * Frames per second. They always repeat.
+   */
+  fps: number;
+  /**
+   * Each frame is rows of palette keys; `.` is transparent.
+   */
+  frames: string[][];
+  /**
+   * `#rrggbb` per palette key, `a` first.
+   */
+  palette: string[];
+  [k: string]: unknown;
+}
+/**
+ * Slot values for a range of drawn sizes.
+ */
+export interface AnimSize {
+  /**
+   * This entry applies below this many CSS px. Absent on the last.
+   */
+  below?: number | null;
+  /**
+   * Slot name to value.
+   */
+  statics: {
+    [k: string]: string;
+  };
+  [k: string]: unknown;
+}
+/**
+ * How a state plays.
+ */
+export interface AnimState {
+  /**
+   * Frames per second.
+   */
+  fps: number;
+  /**
+   * How many frames it has.
+   */
+  frames: number;
+  /**
+   * Whether it repeats; when not, it holds its last frame.
+   */
+  loop: boolean;
+  /**
+   * The frame a repeat starts at, when not the first (an intro plays once).
+   */
+  loopFrom?: number | null;
+  [k: string]: unknown;
+}
+/**
+ * One theme's slot values.
+ */
+export interface AnimTheme {
+  /**
+   * Per state: one row of values per frame, in [`AnimDef::slots`] order.
+   */
+  frames: {
+    [k: string]: string[][];
+  };
+  /**
+   * Slot name to value, for slots that do not change per frame.
+   */
+  statics: {
+    [k: string]: string;
+  };
+  [k: string]: unknown;
+}
+/**
+ * What a turn is allowed to spend.
+ */
+export interface Budget {
+  /**
+   * How much money, in micro-USD. `None` means unmetered.
+   */
+  max_micro_usd?: number | null;
+  /**
+   * How many tokens, input and output together.
+   */
+  max_tokens: number;
+  /**
+   * How many kernel turns.
+   */
+  max_turns: number;
+  /**
+   * How long, in milliseconds of wall clock.
+   */
+  wall_clock_ms: number;
+  [k: string]: unknown;
+}
+/**
+ * One tab of a `tabs`.
+ */
+export interface Tab {
+  /**
+   * What it shows.
+   */
+  children?: CatalogNode[];
+  /**
+   * Its handle, unique among its siblings.
+   */
+  key: string;
+  /**
+   * What the tab says.
+   */
+  label: string;
+  [k: string]: unknown;
+}
+/**
+ * One run of a `text`.
+ */
+export interface Span {
+  /**
+   * How it is meant.
+   */
+  style?: SpanStyle | null;
+  /**
+   * The run.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * One pair of a `kv`.
+ */
+export interface KvItem {
+  /**
+   * The key.
+   */
+  label: string;
+  /**
+   * The value, already formatted.
+   */
+  value: string;
+  [k: string]: unknown;
+}
+/**
+ * One cell of a [`SurfaceKind::Table`].
+ */
+export interface Cell {
+  /**
+   * How it is meant.
+   */
+  style?: TextStyle | null;
+  /**
+   * The cell's text, already formatted by whoever knows the units.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * One entry of a [`NodeKind::List`].
+ */
+export interface ListItem {
+  /**
+   * A second, dimmer line.
+   */
+  detail?: string | null;
+  /**
+   * Shown, but cannot be chosen.
+   */
+  disabled?: boolean;
+  /**
+   * What is shown.
+   */
+  label: string;
+  /**
+   * What comes back when it is chosen.
+   */
+  value: string;
+  [k: string]: unknown;
+}
+/**
+ * One node of a [`SurfaceKind::Tree`].
+ */
+export interface TreeNode {
+  /**
+   * Its children. A leaf has none.
+   */
+  children?: TreeNode[];
+  /**
+   * Whether the node starts open. Absent reads as closed (decision 0094).
+   */
+  expanded?: boolean;
+  /**
+   * A stable handle, when the client needs to address this node: what a catalog `tree`'s action sends. Also read as `value` (decision 0094), always written as `id`.
+   */
+  id?: string | null;
+  /**
+   * What to show.
+   */
+  label: string;
+  [k: string]: unknown;
+}
+/**
+ * One line of a `stream`.
+ */
+export interface StreamLine {
+  /**
+   * Its level.
+   */
+  level?: LogLevel | null;
+  /**
+   * The line.
+   */
+  text: string;
+  /**
+   * When, in epoch ms.
+   */
+  ts?: number | null;
+  [k: string]: unknown;
+}
+/**
+ * One series of a [`SurfaceKind::Chart`].
+ */
+export interface Series {
+  /**
+   * What it is, in the legend.
+   */
+  label: string;
+  /**
+   * Its values, one per label (x, y pairs for `scatter`).
+   */
+  values?: number[];
+  [k: string]: unknown;
+}
+/**
+ * One entry of a [`SurfaceKind::Task`] list.
+ */
+export interface TaskItem {
+  /**
+   * A stable handle, so a patch can update one item. Absent reads as empty (a catalog `task` names none, decision 0094).
+   */
+  id?: string;
+  /**
+   * What to show.
+   */
+  label: string;
+  /**
+   * How far along it is.
+   */
+  status: Status;
+  [k: string]: unknown;
+}
+/**
+ * One field of a catalog `form`: the surface library's [`Field`] plus decision 0094's options, all optional.
+ */
+export interface FormField {
+  /**
+   * What it starts as.
+   */
+  default?: string | null;
+  /**
+   * What is wrong with the value, shown under it.
+   */
+  error?: string | null;
+  /**
+   * What it collects.
+   */
+  kind: FieldKind;
+  /**
+   * What is shown next to it.
+   */
+  label: string;
+  /**
+   * A number's greatest value.
+   */
+  max?: number | null;
+  /**
+   * A number's least value.
+   */
+  min?: number | null;
+  /**
+   * A choice that takes more than one.
+   */
+  multi?: boolean;
+  /**
+   * The key this field's value is submitted under.
+   */
+  name: string;
+  /**
+   * A regex the value must match.
+   */
+  pattern?: string | null;
+  /**
+   * What the empty field says.
+   */
+  placeholder?: string | null;
+  /**
+   * Whether the form can be submitted without it.
+   */
+  required: boolean;
+  /**
+   * A number's step.
+   */
+  step?: number | null;
+  /**
+   * How it is drawn.
+   */
+  style?: FieldStyle | null;
+  [k: string]: unknown;
+}
+/**
+ * One option of a [`SurfaceKind::Question`] or of a choice [`Field`].
+ */
+export interface Choice {
+  /**
+   * What is shown.
+   */
+  label: string;
+  /**
+   * What is sent back on selection.
+   */
+  value: string;
+  [k: string]: unknown;
+}
+/**
+ * The names of a [`SurfaceKind::Raster`]'s rows and columns.
+ */
+export interface RasterLabels {
+  /**
+   * Column names, left first; may be fewer than the columns (ends only).
+   */
+  cols?: string[];
+  /**
+   * One per row, top first.
+   */
+  rows?: string[];
+  [k: string]: unknown;
+}
+/**
+ * One step of a [`SurfaceKind::Raster`]'s legend.
+ */
+export interface LegendItem {
+  /**
+   * The colour, packed `0xRRGGBB`.
+   */
+  colour: number;
+  /**
+   * What it means.
+   */
+  label: string;
+  [k: string]: unknown;
+}
+/**
+ * One entry of a `files`.
+ */
+export interface FileEntry {
+  /**
+   * Lines added.
+   */
+  add?: number | null;
+  /**
+   * Lines removed.
+   */
+  del?: number | null;
+  /**
+   * The path, `/`-separated.
+   */
+  path: string;
+  /**
+   * How it changed.
+   */
+  status: FileStatus;
+  [k: string]: unknown;
+}
+/**
+ * One changed region of a file.
+ */
+export interface Hunk {
+  /**
+   * The lines.
+   */
+  lines?: DiffLine[];
+  /**
+   * How many lines it covers.
+   */
+  new_lines: number;
+  /**
+   * First line of the region in the new file, 1-based.
+   */
+  new_start: number;
+  /**
+   * How many lines it covered.
+   */
+  old_lines: number;
+  /**
+   * First line of the region in the old file, 1-based.
+   */
+  old_start: number;
+  [k: string]: unknown;
+}
+/**
+ * One line inside a [`Hunk`].
+ */
+export interface DiffLine {
+  /**
+   * Added, removed or unchanged.
+   */
+  kind: DiffLineKind;
+  /**
+   * The line itself, without its leading marker.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * A surface, with the handle a patch addresses it by and how far along it is.
+ */
+export interface Surface {
+  /**
+   * The handle. Absent for a surface nothing will ever patch.
+   */
+  id?: SurfaceId | null;
+  /**
+   * What it is.
+   */
+  kind: SurfaceKind;
+  /**
+   * Who a flow's question belongs to (decision 0058 §5): a client on another connection draws it read-only. Absent: anyone answers.
+   */
+  requester?: Requester | null;
+  /**
+   * How far along it is.
+   */
+  status?: Status | null;
+  [k: string]: unknown;
+}
+/**
+ * One input of a [`SurfaceKind::Form`].
+ */
+export interface Field {
+  /**
+   * What it starts as.
+   */
+  default?: string | null;
+  /**
+   * What it collects.
+   */
+  kind: FieldKind;
+  /**
+   * What is shown next to it.
+   */
+  label: string;
+  /**
+   * The key this field's value is submitted under.
+   */
+  name: string;
+  /**
+   * Whether the form can be submitted without it.
+   */
+  required: boolean;
+  [k: string]: unknown;
+}
+/**
+ * Who a flow's question belongs to: the connection that sent the `command` (decision 0058 §5). A client whose own connection is another draws the question read-only, as "<client> is choosing…".
+ */
+export interface Requester {
+  /**
+   * What that client calls itself, for the read-only line.
+   */
+  client?: string | null;
+  /**
+   * The connection that asked.
+   */
+  conn: number;
+  [k: string]: unknown;
+}
+/**
+ * What is being asked for, and why.
+ */
+export interface ConsentPrompt {
+  /**
+   * What they want.
+   */
+  capabilities?: Capability[];
+  /**
+   * The handle an answer is matched to.
+   */
+  id: PromptId;
+  /**
+   * Why, in words a person can act on.
+   */
+  reason: string;
+  /**
+   * The rule that requires the ask, when one does.
+   */
+  rule?: RuleId | null;
+  /**
+   * Who is asking.
+   */
+  subject: Subject;
+  /**
+   * Something to show alongside the question — the diff that is about to be written, the command that is about to run.
+   */
+  surface?: Surface | null;
+  [k: string]: unknown;
+}
+/**
+ * One aspect and the scope it is granted over.
+ *
+ * An **empty** `scope` means unqualified: the whole aspect, not nothing. That is what makes an unscoped parent wider than a scoped child, which is the direction narrowing needs.
+ */
+export interface Capability {
+  /**
+   * What the capability is about.
+   */
+  aspect: Aspect;
+  /**
+   * The names or patterns it covers. Empty means unqualified.
+   */
+  scope?: string[];
+  [k: string]: unknown;
+}
+/**
+ * What was actually spent.
+ */
+export interface Usage {
+  /**
+   * Tokens served from a provider-side prompt cache.
+   */
+  cache_hits: number;
+  /**
+   * Tokens sent.
+   */
+  input_tokens: number;
+  /**
+   * Cost in micro-USD, when the provider reports one.
+   */
+  micro_usd?: number | null;
+  /**
+   * Tokens received.
+   */
+  output_tokens: number;
+  [k: string]: unknown;
+}
+/**
+ * What went wrong.
+ */
+export interface ErrorDetail {
+  /**
+   * A stable, machine-readable code: `provider.unavailable`, `ext.crashed`.
+   */
+  code: string;
+  /**
+   * Anything structured a client could use.
+   */
+  data?: {
+    [k: string]: unknown;
+  };
+  /**
+   * What went wrong, in words.
+   */
+  message: string;
+  /**
+   * Whether the same thing, tried again, might work.
+   */
+  retryable: boolean;
+  [k: string]: unknown;
+}
+/**
+ * The whole screen.
+ */
+export interface UiDoc {
+  /**
+   * The structures [`NodeKind::Component`] nodes name, by name (`/ui/components`, decision 0092). Kept as JSON: a structure's values may be bindings, which only the binder resolves. Absent when empty.
+   */
+  components?: {
+    [k: string]: unknown;
+  };
+  /**
+   * Every node, by id.
+   */
+  nodes: {
+    [k: string]: Node;
+  };
+  /**
+   * The placed surfaces, by node id: who placed each and how it is doing (decisions 0087 and 0088). Every node in a pane or the band is here.
+   */
+  placed?: {
+    [k: string]: Placed;
+  };
+  /**
+   * The root node, a [`NodeKind::Layout`].
+   */
+  root: string;
+  /**
+   * What the host adds to each turn, by run id.
+   */
+  turns?: {
+    [k: string]: TurnMeta;
+  };
+  [k: string]: unknown;
+}
+/**
+ * A command the input box can complete and hint.
+ */
+export interface CommandSpec {
+  /**
+   * A usage hint: `[provider]`, `<command>`.
+   */
+  args?: string;
+  /**
+   * `/model`, or `!` for the shell.
+   */
+  name: string;
+  /**
+   * One line.
+   */
+  summary?: string;
+  [k: string]: unknown;
+}
+/**
+ * A key bound to a command (decision 0083 §4).
+ */
+export interface KeyBinding {
+  /**
+   * The command it runs, without the slash: `git.status`.
+   */
+  command: string;
+  /**
+   * The key as written: `ctrl+g`, `f5`, `alt+r`.
+   */
+  key: string;
+  [k: string]: unknown;
+}
+/**
+ * How full the context window is.
+ */
+export interface ContextUse {
+  /**
+   * Tokens it holds.
+   */
+  limit: number;
+  /**
+   * Tokens in it.
+   */
+  used: number;
+  [k: string]: unknown;
+}
+/**
+ * One extension's segment of the status line.
+ */
+export interface ExtStatus {
+  /**
+   * The extension.
+   */
+  ext: string;
+  /**
+   * Which of its segments.
+   */
+  key: string;
+  /**
+   * What it says now.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * What the host knows about a placed node beyond the node itself.
+ */
+export interface Placed {
+  /**
+   * What a client that cannot draw the node draws instead (decision 0086): core kinds only, checked when it was sent.
+   */
+  fallback?: Surface | null;
+  /**
+   * The id its owner gave it (`ui.show {id}`); one per owner.
+   */
+  id: string;
+  /**
+   * Who placed it, drawn with it: `ext:<id>`, `agent` or `config`.
+   */
+  owner: string;
+  /**
+   * Where it is.
+   */
+  placement: Placement;
+  /**
+   * How it is doing; absent is live.
+   */
+  state?: PlacedState;
+  /**
+   * A title for its pane or band row, when the owner gave one.
+   */
+  title?: string | null;
+  [k: string]: unknown;
+}
+/**
+ * What the host knows about one turn that its events do not say.
+ */
+export interface TurnMeta {
+  /**
+   * The line that started it, echoed above it.
+   */
+  echo?: string | null;
+  /**
+   * What it cost, in micro-USD, when the provider says.
+   */
+  micro_usd?: number | null;
+  /**
+   * How long it took, once settled.
+   */
+  ms?: number | null;
+  /**
+   * Whether input typed while it runs joins it (decision 0008): a kernel run, as opposed to a flow such as a picker. A client sends a prompt at once to a steerable run, and holds it until any other run ends.
+   */
+  steerable?: boolean;
+  /**
+   * Tokens it used.
+   */
+  tokens?: number | null;
+  /**
+   * How many tools it called.
+   */
+  tools?: number | null;
+  [k: string]: unknown;
+}
+/**
+ * One task, as the registry holds it and the wire carries it.
+ */
+export interface TaskInfo {
+  /**
+   * The agent it is, for an agent task.
+   */
+  agent?: string | null;
+  /**
+   * Whether the main thread waits on it (an attached task) rather than working beside it (a background task).
+   */
+  attached?: boolean;
+  /**
+   * How a process ended, when it did by itself.
+   */
+  exit?: number | null;
+  /**
+   * Its id in the session: `t1`, `t2`, …
+   */
+  id: string;
+  /**
+   * What it is.
+   */
+  kind: TaskKind;
+  /**
+   * What a person reads: the agent's id, or the command.
+   */
+  label: string;
+  /**
+   * Where its output goes, for a process task.
+   */
+  log?: string | null;
+  /**
+   * Its process id, for a process task.
+   */
+  pid?: number | null;
+  /**
+   * The port it serves on, when it was started with one.
+   */
+  port?: number | null;
+  /**
+   * When it started, in unix milliseconds.
+   */
+  started_ms: number;
+  /**
+   * Where it stands.
+   */
+  state: TaskState;
+  [k: string]: unknown;
+}
+/**
+ * What a subject is allowed to do.
+ */
+export interface Grant {
+  /**
+   * The capabilities, one entry per aspect-and-scope.
+   */
+  capabilities?: Capability[];
+  /**
+   * How often to ask.
+   */
+  consent: Consent;
+  [k: string]: unknown;
+}
+/**
+ * What an extension added to the session.
+ *
+ * `kind` is a plain enum here. The derive macro that keeps it in step with the extension's manifest — so that a manifest promising a tool and a crate contributing a renderer is a build error rather than a surprise — is the extension host's (plan 06).
+ */
+export interface Contribution {
+  /**
+   * What kind of thing it is.
+   */
+  kind: ContributionKind;
+  /**
+   * Its name, unqualified: the extension is already known.
+   */
+  name: string;
+  [k: string]: unknown;
+}
+/**
+ * One turn of the conversation.
+ */
+export interface Message {
+  /**
+   * What they said.
+   */
+  content?: ContentBlock[];
+  /**
+   * Who said it.
+   */
+  role: MessageRole;
+  [k: string]: unknown;
+}
+/**
+ * What a person submitted.
+ */
+export interface UserInput {
+  /**
+   * Anything else they attached, resolved: what the model is shown (text inline, image blocks). Filled by the kernel from [`Self::parts`]; what a stored turn records.
+   */
+  attachments?: ContentBlock[];
+  /**
+   * Which branch of the turn tree to submit on. Absent means the current one; present means "re-run from here", which is how an edited turn forks rather than overwrites.
+   */
+  branch?: BranchId | null;
+  /**
+   * Files as a client sends them: AG-UI 1.0 content parts (decision 0050). The kernel resolves them into [`Self::attachments`] before the turn runs, refusing what it cannot show the model.
+   */
+  parts?: ContentPart[];
+  /**
+   * What they typed.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * The body of `orrery.session.changes`.
+ */
+export interface SessionChanges {
+  /**
+   * The files that changed in this flush.
+   */
+  changed: FileChange[];
+  /**
+   * The whole set after it.
+   */
+  files: FileChange[];
+  /**
+   * The branch pushed (and its pull request), once a push succeeded. Absent before; additive: a client that does not know it ignores it.
+   */
+  pushed?: Pushed | null;
+  /**
+   * Totals of the whole set.
+   */
+  totals: ChangeTotals;
+  [k: string]: unknown;
+}
+/**
+ * One file's change, relative to the git index.
+ */
+export interface FileChange {
+  /**
+   * Lines added.
+   */
+  add: number;
+  /**
+   * Binary content: no line counts.
+   */
+  binary?: boolean;
+  /**
+   * Lines removed.
+   */
+  del: number;
+  /**
+   * How it differs.
+   */
+  kind: ChangeKind;
+  /**
+   * Path relative to the workspace root, `/`-separated.
+   */
+  path: string;
+  [k: string]: unknown;
+}
+/**
+ * What the session pushed: set once a `git.push` (or `git.pr`) succeeded, and carried by every later `orrery.session.changes`.
+ */
+export interface Pushed {
+  /**
+   * The branch that was pushed (`agent/<session>`).
+   */
+  branch: string;
+  /**
+   * The pull request `git.pr` opened, when it did.
+   */
+  pr_url?: string | null;
+  [k: string]: unknown;
+}
+/**
+ * Totals of a change set.
+ */
+export interface ChangeTotals {
+  /**
+   * Lines added.
+   */
+  add: number;
+  /**
+   * Lines removed.
+   */
+  del: number;
+  /**
+   * Files.
+   */
+  files: number;
+  [k: string]: unknown;
+}
+/**
+ * One tool, as it appears in a model request.
+ *
+ * A wire type, and therefore this crate's: the registry produces it from [`AgentScope`](crate::AgentScope), a provider serialises it into the prompt, and the model is shown it. Both sides naming the same struct is what stops the two halves drifting — there used to be a copy in `orrery-provider` and a second in `orrery-tools`, with no conversion between them.
+ *
+ * It is produced only by `Registry::visible`, so the list the model sees is a real subset of what exists rather than a promise in a prompt.
+ */
+export interface ToolDescriptor {
+  /**
+   * Whether the tool's effect is all-or-nothing.
+   */
+  atomic: boolean;
+  /**
+   * What it does, in the model's context window.
+   */
+  description: string;
+  /**
+   * JSON Schema for the input. Validated at the dispatch boundary, never by the provider.
+   */
+  input_schema: {
+    [k: string]: unknown;
+  };
+  /**
+   * The form the model should emit: the short name where it is unambiguous within this scope, the full `ext.name` where it is not.
+   */
+  name: string;
+  [k: string]: unknown;
+}
+/**
+ * The answer to `workspace.commit`.
+ */
+export interface WorkspaceCommitted {
+  /**
+   * The new commit, in full.
+   */
+  sha: string;
+  [k: string]: unknown;
+}
+/**
+ * A refused workspace request: its code and what to do.
+ */
+export interface WorkspaceFailure {
+  /**
+   * Why, for a program.
+   */
+  code: WorkspaceErrorCode;
+  /**
+   * Why, for a person, with the fix.
+   */
+  message: string;
+  [k: string]: unknown;
+}
+/**
+ * The answer to `workspace.read`.
+ */
+export interface WorkspaceFile {
+  /**
+   * The index side (asked with `base`, decision 0057). A node older than decision 0056 never sets it: it ignores `base` and answers with the working file.
+   */
+  base?: boolean;
+  /**
+   * Its size on disk, in bytes.
+   */
+  bytes: number;
+  /**
+   * The path as asked.
+   */
+  path: string;
+  /**
+   * The file's text (UTF-8).
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * The answer to `workspace.push`: git ran, and this is what it said.
+ */
+export interface WorkspacePushed {
+  /**
+   * Whether the push went through. `false` when the remote refused it (rejected, no access, timed out): `output` says why.
+   */
+  ok: boolean;
+  /**
+   * What `git push` printed.
+   */
+  output: string;
+  [k: string]: unknown;
+}