@sponsio/sdk 0.2.0-alpha.4 → 0.2.0-alpha.9

package/dist/index.js

@@ -20,12 +20,16 @@
  *   if (result.blocked) { ... }
  */
 import { evaluate } from "./core/evaluator.js";
-import { groundEvent, newGroundingState, collectContentAtoms, } from "./core/grounding.js";
+import { groundEvent, newGroundingState, collectContentAtoms, validateContentPatterns, numericArg, toolMatches, } from "./core/grounding.js";
 import { parseNl } from "./core/nl-parser.js";
+import { canonicalTool, toolAliases } from "./core/tool-names.js";
 import { loadSponsoConfig, } from "./core/config-loader.js";
 import { SessionLogger } from "./core/session-log.js";
-import { ContractCheckSpan, EnforcementSpan, GuaranteeSpan, SpanCollector, } from "./core/spans.js";
+import { AgentTurnSpan, ContractCheckSpan, EnforcementSpan, GuaranteeSpan, SpanCollector, } from "./core/spans.js";
 import { renderSession } from "./render/session-view.js";
+import { CloudClient, readProject } from "./cloud/client.js";
+import * as privacy from "./cloud/privacy.js";
+import { buildViewModel, newSessionId, } from "./cloud/view-model.js";
 // Re-exports
 export { evaluate } from "./core/evaluator.js";
 export * from "./core/formula.js";
@@ -37,6 +41,18 @@ export { loadSponsoConfig } from "./core/config-loader.js";
 export { SessionLogger, rotateSessions } from "./core/session-log.js";
 export { contract, ContractBuilder } from "./contract.js";
 export { parseScore, CloudFeatureError } from "./core/sto.js";
