agent-from-zero 0.5.0 → 0.27.0

package/dist/cost.js

@@ -0,0 +1,93 @@
+// Token & cost accounting. The most-emphasized lesson of the Harness book is
+// token economics: "cache breaks are silent", "90% of the bill is re-sending
+// the same prompt". You cannot manage what you cannot see — so every model
+// call's usage is metered, and /cost shows tokens, the cache hit rate, and an
+// estimated spend. Nothing here leaves the machine; it is just arithmetic over
+// the `usage` the API already returns.
+export const DEFAULT_PRICING = {
+    inputPerM: 0.27, // $ / 1M — check your provider; override in settings.pricing
+    cachedInputPerM: 0.07, // cache hits are ~4x cheaper — this is why hit rate matters
+    outputPerM: 1.1, // output is the pricey one — don't let the model ramble
+};
+// Normalize a provider `usage` object into our four fields. Handles DeepSeek
+// (prompt_cache_hit_tokens / prompt_cache_miss_tokens) and OpenAI
+// (prompt_tokens_details.cached_tokens) shapes; falls back gracefully.
+export function normalizeUsage(usage) {
+    if (!usage)
+        return { inputUncached: 0, inputCached: 0, output: 0 };
+    const prompt = Number(usage.prompt_tokens ?? 0); // total input tokens
+    const output = Number(usage.completion_tokens ?? 0); // total output tokens
+    // DeepSeek reports the split directly:
+    const dsHit = Number(usage.prompt_cache_hit_tokens ?? NaN);
+    const dsMiss = Number(usage.prompt_cache_miss_tokens ?? NaN);
+    if (!Number.isNaN(dsHit) && !Number.isNaN(dsMiss)) {
+        return { inputUncached: dsMiss, inputCached: dsHit, output };
+    }
+    // OpenAI reports only the cached count, nested:
+    const details = usage.prompt_tokens_details;
+    const cached = Number(details?.cached_tokens ?? 0);
+    return { inputUncached: Math.max(0, prompt - cached), inputCached: cached, output };
+}
+// Estimated dollar cost of some usage under some pricing. Pure — easy to test.
+export function costOf(u, p) {
+    return (u.inputUncached * p.inputPerM + u.inputCached * p.cachedInputPerM + u.output * p.outputPerM) / 1_000_000;
+}
+// Cache hit rate over input tokens, 0..1. The single most useful number for
+// spotting a silent cache break: if it drops, you are paying full price for a
+// prefix that should have been free.
+export function cacheHitRate(u) {
+    const input = u.inputUncached + u.inputCached;
+    return input === 0 ? 0 : u.inputCached / input;
+}
+// The process-wide meter. The loop records into it from every stream; the CLI
+// builds it once (with the configured prices) and /cost reads it. A module
+// singleton because metering is ambient — threading it through every call would
+// add noise for a cross-cutting concern. Tests construct their own CostMeter.
+let sessionMeter = null;
+export function initCostMeter(pricing) {
+    sessionMeter = new CostMeter(pricing);
+    return sessionMeter;
+}
+export function recordUsage(usage) {
+    sessionMeter?.record(usage); // no-op until the CLI initializes it (tests stay silent)
+}
+// Accumulates usage across a session and formats /cost.
+export class CostMeter {
+    pricing;
+    total = { inputUncached: 0, inputCached: 0, output: 0 };
+    calls = 0; // how many model calls were metered
+    constructor(pricing) {
+        this.pricing = pricing;
+    }
+    // Fold one response's usage into the running total.
+    record(usage) {
+        const u = normalizeUsage(usage);
+        if (u.inputUncached + u.inputCached + u.output === 0)
+            return; // a chunk with no usage — ignore
+        this.total.inputUncached += u.inputUncached;
+        this.total.inputCached += u.inputCached;
+        this.total.output += u.output;
+        this.calls++;
+    }
+    // Numbers for the status line: estimated spend so far and total tokens.
+    cost() {
+        return costOf(this.total, this.pricing);
+    }
+    inputTokens() {
+        return this.total.inputUncached + this.total.inputCached;
+    }
+    outputTokens() {
+        return this.total.output;
+    }
+    // The /cost report. Estimated, local-only.
+    report() {
+        const t = this.total;
+        const input = t.inputUncached + t.inputCached;
+        return [
+            `tokens this session (${this.calls} model calls):`,
+            `  input:  ${input} (${t.inputCached} cached, ${(cacheHitRate(t) * 100).toFixed(0)}% hit rate)`,
+            `  output: ${t.output}`,
+            `  estimated cost: $${costOf(t, this.pricing).toFixed(4)} (rough — prices set in settings.pricing)`,
+        ].join("\n");
+    }
+}

