@anteros/core 0.0.40 → 0.0.42

package/lib/jsonSchema.ts

@@ -0,0 +1,183 @@
+import type Joi from "joi";
+
+/**
+ * Schema helpers shared by the MCP server and the agent runtime.
+ *
+ * A tenant declares its schemas in Joi (the collection field DSL, `v`), but the
+ * outside world speaks JSON Schema: the MCP protocol and every model provider
+ * (`tools[].function.parameters` / `tools[].input_schema`) want JSON Schema.
+ * Both callers use the same converter so a tool looks identical wherever it is
+ * exposed. zod and plain JSON Schema objects are accepted as well.
+ */
+
+// ─── Joi → JSON Schema ───────────────────────────────────────────────────
+
+function joiTypeToJson(type: string): string {
+    switch (type) {
+        case 'number': return 'number';
+        case 'integer': return 'integer';
+        case 'boolean': return 'boolean';
+        case 'date': return 'string';
+        default: return 'string';
+    }
+}
+
+/** Minimal Joi → JSON Schema converter (covers the common field types). */
+function joiToJsonSchema(schema: Joi.Schema, describe = schema.describe() as any): any {
+    const node: any = {};
+    const type = describe?.type;
+
+    switch (type) {
+        case 'object': {
+            node.type = 'object';
+            const properties: Record<string, any> = {};
+            const required: string[] = [];
+            for (const [key, child] of Object.entries(describe.keys ?? {})) {
+                properties[key] = joiToJsonSchema(child as any, child);
+                if ((child as any)?.flags?.presence === 'required') required.push(key);
+            }
+            node.properties = properties;
+            if (required.length) node.required = required;
+            break;
+        }
+        case 'array': {
+            node.type = 'array';
+            if (describe.items?.length) node.items = joiToJsonSchema(describe.items[0], describe.items[0]);
+            break;
+        }
+        case 'alternatives': {
+            // Joi alternatives → anyOf (only the simple `try` list is covered)
+            const matches = (describe.matches ?? []).map((m: any) => joiToJsonSchema(m.schema, m.schema));
+            if (matches.length) node.anyOf = matches;
+            else node.type = 'object';
+            break;
+        }
+        default: {
+            node.type = joiTypeToJson(type);
+            if (type === 'date') node.format = 'date-time';
+            if (type === 'string') {
+                for (const rule of describe.rules ?? []) {
+                    if (['email', 'uri', 'uuid', 'isoDate', 'ip'].includes(rule.name)) {
+                        node.format = rule.name;
+                    }
+                    if (rule.name === 'pattern' && rule.args?.regex) {
+                        node.pattern = String(rule.args.regex).replace(/^\/|\/[gimsuy]*$/g, '');
+                    }
+                }
+            }
+            if (describe.valids?.length && describe.valids.length <= 50) {
+                node.enum = describe.valids;
+            }
+            break;
+        }
+    }
+
+    if (describe?.flags?.description) node.description = describe.flags.description;
+    return node;
+}
+
+// ─── Detection ───────────────────────────────────────────────────────────
+
+function isJoiSchema(schema: any): boolean {
+    return !!schema && typeof schema === 'object'
+        && typeof schema.describe === 'function' && typeof schema.validate === 'function';
+}
+
+function isZodSchema(schema: any): boolean {
+    return !!schema && typeof schema === 'object'
+        && typeof schema.safeParse === 'function' && (!!schema._zod || !!schema._def);
+}
+
+function isJsonSchema(schema: any): boolean {
+    return !!schema && typeof schema === 'object'
+        && (typeof schema.type === 'string' || !!schema.properties || !!schema.anyOf || !!schema.oneOf || !!schema.allOf);
+}
+
+// ─── zod → JSON Schema (zod is imported only when a zod schema is used) ──
+
+let zodModule: any | undefined;
+
+async function ensureZod(): Promise<any | null> {
+    if (zodModule !== undefined) return zodModule;
+    try {
+        zodModule = await import("zod");
+    } catch {
+        zodModule = null;
+    }
+    return zodModule;
+}
+
+/** An open object schema — the fallback when nothing usable was declared. */
+function openObjectSchema(): any {
+    return { type: 'object', properties: {}, additionalProperties: true };
+}
+
+/**
+ * Normalize a Joi / zod / JSON Schema into a JSON Schema object.
+ * `undefined` → an open object (the provider requires *some* schema).
+ */
+async function toJsonSchema(schema?: any): Promise<any> {
+    if (schema === undefined || schema === null) return openObjectSchema();
+    if (isJoiSchema(schema)) return joiToJsonSchema(schema);
+    if (isZodSchema(schema)) {
+        const zod = await ensureZod();
+        const convert = zod?.toJSONSchema ?? zod?.z?.toJSONSchema;
+        if (typeof convert !== 'function') {
+            console.error('zod schema support requires zod >= 4 (`z.toJSONSchema`) — schema ignored');
+            return openObjectSchema();
+        }
+        try {
+            return convert(schema, { unrepresentable: 'any' });
+        } catch (err: any) {
+            console.error(`Failed to convert the zod schema to JSON Schema: ${err?.message}`);
+            return openObjectSchema();
+        }
+    }
+    if (isJsonSchema(schema)) return schema;
+    // Unknown shape (a boolean schema, a `{}`…) — pass it through
+    return typeof schema === 'object' ? schema : openObjectSchema();
+}
+
+// ─── Validation ──────────────────────────────────────────────────────────
+
+export type SchemaValidation = { value: any; error: string | null };
+
+/**
+ * Validate a value against a declared schema.
+ * Joi and zod are enforced; a plain JSON Schema is not (there is no validator
+ * in the dependency set) — the value is returned untouched.
+ */
+async function validateWithSchema(schema: any, value: any): Promise<SchemaValidation> {
+    if (schema === undefined || schema === null) return { value, error: null };
+
+    if (isJoiSchema(schema)) {
+        const { error, value: validated } = schema.validate(value, {
+            allowUnknown: true,
+            stripUnknown: false,
+            abortEarly: false,
+            convert: true,
+        });
+        return { value: validated, error: error ? error.message : null };
+    }
+
+    if (isZodSchema(schema)) {
+        const parsed = schema.safeParse(value);
+        if (parsed.success) return { value: parsed.data, error: null };
+        const first = parsed.error?.issues?.[0];
+        const path = first?.path?.length ? `${first.path.join('.')}: ` : '';
+        return { value, error: `${path}${first?.message ?? parsed.error?.message ?? 'invalid'}` };
+    }
+
+    return { value, error: null };
+}
+
+export {
+    joiTypeToJson,
+    joiToJsonSchema,
+    isJoiSchema,
+    isZodSchema,
+    isJsonSchema,
+    openObjectSchema,
+    toJsonSchema,
+    validateWithSchema,
+};

