@oxagen/cli 0.5.0 → 0.6.1

package/dist/agent/permissions.js

@@ -0,0 +1,245 @@
+/**
+ * The permission broker — the safety layer between the model and the host.
+ *
+ * Oxagen's coding tools (`write_file`, `edit_file`, `bash`) mutate the user's
+ * filesystem and run arbitrary shell commands. Until now they executed with no
+ * gate other than `--readonly` (which simply withholds them). That is fine for a
+ * developer dogfooding their own repo, but it blocks every unattended / shared /
+ * CI use case and offers no protection against a destructive command.
+ *
+ * This module adds a deterministic decision layer that every mutating tool call
+ * is routed through before it runs. It is intentionally framework-agnostic: the
+ * broker decides `allow` / `deny`, and the *interactive* part (asking the human)
+ * is a pluggable async {@link Approver} the REPL supplies. Non-interactive
+ * callers (one-shot, CI) simply omit the approver and get the mode's safe
+ * default.
+ *
+ * Decision order for a mutating call (most → least decisive):
+ *   1. `bypass` mode → allow (the user explicitly opted out of the safety layer).
+ *   2. First matching explicit rule (project/user/session) → allow | ask | deny.
+ *   3. A catastrophic command pattern → forced to `ask` (never silently allowed).
+ *   4. A write/edit outside the workspace root → forced to `ask`.
+ *   5. Mode default: `acceptEdits` auto-allows file edits (bash still asks);
+ *      `ask` asks for everything.
+ *   6. Resolve an `ask`: call the approver if present; otherwise `deny`.
+ */
+import { isAbsolute, relative, resolve } from "node:path";
+/** The tools that can change the host. Read/search tools are never gated. */
+export const MUTATING_TOOLS = ["write_file", "edit_file", "bash"];
+export function isMutatingTool(name) {
+    return MUTATING_TOOLS.includes(name);
+}
+/**
+ * Commands that can irreversibly destroy data or compromise the machine. A match
+ * never silently passes — it is forced to `ask` even under `acceptEdits`, so the
+ * human always sees it. (In `bypass` mode the user has opted out entirely.)
+ */
+const DANGEROUS_COMMAND = [
+    /\brm\s+(-[a-z]*\s+)*-[a-z]*r[a-z]*f|\brm\s+(-[a-z]*\s+)*-[a-z]*f[a-z]*r/i, // rm -rf / -fr
+    /\brm\s+-[a-z]*\s+\/(\s|$)/i, // rm -… /
+    /\b(mkfs|fdisk|parted)\b/i,
+    /\bdd\b[^|]*\bof=\/dev\//i,
+    /[>|]\s*\/dev\/(sd|nvme|disk|hd)/i,
+    /:\(\)\s*\{.*\};\s*:/, // fork bomb
+    /\bchmod\s+-R\s+777\s+\//i,
+    /\b(curl|wget)\b[^|&;]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/i, // curl … | sh
+    /\bgit\s+push\b[^&;]*--force\b[^&;]*\b(origin\s+)?(main|master)\b/i,
+    /\bsudo\s+rm\b/i,
+    /\b(shutdown|reboot|halt)\b/i,
+];
+function matchesDangerous(command) {
+    return DANGEROUS_COMMAND.some((re) => re.test(command));
+}
+/** Minimal glob → RegExp (mirrors the tools' matcher): `**` any, `*` segment, `?` one. */
+function globToRegExp(pattern) {
+    let re = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                re += ".*";
+                i++;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else if (".+^${}()|[]\\".includes(c)) {
+            re += "\\" + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp("^" + re + "$");
+}
+/**
+ * The string a rule's `pattern` is tested against. File rules match the path
+ * *relative to the workspace root* (so `src/**` works regardless of where the
+ * repo lives); bash rules match the raw command string.
+ */
+function subjectOf(req, cwd) {
+    if (req.tool === "bash")
+        return req.command ?? "";
+    return req.path ? relative(cwd, req.path) : "";
+}
+function ruleMatches(rule, req, cwd) {
+    if (rule.tool && rule.tool !== "*" && rule.tool !== req.tool)
+        return false;
+    if (rule.pattern) {
+        const subject = subjectOf(req, cwd);
+        // A command rule matches as a prefix or a glob; a path rule as a glob.
+        if (req.tool === "bash") {
+            if (!subject.startsWith(rule.pattern) && !globToRegExp(rule.pattern).test(subject))
+                return false;
+        }
+        else if (!globToRegExp(rule.pattern).test(subject)) {
+            return false;
+        }
+    }
+    return true;
+}
+/** True when an absolute path is not inside (or equal to) the workspace root. */
+export function isOutsideWorkspace(cwd, absPath) {
+    const rel = relative(resolve(cwd), resolve(absPath));
+    return rel === ".." || rel.startsWith(".." + "/") || isAbsolute(rel);
+}
+function summarize(req) {
+    if (req.tool === "bash")
+        return `Run: ${req.command ?? ""}`;
+    const verb = req.tool === "write_file" ? "Write" : "Edit";
+    const shown = req.path ? relative(req.cwd, req.path) || req.path : "(unknown path)";
+    return `${verb} ${shown}`;
+}
+/**
+ * The broker. Stateful only in that it accumulates session rules the human
+ * chooses to "remember"; everything else is a pure function of the request and
+ * the configured rules/mode.
+ */
+export class PermissionBroker {
+    mode;
+    cwd;
+    approver;
+    baseRules;
+    sessionRules = [];
+    constructor(opts) {
+        this.mode = opts.mode;
+        this.cwd = resolve(opts.cwd);
+        this.approver = opts.approver;
+        this.baseRules = opts.rules ?? [];
+    }
+    get currentMode() {
+        return this.mode;
+    }
+    /** Switch posture mid-session (drives the REPL `/mode` command). */
+    setMode(mode) {
+        this.mode = mode;
+    }
+    /** Rules in precedence order: remembered session rules first, then configured. */
+    rules() {
+        return [...this.sessionRules, ...this.baseRules];
+    }
+    /** Record a rule so an identical future call resolves the same way silently. */
+    remember(req, decision) {
+        const pattern = req.tool === "bash" ? (req.command ?? "") : (req.path ? relative(this.cwd, req.path) : undefined);
+        this.sessionRules.unshift({ tool: req.tool, pattern, decision });
+    }
+    /**
+     * Decide whether a mutating call may proceed. Never throws; an absent approver
+     * on an `ask` resolves to `deny` (fail closed). Returns the decision plus a
+     * human-readable reason (surfaced in the trace / tool result).
+     */
+    async check(req) {
+        // 1. Explicit opt-out — the user has accepted full responsibility.
+        if (this.mode === "bypass")
+            return { decision: "allow", reason: "bypass mode" };
+        // 2. Base decision: first matching rule, else the mode default.
+        let decision;
+        let reason;
+        const rule = this.rules().find((r) => ruleMatches(r, req, this.cwd));
+        if (rule) {
+            decision = rule.decision;
+            reason = `matched ${rule.decision} rule`;
+        }
+        else if (this.mode === "acceptEdits" && req.tool !== "bash") {
+            decision = "allow";
+            reason = "acceptEdits: file change auto-approved";
+        }
+        else {
+            decision = "ask";
+            reason = this.mode === "acceptEdits" ? "shell command needs approval" : "approval required";
+        }
+        // 3. Safety escalations downgrade an `allow` to `ask` so a catastrophic
+        //    command or a write outside the workspace is never run silently — even
+        //    when a broad allow rule would otherwise pass it. An explicit `deny`
+        //    still denies; bypass already returned above.
+        if (decision === "allow") {
+            if (req.tool === "bash" && req.command && matchesDangerous(req.command)) {
+                decision = "ask";
+                reason = "command matches a dangerous pattern";
+            }
+            else if (req.tool !== "bash" && req.path && isOutsideWorkspace(this.cwd, req.path)) {
+                decision = "ask";
+                reason = "writes outside the workspace root";
+            }
+        }
+        if (decision === "allow")
+            return { decision: "allow", reason };
+        if (decision === "deny")
+            return { decision: "deny", reason };
+        return this.ask(req, reason);
+    }
+    async ask(req, reason) {
+        if (!this.approver) {
+            // Fail closed: no human available to approve.
+            return { decision: "deny", reason: `${reason} (no approver — denied)` };
+        }
+        const response = await this.approver({ ...req, summary: summarize(req), reason });
+        if (response.remember)
+            this.remember(req, response.decision);
+        return {
+            decision: response.decision,
+            reason: response.decision === "allow" ? `approved (${reason})` : `denied by user (${reason})`,
+        };
+    }
+}
+/** Map a CLI flag set to a {@link PermissionMode}. `readonly` wins; then bypass. */
+export function resolveMode(opts) {
+    if (opts.readOnly)
+        return "readonly";
+    if (opts.bypass)
+        return "bypass";
+    if (opts.acceptEdits)
+        return "acceptEdits";
+    return "ask";
+}
+/** Accepted spellings for the `--mode` flag and the `/mode` command. */
+const MODE_ALIASES = {
+    ask: "ask",
+    "auto-edit": "acceptEdits",
+    "accept-edits": "acceptEdits",
+    acceptedits: "acceptEdits",
+    bypass: "bypass",
+    readonly: "readonly",
+    "read-only": "readonly",
+};
+/** Parse a user-supplied mode string to a {@link PermissionMode} (or undefined). */
+export function parseModeArg(s) {
+    return MODE_ALIASES[s.trim().toLowerCase()];
+}
+/** Build a normalized {@link PermissionRequest} from a raw tool call. */
+export function toRequest(tool, input, cwd) {
+    if (!isMutatingTool(tool))
+        return null;
+    const obj = (input ?? {});
+    if (tool === "bash") {
+        return { tool, command: typeof obj.command === "string" ? obj.command : "", cwd };
+    }
+    const p = typeof obj.path === "string" ? obj.path : "";
+    const abs = p ? (isAbsolute(p) ? p : resolve(cwd, p)) : "";
+    return { tool, path: abs, cwd };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/agent/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/agent/permissions.ts"],"names":[],"mappings":"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"}

package/dist/agent/pipeline.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The turn pipeline — what every user prompt flows through.
+ *
+ * This is the orchestrator that makes `oxagen` excellent at context and honest
+ * about completion. For each prompt it:
+ *
+ *   1. EVALUATE — a cheap model scores completeness + complexity and proposes
+ *      context to pull and a noise-removed rewrite.
+ *   2. ENHANCE  — the code graph + recalled lessons are injected, grounding the
+ *      agent in the real files/symbols involved.
+ *   3. ROUTE    — the Haiku evaluator's chosen tier selects the worker model
+ *      (cheapest tier for the job); a one-way deterministic safety floor only
+ *      prevents under-spending on high-stakes domains.
+ *   4. EXECUTE  — the coding agent runs the local tool loop.
+ *   5. JUDGE    — a DIFFERENT model (default: the most powerful OpenAI model)
+ *      checks whether the work is actually complete.
+ *   6. REVISE   — if it isn't, the agent is sent back with the judge's findings,
+ *      then re-judged, up to a bounded number of rounds.
+ *
+ * Every stage emits a {@link StageEvent} so the REPL can show the process live,
+ * and the whole thing is recorded as a {@link TurnTrace} for `/replay`. The
+ * pipeline degrades gracefully: any evaluator/judge model failure falls back to a
+ * heuristic, so a turn always runs.
+ */
+import type { ModelMessage } from "ai";
+import { MissingGatewayKeyError } from "./env.js";
+import type { ProjectContext } from "./project-context.js";
+import type { SessionMemory } from "./memory.js";
+import type { FleetMemory } from "./fleet/memory.js";
+import type { PermissionBroker } from "./permissions.js";
+import type { StageEvent, TurnTrace } from "./trace.js";
+export { MissingGatewayKeyError };
+export interface RunTurnOptions {
+    /** The user's prompt for this turn, exactly as typed. */
+    prompt: string;
+    /** Working directory the agent operates on (default: process.cwd()). */
+    cwd?: string;
+    /** Prior conversation messages (for multi-turn REPL sessions). */
+    history?: ModelMessage[];
+    /** Manual model override — pins the executor and skips auto-routing. */
+    model?: string;
+    /** Max tool-loop steps per execution round (default 32). */
+    maxSteps?: number;
+    /** Loaded project rules (CLAUDE.md/AGENTS.md). */
+    projectContext?: ProjectContext;
+    /** Read-only mode: no file mutation, and the auto-revise loop is disabled. */
+    readOnly?: boolean;
+    /** Permission broker gating mutating tools (absent ⇒ ungated). */
+    broker?: PermissionBroker;
+    /** Episodic session memory (recalled before, written after). */
+    memory?: SessionMemory | null;
+    /** Fleet memory for recalling/recording weighted lessons. */
+    fleetMemory?: FleetMemory | null;
+    /** Max judge→revise rounds (default 1; 0 disables auto-revision). */
+    maxReviseRounds?: number;
+    /** Skip the eval/enhance/judge pipeline and run the bare agent. */
+    bare?: boolean;
+    /**
+     * Capture full per-phase telemetry (timing, per-model token/cost breakdown,
+     * tool calls + results, the injected context) onto the trace, for `/verbose`.
+     */
+    verbose?: boolean;
+    /** Abort the turn (e.g. user hit Ctrl-C / Esc). */
+    signal?: AbortSignal;
+    /** Live stage events for the UI. */
+    onStage?: (e: StageEvent) => void;
+    /** Streamed assistant text deltas. */
+    onText?: (delta: string) => void;
+    /** Fired when the model invokes a tool. */
+    onToolCall?: (name: string, input: unknown) => void;
+}
+export interface RunTurnResult {
+    /** The agent's final assistant text (last execution round). */
+    text: string;
+    /** Tool-loop steps across all execution rounds. */
+    steps: number;
+    /** Full message history including this turn's assistant/tool messages. */
+    messages: ModelMessage[];
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    /** The full, persisted record of how this turn was handled. */
+    trace: TurnTrace;
+}
+/**
+ * Run one prompt through the full pipeline. Throws {@link MissingGatewayKeyError}
+ * if no gateway credential can be resolved; otherwise always produces a trace.
+ */
+export declare function runTurn(opts: RunTurnOptions): Promise<RunTurnResult>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/agent/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/agent/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,OAAO,EAAoB,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAYpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAKV,UAAU,EAEV,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAelC,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gEAAgE;IAChE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,sCAAsC;IACtC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E,+DAA+D;IAC/D,KAAK,EAAE,SAAS,CAAC;CAClB;AAmBD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAgL1E"}