package/dist/diff.js

@@ -0,0 +1,135 @@
+import fs from "node:fs"; // read the target file to diff against
+import path from "node:path"; // resolve the file path
+import chalk from "chalk"; // color the +/- lines (auto-disabled when output isn't a TTY)
+// Longest-common-subsequence over lines → an ordered list of ops. Classic DP:
+// lcs[i][j] = length of the LCS of a[i:] and b[j:]. Walking it forwards turns the
+// table into the smallest set of removals + additions that turns a into b.
+export function diffLines(oldText, newText) {
+    const a = oldText.length ? oldText.split("\n") : []; // empty string = no lines (not [""])
+    const b = newText.length ? newText.split("\n") : [];
+    const n = a.length;
+    const m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0)); // (n+1)×(m+1), last row/col are zeros
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]); // match extends the subsequence; else take the better side
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j])
+            ops.push({ kind: " ", line: a[i++] }), j++; // common line — keep it as context
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            ops.push({ kind: "-", line: a[i++] }); // dropping a[i] keeps more of the LCS → it was removed
+        else
+            ops.push({ kind: "+", line: b[j++] }); // otherwise b[j] is an addition
+    }
+    while (i < n)
+        ops.push({ kind: "-", line: a[i++] }); // leftover old lines were all removed
+    while (j < m)
+        ops.push({ kind: "+", line: b[j++] }); // leftover new lines were all added
+    return ops;
+}
+const CONTEXT = 3; // unchanged lines to keep around each change, for readability
+const MAX_LINES = 60; // hard cap on rendered lines — a huge diff must not flood the prompt
+// Paint one line by its kind. chalk no-ops when colors are off, so the plain
+// text is always present (and assertable in tests).
+function paint(kind, text) {
+    if (kind === "+")
+        return chalk.green(text);
+    if (kind === "-")
+        return chalk.red(text);
+    return chalk.dim(text);
+}
+// Render ops as a compact unified diff: a "+A -B" summary header, the changed
+// lines with a few lines of context, and long runs of untouched lines collapsed
+// to a "⋮ (N unchanged lines)" marker so the reader sees the change, not the file.
+export function renderDiff(oldText, newText, color = true) {
+    const ops = diffLines(oldText, newText);
+    const added = ops.filter((o) => o.kind === "+").length;
+    const removed = ops.filter((o) => o.kind === "-").length;
+    // Keep any unchanged line within CONTEXT of a change; drop the rest.
+    const keep = new Array(ops.length).fill(false);
+    ops.forEach((op, idx) => {
+        if (op.kind === " ")
+            return;
+        for (let k = Math.max(0, idx - CONTEXT); k <= Math.min(ops.length - 1, idx + CONTEXT); k++)
+            keep[k] = true;
+    });
+    const out = [];
+    let i = 0;
+    while (i < ops.length) {
+        if (keep[i]) {
+            out.push(color ? paint(ops[i].kind, `${ops[i].kind} ${ops[i].line}`) : `${ops[i].kind} ${ops[i].line}`);
+            i++;
+        }
+        else {
+            let skipped = 0;
+            while (i < ops.length && !keep[i])
+                skipped++, i++; // collapse the whole untouched run at once
+            const note = `   ⋮ (${skipped} unchanged line${skipped === 1 ? "" : "s"})`;
+            out.push(color ? chalk.dim(note) : note);
+        }
+    }
+    const body = out.length > MAX_LINES ? [...out.slice(0, MAX_LINES), `   … (${out.length - MAX_LINES} more diff lines)`] : out;
+    const header = `  +${added} -${removed}`;
+    return [color ? chalk.dim(header) : header, ...body].join("\n");
+}
+const MAX_PREVIEW_BYTES = 200_000; // don't read+diff an enormous file just to preview it
+// Read a file for diffing, or null if it shouldn't be diffed (missing, too big,
+// or binary). A preview must never break a tool call, so every failure is null.
+function safeRead(p) {
+    try {
+        if (fs.statSync(p).size > MAX_PREVIEW_BYTES)
+            return null; // too big to preview cheaply
+        const text = fs.readFileSync(p, "utf8");
+        return text.includes("\0") ? null : text; // a NUL byte means binary — don't diff it
+    }
+    catch {
+        return null; // unreadable / missing
+    }
+}
+// Build the diff preview shown before a write/edit runs. Returns null when there
+// is nothing useful to show (not a write tool, unparseable args, binary file).
+// NEVER throws.
+export function previewChange(toolName, argsJson) {
+    let args;
+    try {
+        args = JSON.parse(argsJson);
+    }
+    catch {
+        return null; // dispatch will report the JSON error; nothing to preview
+    }
+    try {
+        if (toolName === "write_file") {
+            const p = path.resolve(args.path ?? "");
+            const exists = fs.existsSync(p);
+            const oldText = exists ? safeRead(p) : ""; // new file → empty "before"
+            if (oldText === null)
+                return null; // existing but binary/oversized
+            return `  ${exists ? "overwrite" : "create"} ${args.path}\n${renderDiff(oldText, String(args.content ?? ""))}`;
+        }
+        if (toolName === "edit_file") {
+            const p = path.resolve(args.path ?? "");
+            if (!fs.existsSync(p))
+                return null; // edit of a missing file → the tool will error
+            const oldText = safeRead(p);
+            if (oldText === null)
+                return null;
+            const occurrences = args.old_string ? oldText.split(args.old_string).length - 1 : 0;
+            // The tool only applies a unique match. If it's unique, diff the real
+            // before/after; otherwise just show the intended swap (the tool will
+            // reject a 0/ambiguous match anyway, but the human still sees the intent).
+            const newText = occurrences === 1 ? oldText.split(args.old_string).join(args.new_string ?? "") : null;
+            return newText !== null
+                ? `  edit ${args.path}\n${renderDiff(oldText, newText)}`
+                : `  edit ${args.path}\n${renderDiff(String(args.old_string ?? ""), String(args.new_string ?? ""))}`;
+        }
+    }
+    catch {
+        return null; // anything unexpected → no preview, never a crash
+    }
+    return null; // not a file-changing tool
+}

