zcode-acp-server 0.46.7 → 0.47.0

package/dist/settings/cli-config.js

@@ -0,0 +1,320 @@
+/**
+ * Read/write for the ZCode CLI config (`~/.zcode/cli/config.json`).
+ *
+ * ONE file, four independent owners: skills enablement, MCP servers, hooks, and
+ * plugins. Every writer is therefore a read-modify-write that preserves keys it
+ * does not recognise — the file also carries agent-runtime settings owned by
+ * the backend, and rewriting from a partial model would silently delete them.
+ *
+ * The enable/disable spellings are not symmetric, and getting them wrong makes
+ * a toggle look broken while the file is technically valid:
+ *
+ *  - **skills**: key = the SKILL.md absolute path, value `{enable: false}`.
+ *    `enable: true` is the DEFAULT and must DELETE the key — writing `true`
+ *    leaves a permanent override that shadows later enablement changes.
+ *  - **MCP**: `enabled: false` inside the server object. Same rule: `true`
+ *    deletes the key (and a legacy `enable` key is migrated on the way).
+ *  - **hooks**: a whole different shape — a nested tree under `hooks`, gated by
+ *    a top-level `hooks.enabled: true`. WITHOUT that flag every hook in the file
+ *    is inert, which is the single most common way a hand-written config does
+ *    nothing.
+ *  - **plugins**: `enabledPlugins` / `suppressedBuiltins` maps keyed by
+ *    `<name>@<marketplace>`.
+ *
+ * None of these are hot-reloaded by the agent: `cli/config.json` is read once
+ * at agent start (MCP servers are frozen into the runtime config), except the
+ * skills enablement map which the host re-reads live. Writes therefore report
+ * `needs-restart` for MCP and hooks, `immediate` for skills.
+ */
+import { readFile } from "node:fs/promises";
+import { readJsonDocument, writeJsonAtomic } from "./atomic-write.js";
+import { zcodeCliConfigPath } from "../utils.js";
+/** The seven hook events the schema accepts, in its own order. */
+export const HOOK_EVENT_NAMES = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "Stop",
+];
+/**
+ * Read the CLI config.
+ *
+ * @throws when the file exists but is malformed. Unlike the app's skills
+ *         writer (which silently reads damage as `{}` and would then rewrite
+ *         the file from an empty base), this refuses — the caller surfaces an
+ *         error instead of destroying what is left of the document.
+ */
+export async function readCliConfig() {
+    const doc = await readJsonDocument(zcodeCliConfigPath());
+    return (doc ?? {});
+}
+/** Structural check for the parts of the file this module owns. */
+export function validateCliConfig(doc) {
+    const skills = doc["skills"];
+    if (skills !== undefined && !isRecord(skills))
+        return "skills must be an object";
+    const mcp = doc["mcp"];
+    if (mcp !== undefined) {
+        if (!isRecord(mcp))
+            return "mcp must be an object";
+        const servers = mcp["servers"];
+        if (servers !== undefined && !isRecord(servers))
+            return "mcp.servers must be an object";
+        if (isRecord(servers)) {
+            for (const [name, server] of Object.entries(servers)) {
+                if (!isRecord(server))
+                    return `mcp.servers.${name} must be an object`;
+            }
+        }
+    }
+    const hooks = doc["hooks"];
+    if (hooks !== undefined) {
+        if (!isRecord(hooks))
+            return "hooks must be an object";
+        const events = hooks["events"];
+        if (events !== undefined) {
+            if (!isRecord(events))
+                return "hooks.events must be an object";
+            for (const [event, matchers] of Object.entries(events)) {
+                if (!HOOK_EVENT_NAMES.includes(event)) {
+                    return `hooks.events.${event} is not a known event name`;
+                }
+                if (!Array.isArray(matchers))
+                    return `hooks.events.${event} must be an array`;
+                for (const matcher of matchers) {
+                    if (!isRecord(matcher))
+                        return `hooks.events.${event} entries must be objects`;
+                    if (!Array.isArray(matcher["hooks"]) || matcher["hooks"].length === 0) {
+                        return `hooks.events.${event} matcher needs at least one hook`;
+                    }
+                    for (const hook of matcher["hooks"]) {
+                        if (!isRecord(hook))
+                            return "a hook entry must be an object";
+                        const type = hook["type"];
+                        if (type !== "command" && type !== "process") {
+                            return "a hook entry needs type 'command' or 'process'";
+                        }
+                        if (typeof hook["command"] !== "string" || !hook["command"]) {
+                            return "a hook entry needs a non-empty command";
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const plugins = doc["plugins"];
+    if (plugins !== undefined && !isRecord(plugins))
+        return "plugins must be an object";
+    return true;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The single write path for this file. */
+async function saveCliConfig(mutator) {
+    const { doc } = await writeJsonAtomic(zcodeCliConfigPath(), async (current) => {
+        const next = await mutator(current);
+        return next;
+    }, { validate: (d) => validateCliConfig(d) });
+    return doc;
+}
+// ---------- skills ----------
+/**
+ * Set a skill's enabled state.
+ *
+ * `enable: true` REMOVES the override rather than writing `true` — enabled is
+ * the default state, and a stored `true` is a permanent pin that would shadow
+ * the file's real state.
+ */
+export async function setSkillEnabled(skillPath, enable) {
+    return saveCliConfig((doc) => {
+        const skills = { ...(doc.skills ?? {}) };
+        if (enable)
+            delete skills[skillPath];
+        else
+            skills[skillPath] = { enable: false };
+        return applySkillsBlock(doc, skills);
+    });
+}
+/** Drop the whole `skills` block when every entry is enabled (the app's rule). */
+function applySkillsBlock(doc, skills) {
+    const next = { ...doc };
+    if (Object.keys(skills).length === 0)
+        delete next.skills;
+    else
+        next.skills = skills;
+    return next;
+}
+// ---------- mcp ----------
+/**
+ * Create or update an MCP server.
+ *
+ * `enabled: true` deletes the flag (and a legacy `enable` key) instead of
+ * storing it; only a DISABLE is worth persisting.
+ */
+export async function upsertMcpServer(name, server) {
+    assertMcpName(name);
+    return saveCliConfig((doc) => {
+        const servers = { ...(doc.mcp?.servers ?? {}) };
+        const existing = servers[name] ?? {};
+        const merged = { ...existing, ...server };
+        delete merged["enable"];
+        if (merged.enabled === true)
+            delete merged.enabled;
+        servers[name] = merged;
+        return { ...doc, mcp: { ...(doc.mcp ?? {}), servers } };
+    });
+}
+/** Enable or disable an existing MCP server. */
+export async function setMcpServerEnabled(name, enabled) {
+    return saveCliConfig((doc) => {
+        const servers = { ...(doc.mcp?.servers ?? {}) };
+        const existing = servers[name];
+        if (!existing)
+            throw new Error(`MCP server '${name}' is not configured`);
+        const merged = { ...existing };
+        delete merged["enable"];
+        if (enabled)
+            delete merged.enabled;
+        else
+            merged.enabled = false;
+        servers[name] = merged;
+        return { ...doc, mcp: { ...(doc.mcp ?? {}), servers } };
+    });
+}
+export async function removeMcpServer(name) {
+    return saveCliConfig((doc) => {
+        const servers = { ...(doc.mcp?.servers ?? {}) };
+        if (!(name in servers))
+            throw new Error(`MCP server '${name}' is not configured`);
+        delete servers[name];
+        return { ...doc, mcp: { ...(doc.mcp ?? {}), servers } };
+    });
+}
+function assertMcpName(name) {
+    if (!name || /[\\/]/.test(name)) {
+        throw new Error("MCP server name must be non-empty and free of path separators");
+    }
+}
+// ---------- hooks ----------
+/**
+ * Read the hooks tree. Returns the raw config; an absent file yields `{}`.
+ *
+ * Note the returned `enabled` flag: hooks are inert unless the top-level flag
+ * is `true`, so callers must surface it rather than inferring it.
+ */
+export async function readHooks() {
+    const doc = await readCliConfig();
+    return doc.hooks ?? {};
+}
+/**
+ * Set the global hooks switch.
+ *
+ * A file full of hooks with `enabled` absent runs NOTHING — the runtime root
+ * defaults to disabled. This is the one field that turns the whole tree on.
+ */
+export async function setHooksEnabled(enabled) {
+    return saveCliConfig((doc) => {
+        const hooks = { ...(doc.hooks ?? {}) };
+        if (enabled)
+            hooks.enabled = true;
+        else
+            delete hooks.enabled;
+        return { ...doc, hooks };
+    });
+}
+/**
+ * Edit ONE existing hook entry in place.
+ *
+ * Deliberately not a create path: the matcher list is an array of arrays, and
+ * an insert shifts every later index, so a remote "add a hook" call races with
+ * any concurrent edit of the same event. Editing an existing entry's
+ * command/timeout/enabled covers the real use case (temporarily disable one,
+ * tweak a command) without that hazard.
+ *
+ * Unknown keys on the hook object are preserved: the schema is `.passthrough()`
+ * precisely so extensions can ride along.
+ */
+export async function updateHookEntry(event, matcherIndex, hookIndex, patch) {
+    if (!HOOK_EVENT_NAMES.includes(event)) {
+        throw new Error(`unknown hook event '${event}'`);
+    }
+    if (!Number.isInteger(matcherIndex) || matcherIndex < 0) {
+        throw new Error("matcherIndex must be a non-negative integer");
+    }
+    if (!Number.isInteger(hookIndex) || hookIndex < 0) {
+        throw new Error("hookIndex must be a non-negative integer");
+    }
+    if (patch.timeoutMs !== undefined &&
+        (!Number.isFinite(patch.timeoutMs) || patch.timeoutMs <= 0)) {
+        throw new Error("timeoutMs must be a positive number");
+    }
+    if (patch.timeout !== undefined && (!Number.isFinite(patch.timeout) || patch.timeout <= 0)) {
+        throw new Error("timeout must be a positive number of seconds");
+    }
+    if (patch.command !== undefined && !patch.command) {
+        throw new Error("command must be non-empty");
+    }
+    return saveCliConfig((doc) => {
+        const hooks = { ...(doc.hooks ?? {}) };
+        const events = { ...(hooks.events ?? {}) };
+        const matchers = [...(events[event] ?? [])];
+        const matcher = matchers[matcherIndex];
+        if (!matcher)
+            throw new Error(`no matcher at index ${matcherIndex} for ${event}`);
+        const entries = [...matcher.hooks];
+        const entry = entries[hookIndex];
+        if (!entry)
+            throw new Error(`no hook at index ${hookIndex} in ${event} matcher ${matcherIndex}`);
+        // Explicit `enabled: true` removes the flag: enabled is the default, and a
+        // stored `true` is a pin that survives later enablement changes.
+        const merged = { ...entry };
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined)
+                continue;
+            if (key === "enabled") {
+                if (value === true)
+                    delete merged.enabled;
+                else
+                    merged.enabled = value;
+                continue;
+            }
+            merged[key] = value;
+        }
+        entries[hookIndex] = merged;
+        matchers[matcherIndex] = { ...matcher, hooks: entries };
+        events[event] = matchers;
+        hooks.events = events;
+        return { ...doc, hooks };
+    });
+}
+// ---------- plugins ----------
+/** Enable or disable a plugin by its `<name>@<marketplace>` key. */
+export async function setPluginEnabled(pluginKey, enabled) {
+    if (!pluginKey.includes("@")) {
+        throw new Error("plugin key must be '<name>@<marketplace>'");
+    }
+    return saveCliConfig((doc) => {
+        const plugins = { ...(doc.plugins ?? {}) };
+        const enabledPlugins = { ...(plugins.enabledPlugins ?? {}) };
+        if (enabled)
+            delete enabledPlugins[pluginKey];
+        else
+            enabledPlugins[pluginKey] = false;
+        plugins.enabledPlugins = enabledPlugins;
+        return { ...doc, plugins };
+    });
+}
+/** Raw text for the settings snapshot. Absent → null. */
+export async function readCliConfigRaw() {
+    try {
+        return await readFile(zcodeCliConfigPath(), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cli-config.js.map

package/dist/settings/cli-config.js.map

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

package/dist/settings/coding-plan.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Coding-plan quota reset cards.
+ *
+ * The desktop app exposes "reset cards" — a limited number of quota resets the
+ * user can spend to clear a 5-hour or weekly window. This module is the headless
+ * equivalent: the same four endpoints, the same headers, the same credentials,
+ * so a client that cannot open the app still gets the feature.
+ *
+ * Credentials are the hard part. They live in `~/.zcode/v2/credentials.json`,
+ * AES-256-GCM encrypted, keyed by `ZCODE_CREDENTIAL_SECRET` or a machine-bound
+ * fallback string. Two tokens are needed and they are NOT interchangeable:
+ *
+ *  - `zcodejwttoken` → `Authorization: Bearer …`
+ *  - the OAuth access token for the CURRENT provider family → `X-Bigmodel-Authorization`
+ *
+ * Picking the family correctly matters: a `zai`-only account has no bigmodel
+ * token, and falling back across families would send a token the backend
+ * rejects. The family is read from the provider id (`account:zai-…` vs
+ * `account:bigmodel-…`), which is the same spelling the registry uses.
+ *
+ * Known limit: a TEAM plan's requests need `Bigmodel-Organization` /
+ * `Bigmodel-Project` headers, and the ids are not in the credential store a
+ * headless process can read. Team-plan resets therefore answer a backend error
+ * rather than working; personal plans (the common case) are unaffected.
+ *
+ * This is the ONLY irreversible operation in the settings API. A spent card is
+ * gone. `use()` therefore takes an idempotency key so a retry (a dropped
+ * response, a double tap) cannot burn two cards, and the route layer requires a
+ * fresh status nonce before it will call it.
+ */
+export type ResetFamily = "zai" | "bigmodel";
+export type ResetType = "FIVE_HOUR" | "WEEK";
+export interface ResetCardStatus {
+    /** Cards still available, with their expiry (epoch ms). */
+    availableFiveHour: Array<{
+        expireAt: number;
+    }>;
+    availableWeek: Array<{
+        expireAt: number;
+    }>;
+    latestFiveHour: {
+        usedAt: number;
+    } | null;
+    latestWeek: {
+        usedAt: number;
+    } | null;
+    hasUnreadHistory: boolean;
+    /**
+     * Opaque token the client must send back with `use()`. Ties a spend to a
+     * status read made moments earlier, so a stale screen cannot consume a card
+     * the user has already seen change.
+     */
+    nonce: string;
+}
+export interface ResetAuthorization {
+    zcodeAuthorization: string;
+    codingPlanAuthorization: string;
+    /** Present for team plans; absent for personal ones. */
+    teamContext?: {
+        organizationId: string;
+        projectId: string;
+    };
+}
+/** Which family a provider id belongs to. */
+export declare function resetFamilyFor(providerId: string): ResetFamily;
+/** True when the provider id can own a coding plan. */
+export declare function isCodingPlanProvider(providerId: string): boolean;
+/**
+ * Resolve both tokens for a reset request.
+ *
+ * @throws `coding_plan_provider_required` for a non-account provider,
+ *         `credentials_unavailable` when the store cannot be decrypted, and
+ *         `coding_plan_<x>_jwt_required` when a token is missing.
+ */
+export declare function resolveResetAuthorization(providerId: string, env?: NodeJS.ProcessEnv): Promise<ResetAuthorization>;
+/** Fetch the current card inventory. */
+export declare function readResetStatus(providerId: string, fetchImpl?: typeof globalThis.fetch, env?: NodeJS.ProcessEnv): Promise<ResetCardStatus>;
+export interface ResetUseResult {
+    used: boolean;
+    /** Set when the backend declined the opportunity (code 3301). */
+    nextTryAt?: number;
+}
+/**
+ * Spend one card.
+ *
+ * The idempotency key is what makes a retry safe: the same key always answers
+ * the same outcome instead of consuming a second card. The caller supplies it
+ * (the route layer derives one per request), so a client that retries can
+ * reuse the value it already sent.
+ */
+export declare function useResetCard(providerId: string, resetType: ResetType, idempotencyKey: string, fetchImpl?: typeof globalThis.fetch, env?: NodeJS.ProcessEnv): Promise<ResetUseResult>;
+/**
+ * Ask whether a reset would be granted right now.
+ *
+ * A denial (code 3301) is a normal answer carrying `next_try_at`, not a
+ * failure — the UI shows a countdown rather than an error.
+ */
+export declare function requestResetOpportunity(providerId: string, idempotencyKey: string, fetchImpl?: typeof globalThis.fetch, env?: NodeJS.ProcessEnv): Promise<{
+    granted: boolean;
+    nextTryAt: number | null;
+}>;
+/** Mark the reset history read (clears the unread badge). */
+export declare function markResetHistoryRead(providerId: string, fetchImpl?: typeof globalThis.fetch, env?: NodeJS.ProcessEnv): Promise<void>;
+/** Exposed for the eligibility check the route layer runs before any spend. */
+export declare function codingPlanProviderIds(): string[];
+//# sourceMappingURL=coding-plan.d.ts.map

package/dist/settings/coding-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-plan.d.ts","sourceRoot":"","sources":["../../src/settings/coding-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA4BH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,UAAU,CAAC;AAC7C,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,iBAAiB,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,aAAa,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1C,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uBAAuB,EAAE,MAAM,CAAC;IAChC,wDAAwD;IACxD,WAAW,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AA0ED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAE9D;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAc7B;AAmED,wCAAwC;AACxC,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,OAAO,UAAU,CAAC,KAAwB,EACrD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,eAAe,CAAC,CAqC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,OAAO,UAAU,CAAC,KAAwB,EACrD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,OAAO,UAAU,CAAC,KAAwB,EACrD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAiBzD;AAED,6DAA6D;AAC7D,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,OAAO,UAAU,CAAC,KAAwB,EACrD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAShD"}