@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/delivery/shaper.ts

@@ -0,0 +1,389 @@
+/**
+ * The deterministic shaper: one model step's Markdown → chat messages, or a
+ * spill (lead message, artefact, closing question) when the step is too long
+ * or too structured for chat. No model call; the same input always gives the
+ * same output, which is what makes a Reply Plan safe to rebuild on recovery.
+ */
+import { marked, type Token, type Tokens } from 'marked';
+import type { ChatLimits } from './types';
+
+export interface SpillShape {
+  title: string;
+  /** The whole step as the model wrote it: the artefact's content. */
+  markdown: string;
+  /** What stays in chat: the first block, or a list's lead-in and first items. */
+  lead: string;
+  /** The step's closing question, kept as its own message after the link. */
+  closing?: string;
+}
+
+export type StepShape =
+  | { kind: 'messages'; messages: string[] }
+  | { kind: 'spill'; spill: SpillShape };
+
+type BlockKind = 'heading' | 'paragraph' | 'list' | 'code' | 'table' | 'quote';
+
+interface Block {
+  kind: BlockKind;
+  md: string;
+  token: Token;
+}
+
+const TITLE_MAX = 60;
+
+const isHeading = (t: Token): t is Tokens.Heading => t.type === 'heading';
+const isList = (t: Token): t is Tokens.List => t.type === 'list';
+const isCode = (t: Token): t is Tokens.Code => t.type === 'code';
+const isTable = (t: Token): t is Tokens.Table => t.type === 'table';
+const isHtml = (t: Token): t is Tokens.HTML => t.type === 'html';
+
+const sentenceSegmenter = new Intl.Segmenter(undefined, {
+  granularity: 'sentence',
+});
+
+/**
+ * HTML elements a model mixes into Markdown. Anything else in angle brackets
+ * (`Promise<string>`, `<name>` placeholders) is text and stays.
+ */
+const HTML_ELEMENTS = new Set(
+  (
+    'a abbr address article aside b bdi bdo blockquote body br button ' +
+    'caption center cite code col colgroup dd del details dfn div dl dt ' +
+    'em figcaption figure font footer form h1 h2 h3 h4 h5 h6 head ' +
+    'header hr html i iframe img input ins kbd label li main mark nav ' +
+    'ol p picture pre q s samp script section select small source span ' +
+    'strike strong style sub summary sup table tbody td textarea tfoot ' +
+    'th thead tr tt u ul var video wbr'
+  ).split(' '),
+);
+
+/**
+ * Raw HTML → its text: HTML elements' tags and comments removed, `<br>` a
+ * line break. Only ever applied to what the lexer read as raw HTML, never to
+ * code. `a < b and c > d` is left alone.
+ */
+function stripHtmlTags(html: string): string {
+  return html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(
+      /<\/?([a-zA-Z][a-zA-Z0-9-]*)(\s[^<>]*)?\/?>/g,
+      (tag, name: string) => (HTML_ELEMENTS.has(name.toLowerCase()) ? '' : tag),
+    );
+}
+
+/** Characters that render as nothing: whitespace and zero-width marks. */
+const INVISIBLE = /[\s\u200B-\u200D\u2060\uFEFF]/g;
+
+/** True when a message would look empty: only whitespace or zero-width characters. */
+export function isBlank(text: string): boolean {
+  return text.replace(INVISIBLE, '') === '';
+}
+
+function childTokens(token: Token): Token[] {
+  if (isList(token)) return token.items;
+  return 'tokens' in token && Array.isArray(token.tokens) ? token.tokens : [];
+}
+
+const isLinkOrImage = (t: Token): t is Tokens.Link | Tokens.Image =>
+  t.type === 'link' || t.type === 'image';
+
+/** `[text][ref]`, `[text][]` or `[ref]`, inline: its definition is not delivered. */
+function referenceLinkInline(token: Token): string | null {
+  if (!isLinkOrImage(token) || token.raw.endsWith(')')) return null;
+  const image = token.type === 'image';
+  if (!token.raw.startsWith(image ? '![' : '[')) return null;
+  const title = token.title ? ` "${token.title.replace(/"/g, '\\"')}"` : '';
+  return `${image ? '!' : ''}[${token.text}](${token.href}${title})`;
+}
+
+/**
+ * A block's Markdown for chat: `token.raw` with raw HTML reduced to its text
+ * and reference links written inline (their definitions are not delivered).
+ * Code spans and code blocks stay verbatim, so `` `<div>` `` survives.
+ */
+function chatMarkdown(token: Token): string {
+  const raw = token.raw;
+  const edits: Array<{ start: number; end: number; text: string }> = [];
+  let cursor = 0;
+  const locate = (part: string): number => {
+    const at = part ? raw.indexOf(part, cursor) : -1;
+    if (at >= 0) cursor = at + part.length;
+    return at;
+  };
+  const visit = (node: Token): void => {
+    if (node.type === 'code' || node.type === 'codespan') {
+      locate(node.raw);
+      return;
+    }
+    const inline = referenceLinkInline(node);
+    const replacement = node.type === 'html' ? stripHtmlTags(node.raw) : inline;
+    if (replacement !== null) {
+      const at = locate(node.raw);
+      if (at >= 0)
+        edits.push({ start: at, end: at + node.raw.length, text: replacement });
+      return;
+    }
+    const children = childTokens(node);
+    if (children.length === 0) locate(node.raw);
+    else for (const child of children) visit(child);
+  };
+  for (const child of childTokens(token)) visit(child);
+  let out = '';
+  let from = 0;
+  for (const edit of edits) {
+    out += raw.slice(from, edit.start) + edit.text;
+    from = edit.end;
+  }
+  return out + raw.slice(from);
+}
+
+function plainText(text: string): string {
+  return stripHtmlTags(text)
+    .replace(/[*_`#>~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function tableAsList(table: Tokens.Table): string {
+  return table.rows
+    .map((row) => {
+      const [first, ...rest] = row.map((cell) => cell.text.trim());
+      const pairs = rest.map((value, i) => {
+        const header = table.header[i + 1]?.text.trim();
+        return header ? `${header}: ${value}` : value;
+      });
+      return `- **${first ?? ''}**${pairs.length ? ` · ${pairs.join(' · ')}` : ''}`;
+    })
+    .join('\n');
+}
+
+function toBlocks(markdown: string, limits: ChatLimits): Block[] {
+  const blocks: Block[] = [];
+  for (const token of marked.lexer(markdown)) {
+    if (token.type === 'space' || token.type === 'hr' || token.type === 'def')
+      continue;
+    if (isHeading(token)) {
+      const text = plainText(token.text);
+      if (text) blocks.push({ kind: 'heading', md: `**${text}**`, token });
+    } else if (isList(token)) {
+      blocks.push({ kind: 'list', md: chatMarkdown(token).trim(), token });
+    } else if (isCode(token)) {
+      blocks.push({ kind: 'code', md: token.raw.trim(), token });
+    } else if (isTable(token)) {
+      blocks.push({
+        kind: 'table',
+        md: limits.tables ? token.raw.trim() : tableAsList(token),
+        token,
+      });
+    } else if (token.type === 'blockquote') {
+      blocks.push({ kind: 'quote', md: chatMarkdown(token).trim(), token });
+    } else {
+      const md = (
+        isHtml(token) ? stripHtmlTags(token.text) : chatMarkdown(token)
+      ).trim();
+      if (!isBlank(md)) blocks.push({ kind: 'paragraph', md, token });
+    }
+  }
+  return blocks;
+}
+
+function sentencesOf(text: string): string[] {
+  return Array.from(sentenceSegmenter.segment(text), (s) => s.segment);
+}
+
+function packPieces(
+  pieces: string[],
+  separator: string,
+  max: number,
+): string[] {
+  const out: string[] = [];
+  let current = '';
+  for (const piece of pieces) {
+    const candidate = current ? current + separator + piece : piece;
+    if (candidate.length <= max) {
+      current = candidate;
+      continue;
+    }
+    if (current) out.push(current);
+    if (piece.length > max) {
+      out.push(...splitText(piece, max));
+      current = '';
+    } else current = piece;
+  }
+  if (current) out.push(current);
+  return out.map((s) => s.trim()).filter((s) => !isBlank(s));
+}
+
+/** Split at the largest boundary that works: paragraph, line, sentence, word. */
+export function splitText(text: string, max: number): string[] {
+  // A size below one character would never move through the text.
+  const size = Number.isFinite(max) && max >= 1 ? Math.floor(max) : 1;
+  if (text.length <= size) return [text];
+  for (const separator of ['\n\n', '\n']) {
+    const pieces = text.split(separator);
+    if (pieces.length > 1) return packPieces(pieces, separator, size);
+  }
+  const sentences = sentencesOf(text);
+  if (sentences.length > 1) return packPieces(sentences, '', size);
+  const words = text.split(/(?<=\s)/);
+  if (words.length > 1) return packPieces(words, '', size);
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += size) out.push(text.slice(i, i + size));
+  return out;
+}
+
+/** A code block too long for one message is re-fenced per piece. */
+function splitBlock(block: Block, max: number): string[] {
+  if (block.md.length <= max) return [block.md];
+  if (isCode(block.token)) {
+    const fence = '```' + (block.token.lang ?? '');
+    const room = max - fence.length - 5;
+    if (room >= 1)
+      return splitText(block.token.text, room).map(
+        (piece) => `${fence}\n${piece}\n\`\`\``,
+      );
+  }
+  return splitText(block.md, max);
+}
+
+function trimToSentence(text: string, max: number): string {
+  if (text.length <= max) return text;
+  let out = '';
+  for (const sentence of sentencesOf(text)) {
+    if ((out + sentence).length > max) break;
+    out += sentence;
+  }
+  if (out.trim()) return out.trim();
+  const cut = text.slice(0, max - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+function titleOf(text: string): string {
+  const plain = plainText(sentencesOf(text)[0] ?? text).replace(/[:.]$/, '');
+  if (plain.length <= TITLE_MAX) return plain;
+  const cut = plain.slice(0, TITLE_MAX - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > TITLE_MAX / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+function firstLine(text: string): string {
+  return (text.split('\n')[0] ?? '').trim();
+}
+
+function preview(list: Tokens.List, count: number): string {
+  const start = typeof list.start === 'number' ? list.start : 1;
+  const items = list.items
+    .slice(0, count)
+    .map(
+      (item, i) =>
+        `${list.ordered ? `${start + i}.` : '-'} ${firstLine(item.text)}`,
+    );
+  const more = list.items.length - count;
+  return items.join('\n') + (more > 0 ? `\n…and ${more} more` : '');
+}
+
+const endsWithColon = (md: string): boolean => /:\s*$/.test(md);
+const joinBlocks = (a: string, b: string): string => (a ? `${a}\n\n${b}` : b);
+
+/** Blocks → messages: headings and "…:" lead-ins stay with what follows. */
+function pack(blocks: Block[], limits: ChatLimits): string[] {
+  const units: string[] = [];
+  let carry = '';
+  blocks.forEach((block, i) => {
+    const next = blocks[i + 1];
+    const leadIn =
+      block.kind === 'paragraph' &&
+      endsWithColon(block.md) &&
+      next !== undefined &&
+      (next.kind === 'list' || next.kind === 'code' || next.kind === 'table');
+    if (block.kind === 'heading' || leadIn) {
+      carry = joinBlocks(carry, block.md);
+      return;
+    }
+    const pieces = splitBlock(block, limits.bubbleMax);
+    pieces.forEach((piece, j) => {
+      units.push(j === 0 ? joinBlocks(carry, piece) : piece);
+    });
+    carry = '';
+  });
+  if (carry) units.push(carry);
+  const merged: string[] = [];
+  for (let i = 0; i < units.length; i++) {
+    const unit = units[i]!;
+    if (unit.length < limits.minBubble && i + 1 < units.length)
+      units[i + 1] = joinBlocks(unit, units[i + 1]!);
+    else merged.push(unit);
+  }
+  return merged;
+}
+
+function spillOf(
+  markdown: string,
+  blocks: Block[],
+  limits: ChatLimits,
+): SpillShape {
+  const heading = blocks.find((b) => b.kind === 'heading');
+  const content = blocks.filter((b) => b.kind !== 'heading');
+  const [first, second] = content;
+  let lead = '';
+  if (first && isList(first.token))
+    lead = preview(first.token, limits.previewItems);
+  else if (
+    first?.kind === 'paragraph' &&
+    endsWithColon(first.md) &&
+    second &&
+    isList(second.token)
+  )
+    lead = joinBlocks(first.md, preview(second.token, limits.previewItems));
+  else if (first && (first.kind === 'paragraph' || first.kind === 'quote'))
+    lead = trimToSentence(first.md, limits.bubbleTarget);
+  const last = content.at(-1);
+  const closing =
+    last &&
+    last !== first &&
+    last.kind === 'paragraph' &&
+    /\?\s*$/.test(last.md) &&
+    last.md.length <= limits.bubbleMax
+      ? last.md
+      : undefined;
+  const titleSource =
+    heading?.md ?? (first?.kind === 'paragraph' ? first.md : undefined);
+  return {
+    title: (titleSource && titleOf(titleSource)) || 'Details',
+    markdown,
+    lead,
+    ...(closing ? { closing } : {}),
+  };
+}
+
+/**
+ * Shape one model step for a chat surface. With `canSpill` false (no
+ * artefact storage configured) the step is always split into messages:
+ * tables become lists and nothing is dropped.
+ */
+export function shapeStep(
+  markdown: string,
+  limits: ChatLimits,
+  canSpill: boolean,
+): StepShape {
+  const blocks = toBlocks(markdown.trim(), limits);
+  const messages = pack(blocks, limits);
+  if (!canSpill) return { kind: 'messages', messages };
+  const length = blocks.reduce((n, b) => n + b.md.length + 2, 0);
+  const tooStructured = blocks.some(
+    (b) =>
+      (b.kind === 'table' && !limits.tables) ||
+      (isCode(b.token) &&
+        b.token.text.split('\n').length > limits.maxCodeLines) ||
+      (isList(b.token) && b.token.items.length > limits.maxListItems),
+  );
+  if (
+    length > limits.spillChars ||
+    tooStructured ||
+    messages.length > limits.maxBubbles
+  )
+    return { kind: 'spill', spill: spillOf(markdown.trim(), blocks, limits) };
+  return { kind: 'messages', messages };
+}

package/src/delivery/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Chat delivery: how a finished turn reaches a chat surface (an IXO Channels
+ * provider such as WhatsApp, or a Matrix room) as a few short messages and
+ * artefact links instead of the one streamed document the Portal renders.
+ *
+ * Plain data only. The Matrix gateway script imports these types without the
+ * agent core, and IXO Channels reads the same shapes off `/channels/turn`.
+ */
+
+/** Size and shape limits the shaper enforces on one chat surface. */
+export interface ChatLimits {
+  /** Soft size of one message, in characters. */
+  bubbleTarget: number;
+  /** Hard size of one message before it is split at a sentence boundary. */
+  bubbleMax: number;
+  /** Fragments shorter than this merge into the message that follows. */
+  minBubble: number;
+  /** Messages one model step may become before it moves to an artefact. */
+  maxBubbles: number;
+  /**
+   * Parts one run delivers at most, met by merging text within `bubbleMax`
+   * and dropping spill framing. Text found nowhere else is never dropped.
+   */
+  maxPartsPerRun: number;
+  /** A step longer than this moves to an artefact. */
+  spillChars: number;
+  /** A longer list moves to an artefact, previewed by its first items. */
+  maxListItems: number;
+  /** List items kept in the message when a list moves to an artefact. */
+  previewItems: number;
+  /** A longer code block moves to an artefact. */
+  maxCodeLines: number;
+  /** Whether a Markdown table may stay inside a message. */
+  tables: boolean;
+}
+
+/**
+ * How one turn's reply is delivered. `stream` is the Portal: SSE frames,
+ * nothing reshaped. `chat` builds a Reply Plan under `limits`.
+ */
+export type DeliveryProfile =
+  | { kind: 'stream' }
+  | {
+      kind: 'chat';
+      /** `whatsapp`, `telegram`, `slack`, `matrix` or `generic`. */
+      surface: string;
+      /** How the prompt names the surface: "WhatsApp", "a Matrix chat room". */
+      label: string;
+      limits: ChatLimits;
+    };
+
+/** A browser-openable document delivered as a link. */
+export interface ArtifactRef {
+  artifactId: string;
+  title: string;
+  /**
+   * Viewer link. Its decryption key sits after `#`, so R2 and the viewer host
+   * never receive it; the oracle stores it with the user's data.
+   */
+  url: string;
+  mime: 'text/markdown';
+  bytes: number;
+  expiresAt: string;
+}
+
+/**
+ * One delivery unit. `text` carries chat Markdown: bold, italic, strike,
+ * inline code, fenced code, `-` and `1.` lists, `>` quotes and links. No
+ * headings, tables or raw HTML reach a text part.
+ */
+export type ReplyPart =
+  | { partId: string; kind: 'text'; text: string }
+  | { partId: string; kind: 'artifact'; artifact: ArtifactRef };
+
+/** A part before it is numbered: what a plan is assembled from. */
+export type ReplyContent =
+  | { kind: 'text'; text: string }
+  | { kind: 'artifact'; artifact: ArtifactRef };
+
+/** What a chat surface delivers for one finished run, in delivery order. */
+export interface ReplyPlan {
+  v: 1;
+  parts: ReplyPart[];
+}

package/src/do/ambient.ts

@@ -12,6 +12,7 @@
  *  - emit      → routed to the SSE writer of the turn that owns the
  *                payload's `sessionId` (same shape as the Node `wsEmitter`).
  */
+import type { DecisionEvaluator } from '@ixo/common/ai/decisions';
 import type {
   AmbientServices,
   DelegationLike,
@@ -19,12 +20,16 @@ import type {
   RawEventPayload,
   SecretsAdapter,
 } from '../core/runtime-context';
-import type { LlmAdapter } from '../core/runtime-context';
+import {
+  delegationHasCapability,
+  type LlmAdapter,
+} from '../core/runtime-context';
 import type {
   Logger,
   MatrixEvent,
   OracleIdentity,
   RoomStateSnapshot,
+  UserKvSurface,
 } from '../plugin-api/types';
 import type { MatrixGatewayObject } from './contracts';
 import { type WorkersUcanService } from './ucan-service';
@@ -127,6 +132,44 @@ export function createBlobStore(
   };
 }
 
+/** Keys one blob sweep call reads at most (one `storage.list` page). */
+export const BLOB_SWEEP_PAGE = 128;
+
+/**
+ * Delete expired blobs (a plugin may store one and never read it back; a
+ * read deletes an expired blob, nothing else does). Bounded: one call reads
+ * at most `limit` entries in key order after `startAfter`, deletes the
+ * expired ones, and returns where the next call continues (`next`), or
+ * `null` once the end of the `blob:` keys was reached.
+ */
+export async function sweepExpiredBlobs(
+  storage: Pick<DurableObjectStorage, 'list' | 'delete'>,
+  options: { startAfter?: string; limit?: number; now?: number } = {},
+): Promise<{ deleted: number; next: string | null }> {
+  const limit = Math.max(1, Math.min(options.limit ?? BLOB_SWEEP_PAGE, 128));
+  const now = options.now ?? Date.now();
+  const page = await storage.list<{ expiresAt?: unknown }>({
+    prefix: 'blob:',
+    limit,
+    ...(options.startAfter !== undefined
+      ? { startAfter: options.startAfter }
+      : {}),
+  });
+  const expired: string[] = [];
+  let last: string | null = null;
+  for (const [key, entry] of page) {
+    last = key;
+    const expiresAt = entry?.expiresAt;
+    if (typeof expiresAt !== 'number' || expiresAt <= now) expired.push(key);
+  }
+  // `delete` takes at most 128 keys, the page size cap.
+  if (expired.length > 0) await storage.delete(expired);
+  return {
+    deleted: expired.length,
+    next: page.size < limit ? null : last,
+  };
+}
+
 export function createMatrixAdapter(
   gateway: DurableObjectStub<MatrixGatewayObject>,
 ): AmbientServices['matrix'] {
@@ -183,25 +226,12 @@ export function createMatrixAdapter(
   };
 }
 
-function abilityCovers(granted: string, required: string): boolean {
-  if (granted === '*' || granted === required) return true;
-  if (granted.endsWith('/*')) {
-    const ns = granted.slice(0, -2);
-    return required === ns || required.startsWith(`${ns}/`);
-  }
-  return false;
-}
-
 export function createUcanAdapter(
   service: WorkersUcanService,
   delegationFor: (userDid: string) => { raw?: string } | undefined,
 ): AmbientServices['ucan'] {
   const has = (delegation: DelegationLike, resource: string, action: string) =>
-    (delegation?.capabilities ?? []).some(
-      (c) =>
-        (c.resource === resource || c.resource.startsWith(resource)) &&
-        abilityCovers(c.action, action),
-    );
+    delegationHasCapability(delegation, resource, action);
   return {
     hasCapability: has,
     requireCapability: (delegation, resource, action) => {
@@ -239,6 +269,8 @@ export interface CreateAmbientInput {
   /** Host task scheduler surface for this user, when tasks are enabled. */
   tasks?: import('../plugin-api/types').OracleTasksSurface;
   preferences?: import('../plugin-api/types').UserPreferencesSurface;
+  /** `ctx.kv` over the user's working copy (`SqliteUserKv`). */
+  kv?: UserKvSurface;
   /** Host bridge to the user's browser (realtime channel), when terminated here. */
   frontend?: import('../plugin-api/types').FrontendCallSurface;
   /** Per-turn cleanup registry (see `RuntimeContext.onTurnEnd`). */
@@ -249,6 +281,8 @@ export interface CreateAmbientInput {
   identity: OracleIdentity;
   availablePlugins: ReadonlySet<string>;
   llm: LlmAdapter;
+  /** The core's Decision evaluator (`RuntimeCore.decisions`), behind `ctx.decisions`. */
+  decisions?: DecisionEvaluator;
   logger: Logger;
   storage: DurableObjectStorage;
   gateway: DurableObjectStub<MatrixGatewayObject>;
@@ -269,6 +303,7 @@ export function createAmbientServices(
   return {
     ...(input.tasks ? { tasks: input.tasks } : {}),
     ...(input.preferences ? { preferences: input.preferences } : {}),
+    ...(input.kv ? { kv: input.kv } : {}),
     ...(input.frontend ? { frontend: input.frontend } : {}),
     ...(input.onTurnEnd ? { onTurnEnd: input.onTurnEnd } : {}),
     ...(input.background ? { background: input.background } : {}),
@@ -276,6 +311,7 @@ export function createAmbientServices(
     identity: input.identity,
     availablePlugins: input.availablePlugins,
     llm: input.llm,
+    ...(input.decisions ? { decisions: input.decisions } : {}),
     logger: input.logger,
     emit: input.events,
     blobStore: createBlobStore(input.storage),