@ixo/oracle-runtime-workers 0.24.0 → 0.26.0

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

@@ -19,6 +19,10 @@ import {
   MEMORY_DELETE_EDGE_MCP_NAME,
   MEMORY_DELETE_EPISODE_MCP_NAME,
 } from '../plugins/memory/memory-tools';
+import {
+  ADD_ORACLE_DOCUMENT_TOOL_NAME,
+  DELETE_ORACLE_DOCUMENT_TOOL_NAME,
+} from '../plugins/memory/oracle-document-tools';
 
 /** The memory engine tools that write or delete what the prefetch reads. */
 export const MEMORY_WRITE_TOOL_NAMES: readonly string[] = [
@@ -27,6 +31,8 @@ export const MEMORY_WRITE_TOOL_NAMES: readonly string[] = [
   MEMORY_DELETE_EPISODE_MCP_NAME,
   MEMORY_DELETE_EDGE_MCP_NAME,
   MEMORY_CLEAR_MCP_NAME,
+  ADD_ORACLE_DOCUMENT_TOOL_NAME,
+  DELETE_ORACLE_DOCUMENT_TOOL_NAME,
 ];
 
 export interface UserContextInvalidationOptions {

package/src/plugin-api/types.ts

@@ -762,7 +762,26 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       provider: string;
       bindingId: string;
       bindingRevision: number;
-    }): Promise<import('@ixo/action-protocol').HubActionOptionsV2>;
+    }): Promise<import('@ixo/action-protocol').HubActionOptionsV3>;
+    /**
+     * A bank send of a token from the owner's options list: `amount` is a
+     * decimal in the token's display units; the host converts it to base
+     * units from the listed decimals and builds the operation (no fee).
+     */
+    transfer(input: {
+      ownerDid: string;
+      sessionId: string;
+      runId: string;
+      requestId: string;
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+      requestKey: string;
+      toAddress: string;
+      denom: string;
+      amount: string;
+      memo: string;
+    }): Promise<ActionReferenceV1>;
     request(input: {
       ownerDid: string;
       sessionId: string;
@@ -774,7 +793,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       requestKey: string;
       operation: ActionOperationV1;
     }): Promise<ActionReferenceV1>;
-    status(ownerDid: string, actionId: string): Promise<ActionOutcomeV1 | null>;
+    /** The latest authenticated outcome and, for a transfer, its owner-facing line. */
+    status(
+      ownerDid: string,
+      actionId: string,
+    ): Promise<{ outcome: ActionOutcomeV1 | null; summary: string | null }>;
   };
 
   decisions: {

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

@@ -24,9 +24,37 @@ const statusSchema = z.strictObject({
   actionId: z.string().regex(/^[A-Za-z0-9_-]{32}$/),
 });
 const discoverSchema = z.strictObject({});
+const transferSchema = z.strictObject({
+  toAddress: z
+    .string()
+    .min(1)
+    .max(100)
+    .describe('The recipient address the user gave, exactly.'),
+  denom: z
+    .string()
+    .min(1)
+    .max(128)
+    .describe(
+      'The token, copied exactly from a `denom` in hub_action_options `transfer.tokens` (never guessed).',
+    ),
+  amount: z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)(\.[0-9]+)?$/)
+    .max(80)
+    .describe(
+      "A decimal amount in the token's listed units (its `decimals`); for an unverified token (decimals 0) a whole number of base units.",
+    ),
+  memo: z.string().max(256).optional(),
+});
 
 export type HubActionRequestResult =
-  | { status: 'prepared'; actionReference: ActionReferenceV1; summary: string }
+  | {
+      status: 'prepared';
+      actionReference: ActionReferenceV1;
+      summary: string;
+      /** How the review reaches the user; set on a chat surface only. */
+      note?: string;
+    }
   | {
       status: 'unavailable' | 'expired';
       reason: string;
@@ -34,6 +62,34 @@ export type HubActionRequestResult =
       priorActionId?: string;
     };
 
