@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/plugins/ixo-transaction/tools.ts

@@ -0,0 +1,329 @@
+/**
+ * The ixo-transaction tools. Three read tools resolve and validate a draft;
+ * `sign_ixo_transaction` dispatches the validated transaction to the user's
+ * Portal wallet as the hidden `sign_transaction` AG-UI action over the
+ * realtime channel (`ctx.frontend.callAgAction`) and maps the answer to a
+ * status. The oracle never signs, broadcasts or holds a key: the wallet does,
+ * in the user's browser.
+ *
+ * Every request names its chain id; the Portal refuses any other chain. A
+ * signed testnet transaction is recorded as a receipt (`receipts.ts`), and a
+ * mainnet draft is dispatched only when it cites the receipt of the same
+ * message.
+ */
+import {
+  DEFERRED_MODULES,
+  MESSAGE_CATALOG,
+  QUERY_ONLY_MODULES,
+  SIGN_TRANSACTION_ACTION_NAME,
+  TransactionDraftInputSchema,
+  TransactionDraftSchema,
+  buildSignTransactionActionArgs,
+  classifyIntent,
+  describeValidationError,
+  validateTransactionDraft,
+  type Network,
+  type SingleSignTransactionActionArgs,
+  type ITrxMsg,
+  type TestnetReceipt,
+} from '@ixo/ixo-transaction';
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import { logActionToMatrix } from '../portal/action-log';
+import { recordTestnetReceipt, testnetReceiptProblem } from './receipts';
+import {
+  requestWalletSignature,
+  walletUnavailableReason,
+  type WalletSignatureOutcome,
+} from './wallet-signing';
+
+export interface IxoTransactionToolOptions {
+  /** How long the wallet has to answer a signing request. */
+  signTimeoutMs: number;
+  /** Whether mainnet drafts may pass validation at all. */
+  allowMainnet: boolean;
+  /** The chain id each network's requests are for. */
+  chainIds: Readonly<Record<Network, string>>;
+}
+
+/** What `sign_ixo_transaction` returns to the model. */
+export type SignIxoTransactionResult =
+  | {
+      status: 'signed';
+      network: Network;
+      chainId: string;
+      typeUrl: string;
+      transactionHash?: string;
+      code?: number;
+      height?: string | number;
+      /** Testnet only: cite it in the mainnet draft of the same message. */
+      testnetReceipt?: TestnetReceipt & { expiresInHours: number };
+      /** Testnet only: why no receipt could be recorded. */
+      receiptError?: string;
+    }
+  | {
+      /** Included in a block but failed: the hash and code are real. */
+      status: 'failed';
+      network: Network;
+      chainId: string;
+      typeUrl: string;
+      code: number;
+      transactionHash?: string;
+      height?: string | number;
+      error: string;
+    }
+  | {
+      status: 'rejected' | 'error';
+      network: Network;
+      typeUrl: string;
+      error: string;
+    }
+  | {
+      status: 'timeout';
+      /** The wallet may still sign after the oracle stopped waiting. */
+      outcome: 'unknown';
+      network: Network;
+      typeUrl: string;
+      error: string;
+    }
+  | { status: 'validation_error' | 'unavailable'; error: string };
+
+const RouteListToolSchema = z.object({
+  messageType: z
+    .string()
+    .optional()
+    .describe(
+      'Module to list (entity, iid, claims, token, smart-account); all when omitted',
+    ),
+});
+
+const IntentInputToolSchema = z.object({
+  input: z
+    .string()
+    .min(1)
+    .describe('A slash command, Msg name, typeUrl, or the user request'),
+});
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function listRoutes(messageType: string | undefined) {
+  const module = messageType?.trim().toLowerCase();
+  return {
+    slashCommandFormat: '/ixo {message-type} {message-action}',
+    queryOnlyModules: QUERY_ONLY_MODULES,
+    deferredModules: DEFERRED_MODULES,
+    routes: MESSAGE_CATALOG.filter(
+      (entry) => !module || entry.module === module,
+    ).map((entry) => ({
+      command: `/ixo ${entry.module} ${entry.action}`,
+      messageName: entry.messageName,
+      typeUrl: entry.typeUrl,
+      fields: entry.fields,
+      riskLevel: entry.riskLevel,
+      risks: entry.risks,
+    })),
+  };
+}
+
+/** The tool's status for a signing outcome: which network, chain and message. */
+function signResult(
+  args: SingleSignTransactionActionArgs,
+  outcome: WalletSignatureOutcome,
+): SignIxoTransactionResult {
+  const network = args.network;
+  const typeUrl = args.intent.typeUrl;
+  switch (outcome.status) {
+    case 'signed':
+    case 'failed':
+      return { ...outcome, network, chainId: args.chainId, typeUrl };
+    case 'rejected':
+    case 'error':
+    case 'timeout':
+      return { ...outcome, network, typeUrl };
+    case 'unavailable':
+      return outcome;
+  }
+}
+
+/**
+ * For a mainnet draft: why its `testnetReceipt` does not prove a testnet
+ * signing of the same message by this user, or null. Null for other networks.
+ */
+async function mainnetReceiptProblem(
+  ctx: RuntimeContext,
+  options: IxoTransactionToolOptions,
+  network: Network,
+  receipt: TestnetReceipt | undefined,
+  message: ITrxMsg | undefined,
+): Promise<string | null> {
+  if (network !== 'mainnet') return null;
+  if (!receipt || !message) {
+    return 'Mainnet draft blocked: sign the same transaction on testnet first and pass the testnetReceipt that signing returned';
+  }
+  return testnetReceiptProblem(ctx, receipt, message, options.chainIds.testnet);
+}
+
+/** The draft's `testnetReceipt`, when it has a well-formed one. */
+function testnetReceiptOf(input: unknown): TestnetReceipt | undefined {
+  const parsed = TransactionDraftSchema.safeParse(input);
+  return parsed.success ? parsed.data.testnetReceipt : undefined;
+}
+
+/** A signed testnet transaction gets a receipt the mainnet draft can cite. */
+async function withTestnetReceipt(
+  ctx: RuntimeContext,
+  args: SingleSignTransactionActionArgs,
+  result: SignIxoTransactionResult,
+): Promise<SignIxoTransactionResult> {
+  const message = args.messages[0];
+  if (
+    result.status !== 'signed' ||
+    args.network !== 'testnet' ||
+    result.transactionHash === undefined ||
+    !message
+  ) {
+    return result;
+  }
+  try {
+    const receipt = await recordTestnetReceipt(ctx, {
+      transactionHash: result.transactionHash,
+      message,
+      chainId: args.chainId,
+    });
+    return { ...result, testnetReceipt: { ...receipt, expiresInHours: 24 } };
+  } catch (error) {
+    return {
+      ...result,
+      receiptError: `The testnet signing could not be recorded (${errorText(error)}); a mainnet run of this transaction will be refused until a testnet signing is recorded.`,
+    };
+  }
+}
+
+async function signIxoTransaction(
+  input: unknown,
+  ctx: RuntimeContext,
+  options: IxoTransactionToolOptions,
+): Promise<SignIxoTransactionResult> {
+  let args: SingleSignTransactionActionArgs;
+  try {
+    args = buildSignTransactionActionArgs(input, {
+      allowMainnet: options.allowMainnet,
+      chainIds: options.chainIds,
+    });
+  } catch (error) {
+    return {
+      status: 'validation_error',
+      error: describeValidationError(error),
+    };
+  }
+  const receiptProblem = await mainnetReceiptProblem(
+    ctx,
+    options,
+    args.network,
+    args.testnetReceipt,
+    args.messages[0],
+  );
+  if (receiptProblem !== null) {
+    return { status: 'validation_error', error: receiptProblem };
+  }
+  // Nothing to log in the room when the request cannot be sent at all.
+  const unavailable = walletUnavailableReason(ctx);
+  if (unavailable !== null) {
+    return { status: 'unavailable', error: unavailable };
+  }
+
+  const outcome = await requestWalletSignature(ctx, {
+    args,
+    callIdPrefix: 'ixo_tx',
+    timeoutMs: options.signTimeoutMs,
+  });
+  const result = await withTestnetReceipt(ctx, args, signResult(args, outcome));
+  logActionToMatrix(ctx, {
+    name: SIGN_TRANSACTION_ACTION_NAME,
+    args,
+    result,
+    success: result.status === 'signed',
+    ...('error' in result ? { error: result.error } : {}),
+  });
+  return result;
+}
+
+export function createIxoTransactionTools(
+  options: IxoTransactionToolOptions,
+): PluginTool[] {
+  return [
+    tool(
+      async (input) => {
+        const { messageType } = RouteListToolSchema.parse(input);
+        return listRoutes(messageType);
+      },
+      {
+        name: 'list_ixo_transaction_routes',
+        description:
+          'List the supported IXO transaction routes with their fields, risk level and risks. Read-only.',
+        schema: RouteListToolSchema,
+        effect: 'read',
+      },
+    ),
+    tool(
+      async (input) => {
+        const { input: text } = IntentInputToolSchema.parse(input);
+        try {
+          return { status: 'resolved', intent: classifyIntent(text) };
+        } catch (error) {
+          return { status: 'unresolved', error: errorText(error) };
+        }
+      },
+      {
+        name: 'classify_ixo_transaction_intent',
+        description:
+          'Resolve an IXO transaction route from a slash command, Msg name, typeUrl, or a natural-language request. Read-only.',
+        schema: IntentInputToolSchema,
+        effect: 'read',
+      },
+    ),
+    tool(
+      async (input, ctx) => {
+        let validated: ReturnType<typeof validateTransactionDraft>;
+        try {
+          validated = validateTransactionDraft(input, {
+            allowMainnet: options.allowMainnet,
+          });
+        } catch (error) {
+          return { status: 'invalid', error: describeValidationError(error) };
+        }
+        const receiptProblem = await mainnetReceiptProblem(
+          ctx,
+          options,
+          validated.network,
+          testnetReceiptOf(input),
+          validated.message,
+        );
+        if (receiptProblem !== null) {
+          return { status: 'invalid', error: receiptProblem };
+        }
+        return {
+          status: 'valid',
+          ...validated,
+          chainId: options.chainIds[validated.network],
+        };
+      },
+      {
+        name: 'validate_ixo_transaction_draft',
+        description:
+          'Strictly validate an IXO transaction draft WITHOUT signing: returns the canonical message, its risks and whether the user must confirm them, or what is wrong. Read-only.',
+        schema: TransactionDraftInputSchema,
+        effect: 'read',
+      },
+    ),
+    tool((input, ctx) => signIxoTransaction(input, ctx, options), {
+      name: 'sign_ixo_transaction',
+      description:
+        "Send a validated IXO transaction to the user's Portal wallet for them to sign, and return the outcome: signed (with the tx hash; on testnet also a testnetReceipt), failed (on chain, with hash and code), rejected, timeout (outcome unknown), error, validation_error or unavailable. Only after the user accepted every listed risk; quote each one exactly in riskConfirmation.acceptedRisks. Network defaults to testnet. Mainnet (when the oracle allows it) needs the testnetReceipt of the same transaction signed on testnet. The oracle never signs or broadcasts; the user does, in their wallet.",
+      schema: TransactionDraftInputSchema,
+    }),
+  ];
+}

