@neosh/api 0.1.0

package/src/generated/SessionInfo.ts

@@ -0,0 +1,171 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BackgroundTask } from "./BackgroundTask";
+import type { PermissionMode } from "./PermissionMode";
+import type { SessionId } from "./SessionId";
+import type { TurnId } from "./TurnId";
+import type { Usage } from "./Usage";
+
+export type SessionInfo = {
+  id: SessionId;
+  cwd: string;
+  /**
+   * What to call the directory this conversation is in.
+   *
+   * The last segment of the path is the obvious answer and is wrong for the case that matters:
+   * a worktree is named by whoever created it, and a list of projects reading `wt-fe3c0d93`
+   * tells you nothing about which repository or branch that is. A checkout is named by the
+   * repository it belongs to, and a linked worktree adds the branch — `neosh · fix/thing` —
+   * because that is what a person means when they say which one they are in.
+   *
+   * Computed by the host so every frontend and plugin agrees, the same as `label`.
+   */
+  project: string;
+  /**
+   * The main checkout of the repository `cwd` is in, when it is in one.
+   *
+   * This is what lets a list *group* rather than merely label: `project` says `neosh ·
+   * fix/thing` about a linked worktree, but a string made for reading is not a key — the only
+   * way to find the worktree's siblings in it is to parse a display format back apart. The
+   * sidebar nests a worktree under the project it is a worktree *of*, and this is the field
+   * that says which one that is. Equal to `cwd` in the main checkout itself; `None` outside a
+   * repository.
+   */
+  repo_root?: string | null;
+  /**
+   * The branch checked out at `cwd` when the host last looked, `None` on a detached head or
+   * outside a repository. A label, not a fact about *now*: it is refreshed when the directory
+   * is next visited, not on every `git switch` someone runs in a shell.
+   */
+  branch?: string | null;
+  message_count: number;
+  active_turn?: TurnId | null;
+  /**
+   * Seconds since the epoch, stamped when the running turn began.
+   *
+   * A list that says a conversation is working should say for how long — "thinking" with no
+   * clock is indistinguishable from "wedged". Only meaningful while `active_turn` is set; the
+   * value is deliberately left behind afterwards rather than cleared, because nothing reads it
+   * then and clearing it would be one more write on the turn-end path.
+   */
+  turn_started_at?: number | null;
+  /**
+   * Set by the user or by generation. `None` until something names it.
+   */
+  title?: string | null;
+  /**
+   * What to show in a list: the title, else the opening of the first user message. Computed by
+   * the host so every frontend and plugin agrees on the fallback.
+   */
+  label: string;
+  created_at: number;
+  updated_at: number;
+  usage: Usage;
+  /**
+   * How full the context window was on the most recent request: input plus cache, for that one
+   * turn.
+   *
+   * Separate from `usage`, which is cumulative and therefore useless for this: a conversation
+   * that has spent 400k tokens across twenty turns is not 400k tokens *long*. The number people
+   * want is how much room is left, and only the last request knows it.
+   */
+  context_tokens: number;
+  /**
+   * The window those tokens are a fraction of, **as the driver reports it**.
+   *
+   * `None` when nothing has said, and then a catalogue figure is the best available guess. It is
+   * only a guess: a vendor CLI's window is whatever that CLI decided, which is not always what a
+   * catalogue says the model has. `claude` running `claude-haiku-4-5` answers `maxTokens:
+   * 200000` while neosh's own entry for the selected model said a million — so the meter was
+   * dividing a number it half-knew by a denominator it had invented, and read `2%` where the
+   * agent itself would have said `8%`.
+   */
+  context_window?: number | null;
+  /**
+   * Whether this is the conversation on screen **in the terminal that asked**.
+   *
+   * A workspace can have several terminals and each is somewhere, so this is a question with as
+   * many answers as there are screens and the host stamps in the one for whoever is asking. A
+   * panel drawing a list marks its own conversation with it; use [`Self::on_screen`] for "is
+   * anybody looking at this".
+   */
+  is_active: boolean;
+  /**
+   * Whether *some* terminal is reading this conversation.
+   *
+   * The workspace-wide half of the question above, and the one an unread mark turns on: a turn
+   * that ends where nobody could see it is news, and where nobody could see it means every
+   * screen.
+   */
+  on_screen: boolean;
+  /**
+   * A turn finished here while you were looking at something else.
+   *
+   * The one thing a list of conversations cannot say without being told. A turn takes minutes,
+   * you switch away, and the row it left behind is indistinguishable from the twelve above it —
+   * so the answer you were waiting for is found by opening conversations until one of them has
+   * it. This is the mark that makes it findable, and it is *news* rather than state: it is set
+   * when a turn ends somewhere you were not, and cleared the moment you arrive.
+   *
+   * Off screen is the whole test. A turn that ended in the conversation on screen has already
+   * been seen — including when nothing was attached, because reattaching lands you in that
+   * conversation with the answer in it.
+   */
+  unread: boolean;
+  /**
+   * The workspace stopped while a turn was running here, and nothing ended that turn.
+   *
+   * The one thing a conversation cannot notice about itself: a process that is killed does not
+   * get to write down that it was. So a turn writes down that it *started* and clears the note
+   * when it ends, and a note still there when the conversation is next loaded says the process
+   * that made it never got to the end — the machine was shut down, the workspace was `SIGKILL`ed,
+   * the OOM killer chose it. Whatever the agent had already done is in `messages`; what it was
+   * in the middle of is gone, and this is the only thing that will ever say so.
+   *
+   * Deliberately *not* the same kind of mark as [`Self::unread`], which is news and is cleared
+   * by arriving. This is a fact about the conversation's last turn, and arriving does not change
+   * it: at startup you land in the conversation you were last in, which is usually the one that
+   * was cut off, and a mark that cleared on arrival would clear exactly the one that mattered
+   * most before you had read it. It goes when a new turn starts here, because that is the point
+   * at which the last turn stops being the last turn.
+   */
+  interrupted: boolean;
+  /**
+   * What is still running here that no turn is waiting for.
+   *
+   * The other half of [`Self::unread`]. That one says a turn *finished* somewhere you were not
+   * looking; this says one did not finish everything it started — a shell the agent put in the
+   * background, a sub-agent it let go of — and that the conversation is still doing something
+   * even though it has told you it is done.
+   *
+   * A level: whatever the driver last said is running, verbatim, and empty means nothing is.
+   * Kept on the conversation rather than the turn because the turn is over — that is the case
+   * it exists for — and because there is more than one list that has to agree about it. See
+   * [`crate::Activity::Background`], including why it is never persisted.
+   */
+  background?: Array<BackgroundTask>;
+  /**
+   * Put away rather than thrown away.
+   *
+   * An archived conversation keeps every message and can be brought back; it is simply not in
+   * the list you look at every day. It exists because the alternative verb people were reaching
+   * for was delete, and delete is the one thing in a workspace that cannot be undone.
+   */
+  archived: boolean;
+  /**
+   * Seconds since the epoch, stamped when it was archived. `None` while it is in the open list.
+   */
+  archived_at?: number | null;
+  /**
+   * What this conversation lets the agent do without asking.
+   *
+   * A property of the conversation and not of the process, because that is how it is used: a
+   * throwaway question in someone else's repository and the branch you have been on all week are
+   * not the same risk, and a mode that followed whichever one you looked at last would be a
+   * setting you could only trust by re-reading it. It is saved with the conversation for the
+   * same reason — coming back to a conversation should mean coming back to how it was set up.
+   *
+   * `None` means the conversation has never been given one and takes whatever `config.toml`
+   * says.
+   */
+  permission_mode?: PermissionMode | null;
+};

