atom-agent 0.3.0 → 1.1.0

package/dist/policy.js

@@ -0,0 +1,286 @@
+// Policy / Security layer: explicit trust boundaries for a powerful local
+// coding agent. Filesystem access and shell execution are INTENTIONAL
+// capabilities (never silently removed); this module makes the decisions
+// governing them explicit, testable, and centralized:
+//
+//   Tool request → decidePolicy() → approval if needed → execution
+//
+// Pure module (no I/O except injected resolvers, no UI): the App owns prompts
+// and side effects, tools own execution. Covers three surfaces:
+//
+// 1. Approval decisions — one ordered rule (deny → plan → allow → yolo →
+//    trust → always → skill grants → prompt) replacing the previously inline
+//    if-chain in App.approve. Same order, same outcomes, now unit-tested.
+// 2. Skill-grant trust — project-local skill content is untrusted: only
+//    global (user-controlled) skills may arm turn-scoped tool grants.
+//    Project skills never silently escalate to shell/filesystem/network.
+// 3. Network zones + policy — SSRF surface for webfetch: every URL (initial
+//    and every redirect hop) classifies into public/localhost/private/
+//    link-local/blocked, gated by an explicit configurable policy.
+// 4. Secret scrubbing — shell outputs pass through scrubSecrets so a pasted
+//    or env-provided provider key echoed by a command never rides back to
+//    the model (and into saved transcripts) verbatim.
+import { checkRules } from "./permissions.js";
+export function decidePolicy(name, args, ctx) {
+    const verdict = checkRules(ctx.rules, name, args);
+    // Deny wins over everything, including plan mode.
+    if (verdict === "deny")
+        return { kind: "deny" };
+    // Plan mode is read-only: mutations skip the prompt and flow to the
+    // execute gate, which refuses them pre-execution with a replan note.
+    if (ctx.mode === "plan" && ctx.approvalGated) {
+        return { kind: "allow", via: "plan-passthrough" };
+    }
+    if (verdict === "allow")
+        return { kind: "allow", via: "allow-rule" };
+    if (ctx.mode === "yolo")
+        return { kind: "allow", via: "yolo" };
+    if (ctx.trustAll)
+        return { kind: "allow", via: "trust" };
+    if (ctx.alwaysAllowed.has(name))
+        return { kind: "allow", via: "always" };
+    if (ctx.skillGrants.has(name))
+        return { kind: "allow", via: "skill-grant" };
+    return { kind: "prompt" };
+}
+// ---- 2. Skill-grant trust boundary ----
+// Approval-gated tools: the dangerous capabilities a grant can unlock
+// (shell, filesystem mutation; network/process execution ride bash).
+export const SKILL_GRANT_SENSITIVE_TOOLS = new Set([
+    "write",
+    "edit",
+    "bash",
+]);
+// Explicit trust policy (not a scattered special case):
+// - global skills live under the user's own ~/.claude|~/.agents: user
+//   controlled, so allowed-tools arm turn-scoped grants per existing policy.
+// - project skills live in repo content, which may be untrusted (a cloned
+//   repo's SKILL.md can declare anything): they NEVER arm grants. Approval
+//   tools invoked under them prompt normally (or via /trust); read-only
+//   tools auto-run regardless, so nothing functional is lost.
+export function skillGrantsFor(source, allowedTools) {
+    if (source === "global")
+        return { grants: [...allowedTools], blocked: [] };
+    return {
+        grants: [],
+        blocked: allowedTools.filter((t) => SKILL_GRANT_SENSITIVE_TOOLS.has(t)),
+    };
+}
+export function defaultNetworkPolicy() {
+    return {
+        // ATOM is a local agent: public docs plus localhost dev servers stay
+        // reachable; private LAN and link-local (cloud metadata) stay closed
+        // until the owner opens them in atom.json.
+        allowPublic: true,
+        allowLocalhost: true,
+        allowPrivate: false,
+        allowLinkLocal: false,
+    };
+}
+export function parseNetworkPolicy(raw) {
+    const policy = defaultNetworkPolicy();
+    const warnings = [];
+    if (raw === undefined)
+        return { policy, warnings };
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        warnings.push(`network: must be an object — ignored`);
+        return { policy, warnings };
+    }
+    const o = raw;
+    Object.keys(policy).forEach((key) => {
+        const v = o[key];
+        if (v === undefined)
+            return;
+        if (typeof v !== "boolean") {
+            warnings.push(`network: ignoring invalid "${key}" (must be a boolean)`);
+            return;
+        }
+        policy[key] = v;
+    });
+    return { policy, warnings };
+}
+export function zoneAllows(zone, policy) {
+    switch (zone) {
+        case "public":
+            return policy.allowPublic;
+        case "localhost":
+            return policy.allowLocalhost;
+        case "private":
+            return policy.allowPrivate;
+        case "link-local":
+            return policy.allowLinkLocal;
+        case "blocked":
+            return false;
+    }
+}
+// Redirect statuses followed manually (GET-only client, so 303's method
+// rewrite is moot). Anything else with a Location is left alone.
+export function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+// Fail-closed IP classifier (pure, no DNS). Returns "invalid" for anything
+// unparseable — callers treat invalid as blocked.
+export function classifyIp(raw) {
+    let ip = raw.trim().toLowerCase();
+    // Bracketed IPv6 literals as carried by URL.hostname.
+    if (ip.startsWith("[") && ip.endsWith("]"))
+        ip = ip.slice(1, -1);
+    // Zone IDs (fe80::1%eth0, encoded %25eth0) describe the interface, not the
+    // address: classify the address part.
+    const pct = ip.indexOf("%");
+    if (pct !== -1)
+        ip = ip.slice(0, pct);
+    if (ip.includes(":"))
+        return classifyIpv6(ip);
+    return classifyIpv4(ip);
+}
+function parseDecOctet(part) {
+    if (!/^\d+$/.test(part))
+        return null;
+    // Leading zeros would be octal to getaddrinfo ("010" = 8, "0177" = 127):
+    // a strict decimal read could call 0177.0.0.1 public while the resolver
+    // reaches localhost. Fail closed instead.
+    if (part.length > 1 && part.startsWith("0"))
+        return null;
+    const n = Number(part);
+    return Number.isInteger(n) && n >= 0 && n <= 255 ? n : null;
+}
+function classifyIpv4(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return "invalid";
+    const octets = [];
+    for (const p of parts) {
+        const n = parseDecOctet(p);
+        if (n === null)
+            return "invalid";
+        octets.push(n);
+    }
+    const [o1 = 0, o2 = 0, o3 = 0] = octets;
+    if (o1 === 127)
+        return "localhost"; // 127.0.0.0/8 loopback
+    if (o1 === 0 && o2 === 0 && o3 === 0)
+        return "localhost"; // 0.0.0.0 unspecified
+    if (o1 === 10)
+        return "private"; // 10.0.0.0/8 RFC1918
+    if (o1 === 172 && o2 >= 16 && o2 <= 31)
+        return "private"; // 172.16.0.0/12
+    if (o1 === 192 && o2 === 168)
+        return "private"; // 192.168.0.0/16
+    if (o1 === 169 && o2 === 254)
+        return "link-local"; // 169.254.0.0/16 (cloud metadata lives here)
+    if (o1 === 100 && o2 >= 64 && o2 <= 127)
+        return "private"; // 100.64.0.0/10 CGNAT shared space
+    if ((o1 === 192 && o2 === 0 && o3 === 2) ||
+        (o1 === 198 && o2 === 51 && o3 === 100) ||
+        (o1 === 203 && o2 === 0 && o3 === 113)) {
+        return "private"; // TEST-NET documentation ranges: unroutable, fail closed
+    }
+    if (o1 >= 224)
+        return "invalid"; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved
+    return "public";
+}
+function expandIpv6(ip) {
+    // Embedded IPv4 tail (::ffff:1.2.3.4) is handled by the caller.
+    const halves = ip.split("::");
+    if (halves.length > 2)
+        return null;
+    const parseGroup = (s) => {
+        if (s === "")
+            return [];
+        const out = [];
+        for (const g of s.split(":")) {
+            if (!/^[0-9a-f]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    if (halves.length === 1) {
+        const groups = parseGroup(halves[0]);
+        return groups && groups.length === 8 ? groups : null;
+    }
+    const head = parseGroup(halves[0]);
+    const tail = parseGroup(halves[1]);
+    if (!head || !tail || head.length + tail.length > 7)
+        return null;
+    const zeros = new Array(8 - head.length - tail.length).fill(0);
+    return [...head, ...zeros, ...tail];
+}
+function classifyIpv6(ip) {
+    // Dotted mapped tail (::ffff:1.2.3.4): expandIpv6 cannot parse dots, so
+    // unwrap before expansion. (Real URLs never reach this branch — the URL
+    // parser normalizes dotted tails to hex — but direct callers might.)
+    const dotted = ip.match(/^(?:::ffff:)(.+)$/);
+    if (dotted && dotted[1].includes("."))
+        return classifyIpv4(dotted[1]);
+    // Embedded dotted tail in other positions is not a valid literal here.
+    if (ip.includes("."))
+        return "invalid";
+    const g = expandIpv6(ip);
+    if (!g || g.length !== 8)
+        return "invalid";
+    // IPv4-mapped ::ffff:0:0/96 in hex form (::ffff:7f00:1 — the shape the URL
+    // parser produces): classify the embedded IPv4 address, so mapped
+    // loopback/private cannot slip past the v4 rules as "public".
+    if (g[0] === 0 && g[1] === 0 && g[2] === 0 && g[3] === 0 && g[4] === 0 &&
+        g[5] === 0xffff) {
+        const hi = g[6];
+        const lo = g[7];
+        return classifyIpv4(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`);
+    }
+    if (g.every((x) => x === 0)) {
+        // :: unspecified — like 0.0.0.0, connections stay on the machine.
+        return "localhost";
+    }
+    if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1)
+        return "localhost"; // ::1
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return "link-local"; // fe80::/10
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return "private"; // fc00::/7 unique-local
+    if (g[0] === 0x2001 && g[1] === 0x0db8)
+        return "private"; // 2001:db8::/32 documentation
+    if ((g[0] & 0xff00) === 0xff00)
+        return "invalid"; // ff00::/8 multicast
+    return "public";
+}
+// Classify a hostname's resolved addresses, worst zone wins (fail closed):
+// link-local > localhost > private > public. A hostname straddling zones is
+// gated by its most sensitive address, which also blunts DNS-rebinding
+// races (at most one lookup happens per check; see webfetchTool).
+const ZONE_RANK = {
+    blocked: 4,
+    "link-local": 3,
+    localhost: 2,
+    private: 1,
+    public: 0,
+};
+export function zoneForAddresses(addresses) {
+    let worst = "public";
+    for (const addr of addresses) {
+        const zone = classifyIp(addr);
+        const effective = zone === "invalid" ? "blocked" : zone;
+        if (ZONE_RANK[effective] > ZONE_RANK[worst])
+            worst = effective;
+    }
+    return worst;
+}
+// ---- 4. Secret scrubbing ----
+// Minimum secret length worth redacting: shorter values would nuke ordinary
+// words (a 1-char "secret" redacts every matching letter).
+export const SECRET_MIN_LENGTH = 8;
+// Redact every occurrence of each known secret. Longest-first so overlapping
+// values mask fully; split/join (never regex) so values cannot inject
+// patterns. Idempotent. Pure.
+export function scrubSecrets(text, secrets) {
+    const ordered = [...new Set(secrets)]
+        .filter((s) => typeof s === "string" && s.length >= SECRET_MIN_LENGTH)
+        .sort((a, b) => b.length - a.length);
+    if (ordered.length === 0)
+        return text;
+    let out = text;
+    for (const s of ordered)
+        out = out.split(s).join("[redacted]");
+    return out;
+}

package/dist/prompt-cache.js

@@ -0,0 +1,99 @@
+// Prompt-cache architecture: ATOM intentionally constructs a cache-friendly
+// prompt, and each provider decides how that cache is actually realized.
+//
+// Conceptual split (every POST):
+//   STABLE PREFIX (byte-identical across POSTs, cacheable)
+//     - system instructions (src/system.ts one-liner)
+//     - project instructions (AGENTS.md overlay)
+//     - tool definitions (source order, stable serialization)
+//   DYNAMIC SUFFIX (changes constantly, never cached as prefix)
+//     - environment block (timestamps, git status — refreshed per turn)
+//     - current conversation, tool calls/results, skill injections,
+//       todo state, task state
+//
+// Deliberate non-goals (documented, not oversights):
+// - No Tier-1 skill catalog is injected: the deterministic local matcher
+//   owns skill discovery, so skill metadata never enters the prefix
+//   unsolicited. Loaded skill bodies ride the dynamic suffix (they change
+//   turn to turn); their references stay on demand.
+// - The cwd/node tail of the env block rides the dynamic suffix with the
+//   timestamp — splitting that one line further is not worth the fragility;
+//   it is ~200 chars.
+// - Gemini explicit cache objects (a separate resource lifecycle with its own
+//   create/reference/TTL calls) are out of scope; Gemini uses implicit
+//   prefix stability like everyone else.
+//
+// The split reuses the env-block boundary history[0] already carries:
+// `stripEnvBlock` separates the stable base from the trailing `[env ...]`
+// block, so NO storage format changes — histories with no env block (tests,
+// old saves) assemble to a single stable system message, byte-identical to
+// the pre-cache wire shape.
+//
+// Layering (AgentRuntime → ContextManager → assembled context →
+// ProviderAdapter): this module owns the neutral assembly + policy + caps.
+// The agent loop never sees caching (no loop changes); adapters translate
+// the assembly into kind-specific wire shapes (Anthropic blocks+breakpoints,
+// OpenAI-shape message split, Gemini parts split).
+//
+// Prompt caching itself is NEVER implemented here — this is the foundation:
+// deterministic assembly, capability declarations, usage-field plumbing, and
+// instrumentation. Cost/latency wins come from providers honoring it.
+import { createHash } from "node:crypto";
+import { stripEnvBlock } from "./env-block.js";
+import { estimateTokensForChars } from "./context-manager.js";
+import { getProvider } from "./providers.js";
+// Declared caching support lives on the provider registry itself
+// (ProviderDef.cache in providers.ts — the single declaration point).
+// Unknown ids get the conservative all-false default (compatibility first —
+// never assume).
+export function providerCacheSupport(id) {
+    return (getProvider(id)?.cache ?? {
+        explicitBreakpoints: false,
+        implicitPrefix: false,
+        usageCacheFields: false,
+        notes: "unknown provider — no caching assumed",
+    });
+}
+// Fresh `{type:"ephemeral"}` breakpoint per call (never a shared object —
+// callers embed it into request bodies they own).
+export function ephemeralBreakpoint() {
+    return { type: "ephemeral" };
+}
+// OpenAI-shape head split: history[0]'s env tail becomes its own system
+// message ([stable, dynamic, ...rest]). Returns the input array UNTOUCHED
+// when there is nothing to split (no system head, or no env tail) — callers
+// then send the legacy shape byte-identically. Always returns a NEW array
+// when splitting (never mutates the loop's history; rollback indices and the
+// ledger keep pointing at the original).
+export function splitSystemHead(history) {
+    const first = history[0];
+    if (!first || first.role !== "system" || typeof first.content !== "string") {
+        return history;
+    }
+    const prefix = assemblePrefix({ systemContent: first.content });
+    if (prefix.dynamicSystem === null || prefix.stableSystem.trim().length === 0) {
+        return history;
+    }
+    return [
+        { role: "system", content: prefix.stableSystem },
+        { role: "system", content: prefix.dynamicSystem },
+        ...history.slice(1),
+    ];
+}
+function sha1Hex(text) {
+    return createHash("sha1").update(text, "utf8").digest("hex");
+}
+export function assemblePrefix(args) {
+    const stableSystem = stripEnvBlock(args.systemContent);
+    const tail = args.systemContent.slice(stableSystem.length);
+    const dynamicSystem = tail.trim().length > 0 ? tail.trim() : null;
+    const toolsPart = args.toolsJson ?? "<no-tools>";
+    // Length-prefixed so contents can never alias across the boundary.
+    const fingerprint = sha1Hex(`${stableSystem.length}:${stableSystem}\n${toolsPart.length}:${toolsPart}`);
+    return {
+        stableSystem,
+        dynamicSystem,
+        fingerprint,
+        stableTokens: estimateTokensForChars(stableSystem.length + (args.toolsJson?.length ?? 0)),
+    };
+}

package/dist/providers.js

@@ -19,8 +19,36 @@
 //   Gemini 2.5/2.0/1.5 Flash/Pro with function calling.
 // - openai-compatible: generic OpenAI-shape ids (custom baseURL); the live
 //   /models list is authoritative, these are just offline placeholders.
-export const DEFAULT_PROVIDER = "opencode-zen";
+export const LOCAL_PROVIDER_IDS = [
+    "ollama",
+    "lmstudio",
+    "llamacpp",
+];
+export function isLocalProviderId(id) {
+    return LOCAL_PROVIDER_IDS.includes(id);
+}
+export const DEFAULT_PROVIDER = "kilo";
 export const PROVIDERS = [
+    {
+        id: "kilo",
+        name: "Kilo",
+        kind: "openai-chat",
+        chatEndpoint: "https://api.kilo.ai/api/gateway/chat/completions",
+        consoleURL: "https://kilo.ai",
+        envVars: ["KILO_API_KEY"],
+        // Offline placeholder only: the live /models catalog is authoritative.
+        // kilo-auto/free is Kilo's dynamic free routing model, preferred when no
+        // API key is configured (see preferFreeKiloModel in src/kilo.ts).
+        defaultModel: "kilo-auto/free",
+        fallbackModels: ["kilo-auto/free"],
+        notes: "Kilo Gateway (OpenAI-compatible). Free :free models work without a key; key unlocks the full catalog.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: false,
+            notes: "server-dependent; stable serialization only, usage passes through when reported",
+        },
+    },
     {
         id: "opencode-zen",
         name: "OpenCode Zen",
@@ -41,6 +69,12 @@ export const PROVIDERS = [
             "big-pickle",
         ],
         notes: "OpenAI-compatible chat/completions. reasoning_effort only here.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: true,
+            notes: "upstream-dependent prefix behavior; usage cache fields pass through when reported",
+        },
     },
     {
         id: "openai",
@@ -57,6 +91,12 @@ export const PROVIDERS = [
             "gpt-5.6-luna",
         ],
         notes: "OpenAI-compatible chat/completions. reasoning_effort never sent.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: true,
+            notes: "automatic prefix caching; usage.prompt_tokens_details.cached_tokens",
+        },
     },
     {
         id: "anthropic",
@@ -73,6 +113,12 @@ export const PROVIDERS = [
             "claude-3-5-haiku-20241022",
         ],
         notes: "Messages API with tool_use blocks. max_tokens 4096.",
+        cache: {
+            explicitBreakpoints: true,
+            implicitPrefix: true,
+            usageCacheFields: true,
+            notes: "cache_control {type:ephemeral} on stable system block + last tool (5m default TTL); usage.cache_read/cache_creation_input_tokens",
+        },
     },
     {
         id: "deepseek",
@@ -89,6 +135,12 @@ export const PROVIDERS = [
             "deepseek-v4-pro",
         ],
         notes: "OpenAI-compatible (no /v1 prefix). reasoning_effort never sent.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: true,
+            notes: "automatic on-disk context caching; usage.prompt_cache_hit_tokens (+miss informational)",
+        },
     },
     {
         id: "mistral",
@@ -105,6 +157,12 @@ export const PROVIDERS = [
             "open-mistral-nemo",
         ],
         notes: "OpenAI-compatible chat/completions. reasoning_effort never sent.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: false,
+            usageCacheFields: false,
+            notes: "no verified caching contract — stable serialization only",
+        },
     },
     {
         id: "google-gemini",
@@ -122,6 +180,12 @@ export const PROVIDERS = [
             "gemini-1.5-flash",
         ],
         notes: "streamGenerateContent SSE; :generateContent fallback.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: true,
+            notes: "implicit caching by default (stable content first); usageMetadata.cachedContentTokenCount",
+        },
     },
     {
         id: "openai-compatible",
@@ -138,6 +202,81 @@ export const PROVIDERS = [
             "mixtral-8x7b-32768",
         ],
         notes: "Stored baseURL + stored key only. Live /models authoritative.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: false,
+            notes: "server-dependent; stable serialization only, nothing reported",
+        },
+    },
+    // Local runtimes (auto-discovered; see src/local-discovery.ts). All three
+    // serve the OpenAI-compatible /v1/* surface ATOM chats through
+    // (Ollama natively documents /v1/chat/completions with streaming, tools,
+    // vision, and reasoning support). No API key: the servers ignore bearer
+    // auth. fallbackModels stay empty — nothing is listed until discovery
+    // reports it, so no model names are fabricated.
+    {
+        id: "ollama",
+        name: "Ollama",
+        kind: "openai-chat",
+        chatEndpoint: undefined,
+        consoleURL: "https://ollama.com",
+        envVars: [],
+        defaultModel: "",
+        fallbackModels: [],
+        notes: "Local Ollama server (auto-discovered). Discovery reads native /api/tags, chat uses OpenAI-compatible /v1.",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: false,
+            notes: "server-dependent; stable serialization only, nothing reported",
+        },
+        local: {
+            defaultBaseURL: "http://127.0.0.1:11434",
+            baseURLEnvVar: "ATOM_OLLAMA_URL",
+        },
+    },
+    {
+        id: "lmstudio",
+        name: "LM Studio",
+        kind: "openai-chat",
+        chatEndpoint: undefined,
+        consoleURL: "https://lmstudio.ai",
+        envVars: [],
+        defaultModel: "",
+        fallbackModels: [],
+        notes: "Local LM Studio server (auto-discovered, OpenAI-compatible /v1).",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: false,
+            notes: "server-dependent; stable serialization only, nothing reported",
+        },
+        local: {
+            defaultBaseURL: "http://127.0.0.1:1234",
+            baseURLEnvVar: "ATOM_LMSTUDIO_URL",
+        },
+    },
+    {
+        id: "llamacpp",
+        name: "llama.cpp",
+        kind: "openai-chat",
+        chatEndpoint: undefined,
+        consoleURL: "https://github.com/ggml-org/llama.cpp",
+        envVars: [],
+        defaultModel: "",
+        fallbackModels: [],
+        notes: "Local llama-server (auto-discovered, OpenAI-compatible /v1; exposes only the loaded model).",
+        cache: {
+            explicitBreakpoints: false,
+            implicitPrefix: true,
+            usageCacheFields: false,
+            notes: "server-dependent; stable serialization only, nothing reported",
+        },
+        local: {
+            defaultBaseURL: "http://127.0.0.1:8080",
+            baseURLEnvVar: "ATOM_LLAMACPP_URL",
+        },
     },
 ];
 const BY_ID = Object.fromEntries(PROVIDERS.map((p) => [p.id, p]));
@@ -161,6 +300,28 @@ export function providerLabel(id) {
         return "Provider";
     return def.name;
 }
+// Local runtimes need no API key (loopback servers ignore bearer auth),
+// and Kilo serves anonymous free (`:free`) models, so picker/submit key
+// gates must let both through keyless.
+export function providerNeedsKey(id) {
+    if (id === "kilo")
+        return false;
+    return !isLocalProviderId(id);
+}
+// Resolve a local server baseURL: explicit override wins, then the
+// ATOM_*_URL env var, then the loopback default. Env-before-stored matches
+// key resolution (env wins); stored stays reserved for future UI.
+export function localBaseURLFor(id, storedBaseURL) {
+    const def = getProvider(id);
+    const envVar = def?.local?.baseURLEnvVar;
+    const fromEnv = envVar ? (process.env[envVar] ?? "").trim() : "";
+    if (fromEnv)
+        return normalizeBaseURL(fromEnv);
+    const stored = (storedBaseURL ?? "").trim();
+    if (stored)
+        return normalizeBaseURL(stored);
+    return def?.local?.defaultBaseURL ?? "";
+}
 // Normalize a custom baseURL: trim whitespace/trailing slashes.
 export function normalizeBaseURL(raw) {
     return raw.trim().replace(/\/+$/, "");
@@ -173,12 +334,29 @@ export function openaiCompatibleChatEndpoint(baseURL) {
         ? base
         : `${base}/chat/completions`;
 }
-// Chat endpoint for a provider (openai-compatible needs stored baseURL).
+// Local chat endpoint: server base + OpenAI-compatible path, appended iff
+// missing (a custom baseURL may already include /v1).
+export function localChatEndpoint(baseURL) {
+    const base = normalizeBaseURL(baseURL);
+    return base.endsWith("/v1/chat/completions")
+        ? base
+        : `${base}/v1/chat/completions`;
+}
+// Local models URL: server base + OpenAI-compatible listing path.
+export function localModelsURL(baseURL) {
+    const base = normalizeBaseURL(baseURL);
+    return base.endsWith("/v1/models") ? base : `${base}/v1/models`;
+}
+// Chat endpoint for a provider (openai-compatible needs stored baseURL;
+// local runtimes resolve env/default loopback baseURLs).
 export function chatEndpointFor(id, storedBaseURL) {
     const def = getProvider(id);
     if (id === "openai-compatible") {
         return openaiCompatibleChatEndpoint(storedBaseURL ?? "");
     }
+    if (isLocalProviderId(id)) {
+        return localChatEndpoint(localBaseURLFor(id, storedBaseURL));
+    }
     return def.chatEndpoint ?? "";
 }
 // Derive the models URL from a chat/completions endpoint
@@ -196,6 +374,9 @@ export function modelsUrlForProvider(id, storedBaseURL) {
         return "https://api.anthropic.com/v1/models";
     if (id === "google-gemini")
         return "https://generativelanguage.googleapis.com/v1beta/models";
+    if (isLocalProviderId(id)) {
+        return localModelsURL(localBaseURLFor(id, storedBaseURL));
+    }
     return modelsUrlForEndpoint(chatEndpointFor(id, storedBaseURL));
 }
 // Mask a key for display: "…1234". Never the full key.

package/dist/rollback.js

@@ -0,0 +1,21 @@
+/** How each scope rolls back: automatic, explicit-only, or never. */
+export const ROLLBACK_MODE = {
+    conversation: "automatic",
+    filesystem: "explicit",
+    process: "never",
+};
+/** One-line runtime truth per scope, reused by UX text and docs. */
+export const ROLLBACK_NOTES = {
+    conversation: "history/turns splice back to the turn start (cancel/failure) or a checkpoint mark (/rewind); rolled-back turns never reach the session file",
+    filesystem: "only an explicit /rewind restore reverts bytes (hash-verified); cancel and failure never touch disk",
+    process: "never rolled back: foreground bash runs to completion, background tasks survive cancel, nothing is killed",
+};
+/**
+ * The cancelled-turn transcript line. Keeps the historical "(cancelled)"
+ * marker byte-identical (tests and muscle memory match on the substring)
+ * and states the no-revert truth in the same breath, so a cancel can never
+ * read as "undone".
+ */
+export function cancelledTurnLine() {
+    return "(cancelled) conversation rolled back; files and processes were NOT reverted — /rewind restores file snapshots";
+}