@kilnai/cli 0.23.2 → 1.0.0

package/README.md

@@ -66,6 +66,28 @@ Run a single task:
 kiln run "Implement the login page"
 ```
 
+### `kiln tui`
+
+Start the interactive terminal UI:
+
+```bash
+kiln tui
+```
+
+Useful flags:
+
+- `--provider <name>` to select the initial provider
+- `--theme <name>` to select a theme
+- `--port <number>` to override the local TUI gateway port
+- `--plan` to start in plan mode
+
+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.
+
 ### `kiln gateway`
 
 Start the production gateway:
@@ -109,6 +131,17 @@ Show current session status:
 kiln status
 ```
 
+### `kiln cron`
+
+Manage schedule triggers:
+
+```bash
+kiln cron list                    # List all schedules
+kiln cron add <name> <cron> <task> [--timezone <tz>]
+kiln cron remove <name>
+kiln cron run <name>              # Fire immediately without resetting schedule
+```
+
 ## MCP Server
 
 The CLI includes a built-in MCP server for Claude Code integration:

package/dist/application/__tests__/plan-exit-tool.test.d.ts

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

package/dist/application/__tests__/plan-exit-tool.test.d.ts.map

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

package/dist/application/__tests__/plan-exit-tool.test.js

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { PLAN_EXIT_TOOL_NAME, planExitToolSchema } from "../plan-exit-tool.js";
+describe("plan-exit-tool", () => {
+    it("uses submit_plan as schema name", () => {
+        expect(PLAN_EXIT_TOOL_NAME).toBe("submit_plan");
+        expect(planExitToolSchema.name).toBe("submit_plan");
+    });
+    it("requires the plan field in input schema", () => {
+        expect(planExitToolSchema.inputSchema.required).toContain("plan");
+    });
+});
+//# sourceMappingURL=plan-exit-tool.test.js.map

package/dist/application/__tests__/plan-exit-tool.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-exit-tool.test.js","sourceRoot":"","sources":["../../../src/application/__tests__/plan-exit-tool.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChD,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,12 @@
+export interface KilnAgentDefinition {
+    readonly name: string;
+    readonly role: string;
+    readonly tools?: readonly string[];
+    readonly model?: string;
+    readonly skills?: readonly string[];
+    readonly instructions?: string;
+    readonly scope: "global" | "project";
+}
+export declare function loadAgentDefinitions(projectPath: string): 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

@@ -0,0 +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"}

