@sponsio/sdk 0.1.0-alpha.3

package/dist/core/sto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sto.d.ts","sourceRoot":"","sources":["../../src/core/sto.ts"],"names":[],"mappings":"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"}

package/dist/core/sto.js

@@ -0,0 +1,147 @@
+/**
+ * Stub for the sto (stochastic / LLM-judge) pipeline.
+ *
+ * The real evaluator catalog (``tone`` / ``relevance`` / ``llm_judge`` /
+ * ``hallucination_free`` …) and the OpenAI-compatible judge client are
+ * Sponsio Cloud features, not bundled with the OSS engine. The OSS
+ * ``Sponsio`` constructor logs-and-skips sto contracts at load time
+ * with a one-time warning — matching Python's
+ * ``sponsio.patterns.sto_catalog`` behaviour.
+ *
+ * This file exists so that:
+ *   - imports in ``index.ts`` resolve cleanly
+ *   - downstream consumers depending on the type names
+ *     (``StoEvaluator``, ``JudgeClient``, …) compile against the
+ *     same surface
+ *   - any code path that *constructs* an evaluator or *builds* a
+ *     judge fails loudly with ``CloudFeatureError`` rather than
+ *     silently pretending to enforce
+ *
+ * Operators who want the sto pipeline:
+ *
+ *     pip install sponsio[cloud]
+ *
+ * or contact your Sponsio account team for managed sto access. See
+ * ``docs/oss_scope.md`` for the OSS / Cloud boundary.
+ */
+// ----- CloudFeatureError ---------------------------------------------
+const CLOUD_HINT = "Sponsio's sto (LLM-judge) pipeline is a Cloud feature, not bundled " +
+    "with the OSS engine. Install `sponsio[cloud]` (Python) or contact " +
+    "your Sponsio account team for managed sto access. See " +
+    "https://github.com/SponsioLabs/Sponsio/blob/main/docs/oss_scope.md.";
+export class CloudFeatureError extends Error {
+    constructor(featureName) {
+        super(`[sponsio] ${featureName} is not available in OSS. ${CLOUD_HINT}`);
+        this.name = "CloudFeatureError";
+    }
+}
+// ----- createJudge: stub ---------------------------------------------
+/**
+ * Stub. The OSS engine does not ship a managed judge client; calling
+ * this throws ``CloudFeatureError``. The OSS ``Sponsio`` constructor
+ * never reaches this — yaml ``judge:`` blocks and ``options.judge``
+ * are routed through the ``skipped`` warning path instead.
+ */
+export function createJudge(_config) {
+    throw new CloudFeatureError("createJudge()");
+}
+// ----- parseScore: pure utility, kept --------------------------------
+/**
+ * Parse a 0–1 score from a judge response. Pure utility; safe to ship
+ * because it never calls a judge. Kept so any user calling it
+ * directly (rare) keeps working.
+ */
+export function parseScore(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("{")) {
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj.score === "number")
+                return clamp01(obj.score);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    const m = trimmed.match(/([01](?:\.\d+)?|0?\.\d+)/);
+    if (!m) {
+        throw new Error(`unparseable score: ${JSON.stringify(trimmed.slice(0, 80))}`);
+    }
+    const n = parseFloat(m[1]);
+    if (!Number.isFinite(n))
+        throw new Error(`non-finite score: ${m[1]}`);
+    return clamp01(n);
+}
+function clamp01(n) {
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+// ----- Evaluator class stubs -----------------------------------------
+// Each class preserves the 3 public ``StoEvaluator`` fields that
+// callers may inspect (``atom`` / ``desc`` / ``threshold``), but
+// ``evaluate()`` rejects with ``CloudFeatureError``. The OSS Sponsio
+// ctor never instantiates these — yaml sto specs flow through the
+// ``skipped`` path before any evaluator is built.
+class _StubEvaluator {
+    desc;
+    threshold;
+    constructor(desc, threshold) {
+        this.desc = desc;
+        this.threshold = threshold;
+    }
+    evaluate(_input) {
+        return Promise.reject(new CloudFeatureError(`${this.atom} evaluator`));
+    }
+}
+export class LlmJudgeEvaluator extends _StubEvaluator {
+    atom = "llm_judge";
+    constructor(desc, threshold, _judge, _promptTemplate) {
+        super(desc, threshold);
+    }
+}
+export class ToneEvaluator extends _StubEvaluator {
+    atom = "tone";
+    constructor(desc, threshold, _judge, _targetTone) {
+        super(desc, threshold);
+    }
+}
+export class RelevanceEvaluator extends _StubEvaluator {
+    atom = "relevance";
+    constructor(desc, threshold, _judge) {
+        super(desc, threshold);
+    }
+}
+export class SemanticPiiFreeEvaluator extends _StubEvaluator {
+    atom = "semantic_pii_free";
+    constructor(desc, threshold, _judge) {
+        super(desc, threshold);
+    }
+}
+export class HallucinationFreeEvaluator extends _StubEvaluator {
+    atom = "hallucination_free";
+    constructor(desc, threshold, _judge) {
+        super(desc, threshold);
+    }
+}
+export class ScopeRespectEvaluator extends _StubEvaluator {
+    atom = "scope_respect";
+    constructor(desc, threshold, _judge, _defaultScope) {
+        super(desc, threshold);
+    }
+}
+export class MetricIntegrityEvaluator extends _StubEvaluator {
+    atom = "metric_integrity";
+    constructor(desc, threshold, _judge) {
+        super(desc, threshold);
+    }
+}
+export class InjectionFreeEvaluator extends _StubEvaluator {
+    atom = "injection_free";
+    constructor(desc, threshold, _judge) {
+        super(desc, threshold);
+    }
+}
+//# sourceMappingURL=sto.js.map

package/dist/core/sto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sto.js","sourceRoot":"","sources":["../../src/core/sto.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @sponsio/sdk — Runtime contract enforcement for LLM agents.
+ *
+ * Native TypeScript implementation. < 50KB bundle, zero cold start,
+ * Edge/Serverless compatible.
+ *
+ * Usage:
+ *   import { Sponsio } from "@sponsio/sdk"
+ *
+ *   // Inline contracts:
+ *   const guard = new Sponsio({
+ *     agentId: "refund_bot",
+ *     contracts: ["tool `check_policy` must precede `issue_refund`"]
+ *   })
+ *
+ *   // Or loaded from a shared sponsio.yaml:
+ *   const guard = new Sponsio({ config: "sponsio.yaml", agentId: "refund_bot" })
+ *
+ *   const result = guard.guardBefore("issue_refund", { orderId: "#123" })
+ *   if (result.blocked) { ... }
+ */
+import { AgentTurnSpan } from "./core/spans.js";
+import type { DetFormula } from "./core/patterns.js";
+import { type JudgeClient, type JudgeConfig, type StoContextSnapshot } from "./core/sto.js";
+export { evaluate } from "./core/evaluator.js";
+export type { Valuation } from "./core/evaluator.js";
+export * from "./core/formula.js";
+export * from "./core/patterns.js";
+export { parseNl } from "./core/nl-parser.js";
+export { parseRepr, ParseError } from "./core/parser.js";
+export { groundEvent, newGroundingState, collectContentAtoms, } from "./core/grounding.js";
+export { loadSponsoConfig } from "./core/config-loader.js";
+export type { LoadedConfig, SkippedItem } from "./core/config-loader.js";
+export { SessionLogger, rotateSessions } from "./core/session-log.js";
+export type { SessionRecord, SessionLoggerOptions, } from "./core/session-log.js";
+export { contract, ContractBuilder } from "./contract.js";
+export { createJudge, LlmJudgeEvaluator, ToneEvaluator, RelevanceEvaluator, SemanticPiiFreeEvaluator, HallucinationFreeEvaluator, ScopeRespectEvaluator, MetricIntegrityEvaluator, InjectionFreeEvaluator, parseScore, } from "./core/sto.js";
+export type { StoEvaluator, StoContract, StoInput, StoResult, StoContextSnapshot, JudgeClient, JudgeConfig, } from "./core/sto.js";
+/**
+ * One det violation, with enough structure to feed into downstream
+ * agent feedback — mirrors Python's ``EnforcementResult`` fields that
+ * examples reach for (``check.det_violations[0].message``).
+ *
+ * Phrasing contract (mirrors Python ``OutcomeBuilder``):
+ *
+ * - ``message`` is the **human-facing** log line —
+ *   ``"BLOCKED: agent.tool — det constraint violated: …"``. It keeps
+ *   the legacy prefix so log-parsing back-compat holds. Don't inject
+ *   it into the LLM's next prompt; it's noise to the model.
+ * - ``agentMsg`` is the **agent-facing** line, phrased to nudge the
+ *   model into the right reaction. For block this should read
+ *   "abandon this action" rather than parroting the log line.
+ *   Empty until the strategy populates it; integrations fall back to
+ *   ``message`` when empty.
+ * - ``ruleId`` is a stable identifier (``DetFormula.patternName`` or
+ *   sto atom name) integrations can group on without parsing
+ *   free text.
+ * - ``retryHint`` is populated only on retry-style outcomes — the
+ *   "to fix this, do X" guidance, kept distinct from ``agentMsg``
+ *   so adapters can format the two parts in framework-native ways.
+ * - ``alternatives`` is an optional list of suggested replacement
+ *   actions for blocked / redirected outcomes.
+ */
+export interface DetViolation {
+    /** Human-readable contract description (``DetFormula.desc``). */
+    desc: string;
+    /** Formatted ``"[WOULD-]BLOCKED: agent.tool — det constraint …"``. */
+    message: string;
+    /** Stable rule identifier (pattern name / contract id). */
+    ruleId?: string;
+    /** Agent-facing line, tuned per action voice. Falls back to ``message``. */
+    agentMsg?: string;
+    /** "To fix this, do X" guidance. Only set on retry-style outcomes. */
+    retryHint?: string;
+    /** Suggested replacement actions for the agent. */
+    alternatives?: string[];
+}
+/**
+ * Best-effort accessor for the agent-facing line. Prefers the
+ * structured ``agentMsg`` field when populated; falls back to
+ * ``message`` for adapters that haven't migrated yet. Mirrors the
+ * Python ``select_agent_message`` helper.
+ */
+export declare function selectAgentMessage(violations: DetViolation[], fallback?: string): string;
+export interface CheckResult {
+    blocked: boolean;
+    allowed: boolean;
+    message: string;
+    /**
+     * Flat list of violation messages — kept for back-compat with
+     * existing TS call sites that only need a string feed.
+     */
+    violations: string[];
+    /**
+     * Structured det violations — parallel to Python's
+     * ``CheckResult.det_violations``. Populated in both enforce-block
+     * and observe-log paths; empty on a clean allow.
+     */
+    detViolations: DetViolation[];
+    /**
+     * Sto-pipeline violations — populated by ``guardAfter`` when
+     * stochastic contracts (e.g. ``tone``, ``llm_judge``) are declared
+     * in the yaml and a ``judge:`` block is configured. Empty on a
+     * clean pass or when no sto contracts exist.
+     */
+    stoViolations: DetViolation[];
+}
+export type SponsoMode = "enforce" | "observe";
+export interface SponsoOptions {
+    /** Logical agent id — used for session log paths. */
+    agentId?: string;
+    /** Inline NL-string / DetFormula contracts. Merged with `config:` if both given. */
+    contracts?: (string | DetFormula)[];
+    /**
+     * Path to a ``sponsio.yaml`` config file. Loaded synchronously at
+     * construction time; contracts and runtime settings from the yaml
+     * merge with inline options.
+     *
+     * When set, the TS SDK reads:
+     *   - ``runtime.mode`` (observe | enforce)
+     *   - ``agents.<agentId>.contracts[]`` (NL strings; structured
+     *     patterns and packs are skipped with a warning)
+     *
+     * Uses the ``yaml`` package (declared as a dependency of
+     * ``@sponsio/sdk``).
+     */
+    config?: string;
+    /**
+     * Runtime mode. Precedence (matches the Python SDK):
+     *
+     *     SPONSIO_MODE env  >  ctor arg  >  yaml runtime.mode  >  "observe"
+     *
+     * ``observe`` (the default) logs every would-have-blocked decision
+     * to ``~/.sponsio/sessions/<agent_id>/*.jsonl`` without actually
+     * blocking. ``enforce`` returns ``blocked: true`` on violation.
+     */
+    mode?: SponsoMode;
+    /**
+     * Write session JSONL log to ``~/.sponsio/sessions/<agent_id>/…``.
+     * Defaults to ``true`` in observe mode, ``true`` in enforce mode
+     * (matches Python — the log is the audit trail, not an observe
+     * mode artefact). Pass ``false`` to disable (tests, edge runtimes
+     * without a writable home dir).
+     */
+    sessionLog?: boolean;
+    /** Override session log base dir (tests / alternative layouts). */
+    sessionLogBaseDir?: string;
+    /**
+     * Judge config for the sto pipeline. Either a plain config object
+     * (provider / model / apiKey / baseUrl / fallbackMode) or a
+     * pre-built ``JudgeClient``. Falls through to the yaml ``judge:``
+     * block if the ctor arg is omitted. When no sto contracts exist,
+     * the judge is never contacted.
+     */
+    judge?: JudgeConfig | JudgeClient;
+}
+export declare class Sponsio {
+    readonly agentId: string;
+    readonly mode: SponsoMode;
+    private _contracts;
+    private _stoContracts;
+    private _judge;
+    private _judgeFallback;
+    private _stoContext;
+    private _trace;
+    private _state;
+    private _contentAtoms;
+    private _violations;
+    private _logger;
+    private _turnSpans;
+    constructor(options?: SponsoOptions);
+    /**
+     * Check a tool call against contracts before execution.
+     *
+     * On block, **all** mutations made by ``groundEvent`` are rolled back via a
+     * pre-call snapshot. Previously only ``callCounts[toolName]`` was undone,
+     * leaving ``consecutiveCounts``, ``lastTool``, ``callWithCounts``,
+     * ``tokenCounts``, and ``delegationDepth`` in a stale state; subsequent
+     * guards saw counts as if the blocked call had executed.
+     *
+     * In **observe mode**, violations are logged to the session JSONL
+     * but not reported as blocks — the method always returns ``allowed: true``.
+     * In **enforce mode**, the first violation blocks the call.
+     */
+    /** Read the human-readable descs of all compiled contracts (det only). */
+    contractDescs(): string[];
+    guardBefore(toolName: string, args?: Record<string, unknown>): CheckResult;
+    /**
+     * Snapshot of the per-turn span trees this guard has produced since
+     * construction (or the last ``resetSession``). One root
+     * ``AgentTurnSpan`` per ``guardBefore`` call, with nested
+     * ``ContractCheckSpan`` / ``GuaranteeSpan`` / ``EnforcementSpan``
+     * children. Mirrors Python's ``RuntimeMonitor.turn_spans``.
+     */
+    turnSpans(): AgentTurnSpan[];
+    /** Drop accumulated turn spans (used between sessions in tests). */
+    resetSession(): void;
+    /**
+     * Render the end-of-session view to ``out`` (defaults to stderr) —
+     * banner, contracts armed, trace tree, verdict, perf, CTA. Mirrors
+     * Python's ``RuntimeMonitor.finish_session`` + ``render_session``
+     * pipeline. Call this once at the end of the agent's run.
+     */
+    finishSession(opts?: {
+        out?: NodeJS.WritableStream;
+        sessionId?: string;
+        tenant?: string;
+        env?: string;
+        sdk?: string;
+        ctas?: string[];
+        useColor?: boolean;
+    }): void;
+    /** Deep-copy the grounding state so it can be restored on a blocked call. */
+    private _snapshotState;
+    private _logViolations;
+    private _logAllow;
+    /**
+     * Record tool output after execution and run the sto pipeline.
+     *
+     * Returns a ``CheckResult`` whose ``stoViolations`` carries any
+     * stochastic rule failures (``tone`` / ``llm_judge``). When no sto
+     * contracts are declared the method returns synchronously in
+     * effect (the ``Promise`` resolves on the microtask queue) and
+     * never contacts the judge LLM.
+     *
+     * In **observe mode** violations are logged but the method still
+     * reports ``allowed: true``. In **enforce mode** the first sto
+     * violation flips ``blocked: true`` — but the tool output has
+     * already executed, so the caller is responsible for routing the
+     * result (retry with feedback, redirect to safe, etc.).
+     */
+    guardAfter(toolName: string, output?: string): Promise<CheckResult>;
+    private _logSto;
+    /**
+     * Reset guard state for a new session.
+     */
+    reset(): void;
+    /**
+     * Stash per-turn context for the sto pipeline. Atoms that need
+     * grounding — ``relevance`` (``query``), ``hallucination_free``
+     * (``source``), ``scope_respect`` (``scope`` override),
+     * ``metric_integrity`` (``history``) — read from this snapshot on
+     * the next ``guardAfter`` call.
+     *
+     * Merges with any previously-set context; pass ``{ query: undefined }``
+     * to explicitly clear a field. ``reset()`` clears the whole snapshot.
+     */
+    setContext(ctx: Partial<StoContextSnapshot>): void;
+    /**
+     * Get all violations from this session.
+     */
+    get violations(): string[];
+    /**
+     * Get a summary string. Returns a formatted list of violations
+     * observed in this session, or ``"No violations"`` if clean.
+     */
+    summary(): string;
+    /**
+     * Print the session summary to stdout — Python parity for
+     * ``guard.print_summary()``. Equivalent to
+     * ``console.log(guard.summary())``; exists so copy-pasted Python
+     * snippets compile (and so ad-hoc review in scripts reads the
+     * same way across both SDKs).
+     */
+    printSummary(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}