@actuarial-ts/agents 0.1.0 → 0.2.0

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAKhE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D,GAAG,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACnC;AA8BD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,EAAE,GAAG,SAAc,GAAG,MAAM,CAU/F;AAKD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,gBAAgB,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACzF,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,iGAAiG;IACjG,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,eAAe,CAAC;CACrC;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBtF"}

package/dist/mcp.js

@@ -0,0 +1,138 @@
+/**
+ * MCP tenant seam + boot self-test for the governed workspace.
+ *
+ * When the workspace is exposed over the Model Context Protocol, external AI
+ * clients read everything and mutate nothing directly. The one hard guarantee
+ * is that EVERY exposed tool resolves its tenant (project id) from the MCP
+ * request's auth info, never from the model — the same secureToolWrapper rule
+ * the ActNG server proved in production, restated for the MCP transport.
+ *
+ * @mastra/mcp gives no built-in per-tool authorization outside its EE FGA path,
+ * so a missed wire-up FAILS OPEN: a tool that forgets to read authInfo would
+ * happily serve an unauthenticated caller. These two helpers close that caveat:
+ *
+ * 1. requireMcpTenant — the read side. A tool calls it instead of trusting the
+ *    model; absent auth info it THROWS AgentsError("NO_TENANT_CONTEXT"), which
+ *    the defineActuarialTool wrapper turns into a { success:false } envelope.
+ *    A tool built on it fails CLOSED.
+ *
+ * 2. assertFailClosed — the proof. At server startup, drive a probe read tool
+ *    through the server WITHOUT auth and assert it fails closed. If the probe
+ *    SUCCEEDS, the seam is not wired up: this throws MCP_SELF_TEST_FAILED and
+ *    startup MUST abort.
+ *
+ * ---------------------------------------------------------------------------
+ * VERIFIED against the installed @mastra/mcp 1.14.0 (house rule — types and
+ * compiled source, not memory):
+ *
+ * - MCPServer.executeTool(toolId, args, executionContext?: { messages?,
+ *   toolCallId?, requestContext? }): Promise<any> returns the tool's execute
+ *   result VERBATIM (dist/index.js: `const result = await tool.execute(...);
+ *   return result;`). For a defineActuarialTool with no outputSchema the core
+ *   tool builder passes the value through untouched, so an executeTool caller
+ *   sees exactly the { success:false, error:{ code } } envelope the wrapper
+ *   produced. Argument validation runs FIRST and, on failure, short-circuits
+ *   to a { error:true, message } object before the tool ever executes — hence
+ *   assertFailClosed passes minimal VALID probe args.
+ *
+ * - Auth-context access path. On the real streamable-HTTP call path the SDK
+ *   copies the transport `extra` (with `authInfo` from `req.auth`) into the
+ *   tool context TWO ways: directly at `context.mcp.extra`, and — via
+ *   createProxiedRequestContext — as INDIVIDUAL keys set on a fresh
+ *   RequestContext (`context.requestContext.get("authInfo")`). NOTE the
+ *   surprise: the installed 1.14.0 sets each extra key on the RequestContext
+ *   verbatim, so the tenant lives at `requestContext.get("authInfo")`, NOT
+ *   under a single `"mcp.extra"` key as the research draft documented. This
+ *   helper tries all three shapes so it is correct against both the installed
+ *   package and the documented pattern.
+ */
+import { AgentsError } from "./errors.js";
+/**
+ * Resolves the MCP auth-info bag from a tool context, trying every shape the
+ * installed and documented transports expose (see the file header). Returns
+ * undefined when no auth info is present — the caller decides that is fatal.
+ */
+function resolveMcpAuthInfo(context) {
+    if (!context)
+        return undefined;
+    // Primary: the streamable-HTTP call path passes the transport extra at
+    // context.mcp.extra (mcpOptions.mcp.extra in @mastra/mcp).
+    const directAuthInfo = context.mcp?.extra?.authInfo;
+    if (directAuthInfo)
+        return directAuthInfo;
+    const requestContext = context.requestContext;
+    if (requestContext && typeof requestContext.get === "function") {
+        // Documented universal fallback: the whole extra bag under "mcp.extra".
+        const proxiedExtra = requestContext.get("mcp.extra");
+        if (proxiedExtra?.authInfo)
+            return proxiedExtra.authInfo;
+        // Installed @mastra/mcp 1.14.0: createProxiedRequestContext copies each
+        // extra key onto the RequestContext verbatim, so authInfo is top-level.
+        const topLevelAuthInfo = requestContext.get("authInfo");
+        if (topLevelAuthInfo)
+            return topLevelAuthInfo;
+    }
+    return undefined;
+}
+/**
+ * Reads the tenant id (default key "projectId") from the MCP execution
+ * context's auth info — the server-set identity, never the model. THROWS a
+ * typed AgentsError("NO_TENANT_CONTEXT") when the auth info or the key is
+ * absent, non-string, or empty. Inside a defineActuarialTool execute the
+ * wrapper converts that throw into a { success:false } envelope, so a tool
+ * built on requireMcpTenant fails CLOSED for any unauthenticated MCP caller.
+ */
+export function requireMcpTenant(context, key = "projectId") {
+    const authInfo = resolveMcpAuthInfo(context);
+    const value = authInfo?.[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new AgentsError("NO_TENANT_CONTEXT", `MCP tool invoked without a non-empty "${key}" in the request's authInfo; the host's bearer-token middleware must set req.auth = { ${key} } so it reaches context.mcp.extra.authInfo — the tenant never comes from the model`);
+    }
+    return value;
+}
+/** Structural check for the { success:false, error:{ code } } tool-failure envelope. */
+function isFailureEnvelope(result) {
+    if (typeof result !== "object" || result === null)
+        return false;
+    if (result.success !== false)
+        return false;
+    const error = result.error;
+    return typeof error?.code === "string";
+}
+/** A short, log-safe description of an unexpected probe result for the abort message. */
+function describeResult(result) {
+    if (isFailureEnvelope(result)) {
+        return `a { success: false } envelope with code "${result.error.code}"`;
+    }
+    if (typeof result === "object" && result !== null) {
+        if (result.error === true) {
+            return "an argument-validation error (the probe never reached the tenant check — pass valid probeArgs)";
+        }
+        if (result.success === true) {
+            return "a { success: true } result (the probe SUCCEEDED without tenant context — the seam is not wired up)";
+        }
+    }
+    return "a non-envelope result (the probe did not fail closed on tenant context)";
+}
+/**
+ * The boot self-test. Drives {@link AssertFailClosedOptions.probeToolId}
+ * through the server WITHOUT any auth info and asserts it fails closed with the
+ * tenant error code. THROWS AgentsError("MCP_SELF_TEST_FAILED") loudly for any
+ * other outcome — most importantly if the probe SUCCEEDED, which means the tool
+ * did not require tenant context and the MCP tenant seam is a fail-open hole.
+ *
+ * Call this at server startup whenever MCP is enabled, and ABORT startup if it
+ * throws: a governed workspace must never accept unauthenticated MCP clients.
+ */
+export async function assertFailClosed(options) {
+    const { server, probeToolId, probeArgs = {}, expectedErrorCode = "NO_TENANT_CONTEXT" } = options;
+    // No requestContext, no mcp.extra -> the probe sees no auth info at all.
+    const result = await server.executeTool(probeToolId, probeArgs, {});
+    if (isFailureEnvelope(result) && result.error.code === expectedErrorCode) {
+        return;
+    }
+    throw new AgentsError("MCP_SELF_TEST_FAILED", `MCP boot self-test failed: probe tool "${probeToolId}" did not fail closed without auth. ` +
+        `Expected a { success: false, error.code: "${expectedErrorCode}" } envelope but got ${describeResult(result)}. ` +
+        `An MCP-exposed read tool must resolve its tenant with requireMcpTenant so an unauthenticated call is rejected; this outcome means the tenant seam is not wired up. Abort startup.`);
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

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

package/dist/promotion.d.ts

@@ -0,0 +1,269 @@
+/**
+ * promoteStudy: notebook study -> governed judgment (interchange spec rev 2.1,
+ * Section 6). A four-gate judgment chain built on createJudgmentChain:
+ *
+ *   Gate 1 "study-intake"  - schema/integrity validation via interchange
+ *                            parseDocument, ASOP 23 data review on the study's
+ *                            triangles, selection coherence (spec 3.2 rule),
+ *                            segment resolution (v1: one selection per
+ *                            segment), and the tolerance ceiling.
+ *   Gate 2 "replay-verify" - table-exact intents replayed through
+ *                            interchange/core; approx/value-only targets
+ *                            labeled verified-by-value; supportingResults
+ *                            refereed via crosscheck at the effective
+ *                            tolerance; a "disagree" verdict HARD-BLOCKS.
+ *   Gate 3 "rationale"     - a DRAFT rationale (template-assembled from the
+ *                            study narrative; options.draftRationale is the
+ *                            injection hook for future agent drafting); resume
+ *                            REQUIRES a non-blank rationale AND attestation.
+ *   Gate 4 "apply"         - deps.applySelections per selection,
+ *                            deps.runAnalysis, ledger entries carrying the
+ *                            Gate 3 rationale + attestation verbatim, and
+ *                            deps.persistNote with the trail + ledger JSON.
+ *
+ * Architecture decisions (each is load-bearing):
+ *
+ * - EAGER, DETERMINISTIC INTAKE. All Gate 1/2 computation (parse, review,
+ *   coherence, segment resolution, replay, crosschecks) runs synchronously at
+ *   chain-CONSTRUCTION time. Everything is a pure function of the study
+ *   document plus deps.resolveSegment, so a host that reconstructs the chain
+ *   after a restart (promoteStudy again with the same study) gets IDENTICAL
+ *   gates and resume schemas - which is what makes the Gate 2 hard-block
+ *   structural: when any referee verdict is "disagree", the replay-verify
+ *   resume schema literally only admits { decision: "abort" }. Mastra's own
+ *   resume validation rejects an accept; no runtime flag to lose across a
+ *   snapshot rehydration, no advisory check an agent could talk its way past.
+ *
+ * - STUDY-CONTENT FAILURES SURFACE AS GATE FAILURES. A malformed study
+ *   (BAD_INTERCHANGE), a tolerance above the host ceiling
+ *   (TOLERANCE_CEILING_EXCEEDED), an unresolvable or ambiguous segment
+ *   (SEGMENT_UNRESOLVED / SEGMENT_AMBIGUOUS), an incoherent selection under
+ *   refuse strictness (INCOHERENT_SELECTION), or an empty study (EMPTY_STUDY)
+ *   never throws out of promoteStudy itself: the captured error is thrown
+ *   from Gate 1's gatherEvidence, so the run fails AT the study-intake gate
+ *   with the named error, where the host's gate UI can render it.
+ *   promoteStudy throws synchronously only for programmer errors
+ *   (BAD_PROMOTION_OPTIONS: missing deps, non-positive ceiling, ...).
+ *
+ * - DATA REVIEW CHOICE (documented per plan task B2): where a segment group
+ *   contains exactly one paid and one incurred triangle, the full
+ *   @actuarial-ts/data reviewTriangles pair review runs (it includes the
+ *   per-triangle monotonicity and interior-missing checks). Every other core
+ *   loss triangle gets the per-triangle STRUCTURAL subset of those checks
+ *   (non-decreasing cumulative rows, interior missing cells), reported in the
+ *   same DataReviewReport shape. Non-core measures (earnedPremium, custom:*)
+ *   are exposure/reference data, not loss triangles: their review is reported
+ *   "not-evaluated" rather than silently passed - unless a selection
+ *   references one, which fails intake (BAD_INTERCHANGE from the converter).
+ *   Review findings, including fail-status checks, are EVIDENCE for the human
+ *   intake decision, not automatic blocks; only the named error classes above
+ *   block mechanically. The recommendation says so when checks fail.
+ *
+ * - PURITY. This module never reads a clock; options.now supplies every
+ *   timestamp (envelope createdAt at construction, ledger timestamps at
+ *   resume). The tenant seam is untouched: deps close over the host's own
+ *   authenticated context, and nothing model-facing exists here at all.
+ *
+ * FOOTGUN (inherited from createJudgmentChain): the returned workflow exposes
+ * .then(step), making it an ACCIDENTAL THENABLE. Never await promoteStudy's
+ * return value and never return it from an async function - assign it
+ * synchronously and register it on a Mastra instance.
+ */
+import { type LdfSelections } from "@actuarial-ts/core";
+import { type CoherenceCheck, type CrosscheckReportDoc, type SelectionDoc, type StudyBody } from "@actuarial-ts/interchange";
+import { type DataReviewReport } from "@actuarial-ts/data";
+import { type JudgmentChainWorkflow } from "./judgment.js";
+/**
+ * The host-adapter seam (spec 6 Gate 4; the workbench adapter arrives with
+ * plan task B4). resolveSegment is SYNCHRONOUS so promoteStudy can stay
+ * synchronous (the accidental-thenable footgun forbids async construction);
+ * the mutation hooks may be async - they run inside gate execution.
+ */
+export interface PromoteStudyDeps {
+    /**
+     * Maps a selection's triangle segment labels to exactly one host workspace
+     * target, or null when nothing matches (v1: no fuzzy matching). A
+     * single-segment host returns its only target regardless of labels.
+     */
+    resolveSegment(labels: Record<string, string>): string | null;
+    /**
+     * Applies one promoted selection through the host's service layer.
+     * `replayedSelections` is the core LdfSelections the replay verified;
+     * `segmentTarget` is the resolved workspace target (a two-parameter
+     * implementation that closes over its single segment may ignore it).
+     */
+    applySelections(selectionDoc: SelectionDoc, replayedSelections: LdfSelections, segmentTarget: string): Promise<void> | void;
+    /** Reruns the host analysis after the selections are applied. */
+    runAnalysis(label: string): Promise<void> | void;
+    /** Persists a completion note (called twice: trail, then ledger JSON). */
+    persistNote(text: string, author: string): Promise<void> | void;
+}
+/** Context handed to the rationale-drafting hook. */
+export interface DraftRationaleContext {
+    study: StudyBody;
+    studyIntegrity: string;
+    intake: StudyIntakeEvidence;
+    replay: ReplayVerifyEvidence;
+}
+export interface PromoteStudyOptions {
+    /**
+     * The host's replay-tolerance ceiling. The EFFECTIVE tolerance is
+     * min(study replayTolerance, ceiling); a study STATING a tolerance above
+     * the ceiling fails intake (tolerance editing is not an escape hatch).
+     */
+    toleranceCeiling: number;
+    /** Actor recorded when a resume payload names none. Default "actuary". */
+    actorDefault?: string;
+    /** Host-injected clock (purity: this package never reads Date). */
+    now: () => string;
+    /**
+     * Coherence/integrity strictness for intake. Default "refuse" (promotion
+     * is a refuse-mode consumer per spec 3.2); "warn" downgrades divergence
+     * to evidence warnings.
+     */
+    strictness?: "warn" | "refuse";
+    /**
+     * Injection hook for agent-assisted rationale drafting (spec 9.2 arrives
+     * later); the default assembles a template from the study narrative. The
+     * human always owns the final text - this drafts, never decides.
+     */
+    draftRationale?: (ctx: DraftRationaleContext) => Promise<string> | string;
+}
+/** Prominent tolerance block (spec 6 Gate 1). */
+export interface ReplayToleranceEvidence {
+    /** expectations.replayTolerance as stated, or null when the study omits it. */
+    stated: number | null;
+    /** The convention-profile default the 10x flag is measured against. */
+    profileId: string;
+    profileDefault: number;
+    /** true when the stated tolerance exceeds 10x the profile default. */
+    exceedsTenTimesProfileDefault: boolean;
+    /** The host ceiling from options. */
+    ceiling: number;
+    /** min(stated ?? profileDefault, ceiling): what Gate 2 referees at. */
+    effective: number;
+}
+export interface TriangleReviewEvidence {
+    /** paired-asop23 = reviewTriangles on a paid/incurred pair; structural =
+     * per-triangle checks; not-evaluated = non-core measure. */
+    mode: "paired-asop23" | "structural" | "not-evaluated";
+    triangles: {
+        integrity: string;
+        measure: string;
+    }[];
+    report: DataReviewReport;
+}
+export interface SegmentResolutionEvidence {
+    selectionIntegrity: string;
+    labels: Record<string, string>;
+    target: string;
+}
+export interface SelectionCoherenceEvidence {
+    selectionIntegrity: string;
+    triangleIntegrity: string;
+    coherence: CoherenceCheck;
+}
+export interface StudyIntakeEvidence {
+    study: {
+        title: string;
+        analyst: string | null;
+        sourceRef: string | null;
+        summary: string;
+        integrity: string;
+    };
+    /** FIRST, on purpose: the spec requires prominent display. */
+    replayTolerance: ReplayToleranceEvidence;
+    dataReview: TriangleReviewEvidence[];
+    coherence: SelectionCoherenceEvidence[];
+    segments: SegmentResolutionEvidence[];
+    warnings: string[];
+    /**
+     * ALWAYS populated: the verification-scope disclosure. Coherence, replay,
+     * and referee all verify the study against its OWN embedded triangle;
+     * whether that triangle IS the host workspace's book of business is not
+     * machine-verified anywhere in the chain. Stating this in the evidence
+     * keeps the gates honest about what they checked - the data-binding
+     * judgment belongs to the reviewing actuary, and the UI must say so
+     * rather than let "verified" read wider than it is.
+     */
+    workspaceBindingNote: string;
+}
+/** Per replay target: how this shore verified it (spec 3.2 capabilities). */
+export interface ReplayTargetLabel {
+    /** "12-24" for a development interval, or "tail". */
+    target: string;
+    /** exact = independently recomputed; value-only = applied as stated. */
+    capability: "exact" | "value-only";
+    /** The disclosure-honest label: replayed-exact or verified-by-value. */
+    label: "replayed-exact" | "verified-by-value";
+    note?: string;
+}
+export interface SelectionReplayEvidence {
+    selectionIntegrity: string;
+    triangleIntegrity: string;
+    segmentTarget: string;
+    targets: ReplayTargetLabel[];
+    /** Every intent judgmental/external: the whole replay is value transport. */
+    verifiedByValueOnly: boolean;
+    replayTotals: {
+        ultimate: number;
+        unpaid: number;
+    };
+}
+export interface SupportingCrosscheckEvidence {
+    resultIntegrity: string;
+    engine: {
+        name: string;
+        version: string;
+    };
+    /** null when the result could not be refereed (see reason). */
+    verdict: "agree" | "disagree" | "not-comparable" | "verified-by-value" | null;
+    report: CrosscheckReportDoc | null;
+    reason?: string;
+}
+export interface ReplayVerifyEvidence {
+    effectiveTolerance: number;
+    replays: SelectionReplayEvidence[];
+    crosschecks: SupportingCrosscheckEvidence[];
+    /** Any crosscheck verdict "disagree": the gate cannot accept (spec 6). */
+    hardBlocked: boolean;
+    /** States exactly what the verification consisted of - including, when the
+     * study carried no supportingResults, that it was coherence + replay only. */
+    verification: string;
+}
+export interface RationaleEvidence {
+    draftRationale: string;
+    attestationRequired: true;
+    study: {
+        title: string;
+        sourceRef: string | null;
+        analyst: string | null;
+    };
+}
+export interface ApplyEvidence {
+    applications: {
+        segmentTarget: string;
+        selectionIntegrity: string;
+        developmentCount: number;
+        tailFactor: number;
+    }[];
+    analysisLabel: string;
+    ledgerSource: string;
+}
+/** The workflow id promoteStudy builds its chain with. */
+export declare const PROMOTION_CHAIN_ID = "promote-study";
+/** See StudyIntakeEvidence.workspaceBindingNote; one constant so every
+ * intake states the same scope, verbatim. */
+export declare const WORKSPACE_BINDING_NOTE: string;
+/**
+ * Builds the promotion judgment chain for one study. SYNCHRONOUS by design
+ * (see the accidental-thenable footgun in the module doc): assign the return
+ * value and register it on a Mastra instance, exactly like any
+ * createJudgmentChain workflow; then createRun/start/resume drive the gates.
+ *
+ * Reconstruction contract: promoteStudy(deps, studyDoc, options) is
+ * deterministic given the study document and deps.resolveSegment, so a host
+ * resuming a snapshot after a restart rebuilds the identical chain.
+ */
+export declare function promoteStudy(deps: PromoteStudyDeps, studyDoc: unknown, options: PromoteStudyOptions): JudgmentChainWorkflow;
+//# sourceMappingURL=promotion.d.ts.map

package/dist/promotion.d.ts.map

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