package/dist/application/agent-loader.js

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parse } from "yaml";
+function parseFrontmatter(raw) {
+    const content = raw.replace(/^\uFEFF/, "");
+    const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*([\s\S]*)$/u.exec(content);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        frontmatter: match[1] ?? "",
+        body: (match[2] ?? "").trim(),
+    };
+}
+function asNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return entries.length > 0 ? entries : undefined;
+}
+function parseAgentDefinition(raw, scope) {
+    const parsed = parseFrontmatter(raw);
+    if (!parsed) {
+        return undefined;
+    }
+    let frontmatter;
+    try {
+        frontmatter = parse(parsed.frontmatter);
+    }
+    catch {
+        return undefined;
+    }
+    if (!frontmatter || typeof frontmatter !== "object") {
+        return undefined;
+    }
+    const record = frontmatter;
+    const name = asNonEmptyString(record.name);
+    const role = asNonEmptyString(record.role);
+    if (!name || !role) {
+        return undefined;
+    }
+    const tools = asStringArray(record.tools);
+    const model = asNonEmptyString(record.model);
+    const skills = asStringArray(record.skills);
+    const instructions = parsed.body.length > 0 ? parsed.body : undefined;
+    return {
+        name,
+        role,
+        ...(tools ? { tools } : {}),
+        ...(model ? { model } : {}),
+        ...(skills ? { skills } : {}),
+        ...(instructions ? { instructions } : {}),
+        scope,
+    };
+}
+function readDefinitionsFromDirectory(directory, scope) {
+    let entries;
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const definitions = [];
+    for (const entry of entries) {
+        if (!entry.toLowerCase().endsWith(".md")) {
+            continue;
+        }
+        try {
+            const filePath = join(directory, entry);
+            const raw = readFileSync(filePath, "utf-8");
+            const definition = parseAgentDefinition(raw, scope);
+            if (definition) {
+                definitions.push(definition);
+            }
+        }
+        catch {
+            // skip unreadable or malformed files
+        }
+    }
+    return definitions;
+}
+export async function loadAgentDefinitions(projectPath) {
+    const globalDirectory = join(homedir(), ".kiln", "agents");
+    const projectDirectory = join(projectPath, ".kiln", "agents");
+    const merged = new Map();
+    for (const definition of readDefinitionsFromDirectory(globalDirectory, "global")) {
+        merged.set(definition.name.toLowerCase(), definition);
+    }
+    for (const definition of readDefinitionsFromDirectory(projectDirectory, "project")) {
+        merged.set(definition.name.toLowerCase(), definition);
+    }
+    return [...merged.values()];
+}
+export function findAgent(definitions, name) {
+    const target = name.trim().toLowerCase();
+    if (target.length === 0) {
+        return undefined;
+    }
+    return definitions.find((definition) => definition.name.toLowerCase() === target);
+}
+//# sourceMappingURL=agent-loader.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loader.js","sourceRoot":"","sources":["../../src/application/agent-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAiB7B,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,8CAA8C,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;QAC3B,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;KAC9B,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,KAAK;SAClB,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;SAC7D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEvC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAW,EAAE,KAA2B;IACpE,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,WAAoB,CAAC;IACzB,IAAI,CAAC;QACH,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,WAAsC,CAAC;IACtD,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAEtE,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CACnC,SAAiB,EACjB,KAA2B;IAE3B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,SAAS,CAAa,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,WAAW,GAA0B,EAAE,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACxC,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC5C,MAAM,UAAU,GAAG,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACpD,IAAI,UAAU,EAAE,CAAC;gBACf,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;QACvC,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAmB;IAC5D,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE9D,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEtD,KAAK,MAAM,UAAU,IAAI,4BAA4B,CAAC,eAAe,EAAE,QAAQ,CAAC,EAAE,CAAC;QACjF,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,4BAA4B,CAAC,gBAAgB,EAAE,SAAS,CAAC,EAAE,CAAC;QACnF,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,WAAkC,EAClC,IAAY;IAEZ,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;AACpF,CAAC"}

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

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

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

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

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

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+vi.mock("node:fs", () => ({
+    readdirSync: vi.fn(),
+    readFileSync: vi.fn(),
+}));
+vi.mock("node:os", () => ({
+    homedir: vi.fn(() => "/home/test-user"),
+}));
+import { findAgent, loadAgentDefinitions } from "./agent-loader.js";
+const HOME_DIR = "/home/test-user";
+const PROJECT_PATH = "/workspace/project";
+const GLOBAL_AGENTS_DIR = join(HOME_DIR, ".kiln", "agents");
+const PROJECT_AGENTS_DIR = join(PROJECT_PATH, ".kiln", "agents");
+const readdirSyncMock = readdirSync;
+const readFileSyncMock = readFileSync;
+const homedirMock = homedir;
+function throwNotFound() {
+    const error = new Error("ENOENT");
+    throw error;
+}
+function markdownWithFrontmatter(frontmatter, body = "") {
+    return `---\n${frontmatter}\n---\n${body}`;
+}
+function configureDirectories(globalEntries, projectEntries) {
+    readdirSyncMock.mockImplementation((directoryPath) => {
+        if (directoryPath === GLOBAL_AGENTS_DIR) {
+            if (!globalEntries)
+                throwNotFound();
+            return [...globalEntries];
+        }
+        if (directoryPath === PROJECT_AGENTS_DIR) {
+            if (!projectEntries)
+                throwNotFound();
+            return [...projectEntries];
+        }
+        throwNotFound();
+    });
+}
+function configureFiles(files) {
+    readFileSyncMock.mockImplementation((filePath) => {
+        const content = files[String(filePath)];
+        if (content === undefined) {
+            throwNotFound();
+        }
+        return content;
+    });
+}
+describe("agent-loader", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        homedirMock.mockReturnValue(HOME_DIR);
+        configureDirectories();
+        configureFiles({});
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns empty array when both directories missing", async () => {
+        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        expect(definitions).toEqual([]);
+        expect(readdirSyncMock).toHaveBeenCalledWith(GLOBAL_AGENTS_DIR);
+        expect(readdirSyncMock).toHaveBeenCalledWith(PROJECT_AGENTS_DIR);
+    });
+    it("parses frontmatter correctly (name, role, tools, model, skills)", async () => {
+        configureDirectories(["architect.md"], []);
+        configureFiles({
+            [join(GLOBAL_AGENTS_DIR, "architect.md")]: markdownWithFrontmatter([
+                "name: Architect",
+                "role: System architect",
+                "tools:",
+                "  - read",
+                "  - write",
+                "model: claude-sonnet-4-6",
+                "skills:",
+                "  - sequel-spring",
+                "  - refactor",
+            ].join("\n")),
+        });
+        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        expect(definitions).toEqual([
+            {
+                name: "Architect",
+                role: "System architect",
+                tools: ["read", "write"],
+                model: "claude-sonnet-4-6",
+                skills: ["sequel-spring", "refactor"],
+                scope: "global",
+            },
+        ]);
+    });
+    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"),
+        });
+        const [definition] = await loadAgentDefinitions(PROJECT_PATH);
+        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")),
+        });
+        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        expect(definitions).toHaveLength(3);
+        expect(findAgent(definitions, "shared")).toEqual({
+            name: "Shared",
+            role: "Project role",
+            scope: "project",
+        });
+        expect(findAgent(definitions, "globalonly")?.scope).toBe("global");
+        expect(findAgent(definitions, "projectonly")?.scope).toBe("project");
+    });
+    it("skips files missing required name field", async () => {
+        configureDirectories(["missing-name.md"], []);
+        configureFiles({
+            [join(GLOBAL_AGENTS_DIR, "missing-name.md")]: markdownWithFrontmatter(["role: No name present"].join("\n")),
+        });
+        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        expect(definitions).toEqual([]);
+    });
+    it("skips files missing required role field", async () => {
+        configureDirectories(["missing-role.md"], []);
+        configureFiles({
+            [join(GLOBAL_AGENTS_DIR, "missing-role.md")]: markdownWithFrontmatter(["name: MissingRole"].join("\n")),
+        });
+        const definitions = await loadAgentDefinitions(PROJECT_PATH);
+        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" },
+        ];
+        expect(findAgent(definitions, "planner")).toBe(definitions[0]);
+        expect(findAgent(definitions, "CODE-REVIEWER")).toBe(definitions[1]);
+    });
+    it("findAgent() returns undefined for unknown name", () => {
+        const definitions = [
+            { name: "Planner", role: "Planning specialist", scope: "global" },
+        ];
+        expect(findAgent(definitions, "unknown")).toBeUndefined();
+    });
+});
+//# sourceMappingURL=agent-loader.test.js.map

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

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

