@anteros/core 0.0.44 → 0.0.47

package/lib/files.ts

@@ -254,11 +254,22 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     });
   }
 
-  // Validate MIME type
-  const mimetype = file.type || 'application/octet-stream';
-  if (col.upload?.allowedMimeTypes?.length && !col.upload.allowedMimeTypes.includes(mimetype)) {
-    throw new AppError(`MIME type '${mimetype}' not allowed`, {
-      code: 'MIMETYPE_NOT_ALLOWED', status: 400,
+  // Validate MIME type — compare the **base** type: a browser sends `text/html;charset=utf-8`
+  const mimetype = (file.type || 'application/octet-stream').split(';')[0]!.trim().toLowerCase();
+  if (col.upload?.allowedMimeTypes?.length) {
+    const allowed = col.upload.allowedMimeTypes.map((type: string) => type.split(';')[0]!.trim().toLowerCase());
+    if (!allowed.includes(mimetype)) {
+      throw new AppError(`MIME type '${mimetype}' not allowed`, {
+        code: 'MIMETYPE_NOT_ALLOWED', status: 400,
+      });
+    }
+  }
+
+  // Size first (#51): never buffer an oversized upload just to reject it later.
+  const maxSize = col.upload?.maxSize ?? 100 * 1024 * 1024; // 100MB per-file default
+  if (file.size > maxSize) {
+    throw new AppError(`File too large (max ${Math.round(maxSize / 1024 / 1024)}MB)`, {
+      code: 'FILE_TOO_LARGE', status: 413,
     });
   }
 
@@ -284,14 +295,6 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     });
   }
 
-  // Validate file size
-  const maxSize = col.upload?.maxSize ?? 10 * 1024 * 1024; // 10MB default
-  if (file.size > maxSize) {
-    throw new AppError(`File too large (max ${Math.round(maxSize / 1024 / 1024)}MB)`, {
-      code: 'FILE_TOO_LARGE', status: 413,
-    });
-  }
-
   // Timestamps (ISO strings) — stored and returned in the response
   const now = new Date()
 
@@ -450,8 +453,11 @@ export async function handleServe(
     return { stream: new ReadableStream({ start(controller) { controller.enqueue(data); controller.close(); } }), mimetype: newMime, size: data.length };
   }
 
-  // Flaw 4: SVG is served as an attachment (never inline) to prevent stored XSS
-  if (isSvg) {
+  // #37: only raster images (and PDFs) may render inline. Anything else — HTML,
+  // SVG, JS, unknown — is served as a **download**, so an uploaded file can never
+  // execute on the API origin (stored XSS).
+  const INLINE_MIME = /^image\/(png|jpe?g|gif|webp|avif|bmp)$/i;
+  if (isSvg || !(INLINE_MIME.test(mimetype) || mimetype === 'application/pdf')) {
     return { stream, mimetype, attachment: true };
   }
 

package/lib/jsonSchema.ts

@@ -38,6 +38,10 @@ function joiToJsonSchema(schema: Joi.Schema, describe = schema.describe() as any
             }
             node.properties = properties;
             if (required.length) node.required = required;
+            // The model is told to stay inside the declared shape. Joi still tolerates
+            // unknown keys at validation time (`allowUnknown`) — the schema is the
+            // stricter of the two on purpose: a stray key costs tokens and attention.
+            node.additionalProperties = describe.flags?.unknown === true;
             break;
         }
         case 'array': {
@@ -73,6 +77,10 @@ function joiToJsonSchema(schema: Joi.Schema, describe = schema.describe() as any
     }
 
     if (describe?.flags?.description) node.description = describe.flags.description;
+    // A default is part of what the model should know: it can omit a field instead of
+    // inventing a value. A function default cannot travel — it is applied at validation.
+    const fallback = describe?.flags?.default;
+    if (fallback !== undefined && typeof fallback !== 'function') node.default = fallback;
     return node;
 }
 

package/lib/mcp.ts

