@crediolabs/policy-synth 0.1.4 → 0.1.6

package/src/record/decode.ts

@@ -18,13 +18,14 @@
 
 import { Address, StrKey, xdr } from '@stellar/stellar-sdk'
 import { identifyProtocol } from '../registry/identify.ts'
-import type {
-  ContractInvocation,
-  Network,
-  OnChainEvent,
-  ParseConfidence,
-  ScVal,
-  TokenMovement,
+import {
+  type ContractInvocation,
+  MAX_SCVAL_DEPTH,
+  type Network,
+  type OnChainEvent,
+  type ParseConfidence,
+  type ScVal,
+  type TokenMovement,
 } from '../types.ts'
 
 /** Result of decoding an envelope XDR plus the surrounding metadata from
@@ -334,11 +335,15 @@ function symbolValueFromBufferOrString(s: string | Buffer): 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. */
+ *  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: xdr.ScVal,
   path: string,
-  opaqueScVals: ParseConfidence['opaqueScVals']
+  opaqueScVals: ParseConfidence['opaqueScVals'],
+  depth = 0
 ): ScVal {
   const kind = val.switch().name
   switch (kind) {
@@ -364,14 +369,40 @@ export function scValToSubset(
       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() ?? []) as xdr.ScVal[]
       return {
         type: 'vec',
         value: arr.map((v: xdr.ScVal, i: number) =>
-          scValToSubset(v, `${path}[${i}]`, opaqueScVals)
+          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() ?? []) as xdr.ScMapEntry[]
+      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': {
       return { type: 'bytes', value: Buffer.from(val.bytes() as Uint8Array).toString('hex') }
     }
@@ -458,6 +489,28 @@ export function scValToTopicString(val: xdr.ScVal): string {
   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: xdr.ScVal,
+  path: string,
+  opaqueScVals: ParseConfidence['opaqueScVals']
+): string {
+  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() as Uint8Array).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/src/record/freshness.ts

@@ -49,8 +49,23 @@ export 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 function buildLowConfidenceQuestion(c: ParseConfidence): string {
+  const hasUnknown = c.unknownContracts.length > 0
+  const hasOpaque = c.opaqueScVals.length > 0
   const reasons: string[] = []
   for (const u of c.unknownContracts) {
     reasons.push(`unknown contract ${u.contract} (${u.reason})`)
@@ -59,5 +74,22 @@ export function buildLowConfidenceQuestion(c: ParseConfidence): string {
     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/src/record/index.ts

@@ -41,6 +41,9 @@ import { validateAgainstEvents } from './validate.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
@@ -51,6 +54,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
 }
 
@@ -92,6 +103,25 @@ export async function recordTransaction(input: RecordInput): Promise<RecordResul
     if (!hash) 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: Network = 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)
@@ -184,6 +214,16 @@ function finish(
     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/src/record/movements.ts

@@ -87,20 +87,53 @@ function parseSingleEvent(evt: OnChainEvent): TokenMovement | null {
 
 /** 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: OnChainEvent['data']): string | null {
   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: Array<{ key: string; val: OnChainEvent['data'] }>
+): string | null {
+  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
 }
 

package/src/run/index.ts

@@ -0,0 +1,277 @@
+// 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 {
+  type ErrorCode,
+  type MandateSpec,
+  type OzAdapterConfig,
+  type ProposedPolicy,
+  placeholderOzConfig,
+  type RecordedTransaction,
+  recordTransaction,
+  type SynthesizeFromRecordingOptions,
+  synthesizeFromMandate,
+  synthesizeFromRecording,
+  type ToolError,
+  type ToolResponse,
+} from '../index.ts'
+import {
+  type RecordTransactionInput,
+  RecordTransactionInputSchema,
+  type SynthesizePolicyInput,
+  SynthesizePolicyInputSchema,
+} from './schemas.ts'
+
+export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts'
+// 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.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 async function runRecordTransaction(
+  raw: unknown
+): Promise<ToolResponse<RecordedTransaction>> {
+  const parsed = RecordTransactionInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: validationError('record_transaction', parsed.error.issues),
+    }
+  }
+  const input: RecordTransactionInput = 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: unknown): Promise<ToolResponse<ProposedPolicy>> {
+  const parsed = SynthesizePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: validationError('synthesize_policy', parsed.error.issues),
+    }
+  }
+  const input = parsed.data
+  const ozConfig: OzAdapterConfig = 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 as MandateSpec, ozConfig)
+    }
+    // recording source
+    const recorded: RecordedTransaction = input.recordedTx as RecordedTransaction
+    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 } : {}),
+      } as SynthesizeFromRecordingOptions,
+      ozConfig
+    )
+  } catch (e) {
+    return {
+      ok: false,
+      error: caughtError('synthesize_policy', 'SYNTHESIS_ERROR', e),
+    }
+  }
+}
+
+function resolveOzConfig(input: SynthesizePolicyInput): OzAdapterConfig {
+  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: 'record_transaction' | 'synthesize_policy',
+  issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>
+): ToolError {
+  const code: ErrorCode = 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: 'record_transaction' | 'synthesize_policy',
+  code: ErrorCode,
+  e: unknown
+): ToolError {
+  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: unknown, toolName: string): string {
+  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 as Record<string, unknown>
+    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: unknown): string {
+  const seen = new WeakSet<object>()
+  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: string, cap = MAX_MESSAGE_LEN): string {
+  if (s.length <= cap) return s
+  return `${s.slice(0, cap)}\n…[truncated ${s.length - cap} chars]`
+}