@sigrun/sigrun 0.7.0 → 0.9.0

package/dist/harness/decisions.js

@@ -0,0 +1,477 @@
+/**
+ * Warden Task 5: the decision-provider core — typebox schemas for the
+ * decision wire shape, request/answer validators, and the pure
+ * {@link buildDecisionRegistry} (fixture-testable; the loader/boot
+ * wiring lands in Task 6). The wire TYPES live in
+ * `@sigrun/shared/decisions`; the schemas live here because the shared
+ * leaf is import-free.
+ *
+ * `evaluate` NEVER throws: every failure is a `DecisionResult`
+ * `ok:false` with one of the spec's codes. Error text never carries the
+ * credential (scrubbed) nor the submitted request.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { Compile } from "typebox/compile";
+import { DECISION_MAX_BYTES, DECISION_MAX_QUESTIONS, } from "@sigrun/shared/decisions";
+// A strict-JSON value schema. `Type.Unknown()` leaves a node unchecked;
+// depth/self-reference aren't expressible without a recursive builder the
+// pi-ai Type mirror doesn't carry, so deep validation happens in
+// `assertJsonValue` below (the wire contract is strict JSON).
+const JsonValue = Type.Unknown();
+/** The depth/self-reference bound for {@link assertJsonValue}. */
+const JSON_MAX_DEPTH = 64;
+/**
+ * Throw unless `value` is a strict-JSON value (finite numbers,
+ * plain objects/arrays only). The typebox schema admits unknowns;
+ * this pass keeps the wire contract strict.
+ */
+function assertJsonValue(value, path, depth) {
+    if (depth > JSON_MAX_DEPTH) {
+        throw new Error(`${path}: JSON nesting exceeds ${JSON_MAX_DEPTH}`);
+    }
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${path}: a number must be finite`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            assertJsonValue(value[i], `${path}/${i}`, depth + 1);
+        return;
+    }
+    if (typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Error(`${path}: not a plain JSON object`);
+        }
+        for (const [key, entry] of Object.entries(value)) {
+            assertJsonValue(entry, `${path}/${key}`, depth + 1);
+        }
+        return;
+    }
+    throw new Error(`${path}: not a JSON value`);
+}
+const NoulQuestion = Type.Object({
+    type: Type.Literal("noul"),
+    instructions: Type.Optional(JsonValue),
+    criteria: Type.Optional(Type.Union([
+        Type.Object({
+            true: Type.Optional(JsonValue),
+            false: Type.Optional(JsonValue),
+        }),
+        Type.Null(),
+    ])),
+});
+const ChoiceQuestion = Type.Object({
+    type: Type.Literal("choice"),
+    instructions: Type.Optional(JsonValue),
+    criteria: Type.Record(Type.String(), Type.Union([JsonValue, Type.Null()])),
+});
+const ScoreQuestion = Type.Object({
+    type: Type.Literal("score"),
+    instructions: Type.Optional(JsonValue),
+    criteria: Type.Array(JsonValue),
+});
+const DecisionQuestionSchema = Type.Union([NoulQuestion, ChoiceQuestion, ScoreQuestion]);
+const DecisionRequestSchema = Type.Object({
+    state: Type.Union([Type.String(), Type.Record(Type.String(), JsonValue), Type.Array(JsonValue)]),
+    questions: Type.Record(Type.String(), DecisionQuestionSchema),
+});
+const Probability = Type.Number({ minimum: 0, maximum: 1 });
+const DecisionAnswerSchema = Type.Union([
+    Type.Object({ type: Type.Literal("noul"), noul: Probability }),
+    Type.Object({
+        type: Type.Literal("choice"),
+        choice: Type.String(),
+        confidence: Probability,
+        probabilities: Type.Record(Type.String(), Probability),
+    }),
+    Type.Object({
+        type: Type.Literal("score"),
+        score: Type.Number(),
+        confidence: Probability,
+        probabilities: Type.Record(Type.String(), Probability),
+        legend: Type.Optional(Type.Record(Type.String(), JsonValue)),
+    }),
+]);
+const DecisionAnswersSchema = Type.Object({
+    answers: Type.Record(Type.String(), DecisionAnswerSchema),
+    usage: Type.Optional(Type.Object({
+        input_tokens: Type.Union([Type.Integer(), Type.Null()]),
+        output_tokens: Type.Union([Type.Integer(), Type.Null()]),
+    })),
+    model: Type.Optional(Type.String()),
+});
+const requestValidator = Compile(DecisionRequestSchema);
+const answersValidator = Compile(DecisionAnswersSchema);
+function describeErrors(validator, value) {
+    const out = [];
+    for (const err of validator.Errors(value)) {
+        out.push({ path: err.instancePath, message: err.message ?? "invalid" });
+    }
+    return out.length > 0 ? out : [{ path: "", message: "invalid" }];
+}
+function questionEntries(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return [];
+    const questions = value.questions;
+    if (typeof questions !== "object" || questions === null || Array.isArray(questions))
+        return [];
+    return Object.entries(questions);
+}
+/**
+ * Validate an unknown value as a {@link DecisionRequest}: schema shape
+ * first (`invalid_request`, errors carry `instancePath`), then the
+ * limits (`over_limits`) — the built-in caps, narrowed by the model's
+ * declared `limits`.
+ */
+export function validateDecisionRequest(value, limits) {
+    if (!requestValidator.Check(value)) {
+        return { ok: false, code: "invalid_request", errors: describeErrors(requestValidator, value) };
+    }
+    // The WHOLE request (state + questions) must be strict JSON — a
+    // function or undefined hiding in criteria/instructions must never
+    // reach the provider.
+    try {
+        assertJsonValue(value, "", 0);
+    }
+    catch (err) {
+        return { ok: false, code: "invalid_request", errors: [{ path: "", message: errorMessage(err) }] };
+    }
+    const request = value;
+    const entries = questionEntries(value);
+    for (const [key, question] of entries) {
+        const q = questionOf(key, question);
+        if (!q) {
+            return {
+                ok: false,
+                code: "invalid_request",
+                errors: [{ path: `/questions/${key}`, message: "unknown question type" }],
+            };
+        }
+        const minChoiceOptions = limits?.minChoiceOptions ?? 1;
+        if (q.type === "choice" && Object.keys(q.criteria).length < minChoiceOptions) {
+            return {
+                ok: false,
+                code: "invalid_request",
+                errors: [
+                    {
+                        path: `/questions/${key}/criteria`,
+                        message: `a choice needs at least ${minChoiceOptions} label${minChoiceOptions === 1 ? "" : "s"}`,
+                    },
+                ],
+            };
+        }
+        const maxScore = limits?.maxScoreLevels ?? Number.POSITIVE_INFINITY;
+        const minScore = 2;
+        const levels = q.type === "score" ? q.criteria.length : minScore;
+        if (q.type === "score" && (levels < minScore || levels > maxScore)) {
+            return {
+                ok: false,
+                code: "invalid_request",
+                errors: [
+                    {
+                        path: `/questions/${key}/criteria`,
+                        message: levels < minScore
+                            ? "a score needs at least 2 levels"
+                            : `a score has ${levels} levels; the cap is ${maxScore}`,
+                    },
+                ],
+            };
+        }
+    }
+    const maxQuestions = Math.min(limits?.maxQuestions ?? DECISION_MAX_QUESTIONS, DECISION_MAX_QUESTIONS);
+    if (entries.length < 1) {
+        return {
+            ok: false,
+            code: "over_limits",
+            errors: [{ path: "/questions", message: "a request needs at least 1 question" }],
+        };
+    }
+    if (entries.length > maxQuestions) {
+        return {
+            ok: false,
+            code: "over_limits",
+            errors: [
+                { path: "/questions", message: `${entries.length} questions; the cap is ${maxQuestions}` },
+            ],
+        };
+    }
+    const maxBytes = Math.min(limits?.maxInputBytes ?? DECISION_MAX_BYTES, DECISION_MAX_BYTES);
+    const stateBytes = byteLength(JSON.stringify(value.state));
+    if (stateBytes > maxBytes) {
+        return {
+            ok: false,
+            code: "over_limits",
+            errors: [
+                { path: "/state", message: `the state is ${stateBytes} bytes; the cap is ${maxBytes}` },
+            ],
+        };
+    }
+    return { ok: true, request };
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function questionOf(_key, question) {
+    if (typeof question !== "object" || question === null)
+        return undefined;
+    const q = question;
+    if (q.type === "noul")
+        return { type: "noul" };
+    if (q.type === "choice" && typeof q.criteria === "object" && q.criteria !== null && !Array.isArray(q.criteria)) {
+        return { type: "choice", criteria: q.criteria };
+    }
+    if (q.type === "score" && Array.isArray(q.criteria)) {
+        return { type: "score", criteria: q.criteria };
+    }
+    return undefined;
+}
+/**
+ * Validate an unknown value as the {@link DecisionAnswers} for
+ * `request`: the schema shape, then coverage — every question answered
+ * with the matching type (probabilities are already range-checked by the
+ * schema).
+ */
+export function validateDecisionAnswers(request, value) {
+    if (!answersValidator.Check(value)) {
+        const first = describeErrors(answersValidator, value)[0];
+        return { ok: false, error: `answers fail the wire schema at ${first?.path ?? ""}: ${first?.message ?? "invalid"}` };
+    }
+    const answers = value;
+    for (const [key, question] of Object.entries(request.questions)) {
+        const answer = answers.answers[key];
+        if (answer === undefined) {
+            return { ok: false, error: `missing an answer for question "${key}"` };
+        }
+        if (answer.type !== question.type) {
+            return {
+                ok: false,
+                error: `question "${key}" is ${question.type} but its answer is ${answer.type}`,
+            };
+        }
+    }
+    return { ok: true, answers };
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    try {
+        return String(err);
+    }
+    catch {
+        return "non-Error throw";
+    }
+}
+function readiness(contribution) {
+    try {
+        return contribution.readiness?.().status ?? "ready";
+    }
+    catch {
+        return "degraded";
+    }
+}
+/**
+ * Build the pure decision registry. Last-registered wins per provider id
+ * (each loser warns once, naming both); `evaluate` resolves the model,
+ * validates the request against the model's limits, resolves the
+ * credential (core decides `not_configured` — never the tracker), runs
+ * the provider under `min(timeoutMs, timeoutCapMs)` linked to the
+ * caller's signal, and validates the answers. It never throws.
+ */
+export function buildDecisionRegistry(declarations, deps) {
+    // Last-registered wins per id (the chat-provider collision rule).
+    const entries = new Map();
+    const collisionList = [];
+    for (const declaration of declarations) {
+        const id = declaration.contribution.id;
+        const existing = entries.get(id);
+        if (existing) {
+            deps.warn(`decision provider "${id}": ${declaration.extension} wins over ${existing.declaration.extension} (last-registered wins)`);
+            const recorded = collisionList.find((c) => c.id === id);
+            if (recorded) {
+                recorded.losers.push(recorded.winner);
+                recorded.winner = declaration.extension;
+            }
+            else {
+                collisionList.push({
+                    id,
+                    winner: declaration.extension,
+                    losers: [existing.declaration.extension],
+                });
+            }
+        }
+        entries.set(id, {
+            declaration,
+            models: new Map(declaration.contribution.models.map((m) => [m.id, m])),
+        });
+    }
+    function resolveModel(spec) {
+        if (spec !== undefined) {
+            const slash = spec.indexOf("/");
+            if (slash < 0)
+                return undefined;
+            const providerId = spec.slice(0, slash);
+            const modelId = spec.slice(slash + 1);
+            const entry = entries.get(providerId);
+            if (!entry || !entry.models.has(modelId))
+                return undefined;
+            return { entry, modelId, full: `${providerId}/${modelId}` };
+        }
+        const first = entries.values().next().value;
+        if (!first)
+            return undefined;
+        const firstModel = first.declaration.contribution.models[0];
+        if (!firstModel)
+            return undefined;
+        return { entry: first, modelId: firstModel.id, full: `${first.declaration.contribution.id}/${firstModel.id}` };
+    }
+    function settingsTimeoutMs() {
+        const decisions = deps.readSettings().server
+            ?.decisions;
+        // Env tier first (env always wins), then the live file value,
+        // then the configured fallback.
+        return deps.timeoutMs ?? decisions?.timeoutMs ?? deps.timeoutCapMs;
+    }
+    async function evaluate(caller, request, opts) {
+        // 1. Resolve the model: opts.model, else the live decisionModel
+        //    setting, else the first model of the first-registered provider.
+        const settings = deps.readSettings();
+        const spec = opts.model ?? settings.decisionModel;
+        if (spec === undefined && entries.size === 0) {
+            return { ok: false, code: "no_model", error: "no decision provider is registered" };
+        }
+        const resolved = resolveModel(spec);
+        if (!resolved) {
+            return spec !== undefined
+                ? { ok: false, code: "unknown_model", error: `unknown decision model "${spec}"` }
+                : { ok: false, code: "no_model", error: "no decision provider is registered" };
+        }
+        // 2. Validate the request against the model's declared limits.
+        const modelInfo = resolved.entry.models.get(resolved.modelId);
+        const validation = validateDecisionRequest(request, modelInfo?.limits);
+        if (!validation.ok) {
+            const first = validation.errors[0];
+            return {
+                ok: false,
+                code: validation.code,
+                error: `${validation.code} at ${first?.path ?? ""}: ${first?.message ?? "invalid"}`,
+            };
+        }
+        // 3. Credential — core decides not_configured, never the tracker.
+        const contribution = resolved.entry.declaration.contribution;
+        const credential = deps.credential(contribution.id, contribution.credentialEnv);
+        if (credential === undefined || credential === "") {
+            return {
+                ok: false,
+                code: "not_configured",
+                error: `no credential for decision provider "${contribution.id}"`,
+            };
+        }
+        // 4. Run under min(timeoutMs, cap), linked to the caller's signal.
+        const deadlineMs = Math.min(opts.timeoutMs ?? settingsTimeoutMs(), deps.timeoutCapMs);
+        const controller = new AbortController();
+        let timedOut = false;
+        let callerAborted = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, deadlineMs);
+        const onCallerAbort = () => {
+            callerAborted = true;
+            controller.abort();
+        };
+        opts.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        // A signal aborted before registration never fires the listener —
+        // fire the handler immediately so the provider is never called.
+        if (opts.signal?.aborted === true)
+            onCallerAbort();
+        if (callerAborted) {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onCallerAbort);
+            return { ok: false, code: "aborted", error: "aborted by the caller" };
+        }
+        const started = deps.now();
+        let value;
+        try {
+            value = await contribution.evaluate(validation.request, {
+                model: resolved.modelId,
+                credential,
+                signal: controller.signal,
+                caller,
+            });
+        }
+        catch (err) {
+            const raw = errorMessage(err);
+            const scrubbed = credential === "" ? raw : raw.replaceAll(credential, "[redacted]");
+            if (timedOut) {
+                return { ok: false, code: "timeout", error: `timed out after ${deadlineMs}ms` };
+            }
+            if (callerAborted) {
+                return { ok: false, code: "aborted", error: "aborted by the caller" };
+            }
+            return { ok: false, code: "failed", error: scrubbed };
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onCallerAbort);
+        }
+        if (timedOut) {
+            return { ok: false, code: "timeout", error: `timed out after ${deadlineMs}ms` };
+        }
+        if (callerAborted) {
+            return { ok: false, code: "aborted", error: "aborted by the caller" };
+        }
+        // 5. Validate the answers.
+        const answersValidation = validateDecisionAnswers(validation.request, value);
+        if (!answersValidation.ok) {
+            return { ok: false, code: "bad_answer", error: answersValidation.error };
+        }
+        return {
+            ok: true,
+            model: resolved.full,
+            answers: answersValidation.answers.answers,
+            usage: {
+                input_tokens: answersValidation.answers.usage?.input_tokens ?? null,
+                output_tokens: answersValidation.answers.usage?.output_tokens ?? null,
+            },
+            elapsedMs: deps.now() - started,
+        };
+    }
+    return {
+        evaluate,
+        list() {
+            const out = [];
+            for (const entry of entries.values()) {
+                const contribution = entry.declaration.contribution;
+                const status = readiness(contribution);
+                for (const model of contribution.models) {
+                    out.push({ model: `${contribution.id}/${model.id}`, provider: contribution.id, status });
+                }
+            }
+            return out;
+        },
+        providers() {
+            return [...entries.values()].map((entry) => ({
+                id: entry.declaration.contribution.id,
+                label: entry.declaration.contribution.label,
+                extension: entry.declaration.extension,
+                models: entry.declaration.contribution.models.map((m) => m.id),
+                status: readiness(entry.declaration.contribution),
+            }));
+        },
+        resolvedDefault() {
+            const settings = deps.readSettings();
+            if (settings.decisionModel !== undefined)
+                return settings.decisionModel;
+            const first = entries.values().next().value;
+            const firstModel = first?.declaration.contribution.models[0];
+            return first && firstModel ? `${first.declaration.contribution.id}/${firstModel.id}` : undefined;
+        },
+        collisions() {
+            return collisionList;
+        },
+    };
+}

package/dist/harness/event-bus.js

@@ -772,6 +772,12 @@ export class EventBus {
                             const recordAnsweredByUser = typeof record.answeredByUser === "string"
                                 ? record.answeredByUser
                                 : undefined;
+                            // Ask-user Task 1: the decline channel rides the payload
+                            // next to the answering user (same record read).
+                            const recordDeclinedVia = record.declinedVia === "button" ||
+                                record.declinedVia === "message"
+                                ? record.declinedVia
+                                : undefined;
                             const recordAnswerValues = typeof record.answer === "object" &&
                                 record.answer !== null &&
                                 typeof record.answer.values ===
@@ -808,6 +814,9 @@ export class EventBus {
                                     ...(recordAnsweredByUser === undefined
                                         ? {}
                                         : { answeredByUser: recordAnsweredByUser }),
+                                    ...(recordDeclinedVia === undefined
+                                        ? {}
+                                        : { declinedVia: recordDeclinedVia }),
                                     ...(recordAnswerValues === undefined
                                         ? {}
                                         : { answer: recordAnswerValues }),
@@ -1204,6 +1213,9 @@ export class EventBus {
                     ...(event.answeredByUser === undefined
                         ? {}
                         : { answeredByUser: event.answeredByUser }),
+                    ...(event.declinedVia === undefined
+                        ? {}
+                        : { declinedVia: event.declinedVia }),
                     ...(event.answer === undefined ? {} : { answer: event.answer }),
                 };
         }

package/dist/harness/interactions.js

@@ -80,6 +80,15 @@ export const InteractionsIndexDoc = defineDoc({
     checkpointWhen: () => false,
     initial: () => ({ pending: {} }),
 });
+export const QueuedHumanInputsDoc = defineDoc({
+    kind: "sigrun.interactions.queued-human-inputs",
+    version: 1,
+    scope: "conversation",
+    checkpointWhen: () => false,
+    history: "latest",
+    fork: "current",
+    initial: () => ({ byId: {} }),
+});
 /** Terminal statuses: answering one of these is a no-op (first wins).
  * Exported for the event bus (W3 Task 4): the `interaction.pending` /
  * `interaction.settled` host-event split derives from the SAME set — one
@@ -127,6 +136,12 @@ export function validateInteraction(value) {
     if (r.answeredBy !== undefined && r.answeredBy !== "human" && r.answeredBy !== "extension") {
         return "answeredBy must be 'human' or 'extension'";
     }
+    if (r.declinable !== undefined && r.declinable !== true) {
+        return "declinable must be true when present";
+    }
+    if (r.declinedVia !== undefined && r.declinedVia !== "button" && r.declinedVia !== "message") {
+        return "declinedVia must be 'button' or 'message'";
+    }
     if (r.body !== undefined) {
         // Ruling 16 (no compatibility layer): legacy-shaped bodies (objects
         // keyed text/options/fields/diff rather than {v, root}) fail HERE,
@@ -391,6 +406,64 @@ export function applyAnswer(draft, answer, answeredBy, now, answeredByUser, opts
     mutable.settledAt = now;
     return true;
 }
+/**
+ * The committed decline for one record (ask-user Task 1): status
+ * `"skipped"` with `declinedVia`, `answeredBy: "human"` (declining is a
+ * human act — nothing auto-declines) and `answeredByUser` when given.
+ * Returns `"declined"` on the applied transition, `"not_pending"` when
+ * the record is already terminal (first-wins), `"not_declinable"` when
+ * the record carries no `declinable: true` flag. The draft is mutated in
+ * place — this runs inside the caller's commit.
+ */
+export function applyDecline(draft, via, now, user) {
+    if (draft.status !== "pending")
+        return "not_pending";
+    if (draft.declinable !== true)
+        return "not_declinable";
+    // SAFETY: the draft's declared shape is readonly; the doc family's
+    // tracked-draft write pattern mutates through a structural record view
+    // (every key below exists on the stored record by construction).
+    const mutable = draft;
+    mutable.status = "skipped";
+    mutable.settledAt = now;
+    mutable.answeredBy = "human";
+    if (user !== undefined)
+        mutable.answeredByUser = user;
+    mutable.declinedVia = via;
+    return "declined";
+}
+/**
+ * The admitted-message decline (ask-user Task 2): a human's message
+ * admitted through `submitOp` declines every PENDING declinable record in
+ * the conversation (`via: "message"`), in one commit, right after
+ * admission. Only the seam host's own kinds are in scope — the index
+ * lists every pending record, and the seed's `interactionKinds` gate
+ * already restricted what can be pending, but the draft read re-checks
+ * `declinable` so a record without the flag is never touched.
+ *
+ * Returns the callIds that transitioned. The caller (submitOp) passes
+ * `user` (the submitting principal's user, when identified); an
+ * unidentified submitter still declines, just without attribution.
+ */
+export async function declinePendingOnMessage(harness, conversationId, user, now, context) {
+    return await harness.commit(async (tx) => {
+        const index = await tx.doc(InteractionsIndexDoc);
+        const pending = index.pending[String(conversationId)] ?? [];
+        if (pending.length === 0)
+            return [];
+        const declined = [];
+        for (const callId of pending) {
+            const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
+            const outcome = applyDecline(draft, "message", now, user);
+            if (outcome === "declined") {
+                indexSettled(index, conversationId, callId);
+                sweepSecretDelivery(conversationId, callId);
+                declined.push(callId);
+            }
+        }
+        return declined;
+    }, context);
+}
 /**
  * Take one interaction's secret delivery (the extension-only read path):
  * the TRUE answer when a secret was answered and never yet read — the
@@ -400,6 +473,14 @@ export function applyAnswer(draft, answer, answeredBy, now, answeredByUser, opts
 export function takeSecretDelivery(conversationId, callId) {
     return secretDeliveries.take(conversationId, callId);
 }
+/**
+ * Record one interaction's true-answer delivery WITHOUT settling the
+ * record. @internal test-only (ask-user tests stage deliveries out of
+ * band); production writes go through `applyAnswer`.
+ */
+export function recordSecretDelivery(conversationId, callId, answer) {
+    secretDeliveries.record(conversationId, callId, answer);
+}
 /**
  * Drop one interaction's unread secret delivery without reading it (the
  * settle/expiry sweep: terminal transitions the extension never polled