@kilnai/cli 1.0.7 → 2.1.0

package/README.md

@@ -6,16 +6,19 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@kilnai/cli"><img src="https://img.shields.io/npm/v/@kilnai/cli.svg" alt="npm version" /></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache-2.0" /></a>
 </p>
 
-<p align="center">CLI and MCP server for the Kiln AI orchestration engine.</p>
+<p align="center">CLI, GUI launcher, and MCP tooling for the Kiln governed AI control plane.</p>
 
 ---
 
 ## What is this?
 
-`@kilnai/cli` is the command-line interface for [Kiln](https://github.com/sequelcore/kiln). It provides an interactive setup wizard, dev mode with YAML hot-reload, and an MCP server for Claude Code integration.
+`@kilnai/cli` is the command-line interface for
+[Kiln](https://github.com/sequelcore/kiln). It provides local operator
+commands, GUI/TUI launchers, config projection tools, workflow commands, and
+the dev-tools MCP server.
 
 ## Install
 
@@ -23,6 +26,9 @@
 bun add -g @kilnai/cli
 ```
 
+This installs the official CLI, GUI launcher/assets, TUI, runtime, and gateway
+contracts so `kiln gui` and `kiln tui` can run from any project directory.
+
 Or use directly:
 
 ```bash
@@ -40,9 +46,9 @@ kiln init
 ```
 
 Walks you through:
-- Provider selection (Anthropic, OpenAI, DeepSeek, Ollama)
-- Channel selection (CLI, Web, WhatsApp, Slack, API)
-- Team mode (sequential, supervisor, swarm)
+- Provider selection
+- Channel selection
+- Team mode selection for YAML app scaffolding
 - Quality gates (test, lint, typecheck)
 - Domain detection (React, Python, docs, etc.)
 
@@ -66,6 +72,20 @@ Run a single task:
 kiln run "Implement the login page"
 ```
 
+Useful flags:
+
+- `--provider <name>` to select the provider for the run
+- `--model <name>` to select the model for providers that require model selection
+- `--effort <minimal|low|medium|high|xhigh>` or
+  `--reasoning-effort <minimal|low|medium|high|xhigh>` to set reasoning effort
+  for providers/models that support it
+- `--plan` to start in plan mode
+- `--workers <number>` to run isolated parallel workers
+
+Reasoning effort is forwarded through the shared session contract. For the
+Codex CLI wrapper it becomes Codex's `model_reasoning_effort` config override;
+for direct runtime providers it is sent as provider request metadata.
+
 ### `kiln tui`
 
 Start the interactive terminal UI:
@@ -77,6 +97,7 @@ kiln tui
 Useful flags:
 
 - `--provider <name>` to select the initial provider
+- `--model <name>` to select the initial model
 - `--theme <name>` to select a theme
 - `--port <number>` to override the local TUI gateway port
 - `--plan` to start in plan mode
@@ -86,7 +107,12 @@ Current transport behavior:
 - gateway transport is the default path
 - direct transport is available only with `KILN_TUI_TRANSPORT=direct`
 
-The default gateway path keeps TUI conversations on the runtime session pipeline so provider routing, continuity, approvals, and sidebar route labels reflect the actual backend used for each turn.
+The default gateway path keeps TUI conversations on the runtime session
+pipeline so provider routing, continuity, approvals, reasoning effort, and
+sidebar route labels reflect the actual backend used for each turn.
+
+Inside the TUI, use `/provider` to change provider/model and `/effort` to cycle
+the active model's advertised reasoning effort options.
 
 ### `kiln gateway`
 
@@ -160,4 +186,4 @@ This lets Claude Code use Kiln tools directly in your development workflow.
 
 ## License
 
-[MIT](https://github.com/sequelcore/kiln/blob/main/LICENSE)
+[Apache-2.0](https://github.com/sequelcore/kiln/blob/main/LICENSE)

package/dist/application/__tests__/session-report.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-report.test.d.ts.map

package/dist/application/__tests__/session-report.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-report.test.d.ts","sourceRoot":"","sources":["../../../src/application/__tests__/session-report.test.ts"],"names":[],"mappings":""}

package/dist/application/__tests__/session-report.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { summarizeContextGovernance } from "../session-report.js";
+describe("summarizeContextGovernance", () => {
+    it("uses core context audit reasons instead of local inference when available", () => {
+        const projectedContext = {
+            blocks: [
+                {
+                    id: "candidate:0",
+                    kind: "summary",
+                    source: "runtime-continuity",
+                    content: "summary",
+                    required: false,
+                    score: 80,
+                    estimatedTokens: 2,
+                },
+            ],
+            deferredBlocks: [
+                {
+                    id: "candidate:1",
+                    kind: "memory",
+                    source: "runtime-recalled-memory",
+                    content: "memory",
+                    required: false,
+                    score: 40,
+                    estimatedTokens: 2,
+                },
+            ],
+            estimatedTokens: 2,
+            tokenBudget: 2,
+            overflow: true,
+            auditTrail: [
+                {
+                    governor: "DefaultContextGovernor",
+                    selectedBlockIds: ["candidate:0"],
+                    deferredBlockIds: ["candidate:1"],
+                    requiredBlockIds: [],
+                    preservedRequiredBlockIds: [],
+                    selectedTokens: 2,
+                    requiredTokens: 0,
+                    tokenBudget: 2,
+                    overflow: true,
+                    overflowReason: "budget-cap",
+                    blocks: [
+                        {
+                            id: "candidate:0",
+                            kind: "summary",
+                            source: "runtime-continuity",
+                            required: false,
+                            estimatedTokens: 2,
+                            baseScore: 80,
+                            effectiveScore: 80,
+                            decision: "admitted",
+                            reason: "within-budget",
+                            order: 0,
+                        },
+                        {
+                            id: "candidate:1",
+                            kind: "memory",
+                            source: "runtime-recalled-memory",
+                            required: false,
+                            estimatedTokens: 2,
+                            baseScore: 40,
+                            effectiveScore: 40,
+                            decision: "deferred",
+                            reason: "budget-cap",
+                            order: 1,
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(summarizeContextGovernance(projectedContext).deferredReasons).toEqual([
+            "budget-cap",
+        ]);
+    });
+    it("keeps the local deferred reason fallback when no core audit is present", () => {
+        const projectedContext = {
+            blocks: [],
+            deferredBlocks: [
+                {
+                    id: "candidate:1",
+                    kind: "memory",
+                    source: "runtime-recalled-memory",
+                    content: "memory",
+                    required: false,
+                    score: 40,
+                    estimatedTokens: 2,
+                },
+            ],
+            estimatedTokens: 0,
+            tokenBudget: 2,
+            overflow: true,
+        };
+        expect(summarizeContextGovernance(projectedContext).deferredReasons).toEqual([
+            "required-overflow",
+            "lower-priority-memory",
+        ]);
+    });
+});
+//# sourceMappingURL=session-report.test.js.map

package/dist/application/__tests__/session-report.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-report.test.js","sourceRoot":"","sources":["../../../src/application/__tests__/session-report.test.ts"],"names":[],"mappings":"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"}

package/dist/application/agent-loader.d.ts

@@ -1,12 +1,40 @@
+import type { AgentTier, ModelTaskSuitabilityTask } from "@kilnai/core";
 export interface KilnAgentDefinition {
     readonly name: string;
+    readonly displayName?: string;
+    readonly nicknameCandidates?: readonly string[];
     readonly role: string;
+    readonly description?: string;
+    readonly goal: string;
+    readonly backstory?: string;
+    readonly tier: AgentTier;
     readonly tools?: readonly string[];
     readonly model?: string;
     readonly skills?: readonly string[];
+    readonly instructionProfiles?: readonly string[];
+    readonly taskAffinity?: readonly ModelTaskSuitabilityTask[];
+    readonly mode?: KilnAgentMode;
+    readonly structured?: boolean;
+    readonly count?: number;
+    readonly sandbox?: boolean;
+    readonly modalities?: readonly string[];
+    readonly authorityProfile?: string;
+    readonly routeId?: string;
+    readonly providerRoute?: KilnAgentProviderRoute;
+    readonly voiceProfile?: string;
     readonly instructions?: string;
-    readonly scope: "global" | "project";
+    readonly scope: "builtin" | "global" | "project";
 }
-export declare function loadAgentDefinitions(projectPath: string): Promise<KilnAgentDefinition[]>;
+export type KilnAgentMode = "primary" | "subagent" | "managed-child" | "all";
+export interface KilnAgentProviderRoute {
+    readonly providerId: string;
+    readonly model?: string;
+    readonly reasoningEffort?: string;
+}
+export declare function parseAgentDefinitionContent(raw: string, scope?: "global" | "project"): KilnAgentDefinition | undefined;
+export interface LoadAgentDefinitionsOptions {
+    readonly includeBuiltins?: boolean;
+}
+export declare function loadAgentDefinitions(projectPath: string, options?: LoadAgentDefinitionsOptions): Promise<KilnAgentDefinition[]>;
 export declare function findAgent(definitions: KilnAgentDefinition[], name: string): KilnAgentDefinition | undefined;
 //# sourceMappingURL=agent-loader.d.ts.map

package/dist/application/agent-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../../src/application/agent-loader.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CACtC;AAiHD,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAe9F;AAED,wBAAgB,SAAS,CACvB,WAAW,EAAE,mBAAmB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,mBAAmB,GAAG,SAAS,CAOjC"}
+{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../../src/application/agent-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,sBAAsB,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,GAAG,KAAK,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAuKD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,QAAQ,GAAG,SAAqB,GAAG,mBAAmB,GAAG,SAAS,CAEjI;AAkCD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqBhC;AAED,wBAAgB,SAAS,CACvB,WAAW,EAAE,mBAAmB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,mBAAmB,GAAG,SAAS,CAkBjC"}

package/dist/application/agent-loader.js

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
+import { KILN_FIRST_PARTY_AGENT_DEFAULTS } from "./first-party-agent-defaults.js";
 function parseFrontmatter(raw) {
     const content = raw.replace(/^\uFEFF/, "");
     const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*([\s\S]*)$/u.exec(content);
@@ -30,6 +31,50 @@ function asStringArray(value) {
         .filter((entry) => entry.length > 0);
     return entries.length > 0 ? entries : undefined;
 }
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function asAgentTier(value) {
+    return value === "reasoning" || value === "coding" || value === "fast" ? value : undefined;
+}
+function asAgentMode(value) {
+    return value === "primary" || value === "subagent" || value === "managed-child" || value === "all"
+        ? value
+        : undefined;
+}
+function asTaskAffinity(value) {
+    const entries = asStringArray(value);
+    if (!entries) {
+        return undefined;
+    }
+    const supported = entries.filter((entry) => entry === "architecture-review"
+        || entry === "backend-coding"
+        || entry === "frontend-design"
+        || entry === "mechanical-edit"
+        || entry === "research"
+        || entry === "test-writing");
+    return supported.length > 0 ? supported : undefined;
+}
+function asProviderRoute(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    const providerId = asNonEmptyString(record.providerId);
+    if (!providerId) {
+        return undefined;
+    }
+    const model = asNonEmptyString(record.model);
+    const reasoningEffort = asNonEmptyString(record.reasoningEffort);
+    return {
+        providerId,
+        ...(model ? { model } : {}),
+        ...(reasoningEffort ? { reasoningEffort } : {}),
+    };
+}
 function parseAgentDefinition(raw, scope) {
     const parsed = parseFrontmatter(raw);
     if (!parsed) {
@@ -48,23 +93,60 @@ function parseAgentDefinition(raw, scope) {
     const record = frontmatter;
     const name = asNonEmptyString(record.name);
     const role = asNonEmptyString(record.role);
-    if (!name || !role) {
+    const goal = asNonEmptyString(record.goal);
+    const tier = asAgentTier(record.tier);
+    if (!name || !role || !goal || !tier) {
         return undefined;
     }
+    const description = asNonEmptyString(record.description);
+    const displayName = asNonEmptyString(record.displayName);
+    const nicknameCandidates = asStringArray(record.nicknameCandidates);
+    const backstory = asNonEmptyString(record.backstory);
     const tools = asStringArray(record.tools);
     const model = asNonEmptyString(record.model);
     const skills = asStringArray(record.skills);
+    const instructionProfiles = asStringArray(record.instructionProfiles);
+    const taskAffinity = asTaskAffinity(record.taskAffinity);
+    const mode = asAgentMode(record.mode);
+    const structured = asBoolean(record.structured);
+    const count = asPositiveInteger(record.count);
+    const sandbox = asBoolean(record.sandbox);
+    const modalities = asStringArray(record.modalities);
+    const authorityProfile = asNonEmptyString(record.authorityProfile);
+    const routeId = asNonEmptyString(record.routeId);
+    const providerRoute = asProviderRoute(record.providerRoute);
+    const voiceProfile = asNonEmptyString(record.voiceProfile);
     const instructions = parsed.body.length > 0 ? parsed.body : undefined;
     return {
         name,
+        ...(displayName ? { displayName } : {}),
+        ...(nicknameCandidates ? { nicknameCandidates } : {}),
         role,
+        ...(description ? { description } : {}),
+        goal,
+        ...(backstory ? { backstory } : {}),
+        tier,
         ...(tools ? { tools } : {}),
         ...(model ? { model } : {}),
         ...(skills ? { skills } : {}),
+        ...(instructionProfiles ? { instructionProfiles } : {}),
+        ...(taskAffinity ? { taskAffinity } : {}),
+        ...(mode ? { mode } : {}),
+        ...(structured !== undefined ? { structured } : {}),
+        ...(count !== undefined ? { count } : {}),
+        ...(sandbox !== undefined ? { sandbox } : {}),
+        ...(modalities ? { modalities } : {}),
+        ...(authorityProfile ? { authorityProfile } : {}),
+        ...(routeId ? { routeId } : {}),
+        ...(providerRoute ? { providerRoute } : {}),
+        ...(voiceProfile ? { voiceProfile } : {}),
         ...(instructions ? { instructions } : {}),
         scope,
     };
 }
+export function parseAgentDefinitionContent(raw, scope = "project") {
+    return parseAgentDefinition(raw, scope);
+}
 function readDefinitionsFromDirectory(directory, scope) {
     let entries;
     try {
@@ -92,10 +174,15 @@ function readDefinitionsFromDirectory(directory, scope) {
     }
     return definitions;
 }
-export async function loadAgentDefinitions(projectPath) {
+export async function loadAgentDefinitions(projectPath, options = {}) {
     const globalDirectory = join(homedir(), ".kiln", "agents");
     const projectDirectory = join(projectPath, ".kiln", "agents");
     const merged = new Map();
+    if (options.includeBuiltins !== false) {
+        for (const definition of KILN_FIRST_PARTY_AGENT_DEFAULTS) {
+            merged.set(definition.name.toLowerCase(), definition);
+        }
+    }
     for (const definition of readDefinitionsFromDirectory(globalDirectory, "global")) {
         merged.set(definition.name.toLowerCase(), definition);
     }
@@ -109,6 +196,15 @@ export function findAgent(definitions, name) {
     if (target.length === 0) {
         return undefined;
     }
-    return definitions.find((definition) => definition.name.toLowerCase() === target);
+    const canonicalMatch = definitions.find((definition) => definition.name.toLowerCase() === target);
+    if (canonicalMatch) {
+        return canonicalMatch;
+    }
+    const nicknameMatches = definitions.filter((definition) => {
+        const displayName = definition.displayName?.toLowerCase();
+        const nicknames = definition.nicknameCandidates?.map((nickname) => nickname.toLowerCase()) ?? [];
+        return displayName === target || nicknames.includes(target);
+    });
+    return nicknameMatches.length === 1 ? nicknameMatches[0] : undefined;
 }
 //# sourceMappingURL=agent-loader.js.map

package/dist/application/agent-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loader.js","sourceRoot":"","sources":["../../src/application/agent-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-loader.js","sourceRoot":"","sources":["../../src/application/agent-loader.ts"],"names":[],"mappings":"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"}

package/dist/application/agent-loader.test.js

@@ -58,18 +58,34 @@ describe("agent-loader", () => {
     afterEach(() => {
         vi.restoreAllMocks();
     });
-    it("returns empty array when both directories missing", async () => {
+    it("returns first-party defaults when both directories missing", async () => {
         const definitions = await loadAgentDefinitions(PROJECT_PATH);
-        expect(definitions).toEqual([]);
+        expect(findAgent(definitions, "architect")).toMatchObject({
+            name: "architect",
+            scope: "builtin",
+            taskAffinity: ["architecture-review"],
+        });
+        expect(findAgent(definitions, "coder")).toMatchObject({
+            name: "coder",
+            scope: "builtin",
+            tools: ["read", "grep", "glob", "write", "bash"],
+        });
         expect(readdirSyncMock).toHaveBeenCalledWith(GLOBAL_AGENTS_DIR);
         expect(readdirSyncMock).toHaveBeenCalledWith(PROJECT_AGENTS_DIR);
     });
-    it("parses frontmatter correctly (name, role, tools, model, skills)", async () => {
+    it("parses canonical agent profile frontmatter", async () => {
         configureDirectories(["architect.md"], []);
         configureFiles({
             [join(GLOBAL_AGENTS_DIR, "architect.md")]: markdownWithFrontmatter([
                 "name: Architect",
+                "displayName: Piama",
+                "nicknameCandidates:",
+                "  - Architect Piama",
                 "role: System architect",
+                "description: Reviews system boundaries",
+                "goal: Keep architecture coherent",
+                "backstory: Staff engineer perspective",
+                "tier: reasoning",
                 "tools:",
                 "  - read",
                 "  - write",
@@ -77,16 +93,47 @@ describe("agent-loader", () => {
                 "skills:",
                 "  - sequel-spring",
                 "  - refactor",
+                "instructionProfiles:",
+                "  - sequel-engineering",
+                "mode: managed-child",
+                "structured: true",
+                "count: 2",
+                "sandbox: true",
+                "modalities:",
+                "  - text",
+                "authorityProfile: foundation-readonly-plan",
+                "routeId: codex-oauth-readonly",
+                "providerRoute:",
+                "  providerId: codex-oauth",
+                "  model: gpt-5.4-mini",
             ].join("\n")),
         });
-        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        const definitions = await loadAgentDefinitions(PROJECT_PATH, { includeBuiltins: false });
         expect(definitions).toEqual([
             {
                 name: "Architect",
+                displayName: "Piama",
+                nicknameCandidates: ["Architect Piama"],
                 role: "System architect",
+                description: "Reviews system boundaries",
+                goal: "Keep architecture coherent",
+                backstory: "Staff engineer perspective",
+                tier: "reasoning",
                 tools: ["read", "write"],
                 model: "claude-sonnet-4-6",
                 skills: ["sequel-spring", "refactor"],
+                instructionProfiles: ["sequel-engineering"],
+                mode: "managed-child",
+                structured: true,
+                count: 2,
+                sandbox: true,
+                modalities: ["text"],
+                authorityProfile: "foundation-readonly-plan",
+                routeId: "codex-oauth-readonly",
+                providerRoute: {
+                    providerId: "codex-oauth",
+                    model: "gpt-5.4-mini",
+                },
                 scope: "global",
             },
         ]);
@@ -94,24 +141,26 @@ describe("agent-loader", () => {
     it("captures markdown body as instructions", async () => {
         configureDirectories(["planner.md"], []);
         configureFiles({
-            [join(GLOBAL_AGENTS_DIR, "planner.md")]: markdownWithFrontmatter(["name: Planner", "role: Planning specialist"].join("\n"), "\n# Plan\n\nCreate a concrete implementation plan.\n"),
+            [join(GLOBAL_AGENTS_DIR, "planner.md")]: markdownWithFrontmatter(["name: Planner", "role: Planning specialist", "goal: Produce plans", "tier: reasoning"].join("\n"), "\n# Plan\n\nCreate a concrete implementation plan.\n"),
         });
-        const [definition] = await loadAgentDefinitions(PROJECT_PATH);
+        const [definition] = await loadAgentDefinitions(PROJECT_PATH, { includeBuiltins: false });
         expect(definition?.instructions).toBe("# Plan\n\nCreate a concrete implementation plan.");
     });
     it("project agents override global agents with same name", async () => {
         configureDirectories(["shared.md", "global-only.md"], ["shared.md", "project-only.md"]);
         configureFiles({
-            [join(GLOBAL_AGENTS_DIR, "shared.md")]: markdownWithFrontmatter(["name: Shared", "role: Global role"].join("\n")),
-            [join(GLOBAL_AGENTS_DIR, "global-only.md")]: markdownWithFrontmatter(["name: GlobalOnly", "role: Global only role"].join("\n")),
-            [join(PROJECT_AGENTS_DIR, "shared.md")]: markdownWithFrontmatter(["name: Shared", "role: Project role"].join("\n")),
-            [join(PROJECT_AGENTS_DIR, "project-only.md")]: markdownWithFrontmatter(["name: ProjectOnly", "role: Project only role"].join("\n")),
+            [join(GLOBAL_AGENTS_DIR, "shared.md")]: markdownWithFrontmatter(["name: Shared", "role: Global role", "goal: Global goal", "tier: fast"].join("\n")),
+            [join(GLOBAL_AGENTS_DIR, "global-only.md")]: markdownWithFrontmatter(["name: GlobalOnly", "role: Global only role", "goal: Global only goal", "tier: coding"].join("\n")),
+            [join(PROJECT_AGENTS_DIR, "shared.md")]: markdownWithFrontmatter(["name: Shared", "role: Project role", "goal: Project goal", "tier: reasoning"].join("\n")),
+            [join(PROJECT_AGENTS_DIR, "project-only.md")]: markdownWithFrontmatter(["name: ProjectOnly", "role: Project only role", "goal: Project only goal", "tier: fast"].join("\n")),
         });
-        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        const definitions = await loadAgentDefinitions(PROJECT_PATH, { includeBuiltins: false });
         expect(definitions).toHaveLength(3);
         expect(findAgent(definitions, "shared")).toEqual({
             name: "Shared",
             role: "Project role",
+            goal: "Project goal",
+            tier: "reasoning",
             scope: "project",
         });
         expect(findAgent(definitions, "globalonly")?.scope).toBe("global");
@@ -122,28 +171,73 @@ describe("agent-loader", () => {
         configureFiles({
             [join(GLOBAL_AGENTS_DIR, "missing-name.md")]: markdownWithFrontmatter(["role: No name present"].join("\n")),
         });
-        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        const definitions = await loadAgentDefinitions(PROJECT_PATH, { includeBuiltins: false });
         expect(definitions).toEqual([]);
     });
-    it("skips files missing required role field", async () => {
+    it("skips files missing required canonical fields", async () => {
         configureDirectories(["missing-role.md"], []);
         configureFiles({
-            [join(GLOBAL_AGENTS_DIR, "missing-role.md")]: markdownWithFrontmatter(["name: MissingRole"].join("\n")),
+            [join(GLOBAL_AGENTS_DIR, "missing-role.md")]: markdownWithFrontmatter(["name: MissingRole", "role: Worker"].join("\n")),
         });
-        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        const definitions = await loadAgentDefinitions(PROJECT_PATH, { includeBuiltins: false });
         expect(definitions).toEqual([]);
     });
     it("findAgent() returns correct definition case-insensitively", () => {
         const definitions = [
-            { name: "Planner", role: "Planning specialist", scope: "global" },
-            { name: "Code-Reviewer", role: "Review specialist", scope: "project" },
+            { name: "Planner", role: "Planning specialist", goal: "Plan work", tier: "reasoning", scope: "global" },
+            { name: "Code-Reviewer", role: "Review specialist", goal: "Review code", tier: "coding", scope: "project" },
         ];
         expect(findAgent(definitions, "planner")).toBe(definitions[0]);
         expect(findAgent(definitions, "CODE-REVIEWER")).toBe(definitions[1]);
     });
+    it("findAgent() resolves unique display names and nicknames", () => {
+        const definitions = [
+            {
+                name: "tdd",
+                displayName: "Malcolm",
+                nicknameCandidates: ["Malcolm Wilkerson"],
+                role: "TDD specialist",
+                goal: "Write tests first",
+                tier: "reasoning",
+                scope: "global",
+            },
+            {
+                name: "coder",
+                displayName: "Reese",
+                role: "Coding specialist",
+                goal: "Implement code",
+                tier: "coding",
+                scope: "global",
+            },
+        ];
+        expect(findAgent(definitions, "malcolm")).toBe(definitions[0]);
+        expect(findAgent(definitions, "Malcolm Wilkerson")).toBe(definitions[0]);
+        expect(findAgent(definitions, "reese")).toBe(definitions[1]);
+    });
+    it("findAgent() does not resolve ambiguous nicknames", () => {
+        const definitions = [
+            {
+                name: "reviewer-one",
+                displayName: "Reviewer",
+                role: "Review specialist",
+                goal: "Review code",
+                tier: "reasoning",
+                scope: "global",
+            },
+            {
+                name: "reviewer-two",
+                nicknameCandidates: ["Reviewer"],
+                role: "Second review specialist",
+                goal: "Review code",
+                tier: "reasoning",
+                scope: "global",
+            },
+        ];
+        expect(findAgent(definitions, "Reviewer")).toBeUndefined();
+    });
     it("findAgent() returns undefined for unknown name", () => {
         const definitions = [
-            { name: "Planner", role: "Planning specialist", scope: "global" },
+            { name: "Planner", role: "Planning specialist", goal: "Plan work", tier: "reasoning", scope: "global" },
         ];
         expect(findAgent(definitions, "unknown")).toBeUndefined();
     });