@ixo/oracle-runtime-workers 0.21.2 → 0.23.0

package/src/realtime/session-socket-hub.ts

@@ -10,7 +10,14 @@
  * (`serializeAttachment`), so the set is rebuilt losslessly from
  * `ctx.getWebSockets()` whenever the object wakes from hibernation or
  * restarts. Nothing here is kept only in memory.
+ *
+ * A socket is a foreground executor (a tab showing the chat: it renders the
+ * session's events and runs any frontend call) unless its CONNECT declared
+ * itself a background executor: then it runs only the browser tools it
+ * named — never an AG-UI action, which renders on the chat's own surface or
+ * asks the user (a wallet signature) — and receives no fan-out.
  */
+import type { FrontendCallKind } from './frontend-call-registry';
 import { ENGINE_PING, encodeEvent } from './socket-io-codec';
 
 export interface SocketAttachment {
@@ -32,8 +39,40 @@ export interface SocketAttachment {
    * engine.io pongs do not count — a background tab answers those too.
    */
   lastActiveAt?: number;
+  /** Set when the CONNECT declared a background executor; absent = foreground. */
+  executor?: 'background';
+  /** The tools a background executor can run (validated, bounded; see `realtime-endpoint.ts`). */
+  tools?: string[];
+}
+
+/** An executor socket with its attachment. */
+export interface HubEntry<S> {
+  socket: S;
+  attachment: SocketAttachment;
+}
+
+const isForeground = (attachment: SocketAttachment): boolean =>
+  attachment.executor !== 'background';
+
+/**
+ * Whether the socket may run a call of `kind` to `toolName`: any call in
+ * the foreground; in the background only a browser tool it declared.
+ */
+export function canRunTool(
+  attachment: SocketAttachment,
+  kind: FrontendCallKind,
+  toolName: string,
+): boolean {
+  return (
+    isForeground(attachment) ||
+    (kind === 'browser' && (attachment.tools ?? []).includes(toolName))
+  );
 }
 
+/** Most recent client event, else open time (see `executorFor`). */
+const recency = (attachment: SocketAttachment): number =>
+  attachment.lastActiveAt ?? attachment.openedAt;
+
 /** The subset of the Workers `WebSocket` the hub needs (tests use fakes). */
 export interface HubSocket {
   send(message: string): void;
@@ -148,14 +187,14 @@ export class SessionSocketHub<S extends HubSocket = HubSocket> {
   }
 
   /** Every socket with its heartbeat bookkeeping (diagnostics). */
-  entries(): Array<{ socket: S; attachment: SocketAttachment }> {
+  entries(): Array<HubEntry<S>> {
     return [...this.sockets].map(([socket, attachment]) => ({
       socket,
       attachment,
     }));
   }
 
-  /** Authenticated sockets subscribed to `sessionId`. */
+  /** Authenticated sockets subscribed to `sessionId`, background executors included. */
   forSession(sessionId: string): S[] {
     const out: S[] = [];
     for (const [socket, meta] of this.sockets) {
@@ -168,42 +207,74 @@ export class SessionSocketHub<S extends HubSocket = HubSocket> {
     return this.forSession(sessionId).length > 0;
   }
 
-  /** A client event arrived on the socket: persist the time (see `executorForSession`). */
+  /** Whether a foreground (chat-rendering) socket of `sessionId` is authenticated. */
+  hasForegroundSession(sessionId: string): boolean {
+    for (const meta of this.sockets.values())
+      if (meta.userDid && meta.sessionId === sessionId && isForeground(meta))
+        return true;
+    return false;
+  }
+
+  /** A client event arrived on the socket: persist the time (see `executorFor`). */
   noteActivity(socket: S): void {
     if (this.sockets.has(socket))
       this.update(socket, { lastActiveAt: this.now() });
   }
 
   /**
-   * The authenticated socket of `sessionId` a frontend call runs on: the one
-   * with the most recent client event, else the one opened last. The tab the
-   * user acted in last is the likeliest to be in front; the tab that
-   * connected last is often just a background tab that reconnected after a
-   * laptop woke. Ties go to the socket registered later.
+   * The authenticated socket of `sessionId` a frontend call of `kind` to
+   * `toolName` runs on. A foreground socket first: the one with the most recent client
+   * event, else the one opened last — the tab the user acted in last is the
+   * likeliest to be in front; the tab that connected last is often just a
+   * background tab that reconnected after a laptop woke. Without one, a
+   * background executor that declared the browser tool `toolName`, by the
+   * same recency.
+   * Ties go to the socket registered later. Undefined when no socket of the
+   * session can run the tool.
    */
-  executorForSession(
+  executorFor(
     sessionId: string,
-  ): { socket: S; attachment: SocketAttachment } | undefined {
-    const recency = (attachment: SocketAttachment): number =>
-      attachment.lastActiveAt ?? attachment.openedAt;
-    let chosen: { socket: S; attachment: SocketAttachment } | undefined;
+    kind: FrontendCallKind,
+    toolName: string,
+  ): HubEntry<S> | undefined {
+    let foreground: HubEntry<S> | undefined;
+    let background: HubEntry<S> | undefined;
     for (const [socket, attachment] of this.sockets) {
       if (!attachment.userDid || attachment.sessionId !== sessionId) continue;
-      if (!chosen || recency(attachment) >= recency(chosen.attachment))
-        chosen = { socket, attachment };
+      if (isForeground(attachment)) {
+        if (
+          !foreground ||
+          recency(attachment) >= recency(foreground.attachment)
+        )
+          foreground = { socket, attachment };
+      } else if (
+        canRunTool(attachment, kind, toolName) &&
+        (!background || recency(attachment) >= recency(background.attachment))
+      )
+        background = { socket, attachment };
     }
-    return chosen;
+    return foreground ?? background;
   }
 
-  /** Fan an event out to every authenticated socket of the session. */
+  /**
+   * Fan an event out to the session's authenticated FOREGROUND sockets: a
+   * background executor runs calls, it does not render the chat.
+   */
   emitToSession(
     sessionId: string,
     eventName: string,
     payload: unknown,
   ): number {
-    const frame = encodeEvent(eventName, payload);
+    // Encoded once, and only when a socket will take it: most events of a
+    // session nobody has open (or only background executors) cost nothing.
+    let frame: string | undefined;
     let sent = 0;
-    for (const socket of this.forSession(sessionId)) {
+    // A failed send removes that socket; deleting the entry being visited
+    // is safe while iterating a Map.
+    for (const [socket, meta] of this.sockets) {
+      if (!meta.userDid || meta.sessionId !== sessionId || !isForeground(meta))
+        continue;
+      frame ??= encodeEvent(eventName, payload);
       if (this.trySend(socket, frame)) sent += 1;
     }
     return sent;

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
@@ -213,7 +242,15 @@ export function isDidShaped(value: string): boolean {
  */
 export function rateLimitKey(
   env: Pick<OracleWorkerEnv, 'ORACLE_DID'>,
-  scope: 'user' | 'channel' | 'artifact' | 'socket' | 'status' | 'start',
+  scope:
+    | 'user'
+    | 'poll'
+    | 'channel'
+    | 'action'
+    | 'artifact'
+    | 'socket'
+    | 'status'
+    | 'start',
   subject: string,
 ): string {
   return `${env.ORACLE_DID}|${scope}|${subject}`;
@@ -417,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)
@@ -471,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,
@@ -523,13 +594,25 @@ export function createShell(
   // unbounded LLM spend; the key carries the oracle's DID (`rateLimitKey`).
   // Auth-excluded routes (health/models/matrix status) ran `next()` above
   // and never reach here. Absent binding = no limiting (local harness / tests).
+  // The chat lists' status poll (`GET /runs/active`) spends its own budget
+  // (`poll` scope, same binding): a tab polling every 4 s never pushes the
+  // user's messages into 429, nor the other way round.
   app.use('*', async (c, next) => {
     const limiter = c.env.RATE_LIMIT;
     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'
+        : c.req.path.startsWith('/action-proposals/')
+          ? 'action'
+          : 'user';
     const { success } = await limiter.limit({
-      key: rateLimitKey(c.env, 'user', auth.userDid),
+      key: rateLimitKey(c.env, scope, auth.userDid),
     });
     if (!success)
       return c.json(
@@ -543,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);
@@ -668,6 +874,7 @@ export function createShell(
       return c.json({ message: 'sessionId is required' }, 400);
     const success = await userStub(c.env, identity.userDid).abortTurn(
       body.sessionId,
+      identity,
     );
     return c.json({ success });
   });
@@ -745,6 +952,15 @@ export function createShell(
     );
     return c.json({ run });
   });
+  // Every active run of the caller's chats (task runs excluded, no
+  // `partialText`), oldest first: a client's chat lists poll it to show
+  // which chats are busy. Registered before `/runs/:runId`, which would
+  // otherwise take `active` for a run id.
+  app.get('/runs/active', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const runs = await userStub(c.env, identity.userDid).activeRuns(identity);
+    return c.json({ runs });
+  });
   // Re-join a run's SSE stream after a cursor (`?after=<seq>`, the `id:` of
   // the last frame the client saw). Frames after it are replayed, then the
   // live tail until `done`. A run that ended replays and closes at once.

package/src/sqlite/sessions-store.ts

@@ -220,6 +220,28 @@ export class SessionsStore {
     return { sessions: [], total: Number(count?.n ?? 0) };
   }
 
+  /**
+   * The room of each of these sessions that has a row (`null`: a row
+   * without a room). One statement for the lot; sessions without a row are
+   * absent from the map.
+   */
+  async roomsOf(
+    sessionIds: readonly string[],
+  ): Promise<Map<string, string | null>> {
+    const rooms = new Map<string, string | null>();
+    if (sessionIds.length === 0) return rooms;
+    await this.setup();
+    const rows = await this.db.exec<{
+      session_id: string;
+      room_id: string | null;
+    }>(
+      `SELECT session_id, room_id FROM sessions WHERE session_id IN (${sessionIds.map(() => '?').join(', ')})`,
+      [...sessionIds],
+    );
+    for (const row of rows) rooms.set(row.session_id, row.room_id);
+    return rooms;
+  }
+
   async getSession(sessionId: string): Promise<SessionRecord | undefined> {
     await this.setup();
     const row = await this.db.get<SessionRow>(