klyro 0.1.21 → 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

@@ -513,6 +513,21 @@ export async function startRepl(opts = {}) {
                 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/slash/parser.d.ts

@@ -53,6 +53,11 @@ export type SlashCommand = {
     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', 'project', '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('/')) {
@@ -37,6 +37,8 @@ export function parse(input) {
         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/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/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/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

@@ -23,6 +23,8 @@ 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();
@@ -103,5 +105,7 @@ export const builtinRegistry = () => {
     r.register(findSymbolTool);
     r.register(lspDiagnosticsTool);
     r.register(lspGotoDefinitionTool);
+    r.register(expandResultTool);
+    r.register(memoryWriteTool);
     return r;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klyro",
-  "version": "0.1.21",
+  "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",