@substrate-ai/factory 0.19.54

package/dist/backend/direct-bootstrap.js

@@ -0,0 +1,109 @@
+/**
+ * Bootstrap function for the DirectCodergenBackend.
+ *
+ * Instantiates the correct provider adapter, LLMClient, and ExecutionEnvironment
+ * based on the given options, and returns a ready-to-use DirectCodergenBackend.
+ *
+ * Story 48-12.
+ */
+import { execSync } from 'node:child_process';
+import { LLMClient } from '../llm/client.js';
+import { AnthropicAdapter } from '../llm/providers/anthropic.js';
+import { OpenAIAdapter } from '../llm/providers/openai.js';
+import { GeminiAdapter } from '../llm/providers/gemini.js';
+import { AnthropicProfile, OpenAIProfile, GeminiProfile } from '../agent/tools/profiles.js';
+import { createDirectCodergenBackend } from './direct-backend.js';
+// ---------------------------------------------------------------------------
+// bootstrapDirectBackend
+// ---------------------------------------------------------------------------
+/**
+ * Bootstrap a DirectCodergenBackend for the given provider and model.
+ *
+ * Reads the required API key from the environment, instantiates the correct
+ * provider adapter and profile, constructs an LLMClient, and returns a
+ * DirectCodergenBackend configured with the given options.
+ *
+ * @throws Error if the required API key environment variable is missing
+ * @throws Error if the provider string is not recognised
+ */
+export function bootstrapDirectBackend(opts) {
+    const { provider, model, maxTurns, projectDir, onEvent } = opts;
+    // Build an ExecutionEnvironment backed by child_process.execSync
+    const executionEnv = {
+        workdir: projectDir,
+        exec: (command, timeoutMs) => {
+            return new Promise((resolve) => {
+                try {
+                    const stdout = execSync(command, {
+                        cwd: projectDir,
+                        timeout: timeoutMs,
+                        encoding: 'utf-8',
+                    });
+                    resolve({ stdout: stdout || '', stderr: '', exitCode: 0 });
+                }
+                catch (err) {
+                    const execError = err;
+                    resolve({
+                        stdout: execError.stdout ? String(execError.stdout) : '',
+                        stderr: execError.stderr ? String(execError.stderr) : '',
+                        exitCode: typeof execError.status === 'number' ? execError.status : 1,
+                    });
+                }
+            });
+        },
+    };
+    const client = new LLMClient();
+    if (provider === 'anthropic') {
+        const apiKey = process.env['ANTHROPIC_API_KEY'];
+        if (!apiKey) {
+            throw new Error('ANTHROPIC_API_KEY environment variable is required for direct backend with anthropic provider');
+        }
+        const adapter = new AnthropicAdapter({ apiKey });
+        client.registerProvider('anthropic', adapter);
+        client.registerModelPattern('claude-*', 'anthropic');
+        const providerProfile = new AnthropicProfile(model);
+        return createDirectCodergenBackend({
+            llmClient: client,
+            providerProfile,
+            executionEnv,
+            config: { max_turns: maxTurns },
+            ...(onEvent !== undefined ? { onEvent } : {}),
+        });
+    }
+    if (provider === 'openai') {
+        const apiKey = process.env['OPENAI_API_KEY'];
+        if (!apiKey) {
+            throw new Error('OPENAI_API_KEY environment variable is required for direct backend with openai provider');
+        }
+        const adapter = new OpenAIAdapter({ apiKey });
+        client.registerProvider('openai', adapter);
+        client.registerModelPattern('gpt-*', 'openai');
+        const providerProfile = new OpenAIProfile(model);
+        return createDirectCodergenBackend({
+            llmClient: client,
+            providerProfile,
+            executionEnv,
+            config: { max_turns: maxTurns },
+            ...(onEvent !== undefined ? { onEvent } : {}),
+        });
+    }
+    if (provider === 'gemini') {
+        const apiKey = process.env['GEMINI_API_KEY'];
+        if (!apiKey) {
+            throw new Error('GEMINI_API_KEY environment variable is required for direct backend with gemini provider');
+        }
+        const adapter = new GeminiAdapter({ apiKey });
+        client.registerProvider('gemini', adapter);
+        client.registerModelPattern('gemini-*', 'gemini');
+        const providerProfile = new GeminiProfile(model);
+        return createDirectCodergenBackend({
+            llmClient: client,
+            providerProfile,
+            executionEnv,
+            config: { max_turns: maxTurns },
+            ...(onEvent !== undefined ? { onEvent } : {}),
+        });
+    }
+    throw new Error(`Unknown direct backend provider: ${provider}`);
+}
+//# sourceMappingURL=direct-bootstrap.js.map

