atom-agent 0.3.0 → 1.1.0

package/dist/scheduler.js

@@ -0,0 +1,247 @@
+// Effect-aware tool scheduler: data-driven parallelism without Promise.all-
+// ing every tool.
+//
+// The conservative contract (unchanged): batchable reads run concurrently,
+// mutations stay serialized, results commit in original call order, cancel
+// stops between batches, approval happens per call inside runOneTool. This
+// module only PLANS batches; execution (zen.ts runLoopWithChat) is untouched.
+//
+// How it reasons (per tool, from the TOOL_EFFECTS table — the single
+// coupling point; the algorithm below has no per-tool branches):
+// - missing metadata → serial singleton (new tools fail safe, like the old
+//   allowlist-miss; current safe behavior is preserved when metadata is
+//   absent, not degraded).
+// - unknown name / malformed JSON / failed validation / empty target →
+//   serial singleton (never batch what you cannot see; validation failures
+//   become inline-error singletons downstream, exactly as before).
+// - interactive (ask_question) or exclusive (shared ambient state the effect
+//   model cannot see: todowrite/todo_update/todo_get) → serial singleton.
+// - any filesystem/network WRITE, or any process SPAWN → serial singleton.
+//   Writes conflict GLOBALLY (not just same-target): a write splits the
+//   block and read-after-write stays ordered. Target-scoped write batching
+//   is a deliberate non-goal — correctness over theoretical parallelism.
+// - reads (filesystem or network) batch with pairwise-disjoint keys, where
+//   the key is tool + target. Same tool + same target serializes (the old
+//   overlap rule, kept verbatim: e.g. two reads of one path). Reads never
+//   conflict across keys — an all-read batch cannot race a writer, because
+//   writers never join batches.
+// - deterministic is declared per tool; its current enforcement is the
+//   same-key rule (a re-poll of the same background task, whose output can
+//   grow, never runs concurrently with itself).
+//
+// Pure module except the shared arg validators (same imports zen.ts already
+// carries — no new coupling class). Covered by tests/scheduler.test.ts; the
+// end-to-end ordering/cancel behavior stays pinned by
+// tests/parallel-calls.test.ts.
+import { toolNames, validateToolArgs } from "./tools.js";
+const str = (v) => (typeof v === "string" ? v : "");
+const targetOf = (key) => (args) => {
+    const t = str(args[key]);
+    return t.length > 0 ? t : null;
+};
+/** Effect metadata for every known tool. Missing name ⇒ serial singleton. */
+export const TOOL_EFFECTS = {
+    read: {
+        filesystem: "read",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("path"),
+    },
+    grep: {
+        filesystem: "read",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("pattern"),
+    },
+    glob: {
+        filesystem: "read",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("pattern"),
+    },
+    webfetch: {
+        filesystem: "none",
+        network: "read",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("url"),
+    },
+    websearch: {
+        filesystem: "none",
+        network: "read",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        // Live search results vary call to call; same-query conflict is still
+        // serialized by the same-key rule.
+        deterministic: false,
+        target: targetOf("query"),
+    },
+    bash_output: {
+        // Reads background-task temp files scoped by taskId (not the repo).
+        filesystem: "read",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        // A running task's output grows between polls — same-task polls
+        // serialize via the same-key rule.
+        deterministic: false,
+        target: targetOf("taskId"),
+    },
+    write: {
+        filesystem: "write",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("path"),
+    },
+    edit: {
+        filesystem: "write",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: false,
+        deterministic: true,
+        target: targetOf("path"),
+    },
+    bash: {
+        // A command can touch anything (files, network, processes) with no
+        // statically visible footprint: global conflict, always singleton.
+        filesystem: "write",
+        network: "write",
+        process: "spawn",
+        interactive: false,
+        exclusive: false,
+        deterministic: false,
+        target: targetOf("command"),
+    },
+    ask_question: {
+        filesystem: "none",
+        network: "none",
+        process: "none",
+        interactive: true,
+        exclusive: false,
+        deterministic: false,
+        target: () => null,
+    },
+    todowrite: {
+        filesystem: "none",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: true,
+        deterministic: false,
+        target: () => null,
+    },
+    todo_update: {
+        filesystem: "none",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: true,
+        deterministic: false,
+        target: () => null,
+    },
+    todo_get: {
+        filesystem: "none",
+        network: "none",
+        process: "none",
+        interactive: false,
+        exclusive: true,
+        deterministic: true,
+        target: () => null,
+    },
+};
+// Partition one assistant message's tool_calls into commit batches,
+// preserving program order: consecutive batchable calls with pairwise
+// disjoint keys form one batch; any serial-only call — and any call whose
+// key already appears in the open batch — closes the batch and runs as a
+// strict serial singleton. A later batch never moves ahead of an earlier
+// serial call (read-after-write stays ordered), and batches never span the
+// block boundary.
+export function planBatches(calls) {
+    const batches = [];
+    let open = [];
+    const keys = new Set();
+    const flush = () => {
+        if (open.length > 0) {
+            batches.push(open);
+            open = [];
+            keys.clear();
+        }
+    };
+    const singleton = (call, parsed) => {
+        flush();
+        batches.push([{ call, parsed, parallelKey: null }]);
+    };
+    for (const call of calls) {
+        let parsed;
+        let malformed = false;
+        try {
+            const raw = call?.function?.arguments ?? "{}";
+            const v = JSON.parse(typeof raw === "string" ? raw : "{}");
+            parsed = typeof v === "object" && v !== null ? v : {};
+        }
+        catch {
+            parsed = {};
+            malformed = true;
+        }
+        const name = typeof call?.function?.name === "string" ? call.function.name : "(unknown)";
+        // Missing metadata fails safe to serial (never batch the unknown).
+        const meta = TOOL_EFFECTS[name];
+        if (malformed || !meta || !toolNames().includes(name)) {
+            singleton(call, parsed);
+            continue;
+        }
+        // Failed validation becomes an inline-error singleton downstream.
+        if (validateToolArgs(name, parsed)) {
+            singleton(call, parsed);
+            continue;
+        }
+        // Interactive, ambient-state, mutating, or spawning calls serialize.
+        if (meta.interactive ||
+            meta.exclusive ||
+            meta.filesystem === "write" ||
+            meta.network === "write" ||
+            meta.process !== "none") {
+            singleton(call, parsed);
+            continue;
+        }
+        // Reads batch on disjoint tool+target keys; empty target = unknown
+        // footprint = serial.
+        let target = null;
+        try {
+            target = meta.target(parsed);
+        }
+        catch {
+            target = null;
+        }
+        if (!target) {
+            singleton(call, parsed);
+            continue;
+        }
+        const key = `${name} ${target}`;
+        if (keys.has(key)) {
+            singleton(call, parsed);
+            continue;
+        }
+        keys.add(key);
+        open.push({ call, parsed, parallelKey: key });
+    }
+    flush();
+    return batches;
+}