package/lib/lifecycle.ts

@@ -0,0 +1,147 @@
+import path from "path";
+import fs from "fs/promises";
+import { cfg } from "../server/config";
+import { useRest } from "../database/rest";
+import { createAgents } from "./agents";
+import { createApi } from "./api";
+import { logger } from "../utils/logger";
+import {
+    replicationNow,
+    getReplicationState,
+    resetReplication,
+    seedReplication,
+} from "../database/replication";
+import type { Lifecycle, LifecycleReason } from "../types/lifecycle";
+import type { Tenant } from "../types/tenant";
+import type { TenantReplicationApi } from "../types/replication";
+
+/**
+ * Tenant-scoped replication API — like `rest`, the tenant is implicit. Built per
+ * tenant for the lifecycle context, so hooks never pass a tenant id.
+ */
+function tenantReplication(tenantId: string): TenantReplicationApi {
+    return {
+        now: () => replicationNow(tenantId),
+        state: (destinationId?: string, collection?: string) => getReplicationState(tenantId, destinationId, collection),
+        reset: (opts) => resetReplication(tenantId, opts),
+        seed: (value, opts) => seedReplication(tenantId, value, opts),
+    };
+}
+
+/** Lifecycles by tenant id — one `{tenant.dir}/lifecycle.ts` per tenant. */
+const lifecycles = new Map<string, Lifecycle>();
+/** Ensures `onDestroy` runs at most once per process. */
+let destroyed = false;
+
+/**
+ * Load `{tenant.dir}/lifecycle.ts` for every tenant. A missing file is fine —
+ * a tenant simply has no lifecycle.
+ */
+async function loadLifecycles(): Promise<void> {
+    lifecycles.clear();
+    destroyed = false;
+    for (const tenant of cfg.tenants ?? []) {
+        try {
+            const file = path.join(process.cwd(), tenant.dir, "lifecycle.ts");
+            if (!(await fs.exists(file))) continue;
+            const module = await import(file);
+            const lifecycle = module?.default;
+            if (lifecycle?._isLifecycle_) {
+                lifecycles.set(tenant.id, { ...lifecycle, _tenant_: tenant.id });
+            }
+        } catch (err: any) {
+            logger.file("error", "lifecycle: failed to load", { tenant: tenant.id, error: err?.message });
+        }
+    }
+}
+
+/** Tenant-scoped context passed to every hook. */
+function buildContext(tenant: Tenant, extra?: Record<string, any>) {
+    const rest = new useRest({ tenant_id: tenant.id });
+    return {
+        tenant,
+        rest,
+        // Tenant-scoped LLM registry — a lifecycle hook can seed/refresh an agent
+        agents: createAgents(tenant.id, rest),
+        api: createApi(rest),
+        logger,
+        cfg,
+        replication: tenantReplication(tenant.id),
+        ...(extra ?? {}),
+    } as any;
+}
+
+/**
+ * Run every `beforeBoot` hook, sequentially in `cfg.tenants` order. Blocking:
+ * a throwing hook aborts the boot (fail-fast).
+ */
+async function runBeforeBoot(): Promise<void> {
+    for (const tenant of cfg.tenants ?? []) {
+        const lifecycle = lifecycles.get(tenant.id);
+        if (!lifecycle?.enabled || !lifecycle.beforeBoot) continue;
+        try {
+            await lifecycle.beforeBoot(buildContext(tenant));
+            logger.file("lifecycle: beforeBoot", { tenant: tenant.id });
+        } catch (err: any) {
+            logger.error(`lifecycle beforeBoot failed for tenant '${tenant.id}'`, { error: err?.message, stack: err?.stack });
+            throw new Error(`[${tenant.id}] lifecycle beforeBoot failed: ${err?.message ?? err}`);
+        }
+    }
+}
+
+/**
+ * Run every `afterBoot` hook once the server is listening. Errors are logged
+ * but never fatal — the server is already serving.
+ */
+async function runAfterBoot(server: any, io: any): Promise<void> {
+    for (const tenant of cfg.tenants ?? []) {
+        const lifecycle = lifecycles.get(tenant.id);
+        if (!lifecycle?.enabled || !lifecycle.afterBoot) continue;
+        try {
+            await lifecycle.afterBoot(buildContext(tenant, { io, server }));
+            logger.file("lifecycle: afterBoot", { tenant: tenant.id });
+        } catch (err: any) {
+            logger.error(`lifecycle afterBoot failed for tenant '${tenant.id}'`, { error: err?.message });
+        }
+    }
+}
+
+/** Bound a promise with a timeout that rejects. */
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)) as Promise<T>;
+}
+
+/**
+ * Run every `onDestroy` hook on shutdown (once per process), before replication
+ * stops and DB clients close. Each hook is bounded by `destroyTimeout`.
+ */
+async function runOnDestroy(reason: LifecycleReason): Promise<void> {
+    if (destroyed) return;
+    destroyed = true;
+
+    for (const tenant of cfg.tenants ?? []) {
+        const lifecycle = lifecycles.get(tenant.id);
+        if (!lifecycle?.enabled || !lifecycle.onDestroy) continue;
+        try {
+            await withTimeout(
+                Promise.resolve(lifecycle.onDestroy(buildContext(tenant, { reason }))),
+                lifecycle.destroyTimeout ?? 10_000,
+                `lifecycle onDestroy timed out after ${lifecycle.destroyTimeout ?? 10_000}ms`,
+            );
+            logger.file("lifecycle: onDestroy", { tenant: tenant.id, reason });
+        } catch (err: any) {
+            logger.error(`lifecycle onDestroy failed for tenant '${tenant.id}'`, { error: err?.message });
+        }
+    }
+}
+
+export {
+    loadLifecycles,
+    runBeforeBoot,
+    runAfterBoot,
+    runOnDestroy,
+};