package/dist/backend/direct-bootstrap.js.map

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

package/dist/backend/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for the backend module.
+ * Story 42-18.
+ */
+export type { ICodergenBackend, MockBackendResponse, MockCodergenBackendConfig, CallRecord } from './types.js';
+export { MockCodergenBackend, createMockCodergenBackend } from './mock-backend.js';
+export type { DirectBackendOptions } from './direct-backend.js';
+export { DirectCodergenBackend, createDirectCodergenBackend } from './direct-backend.js';
+export { bootstrapDirectBackend } from './direct-bootstrap.js';
+export type { DirectBootstrapOptions } from './direct-bootstrap.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC9G,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAClF,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAA;AACxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/backend/index.js

@@ -0,0 +1,8 @@
+/**
+ * Barrel export for the backend module.
+ * Story 42-18.
+ */
+export { MockCodergenBackend, createMockCodergenBackend } from './mock-backend.js';
+export { DirectCodergenBackend, createDirectCodergenBackend } from './direct-backend.js';
+export { bootstrapDirectBackend } from './direct-bootstrap.js';
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAElF,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAA;AACxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/backend/mock-backend.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MockCodergenBackend — injectable mock for testing the graph engine.
+ *
+ * Supports configurable response sequences, per-call failure injection,
+ * artificial delays, and full call argument recording.
+ *
+ * Story 42-18.
+ */
+import type { GraphNode, IGraphContext, Outcome } from '../graph/types.js';
+import type { ICodergenBackend, MockCodergenBackendConfig, CallRecord } from './types.js';
+/**
+ * A configurable mock implementation of `ICodergenBackend`.
+ *
+ * Usage:
+ * ```ts
+ * const mock = createMockCodergenBackend({
+ *   responses: [{ status: 'NEEDS_RETRY' }, { status: 'SUCCESS', contextUpdates: { result: 'done' } }],
+ * })
+ * const handler = createCodergenHandler({ backend: mock })
+ * ```
+ */
+export declare class MockCodergenBackend implements ICodergenBackend {
+    /** Configuration for this mock instance. */
+    private readonly config;
+    /** 1-based call counter. Incremented before each `run()` evaluation. */
+    private _callCount;
+    /** Recorded arguments from every `run()` invocation, in order. */
+    calls: CallRecord[];
+    constructor(config?: MockCodergenBackendConfig);
+    /**
+     * Simulate a codergen backend invocation.
+     *
+     * Steps:
+     *   1. Increment `_callCount` (1-based).
+     *   2. Record the call arguments into `calls`.
+     *   3. Optionally wait `config.delay` milliseconds.
+     *   4. If this call index is in `failOnCall`, return `{ status: 'FAILURE' }`.
+     *   5. Otherwise return the configured response (last response repeats on over-use).
+     */
+    run(node: GraphNode, prompt: string, context: IGraphContext): Promise<Outcome>;
+}
+/**
+ * Create a new `MockCodergenBackend` instance with the given configuration.
+ *
+ * @param config - Optional mock configuration (responses, failOnCall, delay).
+ * @returns A fresh `MockCodergenBackend` instance.
+ */
+export declare function createMockCodergenBackend(config?: MockCodergenBackendConfig): MockCodergenBackend;
+//# sourceMappingURL=mock-backend.d.ts.map

