klyro 0.1.1

package/dist/context/level6.js

@@ -0,0 +1,231 @@
+/**
+ * Level-6 context: project map + repo map + recent files + dependencies.
+ *
+ * Computed once per run, formatted compactly, and prepended to the system
+ * prompt. Each sub-block is independently optional — if a sub-step errors
+ * (e.g. unreadable package.json), we omit that block rather than failing
+ * the whole context load.
+ *
+ * Token budget: we cap each sub-block so the total added context is bounded
+ * (≤ ~6 KB). The exact budget is exposed via Level6Options.
+ *
+ * Static counterpart to Level-7 (`./level7.ts`), which injects a *live*
+ * runtime-telemetry snapshot (step count, recent tool calls, errors) into
+ * every model call. Together they give the model a static picture of the
+ * project (L6) and a live picture of its own run (L7).
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { buildProjectMap, formatProjectMap } from './project-map.js';
+import { buildRepoMap, formatRepoMap } from './repo-map.js';
+const DEFAULT_MAX_TOTAL_CHARS = 12_000;
+const RECENT_LIMIT = 15;
+const RECENT_GLOB = 'src/**';
+async function buildRecentFilesBlock(cwd, hours) {
+    const sinceMs = Date.now() - hours * 60 * 60 * 1000;
+    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.klyro']);
+    const SKIP_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.woff', '.woff2', '.ttf', '.otf', '.map']);
+    async function walk(dir, onFile) {
+        let entries = [];
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (SKIP_DIRS.has(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            let isDir = false;
+            try {
+                const s = await fs.lstat(full);
+                if (s.isSymbolicLink())
+                    continue;
+                isDir = s.isDirectory();
+            }
+            catch {
+                continue;
+            }
+            const rel = path.relative(cwd, full).split(path.sep).join('/');
+            if (isDir) {
+                if (rel.startsWith(RECENT_GLOB.replace('/**', '/')))
+                    await walk(full, onFile);
+            }
+            else {
+                const ext = path.extname(full).toLowerCase();
+                if (SKIP_EXT.has(ext))
+                    continue;
+                if (!rel.startsWith(RECENT_GLOB.replace('/**', '/')))
+                    continue;
+                await onFile(full, rel);
+            }
+        }
+    }
+    const recent = [];
+    await walk(cwd, async (full, rel) => {
+        try {
+            const mtimeMs = (await fs.stat(full)).mtimeMs;
+            if (mtimeMs >= sinceMs)
+                recent.push({ rel, mtimeMs });
+        }
+        catch { /* noop */ }
+    });
+    recent.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const top = recent.slice(0, RECENT_LIMIT);
+    if (!top.length)
+        return '';
+    const lines = ['# Recently changed (in src/, last ' + hours + 'h)'];
+    for (const f of top) {
+        const ageH = ((Date.now() - f.mtimeMs) / (1000 * 60 * 60)).toFixed(1);
+        lines.push(`- ${f.rel}  (${ageH}h ago)`);
+    }
+    return lines.join('\n');
+}
+async function buildDepsBlock(cwd) {
+    // Quick-and-dirty: only package.json for now (Python/Go/Rust fall back
+    // to the dedicated `dependencies` tool the model can call).
+    let pkgText = null;
+    try {
+        const s = await fs.stat(path.join(cwd, 'package.json'));
+        if (s.isFile() && s.size <= 64 * 1024) {
+            pkgText = await fs.readFile(path.join(cwd, 'package.json'), 'utf-8');
+        }
+    }
+    catch { /* no package.json */ }
+    if (!pkgText)
+        return '';
+    let pkg;
+    try {
+        pkg = JSON.parse(pkgText);
+    }
+    catch {
+        return '';
+    }
+    const sections = {};
+    for (const k of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+        const d = pkg[k];
+        if (!d || typeof d !== 'object')
+            continue;
+        sections[k] = d;
+    }
+    if (!Object.keys(sections).length)
+        return '';
+    const lines = ['# Direct dependencies (npm)'];
+    for (const [k, obj] of Object.entries(sections)) {
+        const entries = Object.entries(obj);
+        if (!entries.length)
+            continue;
+        lines.push(`## ${k}`);
+        for (const [n, v] of entries)
+            lines.push(`- ${n} ${v}`);
+    }
+    return lines.join('\n');
+}
+/** Build a Level-6 context block for the given working directory. */
+export async function buildLevel6Context(opts) {
+    const maxChars = opts.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
+    const recentHours = opts.recentHours ?? 24;
+    const blocks = [];
+    const flags = { hasProjectMap: false, hasRepoMap: false, hasRecentFiles: false, hasDeps: false };
+    if (!opts.skipProjectMap) {
+        try {
+            const m = await buildProjectMap(opts.cwd);
+            const text = formatProjectMap(m);
+            if (text) {
+                blocks.push(text);
+                flags.hasProjectMap = true;
+            }
+        }
+        catch { /* swallow — project map is a soft signal */ }
+    }
+    if (!opts.skipRepoMap) {
+        try {
+            const files = await buildRepoMap({ cwd: opts.cwd, maxFiles: 80, maxFileBytes: 16 * 1024 });
+            // Rank: prefer files with more named symbols + first-party paths.
+            const ranked = files
+                .map((f) => ({ f, score: f.symbols.length * 3 + (f.path.startsWith('src/') || f.path.startsWith('lib/') ? 5 : 0) }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 40)
+                .map((x) => x.f);
+            const text = formatRepoMap(ranked);
+            if (text) {
+                blocks.push(text);
+                flags.hasRepoMap = true;
+            }
+        }
+        catch { /* swallow */ }
+    }
+    if (!opts.skipRecentFiles) {
+        try {
+            const text = await buildRecentFilesBlock(opts.cwd, recentHours);
+            if (text) {
+                blocks.push(text);
+                flags.hasRecentFiles = true;
+            }
+        }
+        catch { /* swallow */ }
+    }
+    if (!opts.skipDeps) {
+        try {
+            const text = await buildDepsBlock(opts.cwd);
+            if (text) {
+                blocks.push(text);
+                flags.hasDeps = true;
+            }
+        }
+        catch { /* swallow */ }
+    }
+    let formatted = blocks.join('\n\n');
+    if (formatted.length > maxChars) {
+        // Truncate at the last newline before maxChars, then append a marker.
+        const cut = formatted.lastIndexOf('\n', maxChars);
+        formatted = formatted.slice(0, cut > 0 ? cut : maxChars) + '\n[truncated]';
+    }
+    return { formatted, ...flags };
+}
+/** Persist the Level-6 context to a JSON cache under .klyro/. */
+export async function writeLevel6Cache(cwd, ctx) {
+    if (!ctx.formatted)
+        return null;
+    const dir = path.join(cwd, '.klyro');
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    catch {
+        return null;
+    }
+    const file = path.join(dir, 'context.json');
+    const payload = {
+        generatedAt: new Date().toISOString(),
+        formatted: ctx.formatted,
+        hasProjectMap: ctx.hasProjectMap,
+        hasRepoMap: ctx.hasRepoMap,
+        hasRecentFiles: ctx.hasRecentFiles,
+        hasDeps: ctx.hasDeps,
+    };
+    try {
+        await fs.writeFile(file, JSON.stringify(payload, null, 2), 'utf-8');
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readLevel6Cache(cwd) {
+    const file = path.join(cwd, '.klyro', 'context.json');
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const data = JSON.parse(raw);
+        return {
+            formatted: typeof data.formatted === 'string' ? data.formatted : '',
+            hasProjectMap: !!data.hasProjectMap,
+            hasRepoMap: !!data.hasRepoMap,
+            hasRecentFiles: !!data.hasRecentFiles,
+            hasDeps: !!data.hasDeps,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/context/level7.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Level-7 context: runtime telemetry injected into every model call.
+ *
+ * Level-6 gives the model a precomputed, file-system-shaped picture of the
+ * project (file map, deps, recent files). Level-7 gives it a live picture
+ * of *itself mid-run* — the run so far is a feedback channel, not a blind
+ * loop.
+ *
+ * What gets surfaced (per step, before the next model call):
+ *   - current step number, max steps
+ *   - cumulative tool call count
+ *   - approximate token usage
+ *   - the last N tool calls (name, brief arg, latency, error?)
+ *   - the last error, if any
+ *   - how many times we've hit "max_steps" / abort / etc.
+ *
+ * Budget: hard-capped at `maxChars` (default 1.2 KB) so the telemetry
+ * block can never bloat the system prompt. Each sub-block is independently
+ * optional and bounded.
+ *
+ * This is in-memory only. No cache, no .klyro/ write — telemetry dies
+ * with the process. (We never want to leak one run's state into another.)
+ */
+import type { ToolUseBlock } from '../agent/message.js';
+export interface TelemetryToolCall {
+    name: string;
+    /** One-line summary (path for fs tools, command for shell). */
+    brief: string;
+    latencyMs: number;
+    isError: boolean;
+    step: number;
+}
+export interface TelemetrySnapshot {
+    step: number;
+    maxSteps: number;
+    toolCallCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    lastError: string | null;
+    lastToolCalls: TelemetryToolCall[];
+    /** How many tool calls failed in the entire run so far. */
+    errorCount: number;
+    /** When the run started (ISO string). */
+    startedAt: string;
+}
+export interface Level7Options {
+    maxRecentCalls?: number;
+    /** Cap on the formatted string (characters). */
+    maxChars?: number;
+}
+/** Mutable accumulator the runtime mutates each step. */
+export declare class RuntimeTelemetry {
+    private readonly opts;
+    private startMs;
+    private step;
+    private maxSteps;
+    private toolCallCount;
+    private inputTokens;
+    private outputTokens;
+    private lastError;
+    private errorCount;
+    private recent;
+    constructor(opts?: Level7Options);
+    setMaxSteps(n: number): void;
+    recordStepStart(step: number): void;
+    recordUsage(input: number, output: number): void;
+    recordToolCall(call: ToolUseBlock, latencyMs: number, isError: boolean): void;
+    recordError(msg: string): void;
+    /**
+     * One-shot helper for "this call didn't run / failed before executing".
+     * Records the call as an error (counted in `errorCount`, surfaced in
+     * `recentToolCalls`) AND sets the `lastError` message — both in one
+     * call so a future contributor can't update one without the other.
+     */
+    recordToolError(call: ToolUseBlock, kind: string): void;
+    snapshot(): TelemetrySnapshot;
+    format(): string;
+}
+/** Exported so the runtime can reuse this exact one-liner for the user-facing
+ *  approval prompt — keeps the L7 telemetry line and the approval summary
+ *  in sync. */
+export declare function summarizeToolCall(call: ToolUseBlock): string;
+/** Convenience: the empty "no telemetry yet" block. Used at step 0. */
+export declare function emptyTelemetryBlock(): string;

package/dist/context/level7.js

@@ -0,0 +1,156 @@
+/**
+ * Level-7 context: runtime telemetry injected into every model call.
+ *
+ * Level-6 gives the model a precomputed, file-system-shaped picture of the
+ * project (file map, deps, recent files). Level-7 gives it a live picture
+ * of *itself mid-run* — the run so far is a feedback channel, not a blind
+ * loop.
+ *
+ * What gets surfaced (per step, before the next model call):
+ *   - current step number, max steps
+ *   - cumulative tool call count
+ *   - approximate token usage
+ *   - the last N tool calls (name, brief arg, latency, error?)
+ *   - the last error, if any
+ *   - how many times we've hit "max_steps" / abort / etc.
+ *
+ * Budget: hard-capped at `maxChars` (default 1.2 KB) so the telemetry
+ * block can never bloat the system prompt. Each sub-block is independently
+ * optional and bounded.
+ *
+ * This is in-memory only. No cache, no .klyro/ write — telemetry dies
+ * with the process. (We never want to leak one run's state into another.)
+ */
+const DEFAULT_MAX_RECENT = 6;
+const DEFAULT_MAX_CHARS = 1200;
+/** Mutable accumulator the runtime mutates each step. */
+export class RuntimeTelemetry {
+    opts;
+    startMs = Date.now();
+    step = 0;
+    maxSteps = 30;
+    toolCallCount = 0;
+    inputTokens = 0;
+    outputTokens = 0;
+    lastError = null;
+    errorCount = 0;
+    recent = [];
+    constructor(opts = {}) {
+        this.opts = {
+            maxRecentCalls: opts.maxRecentCalls ?? DEFAULT_MAX_RECENT,
+            maxChars: opts.maxChars ?? DEFAULT_MAX_CHARS,
+        };
+    }
+    setMaxSteps(n) { this.maxSteps = n; }
+    recordStepStart(step) { this.step = step; }
+    recordUsage(input, output) {
+        this.inputTokens += input;
+        this.outputTokens += output;
+    }
+    recordToolCall(call, latencyMs, isError) {
+        this.toolCallCount++;
+        if (isError)
+            this.errorCount++;
+        this.recent.push({
+            name: call.name,
+            brief: summarize(call),
+            latencyMs,
+            isError,
+            step: this.step,
+        });
+        if (this.recent.length > this.opts.maxRecentCalls) {
+            this.recent.splice(0, this.recent.length - this.opts.maxRecentCalls);
+        }
+    }
+    recordError(msg) {
+        this.lastError = msg;
+    }
+    /**
+     * One-shot helper for "this call didn't run / failed before executing".
+     * Records the call as an error (counted in `errorCount`, surfaced in
+     * `recentToolCalls`) AND sets the `lastError` message — both in one
+     * call so a future contributor can't update one without the other.
+     */
+    recordToolError(call, kind) {
+        this.recordToolCall(call, 0, true);
+        this.recordError(`${kind}: ${call.name}`);
+    }
+    snapshot() {
+        return {
+            step: this.step,
+            maxSteps: this.maxSteps,
+            toolCallCount: this.toolCallCount,
+            inputTokens: this.inputTokens,
+            outputTokens: this.outputTokens,
+            lastError: this.lastError,
+            lastToolCalls: [...this.recent],
+            errorCount: this.errorCount,
+            startedAt: new Date(this.startMs).toISOString(),
+        };
+    }
+    format() {
+        const s = this.snapshot();
+        const lines = [];
+        lines.push('# Runtime telemetry');
+        const elapsedMs = Date.now() - this.startMs;
+        const elapsed = formatElapsed(elapsedMs);
+        lines.push(`Step ${s.step}/${s.maxSteps}  |  tool calls: ${s.toolCallCount}  |  errors: ${s.errorCount}  |  tokens: ${s.inputTokens} in / ${s.outputTokens} out  |  elapsed: ${elapsed}`);
+        if (s.lastError) {
+            lines.push(`Last error: ${truncate(s.lastError, 200)}`);
+        }
+        if (s.lastToolCalls.length) {
+            lines.push('Recent calls (newest last):');
+            for (const c of s.lastToolCalls) {
+                const tag = c.isError ? 'ERR' : 'ok ';
+                const lat = c.latencyMs < 1000 ? `${c.latencyMs}ms` : `${(c.latencyMs / 1000).toFixed(1)}s`;
+                lines.push(`  [${tag}] step=${c.step} ${c.name} ${truncate(c.brief, 80)} (${lat})`);
+            }
+        }
+        let out = lines.join('\n');
+        if (out.length > this.opts.maxChars) {
+            const cut = out.lastIndexOf('\n', this.opts.maxChars);
+            out = out.slice(0, cut > 0 ? cut : this.opts.maxChars) + '\n[truncated]';
+        }
+        return out;
+    }
+}
+function summarize(call) {
+    const i = call.input;
+    if (call.name === 'shell_exec' || call.name === 'run_verify') {
+        return String(i.command ?? '');
+    }
+    if (call.name === 'read_file' || call.name === 'write_file' || call.name === 'edit_file') {
+        return String(i.path ?? '');
+    }
+    if (call.name === 'grep' || call.name === 'search_files' || call.name === 'glob') {
+        return String(i.pattern ?? i.query ?? i.path ?? '');
+    }
+    if (call.name === 'list_directory') {
+        return String(i.path ?? '.');
+    }
+    return '';
+}
+/** Exported so the runtime can reuse this exact one-liner for the user-facing
+ *  approval prompt — keeps the L7 telemetry line and the approval summary
+ *  in sync. */
+export function summarizeToolCall(call) {
+    return summarize(call);
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, Math.max(0, n - 1)) + '…';
+}
+function formatElapsed(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    return `${m}m${s % 60}s`;
+}
+/** Convenience: the empty "no telemetry yet" block. Used at step 0. */
+export function emptyTelemetryBlock() {
+    return '# Runtime telemetry\n(no telemetry yet — this is step 0)';
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Project map — high-level description of a repository.
+ *
+ * Goal: when an agent opens a repo for the first time, it should learn
+ * "what kind of project is this" in one read. We detect:
+ *   - language(s)              from file extensions
+ *   - framework                from package.json / requirements.txt / go.mod
+ *   - package manager          from lockfiles + scripts
+ *   - test framework           from package.json scripts + devDependencies
+ *   - build commands           from package.json scripts + Makefile
+ *   - source directories       from convention + first-party markers
+ *   - important config files   from a curated allow-list
+ *
+ * Output: ProjectMap (machine-readable) + formatProjectMap() (model-readable).
+ *
+ * Design constraints:
+ *   - Single root-dir read, no subprocess calls (fast + hermetic).
+ *   - Bounded output: at most MAX_SOURCE_DIRS source dirs, MAX_CONFIG_FILES
+ *     config files, top-3 languages, top-3 frameworks.
+ *   - Reuses IGNORED_DIRS from repo-map.ts so the two scanners agree on
+ *     what to walk past.
+ */
+export declare const IGNORED_DIRS: Set<string>;
+export interface Dependency {
+    name: string;
+    version?: string;
+}
+export interface ProjectMap {
+    root: string;
+    language: string[];
+    framework: string[];
+    packageManager?: string;
+    testFramework?: string;
+    buildCommands: string[];
+    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;
+}
+/** 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. */
+export declare function formatProjectMap(m: ProjectMap): string;