@ixo/oracle-runtime-workers 0.38.0 → 0.40.1

package/src/shell/app.ts

@@ -1,3 +1,14 @@
+import {
+  ActionInteractionError,
+  CheckClaimDispatchSchema,
+  CheckDispatchSchema,
+} from '@ixo/action-interactions';
+import { ZodError } from 'zod';
+import {
+  interactionStatus,
+  parseInteractionCommand,
+  parseInteractionRead,
+} from '../action-interactions/routes';
 import {
   ActionProposalWireSchema,
   TopicReceiptReferencesSchema,
@@ -246,6 +257,9 @@ export function rateLimitKey(
   env: Pick<OracleWorkerEnv, 'ORACLE_DID'>,
   scope:
     | 'user'
+    | 'card-read'
+    | 'card-write'
+    | 'card-dispatch'
     | 'poll'
     | 'channel'
     | 'channel-control'
@@ -422,6 +436,32 @@ export function createShell(
       status: 'ok',
       timestamp: new Date().toISOString(),
       frontendTools: FRONTEND_BRIDGE,
+      ...(c.env.ACTION_INTERACTIONS_ENABLED === 'true'
+        ? {
+            actionInteractions: {
+              version: 1,
+              owners: [
+                'flow-claim',
+                'flow-claim-block',
+                'flow-bid',
+                'owner-reference',
+                'approval',
+                'task',
+                'question',
+                'artifact',
+              ],
+              operations: [
+                'prepare',
+                'read',
+                'update',
+                'reserve',
+                'observe',
+                'dispatch',
+                'read-task',
+              ],
+            },
+          }
+        : {}),
     }),
   );
   // A liveness probe: the gateway's in-memory flag, no storage read. The
@@ -688,15 +728,27 @@ 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.
+    // The chat lists' status poll, the card routes (Portal's review page) and
+    // action-card reads, writes and dispatch checks each have their own bucket:
+    // polling or typing in a card while chatting must not push turns into 429,
+    // and neither chat nor card edits can use up the dispatch check, whose 429
+    // the Portal treats as "could not ask" and lets the submission through.
+    const isGet = c.req.method === 'GET';
+    const path = c.req.path;
+    const card = path.startsWith('/action-interactions');
     const scope =
-      c.req.method === 'GET' && c.req.path === '/runs/active'
+      isGet && path === '/runs/active'
         ? 'poll'
-        : c.req.path.startsWith('/action-proposals/')
+        : path.startsWith('/action-proposals/')
           ? 'action'
-          : 'user';
+          : card && isGet
+            ? 'card-read'
+            : path === '/action-interactions/dispatch' ||
+                path === '/action-interactions/claim-dispatch'
+              ? 'card-dispatch'
+              : card
+                ? 'card-write'
+                : 'user';
     const { success } = await limiter.limit({
       key: rateLimitKey(c.env, scope, auth.userDid),
     });
@@ -712,6 +764,189 @@ export function createShell(
     return next();
   });
 
