@sponsio/sdk 0.1.0-alpha.3 → 0.2.0-alpha.10

package/dist/core/grounding.d.ts

@@ -1,5 +1,5 @@
 /**
- * Grounding: convert tool-call events into per-timestep predicate valuations.
+ * Grounding: convert events into per-timestep predicate valuations.
  *
  * Port of sponsio/tracer/grounding.py (Det-relevant atoms).
  *
@@ -16,19 +16,69 @@
  *   arg_paths_within(tool, *prefixes)  — all paths in args within prefix set
  *   token_count(type)                  — cumulative tokens (from event.args.tokens)
  *   delegation_depth                   — depth of agent-to-agent delegation
+ *   ctx(key, value)                    — external fact pushed via observe_context
+ *   ctx_matches(key, pattern)          — current ctx[key] matches regex
+ *   llm_said(pattern)                  — llm_response content matches regex
+ *   response_words / response_chars    — response length on llm_response
+ *   time_since(predicate_key)          — event-clock delta since predicate last True
  */
 import type { Formula } from "./formula.js";
+/**
+ * Public event shape consumed by the grounding kernel. ``tool`` is
+ * required for the dominant ``tool_call`` path; the optional fields
+ * cover ``llm_response`` (response-length / regex content checks) and
+ * ``context_update`` (external-fact ``ctx`` atoms).
+ */
 export interface ToolEvent {
     tool: string;
     args?: Record<string, unknown>;
+    /** ``"tool_call"`` (default) | ``"llm_response"`` | ``"context_update"`` | ``"delegation"``. */
+    event_type?: string;
+    /** Free-form text — only consumed for ``llm_response`` events (regex matching, length). */
+    content?: string;
+    /** Optional event timestamp; if omitted, the grounding state's monotonic clock advances by 1. */
+    ts?: number;
+    /**
+     * Subject of the event, for kinds whose subject is not a tool name.
+     * An ``evidence`` event puts the predicate name here.
+     */
+    key?: string;
 }
 export interface GroundingState {
     callCounts: Record<string, number>;
     callWithCounts: Record<string, number>;
+    /** Canonical spelling of the previous tool (see core/tool-names.ts). */
     lastTool: string | null;
+    /**
+     * Every spelling the previous call was grounded under, so a tool change
+     * zeroes all of them rather than only the raw name.
+     */
+    lastToolAliases: string[];
     consecutiveCounts: Record<string, number>;
     tokenCounts: Record<string, number>;
     delegationDepth: number;
+    /**
+     * External facts pushed by the integration via ``observeContext``.
+     * Persists across events; re-emitted as ``ctx(k, v)`` atoms each
+     * timestep so ``G(called(x) → ctx(k, v))`` fires as expected.
+     */
+    currentCtx: Record<string, string>;
+    /**
+     * Event clock — advances by 1 per event when no explicit ``ts`` is
+     * supplied. Used as the numerator for ``time_since(key)`` and
+     * accessible to formulas via ``Var("now")``.
+     */
+    now: number;
+    /**
+     * Per-predicate-key timestamp of the most recent False→True
+     * transition. Re-emissions of a sustained predicate (forward-
+     * propagated ``flow``/``contains``, ``ctx`` atoms held in scope)
+     * do NOT refresh this — that's what makes ``time_since(approval)``
+     * measure "since granted" rather than "since last re-emit".
+     */
+    lastTs: Record<string, number>;
+    /** Predicates that were True at the previous event (post-emission). */
+    trueAtPrev: Set<string>;
 }
 export declare function newGroundingState(): GroundingState;
 /**
@@ -36,8 +86,41 @@ export declare function newGroundingState(): GroundingState;
  * These are atoms whose grounding depends on event content (arg patterns).
  */
 export declare function collectContentAtoms(formulas: Formula[]): Record<string, Set<string>>;
+export declare function pathWithin(path: string, prefix: string): boolean;
+/**
+ * Fail at construction on a contract pattern that is not a valid regular
+ * expression. Mirrors Python, where a malformed contract raises when the
+ * guard is built. Without this an ``llm_said`` / ``ctx_matches`` pattern
+ * that never compiles silently never matches (fail-open), and an
+ * ``arg_*`` pattern throws on the first tool call instead of at startup.
+ *
+ * Patterns are stored as ``args.join("|")``; each predicate knows which
+ * tail of that string is the regex, exactly as ``groundEvent`` reads it.
+ */
+export declare function validateContentPatterns(atoms: Record<string, Set<string>>): void;
 /**
- * Ground a single tool-call event into a predicate valuation dict.
+ * Read a tool argument as a number, the way a numeric cap needs it.
+ *
+ * ``"$5,000"``, ``"5,000"`` and ``"5000 USD"`` are the shapes a model
+ * writes for an amount. ``parseFloat`` read ``"5,000"`` as ``5`` and
+ * ``"$5,000"`` as nothing at all, and the evaluator reads a missing
+ * ``arg_numeric`` as ``0``, so ``argValueRange`` waved them through a cap
+ * that stopped ``5000``. The normalisation is the one ordered comparisons
+ * already use (``numericString`` in core/evaluator.ts), so both paths
+ * agree. Parity with Python ``numeric_arg`` in sponsio/tracer/grounding.py:
+ * a boolean reads as 0/1, a number as itself, anything else as undefined.
+ */
+export declare function numericArg(value: unknown): number | undefined;
+/**
+ * Does a contract's target tool name the tool this event called?
+ *
+ * The target is canonicalised and looked up among every spelling the
+ * event answers to (see core/tool-names.ts), so a rule on ``issue_refund``
+ * binds ``Issue_Refund``, ``"issue_refund "`` and
+ * ``mcp__finance__issue_refund``. Parity with Python ``_tool_matches``
+ * for plain names; the ``tool:argpattern`` form is split by the pattern
+ * factories before it reaches grounding in this runtime.
  */
-export declare function groundEvent(event: ToolEvent, state: GroundingState, contentAtoms?: Record<string, Set<string>>): Record<string, boolean | number>;
+export declare function toolMatches(targetTool: string, aliases: Iterable<string>): boolean;
+export declare function groundEvent(event: ToolEvent, state: GroundingState, contentAtoms?: Record<string, Set<string>>): Record<string, unknown>;
 //# sourceMappingURL=grounding.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/core/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AAE9E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CASlD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAgC7B;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,cAAc,EACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CA6MlC"}
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/core/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,uEAAuE;IACvE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAclD;AAmCD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA0B7B;AA8CD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACjC,IAAI,CA2BN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAIlF;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,cAAc,EACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoXzB"}