@ixo/oracle-runtime-workers 0.33.0 → 0.33.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.33.0",
+  "version": "0.33.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": {
@@ -34,7 +34,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
-    "@ixo/action-protocol": "0.9.0",
+    "@ixo/action-protocol": "0.9.1",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",

package/src/hub-actions/client.ts

@@ -115,12 +115,14 @@ export interface HubActionTransport {
  * An Auth Hub older than this runtime's version checks `?version=` against
  * its closed list (1 to 6 on 0.8.0, 1 to 5 on 0.7.0) and answers every call
  * that declares a version it does not know with 400 `invalid_request`,
- * before anything else. This runtime then steps down
+ * before anything else. This runtime's capabilities read then steps down
  * (`HUB_PROTOCOL_VERSIONS`: 7, then 6, then 5) to the highest version that
- * Hub answers (every Hub action the lower level has keeps working while
- * Auth Hub is rolled out: the group steps at 6, the level-6 chain types too
- * at 5) and asks for 7 again after `HUB_PROTOCOL_RECHECK_MS`; a Hub that
- * refuses 5 too is told apart with `HUB_UPDATE_REQUIRED`.
+ * Hub answers, and every other call uses that version (every Hub action
+ * the lower level has keeps working while Auth Hub is rolled out: the group
+ * steps at 6, the level-6 chain types too at 5); it asks for 7 again after
+ * `HUB_PROTOCOL_RECHECK_MS`. Another read refused at that version never
+ * lowers it (`atSettledVersion`). A Hub that refuses 5 too is told apart
+ * with `HUB_UPDATE_REQUIRED`.
  */
 const HUB_PROTOCOL_VERSION = '7';
 /** The lowest version this runtime works at: 7 without the group steps and the level-6 chain types. */
@@ -144,6 +146,14 @@ export const HUB_PROTOCOL_RECHECK_MS = 10 * 60_000;
  * callbacks pick the outcomes up once the Hub is updated.
  */
 export const HUB_UPDATE_REQUIRED = `Auth Hub must be updated before this oracle can use Hub actions: it does not accept protocol version ${HUB_PROTOCOL_LOWEST_VERSION}, the lowest this runtime works with (invalid_request). Tell the person this is not available right now; retrying or changing the fields will not help.`;
+/**
+ * A read (options, status) Auth Hub refused at the version its
+ * capabilities read accepts: a fault on that route, not an older Hub.
+ */
+export function hubReadRefused(version: string): string {
+  return `Auth Hub refused this read at protocol version ${version}, which it accepts for this oracle's other calls (invalid_request). Tell the person this is not available right now and try again later; changing the fields will not help.`;
+}
+
 /** Every Hub call but a chain-transaction prepare. */
 const HUB_TIMEOUT_MS = 10_000;
 /**
@@ -198,12 +208,15 @@ export class HubActionClient {
   }
 
   /**
-   * A read at the current version; when Auth Hub refuses it as unknown,
-   * the same read at each lower version in turn (`HUB_PROTOCOL_VERSIONS`),
-   * and the version it answered is remembered for
-   * `HUB_PROTOCOL_RECHECK_MS`. Only reads do this: a refused read changed
-   * nothing, while a prepare's 400 can be a real refusal of its operation.
-   * A Hub that refuses the lowest version too answers `HUB_UPDATE_REQUIRED`.
+   * The capabilities read at the current version; when Auth Hub refuses it
+   * as unknown, the same read at each lower version in turn
+   * (`HUB_PROTOCOL_VERSIONS`), and the version it answered is remembered for
+   * `HUB_PROTOCOL_RECHECK_MS`. Only the capabilities read decides the
+   * version: a refused read changed nothing, while a prepare's 400 can be a
+   * real refusal of its operation, and another route refusing a version
+   * (an options route bug once refused 7 and 6) must never downgrade the
+   * operations. A Hub that refuses the lowest version too answers
+   * `HUB_UPDATE_REQUIRED`.
    */
   private async negotiated<T>(
     read: (version: HubProtocolVersion) => Promise<T>,
@@ -229,6 +242,37 @@ export class HubActionClient {
     throw new Error('No Hub protocol version to read at');
   }
 
+  /**
+   * Another read (options, status) at the version the capabilities read
+   * settled on. When Auth Hub refuses it as unknown, the capabilities read
+   * settles the version again (a Hub rolled back since); only when that
+   * changes the version is the read tried once more, at the new version.
+   * Otherwise this read fails on its own (`hubReadRefused`) and the version
+   * the operations use stays as it is. `timeoutMs` bounds that capabilities
+   * read as it bounds this one.
+   */
+  private async atSettledVersion<T>(
+    read: (version: HubProtocolVersion) => Promise<T>,
+    timeoutMs = HUB_TIMEOUT_MS,
+  ): Promise<T> {
+    const version = this.protocolVersion;
+    try {
+      return await read(version);
+    } catch (error) {
+      if (!isUpdateRequired(error)) throw error;
+    }
+    await this.capabilities(timeoutMs);
+    const settled = this.protocolVersion;
+    if (settled === version)
+      throw new HubActionRefused(
+        'refused',
+        hubReadRefused(version),
+        undefined,
+        400,
+      );
+    return read(settled);
+  }
+
   /**
    * `subject`: what a refused prepare is called in the model's words;
    * `steps`: a chain transaction's message types, for the words of a refusal
@@ -343,7 +387,7 @@ export class HubActionClient {
     // Options version 3 (asked at the protocol version; version 4 answers
     // the same): version 2 plus the owner's bank tokens
     // (`transfer.tokens`), which any-token transfers are chosen from.
-    const options = await this.negotiated(async (version) => {
+    const options = await this.atSettledVersion(async (version) => {
       const query = new URLSearchParams({
         bindingId: input.bindingId,
         bindingRevision: String(input.bindingRevision),
@@ -391,12 +435,14 @@ export class HubActionClient {
   ): Promise<HubActionStatus> {
     if (!/^[A-Za-z0-9_-]{32}$/.test(id))
       throw new Error('Invalid Hub action id');
-    const raw = await this.negotiated((version) =>
-      this.send(
-        `/api/internal/actions/operations/${id}?version=${version}`,
-        undefined,
-        timeoutMs,
-      ),
+    const raw = await this.atSettledVersion(
+      (version) =>
+        this.send(
+          `/api/internal/actions/operations/${id}?version=${version}`,
+          undefined,
+          timeoutMs,
+        ),
+      timeoutMs,
     );
     if (!isRecord(raw)) throw new Error('Invalid Hub action status');
     const value = raw;

package/src/hub-actions/transfer.ts

@@ -406,6 +406,16 @@ const HUB_TRANSIENT_CODES: Readonly<Record<number, readonly string[]>> = {
   503: ['transfer_unavailable'],
 };
 
+/**
+ * Auth Hub's 409 `sequence_reserved`: another card of the owner's is still
+ * waiting for their review and holds the account's next transaction, so no
+ * new card can be made until that one is approved or declined. Plain words
+ * and the next step; the account's sequence is never named (the model
+ * repeated "reserved transaction sequence" to the person on devnet).
+ */
+export const PENDING_CARD_WORDS =
+  'The owner already has another card waiting for their review, so this one cannot be prepared yet. Tell them, in these words or close to them: “You already have another card waiting for your review. Approve or decline that one first, then I can prepare this.” Do not retry until they have, and never mention sequences or anything technical.';
+
 function hubErrorBody(
   body: unknown,
 ): { error: string; reason?: string } | null {
@@ -436,6 +446,8 @@ const HUB_REASON_MAX = 200;
  *   `not_authorized`, `operation_not_registered`: the transfer or
  *   transaction as asked cannot go ahead (with the Hub's reason, quoted and
  *   labelled as data, see `quoteHubText`);
+ * - 409 `sequence_reserved`: another card is waiting for the owner's
+ *   review; approve or decline it first (`PENDING_CARD_WORDS`);
  * - 409 `sequence_mismatch`, 503 `transfer_unavailable`: temporary, try
  *   again shortly;
  * - any other 409: the account may not use this operation (deterministic,
@@ -484,10 +496,16 @@ export function hubPrepareRefusal(
       undefined,
       status,
     );
+  if (status === 409 && parsed.error === 'sequence_reserved')
+    return new HubActionRefused('refused', PENDING_CARD_WORDS, undefined, 409);
   if (HUB_TRANSIENT_CODES[status]?.includes(parsed.error))
     return new HubActionRefused(
       'refused',
-      `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
+      // A sequence race is named by its effect only: the code would read as
+      // jargon if repeated to the person.
+      parsed.error === 'sequence_mismatch'
+        ? 'Auth Hub could not prepare this just now because the account changed while it was being prepared; try again shortly.'
+        : `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
       undefined,
       status,
     );

package/src/plugins/hub-actions/chain-tx-catalog.ts

@@ -103,6 +103,13 @@ const SERVICE_REF =
  */
 const LINKED_ENTITY_ADDRESS =
   /^(?:\{id\}#)?ixo1(?:[023456789acdefghjklmnpqrstuvwxyz]{38}|[023456789acdefghjklmnpqrstuvwxyz]{58})$/;
+/**
+ * Who receives coins or impact tokens: a 20-byte account or a 32-byte
+ * contract address (a group's own account, its treasury). Never a signer or
+ * identity field.
+ */
+const RECIPIENT_ADDRESS =
+  /^ixo1(?:[023456789acdefghjklmnpqrstuvwxyz]{38}|[023456789acdefghjklmnpqrstuvwxyz]{58})$/;
 /** A 32-byte contract address (a group and its proposal list): `ixo1` and 58 characters. */
 const CONTRACT_ADDRESS = /^ixo1[023456789acdefghjklmnpqrstuvwxyz]{58}$/;
 /**
@@ -193,6 +200,14 @@ const address = (what: string) =>
       'A 20-byte ixo1… account address (42 characters); contract addresses are refused.',
     )
     .describe(`${what} (an ixo1… account address).`);
+const recipient = (what: string) =>
+  z
+    .string()
+    .regex(
+      RECIPIENT_ADDRESS,
+      'An ixo1… account address (42 characters), or a group’s own address (62 characters, `dao` in chain_lookup daos or dao_proposals), copied exactly.',
+    )
+    .describe(`${what} (an ixo1… account address, or a group’s own address).`);
 const validator = (what: string) =>
   z
     .string()
@@ -519,11 +534,12 @@ const OWNER_CATALOG = {
       "Sends coins from the owner's wallet to `toAddress`, alone (a single coin send) or as a step of a batch.",
       '`amount` is the amount as the user said it, in the token’s display units ("1.5" for 1.5 IXO): a plain decimal, never base units. The runtime looks the token up in the owner’s token list (hub_action_options `transfer.tokens`), converts the amount with the listed `decimals`, and refuses a token not in the list, more digits after the point than the token has, zero, and more than the listed balance (the bank and stake steps of one token together).',
       '`denom` is optional and defaults to uixo (IXO, 6 decimals). For another token copy its `denom` exactly from `transfer.tokens` (never guess an `ibc/…` hash); name the full denom to the owner for anything but IXO, and say when the token is unverified (it lists 0 decimals: its amount is a whole number of base units).',
-      'Say it like: “Send 1.5 IXO to Thandi (ixo1qy…lvf0).”',
+      '`toAddress` may also be a group’s own address (62 characters): coins sent there go to the group’s treasury. Find it with chain_lookup daos or dao_proposals (`dao`) when the owner names the group, and say the group’s name.',
+      'Say it like: “Send 1.5 IXO to Thandi (ixo1qy…lvf0).” or “Send 2 IXO to the Auth Hub drill group.”',
     ].join(' '),
     schema: z.strictObject({
       type: z.literal('cosmos.bank.send'),
-      toAddress: address('The recipient'),
+      toAddress: recipient('The recipient'),
       amount: z
         .string()
         .max(80)
@@ -596,10 +612,10 @@ const OWNER_CATALOG = {
   'ixo.token.transfer': {
     summary:
       "move IXO impact tokens (1155-style token ids, whole amounts) from the owner's wallet.",
-    rules: `Moves IXO impact tokens (1155-style: each line a token \`id\` of 32 hex characters and a whole \`amount\`, 1 to ${CHAIN_TX_MAX_TOKEN_LINES} lines) from the owner’s wallet to \`recipient\`. Impact tokens have no decimals: an amount is a whole number of tokens. All tokens in one message must come from one token contract. These are not the IXO coin: coins go through \`cosmos.bank.send\`. Say it like: “Give 3 of your carbon credits to Thandi (ixo1qy…lvf0).”`,
+    rules: `Moves IXO impact tokens (1155-style: each line a token \`id\` of 32 hex characters and a whole \`amount\`, 1 to ${CHAIN_TX_MAX_TOKEN_LINES} lines) from the owner’s wallet to \`recipient\` (an account, or a group’s own address from chain_lookup daos or dao_proposals). Impact tokens have no decimals: an amount is a whole number of tokens. All tokens in one message must come from one token contract. These are not the IXO coin: coins go through \`cosmos.bank.send\`. Say it like: “Give 3 of your carbon credits to Thandi (ixo1qy…lvf0).”`,
     schema: z.strictObject({
       type: z.literal('ixo.token.transfer'),
-      recipient: address('The recipient'),
+      recipient: recipient('The recipient'),
       tokens: z
         .array(
           z.strictObject({
@@ -1315,7 +1331,7 @@ const GROUP_CATALOG = {
   'daodao.proposal.execute': {
     summary:
       'carry out a group proposal that passed, so the group’s own account does what it says.',
-    rules: `${GROUP_RULES} Carries out a proposal that passed (\`canRun\` in dao_proposals): the group’s own account then does the proposal’s actions, which the review card lists. On a proposal list the group switched off (\`listDisabled\`), a proposal with actions can’t be carried out. Only when the owner asks for it. Tell them what the proposal does (its title) before preparing. Some groups let only members carry proposals out. Auth Hub tries it first and refuses the card when the actions would fail now (in most groups a failed run marks the proposal failed for good), for example when the group doesn’t hold enough; tell the owner it can be tried again once that is fixed. It costs the owner only the network fee; a deposit paid with the proposal goes back to whoever proposed it unless the group keeps deposits (the review card says). After it goes through (hub_action_status), read the receipt’s \`groupActions\`: \`"failed"\` means the proposal’s actions did not happen and it can’t be tried again; never say it is done. \`"unknown"\`: check its status with chain_lookup dao_proposals before saying anything. Say it like: “Carry out proposal A3, ‘Pay Thandi’, in Clean Water Group: the group sends Thandi 500 IXO. This can’t be undone.”`,
+    rules: `${GROUP_RULES} Carries out a proposal that passed (\`canRun\` in dao_proposals): the group’s own account then does the proposal’s actions, which the review card lists. A proposal with no actions (one that asked for agreement only) is simply marked as carried out: never describe an action for it; say “This just marks it as carried out; nothing else happens.” On a proposal list the group switched off (\`listDisabled\`), a proposal with actions can’t be carried out. Only when the owner asks for it. Tell them what the proposal does (its title) before preparing. Some groups let only members carry proposals out. Auth Hub tries it first and refuses the card when the actions would fail now (in most groups a failed run marks the proposal failed for good), for example when the group doesn’t hold enough; tell the owner it can be tried again once that is fixed. It costs the owner only the network fee; a deposit paid with the proposal goes back to whoever proposed it unless the group keeps deposits (the review card says). After it goes through (hub_action_status), read the receipt’s \`groupActions\`: \`"failed"\` means the proposal’s actions did not happen and it can’t be tried again; never say it is done. \`"unknown"\`: check its status with chain_lookup dao_proposals before saying anything. Say it like: “Carry out proposal A3, ‘Pay Thandi’, in Clean Water Group: the group sends Thandi 500 IXO. This can’t be undone.”`,
     schema: z
       .strictObject({
         type: z.literal('daodao.proposal.execute'),
@@ -1374,7 +1390,7 @@ export const CHAIN_TX_CATALOG = {
 
 /** What every message type shares, returned once by describe_chain_messages. */
 export const CHAIN_TX_GENERAL_RULES = [
-  'Addresses are 20-byte `ixo1…` account addresses (contract addresses are refused), except a group’s own address and its proposal list in the group steps (32-byte `ixo1…` contract addresses); validators `ixovaloper1…`, entities `did:ixo:entity:…`. Copy every id, address and number exactly from a lookup (chain_lookup, hub_action_options) or from the owner; never invent or guess one. Ids (`claimId`, `collectionId`, token `id`, proofs) use only letters, digits and `: . _ / -`.',
+  'Addresses are 20-byte `ixo1…` account addresses, except where a type says otherwise: a coin send or impact-token transfer may go to a group’s own address, and the group steps take the group’s and its proposal list’s addresses (32-byte `ixo1…` contract addresses, 62 characters); validators `ixovaloper1…`, entities `did:ixo:entity:…`. Copy every id, address and number exactly from a lookup (chain_lookup, hub_action_options) or from the owner; never invent or guess one. Ids (`claimId`, `collectionId`, token `id`, proofs) use only letters, digits and `: . _ / -`.',
   'Give only the fields listed for a type: the runtime adds the chain, the network, the signer and the owner’s own DID and address where a message needs them, and Auth Hub sets the fee. Amounts: coin sends and stakes are what the owner says in the token’s units ("100" IXO); impact tokens are whole tokens; collection payments are base units (1 IXO = 1000000 uixo). Dates are RFC 3339 with Z or an offset, from the owner’s time zone.',
   `Up to ${CHAIN_TX_MAX_MESSAGES} messages per transaction, run in the order given (put them in the order the owner said them, and keep one decision in one card); all succeed or none do. A group step (a vote, carrying out or closing a group proposal, a new group proposal) goes alone on its card. A step that needs something stored first (a dispute statement, a profile, a document) can only be prepared once it is stored.`,
   'How to talk about it: before preparing, say in one or two plain, everyday sentences what will happen and what it means for the owner (what leaves their wallet, what someone else will be able to do, how long it takes, whether it can be undone), the way each type’s “Say it like” does. Use names (of the validator, collection, entity or person) when a lookup gives them. Never say message type names or chain words such as authz, grant, MsgExec, bech32, valoper, uixo, base units, DID, IID, delegate, redelegate, DAO, proposal module, contract or execute: say stake, unstake, move stake, permission, account, identity, IXO, group, proposal, vote, deposit and carry out. Show an address only when the owner needs it to check who receives something. The review card in Auth Hub shows every exact value.',

package/src/plugins/ixo-chain/kinds/indexed/dao-proposals.ts

@@ -278,7 +278,7 @@ export const daoProposals = defineKind({
     '`allowRevoting`: whether a vote on it can be changed until voting closes. `canRun: true`: it passed and can be carried out (on an `open` proposal whose voting ended: it may have passed); `canClose: true`: it did not pass and can be closed (on an `open` one whose voting ended: it may not have passed); Auth Hub checks the real result. `multipleChoice: true`: Auth Hub cards cannot vote on, carry out or close it. `listDisabled: true`: the group switched that proposal list off; cards can still vote and close, but a proposal with actions on it can’t be carried out (so `canRun` is not set there; one without actions can be). Whether the person may vote is weighed by what they held in the DAO when it started: Auth Hub checks it; never claim it.',
     'For cards copy `dao`, `proposalModule` and `id` exactly (not the label). `dao` is also the group’s own account (what it holds and what acts when a proposal passes).',
     'Without `dao`, the DAOs of `address` (default: the user), at most 3 per kind of membership (see `daos`); `more: true` when there are more proposals or DAOs. Newest start first.',
-    'Titles are written by the proposer and DAO names by the DAO: what they claim, never an endorsement or a verified fact.',
+    'Titles are written by whoever proposed them and group names by the group itself: their own words. Say so only when it matters, in one short, calm note.',
   ].join(' '),
   source: 'blocksync',
   list: true,

package/src/plugins/ixo-chain/kinds/indexed/daos.ts

@@ -419,8 +419,8 @@ export const daos = defineKind({
     '`membership`: `cw4-member` (a group member with a fixed `weight`), `cw20-staked` (voting power from cw20 tokens staked in the DAO, `staked.amountBaseUnits` of the `staked.token` contract) or `native-staked` (from staked bank tokens, e.g. IXO; `staked` is a bank coin, `amount` in display units beside `symbol`).',
     '`votingPowerShare` is the account’s weight or stake over the voting module’s total, rounded down; staked tokens count only while staked, and unstaking may take a waiting period.',
     'Each: dao (the DAO core contract address), name, description, membership, staked or weight, votingPowerShare, votingModule.',
-    '`addedByGroupAdmin: true` (every cw4-member row): a cw4 group’s admin can add any address to the group without its consent, so membership alone does not mean the account joined, agreed or knows of the DAO.',
-    '`nameIsSelfChosen: true`: the name and description are whatever the DAO set for itself, never a verified identity or an endorsement; say so before relying on them.',
+    '`addedByGroupAdmin: true` (every cw4-member row): members of this kind of group are added by its admin. That is normal: leave it out of an ordinary answer and never suggest the person did not join; mention it briefly only when it matters, for example when they do not recognise a group (“Members of this group are added by its admin.”).',
+    '`nameIsSelfChosen: true`: the group chose its own name and description. Mention it only when it matters (for example when they rely on the name to tell who runs the group), in one short, calm note such as “Group names are chosen by the group itself.”',
     '`dao` is also the group’s own account: what the group holds (chain_lookup balances with that address) and what acts when one of its proposals passes.',
     '`proposalLists` (at most 3; `moreProposalLists: true` past them): where the DAO takes proposals, each `proposalModule` (its address), `prefix` (the letter before proposal numbers, A in A3), `votingTime`, `allowRevoting` (whether a vote can be changed until voting closes), `membersOnly: true` (only members may propose), `membersOnlyCarryOut: true` (only members may carry out a passed proposal), and `deposit` when proposing takes one: a bank coin (`amount` beside `symbol`) or a cw20 amount with `cardCannotPay: true`, with `refundPolicy` (`only_passed`: back only if it passes and is carried out, `always`: back when carried out or closed, `never`: not back). `multipleChoice: true`: Auth Hub cards cannot use that list. `disabled: true`: the group switched it off: no new proposals through it, and its proposals with actions can’t be carried out (votes and closes still work).',
     'NFT (cw721) staking is not indexed here. Ask `dao_proposals` for what the DAOs are voting on.',