@ixo/oracle-runtime-workers 0.2.0

package/src/do/transcript.ts

@@ -0,0 +1,192 @@
+/**
+ * Transcript → client DTO. Port of `@ixo/common`'s
+ * `transformGraphStateMessageToListMessageResponse` so `GET /messages/:id`
+ * returns the exact shape the Portal / client SDK already consume.
+ */
+import type {
+  AIMessage,
+  BaseMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import {
+  isAttachmentPlaceholderText,
+  isAttachmentViewMessage,
+} from '../attachments/retention';
+
+export interface ToolCallDto {
+  name: string;
+  id: string;
+  args: unknown;
+  status?: 'isRunning' | 'done';
+  output?: string;
+}
+
+export interface AttachmentMeta {
+  filename: string;
+  mimetype: string;
+  size?: number;
+  mxcUri?: string;
+  eventId?: string;
+  category?: string;
+}
+
+export interface MessageDto {
+  id: string;
+  type: 'ai' | 'human';
+  content: string;
+  toolCalls?: ToolCallDto[];
+  reasoning?: string;
+  isComplete?: boolean;
+  isReasoning?: boolean;
+  attachment?: AttachmentMeta;
+  attachments?: AttachmentMeta[];
+}
+
+export interface ListMessagesResponse {
+  messages: MessageDto[];
+}
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Stable id for a message without one — sha256 hex of its text (as the Node runtime does). */
+export async function uuidFromString(str: string): Promise<string> {
+  if (UUID_RE.test(str)) return str;
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(str),
+  );
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function reasoningToText(reasoning: unknown): string | undefined {
+  if (typeof reasoning === 'string') return reasoning || undefined;
+  if (
+    reasoning &&
+    typeof reasoning === 'object' &&
+    Array.isArray((reasoning as { summary?: unknown }).summary)
+  ) {
+    const text = (reasoning as { summary: unknown[] }).summary
+      .map((part) =>
+        part &&
+        typeof part === 'object' &&
+        typeof (part as { text?: unknown }).text === 'string'
+          ? (part as { text: string }).text
+          : '',
+      )
+      .join('');
+    return text || undefined;
+  }
+  return undefined;
+}
+
+export function contentToText(content: BaseMessage['content']): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === 'string') return part;
+        if (part && typeof part === 'object' && 'text' in part) {
+          const text = (part as { text?: unknown }).text;
+          // The retention placeholder is model-facing only; the transcript
+          // keeps listing the attachment from its metadata.
+          return typeof text === 'string' && !isAttachmentPlaceholderText(text)
+            ? text
+            : '';
+        }
+        return '';
+      })
+      .join('');
+  }
+  return String(content);
+}
+
+/** The summarization middleware's bookkeeping message — never shown to users. */
+export function isSummarizationMessage(message: BaseMessage): boolean {
+  const kw = message.additional_kwargs as Record<string, unknown> | undefined;
+  if (kw?.lc_summary_message === true || kw?.summary === true) return true;
+  const text = contentToText(message.content);
+  return message.type === 'system' && /summary of the conversation/i.test(text);
+}
+
+export async function transformTranscript(
+  messages: BaseMessage[],
+): Promise<ListMessagesResponse> {
+  const acc: MessageDto[] = [];
+  for (const message of messages) {
+    const toolMsg = message.type === 'tool' ? (message as ToolMessage) : null;
+    const kw = (message.additional_kwargs ?? {}) as Record<string, unknown>;
+    const isExtractionContext = message.type === 'ai' && Boolean(kw.attachment);
+
+    if (
+      message.type !== 'system' &&
+      message.type !== 'tool' &&
+      !kw.isError &&
+      !isExtractionContext &&
+      // `view_attachment` re-attaching an offloaded payload — model-facing.
+      !isAttachmentViewMessage(message)
+    ) {
+      const reasoning = reasoningToText(kw.reasoning);
+      const attachments =
+        message.type === 'human'
+          ? ((kw.attachments as AttachmentMeta[] | undefined) ??
+            (kw.attachment ? [kw.attachment as AttachmentMeta] : undefined))
+          : undefined;
+      const attachment = attachments?.[0];
+      const textContent = contentToText(message.content);
+      const toolCalls = (message as AIMessage).tool_calls;
+      const dto: MessageDto = {
+        type: message.type === 'ai' ? 'ai' : 'human',
+        content: textContent,
+        id: await uuidFromString(message.id ?? textContent),
+        isComplete: true,
+        isReasoning: false,
+      };
+      if (toolCalls?.length) {
+        dto.toolCalls = [];
+        for (const tc of toolCalls) {
+          dto.toolCalls.push({
+            name: tc.name,
+            args: tc.args,
+            id: tc.id ?? (await uuidFromString(JSON.stringify(tc.args))),
+            output: undefined,
+          });
+        }
+      }
+      if (reasoning) dto.reasoning = reasoning;
+      if (attachment) dto.attachment = attachment;
+      if (attachments?.length) dto.attachments = attachments;
+      acc.push(dto);
+    }
+
+    if (toolMsg) {
+      const kwargs = (
+        toolMsg as unknown as {
+          lc_kwargs?: { tool_call_id?: string; args?: unknown };
+        }
+      ).lc_kwargs;
+      const toolCallId =
+        toolMsg.tool_call_id ??
+        kwargs?.tool_call_id ??
+        (await uuidFromString(JSON.stringify(kwargs?.args)));
+      const idx = acc.findIndex((m) =>
+        m.toolCalls?.some((t) => t.id === toolCallId),
+      );
+      const el = idx !== -1 ? acc[idx] : undefined;
+      if (el) {
+        el.toolCalls = el.toolCalls?.map((t) =>
+          t.id === toolCallId
+            ? {
+                ...t,
+                output: JSON.stringify(toolMsg.content),
+                status: 'done' as const,
+              }
+            : t,
+        );
+      }
+    }
+  }
+  return { messages: acc };
+}

