@matatbread/matbot-plugin-api 0.3.8 → 0.4.0

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { Session } from './types.js';
+import type { MessageContent, Session } from './types.js';
 
 /**
  * A session's `updatedAt` invariant: the timestamp of its last message, or its own `createdAt` when it
@@ -15,3 +15,32 @@ export function lastActivityAt(session: Session): string {
   const last = session.messages[session.messages.length - 1];
   return last ? last.createdAt : session.createdAt;
 }
+
+/**
+ * Index of the turn's user message — the message a durable fold attaches to, and the point a retraction
+ * pops back to. `-1` when the session has none.
+ */
+export function lastUserIndex(session: Session): number {
+  return session.messages.findLastIndex(m => m.role === 'user');
+}
+
+/**
+ * Append `blocks` to the turn's user message, returning a new session. This is what "durable" means
+ * everywhere it appears: unlike `ephemeral` (tail-folded into the outgoing copy and discarded), the blocks
+ * become part of the user turn — persisted, visible to a reader, and carried by every subsequent provider
+ * call in the turn and after it.
+ *
+ * With no user message the blocks are **dropped rather than orphaned**: there is nothing they could belong
+ * to, and appending a message of their own would change the role sequence the adapters depend on.
+ *
+ * Shared because the three callers must agree: the `screen` hook fold, the runner's raced-verdict
+ * correction, and the pump's retract-and-rerun rebase. They were three independent copies of one
+ * `findLastIndex` + splice, in two different packages.
+ */
+export function foldOntoUserTurn(session: Session, blocks: readonly MessageContent[]): Session {
+  if (blocks.length === 0) return session;
+  const idx = lastUserIndex(session);
+  if (idx < 0) return session;
+  return { ...session, messages: session.messages.map((m, i) =>
+    i === idx ? { ...m, content: [...m.content, ...blocks] } : m) };
+}

package/src/types/events.ts

