@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/agents/definition.js

@@ -1,5 +1,7 @@
 import { validateParams } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { isLegacyBuiltinKey, isLegacyPrefixedKey, legacyToolKey, } from "../tools/legacy-keys.js";
+import { InstructionFilesSchema } from "./instruction-files.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export const ModelRef = z.object({ provider: z.string(), model: z.string() });
 /**
@@ -37,14 +39,7 @@ export const AgentToolRef = z.preprocess(normalizeToolRef, z.discriminatedUnion(
     })
         .strict(),
 ]));
-/**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
- */
-export const DEFAULT_AGENT_TOOLS = [
-    { kind: "builtin", name: "ask_user" },
-    { kind: "builtin", name: "read_tool_output" },
-];
+export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export const SUBAGENT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /**
@@ -68,7 +63,7 @@ export const InlineAgentTemplate = z
 })
     .strict();
 /**
- * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * Sub-agents this agent may dispatch with the builtin `Agent` tool (phase C, spec §5.2). No
  * default: definitions without it are unchanged and gain no version.
  */
 export const SubagentsSchema = z
@@ -100,7 +95,16 @@ export const SubagentsSchema = z
 export const AgentDefinitionSchema = z.object({
     name: z.string().min(1).max(80),
     avatarUrl: z.url().nullable().default(null),
+    /**
+     * The model-visible system prompt. Derived on save from `instructionFiles` when they are given
+     * (`deriveInstructions`); every reader (build.ts, the sub-agent copy, evals, replay) reads this.
+     */
     instructions: z.string().max(100_000).default(""),
+    /**
+     * The prompt files, the authoring form of `instructions` (spec 2026-11-04 §3.3). No default:
+     * definitions without it (every older version) read as one `AGENTS.md` and gain no version.
+     */
+    instructionFiles: InstructionFilesSchema.optional(),
     model: ModelRef,
     fallback: ModelRef.nullable().default(null),
     /** 主模型的参数（按主模型的声明校验）。 */
@@ -118,7 +122,7 @@ export const AgentDefinitionSchema = z.object({
      * 技能（M5 T13）：`orgSkills` 是引用的组织技能 id（保存时校验属于本组织且未删除，不可重复）。
      * agent 自己的技能（`scope=agent`）自动对它生效，不进定义。可省略（较早保存的定义也没有），按空处理；
      * 不给默认值：没用技能的定义保存前后不变，不会因此多出一个版本。
-     * `writePolicy`（M6 T27，D10）：私有 agent 的 `skill_write` 是否固定确认，缺省按 `allow`（不写进定义）；
+     * `writePolicy`（M6 T27，D10）：私有 agent 的 `SkillWrite` 是否固定确认，缺省按 `allow`（不写进定义）；
      * 共享 agent 不论取值都走 R3 + R4。
      */
     skills: z
@@ -136,20 +140,202 @@ export const AgentDefinitionSchema = z.object({
     })
         .strict()
         .optional(),
-    /** Sub-agents (phase C); offered only when the builtin `agent` tool is in `tools`. */
+    /** Sub-agents (phase C); offered only when the builtin `Agent` tool is in `tools`. */
     subagents: SubagentsSchema.optional(),
 });
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The connector slugs and extension names `definition`'s `tools` name: connector refs (through
+ * `scope.connectorSlugById`), plugin refs, and current-format keys of a template's `tools`;
+ * `inherited` (the parent agent's, for an inline template) is added.
+ */
+function ownRefs(definition, scope, inherited) {
+    const connectors = new Set(inherited?.connectors);
+    const extensions = new Set(inherited?.extensions);
+    const tools = Array.isArray(definition.tools) ? definition.tools : [];
+    for (const r of tools) {
+        if (typeof r === "string") {
+            const m = /^(mcp|plugin)__([^_].*?)__./.exec(r);
+            if (m)
+                (m[1] === "mcp" ? connectors : extensions).add(m[2]);
+        }
+        else if (isRecord(r) && r.kind === "connector" && typeof r.connectorId === "string") {
+            const slug = scope.connectorSlugById?.get(r.connectorId);
+            if (slug !== undefined)
+                connectors.add(slug);
+        }
+        else if (isRecord(r) && r.kind === "plugin" && typeof r.plugin === "string") {
+            extensions.add(r.plugin);
+        }
+    }
+    return { connectors, extensions };
+}
+/**
+ * The current key(s) of a stored key. A builtin and an unambiguous `<x>__<tool>` map to one key
+ * ({@link legacyToolKey}). When `x` is both a connector slug and an extension name, the
+ * definition's own refs decide (only connector `x` -> `mcp__…`, only extension `x` ->
+ * `plugin__…`); when they name both or neither, both candidates are returned and the caller
+ * decides (a policy keeps a deny / ask on both: it must never be lost). Anything else: as is.
+ */
+function currentKeys(key, scope, own) {
+    const one = legacyToolKey(key, scope);
+    if (one !== null)
+        return [one];
+    if (scope === undefined || !isLegacyPrefixedKey(key))
+        return [key];
+    const head = key.slice(0, key.indexOf("__"));
+    if (!scope.connectorSlugs.has(head) || !scope.extensionNames.has(head))
+        return [key];
+    const c = own?.connectors.has(head) === true;
+    const e = own?.extensions.has(head) === true;
+    if (c && !e)
+        return [`mcp__${key}`];
+    if (e && !c)
+        return [`plugin__${key}`];
+    return [`mcp__${key}`, `plugin__${key}`];
+}
+/**
+ * A list of tool keys (a template's `tools` / `disallowedTools`) in current keys, deduplicated.
+ * A still-ambiguous key becomes both candidates in a deny list (`widen`), and stays as is (inert,
+ * so narrower) in an allowlist.
+ */
+function keyList(v, scope, own, widen) {
+    if (!Array.isArray(v))
+        return v;
+    let changed = false;
+    const out = [];
+    for (const x of v) {
+        let next = [x];
+        if (typeof x === "string") {
+            const keys = currentKeys(x, scope, own);
+            next = keys.length > 1 && !widen ? [x] : keys;
+        }
+        if (next.length !== 1 || next[0] !== x)
+            changed = true;
+        for (const n of next) {
+            if (typeof n === "string" && out.includes(n)) {
+                changed = true;
+                continue;
+            }
+            out.push(n);
+        }
+    }
+    return changed ? out : v;
+}
+/**
+ * `toolPolicies` in current keys; keys that become one keep the stricter policy, and a
+ * still-ambiguous key keeps its `ask` / `deny` on both candidates (anything else is dropped).
+ */
+function policyKeys(v, scope, own) {
+    if (!isRecord(v))
+        return v;
+    const mapped = Object.entries(v).map(([k, p]) => [k, p, currentKeys(k, scope, own)]);
+    if (mapped.every(([k, , keys]) => keys.length === 1 && keys[0] === k))
+        return v;
+    const rank = (p) => (p === "deny" ? 2 : p === "ask" ? 1 : 0);
+    const out = {};
+    for (const [, p, keys] of mapped) {
+        if (keys.length > 1 && rank(p) === 0)
+            continue;
+        for (const next of keys) {
+            if (!Object.hasOwn(out, next) || rank(p) > rank(out[next]))
+                out[next] = p;
+        }
+    }
+    return out;
+}
+/** An agent definition's `tools`: builtin refs by their current names (connector and plugin refs name tools, not keys). */
+function toolRefs(v, scope, own) {
+    if (!Array.isArray(v))
+        return v;
+    // template-shaped (`tools: string[]`): an allowlist
+    if (v.some((x) => typeof x === "string"))
+        return keyList(v, scope, own, false);
+    if (!v.some((r) => isRecord(r) &&
+        r.kind === "builtin" &&
+        typeof r.name === "string" &&
+        isLegacyBuiltinKey(r.name))) {
+        return v;
+    }
+    return v.map((r) => isRecord(r) && r.kind === "builtin" && typeof r.name === "string"
+        ? { ...r, name: legacyToolKey(r.name) ?? r.name }
+        : r);
+}
+/**
+ * Release-candidate tool keys in a stored definition, read as current keys (tool naming spec
+ * §8.3), the way {@link normalizeToolRef} reads the app -> connector rename: builtin refs in
+ * `tools`, the keys of `toolPolicies`, and the `tools` / `disallowedTools` / `toolPolicies` of a
+ * template, the agent's inline sub-agent templates included. Works on an agent definition and on
+ * an agent template alike. Old builtin names map without `scope`; an rc `<x>__<tool>` key maps
+ * only with one (the org's connector slugs and their ids, the deployment's extension names). When
+ * `x` is both a slug and an extension name, the definition's own tool refs decide; when they
+ * cannot, a policy or a deny list keeps the restriction on both candidate keys (a deny is never
+ * lost) and an allowlist keeps the old key (inert). An unknown key stays as it is. Keys in the
+ * current format are never touched. Returns the same object when nothing changes. Saving never
+ * goes through this: a new definition with an old key is refused (`AgentsService`).
+ */
+export function normalizeToolKeys(definition, scope, inherited) {
+    if (!isRecord(definition))
+        return definition;
+    const own = scope === undefined ? undefined : ownRefs(definition, scope, inherited);
+    const next = { ...definition };
+    let changed = false;
+    const put = (field, value) => {
+        if (value === definition[field])
+            return;
+        next[field] = value;
+        changed = true;
+    };
+    if ("tools" in definition)
+        put("tools", toolRefs(definition.tools, scope, own));
+    if ("disallowedTools" in definition) {
+        put("disallowedTools", keyList(definition.disallowedTools, scope, own, true));
+    }
+    if ("toolPolicies" in definition) {
+        put("toolPolicies", policyKeys(definition.toolPolicies, scope, own));
+    }
+    const sub = definition.subagents;
+    if (isRecord(sub) && Array.isArray(sub.inline)) {
+        const inline = sub.inline.map((t) => normalizeToolKeys(t, scope, own));
+        if (inline.some((t, i) => t !== sub.inline[i])) {
+            put("subagents", { ...sub, inline });
+        }
+    }
+    return changed ? next : definition;
+}
+/**
+ * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
+ * {@link LegacyScope} can map? (Callers load the scope only then.)
+ */
+export function needsLegacyScope(definition) {
+    if (!isRecord(definition))
+        return false;
+    const lists = [definition.tools, definition.disallowedTools];
+    for (const l of lists) {
+        if (Array.isArray(l) && l.some((x) => typeof x === "string" && isLegacyPrefixedKey(x))) {
+            return true;
+        }
+    }
+    if (isRecord(definition.toolPolicies)) {
+        if (Object.keys(definition.toolPolicies).some(isLegacyPrefixedKey))
+            return true;
+    }
+    const sub = definition.subagents;
+    return isRecord(sub) && Array.isArray(sub.inline) && sub.inline.some(needsLegacyScope);
+}
 /**
  * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
+ * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
+ * object is returned.
  */
-export function normalizeStoredDefinition(def) {
-    const d = def;
+export function normalizeStoredDefinition(def, scope) {
+    let d = def;
     const tools = d.tools;
-    if (!Array.isArray(tools) || !tools.some((t) => t?.kind === "app")) {
-        return d;
+    if (Array.isArray(tools) && tools.some((t) => t?.kind === "app")) {
+        d = { ...d, tools: tools.map(normalizeToolRef) };
     }
-    return { ...d, tools: tools.map(normalizeToolRef) };
+    return normalizeToolKeys(d, scope);
 }
 /** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
 export function paramIssues(field, decl, params) {

package/dist/agents/instruction-files.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import type { AgentDefinition } from "./definition.js";
+/**
+ * Prompt files (spec 2026-11-04 §3.3): the authoring form of an agent's system prompt. The kernel
+ * joins them into `instructions` on save, and `instructions` stays the one model-visible field
+ * (build.ts, the sub-agent copy, eval candidates and replay keep reading it), so no log event
+ * changes shape and replay needs no new `DriftReason`.
+ */
+export type InstructionFile = {
+    name: string;
+    content: string;
+};
+/** The default and first file. */
+export declare const AGENTS_MD = "AGENTS.md";
+export declare const INSTRUCTION_FILE_LIMITS: {
+    /** At most this many files, at least one. */
+    readonly count: 20;
+    /** The joined text, the same bound as `instructions`. */
+    readonly joinedChars: 100000;
+};
+/** A file name: 1–64 characters without `/` or `\`, then `.md`. */
+export declare const INSTRUCTION_FILE_NAME_RE: RegExp;
+/**
+ * The starter prompt of a new agent created without one (model-visible once saved; English like
+ * every model-facing text).
+ */
+export declare const AGENTS_MD_STARTER: string;
+/**
+ * The model-visible join: one file gives exactly its content (so an old agent edited without
+ * adding files sends the same text as before); several files give `# <name>\n\n<content>` each,
+ * in order, joined by `\n\n`.
+ */
+export declare function joinInstructionFiles(files: readonly InstructionFile[]): string;
+/** The files of a definition; a definition without them (every old version) is one `AGENTS.md`. */
+export declare function readInstructionFiles(def: Pick<AgentDefinition, "instructions" | "instructionFiles">): InstructionFile[];
+export declare const InstructionFileSchema: z.ZodObject<{
+    name: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>;
+/**
+ * 1–20 files, names unique ignoring case (`AGENTS.md` and `agents.md` would collide on a
+ * case-insensitive file system), a joined total of at most 100 000 characters.
+ */
+export declare const InstructionFilesSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>>;
+/** A definition as a save request gives it: `instructions` may be left out. */
+export type AgentDefinitionInput = Omit<AgentDefinition, "instructions"> & {
+    instructions?: string | undefined;
+};
+/**
+ * Derives the stored definition of a save. With `instructionFiles`, `instructions` is their join
+ * (a differing `instructions` given with them → 400 `agent.instructions_mismatch`). With only
+ * `instructions` (old clients) the current files are kept while it equals their join, else the
+ * definition is stored as given, without files. Given neither,
+ * an update keeps the `current` version's prompt, and a new agent (`current` null) gets the
+ * `AGENTS.md` starter.
+ */
+export declare function deriveInstructions(def: AgentDefinitionInput, current: Pick<AgentDefinition, "instructions" | "instructionFiles"> | null): AgentDefinition;

package/dist/agents/instruction-files.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { CONTROL_OR_HIDDEN_RE } from "../text.js";
+/** The default and first file. */
+export const AGENTS_MD = "AGENTS.md";
+export const INSTRUCTION_FILE_LIMITS = {
+    /** At most this many files, at least one. */
+    count: 20,
+    /** The joined text, the same bound as `instructions`. */
+    joinedChars: 100_000,
+};
+/** A file name: 1–64 characters without `/` or `\`, then `.md`. */
+export const INSTRUCTION_FILE_NAME_RE = /^[^/\\]{1,64}\.md$/;
+/**
+ * The starter prompt of a new agent created without one (model-visible once saved; English like
+ * every model-facing text).
+ */
+export const AGENTS_MD_STARTER = [
+    "You are an assistant for this team. Help people get their work done accurately and efficiently.",
+    "",
+    "- Tone: clear, friendly and concise. Use plain language, keep answers short, and add detail when asked.",
+    "- When a request is unclear or missing key details, ask one short clarifying question before acting.",
+    "  If you go ahead anyway, say what you assumed.",
+    "- If you don't know something or can't do it, say so instead of guessing.",
+].join("\n");
+/**
+ * The model-visible join: one file gives exactly its content (so an old agent edited without
+ * adding files sends the same text as before); several files give `# <name>\n\n<content>` each,
+ * in order, joined by `\n\n`.
+ */
+export function joinInstructionFiles(files) {
+    if (files.length === 1)
+        return files[0]?.content ?? "";
+    return files.map((f) => `# ${f.name}\n\n${f.content}`).join("\n\n");
+}
+/** The files of a definition; a definition without them (every old version) is one `AGENTS.md`. */
+export function readInstructionFiles(def) {
+    return def.instructionFiles ?? [{ name: AGENTS_MD, content: def.instructions }];
+}
+export const InstructionFileSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(INSTRUCTION_FILE_NAME_RE, "a file name is 1–64 characters without / or \\, then .md")
+        .refine((n) => !CONTROL_OR_HIDDEN_RE.test(n), "a file name must not contain control or format characters"),
+    content: z.string().max(INSTRUCTION_FILE_LIMITS.joinedChars),
+})
+    .strict();
+/**
+ * 1–20 files, names unique ignoring case (`AGENTS.md` and `agents.md` would collide on a
+ * case-insensitive file system), a joined total of at most 100 000 characters.
+ */
+export const InstructionFilesSchema = z
+    .array(InstructionFileSchema)
+    .min(1)
+    .max(INSTRUCTION_FILE_LIMITS.count)
+    .superRefine((files, ctx) => {
+    const seen = new Set();
+    files.forEach((f, i) => {
+        const key = f.name.toLowerCase();
+        if (seen.has(key)) {
+            ctx.addIssue({ code: "custom", path: [i, "name"], message: `duplicate file ${f.name}` });
+        }
+        seen.add(key);
+    });
+    const joined = joinInstructionFiles(files).length;
+    if (joined > INSTRUCTION_FILE_LIMITS.joinedChars) {
+        ctx.addIssue({
+            code: "custom",
+            message: `the joined files are ${joined} characters, more than ${INSTRUCTION_FILE_LIMITS.joinedChars}`,
+        });
+    }
+});
+/**
+ * Derives the stored definition of a save. With `instructionFiles`, `instructions` is their join
+ * (a differing `instructions` given with them → 400 `agent.instructions_mismatch`). With only
+ * `instructions` (old clients) the current files are kept while it equals their join, else the
+ * definition is stored as given, without files. Given neither,
+ * an update keeps the `current` version's prompt, and a new agent (`current` null) gets the
+ * `AGENTS.md` starter.
+ */
+export function deriveInstructions(def, current) {
+    const { instructions, instructionFiles, ...rest } = def;
+    if (instructionFiles !== undefined) {
+        const joined = joinInstructionFiles(instructionFiles);
+        if (instructions !== undefined && instructions !== joined) {
+            throw new ApiError("agent.instructions_mismatch", "instructions differs from the join of instructionFiles; send only instructionFiles");
+        }
+        return { ...rest, instructions: joined, instructionFiles };
+    }
+    if (instructions !== undefined) {
+        // an old client re-sending the same joined text (an unrelated edit) keeps the files
+        const files = current?.instructionFiles;
+        if (files !== undefined && instructions === joinInstructionFiles(files)) {
+            return { ...rest, instructions, instructionFiles: files };
+        }
+        return { ...rest, instructions };
+    }
+    if (current !== null) {
+        return {
+            ...rest,
+            instructions: current.instructions,
+            ...(current.instructionFiles !== undefined && { instructionFiles: current.instructionFiles }),
+        };
+    }
+    return {
+        ...rest,
+        instructions: AGENTS_MD_STARTER,
+        instructionFiles: [{ name: AGENTS_MD, content: AGENTS_MD_STARTER }],
+    };
+}

package/dist/agents/models.controller.d.ts

@@ -1,12 +1,18 @@
-import type { ModelInfo } from "@capybara-hq/plugin-sdk";
+import type { LocalizedName, ModelInfo } from "@capybara-hq/plugin-sdk";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { ProviderRegistry } from "../runtime/providers.js";
-/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+/**
+ * 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。Each provider
+ * carries its extension's display name (null when it has none).
+ */
 export declare class ModelsController {
     private readonly registry;
-    constructor(registry: ProviderRegistry);
+    private readonly displayNames;
+    constructor(registry: ProviderRegistry, displayNames: ExtensionDisplayNames);
     list(): Promise<{
         providers: {
             provider: string;
+            displayName: LocalizedName | null;
             models: ModelInfo[];
         }[];
     }>;

package/dist/agents/models.controller.js

@@ -8,16 +8,30 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Inject } from "@nestjs/common";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { OrgAction } from "../orgs/org.guard.js";
 import { ProviderRegistry } from "../runtime/providers.js";
-/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+/**
+ * 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。Each provider
+ * carries its extension's display name (null when it has none).
+ */
 let ModelsController = class ModelsController {
     registry;
-    constructor(registry) {
+    displayNames;
+    constructor(registry, displayNames) {
         this.registry = registry;
+        this.displayNames = displayNames;
     }
     async list() {
-        return { providers: await this.registry.list() };
+        const providers = await this.registry.list();
+        const names = await this.displayNames.many(providers.map((p) => p.provider));
+        return {
+            providers: providers.map((p) => ({
+                provider: p.provider,
+                displayName: names.get(p.provider) ?? null,
+                models: p.models,
+            })),
+        };
     }
 };
 __decorate([
@@ -26,6 +40,7 @@ __decorate([
 ], ModelsController.prototype, "list", null);
 ModelsController = __decorate([
     Controller("api/v1/orgs/:orgId/models"),
-    __param(0, Inject(ProviderRegistry))
+    __param(0, Inject(ProviderRegistry)),
+    __param(1, Inject(ExtensionDisplayNames))
 ], ModelsController);
 export { ModelsController };

package/dist/agents/profile.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/** The ten built-in pixel-animal avatars (drawn by `@capybara-hq/design`). */
+export declare const PRESET_IDS: readonly ["capybara", "black-bear", "panda", "elephant", "fox", "owl", "penguin", "rabbit", "turtle", "whale"];
+export type PresetId = (typeof PRESET_IDS)[number];
+export declare const PROFILE_LIMITS: {
+    readonly description: 500;
+    readonly quickActions: 9;
+    readonly title: 40;
+    readonly body: 20000;
+};
+/** A random preset id: the avatar of an agent created without one. */
+export declare function randomPreset(): PresetId;
+export declare const AgentAvatarSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"preset">;
+    id: z.ZodEnum<{
+        "black-bear": "black-bear";
+        capybara: "capybara";
+        elephant: "elephant";
+        fox: "fox";
+        owl: "owl";
+        panda: "panda";
+        penguin: "penguin";
+        rabbit: "rabbit";
+        turtle: "turtle";
+        whale: "whale";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    uploadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    url: z.ZodURL;
+}, z.core.$strict>], "kind">;
+/** `null` only for agents created before profiles existed. */
+export type AgentAvatar = z.infer<typeof AgentAvatarSchema> | null;
+export declare const QuickActionSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strict>;
+export type QuickAction = z.infer<typeof QuickActionSchema>;
+export declare const DescriptionSchema: z.ZodString;
+export declare const QuickActionsSchema: z.ZodArray<z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strict>>;
+/** What a client may write (`external` is migrated data only). */
+export declare const AvatarInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"preset">;
+    id: z.ZodEnum<{
+        "black-bear": "black-bear";
+        capybara: "capybara";
+        elephant: "elephant";
+        fox: "fox";
+        owl: "owl";
+        panda: "panda";
+        penguin: "penguin";
+        rabbit: "rabbit";
+        turtle: "turtle";
+        whale: "whale";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    uploadId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const ProfileInputSchema: z.ZodObject<{
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"preset">;
+        id: z.ZodEnum<{
+            "black-bear": "black-bear";
+            capybara: "capybara";
+            elephant: "elephant";
+            fox: "fox";
+            owl: "owl";
+            panda: "panda";
+            penguin: "penguin";
+            rabbit: "rabbit";
+            turtle: "turtle";
+            whale: "whale";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+        uploadId: z.ZodString;
+    }, z.core.$strict>], "kind">>>;
+    description: z.ZodOptional<z.ZodString>;
+    quickActions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ProfileInput = z.infer<typeof ProfileInputSchema>;
+export interface AgentProfile {
+    avatar: AgentAvatar;
+    description: string;
+    quickActions: QuickAction[];
+    updatedAt: string;
+}

package/dist/agents/profile.js

@@ -0,0 +1,51 @@
+import { randomInt } from "node:crypto";
+import { z } from "zod";
+/** The ten built-in pixel-animal avatars (drawn by `@capybara-hq/design`). */
+export const PRESET_IDS = [
+    "capybara",
+    "black-bear",
+    "panda",
+    "elephant",
+    "fox",
+    "owl",
+    "penguin",
+    "rabbit",
+    "turtle",
+    "whale",
+];
+export const PROFILE_LIMITS = {
+    description: 500,
+    quickActions: 9,
+    title: 40,
+    body: 20_000,
+};
+/** A random preset id: the avatar of an agent created without one. */
+export function randomPreset() {
+    return PRESET_IDS[randomInt(PRESET_IDS.length)];
+}
+export const AgentAvatarSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("preset"), id: z.enum(PRESET_IDS) }).strict(),
+    z.object({ kind: z.literal("upload"), uploadId: z.string().min(1).max(200) }).strict(),
+    // only produced by the migration of `definition.avatarUrl`; never accepted from a client
+    z.object({ kind: z.literal("external"), url: z.url() }).strict(),
+]);
+export const QuickActionSchema = z
+    .object({
+    title: z.string().min(1).max(PROFILE_LIMITS.title),
+    body: z.string().min(1).max(PROFILE_LIMITS.body),
+})
+    .strict();
+export const DescriptionSchema = z.string().max(PROFILE_LIMITS.description);
+export const QuickActionsSchema = z.array(QuickActionSchema).max(PROFILE_LIMITS.quickActions);
+/** What a client may write (`external` is migrated data only). */
+export const AvatarInputSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("preset"), id: z.enum(PRESET_IDS) }).strict(),
+    z.object({ kind: z.literal("upload"), uploadId: z.string().min(1).max(200) }).strict(),
+]);
+export const ProfileInputSchema = z
+    .object({
+    avatar: AvatarInputSchema.nullable().optional(),
+    description: DescriptionSchema.optional(),
+    quickActions: QuickActionsSchema.optional(),
+})
+    .strict();