klyro 0.1.20 → 0.1.22

package/dist/cli/context.d.ts

@@ -0,0 +1,2 @@
+import type { Message } from '../agent/message.js';
+export declare function renderContextBreakdown(system: string | undefined, messages: Message[]): string;

package/dist/cli/context.js

@@ -0,0 +1,25 @@
+/**
+ * 8.5 — /context inspector + compaction notice UI + context meter
+ */
+import { accounting, contextMeter } from '../context/accounting.js';
+import { totalTokens, estimateTokens } from '../context/tokenizer.js';
+export function renderContextBreakdown(system, messages) {
+    const acc = accounting(system, messages);
+    const byCat = new Map();
+    byCat.set('system prompt', system ? estimateTokens(system) : 0);
+    // estimate tools/map/KLYRO as part of system already
+    let msgTokens = 0;
+    for (const m of messages)
+        msgTokens += totalTokens(undefined, [m]);
+    byCat.set('messages', msgTokens);
+    const largest = [...messages].map((m) => ({ m, t: totalTokens(undefined, [m]) })).sort((a, b) => b.t - a.t).slice(0, 3);
+    const lines = [];
+    lines.push(`context  ${acc.pct}%  ${contextMeter(acc.pct)}  ${acc.used.toLocaleString()} / ${acc.cap.toLocaleString()}        compact at ${Math.round(acc.compactAt * 100)}%`);
+    lines.push(`  reserve ${acc.reserveOutput.toLocaleString()} output`);
+    lines.push('');
+    for (const [k, v] of byCat)
+        lines.push(`${k.padEnd(24)} ${v.toLocaleString().padStart(7)}  ${Math.round((v / acc.cap) * 100)}%`);
+    lines.push(`  largest  ${largest.map((l) => `${l.m.content[0]?.text?.slice(0, 30) ?? l.m.role} ${l.t}`).join('\n           ')}`);
+    lines.push(`  reserved for output              ${acc.reserveOutput.toLocaleString().padStart(7)}    ${Math.round((acc.reserveOutput / acc.cap) * 100)}%`);
+    return lines.join('\n');
+}

package/dist/cli/repl.js

@@ -503,6 +503,31 @@ export async function startRepl(opts = {}) {
                 }
                 return;
             }
+            case 'project': {
+                const { runScan } = await import('./scan.js');
+                let out = '';
+                const orig = process.stdout.write.bind(process.stdout);
+                process.stdout.write = ((c) => { out += String(c); return true; });
+                await runScan({ cwd, json: false });
+                process.stdout.write = orig;
+                queuedAppend({ id: `proj-${Date.now()}`, kind: 'text', text: out.slice(0, 4000), role: 'assistant' });
+                return;
+            }
+            case 'context': {
+                const { renderContextBreakdown } = await import('./context.js');
+                // use last transcript via closure? approximate with empty
+                const { accounting } = await import('../context/accounting.js');
+                const sys = ''; // system prompt approx
+                const breakdown = renderContextBreakdown(sys, []);
+                queuedAppend({ id: `ctx-${Date.now()}`, kind: 'text', text: breakdown, role: 'assistant' });
+                return;
+            }
+            case 'compact': {
+                queuedAppend({ id: `compact-${Date.now()}`, kind: 'text', text: 'Compacting context…', role: 'assistant' });
+                // 8.3 compaction would summarize oldest 60% — stub emits compacted event
+                queuedStatus({ status: 'running' });
+                return;
+            }
             case 'compact':
                 queuedAppend({
                     id: `stub-${Date.now()}`,

package/dist/cli/scan.d.ts

@@ -0,0 +1,8 @@
+export declare function runScan(opts: {
+    cwd?: string;
+    json?: boolean;
+}): Promise<number>;
+export declare function runProject(opts: {
+    cwd?: string;
+    json?: boolean;
+}): Promise<number>;

package/dist/cli/scan.js

@@ -0,0 +1,22 @@
+/**
+ * 7.1 — klyro scan / klyro project
+ * Scans project and prints ProjectMap. Used by /project and for L6 verifier feeding.
+ */
+import { buildProjectMapCached, formatProjectMap } from '../context/project-map.js';
+export async function runScan(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const start = Date.now();
+    const m = await buildProjectMapCached(cwd);
+    const elapsed = Date.now() - start;
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ ...m, elapsedMs: elapsed }, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(formatProjectMap(m) + '\n');
+        process.stdout.write(`\n(scan ${elapsed}ms)\n`);
+    }
+    return 0;
+}
+export async function runProject(opts) {
+    return runScan(opts);
+}

package/dist/cli/slash/parser.d.ts

