@kognai/build 0.6.0

package/dist/bin/kognai.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * kognai — interactive REPL for the Kognai sovereign orchestrator runtime.
+ *
+ * Type `kognai` from any directory. Banner, workspace info, then a prompt
+ * where you submit goals or tasks. Each command spawns `kognai-build` as
+ * a subprocess so you see the full canonical orchestrator UI for every run.
+ *
+ * Slash commands:
+ *   /goal <text>            decompose into 1-5 tasks, run each through pipeline
+ *   /task <text>            single-task triple-supervisor pipeline
+ *   /no-compliance ...      append to either command to bypass Sup3
+ *   /help                   show this
+ *   /clear                  clear screen
+ *   /quit, /exit, Ctrl-D    leave
+ *
+ * Bare text (no slash) defaults to /goal — builders mostly think in goals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = require("node:readline");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+// TICKET-202: mandate lifecycle commands run in-process against the cwd's
+// .swarm-state/mandates/ (the same store kognai-build --mandate persists to).
+const mandate_1 = require("../lib/mandate");
+// ─── Visual primitives (mirrors kognai-build.ts) ─────────────────────────────
+const C = {
+    reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
+    red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', gray: '\x1b[90m',
+    jade: '\x1b[38;5;79m',
+};
+const out = (s = '') => process.stdout.write(s + '\n');
+const W = 72;
+const VERSION = (() => {
+    try {
+        const pj = (0, node_path_1.join)(__dirname, '..', 'package.json');
+        return (0, node_fs_1.existsSync)(pj) ? JSON.parse((0, node_fs_1.readFileSync)(pj, 'utf-8')).version : '?';
+    }
+    catch {
+        return '?';
+    }
+})();
+function visLen(s) { return s.replace(/\x1b\[[0-9;]*m/g, '').length; }
+function sessionId() { return Math.floor(Date.now() / 1000).toString(36).slice(-4); }
+// ─── Welcome banner (entry only — runs once per shell session) ───────────────
+function welcomeBanner(workspace, sid) {
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const left = `${C.jade}●${C.reset}  ${C.bold}KOGNAI RUNTIME${C.reset} ${C.gray}·${C.reset} ${C.jade}${C.bold}READY${C.reset}`;
+    const right = `${C.gray}${ts}${C.reset}`;
+    const pad = W - visLen(left) - visLen(right) - 4;
+    const subLine1 = `   ${C.gray}sovereign orchestrator · v${VERSION} · session #${sid}${C.reset}`;
+    const subLine2 = `   ${C.gray}workspace: ${workspace}${C.reset}`;
+    out('');
+    out(`   ${C.jade}╔${'═'.repeat(W - 2)}╗${C.reset}`);
+    out(`   ${C.jade}║${C.reset}  ${left}${' '.repeat(Math.max(2, pad))}${right}  ${C.jade}║${C.reset}`);
+    out(`   ${C.jade}║${C.reset}${subLine1}${' '.repeat(Math.max(0, W - visLen(subLine1) - 2))}${C.jade}║${C.reset}`);
+    out(`   ${C.jade}║${C.reset}${subLine2}${' '.repeat(Math.max(0, W - visLen(subLine2) - 2))}${C.jade}║${C.reset}`);
+    out(`   ${C.jade}╚${'═'.repeat(W - 2)}╝${C.reset}`);
+    out('');
+    out(`   ${C.gray}Type ${C.reset}${C.bold}/help${C.reset}${C.gray} for commands, or just describe what you want to build.${C.reset}`);
+    out(`   ${C.gray}Bare text is treated as a goal. Use ${C.reset}${C.bold}/task${C.reset}${C.gray} for a single deliverable.${C.reset}`);
+    out('');
+}
+function showHelp() {
+    out('');
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}Commands${C.reset}`);
+    out('');
+    out(`     ${C.bold}/goal${C.reset} ${C.gray}<text>${C.reset}            decompose into 1-5 tasks, run each through the pipeline`);
+    out(`     ${C.bold}/task${C.reset} ${C.gray}<text>${C.reset}            single-deliverable triple-supervisor pipeline`);
+    out(`     ${C.bold}/mandate${C.reset} ${C.gray}<goal>${C.reset}         sign a PACT mandate (template + cost envelope), then execute`);
+    out(`     ${C.bold}/mandates${C.reset}                list signed mandates + burn/status`);
+    out(`     ${C.bold}/revoke${C.reset} ${C.gray}<id>${C.reset}             revoke a mandate (halts its autonomous run)`);
+    out(`     ${C.bold}--profile <axis>${C.reset}         TICKET-135 optimization axis. Cascades to all tasks;`);
+    out(`                              supervisor lens matches.`);
+    out(`                              ${C.gray}security · reliability · performance · maintainability${C.reset}`);
+    out(`                              ${C.gray}compatibility · usability · portability · compliance${C.reset}`);
+    out(`                              ${C.gray}cost-efficiency · time-to-market · sovereignty${C.reset}`);
+    out(`     ${C.bold}/no-compliance${C.reset} ${C.gray}...${C.reset}      bypass Sup3 compliance review (trusted tasks only)`);
+    out(`     ${C.bold}/help${C.reset}                    this`);
+    out(`     ${C.bold}/clear${C.reset}                   clear screen`);
+    out(`     ${C.bold}/version${C.reset}                 version info`);
+    out(`     ${C.bold}/quit${C.reset} ${C.gray}or${C.reset} ${C.bold}/exit${C.reset} ${C.gray}or Ctrl-D${C.reset}   leave`);
+    out('');
+    out(`   ${C.gray}Examples${C.reset}`);
+    out(`     ${C.gray}>${C.reset} TypeScript SDK for a TODO REST API`);
+    out(`     ${C.gray}>${C.reset} /task Stripe webhook handler with idempotency`);
+    out(`     ${C.gray}>${C.reset} /goal Express CRUD service with Postgres`);
+    out('');
+}
+// ─── Locate kognai-build (sibling in same /bin/ directory) ───────────────────
+function locateKognaiBuild() {
+    const here = __dirname;
+    const local = (0, node_path_1.join)(here, 'kognai-build.js');
+    if ((0, node_fs_1.existsSync)(local))
+        return local;
+    return 'kognai-build'; // fallback to PATH lookup
+}
+const KOGNAI_BUILD = locateKognaiBuild();
+// ─── Mandate lifecycle (TICKET-202) ──────────────────────────────────────────
+function shortId(id) { return id.slice(0, 8); }
+function statusColor(status) {
+    return status === 'active' ? C.green
+        : status === 'completed' ? C.gray
+            : status === 'breached' ? C.red
+                : C.yellow; // revoked
+}
+function listMandatesCmd() {
+    let mandates = [];
+    try {
+        mandates = (0, mandate_1.listMandates)();
+    }
+    catch (e) {
+        out(`   ${C.red}error:${C.reset} ${e?.message || String(e)}`);
+        return;
+    }
+    out('');
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}Mandates${C.reset} ${C.gray}(.swarm-state/mandates/)${C.reset}`);
+    out('');
+    if (mandates.length === 0) {
+        out(`     ${C.gray}none yet — sign one with ${C.reset}${C.bold}/mandate <goal>${C.reset}`);
+        out('');
+        return;
+    }
+    for (const m of mandates) {
+        const col = statusColor(m.status);
+        const burn = `$${m.burn.usdc_consumed.toFixed(4)}/$${m.cost_envelope.max_usdc.toFixed(4)}`;
+        out(`     ${C.bold}${shortId(m.mandate_id)}${C.reset}  ${col}${m.status.padEnd(9)}${C.reset} ${C.gray}${burn} · ${m.burn.tasks_completed} task(s)${C.reset}`);
+        out(`              ${C.gray}${m.objective.slice(0, 60)}${m.objective.length > 60 ? '…' : ''}${C.reset}`);
+    }
+    out('');
+    out(`   ${C.gray}Revoke with ${C.reset}${C.bold}/revoke <id>${C.reset}${C.gray} (8-char prefix is fine).${C.reset}`);
+    out('');
+}
+function revokeCmd(rest) {
+    const parts = rest.trim().split(/\s+/);
+    const idArg = (parts.shift() || '').replace(/[^a-fA-F0-9]/g, ''); // strip 0x / ellipsis
+    if (!idArg) {
+        out(`   ${C.yellow}usage:${C.reset} /revoke <mandate-id> [reason]`);
+        return;
+    }
+    const reason = parts.join(' ').trim() || 'founder revoked via REPL';
+    let mandates = [];
+    try {
+        mandates = (0, mandate_1.listMandates)();
+    }
+    catch {
+        mandates = [];
+    }
+    const matches = mandates.filter((m) => m.mandate_id.startsWith(idArg));
+    if (matches.length === 0) {
+        out(`   ${C.yellow}no mandate matches${C.reset} ${idArg}  ${C.gray}— /mandates to list${C.reset}`);
+        return;
+    }
+    if (matches.length > 1) {
+        out(`   ${C.yellow}ambiguous id${C.reset} ${idArg} — matches ${matches.length}; use more characters`);
+        return;
+    }
+    const target = matches[0];
+    if (target.status === 'revoked') {
+        out(`   ${C.gray}mandate ${shortId(target.mandate_id)} is already revoked.${C.reset}`);
+        return;
+    }
+    try {
+        const m = (0, mandate_1.revokeMandate)(target.mandate_id, reason);
+        out(`   ${C.jade}◇${C.reset} Mandate ${C.bold}${shortId(m.mandate_id)}${C.reset} ${C.yellow}revoked${C.reset} ${C.gray}— ${reason}${C.reset}`);
+        out(`     ${C.gray}Autonomous run halts at the next task boundary.${C.reset}`);
+    }
+    catch (e) {
+        out(`   ${C.red}error:${C.reset} ${e?.message || String(e)}`);
+    }
+}
+// ─── Command dispatch ────────────────────────────────────────────────────────
+function runSubcommand(args) {
+    // spawnSync with stdio:'inherit' streams the subprocess output live —
+    // user sees the canonical banner + sections + verdict for each run.
+    const r = (0, node_child_process_1.spawnSync)(process.execPath, [KOGNAI_BUILD, ...args], {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (r.status !== 0 && r.status !== 1) {
+        // Exit 0 = ship, 1 = reject (both expected). Anything else = real error.
+        out(`   ${C.yellow}(subcommand exited with code ${r.status})${C.reset}`);
+    }
+}
+function parseAndDispatch(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    // Slash commands
+    if (trimmed === '/help' || trimmed === '/h' || trimmed === '/?') {
+        showHelp();
+        return;
+    }
+    if (trimmed === '/clear') {
+        process.stdout.write('\x1b[2J\x1b[H');
+        return;
+    }
+    if (trimmed === '/version' || trimmed === '/v') {
+        out(`   ${C.bold}@kognai/build${C.reset} v${VERSION}`);
+        out(`   ${C.gray}bin: ${KOGNAI_BUILD}${C.reset}`);
+        return;
+    }
+    if (trimmed === '/quit' || trimmed === '/exit' || trimmed === '/q') {
+        out(`   ${C.gray}goodbye${C.reset}`);
+        process.exit(0);
+    }
+    // Mandate lifecycle (TICKET-202) — in-process, no subcommand spawn.
+    if (trimmed === '/mandates') {
+        listMandatesCmd();
+        return;
+    }
+    if (trimmed === '/revoke' || trimmed.startsWith('/revoke ')) {
+        revokeCmd(trimmed.replace(/^\/revoke\s*/, ''));
+        return;
+    }
+    // Strip --no-compliance + --profile <axis> from anywhere in the input.
+    // --profile maps to TICKET-135 optimization axes (security / reliability / ...).
+    const noCompliance = /(^|\s)\/?no-compliance(\s|$)/.test(trimmed);
+    let profile;
+    const profileMatch = trimmed.match(/(?:^|\s)--?profile\s+(\S+)/);
+    if (profileMatch)
+        profile = profileMatch[1];
+    const cleaned = trimmed
+        .replace(/(^|\s)\/?no-compliance(\s|$)/g, ' ')
+        .replace(/(?:^|\s)--?profile\s+\S+/g, ' ')
+        .trim();
+    // /task <text> — single deliverable
+    if (cleaned.startsWith('/task ') || cleaned === '/task') {
+        const taskText = cleaned.replace(/^\/task\s*/, '').trim();
+        if (!taskText) {
+            out(`   ${C.yellow}usage:${C.reset} /task <description> [--profile <axis>] [--no-compliance]`);
+            return;
+        }
+        const args = [taskText];
+        if (profile)
+            args.push('--profile', profile);
+        if (noCompliance)
+            args.push('--no-compliance');
+        runSubcommand(args);
+        return;
+    }
+    // /goal <text> — multi-task decomposition
+    if (cleaned.startsWith('/goal ') || cleaned === '/goal') {
+        const goalText = cleaned.replace(/^\/goal\s*/, '').trim();
+        if (!goalText) {
+            out(`   ${C.yellow}usage:${C.reset} /goal <description> [--profile <axis>] [--no-compliance]`);
+            return;
+        }
+        const args = ['--goal', goalText];
+        if (profile)
+            args.push('--profile', profile);
+        if (noCompliance)
+            args.push('--no-compliance');
+        runSubcommand(args);
+        return;
+    }
+    // /mandate <text> — decompose, sign a PACT mandate, then execute within envelope
+    if (cleaned.startsWith('/mandate ') || cleaned === '/mandate') {
+        const goalText = cleaned.replace(/^\/mandate\s*/, '').trim();
+        if (!goalText) {
+            out(`   ${C.yellow}usage:${C.reset} /mandate <goal> [--profile <axis>] [--no-compliance]`);
+            return;
+        }
+        const args = ['--mandate', goalText];
+        if (profile)
+            args.push('--profile', profile);
+        if (noCompliance)
+            args.push('--no-compliance');
+        runSubcommand(args);
+        return;
+    }
+    // Unknown slash command
+    if (cleaned.startsWith('/')) {
+        out(`   ${C.yellow}unknown command:${C.reset} ${cleaned.split(/\s+/)[0]}`);
+        out(`   ${C.gray}try${C.reset} /help`);
+        return;
+    }
+    // Bare text → default to /goal
+    const args = ['--goal', cleaned];
+    if (profile)
+        args.push('--profile', profile);
+    if (noCompliance)
+        args.push('--no-compliance');
+    runSubcommand(args);
+}
+// ─── Main REPL ───────────────────────────────────────────────────────────────
+function main() {
+    // ANTHROPIC_API_KEY check upfront (subcommands also check, but fail fast here)
+    if (!process.env.ANTHROPIC_API_KEY) {
+        out('');
+        out(`   ${C.red}${C.bold}error:${C.reset} ANTHROPIC_API_KEY environment variable not set.`);
+        out(`   ${C.gray}Run${C.reset} ${C.bold}export ANTHROPIC_API_KEY=sk-ant-...${C.reset} ${C.gray}and retry.${C.reset}`);
+        out('');
+        process.exit(2);
+    }
+    welcomeBanner(process.cwd(), sessionId());
+    const rl = (0, node_readline_1.createInterface)({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: `   ${C.jade}›${C.reset} `,
+        terminal: true,
+    });
+    rl.prompt();
+    rl.on('line', (line) => {
+        try {
+            parseAndDispatch(line);
+        }
+        catch (e) {
+            out(`   ${C.red}error:${C.reset} ${e?.message || String(e)}`);
+        }
+        out('');
+        rl.prompt();
+    });
+    rl.on('close', () => {
+        out('');
+        out(`   ${C.gray}goodbye${C.reset}`);
+        out('');
+        process.exit(0);
+    });
+}
+main();

package/dist/lib/boot-env.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * boot-env.ts — side-effect module that MUST be imported before
+ * @kognai/orchestrator-core (TICKET-233 Phase 1).
+ *
+ * The engine's KSL record-writer captures its write root from KOGNAI_ROOT at
+ * module-load time. To keep the CLI's KSL measurement scoped to a bound
+ * `.kognai/` workspace (and out of arbitrary builder cwds), we resolve the
+ * workspace root here — before the engine loads — and set KOGNAI_ROOT to it.
+ *
+ * No `.kognai/` found → KOGNAI_ROOT stays unset and the CLI does not tap KSL
+ * (see runOneTask), so a plain `npx @kognai/build "..."` writes nothing extra.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+if (!process.env.KOGNAI_ROOT) {
+    let dir = process.cwd();
+    // Walk up looking for <dir>/.kognai/config.yaml (mirrors discoverWorkspace).
+    for (;;) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(dir, '.kognai', 'config.yaml'))) {
+            process.env.KOGNAI_ROOT = dir;
+            break;
+        }
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+}