package/dist/application/context-artifact-keys.d.ts

@@ -0,0 +1,5 @@
+export declare function buildCliSessionSummaryArtifactKey(sessionId: string): string;
+export declare function buildCliProjectSummaryArtifactKey(projectPath: string): string;
+export declare function buildCliPlanSummaryArtifactKey(projectPath: string, task: string, maxTaskShapeLength?: number): string;
+export declare function buildCliPlanSummaryArtifactKeyFromShape(projectPath: string, taskShape: string): string;
+//# sourceMappingURL=context-artifact-keys.d.ts.map

package/dist/application/context-artifact-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-artifact-keys.d.ts","sourceRoot":"","sources":["../../src/application/context-artifact-keys.ts"],"names":[],"mappings":"AAEA,wBAAgB,iCAAiC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,kBAAkB,SAAK,GACtB,MAAM,CAER;AAED,wBAAgB,uCAAuC,CACrD,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER"}

package/dist/application/context-artifact-keys.js

@@ -0,0 +1,14 @@
+import { normalizeTaskShapeKey } from "@kilnai/core";
+export function buildCliSessionSummaryArtifactKey(sessionId) {
+    return `session-summary:${sessionId}`;
+}
+export function buildCliProjectSummaryArtifactKey(projectPath) {
+    return `project-summary:${projectPath}`;
+}
+export function buildCliPlanSummaryArtifactKey(projectPath, task, maxTaskShapeLength = 80) {
+    return `plan-summary:${projectPath}:${normalizeTaskShapeKey(task, maxTaskShapeLength)}`;
+}
+export function buildCliPlanSummaryArtifactKeyFromShape(projectPath, taskShape) {
+    return `plan-summary:${projectPath}:${taskShape}`;
+}
+//# sourceMappingURL=context-artifact-keys.js.map

