@olane/o-lane 0.8.1 → 0.8.3

package/README.md

@@ -14,12 +14,12 @@ The execution layer that manages AI agent processes through capability-based loo
 - 📊 **Execution Tracking** - Complete sequence history with cycle-by-cycle audit trails
 - 🌊 **Streaming Support** - Real-time progress updates to calling agents
 - 💾 **Persistent State** - Content-addressed storage of lane execution history
-- 🎯 **Pre-built Capabilities** - Evaluate, Task, Search, Configure, Error handling included
+- 🎯 **Pre-built Capabilities** - Evaluate and Execute included, with Search, Configure, and Multiple Step planned
 
 ## Installation
 
 ```bash
-npm install @olane/o-lane
+pnpm install @olane/o-lane
 ```
 
 ## Quick Start
@@ -53,7 +53,7 @@ await agent.start();
 
 ```typescript
 // Agent receives an intent and autonomously determines how to execute it
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Analyze the sales data and create a summary report',
@@ -62,15 +62,15 @@ const response = await agent.use({
   }
 });
 
-console.log(response.result);
+console.log(response.result.data);
 // {
 //   result: "Analysis complete. Created summary report with key insights...",
 //   cycles: 5,
 //   sequence: [
 //     { type: 'EVALUATE', reasoning: '...' },
-//     { type: 'TASK', result: '...' },
-//     { type: 'SEARCH', result: '...' },
-//     { type: 'TASK', result: '...' },
+//     { type: 'EXECUTE', result: '...' },
+//     { type: 'EVALUATE', result: '...' },
+//     { type: 'EXECUTE', result: '...' },
 //     { type: 'STOP', result: '...' }
 //   ]
 // }
@@ -256,7 +256,7 @@ The heart of o-lane's emergent orchestration:
 - **Maximum Cycles**: Configurable limit (default: 20) prevents infinite loops
 - **State Accumulation**: Each cycle builds on previous results
 - **Emergent Patterns**: Optimal workflows discovered through execution
-- **Fault Tolerance**: Errors trigger ERROR capability for recovery
+- **Fault Tolerance**: Errors are handled within capability execution
 
 ```typescript
 // The loop runs automatically in lane.execute()
@@ -289,13 +289,13 @@ console.log(lane.sequence);
 //     id: 'cap-1',
 //     type: 'EVALUATE',
 //     config: { intent: '...', context: '...' },
-//     result: { reasoning: 'Need to search for information', next: 'SEARCH' }
+//     result: { reasoning: 'Need to fetch customer data', next: 'EXECUTE' }
 //   },
 //   {
 //     id: 'cap-2',
-//     type: 'SEARCH',
-//     config: { query: 'customer data' },
-//     result: { data: [...], next: 'TASK' }
+//     type: 'EXECUTE',
+//     config: { task: { address: 'o://data', method: 'get_customer' } },
+//     result: { data: [...], next: 'EVALUATE' }
 //   },
 //   // ... more cycles
 // ]
@@ -312,13 +312,15 @@ console.log(lane.agentHistory);
 
 ## Built-in Capabilities
 
-o-lane includes six core capabilities that handle most agentic workflows:
+o-lane includes two active capabilities, with three additional ones planned:
+
+### Active Capabilities
 
 ### 1. Evaluate (`EVALUATE`)
 
 **Purpose**: Analyze the intent and determine the next capability to use.
 
-**When Used**: 
+**When Used**:
 - Start of every lane
 - After completing any other capability
 - When agent needs to reassess approach
@@ -327,18 +329,20 @@ o-lane includes six core capabilities that handle most agentic workflows:
 import { oCapabilityEvaluate } from '@olane/o-lane';
 
 // Automatically uses AI to evaluate intent and choose next step
-// Returns: { type: 'TASK' | 'SEARCH' | 'CONFIGURE' | 'STOP', reasoning: '...' }
+// Returns: { type: 'EXECUTE' | 'STOP', reasoning: '...' }
 ```
 
-### 2. Task (`TASK`)
+### 2. Execute (`EXECUTE`)
 
-**Purpose**: Execute a specific tool method with parameters.
+**Purpose**: Execute a specific tool method with parameters determined by the AI agent.
 
 **When Used**: Agent needs to call a tool (API, database, computation, etc.)
 
 ```typescript
