@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/delivery/plan.ts

@@ -0,0 +1,278 @@
+/**
+ * A finished run → its Reply Plan. Built once, when the run finishes, from
+ * the turn's own messages (the model's checkpointed history is never
+ * rewritten; the plan is a projection of it for one chat surface):
+ *
+ *  - every model step with text is delivered in order, not only the last
+ *    one; a short line of narration before a tool call ("Checking your
+ *    calendar.") is dropped when a later step speaks to the user, because
+ *    the typing indicator already says so — a step whose short text is the
+ *    whole answer ("Your flight is 9:40." + a memory save) keeps it;
+ *  - each step goes through the shaper, which may spill it to an artefact;
+ *  - a `create_artifact` call becomes its message, the link, its question.
+ */
+import {
+  AIMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
+import { contentToText } from '../do/transcript';
+import { CREATE_ARTIFACT_TOOL, createArtifactParts } from '../artifacts/tool';
+import { isBlank, shapeStep, type SpillShape } from './shaper';
+import type {
+  ArtifactRef,
+  ChatLimits,
+  ReplyContent,
+  ReplyPart,
+  ReplyPlan,
+} from './types';
+
+export interface TurnStep {
+  text: string;
+  toolCalls: Array<{ id: string; name: string; args: unknown }>;
+}
+
+export type DraftPart =
+  | ReplyContent
+  | { kind: 'spill'; key: string; spill: SpillShape };
+
+const NARRATION_MAX_CHARS = 200;
+
+/** The model steps of the turn that ended the thread, with its tool results. */
+export function turnSteps(messages: readonly BaseMessage[]): {
+  steps: TurnStep[];
+  toolResults: Map<string, string>;
+} {
+  let start = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.type === 'human') {
+      start = i + 1;
+      break;
+    }
+  }
+  const steps: TurnStep[] = [];
+  const toolResults = new Map<string, string>();
+  for (const message of messages.slice(start)) {
+    if (ToolMessage.isInstance(message)) {
+      toolResults.set(message.tool_call_id, contentToText(message.content));
+      continue;
+    }
+    // Extraction-lane attachment text rides as hidden AI messages.
+    if (!AIMessage.isInstance(message) || message.additional_kwargs?.attachment)
+      continue;
+    steps.push({
+      text: contentToText(message.content).trim(),
+      toolCalls: (message.tool_calls ?? []).map((call) => ({
+        id: call.id ?? '',
+        name: call.name,
+        args: call.args,
+      })),
+    });
+  }
+  return { steps, toolResults };
+}
+
+/** One short paragraph of prose: what a model says before it calls a tool. */
+export function isNarration(text: string): boolean {
+  return (
+    text.length <= NARRATION_MAX_CHARS &&
+    !text.includes('\n\n') &&
+    !text.includes('```') &&
+    !/^\s*([-*+]|\d+[.)])\s/m.test(text)
+  );
+}
+
+/**
+ * What a resumed run still has to deliver of `continuation`, the text it
+ * streamed before the reset. That text starts with the steps the checkpoint
+ * kept, verbatim, and those steps are in `steps` already; the rest was cut
+ * off mid-step and belongs in front of the first step after them, or after
+ * the last step when the checkpoint kept every step.
+ */
+function pendingContinuation(
+  continuation: string,
+  steps: readonly TurnStep[],
+): { text: string; step: number; after: boolean } {
+  let rest = continuation;
+  let step = 0;
+  for (const { text } of steps) {
+    const trimmed = rest.trimStart();
+    if (!trimmed.startsWith(text)) break;
+    rest = trimmed.slice(text.length);
+    step++;
+  }
+  return step < steps.length
+    ? { text: rest, step, after: false }
+    : { text: rest, step: steps.length - 1, after: true };
+}
+
+/**
+ * The plan before any artefact exists: spills are still drafts. `continuation`
+ * is the text a run had streamed before a reset (see `pendingContinuation`);
+ * a run with no step of its own delivers it alone.
+ */
+export function draftReplyPlan(input: {
+  steps: TurnStep[];
+  toolResults: ReadonlyMap<string, string>;
+  continuation?: string | null;
+  limits: ChatLimits;
+  canSpill: boolean;
+}): DraftPart[] {
+  const parts: DraftPart[] = [];
+  const steps =
+    input.steps.length > 0 || !input.continuation
+      ? input.steps
+      : [{ text: input.continuation.trim(), toolCalls: [] }];
+  const pending =
+    input.continuation && input.steps.length > 0
+      ? pendingContinuation(input.continuation, input.steps)
+      : null;
+  const texts = steps.map((step, i) => {
+    if (!pending || i !== pending.step || isBlank(pending.text))
+      return step.text;
+    return (
+      pending.after
+        ? `${step.text}${pending.text}`
+        : `${pending.text}${step.text}`
+    ).trim();
+  });
+  // Whether the reply goes on after a step's text: a later step with text,
+  // or a `create_artifact` call (its message follows, even in the same step).
+  // Only then is a short line before a tool call narration to drop.
+  const createsArtifact = steps.map((step) =>
+    step.toolCalls.some((call) => call.name === CREATE_ARTIFACT_TOOL),
+  );
+  const saysMore: boolean[] = [];
+  let later = false;
+  for (let i = steps.length - 1; i >= 0; i--) {
+    saysMore[i] = later || createsArtifact[i] === true;
+    later ||= !isBlank(texts[i] ?? '') || createsArtifact[i] === true;
+  }
+  steps.forEach((step, i) => {
+    const text = texts[i] ?? '';
+    const narration =
+      step.toolCalls.length > 0 && saysMore[i] === true && isNarration(text);
+    if (!isBlank(text) && !narration) {
+      const shape = shapeStep(text, input.limits, input.canSpill);
+      if (shape.kind === 'messages')
+        parts.push(
+          ...shape.messages.map((m) => ({ kind: 'text' as const, text: m })),
+        );
+      else parts.push({ kind: 'spill', key: `step-${i}`, spill: shape.spill });
+    }
+    for (const call of step.toolCalls)
+      if (call.name === CREATE_ARTIFACT_TOOL)
+        parts.push(
+          ...createArtifactParts(call.args, input.toolResults.get(call.id)),
+        );
+  });
+  return parts;
+}
+
+/**
+ * A part before it is numbered. `framing` marks a spill's lead or closing
+ * question: its artefact holds the same text.
+ */
+type PlanPart = ReplyContent & { framing?: boolean };
+
+/**
+ * Over the run's cap: merge the shortest neighbouring messages while the
+ * result stays within `bubbleMax`, then drop spill framing, keeping the
+ * reply's last part for as long as possible. Order is kept, and text that
+ * exists nowhere else is never dropped: a reply with several documents, or a
+ * long one without artefact storage, can stay over the cap.
+ */
+function capParts(parts: PlanPart[], limits: ChatLimits): ReplyContent[] {
+  const out = [...parts];
+  const merge = (): boolean => {
+    let best = -1;
+    let bestLength = Infinity;
+    for (let i = 0; i + 1 < out.length; i++) {
+      const a = out[i];
+      const b = out[i + 1];
+      if (a?.kind !== 'text' || b?.kind !== 'text') continue;
+      const length = a.text.length + 2 + b.text.length;
+      if (length <= limits.bubbleMax && length < bestLength) {
+        best = i;
+        bestLength = length;
+      }
+    }
+    const a = out[best];
+    const b = out[best + 1];
+    if (a?.kind !== 'text' || b?.kind !== 'text') return false;
+    out.splice(best, 2, {
+      kind: 'text',
+      text: `${a.text}\n\n${b.text}`,
+      framing: a.framing === true && b.framing === true,
+    });
+    return true;
+  };
+  const dropFraming = (): boolean => {
+    const framing = out.flatMap((part, i) => (part.framing ? [i] : []));
+    const i = framing.find((index) => index < out.length - 1) ?? framing[0];
+    if (i === undefined) return false;
+    out.splice(i, 1);
+    return true;
+  };
+  while (out.length > limits.maxPartsPerRun) {
+    if (!merge() && !dropFraming()) break;
+  }
+  return out.map(
+    (part): ReplyContent =>
+      part.kind === 'text'
+        ? { kind: 'text', text: part.text }
+        : { kind: 'artifact', artifact: part.artifact },
+  );
+}
+
+/**
+ * Turn spill drafts into artefacts. A spill whose artefact cannot be created
+ * falls back to plain messages: the reply is never lost to a storage error.
+ */
+export async function materializeReplyPlan(
+  draft: DraftPart[],
+  options: {
+    limits: ChatLimits;
+    createSpill: (key: string, spill: SpillShape) => Promise<ArtifactRef>;
+    onSpillError?: (error: unknown) => void;
+  },
+): Promise<ReplyPlan> {
+  const parts: PlanPart[] = [];
+  for (const part of draft) {
+    if (part.kind !== 'spill') {
+      parts.push(part);
+      continue;
+    }
+    const ref = await options
+      .createSpill(part.key, part.spill)
+      .catch((error: unknown) => {
+        options.onSpillError?.(error);
+        return null;
+      });
+    if (ref) {
+      if (part.spill.lead)
+        parts.push({ kind: 'text', text: part.spill.lead, framing: true });
+      parts.push({ kind: 'artifact', artifact: ref });
+      if (part.spill.closing)
+        parts.push({ kind: 'text', text: part.spill.closing, framing: true });
+    } else {
+      const shape = shapeStep(part.spill.markdown, options.limits, false);
+      if (shape.kind === 'messages')
+        parts.push(
+          ...shape.messages.map((m) => ({ kind: 'text' as const, text: m })),
+        );
+    }
+  }
+  // A part that would look empty (only whitespace or zero-width characters)
+  // is never sent.
+  const capped = capParts(
+    parts.filter((part) => part.kind !== 'text' || !isBlank(part.text)),
+    options.limits,
+  );
+  return {
+    v: 1,
+    parts: capped.map(
+      (part, i): ReplyPart => ({ partId: `p${i + 1}`, ...part }),
+    ),
+  };
+}