package/dist/session.js

@@ -16,8 +16,8 @@
 // outside the repo, so .gitignore needs no change).
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
-import { atomDir } from "./auth.js";
-import { isProviderId } from "./providers.js";
+import { atomDir, getStoredBaseURL, loadAuth, resolveApiKey } from "./auth.js";
+import { chatEndpointFor, isProviderId, openaiCompatibleChatEndpoint, } from "./providers.js";
 import { EFFORT_OPTIONS, } from "./zen.js";
 export const SESSION_VERSION = 1;
 export const SESSION_FILENAME = "session.json";
@@ -32,6 +32,32 @@ export function sessionExists(home) {
         return false;
     }
 }
+export function loadPrefs(home, zenEndpoint) {
+    try {
+        const loaded = loadSession(home);
+        if (loaded.status !== "ok")
+            return null;
+        const s = loaded.session;
+        const auth = loadAuth(home);
+        const key = resolveApiKey(s.provider, auth);
+        // Kilo serves anonymous free models, so a saved kilo session restores
+        // keyless; every other keyed provider still needs a resolvable key.
+        if (!key && s.provider !== "kilo")
+            return null;
+        const baseURL = getStoredBaseURL(auth, s.provider);
+        if (s.provider === "openai-compatible" && !baseURL)
+            return null;
+        const endpoint = s.provider === "opencode-zen"
+            ? zenEndpoint
+            : s.provider === "openai-compatible"
+                ? openaiCompatibleChatEndpoint(baseURL)
+                : chatEndpointFor(s.provider, baseURL);
+        return { provider: s.provider, model: s.model, effort: s.effort, apiKey: key, endpoint };
+    }
+    catch {
+        return null;
+    }
+}
 // Atomic save: write temp + rename, 0600 POSIX (best-effort Windows).
 // Never throws for missing dirs (mkdir -p); disk errors propagate to the
 // caller, which ignores them (in-memory session still applies).
