@actuarial-ts/agents 0.4.0 → 0.6.0

package/src/diagnostics.ts

@@ -0,0 +1,71 @@
+import { assertCompiledDiagnosticDefinition, type CompiledDiagnosticDefinition, type DiagnosticDeepReadonly } from "@actuarial-ts/core";
+import { assertVerifiedDiagnosticRunProvenance, type VerifiedDiagnosticRunProvenance } from "@actuarial-ts/compliance";
+import { z } from "zod";
+import { AgentsError } from "./errors.js";
+import { defineActuarialTool, type DefinedActuarialTool, type ToolEnvelopeFailure } from "./tools.js";
+
+export const diagnosticAgentToolInputSchema = z.object({
+  runPresetId:z.string().min(1),
+  instanceIds:z.array(z.string().min(1)).min(1),
+  view:z.enum(["emergence","triangles","latest-diagonal"]),
+}).strict();
+export type DiagnosticAgentToolInput=z.input<typeof diagnosticAgentToolInputSchema>;
+
+export interface DiagnosticAgentRunPreset {
+  readonly id:string;
+  readonly definitionIntegrity:string;
+  readonly allowedInstanceIds:readonly string[];
+  readonly execute:(input:{readonly tenant:string;readonly instanceIds:readonly string[]})=>Promise<VerifiedDiagnosticRunProvenance>;
+}
+export interface CreateDiagnosticSelectionToolInput { readonly definition:CompiledDiagnosticDefinition;readonly presets:readonly DiagnosticAgentRunPreset[];readonly id?:string;readonly description?:string;readonly tenantContextKey?:string }
+export type DiagnosticAgentDisplayProjection=
+  | {readonly view:"emergence";readonly value:VerifiedDiagnosticRunProvenance["result"]["emergence"]}
+  | {readonly view:"triangles";readonly value:VerifiedDiagnosticRunProvenance["result"]["triangles"]}
+  | {readonly view:"latest-diagonal";readonly value:VerifiedDiagnosticRunProvenance["result"]["latestDiagonal"]};
+export type DiagnosticAgentDisplayPoint=
+  | VerifiedDiagnosticRunProvenance["result"]["emergence"][number]
+  | VerifiedDiagnosticRunProvenance["result"]["triangles"][number]
+  | VerifiedDiagnosticRunProvenance["result"]["latestDiagonal"][number];
+export interface DiagnosticAgentToolSuccess {
+  readonly success:true;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;
+
+const toolFailureSchema=z.object({success:z.literal(false),error:z.object({code:z.string(),message:z.string()}).strict()}).strict();
+const displaySchema=z.discriminatedUnion("view",[
+  z.object({view:z.literal("emergence"),value:z.custom<Extract<DiagnosticAgentDisplayProjection,{readonly view:"emergence"}>["value"]>()}).strict(),
+  z.object({view:z.literal("triangles"),value:z.custom<Extract<DiagnosticAgentDisplayProjection,{readonly view:"triangles"}>["value"]>()}).strict(),
+  z.object({view:z.literal("latest-diagonal"),value:z.custom<Extract<DiagnosticAgentDisplayProjection,{readonly view:"latest-diagonal"}>["value"]>()}).strict(),
+]);
+const toolSuccessSchema=z.object({
+  success:z.literal(true),runPresetId:z.string(),instanceIds:z.array(z.string()),definitionIntegrity:z.string(),
+  formulaFingerprints:z.record(z.string()),calculationFingerprints:z.record(z.string()),runFingerprint:z.string(),
+  resultFingerprint:z.string(),runResultFingerprint:z.string(),review:z.custom<VerifiedDiagnosticRunProvenance["review"]>(),
+  display:displaySchema,
+}).strict();
+/** Strict model-visible output schema, including the wrapper's failure branch. */
+export const diagnosticAgentToolResultSchema:z.ZodType<DiagnosticAgentToolResult>=z.union([toolSuccessSchema,toolFailureSchema]);
+export type DiagnosticSelectionTool=DefinedActuarialTool<DiagnosticAgentToolInput,DiagnosticAgentToolResult>;
+
+function token(value:string,label:string):void{if(value.length===0||/^[\t-\r ]|[\t-\r ]$/.test(value)||value.includes("\0"))throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`${label} must be a nonempty token`)}
+function sortUniqueRequested(values:readonly string[]):string[]{const result=[...new Set(values)];result.sort((a,b)=>a<b?-1:a>b?1:0);return result}
+
+export function createDiagnosticSelectionTool(input:CreateDiagnosticSelectionToolInput):DiagnosticSelectionTool{
+  try{assertCompiledDiagnosticDefinition(input.definition)}catch{throw new AgentsError("BAD_DIAGNOSTIC_CATALOG","definition must be an authentic compiled diagnostic definition")}
+  const id=input.id??"run_diagnostic_selection";const description=input.description??"Run a host-approved diagnostic preset for selected registered metric instances.";const tenantKey=input.tenantContextKey??"projectId";
+  token(id,"tool id");token(tenantKey,"tenant context key");if(description.trim().length===0)throw new AgentsError("BAD_DIAGNOSTIC_CATALOG","description must be nonblank");if(input.presets.length===0)throw new AgentsError("BAD_DIAGNOSTIC_CATALOG","at least one approved diagnostic preset is required");
+  const known=new Set(input.definition.definition.instances.map((item)=>item.id));const catalog=new Map<string,{definitionIntegrity:string;allowedInstanceIds:readonly string[];execute:DiagnosticAgentRunPreset["execute"]}>();
+  for(const preset of input.presets){token(preset.id,"preset id");if(catalog.has(preset.id))throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`duplicate preset ${preset.id}`);if(preset.definitionIntegrity!==input.definition.definitionIntegrity)throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`preset ${preset.id} targets another definition`);if(typeof preset.execute!=="function")throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`preset ${preset.id} has no executor`);const seen=new Set<string>();for(const instanceId of preset.allowedInstanceIds){token(instanceId,"allowed instance id");if(seen.has(instanceId))throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`preset ${preset.id} repeats ${instanceId}`);if(!known.has(instanceId))throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`preset ${preset.id} references unknown instance ${instanceId}`);seen.add(instanceId)}if(seen.size===0)throw new AgentsError("BAD_DIAGNOSTIC_CATALOG",`preset ${preset.id} has no allowed instances`);catalog.set(preset.id,Object.freeze({definitionIntegrity:preset.definitionIntegrity,allowedInstanceIds:Object.freeze([...seen].sort()),execute:preset.execute}))}
+  return defineActuarialTool({id,description,kind:"read",tenant:"required",tenantKey,inputSchema:diagnosticAgentToolInputSchema,outputSchema:diagnosticAgentToolResultSchema,execute:async(raw,tenant):Promise<DiagnosticAgentToolSuccess>=>{
+    const preset=catalog.get(raw.runPresetId);if(!preset)throw new AgentsError("UNKNOWN_DIAGNOSTIC_PRESET",`Unknown diagnostic preset ${raw.runPresetId}`);const selected=sortUniqueRequested(raw.instanceIds);if(selected.some((item)=>!preset.allowedInstanceIds.includes(item)))throw new AgentsError("UNAPPROVED_DIAGNOSTIC_INSTANCE","One or more diagnostic instances are not approved by the selected preset");
+    const provenance=await preset.execute({tenant,instanceIds:selected});try{assertVerifiedDiagnosticRunProvenance(provenance)}catch{throw new AgentsError("DIAGNOSTIC_RUN_MISMATCH","Preset executor returned unauthenticated diagnostic provenance")}
+    const filter=provenance.manifest.preparation.filter;if(provenance.definitionIdentities.definition!==input.definition.definitionIntegrity||provenance.manifest.runPresetId!==raw.runPresetId||!filter||JSON.stringify(filter.instanceIds??[])!==JSON.stringify(selected))throw new AgentsError("DIAGNOSTIC_RUN_MISMATCH","Verified run does not match the selected definition, preset, and exact instance set");
+    const instances=input.definition.definition.instances.filter((item)=>selected.includes(item.id));const formulaIds=[...new Set(instances.map((item)=>item.formulaId))].sort();const formulaFingerprints=Object.fromEntries(formulaIds.map((formulaId)=>[formulaId,provenance.definitionIdentities.formulaById[formulaId]!]));const calculationFingerprints=Object.fromEntries(selected.map((instanceId)=>[instanceId,provenance.definitionIdentities.calculationByInstanceId[instanceId]!]));
+    const display=raw.view==="emergence"?{view:"emergence" as const,value:provenance.result.emergence}:raw.view==="triangles"?{view:"triangles" as const,value:provenance.result.triangles}:{view:"latest-diagonal" as const,value:provenance.result.latestDiagonal};
+    return {success:true,runPresetId:raw.runPresetId,instanceIds:selected,definitionIntegrity:provenance.definitionIdentities.definition,formulaFingerprints,calculationFingerprints,runFingerprint:provenance.runFingerprint,resultFingerprint:provenance.resultFingerprint,runResultFingerprint:provenance.runResultFingerprint,review:provenance.review,display};
+  }});
+}