@@ -0,0 +1,81 @@
+import type { FileHandle } from './files.js';
+import type { MessageContent, Session } from './messages.js';
+import type { Usage } from './provider.js';
+
+// ── Pipeline events ─────────────────────────────────────────────────────────────
+
+/**
+ * A turn's own events. `traceId` — the turn that produced it — is the correlation key a frontend routes
+ * on (see `SessionRunner`), and every arm here carries it. Grouped by what a consumer does with them:
+ * streamed model output, tool progress, live delivery of something already persisted, and the terminals.
+ *
+ * A turn ends with **exactly one** terminal: `done`, `aborted` (interrupted mid-flight), or `error`.
+ */
+export type TurnEvent =
+  // ── streamed model output ──
+  | { type: 'text-delta';     delta: string;          traceId: string }
+  | { type: 'thinking';       delta: string;          traceId: string }
+  | { type: 'system-context'; text: string;           traceId: string }
+  | ({ type: 'usage';         traceId: string } & Usage)
+
+  // ── tool execution ──
+  | { type: 'tool:start';     callId: string; name: string; input: unknown; traceId: string }
+  | { type: 'tool:stdout';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:stderr';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:progress';  callId: string; pct: number; message?: string; traceId: string }
+  | { type: 'tool:end';       callId: string; result: unknown; isError: boolean; traceId: string }
+
+  // ── live delivery of state that is ALREADY persisted; never the source of truth ──
+  | { type: 'file';           handle: FileHandle;     traceId: string }
+  // Machine-authored content folded onto the running turn's user message (a `screen` hook's
+  // `durable` result — e.g. a fired `contextual` trigger), carried live so a frontend draws it
+  // immediately. The blocks are already persisted in that user message (origin: 'robo'); this is
+  // purely the live-delivery channel, so a live draw matches the reload (which splits the user
+  // turn's robo blocks into their own agent-side bubble).
+  | { type: 'robo-user';      content: MessageContent[]; traceId: string }
+  // Marker blocks appended to the session this turn (e.g. the dispatcher's record of a hook that
+  // threw), carried live so a frontend renders them without waiting for a session reload. The blocks
+  // are already persisted in the session; this event is purely the live-delivery channel.
+  | { type: 'marker';         content: MessageContent[]; traceId: string }
+
+  // ── queue disposition ──
+  // A queued (not-yet-running) submission, carried on the stream so a frontend renders it as part
+  // of the live "delta" (everything after the last committed message), never from stored state.
+  // `queued` is the number of submissions ahead of it (0 ⇒ about to run). Emitted live on enqueue
+  // and replayed (in queue order) to anyone subscribing mid-flight.
+  | { type: 'queued';         content: MessageContent[]; queued: number; concatQueue: boolean; traceId: string; rootTraceId: string }
+  // A mid-turn steer that INTERRUPTED the running turn (see `SteeringPolicy`). Emitted synchronously
+  // when the steer is accepted, so the new user bubble lands in correct stream order and a frontend
+  // knows the imminent `aborted` (reason 'steer') on `interruptedTraceId` is a yield, not a dead-end:
+  // keep that turn's partial work rendered and expect a continuation. `traceId`/`rootTraceId` identify
+  // the steer submission itself (the continuation turn). Late subscribers reconstruct the bubble from
+  // the pump's per-turn `queued` replay seed / committed store order — this is purely live delivery.
+  | { type: 'steer';          content: MessageContent[]; interruptedTraceId: string; traceId: string; rootTraceId: string }
+
+  // ── terminals: exactly one per turn ──
+  | { type: 'done';           session: Session;       traceId: string }
+  | { type: 'aborted';        reason: string; session: Session; traceId: string }
+  | { type: 'error';          error: string;          traceId: string }
+  // A queued submission dropped before it ever ran (e.g. by `SessionRunner.abort`). It carries no
+  // session because nothing ran and so nothing was persisted — but it does have a traceId: the
+  // submission it cancels was assigned one at enqueue, and a frontend needs it to retire that bubble.
+  | { type: 'cancelled';      sessionId: string;      traceId: string };
+
+/**
+ * Events about the *session*, not any one turn — hence keyed on `sessionId` with no `traceId`. Split from
+ * {@link TurnEvent} so that absence is type-checkable rather than a comment: `idle` was the single arm of
+ * a 20-arm union without a `traceId`, which every consumer had to know by having read the note saying so.
+ */
+export type SessionEvent =
+  // The runner has fully drained its queue. Emitted once per busy period, *after* `running` flips false,
+  // so a consumer can map it to an authoritative busy→idle transition without racing the internal flip.
+  | { type: 'idle';           sessionId: string };
+
+/**
+ * The streaming output of a session: its turns' events, plus the session-level ones.
+ *
+ * Consumers that only ever see one turn (a tool reporting progress, a per-turn frontend) should narrow to
+ * {@link TurnEvent} and get `traceId` unconditionally; a subscriber to a whole session takes this union
+ * and must handle `idle`. Switching on `type` works the same either way.
+ */
+export type PipelineEvent = TurnEvent | SessionEvent;

package/src/types/files.ts

