@staix/agent-console 0.0.0-stage → 0.1.1

package/src/conformance.ts

@@ -0,0 +1,299 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CONSOLE_FEATURES, type ConsolePlugin, type ConsoleProvider } from "./contract.ts";
+import { ASSET_TYPES, assetResultProblems, manifestProblems, providerProblems, withTimeout } from "./plugins.ts";
+import { spaceSceneProblems } from "./space.ts";
+
+export { spaceSceneProblems } from "./space.ts";
+
+export interface ConformanceOptions {
+  /** Family home passed to open(); a fresh temp directory by default. */
+  home?: string;
+  /** Actions that must answer needsConfirm when sent without confirmation. */
+  destructive?: ({ action: string } & Record<string, unknown>)[];
+  /** Asset ids that must answer a served type (provider.asset). */
+  assets?: string[];
+}
+
+const GROUPS = ["decision", "review", "result", "candidate", "alert"];
+/** What the console passes as action meta (#27), so a plugin that reads meta.identity is checked as it runs. */
+const META = { identity: "local", node: "local", via: "console" } as const;
+const within = (v: unknown, max: number) => typeof v === "string" && v.length > 0 && v.length <= max;
+
+/** Problems with a verb's choice form against the #27 bounds; the shell skips an item whose form has any. */
+export function verbFormProblems(form: unknown): string[] {
+  const f = form as { questions?: unknown } | null;
+  if (!f || typeof f !== "object" || !Array.isArray(f.questions)) return ["form.questions must be an array"];
+  const out: string[] = [];
+  if (f.questions.length < 1 || f.questions.length > 4) out.push("form needs 1-4 questions");
+  const ids = new Set<unknown>();
+  f.questions.forEach((q: Record<string, unknown> | null, i: number) => {
+    const at = `form.questions[${i}]`;
+    if (!q || typeof q !== "object") { out.push(`${at} must be an object`); return; }
+    if (!within(q.id, 64) || ids.has(q.id)) out.push(`${at}.id must be a unique string of at most 64 characters`);
+    ids.add(q.id);
+    if (q.header !== undefined && !within(q.header, 80)) out.push(`${at}.header must be at most 80 characters`);
+    if (!within(q.prompt, 1000)) out.push(`${at}.prompt must be 1-1000 characters`);
+    if (q.multiple !== undefined && typeof q.multiple !== "boolean") out.push(`${at}.multiple must be a boolean`);
+    const options = q.options as Record<string, unknown>[] | undefined;
+    if (!Array.isArray(options) || options.length < 2 || options.length > 8) out.push(`${at}.options needs 2-8 options`);
+    else {
+      const oids = new Set<unknown>();
+      options.forEach((o, j) => {
+        if (!o || !within(o.id, 64) || oids.has(o.id)) out.push(`${at}.options[${j}].id must be a unique string of at most 64 characters`);
+        oids.add(o?.id);
+        if (!o || !within(o.label, 80)) out.push(`${at}.options[${j}].label must be 1-80 characters`);
+        if (o?.description !== undefined && !within(o.description, 240)) out.push(`${at}.options[${j}].description must be at most 240 characters`);
+      });
+    }
+    const other = q.other as Record<string, unknown> | undefined;
+    if (other !== undefined) {
+      if (!other || typeof other !== "object") out.push(`${at}.other must be an object`);
+      else {
+        if (other.label !== undefined && !within(other.label, 80)) out.push(`${at}.other.label must be at most 80 characters`);
+        if (other.maxLength !== undefined && !(Number.isSafeInteger(other.maxLength) && (other.maxLength as number) >= 1 && (other.maxLength as number) <= 1000)) out.push(`${at}.other.maxLength must be 1-1000`);
+      }
+    }
+  });
+  return out;
+}
+const isText = (v: unknown) => typeof v === "string" && v.length > 0;
+
+export function inboxItemProblems(item: unknown): string[] {
+  const i = item as Record<string, unknown> | null;
+  if (!i || typeof i !== "object") return ["item must be an object"];
+  const out: string[] = [];
+  for (const key of ["id", "kind", "title", "at"]) if (!isText(i[key])) out.push(`item.${key} must be a non-empty string`);
+  if (!GROUPS.includes(i.group as string)) out.push("item.group must be decision, review, result, candidate or alert");
+  if (typeof i.at === "string" && Number.isNaN(Date.parse(i.at))) out.push("item.at must be an ISO time");
+  if (!Array.isArray(i.verbs) || i.verbs.some((v) => !v || !isText(v.id) || !isText(v.label))) out.push("item.verbs must be {id, label}[]");
+  else {
+    if (i.verbs.some((v) => v.reason !== undefined && v.reason !== "optional" && v.reason !== "required")) out.push("item.verbs[].reason must be optional or required");
+    for (const v of i.verbs) if (v.form !== undefined) out.push(...verbFormProblems(v.form).map((p) => `verb ${String(v.id)}: ${p}`));
+  }
+  const seen = i.seen as Record<string, unknown> | undefined;
+  if (seen !== undefined && (!seen || !isText(seen.action))) out.push("item.seen.action must be a non-empty string");
+  const link = i.link as Record<string, unknown> | undefined;
+  if (!link || !isText(link.panel)) out.push("item.link.panel is required");
+  return out;
+}
+
+/** Items present in both inbox snapshots whose `at` changed; snooze and oldest-first order key on `at`. */
+export function stableAtProblems(first: unknown[], second: unknown[]): string[] {
+  const at = new Map<unknown, unknown>();
+  for (const item of first) if (item && typeof item === "object") at.set((item as { id?: unknown }).id, (item as { at?: unknown }).at);
+  const out: string[] = [];
+  for (const item of second) {
+    const { id, at: now } = (item ?? {}) as { id?: unknown; at?: unknown };
+    if (at.has(id) && at.get(id) !== now) out.push(`item ${String(id)}: at changed from ${String(at.get(id))} to ${String(now)} with nothing changed`);
+  }
+  return out;
+}
+
+/** Problems in a ui.table column list; panels and #29-style payloads can assert this is empty. */
+export function tableColumnProblems(columns: unknown): string[] {
+  if (!Array.isArray(columns)) return ["columns must be an array"];
+  const out: string[] = [];
+  if (columns.length > 12) out.push(`columns: ${columns.length} exceeds 12; ui.table shows the first 12`);
+  const keys = new Set<unknown>();
+  columns.forEach((c, i) => {
+    const col = (c ?? {}) as Record<string, unknown>;
+    if (!isText(col.key)) out.push(`columns[${i}].key must be a non-empty string`);
+    else if (keys.has(col.key)) out.push(`columns[${i}].key ${String(col.key)} repeats`);
+    keys.add(col.key);
+    if (!isText(col.label)) out.push(`columns[${i}].label must be a non-empty string`);
+    if (col.align !== undefined && col.align !== "start" && col.align !== "end") out.push(`columns[${i}].align must be start or end`);
+    if (col.format !== undefined && !["text", "number", "percent"].includes(col.format as string)) out.push(`columns[${i}].format must be text, number or percent`);
+  });
+  return out;
+}
+
+/** Review bounds shared with agent-hub through test/fixtures/review/cases.json. */
+export const REVIEW_BOUNDS = Object.freeze({ exact: 2000, context: 64, selectors: 4, threads: 200, body: 4000 });
+const SHA256 = /^[0-9a-f]{64}$/;
+const posInt = (v: unknown) => Number.isInteger(v) && (v as number) >= 1;
+const finiteNum = (v: unknown) => typeof v === "number" && Number.isFinite(v);
+
+function selectorProblems(s: unknown, at: string): string[] {
+  const x = (s ?? {}) as Record<string, unknown>;
+  if (!s || typeof s !== "object") return [`${at} must be an object`];
+  switch (x.kind) {
+    case "lineRange":
+      if (!posInt(x.startLine) || !posInt(x.endLine)) return [`${at}: startLine and endLine must be integers >= 1`];
+      return (x.startLine as number) > (x.endLine as number) ? [`${at}: startLine must not exceed endLine`] : [];
+    case "textQuote": {
+      const out: string[] = [];
+      if (typeof x.exact !== "string" || !x.exact) out.push(`${at}.exact must be a non-empty string`);
+      else if (x.exact.length > REVIEW_BOUNDS.exact) out.push(`${at}.exact is over ${REVIEW_BOUNDS.exact} characters`);
+      for (const k of ["prefix", "suffix"]) {
+        if (typeof x[k] !== "string") out.push(`${at}.${k} must be a string`);
+        else if ((x[k] as string).length > REVIEW_BOUNDS.context) out.push(`${at}.${k} is over ${REVIEW_BOUNDS.context} characters`);
+      }
+      return out;
+    }
+    case "diffHunk":
+      return typeof x.hunkHeader === "string" && x.hunkHeader.startsWith("@@") ? [] : [`${at}.hunkHeader must be a unified diff hunk header`];
+    case "structural":
+      return isText(x.scheme) && isText(x.ref) ? [] : [`${at}: scheme and ref must be non-empty strings`];
+    case "region": {
+      const out = ["x", "y", "width", "height"].filter((k) => !finiteNum(x[k]) || (x[k] as number) < 0).map((k) => `${at}.${k} must be a number >= 0`);
+      if (x.page !== undefined && !posInt(x.page)) out.push(`${at}.page must be an integer >= 1`);
+      return out;
+    }
+    default:
+      return [`${at}.kind must be lineRange, textQuote, diffHunk, structural or region`];
+  }
+}
+
+/** Problems in one ReviewAnchor. */
+export function reviewAnchorProblems(anchor: unknown): string[] {
+  const a = (anchor ?? {}) as Record<string, unknown>;
+  if (!anchor || typeof anchor !== "object" || Array.isArray(anchor)) return ["anchor must be an object"];
+  const out: string[] = [];
+  if (!isText(a.path)) out.push("anchor.path must be a non-empty string");
+  if (a.side !== undefined && a.side !== "base" && a.side !== "head") out.push("anchor.side must be base or head");
+  if (a.contentHash !== undefined && (typeof a.contentHash !== "string" || !SHA256.test(a.contentHash))) out.push("anchor.contentHash must be a lowercase hex sha256");
+  if (a.projection !== undefined) {
+    const p = (a.projection ?? {}) as Record<string, unknown>;
+    if (!a.projection || typeof a.projection !== "object" || !isText(p.name) || !isText(p.version)) out.push("anchor.projection must be {name, version}");
+  }
+  if (!Array.isArray(a.selectors) || !a.selectors.length) out.push("anchor.selectors must be a non-empty array");
+  else {
+    if (a.selectors.length > REVIEW_BOUNDS.selectors) out.push(`anchor.selectors has more than ${REVIEW_BOUNDS.selectors} selectors`);
+    a.selectors.forEach((s, i) => out.push(...selectorProblems(s, `anchor.selectors[${i}]`)));
+  }
+  return out;
+}
+
+/** Problems in one ReviewThread. */
+export function reviewThreadProblems(thread: unknown): string[] {
+  const t = (thread ?? {}) as Record<string, unknown>;
+  if (!thread || typeof thread !== "object" || Array.isArray(thread)) return ["thread must be an object"];
+  const out: string[] = [];
+  if (!isText(t.id)) out.push("thread.id must be a non-empty string");
+  if (!isText(t.author)) out.push("thread.author must be a non-empty string");
+  if (typeof t.body !== "string" || !t.body) out.push("thread.body must be a non-empty string");
+  else if (t.body.length > REVIEW_BOUNDS.body) out.push(`thread.body is over ${REVIEW_BOUNDS.body} characters`);
+  if (typeof t.at !== "string" || Number.isNaN(Date.parse(t.at))) out.push("thread.at must be an ISO time");
+  if (t.state !== undefined && t.state !== "open" && t.state !== "resolved") out.push("thread.state must be open or resolved");
+  out.push(...reviewAnchorProblems(t.anchor).map((p) => `thread.${p}`));
+  return out;
+}
+
+/** Problems in the thread list a plugin passes to ui.review: shape, bounds and unique ids. */
+export function reviewProblems(threads: unknown): string[] {
+  if (!Array.isArray(threads)) return ["threads must be an array"];
+  const out: string[] = [];
+  if (threads.length > REVIEW_BOUNDS.threads) out.push(`threads: ${threads.length} is over ${REVIEW_BOUNDS.threads}; ui.review shows the first ${REVIEW_BOUNDS.threads}`);
+  const ids = new Set<unknown>();
+  threads.forEach((t, i) => {
+    out.push(...reviewThreadProblems(t).map((p) => `threads[${i}]: ${p}`));
+    const id = (t as { id?: unknown } | null)?.id;
+    if (ids.has(id)) out.push(`threads[${i}]: id ${String(id)} repeats`);
+    ids.add(id);
+  });
+  return out;
+}
+
+/** Expands the compact forms in test/fixtures/review/cases.json: "<N x c>" strings and {repeat: {count, of, idPrefix}} lists. */
+export function expandReviewCase(value: unknown): unknown {
+  if (typeof value === "string") {
+    const m = /^<(\d+) x (.)>$/u.exec(value);
+    return m ? m[2]!.repeat(Number(m[1])) : value;
+  }
+  if (Array.isArray(value)) return value.map(expandReviewCase);
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expandReviewCase(v)]));
+  return value;
+}
+export function reviewCaseValue(c: { value?: unknown; repeat?: { count: number; of: unknown; idPrefix: string } }): unknown {
+  if (c.repeat) return Array.from({ length: c.repeat.count }, (_, i) => ({ ...(expandReviewCase(c.repeat!.of) as object), id: `${c.repeat!.idPrefix}${i}` }));
+  return expandReviewCase(c.value);
+}
+
+/** Registers the api 1 conformance suite for a plugin under bun:test. */
+export function registerConsoleConformance(plugin: ConsolePlugin, options: ConformanceOptions = {}): void {
+  const tool = plugin.manifest?.tool ?? "plugin";
+  describe(`console conformance: ${tool}`, () => {
+    let provider: ConsoleProvider;
+    beforeAll(async () => {
+      const home = options.home ?? mkdtempSync(join(tmpdir(), "acon-conf-"));
+      provider = await withTimeout(plugin.open({ home, log: () => {}, features: [...CONSOLE_FEATURES] }), 5_000, "open()");
+    });
+    afterAll(async () => { await provider?.close?.(); });
+
+    test("manifest is valid JSON-serializable data", () => {
+      expect(manifestProblems(plugin.manifest)).toEqual([]);
+      expect(() => JSON.stringify(plugin.manifest)).not.toThrow();
+    });
+    test("open() resolves to a provider", () => expect(providerProblems(provider)).toEqual([]));
+    test("every panel answers a snapshot within 5 s", async () => {
+      for (const panel of plugin.manifest.panels) {
+        const result = await withTimeout(provider.snapshot({ after: 0, panel: panel.id }), 5_000, `snapshot ${panel.id}`);
+        expect(result && typeof result === "object" && !Array.isArray(result)).toBe(true);
+      }
+    });
+    if (plugin.manifest.capabilities?.inbox) test("inbox items have the InboxItem shape", async () => {
+      const result = await provider.snapshot({ after: 0, panel: "inbox" });
+      expect(Array.isArray(result.items)).toBe(true);
+      for (const item of result.items as unknown[]) expect(inboxItemProblems(item)).toEqual([]);
+    });
+    if (plugin.manifest.capabilities?.inbox) test("a console without features gets no result items or verb forms", async () => {
+      // An older console (no ConsoleContext.features) reports both as malformed; a plugin must check the features.
+      const plain = await withTimeout(plugin.open({ home: options.home ?? mkdtempSync(join(tmpdir(), "acon-conf-")), log: () => {} }), 5_000, "open()");
+      try {
+        const result = await plain.snapshot({ after: 0, panel: "inbox" });
+        const items = (Array.isArray(result.items) ? result.items : []) as { id?: unknown; group?: unknown; verbs?: { form?: unknown }[] }[];
+        expect(items.filter((i) => i.group === "result" || i.verbs?.some((v) => v.form !== undefined)).map((i) => String(i.id))).toEqual([]);
+      } finally { await plain.close?.(); }
+    });
+    if (plugin.manifest.capabilities?.inbox) test("inbox at is stable across snapshots", async () => {
+      // Copy before the next call: a provider may reuse and mutate the same item objects.
+      const first = structuredClone(await provider.snapshot({ after: 0, panel: "inbox" }));
+      await Bun.sleep(50);
+      const second = await provider.snapshot({ after: 0, panel: "inbox" });
+      expect(stableAtProblems(first.items as unknown[], second.items as unknown[])).toEqual([]);
+    });
+    if (plugin.manifest.capabilities?.search) test("search answers hits and total", async () => {
+      const result = await provider.snapshot({ after: 0, panel: "search", q: "a", limit: 10 });
+      expect(Array.isArray(result.hits)).toBe(true);
+      expect(typeof result.total).toBe("number");
+    });
+    if (plugin.manifest.capabilities?.space) test("space answers a public scene within 5 s", async () => {
+      const result = await withTimeout(provider.snapshot({ after: 0, panel: "space" }), 5_000, "space snapshot");
+      expect(spaceSceneProblems(result.scene)).toEqual([]);
+    });
+    test("asset, when present, answers null for an unknown id within 5 s", async () => {
+      if (typeof provider.asset !== "function") return;
+      const result = await withTimeout(provider.asset({ id: "acon-conformance-unknown" }), 5_000, "asset");
+      expect(result).toBeNull();
+    });
+    for (const id of options.assets ?? []) test(`asset ${id} is a served type with bytes and a name`, async () => {
+      expect(typeof provider.asset).toBe("function");
+      const result = await withTimeout(provider.asset!({ id }), 5_000, `asset ${id}`);
+      expect(assetResultProblems(result)).toEqual([]);
+      expect(ASSET_TYPES.has(result!.mime)).toBe(true);
+    });
+    test("an unknown action answers ok: false", async () => {
+      const result = await provider.action({ action: "acon-conformance-unknown" }, META);
+      expect(result.ok).toBe(false);
+    });
+    for (const input of options.destructive ?? []) test(`${input.action} needs confirmation`, async () => {
+      const result = await provider.action(input, META);
+      expect(result.ok).toBe(false);
+      expect("needsConfirm" in result && result.needsConfirm).toBe(true);
+      if ("needsConfirm" in result) {
+        expect(typeof result.fingerprint === "string" && result.fingerprint.length > 0).toBe(true);
+        expect(Array.isArray(result.preview)).toBe(true);
+      }
+    });
+    test("panel.js is an ES module with a default export", () => {
+      const scan = new Bun.Transpiler({ loader: "js" }).scan(provider.assets.js);
+      expect(scan.exports).toContain("default");
+    });
+    test("panel css loads nothing remote", () => {
+      expect(/@import|url\(\s*["']?(https?:)?\/\//i.test(provider.assets.css ?? "")).toBe(false);
+    });
+  });
+}

package/src/contract.ts

@@ -0,0 +1,276 @@
+/// <reference lib="dom" />
+/**
+ * Console plugin contract, api 1. Changes are additive only.
+ * Plan of record: entelecheia/ai-workspace#60 §2.3; UX additions: STAIxBWLB/vault-mem#48.
+ */
+
+export const CONSOLE_API = 1 as const;
+/** The api range this console speaks (#26). A plugin loads when its [apiMin, apiMax] overlaps it. */
+export const CONSOLE_API_MIN = 1;
+export const CONSOLE_API_MAX = 1;
+export const TOOL_ID = /^[a-z][a-z0-9-]{1,15}$/;
+export const PANEL_ID = /^[a-z][a-z0-9-]{0,31}$/;
+export const ACTION_ID = /^[a-z][a-z0-9_.:-]{0,63}$/;
+
+export interface ConsolePanelManifest {
+  api: 1;
+  /** The api range the plugin works with; each defaults to `api` (#26). */
+  apiMin?: number;
+  apiMax?: number;
+  tool: string;
+  version: string;
+  title: string;
+  /** Area icon name the shell knows (agents, memory, vault, ...); unknown names fall back to a generic glyph. */
+  icon?: string;
+  panels: { id: string; title: string; icon?: string; order?: number }[];
+  /** Palette entries; each runs action({...input, action}) through the same confirm path as a verb. */
+  commands?: ConsoleCommand[];
+  /** Poll interval for the visible panel; the shell clamps it to 2-60 s. */
+  pollMs?: number;
+  capabilities?: {
+    actions?: string[];
+    confirm?: boolean;
+    multiProject?: boolean;
+    /** snapshot({panel: "inbox", after}) returns {items: InboxItem[]}. */
+    inbox?: boolean;
+    /** snapshot({panel: "search", q, limit}) returns {hits: SearchHit[], total}. */
+    search?: boolean;
+    /** snapshot({panel: "space", after}) returns {scene: SpaceScene}, public fields only. */
+    space?: boolean;
+  };
+}
+
+export interface ConsoleCommand {
+  id: string;
+  title: string;
+  hint?: string;
+  action: string;
+  /** Fixed action input; it may not set action, confirmed, fingerprint or confirmToken. */
+  input?: Record<string, unknown>;
+}
+
+export interface ConsoleContext {
+  /** Family home ($AGENTHUB_HOME or ~/.agenthub). */
+  home: string;
+  log(line: string): void;
+  /**
+   * What this console renders beyond api 1's base (#27); set by the console, absent in older consoles. Send verb
+   * `form`s only with "inbox.form" and `result` items only with "inbox.result"; "action.meta" means action() gets `meta`.
+   */
+  features?: readonly string[];
+}
+
+/** Features this console advertises in ConsoleContext.features. */
+export const CONSOLE_FEATURES = ["inbox.form", "inbox.result", "action.meta"] as const;
+
+/** Who acted, built by the console from the verified session; the page cannot set it (#27). */
+export interface ActionMeta {
+  /** "local" under `acon ui`; under `acon serve` "access:<subject>", "bearer" or "loopback", as authenticated. */
+  identity: string;
+  node: string;
+  via: "console";
+}
+
+export interface ConsolePlugin {
+  manifest: ConsolePanelManifest;
+  open(ctx: ConsoleContext): Promise<ConsoleProvider>;
+}
+
+export interface ConsoleProvider {
+  /** panel.js is an ES module: `export default (host) => ({ show(panelId, params), hide(), destroy() })`. */
+  assets: { js: string; css?: string };
+  snapshot(input: { after: number; panel: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** `meta` is present when the console advertises "action.meta"; tools use it as evidence of who acted, under their own rules. */
+  action(input: { action: string; confirmed?: true; fingerprint?: string } & Record<string, unknown>, meta?: ActionMeta): Promise<ActionResult>;
+  /** Optional file for GET /p/<tool>/asset?id=; null when the id is unknown. Types: see README "Plugin assets". */
+  asset?(input: { id: string }): Promise<{ bytes: Uint8Array; mime: string; name: string } | null>;
+  close?(): Promise<void>;
+}
+
+export interface Change { op: "create" | "modify" | "delete" | "log"; target: string; note?: string }
+
+export type ActionResult =
+  | ({ ok: true; message?: string; undo?: { action: string } & Record<string, unknown> } & Record<string, unknown>)
+  | { ok: false; error: string; unconfirmed?: true }
+  | {
+      ok: false;
+      needsConfirm: true;
+      preview: string[];
+      fingerprint: string;
+      /** Verb shown on the confirm button ("Promote note"). */
+      verb?: string;
+      changes?: Change[];
+      warnings?: string[];
+      /** Authority-raising settings: the person types this text to confirm. */
+      confirmText?: string;
+    };
+
+/** "result" needs the "inbox.result" feature (#27); an older console reports it as malformed. */
+export type InboxGroup = "decision" | "review" | "result" | "candidate" | "alert";
+export type Tone = "ok" | "warn" | "err" | "neutral";
+
+export interface InboxItem {
+  id: string;
+  group: InboxGroup;
+  kind: string;
+  title: string;
+  detail?: string;
+  actor?: string;
+  project?: string;
+  /** ISO time the item started waiting. Keep it stable across snapshots: snooze and oldest-first order key on it. */
+  at: string;
+  chip?: { text: string; tone: Tone };
+  /** With `reason`, the shell asks for a reason and sends it as `reason` in the action input; "required" refuses an empty one. */
+  verbs: InboxVerb[];
+  link: { panel: string; params?: Record<string, string> };
+  /**
+   * For `result` items: the shell runs action({action, id, seenAt}) once per page session after the result body was
+   * in view for 1 s in a focused, visible window, and with `explicit: true` from "Mark all read".
+   */
+  seen?: { action: string };
+}
+
+export interface InboxVerb {
+  id: string; label: string; primary?: boolean; destructive?: boolean; reason?: "optional" | "required";
+  /** Choice questions (needs "inbox.form"); submit sends action({action: id, id: item.id, answers}). */
+  form?: VerbForm;
+}
+
+/** Bounds: 1-4 questions, 2-8 options, label <= 80, description <= 240, prompt <= 1000, other.maxLength <= 1000 (500). */
+export interface VerbForm {
+  questions: {
+    id: string; header?: string; prompt: string;
+    options: { id: string; label: string; description?: string }[];
+    multiple?: boolean;
+    other?: { label?: string; maxLength?: number };
+  }[];
+}
+
+/** Answers by question id: chosen option ids, and the "Other" text when given. */
+export type InboxAnswers = Record<string, { selected: string[]; other?: string }>;
+
+export interface SearchHit {
+  id: string;
+  kind: string;
+  title: string;
+  detail?: string;
+  at?: string;
+  link: { panel: string; params?: Record<string, string> };
+}
+
+/** Public collaboration facts, never message bodies, task details, paths or symbols. */
+export interface SpaceScene {
+  actors: {
+    id: string; name: string; state: "idle" | "working" | "waiting" | "blocked" | "away";
+    pet?: string; card?: string;
+    marks?: { kind: "approval" | "inbox" | "paused" | "mode"; text: string }[];
+    link: { panel: string; params?: Record<string, string> };
+  }[];
+  zones: { id: string; title: string; kind?: "queue" | "work" | "review" | "done"; count: number }[];
+  cards: {
+    id: string; title: string; zone: string; owner?: string; tone?: Tone;
+    link: { panel: string; params?: Record<string, string> };
+  }[];
+  links?: { kind: "message" | "overlap" | "conflict" | "cohort"; from: string; to: string; label?: string; at?: string }[];
+}
+
+/** A ui.table column. Cells render as text; `number` and `percent` format numeric cells, and `percent` expects percent units (38.5, not 0.385). */
+export interface TableColumn { key: string; label: string; align?: "start" | "end"; format?: "text" | "number" | "percent" }
+
+/** Where a review comment points. The kit creates lineRange, textQuote and diffHunk; it only displays the others. */
+export type ReviewSelector =
+  | { kind: "lineRange"; startLine: number; endLine: number }
+  | { kind: "textQuote"; exact: string; prefix: string; suffix: string }
+  | { kind: "diffHunk"; hunkHeader: string }
+  | { kind: "structural"; scheme: string; ref: string }
+  | { kind: "region"; x: number; y: number; width: number; height: number; page?: number };
+/**
+ * A review anchor, stored unchanged by the owning tool. `contentHash` is the lowercase hex sha256 of the text the
+ * anchor was made against: the projected text when `projection` is set, else the raw file bytes.
+ * Bounds: exact <= 2000 chars, prefix/suffix <= 64, 1-4 selectors. Shared cases: test/fixtures/review/cases.json.
+ */
+export interface ReviewAnchor {
+  path: string;
+  side?: "base" | "head";
+  contentHash?: string;
+  projection?: { name: string; version: string };
+  selectors: ReviewSelector[];
+}
+/** One comment thread on an anchor; body <= 4000 chars, at most 200 threads per view. */
+export interface ReviewThread { id: string; anchor: ReviewAnchor; body: string; author: string; at: string; state?: "open" | "resolved" }
+/** The document under review: plain text, prose (paragraphs split on blank lines, Markdown shown as source) or a unified diff. */
+export type ReviewDoc =
+  | { kind: "text" | "prose"; path: string; text: string; contentHash: string; projection?: { name: string; version: string } }
+  | { kind: "diff"; path: string; unified: string; contentHash: string };
+/** One placement result reported by ui.review; the tool's stored anchor stays the authority. */
+export interface ReviewPlacement { threadId: string; placed: boolean; via: "hash" | "quote" | null }
+
+/** One side of a before/after visual: text, or this plugin's asset id (#24) with alt text. */
+export type VisualSide = { text: string } | { asset: string; alt: string };
+/**
+ * A visual a plugin shows with ui.visual. Mermaid renders only in a sandboxed frame; tables use ui.table; asset
+ * sides use ui.img. Bounds: mermaid source <= 20 KB; comparison 2-6 options with at most 10 pros and 10 cons each.
+ */
+export type VisualPayload =
+  | { kind: "mermaid"; source: string; title?: string }
+  | { kind: "comparison"; title?: string; options: { title: string; summary?: string; pros?: string[]; cons?: string[]; recommended?: boolean }[] }
+  | { kind: "table"; caption?: string; columns: TableColumn[]; rows: Record<string, string | number>[] }
+  | { kind: "beforeAfter"; caption?: string; before: VisualSide; after: VisualSide };
+
+/** Text-only DOM kit supplied by the shell. Classes and tokens are documented in README. */
+export interface ConsoleUi {
+  h(tag: string, props?: Record<string, unknown>, ...kids: (Node | string | null | false)[]): HTMLElement;
+  rows<T>(items: T[], render: (item: T) => HTMLElement): HTMLElement | null;
+  row(o: { title: string; sub?: string; onOpen?: () => void; chip?: { text: string; tone?: Tone }; verbs?: HTMLElement[] }): HTMLElement;
+  empty(title: string, hint?: string): HTMLElement;
+  chip(text: string, tone?: Tone): HTMLElement;
+  /** A `button.btn` with `type="button"`; `tone` adds the `primary` or `danger` modifier. */
+  button(label: string, onClick: () => void, o?: { tone?: "primary" | "danger"; disabled?: boolean }): HTMLButtonElement;
+  /** `err` is announced assertively (`role="alert"`); other tones are polite (`role="status"`). */
+  notice(text: string, tone?: Tone): HTMLElement;
+  form(fields: { name: string; label: string; required?: boolean; value?: string }[], submit: { label: string; primary?: boolean }, onSubmit: (values: Record<string, string>) => void): HTMLFormElement;
+  detail(o: {
+    kind: string; title: string; state?: { text: string; tone?: Tone }; whoseMove?: "you" | "agent";
+    actions?: HTMLElement[]; summary?: string; provenance?: { label: string; value: string; at?: string }[];
+    sections?: { title: string; body: Node | string; open?: boolean }[]; footer?: string[];
+  }): HTMLElement;
+  /** At most 500 rows and 12 columns; extra input is cut with a notice. Sortable unless `sortable: false`. */
+  table(o: { columns: TableColumn[]; rows: Record<string, string | number>[]; caption?: string; sortable?: boolean }): HTMLElement;
+  /** Horizontal bars with an optional target marker per item; at most 50 items. */
+  bars(o: { items: { label: string; value: number; target?: number }[]; max?: number; caption: string }): HTMLElement;
+  /** A small line of the last 365 values at most. */
+  spark(o: { values: number[]; caption: string }): HTMLElement;
+  /** An image of this plugin's asset `id` (PNG or JPEG). Only asset ids are accepted, never URLs. */
+  img(o: { asset: string; alt: string }): HTMLElement;
+  /** A same-origin frame of this plugin's asset `id`, for PDF and text. */
+  frame(o: { asset: string; title: string }): HTMLElement;
+  /** A link to this plugin's asset or to one of its panels; any other target throws TypeError. */
+  link(to: { asset: string } | { panel: string; params?: Record<string, string> }, text: string): HTMLElement;
+  /** Line-numbered review of a text, prose or diff document: select a range, comment on it, see placed and unplaced threads. */
+  review(o: {
+    doc: ReviewDoc; threads: ReviewThread[];
+    onComment(c: { anchor: ReviewAnchor; body: string }): void | Promise<unknown>;
+    onPlacement?(results: ReviewPlacement[]): void;
+  }): HTMLElement;
+  /** A diagram (sandboxed Mermaid frame), comparison cards, a table or a before/after pair; failures show the source. */
+  visual(payload: VisualPayload): HTMLElement;
+}
+
+/** Browser-side host each panel module receives. Declared for panel authors; the shell implements it. */
+export interface ConsoleHost {
+  tool: string;
+  node: string;
+  mount: HTMLElement;
+  ui: ConsoleUi;
+  theme: { mode: "light" | "dark"; tokens: Record<string, string> };
+  snapshot(extra?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  action(input: { action: string } & Record<string, unknown>): Promise<ActionResult | ({ ok: true } & Record<string, unknown>)>;
+  navigate(tool: string, panel: string, params?: Record<string, string>): void;
+  onSnapshot(cb: (snapshot: Record<string, unknown>) => void): void;
+  onTheme(cb: (theme: ConsoleHost["theme"]) => void): void;
+  toast(text: string, options?: { undo?: () => void }): void;
+  sheet: { open(title: string): HTMLElement; close(): void };
+}
+
+/** Manifest file written by a tool's setup under $AGENTHUB_HOME/console/plugins/<tool>.json. */
+export interface PluginManifestFile { api: 1; tool: string; module: string; sha256: string }