@amitdeshmukh/ax-crew 8.7.3 → 9.0.0

package/dist/agents/lazyAgent.d.ts

@@ -0,0 +1,33 @@
+import { AxSignature as AxSignatureClass } from "@ax-llm/ax";
+import type { AxFunction } from "@ax-llm/ax";
+import type { AxCrewConfig } from "../types.js";
+/**
+ * Lightweight proxy that stands in for a real agent in the crew's agent map.
+ * It exposes the same `getFunction()` interface (built from the crew config)
+ * but defers the expensive `createAgent()` call — and therefore MCP server
+ * startup — until the Manager actually delegates to it.
+ *
+ * Usage: `crew.addLazyAgent("CreateChart")` instead of `crew.addAgent("CreateChart")`
+ */
+declare class LazyStatefulAxAgent {
+    private realAgent;
+    private crewRef;
+    private agentName;
+    private description;
+    private signatureStr;
+    private func;
+    private _id;
+    constructor(crewRef: any, agentName: string, crewConfig: AxCrewConfig);
+    private resolve;
+    getFunction(): AxFunction;
+    getSignature(): AxSignatureClass<Record<string, any>, Record<string, any>>;
+    getId(): string;
+    setId(id: string): void;
+    getTraces(): any[];
+    setDemos(): void;
+    getUsage(): any[];
+    resetUsage(): void;
+    forward(...args: any[]): Promise<any>;
+    streamingForward(...args: any[]): any;
+}
+export { LazyStatefulAxAgent };

package/dist/agents/lazyAgent.js

@@ -0,0 +1,78 @@
+import { AxSignature as AxSignatureClass } from "@ax-llm/ax";
+import { parseCrewConfig } from "./agentConfig.js";
+/**
+ * Lightweight proxy that stands in for a real agent in the crew's agent map.
+ * It exposes the same `getFunction()` interface (built from the crew config)
+ * but defers the expensive `createAgent()` call — and therefore MCP server
+ * startup — until the Manager actually delegates to it.
+ *
+ * Usage: `crew.addLazyAgent("CreateChart")` instead of `crew.addAgent("CreateChart")`
+ */
+class LazyStatefulAxAgent {
+    realAgent = null;
+    crewRef; // AxCrew — forward-declared to avoid circular ref
+    agentName;
+    description;
+    signatureStr;
+    func;
+    _id = "lazy";
+    constructor(crewRef, agentName, crewConfig) {
+        this.crewRef = crewRef;
+        this.agentName = agentName;
+        const agentDef = parseCrewConfig(crewConfig).crew.find((a) => a.name === agentName);
+        if (!agentDef) {
+            throw new Error(`Agent "${agentName}" not found in crew config`);
+        }
+        this.description = agentDef.description;
+        this.signatureStr = agentDef.signature;
+        // Build the tool schema from the signature's input fields
+        const sig = new AxSignatureClass(this.signatureStr);
+        const parameters = sig.toInputJSONSchema();
+        this.func = {
+            name: agentName.replace(/[^a-zA-Z0-9_]/g, "_").toLowerCase(),
+            description: this.description,
+            parameters,
+            func: async (args) => {
+                const agent = await this.resolve();
+                return agent.forward(args);
+            },
+        };
+    }
+    async resolve() {
+        if (!this.realAgent) {
+            const agent = await this.crewRef.createAgent(this.agentName);
+            agent.setId(this._id);
+            this.realAgent = agent;
+        }
+        return this.realAgent;
+    }
+    // AxAgentic interface
+    getFunction() {
+        return this.func;
+    }
+    getSignature() {
+        return new AxSignatureClass(this.signatureStr);
+    }
+    // AxProgrammable / AxTunable stubs
+    getId() { return this._id; }
+    setId(id) { this._id = id; }
+    getTraces() { return this.realAgent?.getTraces() ?? []; }
+    setDemos() { }
+    getUsage() { return this.realAgent?.getUsage() ?? []; }
+    resetUsage() { this.realAgent?.resetUsage(); }
+    // Forward / streaming — resolve on demand
+    async forward(...args) {
+        const agent = await this.resolve();
+        return agent.forward(...args);
+    }
+    streamingForward(...args) {
+        // Must be sync to match the interface, so we wrap in an async generator
+        const self = this;
+        async function* lazyStream() {
+            const agent = await self.resolve();
+            yield* agent.streamingForward(...args);
+        }
+        return lazyStream();
+    }
+}
+export { LazyStatefulAxAgent };