+  // These routes own private proposals, never action execution. No route is a
+  // model tool; host reservation requires the authenticated signed invocation.
+  app.use('/action-interactions*', async (c, next) => {
+    if (
+      c.env.ACTION_INTERACTIONS_ENABLED !== 'true' &&
+      c.req.path !== '/action-interactions/claim-dispatch' &&
+      c.req.path !== '/action-interactions/dispatch'
+    )
+      return c.json(
+        { code: 'unavailable', message: 'Action interactions are disabled' },
+        404,
+      );
+    if (c.get('auth')?.via !== 'invocation')
+      return c.json(
+        {
+          code: 'invocation_required',
+          message: 'A signed invocation is required',
+        },
+        401,
+      );
+    return next();
+  });
+  const interactionBodyLimit = (maxSize: number) =>
+    bodyLimit({
+      maxSize,
+      onError: (c) =>
+        c.json({ code: 'too_large', message: 'Request is too large' }, 413),
+    });
+  const smallInteractionBody = interactionBodyLimit(96 * 1024);
+  // Only a prepare can carry a domain-write approval (up to 2 MiB).
+  const preparedInteractionBody = interactionBodyLimit(2 * 1024 * 1024);
+  app.use('/action-interactions*', (c, next) =>
+    c.req.method === 'POST' && c.req.path === '/action-interactions'
+      ? preparedInteractionBody(c, next)
+      : smallInteractionBody(c, next),
+  );
+  app.get('/action-interactions/tasks/:taskId', async (c) => {
+    const sessionId = c.req.query('sessionId');
+    if (!sessionId)
+      return c.json(
+        { code: 'invalid_request', message: 'sessionId is required' },
+        400,
+      );
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const result = await userStub(
+      c.env,
+      identity.userDid,
+    ).readActionInteractionTask(identity, sessionId, c.req.param('taskId'));
+    if (result.ok)
+      return new Response(result.value, {
+        headers: {
+          'content-type': 'application/json',
+          'cache-control': 'no-store',
+        },
+      });
+    return c.json({ code: result.code, message: result.message }, 404);
+  });
+  app.post('/action-interactions/dispatch', async (c) => {
+    const parsed = CheckDispatchSchema.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success)
+      return c.json(
+        { code: 'invalid_request', message: 'Invalid dispatch binding' },
+        400,
+      );
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const result = await userStub(c.env, identity.userDid).checkDispatch(
+      identity,
+      parsed.data,
+    );
+    if (result.ok)
+      return new Response(result.value, {
+        headers: {
+          'content-type': 'application/json',
+          'cache-control': 'no-store',
+        },
+      });
+    return c.json(
+      { code: result.code, message: result.message },
+      result.status === 403 ? 403 : 409,
+    );
+  });
+  app.post('/action-interactions/claim-dispatch', async (c) => {
+    const parsed = CheckClaimDispatchSchema.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success)
+      return c.json(
+        { code: 'invalid_request', message: 'Invalid claim dispatch binding' },
+        400,
+      );
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const result = await userStub(c.env, identity.userDid).checkClaimDispatch(
+      identity,
+      parsed.data,
+    );
+    if (result.ok)
+      return new Response(result.value, {
+        headers: {
+          'content-type': 'application/json',
+          'cache-control': 'no-store',
+        },
+      });
+    return c.json(
+      { code: result.code, message: result.message },
+      result.status === 403 ? 403 : 409,
+    );
+  });
+  app.on(
+    ['GET', 'POST', 'PATCH'],
+    [
+      '/action-interactions',
+      '/action-interactions/:id',
+      '/action-interactions/:id/:operation',
+    ],
+    async (c) => {
+      try {
+        // Every request is parsed before a user object is addressed.
+        const identity = identityOf(c.get('auth'), c.req.raw.headers);
+        if (c.req.method === 'GET') {
+          const read = parseInteractionRead(
+            c.req.query('sessionId'),
+            c.req.param('id'),
+            c.req.param('operation'),
+          );
+          const result = await userStub(
+            c.env,
+            identity.userDid,
+          ).readActionInteraction(
+            identity,
+            read.sessionId,
+            read.id,
+            c.req.query('view') === 'references',
+          );
+          if (result.ok)
+            return new Response(result.value, {
+              headers: {
+                'content-type': 'application/json',
+                'cache-control': 'no-store',
+              },
+            });
+          return c.json(
+            { code: result.code, message: result.message },
+            interactionStatus(result.status),
+          );
+        }
+        const command = await parseInteractionCommand(
+          c.req.raw,
+          c.req.param('id'),
+          c.req.param('operation'),
+        );
+        const result = await userStub(
+          c.env,
+          identity.userDid,
+        ).actionInteraction(identity, command);
+        if (result.ok)
+          return new Response(result.value, {
+            headers: {
+              'content-type': 'application/json',
+              'cache-control': 'no-store',
+            },
+          });
+        return c.json(
+          { code: result.code, message: result.message },
+          interactionStatus(result.status),
+        );
+      } catch (error) {
+        if (error instanceof ZodError)
+          return c.json(
+            { code: 'invalid_request', message: 'Invalid interaction request' },
+            400,
+          );
+        if (error instanceof ActionInteractionError)
+          return c.json(
+            { code: error.code, message: error.message },
+            interactionStatus(error.status),
+          );
+        throw error;
+      }
+    },
+  );
+
   // 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

package/src/sqlite/serialization.ts

@@ -12,6 +12,10 @@
  * and LangGraph `Send` objects. `stringify` is fast-safe-stringify's
  * circular-safe variant, typed.
  */