+/**
+ * What a prepared result tells the model on a chat surface. There the
+ * finished run's Reply Plan carries the review as its own `hub-action` part
+ * (a card with the title and a review button; its title linked to the review
+ * in a plain-text rendering), so text that repeats it reaches the user twice.
+ */
+export const HUB_ACTION_CARD_NOTE =
+  'The user is shown this action automatically as a card with its title and a Review action button that opens it in Auth Hub. Do not repeat the link or the title, and do not say that you have not executed or signed anything. Reply with one short line, or nothing.';
+
+/**
+ * A prepared result. Only a chat turn's reply is a Reply Plan, so only a
+ * chat surface gets the note: on the Portal stream no card is added and the
+ * model's own text is the whole reply.
+ */
+function preparedResult(
+  reference: ActionReferenceV1,
+  ctx: RuntimeContext,
+): HubActionRequestResult {
+  return {
+    status: 'prepared',
+    actionReference: reference,
+    summary: reference.title,
+    ...(ctx.session.surface?.kind === 'chat'
+      ? { note: HUB_ACTION_CARD_NOTE }
+      : {}),
+  };
+}
+
 /**
  * The idempotency key the Hub sees: a fixed-length digest of the run and
  * tool call (the Hub allows 120 characters; a run id alone is 72).
@@ -74,6 +130,15 @@ async function requestHubAction(
   let operation;
   try {
     operation = parseOperation(parsed.data.operation);
+    if (operation.kind === 'ixo.bank.send.v1')
+      // A transfer is built by the runtime from a listed token and a
+      // display amount (request_hub_transfer): the model never supplies
+      // base units, a denom it chose or a fee.
+      return {
+        status: 'unavailable',
+        reason:
+          'Use request_hub_transfer with a token from hub_action_options for a transfer.',
+      };
   } catch (error) {
     // The protocol's own words ("Invalid fromAddress"): the model can fix
     // the field instead of guessing.
@@ -96,28 +161,83 @@ async function requestHubAction(
       operation,
     });
   } catch (error) {
-    // A cap reached, a request that expired, a run no user message
-    // started: the runtime's own words, so the model can tell the user.
+    // A request that expired, a run no user message started, a Hub
+    // refusal: the runtime's own words, so the model can tell the user.
     // Anything else stays an error.
-    if (
-      error instanceof Error &&
-      error.name === 'HubActionRefused' &&
-      'kind' in error
-    )
-      return {
-        status: error.kind === 'expired' ? 'expired' : 'unavailable',
-        reason: error.message,
-        ...('priorActionId' in error && typeof error.priorActionId === 'string'
-          ? { priorActionId: error.priorActionId }
-          : {}),
-      };
+    const refused = refusalOf(error);
+    if (refused) return refused;
     throw error;
   }
-  return {
-    status: 'prepared',
-    actionReference: reference,
-    summary: reference.title,
-  };
+  return preparedResult(reference, ctx);
+}
+
+async function requestHubTransfer(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<HubActionRequestResult> {
+  const parsed = transferSchema.safeParse(input);
+  if (!parsed.success)
+    return {
+      status: 'unavailable',
+      reason:
+        'A recipient, a listed token denom and a plain decimal amount are required.',
+    };
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      status: 'unavailable',
+      reason: 'Hub actions are not enabled for this oracle.',
+    };
+  const channel = ctx.session.channel;
+  if (
+    ctx.session.client !== 'channel' ||
+    !channel ||
+    !ctx.session.runId ||
+    !ctx.toolCallId
+  )
+    return {
+      status: 'unavailable',
+      reason: 'A verified channel turn is required.',
+    };
+  try {
+    const reference = await ctx.hubActions.transfer({
+      ownerDid: ctx.user.did,
+      sessionId: ctx.session.id,
+      runId: ctx.session.runId,
+      requestId: ctx.session.requestId,
+      provider: channel.provider,
+      bindingId: channel.bindingId,
+      bindingRevision: channel.bindingRevision,
+      requestKey: await hubRequestKey(ctx.session.runId, ctx.toolCallId),
+      toAddress: parsed.data.toAddress,
+      denom: parsed.data.denom,
+      amount: parsed.data.amount,
+      memo: parsed.data.memo ?? '',
+    });
+    return preparedResult(reference, ctx);
+  } catch (error) {
+    // The owner object turns the protocol refusing the operation built
+    // from the model's fields into a refusal; anything else is an error.
+    const refused = refusalOf(error);
+    if (refused) return refused;
+    throw error;
+  }
+}
+
+/** A typed runtime refusal as a result the model can relay, else null. */
+function refusalOf(error: unknown): HubActionRequestResult | null {
+  if (
+    error instanceof Error &&
+    error.name === 'HubActionRefused' &&
+    'kind' in error
+  )
+    return {
+      status: error.kind === 'expired' ? 'expired' : 'unavailable',
+      reason: error.message,
+      ...('priorActionId' in error && typeof error.priorActionId === 'string'
+        ? { priorActionId: error.priorActionId }
+        : {}),
+    };
+  return null;
 }
 
 async function hubActionStatus(
@@ -131,10 +251,11 @@ async function hubActionStatus(
     ctx.config.HUB_ACTIONS_ENABLED !== 'true'
   )
     return { status: 'unavailable' };
-  return {
-    status: 'known',
-    outcome: await ctx.hubActions.status(ctx.user.did, parsed.data.actionId),
-  };
+  const { outcome, summary } = await ctx.hubActions.status(
+    ctx.user.did,
+    parsed.data.actionId,
+  );
+  return { status: 'known', outcome, ...(summary ? { summary } : {}) };
 }
 
 async function hubActionCapabilities(
@@ -218,7 +339,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_options',
         description:
-          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents and action resources. Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending.',
+          '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.',
         schema: discoverSchema,
         effect: 'read',
         handler: hubActionOptions,
@@ -231,6 +352,14 @@ export class HubActionsPlugin extends OraclePlugin {
         effect: 'write',
         handler: requestHubAction,
       },
+      {
+        name: 'request_hub_transfer',
+        description:
+          'Prepare a bank transfer of one of the owner’s listed tokens for review in Auth Hub. Never signs or executes. Read hub_action_options first and copy the token `denom` exactly; give the amount as the user said it in that token’s units (no base-unit math, no fee: Auth Hub sets the fee). Name the full denom for anything but IXO, and say when a token is unverified.',
+        schema: transferSchema,
+        effect: 'write',
+        handler: requestHubTransfer,
+      },
       {
         name: 'hub_action_status',
         description:

package/src/plugins/memory/document-chunker.ts

@@ -0,0 +1,313 @@
+/**
+ * Splits extracted document text into chunks the Memory Engine accepts: every
+ * chunk is at most `maxChunkBytes` UTF-8 bytes, cut at the largest natural
+ * boundary that fits (paragraph, line, sentence) and only then mid-text, never
+ * inside a UTF-8 sequence or surrogate pair.
+ */
+
+export interface ChunkerOptions {
+  /** Upper bound of one chunk in UTF-8 bytes (default 12 000). */
+  maxChunkBytes: number;
+  /** Most chunks to return (default 64). */
+  maxChunks: number;
+}
+
+export interface DocumentChunk {
+  /** Zero-based position in the document. */
+  index: number;
+  /** `p. 3`, `p. 3–5` when the text carries page markers, else `part 2 of 7`. */
+  label: string;
+  content: string;
+}
+
+export interface ChunkedDocument {
+  chunks: DocumentChunk[];
+  /** More chunks were needed than `maxChunks`; only the first ones are returned. */
+  truncated: boolean;
+  /** UTF-8 size of the normalised text. */
+  totalBytes: number;
+}
+
+export const DEFAULT_CHUNK_BYTES = 12_000;
+export const DEFAULT_MAX_CHUNKS = 64;
+
+const MIN_CHUNK_BYTES = 4;
+/** A whole line that only names a page: `--- page 3 ---`, `Page 3`, `p. 3`, `Page 3 of 10`. */
+const PAGE_MARKER =
+  /^\s*(?:---\s*page\s+(\d+)\s*---|(?:page|p\.)\s*(\d+)(?:\s*(?:of|\/)\s*\d+)?)\s*$/i;
+
+/** UTF-8 length of a string, counting a lone surrogate as U+FFFD (3 bytes). */
+export function utf8ByteLength(text: string): number {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+interface Paragraph {
+  text: string;
+  page: number | undefined;
+}
+
+interface Unit {
+  text: string;
+  /** What joins this unit to the previous one inside a chunk. */
+  sep: string;
+  page: number | undefined;
+}
+
+/** Drops trailing spaces and tabs in one backwards pass (no regex backtracking; a form feed stays). */
+function trimLineEnd(line: string): string {
+  let end = line.length;
+  while (end > 0 && (line[end - 1] === ' ' || line[end - 1] === '\t')) end -= 1;
+  return end === line.length ? line : line.slice(0, end);
+}
+
+function normalise(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(trimLineEnd)
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function isMarkerOnly(text: string): boolean {
+  return !text.includes('\n') && PAGE_MARKER.test(text);
+}
+
+function groupText(group: readonly Unit[]): string {
+  return group.reduce(
+    (acc, u, i) => (i === 0 ? u.text : acc + u.sep + u.text),
+    '',
+  );
+}
+
+/**
+ * A group that only names pages (`--- page 4 ---`) says nothing: it joins the
+ * start of the next group, else the end of the previous one, if it fits, and
+ * is dropped otherwise (the page of every unit is already known).
+ */
+function absorbMarkerGroups(groups: Unit[][], maxBytes: number): Unit[][] {
+  const out: Unit[][] = [];
+  let carry: Unit[] = [];
+  for (const group of groups) {
+    if (group.every((u) => isMarkerOnly(u.text))) {
+      carry = [...carry, ...group];
+      continue;
+    }
+    if (
+      carry.length > 0 &&
+      utf8ByteLength(groupText([...carry, ...group])) <= maxBytes
+    ) {
+      out.push([...carry, ...group]);
+    } else {
+      const last = out[out.length - 1];
+      if (
+        carry.length > 0 &&
+        last &&
+        utf8ByteLength(groupText([...last, ...carry])) <= maxBytes
+      ) {
+        last.push(...carry);
+      }
+      out.push(group);
+    }
+    carry = [];
+  }
+  const last = out[out.length - 1];
+  if (
+    carry.length > 0 &&
+    last &&
+    utf8ByteLength(groupText([...last, ...carry])) <= maxBytes
+  ) {
+    last.push(...carry);
+  }
+  return out;
+}
+
+/** Paragraphs in order, each tagged with the page it starts on (if paged). */
+function splitParagraphs(text: string): {
+  paragraphs: Paragraph[];
+  paged: boolean;
+} {
+  const lines = text.replace(/\f/g, '\n\f\n').split('\n');
+  const paged =
+    text.includes('\f') || lines.some((line) => PAGE_MARKER.test(line));
+  const paragraphs: Paragraph[] = [];
+  let page: number | undefined = paged ? 1 : undefined;
+  let current: string[] = [];
+  let currentPage = page;
+
+  const flush = (): void => {
+    const joined = current.join('\n').trim();
+    if (joined) paragraphs.push({ text: joined, page: currentPage });
+    current = [];
+  };
+
+  for (const line of lines) {
+    if (line === '\f') {
+      flush();
+      page = (page ?? 1) + 1;
+      continue;
+    }
+    if (line.trim() === '') {
+      flush();
+      continue;
+    }
+    const marker = PAGE_MARKER.exec(line);
+    if (marker) {
+      flush();
+      page = Number(marker[1] ?? marker[2]);
+    }
+    if (current.length === 0) currentPage = page;
+    current.push(line);
+  }
+  flush();
+  return { paragraphs, paged };
+}
+
+interface Level {
+  sep: string;
+  split: (text: string) => string[];
+}
+
+/** Boundaries tried in order when a piece is still too large. */
+const LEVELS: readonly Level[] = [
+  {
+    sep: '\n',
+    split: (t) =>
+      t
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean),
+  },
+  {
+    sep: ' ',
+    split: (t) =>
+      t
+        .split(/(?<=[.!?。！？])\s+/u)
+        .map((s) => s.trim())
+        .filter(Boolean),
+  },
+];
+
+function hardSplit(text: string, maxBytes: number): string[] {
+  const pieces: string[] = [];
+  let start = 0;
+  let bytes = 0;
+  let i = 0;
+  while (i < text.length) {
+    const code = text.codePointAt(i) ?? 0;
+    const width = code > 0xffff ? 2 : 1;
+    const size = utf8ByteLength(text.slice(i, i + width));
+    if (bytes + size > maxBytes) {
+      pieces.push(text.slice(start, i));
+      start = i;
+      bytes = 0;
+    }
+    bytes += size;
+    i += width;
+  }
+  if (start < text.length) pieces.push(text.slice(start));
+  return pieces;
+}
+
+function fit(
+  text: string,
+  sep: string,
+  levels: readonly Level[],
+  maxBytes: number,
+  page: number | undefined,
+): Unit[] {
+  if (utf8ByteLength(text) <= maxBytes) return [{ text, sep, page }];
+  const [level, ...rest] = levels;
+  if (!level) {
+    return hardSplit(text, maxBytes).map((piece, i) => ({
+      text: piece,
+      sep: i === 0 ? sep : '',
+      page,
+    }));
+  }
+  const parts = level.split(text);
+  if (parts.length <= 1) return fit(text, sep, rest, maxBytes, page);
+  return parts.flatMap((part, i) =>
+    fit(part, i === 0 ? sep : level.sep, rest, maxBytes, page),
+  );
+}
+
+function pageLabel(first: number, last: number): string {
+  return first === last ? `p. ${first}` : `p. ${first}–${last}`;
+}
+
+export function chunkDocument(
+  text: string,
+  opts: Partial<ChunkerOptions> = {},
+): ChunkedDocument {
+  const maxChunkBytes = opts.maxChunkBytes ?? DEFAULT_CHUNK_BYTES;
+  const maxChunks = opts.maxChunks ?? DEFAULT_MAX_CHUNKS;
+  if (!Number.isInteger(maxChunkBytes) || maxChunkBytes < MIN_CHUNK_BYTES) {
+    throw new RangeError(
+      `maxChunkBytes must be an integer >= ${MIN_CHUNK_BYTES}`,
+    );
+  }
+  if (!Number.isInteger(maxChunks) || maxChunks < 1) {
+    throw new RangeError('maxChunks must be a positive integer');
+  }
+
+  const normalised = normalise(text);
+  if (!normalised) return { chunks: [], truncated: false, totalBytes: 0 };
+
+  const { paragraphs, paged } = splitParagraphs(normalised);
+  const units = paragraphs
+    .flatMap((p) => fit(p.text, '\n\n', LEVELS, maxChunkBytes, p.page))
+    .filter((u) => u.text.trim() !== '');
+
+  const groups: Unit[][] = [];
+  let group: Unit[] = [];
+  let groupBytes = 0;
+  for (const unit of units) {
+    const unitBytes = utf8ByteLength(unit.text);
+    // Separators are ASCII, so their length is their byte length.
+    const joined = groupBytes + unit.sep.length + unitBytes;
+    if (group.length > 0 && joined <= maxChunkBytes) {
+      group.push(unit);
+      groupBytes = joined;
+    } else {
+      if (group.length > 0) groups.push(group);
+      group = [unit];
+      groupBytes = unitBytes;
+    }
+  }
+  if (group.length > 0) groups.push(group);
+
+  const kept = absorbMarkerGroups(groups, maxChunkBytes);
+  const total = kept.length;
+  const chunks = kept.slice(0, maxChunks).map((members, index) => {
+    const body = groupText(members);
+    const pages = members
+      .map((u) => u.page)
+      .filter((p): p is number => p !== undefined);
+    const label =
+      paged && pages.length > 0
+        ? pageLabel(Math.min(...pages), Math.max(...pages))
+        : `part ${index + 1} of ${total}`;
+    return { index, label, content: body };
+  });
+
+  return {
+    chunks,
+    truncated: total > maxChunks,
+    totalBytes: utf8ByteLength(normalised),
+  };
+}