klyro 0.1.1

package/dist/persistence/audit.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Audit log — append-only JSONL of runtime events. Same shape as the
+ * future durable-task scheduler will read, so the data layout is
+ * forward-compatible.
+ */
+export type AuditEvent = {
+    kind: 'session_created';
+    sessionId: string;
+    task: string;
+    cwd: string;
+    ts: number;
+} | {
+    kind: 'session_resumed';
+    sessionId: string;
+    ts: number;
+} | {
+    kind: 'session_completed';
+    sessionId: string;
+    status: string;
+    ts: number;
+} | {
+    kind: 'step_started';
+    sessionId: string;
+    step: number;
+    ts: number;
+} | {
+    kind: 'step_completed';
+    sessionId: string;
+    step: number;
+    ts: number;
+} | {
+    kind: 'tool_call_started';
+    sessionId: string;
+    callId: string;
+    name: string;
+    ts: number;
+} | {
+    kind: 'tool_call_completed';
+    sessionId: string;
+    callId: string;
+    isError: boolean;
+    latencyMs: number;
+    ts: number;
+} | {
+    kind: 'policy_decision';
+    sessionId: string;
+    callId: string;
+    action: string;
+    ts: number;
+} | {
+    kind: 'verification_attempted';
+    sessionId: string;
+    command: string;
+    ts: number;
+} | {
+    kind: 'verification_succeeded';
+    sessionId: string;
+    ts: number;
+} | {
+    kind: 'verification_failed';
+    sessionId: string;
+    exitCode: number;
+    type: string;
+    ts: number;
+} | {
+    kind: 'repair_attempted';
+    sessionId: string;
+    attempt: number;
+    ts: number;
+};
+export declare class AuditLog {
+    private readonly filePath;
+    constructor(filePath: string);
+    write(event: AuditEvent): Promise<void>;
+}

package/dist/persistence/audit.js

@@ -0,0 +1,15 @@
+/**
+ * Audit log — append-only JSONL of runtime events. Same shape as the
+ * future durable-task scheduler will read, so the data layout is
+ * forward-compatible.
+ */
+import { SessionStore } from './store.js';
+export class AuditLog {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async write(event) {
+        await SessionStore.appendJsonl(this.filePath, event);
+    }
+}

package/dist/persistence/store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Session store — JSON-on-disk persistence for sessions, transcripts,
+ * and observations. Single file per session, indexed by a `sessions.json`
+ * directory index. No native deps.
+ *
+ * MVP rationale: better-sqlite3 needs a native build step that fails on
+ * some Windows installs. A JSON file per session + a flat index is
+ * trivial to back up, easy to inspect, and good enough for the MVP's
+ * ~50-task eval suite. v1.0 can swap in SQLite behind the same
+ * SessionStore interface.
+ */
+export type SessionStatus = 'open' | 'complete' | 'verify_failed' | 'aborted' | 'max_steps';
+export interface SessionConfig {
+    model: string;
+    maxSteps: number;
+    policyAllow?: string[];
+}
+export interface SessionRecord {
+    id: string;
+    cwd: string;
+    task: string;
+    status: SessionStatus;
+    createdAt: number;
+    updatedAt: number;
+    config: SessionConfig;
+    finalText?: string;
+}
+export interface StoredMessage {
+    role: 'user' | 'assistant' | 'tool' | 'system';
+    content: unknown;
+    ts: number;
+}
+export interface StoredObservation {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    output: unknown;
+    isError: boolean;
+    startedAt: number;
+    finishedAt: number;
+}
+export declare class SessionStore {
+    private readonly dir;
+    private readonly indexPath;
+    constructor(dir: string);
+    private ensureDir;
+    private readIndex;
+    private writeIndex;
+    create(opts: {
+        cwd: string;
+        task: string;
+        config: SessionConfig;
+    }): Promise<SessionRecord>;
+    private readSession;
+    private writeSession;
+    appendMessage(id: string, message: StoredMessage): Promise<void>;
+    appendObservation(id: string, obs: StoredObservation): Promise<void>;
+    setStatus(id: string, status: SessionStatus, finalText?: string): Promise<void>;
+    loadMessages(id: string): Promise<StoredMessage[]>;
+    loadObservations(id: string): Promise<StoredObservation[]>;
+    list(filter?: {
+        status?: SessionStatus;
+    }): Promise<SessionRecord[]>;
+    get(id: string): Promise<SessionRecord | null>;
+    /** Atomic append — survives crashes; suitable for audit log. */
+    static appendJsonl(filePath: string, entry: unknown): Promise<void>;
+}