package/dist/form.js

@@ -0,0 +1,78 @@
+import chalk from "chalk"; // rendering only
+// The rows are a flat list: every option of every question, then one submit row.
+// rowCount = total options + 1. The cursor walks this flat list.
+export function formRowCount(questions) {
+    return questions.reduce((n, q) => n + q.options.length, 0) + 1; // +1 for "Submit"
+}
+// Map a flat cursor to either a question/option, or the submit row.
+export function rowAt(questions, cursor) {
+    let i = cursor;
+    for (let q = 0; q < questions.length; q++) {
+        if (i < questions[q].options.length)
+            return { q, opt: i };
+        i -= questions[q].options.length;
+    }
+    return { submit: true };
+}
+// The flat cursor position of a question's first option — used to jump the
+// cursor to the first unanswered question when the user tries to submit early.
+function cursorForQuestion(questions, q) {
+    let c = 0;
+    for (let i = 0; i < q; i++)
+        c += questions[i].options.length;
+    return c;
+}
+export function initFormState(questions) {
+    return { cursor: 0, selections: questions.map(() => -1) }; // nothing chosen yet
+}
+// The one transition function. Returns the next state, and `done: true` only
+// when the user submits with every question answered.
+export function reduceForm(questions, state, action) {
+    const rows = formRowCount(questions);
+    if (action === "up")
+        return { state: { ...state, cursor: Math.max(0, state.cursor - 1) } };
+    if (action === "down")
+        return { state: { ...state, cursor: Math.min(rows - 1, state.cursor + 1) } };
+    // select (Enter / Space)
+    const row = rowAt(questions, state.cursor);
+    if ("submit" in row) {
+        const firstUnanswered = state.selections.findIndex((s) => s < 0);
+        if (firstUnanswered < 0)
+            return { state, done: true }; // all answered → submit for real
+        return { state: { ...state, cursor: cursorForQuestion(questions, firstUnanswered) } }; // nudge to the gap
+    }
+    const selections = state.selections.slice();
+    selections[row.q] = row.opt; // set this question's answer (single-select)
+    return { state: { ...state, selections } };
+}
+// Turn a completed form into question→answer pairs for the model.
+export function collectAnswers(questions, state) {
+    return questions.map((q, i) => ({ question: q.question, answer: q.options[state.selections[i]] ?? "(unanswered)" }));
+}
+const FORM_HINT = chalk.dim("↑↓ to move · Enter to choose / submit · Esc to cancel");
+// Render the whole form: each question with radio-style options, the cursor on
+// one row, then a submit row. Line count is constant for a given question set
+// (selections don't add/remove lines), which is what lets the driver redraw in
+// place by moving the cursor up a fixed number of lines.
+export function renderForm(questions, state) {
+    const lines = ["The agent needs your input:", ""];
+    let flat = 0;
+    questions.forEach((q, qi) => {
+        lines.push(chalk.bold(`${qi + 1}. ${q.question}`));
+        q.options.forEach((opt, oi) => {
+            const onCursor = state.cursor === flat;
+            const chosen = state.selections[qi] === oi;
+            const text = `${chosen ? "●" : "○"} ${opt}`; // filled radio = chosen
+            lines.push(onCursor ? chalk.cyan.bold(`❯ ${text}`) : chosen ? chalk.cyan(`  ${text}`) : chalk.dim(`  ${text}`));
+            flat++;
+        });
+        lines.push("");
+    });
+    const onSubmit = state.cursor === flat; // the submit row is last
+    const allAnswered = state.selections.every((s) => s >= 0);
+    const submitText = allAnswered ? "▶ Submit answers" : "▶ Submit answers (answer every question first)";
+    lines.push(onSubmit ? chalk.green.bold(`❯ ${submitText}`) : chalk.dim(`  ${submitText}`));
+    lines.push("");
+    lines.push(FORM_HINT);
+    return lines.join("\n");
+}