+import {
+  TURN_GUIDE_NOTE_KWARG,
+  USAGE_CARRIED_KWARG,
+} from '../core/operating-guides';
 import { TURN_TIME_NOTE_KWARG } from '../core/turn-time-note';
 import {
   CHANNEL_DELIVERY_NOTICE_KWARG,
@@ -382,6 +386,14 @@ export function cleanAdditionalKwargs(
   const deliveryNotice = additionalKwargs[CHANNEL_DELIVERY_NOTICE_KWARG];
   if (typeof deliveryNotice === 'string')
     cleaned[CHANNEL_DELIVERY_NOTICE_KWARG] = deliveryNotice;
+  const guideNote = additionalKwargs[TURN_GUIDE_NOTE_KWARG];
+  if (typeof guideNote === 'string') cleaned[TURN_GUIDE_NOTE_KWARG] = guideNote;
+  // Kept for the context guard and the summary (core/operating-guides.ts).
+  const usage = additionalKwargs[USAGE_CARRIED_KWARG];
+  if (Array.isArray(usage))
+    cleaned[USAGE_CARRIED_KWARG] = usage.filter(
+      (name): name is string => typeof name === 'string',
+    );
   // Channel provenance, read back typed by the transcript (ChannelOrigin,
   // ChannelReplyReference); anything malformed is dropped there.
   for (const key of ['org.ixo.qi.origin', 'org.ixo.qi.reply'] as const)

package/src/sqlite/sqlite-saver.ts

@@ -536,6 +536,23 @@ export class SqliteSaver extends BaseCheckpointSaver {
     return Promise.all(rows.map((row) => this.loadMessage(row.message)));
   }
 
+  /**
+   * The thread's newest human and AI rows with stored content, newest first.
+   * `limit` bounds the rows decoded, so the read stays O(limit) in a long
+   * thread, unlike `listThreadMessages`.
+   */
+  async listRecentThreadMessages(
+    threadId: string,
+    limit: number,
+  ): Promise<BaseMessage[]> {
+    await this.setup();
+    const rows = await this.db.exec<MessageRow>(
+      `SELECT message FROM messages WHERE thread_id = ? AND message_type IN ('human', 'ai') AND message_content <> '' ORDER BY created_at DESC, rowid DESC LIMIT ?`,
+      [threadId, limit],
+    );
+    return Promise.all(rows.map((row) => this.loadMessage(row.message)));
+  }
+
   /**
    * Where a transcript row sits in the listing order (`created_at`, then
    * `rowid`), or null when the thread has no row with that message id. A

package/src/tasks/schedule-input.ts

@@ -14,32 +14,15 @@ import { z } from 'zod';
 import type { OracleTaskSchedule } from '../plugin-api/types';
 
 const SCHEDULE_DESCRIPTION =
-  'When the task fires. kind "once" needs `at` (ISO timestamp, computed from the current time — ALWAYS use it for one-time requests such as "in 10 minutes" or "tomorrow at 5pm"); kind "cron" needs `cron` (+ optional IANA `timezone`) and is ONLY for genuinely recurring intents — `*/10 * * * *` means every 10 minutes forever, not once in 10 minutes; kind "interval" needs `everySeconds`. Leave the other kinds\' fields out.';
+  'kind "once" needs `at`, computed from the current time: ALWAYS for one-time requests such as "in 10 minutes" or "tomorrow at 5pm". kind "cron" needs `cron` and is ONLY for genuinely recurring intents: `*/10 * * * *` means every 10 minutes forever, not once in 10 minutes. kind "interval" needs `everySeconds`. Leave the other kinds\' fields out.';
 
 export const ScheduleInputSchema = z
   .object({
     kind: z.enum(['once', 'cron', 'interval']),
-    at: z
-      .string()
-      .min(1)
-      .optional()
-      .describe('ISO timestamp — kind "once" only.'),
-    cron: z
-      .string()
-      .min(1)
-      .optional()
-      .describe('Cron expression (5 fields) — kind "cron" only.'),
-    timezone: z
-      .string()
-      .min(1)
-      .optional()
-      .describe('IANA timezone for the cron expression — kind "cron" only.'),
-    everySeconds: z
-      .number()
-      .int()
-      .positive()
-      .optional()
-      .describe('Seconds between runs — kind "interval" only.'),
+    at: z.string().min(1).optional().describe('ISO timestamp.'),
+    cron: z.string().min(1).optional().describe('5 fields.'),
+    timezone: z.string().min(1).optional().describe('IANA, for `cron`.'),
+    everySeconds: z.number().int().positive().optional(),
   })
   .describe(SCHEDULE_DESCRIPTION);