package/dist/backend/mock-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-backend.d.ts","sourceRoot":"","sources":["../../src/backend/mock-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC1E,OAAO,KAAK,EACV,gBAAgB,EAEhB,yBAAyB,EACzB,UAAU,EACX,MAAM,YAAY,CAAA;AAMnB;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D,wEAAwE;IACxE,OAAO,CAAC,UAAU,CAAI;IAEtB,kEAAkE;IAC3D,KAAK,EAAE,UAAU,EAAE,CAAK;gBAEnB,MAAM,CAAC,EAAE,yBAAyB;IAQ9C;;;;;;;;;OASG;IACG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;CAgCrF;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,CAAC,EAAE,yBAAyB,GACjC,mBAAmB,CAErB"}

package/dist/backend/mock-backend.js

@@ -0,0 +1,87 @@
+/**
+ * MockCodergenBackend — injectable mock for testing the graph engine.
+ *
+ * Supports configurable response sequences, per-call failure injection,
+ * artificial delays, and full call argument recording.
+ *
+ * Story 42-18.
+ */
+// ---------------------------------------------------------------------------
+// MockCodergenBackend
+// ---------------------------------------------------------------------------
+/**
+ * A configurable mock implementation of `ICodergenBackend`.
+ *
+ * Usage:
+ * ```ts
+ * const mock = createMockCodergenBackend({
+ *   responses: [{ status: 'NEEDS_RETRY' }, { status: 'SUCCESS', contextUpdates: { result: 'done' } }],
+ * })
+ * const handler = createCodergenHandler({ backend: mock })
+ * ```
+ */
+export class MockCodergenBackend {
+    /** Configuration for this mock instance. */
+    config;
+    /** 1-based call counter. Incremented before each `run()` evaluation. */
+    _callCount = 0;
+    /** Recorded arguments from every `run()` invocation, in order. */
+    calls = [];
+    constructor(config) {
+        this.config = {
+            responses: config?.responses ?? [{ status: 'SUCCESS' }],
+            failOnCall: config?.failOnCall ?? [],
+            delay: config?.delay ?? 0,
+        };
+    }
+    /**
+     * Simulate a codergen backend invocation.
+     *
+     * Steps:
+     *   1. Increment `_callCount` (1-based).
+     *   2. Record the call arguments into `calls`.
+     *   3. Optionally wait `config.delay` milliseconds.
+     *   4. If this call index is in `failOnCall`, return `{ status: 'FAILURE' }`.
+     *   5. Otherwise return the configured response (last response repeats on over-use).
+     */
+    async run(node, prompt, context) {
+        // 1. Increment call counter (1-based)
+        this._callCount++;
+        const callIndex = this._callCount;
+        // 2. Record call
+        this.calls.push({ node, prompt, context, callIndex });
+        // 3. Apply artificial delay
+        if (this.config.delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this.config.delay));
+        }
+        // 4. Inject failure if this call index is in failOnCall
+        if (this.config.failOnCall.includes(callIndex)) {
+            return { status: 'FAILURE' };
+        }
+        // 5. Determine which response to use (last repeats on over-use)
+        const responses = this.config.responses;
+        const responseIndex = Math.min(callIndex - 1, responses.length - 1);
+        const response = responses[responseIndex];
+        const result = {
+            status: response.status,
+            contextUpdates: response.contextUpdates ?? {},
+        };
+        if (response.notes !== undefined) {
+            result.notes = response.notes;
+        }
+        return result;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a new `MockCodergenBackend` instance with the given configuration.
+ *
+ * @param config - Optional mock configuration (responses, failOnCall, delay).
+ * @returns A fresh `MockCodergenBackend` instance.
+ */
+export function createMockCodergenBackend(config) {
+    return new MockCodergenBackend(config);
+}
+//# sourceMappingURL=mock-backend.js.map

