@ixo/oracle-runtime-workers 0.41.0 → 0.41.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.41.0",
+  "version": "0.41.2",
   "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": {
@@ -67,8 +67,8 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
-    "@ixo/common": "1.8.0",
     "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/common": "1.8.0",
     "@ixo/ucan": "2.3.0",
     "@ixo/action-interactions": "0.1.1"
   },

package/src/plugins/asks/skills.ts

@@ -2,14 +2,14 @@
  * The asks skills, read at runtime from the released ixo-plugins repo so a
  * newly published skill needs no oracle release: mainnet reads
  * `plugins/asks/skills/<name>/SKILL.md`, testnet and devnet
- * `plugins/asks-testnet/...` (practice money). The names come from the
- * folder listing.
+ * `plugins/asks-testnet/...` (practice money). The names come from
+ * `plugins/<folder>/skills/index.json`.
  *
  * Never on a turn's path: `skills()` answers from memory, then the Workers
  * cache (across isolate restarts), then the bundled copy, and refreshes in
  * the background once the copy is an hour old, with `If-None-Match` so an
- * unchanged file costs a 304 (which GitHub does not count against its rate
- * limit). Any failure keeps what is there.
+ * unchanged file costs a 304. Everything is read from
+ * raw.githubusercontent.com. Any failure keeps what is there.
  *
  * The bundled copy (`skills.bundled.json`) was taken from ixo-plugins `main`;
  * refresh it by re-reading the same two folders when the skills change a lot.
@@ -158,25 +158,18 @@ export class AsksSkills {
   private async pull(): Promise<void> {
     const { folder } = this.deps;
     const before = this.snapshot ?? bundledSnapshot(folder);
+    // Not GitHub's API: unauthenticated, it answers 403 on Cloudflare's shared IPs.
     const list = await this.deps.fetch(
-      `https://api.github.com/repos/${REPO}/contents/plugins/${folder}/skills?ref=${BRANCH}`,
-      {
-        headers: {
-          accept: 'application/vnd.github+json',
-          'user-agent': 'ixo-oracle',
-          ...(before.listEtag ? { 'if-none-match': before.listEtag } : {}),
-        },
-      },
+      `https://raw.githubusercontent.com/${REPO}/${BRANCH}/plugins/${folder}/skills/index.json`,
+      { headers: before.listEtag ? { 'if-none-match': before.listEtag } : {} },
     );
     let names: string[];
     if (list.status === 304) names = Object.keys(before.files);
     else if (list.ok) {
-      const entries =
-        await list.json<Array<{ name?: unknown; type?: unknown }>>();
-      names = entries.flatMap((one) =>
-        one.type === 'dir' && typeof one.name === 'string' ? [one.name] : [],
-      );
-    } else throw new Error(`listing answered ${list.status}`);
+      const index = await list.json<unknown>();
+      if (!Array.isArray(index)) throw new Error('index.json is not a list');
+      names = index.filter((name): name is string => typeof name === 'string');
+    } else throw new Error(`index.json answered ${list.status}`);
     names = names.filter((name) => SKILL_NAME.test(name)).slice(0, MAX_SKILLS);
 
     const files: SkillSnapshot['files'] = {};

package/src/plugins/asks/testing.ts

@@ -141,7 +141,6 @@ export function fakeContext(
       error: () => undefined,
       debug: () => undefined,
     },
-    background: (work: Promise<unknown>) => void work,
     ...extra,
   } as unknown as RuntimeContext;
 }

package/src/plugins/asks/tools.ts

@@ -470,8 +470,13 @@ function connectorTool(
   };
 }
 