package/src/generated/StatusAlign.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type StatusAlign = "left" | "right";

package/src/generated/StatusSegment.ts

@@ -0,0 +1,49 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { StatusAlign } from "./StatusAlign";
+
+/**
+ * One piece of the status line.
+ */
+export type StatusSegment = {
+  text: string;
+  /**
+   * The same thing, said in less room — used when the strip will not fit and before this
+   * segment is dropped for it.
+   *
+   * A narrow terminal is the case a status line has to survive, and the two answers it had were
+   * both wrong. Truncating is out: half a token count is a wrong token count, and a bar cut
+   * short is a bar reading a level nothing is at. Dropping is what happened instead, and it
+   * took the context meter out of exactly the terminal that most needed it — a turn running
+   * adds a segment, which is why the number people watch went missing precisely while there was
+   * something to watch.
+   *
+   * So the segment says its own short form, for the reason [`Hint`] splits its key from its
+   * label: what may be given up is a decision only the thing that wrote the text can make, and
+   * it cannot be made once the text is one string. `███░░░░░ 34%` is the same fact as
+   * `███░░░░░ 34% of 200k` with the denominator left out, and it is still true.
+   *
+   * Absent means there is no shorter true version, and the segment is dropped whole.
+   */
+  short?: string | null;
+  /**
+   * The key that changes this, written the way the user would press it — `^P`, `^Z`.
+   *
+   * Beside what it acts on rather than in a list of its own, because a key is only memorable
+   * once you have seen it next to the thing it does. A separate legend is a second place to
+   * look, and the thing being looked up is right there.
+   */
+  keys?: string | null;
+  hl?: string | null;
+  align: StatusAlign;
+  /**
+   * Lower sorts first within its side. Ties break by key, so the order is stable across redraws
+   * rather than depending on which plugin happened to load first.
+   *
+   * It is also what a narrow strip gives up first, in reverse — so this is a statement about
+   * how much the segment is worth, not only about where it goes. Two segments on the same
+   * number are separated by the spelling of their keys, which is fine for an order and is no
+   * way to decide which of them survives: give anything you would mind losing a number of its
+   * own.
+   */
+  priority: number;
+};

