@sigrun/sigrun 0.1.5 → 0.2.0

package/dist/harness/agent-env.js

@@ -0,0 +1,62 @@
+/**
+ * The agent shell environment (multi-user spec §8, the env-leak fix).
+ *
+ * pi-durable's `NodeExecutionEnv` runs commands with `{...process.env,
+ * ...shellEnv, ...options.env}` unless a call passes `inheritEnv: false`,
+ * and its bash tool always passes `inheritEnv: true`. So without this,
+ * an agent's `env` prints sigrun's own environment: `SIGRUN_API_TOKEN`,
+ * `SIGRUN_PROXY_SECRET`, and provider keys. `shellEnv` cannot fix it
+ * (it merges over `process.env`, it never subtracts), so
+ * {@link AgentExecutionEnv} forces every `exec` onto an allowlist built
+ * from sigrun's environment, plus whatever the caller set explicitly.
+ *
+ * The allowlist is the spec's list plus two variables existing installs
+ * depend on:
+ * - `NPM_CONFIG_CACHE`: the image runs with a read-only root filesystem
+ *   and points npm's cache at `/cache/npm`; without it `npm install` in
+ *   an agent shell fails writing `~/.npm`.
+ * - `SSH_AUTH_SOCK`: a socket path, not a secret; on a single-user
+ *   workstation it is how the agent's `git push` reaches the operator's
+ *   ssh-agent. The multi-user jail (spec §9) must not pass it to other
+ *   users' workers.
+ */
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+/** Variables copied from sigrun's environment into every agent shell. */
+export const AGENT_ENV_KEYS = [
+    "PATH",
+    "HOME",
+    "TMPDIR",
+    "LANG",
+    "TZ",
+    "TERM",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "NPM_CONFIG_CACHE",
+    "SSH_AUTH_SOCK",
+];
+/** Locale variables (`LC_ALL`, `LC_CTYPE`, …) pass through by prefix. */
+const AGENT_ENV_PREFIXES = ["LC_"];
+/** The allowlisted subset of `source` (defined values only). */
+export function agentEnv(source = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (AGENT_ENV_KEYS.includes(key) ||
+            AGENT_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Upstream's local env with every command confined to {@link agentEnv}
+ * plus the call's own `env`. `inheritEnv` is overridden whatever the
+ * caller asked for: that flag is how the leak happens.
+ */
+export class AgentExecutionEnv extends NodeExecutionEnv {
+    exec(command, options, context) {
+        return super.exec(command, { ...options, inheritEnv: false, env: { ...agentEnv(), ...options?.env } }, context);
+    }
+}

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