package/src/do/turn-body.ts

@@ -0,0 +1,84 @@
+/**
+ * `POST /messages/:id` body validation — the Workers counterpart of Node's
+ * `SendMessageDto` under a `ValidationPipe({ whitelist, forbidNonWhitelisted })`
+ * behind express body-parser: malformed JSON, unknown top-level fields and a
+ * missing `message` are all 400s, never a failed turn or a 500.
+ */
+
+/** Top-level fields of Node's `SendMessageDto`; anything else is rejected. */
+export const TURN_BODY_KEYS: ReadonlySet<string> = new Set([
+  'message',
+  'stream',
+  'returnAllMessages',
+  'model',
+  'tools',
+  'agActions',
+  'metadata',
+  'timezone',
+  'homeServer',
+  'mcpInvocations',
+  'attachments',
+  'requestId',
+]);
+
+export interface TurnBody {
+  message: string;
+  stream?: boolean;
+  returnAllMessages?: boolean;
+  timezone?: string;
+  model?: string;
+  /**
+   * Free-form client metadata (Node's `SendMessageDto.metadata`); the runtime
+   * reads `editorRoomId`, `spaceId`, `sessionRunId` and `currentEntityDid`.
+   */
+  metadata?: Record<string, unknown> & {
+    editorRoomId?: string;
+    spaceId?: string;
+    sessionRunId?: string;
+    currentEntityDid?: string;
+  };
+  tools?: Array<{
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+  }>;
+  agActions?: Array<{
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    hasRender?: boolean;
+  }>;
+  attachments?: unknown[];
+}
+
+export type ParsedTurnBody =
+  | { ok: true; body: TurnBody }
+  | { ok: false; status: 400; message: string };
+
+const reject = (message: string): ParsedTurnBody => ({
+  ok: false,
+  status: 400,
+  message,
+});
+
+/** Parse and validate a raw request body. Never throws. */
+export function parseTurnBody(raw: string): ParsedTurnBody {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return reject('Invalid JSON body');
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return reject('Request body must be a JSON object');
+  }
+  const record = parsed as Record<string, unknown>;
+  const unknownProp = Object.keys(record).find((k) => !TURN_BODY_KEYS.has(k));
+  if (unknownProp !== undefined) {
+    return reject(`property ${unknownProp} should not exist`);
+  }
+  if (typeof record.message !== 'string' || record.message.length === 0) {
+    return reject('message is required');
+  }
+  return { ok: true, body: record as unknown as TurnBody };
+}

package/src/do/turn-metadata.ts

