klyro 1.0.5 → 1.0.6

package/dist/cli/slash/custom.js

@@ -0,0 +1,166 @@
+/**
+ * File-based extensibility: `.klyro/commands/*.md` (project) +
+ * `~/.klyro/commands/*.md` (global). Project wins on name clash.
+ *
+ * Format: YAML-ish frontmatter (`---` fences) with `name` (default:
+ * filename), `description`/`hint`, then a body supporting `$1..$9` and
+ * `$@` (all args). A custom command expands to prompt text and runs
+ * through the normal prompt path (with recursion depth guard).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Minimal frontmatter parser: `---` fences + `key: value` lines only. */
+export function parseFrontmatter(text) {
+    const data = {};
+    if (!text.startsWith('---'))
+        return { data, body: text };
+    const end = text.indexOf('\n---', 3);
+    if (end === -1)
+        return { data, body: text };
+    const head = text.slice(3, end);
+    for (const line of head.split('\n')) {
+        const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trimEnd());
+        if (m)
+            data[m[1].toLowerCase()] = (m[2] ?? '').trim();
+    }
+    return { data, body: text.slice(end + 4).replace(/^\r?\n/, '') };
+}
+/** Parse a scalar list: `[a, b]`, `a, b`, or newline/`- ` items. */
+export function parseList(value) {
+    if (!value)
+        return [];
+    let v = value.trim();
+    if (v.startsWith('[') && v.endsWith(']'))
+        v = v.slice(1, -1);
+    const out = [];
+    for (const chunk of v.split(/[\n,]/)) {
+        const t = chunk.trim().replace(/^-+\s*/, '').replace(/^['"]|['"]$/g, '');
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+export function parseBool(value, fallback) {
+    if (value === undefined || value === '')
+        return fallback;
+    return /^(true|yes|1|on)$/i.test(value.trim());
+}
+export function parseInt_(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value.trim());
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/** Expand `$1..$9` and `$@` (all args joined by space). Missing args → ''. */
+export function expandArgs(body, args) {
+    const all = args.join(' ');
+    return body
+        .replace(/\$@/g, () => all)
+        .replace(/\$([1-9])/g, (_m, d) => args[Number(d) - 1] ?? '');
+}
+function commandsDir(home) {
+    return [path.join(home, '.klyro', 'commands')];
+}
+function readCommandFile(file, source) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const { data, body } = parseFrontmatter(raw);
+    const fallback = path.basename(file, path.extname(file)).toLowerCase();
+    const name = (data['name'] || fallback).toLowerCase();
+    if (!/^[a-z0-9_-]{1,32}$/.test(name))
+        return null;
+    if (!body.trim())
+        return null;
+    return { name, description: data['description'] || data['hint'] || '', body: body.trim(), source };
+}
+function listCommandFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+/** Load custom commands: global first, project wins on name clash. Never throws. */
+export function loadCustomCommands(cwd) {
+    const byName = new Map();
+    try {
+        const home = os.homedir() || process.cwd();
+        for (const dir of commandsDir(home)) {
+            for (const f of listCommandFiles(dir)) {
+                const c = readCommandFile(f, 'global');
+                if (c)
+                    byName.set(c.name, c);
+            }
+        }
+        const projectDir = path.join(cwd, '.klyro', 'commands');
+        for (const f of listCommandFiles(projectDir)) {
+            const c = readCommandFile(f, 'project');
+            if (c)
+                byName.set(c.name, c);
+        }
+    }
+    catch {
+        return [...byName.values()];
+    }
+    return [...byName.values()];
+}
+const COMPLETABLE_IGNORED = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.klyro', 'out', '.next', 'target', 'vendor']);
+const MAX_COMPLETABLE_FILES = 1000;
+/**
+ * Relative file paths for `@`-completion: recursive walk, ignored dirs
+ * skipped, capped (directories sort first via trailing `/`).
+ */
+export function listCompletableFiles(cwd) {
+    const out = [];
+    const walk = (dir, rel) => {
+        if (out.length >= MAX_COMPLETABLE_FILES)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const sorted = entries.sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
+        for (const e of sorted) {
+            if (out.length >= MAX_COMPLETABLE_FILES)
+                return;
+            if (rel === '' && COMPLETABLE_IGNORED.has(e.name))
+                continue;
+            if (e.name.startsWith('.') && rel === '') {
+                // Top-level dotfiles are completable (e.g. .env.example) but never traversed.
+                if (e.isFile())
+                    out.push(e.name);
+                continue;
+            }
+            const r = rel === '' ? e.name : `${rel}/${e.name}`;
+            if (e.isDirectory()) {
+                out.push(`${r}/`);
+                walk(path.join(dir, e.name), r);
+            }
+            else if (e.isFile()) {
+                out.push(r);
+            }
+        }
+    };
+    try {
+        walk(cwd, '');
+    }
+    catch {
+        return out;
+    }
+    return out;
+}

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

@@ -39,8 +39,13 @@ export type SlashCommand = {
     kind: 'diff';
 } | {
     kind: 'undo';
+    n?: number;
 } | {
     kind: 'rewind';
+    n?: number;
+    summary?: boolean;
+} | {
+    kind: 'checkpoints';
 } | {
     kind: 'plan';
     task?: string;
@@ -68,6 +73,9 @@ export type SlashCommand = {
     kind: 'thinking';
 } | {
     kind: 'memory';
+} | {
+    kind: 'memory-append';
+    text: string;
 } | {
     kind: 'jobs';
 } | {
@@ -323,4 +331,4 @@ export declare const COMMAND_DEFS: CommandDef[];
  */
 export declare function fuzzyScore(name: string, query: string): number;
 /** Fuzzy-match command names for TUI autocomplete — top `limit` (default 6). */
-export declare function suggestCommands(prefix: string, limit?: number): CommandDef[];
+export declare function suggestCommands(prefix: string, limit?: number, extra?: CommandDef[]): CommandDef[];

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 = ['help', 'clear', 'new', 'exit', 'quit', 'q', 'compact', 'resume', 'sessions', 'rename', 'fork', 'branch', 'export', 'copy', 'model', 'm', 'models', 'provider', 'p', 'effort', 'e', 'fast', 'init', 'status', 'context', 'diff', 'plan', 'todos', 'memory', 'permissions', 'mode', 'sandbox', 'approve', 'deny', 'login', 'logout', 'auth', 'version', 'update', 'cancel', 'shell', 'mention', 'tools', 'config', 'settings', 'doctor', 'cost', 'thinking', 'jobs', 'verify', 'project', 'undo', 'rewind', 'review', 'code-review', 'security-review', 'simplify', 'test', 'lint', 'build', 'run', 'fix', 'explain', 'format', 'ask', 'redo', 'checkpoint', 'accept', 'reject', 'details', 'verbose', 'raw', 'activity', 'tasks', 'ps', 'stop', 'queue', 'retry', 'kill', 'mcp', 'agents', 'agent', 'subagents', 'subtask', 'background', 'add-dir', 'cd', 'attach', 'drop', 'image', 'paste', 'files', 'ls', 'tree', 'search', 'web', 'read', 'map', 'tokens', 'commit', 'push', 'pull', 'pr', 'issue', 'editor', 'keymap', 'vim', 'theme', 'statusline', 'output-style', 'debug', 'whoami', 'reload', 'reset', 'bug', 'changelog', 'prompt', 'alias', 'commands', 'env', 'deps', 'install'];
+const KNOWN = ['help', 'clear', 'new', 'exit', 'quit', 'q', 'compact', 'resume', 'sessions', 'rename', 'fork', 'branch', 'export', 'copy', 'model', 'm', 'models', 'provider', 'p', 'effort', 'e', 'fast', 'init', 'status', 'context', 'diff', 'plan', 'todos', 'memory', 'permissions', 'mode', 'sandbox', 'approve', 'deny', 'login', 'logout', 'auth', 'version', 'update', 'cancel', 'shell', 'mention', 'tools', 'config', 'settings', 'doctor', 'cost', 'thinking', 'jobs', 'verify', 'project', 'undo', 'rewind', 'checkpoints', 'review', 'code-review', 'security-review', 'simplify', 'test', 'lint', 'build', 'run', 'fix', 'explain', 'format', 'ask', 'redo', 'checkpoint', 'accept', 'reject', 'details', 'verbose', 'raw', 'activity', 'tasks', 'ps', 'stop', 'queue', 'retry', 'kill', 'mcp', 'agents', 'agent', 'subagents', 'subtask', 'background', 'add-dir', 'cd', 'attach', 'drop', 'image', 'paste', 'files', 'ls', 'tree', 'search', 'web', 'read', 'map', 'tokens', 'commit', 'push', 'pull', 'pr', 'issue', 'editor', 'keymap', 'vim', 'theme', 'statusline', 'output-style', 'debug', 'whoami', 'reload', 'reset', 'bug', 'changelog', 'prompt', 'alias', 'commands', 'env', 'deps', 'install'];
 export function parse(input) {
     const trimmed = input.trim();
     // `!cmd` alias for /shell, `@path` alias for /mention (commands.md P1)
@@ -35,14 +35,35 @@ export function parse(input) {
         case 'new': return { kind: 'new' };
         case 'compact': return { kind: 'compact', focus: rest || undefined };
         case 'diff': return { kind: 'diff' };
-        case 'undo': return { kind: 'undo' };
-        case 'rewind': return { kind: 'rewind' };
+        case 'undo': {
+            const un = Number(rest.split(/\s+/).filter(Boolean)[0] ?? '1');
+            return { kind: 'undo', n: Number.isInteger(un) && un > 0 ? un : 1 };
+        }
+        case 'rewind': {
+            // /rewind [n] [summary] — nth-back snapshot (1 = latest), optional
+            // post-restore summary of the reverted changes.
+            const parts = rest.split(/\s+/).filter(Boolean);
+            const n = parts.length > 0 ? Number(parts[0]) : 1;
+            return {
+                kind: 'rewind',
+                n: Number.isInteger(n) && n > 0 ? n : 1,
+                ...(parts.slice(1).join(' ').toLowerCase() === 'summary' ? { summary: true } : {}),
+            };
+        }
+        case 'checkpoints': return { kind: 'checkpoints' };
         case 'plan': return { kind: 'plan', task: rest || undefined };
         case 'todos': return { kind: 'todos' };
         case 'status': return { kind: 'status' };
         case 'cost': return { kind: 'cost' };
         case 'thinking': return { kind: 'thinking' };
-        case 'memory': return { kind: 'memory' };
+        case 'memory': {
+            // /memory shows notes; /memory append <text> writes one (human path,
+            // same redaction + atomicity as the memory_write tool).
+            const mm = /^append\s+([\s\S]+)$/.exec(rest);
+            if (mm)
+                return { kind: 'memory-append', text: mm[1].trim() };
+            return { kind: 'memory' };
+        }
         case 'jobs': return { kind: 'jobs' };
         case 'verify': return { kind: 'verify' };
         case 'project': return { kind: 'project' };
@@ -233,9 +254,9 @@ export const COMMAND_DEFS = [
     { name: 'explain', hint: 'explain code' },
     { name: 'format', hint: 'format code' },
     { name: 'ask', hint: 'read-only Q&A' },
-    { name: 'undo', hint: 'undo change' },
-    { name: 'redo', hint: 'redo change' },
+    { name: 'undo', hint: 'undo change' }, { name: 'redo', hint: 'redo change' },
     { name: 'rewind', hint: 'rewind code' },
+    { name: 'checkpoints', hint: 'list snapshots' },
     { name: 'checkpoint', hint: 'create checkpoint' },
     { name: 'accept', hint: 'accept edits' },
     { name: 'reject', hint: 'reject edits' },
@@ -325,11 +346,12 @@ export function fuzzyScore(name, query) {
     return score;
 }
 /** Fuzzy-match command names for TUI autocomplete — top `limit` (default 6). */
-export function suggestCommands(prefix, limit = 6) {
+export function suggestCommands(prefix, limit = 6, extra = []) {
     const p = prefix.toLowerCase().replace(/^\//, '');
+    const pool = extra.length > 0 ? [...extra, ...COMMAND_DEFS] : COMMAND_DEFS;
     if (!p)
-        return COMMAND_DEFS.slice(0, limit);
-    return COMMAND_DEFS.map((d) => ({ d, s: fuzzyScore(d.name, p) + fuzzyScore(d.hint, p) * 0.25 }))
+        return pool.slice(0, limit);
+    return pool.map((d) => ({ d, s: fuzzyScore(d.name, p) + fuzzyScore(d.hint, p) * 0.25 }))
         .filter((x) => x.s > -Infinity)
         .sort((a, b) => b.s - a.s)
         .slice(0, limit)

package/dist/context/memory.js

@@ -24,7 +24,24 @@ export async function memoryWrite(cwd, content) {
     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.
-    const next = (prev + '\n' + redact(content)).slice(-MEMORY_STEADY_STATE_CHARS); // ≤1k tokens ~4k chars
+    const full = prev + '\n' + redact(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.
+        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);
+            }
+        }
+        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)}`);
     await fs.writeFile(tmp, next, 'utf-8');
     try {

package/dist/eval/harness.d.ts

@@ -7,7 +7,7 @@
  * This is the MVP gate per Devolopment-plan.md / docs/plan.md §10: a
  * reproducible suite of programmatic tasks. Real repo tasks come in v1.0.
  */
-import type { StreamEvent } from '../agent/provider-adapter.js';
+import type { ProviderAdapter, StreamEvent } from '../agent/provider-adapter.js';
 export interface ScriptedTask {
     id: string;
     description: string;
@@ -20,6 +20,13 @@ export interface ScriptedTask {
     expectStatus: 'complete' | 'max_steps' | 'aborted' | 'verify_failed' | 'no_final';
     /** Expected tool-call count. */
     expectToolCalls?: number;
+    /**
+     * Semantic rubric graded by a model judge (see judge.ts). Only runs when
+     * the caller supplies a judge adapter; otherwise recorded as skipped.
+     */
+    judge?: {
+        rubric: string[];
+    };
 }
 export interface TaskResult {
     id: string;
@@ -28,8 +35,16 @@ export interface TaskResult {
     observedStatus?: string;
     observedToolCalls?: number;
     durationMs: number;
+    judge?: {
+        pass: boolean;
+        notes: string;
+        skipped: boolean;
+    };
 }
-export declare function runTask(t: ScriptedTask): Promise<TaskResult>;
+export declare function runTask(t: ScriptedTask, opts?: {
+    judgeAdapter?: ProviderAdapter;
+    judgeModel?: string;
+}): Promise<TaskResult>;
 export interface HarnessSummary {
     total: number;
     passed: number;
@@ -38,7 +53,10 @@ export interface HarnessSummary {
     results: TaskResult[];
     durationMs: number;
 }
-export declare function runHarness(tasks: ScriptedTask[]): Promise<HarnessSummary>;
+export declare function runHarness(tasks: ScriptedTask[], opts?: {
+    judgeAdapter?: ProviderAdapter;
+    judgeModel?: string;
+}): Promise<HarnessSummary>;
 /** Format a harness summary as a markdown report. */
 export declare function formatReport(summary: HarnessSummary): string;
 /** 5.4 — File-based fixture support: repo|repo.json, task.md, check.sh, meta.json */

package/dist/eval/harness.js

@@ -42,7 +42,7 @@ function scriptedAdapter(script) {
         },
     };
 }
-export async function runTask(t) {
+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));
     await fs.mkdir(cwd, { recursive: true });
@@ -72,6 +72,33 @@ export async function runTask(t) {
         if (verifyFailure) {
             details += ` verifyFailure=${verifyFailure};`;
         }
+        // Model-graded semantic check (opt-in: needs a live judge adapter).
+        let judge;
+        if (t.judge && t.judge.rubric.length > 0) {
+            if (opts.judgeAdapter) {
+                const { runJudge } = await import('./judge.js');
+                const texts = result.transcript
+                    .filter((m) => m.role === 'assistant')
+                    .flatMap((m) => m.content)
+                    .filter((b) => b.kind === 'text')
+                    .map((b) => b.text)
+                    .join('\n');
+                const v = await runJudge(opts.judgeAdapter, opts.judgeModel ?? 'mock-judge', {
+                    task: t.task,
+                    finalText: result.finalText,
+                    toolCalls: result.toolCalls,
+                    extra: `assistant transcript:\n${texts.slice(0, 3000)}`,
+                }, t.judge.rubric);
+                judge = { pass: v.pass, notes: v.notes, skipped: v.skipped };
+                if (!v.pass) {
+                    details += ` judge=fail (${v.notes || 'rubric unmet'});`;
+                    pass = false;
+                }
+            }
+            else {
+                judge = { pass: true, notes: 'no judge adapter — skipped', skipped: true };
+            }
+        }
         return {
             id: t.id,
             status: pass ? 'pass' : 'fail',
@@ -79,6 +106,7 @@ export async function runTask(t) {
             observedStatus,
             observedToolCalls: result.toolCalls,
             durationMs: Date.now() - start,
+            ...(judge ? { judge } : {}),
         };
     }
     finally {
@@ -88,11 +116,11 @@ export async function runTask(t) {
         catch { }
     }
 }
-export async function runHarness(tasks) {
+export async function runHarness(tasks, opts = {}) {
     const start = Date.now();
     const results = [];
     for (const t of tasks)
-        results.push(await runTask(t));
+        results.push(await runTask(t, opts));
     const passed = results.filter((r) => r.status === 'pass').length;
     return {
         total: results.length,

package/dist/eval/judge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Model-graded judge for evals: scores a finished run against a rubric.
+ *
+ * Structural asserts (status, tool counts) catch regressions; the judge
+ * catches semantic failures (wrong file, wrong content, ignored task).
+ * Runs on any ProviderAdapter — in CI, pass a live adapter + judge model;
+ * offline runs skip judging (recorded as `skipped`).
+ */
+import type { ProviderAdapter } from '../agent/provider-adapter.js';
+export interface JudgeSpec {
+    /** Each item is one binary criterion, e.g. "note.txt contains exactly 'hi'". */
+    rubric: string[];
+    /** Model for grading (defaults to the caller's judge model). */
+    model?: string;
+}
+export interface JudgeVerdict {
+    pass: boolean;
+    scores: Record<string, number>;
+    notes: string;
+    skipped: boolean;
+}
+/**
+ * Grade a finished run. Returns `{pass:false}` (never throws) when the
+ * model output is unparsable or the call fails — an inconclusive judge
+ * must not silently pass.
+ */
+export declare function runJudge(adapter: ProviderAdapter, model: string, input: {
+    task: string;
+    finalText: string;
+    toolCalls: number;
+    extra?: string;
+}, rubric: string[]): Promise<JudgeVerdict>;

package/dist/eval/judge.js

@@ -0,0 +1,63 @@
+function extractJson(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start)
+        return null;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Grade a finished run. Returns `{pass:false}` (never throws) when the
+ * model output is unparsable or the call fails — an inconclusive judge
+ * must not silently pass.
+ */
+export async function runJudge(adapter, model, input, rubric) {
+    if (rubric.length === 0)
+        return { pass: true, scores: {}, notes: 'empty rubric', skipped: false };
+    const criteria = rubric.map((r, i) => `  c${i + 1}. ${r}`).join('\n');
+    const prompt = [
+        'You are an evaluator grading an AI coding agent run. Score ONLY the criteria below.',
+        `Task: ${input.task}`,
+        `Final answer: ${input.finalText.slice(0, 2000)}`,
+        `Tool calls made: ${input.toolCalls}`,
+        input.extra ? `Run facts:\n${input.extra.slice(0, 2000)}` : '',
+        'Criteria (score each 1 = met, 0 = not met):',
+        criteria,
+        'Respond with ONLY a JSON object: {"scores": {"c1": 1, ...}, "notes": "<one line>"}.',
+    ].filter(Boolean).join('\n\n');
+    let text = '';
+    try {
+        for await (const ev of adapter.stream({
+            model,
+            system: 'You are a strict evaluator. Reply with only the requested JSON.',
+            messages: [{ role: 'user', content: [{ kind: 'text', text: prompt }] }],
+            tools: [],
+        })) {
+            if (ev.kind === 'text_delta')
+                text += ev.text;
+            else if (ev.kind === 'error')
+                return { pass: false, scores: {}, notes: `judge call failed: ${ev.message}`, skipped: false };
+        }
+    }
+    catch (err) {
+        return { pass: false, scores: {}, notes: `judge call threw: ${err instanceof Error ? err.message : String(err)}`, skipped: false };
+    }
+    const parsed = extractJson(text);
+    if (!parsed || typeof parsed.scores !== 'object' || parsed.scores === null) {
+        return { pass: false, scores: {}, notes: 'judge output unparsable', skipped: false };
+    }
+    const scores = {};
+    let pass = true;
+    rubric.forEach((_r, i) => {
+        const v = parsed.scores[`c${i + 1}`];
+        const n = v === 1 || v === '1' || v === true ? 1 : 0;
+        scores[`c${i + 1}`] = n;
+        if (n !== 1)
+            pass = false;
+    });
+    return { pass, scores, notes: typeof parsed.notes === 'string' ? parsed.notes.slice(0, 500) : '', skipped: false };
+}

package/dist/eval/tasks.js

@@ -95,4 +95,138 @@ export const MVP_TASKS = [
         expectStatus: 'complete',
         expectToolCalls: 2,
     },
+    {
+        id: 't7-write-verify-content',
+        description: 'Written file bytes are exactly what the model sent (real FS assert).',
+        task: 'create app.txt with content "hello eval"',
+        script: [
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c1', name: 'write_file' },
+                { kind: 'tool_call_delta', id: 'c1', argsJson: '{"path":"app.txt","content":"hello eval"}' },
+                { kind: 'tool_call_end', id: 'c1' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'Created.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ],
+        ],
+        verifyCommand: 'node -e "process.exit(require(\'fs\').readFileSync(\'app.txt\',\'utf8\')===\'hello eval\'?0:1)"',
+        expectStatus: 'complete',
+        expectToolCalls: 1,
+    },
+    {
+        id: 't8-edit-flow',
+        description: 'Write then edit; final bytes reflect the edit.',
+        task: 'create data.txt then change its content',
+        script: [
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c1', name: 'write_file' },
+                { kind: 'tool_call_delta', id: 'c1', argsJson: '{"path":"data.txt","content":"v1"}' },
+                { kind: 'tool_call_end', id: 'c1' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c2', name: 'edit_file' },
+                { kind: 'tool_call_delta', id: 'c2', argsJson: '{"path":"data.txt","find":"v1","replace":"v2"}' },
+                { kind: 'tool_call_end', id: 'c2' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'Edited.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ],
+        ],
+        verifyCommand: 'node -e "process.exit(require(\'fs\').readFileSync(\'data.txt\',\'utf8\')===\'v2\'?0:1)"',
+        expectStatus: 'complete',
+        expectToolCalls: 2,
+    },
+    {
+        id: 't9-allowlisted-shell',
+        description: 'Allowlisted shell command executes.',
+        task: 'run echo',
+        script: [
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c1', name: 'shell_exec' },
+                { kind: 'tool_call_delta', id: 'c1', argsJson: '{"command":"echo eval-ok"}' },
+                { kind: 'tool_call_end', id: 'c1' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'Ran.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ],
+        ],
+        expectStatus: 'complete',
+        expectToolCalls: 1,
+    },
+    {
+        id: 't10-destructive-shell-denied',
+        description: 'Destructive shell is denied before execution.',
+        task: 'try something dangerous',
+        script: [
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c1', name: 'shell_exec' },
+                { kind: 'tool_call_delta', id: 'c1', argsJson: '{"command":"rm -rf /"}' },
+                { kind: 'tool_call_end', id: 'c1' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'Understood.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ],
+        ],
+        expectStatus: 'complete',
+        expectToolCalls: 1,
+    },
+    {
+        id: 't11-write-read-roundtrip',
+        description: 'Write then read back the same file.',
+        task: 'write and read back',
+        script: [
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c1', name: 'write_file' },
+                { kind: 'tool_call_delta', id: 'c1', argsJson: '{"path":"round.txt","content":"roundtrip"}' },
+                { kind: 'tool_call_end', id: 'c1' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'tool_call_start', id: 'c2', name: 'read_file' },
+                { kind: 'tool_call_delta', id: 'c2', argsJson: '{"path":"round.txt"}' },
+                { kind: 'tool_call_end', id: 'c2' },
+                { kind: 'message_end', finishReason: 'tool_calls' },
+            ],
+            [
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'Read it.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ],
+        ],
+        expectStatus: 'complete',
+        expectToolCalls: 2,
+    },
+    {
+        id: 't12-judged-answer',
+        description: 'Semantic rubric example (judge runs only with a live judge adapter).',
+        task: 'say done',
+        script: [[
+                { kind: 'message_start' },
+                { kind: 'text_delta', text: 'All done.' },
+                { kind: 'message_end', finishReason: 'stop' },
+            ]],
+        expectStatus: 'complete',
+        expectToolCalls: 0,
+        judge: { rubric: ['the final answer contains the word "done"'] },
+    },
 ];