@actuarial-ts/agents 0.1.0

package/dist/evals.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Golden-prompt tool-selection eval harness: does a realistic instruction
+ * make the agent call the right tool(s)? Generalizes the ActNG server's
+ * eval-advisor script.
+ *
+ * Asserts tool SELECTION, not prose: each case lists tools that must appear
+ * among the turn's calls. Running against a real agent costs live API tokens
+ * and is opt-in by design - the harness itself is pure bookkeeping, which is
+ * why package tests exercise it with a stubbed agent and canned streams.
+ *
+ * Chunk shapes (verified against @mastra/core 1.49 fullStream): tool calls
+ * arrive as { type: "tool-call", payload: { toolName } }, with a legacy
+ * { type: "tool-call", toolName } fallback.
+ */
+export interface ToolSelectionEvalCase {
+    id: string;
+    prompt: string;
+    /** Tool names that must ALL appear among the turn's calls. */
+    expectTools: readonly string[];
+}
+export interface ToolSelectionCaseResult {
+    id: string;
+    pass: boolean;
+    /** Tool names actually called, in first-call order. */
+    called: string[];
+    /** Expected tools that never got called. */
+    missing: string[];
+    /** Stream error or timeout, when the case failed exceptionally. */
+    error?: string;
+}
+export interface ToolSelectionEvalReport {
+    results: ToolSelectionCaseResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+    };
+}
+/**
+ * The structural slice of an agent the harness needs: stream(messages,
+ * options) resolving to something with an async-iterable fullStream.
+ *
+ * WHY structural instead of the concrete @mastra/core Agent class: the Agent
+ * type carries heavy generics and live-model plumbing the harness never
+ * touches; it only consumes the fullStream chunk feed. Typing the seam
+ * structurally lets package tests substitute a canned-stream stub (no LLM, no
+ * network) and lets hosts pass any Agent from any compatible Mastra patch
+ * level without generic gymnastics.
+ */
+export interface ToolStreamingAgent {
+    stream(messages: Array<{
+        role: "user";
+        content: string;
+    }>, options?: Record<string, unknown>): Promise<{
+        fullStream: AsyncIterable<unknown>;
+    }>;
+}
+export interface RunToolSelectionEvalsOptions {
+    agent: ToolStreamingAgent;
+    cases: readonly ToolSelectionEvalCase[];
+    /** Forwarded verbatim to agent.stream options (the tenant seam for tools). */
+    requestContext?: unknown;
+    /** Max agent steps per case. Default 8. */
+    maxSteps?: number;
+    /** Per-case wall clock: a stalled stream fails the case, not the suite. Default 180000. */
+    timeoutMs?: number;
+    /**
+     * Optional per-case memory option factory (thread/resource), for agents
+     * whose Memory configuration requires one on every stream call.
+     */
+    memoryFor?: (evalCase: ToolSelectionEvalCase) => {
+        thread: string;
+        resource: string;
+    };
+}
+/**
+ * Runs every case sequentially against the agent, collecting the tool calls
+ * from the fullStream and asserting each case's expectTools is a subset of
+ * the tools actually called. A per-case Promise.race timeout keeps one
+ * stalled stream from hanging the whole suite.
+ */
+export declare function runToolSelectionEvals(options: RunToolSelectionEvalsOptions): Promise<ToolSelectionEvalReport>;
+//# sourceMappingURL=evals.d.ts.map

package/dist/evals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evals.d.ts","sourceRoot":"","sources":["../src/evals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CACJ,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC;QAAE,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxC,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAiBD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,uBAAuB,CAAC,CA+DlC"}

package/dist/evals.js