package/src/delivery/profile.ts

@@ -0,0 +1,161 @@
+import type { TurnRequest } from '../do/contracts';
+import { TASK_SESSION_PREFIX } from '../tasks/scheduler';
+import type { ChatLimits, DeliveryProfile } from './types';
+
+/**
+ * `OracleConfig.delivery`: per-oracle tuning of chat delivery. Matrix room
+ * turns use the chat style only when `matrixChat` is `true` (off by default;
+ * `MATRIX_CHAT_DELIVERY` sets it per deployment); `limits` overrides the
+ * defaults below per surface (`whatsapp`, `telegram`, `slack`, `matrix`,
+ * `generic`).
+ */
+export interface DeliveryConfig {
+  matrixChat?: boolean;
+  limits?: Partial<Record<string, Partial<ChatLimits>>>;
+}
+
+const GENERIC: ChatLimits = {
+  bubbleTarget: 600,
+  bubbleMax: 1500,
+  minBubble: 60,
+  maxBubbles: 3,
+  maxPartsPerRun: 5,
+  spillChars: 1800,
+  maxListItems: 7,
+  previewItems: 3,
+  maxCodeLines: 12,
+  tables: false,
+};
+
+/**
+ * Well under each provider's hard limit (WhatsApp and Telegram 4,096
+ * characters, Slack 12,000 per message, Matrix 64 KiB per event): the
+ * gateway still enforces the hard limit, and never truncates.
+ */
+const DEFAULT_LIMITS: Readonly<Record<string, ChatLimits>> = {
+  generic: GENERIC,
+  whatsapp: { ...GENERIC, maxBubbles: 4, maxPartsPerRun: 6 },
+  telegram: {
+    ...GENERIC,
+    bubbleTarget: 800,
+    bubbleMax: 2000,
+    maxBubbles: 4,
+    maxPartsPerRun: 6,
+    spillChars: 2400,
+  },
+  slack: {
+    ...GENERIC,
+    bubbleTarget: 1200,
+    bubbleMax: 3000,
+    spillChars: 3500,
+  },
+  matrix: {
+    ...GENERIC,
+    bubbleTarget: 1200,
+    bubbleMax: 4000,
+    spillChars: 4000,
+  },
+};
+
+/** A group room hears one short answer, not a series. */
+const GROUP_LIMITS: Partial<ChatLimits> = { maxBubbles: 2, maxPartsPerRun: 3 };
+
+const COUNTS = [
+  'bubbleTarget',
+  'bubbleMax',
+  'minBubble',
+  'maxBubbles',
+  'maxPartsPerRun',
+  'spillChars',
+  'maxListItems',
+  'previewItems',
+  'maxCodeLines',
+] as const satisfies ReadonlyArray<keyof ChatLimits>;
+
+/**
+ * The overrides an oracle may set: whole numbers of at least 1, and a
+ * boolean `tables`. Anything else keeps the default, since a size of zero
+ * would leave the shaper nothing to split into.
+ */
+function validLimits(overrides: Partial<ChatLimits> = {}): Partial<ChatLimits> {
+  const out: Partial<ChatLimits> = {};
+  for (const key of COUNTS) {
+    const value = overrides[key];
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1)
+      out[key] = value;
+  }
+  if (typeof overrides.tables === 'boolean') out.tables = overrides.tables;
+  return out;
+}
+
+const LABELS: Readonly<Record<string, string>> = {
+  whatsapp: 'WhatsApp',
+  telegram: 'Telegram',
+  slack: 'Slack',
+  matrix: 'a Matrix chat room',
+  generic: 'a chat app',
+};
+
+/**
+ * `OracleConfig.delivery` with the deployment's `MATRIX_CHAT_DELIVERY` applied:
+ * the variable, when set, decides whether Matrix rooms use the chat style.
+ */
+export function deliveryConfigWithEnv(
+  config: DeliveryConfig | undefined,
+  matrixChatEnv: string | undefined,
+): DeliveryConfig {
+  return {
+    ...config,
+    matrixChat:
+      matrixChatEnv === 'true' || matrixChatEnv === 'false'
+        ? matrixChatEnv === 'true'
+        : config?.matrixChat === true,
+  };
+}
+
+/**
+ * The delivery profile of one turn, from where it came in. A scheduled task
+ * run streams whatever room it reports to: its result is stored and read
+ * later, so it keeps the model's whole text instead of a chat rendering with
+ * expiring links.
+ */
+export function resolveDeliveryProfile(
+  turn: Pick<TurnRequest, 'client' | 'channel' | 'roomKind'> &
+    Partial<Pick<TurnRequest, 'sessionId' | 'taskRunId'>>,
+  config: DeliveryConfig = {},
+): DeliveryProfile {
+  if (turn.client === 'portal') return { kind: 'stream' };
+  if (
+    turn.taskRunId !== undefined ||
+    turn.sessionId?.startsWith(TASK_SESSION_PREFIX)
+  )
+    return { kind: 'stream' };
+  if (turn.client === 'matrix' && config.matrixChat !== true)
+    return { kind: 'stream' };
+  const surface =
+    turn.client === 'matrix'
+      ? 'matrix'
+      : turn.channel?.provider && DEFAULT_LIMITS[turn.channel.provider]
+        ? turn.channel.provider
+        : 'generic';
+  const merged: ChatLimits = {
+    ...(DEFAULT_LIMITS[surface] ?? GENERIC),
+    ...(turn.client === 'matrix' && turn.roomKind === 'group'
+      ? GROUP_LIMITS
+      : {}),
+    ...validLimits(config.limits?.[surface]),
+  };
+  // The soft target and the merge threshold never exceed the hard size.
+  const bubbleTarget = Math.min(merged.bubbleTarget, merged.bubbleMax);
+  const limits: ChatLimits = {
+    ...merged,
+    bubbleTarget,
+    minBubble: Math.min(merged.minBubble, bubbleTarget),
+  };
+  return {
+    kind: 'chat',
+    surface,
+    label: LABELS[surface] ?? 'a chat app',
+    limits,
+  };
+}

