@crediolabs/policy-synth 0.1.3 → 0.1.5

package/src/run/index.ts

@@ -0,0 +1,213 @@
+// 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. We refuse to surface the raw exception's text (the MCP SDK
+ *  stringifies thrown objects as "[object Object]"), 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. */
+function caughtError(
+  toolName: 'record_transaction' | 'synthesize_policy',
+  code: ErrorCode,
+  e: unknown
+): ToolError {
+  let message: string
+  if (e instanceof Error) {
+    message = e.message || `${toolName}: unknown error`
+  } else if (typeof e === 'string') {
+    message = e
+  } else {
+    message = `${toolName}: caught non-Error throw of type ${typeof e}`
+  }
+  return {
+    code,
+    message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+    severity: 'error',
+    retryable: false,
+    remediation: {
+      toolCall: { name: toolName, args: {} },
+    },
+    details: { thrown: String(e) },
+  }
+}

package/src/run/schemas.ts

@@ -0,0 +1,242 @@
+// packages/policy-synth/src/run/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// step with the TS source of truth.
+//
+// i128 amounts and other large integers are carried as base-10 decimal strings
+// end-to-end (no JS number coercion). Networks are pinned to the same closed
+// set the core defines. The discriminated union on `source` exposes BOTH
+// synthesize_policy front-ends through a single tool input.
+//
+// This module is the SINGLE source of truth for these shapes. The MCP package
+// imports them here so its tool-shape bindings stay in step; the CLI imports
+// them here so it can build the same args envelope the MCP transport builds.
+
+import { z } from 'zod'
+
+/** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
+ *  installed on-chain, so reject it at the boundary (fail-closed). */
+const U32_MAX = 4294967295
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512
+
+export const NetworkSchema = z.enum(['mainnet', 'testnet'])
+export type Network = z.infer<typeof NetworkSchema>
+
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ type: z.literal('address'), value: z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    z.object({ type: z.literal('i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ type: z.literal('u64'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('u32'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('symbol'), value: z.string() }),
+    z.object({ type: z.literal('vec'), value: z.array(ScValSchema) }),
+    z.object({ type: z.literal('bytes'), value: z.string() }),
+    z.object({ type: z.literal('other'), value: z.string() }),
+  ])
+)
+
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+export const ContractInvocationSchema: z.ZodType<unknown> = z.object({
+  contract: z.string(),
+  fn: z.string(),
+  args: z.array(ScValSchema),
+  subInvocations: z.array(z.lazy(() => ContractInvocationSchema)),
+})
+
+export const TokenMovementSchema = z.object({
+  token: z.string(),
+  from: z.string(),
+  to: z.string(),
+  // The recorder reads the amount straight from the signed i128 event value
+  // (record/movements.ts readAmount), so a non-standard token that emits a
+  // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+  // that here; the synth gate, not the wire schema, decides what to do with it.
+  amount: z.string().regex(/^-?[0-9]+$/),
+})
+
+export const OnChainEventSchema = z.object({
+  contract: z.string(),
+  topics: z.array(z.string()),
+  data: ScValSchema,
+})
+
+export const ParseConfidenceSchema = z.object({
+  overall: z.number().min(0).max(1),
+  knownContracts: z.array(z.string()),
+  unknownContracts: z.array(
+    z.object({
+      contract: z.string(),
+      reason: z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })
+  ),
+  opaqueScVals: z.array(z.object({ path: z.string(), type: z.string() })),
+  thresholdUsed: z.number().min(0).max(1),
+})
+
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+export const RecordedTransactionSchema = z
+  .object({
+    network: NetworkSchema,
+    signers: z.array(z.string()),
+    invocations: z.array(ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: z.array(TokenMovementSchema),
+    events: z.array(OnChainEventSchema),
+    authEntries: z.array(z.unknown()),
+    ledgerSequence: z.number().int().nonnegative(),
+    fetchedAt: z.number().int().nonnegative(),
+    parseConfidence: ParseConfidenceSchema,
+    sourceAccount: z.string(),
+  })
+  .passthrough()
+
+/** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
+ *  front-end needs no parseConfidence; the tool adapter injects the full
+ *  confidence after synthesis so the orchestrator can compare. */
+export const MandateSpecSchema = z
+  .object({
+    chain: z.literal('stellar'),
+    contract: z.string(),
+    method: z.string().optional(),
+    spendingLimit: z
+      .object({
+        token: z.string(),
+        limit: z.string().regex(/^[0-9]+$/),
+        windowSeconds: z.number().int().positive(),
+      })
+      .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: z.number().int().positive().optional(),
+    recipients: z.array(z.string()).optional(),
+    expiry: z
+      .object({
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: z.number().int().positive().optional(),
+      })
+      .optional(),
+  })
+  .passthrough()
+
+/** ComposeUserResponses mirrors the core. */
+export const ComposeUserResponsesSchema = z
+  .object({
+    windowSeconds: z.number().int().positive().optional(),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: z
+      .string()
+      .regex(/^[0-9]+$/)
+      .optional(),
+    invocationLimit: z.number().int().positive().optional(),
+  })
+  .passthrough()
+
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+export const OzAdapterConfigSchema = z.object({
+  network: NetworkSchema,
+  instances: z.object({
+    spending_limit: z.string(),
+    simple_threshold: z.string(),
+    weighted_threshold: z.string(),
+  }),
+})
+
+// ===== record_transaction =====
+
+export const RecordTransactionInputSchema = z
+  .object({
+    hash: z.string().min(1).optional(),
+    xdr: z.string().min(1).optional(),
+    network: NetworkSchema,
+    confidenceOverride: z.number().min(0).max(1).optional(),
+  })
+  .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+  })
+  .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+  })
+export type RecordTransactionInput = z.infer<typeof RecordTransactionInputSchema>
+
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+
+export const SynthesizePolicyMandateInputSchema = z.object({
+  source: z.literal('mandate'),
+  mandate: MandateSpecSchema,
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+/** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
+ *  express (per-method scoping, invocation-count windows, oracle bounds, exact
+ *  hop paths) lower to a real interpreter predicate document instead of being
+ *  surfaced as warnings. The core deep-validates `smartAccountAddress` (a C...
+ *  contract, not the recording's G... source) and the tighten-only oracle
+ *  bounds; the schema stays light so the core owns the friendly ToolErrors. */
+export const InterpreterOptionsSchema = z.object({
+  smartAccountAddress: z.string(),
+  installNonce: z.number().int().positive().optional(),
+  oracleParams: z
+    .object({
+      maxStalenessSeconds: z.number().int().positive().optional(),
+      maxDeviationBps: z.number().int().positive().optional(),
+    })
+    .optional(),
+})
+
+export const SynthesizePolicyRecordingInputSchema = z.object({
+  source: z.literal('recording'),
+  recordedTx: RecordedTransactionSchema,
+  network: NetworkSchema,
+  userResponses: ComposeUserResponsesSchema.optional(),
+  confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+  interpreter: InterpreterOptionsSchema.optional(),
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
+  SynthesizePolicyMandateInputSchema,
+  SynthesizePolicyRecordingInputSchema,
+])
+export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>
+
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+export const ToolErrorSchema = z
+  .object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: z.boolean(),
+    remediation: z
+      .object({
+        toolCall: z.object({ name: z.string(), args: z.record(z.unknown()) }).optional(),
+        userQuestion: z.object({ code: z.string(), question: z.string() }).optional(),
+        docsUrl: z.string().optional(),
+      })
+      .optional(),
+    details: z.unknown().optional(),
+  })
+  .passthrough()