@cubicecho/agent-core 2.16.0 → 2.18.0

package/dist/spec.js

@@ -0,0 +1,662 @@
+/**
+ * A JSON document that defines an agent, and the rules for reading one.
+ *
+ * Four applications sit on this package and each one spells "an agent" differently: a singleton
+ * settings row, a deliberately jobless agent table whose job comes from three other rows, an
+ * override profile that resolves into a whole synthesised settings object. None of them can read
+ * another's agents, and `maxTokens: 0` means *no ceiling* in one, *inherit* in the next and *a
+ * real ceiling of zero* in the third. This is the shape they can all write and all read, argued
+ * out in `docs/agent-spec.md` before any of it was code.
+ *
+ * Nothing else in `src/` imports this module, and this module imports nothing but types. That is
+ * the same seam `config.ts` draws — the loop takes the parts it reads, not a config object — and
+ * it is what lets the document travel between hosts without the loop growing an opinion about
+ * where an agent comes from. It is also why this is importable in a browser, where `client.ts`
+ * and `hooks.ts` are not: a host validating a pasted document in a form needs no `node:crypto`.
+ */
+/** The token a document declares itself with. A loader refuses anything else. */
+export const AGENT_SPEC = "cubicecho.agent/1";
+/** The major version `AGENT_SPEC` pins. Raised only when a field changes meaning. */
+export const AGENT_SPEC_VERSION = 1;
+/**
+ * The side tasks this package has code for: documentation and a sensible UI order, not a
+ * validator.
+ *
+ * `tasks` is an open record on purpose — a host may run tasks this package has never heard of,
+ * and an unknown key is carried through untouched rather than warned about.
+ */
+export const AGENT_TASKS = ["compaction", "toolSelect", "title", "followups"];
+/**
+ * Every event a hook may be bound to, restated so this module stays free of `node:crypto`.
+ *
+ * `hooks.ts` owns the list; importing its `HOOK_EVENTS` would pull the whole module, and its
+ * `createHash` with it, into a file whose whole point is that a browser can load it. The `HookEvent`
+ * type is imported and erased, so a removed event fails to compile here, and a test asserts this
+ * list and `HOOK_EVENTS` are the same list so an added one cannot drift quietly.
+ */
+export const SPEC_EVENTS = [
+    "sessionStart",
+    "beforeTurn",
+    "afterTurn",
+    "beforeCompact",
+    "sessionEnd",
+    "sessionDelete",
+];
+/** The events whose output can still reach a request, so the only ones `inject` means anything on. */
+const SPEC_INJECT = new Set(["sessionStart", "beforeTurn"]);
+/** Body fields the loop owns. `buildBody` would overwrite them anyway; better to say so on import. */
+const RESERVED_BODY = ["model", "messages", "stream", "tools"];
+/**
+ * What a field falls back to when no layer said anything at all.
+ *
+ * Not sentinels, and not invented: `toolDiscovery`, `maxRetries` and `contextLength` are the
+ * "absent everywhere" column of the document's own table, and `temperature` and `maxToolIterations`
+ * are what all three consumers store as their defaults today. A field left out here is left out of
+ * the resolved object too, which is how `requestTimeoutSeconds` keeps meaning "no opinion".
+ */
+export const RESOLVED_DEFAULTS = {
+    temperature: 0.7,
+    maxTokens: 0,
+    contextLength: 0,
+    toolDiscovery: "eager",
+    maxToolIterations: 20,
+    maxRetries: 0,
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Absent and null are the same thing: a nullable column round-trips through JSON as `null`. */
+const absent = (value) => value === undefined || value === null;
+/** A `${VAR}`-shaped string, which is kept as the literal it is rather than expanded. */
+const VARIABLE = /\$\{[^}]*\}/;
+/** Problems in the order they were found, in `validateHooks`'s `path: what is wrong` shape. */
+class Report {
+    errors = [];
+    warnings = [];
+    fail(path, problem) {
+        this.errors.push(`${path}: ${problem}`);
+    }
+    drop(path, problem) {
+        this.warnings.push(`${path}: ${problem}, and was dropped`);
+    }
+    note(path, problem) {
+        this.warnings.push(`${path}: ${problem}`);
+    }
+    /**
+     * A string field, or nothing. Interpolation is never performed, so a `${VAR}` is reported as
+     * the literal it will stay — the alternative hands whoever wrote the document the ability to
+     * read any variable the process has, which is why the formats that do it need a credential
+     * denylist bolted on afterwards.
+     */
+    string(path, value) {
+        if (absent(value))
+            return undefined;
+        if (typeof value !== "string")
+            return void this.drop(path, "must be a string");
+        if (VARIABLE.test(value))
+            this.note(path, "looks like a variable reference, which is never expanded");
+        return value;
+    }
+    number(path, value, least, most = Infinity) {
+        if (absent(value))
+            return undefined;
+        if (typeof value !== "number" || !Number.isFinite(value))
+            return void this.drop(path, "must be a number");
+        // Dropped, never clamped: a clamp invents a number the author did not write, while dropping
+        // falls back to one somebody did — the layer below, or nothing.
+        if (value < least || value > most)
+            return void this.drop(path, `must be ${most === Infinity ? `at least ${least}` : `between ${least} and ${most}`}`);
+        return value;
+    }
+    boolean(path, value) {
+        if (absent(value))
+            return undefined;
+        if (typeof value !== "boolean")
+            return void this.drop(path, "must be true or false");
+        return value;
+    }
+}
+/** Drops the keys whose value did not survive, so an absent field stays absent. */
+function kept(fields) {
+    const out = {};
+    for (const [key, value] of Object.entries(fields))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+/** Whether a parsed sub-object said anything at all. An empty one is the same as an absent one. */
+const said = (value) => Object.keys(value).length > 0;
+function parseEndpoint(report, path, value) {
+    if (absent(value))
+        return undefined;
+    if (!isRecord(value))
+        return void report.drop(path, "must be an object");
+    const endpoint = kept({
+        baseUrl: report.string(`${path}.baseUrl`, value.baseUrl),
+        requestTimeoutSeconds: report.number(`${path}.requestTimeoutSeconds`, value.requestTimeoutSeconds, 0),
+        firstTokenSeconds: report.number(`${path}.firstTokenSeconds`, value.firstTokenSeconds, 0),
+    });
+    if (!absent(value.apiKey) || !absent(value.api_key))
+        report.drop(`${path}.apiKey`, "is not part of this format — a document carries no credentials");
+    return said(endpoint) ? endpoint : undefined;
+}
+function parseModel(report, value) {
+    if (absent(value))
+        return undefined;
+    if (!isRecord(value))
+        return void report.drop("model", "must be an object");
+    let extraBody;
+    if (!absent(value.extraBody)) {
+        if (!isRecord(value.extraBody))
+            report.drop("model.extraBody", "must be an object");
+        else {
+            extraBody = {};
+            for (const [key, held] of Object.entries(value.extraBody)) {
+                if (RESERVED_BODY.includes(key))
+                    report.drop(`model.extraBody.${key}`, "is the loop's to set");
+                else
+                    extraBody[key] = held;
+            }
+        }
+    }
+    return kept({
+        model: report.string("model.model", value.model),
+        maxTokens: report.number("model.maxTokens", value.maxTokens, 0),
+        temperature: report.number("model.temperature", value.temperature, 0, 2),
+        reasoningEffort: report.string("model.reasoningEffort", value.reasoningEffort),
+        contextLength: report.number("model.contextLength", value.contextLength, 0),
+        extraBody,
+    });
+}
+function parsePrompt(report, value) {
+    const parts = [];
+    for (const [index, held] of value.entries()) {
+        const path = `prompt[${index}]`;
+        if (!isRecord(held)) {
+            report.drop(path, "must be an object");
+            continue;
+        }
+        const id = report.string(`${path}.id`, held.id);
+        if (!id) {
+            report.drop(path, "has no id, and merging happens on the id");
+            continue;
+        }
+        const text = report.string(`${path}.text`, held.text);
+        let ref;
+        if (!absent(held.ref)) {
+            const raw = held.ref;
+            const type = isRecord(raw) ? raw.type : undefined;
+            const value = isRecord(raw) ? report.string(`${path}.ref.value`, raw.value) : undefined;
+            if ((type === "file" || type === "url") && value)
+                ref = { type, value };
+            else
+                report.drop(`${path}.ref`, 'must be { type: "file" | "url", value }');
+        }
+        // An empty text is how a layer deletes the part below it, so it is not the same as neither.
+        if (text === undefined && !ref) {
+            report.drop(path, "has neither text nor a reference");
+            continue;
+        }
+        parts.push(kept({ id, text, ref }));
+    }
+    return parts;
+}
+function parseTools(report, value) {
+    if (absent(value))
+        return undefined;
+    if (!isRecord(value))
+        return void report.drop("tools", "must be an object");
+    let discovery;
+    if (!absent(value.discovery)) {
+        if (value.discovery === "eager" || value.discovery === "ondemand")
+            discovery = value.discovery;
+        else
+            report.drop("tools.discovery", 'must be "eager" or "ondemand"');
+    }
+    let servers;
+    if (!absent(value.servers)) {
+        if (!Array.isArray(value.servers))
+            report.drop("tools.servers", "must be an array of slugs");
+        else {
+            // The empty array survives on purpose: it is "no servers", and collapsing it into absent
+            // would turn a scoped agent into one holding every tool on the box.
+            servers = [];
+            for (const [index, slug] of value.servers.entries()) {
+                const name = report.string(`tools.servers[${index}]`, slug);
+                if (name)
+                    servers.push(name);
+                else if (name === "")
+                    report.drop(`tools.servers[${index}]`, "is empty");
+            }
+        }
+    }
+    return kept({
+        discovery,
+        maxIterations: report.number("tools.maxIterations", value.maxIterations, 1),
+        servers,
+    });
+}
+function parseRetry(report, value) {
+    if (absent(value))
+        return undefined;
+    if (!isRecord(value))
+        return void report.drop("retry", "must be an object");
+    const retry = kept({
+        maxRetries: report.number("retry.maxRetries", value.maxRetries, 0),
+        loadingTimeoutSeconds: report.number("retry.loadingTimeoutSeconds", value.loadingTimeoutSeconds, 0),
+    });
+    return said(retry) ? retry : undefined;
+}
+function parseTasks(report, value) {
+    const tasks = {};
+    for (const [key, held] of Object.entries(value)) {
+        const path = `tasks.${key}`;
+        if (absent(held))
+            continue;
+        if (!isRecord(held)) {
+            report.drop(path, "must be an object");
+            continue;
+        }
+        // An unknown key is not warned about: a host may run side tasks this package has never
+        // heard of, and `AGENT_TASKS` is documentation rather than a validator.
+        tasks[key] = kept({
+            model: report.string(`${path}.model`, held.model),
+            endpoint: parseEndpoint(report, `${path}.endpoint`, held.endpoint),
+            maxTokens: report.number(`${path}.maxTokens`, held.maxTokens, 0),
+            temperature: report.number(`${path}.temperature`, held.temperature, 0, 2),
+            reasoningEffort: report.string(`${path}.reasoningEffort`, held.reasoningEffort),
+        });
+    }
+    return tasks;
+}
+function parseHooks(report, value, events) {
+    const hooks = [];
+    for (const [index, held] of value.entries()) {
+        const path = `hooks[${index}]`;
+        if (!isRecord(held)) {
+            report.drop(path, "must be an object");
+            continue;
+        }
+        const id = report.string(`${path}.id`, held.id);
+        const server = report.string(`${path}.server`, held.server);
+        const tool = report.string(`${path}.tool`, held.tool);
+        const on = report.string(`${path}.on`, held.on);
+        if (!id || !server || !tool || !on) {
+            report.drop(path, "needs an id, an event, a server and a tool");
+            continue;
+        }
+        if (!SPEC_EVENTS.includes(on)) {
+            report.drop(`${path}.on`, `"${on}" is not an event`);
+            continue;
+        }
+        // A host that never compacts refuses to save a `beforeCompact` hook today, which makes an
+        // otherwise good agent unimportable. Kept and noted instead.
+        if (!events.includes(on))
+            report.note(`${path}.on`, `"${on}" is never fired by this host`);
+        let inject = report.boolean(`${path}.inject`, held.inject);
+        if (inject && !SPEC_INJECT.has(on)) {
+            report.drop(`${path}.inject`, `"${on}" runs after the model has already answered`);
+            inject = undefined;
+        }
+        let veto = report.boolean(`${path}.veto`, held.veto);
+        if (veto && on !== "beforeCompact") {
+            report.drop(`${path}.veto`, `"${on}" announces nothing a hook can decline`);
+            veto = undefined;
+        }
+        hooks.push(kept({
+            id,
+            on: on,
+            server,
+            tool,
+            args: absent(held.args) ? undefined : held.args,
+            inject,
+            veto,
+            maxTokens: report.number(`${path}.maxTokens`, held.maxTokens, 0),
+            timeoutMs: report.number(`${path}.timeoutMs`, held.timeoutMs, 0),
+            enabled: report.boolean(`${path}.enabled`, held.enabled),
+        }));
+    }
+    return hooks;
+}
+function parseBundle(report, value) {
+    if (absent(value))
+        return undefined;
+    if (!isRecord(value))
+        return void report.drop("bundle", "must be an object");
+    if (absent(value.mcpServers))
+        return undefined;
+    if (!Array.isArray(value.mcpServers))
+        return void report.drop("bundle.mcpServers", "must be an array");
+    const seen = new Set();
+    const servers = [];
+    for (const [index, held] of value.mcpServers.entries()) {
+        const path = `bundle.mcpServers[${index}]`;
+        if (!isRecord(held)) {
+            report.drop(path, "must be an object");
+            continue;
+        }
+        const slug = typeof held.slug === "string" && held.slug ? held.slug : undefined;
+        const id = typeof held.id === "string" && held.id ? held.id : undefined;
+        const effective = slug ?? id;
+        if (!effective) {
+            report.drop(path, "needs an id or a slug");
+            continue;
+        }
+        if (seen.has(effective)) {
+            report.drop(path, `is a second server called "${effective}"`);
+            continue;
+        }
+        seen.add(effective);
+        // Everything else is passed through untouched, including keys this package has no name for.
+        servers.push(held);
+    }
+    return { mcpServers: servers };
+}
+/** The keys this version names. Anything else is a later 1.x, and is carried rather than erased. */
+const KNOWN = new Set([
+    "spec",
+    "$schema",
+    "id",
+    "name",
+    "description",
+    "endpoint",
+    "model",
+    "prompt",
+    "tools",
+    "retry",
+    "tasks",
+    "hooks",
+    "bundle",
+    "extensions",
+    "requires",
+]);
+/**
+ * Reads a document, dropping what it cannot use and refusing only what it cannot identify.
+ *
+ * Every problem is reported at once, in the `path: what is wrong` shape `validateHooks` already
+ * uses, because a host showing an operator one error at a time makes them fix a document one
+ * round trip at a time.
+ *
+ * There are exactly four hard errors, all of them about the document rather than a value: it is
+ * not an object; the `spec` token is missing or of another major; a `requires` entry this host
+ * does not understand; a container of the wrong kind. Everything else drops the offending field
+ * and warns — the lesson a consumer learned the hard way when one stored out-of-range value
+ * stopped its server booting. Out-of-range values are dropped rather than clamped, because a
+ * clamp invents a number the author did not write while dropping falls back to one somebody did.
+ *
+ * Version handling is the deliberate opposite of `importCapabilities`, which shrugs at a foreign
+ * version and returns false: degrade where the loss is performance, refuse where the loss is
+ * identity. A snapshot of the wrong version costs a few refused requests; an agent of the wrong
+ * version is not the agent its author described.
+ *
+ * @param document Anything at all — this is the front door, and it is given parsed JSON from a
+ * form, a file or another host.
+ * @param options Whether to parse a bundle, which events this host fires, and which extension
+ * keys it understands.
+ */
+export function parseSpec(document, options = {}) {
+    const report = new Report();
+    const events = options.events ?? SPEC_EVENTS;
+    if (!isRecord(document)) {
+        report.fail("spec", "must be an object");
+        return { spec: null, errors: report.errors, warnings: report.warnings };
+    }
+    const token = document.spec;
+    if (typeof token !== "string")
+        report.fail("spec", `must be "${AGENT_SPEC}"`);
+    else if (token !== AGENT_SPEC) {
+        const major = Number(token.split("/")[1]);
+        const named = token.startsWith("cubicecho.agent/") && Number.isInteger(major);
+        report.fail("spec", named
+            ? `is version ${major}, and this build reads version ${AGENT_SPEC_VERSION}`
+            : `must be "${AGENT_SPEC}"`);
+    }
+    // Containers are checked before their contents: "prompt must be an array" is a different
+    // mistake from "this prompt part has no id", and only the first is worth refusing over.
+    if (!absent(document.prompt) && !Array.isArray(document.prompt))
+        report.fail("prompt", "must be an array");
+    if (!absent(document.tasks) && !isRecord(document.tasks))
+        report.fail("tasks", "must be an object");
+    if (!absent(document.hooks) && !Array.isArray(document.hooks))
+        report.fail("hooks", "must be an array");
+    const requires = [];
+    if (!absent(document.requires)) {
+        if (!Array.isArray(document.requires))
+            report.fail("requires", "must be an array");
+        else
+            for (const [index, key] of document.requires.entries()) {
+                if (typeof key !== "string") {
+                    report.fail(`requires[${index}]`, "must be a string");
+                    continue;
+                }
+                // Fails closed: an agent that must not run without its sandbox extension can say so.
+                if (options.understands && !options.understands.includes(key))
+                    report.fail(`requires[${index}]`, `"${key}" is not understood by this host`);
+                requires.push(key);
+            }
+    }
+    let extensions;
+    if (!absent(document.extensions)) {
+        if (!isRecord(document.extensions))
+            report.drop("extensions", "must be an object");
+        // Never validated beyond being an object. It is the escape hatch, and the one place a host
+        // can put what this package has no name for without being told about it.
+        else
+            extensions = document.extensions;
+    }
+    if (!absent(document.bundle) && !options.bundle)
+        report.drop("bundle", "carries a command line, so it is only read with { bundle: true }");
+    const spec = {
+        spec: AGENT_SPEC,
+        ...kept({
+            $schema: report.string("$schema", document.$schema),
+            id: report.string("id", document.id),
+            name: report.string("name", document.name),
+            description: report.string("description", document.description),
+            endpoint: parseEndpoint(report, "endpoint", document.endpoint),
+            model: parseModel(report, document.model),
+            prompt: Array.isArray(document.prompt) ? parsePrompt(report, document.prompt) : undefined,
+            tools: parseTools(report, document.tools),
+            retry: parseRetry(report, document.retry),
+            tasks: isRecord(document.tasks) ? parseTasks(report, document.tasks) : undefined,
+            hooks: Array.isArray(document.hooks) ? parseHooks(report, document.hooks, events) : undefined,
+            bundle: options.bundle ? parseBundle(report, document.bundle) : undefined,
+            extensions,
+            requires: absent(document.requires) ? undefined : requires,
+        }),
+    };
+    for (const [key, held] of Object.entries(document)) {
+        if (KNOWN.has(key))
+            continue;
+        // Kept, not erased: a host stores what it was given and resolves on read, so a key from a
+        // later 1.x survives an edit-and-export cycle instead of dying at the first host to open it.
+        report.note(key, "is not a key this version names, and was carried through unread");
+        spec[key] = held;
+    }
+    return {
+        spec: report.errors.length ? null : spec,
+        errors: report.errors,
+        warnings: report.warnings,
+    };
+}
+/** Merges the layers that named a key, last one winning, and leaves it absent if none did. */
+function mergeEndpoints(layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.baseUrl !== undefined)
+            out.baseUrl = layer.baseUrl;
+        if (layer.requestTimeoutSeconds !== undefined)
+            out.requestTimeoutSeconds = layer.requestTimeoutSeconds;
+        if (layer.firstTokenSeconds !== undefined)
+            out.firstTokenSeconds = layer.firstTokenSeconds;
+    }
+    return out;
+}
+/** An `Endpoint` as the loop takes one. `apiKey` is always empty; see `resolveAgentSpec`. */
+const asEndpoint = (spec) => ({
+    baseUrl: spec.baseUrl ?? "",
+    apiKey: "",
+    ...kept({
+        requestTimeoutSeconds: spec.requestTimeoutSeconds,
+        firstTokenSeconds: spec.firstTokenSeconds,
+    }),
+});
+/**
+ * Layers documents into the flat object the loop takes, weakest first.
+ *
+ * Absent inherits, and nothing else does: `0`, `-1`, `""` and `[]` are values that mean what they
+ * say, which is the whole reason the format exists — `maxTokens: 0` means three different things
+ * across the three applications this was extracted from, and `temperature: 0` is unsayable in one
+ * of them. Scalars take the last layer that has the key. `extraBody` and `extensions` merge by
+ * top-level key. `prompt`, `hooks` and `tasks` merge by id, ordered by first appearance, which is
+ * one rule expressing two behaviours that look unrelated: different ids stack, and the same id
+ * replaces. `tools.servers` replaces whole, because a tri-state cannot be unioned. `requires`
+ * unions, so a layer above cannot quietly drop a requirement below it.
+ *
+ * No layer is ever fetched. There is no `extends` field and no URL resolution; which documents
+ * layer is the host's call, the same answer `resolveApiKey` gives about keys. `apiKey` comes back
+ * empty for the same reason: a document naming somebody else's endpoint must not be able to make
+ * this host send its own provider key there. A host that wants inheritance applies `resolveApiKey`
+ * afterwards.
+ *
+ * @param layers The documents, weakest first: settings, then the agent, then a task, then a step.
+ */
+export function resolveAgentSpec(layers) {
+    const endpoint = mergeEndpoints(layers.map((layer) => layer.endpoint));
+    const model = {};
+    const extraBody = {};
+    for (const layer of layers) {
+        for (const [key, value] of Object.entries(layer.model ?? {})) {
+            if (value === undefined)
+                continue;
+            if (key === "extraBody")
+                Object.assign(extraBody, value);
+            else
+                model[key] = value;
+        }
+    }
+    const parts = new Map();
+    for (const layer of layers)
+        for (const part of layer.prompt ?? [])
+            parts.set(part.id, { ...(parts.get(part.id) ?? { id: part.id }), ...part });
+    const tools = {};
+    for (const layer of layers) {
+        if (layer.tools?.discovery !== undefined)
+            tools.discovery = layer.tools.discovery;
+        if (layer.tools?.maxIterations !== undefined)
+            tools.maxIterations = layer.tools.maxIterations;
+        // Replaced whole rather than unioned: a list, an empty list and no list are three answers,
+        // and a union of the first two is the first, which loses the scoping the operator asked for.
+        if (layer.tools?.servers !== undefined)
+            tools.servers = [...layer.tools.servers];
+    }
+    const retry = {};
+    for (const layer of layers) {
+        if (layer.retry?.maxRetries !== undefined)
+            retry.maxRetries = layer.retry.maxRetries;
+        if (layer.retry?.loadingTimeoutSeconds !== undefined)
+            retry.loadingTimeoutSeconds = layer.retry.loadingTimeoutSeconds;
+    }
+    const merged = new Map();
+    for (const layer of layers)
+        for (const [key, task] of Object.entries(layer.tasks ?? {}))
+            merged.set(key, {
+                ...(merged.get(key) ?? {}),
+                ...task,
+                endpoint: mergeEndpoints([merged.get(key)?.endpoint, task.endpoint]),
+            });
+    const tasks = {};
+    for (const [key, task] of merged) {
+        // `model: ""` is how a layer declines a task a layer below it configured, so the entry goes
+        // rather than coming back with an empty model for the host to interpret.
+        if (!task.model)
+            continue;
+        tasks[key] = kept({
+            model: task.model,
+            endpoint: asEndpoint(mergeEndpoints([endpoint, task.endpoint])),
+            maxTokens: task.maxTokens,
+            temperature: task.temperature,
+            reasoningEffort: task.reasoningEffort,
+        });
+    }
+    const hooks = new Map();
+    for (const layer of layers)
+        for (const hook of layer.hooks ?? [])
+            hooks.set(hook.id, { ...(hooks.get(hook.id) ?? hook), ...hook });
+    const servers = new Map();
+    for (const layer of layers)
+        for (const server of layer.bundle?.mcpServers ?? []) {
+            const slug = server.slug ?? server.id;
+            if (slug)
+                servers.set(slug, { ...(servers.get(slug) ?? {}), ...server });
+        }
+    const extensions = {};
+    for (const layer of layers)
+        Object.assign(extensions, layer.extensions ?? {});
+    const requires = new Set();
+    for (const layer of layers)
+        for (const key of layer.requires ?? [])
+            requires.add(key);
+    const id = [...layers].reverse().find((layer) => layer.id)?.id ?? "";
+    const name = [...layers].reverse().find((layer) => layer.name)?.name;
+    const description = [...layers].reverse().find((layer) => layer.description)?.description;
+    const prompt = [...parts.values()];
+    return {
+        id,
+        name: name ?? id,
+        description: description ?? "",
+        baseUrl: endpoint.baseUrl ?? "",
+        apiKey: "",
+        ...kept({
+            requestTimeoutSeconds: endpoint.requestTimeoutSeconds,
+            firstTokenSeconds: endpoint.firstTokenSeconds,
+            loadingTimeoutSeconds: retry.loadingTimeoutSeconds,
+            reasoningEffort: model.reasoningEffort,
+            extraBody: said(extraBody) ? extraBody : undefined,
+            servers: tools.servers,
+        }),
+        model: model.model ?? "",
+        maxTokens: model.maxTokens ?? RESOLVED_DEFAULTS.maxTokens,
+        temperature: model.temperature ?? RESOLVED_DEFAULTS.temperature,
+        contextLength: model.contextLength ?? RESOLVED_DEFAULTS.contextLength,
+        toolDiscovery: tools.discovery ?? RESOLVED_DEFAULTS.toolDiscovery,
+        toolSelectModel: tasks.toolSelect?.model ?? "",
+        maxToolIterations: tools.maxIterations ?? RESOLVED_DEFAULTS.maxToolIterations,
+        maxRetries: retry.maxRetries ?? RESOLVED_DEFAULTS.maxRetries,
+        // Byte-identical to what a consumer's `systemPromptFor` produces today, so four sources
+        // survive a round trip instead of flattening into one blob nobody can edit a third of.
+        systemPrompt: prompt
+            .map((part) => part.text?.trim() ?? "")
+            .filter(Boolean)
+            .join("\n\n"),
+        prompt,
+        tasks,
+        hooks: [...hooks.values()],
+        mcpServers: [...servers.values()],
+        extensions,
+        requires: [...requires],
+    };
+}
+/**
+ * A document fit to leave the host: the same agent, with the secrets of its bundled servers gone.
+ *
+ * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
+ * resolves, and what comes back is the same agent pointed at the same servers, needing only the
+ * credentials the importing host supplies itself. So this removes values rather than keys, and
+ * nothing outside `bundle` is touched: the format has no credential field at any depth, which is
+ * the reason there is nothing else to strip.
+ *
+ * @param spec A document, ordinarily one `parseSpec` returned.
+ * @param options Whether to keep the secrets. The default is not to.
+ */
+export function exportSpec(spec, { secrets = false } = {}) {
+    if (secrets || !spec.bundle?.mcpServers)
+        return { ...spec };
+    return {
+        ...spec,
+        bundle: {
+            ...spec.bundle,
+            mcpServers: spec.bundle.mcpServers.map(({ env: _env, headers: _headers, ...rest }) => rest),
+        },
+    };
+}