package/dist/lib/cost-estimator.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateCost = estimateCost;
+const tool_layer_1 = require("../lib/tool-layer");
+const TIER_RATES = {
+    local: 0.0,
+    'cloud-code': 0.17,
+    'cloud-exec': 0.015,
+    apex: 0.85,
+};
+const DEFAULT_EXPECTED_TOOL_CALLS = 3;
+const SAFETY_MARGIN = 1.5;
+/**
+ * Produce a heuristic cost envelope for a planned set of tasks under a
+ * chosen template. This is a pure function with no IO; it composes per-task
+ * model baselines with tool-layer cost estimates.
+ *
+ * Phase 3 (TICKET-135 Accountant via x402) will replace these baselines with
+ * a real CFO database query. Until then, the rates here serve as the
+ * authoritative envelope for routing decisions.
+ */
+function estimateCost(tasks, template) {
+    if (!Array.isArray(tasks)) {
+        throw new TypeError('estimateCost: tasks must be an array');
+    }
+    if (!template || typeof template !== 'object') {
+        throw new TypeError('estimateCost: template must be a Template object');
+    }
+    const breakdown = tasks.map((task) => {
+        const tierRate = TIER_RATES[task.task_target];
+        if (tierRate === undefined) {
+            throw new RangeError(`estimateCost: unknown task_target "${task.task_target}" on task ${task.id}`);
+        }
+        const expectedToolCalls = task.expected_tool_calls ?? DEFAULT_EXPECTED_TOOL_CALLS;
+        const model_usdc = tierRate;
+        const tool_usdc = (0, tool_layer_1.estimateToolCost)(template.tools, expectedToolCalls);
+        const total_usdc = model_usdc + tool_usdc;
+        return {
+            task_id: task.id,
+            model_usdc,
+            tool_usdc,
+            total_usdc,
+        };
+    });
+    const estimated_usdc = breakdown.reduce((sum, entry) => sum + entry.total_usdc, 0);
+    const max_usdc = estimated_usdc * SAFETY_MARGIN;
+    const per_task_budget = tasks.length > 0 ? estimated_usdc / tasks.length : 0;
+    return {
+        estimated_usdc,
+        max_usdc,
+        per_task_budget,
+        breakdown,
+    };
+}

