@actuarial-ts/agents 0.7.0 → 0.8.0

package/README.md

@@ -3,11 +3,16 @@
 Mastra tools and human-gated workflows for actuarial-ts. It is an orchestration boundary around the other four packages, not an autonomous actuary.
 
 ```bash
-npm install @actuarial-ts/agents@0.7.0 @actuarial-ts/core@0.7.0 @actuarial-ts/data@0.7.0 @actuarial-ts/interchange@0.7.0 @actuarial-ts/compliance@0.7.0 @mastra/core@^1.51.0 @mastra/mcp@^1.14.0 zod@^3.25.76
+npm install @actuarial-ts/agents@0.8.0 @actuarial-ts/core@0.8.0 @actuarial-ts/data@0.8.0 @actuarial-ts/interchange@0.8.0 @actuarial-ts/compliance@0.8.0 @mastra/core@^1.51.0 @mastra/mcp@^1.14.0 zod@^3.25.76
 ```
 
 Requires Node 22.13+. Peer ranges are `@mastra/core >=1.51.0 <2`, `@mastra/mcp >=1.14.0 <2`, and Zod `^3.25.76`.
 
+SDK 0.8 adds a closed customization selection tool: the model selects only a
+host-approved preset and allowlisted scenario IDs, while tenant identity stays
+in trusted request context. See the [0.8 adoption guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.8-reusable-customization.md)
+and [customization reference](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/reusable-customization.md).
+
 ## Trusted diagnostic selection
 
 `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.
@@ -38,6 +43,17 @@ type DiagnosticAgentToolInput = {
 
 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.
 
+This executor remains **eager-only** in SDK 0.8. The compact diagnostics APIs
+introduced in 0.7.0 do not change its return contract:
+`VerifiedCompactDiagnosticRunProvenance` and streamed replay receipts cannot be
+returned in place of eager verified provenance. Keep this tool's approved
+executor on the eager validated-run/provenance path. Compact analysis and
+paged evidence can be hosted separately through the public core/data/compliance
+APIs; casting or display-filtering a compact result does not authorize a tool
+response. See the [compact adoption guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.7-compact-diagnostics.md)
+for the distinct workflows and [replay reference](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/diagnostic-replay-stream.md)
+for evidence verification and its SDK-version requirements.
+
 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 } }`.
 
 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.
