@ixo/oracle-runtime-workers 0.35.0 → 0.36.0

package/src/delivery/prompt.ts

@@ -1,26 +1,52 @@
 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 (a Word document, PDF, spreadsheet, slide deck, image, CSV or anything else) with \`send_file\`: ${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 in the sandbox and send it this way. 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');

package/src/delivery/schema.ts

@@ -1,7 +1,7 @@
 import { ActionReferenceSchema } from '@ixo/ixo-transaction/action-proposals';
 import { parseReference, type ActionReferenceV1 } from '@ixo/action-protocol';
 import { z } from 'zod';
-import type { ReplyContent, ReplyPlan } from './types';
+import type { ReplyContent, ReplyFile, ReplyPlan } from './types';
 
 const ArtifactRefSchema = z.object({
   artifactId: z.string(),
@@ -12,6 +12,33 @@ const ArtifactRefSchema = z.object({
   expiresAt: z.string(),
 });
 
+function isSignedLink(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The most a gateway takes (`maxFileUrlChars`): with room for its caption the
+ * link must still fit one 4,096-character text message.
+ */
+export const REPLY_FILE_URL_MAX = 3800;
+
+export const ReplyFileSchema = z.object({
+  url: z
+    .string()
+    .max(REPLY_FILE_URL_MAX)
+    .refine(isSignedLink, 'must be an https URL without credentials'),
+  filename: z.string().min(1),
+  mimetype: z.string().min(1),
+  bytes: z.number().int().nonnegative().optional(),
+  caption: z.string().max(1024).optional(),
+  expiresAt: z.string().optional(),
+});
+
 export const ReplyPlanSchema = z.object({
   v: z.literal(1),
   parts: z.array(
@@ -44,6 +71,11 @@ export const ReplyPlanSchema = z.object({
         kind: z.literal('artifact'),
         artifact: ArtifactRefSchema,
       }),
+      z.object({
+        partId: z.string(),
+        kind: z.literal('file'),
+        file: ReplyFileSchema,
+      }),
     ]),
   ),
 });
@@ -65,10 +97,17 @@ function linkLabel(title: string): string {
   return title.replace(/[[\]]/g, '');
 }
 
+function fileLine(file: ReplyFile): string {
+  const link = `[${linkLabel(file.filename)}](${file.url})`;
+  return file.caption ? `${file.caption}\n\n${link}` : link;
+}
+
 /**
- * The plan as one Markdown message: what the user's oracle 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.
+ * The plan as one Markdown message: what gateways that predate plans receive.
+ * A file is a link line, so a gateway that cannot read the `file` part
+ * degrades instead of losing the file. Never stored as a run's text, which
+ * stays the model's own, and never shown to the model or mirrored to a room:
+ * see `planTextForModel`.
  */
 export function planText(plan: { parts: readonly ReplyContent[] }): string {
   return plan.parts
@@ -79,7 +118,32 @@ export function planText(plan: { parts: readonly ReplyContent[] }): string {
           ? `[${linkLabel(part.action.title)}](${part.action.url})`
           : part.kind === 'hub-action'
             ? `[${linkLabel(part.summary)}](${part.actionReference.url})`
-            : `[${linkLabel(part.artifact.title)}](${part.artifact.url})`,
+            : part.kind === 'file'
+              ? fileLine(part.file)
+              : `[${linkLabel(part.artifact.title)}](${part.artifact.url})`,
     )
     .join('\n\n');
 }
+
+/**
+ * `planText` without a file's signed link, which is named instead: for the
+ * model, as when a user quotes an earlier reply, for the room mirror, and for
+ * the transcript, all of which outlive the link.
+ */
+export function planTextForModel(plan: {
+  parts: readonly ReplyContent[];
+}): string {
+  return planText({
+    parts: plan.parts.map(
+      (part): ReplyContent =>
+        part.kind === 'file'
+          ? {
+              kind: 'text',
+              text: [part.file.caption, `[File sent: ${part.file.filename}]`]
+                .filter(Boolean)
+                .join('\n\n'),
+            }
+          : part,
+    ),
+  });
+}