zcode-acp-server 0.46.7 → 0.47.0

package/dist/settings/skills.js

@@ -0,0 +1,245 @@
+/**
+ * Skill management: discovery plus the actions the app's skills page offers.
+ *
+ * `config/skill-discovery.ts` exists to build the editor's command list, so it
+ * filters out disabled skills and drops the SKILL.md path (its `input.hint` is
+ * the author's argument hint, not a location). Neither works for management —
+ * a disabled skill must stay visible so the user can re-enable it, and every
+ * action needs the real path. So discovery is re-done here, over the same roots
+ * and with the same frontmatter rules.
+ *
+ * Escape guards are the point of this module: a skill path is client-supplied
+ * text that becomes a filesystem operation. Every path is resolved through
+ * `realpath` (collapsing symlinks and `..`) BEFORE the containment check, so
+ * `~/.zcode/skills/../../../etc` or a symlink pointing outside the roots can
+ * neither delete nor copy anything outside them. The app's own delete path
+ * carries the same guard.
+ */
+import { cp, mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { setSkillEnabled } from "./cli-config.js";
+import { log, zcodeHomeDir } from "../utils.js";
+/**
+ * Discovery roots, in the app's own order: user scope first (its skills win a
+ * name clash), then the shared `~/.agents` root, then plugin caches.
+ */
+export function skillRoots() {
+    const home = zcodeHomeDir();
+    return [
+        { dir: path.join(home, "skills"), scope: "user", deletable: true },
+        { dir: path.join(homedir(), ".agents", "skills"), scope: "agents", deletable: true },
+        { dir: path.join(home, "cli", "plugins", "cache"), scope: "plugin", deletable: false },
+    ];
+}
+/** The user-scope root new skills are copied into. */
+export function userSkillsRoot() {
+    return path.join(zcodeHomeDir(), "skills");
+}
+/** Resolve through symlinks; fall back to the lexical form when absent. */
+async function resolveReal(target) {
+    try {
+        return await realpath(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+/** True when `target` is `root` itself or inside it — both sides resolved. */
+async function isInside(target, root) {
+    const rel = path.relative(await resolveReal(root), await resolveReal(target));
+    return rel === "" || (!rel.startsWith(`..${path.sep}`) && rel !== ".." && !path.isAbsolute(rel));
+}
+/** Minimal SKILL.md frontmatter reader — name and description only. */
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const fm = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        let value = line.slice(idx + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        fm[line.slice(0, idx).trim()] = value;
+    }
+    return fm;
+}
+/**
+ * The set of disabled SKILL.md paths from `cli/config.json`.
+ *
+ * Keys are normalized (backslashes to forward slashes) the way the app
+ * normalizes them, so a config written on Windows still matches a POSIX
+ * discovery path.
+ */
+async function disabledSkillPaths() {
+    try {
+        const raw = await readFile(path.join(zcodeHomeDir(), "cli", "config.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        const out = new Set();
+        for (const [key, value] of Object.entries(parsed.skills ?? {})) {
+            if (value?.enable === false)
+                out.add(key.replace(/\\/gu, "/"));
+        }
+        return out;
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Every skill, enabled or not.
+ *
+ * Duplicate names are kept rather than de-duplicated: the app lists the same
+ * name from two scopes separately (they are different files), and hiding one
+ * would make its toggle unreachable.
+ */
+export async function listSkills() {
+    const disabled = await disabledSkillPaths();
+    const out = [];
+    for (const root of skillRoots()) {
+        let entries;
+        try {
+            entries = await readdirSafe(root.dir);
+        }
+        catch {
+            continue; // root absent — normal on a machine without that source
+        }
+        for (const entry of entries) {
+            const dir = path.join(root.dir, entry);
+            const skillMd = path.join(dir, "SKILL.md");
+            try {
+                if (!(await stat(dir)).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let content;
+            try {
+                content = await readFile(skillMd, "utf8");
+            }
+            catch {
+                continue; // not a skill directory
+            }
+            const fm = parseSkillFrontmatter(content);
+            const name = fm["name"] ?? entry;
+            if (!name || !fm["description"])
+                continue; // the runtime skips these too
+            if (fm["user-invocable"] === "false")
+                continue;
+            const absPath = path.resolve(skillMd);
+            out.push({
+                name,
+                description: fm["description"],
+                path: absPath,
+                dir,
+                scope: root.scope,
+                enabled: !disabled.has(absPath.replace(/\\/gu, "/")),
+            });
+        }
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+    return out;
+}
+async function readdirSafe(dir) {
+    const { readdir } = await import("node:fs/promises");
+    try {
+        return await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** Enable or disable a skill by its SKILL.md path. */
+export async function setSkillEnabledByPath(skillPath, enable) {
+    assertSkillPath(skillPath);
+    // The stored key uses forward slashes regardless of platform.
+    await setSkillEnabled(skillPath.replace(/\\/gu, "/"), enable);
+}
+function assertSkillPath(skillPath) {
+    if (!path.isAbsolute(skillPath)) {
+        throw new Error("skill path must be absolute");
+    }
+    if (path.basename(skillPath) !== "SKILL.md") {
+        throw new Error("skill path must point at a SKILL.md file");
+    }
+}
+/**
+ * Delete a skill directory.
+ *
+ * Only skills inside a deletable root can go: a plugin's skill belongs to the
+ * plugin install and would reappear on the next update, so the API refuses
+ * rather than deleting something that comes back. The containment check runs on
+ * RESOLVED paths, so a symlinked skill directory cannot point the delete at
+ * something outside the roots.
+ */
+export async function deleteSkill(skillPath) {
+    assertSkillPath(skillPath);
+    const dir = path.dirname(skillPath);
+    // Every deletable root counts, not just the first one — the agents scope
+    // (`~/.agents/skills`) is listed and copyable, so refusing to delete it made
+    // half the listed skills undeletable.
+    const roots = skillRoots().filter((r) => r.deletable);
+    let root;
+    for (const candidate of roots) {
+        if (await isInside(dir, candidate.dir)) {
+            root = candidate;
+            break;
+        }
+    }
+    if (!root) {
+        throw new Error("only skills under the user skill roots can be deleted");
+    }
+    // `isInside` treats the root itself as contained — refuse that explicitly.
+    if ((await resolveReal(dir)) === (await resolveReal(root.dir))) {
+        throw new Error("refusing to delete the skills root itself");
+    }
+    await rm(dir, { recursive: true, force: true });
+}
+/**
+ * Copy a skill into the user root.
+ *
+ * A name collision is refused rather than merged: silently merging two skill
+ * directories yields a SKILL.md whose description matches neither original.
+ */
+export async function copySkillToUser(skillPath) {
+    assertSkillPath(skillPath);
+    const sourceDir = path.dirname(skillPath);
+    // Containment on resolved paths: a symlinked skill elsewhere on disk must not
+    // be copyable through this API.
+    let owned = false;
+    for (const root of skillRoots()) {
+        if (root.scope !== "plugin" && (await isInside(sourceDir, root.dir))) {
+            owned = true;
+            break;
+        }
+    }
+    if (!owned) {
+        throw new Error("only skills under the user skill roots can be copied");
+    }
+    const targetRoot = userSkillsRoot();
+    const name = path.basename(sourceDir);
+    const target = path.join(targetRoot, name);
+    if ((await resolveReal(target)) === (await resolveReal(sourceDir))) {
+        throw new Error("this skill already lives in the user skills root");
+    }
+    try {
+        if ((await stat(target)).isDirectory()) {
+            throw new Error(`a skill named '${name}' already exists in the user skills root`);
+        }
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    await mkdir(targetRoot, { recursive: true });
+    await cp(sourceDir, target, { recursive: true });
+    log(`settings: copied skill '${name}' to ${target}`);
+    return path.join(target, "SKILL.md");
+}
+//# sourceMappingURL=skills.js.map

package/dist/settings/skills.js.map

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

package/dist/settings/usage-stats.d.ts

@@ -0,0 +1,74 @@
+/**
+ * App usage stats, aggregated from the local agent database.
+ *
+ * The desktop app's App Usage panel reads `~/.zcode/cli/db/db.sqlite`
+ * (`model_usage` / `turn_usage` / `tool_usage`). Rather than proxying the
+ * backend's `usage/stats` RPC — which couples a settings screen to a live
+ * backend process and whose `.strict()` params turn any schema drift into a
+ * hard failure — the same tables are aggregated here in read-only mode
+ * (ADR-0027).
+ *
+ * Two things this module is careful about:
+ *
+ *  - **Never blocking the writer.** The connection is opened read-only and every
+ *    query is a bounded aggregate. A `SQLITE_BUSY` degrades to the same
+ *    `available: false` shape a missing database produces, because the caller
+ *    renders an empty state either way.
+ *  - **Never claiming data that is not there.** A machine that never ran an
+ *    agent has no database; that is a normal state, so the response says
+ *    `available: false` with zero values instead of erroring.
+ *
+ * Day buckets use the process timezone offset. The app does the same and notes
+ * the same ≤1h DST imprecision; for a usage overview that is not worth the
+ * complexity of a per-request timezone.
+ */
+export type UsageRange = "7d" | "30d" | "all";
+export interface ModelUsageRow {
+    modelId: string | null;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    requestCount: number;
+    /** Fraction of the window's total tokens, 0..1. */
+    share: number;
+}
+export interface DailyUsageRow {
+    /** Local calendar day, `YYYY-MM-DD`. */
+    date: string;
+    models: Array<{
+        modelId: string | null;
+        totalTokens: number;
+    }>;
+}
+export interface UsageSnapshot {
+    /** false when the database is absent — an empty state, not an error. */
+    available: boolean;
+    range: UsageRange;
+    summary: {
+        totalTokens: number;
+        inputTokens: number;
+        outputTokens: number;
+        reasoningTokens: number;
+        cacheReadTokens: number;
+        requestCount: number;
+        sessionCount: number;
+        turnCount: number;
+        toolCallCount: number;
+        models: number;
+        activeDays: number;
+    };
+    models: ModelUsageRow[];
+    daily: DailyUsageRow[];
+}
+/**
+ * Aggregate the window.
+ *
+ * Two queries: one per-model roll-up, one per-day roll-up. Both are grouped
+ * server-side by sqlite, so the bridge transfers only the aggregated rows —
+ * the raw table on a developed machine holds tens of thousands of rows.
+ */
+export declare function readUsageStats(range?: UsageRange): Promise<UsageSnapshot>;
+//# sourceMappingURL=usage-stats.d.ts.map

package/dist/settings/usage-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-stats.d.ts","sourceRoot":"","sources":["../../src/settings/usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA6DH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AA6BD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,KAAK,GAAE,UAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CA8HrF"}

package/dist/settings/usage-stats.js

@@ -0,0 +1,235 @@
+/**
+ * App usage stats, aggregated from the local agent database.
+ *
+ * The desktop app's App Usage panel reads `~/.zcode/cli/db/db.sqlite`
+ * (`model_usage` / `turn_usage` / `tool_usage`). Rather than proxying the
+ * backend's `usage/stats` RPC — which couples a settings screen to a live
+ * backend process and whose `.strict()` params turn any schema drift into a
+ * hard failure — the same tables are aggregated here in read-only mode
+ * (ADR-0027).
+ *
+ * Two things this module is careful about:
+ *
+ *  - **Never blocking the writer.** The connection is opened read-only and every
+ *    query is a bounded aggregate. A `SQLITE_BUSY` degrades to the same
+ *    `available: false` shape a missing database produces, because the caller
+ *    renders an empty state either way.
+ *  - **Never claiming data that is not there.** A machine that never ran an
+ *    agent has no database; that is a normal state, so the response says
+ *    `available: false` with zero values instead of erroring.
+ *
+ * Day buckets use the process timezone offset. The app does the same and notes
+ * the same ≤1h DST imprecision; for a usage overview that is not worth the
+ * complexity of a per-request timezone.
+ */
+import { createRequire } from "node:module";
+import { log, warn, zcodeUsageDbPath } from "../utils.js";
+/**
+ * Cached constructor; null when node:sqlite is unavailable (Node < 22).
+ *
+ * Loaded through `createRequire` rather than a dynamic `import`: under vite
+ * (the test runner) `import("node:sqlite")` is intercepted and fails to
+ * resolve, which would silently disable usage stats in every test. `require`
+ * resolves Node built-ins directly.
+ */
+let sqliteCtor;
+function loadSqlite() {
+    if (sqliteCtor !== undefined)
+        return sqliteCtor;
+    try {
+        const require = createRequire(import.meta.url);
+        const mod = require("node:sqlite");
+        sqliteCtor = mod.DatabaseSync;
+    }
+    catch {
+        sqliteCtor = null;
+    }
+    return sqliteCtor;
+}
+/** A `database is locked/busy` throw from node:sqlite (see tasks-index.ts). */
+function isBusyError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return /database is (busy|locked)/i.test(msg);
+}
+const BUSY_RETRY_DELAYS_MS = [200, 400];
+/**
+ * Open the usage db read-only, retrying briefly on writer contention.
+ *
+ * Synchronous on purpose: a settings request is a single short operation, and
+ * blocking the event loop for at most 600ms is cheaper than making every caller
+ * async. `Atomics.wait` is the synchronous sleep that does not busy-spin.
+ */
+function openReadOnly(dbPath) {
+    const Ctor = loadSqlite();
+    if (!Ctor)
+        return null;
+    const sleeper = new Int32Array(new SharedArrayBuffer(4));
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return new Ctor(dbPath, { readOnly: true });
+        }
+        catch (error) {
+            const delay = BUSY_RETRY_DELAYS_MS[attempt];
+            if (delay === undefined || !isBusyError(error))
+                return null;
+            Atomics.wait(sleeper, 0, 0, delay);
+        }
+    }
+}
+const EMPTY_SNAPSHOT = (range) => ({
+    available: false,
+    range,
+    summary: {
+        totalTokens: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        reasoningTokens: 0,
+        cacheReadTokens: 0,
+        requestCount: 0,
+        sessionCount: 0,
+        turnCount: 0,
+        toolCallCount: 0,
+        models: 0,
+        activeDays: 0,
+    },
+    models: [],
+    daily: [],
+});
+/** Range → the `started_at` floor (ms epoch). `all` has no floor. */
+function rangeFloor(range, now) {
+    if (range === "7d")
+        return now - 7 * 86_400_000;
+    if (range === "30d")
+        return now - 30 * 86_400_000;
+    return 0;
+}
+/**
+ * Aggregate the window.
+ *
+ * Two queries: one per-model roll-up, one per-day roll-up. Both are grouped
+ * server-side by sqlite, so the bridge transfers only the aggregated rows —
+ * the raw table on a developed machine holds tens of thousands of rows.
+ */
+export async function readUsageStats(range = "7d") {
+    const db = openReadOnly(zcodeUsageDbPath());
+    if (!db) {
+        log("settings: usage database unavailable — reporting an empty snapshot");
+        return EMPTY_SNAPSHOT(range);
+    }
+    try {
+        const floor = rangeFloor(range, Date.now());
+        const modelRows = db
+            .prepare(`SELECT model_id,
+                COALESCE(SUM(computed_total_tokens), 0) AS total_tokens,
+                COALESCE(SUM(input_tokens), 0)            AS input_tokens,
+                COALESCE(SUM(output_tokens), 0)           AS output_tokens,
+                COALESCE(SUM(reasoning_tokens), 0)        AS reasoning_tokens,
+                COALESCE(SUM(cache_read_input_tokens), 0) AS cache_read_tokens,
+                COALESCE(SUM(cache_creation_input_tokens), 0) AS cache_creation_tokens,
+                COUNT(*)                                  AS request_count
+           FROM model_usage
+          WHERE started_at > ?
+          GROUP BY model_id
+          ORDER BY total_tokens DESC`)
+            .all(floor);
+        // Group by LOCAL calendar day, computed by sqlite. Dividing the epoch by
+        // 86400000 would bucket on UTC, which puts a morning session in the wrong
+        // day for every timezone east or west of it — the same imprecision the app
+        // documents for its own day buckets.
+        const dayRows = db
+            .prepare(`SELECT date(started_at / 1000, 'unixepoch', 'localtime') AS day,
+                model_id,
+                COALESCE(SUM(computed_total_tokens), 0) AS total_tokens
+           FROM model_usage
+          WHERE started_at > ?
+          GROUP BY day, model_id
+          ORDER BY day ASC`)
+            .all(floor);
+        // Session/turn/tool counts describe the same window but come from their own
+        // tables; a missing table reads as zero rather than failing the snapshot.
+        const scalar = (sql) => {
+            try {
+                const row = db.prepare(sql).get(floor);
+                return Number(row?.["c"] ?? 0);
+            }
+            catch {
+                return 0;
+            }
+        };
+        const sessionCount = scalar("SELECT COUNT(DISTINCT session_id) AS c FROM turn_usage WHERE started_at > ?");
+        const turnCount = scalar("SELECT COUNT(*) AS c FROM turn_usage WHERE started_at > ?");
+        const toolCallCount = scalar("SELECT COUNT(*) AS c FROM tool_usage WHERE started_at > ?");
+        const grandTotal = modelRows.reduce((sum, r) => sum + Number(r["total_tokens"] ?? 0), 0);
+        const models = modelRows.map((r) => {
+            const total = Number(r["total_tokens"] ?? 0);
+            return {
+                modelId: typeof r["model_id"] === "string" ? r["model_id"] : null,
+                totalTokens: total,
+                inputTokens: Number(r["input_tokens"] ?? 0),
+                outputTokens: Number(r["output_tokens"] ?? 0),
+                reasoningTokens: Number(r["reasoning_tokens"] ?? 0),
+                cacheReadTokens: Number(r["cache_read_tokens"] ?? 0),
+                cacheCreationTokens: Number(r["cache_creation_tokens"] ?? 0),
+                requestCount: Number(r["request_count"] ?? 0),
+                share: grandTotal > 0 ? round4(total / grandTotal) : 0,
+            };
+        });
+        // The day rows arrive already grouped by sqlite; only the per-day model
+        // ordering (by volume, so a chart's legend matches its bars) is done here.
+        const byDay = new Map();
+        for (const row of dayRows) {
+            const day = typeof row["day"] === "string" ? row["day"] : "";
+            if (!day)
+                continue;
+            const modelId = typeof row["model_id"] === "string" ? row["model_id"] : "(unknown)";
+            const bucket = byDay.get(day) ?? new Map();
+            bucket.set(modelId, (bucket.get(modelId) ?? 0) + Number(row["total_tokens"] ?? 0));
+            byDay.set(day, bucket);
+        }
+        const daily = Array.from(byDay.entries())
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([date, bucket]) => ({
+            date,
+            models: Array.from(bucket.entries())
+                .map(([modelId, totalTokens]) => ({ modelId, totalTokens }))
+                .sort((a, b) => b.totalTokens - a.totalTokens),
+        }));
+        return {
+            available: true,
+            range,
+            summary: {
+                totalTokens: grandTotal,
+                inputTokens: models.reduce((s, m) => s + m.inputTokens, 0),
+                outputTokens: models.reduce((s, m) => s + m.outputTokens, 0),
+                reasoningTokens: models.reduce((s, m) => s + m.reasoningTokens, 0),
+                cacheReadTokens: models.reduce((s, m) => s + m.cacheReadTokens, 0),
+                requestCount: models.reduce((s, m) => s + m.requestCount, 0),
+                sessionCount,
+                turnCount,
+                toolCallCount,
+                models: models.length,
+                activeDays: daily.length,
+            },
+            models,
+            daily,
+        };
+    }
+    catch (error) {
+        // A schema drift (a renamed column) must not break the settings screen;
+        // the rest of the API is unaffected.
+        warn(`settings: usage aggregation failed: ${error instanceof Error ? error.message : String(error)}`);
+        return EMPTY_SNAPSHOT(range);
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}
+function round4(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+//# sourceMappingURL=usage-stats.js.map

package/dist/settings/usage-stats.js.map

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

package/dist/utils.d.ts

@@ -37,6 +37,20 @@ export declare function zcodePersonalProviderPath(): string;
 export declare function zcodeCliConfigPath(): string;
 /** Root of the ZCode plugin cache directory (per call — see above). */
 export declare function zcodePluginCacheDir(): string;
+/**
+ * Root of the ZCode user-scope agent definitions (`~/.zcode/agents/*.md`).
+ * Per call, so discovery follows a `ZCODE_HOME` change made after import.
+ */
+export declare function zcodeAgentsDir(): string;
+/**
+ * Path of the agent state file (`~/.zcode/v2/agents-state.json`): per-agent
+ * enablement plus the built-in agents' model overrides. Per call — see above.
+ */
+export declare function zcodeAgentsStatePath(): string;
+/** Path of the CLI agent database (`~/.zcode/cli/db/db.sqlite`) — usage stats. */
+export declare function zcodeUsageDbPath(): string;
+/** Path of the encrypted credential store (`~/.zcode/v2/credentials.json`). */
+export declare function zcodeCredentialsPath(): string;
 /**
  * Slash commands surfaced to the editor. Each maps to a ZCode session method
  * that the server forwards when the user types the command.

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAmBlC,4DAA4D;AAC5D,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAiD,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCjB,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,WAAW;;;;0BAIL,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B/C,CAAC;AAEX,iGAAiG;AACjG,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGhF,CAAC;AAqBF,qEAAqE;AACrE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrC;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB5D"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAmBlC,4DAA4D;AAC5D,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAiD,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCjB,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,WAAW;;;;0BAIL,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B/C,CAAC;AAEX,iGAAiG;AACjG,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGhF,CAAC;AAqBF,qEAAqE;AACrE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrC;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB5D"}

package/dist/utils.js

@@ -67,6 +67,28 @@ export function zcodeCliConfigPath() {
 export function zcodePluginCacheDir() {
     return path.join(zcodeHomeDir(), "cli", "plugins", "cache");
 }
+/**
+ * Root of the ZCode user-scope agent definitions (`~/.zcode/agents/*.md`).
+ * Per call, so discovery follows a `ZCODE_HOME` change made after import.
+ */
+export function zcodeAgentsDir() {
+    return path.join(zcodeHomeDir(), "agents");
+}
+/**
+ * Path of the agent state file (`~/.zcode/v2/agents-state.json`): per-agent
+ * enablement plus the built-in agents' model overrides. Per call — see above.
+ */
+export function zcodeAgentsStatePath() {
+    return path.join(zcodeHomeDir(), "v2", "agents-state.json");
+}
+/** Path of the CLI agent database (`~/.zcode/cli/db/db.sqlite`) — usage stats. */
+export function zcodeUsageDbPath() {
+    return path.join(zcodeHomeDir(), "cli", "db", "db.sqlite");
+}
+/** Path of the encrypted credential store (`~/.zcode/v2/credentials.json`). */
+export function zcodeCredentialsPath() {
+    return path.join(zcodeHomeDir(), "v2", "credentials.json");
+}
 /**
  * Slash commands surfaced to the editor. Each maps to a ZCode session method
  * that the server forwards when the user types the command.