@ixo/oracle-runtime-workers 0.30.0 → 0.32.0

package/src/hub-actions/store.ts

@@ -42,13 +42,17 @@ const HUB_RETENTION_SECONDS = 30 * 24 * 60 * 60;
 /**
  * A refusal the model can act on: a cap reached, a request that expired, or
  * an operation the owner's own state rules out (an unknown connection, an
- * email whose earlier send is unconfirmed: `priorActionId`).
+ * email whose earlier send is unconfirmed: `priorActionId`). A refusal
+ * Auth Hub answered carries its HTTP status (`httpStatus`), so a caller can
+ * tell a 429 or 503, which pass with time, from a deterministic refusal
+ * without reading the words.
  */
 export class HubActionRefused extends Error {
   constructor(
     readonly kind: 'limit' | 'expired' | 'refused',
     message: string,
     readonly priorActionId?: string,
+    readonly httpStatus?: number,
   ) {
     super(message);
     this.name = 'HubActionRefused';

package/src/hub-actions/transfer.ts

@@ -1,9 +1,12 @@
-import type {
-  ActionOperationV1,
-  ActionReceiptV1,
-  OptionsToken,
+import {
+  parseChainTxRefusal,
+  type ActionOperationV1,
+  type ActionReceiptV1,
+  type OptionsToken,
 } from '@ixo/action-protocol';
+import { chainTxRefusalWords, wordableRefusal } from './chain-tx-refusals';
 import type { ChainTxMessageInput } from '../plugin-api/types';
+import { quoteHubText } from './hub-text';
 import type { ChainTxHostMessage } from './request';
 import { HubActionRefused } from './store';
 
@@ -90,24 +93,67 @@ const IXO_TOKEN: TransferToken = {
 };
 
 /**
- * A chain transaction's bank steps in base units; the other messages pass
+ * A chain transaction's amounts in base units; messages without one pass
  * unchanged. Each bank step names a display `amount` of a token from the
  * owner's list (`denom`, absent = uixo): the token must be listed, the
  * amount converts with its listed decimals (`toBaseUnits`: a plain decimal,
  * no more digits after the point than the decimals, above zero; an
  * unverified token lists 0: base units), and the bank steps of one token
- * together stay within its listed balance. `tokens` is the owner's list
- * (hub_action_options `transfer.tokens`), null when the Hub listed none;
- * the caller reads it only when there is a bank step.
+ * together stay within its listed balance. Each stake step (stake, unstake,
+ * move stake) names a display `amount` of IXO, converted with IXO's 6
+ * decimals; what a stake takes from the wallet counts against the listed
+ * IXO balance together with the IXO bank steps, when the list has IXO
+ * (Auth Hub checks every balance again before the card is made). `tokens`
+ * is the owner's list (hub_action_options `transfer.tokens`), null when the
+ * Hub listed none; the caller reads it only when there is a bank or stake
+ * step.
  */
-export function bankStepsInBaseUnits(
+export function chainTxAmountsInBaseUnits(
   messages: readonly ChainTxMessageInput[],
   tokens: readonly OptionsToken[] | null,
 ): ChainTxHostMessage[] {
   const spent = new Map<string, bigint>();
-  return messages.map((message, index) => {
-    if (message.type !== 'cosmos.bank.send') return message;
+  /** The bank and stake steps of one listed token together, within its listed balance. */
+  const spend = (
+    at: string,
+    token: OptionsToken,
+    amount: bigint,
+    what: string,
+  ) => {
+    const total = (spent.get(token.denom) ?? 0n) + amount;
+    spent.set(token.denom, total);
+    if (total > BigInt(token.balanceBaseUnits))
+      throw new HubActionRefused(
+        'refused',
+        `${at}.amount: the owner holds ${describeAmount(token.balanceBaseUnits, token)}, less than ${total === amount ? what : 'what the steps of this transaction take of it together'}.`,
+      );
+  };
+  const converted = (at: string, amount: string, decimals: number) => {
+    try {
+      return toBaseUnits(amount, decimals);
+    } catch (error) {
+      if (error instanceof HubActionRefused)
+        throw new HubActionRefused('refused', `${at}.amount: ${error.message}`);
+      throw error;
+    }
+  };
+  return messages.map((message, index): ChainTxHostMessage => {
     const at = `messages[${index}]`;
+    if (
+      message.type === 'cosmos.staking.delegate' ||
+      message.type === 'cosmos.staking.undelegate' ||
+      message.type === 'cosmos.staking.redelegate'
+    ) {
+      const { amount: display, ...rest } = message;
+      const amount = converted(at, display, IXO_TOKEN.decimals);
+      // Only a stake takes IXO from the wallet: unstaking and moving stake
+      // work on what is already staked.
+      const ixo = tokens?.find((item) => item.denom === IXO_TOKEN.denom);
+      if (message.type === 'cosmos.staking.delegate' && ixo)
+        spend(at, ixo, amount, 'this stake');
+      return { ...rest, amountBaseUnits: amount.toString() };
+    }
+    if (message.type !== 'cosmos.bank.send') return message;
     if (!tokens?.length)
       throw new HubActionRefused(
         'refused',
@@ -123,21 +169,8 @@ export function bankStepsInBaseUnits(
           .slice(0, 10)
           .join(', ')}).`,
       );
-    let amount: bigint;
-    try {
-      amount = toBaseUnits(message.amount, token.decimals);
-    } catch (error) {
-      if (error instanceof HubActionRefused)
-        throw new HubActionRefused('refused', `${at}.amount: ${error.message}`);
-      throw error;
-    }
-    const total = (spent.get(token.denom) ?? 0n) + amount;
-    spent.set(token.denom, total);
-    if (total > BigInt(token.balanceBaseUnits))
-      throw new HubActionRefused(
-        'refused',
-        `${at}.amount: the owner holds ${describeAmount(token.balanceBaseUnits, token)}, less than ${total === amount ? 'this send' : 'the bank steps of this token in this transaction'}.`,
-      );
+    const amount = converted(at, message.amount, token.decimals);
+    spend(at, token, amount, 'this send');
     return {
       type: 'cosmos.bank.send',
       toAddress: message.toAddress,
@@ -279,11 +312,14 @@ function hubErrorBody(
     return null;
   const reason =
     'reason' in body && typeof body.reason === 'string' && body.reason.trim()
-      ? body.reason.trim().slice(0, 200)
+      ? body.reason.trim()
       : undefined;
   return reason ? { error, reason } : { error };
 }
 
+/** The longest part of a Hub refusal's `reason` the model is given. */
+const HUB_REASON_MAX = 200;
+
 /**
  * A Hub refusal of a prepare (`{error, reason?}` with status 400, 409 or
  * 503, or any 404 or 429) as a refusal the model can relay, or null when
@@ -295,7 +331,8 @@ function hubErrorBody(
  *   try again later;
  * - 400 `simulation_failed`, `fee_above_ceiling`, `insufficient_funds`,
  *   `not_authorized`, `operation_not_registered`: the transfer or
- *   transaction as asked cannot go ahead (with the Hub's reason);
+ *   transaction as asked cannot go ahead (with the Hub's reason, quoted and
+ *   labelled as data, see `quoteHubText`);
  * - 409 `sequence_mismatch`, 503 `transfer_unavailable`: temporary, try
  *   again shortly;
  * - any other 409: the account may not use this operation (deterministic,
@@ -308,24 +345,54 @@ export function hubPrepareRefusal(
 ): HubActionRefused | null {
   const parsed = hubErrorBody(body);
   const unfixable = unfixableRefusal(status, parsed, subject);
-  if (unfixable) return new HubActionRefused('refused', unfixable);
+  if (unfixable)
+    return new HubActionRefused('refused', unfixable, undefined, status);
   if (!parsed) return null;
-  const detail = parsed.reason ? `: ${parsed.reason}` : '';
+  // A chain transaction Auth Hub would not make from what it read on chain,
+  // or whose simulation named one message: a fixed code, in the runtime's
+  // own words (the reason text is not passed on). Without a code, the
+  // reason is passed on quoted, as below.
+  const coded =
+    status === 400 &&
+    subject === 'transaction' &&
+    (parsed.error === 'operation_not_registered' ||
+      parsed.error === 'simulation_failed')
+      ? wordableRefusal(parseChainTxRefusal(parsed.reason))
+      : null;
+  if (coded)
+    return new HubActionRefused(
+      'refused',
+      chainTxRefusalWords(coded),
+      undefined,
+      status,
+    );
+  const reason = parsed.reason
+    ? quoteHubText('reason', parsed.reason, HUB_REASON_MAX)
+    : '';
   const words =
     status === 400 && Object.hasOwn(HUB_PREPARE_REFUSALS, parsed.error)
       ? HUB_PREPARE_REFUSALS[parsed.error]
       : undefined;
   if (words)
-    return new HubActionRefused('refused', `${words(subject)}${detail}.`);
+    return new HubActionRefused(
+      'refused',
+      `${words(subject)}.${reason ? ` ${reason}.` : ''}`,
+      undefined,
+      status,
+    );
   if (HUB_TRANSIENT_CODES[status]?.includes(parsed.error))
     return new HubActionRefused(
       'refused',
       `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
+      undefined,
+      status,
     );
   if (status === 409)
     return new HubActionRefused(
       'refused',
-      `This operation is not available for this account (${parsed.error}${detail}).`,
+      `This operation is not available for this account (${parsed.error}).${reason ? ` ${reason}.` : ''}`,
+      undefined,
+      status,
     );
   return null;
 }

package/src/index.ts

@@ -45,6 +45,7 @@ export * from './plugin-api';
 export * from './plugins';
 export * from './do/contracts';
 export type { OwnerStore } from './owner-store/types';
+export type { ChannelAttachment } from './channels/contract';
 export { MigratingOwnerStore } from './owner-store/migrating-store';
 export {
   IxoVfsOwnerStore,

package/src/plugin-api/index.ts

@@ -42,6 +42,7 @@ export type { UserKvLimitKind } from '../core/user-kv';
 export type {
   ActionCallEventPayload,
   AgentMiddleware,
+  HubActionStatusRead,
   AuthExcludedRoute,
   BrowserToolCallEventPayload,
   ChatOpenAIFields,

package/src/plugin-api/types.ts

@@ -18,7 +18,12 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { UserPreferences } from '../core/state';
 import type { AttachmentViewSurface } from '../attachments/view';
+import type { ChannelAttachment } from '../channels/contract';
 import type { DeliveryConfig } from '../delivery/profile';
+import type {
+  HubOperationStatus,
+  HubReviewStatus,
+} from '../hub-actions/client';
 import type {
   ActionOperationV1,
   ActionReferenceV1,
@@ -27,13 +32,40 @@ import type {
   ChainTxMessage,
 } from '@ixo/action-protocol';
 
+/** `Omit` applied to each member of a union (plain `Omit` merges them). */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
+/**
+ * The owner's own identity in chain-transaction messages, which the host
+ * fills and the model never names: the filer's or disputer's `agentDid`
+ * (claims, reservations, disputes), an evaluation's `agentDid` and
+ * `agentAddress`, a claim permission's `creatorDid`, an entity update's
+ * `controllerDid` and a new entity's `ownerDid`: always `did:ixo:<signer>`,
+ * or the signer for an address.
+ */
+export type ChainTxOwnerField =
+  | 'agentDid'
+  | 'agentAddress'
+  | 'creatorDid'
+  | 'controllerDid'
+  | 'ownerDid';
+
+/** The stake steps: their amount is IXO, written in display units. */
+export type ChainTxStakeType =
+  | 'cosmos.staking.delegate'
+  | 'cosmos.staking.undelegate'
+  | 'cosmos.staking.redelegate';
+
 /**
  * A chain-transaction message as the model writes it: the protocol's
- * message without the owner's identity, which the host fills (a claim's
- * `agentDid`, an evaluation's `agentDid` and `agentAddress`: the signer's).
- * A bank step names a display `amount` of a token from the owner's list
- * (`denom`, absent = uixo); the host converts it to the protocol's
- * `amountBaseUnits` from the listed decimals.
+ * message without the owner's identity (`ChainTxOwnerField`), which the
+ * host fills. A bank step names a display `amount` of a token from the
+ * owner's list (`denom`, absent = uixo); a stake step a display `amount` of
+ * IXO. The host converts both to the protocol's `amountBaseUnits` (the
+ * listed decimals; 6 for IXO). Every other amount (impact tokens, a
+ * collection's payments) is already in the protocol's units.
  */
 export type ChainTxMessageInput =
   | {
@@ -43,11 +75,16 @@ export type ChainTxMessageInput =
       amount: string;
       denom?: string;
     }
-  | Extract<ChainTxMessage, { type: 'ixo.token.transfer' }>
-  | Omit<Extract<ChainTxMessage, { type: 'ixo.claims.submit' }>, 'agentDid'>
-  | Omit<
-      Extract<ChainTxMessage, { type: 'ixo.claims.evaluate' }>,
-      'agentDid' | 'agentAddress'
+  | (DistributiveOmit<
+      Extract<ChainTxMessage, { type: ChainTxStakeType }>,
+      'amountBaseUnits'
+    > & {
+      /** A plain decimal in IXO ("100" or "0.5"). */
+      amount: string;
+    })
+  | DistributiveOmit<
+      Exclude<ChainTxMessage, { type: 'cosmos.bank.send' | ChainTxStakeType }>,
+      ChainTxOwnerField
     >;
 
 /**
@@ -551,6 +588,25 @@ export type SessionSurface =
   | { kind: 'stream' }
   | { kind: 'chat'; surface: string; label: string };
 
+/** What `ctx.hubActions.status` reads. */
+export interface HubActionStatusRead {
+  /** False when this owner object holds no action with this id (Auth Hub was not asked). */
+  held: boolean;
+  /**
+   * Auth Hub's review status (`prepared`, `authorized`, `declined`,
+   * `expired`, …) and operation status, each one the protocol lists or
+   * `unknown` for anything else Auth Hub answered; null when not held.
+   * With no outcome yet they tell an action still waiting from one whose
+   * review lapsed.
+   */
+  reviewStatus: HubReviewStatus | null;
+  operationStatus: HubOperationStatus | null;
+  /** The latest authenticated outcome; null when there is none (yet). */
+  outcome: ActionOutcomeV1 | null;
+  /** For a bank-send receipt, the owner-facing line. */
+  summary: string | null;
+}
+
 export interface RuntimeContext<TConfig = MergedConfig> {
   /** Authenticated user identity (validated by core auth middleware). */
   user: {
@@ -575,6 +631,14 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       provider: string;
       bindingId: string;
       bindingRevision: number;
+      /**
+       * Files the person sent with this turn's message (a WhatsApp photo,
+       * video, document or audio file), as the channel gateway serves them:
+       * a capability `url` plus the `sha256` of its bytes. Absent when the
+       * message carried none. The model also sees them through the
+       * attachment pipeline; this is the raw list for tools that keep them.
+       */
+      attachments?: readonly ChannelAttachment[];
     };
     roomId?: string;
     /**
@@ -780,7 +844,13 @@ export interface RuntimeContext<TConfig = MergedConfig> {
 
   /** Host-owned action coordinator. It accepts only runtime-derived channel context. */
   hubActions?: {
-    capabilities(): Promise<ActionCapabilitiesV1>;
+    /**
+     * The Hub's capabilities for this oracle account (cached 60 s).
+     * `turn`: a read on a turn's critical path (a tool list): a short
+     * timeout, no new read within 30 s of a failed one, and the last
+     * capabilities read while reads fail.
+     */
+    capabilities(opts?: { turn?: boolean }): Promise<ActionCapabilitiesV1>;
     options(input: {
       ownerDid: string;
       provider: string;
@@ -790,13 +860,16 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     /**
      * One chain transaction (`ixo.chain.tx.v1`) of 1–8 messages: the host
      * adds the chain id and network (the account's), the signer (the
-     * owner's address) and the owner's identity in claims messages
-     * (`agentDid` = `did:ixo:<signer>`, an evaluation's `agentAddress` = the
-     * signer) and prepares it like any operation (no fee: the Hub simulates
-     * gas and sets it). A bank step's display `amount` is converted to base
-     * units from the owner's token list (one options read per call, only
-     * when there is a bank step), refused for a token not listed, more
-     * digits than its decimals, zero or more than the listed balance.
+     * owner's address) and the owner's identity (`ChainTxOwnerField`:
+     * `did:ixo:<signer>`, an evaluation's `agentAddress` = the signer) and
+     * prepares it like any operation (no fee: the Hub simulates gas and
+     * sets it). A bank step's display `amount` is converted to base units
+     * from the owner's token list (one options read per call, only when
+     * there is a bank or stake step), refused for a token not listed, more
+     * digits than its decimals, zero or more than the listed balance. A
+     * stake step's IXO `amount` is converted with 6 decimals; what a stake
+     * takes from the wallet counts against the listed IXO balance with the
+     * IXO bank steps, when the list has IXO.
      */
     chainTransaction(input: {
       ownerDid: string;
@@ -821,11 +894,20 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       requestKey: string;
       operation: ActionOperationV1;
     }): Promise<ActionReferenceV1>;
-    /** The latest authenticated outcome and, for a transfer, its owner-facing line. */
+    /**
+     * A fresh, authenticated read of one of this owner's actions: Auth
+     * Hub's review and operation status, the latest outcome (null: none
+     * yet) and, for a transfer, its owner-facing line. An action this
+     * owner object never prepared is `held: false` and Auth Hub is not
+     * asked. `timeoutMs` bounds the Hub read (default 10 s). Rejects with
+     * `HubActionRefused` (with `httpStatus`) when Auth Hub refuses the read,
+     * for example when it must be updated first.
+     */
     status(
       ownerDid: string,
       actionId: string,
-    ): Promise<{ outcome: ActionOutcomeV1 | null; summary: string | null }>;
+      opts?: { timeoutMs?: number },
+    ): Promise<HubActionStatusRead>;
   };
 
   decisions: {

package/src/plugins/attachments/view-attachment-tool.ts

@@ -20,6 +20,9 @@ import { z } from 'zod';
 import {
   ATTACHMENT_VIEW_SOURCE,
   buildUserMessageContent,
+  NOTE_FILENAME_MAX,
+  NOTE_MIMETYPE_MAX,
+  sanitizeNoteField,
   VIEW_ATTACHMENT_TOOL_NAME,
 } from '../../attachments';
 import { tool } from '../../plugin-api/tool-helper';
@@ -30,7 +33,7 @@ export const viewAttachmentSchema = z.object({
     .string()
     .min(1)
     .describe(
-      'The attachment reference exactly as listed in the "[attachment offloaded]" note of the message it belongs to (a Matrix event id such as "$abc…" or an mxc:// URI).',
+      'The attachment reference exactly as listed in the "[attachment offloaded]" note of the message it belongs to (a Matrix event id such as "$abc…", a channel file reference such as "channel:0123456789abcdef", or an mxc:// URI).',
     ),
 });
 
@@ -52,12 +55,13 @@ export function createViewAttachmentTool(): PluginTool {
       }
       const { meta, view } = await ctx.attachments.view(ref);
       if (view.kind === 'text') return view.text;
+      const name = sanitizeNoteField(meta.filename, NOTE_FILENAME_MAX);
       if (!ctx.toolCallId) {
         throw new Error(
-          `"${meta.filename}" was fetched but cannot be re-attached outside a tool call`,
+          `"${name}" was fetched but cannot be re-attached outside a tool call`,
         );
       }
-      const label = `Re-attached "${meta.filename}" (${meta.mimetype}) from earlier in this conversation.`;
+      const label = `Re-attached "${name}" (${sanitizeNoteField(meta.mimetype, NOTE_MIMETYPE_MAX)}) from earlier in this conversation.`;
       const timestamp = new Date().toISOString();
       const msgFromMatrixRoom = ctx.session.client === 'matrix';
       return new Command({