package/src/errors.ts

@@ -43,6 +43,13 @@ export const AGENTS_ERROR_CODES = [
   "REMOTE_RESULT_INVALID",
   /** The boot self-test found an MCP-exposed probe tool that did NOT fail closed without tenant context; the MCP tenant seam is not wired up and the server must abort startup. */
   "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",
 ] as const;
 
 export type AgentsErrorCode = (typeof AGENTS_ERROR_CODES)[number];

package/src/index.ts

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

package/src/mcp.ts

@@ -22,7 +22,7 @@
  *    startup MUST abort.
  *
  * ---------------------------------------------------------------------------
- * VERIFIED against the installed @mastra/mcp 1.14.0 (house rule — types and
+ * VERIFIED against the lock-tested @mastra/mcp 1.17.3 (house rule — types and
  * compiled source, not memory):
  *
  * - MCPServer.executeTool(toolId, args, executionContext?: { messages?,
@@ -40,7 +40,7 @@
  *   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
+ *   surprise: the lock-tested 1.17.3 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/src/promotion.ts

@@ -408,6 +408,7 @@ function structuralCheck(
     description,
     status: findings.length > 0 ? "warning" : "pass",
     details: capDetails(findings),
+    findings: findings.map((message) => ({ code: id, message, context: {} })),
   };
 }
 
@@ -472,6 +473,7 @@ function notEvaluatedReview(reason: string): DataReviewReport {
         description: "ASOP 23-oriented triangle review",
         status: "not-evaluated",
         details: [`not evaluated: ${reason}`],
+        findings: [],
       },
     ],
     summary: { pass: 0, warning: 0, fail: 0, notEvaluated: 1 },

package/src/tools.ts

@@ -17,7 +17,8 @@
  *    keep their code; everything else gets the fallback.
  */
 
-import { createTool } from "@mastra/core/tools";
+import { createTool, type Tool } from "@mastra/core/tools";
+import { toStandardSchema, type StandardSchemaWithJSON } from "@mastra/core/schema";
 import type { z } from "zod";
 import { AgentsError } from "./errors.js";
 
@@ -26,10 +27,30 @@ import { AgentsError } from "./errors.js";
 
 /** The uniform tool-failure shape: agents branch on success, hosts log code. */
 export type ToolEnvelopeFailure = {
-  success: false;
-  error: { code: string; message: string };
+  readonly success: false;
+  readonly error: { readonly code: string; readonly message: string };
 };
 
+const TOOL_INPUT_INVALID: ToolEnvelopeFailure = Object.freeze({
+  success: false,
+  error: Object.freeze({ code: "TOOL_INPUT_INVALID", message: "Tool input failed schema validation" }),
+});
+const TOOL_OUTPUT_INVALID: ToolEnvelopeFailure = Object.freeze({
+  success: false,
+  error: Object.freeze({ code: "TOOL_OUTPUT_INVALID", message: "Tool output failed schema validation" }),
+});
+
+function readonlyFailure(code: string, message: string): ToolEnvelopeFailure {
+  return Object.freeze({ success: false, error: Object.freeze({ code, message }) });
+}
+
+function deepFreezeResult<T>(value: T, seen = new WeakSet<object>()): T {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value as Record<string, unknown>)) deepFreezeResult(child, seen);
+  return Object.freeze(value);
+}
+
 /**
  * Converts anything thrown by a tool into the failure envelope. Never throws.
  * Error-like values with a non-empty string "code" property (HttpError,
@@ -60,7 +81,7 @@ export function envelopeFailure(err: unknown, fallbackCode = "TOOL_ERROR"): Tool
   } catch {
     // A hostile getter must not break the envelope; keep the fallbacks.
   }
-  return { success: false, error: { code, message } };
+  return readonlyFailure(code, message);
 }
 
 // ---------------------------------------------------------------------------
@@ -116,7 +137,7 @@ export function resolveMcpAuthInfo(context: McpContextLike | undefined): McpAuth
       | undefined;
     if (proxiedExtra?.authInfo) return proxiedExtra.authInfo;
 
-    // Installed @mastra/mcp 1.14.0: createProxiedRequestContext copies each
+    // Lock-tested @mastra/mcp 1.17.3: createProxiedRequestContext copies each
     // extra key onto the RequestContext verbatim, so authInfo is top-level.
     const topLevelAuthInfo = requestContext.get("authInfo") as McpAuthInfoLike | undefined;
     if (topLevelAuthInfo) return topLevelAuthInfo;
@@ -433,7 +454,7 @@ export type ActuarialToolKind = "read" | "action";
  */
 export type ActuarialToolContext = TenantToolContext;
 
