@ixo/oracle-runtime-workers 0.26.0 → 0.28.0

package/src/memory/user-context-invalidation.ts

@@ -2,8 +2,8 @@
  * Drops a room's prefetched user context (`UserContextFetcher.invalidate`)
  * after a tool call that changed the user's memory succeeded, so the next
  * session in the room gathers again instead of reading the pre-write answer
- * for the rest of the cache TTL. It never changes the current thread: a
- * thread keeps the context it got on first contact.
+ * for the rest of the cache TTL. Channel turns adopt the refreshed context
+ * on a later turn; other clients keep their first-contact context.
  *
  * Applied as a tool middleware to the main agent and every sub-agent; a
  * failed call (thrown, or an error `ToolMessage`) leaves the cache alone.

package/src/plugins/action-proposals/evidence.ts

@@ -1,8 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
-import {
-  stripTurnTimeNote,
-  TURN_TIME_NOTE_KWARG,
-} from '../../core/turn-time-note';
+import { userContent } from '../../channels/replies';
 import { contentToText } from '../../do/transcript';
 
 /** How many of the user's own messages count as evidence, and how much of each. */
@@ -18,8 +15,10 @@ export const NEGATION =
 
 /**
  * The user's own words from the last few turns. The runtime's time note
- * (`Current time: … 14:05 …`) rides on every message the user sent; it is
- * stripped here so its digits can never stand in for an amount.
+ * (`Current time: … 14:05 …`) rides on every message the user sent, and a
+ * WhatsApp reply carries the quoted message; both are stripped here so
+ * neither the note's digits nor an address or amount the user merely quoted
+ * can stand in for what they typed.
  */
 export function userEvidence(messages: readonly BaseMessage[]): string[] {
   return messages
@@ -27,9 +26,9 @@ export function userEvidence(messages: readonly BaseMessage[]): string[] {
     .slice(-EVIDENCE_MESSAGES)
     .map((m) =>
       contentToText(
-        stripTurnTimeNote(
+        userContent(
           m.content,
-          m.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
+          m.additional_kwargs as Record<string, unknown> | undefined,
         ),
       ).slice(0, EVIDENCE_MESSAGE_CHARS),
     );

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -10,6 +10,7 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
+import { ixoAddressOf } from '../../core/user-identity';
 
 const configSchema = z.object({
   HUB_ACTIONS_ENABLED: z.enum(['true', 'false']).default('false'),
@@ -284,12 +285,15 @@ async function hubActionOptions(
     !ctx.hubActions
   )
     return { status: 'unavailable' };
-  return ctx.hubActions.options({
+  const options = await ctx.hubActions.options({
     ownerDid: ctx.user.did,
     provider: channel.provider,
     bindingId: channel.bindingId,
     bindingRevision: channel.bindingRevision,
   });
+  // The address is read off the owner's DID, so the model can name the
+  // account the listed balances belong to without a lookup.
+  return { ...options, ownerAddress: ixoAddressOf(ctx.user.did) };
 }
 
 const manifest: PluginManifest = {
@@ -339,7 +343,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_options',
         description:
-          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units.',
+          "Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units. ownerDid is the authenticated user's DID and ownerAddress their IXO account address.",
         schema: discoverSchema,
         effect: 'read',
         handler: hubActionOptions,

package/src/plugins/index.ts

@@ -1,13 +1,15 @@
 import { ActionProposalsPlugin } from './action-proposals/action-proposals.plugin';
 import { HubActionsPlugin } from './hub-actions/hub-actions.plugin';
+import { IxoChainPlugin } from './ixo-chain';
 export { ActionProposalsPlugin } from './action-proposals/action-proposals.plugin';
 export { HubActionsPlugin } from './hub-actions/hub-actions.plugin';
 /**
  * Bundled Workers-runtime plugins — ports of the Node runtime's MCP / fetch
  * plugins. Each is gated the same way as on Node: `autoDetect` on its env
  * key where one exists (memory / sandbox / firecrawl / composio), always-on
- * otherwise (domain-indexer; vfs self-gates on `ctx.ucan.hasSigningKey()`;
- * pod-creator is on-demand and stays hidden until `load_capability`).
+ * otherwise (domain-indexer; ixo-chain unless `IXO_CHAIN_TOOLS=off`; vfs
+ * self-gates on `ctx.ucan.hasSigningKey()`; pod-creator and ixo-chain are
+ * on-demand and stay hidden until `load_capability`).
  *
  * A host opts in by spreading `BUNDLED_WORKERS_PLUGINS` into
  * `createOracleWorker({ plugins })` — plugins whose env keys are absent are
@@ -46,6 +48,7 @@ export * from './user-preferences';
 export * from './portal';
 export * from './agui';
 export * from './ixo-transaction';
+export * from './ixo-chain';
 export * from './pod-creator';
 
 export const memoryPlugin = new MemoryPlugin();
@@ -72,6 +75,7 @@ export const tasksPlugin = TasksPlugin;
 export const BUNDLED_WORKERS_PLUGINS = [
   new ActionProposalsPlugin(),
   new HubActionsPlugin(),
+  new IxoChainPlugin(),
   memoryPlugin,
   sandboxPlugin,
   firecrawlPlugin,

package/src/plugins/ixo-chain/blocksync.ts

@@ -0,0 +1,214 @@
+/**
+ * Blocksync GraphQL reads: one POST of a document whose ids are inlined as
+ * literals (never JSON variables: two `messages` fields with variables in
+ * one document fail on the server), under the shared retry policy.
+ *
+ * PostGraphile answers field by field: one alias can be null with an error
+ * naming it while the others are fine, so errors are returned beside the
+ * data, never thrown. "current transaction is aborted" and "Connection
+ * terminated unexpectedly" say nothing about the question: the aliases
+ * they name are asked again once, in a document of only those aliases,
+ * and the answers merged; a statement timeout is never asked again (it
+ * would only time out again).
+ */
+import { z } from 'zod';
+import {
+  exchange,
+  unavailable,
+  withRetry,
+  type Attempt,
+  type ChainCall,
+  type Outcome,
+} from './http';
+
+export const BLOCKSYNC_MAX_BYTES = 1024 * 1024;
+/**
+ * Per-attempt wall bound. Above Blocksync's own 8 s statement timeout, so
+ * the server's "statement timeout" answer arrives instead of our abort.
+ */
+export const BLOCKSYNC_ATTEMPT_TIMEOUT_MS = 11_000;
+
+export const TRANSIENT_ERROR =
+  /current transaction is aborted|Connection terminated unexpectedly/;
+export const STATEMENT_TIMEOUT = /statement timeout/i;
+
+export interface GraphqlError {
+  /** The response path; empty when the error is the whole document's. */
+  path: string[];
+  message: string;
+}
+
+export interface BlocksyncAnswer {
+  data: Record<string, unknown> | null;
+  errors: GraphqlError[];
+}
+
+const responseSchema = z.object({
+  data: z.record(z.string(), z.unknown()).nullable().optional(),
+  errors: z
+    .array(
+      z.object({
+        message: z.string(),
+        path: z.array(z.union([z.string(), z.number()])).optional(),
+      }),
+    )
+    .optional(),
+});
+
+/** One aliased root field of a lookup document; `field` begins with `${alias}:`. */
+export interface AliasedField {
+  alias: string;
+  field: string;
+}
+
+/** The fields as one GraphQL document. */
+export function lookupDocument(fields: readonly AliasedField[]): string {
+  return `query ChainLookup { ${fields.map((f) => f.field).join(' ')} }`;
+}
+
+/** Whether `error` concerns `alias` (an error without a path concerns every alias). */
+const concerns = (error: GraphqlError, alias: string) =>
+  error.path.length === 0 || error.path[0] === alias;
+
+/** The fields to ask again: those a transient error names and no statement timeout does. */
+function retryFields(
+  answer: BlocksyncAnswer,
+  fields: readonly AliasedField[],
+): AliasedField[] {
+  const named = (alias: string, pattern: RegExp) =>
+    answer.errors.some(
+      (error) => pattern.test(error.message) && concerns(error, alias),
+    );
+  return fields.filter(
+    ({ alias }) =>
+      named(alias, TRANSIENT_ERROR) && !named(alias, STATEMENT_TIMEOUT),
+  );
+}
+
+/**
+ * The first answer with the retried aliases replaced by the second's. An
+ * error without a path is pinned to the aliases its answer covered, so a
+ * whole-document error of one answer never fails an alias the other
+ * answered.
+ */
+function merge(
+  first: BlocksyncAnswer,
+  second: BlocksyncAnswer,
+  fields: readonly AliasedField[],
+  retried: readonly AliasedField[],
+): BlocksyncAnswer {
+  const again = new Set(retried.map((f) => f.alias));
+  const data: Record<string, unknown> = { ...first.data };
+  for (const alias of again)
+    if (second.data && alias in second.data) data[alias] = second.data[alias];
+    else delete data[alias];
+  const pin = (error: GraphqlError, aliases: readonly string[]) =>
+    error.path.length
+      ? [error]
+      : aliases.map((alias) => ({ path: [alias], message: error.message }));
+  const kept = fields.map((f) => f.alias).filter((alias) => !again.has(alias));
+  return {
+    data,
+    errors: [
+      ...first.errors
+        .filter(
+          (error) => !error.path.length || !again.has(error.path[0] ?? ''),
+        )
+        .flatMap((error) => pin(error, kept)),
+      ...second.errors.flatMap((error) => pin(error, [...again])),
+    ],
+  };
+}
+
+/** One POST of `document`, parsed. */
+async function post(
+  call: ChainCall,
+  document: string,
+  opts: { timeoutMs?: number; maxBytes?: number },
+): Promise<Attempt<BlocksyncAnswer>> {
+  const answer = await exchange(
+    call,
+    'blocksync',
+    call.blocksyncUrl,
+    {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+      },
+      body: JSON.stringify({ query: document }),
+    },
+    {
+      timeoutMs: opts.timeoutMs ?? BLOCKSYNC_ATTEMPT_TIMEOUT_MS,
+      maxBytes: opts.maxBytes ?? BLOCKSYNC_MAX_BYTES,
+    },
+  );
+  if (!answer.ok) return answer;
+  let json: unknown;
+  try {
+    json = JSON.parse(answer.value);
+  } catch {
+    return {
+      ok: false,
+      failure: unavailable(
+        'blocksync',
+        'it answered something that is not JSON',
+        false,
+      ),
+      retry: false,
+      note: 'malformed JSON',
+    };
+  }
+  const parsed = responseSchema.safeParse(json);
+  if (!parsed.success || (!parsed.data.data && !parsed.data.errors?.length))
+    return {
+      ok: false,
+      failure: unavailable(
+        'blocksync',
+        'it answered in an unexpected shape',
+        false,
+      ),
+      retry: false,
+      note: 'unexpected shape',
+    };
+  const errors = (parsed.data.errors ?? []).map((error) => ({
+    path: (error.path ?? []).map(String),
+    message: error.message,
+  }));
+  return { ok: true, value: { data: parsed.data.data ?? null, errors } };
+}
+
+/**
+ * POST the fields as one document to the configured Blocksync GraphQL
+ * endpoint. After a transient error, only the aliases it named are asked
+ * again and merged into the first answer; if that retry fails, the first
+ * answer stands.
+ */
+export function blocksyncLookup(
+  call: ChainCall,
+  fields: readonly AliasedField[],
+  opts: { timeoutMs?: number; maxBytes?: number } = {},
+): Promise<Outcome<BlocksyncAnswer>> {
+  let first: BlocksyncAnswer | null = null;
+  let retried: AliasedField[] = [];
+  return withRetry(
+    call,
+    { label: 'blocksync', upstream: call.blocksyncUrl },
+    async () => {
+      const asked = first ? retried : fields;
+      const read = await post(call, lookupDocument(asked), opts);
+      if (!read.ok) return read;
+      const again = retryFields(read.value, asked);
+      const value = first
+        ? merge(first, read.value, fields, asked)
+        : read.value;
+      if (!first && again.length) {
+        first = read.value;
+        retried = again;
+      }
+      return again.length
+        ? { ok: true, value, retry: true, note: 'transient GraphQL error' }
+        : { ok: true, value };
+    },
+  );
+}

package/src/plugins/ixo-chain/denoms.ts

@@ -0,0 +1,189 @@
+/**
+ * How a bank denom is shown. DenomMetadata is trusted for any denom: on
+ * the IXO chain it is written only by chain code (liquidstake pools, which
+ * governance creates; the IBC transfer module; genesis and upgrades), never
+ * by a token's issuer (the chain has no tokenfactory module). This is
+ * broader than the Auth Hub's rule (ixo-auth-worker
+ * `src/lib/actions/denom-display.ts`), which reads metadata only for
+ * `ibc/…`, so the Hub may still show a native token such as `upay` as
+ * unverified.
+ *
+ * - `uixo`: always IXO with 6 decimals, verified, no lookup.
+ * - any other denom with metadata whose `display` unit is listed in
+ *   `denom_units` with an exponent of 0–18: verified, those decimals, the
+ *   metadata `symbol` (or, when that is empty, the display unit
+ *   upper-cased: `uatom` → `ATOM`) if it is plain ASCII.
+ * - anything else (no metadata, a display unit not listed — the shape IBC
+ *   transfers register — or a malformed denom, which is never looked up):
+ *   unverified, base units (0 decimals), the full denom as its symbol.
+ *
+ * A denom whose metadata could not be read (a transport failure, or no
+ * budget left to ask) is shown the same way with `metadataUnavailable`:
+ * it may still be verified.
+ */
+import { z } from 'zod';
+import { MIN_ATTEMPT_MS, throwIfAborted, type ChainCall } from './http';
+import { restJson } from './rest';
+
+export type DenomMetadataView = { symbol: string; decimals: number } | null;
+export type TokenDisplay = {
+  symbol: string;
+  decimals: number;
+  verified: boolean;
+  metadataUnavailable?: true;
+};
+
+/** Symbols an unverified denom may never use (compared case-insensitively). */
+const RESERVED_SYMBOLS = ['IXO', 'USDC', 'USDT', 'ATOM', 'OSMO'] as const;
+/** The Cosmos SDK bank denom pattern: only such a denom is looked up. */
+const DENOM = /^[a-zA-Z][a-zA-Z0-9/:._-]{2,127}$/;
+// Plain ASCII only: no spaces or look-alike Unicode letters ("UЅDC").
+const SAFE_SYMBOL = /^[A-Za-z0-9._-]{1,32}$/;
+
+export function trustedDenomDisplay(
+  denom: string,
+  metadata: DenomMetadataView,
+): TokenDisplay {
+  if (denom === 'uixo') return { symbol: 'IXO', decimals: 6, verified: true };
+  const symbol =
+    metadata && SAFE_SYMBOL.test(metadata.symbol) ? metadata.symbol : null;
+  if (
+    metadata &&
+    symbol &&
+    DENOM.test(denom) &&
+    Number.isInteger(metadata.decimals) &&
+    metadata.decimals >= 0 &&
+    metadata.decimals <= 18
+  )
+    return { symbol, decimals: metadata.decimals, verified: true };
+  const reserved =
+    symbol !== null &&
+    (RESERVED_SYMBOLS as readonly string[]).includes(symbol.toUpperCase());
+  return {
+    symbol: symbol && !reserved ? symbol : denom,
+    decimals: 0,
+    verified: false,
+  };
+}
+
+/** Base units as a decimal string: `("9000000", 6)` → `"9"`, `("1234567", 6)` → `"1.234567"`. */
+export function formatUnits(amount: string, decimals: number): string {
+  if (decimals === 0) return amount;
+  const padded = amount.padStart(decimals + 1, '0');
+  const whole = padded.slice(0, -decimals);
+  const fraction = padded.slice(-decimals).replace(/0+$/, '');
+  return fraction ? `${whole}.${fraction}` : whole;
+}
+
+/**
+ * Per isolate: found metadata is reused for 10 min, a definite miss (404,
+ * or no display unit) for 60 s, a failed read for 10 s — a failure is
+ * never kept as a miss, so it cannot leave a real token unverified.
+ */
+export const METADATA_TTL_MS = 600_000;
+export const METADATA_NOT_FOUND_TTL_MS = 60_000;
+export const METADATA_FAILED_TTL_MS = 10_000;
+const CACHE_LIMIT = 256;
+
+/** A metadata read: its view (null for a miss), or why there is none. */
+type Lookup = { metadata: DenomMetadataView } | 'failed' | 'aborted';
+
+const metadataCache = new Map<string, { lookup: Lookup; expiresAt: number }>();
+/** Reads in flight, shared by every call of the isolate that needs the same denom. */
+const inflight = new Map<string, Promise<Lookup>>();
+
+/** Tests only: forget every cached metadata answer. */
+export function resetDenomMetadataCache(): void {
+  metadataCache.clear();
+  inflight.clear();
+}
+
+const metadataResponse = z.object({
+  metadata: z.object({
+    denom_units: z.array(
+      z.object({ denom: z.string(), exponent: z.number().int() }),
+    ),
+    display: z.string(),
+    symbol: z.string(),
+  }),
+});
+
+/**
+ * One DenomMetadata read. The by-query-string route is used because the
+ * path route cannot carry the slash in `ibc/…` (the gateway answers 501).
+ * A 404 is a miss; any other failure is `failed`; the launching turn's
+ * abort is `aborted` (never cached), so a call sharing the read is not
+ * failed by another turn's abort.
+ */
+async function readMetadata(call: ChainCall, denom: string): Promise<Lookup> {
+  let read;
+  try {
+    read = await restJson(
+      call,
+      `/cosmos/bank/v1beta1/denoms_metadata_by_query_string?denom=${encodeURIComponent(denom)}`,
+      metadataResponse,
+      { label: 'denom metadata', maxBytes: 64 * 1024, notFoundOn404: true },
+    );
+  } catch (error) {
+    if (call.signal.aborted) return 'aborted';
+    throw error;
+  }
+  if (!read.ok)
+    return read.failure.reason === 'not_found' ? { metadata: null } : 'failed';
+  const { metadata } = read.value;
+  const unit = metadata.denom_units.find((u) => u.denom === metadata.display);
+  return {
+    metadata:
+      unit && unit.exponent >= 0 && unit.exponent <= 18
+        ? {
+            symbol: metadata.symbol || metadata.display.toUpperCase(),
+            decimals: unit.exponent,
+          }
+        : null,
+  };
+}
+
+function remember(key: string, lookup: Lookup): void {
+  if (lookup === 'aborted') return;
+  const ttl =
+    lookup === 'failed'
+      ? METADATA_FAILED_TTL_MS
+      : lookup.metadata
+        ? METADATA_TTL_MS
+        : METADATA_NOT_FOUND_TTL_MS;
+  if (metadataCache.size > CACHE_LIMIT) metadataCache.clear();
+  metadataCache.set(key, { lookup, expiresAt: Date.now() + ttl });
+}
+
+/** The cached lookup, the read in flight, or a new read; `failed` without a read once the budget is spent. */
+function lookupOf(call: ChainCall, denom: string): Promise<Lookup> {
+  const key = `${call.restUrl}|${denom}`;
+  const hit = metadataCache.get(key);
+  if (hit && hit.expiresAt > Date.now()) return Promise.resolve(hit.lookup);
+  const running = inflight.get(key);
+  if (running) return running;
+  if (call.deadline - Date.now() < MIN_ATTEMPT_MS)
+    return Promise.resolve('failed');
+  const read = readMetadata(call, denom)
+    .then((lookup) => {
+      remember(key, lookup);
+      return lookup;
+    })
+    .finally(() => inflight.delete(key));
+  inflight.set(key, read);
+  return read;
+}
+
+/** The display of `denom`, reading its DenomMetadata for every denom but `uixo`. */
+export async function denomDisplay(
+  call: ChainCall,
+  denom: string,
+): Promise<TokenDisplay> {
+  if (denom === 'uixo' || !DENOM.test(denom))
+    return trustedDenomDisplay(denom, null);
+  const lookup = await lookupOf(call, denom);
+  throwIfAborted(call.signal);
+  return lookup === 'failed' || lookup === 'aborted'
+    ? { ...trustedDenomDisplay(denom, null), metadataUnavailable: true }
+    : trustedDenomDisplay(denom, lookup.metadata);
+}