package/src/delivery/prompt.ts

@@ -0,0 +1,27 @@
+import type { DeliveryProfile } from './types';
+
+/**
+ * The prompt section a chat turn gets: write for the surface. Empty on the
+ * Portal. `artifacts` says whether `create_artifact` is bound this turn.
+ */
+export function renderSurfaceSection(
+  profile: DeliveryProfile | undefined,
+  artifacts: boolean,
+): string {
+  if (!profile || profile.kind !== 'chat') return '';
+  const { label, limits } = profile;
+  return [
+    '## Where this conversation is happening',
+    '',
+    `You are replying in ${label}. The user reads your reply as chat messages, not as a document.`,
+    '',
+    '- Lead with the answer. Write like a sharp person texting: short sentences, no preamble, no sign-off.',
+    `- Aim for one to three short messages. A blank line starts a new message; keep each under about ${limits.bubbleTarget} characters.`,
+    `- No headings, tables or horizontal rules. Short lists (up to ${limits.maxListItems} items) and **bold** for the key fact are fine.`,
+    artifacts
+      ? '- Anything longer, such as a plan, report, comparison, draft, table or code, goes in `create_artifact`: the full Markdown as the document, a one-line message, and at most one follow-up question. The user gets the message, a link that opens the document in their browser, then the question.'
+      : '- When something is too long for chat, send the short version and offer the rest.',
+    '- The user sees a typing indicator while you work. Do not narrate your steps or announce tool calls.',
+    '- End with at most one question.',
+  ].join('\n');
+}

