@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/harness/providers/scheduler.js

@@ -0,0 +1,89 @@
+/**
+ * Core-owned refresh policy 2 (spec §"Core: refresh policy"): the
+ * interval scheduler. The boot refresh (T4, `refresh.ts`) populates
+ * every dynamic provider's catalog once at boot; THIS module keeps them
+ * current — ONE host-owned `setInterval` re-running `models.refresh()`
+ * with NO provider filter on a cadence, so an upstream roster change
+ * lands without a restart (and well inside the refresh-on-miss fallback
+ * at the submit call site).
+ *
+ * The cadence resolves at boot from the settings file's
+ * `server.providers.refreshIntervalMinutes` under the
+ * `SIGRUN_PROVIDER_REFRESH_MINUTES` env override, default 15 minutes;
+ * `0` disables the scheduler outright (no timer is created — the
+ * designed off switch, not an error).
+ *
+ * Lifecycle contract:
+ * - the timer is `unref()`ed — a running sigrun keeps the process alive,
+ *   the refresh cadence alone never does;
+ * - `stop()` clears the timer (idempotent); the deploy shutdown path
+ *   (`src/serve.ts`) calls it BEFORE the harness closes, alongside the
+ *   ordered shutdown;
+ * - a failed tick — per-provider failures in the refresh result
+ *   (`ModelsRefreshResult.errors`, the pi-ai contract: provider errors
+ *   are returned, not thrown), an abort, or an unexpected throw — logs
+ *   ONCE per outage, on the TRANSITION into failure. Consecutive
+ *   failures stay silent (the cadence IS the retry); a successful tick
+ *   resets the state so the next outage warns again. One warn per
+ *   episode, not one per tick.
+ */
+import { refreshReadinessSnapshot } from "./refresh.js";
+/**
+ * Start the interval refresh: one `unref()`ed `setInterval` re-running
+ * `models.refresh()` (every dynamic provider, network allowed —
+ * `refresh()` with no options is pi-ai's full refresh) every
+ * `intervalMinutes`. A tick's failures never reject and never stack
+ * retries — the next tick IS the retry; see the module docblock for
+ * the once-per-outage logging rule.
+ */
+export function startProviderRefresh(models, opts) {
+    if (!(opts.intervalMinutes > 0)) {
+        return { stop() { } };
+    }
+    const log = opts.log ?? console.warn;
+    // The outage latch: `true` while the current run of consecutive
+    // failures has already logged. Success resets it.
+    let inOutage = false;
+    const tick = async () => {
+        let failure;
+        try {
+            const result = await models.refresh();
+            if (result.aborted) {
+                failure = "aborted before completing";
+            }
+            else if (result.errors.size > 0) {
+                failure = [...result.errors]
+                    .map(([id, error]) => `${id} (${error instanceof Error ? error.message : String(error)})`)
+                    .join("; ");
+            }
+        }
+        catch (error) {
+            failure = error instanceof Error ? error.message : String(error);
+        }
+        // The readiness observation runs for EVERY completed tick — success
+        // or failure — so a provider that flips either way is observed; a
+        // tick that threw before refreshing holds the previous snapshot.
+        try {
+            opts.onReadinessChange?.((opts.snapshotReadiness ?? refreshReadinessSnapshot)(models));
+        }
+        catch (error) {
+            log(`provider readiness observation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (failure === undefined) {
+            inOutage = false;
+            return;
+        }
+        if (!inOutage) {
+            inOutage = true;
+            log(`provider interval refresh failed: ${failure} — ` +
+                `retrying on cadence (logging once per outage)`);
+        }
+    };
+    const timer = setInterval(() => void tick(), opts.intervalMinutes * 60_000);
+    timer.unref?.();
+    return {
+        stop() {
+            clearInterval(timer);
+        },
+    };
+}

package/dist/harness/registry.js

@@ -0,0 +1,9 @@
+/**
+ * Sigrun's extension registry.
+ *
+ * pi-durable's `createRegistry()` seeds the built-in task definitions
+ * (generation, tool, compaction) that `Harness.open` requires. Sigrun-owned
+ * extensions will be installed here in later tasks; every harness opened by
+ * `openHarness` shares the registry this module creates.
+ */
+export { createRegistry } from "@earendil-works/pi-durable";

package/dist/harness/reserved-sections.js

@@ -0,0 +1,24 @@
+/**
+ * The reserved core prompt-section keys (spec §6.5 R11).
+ *
+ * The prompt-section keys the core surfaces own (system-prompt Task 3).
+ * The registry itself permits duplicate section keys across extensions
+ * (last-writer-wins at render), so a loaded extension could silently
+ * replace a core surface. The loader therefore rejects the LOAD of any
+ * extension declaring one of these keys — a load-time quarantine, never
+ * a boot abort (src/harness/loader.ts) — while boot's post-install walk
+ * over `RESERVED_CORE_SECTION_OWNERS` (src/harness/boot.ts) stays as a
+ * core-only assertion that can fire only on a core bug.
+ *
+ * Lives in its own module (not boot.ts) so the loader can read the
+ * contract without importing boot's runtime graph; boot re-exports the
+ * constant for existing importers.
+ */
+export const RESERVED_CORE_SECTION_KEYS = [
+    "identity",
+    "persona",
+    "workspace-instructions",
+    "skills",
+    "tool-guidance",
+    "execution-guidance",
+];

package/dist/harness/seam-host.js

@@ -0,0 +1,239 @@
+/**
+ * The host context (spec: docs/approval-ux-seams.md, "What this asks of
+ * core"): the object sigrun hands an extension factory so the extension can
+ * use the interaction/ambient seams — and its scoped extension-stores
+ * handle (`stores`: secrets/settings get/set on its own section/file plus
+ * its own raw data/cache/state paths) — without importing anything from
+ * core.
+ *
+ * Factories run BEFORE `Harness.open` (spec §3 boot order), so the context
+ * binds the harness lazily: boot assigns `bindHarness` right after open,
+ * and every seam call awaits that assignment. A seam call that arrives
+ * before the harness exists waits — never a silent drop.
+ *
+ * Failure posture: every method throws `SeamError` on misuse (bad record,
+ * unowned key, unknown kind) — fail-loud, matching the loader's quarantine
+ * posture for shape violations. A throw inside a factory quarantines the
+ * extension; a throw later (tool execute) surfaces to the caller.
+ */
+import { AmbientDoc, AmbientOwnersDoc, validateAmbient, } from "./ambient.js";
+import { InteractionDoc, InteractionsIndexDoc, applyAnswer, indexPending, indexSettled, validateInteraction, } from "./interactions.js";
+import { scopedExtensionStores, } from "./stores.js";
+/** One seam violation. Name carries the surface ("interaction"/"ambient"). */
+export class SeamError extends Error {
+    surface;
+    constructor(surface, message) {
+        super(`${surface}: ${message}`);
+        this.surface = surface;
+        this.name = "SeamError";
+    }
+}
+/**
+ * Build the seam host for one extension. `kinds` gates writes: a record
+ * whose `kind`/`key` the extension never declared is rejected — the
+ * declaration is what channels use to inventory capabilities, so an
+ * undeclared write would silently falsify it. `sharedStores` is the
+ * boot-built store trio (one per boot, from the resolved roots); the
+ * host scopes it to its identity's slug — `rekey` re-scopes in place.
+ */
+export function createSeamHost(identity, kinds, bind, sharedStores) {
+    const interactionKinds = new Set(kinds.interaction ?? []);
+    const ambientKinds = new Set(kinds.ambient ?? []);
+    // The scoped stores view, keyed on the CURRENT identity — the same
+    // closed-over `let` pattern as `identity` itself: rekey re-points it
+    // and the `stores` getter below reads through the closure, so the
+    // factory-captured host object re-scopes IN PLACE (never a second
+    // host, never a stale view).
+    let stores = scopedExtensionStores(sharedStores, identity.name);
+    async function harness(context) {
+        const h = await bind.harness();
+        // The caller's context gates the wait: an aborted request/tool call
+        // unwinds instead of waiting forever for a harness that never opens.
+        context.abortSignal?.throwIfAborted();
+        return h;
+    }
+    // The server-provided host bridge (W5 Task 5): the conversation/
+    // identity/users/access surface binds LATER than the harness — the
+    // bridge only exists once `createServer` builds it — so the same
+    // lazy-promise discipline applies: every call awaits the harness
+    // assignment AND the bridge assignment, so a factory-body call waits
+    // (never a silent drop, never an early resolution before the server
+    // exists), and a call after the binding resolves immediately.
+    let bridgeReleased;
+    const bridgePromise = new Promise((resolve) => {
+        bridgeReleased = resolve;
+    });
+    const hostBridge = async () => {
+        await bind.harness();
+        return bridgePromise;
+    };
+    return {
+        get stores() {
+            return stores;
+        },
+        rekey(nextIdentity, nextKinds) {
+            // In place, by design: the factory already captured THIS object, so
+            // the reassign below is visible to every closure reading it and no
+            // second host instance ever exists. The stores view re-points to the
+            // rekeyed slug the same way — same host object, corrected scope.
+            identity = nextIdentity;
+            stores = scopedExtensionStores(sharedStores, nextIdentity.name);
+            interactionKinds.clear();
+            for (const kind of nextKinds.interaction ?? [])
+                interactionKinds.add(kind);
+            ambientKinds.clear();
+            for (const kind of nextKinds.ambient ?? [])
+                ambientKinds.add(kind);
+        },
+        async seedInteraction(conversationId, record, context) {
+            if (!interactionKinds.has(record.kind)) {
+                throw new SeamError("interaction", `kind ${JSON.stringify(record.kind)} is not declared by ${identity.name} (declare it in the factory result's interactionKinds)`);
+            }
+            const problem = validateInteraction(record);
+            if (problem !== null)
+                throw new SeamError("interaction", problem);
+            const h = await harness(context);
+            await h.commit(async (tx) => {
+                // Maintain the index in the SAME commit as the record.
+                const existing = await tx.doc(InteractionDoc, conversationId, record.callId, record.callId);
+                if (existing.status !== "pending")
+                    return; // first-write wins
+                Object.assign(existing, record);
+                const index = await tx.doc(InteractionsIndexDoc);
+                indexPending(index, conversationId, record.callId);
+            }, context);
+        },
+        async answerInteraction(conversationId, callId, answer, context) {
+            const h = await harness(context);
+            return await h.commit(async (tx) => {
+                const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
+                if (draft.status !== "pending")
+                    return false;
+                const applied = applyAnswer(draft, answer, "extension", Date.now());
+                if (applied) {
+                    const index = await tx.doc(InteractionsIndexDoc);
+                    indexSettled(index, conversationId, callId);
+                }
+                return applied;
+            }, context);
+        },
+        async settleInteraction(conversationId, callId, status, context) {
+            const h = await harness(context);
+            return await h.commit(async (tx) => {
+                const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
+                if (draft.status !== "pending")
+                    return false;
+                const mutable = draft;
+                mutable.status = status;
+                mutable.settledAt = Date.now();
+                const index = await tx.doc(InteractionsIndexDoc);
+                indexSettled(index, conversationId, callId);
+                return true;
+            }, context);
+        },
+        async snapshotInteraction(conversationId, callId, context) {
+            const h = await harness(context);
+            return await h.snapshot(InteractionDoc, conversationId, callId, context);
+        },
+        async setAmbient(conversationId, record, context) {
+            if (!ambientKinds.has(record.key)) {
+                throw new SeamError("ambient", `surface key ${JSON.stringify(record.key)} is not declared by ${identity.name} (declare it in the factory result's ambientKinds)`);
+            }
+            const h = await harness(context);
+            await h.commit(async (tx) => {
+                // Allocation: one owner per key. The claim happens in the same
+                // commit as the first write, so a race between two extensions
+                // serializes and the loser throws.
+                const owners = await tx.doc(AmbientOwnersDoc);
+                const owner = owners.owners[record.key];
+                if (owner === undefined) {
+                    const claimed = owners.owners;
+                    claimed[record.key] = identity.name;
+                }
+                else if (owner !== identity.name) {
+                    throw new SeamError("ambient", `key ${JSON.stringify(record.key)} is owned by ${owner}; ${identity.name} cannot write it`);
+                }
+                const draft = await tx.doc(AmbientDoc, conversationId, record.key, record.key);
+                const full = {
+                    ...record,
+                    owner: identity.name,
+                    expires: record.body === undefined ? draft.expires : "never",
+                    updatedAt: Date.now(),
+                };
+                const problem = validateAmbient(full);
+                if (problem !== null)
+                    throw new SeamError("ambient", problem);
+                Object.assign(draft, full);
+            }, context);
+        },
+        async clearAmbient(conversationId, key, context) {
+            if (!ambientKinds.has(key)) {
+                throw new SeamError("ambient", `surface key ${JSON.stringify(key)} is not declared by ${identity.name}`);
+            }
+            const h = await harness(context);
+            await h.commit(async (tx) => {
+                const draft = await tx.doc(AmbientDoc, conversationId, key, key);
+                // Empty replacement: body undefined, everything else refreshed.
+                const mutable = draft;
+                mutable.updatedAt = Date.now();
+                mutable.body = undefined;
+                mutable.details = undefined;
+            }, context);
+        },
+        // The host conversation/identity/users/access surface (W5 Task 5,
+        // spec §9.5/§9.7): each member awaits the harness + bridge bindings
+        // (the lazy discipline above) and delegates to the server bridge —
+        // the SAME code paths the HTTP routes run. `create` injects the
+        // source default: the CALLING extension's slug (identity.name — the
+        // re-keyed current slug, read at call time).
+        conversations: {
+            async create(opts = {}) {
+                const bridge = await hostBridge();
+                return bridge.conversations.create({
+                    ...(opts.owner === undefined ? {} : { owner: opts.owner }),
+                    ...(opts.sharing === undefined ? {} : { sharing: opts.sharing }),
+                    ...(opts.name === undefined ? {} : { name: opts.name }),
+                    // The source default: the CALLING extension's slug (spec §9.5).
+                    source: opts.source ?? identity.name,
+                });
+            },
+            async submit(id, input, opts) {
+                const bridge = await hostBridge();
+                return bridge.conversations.submit(id, input, opts);
+            },
+            async watch(id, listener) {
+                const bridge = await hostBridge();
+                return bridge.conversations.watch(id, listener);
+            },
+            async list(opts) {
+                const bridge = await hostBridge();
+                return bridge.conversations.list(opts);
+            },
+            async meta(id) {
+                const bridge = await hostBridge();
+                return bridge.conversations.meta(id);
+            },
+        },
+        users: {
+            async list() {
+                return (await hostBridge()).users.list();
+            },
+            async get(user) {
+                return (await hostBridge()).users.get(user);
+            },
+        },
+        access: {
+            async accessOf(principal, resource) {
+                return (await hostBridge()).access.accessOf(principal, resource);
+            },
+        },
+        identity: {
+            async actingUser(conversationId) {
+                return (await hostBridge()).identity.actingUser(conversationId);
+            },
+        },
+        bindBridge(bridge) {
+            bridgeReleased(bridge);
+        },
+    };
+}

package/dist/harness/sections/context-files.js

@@ -0,0 +1,78 @@
+/**
+ * Core context prompt sections: static `identity`, `persona` from
+ * `SOUL.md` (or the shipped `DEFAULT_PERSONA`), and
+ * `workspace-instructions` from `AGENTS.md` (spec §3 + system-prompt spec
+ * §Design).
+ *
+ * Both files are read through `PromptInput.env` — the same `ExecutionEnv`
+ * the harness builds per request — so the sections follow the workspace the
+ * conversation actually resolves without this module knowing which. The
+ * bare file names resolve against the env's `cwd`: the workspace root unless the
+ * conversation narrowed its working directory (`agent.cwd`, T3), in which
+ * case the convention follows that directory — the same cwd-anchored
+ * `AGENTS.md` convention pi itself uses, and the only anchor upstream's
+ * `FileSystem` offers (there is no workspace-root accessor; a path
+ * hard-coded here would break remote/container envs).
+ *
+ * A *missing* `AGENTS.md` is the designed empty case: `render` returns
+ * `undefined` and pi-durable omits the section from the request. A missing
+ * `SOUL.md` (or no env at all) is "absent persona file", not an empty
+ * persona: the shipped `DEFAULT_PERSONA` speaks instead, and a present
+ * `SOUL.md` — including an empty one — owns the section wholesale. Any
+ * other read failure is a real error and fails loud — render throws,
+ * upstream reports it and keeps the last shown text (verified:
+ * dist/harness/prompt.js renderSections).
+ */
+import { defineExtension, section } from "@earendil-works/pi-durable";
+/**
+ * Read one workspace-root context file for a prompt section render.
+ * Resolves `undefined` for the designed empty cases (no env, missing file).
+ */
+async function readContextFile(input, fileName, context) {
+    // Without an environment there is nothing to read: an empty section, not
+    // an error (upstream leaves `PromptInput.env` undefined when the harness
+    // opens without an `env` option).
+    const env = input.env;
+    if (env === undefined)
+        return undefined;
+    const result = await env.readTextFile(fileName, context);
+    if (result.ok)
+        return result.value;
+    if (result.error.code === "not_found")
+        return undefined;
+    throw new Error(`Failed to read ${fileName}: ${result.error.message}`, { cause: result.error });
+}
+/**
+ * The static `identity` section body: runtime facts only. No tool claims
+ * (the system prompt already declares the actually-offered tools per
+ * request) and no model name (it would re-emit this section on every
+ * mid-conversation model swap, defeating the minimal-patch design).
+ */
+export const IDENTITY_TEXT = "You are sigrun, an AI assistant running as a persistent server built on the pi-durable harness. Conversations are durable: they survive restarts and can span channels (web UI, terminal UI, HTTP API). Multiple conversations may be active at once; each is independent.";
+/**
+ * The persona sigrun ships when no `SOUL.md` exists. A present `SOUL.md`
+ * replaces it wholesale; the default is never merged in.
+ */
+export const DEFAULT_PERSONA = `You are Sigrun. You choose, and you say why — a valkyrie doesn't dither over the field. You have opinions and you give them straight: if a plan is bad, say it's bad and say what would make it good. Hedging is a way of lying politely.
+
+Match your reply to the weight of the ask. No filler openers, no restating the request, no narrating what the user can already see. When you don't know, say so and name what would settle it.
+
+Dry wit when it lands. Never forced, never at the user's expense — punch at the problem, not the person. Warmth is welcome; flattery is not.`;
+/**
+ * The context-files extension: static `identity`, `persona` from `SOUL.md`
+ * (defaulting to the shipped persona when the file is absent or there is
+ * no env), and `workspace-instructions` from `AGENTS.md`, read relative to
+ * the conversation env's cwd (the workspace root by default).
+ */
+export const contextFilesExtension = defineExtension({
+    name: "sigrun.context-files",
+    sections: [
+        section("identity", () => IDENTITY_TEXT),
+        section("persona", async (input, context) => 
+        // `??` covers both designed empty cases (not_found, no env); a
+        // successful read — including an empty file — owns the section
+        // wholesale. The throw path inside readContextFile propagates.
+        (await readContextFile(input, "SOUL.md", context)) ?? DEFAULT_PERSONA),
+        section("workspace-instructions", (input, context) => readContextFile(input, "AGENTS.md", context)),
+    ],
+});

package/dist/harness/sections/model-guidance.js

@@ -0,0 +1,77 @@
+/**
+ * Per-model-family prompt guidance (system-prompt spec §Design, model
+ * table): an ordered, first-match-wins table of name patterns with tool /
+ * execution guidance, plus the extension that renders each field as its
+ * own prompt section.
+ *
+ * Section renderers have no access to the `Models` catalog (`Agent` carries
+ * no `models` field), so the matcher keys off the resolved
+ * `${provider}/${modelId}` string alone — case-insensitive substring,
+ * first hit wins, `undefined` when nothing matches. `MODEL_GUIDANCE` match
+ * strings are lowercase by convention: matching lowercases the joined ref
+ * but not the table.
+ *
+ * The two fields are separate section keys (`tool-guidance`,
+ * `execution-guidance`) rather than one guidance blob so a matched→matched
+ * model swap that changes only one dimension patches by value — a few
+ * lines re-emitted instead of the whole blob. Both render `undefined` (the
+ * section is omitted from the request) for an unmatched model or an
+ * unset `agent.model`; that is the designed empty case, not an error.
+ *
+ * Boot installs this extension LAST, after `loadExtensions` and the memory
+ * section (Task 3): guidance sections appear and disappear with the
+ * matched model, and trailing placement keeps those transitions minimal
+ * patches instead of full prompt re-emits.
+ */
+import { defineExtension, section } from "@earendil-works/pi-durable";
+/**
+ * Ordered guidance table: first matching entry wins. Seeded conservative —
+ * the mechanism is the deliverable; entries accumulate with operational
+ * experience.
+ */
+export const MODEL_GUIDANCE = [
+    // Reasoning family: spend the thinking on planning and verification.
+    {
+        match: "kimi",
+        guidance: {
+            execution: "Think through the full plan before acting; verify the result before finalizing.",
+        },
+    },
+    // Reasoning family: spend the thinking on planning and verification.
+    {
+        match: "deepseek",
+        guidance: {
+            execution: "Think through the full plan before acting; verify the result before finalizing.",
+        },
+    },
+    // Known under-caller family: prefer checking over recollecting.
+    {
+        match: "qwen",
+        guidance: {
+            tool: "Prefer your tools over recollection when the answer is checkable on disk or in the environment.",
+        },
+    },
+];
+/**
+ * Resolve the first table entry whose pattern is a substring of the
+ * lowercased `${provider}/${modelId}`, or `undefined` when the ref is
+ * unset or nothing matches.
+ */
+export function matchGuidance(modelRef) {
+    if (modelRef === undefined)
+        return undefined;
+    const key = `${modelRef.provider}/${modelRef.modelId}`.toLowerCase();
+    return MODEL_GUIDANCE.find((entry) => key.includes(entry.match))?.guidance;
+}
+/**
+ * The model-guidance extension: `tool-guidance` and `execution-guidance`
+ * sections keyed on the request's resolved model, each rendering the
+ * matched entry's field or `undefined` (absent section).
+ */
+export const modelGuidanceExtension = defineExtension({
+    name: "sigrun.model-guidance",
+    sections: [
+        section("tool-guidance", (input) => matchGuidance(input.agent.model)?.tool),
+        section("execution-guidance", (input) => matchGuidance(input.agent.model)?.execution),
+    ],
+});