@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/protocol/tcp-transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TcpTransport — newline-delimited JSON over a TCP socket (Duplex stream).
+ *
+ * Phase 6 of the automation plan: lets the same AgentServer that runs over
+ * stdio (agent-server-stdio) also serve over a network socket, so a headless
+ * host can be reached by a remote/local client. The transport implements the
+ * 3-method Transport interface (send/onMessage/close); AgentServer is unchanged
+ * (§0 of docs/automation-plan-2026-05-31.md).
+ *
+ * Framing mirrors StdioTransport: one JSON value per line. The socket core is
+ * separated from listen/accept (`listenTcp`) so the framing is unit-testable
+ * against any Duplex without opening a real port.
+ *
+ * v1 security: intended for localhost / SSH-tunnel use only. There is NO
+ * authentication here — do not bind to a public interface without adding auth.
+ */
+import { type Server, type Socket } from "node:net";
+import type { Duplex } from "node:stream";
+import type { Transport } from "./transport.js";
+import type { RpcMessage } from "./types.js";
+/** Wrap a connected Duplex socket as a Transport (NDJSON framing). */
+export declare class SocketTransport implements Transport {
+    private readonly socket;
+    private rl;
+    private handlers;
+    constructor(socket: Duplex);
+    send(message: RpcMessage): void;
+    onMessage(handler: (message: RpcMessage) => void): void;
+    close(): void;
+}
+export interface TcpListenResult {
+    server: Server;
+    /** The actual port bound (useful when 0 was requested). */
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Listen on host:port and invoke `onConnection` with a SocketTransport for each
+ * accepted client. Resolves once listening. Defaults to 127.0.0.1 — never bind
+ * 0.0.0.0 without auth (v1 has none).
+ */
+export declare function listenTcp(opts: {
+    port: number;
+    host?: string;
+}, onConnection: (transport: SocketTransport, socket: Socket) => void): Promise<TcpListenResult>;

package/dist/protocol/tcp-transport.js

@@ -0,0 +1,74 @@
+/**
+ * TcpTransport — newline-delimited JSON over a TCP socket (Duplex stream).
+ *
+ * Phase 6 of the automation plan: lets the same AgentServer that runs over
+ * stdio (agent-server-stdio) also serve over a network socket, so a headless
+ * host can be reached by a remote/local client. The transport implements the
+ * 3-method Transport interface (send/onMessage/close); AgentServer is unchanged
+ * (§0 of docs/automation-plan-2026-05-31.md).
+ *
+ * Framing mirrors StdioTransport: one JSON value per line. The socket core is
+ * separated from listen/accept (`listenTcp`) so the framing is unit-testable
+ * against any Duplex without opening a real port.
+ *
+ * v1 security: intended for localhost / SSH-tunnel use only. There is NO
+ * authentication here — do not bind to a public interface without adding auth.
+ */
+import { createServer } from "node:net";
+import { createInterface } from "node:readline";
+/** Wrap a connected Duplex socket as a Transport (NDJSON framing). */
+export class SocketTransport {
+    socket;
+    rl;
+    handlers = [];
+    constructor(socket) {
+        this.socket = socket;
+        this.rl = createInterface({ input: socket });
+        this.rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const msg = JSON.parse(line);
+                for (const handler of this.handlers)
+                    handler(msg);
+            }
+            catch {
+                // Skip malformed lines (same policy as StdioTransport).
+            }
+        });
+    }
+    send(message) {
+        this.socket.write(JSON.stringify(message) + "\n");
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    close() {
+        this.rl.close();
+        this.handlers = [];
+        this.socket.end();
+    }
+}
+/**
+ * Listen on host:port and invoke `onConnection` with a SocketTransport for each
+ * accepted client. Resolves once listening. Defaults to 127.0.0.1 — never bind
+ * 0.0.0.0 without auth (v1 has none).
+ */
+export function listenTcp(opts, onConnection) {
+    const host = opts.host ?? "127.0.0.1";
+    return new Promise((resolve, reject) => {
+        const server = createServer((socket) => {
+            onConnection(new SocketTransport(socket), socket);
+        });
+        server.once("error", reject);
+        server.listen(opts.port, host, () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : opts.port;
+            resolve({
+                server,
+                port,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}

package/dist/protocol/transport.js

@@ -25,8 +25,9 @@ export function createInProcessTransport() {
             emitterA.on("message", handler);
         },
         close() {
+            // Only tear down our own incoming channel; the other side listens on
+            // emitterB and must keep working if it hasn't closed yet.
             emitterA.removeAllListeners();
-            emitterB.removeAllListeners();
         },
     };
     const sideB = {
@@ -38,7 +39,7 @@ export function createInProcessTransport() {
             emitterB.on("message", handler);
         },
         close() {
-            emitterA.removeAllListeners();
+            // Only tear down our own incoming channel; sideA listens on emitterA.
             emitterB.removeAllListeners();
         },
     };

package/dist/protocol/types.d.ts

@@ -40,6 +40,12 @@ export declare const ErrorCodes: {
     readonly Overloaded: -32001;
     readonly SessionNotFound: -32002;
     readonly SessionClosed: -32004;
+    /**
+     * Run was cancelled by the user (ESC / Stop). Clients should treat
+     * this as a clean terminal state, not a real error: no banner, no
+     * red toast — just clear busy and stop streaming.
+     */
+    readonly Cancelled: -32005;
 };
 /** Start an agent run with a user task. */
 export interface RunParams {
@@ -55,11 +61,37 @@ export interface RunParams {
      * When omitted, the engine keeps its configured default.
      */
     permissionMode?: PermissionMode;
+    /**
+     * Workspace trust for this run's project (`cwd`), asserted by the host
+     * (desktop main from its trust-store) — never by the renderer. When false,
+     * the engine strips dangerous fields from the project's own .code-shell
+     * settings (permissions/env/hooks/mcpServers/localEnvironment). Omitted →
+     * trusted (preserves behavior for hosts that don't wire trust).
+     */
+    projectTrusted?: boolean;
     /**
      * Per-run plan-mode flag. When true, the Engine enters plan mode for
      * this run; when omitted, the engine keeps its configured default.
      */
     planMode?: boolean;
+    /**
+     * Require the target session to already exist on disk. When true and the
+     * session is absent, the run is rejected with `SessionNotFound` instead of
+     * silently creating a fresh empty session. Used by cron "continue this
+     * conversation" jobs: if the user deleted the target session, the job must
+     * fail loudly (so it can be auto-disabled) rather than run its prompt against
+     * a blank context. Omitted/false → the normal resume-or-create behavior.
+     */
+    requireExisting?: boolean;
+    /**
+     * Goal mode for this run. When set, the engine runs loop-until-done:
+     * on each natural completion a GoalStopHook judges whether this goal is
+     * met and re-prompts if not (bounded). Orthogonal to permissionMode.
+     *
+     * Accepts a bare objective string or a full GoalConfig (objective +
+     * optional token/time budgets). Normalized at the engine run boundary.
+     */
+    goal?: string | import("../engine/goal.js").GoalConfig;
 }
 export interface RunResult {
     text: string;
@@ -88,6 +120,19 @@ export interface InjectParams {
     sessionId: string;
     content: string;
 }
+/** Steer an in-flight run: queue a user message for the next turn-loop step. */
+export interface SteerParams {
+    sessionId: string;
+    text: string;
+    /** Stable host-side id for this queued draft. Rides through to the
+     *  steer_injected event and is the handle Unsteer uses to revoke it. */
+    id?: string;
+}
+/** Revoke a still-pending steer entry by id (before the loop consumes it). */
+export interface UnsteerParams {
+    sessionId: string;
+    id: string;
+}
 /** Update runtime configuration. */
 export interface ConfigureParams {
     /** When present, configure that specific chat session. Otherwise worker-global. */
@@ -104,6 +149,14 @@ export interface ConfigureParams {
      * running engine picks them up without a process restart.
      */
     reloadModels?: boolean;
+    /**
+     * Re-read disk settings and hot-push the disk-default config fields (preset /
+     * customSystemPrompt / appendSystemPrompt / personalization / mcpServers) +
+     * settings hooks onto ALREADY-RUNNING sessions ("config hot-reload layer 2").
+     * No sessionId → applies to every live session; with sessionId → that one.
+     * Applied at the next turn boundary; in-flight turns are not interrupted.
+     */
+    reloadSettings?: boolean;
 }
 /** Query server state. */
 export interface QueryParams {
@@ -206,8 +259,24 @@ export declare const Methods: {
     readonly Query: "agent/query";
     /** Inject context into transcript without triggering LLM. */
     readonly Inject: "agent/inject";
+    /** Steer an in-flight run: queue a user message spliced at the next step (不打断). */
+    readonly Steer: "agent/steer";
+    /** Revoke a still-pending steer entry by id (撤回, before the loop consumes it). */
+    readonly Unsteer: "agent/unsteer";
     /** Close (destroy) a session. */
     readonly CloseSession: "agent/closeSession";
+    /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
+    readonly GoalExtend: "agent/goalExtend";
+    /** Clear a session's persisted active goal (CC /goal clear). */
+    readonly GoalClear: "agent/goalClear";
+    /** Read a session's persisted active goal, to re-surface it on session load. */
+    readonly GoalGet: "agent/goalGet";
+    /** Query/control a session's background shells for the UI panel (TODO 3.2). */
+    readonly BackgroundShells: "agent/backgroundShells";
+    /** Unified listing of a session's background work (shells + sub-agents + jobs)
+     *  for the desktop background panel. Output/kill of a shell still goes through
+     *  BackgroundShells by shellId; this is list-only across all three kinds. */
+    readonly BackgroundWork: "agent/backgroundWork";
     readonly StreamEvent: "agent/streamEvent";
     readonly ApprovalRequest: "agent/approvalRequest";
     readonly Status: "agent/status";

package/dist/protocol/types.js

@@ -18,6 +18,12 @@ export const ErrorCodes = {
     Overloaded: -32001,
     SessionNotFound: -32002,
     SessionClosed: -32004,
+    /**
+     * Run was cancelled by the user (ESC / Stop). Clients should treat
+     * this as a clean terminal state, not a real error: no banner, no
+     * red toast — just clear busy and stop streaming.
+     */
+    Cancelled: -32005,
 };
 // ─── Method Names ───────────────────────────────────────────────────
 export const Methods = {
@@ -29,8 +35,24 @@ export const Methods = {
     Query: "agent/query",
     /** Inject context into transcript without triggering LLM. */
     Inject: "agent/inject",
+    /** Steer an in-flight run: queue a user message spliced at the next step (不打断). */
+    Steer: "agent/steer",
+    /** Revoke a still-pending steer entry by id (撤回, before the loop consumes it). */
+    Unsteer: "agent/unsteer",
     /** Close (destroy) a session. */
     CloseSession: "agent/closeSession",
+    /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
+    GoalExtend: "agent/goalExtend",
+    /** Clear a session's persisted active goal (CC /goal clear). */
+    GoalClear: "agent/goalClear",
+    /** Read a session's persisted active goal, to re-surface it on session load. */
+    GoalGet: "agent/goalGet",
+    /** Query/control a session's background shells for the UI panel (TODO 3.2). */
+    BackgroundShells: "agent/backgroundShells",
+    /** Unified listing of a session's background work (shells + sub-agents + jobs)
+     *  for the desktop background panel. Output/kill of a shell still goes through
+     *  BackgroundShells by shellId; this is list-only across all three kinds. */
+    BackgroundWork: "agent/backgroundWork",
     // Server → Client (notifications, no id)
     StreamEvent: "agent/streamEvent",
     ApprovalRequest: "agent/approvalRequest",

package/dist/quota/credentials.d.ts

@@ -0,0 +1,3 @@
+import type { QuotaCredentials } from "./types.js";
+/** Resolve all tokens from their standard local locations. Never throws. */
+export declare function resolveQuotaCredentials(): Promise<QuotaCredentials>;

package/dist/quota/credentials.js

@@ -0,0 +1,80 @@
+/**
+ * Default resolver for the tokens `quota/` needs.
+ *
+ * This is the ONE platform-specific file in the module — it reads a vendor's
+ * Keychain entry / auth.json. A host that stores secrets differently (or a
+ * future plugin) can bypass this and build QuotaCredentials itself; core logic
+ * in index.ts only depends on the QuotaCredentials shape.
+ *
+ * All reads are best-effort: a missing token yields `undefined`, never a throw,
+ * so a machine without Codex or without Keychain access degrades to "quota
+ * unavailable for that provider" instead of failing the whole call.
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function userHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+/** Read the Codex OAuth token + account id from ~/.codex/auth.json. */
+async function readCodexCreds() {
+    try {
+        const raw = await readFile(join(userHome(), ".codex", "auth.json"), "utf8");
+        const j = JSON.parse(raw);
+        const tokens = (j.tokens ?? {});
+        const token = typeof tokens.access_token === "string" ? tokens.access_token : undefined;
+        const acct = typeof tokens.account_id === "string" ? tokens.account_id : undefined;
+        return { codexAccessToken: token, codexAccountId: acct };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Read the Claude Code OAuth access token.
+ * macOS: Keychain generic-password "Claude Code-credentials".
+ * Other platforms: fall back to a plaintext ~/.claude/.credentials.json if present.
+ */
+async function readClaudeCreds() {
+    // macOS Keychain first.
+    if (process.platform === "darwin") {
+        const raw = await runSecurity();
+        const token = parseClaudeToken(raw);
+        if (token)
+            return { claudeAccessToken: token };
+    }
+    // Cross-platform fallback: some installs keep a plaintext credentials file.
+    try {
+        const raw = await readFile(join(userHome(), ".claude", ".credentials.json"), "utf8");
+        const token = parseClaudeToken(raw);
+        if (token)
+            return { claudeAccessToken: token };
+    }
+    catch {
+        /* not present */
+    }
+    return {};
+}
+function parseClaudeToken(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const j = JSON.parse(raw);
+        const oauth = (j.claudeAiOauth ?? {});
+        return typeof oauth.accessToken === "string" ? oauth.accessToken : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runSecurity() {
+    return new Promise((resolve) => {
+        execFile("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { timeout: 4000 }, (err, stdout) => resolve(err ? null : stdout.toString().trim()));
+    });
+}
+/** Resolve all tokens from their standard local locations. Never throws. */
+export async function resolveQuotaCredentials() {
+    const [codex, claude] = await Promise.all([readCodexCreds(), readClaudeCreds()]);
+    return { ...codex, ...claude };
+}

package/dist/quota/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Query remaining quota for the external coding-agent CLIs.
+ *
+ * Both lookups are verified against the real backends (2026-07-01):
+ *   - Codex: GET https://chatgpt.com/backend-api/wham/usage → JSON
+ *            rate_limit.{primary_window,secondary_window}.{used_percent,reset_at}.
+ *            Zero cost (no message sent).
+ *   - Claude: POST /v1/messages (max_tokens:1) → response headers
+ *            anthropic-ratelimit-unified-{5h,7d}-{utilization,reset}.
+ *            Costs ~1 output token (Claude exposes quota only via response
+ *            headers — there is no standalone usage endpoint).
+ *
+ * The `fetch` and credentials are injected so this is unit-testable offline and
+ * so the host owns secret resolution (see types.ts boundary note).
+ */
+import type { ProviderQuota, QuotaCredentials, QuotaResult } from "./types.js";
+type FetchLike = typeof fetch;
+export interface CheckQuotaOptions {
+    creds: QuotaCredentials;
+    /** Restrict to specific providers; defaults to both. */
+    providers?: ("claude" | "codex")[];
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: FetchLike;
+    /** Caller's abort signal (user Stop); composed with an internal timeout. */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Codex: GET the usage endpoint and map its JSON to ProviderQuota. */
+export declare function queryCodexQuota(creds: QuotaCredentials, fetchImpl: FetchLike, signal: AbortSignal): Promise<ProviderQuota>;
+/** Claude: POST a 1-token probe and read the unified rate-limit headers. */
+export declare function queryClaudeQuota(creds: QuotaCredentials, fetchImpl: FetchLike, signal: AbortSignal): Promise<ProviderQuota>;
+/** Query both providers (or the subset requested), concurrently. */
+export declare function checkQuota(opts: CheckQuotaOptions): Promise<QuotaResult>;
+/** Render a QuotaResult as a compact human/agent-readable summary. */
+export declare function formatQuota(result: QuotaResult, nowSec: number): string;
+export {};

package/dist/quota/index.js

@@ -0,0 +1,155 @@
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const CLAUDE_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+/** Cheapest always-available model for the 1-token probe. */
+const CLAUDE_PROBE_MODEL = "claude-haiku-4-5-20251001";
+const DEFAULT_TIMEOUT_MS = 8000;
+/** Compose the caller signal with a timeout so a hung backend can't block. */
+function withTimeout(signal, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function num(v) {
+    const n = typeof v === "string" ? parseFloat(v) : typeof v === "number" ? v : NaN;
+    return Number.isFinite(n) ? n : null;
+}
+/** Codex: GET the usage endpoint and map its JSON to ProviderQuota. */
+export async function queryCodexQuota(creds, fetchImpl, signal) {
+    if (!creds.codexAccessToken) {
+        return { provider: "codex", error: "no Codex token (是否已 codex login?)" };
+    }
+    let resp;
+    try {
+        resp = await fetchImpl(CODEX_USAGE_URL, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${creds.codexAccessToken}`,
+                ...(creds.codexAccountId ? { "chatgpt-account-id": creds.codexAccountId } : {}),
+                originator: "codex_cli_rs",
+                "user-agent": "codex_cli_rs",
+            },
+            signal,
+        });
+    }
+    catch (err) {
+        return { provider: "codex", error: `请求失败: ${err.message}` };
+    }
+    if (!resp.ok) {
+        return { provider: "codex", error: `HTTP ${resp.status}${resp.status === 401 ? " (token 可能已过期)" : ""}` };
+    }
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        return { provider: "codex", error: "响应非 JSON" };
+    }
+    const rl = (body.rate_limit ?? {});
+    const windows = [];
+    const map = [
+        ["primary_window", "5h"],
+        ["secondary_window", "7d"],
+    ];
+    for (const [key, kind] of map) {
+        const w = rl[key];
+        if (!w)
+            continue;
+        const usedPercent = num(w.used_percent);
+        if (usedPercent == null)
+            continue;
+        windows.push({ kind, usedPercent, resetsAt: num(w.reset_at) });
+    }
+    if (windows.length === 0)
+        return { provider: "codex", error: "响应无 rate_limit 窗口" };
+    return {
+        provider: "codex",
+        windows,
+        planType: typeof body.plan_type === "string" ? body.plan_type : null,
+    };
+}
+/** Claude: POST a 1-token probe and read the unified rate-limit headers. */
+export async function queryClaudeQuota(creds, fetchImpl, signal) {
+    if (!creds.claudeAccessToken) {
+        return { provider: "claude", error: "no Claude Code token (是否已登录 Claude Code?)" };
+    }
+    let resp;
+    try {
+        resp = await fetchImpl(CLAUDE_MESSAGES_URL, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${creds.claudeAccessToken}`,
+                "anthropic-version": "2023-06-01",
+                "anthropic-beta": "oauth-2025-04-20",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: CLAUDE_PROBE_MODEL,
+                max_tokens: 1,
+                messages: [{ role: "user", content: "hi" }],
+            }),
+            signal,
+        });
+    }
+    catch (err) {
+        return { provider: "claude", error: `请求失败: ${err.message}` };
+    }
+    if (!resp.ok) {
+        return { provider: "claude", error: `HTTP ${resp.status}${resp.status === 401 ? " (token 可能已过期)" : ""}` };
+    }
+    const h = resp.headers;
+    const windows = [];
+    const map = [
+        ["anthropic-ratelimit-unified-5h-utilization", "anthropic-ratelimit-unified-5h-reset", "5h"],
+        ["anthropic-ratelimit-unified-7d-utilization", "anthropic-ratelimit-unified-7d-reset", "7d"],
+    ];
+    for (const [utilKey, resetKey, kind] of map) {
+        const util = num(h.get(utilKey)); // 0–1
+        if (util == null)
+            continue;
+        windows.push({ kind, usedPercent: util * 100, resetsAt: num(h.get(resetKey)) });
+    }
+    if (windows.length === 0)
+        return { provider: "claude", error: "响应头无 rate-limit 字段" };
+    return { provider: "claude", windows };
+}
+/** Query both providers (or the subset requested), concurrently. */
+export async function checkQuota(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const providers = opts.providers ?? ["claude", "codex"];
+    const signal = withTimeout(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const result = {};
+    await Promise.all(providers.map(async (p) => {
+        if (p === "codex")
+            result.codex = await queryCodexQuota(opts.creds, fetchImpl, signal);
+        else
+            result.claude = await queryClaudeQuota(opts.creds, fetchImpl, signal);
+    }));
+    return result;
+}
+/** Render a QuotaResult as a compact human/agent-readable summary. */
+export function formatQuota(result, nowSec) {
+    const lines = [];
+    for (const pq of [result.claude, result.codex]) {
+        if (!pq)
+            continue;
+        const name = pq.provider === "claude" ? "Claude Code" : "Codex";
+        if (pq.error || !pq.windows) {
+            lines.push(`${name}: 查询失败 — ${pq.error ?? "unknown"}`);
+            continue;
+        }
+        const plan = pq.planType ? ` [${pq.planType}]` : "";
+        const parts = pq.windows.map((w) => {
+            const reset = w.resetsAt != null ? ` (重置 ${formatReset(w.resetsAt - nowSec)})` : "";
+            return `${w.kind} 用了 ${w.usedPercent.toFixed(0)}%${reset}`;
+        });
+        lines.push(`${name}${plan}: ${parts.join("，")}`);
+    }
+    return lines.length ? lines.join("\n") : "(无可用额度信息)";
+}
+/** "2h13m" / "45m" / "已重置" from a seconds delta. */
+function formatReset(deltaSec) {
+    if (deltaSec <= 0)
+        return "已重置";
+    const h = Math.floor(deltaSec / 3600);
+    const m = Math.floor((deltaSec % 3600) / 60);
+    return h > 0 ? `${h}h${m}m 后` : `${m}m 后`;
+}

package/dist/quota/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Quota (rate-limit / usage) types for external coding-agent CLIs.
+ *
+ * DESIGN / BOUNDARY NOTE (see project_core_minimal_harness_business_layer):
+ * "how to read Claude Code / Codex remaining quota" is provider-specific
+ * BUSINESS policy, not core harness mechanism — it pokes a vendor's Keychain
+ * entry, an undocumented usage endpoint, and private response headers. It lives
+ * in this self-contained `quota/` module (one interface out: `checkQuota`) on
+ * purpose, so it can be lifted wholesale into a plugin later without untangling
+ * it from the rest of core. Nothing outside this module should know about
+ * Keychain / wham endpoints / `anthropic-ratelimit-*` header names.
+ */
+/** A single rolling limit window (e.g. the 5-hour or 7-day window). */
+export interface QuotaWindow {
+    /** Which window this is. */
+    kind: "5h" | "7d";
+    /** Percent of the window's limit already used, 0–100. */
+    usedPercent: number;
+    /** Unix epoch seconds when this window resets, or null if unknown. */
+    resetsAt: number | null;
+}
+/** Quota for one provider (claude | codex). */
+export interface ProviderQuota {
+    provider: "claude" | "codex";
+    /** Present when the lookup succeeded. */
+    windows?: QuotaWindow[];
+    /** Subscription tier, when the source exposes it (e.g. "team", "pro"). */
+    planType?: string | null;
+    /** Human-readable failure reason when the lookup did not succeed. */
+    error?: string;
+}
+export interface QuotaResult {
+    claude?: ProviderQuota;
+    codex?: ProviderQuota;
+}
+/**
+ * A credential the host supplies so this module can talk to a vendor backend.
+ * Core never reads the Keychain / auth.json itself — the host (desktop main /
+ * server) resolves the secret and hands it in. This is the seam that makes the
+ * whole module portable to a plugin.
+ */
+export interface QuotaCredentials {
+    /** Claude Code OAuth access token (from Keychain "Claude Code-credentials"). */
+    claudeAccessToken?: string;
+    /** Codex OAuth access token + account id (from ~/.codex/auth.json). */
+    codexAccessToken?: string;
+    codexAccountId?: string;
+}

package/dist/quota/types.js

@@ -0,0 +1,13 @@
+/**
+ * Quota (rate-limit / usage) types for external coding-agent CLIs.
+ *
+ * DESIGN / BOUNDARY NOTE (see project_core_minimal_harness_business_layer):
+ * "how to read Claude Code / Codex remaining quota" is provider-specific
+ * BUSINESS policy, not core harness mechanism — it pokes a vendor's Keychain
+ * entry, an undocumented usage endpoint, and private response headers. It lives
+ * in this self-contained `quota/` module (one interface out: `checkQuota`) on
+ * purpose, so it can be lifted wholesale into a plugin later without untangling
+ * it from the rest of core. Nothing outside this module should know about
+ * Keychain / wham endpoints / `anthropic-ratelimit-*` header names.
+ */
+export {};

package/dist/remote/bridge.d.ts

@@ -4,6 +4,7 @@
  * Architecture:
  *   Local terminal ←→ SSH ←→ Remote code-shell (NDJSON stdio mode)
  */
+import { type ChildProcess } from "node:child_process";
 export interface BridgeConfig {
     host: string;
     user?: string;
@@ -11,11 +12,20 @@ export interface BridgeConfig {
     identityFile?: string;
     remoteCommand?: string;
 }
+/** A spawn function (injectable for tests). Defaults to child_process.spawn. */
+export type SpawnFn = (command: string, args: string[]) => ChildProcess;
+/**
+ * Build the ssh argv. Each value is a discrete element — spawn runs ssh
+ * without a shell, so identityFile/port/host are never shell-interpreted
+ * (there is no local command-injection surface here).
+ */
+export declare function buildSSHArgs(config: BridgeConfig): string[];
 export declare class RemoteBridge {
     private readonly config;
     private ssh;
     private connected;
-    constructor(config: BridgeConfig);
+    private readonly spawnFn;
+    constructor(config: BridgeConfig, spawnFn?: SpawnFn);
     /**
      * Connect to the remote host via SSH and start code-shell in NDJSON mode.
      */
@@ -33,5 +43,4 @@ export declare class RemoteBridge {
      */
     disconnect(): void;
     get isConnected(): boolean;
-    private buildSSHArgs;
 }