atom-agent 0.3.0 → 1.1.0

package/dist/agent/normalize.js

@@ -0,0 +1,144 @@
+// Safety net for custom executors (built-in tools already cap: read 64KB
+// head + truncation note + overflow pointer ≈ 66KB, bash 8KB, webfetch 64KB
+// + notes). The cap sits at 128KB so legitimate built-in outputs (overflow
+// pointers included) pass through byte-identical; only oversized custom
+// results truncate.
+export const TOOL_RESULT_CAP_CHARS = 128 * 1024;
+export function normalizeToolResult(result) {
+    let text;
+    if (typeof result === "string") {
+        text = result;
+    }
+    else if (result === null || result === undefined) {
+        return "Error: tool returned no result";
+    }
+    else {
+        try {
+            const json = JSON.stringify(result);
+            text = typeof json === "string" ? json : String(result);
+        }
+        catch {
+            try {
+                text = String(result);
+            }
+            catch {
+                return "Error: tool returned an unreadable result";
+            }
+        }
+    }
+    if (text.length > TOOL_RESULT_CAP_CHARS) {
+        return (text.slice(0, TOOL_RESULT_CAP_CHARS) +
+            `\n[truncated: tool result exceeded ${TOOL_RESULT_CAP_CHARS} chars]`);
+    }
+    return text;
+}
+// Recursively key-sorted JSON for stable signatures. Falls back to a short
+// type tag when unstringifiable (never throws, never aliases objects with
+// strings: prefixes the tag).
+function stableStringify(value) {
+    try {
+        return JSON.stringify(sortKeys(value)) ?? "undefined";
+    }
+    catch {
+        return `unstringifiable:${typeof value}`;
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+// Stable repetition/cache key: `name` + canonical args. Parsed args come
+// from JSON.parse (insertion-ordered), so sorting closes the alias where
+// `{"a":1,"b":2}` and `{"b":2,"a":1}` would otherwise count as different.
+export function toolSignature(name, parsed) {
+    return `${name} ${stableStringify(parsed ?? {})}`;
+}
+// Defensive validation of one assistant message. Never throws: malformed
+// tool_calls entries are dropped with a warning (the caller surfaces them
+// via onWarning so the transcript shows what the model attempted); a fully
+// unusable message becomes empty final text (the loop's turn-end gates then
+// decide, exactly as if the model sent empty content).
+export function normalizeChatResult(raw) {
+    const warnings = [];
+    if (typeof raw !== "object" || raw === null) {
+        return { result: { content: null }, warnings: ["model returned a non-object message"] };
+    }
+    const m = raw;
+    const contentRaw = m["content"];
+    const content = typeof contentRaw === "string"
+        ? contentRaw
+        : contentRaw === null || contentRaw === undefined
+            ? null
+            : (() => {
+                try {
+                    return JSON.stringify(contentRaw);
+                }
+                catch {
+                    return String(contentRaw);
+                }
+            })();
+    const callsRaw = m["calls"] ?? m["tool_calls"];
+    if (callsRaw === undefined) {
+        const result = { content };
+        if (m["usage"] !== undefined)
+            result["usage"] = m["usage"];
+        if (m["reasoning"] !== undefined)
+            result["reasoning"] = m["reasoning"];
+        return { result: result, warnings };
+    }
+    if (!Array.isArray(callsRaw)) {
+        warnings.push("model tool_calls was not an array — ignored");
+        return { result: { content, tool_calls: undefined }, warnings };
+    }
+    const calls = [];
+    for (let i = 0; i < callsRaw.length; i++) {
+        const entry = callsRaw[i];
+        if (typeof entry !== "object" || entry === null) {
+            warnings.push(`dropped malformed tool call at index ${i} (not an object)`);
+            continue;
+        }
+        const fn = entry["function"];
+        const name = fn?.["name"];
+        if (typeof name !== "string" || name.length === 0) {
+            const id = typeof entry["id"] === "string" ? entry["id"] : `#${i}`;
+            warnings.push(`dropped tool call ${id} with no function name`);
+            continue;
+        }
+        const id = typeof entry["id"] === "string" && entry["id"].length > 0
+            ? entry["id"]
+            : `call-${i}`;
+        const argsRaw = fn?.["arguments"];
+        let args;
+        if (typeof argsRaw === "string")
+            args = argsRaw;
+        else if (argsRaw === undefined || argsRaw === null)
+            args = "{}";
+        else {
+            try {
+                args = JSON.stringify(argsRaw) ?? "{}";
+            }
+            catch {
+                warnings.push(`dropped tool call ${id} with unstringifiable arguments`);
+                continue;
+            }
+        }
+        const call = { id, function: { name, arguments: args } };
+        if (typeof entry["type"] === "string")
+            call.type = entry["type"];
+        calls.push(call);
+    }
+    const out = { content, tool_calls: calls.length > 0 ? calls : undefined };
+    if (m["usage"] !== undefined)
+        out["usage"] = m["usage"];
+    if (m["reasoning"] !== undefined)
+        out["reasoning"] = m["reasoning"];
+    return { result: out, warnings };
+}

package/dist/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/auth.js

@@ -3,7 +3,8 @@
 //   {version:1, providers:{"<id>":{apiKey, baseURL?}}}
 // 0600 perms on POSIX via chmod; best-effort on Windows.
 // Key resolution per provider: standard env var wins when set, else stored.
-// Env names: OPENCODE_ZEN_API_KEY (zen), OPENAI_API_KEY, ANTHROPIC_API_KEY,
+// Env names: KILO_API_KEY (kilo; optional — free models work anonymously),
+// OPENCODE_ZEN_API_KEY (zen), OPENAI_API_KEY, ANTHROPIC_API_KEY,
 // DEEPSEEK_API_KEY, MISTRAL_API_KEY, GEMINI_API_KEY (also GOOGLE_API_KEY
 // alias). openai-compatible: stored key + stored baseURL only.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";

package/dist/cli.js

@@ -4,25 +4,87 @@ import { render } from "ink";
 import { App } from "./App.js";
 import { DEFAULT_ENDPOINT, DEFAULT_MODEL, endpointConfig, } from "./zen.js";
 import { loadAuth, resolveApiKey } from "./auth.js";
+import { writeTelemetryDashboard } from "./telemetry-dashboard.js";
 const args = process.argv.slice(2);
-if (args.includes("--help") || args.includes("-h")) {
+if (args.includes("--dashboard")) {
+    // Local observability dashboard without starting the TUI: render every
+    // stored session to ~/.atom/telemetry/dashboard.html and print the path.
+    const out = writeTelemetryDashboard();
+    if (out) {
+        console.log(`Observability dashboard written to ${out} — open it in a browser. Local file, nothing uploaded.`);
+        process.exit(0);
+    }
+    console.error("Dashboard failed to write — telemetry store unavailable.");
+    process.exit(1);
+}
+if (args.includes("--serve")) {
+    // Local observability webUI: serve the live dashboard + read-only JSON API
+    // on loopback (Ctrl+C stops). The static --dashboard file is untouched.
+    const flagValue = (name) => {
+        const eq = args.find((a) => a.startsWith(`${name}=`));
+        if (eq !== undefined)
+            return eq.slice(name.length + 1);
+        const i = args.indexOf(name);
+        if (i !== -1 && i + 1 < args.length) {
+            const next = args[i + 1];
+            if (!next.startsWith("-"))
+                return next;
+        }
+        return undefined;
+    };
+    (async () => {
+        const { resolveTelemetryPort, startTelemetryServer } = await import("./telemetry-server.js");
+        const server = await startTelemetryServer({ port: resolveTelemetryPort(process.env, flagValue("--port")) });
+        console.log(`ATOM observability webUI at ${server.url} (loopback-only, read-only — Ctrl+C to stop).`);
+        console.log(`JSON API: ${server.url}api/health · ${server.url}api/aggregates · ${server.url}api/sessions`);
+        const stop = () => {
+            server.close().then(() => process.exit(0), () => process.exit(0));
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        await new Promise(() => { });
+    })().catch((e) => {
+        const detail = e instanceof Error ? e.message : String(e);
+        console.error(`Observability webUI failed to start (${detail}). Is the port already in use? Try --port <n>.`);
+        process.exit(1);
+    });
+}
+else if (args.includes("--help") || args.includes("-h")) {
     console.log(`Atom chatbot (Ink TUI)
 Usage: npm start
+Flags: --dashboard (write ~/.atom/telemetry/dashboard.html and exit)
+       --serve [--port <n>] (serve the live dashboard webUI on loopback and keep running)
 Env:
+  KILO_API_KEY  optional (Kilo free models work anonymously; get a key at https://kilo.ai) — env wins over ~/.atom/auth.json
   OPENCODE_ZEN_API_KEY  optional when ~/.atom/auth.json has a zen key (get one at https://opencode.ai/auth)
   OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / MISTRAL_API_KEY / GEMINI_API_KEY (GOOGLE_API_KEY alias)  optional per provider (env wins over stored)
-  OPENCODE_ZEN_MODEL    optional (default: ${DEFAULT_MODEL})
+  OPENCODE_ZEN_MODEL    optional (default: ${DEFAULT_MODEL}; when set, wins over the saved /model)
   OPENCODE_ZEN_ENDPOINT optional (default: ${DEFAULT_ENDPOINT})
-Commands: /model (model picker) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /mode | /yolo (toggle) | /plan (read-only plan mode) | /clear | /resume (restore last saved session) | /help | /exit | /quit
-Providers: opencode-zen/openai/anthropic/deepseek/mistral/google-gemini/openai-compatible (keys in ~/.atom/auth.json, 0600 POSIX; use /provider to paste one).
+Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /autoscroll on|off (follow new output) | /thinking (toggle reasoning visibility) | /mode | /clear | /resume (restore last saved session) | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan
+Providers: kilo (default; anonymous free models, key optional)/opencode-zen/openai/anthropic/deepseek/mistral/google-gemini/openai-compatible (keys in ~/.atom/auth.json, 0600 POSIX; use /provider to paste one) + local auto-discovery: ollama (:11434), lmstudio (:1234), llamacpp (:8080) — no keys needed, overrides via ATOM_OLLAMA_URL/ATOM_LMSTUDIO_URL/ATOM_LLAMACPP_URL.
 Note: reasoning_effort is sent only for opencode-zen supported models.`);
     process.exit(0);
 }
-const { endpoint, apiKey: envKey, model } = endpointConfig();
+const { endpoint, apiKey: envKey } = endpointConfig();
 // Stored zen key (from a previous /provider paste) applies when no env key.
 const storedZen = resolveApiKey("opencode-zen", loadAuth());
 const apiKey = envKey || storedZen;
+// Explicit model only when OPENCODE_ZEN_MODEL is set: otherwise the saved
+// provider/model/effort restore (restorePrefs), else the compiled default.
+// Env wins over the save when set; the save wins over the default.
+// The /model + /provider + /effort picks persist across restarts (saved on
+// every completed turn and on clean exit); the conversation itself only ever
+// restores via an explicit /resume.
+// Explicit model only when OPENCODE_ZEN_MODEL is set and non-empty: a
+// declared-but-empty entry (`OPENCODE_ZEN_MODEL=`, a common .env shape) must
+// count as unset, or the empty string would win the model chain and every
+// POST would carry an empty model id.
+const envModel = process.env.OPENCODE_ZEN_MODEL?.trim() || undefined;
 // Always start the TUI (even without a key) so /provider can paste one.
 // Chatting without a key for the active provider errors inline with a
 // /provider pointer; nothing is POSTed.
-render(_jsx(App, { apiKey: apiKey, endpoint: endpoint, initialModel: model }));
+// --serve parks above (the server holds the event loop), so the TUI must
+// never start alongside it: serve is a standalone mode like --dashboard.
+if (!args.includes("--serve")) {
+    render(_jsx(App, { apiKey: apiKey, endpoint: endpoint, initialModel: envModel, restorePrefs: true }));
+}

package/dist/compact.js

@@ -15,10 +15,13 @@
 // The App owns session refs (load/streak/disabled/pending) and the atomic
 // swap + save; this module owns math, splitting, instruction, and the
 // summary POST (tools disabled, 4096 cap).
-import { contextWindowFor } from "./context-windows.js";
-import { historyChars, messageChars, chatCompletionForProvider, } from "./zen.js";
+import { chatCompletionForProvider, } from "./zen.js";
+// Context math (estimator, load, threshold, measurement) lives in the
+// ContextManager module; compact.ts imports what its splitter needs and
+// re-exports the stable surface so existing importers keep working untouched.
+import { estimateTokensForChars, messageChars } from "./context-manager.js";
+export { COMPACT_PCT_DEFAULT, compactPct, computeContextLoad, estimateTokensForChars, historyChars, shouldAutoCompact, } from "./context-manager.js";
 // ---- Constants ----
-export const COMPACT_PCT_DEFAULT = 0.83;
 export const COMPACT_KEEP_TOKENS = 8000;
 export const COMPACT_SUMMARY_MAX_TOKENS = 4096;
 export const COMPACT_TOOL_OUTPUT_CAP = 2000;
@@ -27,49 +30,6 @@ export const COMPACT_TOOL_OUTPUT_CAP = 2000;
 // `token: n/a` honesty rule or the NK cumulative spend.
 export const COMPACT_CHARS_PER_TOKEN = 4;
 export const COMPACT_THRASH_LIMIT = 3;
-// ---- Threshold ----
-function clampPctPercent(n) {
-    return Math.min(Math.max(n, 50), 95) / 100;
-}
-// Auto-compact threshold as a fraction (default 0.83). Env ATOM_COMPACT_PCT
-// is a percent (e.g. "83"), clamped 50–95; invalid/unset → default.
-export function compactPct() {
-    const raw = process.env.ATOM_COMPACT_PCT;
-    if (raw === undefined)
-        return COMPACT_PCT_DEFAULT;
-    const text = raw.trim();
-    if (!/^\d+(\.\d+)?$/.test(text))
-        return COMPACT_PCT_DEFAULT;
-    const n = Number(text);
-    if (!Number.isFinite(n))
-        return COMPACT_PCT_DEFAULT;
-    return clampPctPercent(n);
-}
-// ---- Load metric ----
-export function estimateTokensForChars(chars) {
-    // opencode's 4ch/token heuristic.
-    const c = Number.isFinite(chars) && chars > 0 ? Math.floor(chars) : 0;
-    return Math.floor(c / COMPACT_CHARS_PER_TOKEN);
-}
-// Load = last POST's reported prompt_tokens when available, else the
-// 4ch/token estimate of the sent history chars.
-export function computeContextLoad(lastPromptTokens, sentHistoryChars) {
-    if (typeof lastPromptTokens === "number" &&
-        Number.isFinite(lastPromptTokens) &&
-        lastPromptTokens >= 0) {
-        return Math.floor(lastPromptTokens);
-    }
-    return estimateTokensForChars(sentHistoryChars);
-}
-export function shouldAutoCompact(load, model, pctOverride) {
-    const window = contextWindowFor(model);
-    if (window === undefined)
-        return false; // never invent a window
-    const pct = typeof pctOverride === "number" && Number.isFinite(pctOverride)
-        ? pctOverride
-        : compactPct();
-    return load / window >= pct;
-}
 // ---- Turn helpers ----
 export function countUserTurns(history) {
     let n = 0;
@@ -273,5 +233,3 @@ export async function requestCompactSummary(req) {
         }
     }
 }
-// Re-export for callers that need the post-turn history size.
-export { historyChars };

package/dist/config.js

@@ -0,0 +1,171 @@
+// atom.json — ATOM's config file (Claude-Code-settings/opencode.json-style
+// durable configuration layer).
+//
+// Two levels, per-key merge (project wins over global):
+// - project: <cwd>/atom.json
+// - global:  ~/.atom/atom.json (ATOM_HOME overrides home, like auth.json)
+//
+// Precedence overall: env vars > saved session prefs (/model, /provider,
+// /effort picks) > project atom.json > global atom.json > compiled defaults.
+// So atom.json sets first-run/project defaults; a later explicit pick (saved)
+// still wins across restarts; env always wins.
+//
+// Everything is optional and validated: unknown keys are ignored
+// (forward-compatible), invalid values fall back per-key with a warning
+// string (surfaced in /context) — loading never throws, missing files are
+// normal and silent. Reads are fresh per call (edits apply without restart,
+// like skills); files are tiny JSON.
+//
+// Keys:
+// - provider: ProviderId for first-run default (needs its key, else zen)
+// - model: default model id (non-empty string)
+// - reasoningEffort: default/low/medium/high/max
+// - maxHistoryMessages: 10–1000 (message-count safety ceiling)
+// - maxHistoryChars: 10_000–2_000_000 (char safety ceiling — caps the
+//   window-derived budget, never the primary limit)
+// - maxToolSteps: 5–100 (tool rounds per turn)
+// - compactPct: 50–95 (auto-compact percent of verified window)
+// - telemetry: {enabled?: boolean} (local observability recording, default on)
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { homeDir } from "./auth.js";
+import { isProviderId } from "./providers.js";
+import { parseNetworkPolicy } from "./policy.js";
+export const ATOM_CONFIG_FILENAME = "atom.json";
+// Kept local (not imported from zen.js) so config.ts has no runtime import
+// of zen.js — zen.js imports loadAtomConfig for budget fallbacks, and a
+// runtime cycle would be fragile. Mirrors EFFORT_OPTIONS exactly.
+const EFFORT_VALUES = ["default", "low", "medium", "high", "max"];
+export function projectConfigPath(projectDir) {
+    return path.join(projectDir ?? process.cwd(), ATOM_CONFIG_FILENAME);
+}
+export function globalConfigPath(home) {
+    return path.join(home ?? homeDir(), ".atom", ATOM_CONFIG_FILENAME);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+// Parse one level's file. Returns null when absent/unreadable/invalid
+// (silent — a missing config is the normal case); otherwise the validated
+// subset plus per-key warnings.
+function parseLevel(filePath, label) {
+    const empty = { config: {}, warnings: [], present: false };
+    let raw;
+    try {
+        if (!existsSync(filePath))
+            return empty;
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch {
+        return empty;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return {
+            config: {},
+            warnings: [`${label} atom.json is not valid JSON — ignored`],
+            present: true,
+        };
+    }
+    if (!isRecord(data)) {
+        return {
+            config: {},
+            warnings: [`${label} atom.json must be a JSON object — ignored`],
+            present: true,
+        };
+    }
+    const config = {};
+    const warnings = [];
+    const bad = (key, why) => warnings.push(`${label} atom.json: ignoring invalid "${key}" (${why})`);
+    const provider = data["provider"];
+    if (provider !== undefined) {
+        if (typeof provider === "string" && isProviderId(provider)) {
+            config.provider = provider;
+        }
+        else {
+            bad("provider", "must be a known provider id");
+        }
+    }
+    const model = data["model"];
+    if (model !== undefined) {
+        if (typeof model === "string" && model.length > 0) {
+            config.model = model;
+        }
+        else {
+            bad("model", "must be a non-empty string");
+        }
+    }
+    const effort = data["reasoningEffort"];
+    if (effort !== undefined) {
+        if (typeof effort === "string" && EFFORT_VALUES.includes(effort)) {
+            config.reasoningEffort = effort;
+        }
+        else {
+            bad("reasoningEffort", `must be one of ${EFFORT_VALUES.join("/")}`);
+        }
+    }
+    const ranged = [
+        { key: "maxHistoryMessages", min: 10, max: 1000 },
+        { key: "maxHistoryChars", min: 10_000, max: 2_000_000 },
+        { key: "maxToolSteps", min: 5, max: 100 },
+        { key: "compactPct", min: 50, max: 95 },
+    ];
+    for (const { key, min, max } of ranged) {
+        const v = data[key];
+        if (v === undefined)
+            continue;
+        const n = asFiniteNumber(v);
+        if (n === undefined) {
+            bad(key, "must be a number");
+            continue;
+        }
+        // Clamp like the env-var readers (same bounds, same forgiveness), but
+        // say so — a clamped value is usually a typo worth surfacing.
+        const clamped = Math.min(Math.max(Math.floor(n), min), max);
+        if (clamped !== n) {
+            warnings.push(`${label} atom.json: "${key}" clamped to ${clamped} (range ${min}–${max})`);
+        }
+        config[key] = clamped;
+    }
+    const network = data["network"];
+    if (network !== undefined) {
+        const parsed = parseNetworkPolicy(network);
+        config.network = parsed.policy;
+        for (const w of parsed.warnings)
+            warnings.push(`${label} atom.json: ${w}`);
+    }
+    const telemetry = data["telemetry"];
+    if (telemetry !== undefined) {
+        if (!isRecord(telemetry)) {
+            warnings.push(`${label} atom.json: ignoring invalid "telemetry" (must be an object)`);
+        }
+        else {
+            const enabled = telemetry["enabled"];
+            if (enabled === undefined) {
+                // `{}` is valid: all-telemetry keys are optional, nothing to set.
+            }
+            else if (typeof enabled === "boolean") {
+                config.telemetry = { enabled };
+            }
+            else {
+                warnings.push(`${label} atom.json: ignoring invalid "telemetry.enabled" (must be a boolean)`);
+            }
+        }
+    }
+    return { config, warnings, present: true };
+}
+export function loadAtomConfig(projectDir, homeDir) {
+    const project = parseLevel(projectConfigPath(projectDir), "project");
+    const global = parseLevel(globalConfigPath(homeDir), "global");
+    return {
+        config: { ...global.config, ...project.config },
+        warnings: [...global.warnings, ...project.warnings],
+        sources: { project: project.present, global: global.present },
+    };
+}