homegraph 1.2.0 → 1.5.0

package/dist/spec/llm/agents/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Coding-agent adapter abstraction for headless LLM access.
+ *
+ * Each supported coding agent (Claude Code, Codex) implements this
+ * interface so the spec pipelines can fulfil their LLM tasks through the
+ * agent's non-interactive CLI mode — no API key required. Every adapter
+ * owns its own input construction (flags, system-prompt strategy, tool
+ * disabling) and output extraction, guaranteeing the I/O contract matches
+ * what `OpenAiLlmClient` produces.
+ *
+ * @module spec/llm/agents/types
+ */
+/** A prepared headless invocation: argv for execFile + stdin payload. */
+export interface AgentInvocation {
+    /** Argument array — passed to spawn as-is (never shell-concatenated). */
+    args: string[];
+    /** Prompt payload written to the child's stdin. */
+    stdin: string;
+}
+/** Result of a finished headless invocation. */
+export interface AgentRunResult {
+    stdout: string;
+    stderr: string;
+}
+/** Context of a failed invocation, for failure classification. */
+export interface AgentFailure {
+    /**
+     * Process exit code; null for spawn-level failures (e.g. ENOENT).
+     * Timeouts never reach the adapters — the client owns the timer and
+     * always classifies them as retryable.
+     */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Per-agent adapter: detection, invocation construction, output extraction,
+ * and failure classification.
+ */
+export interface AgentAdapter {
+    /** Stable id, also used by the HOMEGRAPH_SPEC_AGENT test override. */
+    readonly id: 'claude-code' | 'codex' | 'deveco-code';
+    /** Human-readable name for log lines. */
+    readonly displayName: string;
+    /** CLI binary name resolved against PATH. */
+    readonly binary: string;
+    /**
+     * Detect whether the agent is installed. Cheap checks only — PATH scan
+     * plus config-directory hint (mirrors the installer targets pattern).
+     * Must NOT spawn the agent itself.
+     */
+    detect(): boolean;
+    /**
+     * Build a non-interactive invocation for one chat call. The adapter is
+     * responsible for disabling all tool/file side effects and for its
+     * system-prompt strategy (native flag vs. prompt embedding).
+     */
+    buildInvocation(systemPrompt: string, userPrompt: string): AgentInvocation;
+    /**
+     * Extract the model's text from raw stdout (e.g. unwrap a JSON envelope,
+     * strip log noise). The returned string must be shaped like an
+     * OpenAI chat-completion content string so downstream `chatJson`
+     * parsing behaves identically across providers.
+     */
+    extractOutput(result: AgentRunResult): string;
+    /**
+     * Classify a failed invocation (non-zero exit or spawn-level error).
+     * 'terminal' covers auth/quota problems — retrying is pointless and the
+     * caller should fall back to the configured LLM. Anything transient
+     * (crashes, timeouts, unexpected exits) is 'retryable'. Both stdout and
+     * stderr are provided: some CLIs (e.g. Codex `--json`) report errors as
+     * structured stdout events rather than on stderr.
+     */
+    classifyFailure(failure: AgentFailure): 'retryable' | 'terminal';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/spec/llm/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/spec/llm/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,GAAG,aAAa,CAAC;IACrD,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC;IAElB;;;;OAIG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,CAAC;IAE3E;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC;IAE9C;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;CAClE"}

package/dist/spec/llm/agents/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Coding-agent adapter abstraction for headless LLM access.
+ *
+ * Each supported coding agent (Claude Code, Codex) implements this
+ * interface so the spec pipelines can fulfil their LLM tasks through the
+ * agent's non-interactive CLI mode — no API key required. Every adapter
+ * owns its own input construction (flags, system-prompt strategy, tool
+ * disabling) and output extraction, guaranteeing the I/O contract matches
+ * what `OpenAiLlmClient` produces.
+ *
+ * @module spec/llm/agents/types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/spec/llm/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/spec/llm/agents/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/dist/spec/llm/client.d.ts

@@ -3,26 +3,46 @@ export interface LlmClient {
     chat(systemPrompt: string, userPrompt: string): Promise<string>;
     chatJson(systemPrompt: string, userPrompt: string): Promise<Record<string, unknown>>;
 }
+/**
+ * Parse an LLM text response as a JSON object.
+ *
+ * Parsing strategy (tried in order):
+ * 1. Direct `JSON.parse(content)`.
+ * 2. Extract from `` ```json ... ``` `` fenced block.
+ * 3. Extract from `` ``` ... ``` `` fenced block.
+ * 4. Fallback: log a debug warning and return `{}`.
+ *
+ * Shared by OpenAiLlmClient and CodingAgentLlmClient so the chatJson
+ * contract is identical regardless of provider.
+ */
+export declare function parseJsonResponse(raw: string): Record<string, unknown>;
 export declare class OpenAiLlmClient implements LlmClient {
     private config;
     constructor(config: LLMConfig);
+    /** Resolve the baseURL for the OpenAI SDK. */
+    private resolveBaseURL;
+    /**
+     * Build a fresh OpenAI client suitable for one call (no SDK-level retry —
+     * we handle retries ourselves with proper visibility).
+     */
+    private buildClient;
     /**
      * Send a chat completion request and return the message content string.
      *
-     * Calls the OpenAI-compatible chat completions API and returns
-     * `choices[0].message.content`. On any error, returns an empty string.
+     * Automatically retries on transient errors (429, 5xx, connection failures)
+     * with exponential backoff and jitter.  Retry-After headers on 429 responses
+     * are honoured as a floor for the delay.
+     *
+     * Retry configuration is in {@link LLMConfig}: `maxRetries` (default 3),
+     * `retryBaseDelayMs` (default 1000), `retryMaxDelayMs` (default 30000).
+     *
+     * Once all retries are exhausted the last error is re-thrown so callers
+     * (e.g. the spec mine generator) can count failures reliably.
      */
     chat(systemPrompt: string, userPrompt: string): Promise<string>;
     /**
-     * Same as `chat()`, but parses the response as JSON.
-     *
-     * Parsing strategy (tried in order):
-     * 1. Direct `JSON.parse(content)`.
-     * 2. Extract from `` ```json ... ``` `` fenced block.
-     * 3. Extract from `` ``` ... ``` `` fenced block.
-     * 4. Fallback: log a debug warning and return `{}`.
-     *
-     * Empty or null content from `chat()` also returns `{}`.
+     * Same as `chat()`, but parses the response as JSON via
+     * {@link parseJsonResponse}. Empty content returns `{}`.
      */
     chatJson(systemPrompt: string, userPrompt: string): Promise<Record<string, unknown>>;
 }

package/dist/spec/llm/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/client.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAOtC,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtF;AAMD,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,EAAE,SAAS;IAQ7B;;;;;OAKG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCrE;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CA+CpC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/client.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4CtE;AAMD,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,EAAE,SAAS;IAQ7B,8CAA8C;IAC9C,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAYnB;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6DrE;;;OAGG;IACG,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAIpC"}

package/dist/spec/llm/client.js

@@ -4,16 +4,80 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAiLlmClient = void 0;
+exports.parseJsonResponse = parseJsonResponse;
 /**
- * Provider-agnostic LLM client for spec self-evolution.
+ * Provider-agnostic LLM client for spec
  *
- * Supports OpenAI-compatible chat completions API. No mock mode — callers
- * that need test doubles inject their own stubs implementing the interface.
+ * Supports OpenAI-compatible chat completions API with automatic retry on
+ * transient errors (rate limits, server errors, network failures). No mock
+ * mode — callers that need test doubles inject their own stubs implementing
+ * the interface.
  *
  * @module spec/llm/client
  */
 const openai_1 = __importDefault(require("openai"));
 const errors_1 = require("../../errors");
+const retry_1 = require("./retry");
+// =============================================================================
+// Shared JSON extraction
+// =============================================================================
+/**
+ * Parse an LLM text response as a JSON object.
+ *
+ * Parsing strategy (tried in order):
+ * 1. Direct `JSON.parse(content)`.
+ * 2. Extract from `` ```json ... ``` `` fenced block.
+ * 3. Extract from `` ``` ... ``` `` fenced block.
+ * 4. Fallback: log a debug warning and return `{}`.
+ *
+ * Shared by OpenAiLlmClient and CodingAgentLlmClient so the chatJson
+ * contract is identical regardless of provider.
+ */
+function parseJsonResponse(raw) {
+    if (!raw)
+        return {};
+    // 1. Direct parse
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to fence extraction
+    }
+    // 2. ```json ... ``` fence
+    const jsonFenceMatch = /```json\s*([\s\S]*?)```/.exec(raw);
+    if (jsonFenceMatch) {
+        try {
+            const parsed = JSON.parse(jsonFenceMatch[1].trim());
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Fall through
+        }
+    }
+    // 3. ``` ... ``` fence
+    const fenceMatch = /```\s*([\s\S]*?)```/.exec(raw);
+    if (fenceMatch) {
+        try {
+            const parsed = JSON.parse(fenceMatch[1].trim());
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Fall through
+        }
+    }
+    // 4. Fallback
+    (0, errors_1.logDebug)('parseJsonResponse: could not parse response as JSON', {
+        raw: raw.length > 200 ? raw.slice(0, 200) + '…' : raw,
+    });
+    return {};
+}
 // =============================================================================
 // OpenAiLlmClient
 // =============================================================================
@@ -23,100 +87,98 @@ class OpenAiLlmClient {
         this.config = config;
     }
     // ===========================================================================
-    // chat
+    // Helpers
     // ===========================================================================
+    /** Resolve the baseURL for the OpenAI SDK. */
+    resolveBaseURL() {
+        if (this.config.baseUrl)
+            return this.config.baseUrl;
+        if (this.config.provider === 'anthropic')
+            return 'https://api.anthropic.com/v1';
+        return undefined;
+    }
     /**
-     * Send a chat completion request and return the message content string.
-     *
-     * Calls the OpenAI-compatible chat completions API and returns
-     * `choices[0].message.content`. On any error, returns an empty string.
+     * Build a fresh OpenAI client suitable for one call (no SDK-level retry —
+     * we handle retries ourselves with proper visibility).
      */
-    async chat(systemPrompt, userPrompt) {
-        const baseURL = this.config.baseUrl
-            ? this.config.baseUrl
-            : this.config.provider === 'anthropic'
-                ? 'https://api.anthropic.com/v1'
-                : undefined;
-        const client = new openai_1.default({
+    buildClient() {
+        return new openai_1.default({
             apiKey: this.config.apiKey,
-            baseURL,
+            baseURL: this.resolveBaseURL(),
+            maxRetries: 0, // disable SDK retry
         });
-        try {
-            const completion = await client.chat.completions.create({
-                model: this.config.model,
-                temperature: this.config.temperature,
-                max_tokens: this.config.maxTokens,
-                messages: [
-                    { role: 'system', content: systemPrompt },
-                    { role: 'user', content: userPrompt },
-                ],
-            });
-            const content = completion.choices[0]?.message?.content;
-            return content ?? '';
-        }
-        catch {
-            return '';
-        }
     }
     // ===========================================================================
-    // chatJson
+    // chat
     // ===========================================================================
     /**
-     * Same as `chat()`, but parses the response as JSON.
+     * Send a chat completion request and return the message content string.
+     *
+     * Automatically retries on transient errors (429, 5xx, connection failures)
+     * with exponential backoff and jitter.  Retry-After headers on 429 responses
+     * are honoured as a floor for the delay.
      *
-     * Parsing strategy (tried in order):
-     * 1. Direct `JSON.parse(content)`.
-     * 2. Extract from `` ```json ... ``` `` fenced block.
-     * 3. Extract from `` ``` ... ``` `` fenced block.
-     * 4. Fallback: log a debug warning and return `{}`.
+     * Retry configuration is in {@link LLMConfig}: `maxRetries` (default 3),
+     * `retryBaseDelayMs` (default 1000), `retryMaxDelayMs` (default 30000).
      *
-     * Empty or null content from `chat()` also returns `{}`.
+     * Once all retries are exhausted the last error is re-thrown so callers
+     * (e.g. the spec mine generator) can count failures reliably.
      */
-    async chatJson(systemPrompt, userPrompt) {
-        const raw = await this.chat(systemPrompt, userPrompt);
-        if (!raw)
-            return {};
-        // 1. Direct parse
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                return parsed;
-            }
-        }
-        catch {
-            // Fall through to fence extraction
-        }
-        // 2. ```json ... ``` fence
-        const jsonFenceMatch = /```json\s*([\s\S]*?)```/.exec(raw);
-        if (jsonFenceMatch) {
-            try {
-                const parsed = JSON.parse(jsonFenceMatch[1].trim());
-                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    return parsed;
-                }
-            }
-            catch {
-                // Fall through
-            }
-        }
-        // 3. ``` ... ``` fence
-        const fenceMatch = /```\s*([\s\S]*?)```/.exec(raw);
-        if (fenceMatch) {
+    async chat(systemPrompt, userPrompt) {
+        // Build once per call — the OpenAI client is stateless so we can reuse it
+        // across retry attempts.
+        const client = this.buildClient();
+        const maxRetries = this.config.maxRetries;
+        const baseDelay = this.config.retryBaseDelayMs;
+        const maxDelay = this.config.retryMaxDelayMs;
+        // We track the cumulative attempt number for logging (1-based),
+        // and the zero-based index for backoff calculation.
+        for (let attemptIndex = 0; attemptIndex <= maxRetries; attemptIndex++) {
+            const callIndex = attemptIndex + 1; // 1-based for logging
             try {
-                const parsed = JSON.parse(fenceMatch[1].trim());
-                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    return parsed;
-                }
+                const completion = await client.chat.completions.create({
+                    model: this.config.model,
+                    temperature: this.config.temperature,
+                    max_tokens: this.config.maxTokens,
+                    messages: [
+                        { role: 'system', content: systemPrompt },
+                        { role: 'user', content: userPrompt },
+                    ],
+                });
+                const content = completion.choices[0]?.message?.content;
+                return content ?? '';
             }
-            catch {
-                // Fall through
+            catch (err) {
+                // No more retries left — re-throw the raw error so callers can
+                // inspect its type (e.g. RateLimitError) if needed.
+                if (attemptIndex >= maxRetries)
+                    throw err;
+                const decision = (0, retry_1.classifyError)(err);
+                if (!decision.retryable)
+                    throw err;
+                const delay = (0, retry_1.computeDelay)(decision.retryAfterMs, baseDelay, maxDelay, attemptIndex);
+                (0, errors_1.logDebug)(`LLM retry ${callIndex}/${maxRetries}`, {
+                    attempt: callIndex,
+                    maxRetries,
+                    delayMs: delay,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                await (0, retry_1.sleep)(delay);
             }
         }
-        // 4. Fallback
-        (0, errors_1.logDebug)('chatJson: could not parse response as JSON', {
-            raw: raw.length > 200 ? raw.slice(0, 200) + '…' : raw,
-        });
-        return {};
+        // Unreachable — the loop returns or throws in every branch.
+        throw new Error('unreachable: retry loop exited without returning');
+    }
+    // ===========================================================================
+    // chatJson
+    // ===========================================================================
+    /**
+     * Same as `chat()`, but parses the response as JSON via
+     * {@link parseJsonResponse}. Empty content returns `{}`.
+     */
+    async chatJson(systemPrompt, userPrompt) {
+        const raw = await this.chat(systemPrompt, userPrompt);
+        return parseJsonResponse(raw);
     }
 }
 exports.OpenAiLlmClient = OpenAiLlmClient;

package/dist/spec/llm/client.js.map

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

package/dist/spec/llm/factory.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LLM client factory for the spec pipelines — the single resolution point
+ * that decides WHERE LLM calls go:
+ *
+ *   1. A locally installed coding agent (Claude Code preferred, then
+ *      Codex) in headless mode — no API key required;
+ *   2. The user-configured LLM (configs.json "llm" section) — used alone
+ *      when no agent is installed, and as an automatic fallback when the
+ *      agent's headless call fails;
+ *   3. undefined — neither available; callers keep their existing
+ *      no-LLM degradation paths.
+ *
+ * Coding-agent resolution is fully automatic (spec evolve is mostly
+ * git-hook triggered, so interactive selection is impossible) and the
+ * LLMConfig surface is deliberately untouched.
+ *
+ * @module spec/llm/factory
+ */
+import { LLMConfig } from '../config';
+import { LlmClient } from './client';
+/**
+ * Composite client: try the coding agent first; on ANY failure of the
+ * primary, delegate the same call to the configured LLM. Terminal agent
+ * failures (auth/quota) therefore degrade seamlessly to the API path.
+ */
+export declare class FallbackLlmClient implements LlmClient {
+    private readonly primary;
+    private readonly secondary;
+    constructor(primary: LlmClient, secondary: LlmClient);
+    chat(systemPrompt: string, userPrompt: string): Promise<string>;
+    chatJson(systemPrompt: string, userPrompt: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Resolve the LLM client for a spec pipeline run.
+ *
+ * @param llmConfig - The configs.json "llm" section (may be null).
+ * @returns A ready client, or undefined when neither a coding agent nor
+ *   an LLM configuration is available.
+ */
+export declare function createSpecLlmClient(llmConfig: LLMConfig | null): LlmClient | undefined;
+//# sourceMappingURL=factory.d.ts.map

package/dist/spec/llm/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,SAAS,EAAmB,MAAM,UAAU,CAAC;AAKtD;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IAE/C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,OAAO,EAAE,SAAS,EAClB,SAAS,EAAE,SAAS;IAGjC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW/D,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAUpC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAWtF"}

package/dist/spec/llm/factory.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * LLM client factory for the spec pipelines — the single resolution point
+ * that decides WHERE LLM calls go:
+ *
+ *   1. A locally installed coding agent (Claude Code preferred, then
+ *      Codex) in headless mode — no API key required;
+ *   2. The user-configured LLM (configs.json "llm" section) — used alone
+ *      when no agent is installed, and as an automatic fallback when the
+ *      agent's headless call fails;
+ *   3. undefined — neither available; callers keep their existing
+ *      no-LLM degradation paths.
+ *
+ * Coding-agent resolution is fully automatic (spec evolve is mostly
+ * git-hook triggered, so interactive selection is impossible) and the
+ * LLMConfig surface is deliberately untouched.
+ *
+ * @module spec/llm/factory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackLlmClient = void 0;
+exports.createSpecLlmClient = createSpecLlmClient;
+const client_1 = require("./client");
+const agent_client_1 = require("./agent-client");
+const agents_1 = require("./agents");
+const errors_1 = require("../../errors");
+/**
+ * Composite client: try the coding agent first; on ANY failure of the
+ * primary, delegate the same call to the configured LLM. Terminal agent
+ * failures (auth/quota) therefore degrade seamlessly to the API path.
+ */
+class FallbackLlmClient {
+    primary;
+    secondary;
+    constructor(primary, secondary) {
+        this.primary = primary;
+        this.secondary = secondary;
+    }
+    async chat(systemPrompt, userPrompt) {
+        try {
+            return await this.primary.chat(systemPrompt, userPrompt);
+        }
+        catch (err) {
+            (0, errors_1.logWarn)('Coding-agent LLM call failed — falling back to configured LLM', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return this.secondary.chat(systemPrompt, userPrompt);
+        }
+    }
+    async chatJson(systemPrompt, userPrompt) {
+        try {
+            return await this.primary.chatJson(systemPrompt, userPrompt);
+        }
+        catch (err) {
+            (0, errors_1.logWarn)('Coding-agent LLM call failed — falling back to configured LLM', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return this.secondary.chatJson(systemPrompt, userPrompt);
+        }
+    }
+}
+exports.FallbackLlmClient = FallbackLlmClient;
+/**
+ * Resolve the LLM client for a spec pipeline run.
+ *
+ * @param llmConfig - The configs.json "llm" section (may be null).
+ * @returns A ready client, or undefined when neither a coding agent nor
+ *   an LLM configuration is available.
+ */
+function createSpecLlmClient(llmConfig) {
+    const agent = (0, agents_1.resolveAgent)();
+    const api = llmConfig ? new client_1.OpenAiLlmClient(llmConfig) : undefined;
+    if (agent) {
+        (0, errors_1.logDebug)(`Using ${agent.displayName} (headless) for LLM tasks`, { agent: agent.id });
+        const primary = new agent_client_1.CodingAgentLlmClient(agent);
+        return api ? new FallbackLlmClient(primary, api) : primary;
+    }
+    return api;
+}
+//# sourceMappingURL=factory.js.map

package/dist/spec/llm/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/spec/llm/factory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAoDH,kDAWC;AA5DD,qCAAsD;AACtD,iDAAsD;AACtD,qCAAwC;AACxC,yCAAiD;AAEjD;;;;GAIG;AACH,MAAa,iBAAiB;IAET;IACA;IAFnB,YACmB,OAAkB,EAClB,SAAoB;QADpB,YAAO,GAAP,OAAO,CAAW;QAClB,cAAS,GAAT,SAAS,CAAW;IACpC,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,YAAoB,EAAE,UAAkB;QACjD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAA,gBAAO,EAAC,+DAA+D,EAAE;gBACvE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,YAAoB,EACpB,UAAkB;QAElB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAA,gBAAO,EAAC,+DAA+D,EAAE;gBACvE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AA9BD,8CA8BC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,SAA2B;IAC7D,MAAM,KAAK,GAAG,IAAA,qBAAY,GAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,wBAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,IAAI,KAAK,EAAE,CAAC;QACV,IAAA,iBAAQ,EAAC,SAAS,KAAK,CAAC,WAAW,2BAA2B,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACrF,MAAM,OAAO,GAAG,IAAI,mCAAoB,CAAC,KAAK,CAAC,CAAC;QAChD,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7D,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/spec/llm/prompts.d.ts

@@ -1,13 +1,29 @@
 /**
- * LLM prompt templates for spec self-evolution.
- *
- * Extracted from logic-checker.ts and spec-rewriter.ts so evolve modules
- * don't contain prompt strings directly.
+ * LLM prompt templates for the spec pipelines — spec self-evolution
+ * (cluster evaluation) and spec mining (spec generation from clusters).
  *
  * @module spec/llm/prompts
  */
-export declare const LOGIC_CHECK_SYSTEM_PROMPT = "You are a code review assistant. Your task is to determine whether a git commit represents a business-logic change (as opposed to purely cosmetic, formatting, comment-only, or test-only changes).\n\nA business-logic change includes:\n- Changes to algorithms, data structures, or control flow\n- Changes to business rules, validation logic, or domain behavior\n- Adding or removing functionality\n- Bug fixes that change behavior\n\nNOT business-logic changes:\n- Whitespace, formatting, or code style changes\n- Comment-only changes\n- Test-only changes (adding tests without changing production code)\n- Configuration changes that don't alter behavior\n- Package/dependency version bumps\n\nRespond with a JSON object:\n{\n  \"is_logic_change\": true/false,\n  \"reason\": \"Brief explanation of why this is or is not a logic change\"\n}";
-export declare function buildLogicCheckUserPrompt(commitMessage: string, truncatedDiff: string): string;
-export declare const SPEC_EVALUATION_SYSTEM_PROMPT = "You are a technical documentation maintainer. Your task is to evaluate whether a git commit requires updating a software design specification (plan.md).\n\nGiven the current plan content, the commit message, and the code diff, determine:\n1. Whether the plan needs to be updated (UPDATE), deprecated (DEPRECATE), or left unchanged (UNCHANGED).\n2. If UPDATE: provide the new title, subtitles (as an array of heading-preview strings), and full rewritten plan_content.\n3. If DEPRECATE: provide a brief explanation in the plan_content field.\n\nResponse format (JSON):\n{\n  \"action\": \"UPDATE\" | \"DEPRECATE\" | \"UNCHANGED\",\n  \"title\": \"New spec title (for UPDATE)\",\n  \"subtitles\": [\"heading1 \u2192 heading2 - preview\", ...],\n  \"plan_content\": \"Full rewritten markdown content (for UPDATE) or deprecation reason (for DEPRECATE)\"\n}";
-export declare function buildSpecEvaluationUserPrompt(planContent: string, commitMessage: string, truncatedDiff: string, scheduleNextSpecs: string[]): string;
+import { ClusterContext } from '../types';
+/** Default markdown template for generated spec documents. */
+export declare const DEFAULT_SPEC_TEMPLATE = "# Spec: {{title}}\n\n## Summary\n{{summary}}\n\n## Motivation\n{{motivation}}\n\n## Specification\n\n### Functional Requirements\n{{functional_requirements}}\n\n### Acceptance Criteria (EARS format)\n{{acceptance_criteria}}\n\n## Implementation Notes\n\n### Related Commits\n{{commit_list}}\n\n### Affected Files\n{{file_list}}\n\n### Key Symbols\n{{symbol_list}}\n";
+/** System prompt for LLM spec generation from a commit cluster. */
+export declare const SPEC_GENERATION_SYSTEM_PROMPT = "You are a technical documentation writer specializing in software design specifications. Given a cluster of related Git commits, generate a design specification in markdown format.\n\nGuidelines:\n- Focus on WHAT was built, not HOW it was implemented\n- Use EARS (Easy Approach to Requirements Syntax) for acceptance criteria\n- Be specific \u2014 reference real symbols, files, and commit messages\n- Keep the spec concise but complete\n- Output ONLY the spec document, no preamble or commentary\n\nOutput format \u2014 fill in the template exactly. Replace {{placeholders}} with real content. Do NOT include the placeholder braces in your output.";
+export declare const SPEC_EVALUATION_CLUSTER_SYSTEM_PROMPT = "You are a technical documentation maintainer. Your task is to evaluate whether a GROUP of related git commits requires updating a software design specification.\n\nGiven the current content and a summary of multiple commits that affect this spec, determine:\n1. Whether the spec needs to be updated (UPDATE), deprecated (DEPRECATE), or left unchanged (UNCHANGED).\n2. If UPDATE: provide the new title, subtitles (as an array of heading-preview strings), and full rewritten spec_content that incorporates the changes from all commits.\n3. If DEPRECATE: provide a brief explanation in the spec_content field.\n\nKey considerations for batch evaluation:\n- Multiple commits may partially overlap in their changes \u2014 synthesize the combined impact.\n- Some commits may be bug fixes that revert earlier changes \u2014 look for the net effect.\n- If the combined changes fundamentally alter the spec's scope, prefer DEPRECATE over UPDATE.\n\nResponse format (JSON):\n{\n  \"action\": \"UPDATE\" | \"DEPRECATE\" | \"UNCHANGED\",\n  \"title\": \"New spec title (for UPDATE)\",\n  \"subtitles\": [\"heading1 \u2192 heading2 - preview\", ...],\n  \"spec_content\": \"Full rewritten markdown content (for UPDATE) or deprecation reason (for DEPRECATE)\"\n}";
+/**
+ * Build the user prompt for cluster-based spec evaluation.
+ *
+ * Presents:
+ * 1. The current spec content.
+ * 2. A cluster overview (commit count, primary files).
+ * 3. Per-commit summaries (short hash, message, changed files, truncated diff).
+ *
+ * The prompt is designed to fit within a reasonable token budget for a
+ * single LLM call even with 5-10 commits in the cluster.
+ *
+ * @param specContent    - Full current spec.md content.
+ * @param clusterContext - Pre-built cluster context from buildClusterContext.
+ * @returns Formatted user prompt string.
+ */
+export declare function buildClusterSpecEvaluationUserPrompt(specContent: string, clusterContext: ClusterContext): string;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/spec/llm/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,yBAAyB,20BAmBpC,CAAC;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,MAAM,CAOR;AAMD,eAAO,MAAM,6BAA6B,w1BAaxC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,MAAM,CAcR"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/prompts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAO1C,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,kXA0BjC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,6BAA6B,6oBASsG,CAAC;AAWjJ,eAAO,MAAM,qCAAqC,quCAkBhD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,cAAc,GAC7B,MAAM,CAmCR"}