@actuarial-ts/agents 0.5.0 → 0.6.1

package/README.md

@@ -1,156 +1,60 @@
 # @actuarial-ts/agents
 
-Mastra agent toolkit for the actuarial-ts SDK: typed actuarial tools with a hard tenant seam, human-gated judgment workflows that write the compliance assumption ledger, a four-gate study-promotion chain (`promoteStudy`), a remote-engine bridge (`defineRemoteMethod`) with a referee divergence explainer, a fail-closed MCP tenant seam, a reserving advisor factory, and a golden-prompt eval harness.
+Mastra tools and human-gated workflows for actuarial-ts. It is an orchestration boundary around the other four packages, not an autonomous actuary.
 
-The package generalizes the agent architecture proven in the ActNG reserving workbench. Its core idea: when an agent participates in an actuarial analysis, the documentation ASOP 41 asks for should fall out of RUNNING the analysis, not be reconstructed afterwards. Judgment chains built here write an `@actuarial-ts/compliance` assumption ledger as decisions are made, so a completed chain hands back a ledger ready for `generateDisclosure`.
-
-These utilities are designed to support the actuary's compliance with the ASOPs; responsibility for compliance remains with the credentialed actuary.
-
-## Install
-
-```sh
-npm install @actuarial-ts/agents @mastra/core zod
-# plus @mastra/mcp if you use the MCP surface:
-npm install @mastra/mcp
-```
-
-`@mastra/core` (>= 1.49, < 2), `zod` (^3.25), and `@mastra/mcp` (>= 1.14, < 2) are peer dependencies: the HOST application owns the Mastra version. `@mastra/mcp` is only needed if you use the MCP surface. `@actuarial-ts/core`, `@actuarial-ts/interchange`, `@actuarial-ts/data`, and `@actuarial-ts/compliance` are regular dependencies, installed for you.
-
-## Security model
-
-The tenant id (project id) reaches tools ONLY via the server-set request context, never from the model. The package enforces the seam at both ends:
-
-- `tenantOf(context, key = "projectId")` reads the tenant from `context.requestContext`, set server-side from the authenticated request. Missing, non-string, or empty ids throw a typed `AgentsError("NO_TENANT_CONTEXT")`, which the tool wrapper converts to a failure envelope.
-- `defineActuarialTool` REJECTS, at definition time, any input schema declaring a tenant-id key (`projectId`, `tenantId`, `project_id`, ... in any casing) with `AgentsError("TENANT_IN_SCHEMA")`. The model must not even be able to express a tenant id.
-
-Tools never throw into the model. Anything the tool body throws becomes:
-
-```ts
-{ success: false, error: { code: string, message: string } }
-```
-
-Errors carrying a string `code` property (HTTP-style coded errors, `AgentsError`, `ComplianceError`) keep their code so the agent can recover deliberately: retry with adjusted parameters, suggest an alternative, or ask.
-
-```ts
-import { defineActuarialTool, tenantOf, toolRegistry } from "@actuarial-ts/agents";
-import { z } from "zod";
-
-const getOverview = defineActuarialTool({
-  id: "get_workspace_overview",
-  description: "Orient yourself in the workspace",
-  kind: "read", // or "action" for state-mutating tools
-  inputSchema: z.object({}),
-  execute: async (_input, context) => {
-    const projectId = tenantOf(context);
-    return { success: true, ...loadOverview(projectId) };
-  },
-});
-
-const { tools, actionToolIds } = toolRegistry([getOverview /* , ... */]);
-// tools     -> Record keyed by id, ready for new Agent({ tools })
-// actionToolIds -> the host client refreshes after these run
+```bash
+npm install @actuarial-ts/agents@0.6.1 @actuarial-ts/core@0.6.1 @actuarial-ts/data@0.6.1 @actuarial-ts/interchange@0.6.1 @actuarial-ts/compliance@0.6.1 @mastra/core@^1.51.0 @mastra/mcp@^1.14.0 zod@^3.25.76
 ```
 
-## Judgment chains: propose, justify, approve, record
-
-`createJudgmentChain` turns an ordered list of `JudgmentGateSpec`s into a committed Mastra workflow that pauses at EVERY actuarial judgment:
+Requires Node 22.13+. Peer ranges are `@mastra/core >=1.51.0 <2`, `@mastra/mcp >=1.14.0 <2`, and Zod `^3.25.76`.
 
-1. **Propose.** The gate gathers evidence through your service layer and suspends with `{ stage, recommendation, evidence }`.
-2. **Justify and approve.** A human decides; the resume payload carries the decision plus a VERBATIM rationale (schemas without a `rationale` key are rejected at definition time; blank rationales fail the gate at runtime).
-3. **Record.** `applyDecision` applies the decision through your service layer and returns the assumptions it fixed; the chain appends them to the threaded ledger with the rationale, the actor from the payload's optional `actor` field (default `"actuary"`), and a timestamp from the host-injected `now()` (the package never reads a clock).
+## Trusted diagnostic selection
 
-A gate may also self-skip (`skipWhen`) based on earlier gates' decisions, recording a skip note in the trail - the shape the ActNG ELR derivation uses when the cap gate chose to stay unlimited and the restoration gate becomes moot.
+`createDiagnosticSelectionTool` lets a model choose only reviewed instance IDs, one host-approved run preset, and a display view. The host owns the authentic compiled definition, allowable instance catalog, cutoff/filter/grouping policy, tenant, data access, and executor.
 
 ```ts
