@olane/o-lane 0.8.2 → 0.8.4

package/README.md

@@ -76,6 +76,39 @@ console.log(response.result.data);
 // }
 ```
 
+### Response Structure
+
+When calling `use()` on a lane-enabled tool, responses follow the standard O-Network wrapping structure:
+
+```typescript
+// Response from use() follows this structure:
+// {
+//   jsonrpc: "2.0",
+//   id: "request-id",
+//   result: {
+//     success: boolean,    // Whether the operation succeeded
+//     data: any,           // The returned data (on success)
+//     error?: string       // Error details (on failure)
+//   }
+// }
+
+const response = await agent.use(agent.address, {
+  method: 'intent',
+  params: { intent: 'Analyze sales data' }
+});
+
+// Always check response.result.success before accessing data
+if (response.result.success) {
+  const data = response.result.data;
+  console.log('Result:', data.result);
+  console.log('Cycles:', data.cycles);
+} else {
+  console.error('Error:', response.result.error);
+}
+```
+
+> **Important**: Access data via `response.result.data`, not `response.data` directly. The `result` object contains the wrapping fields (`success`, `data`, `error`).
+
 ### Expected Output
 
 After executing an intent, you'll receive:
@@ -338,6 +371,8 @@ import { oCapabilityEvaluate } from '@olane/o-lane';
 
 **When Used**: Agent needs to call a tool (API, database, computation, etc.)
 
+> **Note**: `oCapabilityExecute` is exported directly from `@olane/o-lane` and can be imported alongside other lane primitives.
+
 ```typescript
 import { oCapabilityExecute } from '@olane/o-lane';
 
@@ -696,7 +731,7 @@ Result object returned by capabilities.
 import { oCapabilityResult, oCapabilityType } from '@olane/o-lane';
 
 const result = new oCapabilityResult({
-  type: oCapabilityType.TASK,
+  type: oCapabilityType.EXECUTE,
   result: { data: 'success' },
   config: { /* next capability config */ },
   error: undefined
@@ -733,11 +768,11 @@ enum oLaneStatus {
 
 ```typescript
 enum oCapabilityType {
-  TASK = 'task',
+  TASK = 'task',           // Legacy alias - prefer EXECUTE for new code
   SEARCH = 'search',
   MULTIPLE_STEP = 'multiple_step',
   CONFIGURE = 'configure',
-  EXECUTE = 'execute',
+  EXECUTE = 'execute',     // Primary type for executing tool methods
   HANDSHAKE = 'handshake',
   EVALUATE = 'evaluate',
   STOP = 'stop',
@@ -745,6 +780,8 @@ enum oCapabilityType {
 }
 ```
 
+> **Note on TASK vs EXECUTE**: `TASK` is a legacy capability type that predates `EXECUTE`. For new code, prefer using `oCapabilityType.EXECUTE` which maps to the `oCapabilityExecute` capability class. Both exist in the enum for backward compatibility.
+
 ## Examples
 
 ### Basic Intent Resolution
@@ -1253,9 +1290,9 @@ describe('Lane Execution', () => {
 import { oCapability, oCapabilityResult, oCapabilityType } from '@olane/o-lane';
 
 // Create mock capability for testing
-class MockTaskCapability extends oCapability {
+class MockExecuteCapability extends oCapability {
   get type() {
-    return oCapabilityType.TASK;
+    return oCapabilityType.EXECUTE;
   }
 
   async run(): Promise<oCapabilityResult> {
@@ -1271,7 +1308,7 @@ class MockTaskCapability extends oCapability {
 it('should use mock capabilities', async () => {
   const mockCapabilities = [
     new oCapabilityEvaluate(),
-    new MockTaskCapability()
+    new MockExecuteCapability()
   ];
 
   const lane = await manager.createLane({

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/src/index.d.ts

@@ -7,6 +7,7 @@ export * from './o-lane.tool.js';
 export * from './capabilities/index.js';
 export * from './intent/index.js';
 export * from './capabilities-all/o-capability.all.js';
+export * from './capabilities-execute/execute.capability.js';
 export * from './capabilities-evaluate/o-capability.evaluate.js';
 export * from './capabilities-multiple-step/o-capability.multiple-step.js';
 export * from './capabilities-search/o-capability.search.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wCAAwC,CAAC;AACvD,cAAc,kDAAkD,CAAC;AACjE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wCAAwC,CAAC;AACvD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,kDAAkD,CAAC;AACjE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

package/dist/src/index.js

@@ -7,6 +7,7 @@ export * from './o-lane.tool.js';
 export * from './capabilities/index.js';
 export * from './intent/index.js';
 export * from './capabilities-all/o-capability.all.js';
+export * from './capabilities-execute/execute.capability.js';
 export * from './capabilities-evaluate/o-capability.evaluate.js';
 export * from './capabilities-multiple-step/o-capability.multiple-step.js';
 export * from './capabilities-search/o-capability.search.js';

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.2",
+  "version": "0.8.4",
   "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.2",
+    "@olane/o-test": "0.8.4",
     "@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.2",
-    "@olane/o-core": "0.8.2",
-    "@olane/o-node": "0.8.2",
-    "@olane/o-protocol": "0.8.2",
-    "@olane/o-storage": "0.8.2",
-    "@olane/o-tool": "0.8.2",
+    "@olane/o-config": "0.8.4",
+    "@olane/o-core": "0.8.4",
+    "@olane/o-node": "0.8.4",
+    "@olane/o-protocol": "0.8.4",
+    "@olane/o-storage": "0.8.4",
+    "@olane/o-tool": "0.8.4",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
     "handlebars": "^4.7.8"
   },
-  "gitHead": "9e35c874d849d051bcffe483fd2a8c2b3ecf68cc"
+  "gitHead": "b53623b1ad4365133911722f80d5597a72b65bf2"
 }