package/dist/hooks.js

@@ -10,13 +10,21 @@ import { emit } from "./telemetry.js"; // count hook activity
 // logic on via hooks" architecture.
 //
 // Communication protocol (per event):
-//   exit 0  → allow. stdout is shown to the model only for SessionStart.
-//   exit 2  → block. stderr is fed back to the model as the reason.
+//   exit 0  → allow. stdout is captured (SessionStart/UserPromptSubmit inject it
+//             as context; a PreToolUse hook may emit {"toolInput":{…}} to REWRITE
+//             the tool's arguments — something the 3-state permission gate can't).
+//   exit 2  → block. stderr is fed back to the model. The MEANING of "block"
+//             differs by event and is the caller's to interpret (PreToolUse →
+//             don't run; Stop → keep going; UserPromptSubmit → drop the prompt;
+//             observational events just ignore it).
 //   other   → the hook itself errored; we log and treat it as allow (a broken
 //             hook must not wedge the agent — but it is loud, not silent).
-const DEFAULT_HOOK_TIMEOUT_MS = 10_000; // a hook gets 10s, then we kill it
+const DEFAULT_HOOK_TIMEOUT_MS = 10_000; // most hooks get 10s, then we kill it
+// Differentiated timeouts: SessionEnd fires when the user is leaving (often via
+// Ctrl+C) — it MUST return almost instantly, so it gets a tiny budget.
+const EVENT_TIMEOUT_MS = { SessionEnd: 1_500 };
 // Run one hook process, feeding it the event payload on stdin.
