@ixo/oracle-runtime-workers 0.35.1 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.35.1",
+  "version": "0.36.1",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {

package/src/artifacts/tool.ts

@@ -21,16 +21,19 @@ export const CreateArtifactArgs = z.object({
     .string()
     .trim()
     .min(1)
-    .max(600)
+    // Room for the conclusions, decisions and next actions. It is delivered
+    // as its own text part before the link (a gateway splits a text part at
+    // its provider's limit, 4,096 on WhatsApp), never inside the link card.
+    .max(1000)
     .describe(
-      'One or two short sentences sent as the chat message before the link: the answer or the gist, not "here is the document".',
+      'The chat message sent before the document: the conclusions, decisions and next actions, so the user has them without opening the document. Not "here is the document".',
     ),
   followUp: z
     .string()
     .trim()
     .max(300)
     .optional()
-    .describe('At most one short question, sent after the link.'),
+    .describe('At most one short question, sent after the document.'),
 });
 
 /** What the tool returns; the Reply Plan reads it back off the ToolMessage. */
@@ -95,7 +98,7 @@ export function buildCreateArtifactTool(
     {
       name: CREATE_ARTIFACT_TOOL,
       description:
-        'Send the user a document they open in their browser, together with a short chat message. Use it for anything too long or too structured for chat: a plan, report, comparison, table, draft, list of more than a few items, or code. Put the full Markdown in `content`, the answer or gist in `message`, and at most one question in `followUp`. Call it last and on its own: the reply ends after it, and the user receives the message, the link, then the question.',
+        'Send the user a document, with a short chat message, ONLY when they asked for a document with no particular file format (or for any file, when `send_file` is not available), or when the output is genuinely document-length (a long report, long code, several screens of text). Ordinary answers, comparisons, short plans and lists stay in chat as messages: many users read chat on a data plan with no browser. Put the full Markdown in `content`; put the conclusions, decisions and next actions in `message`, so the user has them without opening the document; at most one question in `followUp`. Call it last and on its own: the reply ends after it, and the user receives the message, the document, then the question. A file in a particular format (Word, PDF, a spreadsheet, an image) is built in the sandbox and goes through `send_file` when that tool is available.',
       schema: CreateArtifactArgs,
       effect: 'read',
     },

package/src/channels/contract.ts

@@ -246,8 +246,9 @@ export interface ChannelTurnResponse {
   text?: string;
   /**
    * A finished turn's Reply Plan: the parts to deliver in order (short
-   * messages and artefact links). `text` stays the whole reply as one
-   * message for gateways that predate plans.
+   * messages, artefact links and files). `text` stays the whole reply as one
+   * message for gateways that predate plans, or that cannot read one of its
+   * parts: a file is a link line there.
    */
   plan?: ReplyPlan;
   actionOutcomes?: ActionOutcomeWire[];

package/src/channels/turns.ts

@@ -4,7 +4,7 @@ import type { DoSqliteDatabase } from '../sqlite/database';
 import { UNTITLED_SESSION } from '../sqlite/sessions-store';
 import type { RunRecord } from '../do/run-store';
 import type { TurnIdentity, TurnRequest } from '../do/contracts';
-import { parseReplyPlan, planText } from '../delivery/schema';
+import { parseReplyPlan, planText, planTextForModel } from '../delivery/schema';
 import type { ReplyPlan } from '../delivery/types';
 import {
   ChannelError,
@@ -941,7 +941,10 @@ export class ChannelTurns {
               : undefined))
           : undefined;
       if (reference.partId && reply.plan && !matched) return unknown;
-      text = matched ? planText({ parts: [matched] }) : reply.rendered;
+      // The model reads this: a file part is named, never linked.
+      text = matched
+        ? planTextForModel({ parts: [matched] })
+        : reply.withFileNames;
     }
     return {
       kind: 'resolved',
@@ -1100,11 +1103,20 @@ export class ChannelTurns {
     while (this.draining) await this.draining;
   }
 
-  /** A finished run's Reply Plan, and the reply as the channel user sees it. */
+  /**
+   * A finished run's Reply Plan, the reply as a gateway that predates plans
+   * sends it, and the reply with each file named instead of linked: what the
+   * model reads when the user quotes it, and what the room mirror keeps,
+   * since a signed link expires.
+   */
   private async reply(
     runId: string,
     text: string,
-  ): Promise<{ plan: ReplyPlan | null; rendered: string }> {
+  ): Promise<{
+    plan: ReplyPlan | null;
+    rendered: string;
+    withFileNames: string;
+  }> {
     const plan = parseReplyPlan(await this.host.getPlan(runId));
     const row = await this.db.get<{ routing_json: string | null }>(
       'SELECT routing_json FROM channel_requests WHERE run_id=?',
@@ -1127,7 +1139,12 @@ export class ChannelTurns {
       const to = await this.boldTitle(route.destination.sessionId);
       notice = `Back to ${to ? `*${to}*` : 'an earlier topic'}. Send /resume to pick another topic.`;
     }
-    if (!notice) return { plan, rendered: plan ? planText(plan) : text };
+    if (!notice)
+      return {
+        plan,
+        rendered: plan ? planText(plan) : text,
+        withFileNames: plan ? planTextForModel(plan) : text,
+      };
     const decorated =
       plan && plan.parts.length < 999
         ? {
@@ -1142,11 +1159,12 @@ export class ChannelTurns {
             ],
           }
         : null;
+    const withNotice = (show: (plan: ReplyPlan) => string): string =>
+      decorated ? show(decorated) : `${notice}\n\n${plan ? show(plan) : text}`;
     return {
       plan: decorated,
-      rendered: decorated
-        ? planText(decorated)
-        : `${notice}\n\n${plan ? planText(plan) : text}`,
+      rendered: withNotice(planText),
+      withFileNames: withNotice(planTextForModel),
     };
   }
 
@@ -2021,7 +2039,7 @@ export class ChannelTurns {
               record.runId,
               record.partialText ?? '',
             );
-            await this.host.mirror(request, reply.rendered, 'oracle');
+            await this.host.mirror(request, reply.withFileNames, 'oracle');
             await this.settleMirror(
               row.run_id,
               'reply_mirrored = 1, mirror_pending = 0',

package/src/core/env.ts

@@ -310,12 +310,14 @@ export const baseEnvSchema = z.object({
 
   // --- durable runs (docs/plans/durable-runs.md) ---------------------------
   // Parsed by `runDurabilityConfig` (src/do/run-store.ts) with defaults:
-  // keep-alive 20 s, segment pack every 2 s / 16 KiB, 4 recovery attempts at
-  // 5/15/30/60 s, `interrupt` as the multitask rule.
+  // keep-alive 20 s, segment pack every 2 s / 16 KiB, 4 recovery attempts
+  // without progress at 5/15/30/60 s, 8 recoveries in all, `interrupt` as
+  // the multitask rule.
   RUN_KEEPALIVE_MS: z.string().optional(),
   RUN_SEGMENT_FLUSH_MS: z.string().optional(),
   RUN_SEGMENT_BYTES: z.string().optional(),
   RUN_RECOVERY_ATTEMPTS: z.string().optional(),
+  RUN_RECOVERY_TOTAL_ATTEMPTS: z.string().optional(),
   RUN_RECOVERY_DELAYS_MS: z.string().optional(),
   TURN_MULTITASK_DEFAULT: z.enum(['interrupt', 'enqueue']).optional(),
 

package/src/core/llm.ts

@@ -18,6 +18,7 @@ import {
 } from './env';
 import { fetchOpenRouterPrices } from './openrouter-pricing';
 import type { LlmAdapter } from './runtime-context';
+import { stringify } from '../sqlite/serialization';
 import { NOOP_LOGGER } from './utils';
 
 // ── Catalog ─────────────────────────────────────────────────────────────────
@@ -1014,6 +1015,70 @@ export interface LangsmithTracingDecision {
   callbacks?: [LangChainTracer];
 }
 
+/** The signature of a signed storage link, whatever carries the link. */
+const SIGNED_LINK_SIGNATURE = /(X-Amz-Signature=)[0-9a-f]+/gi;
+
+/** What `SIGNED_LINK_SIGNATURE` needs to match somewhere: the marker and one hex digit. */
+const SIGNED_LINK_MARKER = /X-Amz-Signature=[0-9a-f]/i;
+
+/**
+ * Whether `values` needs the full pass of `redactSignedLinks`: some string
+ * its JSON would carry (a value or a key, through `toJSON` like
+ * `JSON.stringify`) holds a signature, or the walk cannot tell (a BigInt, a
+ * getter or `toJSON` that throws: the full pass decides what is sent).
+ * JSON escaping never touches the marker's characters, so the marker is in
+ * the JSON exactly when it is in one of those strings. Walks without
+ * serializing: every run of a traced turn carries the whole history, and a
+ * stringify per run was a copy of it per run.
+ */
+function needsSignedLinkPass(values: unknown): boolean {
+  const pending: unknown[] = [values];
+  const seen = new Set<object>();
+  try {
+    while (pending.length > 0) {
+      const value = pending.pop();
+      if (typeof value === 'string') {
+        if (SIGNED_LINK_MARKER.test(value)) return true;
+        continue;
+      }
+      if (typeof value === 'bigint') return true;
+      if (value === null || typeof value !== 'object') continue;
+      // A shared object adds no string a first visit did not; a cycle none.
+      if (seen.has(value)) continue;
+      seen.add(value);
+      const toJSON: unknown = Reflect.get(value, 'toJSON');
+      if (typeof toJSON === 'function') {
+        pending.push(toJSON.call(value, ''));
+        continue;
+      }
+      for (const key of Object.keys(value)) {
+        if (SIGNED_LINK_MARKER.test(key)) return true;
+        pending.push(Reflect.get(value, key));
+      }
+    }
+  } catch {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * What a trace may keep of a run's inputs and outputs. A signed link is a
+ * bearer credential, and a trace holds every `ToolMessage.artifact`, so its
+ * signature goes. A value that cannot be read is not sent. A payload with
+ * no signature anywhere is handed back as it is, without serializing it.
+ */
+export function redactSignedLinks(
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!needsSignedLinkPass(values)) return values;
+  const json = stringify(values);
+  const redacted = json.replace(SIGNED_LINK_SIGNATURE, '$1[redacted]');
+  if (redacted !== json) return JSON.parse(redacted) as Record<string, unknown>;
+  // `stringify` answers with a bare string when it cannot serialize.
+  return json.startsWith('{') ? values : {};
+}
+
 /**
  * One `langsmith` Client per (apiKey, endpoint) per isolate. Tracer instances
  * are per-turn and cheap; the client owns the batched upload queue, so
@@ -1025,7 +1090,11 @@ function langsmithClientFor(apiKey: string, endpoint?: string): Client {
   const key = `${apiKey}\n${endpoint ?? ''}`;
   let client = langsmithClients.get(key);
   if (!client) {
-    client = new Client({ apiKey, ...(endpoint && { apiUrl: endpoint }) });
+    client = new Client({
+      apiKey,
+      ...(endpoint && { apiUrl: endpoint }),
+      anonymizer: redactSignedLinks,
+    });
     langsmithClients.set(key, client);
   }
   return client;

package/src/core/main-agent.ts

@@ -80,6 +80,7 @@ import { wrapPluginTool } from './wrap-plugin-tool';
 import { renderSurfaceSection } from '../delivery/prompt';
 import { createReturnDirectFirstMiddleware } from './middlewares/return-direct-first';
 import { CREATE_ARTIFACT_TOOL } from '../artifacts/tool';
+import { SEND_FILE_TOOL } from '../plugins/sandbox/send-file';
 import type { SessionSurface } from '../plugin-api/types';
 
 import { taskExecutionProfile } from './execution-profile';
@@ -927,6 +928,10 @@ export async function createMainAgent(
     surfaceBlock: renderSurfaceSection(
       delivery,
       turnTools.some(({ tool }) => tool.name === CREATE_ARTIFACT_TOOL),
+      allTools.some(
+        ({ pluginName, tool }) =>
+          tool.name === SEND_FILE_TOOL && !unmetRequirements.has(pluginName),
+      ),
     ),
     operatingGuides,
   });

package/src/core/middlewares/result-cap.ts

@@ -158,6 +158,8 @@ export function createResultCapMiddleware(
         name: toolName,
         status: output.status,
         content: capped.text,
+        // What the model never sees is not part of what was capped.
+        ...(output.artifact !== undefined ? { artifact: output.artifact } : {}),
         additional_kwargs: {
           ...output.additional_kwargs,
           [CAPPED_META_KEY]: capped.meta,

package/src/core/middlewares/turn-boundary.ts

@@ -23,6 +23,7 @@ import {
 import { isAttachmentViewMessage } from '../../attachments/retention';
 import { isCapabilityGateRefusal } from './capability-gate';
 import { isToolNotRun } from '../tool-not-run';
+import { SEND_FILE_TOOL } from '../../plugins/sandbox/send-file';
 
 export const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
 
@@ -45,6 +46,12 @@ export interface CarriedToolCall {
   status: 'success' | 'error';
   /** The start of its result, for the repetition guard to quote. */
   result: string;
+  /**
+   * A `send_file` call's `ToolMessage.artifact` and tool call id: the Reply
+   * Plan still owes the user that file after the summary removed the call.
+   */
+  artifact?: unknown;
+  id?: string;
 }
 
 /** `additional_kwargs` key of the calls a mid-turn summary carries. */
@@ -65,6 +72,8 @@ export function turnCarryOf(
     const name: unknown = Reflect.get(entry, 'name');
     const status: unknown = Reflect.get(entry, 'status');
     const result: unknown = Reflect.get(entry, 'result');
+    const artifact: unknown = Reflect.get(entry, 'artifact');
+    const id: unknown = Reflect.get(entry, 'id');
     if (typeof name !== 'string') return [];
     if (status !== 'success' && status !== 'error') return [];
     return [
@@ -73,6 +82,8 @@ export function turnCarryOf(
         args: Reflect.get(entry, 'args'),
         status,
         result: typeof result === 'string' ? result : '',
+        ...(artifact !== undefined ? { artifact } : {}),
+        ...(typeof id === 'string' ? { id } : {}),
       },
     ];
   });
@@ -154,6 +165,9 @@ export function carriedCallsOfTurn(
       args: call.args,
       status: message.status === 'error' ? 'error' : 'success',
       result: resultText(message),
+      ...(call.name === SEND_FILE_TOOL && message.artifact !== undefined
+        ? { artifact: message.artifact, id: message.tool_call_id }
+        : {}),
     });
   }
   return carried;

package/src/delivery/plan.ts

@@ -11,7 +11,9 @@ import { parseReference } from '@ixo/action-protocol';
  *    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.
+ *  - a `create_artifact` call becomes its message, the link, its question;
+ *  - a `send_file` call becomes a file part, where the call stands in the
+ *    turn; a file sent twice is delivered once.
  */
 import {
   AIMessage,
@@ -20,6 +22,8 @@ import {
 } from '@langchain/core/messages';
 import { contentToText } from '../do/transcript';
 import { CREATE_ARTIFACT_TOOL, createArtifactParts } from '../artifacts/tool';
+import { turnCarryOf, turnStart } from '../core/middlewares/turn-boundary';
+import { SEND_FILE_TOOL, sentFile } from '../plugins/sandbox/send-file';
 import { isBlank, shapeStep, type SpillShape } from './shaper';
 import type {
   ArtifactRef,
@@ -40,23 +44,38 @@ export type DraftPart =
 
 const NARRATION_MAX_CHARS = 200;
 
-/** The model steps of the turn that ended the thread, with its tool results. */
+/**
+ * The model steps of the turn that ended the thread, with its tool results.
+ * `toolArtifacts` holds each `ToolMessage.artifact`: what a tool hands the
+ * plan without the model seeing it.
+ */
 export function turnSteps(messages: readonly BaseMessage[]): {
   steps: TurnStep[];
   toolResults: Map<string, string>;
+  toolArtifacts: Map<string, unknown>;
 } {
-  let start = 0;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    if (messages[i]?.type === 'human') {
-      start = i + 1;
-      break;
-    }
-  }
+  const opening = turnStart(messages);
+  const start = messages[opening]?.type === 'human' ? opening + 1 : 0;
   const steps: TurnStep[] = [];
   const toolResults = new Map<string, string>();
+  const toolArtifacts = new Map<string, unknown>();
+  // A mid-turn summary condensed the turn's earlier steps away. It carries
+  // their calls; a file already sent among them is still delivered, first.
+  const carried = start > 0 ? turnCarryOf(messages[opening]!) : undefined;
+  for (const [i, call] of (carried ?? []).entries()) {
+    if (call.name !== SEND_FILE_TOOL || call.artifact === undefined) continue;
+    const id = call.id ?? `carried-${i}`;
+    steps.push({
+      text: '',
+      toolCalls: [{ id, name: call.name, args: call.args }],
+    });
+    toolArtifacts.set(id, call.artifact);
+  }
   for (const message of messages.slice(start)) {
     if (ToolMessage.isInstance(message)) {
       toolResults.set(message.tool_call_id, contentToText(message.content));
+      if (message.artifact !== undefined)
+        toolArtifacts.set(message.tool_call_id, message.artifact);
       continue;
     }
     // Extraction-lane attachment text rides as hidden AI messages.
@@ -71,7 +90,7 @@ export function turnSteps(messages: readonly BaseMessage[]): {
       })),
     });
   }
-  return { steps, toolResults };
+  return { steps, toolResults, toolArtifacts };
 }
 
 /** One short paragraph of prose: what a model says before it calls a tool. */
@@ -116,11 +135,13 @@ function pendingContinuation(
 export function draftReplyPlan(input: {
   steps: TurnStep[];
   toolResults: ReadonlyMap<string, string>;
+  toolArtifacts?: ReadonlyMap<string, unknown>;
   continuation?: string | null;
   limits: ChatLimits;
   canSpill: boolean;
 }): DraftPart[] {
   const parts: DraftPart[] = [];
+  const sentPaths = new Set<string>();
   const steps =
     input.steps.length > 0 || !input.continuation
       ? input.steps
@@ -202,6 +223,13 @@ export function draftReplyPlan(input: {
         parts.push(
           ...createArtifactParts(call.args, input.toolResults.get(call.id)),
         );
+      if (call.name === SEND_FILE_TOOL) {
+        const sent = sentFile(input.toolArtifacts?.get(call.id));
+        if (sent && !sentPaths.has(sent.path)) {
+          sentPaths.add(sent.path);
+          parts.push({ kind: 'file', file: sent.file });
+        }
+      }
     }
   });
   return parts;
@@ -216,9 +244,10 @@ 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.
+ * reply's last part for as long as possible. Order is kept, and neither a
+ * file nor text that exists nowhere else is ever dropped: a reply with
+ * several documents or files, or a long one without artefact storage, can
+ * stay over the cap.
  */
 function capParts(parts: PlanPart[], limits: ChatLimits): ReplyContent[] {
   const out = [...parts];
@@ -261,13 +290,53 @@ function capParts(parts: PlanPart[], limits: ChatLimits): ReplyContent[] {
         ? { kind: 'text', text: part.text }
         : part.kind === 'artifact'
           ? { kind: 'artifact', artifact: part.artifact }
-          : part.kind === 'action'
-            ? { kind: 'action', action: part.action }
-            : {
-                kind: 'hub-action',
-                actionReference: part.actionReference,
-                summary: part.summary,
-              },
+          : part.kind === 'file'
+            ? { kind: 'file', file: part.file }
+            : part.kind === 'action'
+              ? { kind: 'action', action: part.action }
+              : {
+                  kind: 'hub-action',
+                  actionReference: part.actionReference,
+                  summary: part.summary,
+                },
+  );
+}
+
+/** Follows the files of a run that failed after sending them. */
+export const FAILED_RUN_NOTICE =
+  'What I attached above is complete, but something went wrong before I could finish this reply. Send your message again if you need more.';
+
+/**
+ * The reply of a chat run that failed after it sent files: those files, then
+ * a line saying the rest is missing. `calls` are this run's tool call ids,
+ * because the messages come from the checkpoint and may end in an earlier
+ * turn when the run failed before it wrote anything. Null when it sent none.
+ */
+export async function failedRunFiles(
+  messages: readonly BaseMessage[],
+  calls: ReadonlySet<string>,
+  limits: ChatLimits,
+): Promise<ReplyPlan | null> {
+  const { steps, toolResults, toolArtifacts } = turnSteps(messages);
+  const files = draftReplyPlan({
+    steps: steps.map((step) => ({
+      text: '',
+      toolCalls: step.toolCalls.filter(
+        (call) => call.name === SEND_FILE_TOOL && calls.has(call.id),
+      ),
+    })),
+    toolResults,
+    toolArtifacts,
+    limits,
+    canSpill: false,
+  });
+  if (files.length === 0) return null;
+  return materializeReplyPlan(
+    [...files, { kind: 'text', text: FAILED_RUN_NOTICE }],
+    {
+      limits,
+      createSpill: () => Promise.reject(new Error('nothing here spills')),
+    },
   );
 }
 

package/src/delivery/profile.ts

@@ -19,46 +19,51 @@ const GENERIC: ChatLimits = {
   bubbleMax: 1500,
   minBubble: 60,
   maxBubbles: 3,
-  maxPartsPerRun: 5,
-  spillChars: 1800,
-  maxListItems: 7,
+  maxPartsPerRun: 8,
+  spillChars: 4500,
+  maxListItems: 15,
   previewItems: 3,
-  maxCodeLines: 12,
+  maxCodeLines: 40,
   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.
+ * Chat first: many users read on WhatsApp alone, without a browser, so an
+ * ordinary answer (several paragraphs, a list, a small comparison) stays in
+ * the conversation and only a document-length step moves to an artefact.
+ * Message sizes stay 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,
-  },
+  // The generic limits are WhatsApp's: each entry below lists only what differs.
+  whatsapp: { ...GENERIC },
+  telegram: { ...GENERIC, bubbleTarget: 800, bubbleMax: 2000 },
   slack: {
     ...GENERIC,
     bubbleTarget: 1200,
     bubbleMax: 3000,
-    spillChars: 3500,
+    spillChars: 6000,
   },
   matrix: {
     ...GENERIC,
     bubbleTarget: 1200,
     bubbleMax: 4000,
-    spillChars: 4000,
+    spillChars: 8000,
   },
 };
 
-/** A group room hears one short answer, not a series. */
-const GROUP_LIMITS: Partial<ChatLimits> = { maxBubbles: 2, maxPartsPerRun: 3 };
+/**
+ * A group room hears one short answer, not a series: one or two messages,
+ * the run capped at three parts, and a step over 2,400 characters moves to
+ * an artefact.
+ */
+const GROUP_LIMITS: Partial<ChatLimits> = {
+  maxBubbles: 2,
+  maxPartsPerRun: 3,
+  spillChars: 2400,
+};
 
 const COUNTS = [
   'bubbleTarget',

package/src/delivery/prompt.ts

@@ -1,26 +1,53 @@
+import { SENDABLE_FILE_TYPES } from '../plugins/sandbox/send-file';
 import type { DeliveryProfile } from './types';
 
+/**
+ * Whether the surface delivers a file as an attachment. A Matrix room has no
+ * gateway to fetch it, so a file arrives there as a link line.
+ */
+export function deliversAttachments(surface: string): boolean {
+  return surface !== 'matrix';
+}
+
+/** `maxBubbles` as the prompt asks for it: "two or three messages". */
+function preferredMessages(maxBubbles: number): string {
+  if (maxBubbles <= 1) return 'one message';
+  if (maxBubbles === 2) return 'one or two messages';
+  if (maxBubbles === 3) return 'two or three messages';
+  return `up to ${maxBubbles} messages`;
+}
+
 /**
  * The prompt section a chat turn gets: write for the surface. Empty on the
- * Portal. `artifacts` says whether `create_artifact` is bound this turn.
+ * Portal. `artifacts` says whether `create_artifact` is bound this turn,
+ * `files` whether `send_file` is. Agrees with the shaper and the tools' own
+ * descriptions: ordinary answers stay in chat, only document-length output
+ * becomes an artefact, and a made file reaches the user as an attachment.
  */
 export function renderSurfaceSection(
   profile: DeliveryProfile | undefined,
   artifacts: boolean,
+  files: boolean,
 ): string {
   if (!profile || profile.kind !== 'chat') return '';
-  const { label, limits } = profile;
+  const { label, limits, surface } = profile;
+  const preferred = preferredMessages(limits.maxBubbles);
   return [
     '## Where this conversation is happening',
     '',
-    `You are replying in ${label}. The user reads your reply as chat messages, not as a document.`,
+    `You are replying in ${label}. The user reads your reply as chat messages, often on a phone with a chat-only data plan and no browser, so the answer itself belongs in the messages.`,
     '',
     '- 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.`,
+    `- Prefer ${preferred}. A blank line marks where a message may break; short paragraphs are grouped so the reply reads as ${preferred}. Keep each paragraph under about ${limits.bubbleTarget} characters. Use more messages when the answer needs them; never leave content out to fit.`,
+    `- Ordinary answers stay in chat, including explanations, comparisons, short plans and step-by-step instructions. No headings or horizontal rules. Lists up to ${limits.maxListItems} items, code up to ${limits.maxCodeLines} lines and **bold** for the key fact are fine in chat. Write a small comparison as one short line per item, not a table.`,
+    ...(files
+      ? [
+          `- Deliver every file meant for the user with \`send_file\` (${SENDABLE_FILE_TYPES} only): ${deliversAttachments(surface) ? 'the user receives the file itself here, as an attachment' : 'a link to the file is posted here for you'}. When the user asks for a file in a particular format, build it yourself in the sandbox and send it this way. Do not send a file you downloaded from the internet unless the user asked for that exact file. Never paste a download link, and do not describe how to open or download it. Do not send helper scripts or intermediate files. Call it once per file, after the sandbox call that saved the file has finished.`,
+        ]
+      : []),
     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.',
+      ? `- Use \`create_artifact\` ${files ? 'for a document with no particular file format' : 'only when the user asks for a document or file'}, or when the output is genuinely document-length: several screens of text, long code, a long report. Even then, its message carries the conclusions, decisions and next actions, and the document holds the detail. Call it last: the user gets the message, the document, then at most one follow-up question.`
+      : '- Everything you write is delivered as messages; when something is genuinely long, put the essential part first.',
     '- 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');