kritya 0.8.2-beta

package/dist/atomicWrite.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+/**
+ * Write a file without ever leaving a truncated one behind.
+ *
+ * `fs.writeFile` to the target truncates it first and then fills it back in.
+ * Anything that interrupts the gap — a crash, a kill switch, a power cut, a
+ * full disk partway through a large file — leaves the user's source file
+ * destroyed, with the original recoverable only from the in-memory undo stack
+ * of the process that just died. Writing a sibling temp file and renaming it
+ * over the target closes that window: rename is a single filesystem metadata
+ * operation, so a reader sees either the whole old file or the whole new one.
+ *
+ * Three details this has to get right that a bare rename does not:
+ *
+ *  - **Symlinks.** `fs.writeFile` follows them and writes through to the
+ *    target; a rename would replace the link itself. The real path is
+ *    resolved first so the observable behavior is unchanged.
+ *  - **Permissions.** A renamed-in file carries the temp file's mode, not the
+ *    original's, which would silently strip the executable bit off a script.
+ *    The existing mode is copied across before the rename.
+ *  - **Windows.** A rename onto a file another process holds open (an editor,
+ *    an indexer, antivirus) fails with EPERM/EBUSY where a plain write would
+ *    have succeeded. That must not turn a working write into an error, so it
+ *    falls back to writing in place — no worse than the old behavior, and only
+ *    on the paths where the old behavior was the only option.
+ *
+ * Durability is deliberately not part of the contract: there is no fsync, so a
+ * power loss can still lose a just-written file on some filesystems. The
+ * hazard being closed here is truncation, which is both far likelier and far
+ * more destructive, and fsync on every edit is a cost every write would pay.
+ */
+/** Codes that mean "the target is locked", not "the write is wrong". */
+const RENAME_FALLBACK_CODES = new Set(["EPERM", "EACCES", "EBUSY", "EEXIST", "ENOTEMPTY"]);
+function tempPathFor(filePath) {
+    const unique = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${unique}`);
+}
+/** Resolve symlinks so we replace what the path points at, not the link. */
+function resolveTarget(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch {
+        return filePath; // doesn't exist yet — nothing to follow
+    }
+}
+/** The mode to give the replacement, when the file already exists. */
+function existingMode(filePath) {
+    try {
+        return fs.statSync(filePath).mode & 0o777;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeFileAtomic(filePath, data, options = {}) {
+    const target = resolveTarget(filePath);
+    const mode = options.mode ?? existingMode(target);
+    const tmp = tempPathFor(target);
+    try {
+        await fsp.writeFile(tmp, data, options.encoding ?? (typeof data === "string" ? "utf8" : null));
+        if (mode !== undefined)
+            await fsp.chmod(tmp, mode);
+        await fsp.rename(tmp, target);
+    }
+    catch (err) {
+        await fsp.rm(tmp, { force: true }).catch(() => { });
+        if (!isRenameFallback(err))
+            throw err;
+        await fsp.writeFile(filePath, data, options.encoding ?? (typeof data === "string" ? "utf8" : null));
+    }
+}
+export function writeFileAtomicSync(filePath, data, options = {}) {
+    const target = resolveTarget(filePath);
+    const mode = options.mode ?? existingMode(target);
+    const tmp = tempPathFor(target);
+    try {
+        fs.writeFileSync(tmp, data, {
+            ...(options.encoding ? { encoding: options.encoding } : {}),
+            ...(mode !== undefined ? { mode } : {}),
+        });
+        // writeFileSync's `mode` only applies when it creates the file, and umask
+        // can mask bits off it — set it explicitly so the replacement really does
+        // carry the original's permissions.
+        if (mode !== undefined)
+            fs.chmodSync(tmp, mode);
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing more to do; the write result below is what matters.
+        }
+        if (!isRenameFallback(err))
+            throw err;
+        fs.writeFileSync(filePath, data, {
+            ...(options.encoding ? { encoding: options.encoding } : {}),
+            ...(mode !== undefined ? { mode } : {}),
+        });
+    }
+}
+function isRenameFallback(err) {
+    const code = err?.code;
+    return !!code && RENAME_FALLBACK_CODES.has(code);
+}

package/dist/audit/audit.js

@@ -0,0 +1,230 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR } from "../config/config.js";
+import { hardenWindowsDir } from "../config/winAcl.js";
+import { debugLog } from "../config/debug.js";
+const GENESIS = "0".repeat(64);
+/**
+ * Where all audit logs live, across every workspace (not scoped per-project).
+ * KRITYA_AUDIT_DIR overrides it — used by tests so cleanupOld's directory
+ * scan (and any future directory-wide operation) never touches the real
+ * ~/.kritya/audit on a dev machine.
+ */
+export function auditDir() {
+    return process.env.KRITYA_AUDIT_DIR || path.join(CONFIG_DIR, "audit");
+}
+/**
+ * Resolve where audit logs are written for this session, honoring an explicit
+ * override. Kept separate so tests can point it at a temp dir.
+ */
+function defaultAuditFile(sessionId) {
+    const override = process.env.KRITYA_AUDIT_FILE;
+    if (override)
+        return override;
+    return path.join(auditDir(), `${sessionId}.audit.jsonl`);
+}
+export class AuditLog {
+    sessionId;
+    file;
+    seq = 0;
+    prevHash = GENESIS;
+    ready = false;
+    constructor(sessionId, file = defaultAuditFile(sessionId)) {
+        this.sessionId = sessionId;
+        this.file = file;
+    }
+    /** Where this session's records are written, for callers that report it. */
+    get path() {
+        return this.file;
+    }
+    /**
+     * Off by default only when explicitly disabled; auditing is on otherwise so
+     * the trail exists without anyone having to opt in. Returns undefined when
+     * disabled so callers can leave `agent.audit` unset.
+     *
+     * `configDefault` is config.json's persisted `audit` setting, so a user can
+     * turn auditing off for good without exporting KRITYA_AUDIT every launch —
+     * the env var still wins over it when set, for a one-off override.
+     */
+    static forSession(sessionId, configDefault) {
+        const envVal = (process.env.KRITYA_AUDIT ?? "").toLowerCase();
+        const disabled = envVal ? envVal === "off" : configDefault === "off";
+        if (disabled)
+            return undefined;
+        return new AuditLog(sessionId);
+    }
+    /**
+     * Delete audit log files older than `retentionDays`. Best-effort, same
+     * pattern as SessionStore.cleanupOldSessions. 0 or negative means "keep
+     * forever" — auto-delete is disabled, not an immediate-expiry window.
+     */
+    static cleanupOld(retentionDays) {
+        if (retentionDays <= 0)
+            return;
+        const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+        let files;
+        try {
+            files = fs.readdirSync(auditDir()).filter((f) => f.endsWith(".audit.jsonl"));
+        }
+        catch {
+            return;
+        }
+        for (const f of files) {
+            const file = path.join(auditDir(), f);
+            try {
+                if (fs.statSync(file).mtimeMs < cutoff)
+                    fs.unlinkSync(file);
+            }
+            catch (err) {
+                debugLog(`AuditLog.cleanupOld(${file})`, err);
+            }
+        }
+    }
+    logPermission(entry) {
+        this.write({ event: "permission", ...entry });
+    }
+    logTool(entry) {
+        this.write({ event: "tool", ...entry });
+    }
+    write(partial) {
+        // Best-effort, exactly like SessionStore.append: an audit failure must
+        // never crash a turn. A dropped record is preferable to a broken agent.
+        try {
+            this.ensureDir();
+            const base = {
+                ts: new Date().toISOString(),
+                seq: this.seq++,
+                sessionId: this.sessionId,
+                ...partial,
+            };
+            const hash = crypto
+                .createHash("sha256")
+                .update(this.prevHash + JSON.stringify(base))
+                .digest("hex");
+            const record = { ...base, prevHash: this.prevHash, hash };
+            fs.appendFileSync(this.file, JSON.stringify(record) + "\n", { mode: 0o600 });
+            this.prevHash = hash;
+        }
+        catch (err) {
+            // best-effort
+            debugLog(`AuditLog.write(${this.file})`, err);
+        }
+    }
+    ensureDir() {
+        if (this.ready)
+            return;
+        fs.mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        hardenWindowsDir(auditDir());
+        this.ready = true;
+    }
+    /**
+     * Every valid record in a written audit file, in order. Corrupt lines are
+     * skipped (mirrors SessionStore's tolerance for a truncated last line), so
+     * this is for display purposes — use verify() to confirm the file wasn't
+     * silently altered.
+     */
+    static readRecords(file) {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return [];
+        }
+        const records = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch {
+                // skip corrupt lines
+            }
+        }
+        return records;
+    }
+    /**
+     * Re-walk a written audit file and confirm the hash chain is intact.
+     *
+     * Deliberately distinguishes "the file doesn't exist / can't be read" from
+     * "the chain verifies clean" — collapsing those two cases (as an earlier
+     * version of this method did, both returning -1) means deleting the whole
+     * audit log would report the same as an untampered one, which is the
+     * easiest way to defeat a tamper-evident log: don't edit it, remove it.
+     */
+    static verify(file) {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return { ok: false, reason: "unreadable" };
+        }
+        const lines = raw.split("\n").filter((l) => l.trim());
+        let prevHash = GENESIS;
+        for (let i = 0; i < lines.length; i++) {
+            let rec;
+            try {
+                rec = JSON.parse(lines[i]);
+            }
+            catch {
+                return { ok: false, reason: "tampered", line: i };
+            }
+            const { hash, prevHash: recPrev, ...base } = rec;
+            if (recPrev !== prevHash)
+                return { ok: false, reason: "tampered", line: i };
+            const expected = crypto
+                .createHash("sha256")
+                .update(prevHash + JSON.stringify(base))
+                .digest("hex");
+            if (expected !== hash)
+                return { ok: false, reason: "tampered", line: i };
+            prevHash = hash;
+        }
+        return { ok: true, records: lines.length };
+    }
+}
+/** Sorted-array percentile (nearest-rank). Returns 0 for an empty array. */
+function percentile(sortedValues, p) {
+    if (!sortedValues.length)
+        return 0;
+    const idx = Math.min(sortedValues.length - 1, Math.ceil((p / 100) * sortedValues.length) - 1);
+    return sortedValues[Math.max(0, idx)];
+}
+/**
+ * A one-shot statistical rollup of an audit log — counts and latency
+ * percentiles — computed on demand from the existing records rather than
+ * persisted as its own record, so there's nothing new to keep in sync with
+ * the hash chain. Used by `/audit` and `kritya audit --summary`.
+ */
+export function summarizeAudit(records) {
+    const toolCallsByOutcome = {};
+    const permissionsBySource = {};
+    const durations = [];
+    const waits = [];
+    for (const r of records) {
+        if (r.event === "tool") {
+            toolCallsByOutcome[r.outcome] = (toolCallsByOutcome[r.outcome] ?? 0) + 1;
+            if (r.outcome === "ok" && typeof r.durationMs === "number")
+                durations.push(r.durationMs);
+            if (typeof r.waitMs === "number")
+                waits.push(r.waitMs);
+        }
+        else {
+            permissionsBySource[r.source] = (permissionsBySource[r.source] ?? 0) + 1;
+        }
+    }
+    durations.sort((a, b) => a - b);
+    waits.sort((a, b) => a - b);
+    return {
+        totalRecords: records.length,
+        toolCallsByOutcome,
+        permissionsBySource,
+        durationMsP50: percentile(durations, 50),
+        durationMsP95: percentile(durations, 95),
+        waitMsP50: percentile(waits, 50),
+        waitMsP95: percentile(waits, 95),
+    };
+}

package/dist/audit/cli.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AuditLog, auditDir, summarizeAudit } from "./audit.js";
+import { loadConfig } from "../config/config.js";
+import { retentionDaysFor, DEFAULT_RETENTION_DAYS } from "../config/retention.js";
+export const AUDIT_USAGE = `kritya audit — inspect the local, tamper-evident audit log
+
+Usage:
+  kritya audit --list                list recent audit log files, newest first
+  kritya audit --verify [file]       check a log's hash chain is intact
+                                      (defaults to the most recent log)
+  kritya audit --show [file]         print a log's records, one JSON line each
+                                      (defaults to the most recent log)
+  kritya audit --summary [file]      counts and latency percentiles for a log
+                                      (defaults to the most recent log)
+  kritya audit --prune [days]        delete audit logs older than [days]
+                                      (defaults to your configured retention,
+                                      currently ${DEFAULT_RETENTION_DAYS} unless set in config.json)
+
+Audit logs live under ~/.kritya/audit/<session>.audit.jsonl — see the
+"Audit log & telemetry" section of the README for what gets recorded, and for
+how to set retentionDays / audit / otel in ~/.kritya/config.json.`;
+function listAuditFiles() {
+    let names;
+    try {
+        names = fs.readdirSync(auditDir()).filter((f) => f.endsWith(".audit.jsonl"));
+    }
+    catch {
+        return [];
+    }
+    return names.map((f) => path.join(auditDir(), f)).sort((a, b) => statMtime(b) - statMtime(a));
+}
+function statMtime(file) {
+    try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Resolves a --verify/--show argument (bare filename, absolute path, or omitted) to a full path. */
+function resolveFile(arg) {
+    if (!arg)
+        return listAuditFiles()[0];
+    return path.isAbsolute(arg) ? arg : path.join(auditDir(), arg);
+}
+function describeVerify(file) {
+    const result = AuditLog.verify(file);
+    if (result.ok)
+        return `${result.records} record(s), chain intact`;
+    if (result.reason === "unreadable")
+        return "FAILED — file could not be read";
+    return `FAILED — chain broken at record ${result.line}`;
+}
+/** Handles `kritya audit ...`. Returns the process exit code. */
+export function runAuditCli(argv) {
+    if (argv.includes("--list")) {
+        const files = listAuditFiles();
+        if (!files.length) {
+            console.log(`No audit logs found under ${auditDir()}`);
+            return 0;
+        }
+        for (const file of files) {
+            console.log(`${path.basename(file)}  —  ${describeVerify(file)}`);
+        }
+        return 0;
+    }
+    const verifyIdx = argv.indexOf("--verify");
+    if (verifyIdx !== -1) {
+        const next = argv[verifyIdx + 1];
+        const file = resolveFile(next && !next.startsWith("--") ? next : undefined);
+        if (!file) {
+            console.error(`No audit log found under ${auditDir()}`);
+            return 1;
+        }
+        const result = AuditLog.verify(file);
+        console.log(`${file}\n${describeVerify(file)}`);
+        return result.ok ? 0 : 1;
+    }
+    const showIdx = argv.indexOf("--show");
+    if (showIdx !== -1) {
+        const next = argv[showIdx + 1];
+        const file = resolveFile(next && !next.startsWith("--") ? next : undefined);
+        if (!file) {
+            console.error(`No audit log found under ${auditDir()}`);
+            return 1;
+        }
+        for (const record of AuditLog.readRecords(file)) {
+            console.log(JSON.stringify(record));
+        }
+        return 0;
+    }
+    const summaryIdx = argv.indexOf("--summary");
+    if (summaryIdx !== -1) {
+        const next = argv[summaryIdx + 1];
+        const file = resolveFile(next && !next.startsWith("--") ? next : undefined);
+        if (!file) {
+            console.error(`No audit log found under ${auditDir()}`);
+            return 1;
+        }
+        const s = summarizeAudit(AuditLog.readRecords(file));
+        console.log(`${file}`);
+        console.log(`${s.totalRecords} record(s)`);
+        console.log(`Permission decisions by source: ${fmtCounts(s.permissionsBySource)}`);
+        console.log(`Tool outcomes: ${fmtCounts(s.toolCallsByOutcome)}`);
+        console.log(`Tool latency: p50 ${s.durationMsP50}ms / p95 ${s.durationMsP95}ms`);
+        console.log(`Permission wait: p50 ${s.waitMsP50}ms / p95 ${s.waitMsP95}ms`);
+        return 0;
+    }
+    if (argv.includes("--prune")) {
+        const idx = argv.indexOf("--prune");
+        const next = argv[idx + 1];
+        const explicitDays = next && !next.startsWith("--") ? Number(next) : undefined;
+        const days = explicitDays !== undefined && Number.isFinite(explicitDays)
+            ? explicitDays
+            : retentionDaysFor(loadConfig());
+        if (days <= 0) {
+            console.log("Retention is disabled (0 or negative) — nothing pruned. Pass a positive number of days.");
+            return 0;
+        }
+        const before = listAuditFiles().length;
+        AuditLog.cleanupOld(days);
+        const after = listAuditFiles().length;
+        console.log(`Pruned ${before - after} audit log(s) older than ${days} day(s).`);
+        return 0;
+    }
+    console.log(AUDIT_USAGE);
+    return 0;
+}
+function fmtCounts(m) {
+    return (Object.entries(m)
+        .sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ") || "(none)");
+}

package/dist/commands/custom.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR } from "../config/config.js";
+import { debugLog } from "../config/debug.js";
+function readCommandsFrom(dir) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    const commands = [];
+    for (const file of files) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, file), "utf8");
+            const name = "/" + path.basename(file, ".md");
+            const { description, body } = parseCommand(raw);
+            commands.push({ name, description, body });
+        }
+        catch (err) {
+            // Skip unreadable command files.
+            debugLog(`readCommandsFrom(${path.join(dir, file)})`, err);
+        }
+    }
+    return commands;
+}
+/** Extract an optional `description:` front-matter-ish first line. */
+function parseCommand(raw) {
+    const lines = raw.split("\n");
+    const first = lines[0]?.trim() ?? "";
+    const m = /^(?:<!--\s*)?description:\s*(.+?)(?:\s*-->)?$/i.exec(first);
+    if (m) {
+        return { description: m[1].trim(), body: lines.slice(1).join("\n").trim() };
+    }
+    return { description: "custom command", body: raw.trim() };
+}
+/**
+ * Load custom commands; workspace entries override plugin entries, which
+ * override global ones, by name. Workspace and plugin commands are
+ * attacker-controllable prompts (a plugin can be dropped into a cloned repo
+ * just like a .kritya/commands file), so both are only loaded once the
+ * workspace has been trusted (see src/trust/trust.ts); global
+ * (~/.kritya/commands/) commands are always trusted.
+ */
+export function loadCustomCommands(workspace, trustWorkspace = true, plugins = []) {
+    const byName = new Map();
+    for (const cmd of readCommandsFrom(path.join(CONFIG_DIR, "commands"))) {
+        byName.set(cmd.name, cmd);
+    }
+    if (trustWorkspace) {
+        for (const plugin of plugins) {
+            for (const cmd of readCommandsFrom(path.join(plugin.dir, "commands"))) {
+                byName.set(cmd.name, { ...cmd, pluginName: plugin.name });
+            }
+        }
+        for (const cmd of readCommandsFrom(path.join(workspace, ".kritya", "commands"))) {
+            byName.set(cmd.name, cmd);
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Substitute the user's arguments into a command body. */
+export function expandCommand(body, args) {
+    if (!/\$ARGUMENTS|\{\{args\}\}/.test(body)) {
+        return args ? `${body}\n\n${args}` : body;
+    }
+    return body.replace(/\$ARGUMENTS|\{\{args\}\}/g, args);
+}