package/src/generated/StopReason.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Why a turn stopped.
+ *
+ * `Refusal` is explicit because current models return HTTP 200 with a refusal stop reason rather
+ * than an error — code that only checks for transport failures silently renders an empty turn.
+ */
+export type StopReason =
+  | { "kind": "end_turn" }
+  | { "kind": "tool_use" }
+  | { "kind": "max_tokens" }
+  | { "kind": "stop_sequence" }
+  | { "kind": "refusal"; category?: string | null; explanation?: string | null }
+  | { "kind": "cancelled" }
+  | { "kind": "error"; message: string };

package/src/generated/StreamEvent.ts

@@ -0,0 +1,26 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Activity } from "./Activity";
+import type { Message } from "./Message";
+import type { StopReason } from "./StopReason";
+import type { Usage } from "./Usage";
+
+/**
+ * What a subscriber is told while watching one agent.
+ *
+ * The same events the owning node's own frontend gets, minus anything a viewer cannot act on.
+ * Enough to render a live transcript: that is the point, because "it feels like the agent is on
+ * this computer" is a claim about what you can see, not about where the process is.
+ */
+export type StreamEvent =
+  | { "event": "history"; messages: Array<Message> }
+  | { "event": "turn_started"; turn: string }
+  | { "event": "token"; turn: string; text: string }
+  | { "event": "thinking"; turn: string; text: string }
+  | { "event": "activity"; turn: string; activity: Activity }
+  | {
+    "event": "turn_ended";
+    turn: string;
+    stop_reason: StopReason;
+    usage: Usage;
+  }
+  | { "event": "blocked"; turn: string; prompt: string };

package/src/generated/StreamId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Correlates an in-flight provider stream with its cancellation.
+ */
+export type StreamId = string;

package/src/generated/SurfaceCell.ts