package/dist/persistence/store.js

@@ -0,0 +1,106 @@
+/**
+ * Session store — JSON-on-disk persistence for sessions, transcripts,
+ * and observations. Single file per session, indexed by a `sessions.json`
+ * directory index. No native deps.
+ *
+ * MVP rationale: better-sqlite3 needs a native build step that fails on
+ * some Windows installs. A JSON file per session + a flat index is
+ * trivial to back up, easy to inspect, and good enough for the MVP's
+ * ~50-task eval suite. v1.0 can swap in SQLite behind the same
+ * SessionStore interface.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export class SessionStore {
+    dir;
+    indexPath;
+    constructor(dir) {
+        this.dir = dir;
+        this.indexPath = path.join(dir, 'sessions.json');
+    }
+    async ensureDir() {
+        await fs.mkdir(this.dir, { recursive: true });
+    }
+    async readIndex() {
+        try {
+            const raw = await fs.readFile(this.indexPath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeIndex(idx) {
+        await fs.writeFile(this.indexPath, JSON.stringify(idx, null, 2));
+    }
+    async create(opts) {
+        await this.ensureDir();
+        const id = randomUUID();
+        const now = Date.now();
+        const record = {
+            id,
+            cwd: opts.cwd,
+            task: opts.task,
+            status: 'open',
+            createdAt: now,
+            updatedAt: now,
+            config: opts.config,
+        };
+        await fs.writeFile(path.join(this.dir, `${id}.json`), JSON.stringify({ record, messages: [], observations: [] }, null, 2));
+        const idx = await this.readIndex();
+        idx[id] = record;
+        await this.writeIndex(idx);
+        return record;
+    }
+    async readSession(id) {
+        const raw = await fs.readFile(path.join(this.dir, `${id}.json`), 'utf-8');
+        return JSON.parse(raw);
+    }
+    async writeSession(id, data) {
+        data.record.updatedAt = Date.now();
+        await fs.writeFile(path.join(this.dir, `${id}.json`), JSON.stringify(data, null, 2));
+        const idx = await this.readIndex();
+        idx[id] = data.record;
+        await this.writeIndex(idx);
+    }
+    async appendMessage(id, message) {
+        const data = await this.readSession(id);
+        data.messages.push(message);
+        await this.writeSession(id, data);
+    }
+    async appendObservation(id, obs) {
+        const data = await this.readSession(id);
+        data.observations.push(obs);
+        await this.writeSession(id, data);
+    }
+    async setStatus(id, status, finalText) {
+        const data = await this.readSession(id);
+        data.record.status = status;
+        if (finalText !== undefined)
+            data.record.finalText = finalText;
+        await this.writeSession(id, data);
+    }
+    async loadMessages(id) {
+        const data = await this.readSession(id);
+        return data.messages;
+    }
+    async loadObservations(id) {
+        const data = await this.readSession(id);
+        return data.observations;
+    }
+    async list(filter) {
+        const idx = await this.readIndex();
+        const all = Object.values(idx);
+        return filter?.status ? all.filter((s) => s.status === filter.status) : all;
+    }
+    async get(id) {
+        const idx = await this.readIndex();
+        return idx[id] ?? null;
+    }
+    /** Atomic append — survives crashes; suitable for audit log. */
+    static async appendJsonl(filePath, entry) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.appendFile(filePath, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+}

package/dist/policy/approval.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Interactive approval — prompt the user to allow/deny a tool call.
+ *
+ * TTY mode: shows the call, accepts y/n/a (yes/no/always-allow-this-command).
+ * Non-TTY: returns deny. Callers should treat non-TTY as the default
+ * (the user opted out of prompts with `--yes` or pipe input).
+ */
+export type ApprovalChoice = 'allow' | 'deny' | 'always';
+export interface ApprovalRequest {
+    toolName: string;
+    reason: string;
+    /** Best-effort summary of the call (command or path). */
+    summary: string;
+}
+export interface ApprovalPrompt {
+    ask(req: ApprovalRequest): Promise<ApprovalChoice>;
+}
+/** Default prompt backed by readline on stdin/stdout. */
+export declare class StdinApprovalPrompt implements ApprovalPrompt {
+    ask(req: ApprovalRequest): Promise<ApprovalChoice>;
+}
+/** Auto-deny — used in CI and `--no-approve` mode. */
+export declare class DenyAllApprovalPrompt implements ApprovalPrompt {
+    ask(_req: ApprovalRequest): Promise<ApprovalChoice>;
+}
+/**
+ * In-memory allowlist: tracks "always" choices by command prefix so a
+ * single prompt per command covers repeat invocations in the same session.
+ */
+export declare class InMemoryAllowlist implements ApprovalPrompt {
+    private readonly inner;
+    private readonly allow;
+    constructor(inner?: ApprovalPrompt);
+    ask(req: ApprovalRequest): Promise<ApprovalChoice>;
+}

