@sigrun/sigrun 0.1.6 → 0.2.0

package/dist/harness/ambient.js

@@ -1,8 +1,9 @@
 /**
- * The ambient seam (spec: docs/approval-ux-seams.md, "Ambient surfaces"):
- * core-owned, channel-neutral records for persistent read-mostly state —
- * statusline slots and panel widgets — written by extensions through the
- * host context and rendered by channels generically.
+ * The ambient seam (spec: docs/approval-ux-seams.md, "Ambient surfaces";
+ * the block mapping: UI-blocks design §9.2): core-owned,
+ * channel-neutral records for persistent read-mostly state — statusline
+ * slots and panel widgets — written by extensions through the host
+ * context and rendered by channels generically.
  *
  * SPLIT (build-and-webui Task 1): the canonical TYPE declarations live in
  * the `@sigrun/shared` package (`shared/src/ambient.ts` — the records ride
@@ -16,10 +17,22 @@
  * not silent composition — the pi-zentui chrome-skin lesson).
  *
  * Layering mirrors the interaction seam: strict envelope (key, place,
- * budget, refresh, expires) around a body composed only from the closed
- * ambient primitives (line, rows, gauge, ledger), with opaque `details`.
+ * budget, refresh, expires) around a block-tree body (placement
+ * `ambient`; `status`/`footer` allow one line), with opaque `details`.
+ * Legacy-shaped bodies FAIL with paths (ruling 16).
  */
 import { defineDoc, defineDocFamily } from "@earendil-works/pi-durable";