package/dist/application/context-artifact-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-artifact-keys.js","sourceRoot":"","sources":["../../src/application/context-artifact-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,UAAU,iCAAiC,CAAC,SAAiB;IACjE,OAAO,mBAAmB,SAAS,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,WAAmB;IACnE,OAAO,mBAAmB,WAAW,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,IAAY,EACZ,kBAAkB,GAAG,EAAE;IAEvB,OAAO,gBAAgB,WAAW,IAAI,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,uCAAuC,CACrD,WAAmB,EACnB,SAAiB;IAEjB,OAAO,gBAAgB,WAAW,IAAI,SAAS,EAAE,CAAC;AACpD,CAAC"}

package/dist/application/context-governance.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectedContext } from "./context-types.js";
+import type { KilnPermissionPolicy } from "../wrapper/session.js";
+import type { SessionContext } from "../wrapper/index.js";
+export declare function governProjectedContext(projectedContext: ProjectedContext, permissionPolicy: KilnPermissionPolicy): ProjectedContext;
+export declare function governSessionContext(context: SessionContext, permissionPolicy: KilnPermissionPolicy): SessionContext;
+//# sourceMappingURL=context-governance.d.ts.map

package/dist/application/context-governance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-governance.d.ts","sourceRoot":"","sources":["../../src/application/context-governance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,EAAE,oBAAoB,GACrC,gBAAgB,CAalB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,cAAc,EACvB,gBAAgB,EAAE,oBAAoB,GACrC,cAAc,CAKhB"}

package/dist/application/context-governance.js

@@ -0,0 +1,20 @@
+export function governProjectedContext(projectedContext, permissionPolicy) {
+    if (permissionPolicy.fileGovernance?.excludeFromContext !== true) {
+        return projectedContext;
+    }
+    const blocks = projectedContext.blocks.filter((block) => block.kind !== "memory");
+    return {
+        blocks,
+        estimatedTokens: blocks.reduce((total, block) => total + (block.estimatedTokens ?? 0), 0),
+        tokenBudget: projectedContext.tokenBudget,
+        deferredBlocks: projectedContext.deferredBlocks?.filter((block) => block.kind !== "memory"),
+        overflow: projectedContext.overflow,
+    };
+}
+export function governSessionContext(context, permissionPolicy) {
+    return {
+        ...context,
+        projectedContext: governProjectedContext(context.projectedContext, permissionPolicy),
+    };
+}
+//# sourceMappingURL=context-governance.js.map

package/dist/application/context-governance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-governance.js","sourceRoot":"","sources":["../../src/application/context-governance.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,sBAAsB,CACpC,gBAAkC,EAClC,gBAAsC;IAEtC,IAAI,gBAAgB,CAAC,cAAc,EAAE,kBAAkB,KAAK,IAAI,EAAE,CAAC;QACjE,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAClF,OAAO;QACL,MAAM;QACN,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QACzF,WAAW,EAAE,gBAAgB,CAAC,WAAW;QACzC,cAAc,EAAE,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;QAC3F,QAAQ,EAAE,gBAAgB,CAAC,QAAQ;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,OAAuB,EACvB,gBAAsC;IAEtC,OAAO;QACL,GAAG,OAAO;QACV,gBAAgB,EAAE,sBAAsB,CAAC,OAAO,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;KACrF,CAAC;AACJ,CAAC"}

package/dist/application/context-governor.d.ts