package/src/plugins/ixo-transaction/wallet-signing.ts

@@ -0,0 +1,202 @@
+/**
+ * The oracle half of the `sign_transaction` round trip, shared by every
+ * plugin that asks the user's Portal wallet to sign (`sign_ixo_transaction`,
+ * the POD creator's `request_pod_signature`): send the validated action args
+ * over the realtime channel and read the answer through the action's result
+ * contract. The oracle never signs or broadcasts; the wallet does.
+ */
+import {
+  SIGN_TRANSACTION_ACTION_NAME,
+  SignTransactionActionResultSchema,
+  normalizeWalletSignResult,
+  type SignTransactionActionArgs,
+} from '@ixo/ixo-transaction';
+import { reportsUnknownOutcome } from '@ixo/common/ai/frontend-bridge';
+import type {
+  FrontendCallSurface,
+  RuntimeContext,
+} from '../../plugin-api/types';
+
+/** How a signing request ended, before a plugin adds its own context. */
+export type WalletSignatureOutcome =
+  | {
+      status: 'signed';
+      transactionHash?: string;
+      code?: number;
+      height?: string | number;
+    }
+  | {
+      /** Included in a block but failed: the hash and code are real. */
+      status: 'failed';
+      code: number;
+      transactionHash?: string;
+      height?: string | number;
+      error: string;
+    }
+  | { status: 'rejected' | 'error'; error: string }
+  | {
+      status: 'timeout';
+      /**
+       * The wallet may still sign after the oracle stopped waiting. The
+       * tool-execution middleware reads `outcome: 'unknown'`: the write claim
+       * stays and the same request is not dispatched again in the thread.
+       */
+      outcome: 'unknown';
+      error: string;
+    }
+  | { status: 'unavailable'; error: string };
+
+/** The client SDK's answer to an `action_call` for an action it has no handler for. */
+const MISSING_HANDLER = `Action tool ${SIGN_TRANSACTION_ACTION_NAME} not found`;
+
+/**
+ * A wallet's refusal as its error text words it. SignX reports no structured
+ * reason, so a refusal is recognised from the message.
+ */
+const WALLET_REFUSAL = /\b(?:reject|denied|declin|cancel)/i;
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+type WalletChannel =
+  | { ok: true; frontend: FrontendCallSurface; sessionId: string }
+  | { ok: false; reason: string };
+
+/**
+ * The turn's way to the wallet: a session with a realtime channel and a
+ * Portal browser connected to it.
+ */
+function walletChannel(ctx: RuntimeContext): WalletChannel {
+  const sessionId = ctx.session.id;
+  const frontend = ctx.frontend;
+  if (!sessionId || !frontend) {
+    return {
+      ok: false,
+      reason:
+        'Wallet signing needs a Portal session with a realtime connection, which this conversation does not have.',
+    };
+  }
+  if (!frontend.hasClient(sessionId)) {
+    return {
+      ok: false,
+      reason:
+        "No Portal browser is connected to this session, so the transaction cannot reach the user's wallet. Ask the user to open the chat in the Portal.",
+    };
+  }
+  return { ok: true, frontend, sessionId };
+}
+
+/**
+ * Why a signing request cannot reach the user's wallet from this turn, or
+ * null when it can. Nothing is sent either way.
+ */
+export function walletUnavailableReason(ctx: RuntimeContext): string | null {
+  const channel = walletChannel(ctx);
+  return channel.ok ? null : channel.reason;
+}
+
+/** Map a settled bridge call (or its rejection) to an outcome. */
+function settledOutcome(
+  outcome: { ok: true; value: unknown } | { ok: false; error: string },
+  timeoutMs: number,
+): WalletSignatureOutcome {
+  if (outcome.ok && reportsUnknownOutcome(outcome.value)) {
+    // The bridge's own answer when none arrived: the deadline passed, the
+    // socket the request went to is gone, or the turn ended after the
+    // request was sent. The wallet may still have signed.
+    return {
+      status: 'timeout',
+      outcome: 'unknown',
+      error: `The Portal wallet did not answer within ${timeoutMs / 1000} s, or its tab disconnected, and the request timed out. The outcome is unknown: the user may still sign it in their wallet. Do not send it again; ask the user whether it went through.`,
+    };
+  }
+  if (outcome.ok) {
+    // The Portal handler answers with the result contract; anything else is
+    // a raw wallet response from a Portal with its own handler.
+    const contract = SignTransactionActionResultSchema.safeParse(outcome.value);
+    const summary = contract.success
+      ? contract.data
+      : normalizeWalletSignResult(outcome.value);
+    if (summary.delivered) {
+      return {
+        status: 'failed',
+        code: summary.delivered.code,
+        ...(summary.delivered.transactionHash !== undefined
+          ? { transactionHash: summary.delivered.transactionHash }
+          : {}),
+        ...(summary.delivered.height !== undefined
+          ? { height: summary.delivered.height }
+          : {}),
+        error:
+          summary.error ??
+          `The transaction failed on chain with code ${summary.delivered.code}`,
+      };
+    }
+    if (!summary.success) {
+      return {
+        status: 'error',
+        error: summary.error ?? 'The wallet reported a failed transaction',
+      };
+    }
+    return {
+      status: 'signed',
+      ...(summary.transactionHash !== undefined
+        ? { transactionHash: summary.transactionHash }
+        : {}),
+      ...(summary.code !== undefined ? { code: summary.code } : {}),
+      ...(summary.height !== undefined ? { height: summary.height } : {}),
+    };
+  }
+  if (outcome.error === MISSING_HANDLER) {
+    return {
+      status: 'unavailable',
+      error:
+        'This Portal does not handle wallet signing (no sign_transaction handler is registered), so nothing was sent to a wallet.',
+    };
+  }
+  // A rejected call carries only the Portal's error text (a delivered
+  // transaction comes back as `failed` above, with its code and hash), so a
+  // refusal is read from that text — never from a chain log.
+  return {
+    status: WALLET_REFUSAL.test(outcome.error) ? 'rejected' : 'error',
+    error: outcome.error,
+  };
+}
+
+/**
+ * Send `sign_transaction` to the session's Portal tab and wait for the
+ * wallet. The call is bound to the one socket it was sent to and ends as an
+ * unknown outcome on the deadline, a lost socket or the turn's abort after
+ * it was sent. Without a way to the wallet it is `unavailable` and nothing
+ * is sent.
+ */
+export async function requestWalletSignature(
+  ctx: RuntimeContext,
+  request: {
+    args: SignTransactionActionArgs;
+    /** Readable prefix of the call id, e.g. `ixo_tx`. */
+    callIdPrefix: string;
+    timeoutMs: number;
+  },
+): Promise<WalletSignatureOutcome> {
+  const channel = walletChannel(ctx);
+  if (!channel.ok) return { status: 'unavailable', error: channel.reason };
+  const toolCallId = `${request.callIdPrefix}_${ctx.session.requestId || 'noreq'}_${crypto
+    .randomUUID()
+    .slice(0, 8)}`;
+  const outcome = await channel.frontend
+    .callAgAction({
+      sessionId: channel.sessionId,
+      toolCallId,
+      toolName: SIGN_TRANSACTION_ACTION_NAME,
+      args: request.args,
+      timeoutMs: request.timeoutMs,
+      signal: ctx.abortSignal,
+    })
+    .then(
+      (value) => ({ ok: true as const, value }),
+      (error: unknown) => ({ ok: false as const, error: errorText(error) }),
+    );
+  return settledOutcome(outcome, request.timeoutMs);
+}

