@ixo/oracle-runtime-workers 0.10.0 → 0.11.1

package/src/do/transcript.ts

@@ -13,6 +13,10 @@ import {
   isAttachmentViewMessage,
 } from '../attachments/retention';
 import { SUMMARY_PREFIX } from '../core/middlewares/summarization';
+import type {
+  ThreadMessageAnchor,
+  ThreadMessageRow,
+} from '../sqlite/sqlite-saver';
 
 export interface ToolCallDto {
   name: string;
@@ -203,3 +207,237 @@ export async function transformTranscript(
   }
   return { messages: acc };
 }
+
+// ── Transcript paging (docs/plans/transcript-paging.md) ─────────────────────
+
+export const TRANSCRIPT_PAGE_DEFAULT = 20;
+export const TRANSCRIPT_PAGE_MAX = 100;
+/** Rows read per round while a page collects its turns (a turn is one row or dozens). */
+const TRANSCRIPT_ROW_BATCH = 80;
+
+export interface TranscriptPageOptions {
+  /** Turns per page: a user message with everything the agent did until the next one. */
+  limit: number;
+  /** The page of turns older than this cursor (a message id from an earlier page). */
+  before?: string;
+  /**
+   * What follows this cursor, oldest first: the turn the cursor sits in,
+   * re-sent whole from its start when the cursor split it, then up to
+   * `limit` newer turns. A client folds it in by message id.
+   */
+  after?: string;
+}
+
+export interface TranscriptPage extends ListMessagesResponse {
+  /** Continue older from here (`before=`); null once the first message is in the page. */
+  prevCursor: string | null;
+  /** Continue newer from here (`after=`); null while the thread has no rows. */
+  nextCursor: string | null;
+  hasOlder: boolean;
+  hasNewer: boolean;
+}
+
+/** The rows a pager reads — what `SqliteSaver` implements. */
+export interface TranscriptRowSource {
+  findThreadMessageAnchor(
+    threadId: string,
+    messageId: string,
+  ): Promise<ThreadMessageAnchor | null>;
+  listThreadMessageRows(
+    threadId: string,
+    opts: {
+      direction: 'older' | 'newer';
+      anchor?: ThreadMessageAnchor | null;
+      inclusive?: boolean;
+      limit: number;
+    },
+  ): Promise<ThreadMessageRow[]>;
+}
+
+/** A cursor naming no row of the thread (a client kept one from another session). */
+export class TranscriptCursorError extends Error {
+  constructor(readonly cursor: string) {
+    super(`unknown transcript cursor: ${cursor}`);
+    this.name = 'TranscriptCursorError';
+  }
+}
+
+/** A turn starts at a user message; the summarizer's bookkeeping row is not one. */
+function startsTurn(row: ThreadMessageRow): boolean {
+  return row.message.type === 'human' && !isSummarizationMessage(row.message);
+}
+
+/** `GET /sessions/:id/messages` query → options, or the 400 to answer with. */
+export function parseTranscriptPageQuery(
+  query: Record<string, string | undefined>,
+):
+  | { ok: true; options: TranscriptPageOptions }
+  | { ok: false; message: string } {
+  const rawLimit = query.limit?.trim();
+  let limit = TRANSCRIPT_PAGE_DEFAULT;
+  if (rawLimit) {
+    const n = Number(rawLimit);
+    if (!Number.isInteger(n) || n < 1)
+      return { ok: false, message: 'limit must be a positive integer' };
+    limit = Math.min(n, TRANSCRIPT_PAGE_MAX);
+  }
+  const before = query.before?.trim() || undefined;
+  const after = query.after?.trim() || undefined;
+  if (before && after)
+    return { ok: false, message: 'before and after are mutually exclusive' };
+  return {
+    ok: true,
+    options: {
+      limit,
+      ...(before !== undefined && { before }),
+      ...(after !== undefined && { after }),
+    },
+  };
+}
+
+async function toPage(rows: ThreadMessageRow[]): Promise<MessageDto[]> {
+  const { messages } = await transformTranscript(
+    rows.map((r) => r.message).filter((m) => !isSummarizationMessage(m)),
+  );
+  return messages;
+}
+
+/**
+ * One page of a session's transcript, aligned to turns so a tool result is
+ * never separated from the reply that called it. Without a cursor: the
+ * newest `limit` turns. The legacy `GET /messages/:id` listing is this with
+ * no limit.
+ */
+export async function pageThreadTranscript(
+  source: TranscriptRowSource,
+  threadId: string,
+  options: TranscriptPageOptions,
+): Promise<TranscriptPage> {
+  const limit = Math.max(1, Math.min(options.limit, TRANSCRIPT_PAGE_MAX));
+  if (options.after !== undefined)
+    return pageNewer(source, threadId, options.after, limit);
+  return pageOlder(source, threadId, options.before, limit);
+}
+
+async function pageOlder(
+  source: TranscriptRowSource,
+  threadId: string,
+  before: string | undefined,
+  limit: number,
+): Promise<TranscriptPage> {
+  let anchor: ThreadMessageAnchor | null = null;
+  if (before !== undefined) {
+    anchor = await source.findThreadMessageAnchor(threadId, before);
+    if (!anchor) throw new TranscriptCursorError(before);
+  }
+  const collected: ThreadMessageRow[] = []; // newest first
+  let turns = 0;
+  let hasOlder = false;
+  let cursor = anchor;
+  outer: for (;;) {
+    const batch = await source.listThreadMessageRows(threadId, {
+      direction: 'older',
+      anchor: cursor,
+      limit: TRANSCRIPT_ROW_BATCH,
+    });
+    for (let i = 0; i < batch.length; i += 1) {
+      const row = batch[i]!;
+      collected.push(row);
+      if (!startsTurn(row)) continue;
+      turns += 1;
+      if (turns < limit) continue;
+      hasOlder =
+        i + 1 < batch.length ||
+        (
+          await source.listThreadMessageRows(threadId, {
+            direction: 'older',
+            anchor: row.anchor,
+            limit: 1,
+          })
+        ).length > 0;
+      break outer;
+    }
+    if (batch.length < TRANSCRIPT_ROW_BATCH) break; // the thread's first row is in the page
+    cursor = batch[batch.length - 1]!.anchor;
+  }
+  const rows = collected.reverse();
+  return {
+    messages: await toPage(rows),
+    prevCursor: hasOlder ? rows[0]!.messageId : null,
+    nextCursor: rows.length ? rows[rows.length - 1]!.messageId : null,
+    hasOlder,
+    hasNewer: before !== undefined,
+  };
+}
+
+async function pageNewer(
+  source: TranscriptRowSource,
+  threadId: string,
+  after: string,
+  limit: number,
+): Promise<TranscriptPage> {
+  const anchor = await source.findThreadMessageAnchor(threadId, after);
+  if (!anchor) throw new TranscriptCursorError(after);
+  const fresh: ThreadMessageRow[] = []; // oldest first
+  let turns = 0;
+  let hasNewer = false;
+  let cursor: ThreadMessageAnchor = anchor;
+  outer: for (;;) {
+    const batch = await source.listThreadMessageRows(threadId, {
+      direction: 'newer',
+      anchor: cursor,
+      limit: TRANSCRIPT_ROW_BATCH,
+    });
+    for (const row of batch) {
+      if (startsTurn(row)) {
+        turns += 1;
+        if (turns > limit) {
+          hasNewer = true;
+          break outer;
+        }
+      }
+      fresh.push(row);
+    }
+    if (batch.length < TRANSCRIPT_ROW_BATCH) break;
+    cursor = batch[batch.length - 1]!.anchor;
+  }
+  if (fresh.length === 0)
+    return {
+      messages: [],
+      prevCursor: null,
+      nextCursor: after,
+      hasOlder: false,
+      hasNewer: false,
+    };
+  // The cursor split a turn (a reply and its tool results land row by row):
+  // re-send that turn from its start so the tool results fold into their
+  // reply again on the client.
+  const head: ThreadMessageRow[] = []; // newest first, the cursor row included
+  if (!startsTurn(fresh[0]!)) {
+    let back: ThreadMessageAnchor | null = anchor;
+    let inclusive = true;
+    outer2: for (;;) {
+      const batch = await source.listThreadMessageRows(threadId, {
+        direction: 'older',
+        anchor: back,
+        inclusive,
+        limit: TRANSCRIPT_ROW_BATCH,
+      });
+      for (const row of batch) {
+        head.push(row);
+        if (startsTurn(row)) break outer2;
+      }
+      if (batch.length < TRANSCRIPT_ROW_BATCH) break;
+      back = batch[batch.length - 1]!.anchor;
+      inclusive = false;
+    }
+  }
+  const rows = [...head.reverse(), ...fresh];
+  return {
+    messages: await toPage(rows),
+    prevCursor: null,
+    nextCursor: rows[rows.length - 1]!.messageId,
+    hasOlder: false,
+    hasNewer,
+  };
+}

package/src/do/turn-body.ts

@@ -19,11 +19,14 @@ export const TURN_BODY_KEYS: ReadonlySet<string> = new Set([
   'mcpInvocations',
   'attachments',
   'requestId',
+  'multitask',
 ]);
 
 export interface TurnBody {
   message: string;
   stream?: boolean;
+  /** `interrupt` (default) or `enqueue` — see `TurnRequest.multitask`. */
+  multitask?: 'interrupt' | 'enqueue';
   returnAllMessages?: boolean;
   timezone?: string;
   model?: string;
@@ -80,5 +83,12 @@ export function parseTurnBody(raw: string): ParsedTurnBody {
   if (typeof record.message !== 'string' || record.message.length === 0) {
     return reject('message is required');
   }
+  if (
+    record.multitask !== undefined &&
+    record.multitask !== 'interrupt' &&
+    record.multitask !== 'enqueue'
+  ) {
+    return reject('multitask must be one of: interrupt, enqueue');
+  }
   return { ok: true, body: record as unknown as TurnBody };
 }