@ixo/oracle-runtime-workers 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -34,7 +34,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
-    "@ixo/action-protocol": "0.7.0",
+    "@ixo/action-protocol": "0.8.0",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
@@ -67,9 +67,9 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
-    "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/common": "1.7.1",
     "@ixo/ucan": "2.3.0",
-    "@ixo/common": "1.7.1"
+    "@ixo/ixo-transaction": "0.2.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/core/middlewares/tool-repetition-guard.ts

@@ -7,6 +7,7 @@ import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
 import { NOOP_LOGGER } from '../utils';
 import { isCapabilityGateRefusal } from './capability-gate';
+import { isToolNotRun } from '../tool-not-run';
 import { turnCarryOf, turnStart } from './turn-boundary';
 
 export { turnStart };
@@ -145,9 +146,11 @@ export const createToolRepetitionGuardMiddleware = (
         const msg = messages[i];
         if (!(msg instanceof ToolMessage)) continue;
         if (msg.status !== 'error') continue;
-        // The capability gate refused it without running it; after a
-        // `load_capability` the same call is the expected next step.
-        if (isCapabilityGateRefusal(msg)) continue;
+        // The capability gate refused it without running it, or the tool
+        // said it did not run until a step comes first: after that step
+        // (`load_capability`, reading the rules) the same call is the
+        // expected next one.
+        if (isCapabilityGateRefusal(msg) || isToolNotRun(msg)) continue;
         if (msg.name !== toolName) continue;
 
         const priorArgs = argsById.get(msg.tool_call_id);

package/src/core/middlewares/turn-boundary.ts

@@ -22,6 +22,7 @@ import {
 } from '@langchain/core/messages';
 import { isAttachmentViewMessage } from '../../attachments/retention';
 import { isCapabilityGateRefusal } from './capability-gate';
+import { isToolNotRun } from '../tool-not-run';
 
 export const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
 
@@ -140,7 +141,11 @@ export function carriedCallsOfTurn(
         if (call.id) calls.set(call.id, { name: call.name, args: call.args });
       continue;
     }
-    if (!ToolMessage.isInstance(message) || isCapabilityGateRefusal(message))
+    if (
+      !ToolMessage.isInstance(message) ||
+      isCapabilityGateRefusal(message) ||
+      isToolNotRun(message)
+    )
       continue;
     const call = calls.get(message.tool_call_id);
     if (!call) continue;

package/src/core/tool-not-run.ts

@@ -0,0 +1,30 @@
+import { ToolMessage } from '@langchain/core/messages';
+
+/** `response_metadata` key of a result whose tool did not run (never sent to a provider). */
+const NOT_RUN = 'toolNotRun';
+
+/**
+ * A tool result saying the tool did not run because another step must come
+ * first (for example reading a message type's rules before preparing it).
+ * It is an error result, so it never counts as a write that happened, and
+ * like a capability-gate refusal the repetition guard lets the identical
+ * call through once the step is done (`isToolNotRun`).
+ */
+export function toolNotRunMessage(input: {
+  toolCallId: string;
+  name: string;
+  content: string;
+}): ToolMessage {
+  return new ToolMessage({
+    tool_call_id: input.toolCallId,
+    name: input.name,
+    content: input.content,
+    status: 'error',
+    response_metadata: { [NOT_RUN]: true },
+  });
+}
+
+/** A result `toolNotRunMessage` made: the tool did not run. */
+export function isToolNotRun(message: ToolMessage): boolean {
+  return message.response_metadata?.[NOT_RUN] === true;
+}

package/src/core/wrap-plugin-tool.ts

@@ -1,3 +1,4 @@
+import { ToolMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
 import { capToolResult, type ResultCapConfig } from './middlewares/result-cap';
 import { tool } from '@langchain/core/tools';
@@ -125,7 +126,14 @@ export function wrapPluginTool(
       if (pluginName !== undefined)
         requireToolPlane(ctx, pluginName, pluginTool);
       const output = await pluginTool.handler(args, ctx);
-      if (!resultCap || output instanceof Command || output == null)
+      // A tool's own message (a result that says the tool did not run) is
+      // returned whole, never capped into text.
+      if (
+        !resultCap ||
+        output instanceof Command ||
+        ToolMessage.isInstance(output) ||
+        output == null
+      )
         return output;
       const text = typeof output === 'string' ? output : JSON.stringify(output);
       if (typeof text !== 'string' || text.length <= resultCap.capChars)

package/src/do/user-oracle-do.ts

@@ -54,7 +54,7 @@ import {
 import { chainTxOperation, prepareHubAction } from '../hub-actions/request';
 import {
   bankReceiptSummary,
-  bankStepsInBaseUnits,
+  chainTxAmountsInBaseUnits,
 } from '../hub-actions/transfer';
 import {
   HUB_CHECK_AFTER_EXPIRY_MS,
@@ -638,6 +638,14 @@ const ACTION_TICK_BUDGET_MS = 15_000;
 const ACTION_PRUNE_INTERVAL_MS = 60 * 60_000;
 /** How long the Hub's capabilities answer is reused per object. */
 const HUB_CAPABILITIES_CACHE_MS = 60_000;
+/**
+ * A capabilities read on a turn's critical path (the chain transaction
+ * tool's types): a short timeout, and after a failed read none for this
+ * long, so a slow or failing Hub costs a turn at most this timeout once per
+ * window instead of the full Hub timeout on every turn.
+ */
+const HUB_TURN_CAPABILITIES_TIMEOUT_MS = 3_000;
+const HUB_CAPABILITIES_FAILURE_CACHE_MS = 30_000;
 /** A Hub network name as the chain-id config key it is configured under. */
 /**
  * Whether two Hub outcomes are the same event. Receipts are compared in the
@@ -1054,11 +1062,17 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     private actionProposals: ActionProposalStore | null = null;
     private hubActionStore: HubActionStore | null = null;
     private hubActionClient: HubActionClient | null = null;
-    /** The Hub's capabilities for this oracle account, reused for `HUB_CAPABILITIES_CACHE_MS`. */
+    /** The Hub's capabilities for this oracle account, reused for `HUB_CAPABILITIES_CACHE_MS` (and on a turn, while a read fails). */
     private hubCapabilities: {
       value: ActionCapabilitiesV1;
       at: number;
     } | null = null;
+    /** The last failed capabilities read: a turn does not read again within `HUB_CAPABILITIES_FAILURE_CACHE_MS`. */
+    private hubCapabilitiesFailure: { error: unknown; at: number } | null =
+      null;
+    /** A turn's capabilities read in flight, shared by concurrent turns. */
+    private hubTurnCapabilitiesRead: Promise<ActionCapabilitiesV1> | null =
+      null;
     /** The last `hub_action_options` answer for this owner (Gmail connection checks). */
     private lastHubOptions: {
       value: HubActionOptionsV2 | HubActionOptionsV3;
@@ -2277,7 +2291,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         ...(this.hubActionStore && this.hubActionClient
           ? {
               hubActions: {
-                capabilities: () => this.cachedHubCapabilities(),
+                capabilities: (opts) =>
+                  opts?.turn
+                    ? this.turnHubCapabilities()
+                    : this.cachedHubCapabilities(),
                 options: (input) => this.hubActionOptions(input),
                 request: (input: {
                   ownerDid: string;
@@ -2385,6 +2402,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.hubActionStore = null;
       this.hubActionClient = null;
       this.hubCapabilities = null;
+      this.hubCapabilitiesFailure = null;
+      this.hubTurnCapabilitiesRead = null;
       this.lastHubOptions = null;
       this.topicProposals = null;
       this.attachmentTextCache = null;
@@ -3524,16 +3543,57 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     }
 
     /** The Hub's capabilities, cached per object for `HUB_CAPABILITIES_CACHE_MS`. */
-    private async cachedHubCapabilities(): Promise<ActionCapabilitiesV1> {
+    private async cachedHubCapabilities(
+      timeoutMs?: number,
+    ): Promise<ActionCapabilitiesV1> {
       const client = this.hubActionClient;
       if (!client) throw new Error('Hub actions are unavailable');
       const now = Date.now();
       const cached = this.hubCapabilities ?? null;
       if (cached && now - cached.at < HUB_CAPABILITIES_CACHE_MS)
         return cached.value;
-      const value = await client.capabilities();
-      this.hubCapabilities = { value, at: now };
-      return value;
+      try {
+        const value = await client.capabilities(timeoutMs);
+        this.hubCapabilities = { value, at: Date.now() };
+        this.hubCapabilitiesFailure = null;
+        return value;
+      } catch (error) {
+        this.hubCapabilitiesFailure = { error, at: Date.now() };
+        throw error;
+      }
+    }
+
+    /**
+     * The capabilities for a turn's tool list: the cached ones while fresh;
+     * else one read with `HUB_TURN_CAPABILITIES_TIMEOUT_MS`, shared by
+     * concurrent turns and not repeated within
+     * `HUB_CAPABILITIES_FAILURE_CACHE_MS` of a failed read. While reads
+     * fail, the last capabilities read are answered (the Hub enforces its
+     * own on every prepare); with none, the failure.
+     */
+    private async turnHubCapabilities(): Promise<ActionCapabilitiesV1> {
+      const cached = this.hubCapabilities;
+      if (cached && Date.now() - cached.at < HUB_CAPABILITIES_CACHE_MS)
+        return cached.value;
+      const failure = this.hubCapabilitiesFailure;
+      if (
+        failure &&
+        Date.now() - failure.at < HUB_CAPABILITIES_FAILURE_CACHE_MS
+      ) {
+        if (cached) return cached.value;
+        throw failure.error;
+      }
+      this.hubTurnCapabilitiesRead ??= this.cachedHubCapabilities(
+        HUB_TURN_CAPABILITIES_TIMEOUT_MS,
+      ).finally(() => {
+        this.hubTurnCapabilitiesRead = null;
+      });
+      try {
+        return await this.hubTurnCapabilitiesRead;
+      } catch (error) {
+        if (cached) return cached.value;
+        throw error;
+      }
     }
 
     /**
@@ -3586,13 +3646,14 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     /**
      * One chain transaction of the model's messages. The network is the
      * account's capability, the chain id this Worker's own for that
-     * network; the signer and the owner's identity in claims messages come
+     * network; the signer and the owner's identity in the messages come
      * from the owner's DID (`chainTxOperation`). The model names none of
-     * them. Bank steps name a listed token and a display amount: with at
-     * least one, the owner's options are read once, fresh (the balances
-     * must be current), and each step is converted to base units and
-     * checked against the listed balance (`bankStepsInBaseUnits`). No fee
-     * is sent: the Hub simulates gas and sets it.
+     * them. Bank steps name a listed token and a display amount, stake
+     * steps an amount of IXO: with at least one of either, the owner's
+     * options are read once, fresh (the balances must be current), and each
+     * amount is converted to base units and checked against the listed
+     * balance (`chainTxAmountsInBaseUnits`). No fee is sent: the Hub
+     * simulates gas and sets it.
      */
     private async chainTransactionHubAction(input: {
       ownerDid: string;
@@ -3624,7 +3685,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         HUB_NETWORK_CHAIN[capabilities.network]
       ];
       const tokens = input.messages.some(
-        (message) => message.type === 'cosmos.bank.send',
+        (message) =>
+          message.type === 'cosmos.bank.send' ||
+          message.type === 'cosmos.staking.delegate',
       )
         ? ((await this.hubActionOptions(input, true)).transfer?.tokens ?? null)
         : null;
@@ -3633,7 +3696,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         chainId,
         network: capabilities.network,
         memo: input.memo,
-        messages: bankStepsInBaseUnits(input.messages, tokens),
+        messages: chainTxAmountsInBaseUnits(input.messages, tokens),
       });
       return this.requestHubAction({ ...input, operation }, true);
     }

package/src/hub-actions/chain-tx-refusals.ts

@@ -0,0 +1,217 @@
+import {
+  CHAIN_TX_MAX_MESSAGES,
+  CHAIN_TX_REFUSAL_CODES,
+  type ChainTxRefusal,
+  type ChainTxRefusalCode,
+} from '@ixo/action-protocol';
+
+/**
+ * What each chain transaction refusal code means, for the person (`means`,
+ * plain words the model may say) and what the model does next (`next`).
+ * Auth Hub sends the code when it will not make a card from what it read on
+ * chain, or when the node's simulation names one message
+ * (`invalid_message: messages[<i>].<field>: <code>`); the reason text itself
+ * is never given to the person. `satisfies` makes every code of the
+ * protocol need an entry.
+ */
+export const CHAIN_TX_REFUSAL_WORDS = {
+  validator_not_found: {
+    means: 'there is no validator with that address on the network',
+    next: 'Find the validator again with chain_lookup validators and copy its address exactly.',
+  },
+  no_stake: {
+    means: 'they have nothing staked with this validator',
+    next: 'Check where their stake is with chain_lookup staking.',
+  },
+  stake_too_small: {
+    means: 'that is more than they have staked with this validator',
+    next: 'Check how much is staked there with chain_lookup staking and ask for a smaller amount.',
+  },
+  same_validator: {
+    means: 'the stake is already with that validator',
+    next: 'Ask which other validator it should move to.',
+  },
+  invalid_amount: {
+    means: 'the network does not accept that amount',
+    next: 'Ask for the amount again.',
+  },
+  nothing_to_collect: {
+    means: 'there are no rewards to collect from this validator yet',
+    next: 'Leave this validator out of the card.',
+  },
+  proposal_not_found: {
+    means: 'there is no proposal with that number',
+    next: 'Find the open proposals with chain_lookup gov_proposals.',
+  },
+  proposal_not_open: {
+    means:
+      'voting on this proposal is not open (it has closed, or not started yet)',
+    next: 'Tell them; a vote cannot be recorded now.',
+  },
+  invalid_vote_option: {
+    means: 'that is not a vote the network accepts',
+    next: 'Ask whether they vote yes, no, abstain or no with veto.',
+  },
+  token_not_found: {
+    means: 'one of these impact tokens could not be found',
+    next: 'Check the tokens they hold with chain_lookup token_balances.',
+  },
+  collection_not_found: {
+    means: 'there is no claim collection with that number',
+    next: 'Find the collection with chain_lookup claim_collections.',
+  },
+  reservations_off: {
+    means: 'this collection does not take reservations',
+    next: 'File the claim without a reservation.',
+  },
+  reservation_exists: {
+    means: 'they already have a reservation in this collection',
+    next: 'File the claim with it, or wait for it to run out.',
+  },
+  claim_not_found: {
+    means: 'there is no claim with that id',
+    next: 'Find the claim with chain_lookup claims.',
+  },
+  claim_in_other_collection: {
+    means: 'that claim belongs to a different collection',
+    next: 'Check the claim’s collection with chain_lookup claim.',
+  },
+  wrong_admin: {
+    means: 'that is not the collection’s admin account',
+    next: 'Copy the admin account from chain_lookup claim_collection.',
+  },
+  already_in_state: {
+    means: 'the collection is already in that state',
+    next: 'Nothing needs to change; tell them.',
+  },
+  start_date_missing: {
+    means: 'the collection has no start date yet',
+    next: 'Ask when it should open and include that start date.',
+  },
+  end_before_start: {
+    means: 'the end date would come before the start date',
+    next: 'Ask for dates where the end comes after the start.',
+  },
+  quota_below_count: {
+    means: 'the new limit is below the number of claims already filed',
+    next: 'Check the count with chain_lookup claim_collection and ask for a higher limit.',
+  },
+  token_payments_present: {
+    means:
+      'that payment includes contract tokens, which cannot be changed from here',
+    next: 'Leave that payment out of the card so it stays as it is.',
+  },
+  ends_too_soon: {
+    means:
+      'the end date is too soon: it has to be after this review link expires',
+    next: 'Ask for a later end date.',
+  },
+  deadline_too_soon: {
+    means:
+      'the date to decide by is too soon: it has to be after this review link expires',
+    next: 'Ask for a later date.',
+  },
+  current_permission_ends_too_soon: {
+    means: 'their current permission ends too soon to keep its end date',
+    next: 'Ask whether to set a new end date.',
+  },
+  unlimited_permission_exists: {
+    means: 'they already have an unlimited permission of this kind',
+    next: 'It has to be removed first; ask whether to remove it in the same card.',
+  },
+  other_permission_exists: {
+    means: 'a different kind of permission is already set up for them here',
+    next: 'It has to be removed first; ask whether to remove it in the same card.',
+  },
+  too_many_constraints: {
+    means:
+      'this permission already covers too many collections to change it from a card',
+    next: 'Some collections have to be removed from it first; tell them.',
+  },
+  no_such_permission: {
+    means: 'they do not have this permission',
+    next: 'Check what they have with chain_lookup authz_grants.',
+  },
+  collection_of_other_entity: {
+    means: 'that collection belongs to a different entity',
+    next: 'Check the collection with chain_lookup claim_collection.',
+  },
+  entity_not_found: {
+    means: 'there is no entity with that id',
+    next: 'Find the entity with chain_lookup entities.',
+  },
+  account_name_taken: {
+    means: 'this entity already has an account with that name',
+    next: 'Ask for another name.',
+  },
+  document_not_found: {
+    means: 'there is no identity record with that id',
+    next: 'Check the id with chain_lookup did_document.',
+  },
+  nothing_to_remove: {
+    means: 'that item is not in the identity record',
+    next: 'Read the record with chain_lookup did_document and copy the id exactly.',
+  },
+  already_exists: {
+    means: 'an item with that id is already there',
+    next: 'Choose another id, or remove the old item first.',
+  },
+  not_available: {
+    means: 'that isn’t available on this service yet',
+    next: 'Do not retry; tell the person it cannot be done here for now.',
+  },
+  chain_data_too_large: {
+    means: 'this is too large to change in one go here',
+    next: 'Do not retry; tell the person it cannot be done through chat.',
+  },
+  invalid_did: {
+    means: 'one of the identifiers is not a valid ID on the network',
+    next: 'Copy it again exactly from a lookup.',
+  },
+} as const satisfies Record<
+  ChainTxRefusalCode,
+  { means: string; next: string }
+>;
+
+/**
+ * A message field path as the protocol names one (`validatorAddress`,
+ * `payments.approval.amount[1].denom`): checked here as well, because the
+ * path is repeated in text the model reads.
+ */
+const REFUSAL_FIELD =
+  /^[A-Za-z][A-Za-z0-9_]*(?:\[\d{1,3}\])?(?:\.[A-Za-z][A-Za-z0-9_]*(?:\[\d{1,3}\])?){0,5}$/;
+
+/**
+ * A parsed refusal the runtime puts into words: a message index 0..7, a
+ * plain field path of at most 100 characters and a code of the protocol's
+ * list. Anything else is passed on as the Hub's quoted reason instead.
+ */
+export function wordableRefusal(
+  refusal: ChainTxRefusal | null,
+): (ChainTxRefusal & { code: ChainTxRefusalCode }) | null {
+  if (!refusal) return null;
+  const { index, field, code } = refusal;
+  if (
+    !Number.isInteger(index) ||
+    index < 0 ||
+    index >= CHAIN_TX_MAX_MESSAGES ||
+    field.length > 100 ||
+    !REFUSAL_FIELD.test(field) ||
+    code === null ||
+    !CHAIN_TX_REFUSAL_CODES.includes(code)
+  )
+    return null;
+  return { index, field, code };
+}
+
+/**
+ * A coded chain transaction refusal in the model's words: which step, what
+ * it means for the person and the next step. The field and code are for
+ * the model only; the Hub's reason text is not repeated.
+ */
+export function chainTxRefusalWords(
+  refusal: ChainTxRefusal & { code: ChainTxRefusalCode },
+): string {
+  const words = CHAIN_TX_REFUSAL_WORDS[refusal.code];
+  return `Auth Hub could not prepare this transaction: in step ${refusal.index + 1}, ${words.means}. ${words.next} Tell the person in your own plain words; this is not text to show them (for you: messages[${refusal.index}].${refusal.field}, ${refusal.code}).`;
+}