@@ -0,0 +1,95 @@
+/**
+ * Golden-prompt tool-selection eval harness: does a realistic instruction
+ * make the agent call the right tool(s)? Generalizes the ActNG server's
+ * eval-advisor script.
+ *
+ * Asserts tool SELECTION, not prose: each case lists tools that must appear
+ * among the turn's calls. Running against a real agent costs live API tokens
+ * and is opt-in by design - the harness itself is pure bookkeeping, which is
+ * why package tests exercise it with a stubbed agent and canned streams.
+ *
+ * Chunk shapes (verified against @mastra/core 1.49 fullStream): tool calls
+ * arrive as { type: "tool-call", payload: { toolName } }, with a legacy
+ * { type: "tool-call", toolName } fallback.
+ */
+// ---------------------------------------------------------------------------
+// Harness
+/** Extracts the tool name from a fullStream chunk, or null for non-tool-call chunks. */
+function toolCallName(chunk) {
+    const c = chunk;
+    if (c?.type !== "tool-call")
+        return null;
+    const name = c.payload?.toolName ?? c.toolName;
+    return typeof name === "string" && name.length > 0 ? name : null;
+}
+/**
+ * Runs every case sequentially against the agent, collecting the tool calls
+ * from the fullStream and asserting each case's expectTools is a subset of
+ * the tools actually called. A per-case Promise.race timeout keeps one
+ * stalled stream from hanging the whole suite.
+ */
+export async function runToolSelectionEvals(options) {
+    const { agent, cases, requestContext } = options;
+    const maxSteps = options.maxSteps ?? 8;
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    const results = [];
+    for (const evalCase of cases) {
+        const called = new Set();
+        let error;
+        let timer;
+        // On timeout the underlying stream is CANCELLED, not abandoned: the
+        // iterator's return() is invoked so a well-behaved provider stops
+        // generating (and billing), and no chunks bleed into the next case.
+        // Hosts whose models accept an abort signal should prefer abortable
+        // models; the iterator return() is the portable floor.
+        let activeIterator;
+        try {
+            await Promise.race([
+                (async () => {
+                    const stream = await agent.stream([{ role: "user", content: evalCase.prompt }], {
+                        ...(requestContext !== undefined ? { requestContext } : {}),
+                        maxSteps,
+                        ...(options.memoryFor ? { memory: options.memoryFor(evalCase) } : {}),
+                    });
+                    const iterator = stream.fullStream[Symbol.asyncIterator]();
+                    activeIterator = iterator;
+                    for (;;) {
+                        const next = await iterator.next();
+                        if (next.done)
+                            break;
+                        const name = toolCallName(next.value);
+                        if (name)
+                            called.add(name);
+                    }
+                })(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`case timed out after ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : String(err);
+            // Best-effort cancellation of a stream that outlived its race.
+            void activeIterator?.return?.().catch(() => undefined);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        const missing = evalCase.expectTools.filter((tool) => !called.has(tool));
+        const result = {
+            id: evalCase.id,
+            pass: error === undefined && missing.length === 0,
+            called: [...called],
+            missing,
+            ...(error !== undefined ? { error } : {}),
+        };
+        results.push(result);
+    }
+    const passed = results.filter((r) => r.pass).length;
+    return {
+        results,
+        summary: { total: results.length, passed, failed: results.length - passed },
+    };
+}
+//# sourceMappingURL=evals.js.map

package/dist/evals.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./errors.js";
+export * from "./tools.js";
+export * from "./judgment.js";
+export * from "./advisor.js";
+export * from "./evals.js";
+//# 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":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./errors.js";
+export * from "./tools.js";
+export * from "./judgment.js";
+export * from "./advisor.js";
+export * from "./evals.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/judgment.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Judgment gates that write the compliance ledger: the generalization of the
+ * ActNG server's derive-expected-losses workflow (cap -> restoration ->
+ * trends -> ELR) into a factory any host can point at its own gate list.
+ *
+ * The loop each gate enforces is propose -> justify -> approve -> record:
+ * the gate gathers evidence and SUSPENDS with a recommendation; a human
+ * decides; the resume payload carries the decision plus a VERBATIM rationale;
+ * the gate applies the decision and appends the resulting assumptions to an
+ * @actuarial-ts/compliance ledger threaded through the workflow state. A
+ * completed chain returns { trail, ledger } - a ledger ready to hand straight
+ * to generateDisclosure, so ASOP 41 documentation falls out of running the
+ * analysis instead of being reconstructed afterwards.
+ *
+ * Ground truth (verified against @mastra/core 1.49 dist types and a live
+ * suspend/resume probe):
+ * - Steps execute as ({ inputData, resumeData, suspend, requestContext });
+ *   suspend(payload) pauses the run with the payload surfaced under
+ *   result.steps[stepId].suspendPayload; run.resume({ step, resumeData,
+ *   requestContext }) re-executes the step with resumeData set.
+ * - Resume data is validated against the gate's resumeSchema by Mastra
+ *   itself; run.resume REJECTS on schema violations. The chain additionally
+ *   rejects blank rationales at runtime (AgentsError MISSING_RATIONALE), so a
+ *   host schema of plain z.string() cannot smuggle undocumented judgment.
+ * - Suspend/resume requires snapshot storage: hosts register the returned
+ *   workflow on their Mastra instance (new Mastra({ workflows: { chain } })),
+ *   which provides in-memory storage by default and durable storage when
+ *   configured - exactly how the server keeps paused derivations resumable
+ *   across restarts.
+ *
+ * Purity: the package never reads a clock. The host supplies now() and every
+ * ledger timestamp comes from it.
+ *
+ * Tenant seam: the tenant id travels in the workflow requestContext, never in
+ * step inputs - the same boundary as every actuarial tool.
+ */
+import { createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+import { type AssumptionActor, type AssumptionLedger, type JsonValue } from "@actuarial-ts/compliance";
+/** One decision in the audit trail; skip gates record skipped: true. */
+export interface JudgmentTrailEntry {
+    stage: string;
+    decision: string;
+    rationale: string;
+    skipped: boolean;
+}
+/**
+ * What earlier gates decided, keyed by gate id: the validated resume payload
+ * for decided gates, or { skipped: true, reason } for self-skipped ones.
+ * Available to skipWhen/gatherEvidence/applyDecision so a later gate can
+ * self-skip on an earlier decision (the server's ilf gate skips when the cap
+ * gate chose to stay unlimited).
+ */
+export type JudgmentDecisions = Record<string, unknown>;
+/** Marker recorded into the decisions map when a gate self-skips. */
+export interface JudgmentSkipRecord {
+    skipped: true;
+    reason: string;
+}
+/** The context every gate hook receives. */
+export interface JudgmentGateContext {
+    /** The workflow request context (tenant id lives here, never in inputs). */
+    requestContext: {
+        get(key: string): unknown;
+    };
+    /** Host-injected clock; the source of every ledger timestamp. */
+    now: () => string;
+    /** Decisions from earlier gates, keyed by gate id. */
+    decisions: JudgmentDecisions;
+    /** The trail accumulated so far. */
+    trail: readonly JudgmentTrailEntry[];
+}
+/**
+ * A ledger entry as a gate's applyDecision returns it: timestamp, actor, and
+ * rationale may be omitted - the chain fills timestamp from ctx.now(), actor
+ * from the resume payload's optional actor field (default "actuary"), and
+ * rationale from the decision's verbatim rationale.
+ */
+export interface JudgmentLedgerEntry {
+    /** Dotted assumption path, e.g. "layer.cap". */
+    field: string;
+    value: JsonValue;
+    previousValue?: JsonValue;
+    source?: string;
+    rationale?: string;
+    timestamp?: string;
+    actor?: AssumptionActor;
+}
+/** What applyDecision hands back to the chain. */
+export interface JudgmentApplication {
+    /** Assumptions this decision fixed; appended to the threaded ledger. */
+    ledgerEntries?: JudgmentLedgerEntry[];
+    /** Human-readable decision text for the trail; derived from the payload when omitted. */
+    summary?: string;
+}
+/**
+ * One human judgment gate. TDecision is the validated resume payload shape;
+ * its schema MUST declare a rationale key (createJudgmentChain rejects the
+ * spec otherwise) and SHOULD make it a non-empty string - either way the
+ * chain rejects blank rationales at runtime.
+ */
+export interface JudgmentGateSpec<TDecision = unknown> {
+    /** Step id; also the resume target (run.resume({ step: id, ... })). */
+    id: string;
+    /** Stage label surfaced in the suspend payload and the trail. */
+    stage: string;
+    /** Validates the resume payload. Must contain a rationale key. */
+    resumeSchema: z.ZodType<TDecision>;
+    /**
+     * Returns the skip reason when the gate should pass through without a
+     * human decision (e.g. a later gate made moot by an earlier decision),
+     * null to proceed. A skipped gate records a trail note and never suspends.
+     */
+    skipWhen?: (ctx: JudgmentGateContext) => string | null;
+    /** Gathers the evidence and recommendation the gate suspends with. */
+    gatherEvidence: (ctx: JudgmentGateContext) => Promise<{
+        recommendation: string;
+        evidence: unknown;
+    }> | {
+        recommendation: string;
+        evidence: unknown;
+    };
+    /** Applies the human decision through the host's service layer. */
+    applyDecision: (ctx: JudgmentGateContext, decision: TDecision) => Promise<JudgmentApplication>;
+}
+/** The completed chain's output: the audit trail and the fused compliance ledger. */
+export interface JudgmentChainOutcome {
+    trail: JudgmentTrailEntry[];
+    /** Ready for @actuarial-ts/compliance generateDisclosure. */
+    ledger: AssumptionLedger;
+}
+export interface CreateJudgmentChainOptions {
+    /** Workflow id. */
+    id: string;
+    /** The gates, in order. Must be non-empty with unique ids. */
+    gates: readonly JudgmentGateSpec<any>[];
+    /**
+     * Host-injected clock for ledger timestamps (purity: this package never
+     * reads Date). Return an ISO-8601 string.
+     */
+    now: () => string;
+    /** Runs once after the last gate, before the chain returns its outcome. */
+    onComplete?: (outcome: JudgmentChainOutcome, ctx: JudgmentGateContext) => Promise<void> | void;
+    /** Optional request-context validation (e.g. z.object({ projectId: z.string() })). */
+    requestContextSchema?: z.ZodTypeAny;
+}
+declare const chainInputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+declare const chainResultSchema: z.ZodObject<{
+    trail: z.ZodArray<z.ZodObject<{
+        stage: z.ZodString;
+        decision: z.ZodString;
+        rationale: z.ZodString;
+        skipped: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        stage: string;
+        decision: string;
+        rationale: string;
+        skipped: boolean;
+    }, {
+        stage: string;
+        decision: string;
+        rationale: string;
+        skipped: boolean;
+    }>, "many">;
+    ledger: z.ZodType<AssumptionLedger, z.ZodTypeDef, AssumptionLedger>;
+}, "strip", z.ZodTypeAny, {
+    trail: {
+        stage: string;
+        decision: string;
+        rationale: string;
+        skipped: boolean;
+    }[];
+    ledger: AssumptionLedger;
+}, {
+    trail: {
+        stage: string;
+        decision: string;
+        rationale: string;
+        skipped: boolean;
+    }[];
+    ledger: AssumptionLedger;
+}>;
+/**
+ * The committed workflow type hosts receive: register it on a Mastra instance
+ * for snapshot storage, then createRun/start/resume exactly like any Mastra
+ * workflow. (Instantiation expression pins the concrete schema generics; the
+ * step list is dynamic, so the per-step chain typing is erased - see the cast
+ * at the bottom of createJudgmentChain.)
+ */
+export type JudgmentChainWorkflow = ReturnType<typeof createWorkflow<string, typeof chainInputSchema, typeof chainResultSchema>>;
+/**
+ * Builds a committed Mastra workflow from an ordered gate list. Each gate:
+ * skipWhen? -> pass through with a trail note; else gatherEvidence ->
+ * suspend({ stage, recommendation, evidence }); on resume -> validate the
+ * decision (schema + non-blank rationale), applyDecision, append the
+ * resulting assumptions to the threaded ledger. The terminal step rebuilds
+ * the frozen ledger, invokes onComplete, and returns { trail, ledger }.
+ *
+ * FOOTGUN (learned the hard way): a Mastra Workflow exposes a .then(step)
+ * builder method, which makes it an ACCIDENTAL THENABLE. Never await the
+ * returned workflow and never return it from an async function - JS will
+ * call .then(resolve, reject) with the promise resolver as a "step" and the
+ * promise never settles. Assign it synchronously and register it on your
+ * Mastra instance.
+ */
+export declare function createJudgmentChain(options: CreateJudgmentChainOptions): JudgmentChainWorkflow;
+export {};
+//# sourceMappingURL=judgment.d.ts.map

package/dist/judgment.d.ts.map

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