-interface DefineActuarialToolCommon<TShape extends z.ZodRawShape> {
+interface DefineActuarialToolCommon<TShape extends z.ZodRawShape, TResult> {
   /**
    * Exact schema paths (the lint's dot notation, rooted at "input") where an
    * uninspectable type — z.unknown(), z.any(), z.map() — is INTENTIONAL
@@ -456,6 +477,11 @@ interface DefineActuarialToolCommon<TShape extends z.ZodRawShape> {
    * AgentsError("TENANT_IN_SCHEMA") at definition time if it does.
    */
   inputSchema: z.ZodObject<TShape>;
+  /**
+   * Optional observable-result schema. It must admit the complete success /
+   * failure union because validation errors are ordinary tool results.
+   */
+  outputSchema?: z.ZodType<TResult | ToolEnvelopeFailure, z.ZodTypeDef, unknown>;
 }
 
 /**
@@ -474,7 +500,7 @@ interface DefineActuarialToolCommon<TShape extends z.ZodRawShape> {
  * reviewable at the definition site.
  */
 export type DefineActuarialToolOptions<TShape extends z.ZodRawShape, TResult> =
-  | (DefineActuarialToolCommon<TShape> & {
+  | (DefineActuarialToolCommon<TShape, TResult> & {
       tenant: "required";
       /** Trusted source for the tenant id. Default "request-context". */
       tenantSource?: TenantSource;
@@ -487,27 +513,72 @@ export type DefineActuarialToolOptions<TShape extends z.ZodRawShape, TResult> =
        * envelope, never an exception.
        */
       execute: (
-        input: z.infer<z.ZodObject<TShape>>,
+        input: z.output<z.ZodObject<TShape>>,
         tenant: string,
         context: ActuarialToolContext,
       ) => Promise<TResult>;
     })
-  | (DefineActuarialToolCommon<TShape> & {
+  | (DefineActuarialToolCommon<TShape, TResult> & {
       tenant: "none";
       execute: (
-        input: z.infer<z.ZodObject<TShape>>,
+        input: z.output<z.ZodObject<TShape>>,
         tenant: null,
         context: ActuarialToolContext,
       ) => Promise<TResult>;
     });
 
+/**
+ * A Mastra-compatible tool whose direct execute boundary is fully owned by
+ * this SDK. Mastra metadata stays intentionally unknown: the real domain
+ * schemas are retained privately so framework validation cannot run their
+ * transforms a second time.
+ */
+export type DefinedActuarialTool<TInput, TOutput> = Omit<
+  Tool<unknown, unknown>,
+  "execute"
+> & {
+  readonly kind: ActuarialToolKind;
+  execute: (input: TInput, context: ActuarialToolContext) => Promise<TOutput>;
+};
+
+function metadataBridge(schema: z.ZodTypeAny): StandardSchemaWithJSON<unknown, unknown> {
+  const real = toStandardSchema(schema);
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "actuarial-ts-metadata-bridge",
+      validate: (value: unknown) => ({ value }),
+      jsonSchema: {
+        input: (options) => real["~standard"].jsonSchema.input(options),
+        output: (options) => real["~standard"].jsonSchema.output(options),
+      },
+    },
+  };
+}
+
+function isFailure(value: unknown): value is ToolEnvelopeFailure {
+  if (value === null || typeof value !== "object") return false;
+  const candidate = value as { success?: unknown; error?: unknown };
+  if (candidate.success !== false || candidate.error === null || typeof candidate.error !== "object") return false;
+  const error = candidate.error as { code?: unknown; message?: unknown };
+  return typeof error.code === "string" && typeof error.message === "string";
+}
+
+function sameJson(left: unknown, right: unknown): boolean {
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Wraps Mastra's createTool with the envelope + tenant-seam guarantees and
  * tags the result with its kind for toolRegistry classification.
  */
 export function defineActuarialTool<TShape extends z.ZodRawShape, TResult>(
   options: DefineActuarialToolOptions<TShape, TResult>,
-) {
+): DefinedActuarialTool<z.input<z.ZodObject<TShape>>, TResult | ToolEnvelopeFailure> {
   // FAIL CLOSED: a schema the seam cannot inspect is not definable, and the
   // tenant-key lint recurses through every container the model could reach.
   const shape = zodObjectShape(options.inputSchema);
@@ -538,28 +609,81 @@ export function defineActuarialTool<TShape extends z.ZodRawShape, TResult>(
         "relationship to the tenant seam explicitly",
     );
   }
+
+  if (options.outputSchema !== undefined) {
+    let probe;
+    try {
+      probe = options.outputSchema.safeParse(TOOL_OUTPUT_INVALID);
+    } catch {
+      throw new AgentsError(
+        "BAD_OUTPUT_SCHEMA",
+        `Tool "${options.id}": outputSchema threw while validating the required failure envelope`,
+      );
+    }
+    if (!probe.success || !sameJson(probe.data, TOOL_OUTPUT_INVALID)) {
+      throw new AgentsError(
+        "BAD_OUTPUT_SCHEMA",
+        `Tool "${options.id}": outputSchema must preserve the complete tool failure envelope`,
+      );
+    }
+  }
+
   const tool = createTool({
     id: options.id,
     description: options.description,
-    inputSchema: options.inputSchema,
-    execute: async (input: z.infer<z.ZodObject<TShape>>, context: unknown) => {
-      try {
-        if (options.tenant === "required") {
-          // Resolve BEFORE the body runs: an unauthenticated call fails closed
-          // here, and execute never sees it.
-          const tenant = resolveTenant(context as ActuarialToolContext, {
-            source: options.tenantSource,
-            key: options.tenantKey,
-          });
-          return await options.execute(input, tenant, context as ActuarialToolContext);
-        }
-        return await options.execute(input, null, context as ActuarialToolContext);
-      } catch (err) {
-        return envelopeFailure(err);
-      }
-    },
+    inputSchema: metadataBridge(options.inputSchema),
+    ...(options.outputSchema === undefined ? {} : { outputSchema: metadataBridge(options.outputSchema) }),
   });
-  return Object.assign(tool, { kind: options.kind });
+
+  const execute = async (
+    rawInput: z.input<z.ZodObject<TShape>>,
+    context: ActuarialToolContext,
+  ): Promise<TResult | ToolEnvelopeFailure> => {
+    let parsedInput;
+    try {
+      parsedInput = options.inputSchema.safeParse(rawInput);
+    } catch {
+      return TOOL_INPUT_INVALID;
+    }
+    if (!parsedInput.success) return TOOL_INPUT_INVALID;
+
+    let rawOutput: TResult | ToolEnvelopeFailure;
+    try {
+      if (options.tenant === "required") {
+        const tenant = resolveTenant(context, {
+          source: options.tenantSource,
+          key: options.tenantKey,
+        });
+        rawOutput = await options.execute(parsedInput.data, tenant, context);
+      } else {
+        rawOutput = await options.execute(parsedInput.data, null, context);
+      }
+    } catch (err) {
+      rawOutput = envelopeFailure(err);
+    }
+
+    if (options.outputSchema === undefined) {
+      return rawOutput === undefined ? TOOL_OUTPUT_INVALID : rawOutput;
+    }
+    let parsedOutput;
+    try {
+      parsedOutput = options.outputSchema.safeParse(rawOutput);
+    } catch {
+      return TOOL_OUTPUT_INVALID;
+    }
+    if (!parsedOutput.success) return TOOL_OUTPUT_INVALID;
+    if (isFailure(rawOutput) && !sameJson(parsedOutput.data, rawOutput)) return TOOL_OUTPUT_INVALID;
+    return deepFreezeResult(parsedOutput.data);
+  };
+
+  // The metadata bridges deliberately erase domain inference on the inherited
+  // Mastra surface. This is the single convergence assertion: the adapter
+  // above is the only executor and has the exact public input/output contract.
+  const defined = Object.assign(tool, { execute, kind: options.kind }) as DefinedActuarialTool<
+    z.input<z.ZodObject<TShape>>,
+    TResult | ToolEnvelopeFailure
+  >;
+  return defined;
 }
 
 // ---------------------------------------------------------------------------