@@ -95,7 +121,13 @@ function validateUsageTotals(value) {
     if (!isRecord(value))
         return null;
     const out = {};
-    for (const key of ["prompt_tokens", "completion_tokens", "total_tokens"]) {
+    for (const key of [
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "cacheReadTokens",
+        "cacheWriteTokens",
+    ]) {
         const v = value[key];
         if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
             out[key] = Math.floor(v);

package/dist/skills.js

@@ -5,6 +5,12 @@
 // the TUI listing. Levels and precedence (ticket 05), invocation (tickets
 // 03/04), and tool grants (ticket 06) build on this registry.
 //
+// Roots (scanned in order, every call — no cache): project .claude/skills,
+// project .agents/skills (skills.sh installs here), global ~/.claude/skills,
+// global ~/.agents/skills. Same-level name clashes keep the first with a
+// note (see resolveSkills); .claude sorts before .agents so a skill present
+// in both keeps its .claude copy.
+//
 // Node builtins only. Discovery never throws: per-skill failures come back
 // as warning strings, and a missing skills directory is normal (silent).
 import { promises as fsp } from "node:fs";
@@ -99,7 +105,9 @@ export async function discoverSkills(opts) {
     const seenBases = new Set();
     const roots = [
         { base: path.join(projectDir, ".claude", "skills"), source: "project" },
+        { base: path.join(projectDir, ".agents", "skills"), source: "project" },
         { base: path.join(homeDir, ".claude", "skills"), source: "global" },
+        { base: path.join(homeDir, ".agents", "skills"), source: "global" },
     ];
     for (const { base, source } of roots) {
         const resolved = path.resolve(base);
@@ -117,73 +125,102 @@ export async function discoverSkills(opts) {
             .filter((e) => e.isDirectory())
             .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
         for (const e of dirs) {
-            const dir = path.join(base, e.name);
-            let text;
-            try {
-                text = await fsp.readFile(path.join(dir, "SKILL.md"), "utf8");
-            }
-            catch {
-                warnings.push(`skill "${e.name}" (${source}): cannot read SKILL.md — skipped`);
-                continue;
-            }
-            const { front, body, unclosed } = splitFrontmatter(text);
-            if (unclosed) {
-                warnings.push(`skill "${e.name}" (${source}): unclosed frontmatter — skipped`);
-                continue;
-            }
-            const fmName = front ? frontField(front, "name") : undefined;
-            const fmDesc = front ? frontField(front, "description") : undefined;
-            const name = fmName && fmName.length > 0 ? fmName : e.name;
-            const description = fmDesc && fmDesc.length > 0 ? fmDesc : firstParagraph(body);
-            if (!description) {
-                warnings.push(`skill "${name}" (${source}): no description and empty body — skipped`);
-                continue;
-            }
-            const noModel = front ? frontBool(front, "disable-model-invocation") : undefined;
-            const userOnly = front ? frontBool(front, "user-invocable") : undefined;
-            skills.push({
-                name,
-                description,
-                dir,
-                source,
-                userInvocable: userOnly ?? true,
-                modelInvocable: !(noModel ?? false),
-                allowedTools: front ? parseAllowedTools(frontField(front, "allowed-tools")) : [],
-            });
+            const parsed = await parseSkillDir(base, source, e.name);
+            if (parsed.info)
+                skills.push(parsed.info);
+            else if (parsed.warning)
+                warnings.push(parsed.warning);
         }
     }
     return { skills, warnings };
 }
-// One-shot TUI listing for /skills. Name clashes resolve with personal
-// (global) winning (resolveSkills); model-only skills show with an
-// [auto-only] tag instead of hiding — discoverable, but not invocable.
-// The header always renders so the command is self-explanatory when empty;
-// warnings ride along visibly.
+// Parse one skill directory's SKILL.md into metadata (Tier 1) or a warning.
+// Shared by the uncached discoverSkills above and the SkillRegistry below so
+// both paths parse byte-identically. Reads exactly one file; bodies and
+// references stay lazy (see loadSkillBody).
+async function parseSkillDir(base, source, dirname) {
+    const dir = path.join(base, dirname);
+    let text;
+    try {
+        text = await fsp.readFile(path.join(dir, "SKILL.md"), "utf8");
+    }
+    catch {
+        return { info: null, warning: `skill "${dirname}" (${source}): cannot read SKILL.md — skipped` };
+    }
+    const { front, body, unclosed } = splitFrontmatter(text);
+    if (unclosed) {
+        return { info: null, warning: `skill "${dirname}" (${source}): unclosed frontmatter — skipped` };
+    }
+    const fmName = front ? frontField(front, "name") : undefined;
+    const fmDesc = front ? frontField(front, "description") : undefined;
+    const name = fmName && fmName.length > 0 ? fmName : dirname;
+    const description = fmDesc && fmDesc.length > 0 ? fmDesc : firstParagraph(body);
+    if (!description) {
+        return { info: null, warning: `skill "${name}" (${source}): no description and empty body — skipped` };
+    }
+    const noModel = front ? frontBool(front, "disable-model-invocation") : undefined;
+    const userOnly = front ? frontBool(front, "user-invocable") : undefined;
+    return {
+        info: {
+            name,
+            description,
+            dir,
+            source,
+            userInvocable: userOnly ?? true,
+            modelInvocable: !(noModel ?? false),
+            allowedTools: front ? parseAllowedTools(frontField(front, "allowed-tools")) : [],
+        },
+        warning: null,
+    };
+}
+// One-shot listing for copy/paste and headless use. Rows are names only
+// (`/skill:name`, directly runnable) plus source — descriptions stay out of
+// the TUI; the picker and descriptions live in SKILL.md files. Name clashes
+// resolve with personal (global) winning (resolveSkills); model-only skills
+// show with an [auto-only] tag instead of hiding. The header always renders
+// so the command is self-explanatory when empty; warnings ride along visibly.
 export async function skillsListText(projectDir, homeDir) {
     const found = await discoverSkills({ projectDir, homeDir });
     const { skills, notes } = resolveSkills(found.skills);
     const out = [skills.length === 1 ? "Skills (1):" : `Skills (${skills.length}):`];
     for (const s of skills) {
-        out.push(`/${s.name} — ${s.description} [${s.source}]${s.userInvocable ? "" : " [auto-only]"}`);
+        out.push(`/skill:${s.name} [${s.source}]${s.userInvocable ? "" : " [auto-only]"}`);
     }
     for (const n of notes)
         out.push(`note: ${n}`);
     for (const w of found.warnings)
         out.push(`⚠ ${w}`);
     if (skills.length === 0 && found.warnings.length === 0) {
-        out.push("(no skills installed — add SKILL.md skills under .claude/skills/ or ~/.claude/skills/)");
+        out.push("(no skills installed — add SKILL.md skills under .claude/skills/, .agents/skills/, ~/.claude/skills/, or ~/.agents/skills/)");
     }
     return out.join("\n");
 }
 const SKILL_FILE_CAP = 8 * 1024;
 const SKILL_INCLUDE_MAX = 3;
+// Auto-invoke context cap (Tier 2): an auto-loaded skill body is truncated
+// here with a pointer the model can follow via read — auto-activation must
+// never flood the window the way an explicit manual load may.
+export const AUTO_SKILL_BODY_CAP = 12 * 1024;
+export function capSkillBodyForAuto(text, skillDir) {
+    if (text.length <= AUTO_SKILL_BODY_CAP)
+        return text;
+    return (text.slice(0, AUTO_SKILL_BODY_CAP) +
+        `\n[truncated: auto-loaded skill body exceeded 12KB — read ${skillDir}/SKILL.md for the rest]`);
+}
 // references/<path> + scripts/<path> mentions inside the skill body.
 const SKILL_MENTION_RE = /\b(references|scripts)\/[A-Za-z0-9_.\-/@]+/g;
 // Load a skill's body plus the support files its body references (on
 // demand, capped — never the whole directory). Mentioned-but-missing files
 // are skipped silently; path escapes outside the skill dir are dropped.
 // Never throws: an unreadable SKILL.md yields empty text.
-export async function loadSkillBody(skill) {
+//
+// Progressive-disclosure tiers (Claude-Code-style): pass { inlineRefs: false }
+// to load Tier 2 only (body, no inlined references — the model reads
+// references/<…> via the read tool when it actually needs them). Tier 3
+// (references) stays on demand. Manual invocation keeps the default
+// (inline) since the user explicitly asked for the whole skill.
+export async function loadSkillBody(skill, opts) {
+    const inlineRefs = opts?.inlineRefs ?? true;
     let raw;
     try {
         raw = await fsp.readFile(path.join(skill.dir, "SKILL.md"), "utf8");
@@ -192,6 +229,8 @@ export async function loadSkillBody(skill) {
         return { info: skill, text: "", included: [] };
     }
     const { body } = splitFrontmatter(raw);
+    if (!inlineRefs)
+        return { info: skill, text: body, included: [] };
     const seen = new Set();
     const mentions = [];
     for (const m of body.match(SKILL_MENTION_RE) ?? []) {
@@ -232,20 +271,31 @@ function contentWords(s) {
 }
 // Deterministic description match for auto-invoke: distinct
 // name+description words (len ≥ 3, stopwords dropped) hitting the
-// message as substrings, at least minHits (default 2), best score first,
+// message, at least minHits (default 2), best score first,
 // capped at max (default 2) skills per turn. Skills with
 // disable-model-invocation never match. Pure function — no I/O.
+//
+// Matching modes: substring (default — `test` hits `testing`, kept for
+// backward compatibility) or wholeWords (a skill word must appear as a whole
+// message word — kills the biggest false-positive class (`test` inside
+// `latest`, `commit` inside `committed`). The App's auto-invoke path uses
+// wholeWords with a higher bar; the defaults stay for manual tooling.
 export function matchSkills(message, skills, opts) {
     const max = opts?.max ?? 2;
     const minHits = opts?.minHits ?? 2;
+    const wholeWords = opts?.wholeWords ?? false;
     const text = message.toLowerCase();
+    const messageWords = wholeWords ?
+        new Set(text.split(/[^a-z0-9]+/).filter((w) => w.length > 0))
+        : null;
     const scored = [];
     for (const s of skills) {
         if (!s.modelInvocable)
             continue;
         let hits = 0;
         for (const w of contentWords(`${s.name} ${s.description}`)) {
-            if (text.includes(w))
+            const hit = messageWords ? messageWords.has(w) : text.includes(w);
+            if (hit)
                 hits += 1;
         }
         if (hits >= minHits)
@@ -281,3 +331,124 @@ export function resolveSkills(skills) {
     }
     return { skills: order.map((n) => byName.get(n)), notes };
 }
+export function createSkillRegistry(opts) {
+    const projectDir = opts?.projectDir ?? process.cwd();
+    const homeDir = opts?.homeDir ?? os.homedir();
+    // Resolved root base -> dirname -> cached parse. Instance-local: no
+    // cross-talk between Apps, tests, or headless users.
+    const rootState = new Map();
+    let last = { skills: [], warnings: [] };
+    function roots() {
+        return [
+            { base: path.join(projectDir, ".claude", "skills"), source: "project" },
+            { base: path.join(projectDir, ".agents", "skills"), source: "project" },
+            { base: path.join(homeDir, ".claude", "skills"), source: "global" },
+            { base: path.join(homeDir, ".agents", "skills"), source: "global" },
+        ];
+    }
+    async function refresh() {
+        const skills = [];
+        const warnings = [];
+        const stats = {
+            roots: 0,
+            entries: 0,
+            reused: 0,
+            reloaded: 0,
+            added: 0,
+            removed: 0,
+        };
+        const seenBases = new Set();
+        for (const { base, source } of roots()) {
+            const resolved = path.resolve(base);
+            if (seenBases.has(resolved))
+                continue; // e.g. repo rooted at $HOME
+            seenBases.add(resolved);
+            let entries;
+            try {
+                entries = await fsp.readdir(base, { withFileTypes: true });
+            }
+            catch {
+                // Root vanished: drop its cached entries silently (same as discovery).
+                const prev = rootState.get(resolved);
+                if (prev) {
+                    stats.removed += prev.size;
+                    rootState.delete(resolved);
+                }
+                continue;
+            }
+            stats.roots += 1;
+            const dirs = entries
+                .filter((e) => e.isDirectory())
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            const prev = rootState.get(resolved) ?? new Map();
+            const next = new Map();
+            for (const e of dirs) {
+                stats.entries += 1;
+                const skillFile = path.join(base, e.name, "SKILL.md");
+                let fingerprint = null;
+                try {
+                    const st = await fsp.stat(skillFile);
+                    if (st.isFile())
+                        fingerprint = { mtimeMs: st.mtimeMs, size: st.size };
+                }
+                catch {
+                    fingerprint = null;
+                }
+                const cached = prev.get(e.name);
+                // Reuse on fingerprint match. Entries that previously failed to stat
+                // carry the (0, 0) sentinel and can never match a real file, so a
+                // vanished file that reappears is always re-parsed — never stuck.
+                if (cached &&
+                    fingerprint &&
+                    cached.mtimeMs > 0 &&
+                    fingerprint.mtimeMs === cached.mtimeMs &&
+                    fingerprint.size === cached.size) {
+                    next.set(e.name, cached);
+                    stats.reused += 1;
+                    if (cached.info)
+                        skills.push(cached.info);
+                    else if (cached.warning)
+                        warnings.push(cached.warning);
+                    continue;
+                }
+                if (fingerprint === null) {
+                    // Matches discovery's read-failure warning byte-for-byte. Re-checked
+                    // (not reloaded) every refresh — a reappearing file is re-parsed via
+                    // the path below, never stuck warned.
+                    const warning = `skill "${e.name}" (${source}): cannot read SKILL.md — skipped`;
+                    next.set(e.name, { mtimeMs: 0, size: 0, info: null, warning });
+                    warnings.push(warning);
+                    if (!cached)
+                        stats.added += 1;
+                    continue;
+                }
+                const parsed = await parseSkillDir(base, source, e.name);
+                next.set(e.name, {
+                    mtimeMs: fingerprint.mtimeMs,
+                    size: fingerprint.size,
+                    info: parsed.info,
+                    warning: parsed.warning,
+                });
+                if (parsed.info)
+                    skills.push(parsed.info);
+                else if (parsed.warning)
+                    warnings.push(parsed.warning);
+                if (cached)
+                    stats.reloaded += 1;
+                else
+                    stats.added += 1;
+            }
+            for (const name of prev.keys()) {
+                if (!next.has(name))
+                    stats.removed += 1;
+            }
+            rootState.set(resolved, next);
+        }
+        last = { skills, warnings };
+        return { skills, warnings, stats };
+    }
+    function snapshot() {
+        return { skills: [...last.skills], warnings: [...last.warnings] };
+    }
+    return { refresh, snapshot };
+}