@ixo/oracle-runtime-workers 0.21.2 → 0.23.0

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

@@ -0,0 +1,67 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import {
+  stripTurnTimeNote,
+  TURN_TIME_NOTE_KWARG,
+} from '../../core/turn-time-note';
+import { contentToText } from '../../do/transcript';
+
+/** How many of the user's own messages count as evidence, and how much of each. */
+export const EVIDENCE_MESSAGES = 8;
+export const EVIDENCE_MESSAGE_CHARS = 4000;
+
+/**
+ * Words that make the latest message a question, a refusal or a thought
+ * experiment rather than a request.
+ */
+export const NEGATION =
+  /\b(don't|do not|never|not yet|what if|suppose|hypothetically)\b/i;
+
+/**
+ * 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.
+ */
+export function userEvidence(messages: readonly BaseMessage[]): string[] {
+  return messages
+    .filter((m) => m.type === 'human')
+    .slice(-EVIDENCE_MESSAGES)
+    .map((m) =>
+      contentToText(
+        stripTurnTimeNote(
+          m.content,
+          m.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
+        ),
+      ).slice(0, EVIDENCE_MESSAGE_CHARS),
+    );
+}
+
+const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+
+/**
+ * `value` written as a whole token: not inside a longer identifier, number
+ * or id (`CARBON-1` is not evidence for `CARBON-10`, nor the reverse).
+ */
+export function mentionsToken(text: string, value: string): boolean {
+  return new RegExp(`(?<![\\w.-])${escape(value)}(?![\\w.-])`).test(text);
+}
+
+/**
+ * The amount with one of its units right beside it (`1.5 IXO`, `1.5IXO`,
+ * `1500000 uixo`, `10 credits`, `10 CARBON-1`). A bare number is not
+ * evidence: `14` in a clock time, `10` inside `CARBON-10` or `10.5`, `5 uixo`
+ * for a request of 5 IXO, and the tail of a grouped or divided number
+ * (`1 500 IXO`, `1'500 IXO`, `1/5 IXO`, `1:5 IXO`) all fail here.
+ */
+export function mentionsAmount(
+  text: string,
+  amount: string,
+  units: readonly string[],
+): boolean {
+  const unit = units.map(escape).join('|');
+  // Not glued to a word character, and not preceded by a digit or a number
+  // separator with any run of whitespace in between (`1  500`, `1 ,500`).
+  return new RegExp(
+    `(?<!\\w)(?<![\\d.,'’/:-]\\s*)${escape(amount)}\\s*(?:${unit})(?![\\w-])`,
+    'i',
+  ).test(text);
+}

package/src/plugins/agui/agui.plugin.ts

@@ -98,11 +98,8 @@ export function buildActionTool(action: AgAction): PluginTool | null {
           `AG-UI action ${action.name} needs the realtime channel, which this host does not provide.`,
         );
       }
