@crediolabs/policy-synth 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Untangled Finance Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/codegen/template.js

@@ -51,10 +51,10 @@ function renderUncovered(uncovered) {
  *
  *  Same `(spec, name)` always produces byte-identical output. */
 export function generateRust(spec, name) {
-    const contract = spec.contract;
-    const fnName = spec.fnName ?? 'enforce';
+    const _contract = spec.contract;
+    const _fnName = spec.fnName ?? 'enforce';
     const structName = asRustIdent(name);
-    const dataKeyName = `${asRustIdent(name)}_data`;
+    const _dataKeyName = `${asRustIdent(name)}_data`;
     const uncoveredBlock = renderUncovered(spec.uncovered);
     return `// Auto-generated by the OZ Policy Builder codegen escape hatch.
 // THIS OUTPUT IS THE USER'S TO COMPLETE AND AUDIT.

package/dist/record/decode.d.ts

@@ -1,5 +1,5 @@
 import { xdr } from '@stellar/stellar-sdk';
-import type { ContractInvocation, Network, OnChainEvent, ParseConfidence, ScVal, TokenMovement } from '../types.ts';
+import { type ContractInvocation, type Network, type OnChainEvent, type ParseConfidence, type ScVal, type TokenMovement } from '../types.ts';
 /** Result of decoding an envelope XDR plus the surrounding metadata from
  *  `getTransaction` (events + auth entries). All fields are plain JSON; the
  *  caller decides how to interpret them. */
@@ -44,8 +44,11 @@ export declare function decodeScAddressToC(scAddr: xdr.ScAddress): string;
 /** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
  *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
  *  AND recorded in `opaqueScVals` so the freshness module can reduce
- *  parseConfidence. */
-export declare function scValToSubset(val: xdr.ScVal, path: string, opaqueScVals: ParseConfidence['opaqueScVals']): ScVal;
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
+export declare function scValToSubset(val: xdr.ScVal, path: string, opaqueScVals: ParseConfidence['opaqueScVals'], depth?: number): ScVal;
 /** Convert Int128Parts (hi: Int64, lo: Uint64) to a BigInt.
  *  hi is a signed 64-bit value; lo is unsigned. We use the SDK-provided
  *  `toString()` form which gives the signed decimal representation of the 64-bit

package/dist/record/decode.js

@@ -17,6 +17,7 @@
 // No network calls. No randomness. No globals.
 import { Address, StrKey, xdr } from '@stellar/stellar-sdk';
 import { identifyProtocol } from "../registry/identify.js";
+import { MAX_SCVAL_DEPTH, } from "../types.js";
 /** Decode a TransactionEnvelope XDR (base64) into a fully parsed invocation tree. */
 export function decodeEnvelopeXdr(envelopeXdrB64, events = [], _authEntries = [], ledgerSequence = 0, knownContracts = new Set(), network = null) {
     const envelope = xdr.TransactionEnvelope.fromXDR(envelopeXdrB64, 'base64');
@@ -226,8 +227,11 @@ function symbolValueFromBufferOrString(s) {
 /** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
  *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
  *  AND recorded in `opaqueScVals` so the freshness module can reduce
- *  parseConfidence. */
-export function scValToSubset(val, path, opaqueScVals) {
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
+export function scValToSubset(val, path, opaqueScVals, depth = 0) {
     const kind = val.switch().name;
     switch (kind) {
         case 'scvAddress': {
@@ -252,10 +256,36 @@ export function scValToSubset(val, path, opaqueScVals) {
             return { type: 'symbol', value: val.sym().toString() };
         }
         case 'scvVec': {
+            if (depth >= MAX_SCVAL_DEPTH) {
+                // Over-depth branch: collapse to a single opaque terminal so the
+                // downstream parseConfidence gate sees the fail-closed freshness hit.
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
             const arr = (val.vec() ?? []);
             return {
                 type: 'vec',
-                value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals)),
+                value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)),
+            };
+        }
+        case 'scvMap': {
+            if (depth >= MAX_SCVAL_DEPTH) {
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
+            // Map<Symbol, ScVal> is the canonical data shape for SAC/SEP-41
+            // transfer/mint/burn events on Stellar mainnet (verified empirically
+            // against txs 112d2392..., eb39f493..., 50d36f5c...). The entry key is
+            // carried forward so readAmount can route to the conventional field
+            // name without re-decoding the full XDR. Non-symbol / non-string keys
+            // are stringified via the same key-to-string rule used for topics.
+            const entries = (val.map() ?? []);
+            return {
+                type: 'map',
+                value: entries.map((entry, i) => ({
+                    key: mapKeyToString(entry.key(), `${path}.key[${i}]`, opaqueScVals),
+                    val: scValToSubset(entry.val(), `${path}.val[${i}]`, opaqueScVals, depth + 1),
+                })),
             };
         }
         case 'scvBytes': {
@@ -335,6 +365,29 @@ export function scValToTopicString(val) {
         return Buffer.from(val.bytes()).toString('hex');
     return `<${kind}>`;
 }
+/** Convert a Map<Symbol, ...> key ScVal to the string used in the normalised
+ *  ScVal map representation. Uses the same string-form rule as
+ *  `scValToTopicString` so SAC/SEP-41 event Map keys ("amount", "to_muxed_id")
+ *  resolve to the same string in both the topic path and the map-entry path.
+ *  Non-symbol / non-string keys record an opaque diagnostic and return a
+ *  placeholder so the Map entry is still carried forward. */
+function mapKeyToString(val, path, opaqueScVals) {
+    const kind = val.switch().name;
+    if (kind === 'scvSymbol')
+        return val.sym().toString();
+    if (kind === 'scvString')
+        return val.str().toString();
+    if (kind === 'scvU64')
+        return u64PartsToBigInt(val.u64()).toString();
+    if (kind === 'scvU32')
+        return val.u32().toString();
+    if (kind === 'scvI128')
+        return i128PartsToBigInt(val.i128()).toString();
+    if (kind === 'scvBytes')
+        return Buffer.from(val.bytes()).toString('hex');
+    opaqueScVals.push({ path, type: `unsupported-map-key:${kind}` });
+    return `<${kind}>`;
+}
 /** Build the OnChainEvent[] view from raw contract events. Diagnostic-only:
  *  captures the topics + data + emitter contract for the downstream
  *  validator. */

package/dist/record/freshness.d.ts

@@ -13,5 +13,18 @@ export declare function computeParseConfidence(input: FreshnessInput): ParseConf
  *  ToolError with the ParseConfidence payload attached as `details`. */
 export declare function isBelowThreshold(c: ParseConfidence): boolean;
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 export declare function buildLowConfidenceQuestion(c: ParseConfidence): string;

package/dist/record/freshness.js

@@ -36,8 +36,23 @@ export function isBelowThreshold(c) {
     return c.overall < c.thresholdUsed;
 }
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 export function buildLowConfidenceQuestion(c) {
+    const hasUnknown = c.unknownContracts.length > 0;
+    const hasOpaque = c.opaqueScVals.length > 0;
     const reasons = [];
     for (const u of c.unknownContracts) {
         reasons.push(`unknown contract ${u.contract} (${u.reason})`);
@@ -46,5 +61,20 @@ export function buildLowConfidenceQuestion(c) {
         reasons.push(`opaque ScVal at ${o.path} (${o.type})`);
     }
     const why = reasons.length === 0 ? 'no diagnostic reason available' : reasons.join('; ');
-    return `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}. Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    const header = `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}.`;
+    // The two remediation branches are explicit so the user (or the agent)
+    // can dispatch on the verb. The "unknown contract" branch is the only
+    // one that asks for an ABI; the "opaque ScVal" branch asks the user to
+    // report the path and re-run after a tool upgrade.
+    if (hasUnknown && hasOpaque) {
+        return (`${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version; ` +
+            `also file the opaque ScVal path against the recorder (decoder limitation) and re-run record_transaction after a tool upgrade.`);
+    }
+    if (hasUnknown) {
+        return `${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    }
+    if (hasOpaque) {
+        return `${header} This is a recorder decoder limitation (the value shape is supported in principle but not yet decoded) - the agent cannot fix it by supplying an ABI. Report the opaque ScVal path above against the recorder and re-run record_transaction after a tool upgrade.`;
+    }
+    return `${header} No actionable diagnostic was recorded; re-run record_transaction against a fresh fetch and inspect the events.`;
 }

package/dist/record/index.d.ts

@@ -5,6 +5,9 @@ import { type RpcFetcher } from './rpc.ts';
  *    - exactly one of `hash` / `xdr`
  *    - `network` for hash mode (selects the public RPC)
  *    - optional injected `fetcher` for tests + custom RPC endpoints
+ *    - optional `crossNetworkFetcher` (item 2) for tests + offline use;
+ *      production builds the cross-network probe from `createRpcServer` when
+ *      this field is absent
  *    - optional `confidenceOverride` to relax the gate (default 1.0)
  *
  *  In xdr mode `network` is still required so the caller documents intent
@@ -15,6 +18,14 @@ export interface RecordInput {
     xdr?: string;
     network: Network;
     fetcher?: RpcFetcher;
+    /** Test-only seam + explicit production override for the cross-network
+     *  probe (item 2). When the primary fetcher returns null on hash mode,
+     *  the recorder also tries this fetcher against the OTHER network. If it
+     *  finds the hash there, the recorder returns a specific actionable
+     *  error mentioning the actual network. When unset, the recorder builds
+     *  this fetcher from `createRpcServer(otherNetwork)` so the help fires
+     *  automatically; tests can pass a deterministic stub. */
+    crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;

package/dist/record/index.js

@@ -50,6 +50,21 @@ export async function recordTransaction(input) {
             return err('RECORDING_FAILED', 'hash required for on-chain mode', false);
         const fetched = await fetcher(hash);
         if (!fetched) {
+            // Item 2: cross-network sanity check. The default NOT_FOUND message
+            // ("transaction X not found on <network>") is not actionable when the
+            // user just used the wrong --network. Probe the OTHER network's
+            // fetcher before giving up: if the hash actually exists there, the
+            // user almost certainly passed the wrong network flag. Trade-off:
+            // one extra RPC round-trip ONLY on the NOT_FOUND path (the happy
+            // path is unchanged; NOT_FOUND is rare). The probe is auto-built
+            // from createRpcServer(otherNetwork) when the caller did not inject
+            // one; tests pass an explicit stub for offline determinism.
+            const otherNetwork = input.network === 'mainnet' ? 'testnet' : 'mainnet';
+            const crossFetcher = input.crossNetworkFetcher ?? createRpcServer(otherNetwork);
+            const crossFetched = await crossFetcher(hash);
+            if (crossFetched) {
+                return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}; it exists on ${otherNetwork}. Re-run with --network ${otherNetwork} (or the corresponding MCP / API field).`, true);
+            }
             return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}`, true);
         }
         const events = combineEvents(fetched.events);
@@ -125,6 +140,16 @@ function finish(network, decoded, confidenceOverride) {
         unknownContracts: decoded.unknownContracts,
         opaqueScVals: decoded.opaqueScVals,
     });
+    // Item 1: surface the "zero contract invocations decoded" case explicitly.
+    // The math already pins overall = 1.0 via the `denom === 0` guard; the
+    // marker just makes the silence visible so a downstream synth can refuse
+    // the recording (a policy must scope to an authorized contract call)
+    // without inferring the situation from `invocations: []` next to a
+    // confidence of 1.0. Only set when zero invocations were actually decoded
+    // - the marker is a positive signal, not a default.
+    if (decoded.invocations.length === 0) {
+        confidence = { ...confidence, noInvocations: true };
+    }
     if (typeof confidenceOverride === 'number') {
         confidence = { ...confidence, thresholdUsed: confidenceOverride };
     }

package/dist/record/movements.d.ts

@@ -9,9 +9,21 @@ export declare function extractTokenMovements(events: OnChainEvent[], opaqueScVa
 }>): TokenMovement[];
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 export declare function readAmount(data: OnChainEvent['data']): string | null;
 /** Re-decode a single ContractEvent body into a TokenMovement-shaped tuple,
  *  given the raw xdr.ScVal form (NOT the OnChainEvent subset). Used by the

package/dist/record/movements.js

@@ -81,25 +81,60 @@ function parseSingleEvent(evt) {
 }
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 export function readAmount(data) {
     if (data.type === 'i128')
         return data.value;
     if (data.type === 'u64')
         return data.value;
+    if (data.type === 'map')
+        return readAmountFromMap(data.value);
     if (data.type !== 'vec')
         return null;
-    const v = data.value;
-    // SAC transfer event data shape (some clients): Vec<Address, I128>
-    for (const item of v) {
+    // Vec shape: walk the elements and accept the first I128/U64 OR a Map whose
+    // 'amount' entry is I128/U64. SAC transfer event data is sometimes
+    // Vec<Address, I128> and sometimes Vec<Map{amount: I128}, ...>; both reach
+    // the same code path below.
+    for (const item of data.value) {
         if (item.type === 'i128')
             return item.value;
         if (item.type === 'u64')
             return item.value;
+        if (item.type === 'map') {
+            const fromMap = readAmountFromMap(item.value);
+            if (fromMap !== null)
+                return fromMap;
+        }
+    }
+    return null;
+}
+/** Try to extract an I128/U64 amount from a Map's `amount` entry. Returns
+ *  null when the Map lacks an `amount` key or the entry is not a numeric
+ *  ScVal kind this recorder understands. */
+function readAmountFromMap(entries) {
+    for (const entry of entries) {
+        if (entry.key !== 'amount')
+            continue;
+        if (entry.val.type === 'i128')
+            return entry.val.value;
+        if (entry.val.type === 'u64')
+            return entry.val.value;
+        return null;
     }
-    // Some flavours wrap in a Map. We expose Map entries as other; bail.
     return null;
 }
 /** Extract a single address from an event data ScVal at the given vec index. */

package/dist/run/index.d.ts

@@ -0,0 +1,43 @@
+import { type ErrorCode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
+export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
+export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
+export type RunRecordTransactionInput = RecordTransactionInput;
+export type RunSynthesizePolicyInput = SynthesizePolicyInput;
+/** `record_transaction` body - wraps `recordTransaction`. The tool input
+ *  matches the core RecordInput minus the injected `fetcher` (the transport
+ *  layer does not own the RPC). Returns the core ToolResponse unchanged.
+ *
+ *  Item 6: a try/catch envelope wraps the core call. The core's own
+ *  `recordTransaction` already returns `{ok:false, error}` for Zod + decoder
+ *  failures, but a throw from the SDK (e.g. a malformed hash handed to
+ *  `@stellar/stellar-sdk`'s StrKey decoder) would otherwise surface as
+ *  "[object Object]" in the MCP transport. The envelope converts any
+ *  non-ToolResponse throw into a structured `RECORDING_FAILED` ToolError so
+ *  the agent always sees a machine-readable error code. */
+export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse<RecordedTransaction>>;
+/** `synthesize_policy` body - discriminated union on `source`:
+ *    - `mandate`   -> synthesizeFromMandate
+ *    - `recording` -> synthesizeFromRecording
+ *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
+ *  letting the agent pick the deterministic or the inferred path. The CLI
+ *  routes the same way.
+ *
+ *  Item 6: same try/catch envelope as `runRecordTransaction`. The core
+ *  `synthesizeFromRecording` already converts ToolError-shaped throws to
+ *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
+ *  XDR decode error in the adapter) would otherwise surface as
+ *  "[object Object]" in the MCP transport. */
+export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;
+/** Build a canonical ToolError for a thrown exception caught by the tool
+ *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, so we extract a string-friendly message and tag the original
+ *  error in `details` for the agent to inspect. The `code` is the tool's
+ *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
+ *  for `synthesize_policy`) so the agent dispatches on the same code the
+ *  structured ToolError would carry.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+export declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy', code: ErrorCode, e: unknown): ToolError;

package/dist/run/index.js

@@ -0,0 +1,222 @@
+// packages/policy-synth/src/run/index.ts
+//
+// Tool-body adapters for the two core front-ends. Reachable as
+// `@crediolabs/policy-synth/run` from both the MCP server (which re-exports
+// for tool-registration glue) and the CLI (which calls them directly). Each
+// body is a THIN adapter over the pure core:
+//
+//   1. Re-validate the parsed input via Zod. This is a defence-in-depth check -
+//      the SDK has already parsed it through the registered schema, but we never
+//      want a tool body to throw on garbage (the SDK treats uncaught throws as
+//      transport errors and the agent loses the machine-readable ToolError).
+//   2. Dispatch to the matching core entry point with the minimum required
+//      inputs.
+//   3. Return the core's ToolResponse<T> unchanged. The server layer maps it
+//      to the MCP envelope; nothing here knows about MCP.
+//
+// No business logic. No retries. No session state. The same call shape can
+// drive the CLI (which calls into the same core directly without MCP).
+import { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from "../index.js";
+import { RecordTransactionInputSchema, SynthesizePolicyInputSchema, } from "./schemas.js";
+// Re-export the underlying Zod schemas so the MCP package (and any other
+// downstream consumer) can import the canonical input shapes from the same
+// module that owns the tool-body glue. The strict schemas are the source of
+// truth - MCP tool shapes are derived from them.
+export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from "./schemas.js";
+/** `record_transaction` body - wraps `recordTransaction`. The tool input
+ *  matches the core RecordInput minus the injected `fetcher` (the transport
+ *  layer does not own the RPC). Returns the core ToolResponse unchanged.
+ *
+ *  Item 6: a try/catch envelope wraps the core call. The core's own
+ *  `recordTransaction` already returns `{ok:false, error}` for Zod + decoder
+ *  failures, but a throw from the SDK (e.g. a malformed hash handed to
+ *  `@stellar/stellar-sdk`'s StrKey decoder) would otherwise surface as
+ *  "[object Object]" in the MCP transport. The envelope converts any
+ *  non-ToolResponse throw into a structured `RECORDING_FAILED` ToolError so
+ *  the agent always sees a machine-readable error code. */
+export async function runRecordTransaction(raw) {
+    const parsed = RecordTransactionInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('record_transaction', parsed.error.issues),
+        };
+    }
+    const input = parsed.data;
+    // Strip the wire-only `confidenceOverride` and pass the rest straight through.
+    const coreInput = {
+        network: input.network,
+        ...(input.hash !== undefined ? { hash: input.hash } : {}),
+        ...(input.xdr !== undefined ? { xdr: input.xdr } : {}),
+        ...(input.confidenceOverride !== undefined
+            ? { confidenceOverride: input.confidenceOverride }
+            : {}),
+    };
+    try {
+        return await recordTransaction(coreInput);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: caughtError('record_transaction', 'RECORDING_FAILED', e),
+        };
+    }
+}
+/** `synthesize_policy` body - discriminated union on `source`:
+ *    - `mandate`   -> synthesizeFromMandate
+ *    - `recording` -> synthesizeFromRecording
+ *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
+ *  letting the agent pick the deterministic or the inferred path. The CLI
+ *  routes the same way.
+ *
+ *  Item 6: same try/catch envelope as `runRecordTransaction`. The core
+ *  `synthesizeFromRecording` already converts ToolError-shaped throws to
+ *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
+ *  XDR decode error in the adapter) would otherwise surface as
+ *  "[object Object]" in the MCP transport. */
+export async function runSynthesizePolicy(raw) {
+    const parsed = SynthesizePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('synthesize_policy', parsed.error.issues),
+        };
+    }
+    const input = parsed.data;
+    const ozConfig = resolveOzConfig(input);
+    try {
+        if (input.source === 'mandate') {
+            // Zod's optional fields widen to `T | undefined`, which the core's
+            // exact-optional MandateSpec rejects; the schema already validated the
+            // shape, so assert it (same pattern as the recordedTx cast below).
+            return await synthesizeFromMandate(input.mandate, ozConfig);
+        }
+        // recording source
+        const recorded = input.recordedTx;
+        return await synthesizeFromRecording(recorded, {
+            network: input.network,
+            ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+            ...(input.confidenceOverride !== undefined
+                ? { confidenceOverride: input.confidenceOverride }
+                : {}),
+            ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+        }, ozConfig);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: caughtError('synthesize_policy', 'SYNTHESIS_ERROR', e),
+        };
+    }
+}
+function resolveOzConfig(input) {
+    if (input.ozConfig)
+        return input.ozConfig;
+    // The mandate path is network-agnostic; fall back to mainnet so the
+    // placeholder OZ instance addresses are deterministic.
+    return placeholderOzConfig('mainnet');
+}
+/** Build a canonical ToolError for a Zod validation failure. The remediation
+ *  hint points the agent back at the right tool with an empty arg bag - the
+ *  tool name IS the machine-readable hint. */
+function validationError(toolName, issues) {
+    const code = toolName === 'record_transaction' ? 'RECORDING_FAILED' : 'SYNTHESIS_ERROR';
+    return {
+        code,
+        message: `${toolName}: invalid input: ${issues
+            .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+            .join('; ')}`,
+        severity: 'error',
+        retryable: false,
+        remediation: {
+            toolCall: { name: toolName, args: {} },
+        },
+    };
+}
+/** Build a canonical ToolError for a thrown exception caught by the tool
+ *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, so we extract a string-friendly message and tag the original
+ *  error in `details` for the agent to inspect. The `code` is the tool's
+ *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
+ *  for `synthesize_policy`) so the agent dispatches on the same code the
+ *  structured ToolError would carry.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+export function caughtError(toolName, code, e) {
+    const message = describeThrown(e, toolName);
+    const details = { thrown: safeStringify(e) };
+    return {
+        code,
+        message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+        severity: 'error',
+        retryable: false,
+        remediation: {
+            toolCall: { name: toolName, args: {} },
+        },
+        details,
+    };
+}
+/** Build a human-readable message for an unknown caught value. Order matters:
+ *    1. `Error` instances use `.message` (or fallback to the class name).
+ *    2. Native strings pass through verbatim.
+ *    3. Objects with a string `message` field use that field (mirrors the
+ *       shape thrown by some SDKs that package errors as plain objects).
+ *    4. Anything else falls back to a JSON-shaped summary, never to
+ *       "[object Object]".
+ *  The full payload is also captured in `details.thrown` via
+ *  `safeStringify` so the agent can inspect the original value without
+ *  risking an infinite loop on circular refs. */
+function describeThrown(e, toolName) {
+    if (e instanceof Error) {
+        return e.message || `${toolName}: ${e.name || 'Error'}`;
+    }
+    if (typeof e === 'string') {
+        return e;
+    }
+    if (e !== null && typeof e === 'object') {
+        const obj = e;
+        const m = obj.message;
+        if (typeof m === 'string' && m.length > 0) {
+            return truncate(m);
+        }
+        return truncate(safeStringify(e));
+    }
+    return `${toolName}: caught non-Error throw of type ${typeof e}`;
+}
+/** Hard cap on the human-readable message embedded in the ToolError. The full
+ *  payload is still preserved in `details.thrown` so the agent can inspect
+ *  it - the truncation is only to keep the top-level message small enough to
+ *  fit comfortably in transport logs. */
+const MAX_MESSAGE_LEN = 512;
+/** JSON.stringify that survives circular refs and very large payloads. The
+ *  output is itself bounded by the same `MAX_DETAILS_LEN` so a thrown object
+ *  with megabytes of buffer data cannot bloat the WHOLE envelope. */
+const MAX_DETAILS_LEN = 4096;
+function safeStringify(v) {
+    const seen = new WeakSet();
+    const json = JSON.stringify(v, (_k, value) => {
+        if (typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'function')
+            return `[function ${value.name || 'anonymous'}]`;
+        if (value instanceof Error) {
+            return { name: value.name, message: value.message, stack: value.stack };
+        }
+        if (value !== null && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        return value;
+    }, 2);
+    if (json === undefined)
+        return '<unserializable>';
+    return truncate(json, MAX_DETAILS_LEN);
+}
+function truncate(s, cap = MAX_MESSAGE_LEN) {
+    if (s.length <= cap)
+        return s;
+    return `${s.slice(0, cap)}\n…[truncated ${s.length - cap} chars]`;
+}