@@ -0,0 +1,22 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Attrs } from "./Attrs";
+import type { Color } from "./Color";
+
+/**
+ * A directly-addressed cell within a claimed surface.
+ *
+ * The escape hatch for the ~5% of plugins (diff gutters, sparklines, token/cost graphs) that
+ * cannot be expressed as text plus annotations. A non-terminal frontend renders a surface as an
+ * opaque monospace grid.
+ */
+export type SurfaceCell = {
+  row: number;
+  col: number;
+  /**
+   * One grapheme cluster, not one `char`. Emoji and combining sequences are single cells here.
+   */
+  grapheme: string;
+  fg?: Color | null;
+  bg?: Color | null;
+  attrs: Attrs;
+};

package/src/generated/SurfaceId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A claimed raw-cell surface.
+ */
+export type SurfaceId = number;

package/src/generated/SwarmAgent.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AgentSummary } from "./AgentSummary";
+import type { NodeInfo } from "./NodeInfo";
+
+/**
+ * One remote agent, with the node it belongs to attached.
+ *
+ * Flattened for the common case, which is drawing a list: an agent is addressed as `(node,
+ * session)`, and a row that carried only the session would be a row you cannot act on.
+ */
+export type SwarmAgent = { node: NodeInfo; agent: AgentSummary };

package/src/generated/SwarmNode.ts

@@ -0,0 +1,24 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AgentSummary } from "./AgentSummary";
+import type { LinkState } from "./LinkState";
+import type { NodeCapabilities } from "./NodeCapabilities";
+import type { NodeInfo } from "./NodeInfo";
+
+/**
+ * A node, as a plugin sees it: what it is, and what it has.
+ */
+export type SwarmNode = {
+  info: NodeInfo;
+  capabilities: NodeCapabilities;
+  /**
+   * `false` for a machine we have lost touch with. Its agents are still described, because they
+   * were real a moment ago and probably still are — what changed is that we cannot see them.
+   */
+  up: boolean;
+  /**
+   * The story behind `up`: connecting, retrying with a count, or not being dialled at all.
+   */
+  link: LinkState;
+  reason?: string | null;
+  agents: Array<AgentSummary>;
+};

package/src/generated/SwarmStranger.ts

@@ -0,0 +1,21 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { NodeInfo } from "./NodeInfo";
+
+/**
+ * A machine that proved who it is and has not been paired with.
+ */
+export type SwarmStranger = {
+  info: NodeInfo;
+  /**
+   * `true` when we found it by dialling an address, `false` when it dialled us.
+   *
+   * Decides what to ask. One is "this is what is at that address — add it?", the other is
+   * "this machine wants to join — allow it?", and they are different questions even though the
+   * button does the same thing.
+   */
+  dialled: boolean;
+  /**
+   * Where it was reached, when we were the one dialling.
+   */
+  addr?: string | null;
+};

package/src/generated/TaskId.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One sub-agent, from the moment it is spawned to the moment it reports.
+ *
+ * Distinct from the [`ToolCallId`] of the call that started it: a driver may run a task
+ * nobody asked for by name — a background job, a workflow member — and those have no call to
+ * borrow an id from. When there *is* one, it is carried alongside rather than reused, so the
+ * tree can be rebuilt without either id having to mean two things.
+ */
+export type TaskId = string;

package/src/generated/TaskStatus.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Where a sub-agent got to.
+ */
+export type TaskStatus =
+  | "running"
+  | "backgrounded"
+  | "done"
+  | "failed"
+  | "cancelled";

package/src/generated/TextEdit.ts

@@ -0,0 +1,19 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A change to make at a window's cursor.
+ *
+ * Deliberately verbs rather than a text diff: a plugin that wants "delete the word behind the
+ * cursor" should not have to reimplement word boundaries, and every caller getting the same answer
+ * is the only way `<C-w>` means one thing across the whole program.
+ */
+export type TextEdit =
+  | { "kind": "insert"; text: string }
+  | { "kind": "delete_back" }
+  | { "kind": "delete_forward" }
+  | { "kind": "delete_word_back" }
+  | { "kind": "delete_word_forward" }
+  | { "kind": "delete_to_line_start" }
+  | { "kind": "delete_to_line_end" }
+  | { "kind": "delete_range"; from: [number, number]; to: [number, number] }
+  | { "kind": "delete_selection" };