@@ -0,0 +1,26 @@
+import type { ContextArtifactCache } from "@kilnai/core";
+import type { ProjectedContext } from "./context-types.js";
+import type { SessionLedger } from "./session-ledger.js";
+import type { KilnContextGovernanceAggressiveness, KilnContextGovernanceSource } from "../kiln-yaml-types.js";
+export interface ProjectContextInput {
+    readonly memorySnapshot?: string;
+    readonly sessionLedger?: SessionLedger;
+    readonly exactArtifacts?: readonly string[];
+    readonly cache?: ContextArtifactCache;
+    readonly moduleArtifactKeys?: readonly string[];
+    readonly projectArtifactKey?: string;
+    readonly planArtifactKey?: string;
+    readonly sessionArtifactKey?: string;
+    readonly tokenBudget?: number;
+    readonly preferredSources?: readonly KilnContextGovernanceSource[];
+    readonly summaryAggressiveness?: KilnContextGovernanceAggressiveness;
+}
+export interface ContextGovernor {
+    project(input: ProjectContextInput): ProjectedContext;
+}
+export declare const DEFAULT_PROJECTED_CONTEXT_TOKEN_BUDGET = 2000;
+export declare const DEFAULT_SESSION_ARTIFACT_TTL_MS: number;
+export declare class DefaultContextGovernor implements ContextGovernor {
+    project(input: ProjectContextInput): ProjectedContext;
+}
+//# sourceMappingURL=context-governor.d.ts.map

package/dist/application/context-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-governor.d.ts","sourceRoot":"","sources":["../../src/application/context-governor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAA0B,MAAM,cAAc,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAyB,MAAM,oBAAoB,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EACV,mCAAmC,EACnC,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACnE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,mCAAmC,CAAC;CACtE;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB,CAAC;CACvD;AAED,eAAO,MAAM,sCAAsC,OAAO,CAAC;AAC3D,eAAO,MAAM,+BAA+B,QAAsB,CAAC;AA0CnE,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,OAAO,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;CAkItD"}

package/dist/application/context-governor.js

