@ixo/oracle-runtime-workers 0.22.0 → 0.23.0

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/shell/app.ts

@@ -1,3 +1,15 @@
+import {
+  ActionProposalWireSchema,
+  TopicReceiptReferencesSchema,
+  BeginTopicStepSchema,
+  BeginTopicStepResultSchema,
+} from '@ixo/ixo-transaction/topic-proposals';
+import {
+  ActionProposalClaimSchema,
+  ActionProposalIdSchema,
+  ActionProposalReconcileSchema,
+} from '@ixo/ixo-transaction/action-proposals';
+import { ActionProposalConflict } from '../action-proposals/store';
 import {
   authenticateChannel,
   assertActiveChannelBindingCached,
@@ -65,6 +77,23 @@ import {
   type FeedbackShellOptions,
 } from '../feedback/submit';
 import { z } from 'zod';
+import { parseOutcome } from '@ixo/action-protocol';
+
+async function equalOutcomeKeys(
+  provided: string | null,
+  expected: string | undefined,
+): Promise<boolean> {
+  if (!provided || !expected || expected.length < 32 || provided.length > 512)
+    return false;
+  const digest = async (value: string) =>
+    new Uint8Array(
+      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)),
+    );
+  const [a, b] = await Promise.all([digest(provided), digest(expected)]);
+  let difference = 0;
+  for (let i = 0; i < a.length; i++) difference |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return difference === 0;
+}
 
 const DebugEventBody = z.object({
   type: z
@@ -217,6 +246,7 @@ export function rateLimitKey(
     | 'user'
     | 'poll'
     | 'channel'
+    | 'action'
     | 'artifact'
     | 'socket'
     | 'status'
@@ -424,6 +454,38 @@ export function createShell(
     );
   });
 
+  app.use('/api/internal/actions/outcomes', limitBody(64 * 1024));
+  app.post('/api/internal/actions/outcomes', async (c) => {
+    if (
+      c.env.HUB_ACTIONS_ENABLED !== 'true' ||
+      !(await equalOutcomeKeys(
+        c.req.header('x-auth-hub-outcome-key') ?? null,
+        c.env.AUTH_HUB_ACTION_OUTCOME_KEY,
+      ))
+    )
+      return c.json({ code: 'unauthorized' }, 401);
+    const body = await c.req.raw.text();
+    if (body.length > 64_000) return c.json({ code: 'request_too_large' }, 413);
+    try {
+      const outcome = parseOutcome(JSON.parse(body));
+      await userStub(c.env, outcome.ownerDid).recordHubActionOutcome(outcome);
+      return c.json({
+        accepted: true,
+        eventId: outcome.eventId,
+        accountId: outcome.reference.accountId,
+        actionId: outcome.reference.id,
+        revision: outcome.authorizedRevision,
+        digest: outcome.authorizedDigest,
+        sequence: outcome.sequence,
+      });
+    } catch (error) {
+      console.warn(
+        `[hub-actions] outcome refused: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return c.json({ code: 'outcome_refused' }, 409);
+    }
+  });
+
   app.post('/channels/turn', async (c) => {
     try {
       if (parseChannelServiceDids(c.env.CHANNEL_SERVICE_DID).length === 0)
@@ -478,6 +540,8 @@ export function createShell(
           outcome.status,
         );
       const result = outcome.result;
+      if (result.actionOutcomes?.length || result.hubActionOutcomes?.length)
+        await assertActiveChannelBindingCached(identity, c.env);
       return c.json(
         result,
         ['queued', 'running', 'recovering'].includes(result.status) ? 202 : 200,
@@ -538,8 +602,15 @@ export function createShell(
     if (!limiter) return next();
     const auth = c.get('auth') as AuthResult | undefined;
     if (!auth) return next();
+    // The chat lists' status poll and the card routes (Portal's review
+    // page) each have their own bucket: polling a card or the run list
+    // while chatting must not push turns into 429.
     const scope =
-      c.req.method === 'GET' && c.req.path === '/runs/active' ? 'poll' : 'user';
+      c.req.method === 'GET' && c.req.path === '/runs/active'
+        ? 'poll'
+        : c.req.path.startsWith('/action-proposals/')
+          ? 'action'
+          : 'user';
     const { success } = await limiter.limit({
       key: rateLimitKey(c.env, scope, auth.userDid),
     });
@@ -555,6 +626,129 @@ export function createShell(
     return next();
   });
 
+  // What the owner object answers a proposal command with: the card; a
+  // conflict (the card or the authority it was sealed on changed: the Portal
+  // re-reads and retries, 409); or an authority read that failed and may
+  // succeed later (503, with a generic message).
+  const ProposalReply = z.discriminatedUnion('ok', [
+    z.object({ ok: z.literal(true), proposal: ActionProposalWireSchema }),
+    z.object({
+      ok: z.literal(false),
+      error: z.string(),
+      kind: z.enum(['conflict', 'unavailable']).default('conflict'),
+    }),
+  ]);
+  const refusalStatus = (kind: 'conflict' | 'unavailable') =>
+    kind === 'unavailable' ? 503 : 409;
+
+  app.get('/action-proposals/:proposalId', async (c) => {
+    c.header('Cache-Control', 'private, no-store');
+    c.header('Vary', 'Authorization');
+    const parsed = ActionProposalIdSchema.safeParse(c.req.param('proposalId'));
+    if (!parsed.success) return c.json({ error: 'Invalid proposal ID' }, 400);
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const proposal = await userStub(c.env, identity.userDid).actionProposal(
+      identity,
+      parsed.data,
+    );
+    if (!proposal) return c.json({ error: 'Proposal not found' }, 404);
+    const result = ProposalReply.parse(JSON.parse(proposal));
+    return result.ok
+      ? c.json({ proposal: result.proposal })
+      : c.json({ error: result.error }, refusalStatus(result.kind));
+  });
+  for (const operation of ['claim', 'reject', 'revoke', 'reconcile'] as const) {
+    app.post(
+      `/action-proposals/:proposalId/${operation}`,
+      limitBody(4096),
+      async (c) => {
+        c.header('Cache-Control', 'private, no-store');
+        c.header('Vary', 'Authorization');
+        const id = ActionProposalIdSchema.safeParse(c.req.param('proposalId'));
+        const body = await c.req.json().catch(() => null);
+        const parsed = (
+          operation === 'reconcile'
+            ? z.union([
+                ActionProposalReconcileSchema,
+                TopicReceiptReferencesSchema,
+              ])
+            : ActionProposalClaimSchema
+        ).safeParse(body);
+        if (!id.success || !parsed.success)
+          return c.json({ error: 'Invalid proposal command' }, 400);
+        const identity = identityOf(c.get('auth'), c.req.raw.headers);
+        try {
+          const command =
+            operation === 'reconcile'
+              ? 'v' in parsed.data
+                ? {
+                    kind: 'topic-reconcile' as const,
+                    input: TopicReceiptReferencesSchema.parse(parsed.data),
+                  }
+                : {
+                    kind: operation,
+                    ...ActionProposalReconcileSchema.parse(parsed.data),
+                  }
+              : {
+                  kind: operation,
+                  ...ActionProposalClaimSchema.parse(parsed.data),
+                };
+          const proposal = await userStub(
+            c.env,
+            identity.userDid,
+          ).actionProposal(identity, id.data, command);
+          if (!proposal) return c.json({ error: 'Proposal not found' }, 404);
+          const result = ProposalReply.parse(JSON.parse(proposal));
+          return result.ok
+            ? c.json({ proposal: result.proposal })
+            : c.json({ error: result.error }, refusalStatus(result.kind));
+        } catch (error) {
+          if (
+            error instanceof ActionProposalConflict ||
+            (error instanceof Error && error.name === 'ActionProposalConflict')
+          )
+            return c.json({ error: error.message }, 409);
+          throw error;
+        }
+      },
+    );
+  }
+
+  app.post(
+    '/action-proposals/:proposalId/begin-step',
+    limitBody(4096),
+    async (c) => {
+      c.header('Cache-Control', 'private, no-store');
+      c.header('Vary', 'Authorization');
+      const id = ActionProposalIdSchema.safeParse(c.req.param('proposalId'));
+      const body = BeginTopicStepSchema.safeParse(
+        await c.req.json().catch(() => null),
+      );
+      if (!id.success || !body.success)
+        return c.json({ error: 'Invalid topic step command' }, 400);
+      const identity = identityOf(c.get('auth'), c.req.raw.headers);
+      const raw = await userStub(c.env, identity.userDid).beginTopicStep(
+        identity,
+        id.data,
+        body.data,
+      );
+      if (!raw) return c.json({ error: 'Proposal not found' }, 404);
+      const response = z
+        .discriminatedUnion('ok', [
+          z.object({ ok: z.literal(true), result: BeginTopicStepResultSchema }),
+          z.object({
+            ok: z.literal(false),
+            error: z.string(),
+            kind: z.enum(['conflict', 'unavailable']).default('conflict'),
+          }),
+        ])
+        .parse(JSON.parse(raw));
+      return response.ok
+        ? c.json(response.result)
+        : c.json({ error: response.error }, refusalStatus(response.kind));
+    },
+  );
+
   // --- sessions ----------------------------------------------------------------
   app.post('/sessions', async (c) => {
     const identity = identityOf(c.get('auth'), c.req.raw.headers);