package/dist/policy/approval.js

@@ -0,0 +1,54 @@
+/**
+ * Interactive approval — prompt the user to allow/deny a tool call.
+ *
+ * TTY mode: shows the call, accepts y/n/a (yes/no/always-allow-this-command).
+ * Non-TTY: returns deny. Callers should treat non-TTY as the default
+ * (the user opted out of prompts with `--yes` or pipe input).
+ */
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+/** Default prompt backed by readline on stdin/stdout. */
+export class StdinApprovalPrompt {
+    async ask(req) {
+        if (!input.isTTY)
+            return 'deny';
+        const rl = readline.createInterface({ input, output });
+        try {
+            process.stdout.write(`\n[approval needed] ${req.toolName}: ${req.summary}\n  reason: ${req.reason}\n  allow? [y/n/a(llow)] `);
+            const ans = (await rl.question('')).trim().toLowerCase();
+            if (ans === 'y' || ans === 'yes')
+                return 'allow';
+            if (ans === 'a' || ans === 'allow')
+                return 'always';
+            return 'deny';
+        }
+        finally {
+            rl.close();
+        }
+    }
+}
+/** Auto-deny — used in CI and `--no-approve` mode. */
+export class DenyAllApprovalPrompt {
+    async ask(_req) {
+        return 'deny';
+    }
+}
+/**
+ * In-memory allowlist: tracks "always" choices by command prefix so a
+ * single prompt per command covers repeat invocations in the same session.
+ */
+export class InMemoryAllowlist {
+    inner;
+    allow = new Set();
+    constructor(inner = new DenyAllApprovalPrompt()) {
+        this.inner = inner;
+    }
+    async ask(req) {
+        if (this.allow.has(req.summary))
+            return 'allow';
+        const choice = await this.inner.ask(req);
+        if (choice === 'always')
+            this.allow.add(req.summary);
+        return choice;
+    }
+}

package/dist/policy/engine.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Policy engine — gates every tool call.
+ *
+ * Returns a Decision (allow/ask/deny) per tool call based on a list of rules
+ * plus per-tool path/shell/secret checks. The runtime loop is the only
+ * caller; it then either executes the tool, prompts the user, or skips
+ * with a denial observation.
+ */
+export type Decision = {
+    action: 'allow';
+} | {
+    action: 'ask';
+    reason: string;
+} | {
+    action: 'deny';
+    reason: string;
+};
+export interface ToolCallLike {
+    /** Tool name, e.g. "write_file", "shell_exec". */
+    name: string;
+    /** Parsed tool input. */
+    input: Record<string, unknown>;
+}
+export interface PolicyContext {
+    cwd: string;
+    /** Optional transcript (for future rule extensions). */
+    transcript?: unknown;
+    /** True when running in a non-interactive environment (CI, pipe). */
+    nonInteractive: boolean;
+    /** Per-tool config. */
+    config: PolicyConfig;
+}
+export interface PolicyConfig {
+    /** Shell commands that are pre-approved (prefix match). */
+    shellAllow: string[];
+    /** Hard-deny shell commands (prefix or full match). */
+    shellDeny: string[];
+    /** File size limit in MiB for reads without confirmation. */
+    readSizeAskMiB: number;
+}
+export interface PolicyRule {
+    name: string;
+    /** Return a Decision to act on, or null to fall through to the next rule. */
+    evaluate(call: ToolCallLike, ctx: PolicyContext): Decision | null;
+}
+export declare const DEFAULT_POLICY_CONFIG: PolicyConfig;
+/**
+ * Compose multiple rules. The first rule to return a Decision wins.
+ * If none return a Decision, the default is `allow`.
+ */
+export declare class PolicyEngine {
+    private readonly rules;
+    private readonly config;
+    constructor(rules: PolicyRule[], config?: PolicyConfig);
+    evaluate(call: ToolCallLike, base: {
+        cwd: string;
+        transcript?: unknown;
+        nonInteractive: boolean;
+    }): Promise<Decision>;
+}
+/** Builtin set of rules. Order matters: first match wins. */
+export declare function builtinRules(): PolicyRule[];
+/** Hard-deny for obviously destructive shell patterns. */
+export declare const shellDenyRule: PolicyRule;
+/** Allowlist for shell — exact or prefix. Anything not in the list asks. */
+export declare const shellAllowRule: PolicyRule;
+/** Writes are auto-allowed if path resolves inside cwd (path-guard throws otherwise). */
+export declare const writeFileCwdRule: PolicyRule;
+/** Reads > 5 MiB require confirmation (avoid filling the context window). */
+export declare const readFileSizeRule: PolicyRule;
+/** Convenience: evaluate via safe() so a buggy rule doesn't crash the loop. */
+export declare function evaluatePolicy(engine: PolicyEngine, call: ToolCallLike, ctx: {
+    cwd: string;
+    transcript?: unknown;
+    nonInteractive: boolean;
+}): Promise<Decision>;