@@ -54,7 +70,7 @@ In 0.6 the public `DefinedActuarialTool<TInput, TOutput>` execute accepts raw `z
 
 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.
 
-See the [formula catalog](https://github.com/yerromnitsuj/actng/blob/v0.7.0/docs/reference/diagnostic-formulas.md) and [migration guide](https://github.com/yerromnitsuj/actng/blob/v0.7.0/docs/migrations/0.6-generalized-diagnostics.md).
+See the [formula catalog](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/diagnostic-formulas.md) and [migration guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.6-generalized-diagnostics.md).
 
 ## License
 

package/dist/customization.d.ts

@@ -0,0 +1,122 @@
+import { type AnalysisResult } from "@actuarial-ts/core";
+import { z } from "zod";
+import { type DefinedActuarialTool } from "./tools.js";
+export declare const customizationAgentToolInputSchema: z.ZodObject<{
+    runPresetId: z.ZodEffects<z.ZodString, string, string>;
+    scenarioIds: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+}, "strict", z.ZodTypeAny, {
+    runPresetId: string;
+    scenarioIds: string[];
+}, {
+    runPresetId: string;
+    scenarioIds: string[];
+}>;
+export interface CustomizationAgentPresetResult {
+    readonly scenarioId: string;
+    readonly result: AnalysisResult;
+}
+export interface CustomizationAgentRunPreset {
+    readonly id: string;
+    readonly recipeId: string;
+    readonly allowedScenarioIds: readonly string[];
+    readonly execute: (input: {
+        readonly tenantId: string;
+        readonly scenarioIds: readonly string[];
+    }) => Promise<readonly CustomizationAgentPresetResult[]>;
+}
+export interface CustomizationAgentToolSuccess {
+    readonly success: true;
+    readonly data: {
+        readonly runPresetId: string;
+        readonly recipeId: string;
+        readonly scenarioIds: readonly string[];
+        readonly results: readonly CustomizationAgentPresetResult[];
+    };
+}
+export declare const customizationAgentToolResultSchema: z.ZodUnion<[z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        runPresetId: z.ZodEffects<z.ZodString, string, string>;
+        recipeId: z.ZodEffects<z.ZodString, string, string>;
+        scenarioIds: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+        results: z.ZodArray<z.ZodObject<{
+            scenarioId: z.ZodEffects<z.ZodString, string, string>;
+            result: z.ZodType<AnalysisResult, z.ZodTypeDef, AnalysisResult>;
+        }, "strict", z.ZodTypeAny, {
+            scenarioId: string;
+            result: AnalysisResult;
+        }, {
+            scenarioId: string;
+            result: AnalysisResult;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        runPresetId: string;
+        scenarioIds: string[];
+        recipeId: string;
+        results: {
+            scenarioId: string;
+            result: AnalysisResult;
+        }[];
+    }, {
+        runPresetId: string;
+        scenarioIds: string[];
+        recipeId: string;
+        results: {
+            scenarioId: string;
+            result: AnalysisResult;
+        }[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    data: {
+        runPresetId: string;
+        scenarioIds: string[];
+        recipeId: string;
+        results: {
+            scenarioId: string;
+            result: AnalysisResult;
+        }[];
+    };
+    success: true;
+}, {
+    data: {
+        runPresetId: string;
+        scenarioIds: string[];
+        recipeId: string;
+        results: {
+            scenarioId: string;
+            result: AnalysisResult;
+        }[];
+    };
+    success: true;
+}>, z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        code: string;
+        message: string;
+    }, {
+        code: string;
+        message: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+    };
+    success: false;
+}, {
+    error: {
+        code: string;
+        message: string;
+    };
+    success: false;
+}>]>;
+export declare function createCustomizationSelectionTool(input: {
+    readonly runPresets: readonly CustomizationAgentRunPreset[];
+    readonly id?: string;
+    readonly description?: string;
+    readonly tenantContextKey?: string;
+}): DefinedActuarialTool<z.input<typeof customizationAgentToolInputSchema>, z.output<typeof customizationAgentToolResultSchema>>;
+//# sourceMappingURL=customization.d.ts.map

package/dist/customization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customization.d.ts","sourceRoot":"","sources":["../src/customization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,iCAAiC;;;;;;;;;EAGnC,CAAC;AAEZ,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;KACzC,KAAK,OAAO,CAAC,SAAS,8BAA8B,EAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,8BAA8B,EAAE,CAAC;KAC7D,CAAC;CACH;AAMD,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAW7C,CAAC;AAEH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,QAAQ,CAAC,UAAU,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC5D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC,GAAG,oBAAoB,CACtB,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,EACjD,CAAC,CAAC,MAAM,CAAC,OAAO,kCAAkC,CAAC,CACpD,CAmDA"}

package/dist/customization.js

@@ -0,0 +1,79 @@
+import { isDiagnosticToken } from "@actuarial-ts/core";
+import { analysisResultSchema, parseAnalysisResult } from "@actuarial-ts/data";
+import { z } from "zod";
+import { AgentsError } from "./errors.js";
+import { defineActuarialTool, } from "./tools.js";
+const token = z.string().refine(isDiagnosticToken);
+export const customizationAgentToolInputSchema = z.object({
+    runPresetId: token,
+    scenarioIds: z.array(token).max(32),
+}).strict();
+const failureSchema = z.object({
+    success: z.literal(false),
+    error: z.object({ code: z.string(), message: z.string() }).strict(),
+}).strict();
+export const customizationAgentToolResultSchema = z.union([
+    z.object({
+        success: z.literal(true),
+        data: z.object({
+            runPresetId: token,
+            recipeId: token,
+            scenarioIds: z.array(token),
+            results: z.array(z.object({ scenarioId: token, result: analysisResultSchema }).strict()),
+        }).strict(),
+    }).strict(),
+    failureSchema,
+]);
+export function createCustomizationSelectionTool(input) {
+    const catalog = new Map();
+    for (const preset of input.runPresets) {
+        if (!isDiagnosticToken(preset.id) || !isDiagnosticToken(preset.recipeId))
+            throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", "Customization preset id and recipeId must be valid tokens");
+        if (catalog.has(preset.id))
+            throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", `Duplicate customization preset ${preset.id}`);
+        if (new Set(preset.allowedScenarioIds).size !== preset.allowedScenarioIds.length || preset.allowedScenarioIds.some((id) => !isDiagnosticToken(id)))
+            throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", `Preset ${preset.id} has invalid or duplicate scenario IDs`);
+        catalog.set(preset.id, Object.freeze({ ...preset, allowedScenarioIds: Object.freeze([...preset.allowedScenarioIds].sort()) }));
+    }
+    return defineActuarialTool({
+        id: input.id ?? "run-approved-customization",
+        description: input.description ?? "Run a host-approved actuarial recipe and approved scenarios",
+        kind: "read",
+        tenant: "required",
+        tenantKey: input.tenantContextKey ?? "projectId",
+        inputSchema: customizationAgentToolInputSchema,
+        outputSchema: customizationAgentToolResultSchema,
+        execute: async (request, tenant) => {
+            const preset = catalog.get(request.runPresetId);
+            if (preset === undefined)
+                throw new AgentsError("UNKNOWN_CUSTOMIZATION_PRESET", `Unknown customization preset ${request.runPresetId}`);
+            if (new Set(request.scenarioIds).size !== request.scenarioIds.length)
+                throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Requested scenario IDs must be unique");
+            const scenarioIds = [...request.scenarioIds].sort();
+            if (scenarioIds.some((id) => !preset.allowedScenarioIds.includes(id)))
+                throw new AgentsError("UNAPPROVED_CUSTOMIZATION_SCENARIO", "One or more requested scenarios are not approved by the selected preset");
+            const rawResults = await preset.execute({ tenantId: tenant, scenarioIds });
+            const byId = new Map();
+            for (const item of rawResults) {
+                if (!scenarioIds.includes(item.scenarioId) || byId.has(item.scenarioId))
+                    throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor returned an unexpected or duplicate scenario result");
+                const result = parseAnalysisResult(item.result);
+                if (result.recipeId !== preset.recipeId)
+                    throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor returned a result for another recipe");
+                byId.set(item.scenarioId, result);
+            }
+            if (byId.size !== scenarioIds.length)
+                throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor omitted an exact requested scenario result");
+            return {
+                success: true,
+                data: {
+                    runPresetId: preset.id,
+                    recipeId: preset.recipeId,
+                    scenarioIds,
+                    results: scenarioIds.map((scenarioId) => ({ scenarioId, result: byId.get(scenarioId) })),
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=customization.js.map

package/dist/customization.js.map

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

package/dist/errors.d.ts

@@ -10,7 +10,7 @@
  * thrown during tool execution into a { success: false, error } envelope.
  */
 /** Every machine-readable code an AgentsError can carry. */
-export declare const AGENTS_ERROR_CODES: readonly ["NO_TENANT_CONTEXT", "TENANT_IN_SCHEMA", "BAD_INPUT_SCHEMA", "BAD_GATE", "MISSING_RATIONALE", "DUPLICATE_TOOL_ID", "BAD_PROMOTION_OPTIONS", "EMPTY_STUDY", "TOLERANCE_CEILING_EXCEEDED", "SEGMENT_UNRESOLVED", "SEGMENT_AMBIGUOUS", "VERDICT_NOT_DISAGREE", "DIVERGENCE_INPUT_MISMATCH", "NO_DIVERGENCE_EVIDENCE", "REMOTE_RESULT_INVALID", "MCP_SELF_TEST_FAILED", "BAD_DIAGNOSTIC_CATALOG", "UNKNOWN_DIAGNOSTIC_PRESET", "UNAPPROVED_DIAGNOSTIC_INSTANCE", "DIAGNOSTIC_RUN_MISMATCH", "BAD_OUTPUT_SCHEMA", "TOOL_INPUT_INVALID", "TOOL_OUTPUT_INVALID"];
+export declare const AGENTS_ERROR_CODES: readonly ["NO_TENANT_CONTEXT", "TENANT_IN_SCHEMA", "BAD_INPUT_SCHEMA", "BAD_GATE", "MISSING_RATIONALE", "DUPLICATE_TOOL_ID", "BAD_PROMOTION_OPTIONS", "EMPTY_STUDY", "TOLERANCE_CEILING_EXCEEDED", "SEGMENT_UNRESOLVED", "SEGMENT_AMBIGUOUS", "VERDICT_NOT_DISAGREE", "DIVERGENCE_INPUT_MISMATCH", "NO_DIVERGENCE_EVIDENCE", "REMOTE_RESULT_INVALID", "MCP_SELF_TEST_FAILED", "BAD_DIAGNOSTIC_CATALOG", "UNKNOWN_DIAGNOSTIC_PRESET", "UNAPPROVED_DIAGNOSTIC_INSTANCE", "DIAGNOSTIC_RUN_MISMATCH", "BAD_CUSTOMIZATION_CATALOG", "UNKNOWN_CUSTOMIZATION_PRESET", "UNAPPROVED_CUSTOMIZATION_SCENARIO", "CUSTOMIZATION_RUN_MISMATCH", "BAD_OUTPUT_SCHEMA", "TOOL_INPUT_INVALID", "TOOL_OUTPUT_INVALID"];
 export type AgentsErrorCode = (typeof AGENTS_ERROR_CODES)[number];
 /**
  * Thrown for invalid agent-toolkit input: tenant-seam violations, malformed

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,qiBAuCrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBACnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,qqBA2CrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBACnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}

package/dist/errors.js

@@ -46,6 +46,10 @@ export const AGENTS_ERROR_CODES = [
     "UNKNOWN_DIAGNOSTIC_PRESET",
     "UNAPPROVED_DIAGNOSTIC_INSTANCE",
     "DIAGNOSTIC_RUN_MISMATCH",
+    "BAD_CUSTOMIZATION_CATALOG",
+    "UNKNOWN_CUSTOMIZATION_PRESET",
+    "UNAPPROVED_CUSTOMIZATION_SCENARIO",
+    "CUSTOMIZATION_RUN_MISMATCH",
     "BAD_OUTPUT_SCHEMA",
     "TOOL_INPUT_INVALID",
     "TOOL_OUTPUT_INVALID",

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,sFAAsF;IACtF,mBAAmB;IACnB,sHAAsH;IACtH,kBAAkB;IAClB,kBAAkB;IAClB,2EAA2E;IAC3E,UAAU;IACV,iEAAiE;IACjE,mBAAmB;IACnB,8DAA8D;IAC9D,mBAAmB;IACnB,8EAA8E;IAC9E,uBAAuB;IACvB,kEAAkE;IAClE,aAAa;IACb,mFAAmF;IACnF,4BAA4B;IAC5B,6FAA6F;IAC7F,oBAAoB;IACpB,kGAAkG;IAClG,mBAAmB;IACnB,wIAAwI;IACxI,sBAAsB;IACtB,0IAA0I;IAC1I,2BAA2B;IAC3B,sIAAsI;IACtI,wBAAwB;IACxB,yIAAyI;IACzI,uBAAuB;IACvB,iLAAiL;IACjL,sBAAsB;IACtB,wBAAwB;IACxB,2BAA2B;IAC3B,gCAAgC;IAChC,yBAAyB;IACzB,mBAAmB;IACnB,oBAAoB;IACpB,qBAAqB;CACb,CAAC;AAIX;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IAC/B,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,sFAAsF;IACtF,mBAAmB;IACnB,sHAAsH;IACtH,kBAAkB;IAClB,kBAAkB;IAClB,2EAA2E;IAC3E,UAAU;IACV,iEAAiE;IACjE,mBAAmB;IACnB,8DAA8D;IAC9D,mBAAmB;IACnB,8EAA8E;IAC9E,uBAAuB;IACvB,kEAAkE;IAClE,aAAa;IACb,mFAAmF;IACnF,4BAA4B;IAC5B,6FAA6F;IAC7F,oBAAoB;IACpB,kGAAkG;IAClG,mBAAmB;IACnB,wIAAwI;IACxI,sBAAsB;IACtB,0IAA0I;IAC1I,2BAA2B;IAC3B,sIAAsI;IACtI,wBAAwB;IACxB,yIAAyI;IACzI,uBAAuB;IACvB,iLAAiL;IACjL,sBAAsB;IACtB,wBAAwB;IACxB,2BAA2B;IAC3B,gCAAgC;IAChC,yBAAyB;IACzB,2BAA2B;IAC3B,8BAA8B;IAC9B,mCAAmC;IACnC,4BAA4B;IAC5B,mBAAmB;IACnB,oBAAoB;IACpB,qBAAqB;CACb,CAAC;AAIX;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IAC/B,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export * from "./divergence.js";
 export * from "./remote.js";
 export * from "./mcp.js";
 export * from "./diagnostics.js";
+export * from "./customization.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}
+{"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,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -8,4 +8,5 @@ export * from "./divergence.js";
 export * from "./remote.js";
 export * from "./mcp.js";
 export * from "./diagnostics.js";
+export * from "./customization.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}
+{"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,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuarial-ts/agents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Mastra agent toolkit for actuarial-ts: exact validated tools with a hard tenant seam, human-gated judgment, trusted-catalog diagnostic selection, reserving advice, and evals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,17 +47,17 @@
     "prepublishOnly": "node ../../tools/release/verify-release-attestation.mjs @actuarial-ts/agents"
   },
   "dependencies": {
-    "@actuarial-ts/compliance": "^0.7.0",
-    "@actuarial-ts/core": "^0.7.0",
-    "@actuarial-ts/data": "^0.7.0",
-    "@actuarial-ts/interchange": "^0.7.0"
+    "@actuarial-ts/compliance": "^0.8.0",
+    "@actuarial-ts/core": "^0.8.0",
+    "@actuarial-ts/data": "^0.8.0",
+    "@actuarial-ts/interchange": "^0.8.0"
   },
   "devDependencies": {
     "@mastra/core": "^1.51.0",
     "@mastra/mcp": "^1.14.0",
     "@types/node": "^22.10.5",
     "typescript": "^5.7.3",
-    "vitest": "^3.0.5",
+    "vitest": "^5.0.1",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/customization.ts

@@ -0,0 +1,117 @@
+import { isDiagnosticToken, type AnalysisResult } from "@actuarial-ts/core";
+import { analysisResultSchema, parseAnalysisResult } from "@actuarial-ts/data";
+import { z } from "zod";
+import { AgentsError } from "./errors.js";
+import {
+  defineActuarialTool,
+  type DefinedActuarialTool,
+} from "./tools.js";
+
+const token = z.string().refine(isDiagnosticToken);
+export const customizationAgentToolInputSchema = z.object({
+  runPresetId: token,
+  scenarioIds: z.array(token).max(32),
+}).strict();
+
+export interface CustomizationAgentPresetResult {
+  readonly scenarioId: string;
+  readonly result: AnalysisResult;
+}
+
+export interface CustomizationAgentRunPreset {
+  readonly id: string;
+  readonly recipeId: string;
+  readonly allowedScenarioIds: readonly string[];
+  readonly execute: (input: {
+    readonly tenantId: string;
+    readonly scenarioIds: readonly string[];
+  }) => Promise<readonly CustomizationAgentPresetResult[]>;
+}
+
+export interface CustomizationAgentToolSuccess {
+  readonly success: true;
+  readonly data: {
+    readonly runPresetId: string;
+    readonly recipeId: string;
+    readonly scenarioIds: readonly string[];
+    readonly results: readonly CustomizationAgentPresetResult[];
+  };
+}
+
+const failureSchema = z.object({
+  success: z.literal(false),
+  error: z.object({ code: z.string(), message: z.string() }).strict(),
+}).strict();
+export const customizationAgentToolResultSchema = z.union([
+  z.object({
+    success: z.literal(true),
+    data: z.object({
+      runPresetId: token,
+      recipeId: token,
+      scenarioIds: z.array(token),
+      results: z.array(z.object({ scenarioId: token, result: analysisResultSchema }).strict()),
+    }).strict(),
+  }).strict(),
+  failureSchema,
+]);
+
+export function createCustomizationSelectionTool(input: {
+  readonly runPresets: readonly CustomizationAgentRunPreset[];
+  readonly id?: string;
+  readonly description?: string;
+  readonly tenantContextKey?: string;
+}): DefinedActuarialTool<
+  z.input<typeof customizationAgentToolInputSchema>,
+  z.output<typeof customizationAgentToolResultSchema>
+> {
+  const catalog = new Map<string, CustomizationAgentRunPreset>();
+  for (const preset of input.runPresets) {
+    if (!isDiagnosticToken(preset.id) || !isDiagnosticToken(preset.recipeId))
+      throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", "Customization preset id and recipeId must be valid tokens");
+    if (catalog.has(preset.id))
+      throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", `Duplicate customization preset ${preset.id}`);
+    if (new Set(preset.allowedScenarioIds).size !== preset.allowedScenarioIds.length || preset.allowedScenarioIds.some((id) => !isDiagnosticToken(id)))
+      throw new AgentsError("BAD_CUSTOMIZATION_CATALOG", `Preset ${preset.id} has invalid or duplicate scenario IDs`);
+    catalog.set(preset.id, Object.freeze({ ...preset, allowedScenarioIds: Object.freeze([...preset.allowedScenarioIds].sort()) }));
+  }
+  return defineActuarialTool({
+    id: input.id ?? "run-approved-customization",
+    description: input.description ?? "Run a host-approved actuarial recipe and approved scenarios",
+    kind: "read",
+    tenant: "required",
+    tenantKey: input.tenantContextKey ?? "projectId",
+    inputSchema: customizationAgentToolInputSchema,
+    outputSchema: customizationAgentToolResultSchema,
+    execute: async (request, tenant) => {
+      const preset = catalog.get(request.runPresetId);
+      if (preset === undefined)
+        throw new AgentsError("UNKNOWN_CUSTOMIZATION_PRESET", `Unknown customization preset ${request.runPresetId}`);
+      if (new Set(request.scenarioIds).size !== request.scenarioIds.length)
+        throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Requested scenario IDs must be unique");
+      const scenarioIds = [...request.scenarioIds].sort();
+      if (scenarioIds.some((id) => !preset.allowedScenarioIds.includes(id)))
+        throw new AgentsError("UNAPPROVED_CUSTOMIZATION_SCENARIO", "One or more requested scenarios are not approved by the selected preset");
+      const rawResults = await preset.execute({ tenantId: tenant, scenarioIds });
+      const byId = new Map<string, AnalysisResult>();
+      for (const item of rawResults) {
+        if (!scenarioIds.includes(item.scenarioId) || byId.has(item.scenarioId))
+          throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor returned an unexpected or duplicate scenario result");
+        const result = parseAnalysisResult(item.result);
+        if (result.recipeId !== preset.recipeId)
+          throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor returned a result for another recipe");
+        byId.set(item.scenarioId, result);
+      }
+      if (byId.size !== scenarioIds.length)
+        throw new AgentsError("CUSTOMIZATION_RUN_MISMATCH", "Preset executor omitted an exact requested scenario result");
+      return {
+        success: true,
+        data: {
+          runPresetId: preset.id,
+          recipeId: preset.recipeId,
+          scenarioIds,
+          results: scenarioIds.map((scenarioId) => ({ scenarioId, result: byId.get(scenarioId)! })),
+        },
+      };
+    },
+  });
+}

package/src/errors.ts

@@ -47,6 +47,10 @@ export const AGENTS_ERROR_CODES = [
   "UNKNOWN_DIAGNOSTIC_PRESET",
   "UNAPPROVED_DIAGNOSTIC_INSTANCE",
   "DIAGNOSTIC_RUN_MISMATCH",
+  "BAD_CUSTOMIZATION_CATALOG",
+  "UNKNOWN_CUSTOMIZATION_PRESET",
+  "UNAPPROVED_CUSTOMIZATION_SCENARIO",
+  "CUSTOMIZATION_RUN_MISMATCH",
   "BAD_OUTPUT_SCHEMA",
   "TOOL_INPUT_INVALID",
   "TOOL_OUTPUT_INVALID",

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./divergence.js";
 export * from "./remote.js";
 export * from "./mcp.js";
 export * from "./diagnostics.js";
+export * from "./customization.js";