xcoder-dna 0.0.0-stage → 1.3.1

package/dist/license/store.js

@@ -0,0 +1,223 @@
+// xcoder:version 8 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:21:37.747Z | xcoder:subtask code-st-828150
+// Atomic per-user license state persistence.
+//
+// Canonical location: <homedir>/.xcoder/license/activation.json — per-user,
+// next to config.json, NOT inside the workspace. A license belongs to the
+// person/machine, so a fresh `git clone` must not silently consume another
+// seat.
+//
+// SHARED STATE: the canonical file is the SAME file v3 and ronin read and
+// write. One activation therefore covers every xcoder binary on the machine —
+// the bug was never config.json (already shared) but the receipt living at
+// different paths in different schemas. Reads walk the discovery list, writes
+// land on the primary path in the superset shape all readers accept.
+//
+// Contains no secrets by construction: the serial key is never written to
+// disk. `receipt` is a public, signed artifact whose only use is offline
+// verification against the build-pinned key.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { resolveStateCandidates } from "./state-paths.js";
+import { decodeStateFile, recordFromClaims, writeStateFile, } from "./state-codec.js";
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+export function defaultLicenseDir() {
+    return path.join(os.homedir(), ".xcoder", "license");
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Every FILE an activation may be stored in, highest priority first.
+ *
+ * Candidates are files, not directories: $XCODER_LICENSE_FILE names an
+ * arbitrary file and the legacy host store is license.json. Collapsing them to
+ * their parent directory and re-appending a hard-coded activation.json silently
+ * ignored both, which is exactly the v1-asks-for-a-key bug that this sharing
+ * work exists to fix. Reads, writes and clears all use this one list.
+ */
+export function resolveCandidateFiles(env = process.env) {
+    const seen = new Set();
+    const files = [];
+    for (const candidate of resolveStateCandidates(env)) {
+        const key = path.resolve(candidate.path).toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        files.push(candidate.path);
+    }
+    return files;
+}
+/**
+ * Directories of the candidate files, highest priority first.
+ *
+ * Kept for callers that reason about the installation sidecar next to the
+ * activation; activation I/O must use resolveCandidateFiles().
+ */
+export function resolveCandidateDirs(env = process.env) {
+    const seen = new Set();
+    const dirs = [];
+    for (const file of resolveCandidateFiles(env)) {
+        const dir = path.dirname(file);
+        const key = path.resolve(dir).toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        dirs.push(dir);
+    }
+    return dirs;
+}
+export function createLicenseStore(opts) {
+    const dir = opts?.dir ?? defaultLicenseDir();
+    // An explicitly injected dir is a fixture: stay inside it, so a test never
+    // reads (or is shadowed by) the developer's real activation on this machine.
+    const candidateFiles = opts?.dir ? [path.join(dir, "activation.json")] : resolveCandidateFiles();
+    // Writes follow the SAME priority list as reads (including the documented
+    // XCODER_LICENSE_FILE override). Writing to defaultLicenseDir() while reading
+    // from an override would store the activation where no subsequent read looks.
+    const activationFile = candidateFiles[0] ?? path.join(dir, "activation.json");
+    const writeDir = path.dirname(activationFile);
+    const installationFile = path.join(writeDir, "installation.json");
+    function ensureDir() {
+        fs.mkdirSync(writeDir, { recursive: true, mode: DIR_MODE });
+    }
+    /** The decoded shared record from the first candidate that has one. */
+    function readShared() {
+        for (const candidateFile of candidateFiles) {
+            const decoded = decodeStateFile(candidateFile);
+            if (decoded.ok)
+                return decoded.record;
+        }
+        return null;
+    }
+    /** Read raw JSON from one file. Symlinks are never followed. */
+    function readJson(file) {
+        let raw;
+        try {
+            const stat = fs.lstatSync(file);
+            if (stat.isSymbolicLink() || !stat.isFile())
+                return null;
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return null; // missing / unreadable → caller sees "nothing stored"
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return isObject(parsed) ? parsed : null;
+        }
+        catch {
+            // Deliberately do NOT delete the file: the gate maps this to
+            // `corrupt-store` and fails closed, and a human can still inspect it.
+            return null;
+        }
+    }
+    function readInstallation() {
+        const raw = readJson(installationFile);
+        if (raw) {
+            const installationId = asString(raw.installationId);
+            const createdAt = asString(raw.createdAt);
+            if (installationId)
+                return { installationId, createdAt: createdAt ?? new Date(0).toISOString() };
+        }
+        // A machine activated by another binary never wrote installation.json; the
+        // id lives in the shared activation instead. Without this fallback
+        // refresh() would refuse with "no installation id" on a machine that is
+        // plainly activated.
+        const shared = readShared();
+        if (!shared)
+            return null;
+        return { installationId: shared.installationId, createdAt: shared.savedAt };
+    }
+    function ensureInstallation() {
+        const existing = readInstallation();
+        if (existing) {
+            // Adopt-on-read: materialise the id in this dir so older builds keep
+            // working, but never replace an existing file.
+            if (!fs.existsSync(installationFile)) {
+                try {
+                    ensureDir();
+                    fs.writeFileSync(installationFile, `${JSON.stringify({ installationId: existing.installationId, createdAt: existing.createdAt }, null, 2)}\n`, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+                }
+                catch {
+                    /* a concurrent writer won the race; its id is equivalent */
+                }
+            }
+            return existing;
+        }
+        const record = {
+            installationId: randomUUID(),
+            createdAt: new Date().toISOString(),
+        };
+        ensureDir();
+        try {
+            // `wx` fails if the file appeared between our read and this write, so a
+            // concurrent process can never clobber another installation's id.
+            fs.writeFileSync(installationFile, `${JSON.stringify(record, null, 2)}\n`, {
+                encoding: "utf8",
+                mode: FILE_MODE,
+                flag: "wx",
+            });
+            return record;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EEXIST") {
+                const winner = readInstallation();
+                if (winner)
+                    return winner;
+            }
+            throw err;
+        }
+    }
+    function readActivation() {
+        // First candidate wins; the file is the superset every binary shares, but
+        // this module keeps speaking the 7-field shape to its callers.
+        for (const candidateFile of candidateFiles) {
+            const decoded = decodeStateFile(candidateFile);
+            if (!decoded.ok)
+                continue;
+            const record = decoded.record;
+            return {
+                activationId: record.activationId,
+                licenseId: record.licenseId,
+                plan: record.plan,
+                receipt: record.receipt,
+                expiresAt: record.expiresAt,
+                refreshBy: record.refreshBy,
+                savedAt: record.savedAt,
+            };
+        }
+        return null;
+    }
+    function writeActivation(rec) {
+        // Replace, never append: exactly one activation per installation (AC3).
+        // Always the PRIMARY file, in the superset shape, so v3 and ronin read the
+        // very same activation without re-activating.
+        const installation = ensureInstallation();
+        const record = recordFromClaims(rec, {
+            installationId: installation.installationId,
+            receipt: rec.receipt,
+            savedAt: rec.savedAt,
+        });
+        writeStateFile(activationFile, record);
+    }
+    function clearActivation() {
+        // Clear every candidate so a released seat cannot be re-adopted from a
+        // lower-priority copy on the next read.
+        for (const candidateFile of candidateFiles) {
+            try {
+                fs.rmSync(candidateFile, { force: true });
+            }
+            catch {
+                /* already absent — clearing is idempotent */
+            }
+        }
+    }
+    return { dir, readInstallation, ensureInstallation, readActivation, writeActivation, clearActivation };
+}

package/dist/license/trust-anchor.d.ts

@@ -0,0 +1,24 @@
+export interface TrustAnchor {
+    /** SPKI PEM, Ed25519. */
+    readonly publicKeyPem: string;
+    /** True only while the labelled development key is pinned. */
+    readonly isDevelopment: boolean;
+    /** Set by scripts/fetch-public-key.mjs during release prep. */
+    readonly source: "release" | "development";
+}
+/** The `iss` claim the service signs with. */
+export declare const LICENSE_ISSUER = "https://license.coderph.dev";
+/** The `aud` claim; also the product ID sent at activation. */
+export declare const LICENSE_PRODUCT_ID: "xcoder-sdlc-cli";
+/**
+ * Default activation API base: exactly `<LICENSE_ISSUER>/activation/v1`.
+ *
+ * Asserted at import time: a mismatch means the binary would activate against
+ * a surface the Key System does not serve, which fails for every user at
+ * runtime and is invisible in a unit test that injects its own base URL. A
+ * throw here turns that into an immediate, unmissable build/test failure.
+ */
+export declare const LICENSE_API_BASE_URL: string;
+/** The maximum offline window a receipt may claim: 7 days. */
+export declare const RECEIPT_TTL_MS: number;
+export declare const TRUST_ANCHOR: TrustAnchor;

package/dist/license/trust-anchor.js

@@ -0,0 +1,74 @@
+// xcoder:version 2 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:22:00.385Z | xcoder:subtask code-st-828150
+// The pinned license trust anchor — a build artifact, NOT runtime configuration.
+//
+// Invariants (each enforced by src/license/trust-anchor.test.ts):
+//   1. This module contains no `process.env` reference, so neither the
+//      environment nor ~/.xcoder/config.json can replace the pinned key.
+//   2. publicKeyPem parses via crypto.createPublicKey() as Ed25519 SPKI.
+//   3. A release build (XCODER_RELEASE_BUILD=1) carrying the DEV-ONLY key
+//      fails the test suite — release prep must run scripts/fetch-public-key.mjs.
+//   4. The dev key is labelled DEV-ONLY in its comment with source "development".
+//   5. LICENSE_API_BASE_URL is exactly `<LICENSE_ISSUER>/activation/v1` — the
+//      serial-key gateway route the Key System is published behind. A mismatch
+//      throws at import time rather than silently activating against the wrong
+//      surface (v1 shipped `/api/v1`, so every valid key 404'd as bad-response).
+//
+// scripts/fetch-public-key.mjs rewrites everything between the BEGIN/END
+// markers below. Never hand-edit the PEM inside those markers.
+/** The `iss` claim the service signs with. */
+export const LICENSE_ISSUER = "https://license.coderph.dev";
+/** The `aud` claim; also the product ID sent at activation. */
+export const LICENSE_PRODUCT_ID = "xcoder-sdlc-cli";
+/**
+ * The path the serial-key gateway mounts the Key System's `/v1/` API under.
+ * Kept as a literal (not derived from the client) so the client module stays
+ * unchanged and the route is pinned in one auditable place.
+ */
+const GATEWAY_BASE_PATH = "/activation/v1";
+/**
+ * The pinned activation API base — rewritten by hand, never at runtime.
+ *
+ * v1 shipped `<origin>/api/v1`, but the gateway publishes `POST
+ * <origin>/activation/v1/activations` (and /refresh, /release). Every valid
+ * serial key therefore hit a 404, surfaced to the user as `bad-response`: this
+ * is the reason v1 rejected a key v3 accepted. The value lives OUTSIDE the
+ * BEGIN/END marker block because scripts/fetch-public-key.mjs rewrites only
+ * the PEM and the key source, and a release build must not drop the route.
+ */
+const PINNED_API_BASE_URL = "https://license.coderph.dev/activation/v1";
+/** Strip trailing slashes so `<origin>/` and `<origin>` compare equal. */
+function stripTrailingSlashes(value) {
+    return value.replace(/\/+$/, "");
+}
+/**
+ * Default activation API base: exactly `<LICENSE_ISSUER>/activation/v1`.
+ *
+ * Asserted at import time: a mismatch means the binary would activate against
+ * a surface the Key System does not serve, which fails for every user at
+ * runtime and is invisible in a unit test that injects its own base URL. A
+ * throw here turns that into an immediate, unmissable build/test failure.
+ */
+export const LICENSE_API_BASE_URL = (() => {
+    const expected = `${LICENSE_ISSUER}${GATEWAY_BASE_PATH}`;
+    const pinned = stripTrailingSlashes(PINNED_API_BASE_URL);
+    if (pinned !== expected) {
+        throw new Error(`license trust anchor: PINNED_API_BASE_URL must be ${expected} (got ${pinned}) — re-pin it so it is the issuer origin plus ${GATEWAY_BASE_PATH}`);
+    }
+    return expected;
+})();
+/** The maximum offline window a receipt may claim: 7 days. */
+export const RECEIPT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// BEGIN XCODER LICENSE PUBLIC KEY (managed by scripts/fetch-public-key.mjs)
+// DEV-ONLY — this Ed25519 key is published with the source tree and MUST NOT
+// be trusted in a release. Release prep replaces it and flips `source`.
+const PINNED_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEABJbTsj5H+GLJJEpA0X5m2+UofSkDAg/y7Z0ahE6c05Y=
+-----END PUBLIC KEY-----
+`;
+const PINNED_KEY_SOURCE = "development";
+// END XCODER LICENSE PUBLIC KEY
+export const TRUST_ANCHOR = Object.freeze({
+    publicKeyPem: PINNED_PUBLIC_KEY_PEM,
+    isDevelopment: PINNED_KEY_SOURCE === "development",
+    source: PINNED_KEY_SOURCE,
+});

package/dist/license/types.d.ts

@@ -0,0 +1,34 @@
+/** The signed claim set embedded in a license receipt (segment 0). */
+export interface LicenseClaims {
+    iss: string;
+    aud: string;
+    licenseId: string;
+    activationId: string;
+    plan: string;
+    /** ISO-8601, e.g. "2026-11-01T10:00:00.000Z" */
+    issuedAt: string;
+    /** Subscription expiry. */
+    expiresAt: string;
+    /** <= min(expiresAt, issuedAt + 7d) — the offline grace boundary. */
+    refreshBy: string;
+}
+/** Distinct, user-actionable denial codes. */
+export type LicenseDenialReason = "no-activation" | "corrupt-store" | "malformed-receipt" | "bad-signature" | "untrusted-key" | "wrong-issuer" | "wrong-audience" | "expired" | "not-yet-valid" | "refresh-overdue";
+export type VerifyResult = {
+    ok: true;
+    claims: LicenseClaims;
+} | {
+    ok: false;
+    reason: LicenseDenialReason;
+    detail?: string;
+};
+export type LicenseGateResult = {
+    allowed: true;
+    claims: LicenseClaims;
+} | {
+    allowed: false;
+    reason: LicenseDenialReason;
+    message: string;
+};
+/** Human-readable, non-leaking explanation for each denial code. */
+export declare const DENIAL_DETAIL: Record<LicenseDenialReason, string>;

package/dist/license/types.js

@@ -0,0 +1,19 @@
+// xcoder:version 1 | xcoder:task task-1d9460 | xcoder:updated 2026-10-25T17:01:22.522Z | xcoder:subtask code-st-4b0403
+// Client licensing — shared type layer.
+//
+// Type-only by design: no I/O, no `node:fs`, no `process`. Every other
+// module in src/license/ imports its vocabulary from here so the denial
+// codes and the gate result cannot drift apart.
+/** Human-readable, non-leaking explanation for each denial code. */
+export const DENIAL_DETAIL = {
+    "no-activation": "no activation found on this machine",
+    "corrupt-store": "stored license state is unreadable",
+    "malformed-receipt": "the stored receipt is malformed",
+    "bad-signature": "the receipt signature does not verify",
+    "untrusted-key": "the receipt was signed by a key that is not pinned",
+    "wrong-issuer": "the receipt was issued by an unexpected issuer",
+    "wrong-audience": "the receipt is not for this product",
+    expired: "the subscription has expired",
+    "not-yet-valid": "the receipt is not valid yet",
+    "refresh-overdue": "the offline window has elapsed — refresh required",
+};

package/dist/llm/budget.d.ts

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const requestScope: AsyncLocalStorage<{
+    budget?: RequestBudget;
+    recordUsage?: (entry: Record<string, unknown>) => void;
+    /** In-memory mirror prevents a successful call from disappearing if ledger I/O fails. */
+    usageEvents?: Record<string, unknown>[];
+}>;
+/** Shared synchronous reservations prevent concurrent requests overspending a cap.
+ * Unknown/time-out usage retains its reservation until explicit reconciliation.
+ */
+export declare class RequestBudget {
+    readonly capUsd: number;
+    readonly inputPerMillion: number;
+    readonly outputPerMillion: number;
+    private committed;
+    private reserved;
+    constructor(capUsd: number, inputPerMillion: number, outputPerMillion: number);
+    reserve(input: number, output: number): (usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    }) => void;
+    restore(jsonl: string): void;
+}

package/dist/llm/budget.js

@@ -0,0 +1,58 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const requestScope = new AsyncLocalStorage();
+/** Shared synchronous reservations prevent concurrent requests overspending a cap.
+ * Unknown/time-out usage retains its reservation until explicit reconciliation.
+ */
+export class RequestBudget {
+    capUsd;
+    inputPerMillion;
+    outputPerMillion;
+    committed = 0;
+    reserved = 0;
+    constructor(capUsd, inputPerMillion, outputPerMillion) {
+        this.capUsd = capUsd;
+        this.inputPerMillion = inputPerMillion;
+        this.outputPerMillion = outputPerMillion;
+        if (![capUsd, inputPerMillion, outputPerMillion].every(n => Number.isFinite(n) && n >= 0)) {
+            throw new Error("A dollar budget requires non-negative cap and explicit input/output prices");
+        }
+    }
+    reserve(input, output) {
+        if (![input, output].every(n => Number.isFinite(n) && n >= 0))
+            throw new Error("Invalid token reservation");
+        const amount = (input * this.inputPerMillion + output * this.outputPerMillion) / 1e6;
+        if (this.committed + this.reserved + amount > this.capUsd)
+            throw new Error("Request refused: task dollar budget exhausted");
+        this.reserved += amount;
+        let settled = false;
+        return usage => {
+            if (settled)
+                throw new Error("Budget reservation already settled");
+            settled = true;
+            if (!usage)
+                return; // Unknown charge stays reserved.
+            this.reserved -= amount;
+            this.committed += (usage.inputTokens * this.inputPerMillion + usage.outputTokens * this.outputPerMillion) / 1e6;
+        };
+    }
+    restore(jsonl) {
+        const requests = new Map();
+        for (const line of jsonl.split("\n").filter(line => line.trim())) {
+            const entry = JSON.parse(line);
+            if (typeof entry.requestId !== "string")
+                throw new Error("Invalid usage ledger");
+            requests.set(entry.requestId, { ...requests.get(entry.requestId), ...entry });
+        }
+        for (const entry of requests.values()) {
+            if (entry.inputPrice !== this.inputPerMillion || entry.outputPrice !== this.outputPerMillion) {
+                throw new Error("Budget pricing changed or is missing from the ledger; reconcile prior charges before resume");
+            }
+            if (entry.status === "completed" && entry.usageKnown === true && entry.usage) {
+                this.reserve(entry.usage.inputTokens, entry.usage.outputTokens)(entry.usage);
+            }
+            else {
+                this.reserve(entry.estimatedInputTokens ?? NaN, entry.maxOutputTokens ?? NaN)();
+            }
+        }
+    }
+}

package/dist/llm/client.d.ts

@@ -0,0 +1,53 @@
+export type LlmProvider = "deepseek" | "openai-compatible" | "anthropic";
+export interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface LlmClientOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    provider?: LlmProvider;
+    baseUrl?: string;
+    endpoint?: string;
+    apiKeyEnv?: string;
+    apiKey?: string;
+}
+export interface LlmCompletion {
+    text: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** The API's stop reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'length' | 'stop' | 'tool_calls' | null. */
+    stopReason: string | null;
+    /** The model name used for this completion. */
+    model: string;
+}
+/**
+ * One call per ReAct turn: system prompt + running transcript in, raw text
+ * + token usage out. Deliberately thin — the contract parsing lives in
+ * `protocol/react-contract.ts`, not here, so this file never needs to know
+ * what a valid response looks like. Callers are responsible for their own
+ * try/catch around `complete()` — a transient API error here must not be
+ * allowed to propagate all the way up and take the Master Orchestrator
+ * down with it (see `agents/sub-agent.ts`).
+ *
+ * Transport selection:
+ * - `"deepseek"` (default) — DeepSeek's Anthropic-compatible endpoint via
+ *   `@anthropic-ai/sdk`; zero-config behavior is unchanged.
+ * - `"openai-compatible"` — any OpenAI `chat/completions` provider via the
+ *   `openai` SDK (OpenAI, Groq, OpenRouter, Ollama, LM Studio, vLLM, ...).
+ * - `"anthropic"` — native Claude via `@anthropic-ai/sdk`.
+ */
+export declare class LlmClient {
+    private anthropic;
+    private openai;
+    private provider;
+    private model;
+    private maxTokens;
+    private temperature;
+    private endpoint;
+    constructor(opts?: LlmClientOptions);
+    complete(systemPrompt: string, transcript: LlmMessage[]): Promise<LlmCompletion>;
+}

package/dist/llm/client.js

@@ -0,0 +1,122 @@
+// xcoder:version 1 | xcoder:task task-c49600 | xcoder:updated 2026-08-13T13:50:08.142Z | xcoder:subtask code-st-6d79ef
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+/**
+ * One call per ReAct turn: system prompt + running transcript in, raw text
+ * + token usage out. Deliberately thin — the contract parsing lives in
+ * `protocol/react-contract.ts`, not here, so this file never needs to know
+ * what a valid response looks like. Callers are responsible for their own
+ * try/catch around `complete()` — a transient API error here must not be
+ * allowed to propagate all the way up and take the Master Orchestrator
+ * down with it (see `agents/sub-agent.ts`).
+ *
+ * Transport selection:
+ * - `"deepseek"` (default) — DeepSeek's Anthropic-compatible endpoint via
+ *   `@anthropic-ai/sdk`; zero-config behavior is unchanged.
+ * - `"openai-compatible"` — any OpenAI `chat/completions` provider via the
+ *   `openai` SDK (OpenAI, Groq, OpenRouter, Ollama, LM Studio, vLLM, ...).
+ * - `"anthropic"` — native Claude via `@anthropic-ai/sdk`.
+ */
+export class LlmClient {
+    anthropic = null;
+    openai = null;
+    provider;
+    model;
+    maxTokens;
+    temperature;
+    endpoint;
+    constructor(opts = {}) {
+        this.provider = opts.provider ?? "deepseek";
+        this.model = opts.model ?? process.env.XCODER_MODEL ?? "deepseek-chat";
+        this.maxTokens = opts.maxTokens ?? 16384;
+        this.temperature = opts.temperature;
+        if (this.provider === "openai-compatible") {
+            let apiKey = opts.apiKey;
+            if (!apiKey && opts.apiKeyEnv) {
+                apiKey = process.env[opts.apiKeyEnv];
+            }
+            // Keyless local providers (Ollama, LM Studio) accept any placeholder.
+            if (!apiKey)
+                apiKey = "ollama";
+            this.openai = new OpenAI({
+                apiKey,
+                baseURL: opts.baseUrl,
+            });
+            this.endpoint = opts.endpoint ?? "/chat/completions";
+            return;
+        }
+        // `deepseek` (the zero-config default) and native `anthropic` both speak
+        // the Anthropic Messages protocol.
+        let apiKey = opts.apiKey;
+        if (!apiKey && opts.apiKeyEnv) {
+            apiKey = process.env[opts.apiKeyEnv];
+        }
+        if (!apiKey) {
+            if (this.provider === "anthropic") {
+                apiKey = process.env.ANTHROPIC_API_KEY ?? process.env.DEEPSEEK_API_KEY;
+                if (!apiKey) {
+                    throw new Error("ANTHROPIC_API_KEY (or DEEPSEEK_API_KEY) is not set. Export it before running xcoder, e.g.\n" +
+                        '  export ANTHROPIC_API_KEY="sk-ant-..."');
+                }
+            }
+            else {
+                apiKey = process.env.DEEPSEEK_API_KEY;
+                if (!apiKey) {
+                    throw new Error("DEEPSEEK_API_KEY is not set. Export it before running xcoder, e.g.\n" +
+                        '  export DEEPSEEK_API_KEY="sk-..."');
+                }
+            }
+        }
+        const baseURL = opts.baseUrl ??
+            (this.provider === "anthropic"
+                ? "https://api.anthropic.com"
+                : "https://api.deepseek.com/anthropic");
+        this.anthropic = new Anthropic({ apiKey, baseURL });
+    }
+    async complete(systemPrompt, transcript) {
+        if (this.provider === "openai-compatible" && this.openai) {
+            const response = await this.openai.chat.completions.create({
+                model: this.model,
+                max_tokens: this.maxTokens,
+                ...(this.temperature !== undefined ? { temperature: this.temperature } : {}),
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    ...transcript.map((m) => ({ role: m.role, content: m.content })),
+                ],
+            });
+            const choice = response.choices?.[0];
+            return {
+                text: choice?.message?.content ?? "",
+                usage: {
+                    inputTokens: response.usage?.prompt_tokens ?? 0,
+                    outputTokens: response.usage?.completion_tokens ?? 0,
+                },
+                stopReason: choice?.finish_reason ?? null,
+                model: this.model,
+            };
+        }
+        if (!this.anthropic) {
+            throw new Error(`LLM transport not initialized for provider "${this.provider}"`);
+        }
+        const response = await this.anthropic.messages.create({
+            model: this.model,
+            max_tokens: this.maxTokens,
+            ...(this.temperature !== undefined ? { temperature: this.temperature } : {}),
+            system: systemPrompt,
+            messages: transcript.map((m) => ({ role: m.role, content: m.content })),
+        });
+        const text = response.content
+            .map((block) => (block.type === "text" ? block.text : ""))
+            .join("\n")
+            .trim();
+        return {
+            text,
+            usage: {
+                inputTokens: response.usage?.input_tokens ?? 0,
+                outputTokens: response.usage?.output_tokens ?? 0,
+            },
+            stopReason: response.stop_reason ?? null,
+            model: this.model,
+        };
+    }
+}

package/dist/llm/factory.d.ts

@@ -0,0 +1,14 @@
+import { LlmClient } from "./client.js";
+import { type AgentRole } from "../config/loadConfig.js";
+/**
+ * Sole production constructor path for LLM clients. Resolves the effective
+ * per-role configuration from `.xcoder/config/llm.yaml` (or built-in
+ * DeepSeek defaults) and returns a transport ready for that role.
+ *
+ * Precedence in `resolveLlmConfig`: role block → `default` block → built-in
+ * DeepSeek; `XCODER_MODEL` applies to `model` only.
+ */
+export declare function createLlmClient(role: AgentRole, overrides?: {
+    model?: string;
+    maxTokens?: number;
+}): LlmClient;