@@ -0,0 +1,146 @@
+/**
+ * Request `metadata` → agent state, the Node runtime's `agent-builder` rules:
+ *
+ *  - `editorRoomId` / `spaceId` / `currentEntityDid` update the thread's
+ *    checkpointed value when the request carries them, otherwise the prior
+ *    value stands;
+ *  - `sessionRunId` follows the room: a request that names the editor room
+ *    also defines its session run, and "no run" must not fall back to one
+ *    remembered from an earlier flow — so it is written whenever
+ *    `editorRoomId` is, even as `undefined`;
+ *  - an active editor context (room or space, from the request or the
+ *    checkpoint) seeds the editor plugin into `loadedPlugins`, so its tools
+ *    pass the capability gate without an explicit `load_capability` step.
+ *
+ * Metadata crosses the Durable Object boundary as a JSON string; only string
+ * values are honoured, anything else is ignored.
+ */
+
+export const EDITOR_PLUGIN_NAME = 'editor';
+
+export interface TurnMetadata {
+  editorRoomId?: string;
+  spaceId?: string;
+  sessionRunId?: string;
+  currentEntityDid?: string;
+}
+
+const KEYS = [
+  'editorRoomId',
+  'spaceId',
+  'sessionRunId',
+  'currentEntityDid',
+] as const;
+
+export function parseTurnMetadata(json: string | undefined): TurnMetadata {
+  if (!json) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    return {};
+  const record: Record<string, unknown> = { ...parsed };
+  const out: TurnMetadata = {};
+  for (const key of KEYS) {
+    const value = record[key];
+    if (typeof value === 'string' && value.length > 0) out[key] = value;
+  }
+  return out;
+}
+
+/** The checkpointed values the mapping falls back to. */
+export interface PriorMetadataState {
+  editorRoomId?: string;
+  spaceId?: string;
+  sessionRunId?: string;
+  currentEntityDid?: string;
+  loadedPlugins?: string[];
+}
+
+function priorString(
+  prior: Record<string, unknown>,
+  key: keyof PriorMetadataState,
+): string | undefined {
+  const value = prior[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function priorMetadataState(
+  prior: Record<string, unknown>,
+): PriorMetadataState {
+  const loaded = prior['loadedPlugins'];
+  return {
+    editorRoomId: priorString(prior, 'editorRoomId'),
+    spaceId: priorString(prior, 'spaceId'),
+    sessionRunId: priorString(prior, 'sessionRunId'),
+    currentEntityDid: priorString(prior, 'currentEntityDid'),
+    ...(Array.isArray(loaded)
+      ? { loadedPlugins: loaded.filter((p) => typeof p === 'string') }
+      : {}),
+  };
+}
+
+export function editorContextActive(
+  meta: TurnMetadata,
+  prior: PriorMetadataState,
+): boolean {
+  return Boolean(
+    (meta.editorRoomId ?? prior.editorRoomId) ||
+    (meta.spaceId ?? prior.spaceId),
+  );
+}
+
+/** Fields for the build-time state (`history.state`): request over checkpoint. */
+export function metadataBuildState(
+  meta: TurnMetadata,
+  prior: PriorMetadataState,
+): {
+  editorRoomId?: string;
+  sessionRunId?: string;
+  spaceId?: string;
+  currentEntityDid?: string;
+  loadedPlugins: string[];
+} {
+  const loaded = prior.loadedPlugins ?? [];
+  return {
+    editorRoomId: meta.editorRoomId ?? prior.editorRoomId,
+    sessionRunId:
+      meta.editorRoomId !== undefined ? meta.sessionRunId : prior.sessionRunId,
+    spaceId: meta.spaceId ?? prior.spaceId,
+    currentEntityDid: meta.currentEntityDid ?? prior.currentEntityDid,
+    loadedPlugins: editorContextActive(meta, prior)
+      ? Array.from(new Set([...loaded, EDITOR_PLUGIN_NAME]))
+      : loaded,
+  };
+}
+
+/** Fields for the graph input: only what THIS request carries is written. */
+export function metadataGraphInput(
+  meta: TurnMetadata,
+  prior: PriorMetadataState,
+): {
+  editorRoomId?: string;
+  sessionRunId?: string;
+  spaceId?: string;
+  currentEntityDid?: string;
+  loadedPlugins?: string[];
+} {
+  return {
+    ...(meta.editorRoomId !== undefined && {
+      editorRoomId: meta.editorRoomId,
+      // Written even when undefined so a room without a run clears the
+      // checkpointed run id rather than keeping a stale one.
+      sessionRunId: meta.sessionRunId,
+    }),
+    ...(meta.spaceId !== undefined && { spaceId: meta.spaceId }),
+    ...(meta.currentEntityDid !== undefined && {
+      currentEntityDid: meta.currentEntityDid,
+    }),
+    ...(editorContextActive(meta, prior) && {
+      loadedPlugins: [EDITOR_PLUGIN_NAME],
+    }),
+  };
+}