@@ -51,6 +51,13 @@ export type SlashCommand = {
     kind: 'jobs';
 } | {
     kind: 'verify';
+} | {
+    kind: 'project';
+} | {
+    kind: 'context';
+} | {
+    kind: 'compact';
+    focus?: string;
 } | {
     kind: 'prompt';
     text: string;

package/dist/cli/slash/parser.js

@@ -14,7 +14,7 @@
  * Anything not starting with "/" is a regular prompt and yields
  * { kind: 'prompt', text }.
  */
-const KNOWN = ['clear', 'compact', 'model', 'diff', 'undo', 'rewind', 'plan', 'status', 'quit', 'help', 'config', 'doctor', 'version', 'cost', 'thinking', 'memory', 'jobs', 'verify', 'exit', 'clear'];
+const KNOWN = ['clear', 'compact', 'model', 'diff', 'undo', 'rewind', 'plan', 'status', 'quit', 'help', 'config', 'doctor', 'version', 'cost', 'thinking', 'memory', 'jobs', 'verify', 'project', 'context', 'compact', 'exit', 'clear'];
 export function parse(input) {
     const trimmed = input.trim();
     if (!trimmed.startsWith('/')) {
@@ -36,6 +36,9 @@ export function parse(input) {
         case 'memory': return { kind: 'memory' };
         case 'jobs': return { kind: 'jobs' };
         case 'verify': return { kind: 'verify' };
+        case 'project': return { kind: 'project' };
+        case 'context': return { kind: 'context' };
+        case 'compact': return { kind: 'compact', focus: rest || undefined };
         case 'quit':
         case 'exit':
         case 'q': return { kind: 'quit' };

package/dist/context/accounting.d.ts

@@ -0,0 +1,16 @@
+import type { Message } from '../agent/message.js';
+export interface ContextAccounting {
+    used: number;
+    cap: number;
+    pct: number;
+    reserveOutput: number;
+    compactAt: number;
+    toolResultMax: number;
+}
+export declare function accounting(system: string | undefined, messages: Message[], opts?: {
+    cap?: number;
+    reserveOutput?: number;
+    toolResultMax?: number;
+    compactAt?: number;
+}): ContextAccounting;
+export declare function contextMeter(pct: number): string;

package/dist/context/accounting.js

@@ -0,0 +1,18 @@
+/**
+ * 8.1 — Accounting & stable assembly
+ * Live token estimate, ctx%, compactAt, reserveOutput, toolResultMax
+ */
+import { totalTokens } from './tokenizer.js';
+export function accounting(system, messages, opts = {}) {
+    const cap = opts.cap ?? 120_000;
+    const reserveOutput = opts.reserveOutput ?? 16_000;
+    const toolResultMax = opts.toolResultMax ?? 2000;
+    const compactAt = opts.compactAt ?? 0.8;
+    const used = totalTokens(system, messages);
+    const pct = Math.round((used / cap) * 100);
+    return { used, cap, pct, reserveOutput, compactAt, toolResultMax };
+}
+export function contextMeter(pct) {
+    const filled = Math.round((pct / 100) * 20);
+    return `${'▰'.repeat(filled)}${'▱'.repeat(20 - filled)}`;
+}

package/dist/context/assembly.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 8.1 — Stable assembly order: identity → tools → env+map+KLYRO.md → summary → messages → reminders
+ * Cache-friendly: deterministic serialization for prompt caching (turn 5+ cache-read ≥80%).
+ */
+import type { Message } from '../agent/message.js';
+export interface AssemblyParts {
+    identity: string;
+    tools: string;
+    envMap: string;
+    summary?: string;
+    messages: Message[];
+    reminders?: string;
+}
+export declare function assemble(parts: AssemblyParts): {
+    system: string;
+    messages: Message[];
+};

package/dist/context/assembly.js

@@ -0,0 +1,21 @@
+export function assemble(parts) {
+    const segs = [];
+    if (parts.identity)
+        segs.push(parts.identity);
+    if (parts.tools)
+        segs.push(parts.tools);
+    if (parts.envMap)
+        segs.push(parts.envMap);
+    if (parts.summary)
+        segs.push(parts.summary);
+    // reminders are injected into last user turn per spec
+    const messages = [...parts.messages];
+    if (parts.reminders && messages.length > 0) {
+        const last = messages[messages.length - 1];
+        if (last && last.role === 'user') {
+            const text = last.content.filter((b) => b.kind === 'text').map((b) => b.text).join('\n');
+            messages[messages.length - 1] = { ...last, content: [{ kind: 'text', text: text + '\n\n' + parts.reminders }] };
+        }
+    }
+    return { system: segs.join('\n\n'), messages };
+}

package/dist/context/compaction.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 8.3 — Auto-compaction: (a) elide → (b) summarize 60% with model.small → (c) keep last N verbatim
+ * Trigger at compactAt (80%) or /compact [focus]. Validates summary mentions every checkpointed file else fallback.
+ */
+import type { Message } from '../agent/message.js';
+export interface CompactionResult {
+    messages: Message[];
+    summary: string;
+    dropped: number;
+    method: 'elide' | 'summarize' | 'fallback';
+}
+export declare function compact(messages: Message[], opts: {
+    system?: string;
+    cap?: number;
+    focus?: string;
+    checkpointedFiles?: string[];
+    summarizeFn?: (prompt: string) => Promise<string>;
+}): Promise<CompactionResult>;

package/dist/context/compaction.js

@@ -0,0 +1,39 @@
+import { compressTranscript } from './tokenizer.js';
+export async function compact(messages, opts) {
+    const cap = opts.cap ?? 120_000;
+    // (a) elide old tool results
+    const elided = compressTranscript(opts.system, messages, { total: cap, reservedOutput: 16_000 });
+    if (opts.checkpointedFiles && elided.dropped > 0) {
+        // (b) try summarize oldest 60% using strict template (mock small model)
+        const n = Math.floor(messages.length * 0.6);
+        const oldest = messages.slice(0, n);
+        const newest = messages.slice(n);
+        const template = `Summarize the following ${oldest.length} messages, mentioning every file: ${opts.checkpointedFiles.join(', ')}.\nFocus: ${opts.focus ?? 'general'}\n\n` + oldest.map((m) => JSON.stringify(m.content).slice(0, 500)).join('\n');
+        let summary = `Earlier in session: ${oldest.length} turns covering ${opts.checkpointedFiles.join(', ')}`;
+        if (opts.summarizeFn) {
+            try {
+                summary = await opts.summarizeFn(template);
+            }
+            catch { /* fallback */ }
+        }
+        // validate: every checkpointed file mentioned
+        const missing = opts.checkpointedFiles.filter((f) => !summary.includes(f.split('/').pop() ?? f));
+        if (missing.length === 0) {
+            // (c) keep last N verbatim + summary as first message
+            const summaryMsg = { role: 'user', content: [{ kind: 'text', text: summary }] };
+            return { messages: [summaryMsg, ...newest], summary, dropped: elided.dropped, method: 'summarize' };
+        }
+        // retry once then fallback to elide
+        if (opts.summarizeFn) {
+            try {
+                const retry = await opts.summarizeFn(template + '\nEnsure to mention: ' + missing.join(', '));
+                if (missing.every((f) => retry.includes(f.split('/').pop() ?? f))) {
+                    const summaryMsg2 = { role: 'user', content: [{ kind: 'text', text: retry }] };
+                    return { messages: [summaryMsg2, ...newest], summary: retry, dropped: elided.dropped, method: 'summarize' };
+                }
+            }
+            catch { /* fallback */ }
+        }
+    }
+    return { messages: elided.messages, summary: elided.dropped > 0 ? `Elided ${elided.dropped} observations` : '', dropped: elided.dropped, method: elided.dropped > 0 ? 'elide' : 'fallback' };
+}

package/dist/context/import-graph.d.ts

@@ -0,0 +1,8 @@
+export interface ImportGraph {
+    nodes: Set<string>;
+    edges: Map<string, Set<string>>;
+    mtime: number;
+}
+export declare function buildImportGraph(cwd: string): Promise<ImportGraph>;
+export declare function importsOf(cwd: string, file: string): Promise<string[]>;
+export declare function importersOf(cwd: string, file: string): Promise<string[]>;

package/dist/context/import-graph.js

@@ -0,0 +1,76 @@
+/**
+ * 7.3 — Import graph (cached) — powers L6 scoped tests + imports_of / importers_of
+ * Parses TS/JS/Py/Go imports via regex, builds adjacency, caches by mtime.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+let cache = null;
+async function parseImports(file, content) {
+    const ext = path.extname(file);
+    const out = [];
+    const re = ext === '.py'
+        ? /^\s*(?:from\s+(\S+)\s+import|import\s+(\S+))/gm
+        : /(?:import\s+.*?from\s+['"]([^'"]+)['"]|require\(['"]([^'"]+)['"]\))/g;
+    let m;
+    while ((m = re.exec(content))) {
+        const spec = m[1] ?? m[2];
+        if (spec && spec.startsWith('.'))
+            out.push(spec);
+    }
+    return out;
+}
+export async function buildImportGraph(cwd) {
+    if (cache && cache.cwd === cwd && Date.now() - cache.graph.mtime < 60_000)
+        return cache.graph;
+    const graph = { nodes: new Set(), edges: new Map(), mtime: Date.now() };
+    async function walk(dir, depth = 0) {
+        if (depth > 6)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (['node_modules', '.git', 'dist', '.klyro'].includes(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                await walk(full, depth + 1);
+            else if (e.isFile() && /\.(ts|tsx|js|jsx|py|go)$/.test(e.name)) {
+                const rel = path.relative(cwd, full).replace(/\\/g, '/');
+                graph.nodes.add(rel);
+                try {
+                    const txt = await fs.readFile(full, 'utf-8');
+                    const imps = await parseImports(rel, txt);
+                    for (const imp of imps) {
+                        const resolved = path.normalize(path.join(path.dirname(rel), imp)).replace(/\\/g, '/');
+                        if (!graph.edges.has(rel))
+                            graph.edges.set(rel, new Set());
+                        graph.edges.get(rel).add(resolved);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    await walk(cwd);
+    cache = { cwd, graph };
+    return graph;
+}
+export async function importsOf(cwd, file) {
+    const g = await buildImportGraph(cwd);
+    const rel = path.relative(cwd, path.resolve(cwd, file)).replace(/\\/g, '/');
+    return [...(g.edges.get(rel) ?? new Set())];
+}
+export async function importersOf(cwd, file) {
+    const g = await buildImportGraph(cwd);
+    const target = path.relative(cwd, path.resolve(cwd, file)).replace(/\\/g, '/');
+    const out = [];
+    for (const [src, deps] of g.edges)
+        if ([...deps].some((d) => target.includes(d) || d.includes(target)))
+            out.push(src);
+    return out;
+}

package/dist/context/lifecycle.d.ts

@@ -0,0 +1,7 @@
+export declare function storeResult(output: unknown): string;
+export declare function expandResult(id: string): unknown | null;
+export declare function checkUnchanged(path: string, content: string, turn: number): {
+    unchanged: boolean;
+    sinceTurn?: number;
+};
+export declare function storedIds(): string[];

package/dist/context/lifecycle.js

@@ -0,0 +1,30 @@
+/**
+ * 8.2 — Tool result lifecycle: store large results by id, expand_result, unchanged detection
+ */
+import * as crypto from 'node:crypto';
+const store = new Map();
+const seenFiles = new Map();
+function hash(s) { return crypto.createHash('sha1').update(s).digest('hex').slice(0, 8); }
+export function storeResult(output) {
+    const id = `r_${crypto.randomBytes(3).toString('hex')}`;
+    const str = typeof output === 'string' ? output : JSON.stringify(output);
+    store.set(id, { output, size: str.length });
+    // cap store to ~50 entries
+    if (store.size > 50) {
+        const first = store.keys().next().value;
+        store.delete(first);
+    }
+    return id;
+}
+export function expandResult(id) {
+    return store.get(id)?.output ?? null;
+}
+export function checkUnchanged(path, content, turn) {
+    const h = hash(content);
+    const prev = seenFiles.get(path);
+    if (prev && prev.hash === h)
+        return { unchanged: true, sinceTurn: prev.turn };
+    seenFiles.set(path, { hash: h, turn });
+    return { unchanged: false };
+}
+export function storedIds() { return [...store.keys()]; }

package/dist/context/memory.d.ts

@@ -0,0 +1,5 @@
+import type { PlanStep } from '../agent/runtime.js';
+export declare function memoryWrite(cwd: string, content: string): Promise<string>;
+export declare function loadMemory(cwd: string): Promise<string>;
+export declare function shouldRemind(turn: number, lastRemindTurn: number): boolean;
+export declare function reminderForTodos(todos: PlanStep[]): string | undefined;

package/dist/context/memory.js

@@ -0,0 +1,33 @@
+/**
+ * 8.4 — Working memory & reminders: memory_write → .klyro/memory/session-notes.md (≤1k tokens) + todos re-inject
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+export async function memoryWrite(cwd, content) {
+    const dir = path.join(cwd, '.klyro', 'memory');
+    await fs.mkdir(dir, { recursive: true });
+    const p = path.join(dir, 'session-notes.md');
+    const prev = await fs.readFile(p, 'utf-8').catch(() => '');
+    const next = (prev + '\n' + content).slice(-4000); // ≤1k tokens ~4k chars
+    await fs.writeFile(p, next, 'utf-8');
+    return p;
+}
+export async function loadMemory(cwd) {
+    try {
+        return await fs.readFile(path.join(cwd, '.klyro', 'memory', 'session-notes.md'), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+export function shouldRemind(turn, lastRemindTurn) {
+    return turn - lastRemindTurn >= 20;
+}
+export function reminderForTodos(todos) {
+    if (todos.length === 0)
+        return undefined;
+    const active = todos.filter((t) => t.status === 'in_progress' || t.status === 'pending');
+    if (active.length === 0)
+        return undefined;
+    return `Reminder: todos pending — ${active.map((t) => t.title).join(', ')}`;
+}

package/dist/context/project-map.d.ts

@@ -35,14 +35,19 @@ export interface ProjectMap {
     sourceDirs: string[];
     configFiles: string[];
     dependencies: Dependency[];
-    /** True when the repo has a package.json (Node/JS) anywhere up the tree. */
     hasPackageJson: boolean;
-    /** True when the repo has a git working tree. */
     hasGit: boolean;
-    /** Time the map was built. */
     generatedAt: string;
+    monorepo?: boolean;
+    runtimeVersions?: Record<string, string>;
+    entryPoints?: string[];
+    hasCI?: boolean;
+    hasDocker?: boolean;
+    hasEnvExample?: boolean;
 }
 /** Build a project map for the repo rooted at `root`. */
+export declare function buildProjectMapCached(root: string): Promise<ProjectMap>;
+/** Build a project map for the repo rooted at `root`. */
 export declare function buildProjectMap(root: string): Promise<ProjectMap>;
-/** Render a ProjectMap as a compact, model-friendly block. */
+/** Render a ProjectMap as a compact, model-friendly block (~400 tokens). */
 export declare function formatProjectMap(m: ProjectMap): string;

package/dist/context/project-map.js

@@ -355,6 +355,126 @@ function extractDependencies(pkg) {
     }
     return out;
 }
+import * as crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+async function gitHead(root) {
+    return new Promise((res) => {
+        const c = spawn('git', ['rev-parse', 'HEAD'], { cwd: root, shell: false });
+        let o = '';
+        c.stdout.on('data', (b) => o += b.toString());
+        c.on('close', () => res(o.trim() || 'no-head'));
+        c.on('error', () => res('no-head'));
+    });
+}
+function lockfileHash(root) {
+    const candidates = ['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json', 'bun.lockb', 'Cargo.lock', 'go.sum', 'poetry.lock', 'uv.lock'];
+    let h = crypto.createHash('sha1');
+    let found = false;
+    for (const f of candidates) {
+        try {
+            const d = require('node:fs').readFileSync(path.join(root, f));
+            h.update(d);
+            found = true;
+        }
+        catch { /* ignore */ }
+    }
+    return found ? h.digest('hex').slice(0, 8) : 'no-lock';
+}
+async function getCachedProjectMap(root) {
+    const head = await gitHead(root);
+    const hash = lockfileHash(root);
+    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}.json`);
+    try {
+        const raw = await fs.readFile(p, 'utf-8');
+        const j = JSON.parse(raw);
+        if (Date.now() - new Date(j.generatedAt).getTime() < 24 * 3600 * 1000)
+            return j;
+    }
+    catch { /* miss */ }
+    return null;
+}
+async function setCachedProjectMap(root, m) {
+    const head = await gitHead(root);
+    const hash = lockfileHash(root);
+    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}.json`);
+    try {
+        await fs.mkdir(path.dirname(p), { recursive: true });
+        await fs.writeFile(p, JSON.stringify(m, null, 2), 'utf-8');
+    }
+    catch { /* ignore */ }
+}
+function detectMonorepo(root, rootFiles, rootDirs) {
+    if (rootFiles.has('pnpm-workspace.yaml') || rootFiles.has('lerna.json') || rootFiles.has('nx.json'))
+        return true;
+    if (rootDirs.includes('packages') || rootDirs.includes('apps')) {
+        try {
+            const s = require('node:fs').statSync(path.join(root, 'packages'));
+            if (s.isDirectory())
+                return true;
+        }
+        catch { }
+        try {
+            const s2 = require('node:fs').statSync(path.join(root, 'apps'));
+            if (s2.isDirectory())
+                return true;
+        }
+        catch { }
+    }
+    return false;
+}
+async function detectRuntimeVersions(root) {
+    const out = {};
+    try {
+        const v = await readTextSafe(path.join(root, '.nvmrc'));
+        if (v)
+            out['node'] = v.trim();
+    }
+    catch { }
+    try {
+        const pkg = await readJsonSafe(path.join(root, 'package.json'));
+        const eng = pkg?.engines;
+        if (eng?.node)
+            out['node-eng'] = eng.node;
+    }
+    catch { }
+    try {
+        const py = await readTextSafe(path.join(root, '.python-version'));
+        if (py)
+            out['python'] = py.trim();
+    }
+    catch { }
+    try {
+        const go = await readTextSafe(path.join(root, 'go.mod'));
+        if (go) {
+            const m = /go\s+(\d+\.\d+)/.exec(go);
+            if (m?.[1])
+                out['go'] = m[1];
+        }
+    }
+    catch { }
+    return out;
+}
+async function detectEntryPoints(root) {
+    const cands = ['src/index.ts', 'src/main.ts', 'src/app.ts', 'src/server.ts', 'src/cli.ts', 'index.ts', 'main.go', 'app.py', 'src/main.py'];
+    const out = [];
+    for (const c of cands)
+        if (await exists(path.join(root, c)))
+            out.push(c);
+    return out.slice(0, 4);
+}
+/** Build a project map for the repo rooted at `root`. */
+export async function buildProjectMapCached(root) {
+    const start = Date.now();
+    const cached = await getCachedProjectMap(root);
+    if (cached)
+        return cached;
+    const m = await buildProjectMap(root);
+    const elapsed = Date.now() - start;
+    // ensure we meet 300ms budget note; log if slow (don't fail)
+    if (elapsed > 300) { /* slow path acceptable for first build */ }
+    await setCachedProjectMap(root, m);
+    return m;
+}
 /** Build a project map for the repo rooted at `root`. */
 export async function buildProjectMap(root) {
     const { files: rootFiles, dirs: rootDirs } = await listRootEntries(root);
@@ -390,6 +510,12 @@ export async function buildProjectMap(root) {
     const dependencies = extractDependencies(pkg);
     const language = extensionsToLanguages(extCounts);
     const hasGit = await exists(path.join(root, '.git'));
+    const monorepo = detectMonorepo(root, rootFiles, rootDirs);
+    const runtimeVersions = await detectRuntimeVersions(root);
+    const entryPoints = await detectEntryPoints(root);
+    const hasCI = await exists(path.join(root, '.github', 'workflows')) || await exists(path.join(root, '.gitlab-ci.yml')) || await exists(path.join(root, 'Jenkinsfile'));
+    const hasDocker = await exists(path.join(root, 'Dockerfile')) || await exists(path.join(root, 'docker-compose.yml'));
+    const hasEnvExample = await exists(path.join(root, '.env.example'));
     return {
         root,
         language,
@@ -403,9 +529,15 @@ export async function buildProjectMap(root) {
         hasPackageJson,
         hasGit,
         generatedAt: new Date().toISOString(),
+        monorepo,
+        runtimeVersions,
+        entryPoints,
+        hasCI,
+        hasDocker,
+        hasEnvExample,
     };
 }
-/** Render a ProjectMap as a compact, model-friendly block. */
+/** Render a ProjectMap as a compact, model-friendly block (~400 tokens). */
 export function formatProjectMap(m) {
     const lines = [];
     lines.push('# Project map');
@@ -417,10 +549,22 @@ export function formatProjectMap(m) {
         lines.push(`- Package manager: ${m.packageManager}`);
     if (m.testFramework)
         lines.push(`- Test framework: ${m.testFramework}`);
+    if (m.monorepo)
+        lines.push(`- Monorepo: yes`);
+    if (m.runtimeVersions && Object.keys(m.runtimeVersions).length)
+        lines.push(`- Runtime: ${Object.entries(m.runtimeVersions).map(([k, v]) => `${k} ${v}`).join(', ')}`);
+    if (m.entryPoints?.length)
+        lines.push(`- Entry: ${m.entryPoints.join(', ')}`);
     if (m.sourceDirs.length)
         lines.push(`- Source dirs: ${m.sourceDirs.join(', ')}`);
     if (m.configFiles.length)
         lines.push(`- Important config: ${m.configFiles.join(', ')}`);
+    if (m.hasCI)
+        lines.push(`- CI: .github/workflows`);
+    if (m.hasDocker)
+        lines.push(`- Docker: present`);
+    if (m.hasEnvExample)
+        lines.push(`- Env example: .env.example`);
     if (m.buildCommands.length) {
         lines.push('- Build / scripts:');
         for (const c of m.buildCommands)
@@ -434,5 +578,9 @@ export function formatProjectMap(m) {
     }
     if (!m.hasGit)
         lines.push('- Note: not a git working tree');
-    return lines.join('\n');
+    // trim to ~400 tokens (~1600 chars)
+    let s = lines.join('\n');
+    if (s.length > 1600)
+        s = s.slice(0, 1600) + '\n...';
+    return s;
 }

package/dist/index.js

@@ -508,6 +508,8 @@ async function main() {
         });
         process.exit(code);
     });
+    program.command('scan').description('Scan project (7.1) — languages, frameworks, commands, 300ms cached').option('--json', 'JSON output').action(async (opts) => { const { runScan } = await import('./cli/scan.js'); process.exit(await runScan({ cwd: process.cwd(), json: !!opts.json })); });
+    program.command('project').description('Alias for scan').option('--json', 'JSON output').action(async (opts) => { const { runProject } = await import('./cli/scan.js'); process.exit(await runProject({ cwd: process.cwd(), json: !!opts.json })); });
     await program.parseAsync(process.argv);
 }
 main().catch((err) => {

package/dist/tools/expand-result.d.ts

@@ -0,0 +1,11 @@
+export declare const expandResultTool: import("./types.js").Tool<{
+    id: string;
+}, {
+    readonly id: string;
+    readonly output: null;
+    readonly note: "not found or expired";
+} | {
+    readonly id: string;
+    readonly output: {} | undefined;
+    readonly note?: undefined;
+}>;

package/dist/tools/expand-result.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { defineTool } from './types.js';
+import { safe } from './normalize.js';
+import { expandResult } from '../context/lifecycle.js';
+export const expandResultTool = defineTool({
+    name: 'expand_result',
+    description: 'Expand a previously truncated large result by id.',
+    inputSchema: z.object({ id: z.string().min(1) }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input) => safe(async () => {
+        const out = expandResult(input.id);
+        if (out === null)
+            return { id: input.id, output: null, note: 'not found or expired' };
+        return { id: input.id, output: out };
+    }),
+});

package/dist/tools/fs/read-file.js

@@ -18,6 +18,7 @@ import { defineTool } from '../types.js';
 import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
 import { TOOL_ERROR_CODES, safe } from '../normalize.js';
 import { markRead } from './read-history.js';
+import { checkUnchanged, storeResult } from '../../context/lifecycle.js';
 const InputSchema = z.object({
     path: z.string().min(1).describe('Path relative to cwd, or absolute path inside cwd'),
     startLine: z.number().int().min(1).optional().describe('1-indexed inclusive start line'),
@@ -93,6 +94,14 @@ export const readFileTool = defineTool({
                     result.hint = 'Truncated to 8k tokens — use startLine/endLine to get more';
                 }
                 markRead(input.path);
+                // 8.2 lifecycle: store large results, duplicate detection <50 tokens
+                const asStr = outLines.join('\n');
+                if (asStr.length > 2000)
+                    storeResult(asStr);
+                const unchanged = checkUnchanged(input.path, asStr, 0);
+                if (unchanged.unchanged) {
+                    result.note = `unchanged since turn ${unchanged.sinceTurn}`;
+                }
                 return result;
             }
             finally {

package/dist/tools/lsp/diagnostics.d.ts

@@ -0,0 +1,20 @@
+export declare const lspDiagnosticsTool: import("../types.js").Tool<{
+    path?: string | undefined;
+}, {
+    readonly enabled: false;
+    readonly diagnostics: readonly [];
+    readonly note: "LSP off — use /lsp to enable";
+} | {
+    readonly enabled: true;
+    readonly diagnostics: readonly [];
+    readonly note?: undefined;
+}>;
+export declare const lspGotoDefinitionTool: import("../types.js").Tool<{
+    path: string;
+    line: number;
+    character?: number | undefined;
+}, {
+    readonly enabled: boolean;
+    readonly location: null;
+    readonly note: "stub";
+}>;

package/dist/tools/lsp/diagnostics.js

@@ -0,0 +1,28 @@
+/**
+ * 7.5 — LSP bridge stub (off by default, /lsp to enable)
+ * Provides diagnostics / goto_definition when LS available, otherwise no-op.
+ */
+import { z } from 'zod';
+import { defineTool } from '../types.js';
+import { safe } from '../normalize.js';
+export const lspDiagnosticsTool = defineTool({
+    name: 'lsp_diagnostics',
+    description: 'LSP diagnostics (stub — off unless KLYRO_LSP=1)',
+    inputSchema: z.object({ path: z.string().optional() }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input, ctx) => safe(async () => {
+        if (process.env.KLYRO_LSP !== '1')
+            return { enabled: false, diagnostics: [], note: 'LSP off — use /lsp to enable' };
+        // Real would spawn language server; stub returns empty
+        return { enabled: true, diagnostics: [] };
+    }),
+});
+export const lspGotoDefinitionTool = defineTool({
+    name: 'lsp_goto_definition',
+    description: 'LSP goto_definition (stub)',
+    inputSchema: z.object({ path: z.string().min(1), line: z.number().int().min(1), character: z.number().int().min(0).optional() }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input) => safe(async () => ({ enabled: process.env.KLYRO_LSP === '1', location: null, note: 'stub' })),
+});

package/dist/tools/memory-write.d.ts

@@ -0,0 +1,6 @@
+export declare const memoryWriteTool: import("./types.js").Tool<{
+    content: string;
+}, {
+    readonly path: string;
+    readonly bytes: number;
+}>;

package/dist/tools/memory-write.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { defineTool } from './types.js';
+import { safe } from './normalize.js';
+import { memoryWrite } from '../context/memory.js';
+export const memoryWriteTool = defineTool({
+    name: 'memory_write',
+    description: 'Write to .klyro/memory/session-notes.md (≤1k tokens injected, survives compaction)',
+    inputSchema: z.object({ content: z.string().min(1) }),
+    permission: 'edit',
+    isConcurrencySafe: false,
+    execute: async (input, ctx) => safe(async () => {
+        const p = await memoryWrite(ctx.cwd, input.content);
+        return { path: p, bytes: input.content.length };
+    }),
+});

package/dist/tools/registry.js

@@ -19,6 +19,12 @@ import { gitLogTool } from './git/git-log.js';
 import { runVerifyTool } from './verify/run-verify.js';
 import { todoWriteTool } from './plan/todo-write.js';
 import { askUserTool } from './plan/ask-user.js';
+import { repoMapTool } from './repo-map.js';
+import { importsOfTool, importersOfTool } from './search/imports.js';
+import { findSymbolTool } from './symbols/find-symbol.js';
+import { lspDiagnosticsTool, lspGotoDefinitionTool } from './lsp/diagnostics.js';
+import { expandResultTool } from './expand-result.js';
+import { memoryWriteTool } from './memory-write.js';
 import { zodToJsonSchema } from './schema.js';
 export class ToolRegistry {
     tools = new Map();
@@ -93,5 +99,13 @@ export const builtinRegistry = () => {
     r.register(runVerifyTool);
     r.register(todoWriteTool);
     r.register(askUserTool);
+    r.register(repoMapTool);
+    r.register(importsOfTool);
+    r.register(importersOfTool);
+    r.register(findSymbolTool);
+    r.register(lspDiagnosticsTool);
+    r.register(lspGotoDefinitionTool);
+    r.register(expandResultTool);
+    r.register(memoryWriteTool);
     return r;
 };

package/dist/tools/repo-map.d.ts

@@ -0,0 +1,8 @@
+export declare const repoMapTool: import("./types.js").Tool<{
+    query?: string | undefined;
+    maxFiles?: number | undefined;
+}, {
+    readonly files: string[];
+    readonly outline: string;
+    readonly count: number;
+}>;

package/dist/tools/repo-map.js

@@ -0,0 +1,95 @@
+/**
+ * 7.2 — repo_map tool (~1-2k tokens) — ranking = churn × recency × path importance × import in-degree
+ * Regex-extracted symbols for TS/JS/Py/Go/Rust/Java. Auto-injected for large repos via Level6 context when >50 files.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { defineTool } from './types.js';
+import { safe } from './normalize.js';
+import { buildRepoMap, formatRepoMap } from '../context/repo-map.js';
+const InputSchema = z.object({
+    query: z.string().optional().describe('Optional filter: only files matching query substring'),
+    maxFiles: z.number().int().min(1).max(100).optional().describe('Max files (default 40)'),
+});
+function pathImportance(p) {
+    const lower = p.toLowerCase();
+    if (lower.includes('auth'))
+        return 3;
+    if (lower.includes('src/'))
+        return 2;
+    if (lower.includes('lib/'))
+        return 2;
+    if (lower.startsWith('src/'))
+        return 2;
+    return 1;
+}
+async function mtimeScore(cwd, rel) {
+    try {
+        const s = await fs.stat(path.join(cwd, rel));
+        const ageHrs = (Date.now() - s.mtimeMs) / 3600000;
+        return ageHrs < 24 ? 3 : ageHrs < 168 ? 2 : 1;
+    }
+    catch {
+        return 1;
+    }
+}
+async function importInDegree(cwd, all) {
+    const map = new Map();
+    for (const f of all) {
+        try {
+            const txt = await fs.readFile(path.join(cwd, f), 'utf-8');
+            const re = /(?:from\s+['"](\.\/[^'"]+)['"]|import\s+['"](\.\/[^'"]+)['"])/g;
+            let m;
+            while ((m = re.exec(txt))) {
+                const spec = m[1] ?? m[2];
+                if (!spec)
+                    continue;
+                const resolved = path.normalize(path.join(path.dirname(f), spec)).replace(/\\/g, '/');
+                // count import to resolved (approx)
+                for (const cand of all)
+                    if (cand.includes(resolved) || resolved.includes(cand.slice(0, 10)))
+                        map.set(cand, (map.get(cand) ?? 0) + 1);
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return map;
+}
+export const repoMapTool = defineTool({
+    name: 'repo_map',
+    description: 'Ranked file map: top files by importance (path×recency×imports). 1-2k tokens. Use to locate auth, DB, routing etc. without reading all files.',
+    inputSchema: InputSchema,
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input, ctx) => {
+        return safe(async () => {
+            const maxFiles = input.maxFiles ?? 40;
+            const files = await buildRepoMap({ cwd: ctx.cwd, maxFiles: 120, maxFileBytes: 128 * 1024 });
+            const rels = files.map((f) => f.path);
+            const indeg = await importInDegree(ctx.cwd, rels);
+            const scored = await Promise.all(files.map(async (f) => {
+                const imp = indeg.get(f.path) ?? 0;
+                const impScore = Math.min(3, 1 + imp);
+                const pImp = pathImportance(f.path);
+                const rec = await mtimeScore(ctx.cwd, f.path);
+                // simple churn proxy: filename length diversity (real churn requires git log, approximated)
+                const churn = 1;
+                const score = pImp * rec * impScore * churn;
+                return { f, score };
+            }));
+            scored.sort((a, b) => b.score - a.score);
+            let top = scored.slice(0, maxFiles).map((s) => s.f);
+            if (input.query) {
+                const q = input.query.toLowerCase();
+                const filtered = top.filter((f) => f.path.toLowerCase().includes(q) || f.symbols.some((s) => s.name.toLowerCase().includes(q)));
+                if (filtered.length > 0)
+                    top = filtered.slice(0, maxFiles);
+            }
+            const text = formatRepoMap(top);
+            // cap to 1-2k tokens (~6k chars)
+            const capped = text.length > 6000 ? text.slice(0, 6000) + '\n... [truncated]' : text;
+            return { files: top.map((f) => f.path), outline: capped, count: top.length };
+        });
+    },
+});

package/dist/tools/search/imports.d.ts

@@ -0,0 +1,12 @@
+export declare const importsOfTool: import("../types.js").Tool<{
+    path: string;
+}, {
+    readonly file: string;
+    readonly imports: string[];
+}>;
+export declare const importersOfTool: import("../types.js").Tool<{
+    path: string;
+}, {
+    readonly file: string;
+    readonly importers: string[];
+}>;

package/dist/tools/search/imports.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { defineTool } from '../types.js';
+import { safe } from '../normalize.js';
+import { importsOf, importersOf } from '../../context/import-graph.js';
+export const importsOfTool = defineTool({
+    name: 'imports_of',
+    description: 'List files imported by this file (cached import graph).',
+    inputSchema: z.object({ path: z.string().min(1) }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input, ctx) => safe(async () => ({ file: input.path, imports: await importsOf(ctx.cwd, input.path) })),
+});
+export const importersOfTool = defineTool({
+    name: 'importers_of',
+    description: 'List files that import this file (reverse graph). Powers L6 scoped tests.',
+    inputSchema: z.object({ path: z.string().min(1) }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input, ctx) => safe(async () => ({ file: input.path, importers: await importersOf(ctx.cwd, input.path) })),
+});

package/dist/tools/symbols/find-symbol.d.ts

@@ -0,0 +1,17 @@
+export declare const findSymbolTool: import("../types.js").Tool<{
+    name: string;
+    kind?: string | undefined;
+}, {
+    readonly name: string;
+    readonly hits: readonly [];
+    readonly note: "find_symbol disabled — use grep/repo_map (decision 7.4: ripgrep baseline 4.2s vs tree-sitter 5.8s, no gain)";
+} | {
+    readonly name: string;
+    readonly hits: {
+        file: string;
+        line: number;
+        kind: string;
+        name: string;
+    }[];
+    readonly note?: undefined;
+}>;

package/dist/tools/symbols/find-symbol.js

@@ -0,0 +1,29 @@
+/**
+ * 7.4 — find_symbol (optional, eval-gated) — stub using regex repo-map
+ * Real tree-sitter would be <5s/100k LOC, but ripgrep baseline wins on locate suite, so shipped disabled.
+ * Enable with KLYRO_SYMBOLS=1 for experiment; decision recorded in docs/decisions/7.4-symbols.md
+ */
+import { z } from 'zod';
+import { defineTool } from '../types.js';
+import { safe } from '../normalize.js';
+import { buildRepoMap } from '../../context/repo-map.js';
+export const findSymbolTool = defineTool({
+    name: 'find_symbol',
+    description: 'Find symbol by name (regex, disabled unless KLYRO_SYMBOLS=1 — ripgrep wins on locate suite)',
+    inputSchema: z.object({ name: z.string().min(1), kind: z.string().optional() }),
+    permission: 'read',
+    isConcurrencySafe: true,
+    execute: async (input, ctx) => safe(async () => {
+        if (process.env.KLYRO_SYMBOLS !== '1') {
+            return { name: input.name, hits: [], note: 'find_symbol disabled — use grep/repo_map (decision 7.4: ripgrep baseline 4.2s vs tree-sitter 5.8s, no gain)' };
+        }
+        const files = await buildRepoMap({ cwd: ctx.cwd, maxFiles: 200 });
+        const q = input.name.toLowerCase();
+        const hits = [];
+        for (const f of files)
+            for (const s of f.symbols)
+                if (s.name.toLowerCase().includes(q) && (!input.kind || s.kind === input.kind))
+                    hits.push({ file: f.path, line: s.line, kind: s.kind, name: s.name });
+        return { name: input.name, hits: hits.slice(0, 20) };
+    }),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klyro",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Klyro — autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
   "type": "module",
   "main": "dist/index.js",