package/src/generated/ToolCall.ts

@@ -0,0 +1,13 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ToolCallId } from "./ToolCallId";
+import type { TurnId } from "./TurnId";
+
+/**
+ * A tool call in flight, as seen by hooks.
+ */
+export type ToolCall = {
+  id: ToolCallId;
+  turn: TurnId;
+  name: string;
+  input: unknown;
+};

package/src/generated/ToolCallId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Correlates a `tool_use` block with its result.
+ */
+export type ToolCallId = string;

package/src/generated/ToolDef.ts

@@ -0,0 +1,12 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ToolSource } from "./ToolSource";
+
+export type ToolDef = {
+  name: string;
+  description: string;
+  /**
+   * JSON Schema. Passed to the provider verbatim.
+   */
+  input_schema: Record<string, unknown>;
+  source: ToolSource;
+};

package/src/generated/ToolInvocation.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { RequestId } from "./RequestId";
+
+/**
+ * A tool the host wants the plugin to run.
+ */
+export type ToolInvocation = {
+  request: RequestId;
+  name: string;
+  input: unknown;
+};

package/src/generated/ToolResult.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ToolResult = { content: string; is_error: boolean };

package/src/generated/ToolSource.ts

@@ -0,0 +1,12 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Where a tool came from.
+ *
+ * Built-in, plugin and MCP tools land in one namespace with one shape, so that a policy hook does
+ * not have to care which kind it is intercepting.
+ */
+export type ToolSource = { "kind": "builtin" } | {
+  "kind": "plugin";
+  plugin: string;
+} | { "kind": "mcp"; server: string };

package/src/generated/TurnId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One user message plus everything the agent did in response, including tool calls.
+ */
+export type TurnId = string;

package/src/generated/TurnRequest.ts

@@ -0,0 +1,56 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Message } from "./Message";
+import type { ModelSelection } from "./ModelSelection";
+import type { SessionId } from "./SessionId";
+import type { ToolDef } from "./ToolDef";
+
+export type TurnRequest = {
+  selection: ModelSelection;
+  /**
+   * Which conversation this turn belongs to.
+   *
+   * A driver that keeps anything between turns needs this and cannot derive it. A vendor CLI
+   * holds the history on its side and hands back a session id to resume into; a driver that
+   * kept one of those per *process* — as this one did — would resume the second conversation
+   * into the first one's history, and neither of them would ever say anything was wrong.
+   *
+   * Several conversations run at once by design, so "the current one" is not a thing a driver
+   * may assume. Empty for a caller that has no conversation to name, such as a one-shot
+   * generation — a driver keying state by this must treat that as "keep nothing".
+   */
+  conversation: SessionId;
+  /**
+   * The directory this turn happens in.
+   *
+   * The conversation's, not the process's. A vendor CLI is an agent that reads files, runs
+   * commands and looks at git — all of it relative to where it was started — so a driver that
+   * spawns it in whatever directory neosh happened to be launched from is asking about the
+   * wrong repository. Every conversation carries a project; this is how a driver finds out
+   * which one.
+   *
+   * Empty means "wherever the host process is", which is what a driver with no opinion did
+   * before this field existed.
+   */
+  cwd: string;
+  /**
+   * What the driver called this conversation last time, if it named it.
+   *
+   * A vendor CLI keeps the history on its side and hands back a handle — `claude`'s session id,
+   * ACP's session, `codex`'s conversation. A driver that only remembers that handle in its own
+   * process remembers it exactly as long as the workspace lives: restart, reopen a conversation
+   * with a hundred messages in it, and the agent is started fresh and told only the newest one.
+   * The transcript looks full and the model has never heard of any of it, which is not a thing
+   * either side reports as an error — it is simply an agent that has forgotten, and the first
+   * visible sign of it is `/compact` finishing instantly with nothing to compact.
+   *
+   * So the handle belongs to the conversation, which is the thing that outlives the process.
+   * The driver hands it over with [`Activity::Resume`] and is given it back here. `None` means
+   * this conversation has never been run by this driver, which is the only case where starting
+   * fresh is right.
+   */
+  resume?: string | null;
+  system?: string | null;
+  messages: Array<Message>;
+  tools?: Array<ToolDef>;
+  max_output_tokens?: number | null;
+};

