@actuarial-ts/agents 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+actuarial-ts
+Copyright 2026 Justin Morrey
+
+This product includes software developed as part of the actuarial-ts project
+(https://github.com/yerromnitsuj/actng).

package/README.md

@@ -0,0 +1,155 @@
+# @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 reserving advisor factory, and a golden-prompt eval harness.
+
+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
+```
+
+`@mastra/core` (>= 1.49, < 2) and `zod` are peer dependencies: the HOST application owns the Mastra version. `@actuarial-ts/compliance` is a regular dependency (and brings `@actuarial-ts/core` with it).
+
+## 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
+```
+
+## 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:
+
+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).
+
+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.
+
+```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,
+});
+// ... 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:
+
+```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(),
+});
+```
+
+ASOP 41 assumptions-and-judgments documentation as a side effect of running the analysis.
+
+### Footgun: workflows are accidental thenables
+
+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.
+
+## Reserving advisor factory
+
+`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.
+
+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.
+
+```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] });
+```
+
+## Eval harness
+
+`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).
+
+```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 `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.
+
+## License
+
+Apache-2.0. See LICENSE and NOTICE.

package/dist/advisor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reserving advisor factory: assembles an @mastra/core Agent from the
+ * hardened base instruction template the ActNG server converged on, with
+ * host-supplied domain sections spliced in.
+ *
+ * The base sections are exported (BASE_INSTRUCTIONS) and the assembly is a
+ * pure, deterministic string function (assembleInstructions) so hosts and
+ * tests can byte-inspect exactly what their agent runs on - a load-bearing
+ * prompt should never be assembled somewhere you cannot audit.
+ *
+ * HOUSE GOTCHA honored throughout: no literal backtick characters anywhere in
+ * instruction content (a backtick inside a template literal once broke server
+ * boot). Section text uses quotes instead.
+ */
+import { Agent } from "@mastra/core/agent";
+export declare const BASE_INSTRUCTIONS: {
+    readonly role: "You are an embedded reserving advisor inside an actuarial analysis application, working alongside a credentialed actuary on one engagement at a time. You participate in the analysis rather than chatting about it: read tools ground every number you cite, and action tools change the working state through the exact same service layer as the application's own controls. You are expected to operate at the level of an experienced, credentialed reserving actuary.";
+    readonly professionalGrounding: "Your advice follows recognized actuarial practice: Friedland, \"Estimating Unpaid Claims Using Basic Techniques\" (method mechanics and adjustments); Werner and Modlin, \"Basic Ratemaking\" (exposure and trend concepts); ASOP 43 (unpaid claim estimates: intended purpose, materiality, methods appropriate to the data); and CAS reserving principles. When data violates a method's assumptions, say which assumption and why it matters, the way a reviewing actuary would.";
+    readonly workingRules: string;
+    readonly actionConsent: "You may change the working state when the user asks (or clearly implies) it - action tools are the same operations as the application's own controls and are reversible; do them rather than describing how the user could. A direct parameterized instruction is consent - apply it in the SAME turn, then confirm concisely what changed. Reserve ask-backs for genuinely ambiguous requests.";
+    readonly failureRecovery: "If a tool returns success: false, do not pretend it worked. Read the error, fix your parameters and retry once if the problem is yours, otherwise tell the user plainly what failed and offer the closest alternative. Never invent a result to cover a failed call.";
+    readonly selectionWeighting: "When blending method results into selected ultimates, weight like a reviewing actuary: lean toward methods whose assumptions the diagnostics support. Development methods earn weight on mature periods where the pattern is credible; expected-loss methods such as Bornhuetter-Ferguson earn weight on green, volatile periods where the a-priori is more credible than thin emerged experience; credibility blends such as Benktander are the natural compromise for middle-maturity periods. Never set custom weights or overrides without stating the rationale, and offer to record it.";
+    readonly conduct: "Be direct and technical; the user is an actuary, not a consumer. After returning search-like results or recommendations, ask whether they match what the user intended before charging ahead with actions, unless the user already told you to proceed end-to-end. When the user asks you to review, recommend, apply, and rerun in one instruction, do the full sequence without stopping to ask permission between steps, then summarize what changed. Keep a professional skeptic's tone: point out weak spots in the data, thin columns, and judgment calls that could move the answer materially.";
+};
+export type BaseInstructionSection = keyof typeof BASE_INSTRUCTIONS;
+export interface AssembleInstructionsOptions {
+    /**
+     * Host domain sections (capping mechanics, tail conventions, named tool
+     * guidance, ...), spliced verbatim between the base analytical sections and
+     * the conduct section. Bring your own headers.
+     */
+    domainInstructions?: string | readonly string[];
+    /** Replaces the base conduct section wholesale when provided. */
+    conductOverrides?: string;
+}
+/**
+ * Deterministic assembly of the final instruction string: pure string
+ * concatenation with fixed headers, no clock, no randomness - identical
+ * inputs yield byte-identical output, so hosts can snapshot-test the exact
+ * prompt their agent runs on.
+ */
+export declare function assembleInstructions(options?: AssembleInstructionsOptions): string;
+/** Config slices lifted from the installed Agent constructor so the factory tracks the host's Mastra version. */
+type AgentCtorConfig = ConstructorParameters<typeof Agent>[0];
+export interface CreateReservingAdvisorOptions {
+    /** Defaults to "reserving-advisor". */
+    id?: string;
+    /** Defaults to "Reserving Advisor". */
+    name?: string;
+    description?: string;
+    /** The language model (same type the host's Agent constructor takes). */
+    model: AgentCtorConfig["model"];
+    /** The tool record, e.g. toolRegistry(...).tools. */
+    tools?: AgentCtorConfig["tools"];
+    /** Optional Mastra memory instance. */
+    memory?: AgentCtorConfig["memory"];
+    /** Host domain sections; see assembleInstructions. */
+    domainInstructions?: string | readonly string[];
+    /** Replaces the base conduct section wholesale. */
+    conductOverrides?: string;
+}
+/**
+ * Assembles a reserving advisor Agent on the hardened base template. The
+ * final instructions are exactly assembleInstructions({ domainInstructions,
+ * conductOverrides }) - byte-inspect them there.
+ */
+export declare function createReservingAdvisor(options: CreateReservingAdvisorOptions): Agent;
+export {};
+//# sourceMappingURL=advisor.d.ts.map

package/dist/advisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisor.d.ts","sourceRoot":"","sources":["../src/advisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAa3C,eAAO,MAAM,iBAAiB;;;;;;;;CAuBpB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAEpE,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,MAAM,CAkBtF;AAKD,iHAAiH;AACjH,KAAK,eAAe,GAAG,qBAAqB,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,MAAM,WAAW,6BAA6B;IAC5C,uCAAuC;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAChC,qDAAqD;IACrD,KAAK,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,uCAAuC;IACvC,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,KAAK,CAepF"}

package/dist/advisor.js

@@ -0,0 +1,83 @@
+/**
+ * Reserving advisor factory: assembles an @mastra/core Agent from the
+ * hardened base instruction template the ActNG server converged on, with
+ * host-supplied domain sections spliced in.
+ *
+ * The base sections are exported (BASE_INSTRUCTIONS) and the assembly is a
+ * pure, deterministic string function (assembleInstructions) so hosts and
+ * tests can byte-inspect exactly what their agent runs on - a load-bearing
+ * prompt should never be assembled somewhere you cannot audit.
+ *
+ * HOUSE GOTCHA honored throughout: no literal backtick characters anywhere in
+ * instruction content (a backtick inside a template literal once broke server
+ * boot). Section text uses quotes instead.
+ */
+import { Agent } from "@mastra/core/agent";
+// ---------------------------------------------------------------------------
+// Base instruction sections
+//
+// Generalized from the server advisor's non-domain-specific rules: the
+// professional grounding, tools-are-the-only-path-to-numbers,
+// read-before-recommend ordering, no-table-recitation, action consent,
+// failure recovery, selection-of-ultimates weighting, and conversational
+// conduct. Workbench-specific exhibits (LDF vector conventions, capping
+// mechanics, named tools) stay OUT: hosts splice those in as
+// domainInstructions.
+export const BASE_INSTRUCTIONS = {
+    role: "You are an embedded reserving advisor inside an actuarial analysis application, working alongside a credentialed actuary on one engagement at a time. You participate in the analysis rather than chatting about it: read tools ground every number you cite, and action tools change the working state through the exact same service layer as the application's own controls. You are expected to operate at the level of an experienced, credentialed reserving actuary.",
+    professionalGrounding: 'Your advice follows recognized actuarial practice: Friedland, "Estimating Unpaid Claims Using Basic Techniques" (method mechanics and adjustments); Werner and Modlin, "Basic Ratemaking" (exposure and trend concepts); ASOP 43 (unpaid claim estimates: intended purpose, materiality, methods appropriate to the data); and CAS reserving principles. When data violates a method\'s assumptions, say which assumption and why it matters, the way a reviewing actuary would.',
+    workingRules: [
+        "1. EVERY number you cite must come from a tool result in this conversation. Never estimate, recall, or invent figures. If you have not called the tool, you do not know the number.",
+        "2. Call read tools BEFORE forming recommendations: orient yourself in the current working state first, gather the relevant evidence before recommending a selection, and check data quality before opining on method reliability.",
+        "3. The application renders tool results as tables and cards next to this chat. Do NOT recite full tables into the conversation. Reference the handful of figures that carry your argument.",
+    ].join("\n"),
+    actionConsent: "You may change the working state when the user asks (or clearly implies) it - action tools are the same operations as the application's own controls and are reversible; do them rather than describing how the user could. A direct parameterized instruction is consent - apply it in the SAME turn, then confirm concisely what changed. Reserve ask-backs for genuinely ambiguous requests.",
+    failureRecovery: "If a tool returns success: false, do not pretend it worked. Read the error, fix your parameters and retry once if the problem is yours, otherwise tell the user plainly what failed and offer the closest alternative. Never invent a result to cover a failed call.",
+    selectionWeighting: "When blending method results into selected ultimates, weight like a reviewing actuary: lean toward methods whose assumptions the diagnostics support. Development methods earn weight on mature periods where the pattern is credible; expected-loss methods such as Bornhuetter-Ferguson earn weight on green, volatile periods where the a-priori is more credible than thin emerged experience; credibility blends such as Benktander are the natural compromise for middle-maturity periods. Never set custom weights or overrides without stating the rationale, and offer to record it.",
+    conduct: "Be direct and technical; the user is an actuary, not a consumer. After returning search-like results or recommendations, ask whether they match what the user intended before charging ahead with actions, unless the user already told you to proceed end-to-end. When the user asks you to review, recommend, apply, and rerun in one instruction, do the full sequence without stopping to ask permission between steps, then summarize what changed. Keep a professional skeptic's tone: point out weak spots in the data, thin columns, and judgment calls that could move the answer materially.",
+};
+/**
+ * Deterministic assembly of the final instruction string: pure string
+ * concatenation with fixed headers, no clock, no randomness - identical
+ * inputs yield byte-identical output, so hosts can snapshot-test the exact
+ * prompt their agent runs on.
+ */
+export function assembleInstructions(options = {}) {
+    const domain = options.domainInstructions === undefined
+        ? []
+        : typeof options.domainInstructions === "string"
+            ? [options.domainInstructions]
+            : [...options.domainInstructions];
+    const sections = [
+        BASE_INSTRUCTIONS.role,
+        "## Professional grounding\n" + BASE_INSTRUCTIONS.professionalGrounding,
+        "## Non-negotiable working rules\n" + BASE_INSTRUCTIONS.workingRules,
+        "## Acting on the working state\n" + BASE_INSTRUCTIONS.actionConsent,
+        "## Failure recovery\n" + BASE_INSTRUCTIONS.failureRecovery,
+        "## Selection of ultimates\n" + BASE_INSTRUCTIONS.selectionWeighting,
+        ...domain,
+        "## Conversational conduct\n" + (options.conductOverrides ?? BASE_INSTRUCTIONS.conduct),
+    ];
+    return sections.join("\n\n");
+}
+/**
+ * Assembles a reserving advisor Agent on the hardened base template. The
+ * final instructions are exactly assembleInstructions({ domainInstructions,
+ * conductOverrides }) - byte-inspect them there.
+ */
+export function createReservingAdvisor(options) {
+    return new Agent({
+        id: options.id ?? "reserving-advisor",
+        name: options.name ?? "Reserving Advisor",
+        description: options.description ??
+            "Embedded actuarial reserving advisor: analyzes loss development evidence, recommends and applies selections through host tools, and explains diagnostics.",
+        instructions: assembleInstructions({
+            domainInstructions: options.domainInstructions,
+            conductOverrides: options.conductOverrides,
+        }),
+        model: options.model,
+        ...(options.tools !== undefined ? { tools: options.tools } : {}),
+        ...(options.memory !== undefined ? { memory: options.memory } : {}),
+    });
+}
+//# sourceMappingURL=advisor.js.map

package/dist/advisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisor.js","sourceRoot":"","sources":["../src/advisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,8EAA8E;AAC9E,4BAA4B;AAC5B,EAAE;AACF,uEAAuE;AACvE,8DAA8D;AAC9D,uEAAuE;AACvE,yEAAyE;AACzE,wEAAwE;AACxE,6DAA6D;AAC7D,sBAAsB;AAEtB,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,6cAA6c;IAEnd,qBAAqB,EACnB,kdAAkd;IAEpd,YAAY,EAAE;QACZ,qLAAqL;QACrL,mOAAmO;QACnO,4LAA4L;KAC7L,CAAC,IAAI,CAAC,IAAI,CAAC;IAEZ,aAAa,EACX,iYAAiY;IAEnY,eAAe,EACb,sQAAsQ;IAExQ,kBAAkB,EAChB,+jBAA+jB;IAEjkB,OAAO,EACL,wkBAAwkB;CAClkB,CAAC;AAeX;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAuC,EAAE;IAC5E,MAAM,MAAM,GACV,OAAO,CAAC,kBAAkB,KAAK,SAAS;QACtC,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,OAAO,OAAO,CAAC,kBAAkB,KAAK,QAAQ;YAC9C,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC;YAC9B,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG;QACf,iBAAiB,CAAC,IAAI;QACtB,6BAA6B,GAAG,iBAAiB,CAAC,qBAAqB;QACvE,mCAAmC,GAAG,iBAAiB,CAAC,YAAY;QACpE,kCAAkC,GAAG,iBAAiB,CAAC,aAAa;QACpE,uBAAuB,GAAG,iBAAiB,CAAC,eAAe;QAC3D,6BAA6B,GAAG,iBAAiB,CAAC,kBAAkB;QACpE,GAAG,MAAM;QACT,6BAA6B,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,iBAAiB,CAAC,OAAO,CAAC;KACxF,CAAC;IACF,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AA0BD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,OAAO,IAAI,KAAK,CAAC;QACf,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,mBAAmB;QACrC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,mBAAmB;QACzC,WAAW,EACT,OAAO,CAAC,WAAW;YACnB,2JAA2J;QAC7J,YAAY,EAAE,oBAAoB,CAAC;YACjC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC;QACF,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC,CAAC;AACL,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Error idiom for the agents package, mirroring core's ReservingError and
+ * compliance's ComplianceError: a typed Error subclass carrying a registered
+ * machine code. The registry below is the closed contract - add the code here
+ * when introducing a new throw.
+ *
+ * These errors are DEFINITION-TIME and SEAM errors (bad tool schemas, bad
+ * gate specs, missing tenant context, undocumented judgment). They are never
+ * allowed to reach the model: defineActuarialTool's wrapper converts anything
+ * 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"];
+export type AgentsErrorCode = (typeof AGENTS_ERROR_CODES)[number];
+/**
+ * Thrown for invalid agent-toolkit input: tenant-seam violations, malformed
+ * gate specs, undocumented judgment. Carries a registered machine code so
+ * envelopes and tests can match on it without parsing messages.
+ */
+export declare class AgentsError extends Error {
+    readonly code: AgentsErrorCode;
+    constructor(code: AgentsErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,8HAYrB,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

@@ -0,0 +1,39 @@
+/**
+ * Error idiom for the agents package, mirroring core's ReservingError and
+ * compliance's ComplianceError: a typed Error subclass carrying a registered
+ * machine code. The registry below is the closed contract - add the code here
+ * when introducing a new throw.
+ *
+ * These errors are DEFINITION-TIME and SEAM errors (bad tool schemas, bad
+ * gate specs, missing tenant context, undocumented judgment). They are never
+ * allowed to reach the model: defineActuarialTool's wrapper converts anything
+ * thrown during tool execution into a { success: false, error } envelope.
+ */
+/** Every machine-readable code an AgentsError can carry. */
+export const AGENTS_ERROR_CODES = [
+    /** A tool read the request context and found no (or a non-string/empty) tenant id. */
+    "NO_TENANT_CONTEXT",
+    /** A tool's input schema declares a tenant-id key (projectId/tenantId); tenant ids travel only via RequestContext. */
+    "TENANT_IN_SCHEMA",
+    "BAD_INPUT_SCHEMA",
+    /** A judgment chain was defined with an invalid gate list or gate spec. */
+    "BAD_GATE",
+    /** A judgment gate was resumed without a non-blank rationale. */
+    "MISSING_RATIONALE",
+    /** Two tools with the same id were passed to toolRegistry. */
+    "DUPLICATE_TOOL_ID",
+];
+/**
+ * Thrown for invalid agent-toolkit input: tenant-seam violations, malformed
+ * gate specs, undocumented judgment. Carries a registered machine code so
+ * envelopes and tests can match on it without parsing messages.
+ */
+export class AgentsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AgentsError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +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;CACX,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"}