-/** The connector's tools for this turn: cached definitions, a lazy client. `null`: signed out. */
-async function connectorTools(turn: AsksTurn): Promise<PluginTool[] | null> {
+/**
+ * The connector's tools for this turn: cached definitions, a lazy client.
+ * `null`: signed out. `'loading'`: none cached yet, being fetched for the next message.
+ */
+async function connectorTools(
+  turn: AsksTurn,
+): Promise<PluginTool[] | null | 'loading'> {
   const { mcpUrl } = turn;
   const cached = defsCache.get(mcpUrl);
   const list = async (token: string) => {
@@ -479,8 +484,30 @@ async function connectorTools(turn: AsksTurn): Promise<PluginTool[] | null> {
     defsCache.set(mcpUrl, { defs: fresh, expiresAt: turn.now() + DEFS_TTL_MS });
     return fresh;
   };
+  const refresh = (background: (work: Promise<unknown>) => void) => {
+    if (defsRefreshing.has(mcpUrl)) return;
+    defsRefreshing.add(mcpUrl);
+    const work = turn.conn
+      .token()
+      .then(async (read) => {
+        if (read.ok) await list(read.access);
+        else if (read.reason !== 'unreachable') await markSeen(turn, null);
+      })
+      .catch((error: unknown) =>
+        turn.ctx.logger.warn(
+          `[asks] could not list asks tools: ${String(error)}`,
+        ),
+      )
+      .finally(() => defsRefreshing.delete(mcpUrl));
+    background(work);
+  };
   let defs = cached?.defs;
   if (!defs) {
+    // Never hold a turn on asks.world: the full list is there from the next message.
+    if (turn.ctx.background) {
+      refresh(turn.ctx.background);
+      return 'loading';
+    }
     const read = await turn.conn.token();
     if (!read.ok) {
       if (read.reason === 'unreachable')
@@ -489,19 +516,9 @@ async function connectorTools(turn: AsksTurn): Promise<PluginTool[] | null> {
       return null;
     }
     defs = await list(read.access);
-  } else if (
-    cached &&
-    cached.expiresAt <= turn.now() &&
-    !defsRefreshing.has(mcpUrl)
-  ) {
+  } else if (cached && cached.expiresAt <= turn.now() && turn.ctx.background) {
     // Stale definitions keep serving while they refresh in the background.
-    defsRefreshing.add(mcpUrl);
-    const work = turn.conn
-      .token()
-      .then((read) => (read.ok ? list(read.access) : undefined))
-      .catch(() => undefined)
-      .finally(() => defsRefreshing.delete(mcpUrl));
-    turn.ctx.background?.(work);
+    refresh(turn.ctx.background);
   }
   const session = new AsksSession(turn);
   return defs.map((def) => connectorTool(turn, session, def));
@@ -710,5 +727,13 @@ export async function asksTools(turn: AsksTurn): Promise<PluginTool[]> {
     return [];
   });
   if (remote === null) return base;
+  if (remote === 'loading') {
+    const status = base[1]!;
+    base[1] = {
+      ...status,
+      description: `${status.description} asks.world's other actions are still loading and are there from the next message: never say asks cannot do something.`,
+    };
+    return [...base, disconnectTool(turn), attachTool(turn)];
+  }
   return [...base, disconnectTool(turn), attachTool(turn), ...remote];
 }

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

@@ -903,6 +903,41 @@ function issuesOf(
   );
 }
 
+/** Why a Hub action tool did nothing: Hub actions are off for this oracle. */
+export const HUB_ACTIONS_OFF_REASON =
+  'Hub actions are not enabled for this oracle.';
+
+/**
+ * Why a Hub action tool did nothing on a Portal, Matrix or other non-channel
+ * turn. Auth Hub reviews are bound to a channel binding, so nothing can be
+ * prepared here; the reason says so in words the model can relay, so it
+ * never reads the refusal as an Auth Hub outage.
+ */
+export const NOT_A_CHANNEL_CHAT_REASON =
+  'Coin sends, chain transactions and other Auth Hub actions can be prepared only in a channel chat with this oracle (such as WhatsApp), not in this chat. Auth Hub was not contacted and nothing was prepared or sent. Tell the person to ask in their channel chat.';
+
+/**
+ * The turn's channel binding and Hub client when Hub actions can be
+ * prepared on this turn, else the refusal that names why not.
+ */
+function channelTurnOf(ctx: RuntimeContext):
+  | {
+      channel: NonNullable<RuntimeContext['session']['channel']>;
+      hubActions: NonNullable<RuntimeContext['hubActions']>;
+    }
+  | { refusal: { status: 'unavailable'; reason: string } } {
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      refusal: { status: 'unavailable', reason: HUB_ACTIONS_OFF_REASON },
+    };
+  const channel = ctx.session.channel;
+  if (ctx.session.client !== 'channel' || !channel)
+    return {
+      refusal: { status: 'unavailable', reason: NOT_A_CHANNEL_CHAT_REASON },
+    };
+  return { channel, hubActions: ctx.hubActions };
+}
+
 /**
  * The catalogue types this account may use: the Hub capabilities'
  * `chainTx.messageTypes`, which follow the protocol level the Hub speaks
@@ -916,16 +951,11 @@ function issuesOf(
 async function availableChainTxTypes(
   ctx: RuntimeContext,
 ): Promise<readonly ChainTxMessageType[]> {
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !ctx.session.channel ||
-    !ctx.hubActions
-  )
-    return [];
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return [];
   let chainTx;
   try {
-    chainTx = (await ctx.hubActions.capabilities({ turn: true })).chainTx;
+    chainTx = (await turn.hubActions.capabilities({ turn: true })).chainTx;
   } catch (error) {
     ctx.logger.warn(
       `[hub-actions] capabilities unavailable, no chain transaction types this turn: ${error instanceof Error ? error.message : String(error)}`,
@@ -1101,12 +1131,16 @@ async function hubActionStatus(
   ctx: RuntimeContext,
 ): Promise<unknown> {
   const parsed = statusSchema.safeParse(input);
-  if (
-    !parsed.success ||
-    !ctx.hubActions ||
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true'
-  )
-    return { status: 'unavailable' };
+  if (!parsed.success)
+    return {
+      status: 'unavailable',
+      reason:
+        'An actionId is required: the 32-character id of a Hub action prepared for this owner.',
+    };
+  // Not only a channel turn: an action prepared in a channel chat is read
+  // from the Portal too, where the channel's conversation is mirrored.
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return { status: 'unavailable', reason: HUB_ACTIONS_OFF_REASON };
   try {
     const read = await ctx.hubActions.status(
       ctx.user.did,
@@ -1138,15 +1172,10 @@ async function hubActionCapabilities(
   _input: unknown,
   ctx: RuntimeContext,
 ): Promise<unknown> {
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !ctx.session.channel ||
-    !ctx.hubActions
-  )
-    return { status: 'unavailable' };
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return turn.refusal;
   try {
-    return await ctx.hubActions.capabilities();
+    return await turn.hubActions.capabilities();
   } catch (error) {
     const refused = refusalOf(error);
     if (refused) return refused;
@@ -1158,17 +1187,12 @@ async function hubActionOptions(
   _input: unknown,
   ctx: RuntimeContext,
 ): Promise<unknown> {
-  const channel = ctx.session.channel;
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !channel ||
-    !ctx.hubActions
-  )
-    return { status: 'unavailable' };
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return turn.refusal;
+  const { channel } = turn;
   let options;
   try {
-    options = await ctx.hubActions.options({
+    options = await turn.hubActions.options({
       ownerDid: ctx.user.did,
       provider: channel.provider,
       bindingId: channel.bindingId,
@@ -1184,6 +1208,60 @@ async function hubActionOptions(
   return { ...options, ownerAddress: ixoAddressOf(ctx.user.did) };
 }
 
+/**
+ * The tools that prepare a Hub action, offered only on a channel turn
+ * (`getRequestTools`): Auth Hub binds every review to the turn's channel
+ * binding, so on a Portal, Matrix or other turn they could only refuse, and
+ * a model offered them reads the refusal as an Auth Hub outage. Their
+ * handlers still refuse off a channel turn, with a reason. Built once.
+ */
+export const HUB_ACTION_CHANNEL_TOOLS: readonly PluginTool[] = [
+  {
+    name: 'hub_action_capabilities',
+    description:
+      "Read this authenticated oracle account's enabled operation kinds and exact registered form field schema before proposing a Hub action.",
+    schema: discoverSchema,
+    effect: 'read',
+    handler: hubActionCapabilities,
+  },
+  {
+    name: 'hub_action_options',
+    description:
+      "Read the 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 to prepare 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,
+  },
+  {
+    name: 'request_hub_action',
+    description:
+      'Prepare a supported operation for the authenticated channel owner to review in Auth Hub. Never approves, signs, or executes. For email, propose one plain-text message to one recipient using a confirmed Gmail send connection. Supply only the operation candidate; the runtime supplies identity and turn binding. Coin sends and other chain transactions have their own tool (request_chain_transaction). Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again. Limits are checked on the call; `startsAt` and `endsAt` are ISO 8601 with an offset, a saved `filename` ends in .txt, a form field `id` is lower_snake_case.',
+    schema: requestSchema,
+    effect: 'write',
+    handler: requestHubAction,
+  },
+  {
+    name: 'describe_chain_messages',
+    description: DESCRIBE_CHAIN_MESSAGES_TOOL_DESCRIPTION,
+    schema: describeChainMessagesSchema,
+    effect: 'read',
+    handler: describeChainMessages,
+  },
+];
+
+/**
+ * hub_action_status, offered on every turn: an action prepared in a channel
+ * chat is followed from the Portal too, where that conversation is mirrored.
+ */
+export const HUB_ACTION_STATUS_TOOL: PluginTool = {
+  name: 'hub_action_status',
+  description:
+    'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it. Coin sends, chain transactions and other Hub actions are prepared only in a channel chat (such as WhatsApp): when this chat has no tool for one, tell the person to ask there, and never call it an Auth Hub outage.',
+  schema: statusSchema,
+  effect: 'read',
+  handler: hubActionStatus,
+};
+
 const manifest: PluginManifest = {
   title: 'Auth Hub action review',
   summary:
@@ -1224,63 +1302,26 @@ export class HubActionsPlugin extends OraclePlugin {
     );
   }
   /**
+   * The tools that prepare a Hub action, on a channel turn only (none on a
+   * Portal, Matrix or other turn, where Auth Hub cannot bind a review).
    * request_chain_transaction is built per turn: its schema names only the
    * message types this account may use (Auth Hub capabilities, cached by
    * the owner object), so 37 types do not reach a model that may use 4.
    */
   override async getRequestTools(ctx: RuntimeContext): Promise<PluginTool[]> {
+    if ('refusal' in channelTurnOf(ctx)) return [];
     const [available, described] = await Promise.all([
       chainTxTypesForTurn(ctx),
       describedChainTxTypes(ctx, ctx.history.messages),
     ]);
     const tool = chainTransactionTool(available, described);
-    return tool ? [tool] : [];
+    return [...HUB_ACTION_CHANNEL_TOOLS, ...(tool ? [tool] : [])];
   }
   /** Gives each model call the request tool with the fields described so far in the turn. */
   override getRequestMiddlewares(ctx: RuntimeContext): AgentMiddleware[] {
     return [chainTxFieldsMiddleware(ctx)];
   }
   override getTools(): PluginTool[] {
-    return [
-      {
-        name: 'hub_action_capabilities',
-        description:
-          "Read this authenticated oracle account's enabled operation kinds and exact registered form field schema before proposing a Hub action.",
-        schema: discoverSchema,
-        effect: 'read',
-        handler: hubActionCapabilities,
-      },
-      {
-        name: 'hub_action_options',
-        description:
-          "Read the 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 to prepare 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,
-      },
-      {
-        name: 'request_hub_action',
-        description:
-          'Prepare a supported operation for the authenticated channel owner to review in Auth Hub. Never approves, signs, or executes. For email, propose one plain-text message to one recipient using a confirmed Gmail send connection. Supply only the operation candidate; the runtime supplies identity and turn binding. Coin sends and other chain transactions have their own tool (request_chain_transaction). Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again. Limits are checked on the call; `startsAt` and `endsAt` are ISO 8601 with an offset, a saved `filename` ends in .txt, a form field `id` is lower_snake_case.',
-        schema: requestSchema,
-        effect: 'write',
-        handler: requestHubAction,
-      },
-      {
-        name: 'describe_chain_messages',
-        description: DESCRIBE_CHAIN_MESSAGES_TOOL_DESCRIPTION,
-        schema: describeChainMessagesSchema,
-        effect: 'read',
-        handler: describeChainMessages,
-      },
-      {
-        name: 'hub_action_status',
-        description:
-          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it.',
-        schema: statusSchema,
-        effect: 'read',
-        handler: hubActionStatus,
-      },
-    ];
+    return [HUB_ACTION_STATUS_TOOL];
   }
 }