package/lib/load.ts

@@ -0,0 +1,17 @@
+/**
+ * Import a tenant definition file (`*.model.ts`, `*.workflow.ts`, …) for a loader.
+ *
+ * A broken file (syntax error, throwing module) must never hide the other
+ * definitions — nor the other tenants: the failure is logged and `null` is
+ * returned, so the caller simply skips that file.
+ */
+async function importDefinition(file: string, kind: string): Promise<any | null> {
+    try {
+        return await import(file)
+    } catch (err: any) {
+        console.error(`Failed to load ${kind} '${file}':`, err?.message)
+        return null
+    }
+}
+
+export { importDefinition }

package/lib/mcp.ts

@@ -3,6 +3,7 @@ import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
 import type { McpTool, McpResource } from "../types/mcp"
+import { importDefinition } from "./load"
 
 /**
  * Load MCP tools & resources from each tenant's `mcp/` folder:
@@ -26,7 +27,7 @@ async function syncMcpTools() {
             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 import(file)
+                    let module = await importDefinition(file, 'MCP tool')
                     if (module?.default?._isMcpTool_ && module?.default?.enabled !== false) {
                         tools.push({ ...module?.default, _tenant_: tenant.id })
                     }
@@ -38,7 +39,7 @@ async function syncMcpTools() {
             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 import(file)
+                    let module = await importDefinition(file, 'MCP resource')
                     if (module?.default?._isMcpResource_ && module?.default?.enabled !== false) {
                         resources.push({ ...module?.default, _tenant_: tenant.id })
                     }

package/lib/messages.ts

@@ -0,0 +1,299 @@
+import { AppError } from "./error";
+import { MAX_FILE_BYTES } from "./attachment";
+import type {
+    AgentAssistantMessage,
+    AgentContentPart,
+    AgentInput,
+    AgentMediaPart,
+    AgentMessage,
+    AgentMessageInput,
+    AgentToolCall,
+    AgentToolCallPart,
+    AgentToolResultEntry,
+    AgentToolResultPart,
+} from "../types/agent";
+
+/**
+ * The message model — one shape for every provider.
+ *
+ * A caller may hand over anything reasonable: a bare `string`, one message, a
+ * whole conversation, or the **unified content parts** another LLM library uses
+ * (`text`, `image`, `file`, `tool-call`, `tool-result`). Everything is normalized
+ * here, once, into the canonical `AgentMessage[]` the runtime, the providers and
+ * the memory all speak:
+ *
+ * | Input | Canonical result |
+ * | --- | --- |
+ * | `'hi'` | `{ role: 'user', content: 'hi' }` |
+ * | `{ role: 'user', content: [{ type: 'text', … }] }` | the same message, media parts kept |
+ * | `{ role: 'user', content: [{ type: 'tool-result', … }] }` | the `tool` message it really is |
+ * | `{ role: 'assistant', content: [{ type: 'tool-call', … }] }` | `toolCalls` on the assistant turn |
+ * | `{ role: 'developer', … }` | kept as-is (mapped per protocol by the adapters) |
+ *
+ * Two rules worth knowing:
+ *
+ * - **Nothing is dropped silently.** A part the role cannot carry (an image on an
+ *   assistant turn, a `tool-call` on a user turn) is refused with `INVALID_INPUT`
+ *   rather than ignored — a conversation quietly losing a turn shows up as a wrong
+ *   answer, three calls later.
+ * - **A remote file is downloaded here** (10 MB cap, same as an attachment):
+ *   OpenAI-compatible endpoints only accept base64 for a document, so inlining it
+ *   once keeps `file: { url }` working on every provider. A remote **image** is
+ *   left as a URL — both protocols fetch it themselves.
+ *
+ * Only the fields of the canonical message survive: an unknown key on the way in
+ * (a stray `threadId`, a provider flag…) never reaches the wire.
+ */
+
+const ROLES = new Set(["system", "developer", "user", "assistant", "tool"]);
+
+function invalid(message: string): AppError {
+    return new AppError(message, { status: 400, code: "INVALID_INPUT" });
+}
+
+/** 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}`;
+    const result = entry.result;
+    if (typeof result === "string") return result;
+    if (result && typeof result === "object" && Array.isArray((result as any).content)) {
+        const texts = (result as any).content
+            .filter((block: any) => block?.type === "text" && typeof block.text === "string")
+            .map((block: any) => block.text);
+        if (texts.length) return texts.join("\n");
+    }
+    if (result === undefined || result === null) return "OK";
+    try {
+        return JSON.stringify(result);
+    } catch {
+        return String(result);
+    }
+}
+
+/** 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");
+    if (foreign) throw invalid(`A \`${role}\` message only carries \`text\` parts`);
+    return parts.map((part: any) => part.text).join("\n");
+}
+
+function isHttpUrl(url: string | undefined): boolean {
+    return typeof url === "string" && /^https?:\/\//i.test(url);
+}
+
+function checkAddress(part: AgentContentPart, role: string): void {
+    const address = (part as { url?: string }).url;
+    if (!address) return;
+    if (isHttpUrl(address) || address.startsWith("data:")) return;
+    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;
+
+    const url = part.url!;
+    let bytes: Uint8Array;
+    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",
+        });
+    }
+
+    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" },
+        );
+    }
+
+    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") };
+}
+
+/** One media part, validated (and fetched when it is a remote file). */
+async function mediaPart(part: AgentContentPart, role: string): Promise<AgentMediaPart> {
+    if (part?.type === "text") {
+        if (typeof part.text !== "string") throw invalid(`A \`text\` part of a ${role} message needs a \`text\``);
+        return { type: "text", text: part.text };
+    }
+
+    if (part?.type === "image" || part?.type === "file") {
+        if (!part.data && !part.url) throw invalid(`A \`${part.type}\` part needs a \`url\` or a \`data\``);
+        checkAddress(part, role);
+
+        // Only what is there: an explicit `undefined` would be stored as `null`
+        const address = part.url ? { url: part.url } : { data: part.data };
+        const media: AgentMediaPart = part.type === "image"
+            ? { type: "image", ...address, ...(part.mimeType ? { mimeType: part.mimeType } : {}) }
+            : {
+                type: "file",
+                ...address,
+                ...(part.name ? { name: part.name } : {}),
+                ...(part.mimeType ? { mimeType: part.mimeType } : {}),
+            };
+        return media.type === "file" ? await inlineRemoteFile(media) : media;
+    }
+
+    throw invalid(`A \`${(part as any)?.type ?? "unknown"}\` part is not valid on a \`${role}\` message`);
+}
+
+/** An `assistant` turn: text (and the tool calls it asked for) — nothing else. */
+function assistantContent(content: string | AgentContentPart[] | null | undefined, role: string): string | null {
+    if (content === null || content === undefined) return null;
+    if (typeof content === "string") return content;
+
+    const media = content.find((part) => part?.type === "image" || part?.type === "file");
+    if (media) throw invalid(`A \`${media.type}\` part is not valid on a \`${role}\` message`);
+
+    return content
+        .filter((part): part is Extract<AgentContentPart, { type: "text" }> => part?.type === "text")
+        .map((part) => part.text)
+        .join("") || null;
+}
+
+/** A `tool-call` part → the canonical tool call the providers are given back. */
+function toToolCall(part: AgentToolCallPart): AgentToolCall {
+    if (!part?.id || !part?.name) throw invalid("A `tool-call` part needs an `id` and a `name`");
+    const raw = part.args ?? part.arguments ?? {};
+    const args = raw && typeof raw === "object" ? (raw as Record<string, any>) : {};
+    const call: AgentToolCall = { id: part.id, name: part.name, args };
+    if (part.argsText) call.argsText = part.argsText;
+    else if (typeof part.arguments === "string") call.argsText = part.arguments;
+    return call;
+}
+
+/** A `tool-result` part → the `tool` message that answers one call. */
+function toToolMessage(part: AgentToolResultPart): AgentMessage {
+    if (!part?.id) throw invalid("A `tool-result` part needs the `id` of the call it answers");
+    const name = part.name ?? "tool";
+    return {
+        role: "tool",
+        toolCallId: part.id,
+        name,
+        content: serializeToolResult({
+            id: part.id,
+            name,
+            args: {},
+            result: part.result,
+            error: part.error,
+            durationMs: 0,
+        }),
+        ...(part.error ? { isError: true } : {}),
+    };
+}
+
+/**
+ * Everything a caller passed → the canonical conversation.
+ *
+ * Structural only: the input is **appended** to whatever a memory already holds —
+ * this function never touches the thread.
+ */
+async function normalizeMessages(input: AgentInput): Promise<AgentMessage[]> {
+    const list: AgentMessageInput[] = typeof input === "string"
+        ? [{ role: "user", content: input }]
+        : Array.isArray(input) ? input : [input];
+
+    const out: AgentMessage[] = [];
+
+    for (const message of list) {
+        if (!message || typeof message !== "object" || typeof (message as any).role !== "string") {
+            throw invalid("Every message needs a `role`");
+        }
+
+        const role = message.role as string;
+        if (!ROLES.has(role)) throw invalid(`Unknown message role '${role}'`);
+
+        const source = message as any;
+        const content = source.content;
+        const named = source.name ? { name: String(source.name) } : {};
+
+        switch (role) {
+            case "system":
+            case "developer": {
+                const text = typeof content === "string"
+                    ? content
+                    : Array.isArray(content)
+                        ? systemText(content, role)
+                        : (() => { throw invalid(`A \`${role}\` message needs a \`content\``); })();
+                // An empty instruction is a mistake, not a message
+                if (!text.trim()) throw invalid(`A \`${role}\` message needs a \`content\``);
+                out.push({ role, content: text, ...named } as AgentMessage);
+                break;
+            }
+
+            case "user": {
+                if (typeof content === "string") {
+                    out.push({ role: "user", content, ...named });
+                    break;
+                }
+                if (!Array.isArray(content)) throw invalid("A `user` message needs a `content`");
+
+                const parts: AgentMediaPart[] = [];
+                const results: AgentMessage[] = [];
+                for (const part of content) {
+                    if (part?.type === "tool-result") results.push(toToolMessage(part));
+                    else if (part?.type === "tool-call") {
+                        throw invalid("A `tool-call` part belongs to an `assistant` message");
+                    } else parts.push(await mediaPart(part, role));
+                }
+                if (!parts.length && !results.length) throw invalid("A `user` message needs a `content`");
+
+                // A turn that is *only* tool results does not leave an empty user turn behind
+                if (parts.length) out.push({ role: "user", content: parts, ...named });
+                // A tool round expressed as `user` parts becomes the turns it means
+                out.push(...results);
+                break;
+            }
+
+            case "assistant": {
+                const inline = Array.isArray(content)
+                    ? content.filter((part): part is AgentToolCallPart => part?.type === "tool-call")
+                    : [];
+                const declared = source.toolCalls as AgentToolCall[] | undefined;
+                const thinking = source.thinking as AgentAssistantMessage["thinking"];
+
+                out.push({
+                    role: "assistant",
+                    content: assistantContent(content, role),
+                    ...(declared?.length || inline.length
+                        ? { toolCalls: [...(declared ?? []), ...inline.map(toToolCall)] }
+                        : {}),
+                    ...(thinking?.length ? { thinking } : {}),
+                    ...named,
+                });
+                break;
+            }
+
+            case "tool": {
+                if (typeof content === "string") {
+                    if (!source.toolCallId) throw invalid("A `tool` message needs a `toolCallId`");
+                    out.push({
+                        role: "tool",
+                        toolCallId: String(source.toolCallId),
+                        name: source.name ? String(source.name) : "tool",
+                        content,
+                        ...(source.isError ? { isError: true } : {}),
+                    });
+                    break;
+                }
+                if (!Array.isArray(content)) throw invalid("A `tool` message needs a `content`");
+                if (!content.length) throw invalid("A `tool` message needs a `content`");
+
+                for (const part of content) {
+                    if (part?.type !== "tool-result") throw invalid("A `tool` message only carries `tool-result` parts");
+                    out.push(toToolMessage(part));
+                }
+                break;
+            }
+        }
+    }
+
+    return out;
+}
+
+export { normalizeMessages, serializeToolResult };