package/dist/agents/statefulAgent.d.ts

@@ -0,0 +1,93 @@
+import { AxAgent, AxAI } from "@ax-llm/ax";
+import type { AxSignature, AxAgentic, AxFunction, AxProgramForwardOptions, AxProgramStreamingForwardOptions, AxGenStreamingOut } from "@ax-llm/ax";
+import type { StateInstance, UsageCost, MCPTransportConfig, ACEConfig, AgentExecutionMode, AxCrewAxAgentOptions } from "../types.js";
+export interface ParsedAgentConfig {
+    ai: AxAI;
+    name: string;
+    executionMode: AgentExecutionMode;
+    axAgentOptions?: AxCrewAxAgentOptions;
+    description: string;
+    definition?: string;
+    signature: string | AxSignature;
+    functions: (AxFunction | (new (state: Record<string, any>) => {
+        toFunction: () => AxFunction;
+    }) | undefined)[];
+    mcpServers?: Record<string, MCPTransportConfig>;
+    subAgentNames: string[];
+    examples?: Array<Record<string, any>>;
+    tracker?: any;
+}
+declare class StatefulAxAgent extends AxAgent<any, any> {
+    crewState: StateInstance;
+    axai: any;
+    private agentName;
+    private agentDefinition;
+    private executionMode;
+    private axGenProgram;
+    private costTracker?;
+    private debugEnabled;
+    private deferredToolManager?;
+    private static readonly modernAxAgentRuntime;
+    private aceConfig?;
+    private aceOptimizer?;
+    private acePlaybook?;
+    private aceBaseInstruction?;
+    private isAxAIService;
+    constructor(ai: AxAI, options: Readonly<{
+        name: string;
+        description: string;
+        executionMode?: AgentExecutionMode;
+        axAgentOptions?: AxCrewAxAgentOptions;
+        definition?: string;
+        signature: string | AxSignature;
+        agents?: AxAgentic<any, any>[] | undefined;
+        functions?: (AxFunction | (() => AxFunction))[] | undefined;
+        examples?: Array<Record<string, any>> | undefined;
+        mcpServers?: Record<string, MCPTransportConfig> | undefined;
+        debug?: boolean;
+    }>, state: StateInstance);
+    /**
+     * @deprecated Use setExamplesCompat() to avoid Ax runtime version coupling.
+     */
+    setExamples(examples: Readonly<Array<Record<string, any>>>): void;
+    setExamplesCompat(examples: Readonly<Array<Record<string, any>>>): void;
+    /**
+     * @deprecated Use setDescriptionCompat() to avoid Ax runtime version coupling.
+     */
+    setDescription(description: string): void;
+    setDescriptionCompat(description: string): void;
+    getUsage(): (import("@ax-llm/ax").AxModelUsage & {
+        ai: string;
+        model: string;
+    })[];
+    resetUsage(): void;
+    private resolveInvocationArgs;
+    /** Merge deferred tool step hooks into forward options */
+    private mergeStepHooks;
+    private executeForwardByMode;
+    private recordUsageMetrics;
+    private runForwardInvocation;
+    forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    private runStreamingInvocation;
+    streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
+    streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
+    getLastUsageCost(): UsageCost | null;
+    getAccumulatedCosts(): UsageCost | null;
+    getMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetMetrics(): void;
+    initACE(ace?: ACEConfig): Promise<void>;
+    optimizeOffline(params?: {
+        metric?: any;
+        examples?: any[];
+    }): Promise<void>;
+    applyOnlineUpdate(params: {
+        example: any;
+        prediction: any;
+        feedback?: string;
+    }): Promise<void>;
+    getPlaybook(): any | undefined;
+    applyPlaybook(pb: any): void;
+    private composeInstructionWithPlaybook;
+}
+export { StatefulAxAgent };

package/dist/agents/statefulAgent.js

