klyro 1.0.6 → 1.0.7

package/dist/context/memory.js

@@ -10,17 +10,30 @@ import * as fs from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { redact } from '../policy/secret-redactor.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../policy/path-guard.js';
 /** Single-write ceiling — anything larger is rejected, not sliced. */
 export const MEMORY_WRITE_LIMIT_CHARS = 8000;
 /** Steady-state cap (~1k tokens ≈ 4k chars) kept via tail slice. */
 export const MEMORY_STEADY_STATE_CHARS = 4000;
+/** Archive index filename (recall without an LLM pass). */
+export const MEMORY_ARCHIVE_INDEX = 'archive-index.json';
+/** Max retained archives. */
+export const MEMORY_ARCHIVE_KEEP = 20;
 export async function memoryWrite(cwd, content) {
     if (content.length > MEMORY_WRITE_LIMIT_CHARS) {
         throw new Error(`memory budget exceeded: single write is ${content.length} chars (max ${MEMORY_WRITE_LIMIT_CHARS}) — split it into smaller notes`);
     }
+    // B4 — symlink/TOCTOU guard: the memory dir must stay inside cwd even if
+    // `.klyro` or `.klyro/memory` is (or becomes) a symlink. Resolve+follow up
+    // the existing parent chain first (defeats an escaping parent symlink), then
+    // mkdir, then a final realpath + lstat: a swapped-in final symlink is
+    // refused before any write lands outside cwd.
     const dir = path.join(cwd, '.klyro', 'memory');
+    await resolveAndFollowSymlinks(cwd, '.klyro'); // throws if `.klyro` escapes cwd
     await fs.mkdir(dir, { recursive: true });
-    const p = path.join(dir, 'session-notes.md');
+    const { resolved } = await resolveAndFollowSymlinks(cwd, '.klyro/memory');
+    await assertNotSymlink(resolved);
+    const p = path.join(resolved, 'session-notes.md');
     const prev = await fs.readFile(p, 'utf-8').catch(() => '');
     // S4-at-rest: redact before appending — redact() only fires on secret
     // shapes (key/token/password with [:=-]), so normal prose survives.
@@ -28,21 +41,32 @@ export async function memoryWrite(cwd, content) {
     let next = full;
     if (full.length > MEMORY_STEADY_STATE_CHARS) {
         // Rotation, not silent loss: the dropped head is archived to a dated
-        // file (pruned to the latest 20) instead of vanishing. Summarization
-        // of archives is left to an explicit future pass.
+        // file (pruned to the latest 20) instead of vanishing, and the archive
+        // index is refreshed so the model knows what exists to re-read.
         const head = full.slice(0, full.length - MEMORY_STEADY_STATE_CHARS);
         next = full.slice(-MEMORY_STEADY_STATE_CHARS);
         try {
             const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-            await fs.writeFile(path.join(dir, `archive-${stamp}.md`), head, 'utf-8');
-            const entries = (await fs.readdir(dir)).filter((e) => e.startsWith('archive-')).sort();
-            for (const old of entries.slice(0, Math.max(0, entries.length - 20))) {
-                await fs.unlink(path.join(dir, old)).catch(() => undefined);
+            const file = `archive-${stamp}.md`;
+            await fs.writeFile(path.join(resolved, file), head, 'utf-8');
+            const entries = (await fs.readdir(resolved)).filter((e) => e.startsWith('archive-') && e.endsWith('.md')).sort();
+            for (const old of entries.slice(0, Math.max(0, entries.length - MEMORY_ARCHIVE_KEEP))) {
+                await fs.unlink(path.join(resolved, old)).catch(() => undefined);
             }
+            const index = [];
+            for (const e of (await fs.readdir(resolved)).filter((e) => e.startsWith('archive-') && e.endsWith('.md')).sort()) {
+                try {
+                    const content = await fs.readFile(path.join(resolved, e), 'utf-8');
+                    const stat = await fs.stat(path.join(resolved, e));
+                    index.push({ file: e, ts: Math.round(stat.mtimeMs), chars: content.length, preview: content.split('\n')[0]?.slice(0, 160) ?? '' });
+                }
+                catch { /* skip unreadable entries */ }
+            }
+            await fs.writeFile(path.join(resolved, MEMORY_ARCHIVE_INDEX), JSON.stringify(index, null, 2), 'utf-8');
         }
         catch { /* archive is best-effort; the live notes still persist */ }
     }
-    const tmp = path.join(dir, `.session-notes.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    const tmp = path.join(resolved, `.session-notes.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
     await fs.writeFile(tmp, next, 'utf-8');
     try {
         const fh = await fs.open(tmp, 'r+');
@@ -83,7 +107,21 @@ export function loadMemorySync(cwd) {
 /** Wrap persisted notes into the injected prompt block; '' when empty. */
 export function memoryBlock(cwd) {
     const notes = loadMemorySync(cwd).trim();
-    return notes ? `\n\n<memory>\n${notes.slice(0, 4000)}\n</memory>` : '';
+    if (!notes)
+        return '';
+    // Recall aid: tell the model which archives exist (with previews) so it
+    // can re-read them via read_file instead of losing rotated knowledge.
+    let archived = '';
+    try {
+        const raw = readFileSync(path.join(cwd, '.klyro', 'memory', MEMORY_ARCHIVE_INDEX), 'utf-8');
+        const entries = JSON.parse(raw);
+        if (Array.isArray(entries) && entries.length > 0) {
+            const lines = entries.slice(-5).map((e) => `  - .klyro/memory/${e.file} (${e.chars} chars): ${e.preview}`);
+            archived = `\nEarlier notes archived (read one with read_file for detail):\n${lines.join('\n')}`;
+        }
+    }
+    catch { /* no index — nothing archived yet */ }
+    return `\n\n<memory>\n${notes.slice(0, 4000)}${archived}\n</memory>`;
 }
 export function shouldRemind(turn, lastRemindTurn) {
     return turn - lastRemindTurn >= 20;

package/dist/eval/harness.d.ts

@@ -44,6 +44,7 @@ export interface TaskResult {
 export declare function runTask(t: ScriptedTask, opts?: {
     judgeAdapter?: ProviderAdapter;
     judgeModel?: string;
+    workDir?: string;
 }): Promise<TaskResult>;
 export interface HarnessSummary {
     total: number;
@@ -66,14 +67,30 @@ export interface FileFixture {
     checkSh: string;
     meta: Record<string, unknown>;
     repo?: string;
+    /**
+     * Optional canned agent turns (StreamEvent[][], same shape as
+     * ScriptedTask.script). When present the fixture is agent-driven: the
+     * runtime executes the script with real tools in a seeded tmp repo and
+     * check.sh then asserts the filesystem outcomes.
+     */
+    script?: StreamEvent[][];
 }
 export declare function loadFileFixture(dir: string): Promise<FileFixture>;
 export declare function runFileFixture(fixture: FileFixture, opts?: {
     runs?: number;
     parallel?: number;
 }): Promise<TaskResult>;
-/** Hook the harness up to a session + audit log so task runs are durable. */
-export declare function runHarnessWithPersistence(tasks: ScriptedTask[], opts: {
+/**
+ * Agent-driven fixture: seed a tmp repo, run the fixture's canned script
+ * through the REAL runtime + tools, then assert outcomes with check.sh
+ * (plus optional meta judge rubric). This is what makes fixtures more than
+ * static `exit 0` stubs: the agent loop genuinely executes.
+ */
+export declare function runAgentFixture(fixture: FileFixture, opts?: {
+    judgeAdapter?: ProviderAdapter;
+    judgeModel?: string;
+}): Promise<TaskResult>;
+/** Hook the harness up to a session + audit log so task runs are durable. */ export declare function runHarnessWithPersistence(tasks: ScriptedTask[], opts: {
     storeDir: string;
     auditPath: string;
 }): Promise<HarnessSummary>;

package/dist/eval/harness.js

@@ -44,7 +44,11 @@ function scriptedAdapter(script) {
 }
 export async function runTask(t, opts = {}) {
     const start = Date.now();
-    const cwd = path.join(os.tmpdir(), 'klyro-eval-' + t.id + '-' + Math.random().toString(36).slice(2));
+    // workDir lets callers seed a repo and inspect outcomes afterwards
+    // (agent-driven fixtures); otherwise an isolated tmp dir is used and
+    // removed.
+    const owned = !opts.workDir;
+    const cwd = opts.workDir ?? path.join(os.tmpdir(), 'klyro-eval-' + t.id + '-' + Math.random().toString(36).slice(2));
     await fs.mkdir(cwd, { recursive: true });
     const reg = new ToolRegistry()
         .register(readFileTool).register(writeFileTool).register(editFileTool)
@@ -110,10 +114,12 @@ export async function runTask(t, opts = {}) {
         };
     }
     finally {
-        try {
-            await fs.rm(cwd, { recursive: true, force: true });
+        if (owned) {
+            try {
+                await fs.rm(cwd, { recursive: true, force: true });
+            }
+            catch { }
         }
-        catch { }
     }
 }
 export async function runHarness(tasks, opts = {}) {
@@ -158,7 +164,14 @@ export async function loadFileFixture(dir) {
         repo = await fs.readFile(path.join(dir, 'repo'), 'utf-8');
     }
     catch { /* ignore */ }
-    return { dir, task: task.trim(), checkSh, meta, repo };
+    let script;
+    try {
+        const raw = JSON.parse(await fs.readFile(path.join(dir, 'script.json'), 'utf-8'));
+        if (Array.isArray(raw))
+            script = raw;
+    }
+    catch { /* no script → static fixture */ }
+    return { dir, task: task.trim(), checkSh, meta, ...(repo ? { repo } : {}), ...(script ? { script } : {}) };
 }
 export async function runFileFixture(fixture, opts = {}) {
     const start = Date.now();
@@ -196,8 +209,60 @@ export async function runFileFixture(fixture, opts = {}) {
     await fs.rm(tmp, { recursive: true, force: true }).catch(() => undefined);
     return result;
 }
-/** Hook the harness up to a session + audit log so task runs are durable. */
-export async function runHarnessWithPersistence(tasks, opts) {
+/**
+ * Agent-driven fixture: seed a tmp repo, run the fixture's canned script
+ * through the REAL runtime + tools, then assert outcomes with check.sh
+ * (plus optional meta judge rubric). This is what makes fixtures more than
+ * static `exit 0` stubs: the agent loop genuinely executes.
+ */
+export async function runAgentFixture(fixture, opts = {}) {
+    const start = Date.now();
+    const id = path.basename(fixture.dir);
+    if (!fixture.script) {
+        return { id, status: 'fail', details: 'agent fixture needs script.json', durationMs: Date.now() - start };
+    }
+    const tmp = path.join(os.tmpdir(), 'klyro-eval-agent-' + Math.random().toString(36).slice(2));
+    await fs.mkdir(tmp, { recursive: true });
+    try {
+        if (fixture.repo) {
+            const src = path.isAbsolute(fixture.repo) ? fixture.repo : path.join(fixture.dir, fixture.repo);
+            await fs.cp(src, tmp, { recursive: true }).catch(() => undefined);
+        }
+        const meta = fixture.meta;
+        const judgeRubric = meta['judge'] && typeof meta['judge'] === 'object'
+            ? meta['judge'].rubric
+            : undefined;
+        const r = await runTask({
+            id,
+            description: fixture.task.slice(0, 120),
+            task: fixture.task,
+            script: fixture.script,
+            expectStatus: (typeof meta['expectStatus'] === 'string' ? meta['expectStatus'] : 'complete'),
+            ...(typeof meta['expectToolCalls'] === 'number' ? { expectToolCalls: meta['expectToolCalls'] } : {}),
+            ...(Array.isArray(judgeRubric) && judgeRubric.every((s) => typeof s === 'string') ? { judge: { rubric: judgeRubric } } : {}),
+        }, { workDir: tmp, ...(opts.judgeAdapter ? { judgeAdapter: opts.judgeAdapter, judgeModel: opts.judgeModel } : {}) });
+        if (r.status === 'fail')
+            return { ...r, durationMs: Date.now() - start };
+        // Structural pass — now assert real filesystem outcomes.
+        const { spawn } = await import('node:child_process');
+        const out = await new Promise((resolve) => {
+            const child = spawn('bash', ['-c', fixture.checkSh], { cwd: tmp, shell: false });
+            let buf = '';
+            child.stdout?.on('data', (b) => { buf += b.toString(); });
+            child.stderr?.on('data', (b) => { buf += b.toString(); });
+            child.on('close', (code) => resolve(`exit=${code ?? -1} ${buf.slice(0, 500)}`));
+            child.on('error', (err) => resolve(`spawn-error: ${String(err)}`));
+        });
+        if (!out.startsWith('exit=0')) {
+            return { ...r, status: 'fail', details: `${r.details} check.sh: ${out}`.trim(), durationMs: Date.now() - start };
+        }
+        return { ...r, durationMs: Date.now() - start };
+    }
+    finally {
+        await fs.rm(tmp, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** Hook the harness up to a session + audit log so task runs are durable. */ export async function runHarnessWithPersistence(tasks, opts) {
     const store = new SessionStore(opts.storeDir);
     const audit = new AuditLog(opts.auditPath);
     const start = Date.now();

package/dist/index.js

@@ -145,8 +145,9 @@ async function main() {
     program
         .command('update')
         .description('Check for klyro updates (cached 24h, KLYRO_NO_UPDATE_CHECK=1 to disable)')
-        .action(async () => {
-        const code = await runUpdate();
+        .option('--apply', 'Apply the update now via npm i -g (opt-in; default is notify-only)')
+        .action(async (opts) => {
+        const code = await runUpdate({ apply: !!opts.apply });
         process.exit(code);
     });
     program
@@ -645,7 +646,7 @@ async function main() {
     const sessions = program.command('sessions').description('Alias for session (same subcommands)');
     sessions.command('list').description('List persisted sessions').option('--status <s>', 'Filter by status').option('--json', 'Output JSON').action(async (opts) => { await sessionList(opts); });
     sessions.command('show <id>').description('Show session transcript and observations').option('--json', 'Output JSON').action(async (id, opts) => { await sessionShow(id, opts); });
-    sessions.command('resume <id>').description('Resume a persisted session').option('-m, --model <id>', 'Model').option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v)).action(async (id, opts) => { await sessionResume(id, opts); });
+    sessions.command('resume <id>').description('Resume a persisted session').option('-m, --model <id>', 'Model').option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v)).option('--verify-command <cmd>', 'Override verification command').option('--verify', 'Enable verification (default: enabled)').action(async (id, opts) => { await sessionResume(id, opts); });
     sessions.command('export <id> [file]').description('Export session to file (9.4)').action(async (id, file) => { await sessionExport(id, file); });
     sessions.command('import <file>').description('Import session from file (restores record + messages + observations)').action(async (file) => { await sessionImport(file); });
     sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => { await sessionFork(id); });
@@ -732,6 +733,58 @@ async function main() {
             catch { /* ignore */ }
         }
     });
+    mcp.command('trust <name>').description('Trust a project MCP server spec (records its hash, enables auto-connect)').action(async (name) => {
+        const { loadMcpServers } = await import('./mcp/config.js');
+        const { McpTrust, hashSpec } = await import('./mcp/trust.js');
+        const cfg = loadMcpServers(process.cwd());
+        const spec = cfg.servers[name];
+        if (!spec) {
+            process.stderr.write(`klyro: mcp server not found: ${name}\n`);
+            process.exit(2);
+        }
+        new McpTrust().approve(name, hashSpec(spec));
+        process.stdout.write(`trusted mcp server "${name}" (source=${cfg.sources[name] ?? 'unknown'})\n`);
+    });
+    mcp.command('prompts [server]').description('List MCP prompts as /mcp__<server>__<prompt> slash names').action(async (server) => {
+        const { loadMcpServers, enabledServers } = await import('./mcp/config.js');
+        const { makeMcpClient } = await import('./mcp/registry.js');
+        const cfg = loadMcpServers(process.cwd());
+        const targets = server ? [server] : Object.keys(enabledServers(cfg));
+        if (targets.length === 0) {
+            process.stdout.write('mcp prompts: none (no servers configured)\n');
+            return;
+        }
+        let shown = 0;
+        for (const name of targets) {
+            const spec = cfg.servers[name];
+            if (!spec) {
+                process.stderr.write(`klyro: mcp server not found: ${name}\n`);
+                continue;
+            }
+            const client = makeMcpClient(name, spec);
+            try {
+                const withConnect = client;
+                if (typeof withConnect.connect === 'function')
+                    await withConnect.connect();
+                const prompts = typeof client.promptsList === 'function' ? await client.promptsList() : [];
+                for (const p of prompts) {
+                    process.stdout.write(`/mcp__${name}__${p.name}${p.description ? ` — ${p.description}` : ''}\n`);
+                    shown++;
+                }
+            }
+            catch (err) {
+                process.stderr.write(`klyro: mcp prompts ${name} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            finally {
+                try {
+                    await client.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+        if (shown === 0)
+            process.stdout.write('mcp prompts: none exposed by configured servers\n');
+    });
     mcp.command('serve').description('Serve builtin tools as an MCP server over stdio (policy-gated)').action(async () => {
         const { serveStdio } = await import('./mcp/serve.js');
         const code = await serveStdio(process.cwd());
@@ -752,9 +805,42 @@ async function main() {
         for (const h of hooks)
             process.stdout.write(`${h.name} ${h.event}${h.matcher ? ` (${h.matcher})` : ''} ${h.command}\n`);
     });
-    program.command('agents [name] [extra...]').description('List agents (builtins + .klyro/agents/*.md), show one, or run: agents run <name> <task...>').action(async (name, extra) => {
+    program.command('agents [name] [extra...]').description('List agents (builtins + .klyro/agents/*.md), show one, lint files, or run: agents run <name> <task...>').action(async (name, extra) => {
         const { listAllAgents } = await import('./agent/orchestrator.js');
         const ALL = listAllAgents(process.cwd());
+        // `klyro agents lint`: validate custom agent files (ids, tool names).
+        if (name === 'lint') {
+            const { loadCustomAgents } = await import('./agent/custom-agents.js');
+            const { builtinRegistry } = await import('./tools/registry.js');
+            const known = new Set(builtinRegistry().list().map((t) => t.name));
+            const customs = loadCustomAgents(process.cwd());
+            if (customs.length === 0) {
+                process.stdout.write('agents lint: no custom agents in .klyro/agents/ (or ~/.klyro/agents/)\n');
+                return;
+            }
+            let bad = 0;
+            for (const a of customs) {
+                const problems = [];
+                if (!a.description || a.description === `Custom agent ${a.id}`)
+                    problems.push('missing description');
+                for (const t of a.allowedTools ?? []) {
+                    if (!known.has(t))
+                        problems.push(`unknown tool "${t}" (will be dropped at spawn)`);
+                }
+                if (!a.prompt && !(a.allowedTools ?? []).length)
+                    problems.push('no prompt body and no tools — agent has no specialization');
+                if (problems.length > 0) {
+                    bad++;
+                    process.stdout.write(`${a.id} (${a.source ?? 'custom'}):\n${problems.map((p) => `  ! ${p}`).join('\n')}\n`);
+                }
+                else {
+                    process.stdout.write(`${a.id} (${a.source ?? 'custom'}): ok\n`);
+                }
+            }
+            if (bad > 0)
+                process.exit(2);
+            return;
+        }
         // `klyro agents run <name> <task...>`: one-shot run under a named agent.
         if (name === 'run') {
             const [agentName, ...taskParts] = extra ?? [];

package/dist/mcp/auth.d.ts

@@ -0,0 +1,85 @@
+/** Shape of the `auth` block on an MCP server spec (see config.ts). */
+export interface McpAuthSpec {
+    /** OAuth 2.0 client identifier registered with the authorization server. */
+    clientId: string;
+    /** Token endpoint; when absent, discovered from the server's metadata. */
+    tokenEndpoint?: string;
+    /**
+     * Authorization endpoint; when absent, discovered from the server's
+     * metadata. The MCP server URL is the OAuth resource server, so its
+     * `/.well-known/oauth-authorization-server` metadata is the default
+     * discovery source (per the MCP 2025-06-18 auth spec).
+     */
+    authorizationEndpoint?: string;
+    /** Custom redirect URI; defaults to a loopback listener on 127.0.0.1. */
+    redirectUri?: string;
+    /** Space-separated additional scopes to request. */
+    scopes?: string;
+}
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+export interface CachedToken {
+    access_token: string;
+    token_type: string;
+    /** Unix seconds when the token expires. 0 = unknown (treated as valid). */
+    expires_at: number;
+    refresh_token?: string;
+    scope?: string;
+    cachedAtMs: number;
+}
+export declare const TOKEN_STALE_MARGIN_S = 60;
+export declare const TOKENS_FILE = "mcp-tokens.json";
+/** Fully load the token cache as a plain object (missing/corrupt → {}). */
+export declare function loadMcpTokens(): Record<string, CachedToken>;
+/**
+ * Persist a token to the 0600 cache. Merges by key so concurrent server
+ * writes don't clobber each other. A symlinked cache path is refused (the
+ * write would land outside the klyro config dir or be swapped mid-write).
+ */
+export declare function saveMcpToken(cacheKey: string, token: CachedToken): void;
+/** Stable cache key for a server URL + clientId. */
+export declare function mcpTokenCacheKey(url: string, clientId: string): string;
+/** True when a cached token is still usable (with a clock-skew margin). */
+export declare function tokenValid(t: CachedToken): boolean;
+/** PKCE (RFC 7636 §4.1): cryptographically-random 43-128 char code verifier. */
+export declare function generateCodeVerifier(): string;
+/** PKCE §4.2: base64url SHA-256 challenge of the verifier. */
+export declare function codeChallengeFromVerifier(verifier: string): string;
+export interface AuthResolveResult {
+    /** Extra headers (e.g. `Authorization`) to attach to MCP requests. */
+    headers: Record<string, string>;
+    /** True when a cached token was used (no interactive flow needed). */
+    fromCache: boolean;
+}
+/**
+ * Resolve auth headers for a server: reuse a valid cached token, else run
+ * the interactive Authorization Code + PKCE flow. Returns only the headers;
+ * failures surface as `AuthError` so callers (the MCP probe/connect path)
+ * can turn them into a clear error instead of a hang.
+ */
+export declare function resolveAuth(auth: McpAuthSpec, cacheKey: string): Promise<AuthResolveResult>;
+interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+/**
+ * Run the Authorization Code flow with PKCE over a one-shot loopback
+ * redirect (RFC 8252). Best-effort and headless-friendly: on any failure it
+ * throws `AuthError` rather than leaving a stray listener. The token endpoint
+ * defaults to the OAuth metadata `token_endpoint` when the server advertises
+ * it, else the spec's `tokenEndpoint`.
+ */
+export declare function runCodeFlow(auth: McpAuthSpec, serverUrl?: string): Promise<TokenResponse | null>;
+/**
+ * Scrub credential-bearing headers from debug capture so `KLYRO_MCP_DEBUG`
+ * never writes a live access token to disk. Non-credential headers pass
+ * through untouched.
+ */
+export declare function scrubAuthHeaders(headers: Record<string, string>): Record<string, string>;
+/** Refreshes a stale token when a refresh_token is cached (best-effort). */
+export declare function tryRefresh(auth: McpAuthSpec, cached: CachedToken): Promise<CachedToken | null>;
+export {};