+import { validateTree } from "../blocks/validate.js";
+/**
+ * Narrow a stored record to the public wire record. SAFETY: the two
+ * shapes are identical at runtime — a stored body passed `validateTree`
+ * (placement `ambient`) at write time, and a validated tree IS the JSON
+ * the mirror describes; the cast only restores the type-level naming
+ * `JsonObject`-erasure removed.
+ */
+export function asAmbientRecord(value) {
+    return value;
+}
 /**
  * The ambient record family: one record per surface key, per conversation.
  * (Session-scoped statuslines that outlive one conversation are a v2
@@ -48,9 +61,12 @@ export const AmbientOwnersDoc = defineDoc({
 });
 const PLACES = new Set(["status", "footer", "panel"]);
 const OVERFLOWS = new Set(["drop", "wrap", "summarize"]);
-const FORMATS = new Set(["compact", "usd", "percent"]);
-const ZONES = new Set(["left", "middle", "right"]);
-/** Structural validation of one ambient record. Returns the error text or null. */
+/**
+ * Structural validation of one ambient record: the envelope's own checks,
+ * then the body tree through `validateTree({placement: "ambient"})` with
+ * the one-line rule for `status`/`footer` (§9.2). Returns the error text
+ * (with the tree paths) or null.
+ */
 export function validateAmbient(value) {
     if (typeof value !== "object" || value === null) {
         return "ambient record must be an object";
@@ -80,182 +96,20 @@ export function validateAmbient(value) {
     const body = r.body;
     if (body === undefined)
         return null; // an empty write clears the surface
-    if (typeof body !== "object" || body === null) {
-        return "body must be an object";
-    }
-    const b = body;
-    const known = new Set(["line", "rows", "gauge", "ledger"]);
-    const unknownKey = Object.keys(b).find((k) => !known.has(k));
-    if (unknownKey !== undefined) {
-        return `body.${unknownKey} is outside the closed primitives (move it to details)`;
-    }
-    if (b.line !== undefined) {
-        const problem = validateLine(b.line);
-        if (problem !== null)
-            return problem;
-    }
-    if (b.rows !== undefined) {
-        if (!Array.isArray(b.rows))
-            return "body.rows must be an array";
-        for (const row of b.rows) {
-            const problem = validateRow(row);
-            if (problem !== null)
-                return problem;
-        }
-    }
-    if (b.gauge !== undefined) {
-        const problem = validateGauge(b.gauge);
-        if (problem !== null)
-            return problem;
-    }
-    if (b.ledger !== undefined) {
-        if (!Array.isArray(b.ledger))
-            return "body.ledger must be an array";
-        for (const e of b.ledger) {
-            const problem = validateLedgerEntry(e);
-            if (problem !== null)
-                return problem;
-        }
-    }
-    return null;
-}
-function validateLine(value) {
-    if (typeof value !== "object" || value === null)
-        return "line must be an object";
-    const l = value;
-    if (l.text === undefined && l.segments === undefined) {
-        return "line needs text or segments";
-    }
-    if (l.text !== undefined && typeof l.text !== "string") {
-        return "line.text must be a string";
-    }
-    if (l.segments !== undefined) {
-        if (!Array.isArray(l.segments))
-            return "line.segments must be an array";
-        for (const s of l.segments) {
-            if (typeof s !== "object" || s === null)
-                return "segment must be an object";
-            const seg = s;
-            if (typeof seg.id !== "string" || seg.id.length === 0) {
-                return "segment.id must be a non-empty string";
-            }
-            if (typeof seg.text !== "string")
-                return "segment.text must be a string";
-            if (seg.place !== undefined && !ZONES.has(String(seg.place))) {
-                return `segment.place must be one of left|middle|right (got ${String(seg.place)})`;
-            }
-        }
-    }
-    return null;
-}
-function validateRow(value) {
-    if (typeof value !== "object" || value === null)
-        return "row must be an object";
-    const r = value;
-    if (typeof r.id !== "string" || r.id.length === 0) {
-        return "row.id must be a non-empty string";
-    }
-    if (typeof r.label !== "string")
-        return "row.label must be a string";
-    if (r.status !== undefined && typeof r.status !== "string") {
-        return "row.status must be a string";
-    }
-    if (r.severity !== undefined &&
-        r.severity !== 0 &&
-        r.severity !== 1 &&
-        r.severity !== 2) {
-        return "row.severity must be 0, 1, or 2";
-    }
-    if (r.quiet !== undefined && typeof r.quiet !== "boolean") {
-        return "row.quiet must be a boolean";
-    }
-    if (r.detail !== undefined && typeof r.detail !== "string") {
-        return "row.detail must be a string";
-    }
-    if (r.depth !== undefined && typeof r.depth !== "number") {
-        return "row.depth must be a number";
-    }
-    if (r.deps !== undefined && !Array.isArray(r.deps)) {
-        return "row.deps must be an array of ids";
-    }
-    if (Array.isArray(r.deps) && r.deps.some((d) => typeof d !== "string")) {
-        return "row.deps must be an array of ids";
-    }
-    if (r.spinnerLabel !== undefined && typeof r.spinnerLabel !== "string") {
-        return "row.spinnerLabel must be a string";
-    }
-    if (r.metrics !== undefined) {
-        const problem = validateMetrics(r.metrics);
-        if (problem !== null)
-            return problem;
-    }
-    return null;
-}
-function validateMetrics(value) {
-    if (typeof value !== "object" || value === null)
-        return "metrics must be an object";
-    const m = value;
-    for (const k of ["tokens", "cost", "current", "total", "completed"]) {
-        if (m[k] !== undefined && typeof m[k] !== "number") {
-            return `metrics.${k} must be a number`;
-        }
-    }
-    if (m.format !== undefined && !FORMATS.has(String(m.format))) {
-        return `metrics.format must be one of compact|usd|percent (got ${String(m.format)})`;
-    }
-    return null;
-}
-function validateGauge(value) {
-    if (typeof value !== "object" || value === null)
-        return "gauge must be an object";
-    const g = value;
-    if (typeof g.label !== "string")
-        return "gauge.label must be a string";
-    if (g.percent !== undefined && typeof g.percent !== "number") {
-        return "gauge.percent must be a number";
-    }
-    if (g.phase !== undefined && typeof g.phase !== "string") {
-        return "gauge.phase must be a string";
-    }
-    if (g.elapsedMs !== undefined && typeof g.elapsedMs !== "number") {
-        return "gauge.elapsedMs must be a number";
-    }
-    if (g.recentOutput !== undefined && !Array.isArray(g.recentOutput)) {
-        return "gauge.recentOutput must be an array of strings";
-    }
-    if (Array.isArray(g.recentOutput) && g.recentOutput.some((l) => typeof l !== "string")) {
-        return "gauge.recentOutput must be an array of strings";
-    }
-    if (g.checks !== undefined && !Array.isArray(g.checks)) {
-        return "gauge.checks must be row-shaped";
-    }
-    if (Array.isArray(g.checks)) {
-        for (const row of g.checks) {
-            const problem = validateRow(row);
-            if (problem !== null)
-                return `gauge.checks: ${problem}`;
-        }
-    }
-    return null;
-}
-function validateLedgerEntry(value) {
-    if (typeof value !== "object" || value === null)
-        return "ledger entry must be an object";
-    const e = value;
-    if (typeof e.id !== "string" || e.id.length === 0) {
-        return "ledger.id must be a non-empty string";
-    }
-    if (typeof e.at !== "number")
-        return "ledger.at must be a number";
-    if (typeof e.kind !== "string")
-        return "ledger.kind must be a string";
-    if (typeof e.summary !== "string")
-        return "ledger.summary must be a string";
-    if (e.detail !== undefined && !Array.isArray(e.detail)) {
-        return "ledger.detail must be an array of strings";
-    }
-    if (Array.isArray(e.detail) && e.detail.some((d) => typeof d !== "string")) {
-        return "ledger.detail must be an array of strings";
+    // Ruling 16 (no compatibility layer): legacy-shaped bodies (objects
+    // keyed line/rows/gauge/ledger rather than {v, root}) fail HERE, with
+    // the path — a tree is {v, root}.
+    const result = validateTree(body, {
+        placement: "ambient",
+        ambientPlace: r.place,
+    });
+    if (!result.ok) {
+        const first = result.errors[0];
+        if (first === undefined)
+            return "body must be a block tree";
+        // The tree-relative path joins the record's field ("body.root…")
+        // so the error names where the record is wrong, not just the tree.
+        return `body is not a valid ambient tree: body.${first.path} ${first.message}`;
     }
     return null;
 }

package/dist/harness/blocks/entries.js

@@ -0,0 +1,47 @@
+/**
+ * The chat-blocks entry kinds (UI-blocks U5 Task 1, spec §8.2 storage):
+ * typed pi-durable entries the transcript carries.
+ *
+ * - `sigrun.blocks` (`BlocksEntry`): one agent-authored block surface,
+ *   `{title, tree, data}` EXACTLY as `show_blocks` created it. It never
+ *   changes — the live state lives in the `sigrun.blocks.state` family
+ *   (state.ts); the entry is the immutable definition the channels
+ *   re-render from.
+ * - `sigrun.blocks.note` (`BlocksNoteEntry`): the §8.3 change note — a
+ *   `type: "write"` submission whose entry carries the note as a `model`
+ *   user message. Declared here so the kind token exists in one place;
+ *   the note WRITER is Task 3 (src/server/blocks/notes.ts).
+ * - `sigrun.blocks.answer` (`BlocksAnswerEntry`, Task 3): a block answer
+ *   as an input entry kind. Declared alongside for the same
+ *   one-place-ness; Task 3 owns its writer.
+ *
+ * Payload typing: `Tree`'s block interfaces carry no implicit index
+ * signatures, so the payload cannot satisfy pi-durable's
+ * `D extends JsonValue` on its own — `tree` is typed `Tree & JsonValue`
+ * (verified: a `Tree` literal satisfies the intersection), and the
+ * runtime object pi-durable stores is exactly the validated tree.
+ */
+import { defineEntry } from "@earendil-works/pi-durable";
+/** One agent-authored block surface in chat (spec §8.2): never changes. */
+export const BlocksEntry = defineEntry("sigrun.blocks");
+/**
+ * The §8.3 change note entry: `model` is `[UserMessage]` carrying the
+ * note text (Task 3 writes it before every turn admission). `data`
+ * carries the note's COVERAGE ({@link BlocksNoteData}): the durable
+ * artifact of which changes the admitted note names, so a deduped
+ * retry (pi-durable returns the existing submission, discarding the
+ * retried text) advances `notedThrough` only as far as the ADMITTED
+ * note covered — never past changes a later compute added but the
+ * admitted text never described.
+ *
+ * NOTE: `advance`'s element array is mutable-typed because pi-durable's
+ * `D extends JsonValue` constraint rejects `readonly` arrays; the
+ * stored value is still treated as immutable by the writer.
+ */
+export const BlocksNoteEntry = defineEntry("sigrun.blocks.note");
+/**
+ * A block answer as a user-turn entry (Task 3): `model` is `[UserMessage]`
+ * with the server-built answer projection; no payload — the answer's
+ * `{entryId, action, payload, state}` ride the submission record.
+ */
+export const BlocksAnswerEntry = defineEntry("sigrun.blocks.answer");

package/dist/harness/blocks/state.js

@@ -0,0 +1,58 @@
+/**
+ * The chat-block state family (UI-blocks U5 Task 1, spec §8.2): the live
+ * state of one `sigrun.blocks` entry, a conversation-scoped document
+ * family keyed by entry id.
+ *
+ * Shape `{rev, data, changes, notedThrough}`:
+ * - `rev` — the monotonic data revision (both agent `update_blocks` and
+ *   user edits advance it; every advance publishes `surface.changed`);
+ * - `data` — the CURRENT data (the entry's `data` at `show_blocks` time,
+ *   then whatever ops applied since);
+ * - `changes` — the user's `ChangeRecord`s (agent updates record NONE:
+ *   the agent made the change and already knows);
+ * - `notedThrough` — the highest `seq` already sent to the agent in a
+ *   §8.3 note. Records at or below it are trimmed once more than
+ *   {@link MAX_CHANGES} have accumulated (the trim runs on append).
+ *
+ * Fork semantics (ruling 19): `history: "latest", fork: "current"` —
+ * pi-durable copies the current document at fork creation, so the child
+ * gets the block's current `data`, `rev`, records and `notedThrough`,
+ * then diverges. Blocks created after the fork point copy too, but are
+ * never addressable in the child (their entry is not in its history).
+ */
+import { defineDocFamily } from "@earendil-works/pi-durable";
+/** The trim threshold (spec §8.2): trim at-or-below `notedThrough` once more than 50 accumulate. */
+export const MAX_CHANGES = 50;
+/** The `sigrun.blocks.state` family: one member per (conversation, entry id). */
+export const BlocksStateDoc = defineDocFamily({
+    kind: "sigrun.blocks.state",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "current",
+    family: true,
+    // The seed only shapes a first touch; every real member is created by
+    // show_blocks, which writes the full state in its append commit.
+    initial: () => ({ rev: 0, data: {}, changes: [], notedThrough: 0 }),
+});
+/**
+ * Read one block's state (committed). `undefined` when the conversation
+ * has no such member — the entry id is unknown here, or the block was
+ * never created in this conversation.
+ */
+export async function readBlocksState(harness, conversationId, entryId, ctx) {
+    return await harness.snapshot(BlocksStateDoc, conversationId, entryId, ctx);
+}
+/**
+ * Trim change records at or below `notedThrough` once more than
+ * {@link MAX_CHANGES} have accumulated (spec §8.2) — in the caller's
+ * commit, on the draft the append already holds.
+ */
+export function trimChanges(state) {
+    if (state.changes.length <= MAX_CHANGES)
+        return;
+    const kept = state.changes.filter((record) => record.seq > state.notedThrough);
+    // Keep the newest MAX_CHANGES of what remains (the trim is bounded, not
+    // a wholesale wipe): a surge of edits above notedThrough keeps its tail.
+    state.changes = kept.slice(Math.max(0, kept.length - MAX_CHANGES));
+}

package/dist/harness/blocks/tools.js

@@ -0,0 +1,274 @@
+/**
+ * The chat-blocks core tools (UI-blocks U5 Task 1, spec §8.1): the
+ * `sigrun.blocks` pi-durable extension installed by `openHarness` beside
+ * the coding/search tools, so EVERY agent has them.
+ *
+ * - `show_blocks {title, tree, data}` validates the tree against the
+ *   `chat` placement (§5.7: no `page` root, no `secret` fields; §4.5
+ *   limits 200 blocks / 256 KiB tree / 256 KiB data; handler names are
+ *   free labels in chat — no `handlers` set). Validation errors go back
+ *   to the model as the tool error, each naming its JSON path (§14.2).
+ *   On success it appends ONE immutable `sigrun.blocks` entry and seeds
+ *   the state family `{rev: 0, data, changes: [], notedThrough: 0}` in
+ *   the SAME commit; the tool result is the §14.3 text projection of the
+ *   tree and its initial data plus the `entryId`.
+ * - `update_blocks {entryId, ops}` applies `DataOp`s to the surface's
+ *   CURRENT data (spec §8.1's stale-index honesty: an op written against
+ *   old indexes applies to current data — the returned projection shows
+ *   the ACTUAL resulting order). It records NO change record (the agent
+ *   made the change), increments `rev`, publishes
+ *   `surface.changed {conversationId, entryId, rev}` through the publish
+ *   seam, and its result is the NEW projection. A `DataOpError` (a
+ *   missing path, a non-array where one is required) returns a tool
+ *   error naming the op index; a failed batch leaves no partial write
+ *   (the throw unwinds the commit before anything persisted). An entry id
+ *   from another conversation (or one this conversation cannot see) is
+ *   "no such block in this conversation".
+ *
+ * The publish seam (`subscribeChatSurfaceChanged`): the chat
+ * `surface.changed` wire shape joins `HostEventWire` in Task 2 (shared/
+ * views.ts), and the server binds the hub publish then. Until that
+ * bind, the seam carries the events to in-process listeners only — the
+ * default subscriber set is empty, so nothing is lost by not wiring it.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension, defineTool, } from "@earendil-works/pi-durable";
+import { applyOps, DataOpError, toText } from "@sigrun/shared/blocks";
+import { validateData, validateTree } from "../../blocks/validate.js";
+import { BlocksEntry } from "./entries.js";
+import { BlocksStateDoc } from "./state.js";
+/** The §14.3 projection width for what the model sees of its own blocks (spec §8.1). */
+export const PROJECTION_WIDTH = 100;
+/**
+ * The server locale for model-facing projections (spec §14.3: "the model
+ * projection always uses the server's locale"). No locale setting exists
+ * in config today; `en-CA` is the repo's projection convention (the
+ * jobs run-namer and the block-text snapshots both use it).
+ */
+export const PROJECTION_LOCALE = "en-CA";
+/**
+ * The tool-description sentence (spec §8.1, verbatim): it teaches the
+ * action kinds — silent saves, immediate submits, `turn: true` only when
+ * a reply is needed.
+ */
+const ACTION_SENTENCE = "Interactive elements save the user's edits silently; you'll receive a summary of edits at your next turn. A `submit` sends you the result immediately; set `turn: true` on a `move` or `edit` only if each one needs an immediate reply.";
+/** The publish seam's listener set (see `chatSurfaceChanged`). */
+const chatSurfaceChangedListeners = new Set();
+/**
+ * Publish one chat-surface change through the seam (spec §8.2's
+ * `surface.changed {conversation, entry, rev}`). The TOOL layer calls
+ * this after its state commit; the server (Task 2) subscribes and fans
+ * the event out to the watcher registry + hub. In-process subscribers
+ * see every event; a listener that throws is logged, never propagated
+ * into the tool.
+ */
+export function chatSurfaceChanged(event) {
+    for (const listener of chatSurfaceChangedListeners) {
+        try {
+            listener(event);
+        }
+        catch (error) {
+            console.error("blocks: surface.changed listener failed:", error);
+        }
+    }
+}
+/**
+ * Subscribe to chat-surface changes (the test seam and Task 2's server
+ * binding point). Returns the unsubscribe.
+ */
+export function subscribeChatSurfaceChanged(listener) {
+    chatSurfaceChangedListeners.add(listener);
+    return () => {
+        chatSurfaceChangedListeners.delete(listener);
+    };
+}
+/** A tool error: text content the model can read and recover from. */
+function toolError(message) {
+    return { output: [{ type: "text", text: message }], isError: true };
+}
+/** A plain-object check (the `data` arg arrives as `unknown`). */
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The show_blocks tool (spec §8.1). */
+export const showBlocksTool = defineTool({
+    name: "show_blocks",
+    description: "Show the user an interactive UI (tables, charts, forms, lists) in the conversation. " +
+        "The result is the plain-text projection of the surface plus its entryId; keep that entryId to update the surface later. " +
+        ACTION_SENTENCE,
+    parameters: Type.Object({
+        title: Type.String({
+            description: "The surface's title, shown in the channel's header.",
+        }),
+        tree: Type.Unknown({
+            description: "The block tree {v: 1, root: Block} — the chat subset (no page root, no secret fields; at most 200 blocks).",
+        }),
+        data: Type.Unknown({
+            description: "The initial data object the tree's bindings point into (a JSON object).",
+        }),
+    }),
+    async execute(args, api, context) {
+        // Validate first (§8.1): an invalid tree appends NOTHING. Handler
+        // names are free labels in chat — no `handlers` set.
+        const validation = validateTree(args.tree, { placement: "chat" });
+        if (!validation.ok) {
+            const lines = validation.errors.map((error) => `${error.path}: ${error.message}`);
+            return toolError(`show_blocks: the tree is invalid:\n${lines.join("\n")}`);
+        }
+        if (!isJsonObject(args.data)) {
+            return toolError("show_blocks: data must be a JSON object");
+        }
+        const data = args.data;
+        // The data limit (§4.5, chat row) — validateTree covers the tree;
+        // the data object gets its own check.
+        const dataCheck = validateData(data, "chat");
+        if (!dataCheck.ok) {
+            return toolError(`show_blocks: ${dataCheck.errors
+                .map((error) => `${error.path}: ${error.message}`)
+                .join("\n")}`);
+        }
+        const tree = validation.tree;
+        // One commit: append the immutable entry and seed the state family
+        // (spec §8.2) — a crash between the two cannot strand a block
+        // without state.
+        const entryId = await api.commit(async (tx) => {
+            const entry = await tx.appendEntry(BlocksEntry, api.conversationId, {
+                data: {
+                    title: args.title,
+                    tree: tree,
+                    data,
+                },
+            });
+            const state = await tx.doc(BlocksStateDoc, api.conversationId, String(entry.id), String(entry.id));
+            state.rev = 0;
+            state.data = data;
+            state.changes = [];
+            state.notedThrough = 0;
+            return entry.id;
+        }, context);
+        return {
+            output: [
+                {
+                    type: "text",
+                    text: `${toText(tree, data, {
+                        width: PROJECTION_WIDTH,
+                        locale: PROJECTION_LOCALE,
+                    })}\nentryId: ${String(entryId)}`,
+                },
+            ],
+        };
+    },
+});
+/** The update_blocks tool (spec §8.1). */
+export const updateBlocksTool = defineTool({
+    name: "update_blocks",
+    description: "Apply data ops (set/remove/insert/move) to one of this conversation's block surfaces (by its entryId) and see the surface's CURRENT text projection. " +
+        "Ops apply to current data — if the user has reordered things since you last looked, index-based ops land on the new indexes. " +
+        ACTION_SENTENCE,
+    parameters: Type.Object({
+        entryId: Type.String({
+            description: "The entryId show_blocks returned.",
+        }),
+        ops: Type.Array(Type.Unknown(), {
+            description: "The DataOps to apply, in order.",
+        }),
+    }),
+    async execute(args, api, context) {
+        const parsed = parseEntryId(args.entryId);
+        if (parsed === undefined) {
+            return toolError(`update_blocks: entryId ${JSON.stringify(args.entryId)} is not one this conversation has`);
+        }
+        // Structural op validation (the schema is Unknown per element): each
+        // element must carry a known op tag; anything else is a recoverable
+        // model error naming the element's index.
+        const elements = args.ops;
+        // SAFETY: the schema admits unknown elements (typebox cannot express
+        // the DataOp union without duplicating it); the loop below validates
+        // each element's op tag, and applyOps re-validates every path — an
+        // element that is not a DataOp shape is a tool error, never a
+        // misapplied write.
+        const ops = elements;
+        for (let index = 0; index < elements.length; index++) {
+            const tag = elements[index]?.op;
+            if (tag !== "set" &&
+                tag !== "remove" &&
+                tag !== "insert" &&
+                tag !== "move") {
+                return toolError(`update_blocks: op ${index} is not a DataOp (expected {op: "set"|"remove"|"insert"|"move", …})`);
+            }
+        }
+        // The write: one commit reads the CURRENT state, applies the ops,
+        // bumps rev. The tree comes from the entry record — returned only
+        // when visible through THIS conversation (fork-aware), which is the
+        // same check that makes a foreign id "no such block".
+        let updated;
+        try {
+            updated = await api.commit(async (tx) => {
+                const page = await tx.scanEntries({
+                    conversationId: api.conversationId,
+                    minEntryId: parsed,
+                    maxEntryId: parsed,
+                }, 1, undefined);
+                const record = page.items[0];
+                if (record === undefined || !BlocksEntry.is(record)) {
+                    return undefined;
+                }
+                const state = await tx.doc(BlocksStateDoc, api.conversationId, String(parsed), String(parsed));
+                // applyOps throws DataOpError (naming the op index) on a bad
+                // path; the throw unwinds the commit BEFORE anything persists
+                // — a failed batch leaves no partial write.
+                state.data = applyOps(state.data, ops);
+                state.rev += 1;
+                // Snapshot to plain JSON: chord wraps draft values in tracking
+                // proxies that settle when the commit ends — returning the draft
+                // value itself would throw "Cannot use a settled overlay" when
+                // the projection reads it after commit.
+                return {
+                    tree: record.data.tree,
+                    data: JSON.parse(JSON.stringify(state.data)),
+                    rev: state.rev,
+                };
+            }, context);
+        }
+        catch (error) {
+            if (error instanceof DataOpError) {
+                return toolError(`update_blocks: op ${error.opIndex} failed: ${error.message}`);
+            }
+            throw error;
+        }
+        if (updated === undefined) {
+            return toolError(`update_blocks: no such block in this conversation (entryId ${JSON.stringify(args.entryId)})`);
+        }
+        // The change announcement (§8.2): surface.changed to watchers of
+        // this conversation's block.
+        chatSurfaceChanged({
+            type: "surface.changed",
+            conversationId: api.conversationId,
+            entryId: args.entryId,
+            rev: updated.rev,
+        });
+        return {
+            output: [
+                {
+                    type: "text",
+                    text: toText(updated.tree, updated.data, {
+                        width: PROJECTION_WIDTH,
+                        locale: PROJECTION_LOCALE,
+                    }),
+                },
+            ],
+        };
+    },
+});
+/** A numeric entry id (`EntryId` is a branded number; tool args are strings). */
+export function parseEntryId(value) {
+    if (!/^\d+$/.test(value))
+        return undefined;
+    const id = Number(value);
+    return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+}
+/** The core `sigrun.blocks` extension: the two tools, installed for every conversation. */
+export const blocksToolsExtension = defineExtension({
+    name: "sigrun.blocks",
+    tools: [showBlocksTool, updateBlocksTool],
+});