@@ -0,0 +1,473 @@
+import { AxAgent, AxGen } from "@ax-llm/ax";
+import { MetricsRegistry } from "../metrics/index.js";
+// Extend the AxAgent class from ax-llm
+class StatefulAxAgent extends AxAgent {
+    crewState;
+    axai;
+    agentName;
+    agentDefinition;
+    executionMode;
+    axGenProgram;
+    costTracker;
+    debugEnabled = false;
+    deferredToolManager;
+    static modernAxAgentRuntime = typeof AxAgent?.prototype?.getFunction === "function" &&
+        typeof AxAgent?.prototype?.setExamples !== "function";
+    // ACE-related optional state
+    aceConfig;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    aceOptimizer;
+    acePlaybook;
+    aceBaseInstruction; // Original description before playbook injection
+    isAxAIService(obj) {
+        return !!obj && typeof obj.getName === 'function' && typeof obj.chat === 'function';
+    }
+    constructor(ai, options, state) {
+        const { examples, debug } = options;
+        const resolvedFunctions = (options.functions ?? []).map((fn) => typeof fn === "function" ? fn() : fn);
+        const resolvedAgents = (options.agents ?? []);
+        const effectiveDefinition = (options.definition ?? options.description).trim();
+        if (StatefulAxAgent.modernAxAgentRuntime) {
+            const configuredAgentOptions = (options.axAgentOptions ?? {});
+            const configuredAgentGraph = (configuredAgentOptions.agents ?? {});
+            const configuredFunctionGraph = (configuredAgentOptions.functions ?? {});
+            const configuredActorOptions = (configuredAgentOptions.actorOptions ?? {});
+            const configuredResponderOptions = (configuredAgentOptions.responderOptions ?? {});
+            const modernOptions = {
+                ...configuredAgentOptions,
+                debug: debug ?? configuredAgentOptions.debug ?? false,
+                contextFields: Array.isArray(configuredAgentOptions.contextFields)
+                    ? configuredAgentOptions.contextFields
+                    : [],
+            };
+            modernOptions.agents = {
+                ...configuredAgentGraph,
+                local: resolvedAgents,
+            };
+            modernOptions.functions = {
+                ...configuredFunctionGraph,
+                local: resolvedFunctions,
+            };
+            if (effectiveDefinition.length > 0) {
+                modernOptions.actorOptions = {
+                    ...configuredActorOptions,
+                    description: configuredActorOptions.description ?? effectiveDefinition,
+                };
+                modernOptions.responderOptions = {
+                    ...configuredResponderOptions,
+                    description: configuredResponderOptions.description ?? effectiveDefinition,
+                };
+            }
+            else {
+                modernOptions.actorOptions = configuredActorOptions;
+                modernOptions.responderOptions = configuredResponderOptions;
+            }
+            super({
+                ai,
+                agentIdentity: {
+                    name: options.name,
+                    description: options.description,
+                },
+                signature: options.signature,
+            }, modernOptions);
+        }
+        else {
+            super({
+                name: options.name,
+                description: options.description,
+                definition: options.definition,
+                signature: options.signature,
+                agents: resolvedAgents,
+                functions: resolvedFunctions,
+                debug: debug ?? false,
+            }, {});
+        }
+        this.crewState = state;
+        this.axai = ai;
+        this.agentName = options.name;
+        this.agentDefinition = effectiveDefinition;
+        this.executionMode = options.executionMode ?? "axgen";
+        this.debugEnabled = debug ?? false;
+        // Convert sub-agents to callable functions so AxGen can invoke them as tools
+        const subAgentFunctions = resolvedAgents
+            .map(agent => {
+            try {
+                return agent.getFunction();
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter((fn) => fn !== undefined);
+        this.axGenProgram = new AxGen(options.signature, {
+            description: effectiveDefinition,
+            functions: [...resolvedFunctions, ...subAgentFunctions],
+            contextCache: { cacheBreakpoint: 'after-examples' },
+        });
+        for (const agent of resolvedAgents) {
+            try {
+                const childName = agent.getFunction().name;
+                this.axGenProgram.register(agent, childName);
+            }
+            catch {
+                // Best-effort registration for optimizer/introspection support.
+            }
+        }
+        // Apply examples to compatibility layer if provided
+        if (examples && examples.length > 0) {
+            this.setExamplesCompat(examples);
+        }
+    }
+    /**
+     * @deprecated Use setExamplesCompat() to avoid Ax runtime version coupling.
+     */
+    setExamples(examples) {
+        this.setExamplesCompat(examples);
+    }
+    setExamplesCompat(examples) {
+        this.axGenProgram.setExamples(examples);
+        const baseSetExamples = AxAgent.prototype.setExamples;
+        if (typeof baseSetExamples === "function") {
+            baseSetExamples.call(this, examples);
+            return;
+        }
+        const internalProgram = this.program;
+        if (typeof internalProgram?.setExamples === "function") {
+            internalProgram.setExamples(examples);
+        }
+    }
+    /**
+     * @deprecated Use setDescriptionCompat() to avoid Ax runtime version coupling.
+     */
+    setDescription(description) {
+        this.setDescriptionCompat(description);
+    }
+    setDescriptionCompat(description) {
+        this.agentDefinition = description;
+        this.axGenProgram.setDescription(description);
+        const baseSetDescription = AxAgent.prototype.setDescription;
+        if (typeof baseSetDescription === "function") {
+            baseSetDescription.call(this, description);
+            return;
+        }
+        const agentRuntime = this;
+        if (typeof agentRuntime.program?.setDescription === "function") {
+            agentRuntime.program.setDescription(description);
+        }
+        agentRuntime.actorDescription = description;
+        agentRuntime.responderDescription = description;
+        if (typeof agentRuntime._buildSplitPrograms === "function") {
+            agentRuntime._buildSplitPrograms();
+        }
+    }
+    getUsage() {
+        if (this.executionMode === "axgen") {
+            return this.axGenProgram.getUsage();
+        }
+        return super.getUsage();
+    }
+    resetUsage() {
+        this.axGenProgram.resetUsage();
+        super.resetUsage();
+    }
+    resolveInvocationArgs(first, second, third) {
+        const calledWithAI = this.isAxAIService(first);
+        const ai = (calledWithAI ? first : this.axai);
+        if (!ai) {
+            throw new Error(`No AI instance is configured for agent "${this.agentName}"`);
+        }
+        const values = (calledWithAI ? second : first);
+        const options = (calledWithAI ? third : second);
+        return { ai, values, options, calledWithAI };
+    }
+    /** Merge deferred tool step hooks into forward options */
+    mergeStepHooks(options) {
+        if (!this.deferredToolManager?.isActive)
+            return options;
+        const deferredHooks = this.deferredToolManager.getStepHooks();
+        const existingHooks = options?.stepHooks;
+        const mergedHooks = {
+            beforeStep: async (ctx) => {
+                await existingHooks?.beforeStep?.(ctx);
+                await deferredHooks.beforeStep?.(ctx);
+            },
+            afterStep: existingHooks?.afterStep,
+            afterFunctionExecution: async (ctx) => {
+                await existingHooks?.afterFunctionExecution?.(ctx);
+                await deferredHooks.afterFunctionExecution?.(ctx);
+            },
+        };
+        return { ...options, stepHooks: mergedHooks };
+    }
+    async executeForwardByMode(mode, ai, values, options) {
+        const opts = this.mergeStepHooks(options);
+        if (mode === "axgen") {
+            return this.axGenProgram.forward(ai, values, opts);
+        }
+        return super.forward(ai, values, opts);
+    }
+    recordUsageMetrics(labels, mode) {
+        const builtIn = mode === "axgen" ? this.axGenProgram.getUsage?.() : super.getUsage?.();
+        if (!Array.isArray(builtIn))
+            return;
+        const totals = builtIn.reduce((acc, u) => {
+            const pt = u.tokens?.promptTokens ?? u.promptTokens ?? 0;
+            const ct = u.tokens?.completionTokens ?? u.completionTokens ?? 0;
+            acc.promptTokens += typeof pt === "number" ? pt : 0;
+            acc.completionTokens += typeof ct === "number" ? ct : 0;
+            const model = u.model ||
+                this.axai?.getLastUsedChatModel?.() ||
+                this.axai?.defaults?.model;
+            if (model) {
+                acc.byModel[model] = (acc.byModel[model] || 0) + (pt + ct);
+            }
+            return acc;
+        }, { promptTokens: 0, completionTokens: 0, byModel: {} });
+        MetricsRegistry.recordTokens(labels, {
+            promptTokens: totals.promptTokens,
+            completionTokens: totals.completionTokens,
+            totalTokens: totals.promptTokens + totals.completionTokens,
+        });
+        const costTracker = this.costTracker;
+        try {
+            for (const [m, count] of Object.entries(totals.byModel)) {
+                costTracker?.trackTokens?.(count, m);
+            }
+            const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+            if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+                MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+            }
+        }
+        catch { }
+    }
+    async runForwardInvocation(mode, first, second, third) {
+        const { ai, values, options, calledWithAI } = this.resolveInvocationArgs(first, second, third);
+        const start = performance.now();
+        const crewId = this.crewState?.crewId || this.crewState.get?.("crewId") || "default";
+        const labels = { crewId, agent: this.agentName };
+        const taskId = `task_${crewId}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        // Track execution context in crew for ACE feedback routing
+        const crewInstance = this.crewState?.crew;
+        if (crewInstance) {
+            if (calledWithAI) {
+                const parentTaskId = this.crewState?.currentTaskId;
+                if (parentTaskId) {
+                    crewInstance.trackAgentExecution(parentTaskId, this.agentName, values);
+                }
+            }
+            else {
+                crewInstance.trackAgentExecution(taskId, this.agentName, values);
+                this.crewState.currentTaskId = taskId;
+            }
+        }
+        if (this.debugEnabled) {
+            console.log(`[ACE Debug] forward() called, mode=${mode}, aceConfig=${!!this.aceConfig}`);
+        }
+        if (this.aceConfig) {
+            await this.composeInstructionWithPlaybook();
+        }
+        const result = await this.executeForwardByMode(mode, ai, values, options);
+        const durationMs = performance.now() - start;
+        MetricsRegistry.recordRequest(labels, false, durationMs);
+        this.recordUsageMetrics(labels, mode);
+        if (crewInstance) {
+            if (calledWithAI) {
+                const parentTaskId = this.crewState?.currentTaskId;
+                if (parentTaskId) {
+                    crewInstance.recordAgentResult(parentTaskId, this.agentName, result);
+                }
+            }
+            else {
+                crewInstance.recordAgentResult(taskId, this.agentName, result);
+                delete this.crewState.currentTaskId;
+                result._taskId = taskId;
+            }
+        }
+        return result;
+    }
+    // Implementation
+    async forward(first, second, third) {
+        return this.runForwardInvocation(this.executionMode, first, second, third);
+    }
+    runStreamingInvocation(mode, first, second, third) {
+        const { ai, values, options } = this.resolveInvocationArgs(first, second, third);
+        const start = performance.now();
+        const crewId = this.crewState?.crewId || this.crewState.get?.("crewId") || "default";
+        const labels = { crewId, agent: this.agentName };
+        const opts = this.mergeStepHooks(options);
+        const createStream = () => mode === "axgen"
+            ? this.axGenProgram.streamingForward(ai, values, opts)
+            : super.streamingForward(ai, values, opts);
+        const wrappedGenerator = (async function* () {
+            if (this.aceConfig) {
+                await this.composeInstructionWithPlaybook();
+            }
+            const streamingResult = createStream();
+            try {
+                for await (const chunk of streamingResult) {
+                    yield chunk;
+                }
+            }
+            finally {
+                const durationMs = performance.now() - start;
+                MetricsRegistry.recordRequest(labels, true, durationMs);
+                this.recordUsageMetrics(labels, mode);
+            }
+        }).bind(this)();
+        return wrappedGenerator;
+    }
+    // Implementation
+    streamingForward(first, second, third) {
+        return this.runStreamingInvocation(this.executionMode, first, second, third);
+    }
+    // Legacy cost API removed: rely on Ax trackers for cost reporting
+    getLastUsageCost() { return null; }
+    // Get the accumulated costs for all runs of this agent
+    getAccumulatedCosts() { return null; }
+    // Metrics API for this agent
+    getMetrics() {
+        const crewId = this.crewState?.crewId || (this.crewState.get?.('crewId')) || 'default';
+        return MetricsRegistry.snapshot({ crewId, agent: this.agentName });
+    }
+    resetMetrics() {
+        const crewId = this.crewState?.crewId || (this.crewState.get?.('crewId')) || 'default';
+        MetricsRegistry.reset({ crewId, agent: this.agentName });
+    }
+    // =============
+    // ACE API
+    // =============
+    async initACE(ace) {
+        this.aceConfig = ace;
+        if (!ace)
+            return;
+        try {
+            this.aceBaseInstruction =
+                this.agentDefinition || this.getSignature().getDescription() || '';
+            const { buildACEOptimizer, loadInitialPlaybook, createEmptyPlaybook } = await import('./ace.js');
+            this.aceOptimizer = buildACEOptimizer(this.axai, ace);
+            if (!ace.compileOnStart) {
+                this.aceOptimizer.program = this;
+            }
+            const initial = await loadInitialPlaybook(ace.persistence);
+            this.applyPlaybook(initial ?? createEmptyPlaybook());
+            if (this.debugEnabled) {
+                console.log(`[ACE Debug] Initialized for ${this.agentName}, base instruction: ${this.aceBaseInstruction?.slice(0, 50)}...`);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to initialize ACE for agent ${this.agentName}:`, error);
+        }
+    }
+    async optimizeOffline(params) {
+        if (!this.aceConfig || !this.aceOptimizer)
+            return;
+        try {
+            const { runOfflineCompile, resolveMetric } = await import('./ace.js');
+            const registry = this.__functionsRegistry;
+            const metric = params?.metric || resolveMetric(this.aceConfig.metric, registry || {});
+            const examples = params?.examples || [];
+            if (!metric || examples.length === 0) {
+                console.warn(`ACE offline compile skipped for ${this.agentName}: missing metric or examples`);
+                return;
+            }
+            const result = await runOfflineCompile({
+                program: this,
+                optimizer: this.aceOptimizer,
+                metric,
+                examples,
+                persistence: this.aceConfig.persistence
+            });
+            if (result?.artifact?.playbook) {
+                await this.applyPlaybook(result.artifact.playbook);
+            }
+        }
+        catch (error) {
+            console.warn(`ACE offline compile failed for ${this.agentName}:`, error);
+        }
+    }
+    async applyOnlineUpdate(params) {
+        if (!this.aceConfig)
+            return;
+        if (!params.feedback?.trim())
+            return;
+        try {
+            const { persistPlaybook, addFeedbackToPlaybook, createEmptyPlaybook } = await import('./ace.js');
+            let playbook = this.acePlaybook ?? this.aceOptimizer?.playbook;
+            if (!playbook) {
+                playbook = createEmptyPlaybook();
+            }
+            if (this.debugEnabled) {
+                console.log(`[ACE Debug] Adding feedback to playbook: "${params.feedback}"`);
+            }
+            const teacherAI = this.aceOptimizer?.teacherAI;
+            const aiForAnalysis = teacherAI ?? this.axai;
+            await addFeedbackToPlaybook(playbook, params.feedback, aiForAnalysis, this.debugEnabled);
+            this.applyPlaybook(playbook);
+            if (this.aceOptimizer) {
+                this.aceOptimizer.playbook = playbook;
+            }
+            if (this.aceConfig.persistence?.autoPersist) {
+                await persistPlaybook(playbook, this.aceConfig.persistence);
+            }
+            if (this.debugEnabled) {
+                console.log(`[ACE Debug] Playbook updated, sections: ${Object.keys(playbook.sections || {}).join(', ')}`);
+            }
+        }
+        catch (error) {
+            console.warn(`ACE online update failed for ${this.agentName}:`, error);
+        }
+    }
+    getPlaybook() {
+        return this.acePlaybook;
+    }
+    applyPlaybook(pb) {
+        this.acePlaybook = pb;
+        try {
+            this.aceOptimizer.playbook = pb;
+        }
+        catch {
+            // Ignore - optimizer may not be initialized yet
+        }
+    }
+    async composeInstructionWithPlaybook() {
+        const playbook = this.acePlaybook ?? this.aceOptimizer?.playbook;
+        if (this.debugEnabled) {
+            console.log(`[ACE Debug] composeInstructionWithPlaybook called`);
+            console.log(`[ACE Debug] playbook exists: ${!!playbook}, sections: ${playbook ? Object.keys(playbook.sections || {}).length : 0}`);
+            console.log(`[ACE Debug] baseInstruction: "${this.aceBaseInstruction?.slice(0, 50)}..."`);
+        }
+        if (!playbook)
+            return;
+        try {
+            const { renderPlaybook } = await import('./ace.js');
+            const rendered = renderPlaybook(playbook);
+            if (this.debugEnabled) {
+                console.log(`[ACE Debug] rendered playbook (${rendered.length} chars): ${rendered.slice(0, 100)}...`);
+            }
+            if (!rendered)
+                return;
+            const baseInstruction = this.aceBaseInstruction || '';
+            const combinedInstruction = [baseInstruction.trim(), '', rendered]
+                .filter((part) => part.trim().length > 0)
+                .join('\n\n');
+            if (this.debugEnabled) {
+                console.log(`[ACE Debug] combinedInstruction (${combinedInstruction.length} chars)`);
+            }
+            if (combinedInstruction.length >= 20) {
+                const program = this.program;
+                if (program?.setDescription) {
+                    program.setDescription(combinedInstruction);
+                }
+                this.setDescription(combinedInstruction);
+                if (this.debugEnabled) {
+                    console.log(`[ACE Debug] setDescription called successfully`);
+                    console.log(`[ACE Debug] Verifying - signature desc length: ${this.getSignature().getDescription()?.length}`);
+                }
+            }
+        }
+        catch (error) {
+            console.warn('[ACE Debug] Failed to compose instruction:', error);
+        }
+    }
+}
+export { StatefulAxAgent };