@@ -2,53 +2,75 @@ import { Glob } from "bun"
 import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
+import { logger } from "../utils/logger"
 import type { McpTool, McpResource } from "../types/mcp"
 import { importDefinition } from "./load"
 
 /**
- * Load MCP tools & resources from each tenant's `mcp/` folder:
- *   {tenant.dir}/mcp/tools/**\/*.tool.ts        → tools
- *   {tenant.dir}/mcp/resources/**\/*.resource.ts → resources
+ * Load MCP tools & resources from each tenant's AI folder:
+ *   {tenant.dir}/ai/mcp/tools/**\/*.tool.ts         → tools
+ *   {tenant.dir}/ai/mcp/resources/**\/*.resource.ts  → resources
+ *
+ * The legacy `{tenant.dir}/mcp/` layout is still read, with one deprecation
+ * warning per tenant; the `ai/` definition wins when both declare the same name.
  */
 async function syncMcpTools() {
     try {
-        const tools: McpTool[] = []
-        const resources: McpResource[] = []
+        /** Keyed by `tenant:name`, so a migrated file replaces its old copy. */
+        const tools = new Map<string, McpTool>()
+        const resources = new Map<string, McpResource>()
+
         for (let tenant of cfg.tenants ?? []) {
             const TENANT_PATH = path.join(process.cwd(), tenant.dir)
-            const MCP_PATH = path.join(TENANT_PATH, 'mcp')
-            let exist = await fs.exists(MCP_PATH)
-            if (!exist) continue;
-            const isDirectory = await (await fs.stat(MCP_PATH)).isDirectory()
-            if (!isDirectory) continue;
-
-            // tools: mcp/tools/**/*.tool.ts
-            const TOOLS_PATH = path.join(MCP_PATH, 'tools')
-            if (await fs.exists(TOOLS_PATH)) {
-                const toolsGlob = new Glob(path.join(TOOLS_PATH, '**/*.tool.ts'))
-                for await (let file of toolsGlob.scan('.')) {
-                    let module = await importDefinition(file, 'MCP tool')
-                    if (module?.default?._isMcpTool_ && module?.default?.enabled !== false) {
-                        tools.push({ ...module?.default, _tenant_: tenant.id })
+
+            // Legacy first: an `ai/mcp` file of the same name replaces it.
+            const roots = [
+                { dir: path.join(TENANT_PATH, 'mcp'), legacy: true },
+                { dir: path.join(TENANT_PATH, 'ai', 'mcp'), legacy: false },
+            ]
+
+            for (const root of roots) {
+                let exist = await fs.exists(root.dir)
+                if (!exist) continue
+                const isDirectory = await (await fs.stat(root.dir)).isDirectory()
+                if (!isDirectory) continue
+                if (root.legacy) {
+                    logger.warn(
+                        `Tenant '${tenant.id}': '${path.join(tenant.dir, 'mcp')}' is deprecated — ` +
+                        `move it to '${path.join(tenant.dir, 'ai', 'mcp')}'`,
+                    )
+                }
+
+                // tools: <root>/tools/**/*.tool.ts
+                const TOOLS_PATH = path.join(root.dir, 'tools')
+                if (await fs.exists(TOOLS_PATH)) {
+                    const toolsGlob = new Glob(path.join(TOOLS_PATH, '**/*.tool.ts'))
+                    for await (let file of toolsGlob.scan('.')) {
+                        let module = await importDefinition(file, 'MCP tool')
+                        if (module?.default?._isMcpTool_ && module?.default?.enabled !== false) {
+                            const tool = { ...module.default, _tenant_: tenant.id } as McpTool
+                            tools.set(`${tenant.id}:${tool.name}`, tool)
+                        }
                     }
                 }
-            }
 
-            // resources: mcp/resources/**/*.resource.ts
-            const RESOURCES_PATH = path.join(MCP_PATH, 'resources')
-            if (await fs.exists(RESOURCES_PATH)) {
-                const resourcesGlob = new Glob(path.join(RESOURCES_PATH, '**/*.resource.ts'))
-                for await (let file of resourcesGlob.scan('.')) {
-                    let module = await importDefinition(file, 'MCP resource')
-                    if (module?.default?._isMcpResource_ && module?.default?.enabled !== false) {
-                        resources.push({ ...module?.default, _tenant_: tenant.id })
+                // resources: <root>/resources/**/*.resource.ts
+                const RESOURCES_PATH = path.join(root.dir, 'resources')
+                if (await fs.exists(RESOURCES_PATH)) {
+                    const resourcesGlob = new Glob(path.join(RESOURCES_PATH, '**/*.resource.ts'))
+                    for await (let file of resourcesGlob.scan('.')) {
+                        let module = await importDefinition(file, 'MCP resource')
+                        if (module?.default?._isMcpResource_ && module?.default?.enabled !== false) {
+                            const resource = { ...module.default, _tenant_: tenant.id } as McpResource
+                            resources.set(`${tenant.id}:${resource.name}`, resource)
+                        }
                     }
                 }
             }
         }
 
-        cfg.mcpTools = tools
-        cfg.mcpResources = resources
+        cfg.mcpTools = [...tools.values()]
+        cfg.mcpResources = [...resources.values()]
 
     } catch (err: any) {
         console.error(err?.message)

package/lib/messages.ts

@@ -1,4 +1,6 @@
 import { AppError } from "./error";
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
 import { MAX_FILE_BYTES } from "./attachment";
 import type {
     AgentAssistantMessage,
@@ -53,7 +55,9 @@ function invalid(message: string): AppError {
 
 /** A tool result as the model reads it — the same rendering the runtime uses. */
 function serializeToolResult(entry: AgentToolResultEntry): string {
-    if (entry.error) return `Error: ${entry.error}`;
+    // The code travels with the message, so the model can branch on the cause
+    // (`ORDER_NOT_FOUND`, `AGENT_TOOL_TIMEOUT`…) instead of parsing English.
+    if (entry.error) return entry.errorCode ? `Error [${entry.errorCode}]: ${entry.error}` : `Error: ${entry.error}`;
     const result = entry.result;
     if (typeof result === "string") return result;
     if (result && typeof result === "object" && Array.isArray((result as any).content)) {
@@ -61,6 +65,10 @@ function serializeToolResult(entry: AgentToolResultEntry): string {
             .filter((block: any) => block?.type === "text" && typeof block.text === "string")
             .map((block: any) => block.text);
         if (texts.length) return texts.join("\n");
+        // Media-only result — the text answer is a marker, the media travels beside it.
+        if ((result as any).content.some((block: any) => MEDIA_BLOCK.test(String(block?.type)))) {
+            return toolMediaOf((result as any).content).map(mediaMarker).join("\n");
+        }
     }
     if (result === undefined || result === null) return "OK";
     try {
@@ -70,6 +78,51 @@ function serializeToolResult(entry: AgentToolResultEntry): string {
     }
 }
 
+/** A tool result block that carries bytes (MCP spells documents `document`). */
+/** A media block a tool result may carry — text is handled separately. */
+type ToolMediaPart = Extract<AgentMediaPart, { type: "image" } | { type: "file" }>;
+
+const MEDIA_BLOCK = /^(image|file|document)$/;
+
+function toolMediaOf(content: any[]): ToolMediaPart[] {
+    const media: ToolMediaPart[] = [];
+    for (const block of content) {
+        const type = String(block?.type ?? "");
+        if (!MEDIA_BLOCK.test(type)) continue;
+        const mimeType = typeof block.mimeType === "string"
+            ? block.mimeType
+            : (typeof block.mime_type === "string" ? block.mime_type : undefined);
+        if (type === "image") {
+            const data = typeof block.data === "string" ? block.data : undefined;
+            const url = typeof block.url === "string" ? block.url : undefined;
+            if (data || url) media.push({ type: "image", ...(url ? { url } : { data }), ...(mimeType ? { mimeType } : {}) });
+            continue;
+        }
+        const data = typeof block.data === "string" ? block.data : undefined;
+        const url = typeof block.url === "string" ? block.url : undefined;
+        if (!data && !url) continue;
+        media.push({
+            type: "file",
+            ...(url ? { url } : { data }),
+            ...(mimeType ? { mimeType } : {}),
+            ...(block.name ?? block.filename ? { name: String(block.name ?? block.filename) } : {}),
+        });
+    }
+    return media;
+}
+
+/** What a text-only protocol (OpenAI) shows of a media tool result. */
+function mediaMarker(part: ToolMediaPart): string {
+    return part.type === "image" ? `[image: ${part.mimeType ?? "image/png"}]` : `[file: ${part.name ?? part.mimeType ?? "file"}]`;
+}
+
+/** The media a tool returned, when its result is `{ content: […] }`. */
+function toolResultMedia(entry: AgentToolResultEntry): ToolMediaPart[] {
+    const result = entry.result;
+    if (entry.error || !result || typeof result !== "object" || !Array.isArray((result as any).content)) return [];
+    return toolMediaOf((result as any).content);
+}
+
 /** The text of a part array — a `system` message is text and nothing else. */
 function systemText(parts: AgentContentPart[], role: string): string {
     const foreign = parts.find((part) => part?.type !== "text");
@@ -88,28 +141,158 @@ function checkAddress(part: AgentContentPart, role: string): void {
     throw invalid(`A \`${part.type}\` part of a ${role} message needs an \`https://\`, a \`data:\` URL or base64 \`data\``);
 }
 
-/** A `file` part, with its remote payload fetched and inlined when there is one. */
-async function inlineRemoteFile(part: AgentMediaPart): Promise<AgentMediaPart> {
-    if (part.type !== "file" || !isHttpUrl(part.url)) return part;
+/** Remote files: public HTTPS only, bounded time and size — SSRF hardening (issue #30). */
+const REMOTE_FILE_TIMEOUT_MS = 10_000;
+const REMOTE_FILE_MAX_REDIRECTS = 3;
+
+/** Refuse an address that is not publicly routable (loopback, LAN, cloud metadata…). */
+function isPrivateAddress(address: string): boolean {
+    const plain = address.replace(/^\[|\]$/g, "").toLowerCase();
+    const family = isIP(plain);
+
+    if (family === 4) {
+        const [a, b] = plain.split(".").map(Number) as [number, number, number, number];
+        if (a === 0 || a === 10 || a === 127) return true;
+        if (a === 100 && b >= 64 && b <= 127) return true;          // CGNAT
+        if (a === 169 && b === 254) return true;                     // link-local, cloud metadata
+        if (a === 172 && b >= 16 && b <= 31) return true;
+        if (a === 192 && b === 168) return true;
+        if (a === 192 && b === 0) return true;                       // IETF / TEST-NET-1
+        if (a === 198 && (b === 18 || b === 19)) return true;        // benchmark
+        if (a === 198 && b === 51) return true;                      // TEST-NET-2
+        if (a === 203 && b === 0) return true;                       // TEST-NET-3
+        return a >= 224;                                             // multicast, reserved, broadcast
+    }
 
-    const url = part.url!;
-    let bytes: Uint8Array;
+    if (family === 6) {
+        if (plain.startsWith("::")) return true;                     // ::1, ::, ::ffff:… (IPv4-mapped)
+        if (plain.startsWith("fe80:")) return true;                  // link-local
+        if (/^f[cd][0-9a-f]{2}:/.test(plain)) return true;           // unique local fc00::/7
+        if (plain.startsWith("ff")) return true;                     // multicast
+        if (plain.startsWith("2001:db8")) return true;               // documentation
+        if (plain.startsWith("2002:")) return true;                  // 6to4
+        if (plain.startsWith("64:ff9b:")) return true;               // NAT64 — may map a private IPv4
+        return false;
+    }
+
+    return true; // not an IP: the caller resolves the hostname first
+}
+
+function remoteFileError(code: "AGENT_FILE_INVALID" | "AGENT_FILE_NOT_FOUND", message: string): AppError {
+    return new AppError(message, { status: 400, code });
+}
+
+/** Parse one hop: HTTPS, no credentials, and only public addresses. */
+async function assertPublicRemoteUrl(raw: string): Promise<URL> {
+    let url: URL;
     try {
-        const response = await fetch(url);
-        if (!response.ok) throw new Error(`HTTP ${response.status}`);
-        bytes = new Uint8Array(await response.arrayBuffer());
-    } catch (err: any) {
-        throw new AppError(`Cannot download '${url}': ${err?.message ?? "unreachable"}`, {
-            status: 400, code: "AGENT_FILE_NOT_FOUND",
-        });
+        url = new URL(raw);
+    } catch {
+        throw remoteFileError("AGENT_FILE_INVALID", "The remote file URL is invalid");
+    }
+    if (url.protocol !== "https:") {
+        throw remoteFileError("AGENT_FILE_INVALID", "Remote files must use HTTPS");
+    }
+    if (url.username || url.password) {
+        throw remoteFileError("AGENT_FILE_INVALID", "Remote file URLs must not carry credentials");
+    }
+
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (!host) throw remoteFileError("AGENT_FILE_INVALID", "The remote file URL has no host");
+
+    if (isIP(host)) {
+        if (isPrivateAddress(host)) {
+            throw remoteFileError("AGENT_FILE_INVALID", "The remote file URL points to a private address");
+        }
+        return url;
+    }
+
+    let resolved: Array<{ address: string }>;
+    try {
+        resolved = await lookup(host, { all: true, verbatim: true });
+    } catch {
+        throw remoteFileError("AGENT_FILE_NOT_FOUND", "The remote file host could not be resolved");
     }
+    if (!resolved.length || resolved.some(({ address }) => isPrivateAddress(address))) {
+        throw remoteFileError("AGENT_FILE_INVALID", "The remote file URL points to a private address");
+    }
+    return url;
+}
+
+/** Follows a redirect only after re-validating the target — no hop may reach a private address. */
+async function fetchRemoteFile(raw: string): Promise<Response> {
+    let current = raw;
+    for (let hop = 0; hop <= REMOTE_FILE_MAX_REDIRECTS; hop++) {
+        const url = await assertPublicRemoteUrl(current);
+
+        let response: Response;
+        try {
+            response = await fetch(url, {
+                redirect: "manual",
+                signal: AbortSignal.timeout(REMOTE_FILE_TIMEOUT_MS),
+            });
+        } catch {
+            throw remoteFileError("AGENT_FILE_NOT_FOUND", "The remote file could not be downloaded");
+        }
 
-    if (bytes.byteLength > MAX_FILE_BYTES) {
-        throw new AppError(
-            `'${url}' is ${Math.round(bytes.byteLength / 1024 / 1024)}MB — the limit is ${MAX_FILE_BYTES / 1024 / 1024}MB`,
-            { status: 413, code: "AGENT_FILE_TOO_LARGE" },
-        );
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get("location");
+            if (!location) throw remoteFileError("AGENT_FILE_NOT_FOUND", "The remote file could not be downloaded");
+            current = new URL(location, url).href;
+            continue;
+        }
+        if (!response.ok) throw remoteFileError("AGENT_FILE_NOT_FOUND", "The remote file could not be downloaded");
+        return response;
     }
+    throw remoteFileError("AGENT_FILE_INVALID", "The remote file redirects too many times");
+}
+
+/** Reads the body with a hard cap — from `Content-Length` and while streaming. */
+async function readRemoteBytes(response: Response): Promise<Uint8Array> {
+    const limit = MAX_FILE_BYTES;
+    const tooLarge = () => new AppError(
+        `The remote file exceeds the ${limit / 1024 / 1024}MB limit`,
+        { status: 413, code: "AGENT_FILE_TOO_LARGE" },
+    );
+
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > limit) throw tooLarge();
+    if (!response.body) return new Uint8Array(await response.arrayBuffer());
+
+    const reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            total += value.byteLength;
+            if (total > limit) {
+                await reader.cancel().catch(() => {});
+                throw tooLarge();
+            }
+            chunks.push(value);
+        }
+    } catch (err) {
+        if (err instanceof AppError) throw err;
+        throw remoteFileError("AGENT_FILE_NOT_FOUND", "The remote file could not be downloaded");
+    }
+
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+
+/** A `file` part, with its remote payload fetched and inlined when there is one. */
+async function inlineRemoteFile(part: AgentMediaPart): Promise<AgentMediaPart> {
+    if (part.type !== "file" || !isHttpUrl(part.url)) return part;
+
+    const url = part.url!;
+    const bytes = await readRemoteBytes(await fetchRemoteFile(url));
 
     const name = part.name ?? url.split("?")[0]!.split("/").pop() ?? "document.pdf";
     return { type: "file", name, ...(part.mimeType ? { mimeType: part.mimeType } : {}), data: Buffer.from(bytes).toString("base64") };
@@ -296,4 +479,4 @@ async function normalizeMessages(input: AgentInput): Promise<AgentMessage[]> {
     return out;
 }
 
-export { normalizeMessages, serializeToolResult };
+export { normalizeMessages, serializeToolResult, toolResultMedia };

package/lib/partialJson.ts

@@ -0,0 +1,79 @@
+/**
+ * Best-effort JSON for a stream: what the model has produced so far, repaired
+ * enough to parse, or `undefined` while it still makes no sense.
+ *
+ * Used by `agent.streamObject()` — the answer of a structured run is a JSON
+ * object, and a caller usually wants to render it before the last token arrives.
+ */
+
+/** Drop the markdown fence a model wraps its JSON in (` ```json … ``` `). */
+function unfence(text: string): string {
+    let candidate = text.trim();
+    // An opening fence, whose language tag may itself be partial (` ```jso `)
+    candidate = candidate.replace(/^```[a-zA-Z0-9_-]*\s*/, "");
+    candidate = candidate.replace(/\s*```\s*$/, "");
+    return candidate.trim();
+}
+
+/**
+ * Parse a **partial** JSON document — the text of an answer still streaming.
+ *
+ * The scan tracks string state (and escapes, so `"a\"b"` is one string), closes
+ * the open string, then the open objects and arrays, drops a dangling `,` or `:`
+ * and parses. Anything that still fails returns `undefined`: a partial answer is
+ * best-effort by definition, never an error.
+ *
+ * ```ts
+ * parsePartialJson('{"cities": [{"name": "Par') // { cities: [{ name: 'Par' }] }
+ * parsePartialJson('{"cities": [1,')           // { cities: [1] }
+ * parsePartialJson('```json\n{"a":')           // undefined
+ * ```
+ */
+export function parsePartialJson(text: string): unknown {
+    if (typeof text !== "string") return undefined;
+
+    const source = unfence(text);
+    if (!source) return undefined;
+
+    const open: Array<"{" | "["> = [];
+    let inString = false;
+    let escaped = false;
+
+    for (const char of source) {
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            } else if (char === "\\") {
+                escaped = true;
+            } else if (char === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+
+        if (char === "\"") inString = true;
+        else if (char === "{" || char === "[") open.push(char);
+        else if (char === "}" || char === "]") open.pop();
+    }
+
+    let repaired = source;
+
+    // A dangling escape would escape the quote we are about to add
+    if (inString) {
+        if (escaped) repaired = repaired.slice(0, -1);
+        repaired += "\"";
+    }
+
+    // A key or a value waiting for its other half cannot be completed
+    repaired = repaired.replace(/[,:]\s*$/, "");
+
+    for (let index = open.length - 1; index >= 0; index--) {
+        repaired += open[index] === "{" ? "}" : "]";
+    }
+
+    try {
+        return JSON.parse(repaired);
+    } catch {
+        return undefined;
+    }
+}

package/lib/providers.ts

@@ -201,6 +201,23 @@ function openaiContent(content: string | AgentMediaPart[]): any {
     });
 }
 
+/** A tool message's text, with a marker for the media a text-only protocol cannot take. */
+function toolText(content: string | AgentMediaPart[]): string {
+    if (typeof content === "string") return content;
+    return content.map((part) => {
+        switch (part.type) {
+            case "text":
+                return part.text;
+            case "image":
+                return `[image: ${part.mimeType ?? "image/png"}]`;
+            case "file":
+                return `[file: ${part.name ?? part.mimeType ?? "file"}]`;
+            default:
+                return "";
+        }
+    }).filter(Boolean).join("\n");
+}
+
 /** `AgentMessage[]` → OpenAI `messages[]`. */
 function openaiMessages(system: string | undefined, messages: AgentMessage[]): any[] {
     const out: any[] = [];
@@ -229,7 +246,8 @@ function openaiMessages(system: string | undefined, messages: AgentMessage[]): a
                 break;
             }
             case "tool":
-                out.push({ role: "tool", tool_call_id: message.toolCallId, content: message.content });
+                // OpenAI's tool message is text-only: a media result arrives as a marker
+                out.push({ role: "tool", tool_call_id: message.toolCallId, content: toolText(message.content) });
                 break;
         }
     }
@@ -296,7 +314,13 @@ function anthropicMessages(messages: AgentMessage[]): { system: string | undefin
                 break;
             }
             case "tool": {
-                const block: any = { type: "tool_result", tool_use_id: message.toolCallId, content: message.content };
+                // A string stays a string; a part array (text + image/document) is
+                // converted block by block — `tool_result` accepts both.
+                const block: any = {
+                    type: "tool_result",
+                    tool_use_id: message.toolCallId,
+                    content: typeof message.content === "string" ? message.content : anthropicContent(message.content),
+                };
                 if (message.isError) block.is_error = true;
                 const last = out[out.length - 1];
                 if (last?.role === "user" && Array.isArray(last.content)

package/lib/redact.ts

@@ -100,6 +100,16 @@ function redact(value: any, keys: Set<string>, depth = 0): any {
     return changed ? out : value
 }
 
+/**
+ * Redact secrets embedded in a **free-text** message (`password=…`, `token: …`).
+ * The key-based redactor cannot see those — audit error messages need this.
+ */
+const TEXT_SECRET = /((?:password|passwd|pwd|token|secret|api[_-]?key|authorization)\s*[:=]\s*)([^\s,;]+)/gi;
+
+function redactText(value: string): string {
+    return value.replace(TEXT_SECRET, "$1[redacted]");
+}
+
 /** Redact an audit payload — `input`, `result`, `meta` or `request` */
 function redactPayload(value: any): any {
     const keys = redactKeys()
@@ -113,5 +123,6 @@ export {
     redactKeys,
     isSensitiveKey,
     redactPayload,
+    redactText,
     redact,
 }

package/lib/tracing.ts

@@ -0,0 +1,20 @@
+import type { AgentTraceEvent } from "../types/agent";
+
+/** Receives the milestones of a run — see `AgentTraceEvent`. */
+export type AgentTracer = (event: AgentTraceEvent) => void;
+
+/**
+ * Hand one event to a tracer.
+ *
+ * A tracer is an **observer**: a hook that throws is swallowed, so a broken
+ * exporter can never fail the run it watches. The hook is synchronous — a
+ * promise it returns is not awaited (and is not the framework's to settle).
+ */
+export function trace(tracer: AgentTracer | undefined, event: AgentTraceEvent): void {
+    if (!tracer) return;
+    try {
+        tracer(event);
+    } catch {
+        // Observability must never be a failure mode of the run
+    }
+}