package/dist/backend/mock-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-backend.js","sourceRoot":"","sources":["../../src/backend/mock-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAmB;IAC9B,4CAA4C;IAC3B,MAAM,CAAqC;IAE5D,wEAAwE;IAChE,UAAU,GAAG,CAAC,CAAA;IAEtB,kEAAkE;IAC3D,KAAK,GAAiB,EAAE,CAAA;IAE/B,YAAY,MAAkC;QAC5C,IAAI,CAAC,MAAM,GAAG;YACZ,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YACvD,UAAU,EAAE,MAAM,EAAE,UAAU,IAAI,EAAE;YACpC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;SAC1B,CAAA;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG,CAAC,IAAe,EAAE,MAAc,EAAE,OAAsB;QAC/D,sCAAsC;QACtC,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAA;QAEjC,iBAAiB;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;QAErD,4BAA4B;QAC5B,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAC9E,CAAC;QAED,wDAAwD;QACxD,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;QAC9B,CAAC;QAED,gEAAgE;QAChE,MAAM,SAAS,GAA0B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAA;QAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACnE,MAAM,QAAQ,GAAG,SAAS,CAAC,aAAa,CAAE,CAAA;QAE1C,MAAM,MAAM,GAAY;YACtB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,cAAc,EAAE,QAAQ,CAAC,cAAc,IAAI,EAAE;SAC9C,CAAA;QACD,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAA;QAC/B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAkC;IAElC,OAAO,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACxC,CAAC"}