-// Agent decides to execute a task
-// Result: { type: 'TASK', config: { task: { address: 'o://tool', payload: {...} } } }
+import { oCapabilityExecute } from '@olane/o-lane';
+
+// Agent decides to execute a tool call
+// Result: { type: 'EXECUTE', config: { task: { address: 'o://tool', payload: {...} } } }
 
 // Capability executes:
 const response = await this.node.use(new oAddress('o://analytics'), {
@@ -347,7 +351,9 @@ const response = await this.node.use(new oAddress('o://analytics'), {
 });
 ```
 
-### 3. Search (`SEARCH`)
+### Planned Capabilities (not yet active)
+
+### 3. Search (`SEARCH`) *(planned)*
 
 **Purpose**: Query vector stores, registries, or knowledge bases for information.
 
@@ -358,7 +364,7 @@ const response = await this.node.use(new oAddress('o://analytics'), {
 // Can query vector stores, registries, or other search services
 ```
 
-### 4. Configure (`CONFIGURE`)
+### 4. Configure (`CONFIGURE`) *(planned)*
 
 **Purpose**: Set up tool parameters, establish connections, or prepare environment.
 
@@ -369,19 +375,7 @@ const response = await this.node.use(new oAddress('o://analytics'), {
 // Returns configuration result and proceeds to next capability
 ```
 
-### 5. Error (`ERROR`)
-
-**Purpose**: Handle errors gracefully and attempt recovery.
-
-**When Used**: Any capability encounters an error
-
-```typescript
-// Automatically triggered on errors
-// Analyzes error, determines recovery strategy
-// Can retry, use alternative approach, or escalate
-```
-
-### 6. Multiple Step (`MULTIPLE_STEP`)
+### 5. Multiple Step (`MULTIPLE_STEP`) *(planned)*
 
 **Purpose**: Coordinate complex multi-step operations.
 
@@ -398,25 +392,21 @@ const response = await this.node.use(new oAddress('o://analytics'), {
 ```
 Intent: "Analyze Q4 sales and create report"
          ↓
-Cycle 1: EVALUATE → "Need to search for sales data tool"
-         ↓
-Cycle 2: SEARCH → Found 'o://analytics/sales'
+Cycle 1: EVALUATE → "Need to fetch sales data"
          ↓
-Cycle 3: EVALUATE → "Ready to fetch data"
+Cycle 2: EXECUTE → Execute o://analytics/sales/fetch_q4_data
          ↓
-Cycle 4: TASK → Execute o://analytics/sales/fetch_q4_data
+Cycle 3: EVALUATE → "Have data, need to analyze"
          ↓
-Cycle 5: EVALUATE → "Have data, need to analyze"
+Cycle 4: EXECUTE → Execute o://analytics/analyze
          ↓
-Cycle 6: TASK → Execute o://analytics/analyze
+Cycle 5: EVALUATE → "Analysis complete, create report"
          ↓
-Cycle 7: EVALUATE → "Analysis complete, create report"
+Cycle 6: EXECUTE → Execute o://reports/create
          ↓
-Cycle 8: TASK → Execute o://reports/create
+Cycle 7: EVALUATE → "Report created, done"
          ↓
-Cycle 9: EVALUATE → "Report created, done"
-         ↓
-Cycle 10: STOP → Return final result
+Cycle 8: STOP → Return final result
 ```
 
 ## API Reference
@@ -434,12 +424,20 @@ new oLane(config: oLaneConfig)
 **Config Properties:**
 - `intent: oIntent` - The intent to resolve (required)
 - `caller: oAddress` - Address of the calling agent (required)
-- `currentNode: oLaneTool` - The agent tool executing the lane (required)
+- `currentNode: oToolBase` - The tool executing the lane (required)
+- `promptLoader: PromptLoader` - Prompt loader for capability prompts (required)
 - `context?: oLaneContext` - Historical or domain context
+- `chatHistory?: string` - Chat history string for context
 - `streamTo?: oAddress` - Address to stream progress updates
-- `capabilities?: oCapability[]` - Custom capability set
+- `capabilities?: oCapability[]` - Custom capability set (overrides `enabledCapabilityTypes`)
+- `enabledCapabilityTypes?: oCapabilityType[]` - Filter which capability types to enable from `ALL_CAPABILITIES`
+- `extraInstructions?: string` - Additional instructions for the AI agent
 - `maxCycles?: number` - Override default max cycles (20)
 - `parentLaneId?: string` - Parent lane for sub-lanes
+- `persistToConfig?: boolean` - Persist lane for replay on startup
+- `useStream?: boolean` - Enable streaming mode
+- `onChunk?: (chunk: any) => void` - Callback for streaming chunks
+- `requestId?: string | number` - Request ID for request/response correlation
 
 #### Properties
 
@@ -447,9 +445,11 @@ new oLane(config: oLaneConfig)
 - `sequence: oCapabilityResult[]` - Execution history
 - `status: oLaneStatus` - Current lifecycle state
 - `result: oCapabilityResult` - Final execution result
-- `id: string` - Unique lane identifier
+- `id: string` - Unique lane identifier (UUID)
 - `cid?: CID` - Content identifier for storage
 - `agentHistory: string` - Formatted execution history
+- `MAX_CYCLES: number` - Maximum capability loop iterations (default: 20)
+- `onChunk?: (chunk: any) => void` - Streaming chunk callback
 
 #### Methods
 
@@ -471,7 +471,7 @@ Internal capability loop execution (called by execute).
 Add a capability result to the execution sequence.
 
 ```typescript
-lane.addSequence(new oCapabilityResult({ type: 'TASK', result: data }));
+lane.addSequence(new oCapabilityResult({ type: oCapabilityType.EXECUTE, result: data }));
 ```
 
 **`async store(): Promise<void>`**
@@ -492,6 +492,23 @@ const cid = await lane.toCID();
 console.log(cid.toString()); // "bafyreib..."
 ```
 
+**`getExecutionTrace(): string`**
+
+Get a formatted trace of the lane execution for debugging.
+
+```typescript
+const trace = lane.getExecutionTrace();
+console.log(trace);
+```
+
+**`async replay(cid: string): Promise<oCapabilityResult | undefined>`**
+
+Replay a previously stored lane execution from its CID.
+
+```typescript
+const result = await lane.replay('bafyreib...');
+```
+
 **`cancel(): void`**
 
 Cancel lane execution.
@@ -505,7 +522,15 @@ console.log(lane.status); // CANCELLED
 
 ### `oLaneTool` Class
 
-Extends `oNodeTool` with lane execution capabilities.
+Extends `oNodeTool` with lane execution capabilities via the `withLane` mixin pattern:
+
+```typescript
+// oLaneTool is defined as:
+export class oLaneTool extends withLane(oNodeTool) { }
+
+// The withLane mixin can be applied to any tool base class:
+// class MyCustomLaneTool extends withLane(MyBaseClass) { }
+```
 
 #### Built-in Methods
 
@@ -514,7 +539,7 @@ Extends `oNodeTool` with lane execution capabilities.
 Perform capability negotiation with other agents.
 
 ```typescript
-const result = await agent.use({
+const result = await agent.use(agent.address, {
   method: 'handshake',
   params: { intent: 'Discover capabilities' }
 });
@@ -526,7 +551,7 @@ const result = await agent.use({
 Main entry point for intent resolution.
 
 ```typescript
-const result = await agent.use({
+const result = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Your natural language goal here',
@@ -536,6 +561,22 @@ const result = await agent.use({
 });
 ```
 
+**`async _tool_replay(request: oRequest): Promise<any>`**
+
+Replay a stored lane execution from its CID.
+
+```typescript
+const result = await agent.use(agent.address, {
+  method: 'replay',
+  params: { cid: 'bafyreib...' }
+});
+// Returns: { result, error, cycles, cid }
+```
+
+#### Customization
+
+Override `getPromptLoader()` to provide a custom `PromptLoader` for controlling how prompts are loaded for each capability type.
+
 #### Usage Example
 
 ```typescript
@@ -550,7 +591,7 @@ class CustomAgent extends oLaneTool {
   // Add domain-specific tool methods
   async _tool_domain_action(request: oRequest): Promise<any> {
     // Your custom logic
-    return { success: true };
+    return { result: 'done' };
   }
 }
 ```
@@ -619,12 +660,32 @@ const manager = new oLaneManager();
 const lane = await manager.createLane({
   intent: new oIntent({ intent: 'Your goal' }),
   currentNode: agentTool,
-  caller: callerAddress
+  caller: callerAddress,
+  promptLoader: myPromptLoader
 });
 
 // Lane is automatically tracked
 ```
 
+#### Properties
+
+- `lanes: oLane[]` - All tracked lanes
+- `activeLanes: oLane[]` - Currently running lanes
+- `staleLanes: oLane[]` - Lanes that are no longer active
+- `maxLanes: number` - Maximum concurrent lanes (default: 100)
+
+#### Methods
+
+**`async createLane(config: oLaneConfig): Promise<oLane>`** - Create and track a new lane.
+
+**`getLane(id: string): oLane | undefined`** - Retrieve a lane by its ID.
+
+**`cancelLane(lane: oLane): void`** - Cancel a running lane.
+
+**`cleanLanes(): void`** - Remove completed/stale lanes from tracking.
+
+**`async teardown(): Promise<void>`** - Cancel all active lanes and clean up.
+
 ---
 
 ### `oCapabilityResult` Class
@@ -643,10 +704,12 @@ const result = new oCapabilityResult({
 ```
 
 **Properties:**
+- `id: string` - Unique result identifier
 - `type: oCapabilityType` - Next capability to execute
-- `result: any` - Execution result data
-- `config?: any` - Configuration for next capability
+- `result?: any` - Execution result data
+- `config?: oCapabilityConfig` - Configuration for next capability
 - `error?: string` - Error message if failed
+- `shouldPersist?: boolean` - Whether this result should be persisted to storage
 
 ---
 
@@ -670,14 +733,14 @@ enum oLaneStatus {
 
 ```typescript
 enum oCapabilityType {
-  EVALUATE = 'evaluate',
   TASK = 'task',
   SEARCH = 'search',
-  CONFIGURE = 'configure',
-  ERROR = 'error',
   MULTIPLE_STEP = 'multiple_step',
+  CONFIGURE = 'configure',
+  EXECUTE = 'execute',
+  HANDSHAKE = 'handshake',
+  EVALUATE = 'evaluate',
   STOP = 'stop',
-  RESULT = 'result',
   UNKNOWN = 'unknown'
 }
 ```
@@ -699,17 +762,17 @@ const agent = new oLaneTool({
 await agent.start();
 
 // Resolve an intent
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Find the latest sales report and summarize key metrics'
   }
 });
 
-console.log('Result:', response.result);
-console.log('Cycles used:', response.cycles);
-console.log('Execution path:', response.sequence.map(s => s.type));
-// ['EVALUATE', 'SEARCH', 'TASK', 'EVALUATE', 'TASK', 'STOP']
+console.log('Result:', response.result.data);
+console.log('Cycles used:', response.result.data.cycles);
+console.log('Execution path:', response.result.data.sequence.map(s => s.type));
+// ['EVALUATE', 'EXECUTE', 'EVALUATE', 'EXECUTE', 'STOP']
 ```
 
 ### Custom Capability
@@ -741,9 +804,9 @@ class EmailCapability extends oCapability {
       });
     } catch (error) {
       return new oCapabilityResult({
-        type: oCapabilityType.ERROR,
+        type: oCapabilityType.EVALUATE,
         error: error.message,
-        config: { intent: this.intent, originalError: error }
+        config: { intent: this.intent }
       });
     }
   }
@@ -758,10 +821,11 @@ const lane = await manager.createLane({
   intent: new oIntent({ intent: 'Send status update to team' }),
   currentNode: agentTool,
   caller: callerAddress,
+  promptLoader: myPromptLoader,
   capabilities: [
     new oCapabilityEvaluate(),
-    new EmailCapability(),
-    new oCapabilityError()
+    new oCapabilityExecute(),
+    new EmailCapability()
   ]
 });
 
@@ -787,7 +851,7 @@ const receiver = new StreamReceiver({
 await receiver.start();
 
 // Execute intent with streaming
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Process large dataset',
@@ -807,8 +871,10 @@ const response = await agent.use({
 ```typescript
 import { oLaneContext } from '@olane/o-lane';
 
-// Provide conversation history or domain context
-const context = new oLaneContext([
+// Create context and add entries
+const context = new oLaneContext({});
+
+context.addAll([
   '[Previous Conversation]',
   'User: What were our sales last quarter?',
   'Agent: Q3 sales were $1.2M, up 15% from Q2.',
@@ -816,7 +882,10 @@ const context = new oLaneContext([
   '[End Previous Conversation]'
 ]);
 
-const response = await agent.use({
+// Or add individual entries
+context.add('Additional context here');
+
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Calculate Q4 projections',
@@ -831,7 +900,7 @@ const response = await agent.use({
 
 ```typescript
 // Complex intent requiring multiple capabilities
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Analyze customer feedback from last month, identify common themes, and create action items'
@@ -839,8 +908,9 @@ const response = await agent.use({
 });
 
 // Analyze the execution path
+const data = response.result.data;
 console.log('Execution Analysis:');
-response.sequence.forEach((step, index) => {
+data.sequence.forEach((step, index) => {
   console.log(`\nCycle ${index + 1}:`);
   console.log(`  Type: ${step.type}`);
   console.log(`  Reasoning: ${step.reasoning}`);
@@ -850,15 +920,15 @@ response.sequence.forEach((step, index) => {
 });
 
 // Output might show:
-// Cycle 1: EVALUATE - "Need to search for feedback collection tool"
-// Cycle 2: SEARCH - Found o://feedback/collector
-// Cycle 3: TASK - Fetched 145 feedback items
-// Cycle 4: EVALUATE - "Have data, need sentiment analysis"
-// Cycle 5: TASK - Analyzed sentiment across feedback
-// Cycle 6: EVALUATE - "Need to identify themes"
-// Cycle 7: TASK - Extracted 5 common themes
-// Cycle 8: EVALUATE - "Ready to create action items"
-// Cycle 9: TASK - Generated 8 action items
+// Cycle 1: EVALUATE - "Need to fetch feedback data"
+// Cycle 2: EXECUTE - Fetched 145 feedback items from o://feedback/collector
+// Cycle 3: EVALUATE - "Have data, need sentiment analysis"
+// Cycle 4: EXECUTE - Analyzed sentiment across feedback
+// Cycle 5: EVALUATE - "Need to identify themes"
+// Cycle 6: EXECUTE - Extracted 5 common themes
+// Cycle 7: EVALUATE - "Ready to create action items"
+// Cycle 8: EXECUTE - Generated 8 action items
+// Cycle 9: EVALUATE - "All tasks complete"
 // Cycle 10: STOP - Completed successfully
 ```
 
@@ -902,7 +972,7 @@ class DatabaseQueryCapability extends oCapability {
       });
     } catch (error) {
       return new oCapabilityResult({
-        type: oCapabilityType.ERROR,
+        type: oCapabilityType.EVALUATE,
         error: error.message
       });
     }
@@ -920,6 +990,20 @@ class DatabaseQueryCapability extends oCapability {
 - Integration with external systems
 - Performance-critical operations requiring optimization
 
+### Prompt Loading
+
+Lanes require a `PromptLoader` to load prompts for each capability type. The `PromptLoader` abstract class provides a `loadPromptForType(type, params?, provider?)` method. A `PromptLoaderDefault` implementation is included for standard use cases.
+
+To customize prompt loading in your `oLaneTool`, override `getPromptLoader()`:
+
+```typescript
+class MyAgent extends oLaneTool {
+  getPromptLoader(): PromptLoader {
+    return new MyCustomPromptLoader();
+  }
+}
+```
+
 ### Lane Context
 
 Provide rich context to help agents make better decisions:
@@ -928,7 +1012,8 @@ Provide rich context to help agents make better decisions:
 import { oLaneContext } from '@olane/o-lane';
 
 // Conversation context
-const conversationContext = new oLaneContext([
+const conversationContext = new oLaneContext({});
+conversationContext.addAll([
   '[Chat History]',
   'User: Show me last quarter sales',
   'Agent: Q3 sales: $1.2M (↑15%)',
@@ -936,7 +1021,8 @@ const conversationContext = new oLaneContext([
 ]);
 
 // Domain knowledge context
-const domainContext = new oLaneContext([
+const domainContext = new oLaneContext({});
+domainContext.addAll([
   '[Business Rules]',
   '- Sales reports require manager approval',
   '- Sensitive data must be redacted',
@@ -945,12 +1031,13 @@ const domainContext = new oLaneContext([
 ]);
 
 // Combine contexts
-const combinedContext = new oLaneContext([
-  ...conversationContext.contexts,
-  ...domainContext.contexts
+const combinedContext = new oLaneContext({});
+combinedContext.addAll([
+  conversationContext.toString(),
+  domainContext.toString()
 ]);
 
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Generate Q4 sales report',
@@ -1027,7 +1114,7 @@ const tracker = new ProgressTracker({
 await tracker.start();
 
 // Long-running task with progress updates
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: {
     intent: 'Process 10,000 customer records',
@@ -1044,7 +1131,7 @@ Access historical lane executions:
 import { oAddress } from '@olane/o-core';
 
 // Execute and store lane
-const response = await agent.use({
+const response = await agent.use(agent.address, {
   method: 'intent',
   params: { intent: 'Analyze sales data' }
 });
@@ -1059,7 +1146,7 @@ const storedLane = await agent.use(new oAddress('o://lane'), {
   params: { key: cid.toString() }
 });
 
-console.log('Historical execution:', storedLane.result);
+console.log('Historical execution:', storedLane.result.data);
 // {
 //   config: { intent: '...', caller: '...' },
 //   sequence: [...],
@@ -1419,10 +1506,9 @@ import { ALL_CAPABILITIES } from '@olane/o-lane';
 "Do analysis" → "Calculate average sales per region for Q4 2024"
 
 // 2. Provide context
-context: new oLaneContext([
-  'Available data: sales_q4.csv',
-  'Required format: JSON with region, avg_sales fields'
-])
+const ctx = new oLaneContext({});
+ctx.addAll(['Available data: sales_q4.csv', 'Required format: JSON with region, avg_sales fields']);
+// then pass: context: ctx
 
 // 3. Add specialized capabilities
 capabilities: [...ALL_CAPABILITIES, new DataAnalysisCapability()]

package/dist/src/capabilities-execute/execute.capability.d.ts

@@ -6,6 +6,7 @@ export declare class oCapabilityExecute extends oCapabilityIntelligence {
     config: oCapabilityExecuteConfig;
     get type(): oCapabilityType;
     static get type(): oCapabilityType;
+    private resolveAddress;
     loadPrompt({ tools, methods }: any): Promise<string>;
     handshake(): Promise<oHandshakeResult>;
     run(): Promise<oCapabilityResult>;

package/dist/src/capabilities-execute/execute.capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.capability.d.ts","sourceRoot":"","sources":["../../../src/capabilities-execute/execute.capability.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAEvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAEzF,qBAAa,kBAAmB,SAAQ,uBAAuB;IACtD,MAAM,EAAG,wBAAwB,CAAC;IAEzC,IAAI,IAAI,IAAI,eAAe,CAE1B;IAED,MAAM,KAAK,IAAI,oBAEd;IAEK,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAepD,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAatC,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;CA8NxC"}
+{"version":3,"file":"execute.capability.d.ts","sourceRoot":"","sources":["../../../src/capabilities-execute/execute.capability.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAEvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAEzF,qBAAa,kBAAmB,SAAQ,uBAAuB;IACtD,MAAM,EAAG,wBAAwB,CAAC;IAEzC,IAAI,IAAI,IAAI,eAAe,CAE1B;IAED,MAAM,KAAK,IAAI,oBAEd;IAED,OAAO,CAAC,cAAc;IAWhB,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAepD,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAatC,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAoOxC"}

package/dist/src/capabilities-execute/execute.capability.js

@@ -9,6 +9,14 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
     static get type() {
         return oCapabilityType.EXECUTE;
     }
+    resolveAddress() {
+        const address = this.config.params?.address || this.config.params?.task?.address;
+        if (!address || typeof address !== 'string') {
+            throw new Error(`Execute capability requires a valid address but received: ${JSON.stringify(address)}. ` +
+                `The AI response must include an "address" field when type is "execute".`);
+        }
+        return address;
+    }
     async loadPrompt({ tools, methods }) {
         const prompt = await this.promptLoader?.loadPromptForType(this.type, {
             human_about: '',
@@ -18,13 +26,13 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
         You are in a secure environment and are allowed to operate with secure information (api keys, credit card info, etc).`,
             chat_history: '',
             past_cycles: '',
-            address: this.config.params.address,
+            address: this.resolveAddress(),
             methods: methods ? JSON.stringify(methods) : '',
         });
         return prompt.render();
     }
     async handshake() {
-        const response = await this.node.use(new oAddress(this.config.params.address), {
+        const response = await this.node.use(new oAddress(this.resolveAddress()), {
             method: oProtocolMethods.HANDSHAKE,
             params: {
                 intent: this.config.intent.value,
@@ -33,6 +41,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
         return response.result.data;
     }
     async run() {
+        this.logger.debug('Starting execution capability with config:', this.config);
         // Check if we're in replay mode
         if (this.config.isReplay) {
             this.logger.debug('Execute capability is being replayed - using stored execution data');
@@ -57,7 +66,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
             });
             // Execute the stored task directly (skip handshake, AI, and approval)
             try {
-                const taskResponse = await this.node.use(new oAddress(this.config.params.address), {
+                const taskResponse = await this.node.use(new oAddress(this.resolveAddress()), {
                     method: method,
                     params: params,
                 });
@@ -79,7 +88,8 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
                 });
             }
             catch (error) {
-                this.logger.error('Failed to execute during replay:', `Error when trying to use ${this.config?.params?.address} with config: ${JSON.stringify(taskConfig)} resulting in error: ${error?.message}`);
+                const addr = this.config?.params?.address || this.config?.params?.task?.address;
+                this.logger.error('Failed to execute during replay:', `Error when trying to use ${addr} with config: ${JSON.stringify(taskConfig)} resulting in error: ${error?.message}`);
                 return new oCapabilityResult({
                     type: oCapabilityType.EVALUATE,
                     config: this.config,
@@ -87,7 +97,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
                         handshakeResult: handshakeResult,
                         taskConfig: taskConfig,
                     },
-                    error: `Error when trying to use ${this.config?.params?.address} with config: ${JSON.stringify(taskConfig)} resulting in error: ${error?.message}`,
+                    error: `Error when trying to use ${addr} with config: ${JSON.stringify(taskConfig)} resulting in error: ${error?.message}`,
                 });
             }
         }
@@ -116,7 +126,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
             const approvalResponse = await this.node.use(new oAddress('o://approval'), {
                 method: 'request_approval',
                 params: {
-                    toolAddress: this.config.params.address,
+                    toolAddress: this.resolveAddress(),
                     method: method,
                     params: params,
                     intent: this.config.intent,
@@ -142,7 +152,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
         }
         try {
             // Execute the task
-            const taskResponse = await this.node.use(new oAddress(this.config.params.address), {
+            const taskResponse = await this.node.use(new oAddress(this.resolveAddress()), {
                 method: method,
                 params: params,
             });
@@ -164,14 +174,15 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
                         method: method,
                         params: params,
                     },
-                    address: this.config.params.address,
+                    address: this.resolveAddress(),
                     response: taskResponse.result,
                 },
                 shouldPersist,
             });
         }
         catch (error) {
-            this.logger.error('Failed to execute:', `Error when trying to use ${this.config?.params?.address} with config: ${JSON.stringify({
+            const addr = this.config?.params?.address || this.config?.params?.task?.address;
+            this.logger.error('Failed to execute:', `Error when trying to use ${addr} with config: ${JSON.stringify({
                 method: method,
                 params: params,
             })} resulting in error: ${error?.message}`);
@@ -188,7 +199,7 @@ export class oCapabilityExecute extends oCapabilityIntelligence {
                         params: params,
                     },
                 },
-                error: `Error when trying to use ${this.config?.params?.address} with config: ${JSON.stringify({
+                error: `Error when trying to use ${addr} with config: ${JSON.stringify({
                     method: method,
                     params: params,
                 })} resulting in error: ${error?.message}`,

package/dist/src/capabilities-execute/interfaces/o-capability.configure-config.d.ts

@@ -14,6 +14,10 @@ export interface oCapabilityExecuteConfig extends oCapabilityConfig {
             method: string;
             params: any;
         };
+        task?: {
+            address: string;
+            intent?: string;
+        };
     };
 }
 //# sourceMappingURL=o-capability.configure-config.d.ts.map

package/dist/src/capabilities-execute/interfaces/o-capability.configure-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-capability.configure-config.d.ts","sourceRoot":"","sources":["../../../../src/capabilities-execute/interfaces/o-capability.configure-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE;YACf,KAAK,EAAE,MAAM,EAAE,CAAC;YAChB,OAAO,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;aAAE,CAAC;SACrC,CAAC;QACF,UAAU,EAAE;YACV,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,GAAG,CAAC;SACb,CAAC;KACH,CAAC;CACH"}
+{"version":3,"file":"o-capability.configure-config.d.ts","sourceRoot":"","sources":["../../../../src/capabilities-execute/interfaces/o-capability.configure-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE;YACf,KAAK,EAAE,MAAM,EAAE,CAAC;YAChB,OAAO,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;aAAE,CAAC;SACrC,CAAC;QACF,UAAU,EAAE;YACV,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,GAAG,CAAC;SACb,CAAC;QACF,IAAI,CAAC,EAAE;YACL,OAAO,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB,CAAC;KACH,CAAC;CACH"}

package/dist/test/execute-capability-address.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execute-capability-address.spec.d.ts.map

package/dist/test/execute-capability-address.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-capability-address.spec.d.ts","sourceRoot":"","sources":["../../test/execute-capability-address.spec.ts"],"names":[],"mappings":""}

package/dist/test/execute-capability-address.spec.js

@@ -0,0 +1,115 @@
+import { expect } from 'chai';
+import { oCapabilityConfig } from '../src/capabilities/o-capability.config.js';
+import { oCapabilityExecute } from '../src/capabilities-execute/execute.capability.js';
+import { oIntent } from '../src/intent/o-intent.js';
+/**
+ * Tests the interface contract between EVALUATE results and the EXECUTE capability.
+ *
+ * When EVALUATE's AI returns type:"execute", the response may place the address
+ * either at the root level or nested inside a `task` object. resultToConfig()
+ * passes the AI result as `params`, so the execute capability must handle both shapes.
+ */
+describe('EVALUATE → EXECUTE handoff: address resolution', () => {
+    // Minimal stub that satisfies oToolBase enough for oCapabilityConfig
+    const stubNode = {};
+    const stubPromptLoader = {};
+    const intent = new oIntent({ intent: 'test intent' });
+    /**
+     * Simulates what resultToConfig() does: it takes the AI result object
+     * and sets it as `params` on the next capability's config.
+     */
+    function simulateResultToConfig(aiResult) {
+        const obj = aiResult;
+        return oCapabilityConfig.fromJSON({
+            params: typeof obj === 'object' ? obj : {},
+            intent,
+            node: stubNode,
+        });
+    }
+    /**
+     * Creates an oCapabilityExecute instance and sets its config,
+     * then calls the private resolveAddress() via the prototype.
+     */
+    function resolveAddressFrom(config) {
+        const capability = new oCapabilityExecute({
+            promptLoader: stubPromptLoader,
+            node: stubNode,
+        });
+        // Set config as execute() would
+        capability.config = config;
+        // Call private method
+        return capability.resolveAddress();
+    }
+    describe('resolveAddress()', () => {
+        it('should resolve address from params.address (flat AI response)', () => {
+            const aiResult = {
+                type: 'execute',
+                address: 'o://search',
+                summary: 'Searching for something',
+                reasoning: 'User wants to search',
+            };
+            const config = simulateResultToConfig(aiResult);
+            const address = resolveAddressFrom(config);
+            expect(address).to.equal('o://search');
+        });
+        it('should resolve address from params.task.address (nested AI response)', () => {
+            const aiResult = {
+                type: 'execute',
+                task: {
+                    address: 'o://search',
+                    intent: 'Search for card feed refresh functionality',
+                },
+                summary: 'Searching for card feed refresh functionality',
+                reasoning: 'The intent mentions refreshing',
+            };
+            const config = simulateResultToConfig(aiResult);
+            const address = resolveAddressFrom(config);
+            expect(address).to.equal('o://search');
+        });
+        it('should prefer params.address over params.task.address when both exist', () => {
+            const aiResult = {
+                type: 'execute',
+                address: 'o://primary',
+                task: {
+                    address: 'o://fallback',
+                },
+            };
+            const config = simulateResultToConfig(aiResult);
+            const address = resolveAddressFrom(config);
+            expect(address).to.equal('o://primary');
+        });
+        it('should throw when neither address location is present', () => {
+            const aiResult = {
+                type: 'execute',
+                summary: 'Missing address entirely',
+                reasoning: 'Bad AI response',
+            };
+            const config = simulateResultToConfig(aiResult);
+            expect(() => resolveAddressFrom(config)).to.throw('Execute capability requires a valid address');
+        });
+        it('should throw when address is not a string', () => {
+            const aiResult = {
+                type: 'execute',
+                address: 123,
+            };
+            const config = simulateResultToConfig(aiResult);
+            expect(() => resolveAddressFrom(config)).to.throw('Execute capability requires a valid address');
+        });
+    });
+    describe('resultToConfig() params shape', () => {
+        it('should pass AI result object as params', () => {
+            const aiResult = {
+                type: 'execute',
+                address: 'o://search',
+                task: { address: 'o://search', intent: 'find things' },
+                summary: 'test',
+            };
+            const config = simulateResultToConfig(aiResult);
+            expect(config.params).to.deep.equal(aiResult);
+        });
+        it('should set params to empty object for non-object results', () => {
+            const config = simulateResultToConfig('not an object');
+            expect(config.params).to.deep.equal({});
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-lane",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -36,7 +36,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.29.0",
-    "@olane/o-test": "0.8.1",
+    "@olane/o-test": "0.8.3",
     "@tsconfig/node20": "^20.1.6",
     "@types/handlebars": "^4.1.0",
     "@types/jest": "^30.0.0",
@@ -57,15 +57,15 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.8.1",
-    "@olane/o-core": "0.8.1",
-    "@olane/o-node": "0.8.1",
-    "@olane/o-protocol": "0.8.1",
-    "@olane/o-storage": "0.8.1",
-    "@olane/o-tool": "0.8.1",
+    "@olane/o-config": "0.8.3",
+    "@olane/o-core": "0.8.3",
+    "@olane/o-node": "0.8.3",
+    "@olane/o-protocol": "0.8.3",
+    "@olane/o-storage": "0.8.3",
+    "@olane/o-tool": "0.8.3",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
     "handlebars": "^4.7.8"
   },
-  "gitHead": "b84ad7d1c5411d38f3e7ab3c53d336195e7838e9"
+  "gitHead": "189c0cf7b6dd9d5d961f5424af21d37978092d9e"
 }