@@ -0,0 +1,164 @@
+import { getFieldStrength, selectContextWithinBudget } from "@kilnai/core";
+import { estimateTextTokens } from "./context-types.js";
+import { renderSessionLedger } from "./session-ledger.js";
+export const DEFAULT_PROJECTED_CONTEXT_TOKEN_BUDGET = 2000;
+export const DEFAULT_SESSION_ARTIFACT_TTL_MS = 1000 * 60 * 60 * 12;
+const PREFERRED_SOURCE_SCORE_BONUS = 0.2;
+const FIELD_CATEGORY_BONUS = 0.35;
+const SUMMARY_AGGRESSIVENESS_ADJUSTMENTS = {
+    low: { summaryBonus: -0.08, artifactPenalty: 0 },
+    medium: { summaryBonus: 0, artifactPenalty: 0 },
+    high: { summaryBonus: 0.12, artifactPenalty: -0.08 },
+};
+function classifyGovernanceSource(block) {
+    switch (block.kind) {
+        case "ledger":
+            return "ledger";
+        case "artifact":
+            return "artifact";
+        case "summary":
+            return "summary";
+        case "memory":
+            return "memory";
+        case "knowledge":
+            return "knowledge";
+    }
+}
+function mapBlockToFieldCategory(block) {
+    return `category:${block.kind}`;
+}
+function applySummaryAggressiveness(block, aggressiveness) {
+    const adjustment = SUMMARY_AGGRESSIVENESS_ADJUSTMENTS[aggressiveness];
+    if (block.required)
+        return 0;
+    if (block.kind === "summary")
+        return adjustment.summaryBonus;
+    if (block.kind === "artifact")
+        return adjustment.artifactPenalty;
+    return 0;
+}
+export class DefaultContextGovernor {
+    project(input) {
+        const blocks = [];
+        for (const [index, key] of (input.moduleArtifactKeys ?? []).entries()) {
+            const cachedModuleSummary = input.cache?.get(key);
+            if (cachedModuleSummary && cachedModuleSummary.content.trim() !== "") {
+                blocks.push({
+                    id: `summary:cached-module:${index}`,
+                    kind: "summary",
+                    source: "context-artifact-cache",
+                    content: cachedModuleSummary.content,
+                    required: false,
+                    score: 0.78,
+                    estimatedTokens: estimateTextTokens(cachedModuleSummary.content),
+                });
+            }
+        }
+        const cachedPlanSummary = input.planArtifactKey && input.cache
+            ? input.cache.get(input.planArtifactKey)
+            : undefined;
+        if (cachedPlanSummary && cachedPlanSummary.content.trim() !== "") {
+            blocks.push({
+                id: "summary:cached-plan",
+                kind: "summary",
+                source: "context-artifact-cache",
+                content: cachedPlanSummary.content,
+                required: false,
+                score: 0.85,
+                estimatedTokens: estimateTextTokens(cachedPlanSummary.content),
+            });
+        }
+        const cachedProjectSummary = input.projectArtifactKey && input.cache
+            ? input.cache.get(input.projectArtifactKey)
+            : undefined;
+        if (cachedProjectSummary && cachedProjectSummary.content.trim() !== "") {
+            blocks.push({
+                id: "summary:cached-project",
+                kind: "summary",
+                source: "context-artifact-cache",
+                content: cachedProjectSummary.content,
+                required: false,
+                score: 0.75,
+                estimatedTokens: estimateTextTokens(cachedProjectSummary.content),
+            });
+        }
+        const cachedSummary = input.sessionArtifactKey && input.cache
+            ? input.cache.get(input.sessionArtifactKey)
+            : undefined;
+        if (cachedSummary && cachedSummary.content.trim() !== "") {
+            blocks.push({
+                id: "summary:cached-session",
+                kind: "summary",
+                source: "context-artifact-cache",
+                content: cachedSummary.content,
+                required: false,
+                score: 0.8,
+                estimatedTokens: estimateTextTokens(cachedSummary.content),
+            });
+        }
+        const renderedLedger = input.sessionLedger ? renderSessionLedger(input.sessionLedger) : undefined;
+        if (renderedLedger) {
+            blocks.push({
+                id: "ledger:session",
+                kind: "ledger",
+                source: "session-ledger",
+                content: renderedLedger,
+                required: true,
+                score: 1,
+                estimatedTokens: estimateTextTokens(renderedLedger),
+            });
+        }
+        for (const [index, artifact] of (input.exactArtifacts ?? []).entries()) {
+            if (artifact.trim() === "")
+                continue;
+            blocks.push({
+                id: `artifact:${index}`,
+                kind: "artifact",
+                source: "session-artifact",
+                content: artifact,
+                required: true,
+                score: 0.95,
+                estimatedTokens: estimateTextTokens(artifact),
+            });
+        }
+        if (input.memorySnapshot && input.memorySnapshot.trim() !== "") {
+            blocks.push({
+                id: "memory:snapshot",
+                kind: "memory",
+                source: "session-memory-snapshot",
+                content: input.memorySnapshot,
+                required: false,
+                score: 0.6,
+                estimatedTokens: estimateTextTokens(input.memorySnapshot),
+            });
+        }
+        const tokenBudget = input.tokenBudget ?? DEFAULT_PROJECTED_CONTEXT_TOKEN_BUDGET;
+        const preferredSources = new Set(input.preferredSources ?? []);
+        const summaryAggressiveness = input.summaryAggressiveness ?? "medium";
+        const candidates = blocks.map((block) => {
+            const preferredBonus = preferredSources.has(classifyGovernanceSource(block))
+                ? PREFERRED_SOURCE_SCORE_BONUS
+                : 0;
+            const summaryAdjustment = applySummaryAggressiveness(block, summaryAggressiveness);
+            const fieldBoost = FIELD_CATEGORY_BONUS * getFieldStrength(mapBlockToFieldCategory(block));
+            return {
+                id: block.id,
+                required: block.required,
+                estimatedTokens: block.estimatedTokens ?? estimateTextTokens(block.content),
+                score: block.score + preferredBonus + summaryAdjustment + fieldBoost,
+                meta: block,
+            };
+        });
+        const selection = selectContextWithinBudget(candidates, tokenBudget);
+        const selectedBlocks = selection.selected.map((candidate) => candidate.meta);
+        const deferredBlocks = selection.deferred.map((candidate) => candidate.meta);
+        return {
+            blocks: selectedBlocks,
+            estimatedTokens: selection.selectedTokens,
+            tokenBudget,
+            deferredBlocks,
+            overflow: selection.overflow,
+        };
+    }
+}
+//# sourceMappingURL=context-governor.js.map