package/dist/policy/engine.js

@@ -0,0 +1,163 @@
+/**
+ * Policy engine — gates every tool call.
+ *
+ * Returns a Decision (allow/ask/deny) per tool call based on a list of rules
+ * plus per-tool path/shell/secret checks. The runtime loop is the only
+ * caller; it then either executes the tool, prompts the user, or skips
+ * with a denial observation.
+ */
+import { safe } from '../tools/normalize.js';
+export const DEFAULT_POLICY_CONFIG = {
+    shellAllow: [
+        'git',
+        'ls',
+        'cat',
+        'head',
+        'tail',
+        'echo',
+        'pwd',
+        'npm test',
+        'npm run test',
+        'npx vitest',
+        'npx tsc',
+        'node -e',
+    ],
+    shellDeny: [
+        'rm -rf /',
+        'rm -rf ~',
+        'rm -rf .',
+        'del /f /s /q C:\\',
+        'format ',
+        'mkfs',
+        'dd if=',
+        ':(){:|:&};:',
+        'shutdown',
+        'reboot',
+        'bcdedit',
+    ],
+    readSizeAskMiB: 5,
+};
+/**
+ * Compose multiple rules. The first rule to return a Decision wins.
+ * If none return a Decision, the default is `allow`.
+ */
+export class PolicyEngine {
+    rules;
+    config;
+    constructor(rules, config = DEFAULT_POLICY_CONFIG) {
+        this.rules = rules;
+        this.config = config;
+    }
+    async evaluate(call, base) {
+        const ctx = {
+            cwd: base.cwd,
+            transcript: base.transcript,
+            nonInteractive: base.nonInteractive,
+            config: this.config,
+        };
+        for (const rule of this.rules) {
+            const d = rule.evaluate(call, ctx);
+            if (d)
+                return d;
+        }
+        return { action: 'allow' };
+    }
+}
+/** Builtin set of rules. Order matters: first match wins. */
+export function builtinRules() {
+    return [
+        shellDenyRule,
+        shellAllowRule,
+        writeFileCwdRule,
+        readFileSizeRule,
+    ];
+}
+function asString(v) {
+    return typeof v === 'string' ? v : '';
+}
+function startsWithAny(haystack, needles) {
+    const h = haystack.trim().toLowerCase();
+    return needles.some((n) => {
+        const nl = n.toLowerCase().replace(/\s+$/, ''); // strip trailing ws from needle
+        return h === nl || h.startsWith(nl + ' ') || h.startsWith(nl + '\t');
+    });
+}
+/** Hard-deny for obviously destructive shell patterns. */
+export const shellDenyRule = {
+    name: 'shell-deny',
+    evaluate(call, ctx) {
+        if (call.name !== 'shell_exec' && call.name !== 'run_verify')
+            return null;
+        const cmd = asString(call.input.command);
+        if (!cmd)
+            return null;
+        if (cmd.includes('..') && /rm|del/i.test(cmd) && /(\/|\b)([a-z]:)?[\\\/]\s*$|~|\/etc|\/usr|\/var|\/tmp/i.test(cmd)) {
+            return { action: 'deny', reason: 'destructive command targeting system path' };
+        }
+        if (startsWithAny(cmd, ctx.config.shellDeny)) {
+            return { action: 'deny', reason: `command matches deny list: ${cmd.slice(0, 60)}` };
+        }
+        // Pipe-to-shell: curl/wget/fetch piped into sh/bash/cmd.exe/PowerShell
+        if (/\b(curl|wget|fetch|iwr|Invoke-WebRequest)\b.*\|\s*(sh|bash|zsh|cmd|powershell|pwsh|node|node\s+-e)\b/i.test(cmd)) {
+            return { action: 'deny', reason: 'pipe-to-shell: remote download piped into an interpreter' };
+        }
+        return null;
+    },
+};
+/** Allowlist for shell — exact or prefix. Anything not in the list asks. */
+export const shellAllowRule = {
+    name: 'shell-allow',
+    evaluate(call, ctx) {
+        if (call.name !== 'shell_exec' && call.name !== 'run_verify')
+            return null;
+        const cmd = asString(call.input.command);
+        if (!cmd)
+            return null;
+        if (startsWithAny(cmd, ctx.config.shellAllow))
+            return { action: 'allow' };
+        if (ctx.nonInteractive)
+            return { action: 'deny', reason: `non-interactive: '${cmd.slice(0, 40)}' not in allowlist` };
+        return { action: 'ask', reason: `shell command not in allowlist: ${cmd.slice(0, 60)}` };
+    },
+};
+/** Writes are auto-allowed if path resolves inside cwd (path-guard throws otherwise). */
+export const writeFileCwdRule = {
+    name: 'write-file-cwd',
+    evaluate(call) {
+        if (call.name !== 'write_file' && call.name !== 'edit_file')
+            return null;
+        const p = asString(call.input.path);
+        if (!p)
+            return null;
+        if (p.includes('..') || path.isAbsolute(p)) {
+            return { action: 'deny', reason: 'path traversal or absolute path not allowed' };
+        }
+        return null;
+    },
+};
+/** Reads > 5 MiB require confirmation (avoid filling the context window). */
+export const readFileSizeRule = {
+    name: 'read-file-size',
+    evaluate(call, ctx) {
+        if (call.name !== 'read_file')
+            return null;
+        const size = typeof call.input.sizeBytes === 'number' ? call.input.sizeBytes : 0;
+        if (size > ctx.config.readSizeAskMiB * 1024 * 1024) {
+            if (ctx.nonInteractive)
+                return { action: 'deny', reason: `file > ${ctx.config.readSizeAskMiB} MiB` };
+            return { action: 'ask', reason: `file is ${(size / 1024 / 1024).toFixed(1)} MiB` };
+        }
+        return null;
+    },
+};
+/** Convenience: evaluate via safe() so a buggy rule doesn't crash the loop. */
+export async function evaluatePolicy(engine, call, ctx) {
+    const r = await safe(() => engine.evaluate(call, ctx));
+    if (r.ok)
+        return r.value;
+    return { action: 'deny', reason: `policy error: ${r.error.message}` };
+}
+// Late import to avoid a circular dep with policy -> tools via path-guard.
+// (path-guard is already in policy/, and tools/ depend on it. This keeps
+//  policy/ depending only on tools/normalize, no other tool code.)
+import * as path from 'node:path';

package/dist/policy/path-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Path safety: ensure every file path the agent touches stays inside `cwd`.
+ *
+ * Refuses:
+ *   - absolute paths outside cwd
+ *   - parent-directory traversal (`..`)
+ *   - symlinks that resolve outside cwd
+ *
+ * Uses `path.resolve` then `path.relative` to check. On Windows, the
+ * comparison is case-insensitive.
+ */
+import { type ToolErrorCode } from '../tools/normalize.js';
+export interface PathGuardResult {
+    /** Absolute, normalized path that IS inside cwd. */
+    resolved: string;
+}
+export declare class PathGuardError extends Error {
+    readonly code: ToolErrorCode;
+    constructor(code: ToolErrorCode, message: string);
+}
+/**
+ * Resolve a (possibly relative) path against cwd and assert it stays inside.
+ * Does NOT follow symlinks — call `resolveAndFollowSymlinks` for that.
+ */
+export declare function resolveWithinCwd(cwd: string, requested: string): PathGuardResult;
+/**
+ * Resolve, follow symlinks, and assert the target stays inside cwd.
+ * Use this for read_file / write_file to defeat symlink-based escapes.
+ */
+export declare function resolveAndFollowSymlinks(cwd: string, requested: string): Promise<PathGuardResult>;