@sigrun/sigrun 0.7.0 → 0.9.0

package/dist/harness/complete.js

@@ -0,0 +1,127 @@
+/**
+ * `host.models.complete` (warden Task 4): one-shot completions for
+ * extensions — NO conversation, the auto-namer's `completeTitle` shape
+ * generalized into a host surface (skill-card generation is the first
+ * consumer).
+ *
+ * Model resolution (binding): an explicit `input.model` — ANY defined
+ * string, so a `\"\"` fails the parse rather than falling through — wins;
+ * else the live settings' `namingModel` when it is a string (`false`
+ * counts as unset); else the boot default model. The settings read is
+ * lazy (only when no explicit model). The chosen ref must be SERVED —
+ * an unserved model throws `UnservedModelError` naming it, never a
+ * silent fallback.
+ *
+ * Failure posture: throws on an unserved model, a timeout (default
+ * {@link DEFAULT_COMPLETE_TIMEOUT_MS} ms), a caller abort
+ * (`input.signal` — bound, not just forwarded: the race rejects even
+ * when the provider ignores its signal, and an already-aborted signal
+ * rejects before the request starts), or a `stopReason` of
+ * `error`/`aborted` — never resolves silently. The `Promise.race`, not
+ * the abort signal alone, bounds the wait: a provider that ignores the
+ * abort is abandoned without wedging the chain (the race keeps its
+ * late rejection handled).
+ */
+import { parseModelSpec } from "../config.js";
+import { requireServedModel } from "./providers/index.js";
+/** Default bound on one one-shot completion. */
+export const DEFAULT_COMPLETE_TIMEOUT_MS = 60_000;
+/**
+ * Run ONE one-shot completion against the resolved model and return its
+ * concatenated text parts (non-text parts skipped) plus the
+ * `provider/id` of the model actually used.
+ *
+ * @throws `UnservedModelError` naming the ref when no contributor serves
+ *   it; an `Error` naming the timeout when the call overruns
+ *   `timeoutMs`; an `Error` carrying the message's `errorMessage` (or
+ *   the stop reason) when the completion stops with `error`/`aborted`.
+ */
+export async function completeOnce(deps, input) {
+    const ref = input.model !== undefined
+        ? parseModelSpec(input.model, "model")
+        : (() => {
+            // Lazy settings read: an explicit model never touches the file.
+            const settings = deps.readSettings();
+            return typeof settings.namingModel === "string"
+                ? parseModelSpec(settings.namingModel, "namingModel")
+                : deps.defaultModel;
+        })();
+    const model = requireServedModel(deps.models, ref);
+    const key = `${ref.provider}/${ref.modelId}`;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_COMPLETE_TIMEOUT_MS;
+    const controller = new AbortController();
+    // A caller-side abort BOUNDS the wait: the race rejects promptly even
+    // when the provider ignores its signal (the request itself still gets
+    // the abort, best-effort cancellation of the underlying call). An
+    // already-aborted signal rejects before the request is started.
+    if (input.signal?.aborted) {
+        throw new Error("the completion was aborted by the caller");
+    }
+    let rejectCallerAbort;
+    const callerAborted = input.signal === undefined
+        ? undefined
+        : new Promise((_, reject) => {
+            rejectCallerAbort = reject;
+        });
+    const unlinkCaller = input.signal === undefined || rejectCallerAbort === undefined
+        ? undefined
+        : linkAbort(input.signal, controller, rejectCallerAbort);
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`the completion timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    let message;
+    try {
+        const request = deps.models.completeSimple(model, {
+            ...(input.systemPrompt === undefined
+                ? {}
+                : { systemPrompt: input.systemPrompt }),
+            messages: [
+                { role: "user", content: input.prompt, timestamp: Date.now() },
+            ],
+        }, { signal: controller.signal });
+        message = await Promise.race(callerAborted === undefined
+            ? [request, timedOut]
+            : [request, timedOut, callerAborted]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        unlinkCaller?.();
+    }
+    // An errored or aborted completion is a failure, not a result (the
+    // message may still carry text content alongside the error).
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+        throw new Error(`completion on ${key} stopped with ${message.stopReason}` +
+            (message.errorMessage === undefined
+                ? ""
+                : `: ${message.errorMessage}`));
+    }
+    return { text: textOf(message.content), model: key };
+}
+/** The text blocks of an assistant message, concatenated. */
+function textOf(content) {
+    return content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+}
+/**
+ * Abort `target` when `source` aborts and reject the race arm via
+ * `rejectRace` (the bounding arm: the race rejects even when the
+ * request ignores the abort). Callers must handle an already-aborted
+ * `source` BEFORE the request is started (completeOnce does). Returns
+ * the unlink.
+ */
+function linkAbort(source, target, rejectRace) {
+    const fail = () => {
+        target.abort();
+        rejectRace(new Error("the completion was aborted by the caller"));
+    };
+    source.addEventListener("abort", fail, { once: true });
+    return () => source.removeEventListener("abort", fail);
+}

package/dist/harness/decision-tool.js

@@ -0,0 +1,93 @@
+/**
+ * Warden Task 7: the core-owned `decision_evaluate` tool. The
+ * `sigrun.decisions` extension installs it when the boot-built registry
+ * lists ≥ 1 decision model — a no-provider boot carries no tool (the
+ * model is never offered a tool that can only refuse).
+ *
+ * Boot ordering: the registry builds AFTER the loader runs, while core
+ * extensions install BEFORE it. The extension therefore installs with
+ * an empty tool list (the placeholder), and boot RE-INSTALLS it with
+ * the tool once the registry exists (`registry.install` replaces a
+ * same-name extension in place) — the same late-fill seam the skills
+ * extension's collected-roots array uses, one level up.
+ *
+ * The execution reads `decisions.tool` from the LIVE settings per call
+ * (a settings write flips the tool without a restart) and evaluates
+ * through the boot-built registry with the core caller stamp `"sigrun"`.
+ * The result returns as JSON text for the model AND as
+ * `structuredOutput` under the declared schema (pi-durable rejects
+ * structuredOutput without one).
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension, defineTool } from "@earendil-works/pi-durable";
+import { validateDecisionRequest } from "./decisions.js";
+/** The core extension's reserved slug (boot.ts keeps the core slugs). */
+export const DECISIONS_EXTENSION_NAME = "sigrun.decisions";
+/** The tool's disabled refusal (the exact text the brief pins). */
+export const DECISION_TOOL_DISABLED = "decision_evaluate is disabled; set decisions.tool to true";
+function decisionError(message) {
+    return { output: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * The `decision_evaluate` tool registration, built against the LIVE
+ * slots: the boot-built registry and the settings store (the read is
+ * per execution, so `decisions.tool` and `decisionModel` apply without
+ * a restart).
+ */
+export function buildDecisionEvaluateTool(deps) {
+    return defineTool({
+        name: "decision_evaluate",
+        description: "Small structured judgments over a state: one judgment per question, answered by a " +
+            "dedicated decision model. Every question is a `noul` (a probability), a `choice` over " +
+            "labels, or a `score` over ordered levels — include a no-match option (for example " +
+            "\"none of the above\") in every choice so the judge is never forced.",
+        parameters: Type.Object({
+            state: Type.Union([Type.String(), Type.Unknown()], {
+                description: "The state the judgments run over (a string or any strict-JSON value).",
+            }),
+            questions: Type.Record(Type.String(), Type.Unknown(), {
+                description: "Question key → the question ({type, instructions?, criteria}).",
+            }),
+            model: Type.Optional(Type.String({
+                description: "A decision model as `provider/model`; the default resolves from settings.",
+            })),
+        }),
+        structuredOutputSchema: Type.Object({ ok: Type.Boolean() }, { additionalProperties: true }),
+        async execute(args) {
+            const enabled = deps.settings.read().decisions?.tool === true;
+            if (!enabled) {
+                return decisionError(DECISION_TOOL_DISABLED);
+            }
+            // Validate the shape BEFORE the registry (the registry validates
+            // again against the resolved model's limits — this keeps the
+            // refusal vocabulary identical for every caller).
+            const validation = validateDecisionRequest(args);
+            const model = typeof args.model === "string" ? args.model : undefined;
+            const result = validation.ok
+                ? await deps.decisions.evaluate("sigrun", validation.request, {
+                    ...(model === undefined ? {} : { model }),
+                })
+                : {
+                    ok: false,
+                    code: validation.code,
+                    error: `${validation.code} at ${validation.errors[0]?.path ?? ""}: ${validation.errors[0]?.message ?? "invalid"}`,
+                };
+            return {
+                output: [{ type: "text", text: JSON.stringify(result) }],
+                structuredOutput: result,
+            };
+        },
+    });
+}
+/**
+ * The `sigrun.decisions` core extension. `tools` empty = the boot-time
+ * placeholder (a no-provider boot KEEPS the placeholder — no tool);
+ * boot re-installs with `buildDecisionEvaluateTool` once the registry
+ * lists ≥ 1 decision model.
+ */
+export function createDecisionsExtension(tools = []) {
+    return defineExtension({
+        name: DECISIONS_EXTENSION_NAME,
+        tools: [...tools],
+    });
+}