package/src/plugins/mcp-tool-adapter.ts

@@ -24,7 +24,22 @@ export interface RawMcpClientTool {
   name: string;
   description: string;
   schema?: unknown;
-  invoke(input: unknown): Promise<unknown>;
+  invoke(
+    input: unknown,
+    config?: { metadata?: Record<string, unknown> },
+  ): Promise<unknown>;
+}
+
+export interface AdaptMcpClientToolsOptions {
+  /**
+   * Timeout of each tool call's MCP request. `@langchain/mcp-adapters` reads
+   * `metadata.timeoutMs` and hands it to the MCP SDK as the request's
+   * `timeout`, a timer the SDK clears when the response arrives; without it
+   * the SDK's 60 s default applies. Never pass a numeric `timeout` in the
+   * call config instead: LangChain turns that into `AbortSignal.timeout`,
+   * whose timer outlives the call.
+   */
+  requestTimeoutMs?: number;
 }
 
 /** An upstream MCP tool with its schema normalised to Zod. */
@@ -77,11 +92,17 @@ export function mcpToolZodSchema(
 export function adaptMcpClientTools(
   tools: RawMcpClientTool[],
   logger: Logger = NOOP_LOGGER,
+  options: AdaptMcpClientToolsOptions = {},
 ): AdaptedMcpTool[] {
+  const { requestTimeoutMs } = options;
+  const config =
+    requestTimeoutMs === undefined
+      ? undefined
+      : { metadata: { timeoutMs: requestTimeoutMs } };
   return tools.map((t) => ({
     name: t.name,
     description: t.description,
     schema: mcpToolZodSchema(t.schema, t.name, logger),
-    invoke: (input: unknown) => t.invoke(input),
+    invoke: (input: unknown) => t.invoke(input, config),
   }));
 }

package/src/plugins/memory/memory-tools.ts

@@ -98,7 +98,10 @@ export function clearMemoryToolDefsCache(): void {
  * for the life of the isolate.
  */
 const IDLE_CLIENT_CLOSE_MS = 5 * 60 * 1000;
-/** Our own per-call limit (never given to the SDK — see `mcp-call-timeout.ts`). */
+/**
+ * Per-call limit: the MCP request's own timeout (`metadata.timeoutMs`, see
+ * `mcp-tool-adapter.ts`), also enforced by `withCallTimeout`.
+ */
 const MEMORY_TOOL_TIMEOUT_MS = 420_000;
 
 function createMemoryMcpClient(
@@ -303,7 +306,9 @@ function buildLazyUpstreamTools(
       connection = (async () => {
         const client = createMemoryMcpClient(memoryMcpUrl, headers);
         try {
-          const tools = adaptMcpClientTools(await client.getTools(), console);
+          const tools = adaptMcpClientTools(await client.getTools(), console, {
+            requestTimeoutMs: MEMORY_TOOL_TIMEOUT_MS,
+          });
           return { client, byName: new Map(tools.map((t) => [t.name, t])) };
         } catch (error) {
           await client.close().catch(() => undefined);

package/src/plugins/memory/memory-ucan.ts

@@ -1,4 +1,5 @@
 import type { RuntimeContext } from '../../plugin-api/types';
+import { MEMORY_CAPABILITY } from '../delegated-capabilities';
 import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
 
 /**
@@ -31,11 +32,11 @@ export async function buildMemoryHeaders(
 
   const invocation = await mintInvocationSafely(
     runCtx,
-    { did: memoryDid, capability: 'ixo:memory' },
+    { did: memoryDid, capability: MEMORY_CAPABILITY.resource },
     'memory',
     // Claim the ability the user's delegation actually grants. A `'*'` claim is
     // satisfiable only by a `'*'` grant — `'*'.startsWith('memory/')` is false.
-    { can: 'memory/*' },
+    { can: MEMORY_CAPABILITY.action },
   );
   if (!invocation) return null;
 

package/src/plugins/memory/memory.plugin.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { OraclePlugin, type PluginEnv } from '../../plugin-api/oracle-plugin';
+import { MEMORY_CAPABILITY } from '../delegated-capabilities';
 import type {
   MergedConfig,
   PluginManifest,
@@ -42,6 +43,7 @@ const manifest: PluginManifest = {
   category: 'memory',
   visibility: 'always',
   stability: 'stable',
+  requires: [MEMORY_CAPABILITY],
 };
 
 export interface MemoryPluginOptions {