package/src/delivery/schema.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { ReplyContent, ReplyPlan } from './types';
+
+const ArtifactRefSchema = z.object({
+  artifactId: z.string(),
+  title: z.string(),
+  url: z.string(),
+  mime: z.literal('text/markdown'),
+  bytes: z.number(),
+  expiresAt: z.string(),
+});
+
+export const ReplyPlanSchema = z.object({
+  v: z.literal(1),
+  parts: z.array(
+    z.discriminatedUnion('kind', [
+      z.object({
+        partId: z.string(),
+        kind: z.literal('text'),
+        text: z.string(),
+      }),
+      z.object({
+        partId: z.string(),
+        kind: z.literal('artifact'),
+        artifact: ArtifactRefSchema,
+      }),
+    ]),
+  ),
+});
+
+/** A stored or transported plan, or null when it is absent or malformed. */
+export function parseReplyPlan(
+  json: string | null | undefined,
+): ReplyPlan | null {
+  if (!json) return null;
+  try {
+    const parsed = ReplyPlanSchema.safeParse(JSON.parse(json));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+function linkLabel(title: string): string {
+  return title.replace(/[[\]]/g, '');
+}
+
+/**
+ * The plan as one Markdown message: what the Companion room mirror of a
+ * channel turn and gateways that predate plans receive. Never stored as a
+ * run's text, which stays the model's own.
+ */
+export function planText(plan: { parts: readonly ReplyContent[] }): string {
+  return plan.parts
+    .map((part) =>
+      part.kind === 'text'
+        ? part.text
+        : `[${linkLabel(part.artifact.title)}](${part.artifact.url})`,
+    )
+    .join('\n\n');
+}