-function runOne(hook, payload) {
+function runOne(hook, payload, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawn(hook.command, { shell: true, stdio: ["pipe", "pipe", "pipe"] }); // shell so users can write one-liners
         let stdout = "", stderr = "", settled = false; // accumulate; resolve once
@@ -30,7 +38,7 @@ function runOne(hook, payload) {
         const timer = setTimeout(() => {
             child.kill("SIGKILL"); // a hung hook is killed, never hangs the agent
             done(124); // 124 = timed out (treated as "other" → allow, logged)
-        }, hook.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS);
+        }, hook.timeoutMs ?? timeoutMs);
         child.stdout.on("data", (d) => (stdout += d));
         child.stderr.on("data", (d) => (stderr += d));
         child.on("error", () => done(127)); // could not start (e.g. command not found)
@@ -47,12 +55,29 @@ export async function runHooks(event, payload) {
     const feedback = []; // stderr from blocking hooks
     const stdout = []; // stdout from passing hooks
     let block = false; // did any hook exit 2?
+    let rewrite; // a PreToolUse hook's replacement args
+    const timeout = EVENT_TIMEOUT_MS[event] ?? DEFAULT_HOOK_TIMEOUT_MS; // SessionEnd gets a tiny budget
     for (const hook of hooks) {
-        const { code, stdout: out, stderr: err } = await runOne(hook, { event, ...payload }); // run it
+        const { code, stdout: out, stderr: err } = await runOne(hook, { event, ...payload }, timeout); // run it
         emit("agent_hook_run", { event, code }); // observability for hooks themselves
         if (code === 0) {
-            if (out)
-                stdout.push(out); // passing-hook output (used by SessionStart)
+            if (out) {
+                stdout.push(out); // passing-hook output (used by SessionStart / UserPromptSubmit)
+                // A PreToolUse hook can REWRITE the tool's arguments by printing
+                // {"toolInput": {...}} — the "side road" the permission gate can't take
+                // (it only allows/denies). Classic use: rewrite `git commit` to add a
+                // trailer. Last writer wins if several hooks rewrite.
+                if (event === "PreToolUse") {
+                    try {
+                        const parsed = JSON.parse(out);
+                        if (parsed && parsed.toolInput && typeof parsed.toolInput === "object")
+                            rewrite = JSON.stringify(parsed.toolInput);
+                    }
+                    catch {
+                        /* not control JSON — just plain stdout */
+                    }
+                }
+            }
         }
         else if (code === 2) {
             block = true; // a blocking verdict
@@ -63,5 +88,5 @@ export async function runHooks(event, payload) {
             console.error(chalk.yellow(`  [hook] ${event} command exited ${code} (ignored): ${(err || out).slice(0, 120)}`));
         }
     }
-    return { block, feedback: feedback.join("\n"), stdout: stdout.join("\n") };
+    return { block, feedback: feedback.join("\n"), stdout: stdout.join("\n"), rewrite };
 }

package/dist/judge.js

@@ -0,0 +1,77 @@
+import { emit } from "./telemetry.js"; // observe the judge's decisions
+// An OPTIONAL second layer over the rule-based permission gate. The rules
+// (permissions.ts) own deny and the obvious allows; whatever they mark "ask"
+// is the ambiguous middle — an unfamiliar-but-maybe-harmless command like
+// `ffmpeg ...`. Asking the human about every one of those is approval fatigue.
+//
+// The judge looks ONLY at those "ask" verdicts and answers one question: is
+// this clearly safe? If yes, we skip the prompt; if no (or it is unsure, or it
+// errors), we keep asking. Two invariants make this safe to add:
+//   1. The judge NEVER sees a deny — deny always wins, the rules decide it.
+//   2. The judge can only DOWNGRADE ask→allow for the clearly safe. It can
+//      never create an allow the rules denied, and any doubt stays "ask".
+// In other words: the judge reduces friction, it never reduces safety.
+// The judge prompt is deliberately blunt and asks for a single rigid token, so
+// parsing is unambiguous. "Err on the side of NO" is the load-bearing line.
+const JUDGE_SYSTEM = `You are a security classifier for a coding agent. You are shown ONE shell command that the agent wants to run. Decide whether it is CLEARLY SAFE to run without asking a human.
+
+CLEARLY SAFE = read-only or trivially reversible, no data loss, no network exfiltration, no privilege change, no writes outside the project, no credential access.
+NOT clearly safe = anything that deletes, overwrites, installs, pushes, sends data out, changes permissions, or that you are unsure about.
+
+Err strongly on the side of NO. When in doubt, answer no.
+Respond with EXACTLY one line and nothing else: <safe>yes</safe> or <safe>no</safe>`;
+const JUDGE_MAX_TOKENS = 16; // we only need one tiny tagged token — keep it cheap and fast
+const MAX_CONSECUTIVE_JUDGE_ERRORS = 3; // after this many failures, disable the judge for the session
+// Parse the judge's reply. PURE function (no I/O) so the safety logic is unit
+// testable without the network. Fail closed: anything that is not an
+// unambiguous "yes" means "ask".
+export function interpretJudgeOutput(text) {
+    const m = text.toLowerCase().match(/<safe>\s*(yes|no)\s*<\/safe>/); // strict tag, nothing else trusted
+    if (!m)
+        return "ask"; // no clean verdict → ask (fail closed)
+    return m[1] === "yes" ? "allow" : "ask"; // only a clear yes downgrades
+}
+// Tracks the judge's health across a session so a flaky/misconfigured judge
+// degrades gracefully to "always ask" instead of silently failing on every call.
+export class Judge {
+    client;
+    model;
+    consecutiveErrors = 0; // resets on any successful classification
+    disabled = false; // tripped after too many consecutive errors
+    constructor(client, // same client as the loop
+    model) {
+        this.client = client;
+        this.model = model;
+    }
+    // Classify one "ask" command. Returns "allow" only when the judge is
+    // confident it is safe; "ask" in every other case (unsure, error, disabled).
+    async classify(command) {
+        if (this.disabled)
+            return "ask"; // circuit breaker tripped — back to asking
+        try {
+            const res = await this.client.chat.completions.create({
+                model: this.model,
+                max_tokens: JUDGE_MAX_TOKENS, // tiny — this must be cheap
+                temperature: 0, // deterministic classification
+                messages: [
+                    { role: "system", content: JUDGE_SYSTEM },
+                    { role: "user", content: `Command:\n${command}` }, // ONLY the command — no chat history to be injected through
+                ],
+            });
+            this.consecutiveErrors = 0; // a clean call resets the breaker
+            const verdict = interpretJudgeOutput(res.choices[0]?.message?.content ?? "");
+            emit("agent_judge_verdict", { verdict }); // allow / ask, for tuning
+            return verdict;
+        }
+        catch {
+            // A judge that errors must never accidentally allow something. Count the
+            // failure, and after a few in a row, stop trying (degrade to asking).
+            this.consecutiveErrors++;
+            if (this.consecutiveErrors >= MAX_CONSECUTIVE_JUDGE_ERRORS) {
+                this.disabled = true;
+                emit("agent_judge_disabled", {}); // we gave up on the judge this session
+            }
+            return "ask"; // fail closed
+        }
+    }
+}