@sigrun/sigrun 0.1.6 → 0.2.1

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],
+});