package/dist/lib/knowledge.js

@@ -0,0 +1,256 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadKnowledge = loadKnowledge;
+exports.renderKnowledgePrefix = renderKnowledgePrefix;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const DEFAULT_MAX_BYTES = 200_000;
+const KNOWLEDGE_EXTENSIONS = ['.md', '.txt'];
+/**
+ * Check if a filename has a knowledge-eligible extension.
+ */
+function hasKnowledgeExtension(filename) {
+    const lower = filename.toLowerCase();
+    return KNOWLEDGE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Recursively walk a directory and collect files matching the extension filter.
+ */
+function walkDirectory(dirAbs, extensionFilter) {
+    const results = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = path.join(dirAbs, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDirectory(full, extensionFilter));
+        }
+        else if (entry.isFile()) {
+            if (extensionFilter) {
+                if (entry.name.toLowerCase().endsWith(extensionFilter.toLowerCase())) {
+                    results.push(full);
+                }
+            }
+            else if (hasKnowledgeExtension(entry.name)) {
+                results.push(full);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Resolve a single knowledge_ref pattern into a list of absolute file paths.
+ *
+ * Supported patterns:
+ *   - 'path/to/file.md'           — single file
+ *   - 'path/to/dir'               — recursive walk, collect *.md and *.txt
+ *   - 'path/to/dir/**\/*.md'      — explicit recursive glob, ext-filtered
+ *   - Absolute paths honored as-is; relative paths resolve from workspaceRoot
+ */
+function resolvePattern(pattern, workspaceRoot) {
+    // Detect explicit recursive glob: <prefix>/**/*.<ext>
+    const globMatch = pattern.match(/^(.*?)\/\*\*\/\*(\.[A-Za-z0-9]+)$/);
+    if (globMatch) {
+        const prefix = globMatch[1];
+        const ext = globMatch[2];
+        const baseDir = path.isAbsolute(prefix)
+            ? prefix
+            : path.resolve(workspaceRoot, prefix);
+        if (!fs.existsSync(baseDir))
+            return [];
+        let stat;
+        try {
+            stat = fs.statSync(baseDir);
+        }
+        catch {
+            return [];
+        }
+        if (!stat.isDirectory())
+            return [];
+        return walkDirectory(baseDir, ext);
+    }
+    // Reject other glob syntax in Phase 1 — fall through silently (no match).
+    if (pattern.includes('*') || pattern.includes('?')) {
+        return [];
+    }
+    const resolved = path.isAbsolute(pattern)
+        ? pattern
+        : path.resolve(workspaceRoot, pattern);
+    let stat;
+    try {
+        stat = fs.statSync(resolved);
+    }
+    catch {
+        return [];
+    }
+    if (stat.isFile()) {
+        return [resolved];
+    }
+    if (stat.isDirectory()) {
+        return walkDirectory(resolved);
+    }
+    return [];
+}
+/**
+ * Compute a relative path from workspace root, falling back to absolute
+ * when the file lives outside the workspace tree.
+ */
+function relativeToWorkspace(absPath, workspaceRoot) {
+    const rel = path.relative(workspaceRoot, absPath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+        return absPath;
+    }
+    return rel;
+}
+/**
+ * Load knowledge from workspace.knowledge_refs.
+ *
+ * Reads all *.md and *.txt files matching the patterns, concatenates with
+ * boundary markers, and caps the total payload at maxBytes. When the cap
+ * is hit, the OLDEST files (by mtime) are skipped first so the newest
+ * knowledge always wins.
+ */
+function loadKnowledge(workspace, maxBytes = DEFAULT_MAX_BYTES) {
+    const empty = {
+        text: '',
+        files_read: [],
+        files_skipped: [],
+        total_bytes: 0,
+    };
+    const refs = workspace.knowledge_refs;
+    if (!refs || refs.length === 0) {
+        return empty;
+    }
+    const workspaceRoot = workspace.root;
+    // 1. Resolve all patterns into a deduplicated absolute path list.
+    const seen = new Set();
+    const candidates = [];
+    for (const pattern of refs) {
+        for (const abs of resolvePattern(pattern, workspaceRoot)) {
+            if (!seen.has(abs)) {
+                seen.add(abs);
+                candidates.push(abs);
+            }
+        }
+    }
+    if (candidates.length === 0) {
+        return empty;
+    }
+    // 2. Stat each file to capture mtime and size; drop unreadable entries.
+    const entries = [];
+    for (const absPath of candidates) {
+        let stat;
+        try {
+            stat = fs.statSync(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        entries.push({
+            absPath,
+            relPath: relativeToWorkspace(absPath, workspaceRoot),
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+        });
+    }
+    if (entries.length === 0) {
+        return empty;
+    }
+    // 3. Sort newest-first so the most recent knowledge wins under the cap.
+    //    Older files get skipped when we exceed maxBytes.
+    entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const includedParts = [];
+    const filesRead = [];
+    const filesSkipped = [];
+    let totalBytes = 0;
+    for (const entry of entries) {
+        let content;
+        try {
+            content = fs.readFileSync(entry.absPath, 'utf8');
+        }
+        catch {
+            filesSkipped.push(entry.absPath);
+            continue;
+        }
+        const block = `\n# === ${entry.relPath} ===\n${content}\n`;
+        const blockBytes = Buffer.byteLength(block, 'utf8');
+        if (totalBytes + blockBytes > maxBytes) {
+            filesSkipped.push(entry.absPath);
+            continue;
+        }
+        includedParts.push(block);
+        filesRead.push(entry.absPath);
+        totalBytes += blockBytes;
+    }
+    if (filesRead.length === 0) {
+        return {
+            text: '',
+            files_read: [],
+            files_skipped: filesSkipped,
+            total_bytes: 0,
+        };
+    }
+    return {
+        text: includedParts.join(''),
+        files_read: filesRead,
+        files_skipped: filesSkipped,
+        total_bytes: totalBytes,
+    };
+}
+/**
+ * Render knowledge as a planner-prompt prefix.
+ *
+ * Returns a system-context string ready to prepend to the planner system
+ * prompt. Returns the empty string when no files were read so callers can
+ * safely concatenate without guarding.
+ */
+function renderKnowledgePrefix(block) {
+    if (!block.files_read || block.files_read.length === 0) {
+        return '';
+    }
+    return ('# Workspace Knowledge Base\n\n' +
+        'You are operating in a workspace with the following knowledge. ' +
+        'Read it carefully before decomposing the goal into tasks.\n\n' +
+        block.text +
+        '\n# End of Workspace Knowledge\n\n');
+}