package/dist/backend/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Types for the codergen backend abstraction layer.
+ *
+ * Provides `ICodergenBackend` interface and associated types for injecting
+ * configurable mock backends into the codergen handler — enabling deterministic
+ * testing of retry logic, budget enforcement, and convergence behavior without
+ * real LLM calls.
+ *
+ * Story 42-18.
+ */
+import type { GraphNode, IGraphContext, Outcome, OutcomeStatus } from '../graph/types.js';
+/**
+ * A single configured response returned by `MockCodergenBackend` on a given call.
+ */
+export interface MockBackendResponse {
+    /** Status to return for this call. */
+    status: OutcomeStatus;
+    /** Optional context updates to include in the returned Outcome. */
+    contextUpdates?: Record<string, string>;
+    /** Optional notes string to include in the returned Outcome. */
+    notes?: string;
+}
+/**
+ * Configuration for `MockCodergenBackend`.
+ */
+export interface MockCodergenBackendConfig {
+    /**
+     * Ordered list of responses to return on successive `run()` calls.
+     * When calls exceed the list length, the last response is repeated.
+     * Defaults to `[{ status: 'SUCCESS' }]`.
+     */
+    responses?: MockBackendResponse[];
+    /**
+     * 1-based call indices on which `run()` should return `{ status: 'FAILURE' }`.
+     * Defaults to `[]` (no injected failures).
+     */
+    failOnCall?: number[];
+    /**
+     * Artificial delay in milliseconds before each `run()` call resolves.
+     * Use `vi.useFakeTimers()` in tests to avoid real wall-clock waits.
+     * Defaults to `0` (no delay).
+     */
+    delay?: number;
+}
+/**
+ * A record of a single invocation of `MockCodergenBackend.run()`.
+ * Appended to `MockCodergenBackend.calls` on each invocation.
+ */
+export interface CallRecord {
+    /** The graph node dispatched. */
+    node: GraphNode;
+    /** The interpolated prompt string passed to `run()`. */
+    prompt: string;
+    /** The graph context at the time of the call. */
+    context: IGraphContext;
+    /** 1-based index of this call among all calls to this mock instance. */
+    callIndex: number;
+}
+/**
+ * Formal interface for codergen backends.
+ * Implemented by `MockCodergenBackend` for testing and by any future real backend.
+ */
+export interface ICodergenBackend {
+    /**
+     * Invoke the backend with the given node, prompt, and context.
+     * Returns an `Outcome` that the codergen handler returns directly.
+     *
+     * @param node    - The graph node being dispatched.
+     * @param prompt  - The interpolated prompt string.
+     * @param context - The current graph execution context.
+     */
+    run(node: GraphNode, prompt: string, context: IGraphContext): Promise<Outcome>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/backend/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/backend/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAMzF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,MAAM,EAAE,aAAa,CAAA;IACrB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,IAAI,EAAE,SAAS,CAAA;IACf,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,OAAO,EAAE,aAAa,CAAA;IACtB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/E"}

package/dist/backend/types.js

@@ -0,0 +1,12 @@
+/**
+ * Types for the codergen backend abstraction layer.
+ *
+ * Provides `ICodergenBackend` interface and associated types for injecting
+ * configurable mock backends into the codergen handler — enabling deterministic
+ * testing of retry logic, budget enforcement, and convergence behavior without
+ * real LLM calls.
+ *
+ * Story 42-18.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/backend/types.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,196 @@
+/**
+ * FactoryConfigSchema — Zod schema for the `factory:` section of config.yaml.
+ *
+ * Defines and validates all factory pipeline settings with defaults per
+ * architecture Section 10.1.
+ *
+ * Story 44-9.
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for the `factory:` section of `config.yaml`.
+ *
+ * All fields except `graph` have defaults so an empty `factory: {}` block is
+ * fully valid and produces the documented defaults.
+ */
+export declare const FactoryConfigSchema: z.ZodObject<{
+    graph: z.ZodOptional<z.ZodString>;
+    scenario_dir: z.ZodDefault<z.ZodString>;
+    satisfaction_threshold: z.ZodDefault<z.ZodNumber>;
+    budget_cap_usd: z.ZodDefault<z.ZodNumber>;
+    wall_clock_cap_seconds: z.ZodDefault<z.ZodNumber>;
+    plateau_window: z.ZodDefault<z.ZodNumber>;
+    plateau_threshold: z.ZodDefault<z.ZodNumber>;
+    backend: z.ZodDefault<z.ZodEnum<{
+        cli: "cli";
+        direct: "direct";
+    }>>;
+    quality_mode: z.ZodDefault<z.ZodEnum<{
+        "code-review": "code-review";
+        "dual-signal": "dual-signal";
+        "scenario-primary": "scenario-primary";
+        "scenario-only": "scenario-only";
+    }>>;
+    direct_backend: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<{
+            anthropic: "anthropic";
+            openai: "openai";
+            gemini: "gemini";
+        }>>;
+        model: z.ZodDefault<z.ZodString>;
+        max_turns: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type FactoryConfig = z.infer<typeof FactoryConfigSchema>;
+/**
+ * Extends SubstrateConfigSchema with an optional `factory:` section.
+ *
+ * Use this schema to parse the full `config.yaml` file in a factory context.
+ */
+export declare const FactoryExtendedConfigSchema: z.ZodObject<{
+    config_format_version: z.ZodEnum<{
+        1: "1";
+    }>;
+    task_graph_version: z.ZodOptional<z.ZodEnum<{
+        1: "1";
+    }>>;
+    global: z.ZodObject<{
+        log_level: z.ZodEnum<{
+            error: "error";
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            fatal: "fatal";
+        }>;
+        max_concurrent_tasks: z.ZodNumber;
+        budget_cap_tokens: z.ZodNumber;
+        budget_cap_usd: z.ZodNumber;
+        workspace_dir: z.ZodOptional<z.ZodString>;
+        update_check: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    providers: z.ZodObject<{
+        claude: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            cli_path: z.ZodOptional<z.ZodString>;
+            subscription_routing: z.ZodEnum<{
+                auto: "auto";
+                subscription: "subscription";
+                api: "api";
+                disabled: "disabled";
+            }>;
+            max_concurrent: z.ZodNumber;
+            rate_limit: z.ZodOptional<z.ZodObject<{
+                tokens: z.ZodNumber;
+                window_seconds: z.ZodNumber;
+            }, z.core.$strict>>;
+            api_key_env: z.ZodOptional<z.ZodString>;
+            api_billing: z.ZodBoolean;
+        }, z.core.$strict>>;
+        codex: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            cli_path: z.ZodOptional<z.ZodString>;
+            subscription_routing: z.ZodEnum<{
+                auto: "auto";
+                subscription: "subscription";
+                api: "api";
+                disabled: "disabled";
+            }>;
+            max_concurrent: z.ZodNumber;
+            rate_limit: z.ZodOptional<z.ZodObject<{
+                tokens: z.ZodNumber;
+                window_seconds: z.ZodNumber;
+            }, z.core.$strict>>;
+            api_key_env: z.ZodOptional<z.ZodString>;
+            api_billing: z.ZodBoolean;
+        }, z.core.$strict>>;
+        gemini: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            cli_path: z.ZodOptional<z.ZodString>;
+            subscription_routing: z.ZodEnum<{
+                auto: "auto";
+                subscription: "subscription";
+                api: "api";
+                disabled: "disabled";
+            }>;
+            max_concurrent: z.ZodNumber;
+            rate_limit: z.ZodOptional<z.ZodObject<{
+                tokens: z.ZodNumber;
+                window_seconds: z.ZodNumber;
+            }, z.core.$strict>>;
+            api_key_env: z.ZodOptional<z.ZodString>;
+            api_billing: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    cost_tracker: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        token_rates_provider: z.ZodEnum<{
+            builtin: "builtin";
+            custom: "custom";
+        }>;
+        track_planning_costs: z.ZodBoolean;
+        savings_reporting: z.ZodBoolean;
+    }, z.core.$strict>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        default_task_budget_usd: z.ZodNumber;
+        default_session_budget_usd: z.ZodNumber;
+        planning_costs_count_against_budget: z.ZodBoolean;
+        warning_threshold_percent: z.ZodNumber;
+    }, z.core.$strict>>;
+    telemetry: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        meshUrl: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    trivialOutputThreshold: z.ZodOptional<z.ZodNumber>;
+    factory: z.ZodOptional<z.ZodObject<{
+        graph: z.ZodOptional<z.ZodString>;
+        scenario_dir: z.ZodDefault<z.ZodString>;
+        satisfaction_threshold: z.ZodDefault<z.ZodNumber>;
+        budget_cap_usd: z.ZodDefault<z.ZodNumber>;
+        wall_clock_cap_seconds: z.ZodDefault<z.ZodNumber>;
+        plateau_window: z.ZodDefault<z.ZodNumber>;
+        plateau_threshold: z.ZodDefault<z.ZodNumber>;
+        backend: z.ZodDefault<z.ZodEnum<{
+            cli: "cli";
+            direct: "direct";
+        }>>;
+        quality_mode: z.ZodDefault<z.ZodEnum<{
+            "code-review": "code-review";
+            "dual-signal": "dual-signal";
+            "scenario-primary": "scenario-primary";
+            "scenario-only": "scenario-only";
+        }>>;
+        direct_backend: z.ZodDefault<z.ZodObject<{
+            provider: z.ZodDefault<z.ZodEnum<{
+                anthropic: "anthropic";
+                openai: "openai";
+                gemini: "gemini";
+            }>>;
+            model: z.ZodDefault<z.ZodString>;
+            max_turns: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+export type FactoryExtendedConfig = z.infer<typeof FactoryExtendedConfigSchema>;
+/**
+ * Load and parse the factory configuration from `config.yaml`.
+ *
+ * Search order (architecture Section 11.3):
+ *   1. `explicitConfigPath` if provided (bypasses auto-detection)
+ *   2. `<projectDir>/.substrate/config.yaml`
+ *   3. `<projectDir>/config.yaml`
+ *   4. Return all-defaults config if neither file exists
+ *
+ * @param projectDir - Absolute path to the project root directory.
+ * @param explicitConfigPath - Optional explicit path to the config file (e.g. from `--config` flag).
+ * @returns Parsed and validated `FactoryExtendedConfig` with all defaults applied.
+ */
+/**
+ * Resolve the config file path without loading it.
+ * Returns the first existing path, or null if no config file found.
+ */
+export declare function resolveConfigPath(projectDir: string, explicitConfigPath?: string): string | null;
+export declare function loadFactoryConfig(projectDir: string, explicitConfigPath?: string): Promise<FactoryExtendedConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAWvB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqCrB,CAAA;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAM/D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEtC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAM/E;;;;;;;;;;;;GAYG;AACH;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,MAAM,GAAG,IAAI,CAiBf;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA6BhC"}