@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 2.0.0

package/dist/cjs/ai/intents/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module ai/intents
+ * @description Cross-Protocol Intent Resolver — multi-protocol DeFi intent execution.
+ *
+ * Sub-modules:
+ *  - `types`    — Intent, step, plan, and result type definitions
+ *  - `parser`   — Validates and normalizes intent definitions
+ *  - `planner`  — DAG-based execution planning with cycle detection
+ *  - `executor` — Step-by-step execution with reference resolution
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntentParser,
+ *   IntentPlanner,
+ *   IntentExecutor,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * // 1. Parse
+ * const parser = new IntentParser();
+ * const { intent } = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '1000000000' } },
+ *     { id: 'swap',  protocol: 'jupiter', method: 'smartSwap', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '$quote.outAmount' } },
+ *     { id: 'pool',  protocol: 'raydium', method: 'getPoolInfo', params: { poolId: '$swap.poolId' } },
+ *   ],
+ * });
+ *
+ * // 2. Plan
+ * const planner = new IntentPlanner();
+ * const plan = planner.plan(intent);
+ *
+ * // 3. Execute
+ * const executor = new IntentExecutor({
+ *   protocolTools: {
+ *     jupiter: jupiterToolkit.toolMap,
+ *     raydium: raydiumToolkit.toolMap,
+ *   },
+ * });
+ * const result = await executor.execute(plan);
+ * ```
+ *
+ * @since 1.3.0
+ */
+export type { IntentProtocol, StepReference, IntentStep, Intent, IntentOptions, PlannedStep, IntentPlan, StepStatus, StepResult, IntentResultStatus, IntentResult, IntentConfig, } from './types';
+export { IntentError, CyclicDependencyError, UnresolvedReferenceError, BudgetExceededError, } from './types';
+export type { ValidationResult, ParserConfig } from './parser';
+export { IntentParser } from './parser';
+export type { PlannerConfig } from './planner';
+export { IntentPlanner } from './planner';
+export { IntentExecutor } from './executor';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/intents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/intents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/cjs/ai/intents/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * @module ai/intents
+ * @description Cross-Protocol Intent Resolver — multi-protocol DeFi intent execution.
+ *
+ * Sub-modules:
+ *  - `types`    — Intent, step, plan, and result type definitions
+ *  - `parser`   — Validates and normalizes intent definitions
+ *  - `planner`  — DAG-based execution planning with cycle detection
+ *  - `executor` — Step-by-step execution with reference resolution
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntentParser,
+ *   IntentPlanner,
+ *   IntentExecutor,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * // 1. Parse
+ * const parser = new IntentParser();
+ * const { intent } = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '1000000000' } },
+ *     { id: 'swap',  protocol: 'jupiter', method: 'smartSwap', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '$quote.outAmount' } },
+ *     { id: 'pool',  protocol: 'raydium', method: 'getPoolInfo', params: { poolId: '$swap.poolId' } },
+ *   ],
+ * });
+ *
+ * // 2. Plan
+ * const planner = new IntentPlanner();
+ * const plan = planner.plan(intent);
+ *
+ * // 3. Execute
+ * const executor = new IntentExecutor({
+ *   protocolTools: {
+ *     jupiter: jupiterToolkit.toolMap,
+ *     raydium: raydiumToolkit.toolMap,
+ *   },
+ * });
+ * const result = await executor.execute(plan);
+ * ```
+ *
+ * @since 1.3.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntentExecutor = exports.IntentPlanner = exports.IntentParser = exports.BudgetExceededError = exports.UnresolvedReferenceError = exports.CyclicDependencyError = exports.IntentError = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "IntentError", { enumerable: true, get: function () { return types_1.IntentError; } });
+Object.defineProperty(exports, "CyclicDependencyError", { enumerable: true, get: function () { return types_1.CyclicDependencyError; } });
+Object.defineProperty(exports, "UnresolvedReferenceError", { enumerable: true, get: function () { return types_1.UnresolvedReferenceError; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return types_1.BudgetExceededError; } });
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "IntentParser", { enumerable: true, get: function () { return parser_1.IntentParser; } });
+var planner_1 = require("./planner");
+Object.defineProperty(exports, "IntentPlanner", { enumerable: true, get: function () { return planner_1.IntentPlanner; } });
+/* ── Executor ── */
+var executor_1 = require("./executor");
+Object.defineProperty(exports, "IntentExecutor", { enumerable: true, get: function () { return executor_1.IntentExecutor; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/ai/intents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ai/intents/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;;AAkBH,iCAKiB;AAJf,oGAAA,WAAW,OAAA;AACX,8GAAA,qBAAqB,OAAA;AACrB,iHAAA,wBAAwB,OAAA;AACxB,4GAAA,mBAAmB,OAAA;AAKrB,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAIrB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AAEtB,oBAAoB;AACpB,uCAA4C;AAAnC,0GAAA,cAAc,OAAA"}

package/dist/cjs/ai/intents/parser.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module ai/intents/parser
+ * @description Cross-Protocol Intent Parser — validates and normalizes intents.
+ *
+ * Validates intent structure, auto-detects dependencies from `$stepId.field`
+ * references, checks for duplicate IDs, and verifies all referenced steps exist.
+ *
+ * @example
+ * ```ts
+ * import { IntentParser } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const parser = new IntentParser({ maxSteps: 20 });
+ *
+ * const result = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'So11...', outputMint: 'EPjF...' } },
+ *     { id: 'swap', protocol: 'jupiter', method: 'smartSwap', params: { amount: '$quote.outAmount' }, dependsOn: ['quote'] },
+ *   ],
+ * });
+ *
+ * if (result.valid) {
+ *   console.log(result.intent); // Normalized intent with auto-generated ID
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+import type { Intent, IntentStep } from './types';
+/**
+ * @description Result of intent validation.
+ * @since 1.3.0
+ */
+export interface ValidationResult {
+    /** Whether the intent is valid. */
+    valid: boolean;
+    /** Validation errors (empty if valid). */
+    errors: string[];
+    /** Warnings that don't prevent execution. */
+    warnings: string[];
+    /** The normalized intent (only present if valid). */
+    intent?: Intent;
+}
+/**
+ * @description Parser configuration options.
+ * @since 1.3.0
+ */
+export interface ParserConfig {
+    /** Maximum allowed steps. @default 20 */
+    maxSteps?: number;
+    /** Allowed protocols. When set, steps with unknown protocols are rejected. */
+    allowedProtocols?: string[];
+    /** Whether to auto-infer dependencies from `$ref` params. @default true */
+    autoInferDeps?: boolean;
+}
+/**
+ * @description Validates, normalizes, and enriches intent definitions.
+ *
+ * Performs:
+ * 1. Structural validation (required fields, types)
+ * 2. Dependency detection from `$stepId.field` references
+ * 3. Duplicate ID detection
+ * 4. Forward-reference detection (step references future step)
+ * 5. Missing reference detection
+ *
+ * @since 1.3.0
+ */
+export declare class IntentParser {
+    private readonly config;
+    /**
+     * @param {ParserConfig} [config] - Parser configuration
+     */
+    constructor(config?: ParserConfig);
+    /**
+     * @description Parse and validate an intent definition.
+     *
+     * @param {Intent} intent - Raw intent to parse
+     * @returns {ValidationResult} Validation result with normalized intent
+     *
+     * @example
+     * ```ts
+     * const result = parser.parse(myIntent);
+     * if (!result.valid) {
+     *   console.error('Errors:', result.errors);
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    parse(intent: Intent): ValidationResult;
+    /**
+     * @description Extract all step references from an intent step's params.
+     *
+     * @param {IntentStep} step - Step to analyze
+     * @returns {Array<{ param: string; ref: string; stepId: string; fieldPath: string[] }>}
+     *   Array of reference details
+     *
+     * @since 1.3.0
+     */
+    extractReferences(step: IntentStep): Array<{
+        param: string;
+        ref: string;
+        stepId: string;
+        fieldPath: string[];
+    }>;
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/cjs/ai/intents/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/ai/intents/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAiB,MAAM,SAAS,CAAC;AAOjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD;;OAEG;gBACS,MAAM,CAAC,EAAE,YAAY;IAQjC;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAiHvC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;QACzC,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CAiBH"}

package/dist/cjs/ai/intents/parser.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * @module ai/intents/parser
+ * @description Cross-Protocol Intent Parser — validates and normalizes intents.
+ *
+ * Validates intent structure, auto-detects dependencies from `$stepId.field`
+ * references, checks for duplicate IDs, and verifies all referenced steps exist.
+ *
+ * @example
+ * ```ts
+ * import { IntentParser } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const parser = new IntentParser({ maxSteps: 20 });
+ *
+ * const result = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'So11...', outputMint: 'EPjF...' } },
+ *     { id: 'swap', protocol: 'jupiter', method: 'smartSwap', params: { amount: '$quote.outAmount' }, dependsOn: ['quote'] },
+ *   ],
+ * });
+ *
+ * if (result.valid) {
+ *   console.log(result.intent); // Normalized intent with auto-generated ID
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntentParser = void 0;
+const crypto_1 = require("crypto");
+/**
+ * @description Validates, normalizes, and enriches intent definitions.
+ *
+ * Performs:
+ * 1. Structural validation (required fields, types)
+ * 2. Dependency detection from `$stepId.field` references
+ * 3. Duplicate ID detection
+ * 4. Forward-reference detection (step references future step)
+ * 5. Missing reference detection
+ *
+ * @since 1.3.0
+ */
+class IntentParser {
+    config;
+    /**
+     * @param {ParserConfig} [config] - Parser configuration
+     */
+    constructor(config) {
+        this.config = {
+            maxSteps: config?.maxSteps ?? 20,
+            allowedProtocols: config?.allowedProtocols ?? [],
+            autoInferDeps: config?.autoInferDeps ?? true,
+        };
+    }
+    /**
+     * @description Parse and validate an intent definition.
+     *
+     * @param {Intent} intent - Raw intent to parse
+     * @returns {ValidationResult} Validation result with normalized intent
+     *
+     * @example
+     * ```ts
+     * const result = parser.parse(myIntent);
+     * if (!result.valid) {
+     *   console.error('Errors:', result.errors);
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    parse(intent) {
+        const errors = [];
+        const warnings = [];
+        // ── Basic structure ──
+        if (!intent.steps || !Array.isArray(intent.steps)) {
+            return { valid: false, errors: ['Intent must have a "steps" array'], warnings };
+        }
+        if (intent.steps.length === 0) {
+            return { valid: false, errors: ['Intent must have at least one step'], warnings };
+        }
+        if (intent.steps.length > this.config.maxSteps) {
+            errors.push(`Too many steps: ${intent.steps.length} (max: ${this.config.maxSteps})`);
+        }
+        // ── Step validation ──
+        const stepIds = new Set();
+        const stepOrder = new Map(); // stepId → index
+        for (let i = 0; i < intent.steps.length; i++) {
+            const step = intent.steps[i];
+            // Required fields
+            if (!step.id) {
+                errors.push(`Step at index ${i} is missing "id"`);
+                continue;
+            }
+            if (!step.protocol) {
+                errors.push(`Step '${step.id}' is missing "protocol"`);
+            }
+            if (!step.method) {
+                errors.push(`Step '${step.id}' is missing "method"`);
+            }
+            // Duplicate ID
+            if (stepIds.has(step.id)) {
+                errors.push(`Duplicate step ID: '${step.id}'`);
+            }
+            stepIds.add(step.id);
+            stepOrder.set(step.id, i);
+            // Allowed protocols
+            if (this.config.allowedProtocols.length > 0 &&
+                step.protocol &&
+                !this.config.allowedProtocols.includes(step.protocol)) {
+                errors.push(`Step '${step.id}' uses unknown protocol '${step.protocol}'. Allowed: ${this.config.allowedProtocols.join(', ')}`);
+            }
+        }
+        // ── Reference validation & dependency inference ──
+        const normalizedSteps = [];
+        for (const step of intent.steps) {
+            if (!step.id)
+                continue;
+            const inferredDeps = new Set(step.dependsOn ?? []);
+            // Scan params for $references
+            if (step.params && this.config.autoInferDeps) {
+                for (const [key, value] of Object.entries(step.params)) {
+                    if (typeof value === 'string' && value.startsWith('$')) {
+                        const refStepId = value.slice(1).split('.')[0];
+                        // Check reference exists
+                        if (!stepIds.has(refStepId)) {
+                            errors.push(`Step '${step.id}' references unknown step '${refStepId}' in param '${key}'`);
+                        }
+                        // Check for forward references
+                        const refIndex = stepOrder.get(refStepId);
+                        const stepIndex = stepOrder.get(step.id);
+                        if (refIndex !== undefined && stepIndex !== undefined && refIndex >= stepIndex) {
+                            warnings.push(`Step '${step.id}' references step '${refStepId}' which appears later — ensure dependency order is correct`);
+                        }
+                        inferredDeps.add(refStepId);
+                    }
+                }
+            }
+            // Check explicit deps exist
+            for (const dep of step.dependsOn ?? []) {
+                if (!stepIds.has(dep)) {
+                    errors.push(`Step '${step.id}' depends on unknown step '${dep}'`);
+                }
+            }
+            normalizedSteps.push({
+                ...step,
+                dependsOn: [...inferredDeps],
+                params: step.params ?? {},
+            });
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors, warnings };
+        }
+        // ── Return normalized intent ──
+        const normalized = {
+            id: intent.id ?? (0, crypto_1.randomUUID)(),
+            description: intent.description,
+            steps: normalizedSteps,
+            options: intent.options ?? {},
+        };
+        return { valid: true, errors: [], warnings, intent: normalized };
+    }
+    /**
+     * @description Extract all step references from an intent step's params.
+     *
+     * @param {IntentStep} step - Step to analyze
+     * @returns {Array<{ param: string; ref: string; stepId: string; fieldPath: string[] }>}
+     *   Array of reference details
+     *
+     * @since 1.3.0
+     */
+    extractReferences(step) {
+        const refs = [];
+        for (const [key, value] of Object.entries(step.params ?? {})) {
+            if (typeof value === 'string' && value.startsWith('$')) {
+                const parts = value.slice(1).split('.');
+                refs.push({
+                    param: key,
+                    ref: value,
+                    stepId: parts[0],
+                    fieldPath: parts.slice(1),
+                });
+            }
+        }
+        return refs;
+    }
+}
+exports.IntentParser = IntentParser;
+//# sourceMappingURL=parser.js.map

package/dist/cjs/ai/intents/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../../src/ai/intents/parser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH,mCAAoC;AAwCpC;;;;;;;;;;;GAWG;AACH,MAAa,YAAY;IACN,MAAM,CAAyB;IAEhD;;OAEG;IACH,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,EAAE;YAChC,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,IAAI,EAAE;YAChD,aAAa,EAAE,MAAM,EAAE,aAAa,IAAI,IAAI;SAC7C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAc;QAClB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,wBAAwB;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,kCAAkC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAClF,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,oCAAoC,CAAC,EAAE,QAAQ,EAAE,CAAC;QACpF,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,KAAK,CAAC,MAAM,UAAU,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvF,CAAC;QAED,wBAAwB;QACxB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,iBAAiB;QAE9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAE7B,kBAAkB;YAClB,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;gBAClD,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,yBAAyB,CAAC,CAAC;YACzD,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC;YACvD,CAAC;YAED,eAAe;YACf,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBACzB,MAAM,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrB,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAE1B,oBAAoB;YACpB,IACE,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;gBACvC,IAAI,CAAC,QAAQ;gBACb,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EACrD,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,4BAA4B,IAAI,CAAC,QAAQ,eAAe,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjI,CAAC;QACH,CAAC;QAED,oDAAoD;QACpD,MAAM,eAAe,GAAiB,EAAE,CAAC;QAEzC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAAE,SAAS;YAEvB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;YAE3D,8BAA8B;YAC9B,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;wBACvD,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;wBAE/C,yBAAyB;wBACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;4BAC5B,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,8BAA8B,SAAS,eAAe,GAAG,GAAG,CAAC,CAAC;wBAC5F,CAAC;wBAED,+BAA+B;wBAC/B,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;wBAC1C,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;wBACzC,IAAI,QAAQ,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;4BAC/E,QAAQ,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,sBAAsB,SAAS,4DAA4D,CAAC,CAAC;wBAC7H,CAAC;wBAED,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;oBAC9B,CAAC;gBACH,CAAC;YACH,CAAC;YAED,4BAA4B;YAC5B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACtB,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,8BAA8B,GAAG,GAAG,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;YAED,eAAe,CAAC,IAAI,CAAC;gBACnB,GAAG,IAAI;gBACP,SAAS,EAAE,CAAC,GAAG,YAAY,CAAC;gBAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAC5C,CAAC;QAED,iCAAiC;QACjC,MAAM,UAAU,GAAW;YACzB,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,IAAA,mBAAU,GAAE;YAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;SAC9B,CAAC;QAEF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACnE,CAAC;IAED;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAgB;QAMhC,MAAM,IAAI,GAA+E,EAAE,CAAC;QAE5F,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;YAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBACxC,IAAI,CAAC,IAAI,CAAC;oBACR,KAAK,EAAE,GAAG;oBACV,GAAG,EAAE,KAAK;oBACV,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;oBAChB,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA9KD,oCA8KC"}

package/dist/cjs/ai/intents/planner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module ai/intents/planner
+ * @description Cross-Protocol Intent Planner — DAG-based execution planning.
+ *
+ * Converts a validated {@link Intent} into an {@link IntentPlan} by:
+ * 1. Building a directed acyclic graph (DAG) from step dependencies
+ * 2. Detecting cycles
+ * 3. Computing topological sort (execution order)
+ * 4. Identifying parallelizable steps
+ * 5. Estimating costs and latencies
+ *
+ * @example
+ * ```ts
+ * import { IntentPlanner } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const planner = new IntentPlanner();
+ * const plan = planner.plan(parsedIntent);
+ *
+ * console.log(`${plan.totalLevels} execution levels`);
+ * console.log(`Estimated cost: ${plan.estimatedTotalCost}`);
+ *
+ * // View execution order
+ * for (const step of plan.steps) {
+ *   console.log(`[Level ${step.executionOrder}] ${step.id}: ${step.protocol}.${step.method}`);
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+import type { Intent, IntentPlan } from './types';
+/**
+ * @description Configuration for the intent planner.
+ * @since 1.3.0
+ */
+export interface PlannerConfig {
+    /** Custom cost estimates per protocol. */
+    costEstimates?: Record<string, bigint>;
+    /** Custom latency estimates per protocol (ms). */
+    latencyEstimates?: Record<string, number>;
+    /** Maximum DAG depth before rejecting. @default 10 */
+    maxDepth?: number;
+}
+/**
+ * @description Converts validated intents into optimized execution plans.
+ *
+ * The planner performs:
+ * 1. **DAG construction** — edges from each dependency to the dependent step
+ * 2. **Cycle detection** — DFS-based, throws {@link CyclicDependencyError}
+ * 3. **Topological sort** — Kahn's algorithm for deterministic ordering
+ * 4. **Level assignment** — steps at the same level can run in parallel
+ * 5. **Cost estimation** — per-step and total cost/latency estimates
+ *
+ * @since 1.3.0
+ */
+export declare class IntentPlanner {
+    private readonly costEstimates;
+    private readonly latencyEstimates;
+    private readonly maxDepth;
+    /**
+     * @param {PlannerConfig} [config] - Planner configuration
+     */
+    constructor(config?: PlannerConfig);
+    /**
+     * @description Create an execution plan from a validated intent.
+     *
+     * @param {Intent} intent - Validated intent (from {@link IntentParser.parse})
+     * @returns {IntentPlan} Execution plan with topologically sorted steps
+     * @throws {CyclicDependencyError} If the dependency graph contains a cycle
+     * @throws {IntentError} If the DAG exceeds maximum depth
+     *
+     * @example
+     * ```ts
+     * const plan = planner.plan(intent);
+     * if (plan.isValid) {
+     *   for (const step of plan.steps) {
+     *     console.log(`[${step.executionOrder}] ${step.id} (${step.protocol})`);
+     *   }
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    plan(intent: Intent): IntentPlan;
+    /**
+     * @description Optimize a plan by reordering parallelizable steps
+     * to minimize total latency.
+     *
+     * @param {IntentPlan} plan - Plan to optimize
+     * @returns {IntentPlan} Optimized plan (new object, original unchanged)
+     *
+     * @since 1.3.0
+     */
+    optimize(plan: IntentPlan): IntentPlan;
+    private detectCycles;
+}
+//# sourceMappingURL=planner.d.ts.map

package/dist/cjs/ai/intents/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../../../src/ai/intents/planner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAA2B,MAAM,SAAS,CAAC;AAsC3E;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;OAEG;gBACS,MAAM,CAAC,EAAE,aAAa;IAMlC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAgHhC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;IAwBtC,OAAO,CAAC,YAAY;CAuCrB"}