@@ -0,0 +1,46 @@
+import type { ISODate, MimeType } from './primitives.js';
+
+// ── Files ─────────────────────────────────────────────────────────────────────
+
+export interface FileMetaData {
+  id:          string;
+  version:     string;
+  name:        string;
+  mimeType:    MimeType;
+  size:        number;
+  createdAt:   ISODate;
+  sessionId?:  string;
+  messageId?:  string;
+  namespace?:  string;
+  /** Whether this file may be served at a public URL. Default-deny: absent ⇒ not servable. The
+   *  flag rides in the file's own persisted metadata (no separate allow-list), so the same read that
+   *  resolves a request also gates it. Producers opt in per put (the workspace tool sets it true). */
+  allowed?:    boolean;
+}
+
+export interface FileHandle extends FileMetaData {
+  stream(signal?: AbortSignal): AsyncIterable<Uint8Array>;
+}
+
+export interface FileFilter {
+  sessionId?:     string;
+  mimeType?:      string;
+  namespace?:     string;
+  createdAfter?:  ISODate;
+  createdBefore?: ISODate;
+}
+
+export interface FileStore {
+  /** Store a file. When `name` is provided, upserts by (name + namespace); otherwise always creates a new entry. */
+  put(
+    name:     string | undefined,
+    mimeType: MimeType,
+    data:     AsyncIterable<Uint8Array>,
+    meta?:    { sessionId?: string; messageId?: string; namespace?: string; allowed?: boolean }
+  ): Promise<FileHandle>;
+  get(id: string): Promise<FileHandle | null>;
+  getByName(name: string, namespace?: string): Promise<FileHandle | null>;
+  delete(id: string): Promise<void>;
+  list(filter?: FileFilter): AsyncIterable<FileHandle>;
+  putTemp(name: string, mimeType: MimeType, data: AsyncIterable<Uint8Array>): Promise<FileHandle>;
+}

package/src/types/frontend.ts

@@ -0,0 +1,11 @@
+// ── Frontend ──────────────────────────────────────────────────────────────────
+
+/**
+ * Passed to `services.registerFrontend()` by a plugin declaring itself a frontend. A frontend
+ * owns its own I/O (an HTTP server, a bot connection, a REPL); matbot only needs to know it
+ * exists. This object is the growth point for frontend-level capability advertisement
+ * (accepted/produced MIME types, size limits, …) as media support lands.
+ */
+export interface FrontendInfo {
+  name: string;
+}

package/src/types/health.ts

@@ -0,0 +1,6 @@
+// ── Health ────────────────────────────────────────────────────────────────────
+
+export type HealthStatus =
+  | { status: 'ok';       latencyMs?: number }
+  | { status: 'degraded'; reason: string; latencyMs?: number }
+  | { status: 'down';     reason: string };

package/src/types/hooks.ts