package/src/generated/UiEvent.ts

@@ -0,0 +1,80 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BufferId } from "./BufferId";
+import type { CursorShape } from "./CursorShape";
+import type { HighlightDef } from "./HighlightDef";
+import type { LineRender } from "./LineRender";
+import type { MessageLevel } from "./MessageLevel";
+import type { NoticeKind } from "./NoticeKind";
+import type { Rect } from "./Rect";
+import type { SurfaceCell } from "./SurfaceCell";
+import type { SurfaceId } from "./SurfaceId";
+import type { WindowId } from "./WindowId";
+import type { WindowLayout } from "./WindowLayout";
+
+/**
+ * A retained-state delta. Frontends fold these into a mirror and draw from it.
+ *
+ * Emitted in coalesced batches — see [`UiEvent::Flush`].
+ */
+export type UiEvent =
+  | { "type": "init"; protocol_version: number }
+  | { "type": "buffer_opened"; buf: BufferId; name: string }
+  | { "type": "buffer_closed"; buf: BufferId }
+  | {
+    "type": "buffer_lines";
+    buf: BufferId;
+    start: number;
+    old_end: number;
+    lines: Array<LineRender>;
+  }
+  | {
+    "type": "window_opened";
+    win: WindowId;
+    buf: BufferId;
+    layout: WindowLayout;
+  }
+  | { "type": "window_configured"; win: WindowId; layout: WindowLayout }
+  | { "type": "window_buffer"; win: WindowId; buf: BufferId }
+  | { "type": "window_closed"; win: WindowId }
+  | { "type": "cursor_moved"; win: WindowId; row: number; col: number }
+  | { "type": "cursor_shape_changed"; win: WindowId; shape: CursorShape }
+  | { "type": "scroll_to"; win: WindowId; top_line: number | null }
+  | { "type": "highlight_defined"; name: string; def: HighlightDef }
+  | { "type": "highlight_cleared"; name: string }
+  | { "type": "window_highlights"; win: WindowId; map: Record<string, string> }
+  | { "type": "surface_claimed"; surface: SurfaceId; win: WindowId; rect: Rect }
+  | { "type": "surface_cells"; surface: SurfaceId; cells: Array<SurfaceCell> }
+  | { "type": "surface_released"; surface: SurfaceId }
+  | { "type": "focus_changed"; win: WindowId | null }
+  | {
+    "type": "message";
+    level: MessageLevel;
+    text: string;
+    /**
+     * Whether you asked for this, which is what decides how long it lives.
+     *
+     * Defaulted rather than required: `Reply` is what every existing sender meant, and a
+     * frontend from before this existed folds the field away and draws what it always drew.
+     */
+    kind: NoticeKind;
+    /**
+     * Which progress row this is, for [`NoticeKind::Progress`].
+     *
+     * Ignored on every other kind. Writing the same key twice replaces the row; see
+     * [`UiEvent::ProgressDone`] for taking it away.
+     */
+    key?: string | null;
+  }
+  | { "type": "progress_done"; key: string }
+  | {
+    "type": "alert";
+    /**
+     * What this is about, in a few words — a conversation's name, usually.
+     */
+    title: string;
+    body: string;
+    level: MessageLevel;
+  }
+  | { "type": "clipboard"; text: string }
+  | { "type": "flush" }
+  | { "type": "shutdown" };

package/src/generated/Usage.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Token accounting, surfaced so a plugin can render a budget without scraping.
+ */
+export type Usage = {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+  /**
+   * Thinking tokens, where the provider reports them separately.
+   */
+  thinking_tokens: number;
+};