-import { createJudgmentChain } from "@actuarial-ts/agents";
-import { generateDisclosure } from "@actuarial-ts/compliance";
-import { Mastra } from "@mastra/core/mastra";
-
-const chain = createJudgmentChain({
-  id: "derive-expected-losses",
-  gates: [capGate, ilfGate, trendGate, elrGate],
-  now: () => new Date().toISOString(), // the host owns the clock
-  onComplete: async ({ trail, ledger }, ctx) => {
-    persistTrailNote(tenantOf(ctx), trail, ledger);
-  },
-});
-
-// Register for snapshot storage (suspend/resume state lives there; durable
-// storage keeps paused chains resumable across restarts).
-const mastra = new Mastra({ workflows: { chain }, storage });
-
-const run = await mastra.getWorkflow("chain").createRun();
-let state = await run.start({ inputData: {}, requestContext }); // suspended at gate 1
-state = await run.resume({
-  step: "cap-gate",
-  resumeData: { decision: "accept", cap: 150_000, rationale: "volatile large losses distort development" },
-  requestContext,
+import { createDiagnosticSelectionTool } from "@actuarial-ts/agents";
+
+const tool = createDiagnosticSelectionTool({
+  definition: compiledDefinition,
+  runPresets: [{
+    id: "annual-review-v1",
+    definitionIntegrity: compiledDefinition.definitionIntegrity,
+    allowedInstanceIds: ["casualty/count/reported-frequency"],
+    execute: ({ tenantId, instanceIds }) => runApprovedPreset({ tenantId, instanceIds }),
+  }],
 });
-// ... resume each gate; the final result is { trail, ledger }
 ```
 
-### The ledger fusion
-
-The completed chain's `ledger` is a real `@actuarial-ts/compliance` `AssumptionLedger`: every human decision is an `AssumptionEntry` with actor, verbatim rationale, and caller-supplied timestamp. Feed it straight into the disclosure pipeline:
+The strict model input contains only:
 
 ```ts
-const { trail, ledger } = finalResult;
-const disclosure = generateDisclosure({
-  metadata,   // EstimateMetadata for the analysis
-  methods,    // MethodUse[]
-  ledger,     // the chain's fused ledger, judgments and rationales included
-  sdkVersion,
-  generatedAt: now(),
-});
+type DiagnosticAgentToolInput = {
+  runPresetId: string;
+  instanceIds: string[];
+  view: "emergence" | "triangles" | "latest-diagonal";
+};
 ```
 
-ASOP 41 assumptions-and-judgments documentation as a side effect of running the analysis.
-
-### Footgun: workflows are accidental thenables
+It cannot contain formulas, measures, count populations, amount/exposure bases, missingness, period axes, arbitrary filters, provenance, or project/tenant IDs. The executor must return owner-authenticated `VerifiedDiagnosticRunProvenance` stamped for the exact definition, preset, and sorted selection; a cached superset is rejected rather than display-filtered into an apparent run.
 
-A Mastra `Workflow` exposes a `.then(step)` builder method, so `await chain` (or returning a workflow from an `async` function) makes JavaScript treat it as a thenable and the promise NEVER settles. Assign the chain synchronously and register it on your Mastra instance.
+Success returns `{ success: true, data: { ... } }`. The `data` object contains formula/calculation/definition identities, run/result/binding fingerprints, the full review receipt (including triggered and not-evaluated rules), and one explicitly display-only projection. `data.display.points` holds emergence or latest-diagonal points; `data.display.triangles` holds the triangle view. Display points retain reviewed metric evaluations and findings while omitting the raw aggregate `components` field. Failures remain `{ success: false, error: { code, message } }`.
 
-## Reserving advisor factory
+The v0.6.1 correction uses `runPresets` in the host catalog and `tenantId` in the host executor input. Migrate the earlier `presets`, `tenant`, flattened success fields, and `display.value` names to the contract above. There is no definition-editing path; changing a basis or rule requires a separate human-governed workflow.
 
-`createReservingAdvisor` assembles an `@mastra/core` Agent on a hardened base instruction template: professional grounding, every-number-from-a-tool-result, read-before-recommend ordering, action consent, failure recovery, and selection-of-ultimates weighting guidance. Host domain sections splice in between the base analytics and the conduct section.
+## Tool boundary
 
-The template is auditable by construction: `BASE_INSTRUCTIONS` exports the named sections and `assembleInstructions` is a pure deterministic string function, so hosts can byte-inspect (and snapshot-test) the exact prompt their agent runs on.
+`defineActuarialTool` enforces two shared rules. First, required tenant identity is resolved from trusted request context before the body runs; the model schema cannot express a project/tenant key. Second, every failure is a recursively readonly `{ success: false, error: { code, message } }` result rather than a thrown model-visible exception.
 
-```ts
-import { createReservingAdvisor, assembleInstructions } from "@actuarial-ts/agents";
-
-const advisor = createReservingAdvisor({
-  model: anthropic("claude-sonnet-4-5"),
-  tools,
-  memory,
-  domainInstructions: [ldfSelectionGuide, cappingGuide, tailGuide],
-});
-
-// What is this agent actually running on? Byte-inspect it:
-const prompt = assembleInstructions({ domainInstructions: [ldfSelectionGuide, cappingGuide, tailGuide] });
-```
+In 0.6 the public `DefinedActuarialTool<TInput, TOutput>` execute accepts raw `z.input`, parses exactly once, gives the body `z.output`, and returns only the body result or `ToolEnvelopeFailure`. Input/output schemas remain attached through identity-validation metadata bridges whose JSON Schema matches the private real Zod schema, so Mastra cannot run transforms twice. Invalid input is `TOOL_INPUT_INVALID`; malformed/undefined output is `TOOL_OUTPUT_INVALID`. A supplied output schema must accept and preserve the complete failure union or construction throws `BAD_OUTPUT_SCHEMA`. Failure envelopes cannot be rewritten by conditional transforms.
 
-## Eval harness
+## Human judgment and remote engines
 
-`runToolSelectionEvals` asserts tool SELECTION, not prose: each golden case lists the tools that must appear among the turn's calls. Running against a real agent costs live API tokens, so keep it opt-in (an env flag in a script, never in package tests).
+`createJudgmentChain` suspends at declared gates, requires a rationale on resume, records the authenticated actor identity, and writes the compliance assumption ledger. `createReservingAdvisor` assembles a constrained Mastra advisor. `defineRemoteMethod` calls an authenticated interchange sidecar with timeouts, abort support, client-side document validation, and the same tenant/failure seam. Promotion workflows replay and referee imported studies before any selection can enter a workspace.
 
-```ts
-import { runToolSelectionEvals } from "@actuarial-ts/agents";
-
-const report = await runToolSelectionEvals({
-  agent: advisor,
-  requestContext,
-  cases: [
-    { id: "cap-evidence", prompt: "Should we cap this book? Check the claim-size evidence first.", expectTools: ["analyze_claim_sizes"] },
-    { id: "elr-select", prompt: "Select an expected loss ratio of 65%.", expectTools: ["set_elr"] },
-  ],
-  timeoutMs: 180_000, // a stalled stream fails the case, not the suite
-});
-// report.results: per-case { id, pass, called, missing, error? }
-// report.summary: { total, passed, failed }
-```
+The package’s offline test suite covers trusted catalog selection, direct/Mastra-shaped execution, tenant failure, once-only transforms, provenance coherence, judgment gates, remote sidecar behavior, promotion, and golden-prompt tool selection.
 
-The `agent` parameter is typed structurally (anything with a `stream()` yielding a `fullStream`), so the harness itself is testable with a stubbed agent and canned chunks - no LLM, no network.
+See the [formula catalog](https://github.com/yerromnitsuj/actng/blob/v0.6.1/docs/reference/diagnostic-formulas.md) and [migration guide](https://github.com/yerromnitsuj/actng/blob/v0.6.1/docs/migrations/0.6-generalized-diagnostics.md).
 
 ## License
 

package/dist/diagnostics.d.ts

@@ -0,0 +1,69 @@
+import { type CompiledDiagnosticDefinition, type DiagnosticDeepReadonly } from "@actuarial-ts/core";
+import { type VerifiedDiagnosticRunProvenance } from "@actuarial-ts/compliance";
+import { z } from "zod";
+import { type DefinedActuarialTool, type ToolEnvelopeFailure } from "./tools.js";
+export declare const diagnosticAgentToolInputSchema: z.ZodObject<{
+    runPresetId: z.ZodEffects<z.ZodString, string, string>;
+    instanceIds: z.ZodType<readonly string[], z.ZodTypeDef, readonly string[]>;
+    view: z.ZodEnum<["emergence", "triangles", "latest-diagonal"]>;
+}, "strict", z.ZodTypeAny, {
+    runPresetId: string;
+    instanceIds: readonly string[];
+    view: "emergence" | "triangles" | "latest-diagonal";
+}, {
+    runPresetId: string;
+    instanceIds: readonly string[];
+    view: "emergence" | "triangles" | "latest-diagonal";
+}>;
+export type DiagnosticAgentView = "emergence" | "triangles" | "latest-diagonal";
+export interface DiagnosticAgentToolInput {
+    readonly runPresetId: string;
+    readonly instanceIds: readonly string[];
+    readonly view: DiagnosticAgentView;
+}
+export interface DiagnosticAgentPresetExecutionInput {
+    readonly tenantId: string;
+    readonly instanceIds: readonly string[];
+}
+export interface DiagnosticAgentRunPreset {
+    readonly id: string;
+    readonly definitionIntegrity: string;
+    readonly allowedInstanceIds: readonly string[];
+    readonly execute: (input: DiagnosticAgentPresetExecutionInput) => Promise<VerifiedDiagnosticRunProvenance>;
+}
+export interface CreateDiagnosticSelectionToolInput {
+    readonly definition: CompiledDiagnosticDefinition;
+    readonly runPresets: readonly DiagnosticAgentRunPreset[];
+    readonly id?: string;
+    readonly description?: string;
+    readonly tenantContextKey?: string;
+}
+export type DiagnosticAgentDisplayProjection = {
+    readonly view: "emergence" | "latest-diagonal";
+    readonly points: readonly DiagnosticAgentDisplayPoint[];
+} | {
+    readonly view: "triangles";
+    readonly triangles: VerifiedDiagnosticRunProvenance["result"]["triangles"];
+};
+export type DiagnosticAgentDisplayPoint = Omit<VerifiedDiagnosticRunProvenance["result"]["emergence"][number], "components">;
+export interface DiagnosticAgentToolSuccess {
+    readonly success: true;
+    readonly data: {
+        readonly runPresetId: string;
+        readonly instanceIds: readonly string[];
+        readonly definitionIntegrity: string;
+        readonly formulaFingerprints: Readonly<Record<string, string>>;
+        readonly calculationFingerprints: Readonly<Record<string, string>>;
+        readonly runFingerprint: string;
+        readonly resultFingerprint: string;
+        readonly runResultFingerprint: string;
+        readonly review: VerifiedDiagnosticRunProvenance["review"];
+        readonly display: DiagnosticAgentDisplayProjection;
+    };
+}
+export type DiagnosticAgentToolResult = DiagnosticDeepReadonly<DiagnosticAgentToolSuccess> | ToolEnvelopeFailure;
+/** Strict model-visible output schema, including the wrapper's failure branch. */
+export declare const diagnosticAgentToolResultSchema: z.ZodType<DiagnosticAgentToolResult>;
+export type DiagnosticSelectionTool = DefinedActuarialTool<DiagnosticAgentToolInput, DiagnosticAgentToolResult>;
+export declare function createDiagnosticSelectionTool(input: CreateDiagnosticSelectionToolInput): DiagnosticSelectionTool;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

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