@@ -0,0 +1,217 @@
+import type { Message, MessageContent, Session } from './messages.js';
+import type { PromptFn, Tool } from './tools.js';
+
+// ── Pipeline hooks ────────────────────────────────────────────────────────────
+
+export interface RunConfig {
+  provider:   string;
+  sessionId?: string;
+  traceId?:   string;
+}
+
+/**
+ * Hooks are sorted by the *job* they do, not by lifecycle position — the channel name is the
+ * contract. Each channel has a fixed home, cadence, and effect-ceiling (a hook may always do
+ * less: returning nothing makes it a pure observer). The discriminated union on `on` is what
+ * keeps the effects honest — `contribute` hands you a read-only session, `toolcall`/`react` can't
+ * return one at all, so a write that goes nowhere won't type-check.
+ *
+ *   screen      runner, once per turn before the first provider call. The only channel that may
+ *               durably mutate history. Returns any of: a replacement `session` (persisted),
+ *               turn-scoped `ephemeral` context (appended onto the tail of this turn's outgoing
+ *               messages — the freshest input the model reads — never persisted, and placed at the
+ *               tail rather than a system prefix so a "do X now" directive keeps its salience and
+ *               doesn't bust the cached prefix), `durable` context (the persisted, visible twin of
+ *               `ephemeral`: folded onto this turn's user message as `origin: 'robo'` blocks and
+ *               carried live as a `robo-user` event, so it survives into the next turn's history),
+ *               or `abort`. Mix freely. This is where the durable-vs-ephemeral choice for incoming
+ *               user input lives.
+ *   contribute  runner, before *every* provider call. Ephemeral by construction (it re-fires, so a
+ *               durable mutation would accumulate). Returns a transformed copy of `outgoing` — the
+ *               message array about to be sent — and never touches the stored session. Mind prompt
+ *               caching: vary the *tail* (newest turn) freely, but a transform that rewrites the
+ *               cached prefix (system / early history) busts the cache on every call.
+ *   toolcall    runner, before each tool execution. Read-only. Returns `rejectTool` (skip this call,
+ *               feed an error result back so the model self-corrects, without breaking the
+ *               tool_use/tool_result pairing) and/or `abort`.
+ *   toolresult  runner, after each tool execution, before the result is recorded/yielded. Folds the
+ *               result through each hook: return `{ result }` to replace it (hard redaction, truncation),
+ *               or nothing to observe (auditing — the context carries args, result, isError and
+ *               `durationMs`). It owns the LLM-facing + persisted result and the `tool:end` event;
+ *               note it does NOT see the live `tool:stdout/stderr` chunks, which stream before the
+ *               result exists.
+ *   followup    pump, once after a turn commits (post-persist). May `resubmit` a robo follow-up turn
+ *               (head-enqueued, so it runs next as its own real turn; `resubmitDepth` is the chain
+ *               length for the hook's own budget — the runner also hard-caps it), `retractAndRerun`
+ *               (pop the committed turn into a marker and re-run the originating user turn with
+ *               ephemeral context — supersede rather than follow), and/or append durable `markers`
+ *               to the committed session (LLM-invisible annotations — the second durable-write point
+ *               after `screen`, safe because it too fires once per turn).
+ */
+export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup';
+
+export interface ScreenContext {
+  session: Session;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** The turn's interactive prompt, when a frontend supplied one (a live user behind this turn).
+   *  A hook that drives an interactive tool (e.g. a trigger invoking `ask_user`) forwards this into
+   *  the tool's context; absent (cron/background/no frontend) the tool gets a rejecting prompt. */
+  prompt?: PromptFn;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+/**
+ * A raced screen verdict the runner folds in WITHOUT gating the turn on it. A `screen` hook that starts
+ * expensive work concurrently (e.g. a triggers classifier judging the user message) returns immediately
+ * and hands back one of these instead of blocking on it. The runner polls `claim()` — synchronously,
+ * never awaiting — at each turn-loop edge (before a provider call, on every stream event, and just
+ * before committing). The first time `claim()` returns blocks (the work has settled WITH a correction),
+ * the runner DISCARDS the uncommitted in-progress response and re-runs the loop with those blocks
+ * tail-folded as ephemeral context — an in-situ redo: no store pop, no retraction marker, cleaner than a
+ * post-commit retract. Because the mid-stream poll runs before each event is emitted, a verdict faster
+ * than time-to-first-token is caught before any token reaches the frontend (the clean path); a slower
+ * one aborts the in-flight provider request, saving the unstreamed remainder. If it never fires before
+ * the turn commits, the turn commits normally and any correction is left to a post-commit `followup`.
+ *
+ * `claim()` MUST be exactly-once: return the correction on the first successful poll and `undefined`
+ * forever after (not settled, no correction, or already claimed). The hook uses that single delivery to
+ * coordinate with its own post-commit path — a claimed verdict is never also delivered by `followup`.
+ */
+export interface DeferredScreen {
+  claim(): DeferredCorrection | undefined;
+}
+/**
+ * A claimed raced-verdict correction. `ephemeral` is tail-folded onto the re-run's outgoing messages
+ * and never persisted (the transient "for this answer only" twin); `durable` is folded onto the turn's
+ * user message — persisted, visible (the hook marks it `origin: 'robo'`), and carried live as a
+ * `robo-user` event — so it updates the conversation rather than informing one answer (a `contextual`
+ * trigger's semantics, preserved even though the verdict now lands mid-turn instead of before it). At
+ * least one is non-empty when returned.
+ */
+export interface DeferredCorrection {
+  ephemeral?: MessageContent[];
+  durable?:   MessageContent[];
+}
+export interface ScreenResult {
+  session?:   Session;
+  /**
+   * A raced verdict the runner folds in without gating on it (see {@link DeferredScreen}). Lets a
+   * screen hook race expensive work — a classifier — against generation: return immediately, hand this
+   * back, and the runner restarts the turn in-situ if the verdict fires before commit. A hook that
+   * would rather gate the turn (block until the verdict) just returns `ephemeral` as usual instead.
+   */
+  deferred?:  DeferredScreen;
+  /** Turn-scoped context appended onto the tail of this turn's outgoing messages (the freshest
+   *  input the model reads), never persisted. At the tail, not a system prefix, so a directive
+   *  keeps its salience and the cached system/history prefix stays stable across turns. */
+  ephemeral?: MessageContent[];
+  /**
+   * The persisted, visible twin of `ephemeral`: context that should outlive this turn rather than
+   * inform it once. The runner folds these blocks onto this turn's user message (so they ride into
+   * the stored history and every subsequent provider call) AND carries them live as a `robo-user`
+   * event, so a live draw and a reload render the same thing. They are LLM-visible (unlike
+   * `markers`) and machine-authored, so a caller marks them `origin: 'robo'` for presentation.
+   * Use when a fired hook produces context that genuinely updates the conversation, not a one-shot
+   * corrective for the turn about to run.
+   */
+  durable?:   MessageContent[];
+  /**
+   * Durable `marker` blocks to append to this turn's session (LLM-invisible). The dispatcher both
+   * appends them to the persisted session AND carries them live on the turn's event stream, so a
+   * live draw and a reload render the same thing. Use instead of hand-appending to `session` when
+   * you just want to annotate (e.g. a fired trigger's silent tool recording what it did).
+   */
+  markers?:   MessageContent[];
+  abort?:     string;
+}
+
+export interface ContributeContext {
+  readonly outgoing: readonly Message[];
+  readonly session:  Session;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+
+export interface ToolCallContext {
+  readonly session:  Session;
+  readonly toolCall: { id: string; name: string; input: unknown };
+  readonly tool:     Tool;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+export interface ToolCallResult {
+  rejectTool?: { message: string };
+  abort?:      string;
+}
+
+export interface ToolResultContext {
+  readonly session:    Session;
+  readonly toolCall:   { id: string; name: string; input: unknown };
+  readonly tool:       Tool;
+  readonly result:     unknown;
+  readonly isError:    boolean;
+  readonly durationMs: number;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+// The toolresult hook returns `{ result }` to replace the tool's result, or nothing to leave it
+// (and just observe) — a trivial single-field return, inlined in the Hook union like `contribute`'s.
+
+export interface FollowupContext {
+  readonly session:       Session;
+  readonly resubmitDepth: number;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** The turn's interactive prompt, when a frontend supplied one (a live user behind this turn).
+   *  A hook that drives an interactive tool (e.g. a trigger invoking `ask_user` as a proactive
+   *  follow-up question) forwards this into the tool's context; absent (cron/background/no frontend)
+   *  the tool gets a rejecting prompt. Note this prompt fires *post-commit*, out of band from the
+   *  turn's `done`, and blocks the pump until the human answers. */
+  prompt?: PromptFn;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+export interface FollowupResult {
+  resubmit?: { content: MessageContent[] };
+  /**
+   * Retract-and-rerun: supersede the just-committed turn instead of following it. The pump pops the
+   * committed turn back to (and excluding) the last user message, stashes the popped content in a
+   * durable retraction marker (LLM-elided like every marker, so a frontend can render it
+   * struck-through and a post-mortem can audit it), then re-runs that same user turn with `context`
+   * injected EPHEMERALLY (tail-folded, never persisted) — agent-phase injection time-shifted onto a
+   * committed turn. This is the inverse of `resubmit`, which leaves the response in place and appends
+   * a new robo turn after it. Self-terminating by design: a well-formed trigger fires on a *curable*
+   * defect that the injected context dissolves on the redo, so it won't re-fire; `resubmitDepth` (a
+   * redo carries parent+1) caps an ill-formed one. `resubmit` and `retractAndRerun` are independent
+   * capabilities — a single turn returning both is not expected, but both head-enqueue if it does.
+   *
+   * `context` is folded EPHEMERALLY onto the redo (for-this-answer-only). `durable` is instead folded
+   * onto the re-run's user message — persisted, visible (mark it `origin: 'robo'`), carried live as a
+   * `robo-user` event — so a `contextual`-kind correction updates the conversation durably even when it
+   * lands post-commit. At least one of the two is present.
+   */
+  retractAndRerun?: { context?: MessageContent[]; durable?: MessageContent[] };
+  /**
+   * Durable `marker` blocks to append to the just-committed session (LLM-invisible; for tracing /
+   * cross-references). The second durable-write capability after `screen` — safe here for the same
+   * reason: `followup` fires once per turn, so an append can't accumulate the way a per-call channel
+   * would. The pump persists them AND emits them live (post-commit, like a `queued` event) so a live
+   * draw matches a reload. Use for recording what a post-commit reaction (e.g. a fired trigger's
+   * silent tool) actually did.
+   */
+  markers?: MessageContent[];
+}
+
+export type Hook =
+  | { on: 'screen';     priority?: number; pluginName?: string; handler(ctx: ScreenContext):     ScreenResult | void | Promise<ScreenResult | void> }
+  | { on: 'contribute'; priority?: number; pluginName?: string; handler(ctx: ContributeContext): Message[]    | void | Promise<Message[]    | void> }
+  | { on: 'toolcall';   priority?: number; pluginName?: string; handler(ctx: ToolCallContext):   ToolCallResult | void | Promise<ToolCallResult | void> }
+  | { on: 'toolresult'; priority?: number; pluginName?: string; handler(ctx: ToolResultContext): { result: unknown } | void | Promise<{ result: unknown } | void> }
+  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> };

package/src/types/knowledge.ts

@@ -0,0 +1,27 @@
+// ── Knowledge index ───────────────────────────────────────────────────────────
+
+export interface KnowledgeEntry {
+  id:           string;
+  version:      string;
+  entities:     string[];
+  tags:         string[];
+  summary:      string;
+  content:      string;
+  contentHash?: string;
+  source:       { type: string; uuid: string };
+  confidence?:  number;
+  createdAt:    string;
+  updatedAt:    string;
+}
+
+export interface KnowledgeIndex {
+  index(entry: KnowledgeEntry): Promise<void>;
+  /** Remove the entry with this id, if present (idempotent — removing an absent id is a no-op). The
+   *  id is the index's sole primary key (`index` replaces by it), so retraction is by id alone; the
+   *  index never inspects an entry's opaque `source`. The party that indexed an entry owns retracting
+   *  it — e.g. a skill manager retracts a hidden/deleted skill rather than the index policing tenants. */
+  remove(id: string): Promise<void>;
+  search(terms: Array<{ term: string; context?: string }>, signal: AbortSignal): Promise<KnowledgeEntry[]>;
+  /** Enumerate all indexed entries. When present, register('KnowledgeIndex', …) drains these into the incoming backend. */
+  entries?(): Iterable<KnowledgeEntry>;
+}

package/src/types/messages.ts

@@ -0,0 +1,154 @@
+import type { HookPoint } from './hooks.js';
+import type { ISODate, MimeType } from './primitives.js';
+import type { ProviderMeta, Usage, UsageRecord } from './provider.js';
+
+// ── Messages & Session ────────────────────────────────────────────────────────
+
+export type MessageRole = 'user' | 'assistant' | 'tool' | 'system' | 'marker';
+
+export type MessageContent = (
+  // ── prose and reasoning: what the model said ──
+  | { type: 'text';              text: string }
+  | { type: 'thinking';          thinking: string; signature: string }
+  | { type: 'redacted-thinking'; data: string }
+  | { type: 'reasoning';         reasoning: string }
+  | { type: 'refusal';           text: string }
+
+  // ── inline media: bytes plus a mime type. The first three are also `ModelContent` — the arms a tool
+  //    may hand the model to look at (see the `model-content` ToolEvent). `image-url` and `file-ref`
+  //    are references rather than data, and nothing produces them yet; they are reconsidered together
+  //    when durable user-supplied media is built (a `document` / `document-reference` split). ──
+  | { type: 'image';             data: string; mimeType: MimeType }
+  | { type: 'document';          data: string; mimeType: MimeType; name?: string }
+  | { type: 'audio';             data: string; mimeType: MimeType }
+  | { type: 'image-url';         url: string; detail?: 'low' | 'high' | 'auto' }
+  | { type: 'file-ref';          fileId: string; name: string; mimeType: MimeType }
+
+  // ── tool use ──
+  | { type: 'tool-call';         id: string; name: string; input: unknown;
+      /** Provider-specific round-trip metadata, persisted and re-sent verbatim on replay — see
+       *  `ProviderMeta` and the `tool-call` `CompletionEvent`. */
+      meta?: ProviderMeta }
+  | { type: 'tool-result';       id: string; result: unknown; isError?: boolean;
+      /**
+       * Accounting addendum: completions the tool itself ran (e.g. `single_turn`, `dream_time`'s ranker/
+       * merger), captured ambiently via the usage carrier and recorded for cost reckoning. Elided from
+       * provider submission — adapters serialise only `id`/`result`/`isError`. One entry per provider
+       * call, each tagged with the provider billed; never summed at write time, as rates differ.
+       */
+      usage?: UsageRecord[] }
+
+  // ── frontend-facing: rendered to a person, never sent to the model ──
+  | { type: 'form';              fields: FormField[]; submitLabel?: string }
+  | { type: 'form-response';     values: Record<string, string> }
+  // Durable, opaque annotation — persisted unchanged, elided from every submission. See MarkerData below.
+  | { type: 'marker';            creator: string; data: unknown }
+
+  // ── a provider block this build does not know: preserved verbatim rather than dropped ──
+  | { type: 'unknown-content';   blockType: string; raw: unknown }
+) & {
+  /**
+   * Authorship provenance, for *presentation only* — orthogonal to the message's `role`, which is
+   * the LLM-protocol identity. Absent ⇒ authored per the role (a human for `user`, the model for
+   * `assistant`). `'robo'` ⇒ machine-authored by matbot — a `followup` resubmission, or a hook-
+   * injected fragment inside a human turn. It is still carried to the model as ordinary
+   * role-appropriate content (the model sees a `user` block either way); the flag is OOB metadata
+   * that frontends use to present it agent-side (a robot indicator) rather than as the user's words.
+   */
+  origin?: 'robo';
+};
+
+/**
+ * A marker is opaque, durable annotation carried in the message stream: links, status,
+ * cross-references that are meaningful to a frontend but transparent to the LLM. They are
+ * persisted unchanged, elided from provider submission, and deliberately preserved by
+ * session compaction (removing one can break things — e.g. a pointer back to an ancestor
+ * session). Any code with session access may emit one, normally as its own message.
+ *
+ * `creator` is the emitting plugin's reference; `data` is anything serialisable. For
+ * per-creator type safety, augment `MarkerData` and read/write via `Marker<'your-creator'>`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface MarkerData { 'split-session': { peerSessionId: string } }
+ *   }
+ *
+ * Unregistered creators fall back to `data: unknown`. The base `MessageContent` member stays
+ * loose (`creator: string`) so the union and its exhaustive switches are unaffected.
+ *
+ * One of matbot's five open-registry augmentation points — same technique at each; see
+ * docs/DEVELOPING.md *Open-registry augmentation* for the shared shape and the rules that follow from it.
+ */
+export interface MarkerData {
+  /** Emitted by the hook dispatcher when a hook handler threw: the hook was skipped (treated as a
+   *  no-op) and this records it once, so a misconfigured/throwing hook degrades visibly instead of
+   *  bricking the turn. `channel` is the hook point, `pluginName` the owning plugin if known. */
+  'matbot-hooks': { channel: HookPoint; pluginName?: string; message: string };
+  /** Emitted by the runner when a provider call was cut short rather than finishing (see the
+   *  `truncated` CompletionEvent). Marker-role so the reader and an audit see it while the model does
+   *  not — the model's own text is already truncated in the transcript; a block telling it so would
+   *  invite it to narrate the cut-off rather than continue past it. */
+  'matbot-truncation': { reason: 'max-tokens' | 'stream-end'; raw?: string };
+}
+
+export type Marker<K extends string = string> = {
+  type:    'marker';
+  creator: K;
+  data:    K extends keyof MarkerData ? MarkerData[K] : unknown;
+};
+
+export interface FormField {
+  name:        string;
+  label:       string;
+  type:        'text' | 'password' | 'select' | 'confirm';
+  options?:    string[];
+  /** select-only: render an "Other…" affordance that lets the user type a free-form answer instead
+   *  of picking an option. The typed value is returned verbatim, on the same channel as a pick —
+   *  callers never learn whether the answer was a preset or free text. Ignored for other types. */
+  allowOther?: boolean;
+  default?:    string;
+  required?:   boolean;
+  /** Presentation hint only (default true): whether the frontend offers a cancel affordance (the
+   *  "give up" path — see `PromptFn`). Set false to render a hard-blocking prompt with no out. The
+   *  runner and server never consult this; a frontend with no cancel UI simply can't fire one. */
+  cancelable?: boolean;
+}
+
+/**
+ * Canonical values a `type: 'confirm'` prompt resolves to. The rendered label and buttons are a
+ * cosmetic, host-specific concern (and may be localised), so consumers MUST branch on these tokens
+ * — never on the displayed string. Compare case-insensitively to tolerate host casing differences.
+ */
+export const CONFIRM_YES = 'yes';
+export const CONFIRM_NO  = 'no';
+
+export interface Message {
+  id:            string;
+  role:          MessageRole;
+  content:       MessageContent[];
+  createdAt:     ISODate;
+  traceId:       string;
+  providerName?: string;
+  /** Token/cost accounting for the provider call that produced this message (assistant turns). The
+   *  billed provider is this message's `providerName`. Accounting only — elided from provider submission. */
+  usage?:        Usage;
+  metadata?:     Record<string, unknown>;
+}
+
+export type SessionStatus = 'active' | 'archived' | 'pinned';
+
+export interface Session {
+  id:                    string;
+  version:               string;
+  // Legacy: persisted sessions may still carry `ownerPrincipalId` / `actorPrincipalId` / `persona`, and
+  // `contexts` (a required-but-never-read `string[]`, dropped at 0.4.0 — system context is contributed by
+  // SystemContextContributor, not carried on the session). Never read — ownership-at-rest is structural
+  // (the storage partition), resolved via the backend, not a field. Left undeclared; old data keeps them
+  // harmlessly as excess properties.
+  title?:                string;
+  status:                SessionStatus;
+  messages:              Message[];
+  parentSessionId?:      string;
+  branchPointMessageId?: string;
+  createdAt:             ISODate;
+  updatedAt:             ISODate;
+}

package/src/types/primitives.ts

@@ -0,0 +1,5 @@
+// ── Primitives ────────────────────────────────────────────────────────────────
+
+export type ISODate = string;
+export type MimeType = string;
+export type JSONSchema = Record<string, unknown>;

package/src/types/principal.ts

@@ -0,0 +1,10 @@
+// ── Principal ───────────────────────────────────────────────────────────────
+
+/** Identity of whatever initiated an operation — a turn, a tool call, a store read/write.
+ *  Established at each entry point and carried ambiently via the `PrincipalCarrier`
+ *  (`currentPrincipal()` / `runAs()`), so any layer can attribute or test the origin without it
+ *  being threaded through every signature. It grants nothing — policy is the service's concern. */
+export interface Principal {
+  id:    string;
+  type:  'user' | 'agent' | 'system';
+}