-      if (!frontend.hasClient(sessionId)) {
-        throw new Error(
-          `No browser is connected to session ${sessionId}, so AG-UI action ${action.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
-        );
-      }
+      // No browser of the session connected yet: the bridge parks the call
+      // until one joins (or its park deadline / the turn's abort ends it).
       // The bridge makes every invocation unique (`ag_<requestId>:<uuid>`).
       let invocationId: string | undefined;
       const result = await frontend.callAgAction({
@@ -112,6 +109,7 @@ export function buildActionTool(action: AgAction): PluginTool | null {
         args: parseArgs(input),
         timeoutMs: AG_ACTION_TIMEOUT_MS,
         signal: ctx.abortSignal,
+        ...(ctx.markDispatched ? { onDispatched: ctx.markDispatched } : {}),
         onInvocation: (id) => {
           invocationId = id;
         },
@@ -125,6 +123,10 @@ export function buildActionTool(action: AgAction): PluginTool | null {
       schema,
       // A UI action on the user's screen: running it again is a new action.
       repeatable: true,
+      // It runs on this session's AG-UI surface in the browser: scheduled in
+      // the session's frontend lane, so a parked call holds no slot another
+      // chat needs.
+      surface: 'frontend',
     },
   );
 }

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

@@ -0,0 +1,244 @@
+import {
+  operationJsonSchema,
+  parseOperation,
+  type ActionReferenceV1,
+} from '@ixo/action-protocol';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+
+const configSchema = z.object({
+  HUB_ACTIONS_ENABLED: z.enum(['true', 'false']).default('false'),
+});
+
+const operationSchema = z.fromJSONSchema({
+  ...operationJsonSchema,
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+});
+const requestSchema = z.strictObject({ operation: operationSchema });
+const statusSchema = z.strictObject({
+  actionId: z.string().regex(/^[A-Za-z0-9_-]{32}$/),
+});
+const discoverSchema = z.strictObject({});
+
+export type HubActionRequestResult =
+  | { status: 'prepared'; actionReference: ActionReferenceV1; summary: string }
+  | {
+      status: 'unavailable' | 'expired';
+      reason: string;
+      /** The earlier action that blocks this one (an unconfirmed email). */
+      priorActionId?: string;
+    };
+
+/**
+ * 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).
+ */
+async function hubRequestKey(runId: string, toolCallId: string) {
+  const bytes = new Uint8Array(
+    await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(`${runId}:${toolCallId}`),
+    ),
+  );
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function requestHubAction(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<HubActionRequestResult> {
+  const parsed = requestSchema.safeParse(input);
+  if (!parsed.success)
+    return { status: 'unavailable', reason: 'An operation is 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.',
+    };
+  let operation;
+  try {
+    operation = parseOperation(parsed.data.operation);
+  } catch (error) {
+    // The protocol's own words ("Invalid fromAddress"): the model can fix
+    // the field instead of guessing.
+    return {
+      status: 'unavailable',
+      reason: `The requested operation is unsupported or incomplete${error instanceof Error && error.message ? ` (${error.message})` : ''}.`,
+    };
+  }
+  let reference: ActionReferenceV1;
+  try {
+    reference = await ctx.hubActions.request({
+      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),
+      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.
+    // 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 }
+          : {}),
+      };
+    throw error;
+  }
+  return {
+    status: 'prepared',
+    actionReference: reference,
+    summary: reference.title,
+  };
+}
+
+async function hubActionStatus(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<unknown> {
+  const parsed = statusSchema.safeParse(input);
+  if (
+    !parsed.success ||
+    !ctx.hubActions ||
+    ctx.config.HUB_ACTIONS_ENABLED !== 'true'
+  )
+    return { status: 'unavailable' };
+  return {
+    status: 'known',
+    outcome: await ctx.hubActions.status(ctx.user.did, parsed.data.actionId),
+  };
+}
+
+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' };
+  return ctx.hubActions.capabilities();
+}
+
+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' };
+  return ctx.hubActions.options({
+    ownerDid: ctx.user.did,
+    provider: channel.provider,
+    bindingId: channel.bindingId,
+    bindingRevision: channel.bindingRevision,
+  });
+}
+
+const manifest: PluginManifest = {
+  title: 'Auth Hub action review',
+  summary:
+    'Prepare a registered operation for owner review and read its verified status.',
+  whenToUse: [
+    'The user requests a registered form submission or a transfer.',
+    'The user asks to review an exact private resource or to sign a statement.',
+    'The user asks to connect Gmail or Calendar, send a reviewed email or add an event.',
+    'The user asks for document access or to save a private note.',
+  ],
+  whenNotToUse: [
+    'Signing, executing, or treating a resource open as acceptance.',
+  ],
+  tags: ['actions', 'channels'],
+  category: 'integration',
+  visibility: 'on-demand',
+  stability: 'experimental',
+};
+
+export class HubActionsPlugin extends OraclePlugin {
+  readonly name = 'hub-actions';
+  readonly version = '0.1.0';
+  readonly manifest = manifest;
+  override readonly configSchema = configSchema;
+  /** The flag alone is not enough: the owner object needs the Hub's URL and this oracle's key. */
+  override autoDetect(env: Record<string, unknown>): boolean {
+    return (
+      env.HUB_ACTIONS_ENABLED === 'true' &&
+      typeof env.AUTH_HUB_URL === 'string' &&
+      env.AUTH_HUB_URL.length > 0 &&
+      typeof env.AUTH_HUB_CHANNEL_SERVICE_KEY === 'string' &&
+      env.AUTH_HUB_CHANNEL_SERVICE_KEY.length > 0
+    );
+  }
+  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 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.',
+        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. Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again.',
+        schema: requestSchema,
+        effect: 'write',
+        handler: requestHubAction,
+      },
+      {
+        name: 'hub_action_status',
+        description:
+          'Read the verified status of a Hub action already prepared for this owner. Never executes.',
+        schema: statusSchema,
+        effect: 'read',
+        handler: hubActionStatus,
+      },
+    ];
+  }
+}

package/src/plugins/index.ts

@@ -1,3 +1,7 @@
+import { ActionProposalsPlugin } from './action-proposals/action-proposals.plugin';
+import { HubActionsPlugin } from './hub-actions/hub-actions.plugin';
+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
@@ -66,6 +70,8 @@ export const tasksPlugin = TasksPlugin;
  * instances instead of using these singletons.
  */
 export const BUNDLED_WORKERS_PLUGINS = [
+  new ActionProposalsPlugin(),
+  new HubActionsPlugin(),
   memoryPlugin,
   sandboxPlugin,
   firecrawlPlugin,

package/src/plugins/ixo-transaction/wallet-signing.ts

@@ -65,7 +65,10 @@ type WalletChannel =
 
 /**
  * The turn's way to the wallet: a session with a realtime channel and a
- * Portal browser connected to it.
+ * Portal tab that can run the action right now (`canDispatch`: a foreground
+ * socket; a background executor never runs an AG-UI action). A signing
+ * request is never parked: without such a tab it is refused at once, so it
+ * never waits minutes in the user-wide write lane for a tab to open.
  */
 function walletChannel(ctx: RuntimeContext): WalletChannel {
   const sessionId = ctx.session.id;
@@ -77,7 +80,7 @@ function walletChannel(ctx: RuntimeContext): WalletChannel {
         'Wallet signing needs a Portal session with a realtime connection, which this conversation does not have.',
     };
   }
-  if (!frontend.hasClient(sessionId)) {
+  if (!frontend.canDispatch(sessionId, 'agui', SIGN_TRANSACTION_ACTION_NAME)) {
     return {
       ok: false,
       reason:

package/src/plugins/portal/declared-tools.ts

@@ -25,6 +25,18 @@ export interface DeclaredTool {
   schema: Record<string, unknown>;
 }
 
+/**
+ * The effect a client declares for one of its tools (`effect` on a browser
+ * tool declaration): exactly `'read'` or `'write'`. Any other value is
+ * treated as no declaration — the entry itself is kept, and the runtime's
+ * own classification applies.
+ */
+export function declaredToolEffect(
+  value: unknown,
+): 'read' | 'write' | undefined {
+  return value === 'read' || value === 'write' ? value : undefined;
+}
+
 export interface DroppedDeclaration {
   name: string;
   reason: string;

package/src/plugins/portal/portal.plugin.ts

@@ -24,7 +24,11 @@ import type {
   RuntimeContext,
 } from '../../plugin-api/types';
 import { logFrontendAction } from './action-log';
-import { describeDropped, sanitizeDeclaredTools } from './declared-tools';
+import {
+  declaredToolEffect,
+  describeDropped,
+  sanitizeDeclaredTools,
+} from './declared-tools';
 
 const manifest: PluginManifest = {
   title: 'Portal',
@@ -79,6 +83,7 @@ const BROWSER_TOOL_SHAPE = z.object({
   name: z.string(),
   description: z.string(),
   schema: z.record(z.string(), z.unknown()),
+  effect: z.unknown().optional(),
 });
 
 const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
@@ -92,7 +97,9 @@ export function parseBrowserTools(value: unknown): BrowserToolCall[] {
     const parsed = BROWSER_TOOL_SHAPE.safeParse(entry);
     if (!parsed.success || names.has(parsed.data.name)) continue;
     names.add(parsed.data.name);
-    out.push(parsed.data);
+    const { effect: rawEffect, ...declaration } = parsed.data;
+    const effect = declaredToolEffect(rawEffect);
+    out.push(effect ? { ...declaration, effect } : declaration);
   }
   return out;
 }
@@ -170,11 +177,8 @@ export function buildBrowserTool(
           `Browser tool ${descriptor.name} needs the realtime channel, which this host does not provide.`,
         );
       }
-      if (!frontend.hasClient(sessionId)) {
-        throw new Error(
-          `No browser is connected to session ${sessionId}, so browser tool ${descriptor.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
-        );
-      }
+      // No browser of the session connected yet: the bridge parks the call
+      // until one joins (or its park deadline / the turn's abort ends it).
       const args = withRuntimeSuppliedArgs(
         parseArgs(input),
         descriptor,
@@ -189,6 +193,7 @@ export function buildBrowserTool(
         args,
         timeoutMs: browserToolTimeoutMs(descriptor.name),
         signal: ctx.abortSignal,
+        ...(ctx.markDispatched ? { onDispatched: ctx.markDispatched } : {}),
         onInvocation: (id) => {
           invocationId = id;
         },
@@ -202,9 +207,18 @@ export function buildBrowserTool(
       schema,
       // A browser step (scroll, page, click) repeated is a new step.
       repeatable: !HUMAN_DECISION_TOOLS.has(descriptor.name),
+      // It runs in this session's browser tab: scheduled in the session's
+      // frontend lane, so a parked call (or a question to the user) holds
+      // no slot another chat needs.
+      surface: 'frontend',
+      // A question to the user is a write whatever the client declares:
+      // it is never asked twice after a restart once it was sent. Any
+      // other tool keeps the effect its declaration names, if any.
       ...(HUMAN_DECISION_TOOLS.has(descriptor.name)
         ? { effect: 'write' as const }
-        : {}),
+        : descriptor.effect
+          ? { effect: descriptor.effect }
+          : {}),
     },
   );
 }