+export { CloudClient, CloudError, readApiKey, readProject, baseUrl, } from "./cloud/client.js";
+export { LEVELS as PRIVACY_LEVELS } from "./cloud/privacy.js";
+export { buildViewModel, newSessionId } from "./cloud/view-model.js";
+/** Actions after which the original tool call must NOT run. */
+export const STOPPING_ACTIONS = new Set([
+    "blocked",
+    "redirected",
+]);
+/** Parity with Python's ``is_stopping_action``. */
+export function isStoppingAction(action) {
+    return STOPPING_ACTIONS.has(action);
+}
 /**
  * Best-effort accessor for the agent-facing line. Prefers the
  * structured ``agentMsg`` field when populated; falls back to
@@ -54,6 +70,26 @@ export function selectAgentMessage(violations, fallback = "Contract violation")
     }
     return fallback;
 }
+/**
+ * Fill the derived half of a verdict from the violations' actions. One
+ * place, so a new `DetAction` cannot be handled inconsistently across
+ * the several sites that build a `CheckResult`.
+ */
+export function deriveVerdict(detViolations, stoViolations = []) {
+    const acted = detViolations.filter((v) => v.action !== undefined);
+    const redirect = acted.find((v) => v.action === "redirected");
+    return {
+        blocked: acted.some((v) => v.action === "blocked"),
+        escalated: acted.some((v) => v.action === "escalated"),
+        redirected: redirect !== undefined,
+        ...(redirect?.redirectedTo !== undefined
+            ? { redirectedTo: redirect.redirectedTo }
+            : {}),
+        stopOriginal: acted.some((v) => isStoppingAction(v.action)),
+        allViolations: [...detViolations, ...stoViolations],
+        needsRetry: false,
+    };
+}
 export class Sponsio {
     agentId;
     mode;
@@ -69,6 +105,14 @@ export class Sponsio {
     _violations;
     _logger;
     _turnSpans = [];
+    // The same turns with the violations they produced, which the span
+    // tree does not carry in a form the cloud can read: it records that a
+    // contract was violated, not which pattern and arguments, and the
+    // cloud groups findings by exactly those.
+    _runSpans = [];
+    _sessionId = newSessionId();
+    _startedAt = Date.now();
+    _rulebookStamp;
     constructor(options = {}) {
         this.agentId = options.agentId ?? "agent";
         this._trace = [];
@@ -97,6 +141,13 @@ export class Sponsio {
         // ── Resolve mode: env > ctor > yaml > default ────────────────────
         this.mode = resolveMode(options.mode, yamlMode);
         // ── Parse NL strings into det formulas ───────────────────────────
+        // A contract that does not parse is a rule that is not there. In
+        // observe mode that is a warning, because the point of observe is to
+        // keep running and surface what would fire. In enforce it is fatal:
+        // the alternative is an agent that reports success while enforcing a
+        // book with holes in it, and the operator has no way to know which
+        // holes. Python raises here; TypeScript logged one line and ran on.
+        const unparsed = [];
         for (const c of sources) {
             if (typeof c === "string") {
                 const parsed = parseNl(c);
@@ -104,13 +155,25 @@ export class Sponsio {
                     this._contracts.push(parsed);
                 }
                 else {
-                    console.warn(`[sponsio] Could not parse: "${c}"`);
+                    unparsed.push(c);
                 }
             }
             else {
                 this._contracts.push(c);
             }
         }
+        if (unparsed.length > 0) {
+            const listed = unparsed.map((c) => `  - ${c}`).join("\n");
+            if (this.mode === "enforce") {
+                throw new Error(`sponsio: ${unparsed.length} contract(s) could not be parsed, and ` +
+                    `this guard is in enforce mode. THESE RULES ARE NOT ARMED. Fix ` +
+                    `them, or write them as structured \`pattern:\` blocks in a ` +
+                    `sponsio.yaml, which covers every pattern the library has.\n` +
+                    listed);
+            }
+            console.warn(`[sponsio] ${unparsed.length} contract(s) could not be parsed and ` +
+                `are NOT armed (observe mode, so the run continues):\n${listed}`);
+        }
         // ── Sto pipeline is not part of this build ──────────────────────
         // The managed LLM-judge catalog (`tone` / `relevance` / `llm_judge`
         // ...) and the judge client are not part of this build (the
@@ -139,12 +202,125 @@ export class Sponsio {
         // ── Warn once about yaml features the TS runtime can't handle ───
         warnOnceAboutSkipped(yamlSkipped);
         this._contentAtoms = collectContentAtoms(this._contracts.map((c) => c.formula));
+        // A pattern that does not compile is a broken contract; refuse to
+        // arm it rather than let it never match at runtime.
+        validateContentPatterns(this._contentAtoms);
         // ── Session log ─────────────────────────────────────────────────
         const wantLog = options.sessionLog ?? true;
         this._logger = wantLog
             ? new SessionLogger(this.agentId, { baseDir: options.sessionLogBaseDir })
             : null;
     }
+    /**
+     * Predicates whose truth depends on the *contents* of a tool call's
+     * arguments. If a call arrives with no arguments, none of these keys is
+     * written and the evaluator reads a missing key as false, which makes
+     * ``argBlacklist`` (``!arg_field_has(...)``) report "satisfied" for a
+     * call nothing looked at. Mirrors Python's
+     * ``BaseGuard._ARG_SHAPED_PREDICATES``.
+     */
+    static ARG_SHAPED_PREDICATES = [
+        "arg_has",
+        "arg_field_has",
+        "arg_length_exceeds",
+        "arg_paths_within",
+        "arg_numeric",
+        "arg_value",
+    ];
+    /** Canonical names of the tools some contract reads the arguments of. */
+    _toolsNeedingArgs() {
+        const tools = new Set();
+        for (const pred of Sponsio.ARG_SHAPED_PREDICATES) {
+            for (const raw of this._contentAtoms[pred] ?? []) {
+                const tool = raw.split("|")[0];
+                if (tool)
+                    tools.add(canonicalTool(tool));
+            }
+        }
+        return tools;
+    }
+    /** ``[tool, field]`` pairs some ``arg_numeric`` rule reads. */
+    _numericRuleTargets() {
+        const pairs = [];
+        for (const raw of this._contentAtoms["arg_numeric"] ?? []) {
+            const parts = raw.split("|");
+            if (parts.length >= 2)
+                pairs.push([parts[0], parts[1]]);
+        }
+        return pairs;
+    }
+    /**
+     * Refuse a call whose argument rules cannot be evaluated.
+     *
+     * Two cases, both of which used to read as "not violated":
+     *
+     * - The call arrived with no arguments (``{}``, ``undefined``, ``null``)
+     *   but some rule reads this tool's arguments. An adapter that loses the
+     *   arguments, a partial streamed call or a malformed payload all land
+     *   here, and every argument check would pass vacuously.
+     * - A field an ``arg_numeric`` rule bounds is present but is not a
+     *   number (``"five thousand"``). Grounding leaves ``arg_numeric`` unset
+     *   and the evaluator reads the gap as 0, which passes every upper
+     *   bound. An absent field is left alone: CLI-flag and positional rules
+     *   on ``Bash`` legitimately see calls without their flag.
+     *
+     * ``SPONSIO_ALLOW_MISSING_ARGS=1`` restores the permissive behaviour.
+     * Mirrors Python ``BaseGuard._args_unevaluable`` and
+     * ``_unreadable_numeric_arg``; both block under rule id
+     * ``args:unevaluable``.
+     */
+    _unevaluableArgs(toolName, args) {
+        const env = typeof process !== "undefined" ? process.env : undefined;
+        if (env?.SPONSIO_ALLOW_MISSING_ARGS === "1")
+            return null;
+        const empty = args == null || (typeof args === "object" && Object.keys(args).length === 0);
+        if (empty) {
+            // Every spelling grounding binds the call under, so
+            // ``mcp__shell__Bash`` meets a rule written for ``Bash``.
+            const needed = this._toolsNeedingArgs();
+            if (!toolAliases(toolName).some((alias) => needed.has(alias)))
+                return null;
+            const message = `BLOCKED: ${this.agentId}.${toolName}. \`${toolName}\` was called ` +
+                `with no arguments, but a contract inspects its arguments. The ` +
+                `check cannot be evaluated, so the call is refused rather than ` +
+                `passed unchecked (set SPONSIO_ALLOW_MISSING_ARGS=1 to allow).`;
+            return {
+                desc: message,
+                message,
+                action: "blocked",
+                ruleId: "args:unevaluable",
+                agentMsg: `The action \`${toolName}\` was rejected because its arguments ` +
+                    `were missing and a policy needs to read them. Retry with the ` +
+                    `arguments included.`,
+            };
+        }
+        const aliases = toolAliases(toolName);
+        for (const [target, field] of this._numericRuleTargets()) {
+            if (!Object.prototype.hasOwnProperty.call(args, field))
+                continue;
+            if (!toolMatches(target, aliases))
+                continue;
+            const value = args[field];
+            if (value === null || value === undefined)
+                continue;
+            if (numericArg(value) !== undefined)
+                continue;
+            const shown = JSON.stringify(String(value).slice(0, 60));
+            const message = `BLOCKED: ${this.agentId}.${toolName}. \`${field}\`=${shown} is ` +
+                `not a number, but a contract bounds it numerically. The bound ` +
+                `cannot be checked, so the call is refused rather than passed ` +
+                `unchecked (set SPONSIO_ALLOW_MISSING_ARGS=1 to allow).`;
+            return {
+                desc: message,
+                message,
+                action: "blocked",
+                ruleId: "args:unevaluable",
+                agentMsg: `The action \`${toolName}\` was rejected because \`${field}\` ` +
+                    `must be a plain number. Retry with a numeric value.`,
+            };
+        }
+        return null;
+    }
     /**
      * Check a tool call against contracts before execution.
      *
@@ -163,6 +339,20 @@ export class Sponsio {
         return this._contracts.map((c) => c.desc);
     }
     guardBefore(toolName, args = {}) {
+        const unevaluable = this._unevaluableArgs(toolName, args);
+        if (unevaluable) {
+            const violations = [unevaluable.message];
+            this._violations.push(...violations);
+            this._logViolations(toolName, violations, [unevaluable.desc], "blocked");
+            return {
+                ...deriveVerdict([unevaluable]),
+                allowed: false,
+                message: unevaluable.message,
+                violations,
+                detViolations: [unevaluable],
+                stoViolations: [],
+            };
+        }
         const event = { tool: toolName, args };
         const snapshot = this._snapshotState();
         const valuation = groundEvent(event, this._state, this._contentAtoms);
@@ -174,7 +364,7 @@ export class Sponsio {
         const violations = [];
         const violatedDescs = [];
         const detViolations = [];
-        let anyBlocking = false;
+        let anyStopping = false;
         for (const contract of this._contracts) {
             const checkSpan = new ContractCheckSpan(contract.desc, "hard");
             collector.push(checkSpan);
@@ -203,39 +393,68 @@ export class Sponsio {
                 // Per-contract `mode:` overrides the global mode for this one
                 // verdict — same routing as Python's RuntimeMonitor.
                 const effMode = contract.mode ?? this.mode;
-                if (effMode === "enforce")
-                    anyBlocking = true;
+                // The contract's strategy decides which outcome this is, so a
+                // `redirect_to_safe` violation reports `redirected` with its
+                // substitute instead of collapsing into a plain block. Observe
+                // never stops, whatever the strategy says.
+                const action = effMode === "observe"
+                    ? "observed"
+                    : contract.strategy === "redirect"
+                        ? "redirected"
+                        : contract.strategy === "escalate"
+                            ? "escalated"
+                            : "blocked";
+                if (isStoppingAction(action))
+                    anyStopping = true;
                 const verb = effMode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
                 const msg = `${verb}: ${this.agentId}.${toolName} — det constraint violated: ${contract.desc}`;
                 violations.push(msg);
                 violatedDescs.push(contract.desc);
+                const safe = action === "redirected" ? contract.safeName : undefined;
                 detViolations.push({
                     desc: contract.desc,
                     message: msg,
+                    action,
+                    ...(safe !== undefined ? { redirectedTo: safe, alternatives: [safe] } : {}),
                     ruleId: contract.patternName || contract.desc,
                     agentMsg: `The action \`${toolName}\` was rejected by policy ` +
                         `(${contract.patternName || contract.desc}): ${contract.desc}. ` +
-                        `Choose a different approach.`,
+                        (safe !== undefined
+                            ? `Call \`${safe}\` instead.`
+                            : `Choose a different approach.`),
                 });
                 // Nest violation + enforcement spans under the failed
                 // guarantee so the renderer can pick up the verdict word.
-                const enforce = new EnforcementSpan("DetBlock", effMode === "enforce" ? "blocked" : "observed");
+                const strategyName = contract.strategy === "redirect"
+                    ? "RedirectToSafe"
+                    : contract.strategy === "escalate"
+                        ? "EscalateToHuman"
+                        : "DetBlock";
+                const enforce = new EnforcementSpan(strategyName, action);
                 guaranteeSpan.children.push(enforce);
                 enforce.finish("violated");
             }
             collector.pop(result ? "ok" : "violated");
         }
         const hasViolations = violations.length > 0;
-        const blocked = anyBlocking;
-        this._turnSpans.push(collector.finishRoot(blocked, this._contracts.length, violations.length));
-        if (blocked) {
+        const stopping = anyStopping;
+        const turn = collector.finishRoot(stopping, this._contracts.length, violations.length);
+        this._turnSpans.push(turn);
+        this._runSpans.push({ span: turn, violations: [...detViolations] });
+        if (stopping) {
             this._trace.pop();
             this._state = snapshot;
             this._violations.push(...violations);
             this._logViolations(toolName, violations, violatedDescs, "blocked");
+            // `allowed` tracks `blocked` alone, not every stopping outcome:
+            // Python computes `not any(action == "blocked")`, so a redirect
+            // stays `allowed: true` because the agent flow continues down the
+            // safe path. `stopOriginal` is the field that says the original
+            // call must not run.
+            const derived = deriveVerdict(detViolations);
             return {
-                blocked: true,
-                allowed: false,
+                ...derived,
+                allowed: !derived.blocked,
                 message: violations[0],
                 violations,
                 detViolations,
@@ -254,7 +473,7 @@ export class Sponsio {
             this._logAllow(toolName);
         }
         return {
-            blocked: false,
+            ...deriveVerdict(detViolations),
             allowed: true,
             message: "",
             violations: [],
@@ -275,6 +494,63 @@ export class Sponsio {
     /** Drop accumulated turn spans (used between sessions in tests). */
     resetSession() {
         this._turnSpans = [];
+        this._runSpans = [];
+        this._sessionId = newSessionId();
+        this._startedAt = Date.now();
+    }
+    /**
+     * This run, in the shape the cloud stores.
+     *
+     * Exposed so a caller can see exactly what would be uploaded before
+     * uploading anything, which is the question a customer under a data
+     * agreement asks first.
+     */
+    viewModel() {
+        return buildViewModel({
+            agentId: this.agentId,
+            mode: this.mode,
+            sessionId: this._sessionId,
+            startedAt: this._startedAt,
+            contracts: this._contracts,
+            spans: this._runSpans,
+            privacyLevel: privacy.resolve(),
+            ...(this._rulebookStamp === undefined
+                ? {}
+                : { rulebookStamp: this._rulebookStamp }),
+        });
+    }
+    /**
+     * Upload this run.
+     *
+     * Best-effort by construction: it resolves false rather than throwing,
+     * because losing telemetry must never change what an agent does, and a
+     * rejected upload at the end of a run is not a reason to fail the run.
+     * Silent only about the network; a misconfiguration is worth saying
+     * once, since the symptom otherwise is a customer with no runs and no
+     * explanation.
+     */
+    async uploadSession(opts = {}) {
+        const client = opts.client ?? new CloudClient();
+        if (!client.configured)
+            return false;
+        // A per-customer key resolves to its own project and must not name
+        // another, so passing nothing is both correct and safest here.
+        const project = opts.project === undefined ? readProject() : opts.project;
+        try {
+            await client.ingestSession(project ?? null, {
+                key: this._sessionId,
+                live: false,
+                vm: this.viewModel(),
+            });
+            return true;
+        }
+        catch (err) {
+            if ((process.env.SPONSIO_QUIET ?? "") !== "1") {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`sponsio: run not uploaded (${msg})\n`);
+            }
+            return false;
+        }
     }
     /**
      * Render the end-of-session view to ``out`` (defaults to stderr) —
@@ -297,6 +573,7 @@ export class Sponsio {
             callCounts: { ...this._state.callCounts },
             callWithCounts: { ...this._state.callWithCounts },
             lastTool: this._state.lastTool,
+            lastToolAliases: [...this._state.lastToolAliases],
             consecutiveCounts: { ...this._state.consecutiveCounts },
             tokenCounts: { ...this._state.tokenCounts },
             delegationDepth: this._state.delegationDepth,
@@ -352,36 +629,73 @@ export class Sponsio {
      * violations the same way they branch on ``guardBefore``. In
      * enforce mode, ``blocked: true`` rolls back the synthetic event.
      */
+    /**
+     * Record a claim-verification verdict in the trace and check the
+     * contracts that reference it.
+     *
+     * Grounds `claim_emitted(pred)`, `evidence_verdict(pred, V)` and
+     * `evidence_action(pred, a)` at one timestep, so contracts built from
+     * `claimRequiresEvidence` / `underdeterminedMustClarify` can decide.
+     * No verdict is computed here: the atoms restate what
+     * `/v1/evidence/verify` answered.
+     *
+     * Parity with feeding `EvidenceResult.to_event()` through Python's
+     * trace path.
+     */
+    observeEvidence(predicate, verdict, action) {
+        return this._checkSynthetic({
+            tool: "",
+            event_type: "evidence",
+            key: predicate,
+            args: { verdict, action },
+        }, `<evidence:${predicate}>`);
+    }
     observeResponse(content, opts = {}) {
         const args = {};
         if (opts.segment)
             args.segment = opts.segment;
-        const event = {
-            tool: "",
-            event_type: "llm_response",
-            content,
-            args,
-        };
+        return this._checkSynthetic({ tool: "", event_type: "llm_response", content, args }, "<llm_response>");
+    }
+    /**
+     * Check one synthetic (non-tool-call) event against every contract.
+     *
+     * The output lane and the evidence lane both push an event that is not
+     * a tool call and then judge the trace. Sharing the body keeps their
+     * verdicts identical: a second copy is how one lane ends up with a
+     * rollback the other lacks.
+     *
+     * `label` names the subject in violation messages and session logs.
+     */
+    _checkSynthetic(event, label) {
         const snapshot = this._snapshotState();
         const valuation = groundEvent(event, this._state, this._contentAtoms);
         this._trace.push(valuation);
         const violations = [];
         const violatedDescs = [];
         const detViolations = [];
-        let anyBlocking = false;
+        let anyStopping = false;
         for (const contract of this._contracts) {
             const result = evaluate(contract.formula, this._trace);
             if (!result) {
                 const effMode = contract.mode ?? this.mode;
-                if (effMode === "enforce")
-                    anyBlocking = true;
+                // No substitution on the output lane: there is no call to swap,
+                // so a redirect strategy still stops here. `escalate` keeps its
+                // own action, which does not stop.
+                const action = effMode === "observe"
+                    ? "observed"
+                    : contract.strategy === "escalate"
+                        ? "escalated"
+                        : "blocked";
+                if (isStoppingAction(action))
+                    anyStopping = true;
                 const verb = effMode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
-                const msg = `${verb}: ${this.agentId}.<llm_response> — det constraint violated: ${contract.desc}`;
+                const msg = `${verb}: ${this.agentId}.${label} — det constraint violated: ${contract.desc}`;
                 violations.push(msg);
                 violatedDescs.push(contract.desc);
                 detViolations.push({
                     desc: contract.desc,
                     message: msg,
+                    action,
                     ruleId: contract.patternName || contract.desc,
                     agentMsg: `LLM response was rejected by policy ` +
                         `(${contract.patternName || contract.desc}): ${contract.desc}.`,
@@ -389,15 +703,36 @@ export class Sponsio {
             }
         }
         const hasViolations = violations.length > 0;
-        const blocked = anyBlocking;
-        if (blocked) {
+        const stopping = anyStopping;
+        // The output lane builds no span tree, so without this a rule that
+        // fires on what the model said was enforced locally and never
+        // uploaded: at `full` a TypeScript run showed half the run a Python
+        // one showed. A bare turn is enough for the cloud, which reads the
+        // step's type, tool and verdict and not the tree under it.
+        const outTurn = new AgentTurnSpan(this.agentId, label);
+        outTurn.totalContractsChecked = this._contracts.length;
+        outTurn.detViolations = violations.length;
+        outTurn.blocked = stopping;
+        outTurn.finish(hasViolations ? "violated" : "ok");
+        this._runSpans.push({
+            span: outTurn,
+            violations: [...detViolations],
+            type: "output",
+        });
+        if (stopping) {
             this._trace.pop();
             this._state = snapshot;
             this._violations.push(...violations);
-            this._logViolations("<llm_response>", violations, violatedDescs, "blocked");
+            this._logViolations(label, violations, violatedDescs, "blocked");
+            // `allowed` tracks `blocked` alone, not every stopping outcome:
+            // Python computes `not any(action == "blocked")`, so a redirect
+            // stays `allowed: true` because the agent flow continues down the
+            // safe path. `stopOriginal` is the field that says the original
+            // call must not run.
+            const derived = deriveVerdict(detViolations);
             return {
-                blocked: true,
-                allowed: false,
+                ...derived,
+                allowed: !derived.blocked,
                 message: violations[0],
                 violations,
                 detViolations,
@@ -406,10 +741,10 @@ export class Sponsio {
         }
         if (hasViolations) {
             this._violations.push(...violations);
-            this._logViolations("<llm_response>", violations, violatedDescs, "observed");
+            this._logViolations(label, violations, violatedDescs, "observed");
         }
         return {
-            blocked: false,
+            ...deriveVerdict(detViolations),
             allowed: true,
             message: "",
             violations: [],
@@ -552,7 +887,7 @@ let _skippedWarned = false;
 // the ctor.
 function emptyAllow() {
     return {
-        blocked: false,
+        ...deriveVerdict([]),
         allowed: true,
         message: "",
         violations: [],