network-ai 4.11.2 → 4.12.1

package/dist/lib/skill-composer.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Skill Composer — Meta-operations for composing agent execution
+ *
+ * Provides chain(), batch(), loop(), and verify() combinators that orchestrate
+ * multiple agent calls into higher-level workflows. Works with any AdapterRegistry.
+ *
+ * Inspired by Claw-Code's skill composition pattern.
+ *
+ * @module SkillComposer
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillComposer = void 0;
+// ============================================================================
+// SKILL COMPOSER
+// ============================================================================
+/**
+ * Composes agent execution into higher-level workflows.
+ *
+ * @example
+ * ```typescript
+ * const composer = new SkillComposer(registry, { agentId: 'orchestrator' });
+ *
+ * // Sequential chain — output of each step feeds into next
+ * const results = await composer.chain([
+ *   { agentId: 'researcher', payload: { action: 'search', params: { query: 'AI safety' } } },
+ *   { agentId: 'writer', payload: { action: 'draft', params: {} } },
+ *   { agentId: 'reviewer', payload: { action: 'review', params: {} } },
+ * ]);
+ *
+ * // Parallel batch with concurrency limit
+ * const batchResults = await composer.batch(steps, 5);
+ * ```
+ */
+class SkillComposer {
+    registry;
+    baseContext;
+    /**
+     * @param registry The adapter registry to execute agents through
+     * @param baseContext Default execution context (merged with step-level overrides)
+     */
+    constructor(registry, baseContext) {
+        this.registry = registry;
+        this.baseContext = baseContext;
+    }
+    /**
+     * Execute steps sequentially. Each step's result is passed as
+     * `blackboardSnapshot.previousResult` to the next step.
+     *
+     * Stops on first failure unless `continueOnError` is true.
+     */
+    async chain(steps, continueOnError = false) {
+        const start = Date.now();
+        const results = [];
+        let successCount = 0;
+        let failureCount = 0;
+        let previousResult = undefined;
+        for (const step of steps) {
+            const payload = {
+                ...step.payload,
+                blackboardSnapshot: {
+                    ...step.payload.blackboardSnapshot,
+                    previousResult,
+                },
+            };
+            const ctx = { ...this.baseContext, ...step.context };
+            const result = await this.registry.executeAgent(step.agentId, payload, ctx);
+            results.push(result);
+            if (result.success) {
+                successCount++;
+                previousResult = result.data;
+            }
+            else {
+                failureCount++;
+                if (!continueOnError)
+                    break;
+            }
+        }
+        return {
+            success: failureCount === 0,
+            results,
+            totalMs: Date.now() - start,
+            successCount,
+            failureCount,
+        };
+    }
+    /**
+     * Execute steps in parallel with an optional concurrency limit.
+     *
+     * @param steps Steps to execute
+     * @param concurrency Max parallel executions (default: all at once)
+     */
+    async batch(steps, concurrency) {
+        const start = Date.now();
+        const limit = concurrency ?? steps.length;
+        const results = new Array(steps.length);
+        let successCount = 0;
+        let failureCount = 0;
+        // Process in chunks of `limit`
+        for (let i = 0; i < steps.length; i += limit) {
+            const chunk = steps.slice(i, i + limit);
+            const chunkResults = await Promise.all(chunk.map((step, idx) => {
+                const ctx = { ...this.baseContext, ...step.context };
+                return this.registry.executeAgent(step.agentId, step.payload, ctx);
+            }));
+            for (let j = 0; j < chunkResults.length; j++) {
+                results[i + j] = chunkResults[j];
+                if (chunkResults[j].success) {
+                    successCount++;
+                }
+                else {
+                    failureCount++;
+                }
+            }
+        }
+        return {
+            success: failureCount === 0,
+            results,
+            totalMs: Date.now() - start,
+            successCount,
+            failureCount,
+        };
+    }
+    /**
+     * Repeatedly execute a step while `condition` returns true.
+     *
+     * @param step The step to repeat
+     * @param options Loop options (condition + maxIterations)
+     */
+    async loop(step, options) {
+        const start = Date.now();
+        const maxIter = options.maxIterations ?? 10;
+        const results = [];
+        let successCount = 0;
+        let failureCount = 0;
+        for (let i = 0; i < maxIter; i++) {
+            const ctx = {
+                ...this.baseContext,
+                ...step.context,
+                metadata: { ...this.baseContext.metadata, ...step.context?.metadata, iteration: i },
+            };
+            const result = await this.registry.executeAgent(step.agentId, step.payload, ctx);
+            results.push(result);
+            if (result.success) {
+                successCount++;
+            }
+            else {
+                failureCount++;
+            }
+            if (!options.condition(result, i))
+                break;
+        }
+        return {
+            success: failureCount === 0,
+            results,
+            totalMs: Date.now() - start,
+            successCount,
+            failureCount,
+        };
+    }
+    /**
+     * Execute a step and retry until the validator accepts the result or retries are exhausted.
+     *
+     * @param step The step to execute and verify
+     * @param options Verify options (validator + maxRetries)
+     */
+    async verify(step, options) {
+        const maxRetries = options.maxRetries ?? 3;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const ctx = {
+                ...this.baseContext,
+                ...step.context,
+                metadata: { ...this.baseContext.metadata, ...step.context?.metadata, attempt },
+            };
+            const result = await this.registry.executeAgent(step.agentId, step.payload, ctx);
+            if (result.success && options.validator(result)) {
+                return result;
+            }
+            // Last attempt — return whatever we got
+            if (attempt === maxRetries) {
+                return result;
+            }
+        }
+        // Unreachable, but TypeScript needs it
+        return { success: false, error: { code: 'VERIFY_EXHAUSTED', message: 'All retries exhausted', recoverable: false } };
+    }
+}
+exports.SkillComposer = SkillComposer;
+//# sourceMappingURL=skill-composer.js.map

package/dist/lib/skill-composer.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "4.11.2",
+  "version": "4.12.1",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 17 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://network-ai.org",
   "main": "dist/index.js",
@@ -33,6 +33,7 @@
     "test:nemoclaw": "npx ts-node test-nemoclaw.ts",
     "test:cli": "npx ts-node test-cli.ts",
     "test:qa": "npx ts-node test-qa.ts",
+    "test:phase7": "npx ts-node test-phase7.ts",
     "test:all": "npx ts-node run-tests.ts",
     "setup": "npx ts-node setup.ts",
     "setup:check": "npx ts-node setup.ts --check",
@@ -96,7 +97,7 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "dotenv": "^17.3.1",
-    "openai": "^6.31.0",
+    "openai": "^6.33.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },
@@ -105,6 +106,7 @@
     "bin/",
     "types/",
     "scripts/",
+    "socket.json",
     "README.md",
     "QUICKSTART.md",
     "INTEGRATION_GUIDE.md",

package/socket.json

@@ -0,0 +1,181 @@
+{
+  "version": 2,
+  "ignore": {
+    "evalDynamicCodeExecution": [
+      {
+        "path": "lib/blackboard-validator.ts",
+        "reason": "False positive — this pattern is part of dangerous-code detection for untrusted agent content written to the blackboard. It does not execute code."
+      },
+      {
+        "path": "dist/lib/blackboard-validator.js",
+        "reason": "False positive — compiled output of the dangerous-code detector. It matches risky input patterns and does not execute code."
+      }
+    ],
+    "networkAccess": [
+      {
+        "path": "adapters/a2a-adapter.ts",
+        "reason": "Intentional — A2AAdapter implements the Google Agent-to-Agent protocol and sends outbound HTTP requests only to agent endpoints explicitly registered by the user."
+      },
+      {
+        "path": "dist/adapters/a2a-adapter.js",
+        "reason": "Intentional — compiled output of A2AAdapter. It talks only to agent endpoints explicitly registered by the user."
+      },
+      {
+        "path": "adapters/custom-adapter.ts",
+        "reason": "Intentional — CustomAdapter can call a caller-supplied HTTP endpoint as part of its documented bring-your-own-client behavior."
+      },
+      {
+        "path": "dist/adapters/custom-adapter.js",
+        "reason": "Intentional — compiled output of CustomAdapter. It calls a caller-supplied endpoint as part of documented adapter behavior."
+      },
+      {
+        "path": "adapters/aps-adapter.ts",
+        "reason": "Intentional — APSAdapter can verify delegation chains through a configured remote verifier endpoint when that mode is enabled by the caller."
+      },
+      {
+        "path": "dist/adapters/aps-adapter.js",
+        "reason": "Intentional — compiled output of APSAdapter. It talks only to a caller-configured verifier endpoint when that verification mode is enabled."
+      },
+      {
+        "path": "lib/mcp-transport-sse.ts",
+        "reason": "Intentional — McpSseTransport is the HTTP and SSE transport layer for MCP. Serving and connecting over HTTP is its documented role."
+      },
+      {
+        "path": "dist/lib/mcp-transport-sse.js",
+        "reason": "Intentional — compiled output of the MCP HTTP and SSE transport layer."
+      },
+      {
+        "path": "dist/bin/mcp-server.js",
+        "reason": "Intentional — network-ai-server is an opt-in CLI binary that starts an MCP HTTP and SSE server only when the user invokes it explicitly."
+      },
+      {
+        "path": "adapters/codex-adapter.ts",
+        "reason": "Intentional — CodexAdapter sends outbound requests to OpenAI or a caller-provided base URL as part of its documented adapter behavior."
+      },
+      {
+        "path": "dist/adapters/codex-adapter.js",
+        "reason": "Intentional — compiled output of CodexAdapter. It talks to OpenAI or a caller-provided base URL."
+      },
+      {
+        "path": "adapters/minimax-adapter.ts",
+        "reason": "Intentional — MiniMaxAdapter sends outbound requests to MiniMax's API as part of its documented adapter behavior."
+      },
+      {
+        "path": "dist/adapters/minimax-adapter.js",
+        "reason": "Intentional — compiled output of MiniMaxAdapter. It talks to MiniMax endpoints as configured by the caller."
+      }
+    ],
+    "urlStrings": [
+      {
+        "path": "dist/adapters/custom-adapter.js",
+        "reason": "Intentional — CustomAdapter accepts user-supplied endpoint URLs (config.url) as its core function. URLs are provided by the caller at runtime, not hard-coded."
+      },
+      {
+        "path": "dist/adapters/mcp-adapter.js",
+        "reason": "Intentional — MCPAdapter documents example MCP endpoint URL patterns in comments. No runtime URL is hard-coded."
+      },
+      {
+        "path": "dist/bin/mcp-server.js",
+        "reason": "Intentional — mcp-server.js is the MCP server binary; localhost URLs are for the server it starts (e.g. http://localhost:3001/sse) and are documented in help text and comments."
+      },
+      {
+        "path": "adapters/codex-adapter.ts",
+        "reason": "Intentional — CodexAdapter uses https://api.openai.com as default baseUrl for OpenAI API calls. Users can override via config.baseUrl."
+      },
+      {
+        "path": "dist/adapters/codex-adapter.js",
+        "reason": "Intentional — CodexAdapter uses https://api.openai.com as default baseUrl for OpenAI API calls. Users can override via config.baseUrl."
+      },
+      {
+        "path": "adapters/minimax-adapter.ts",
+        "reason": "Intentional — MiniMaxAdapter uses https://api.minimax.io/v1 as default baseUrl for MiniMax API calls. Users can override via config.baseUrl."
+      },
+      {
+        "path": "dist/adapters/minimax-adapter.js",
+        "reason": "Intentional — MiniMaxAdapter uses https://api.minimax.io/v1 as default baseUrl for MiniMax API calls. Users can override via config.baseUrl."
+      }
+    ],
+    "envVars": [
+      {
+        "path": "security.ts",
+        "reason": "Intentional — reads SWARM_TOKEN_SECRET and SWARM_ENCRYPTION_KEY env vars as an opt-in mechanism for users to supply secrets without hard-coding them."
+      },
+      {
+        "path": "dist/security.js",
+        "reason": "Intentional — compiled output of security.ts. Reads SWARM_TOKEN_SECRET and SWARM_ENCRYPTION_KEY env vars."
+      },
+      {
+        "path": "adapters/codex-adapter.ts",
+        "reason": "Intentional — CodexAdapter reads OPENAI_API_KEY env var as a fallback when no API key is provided via config. Declared in skill.json env section."
+      },
+      {
+        "path": "dist/adapters/codex-adapter.js",
+        "reason": "Intentional — compiled output of codex-adapter.ts. Reads OPENAI_API_KEY env var."
+      },
+      {
+        "path": "adapters/minimax-adapter.ts",
+        "reason": "Intentional — MiniMaxAdapter reads MINIMAX_API_KEY env var as a fallback when no API key is provided via config. Declared in skill.json env section."
+      },
+      {
+        "path": "dist/adapters/minimax-adapter.js",
+        "reason": "Intentional — compiled output of minimax-adapter.ts. Reads MINIMAX_API_KEY env var."
+      },
+      {
+        "path": "setup.ts",
+        "reason": "Intentional — setup module checks for OPENAI_API_KEY env var to provide helpful configuration guidance. Declared in skill.json env section."
+      },
+      {
+        "path": "dist/setup.js",
+        "reason": "Intentional — compiled output of setup.ts. Checks for OPENAI_API_KEY env var."
+      }
+    ],
+    "shellExec": [
+      {
+        "path": "adapters/nemoclaw-adapter.ts",
+        "reason": "Intentional — NemoClawAdapter's default executor uses child_process.execFile to invoke the openshell CLI for sandbox management. This is the fallback when no custom executor is provided. Users are expected to bring their own executor in production."
+      },
+      {
+        "path": "dist/adapters/nemoclaw-adapter.js",
+        "reason": "Intentional — compiled output of nemoclaw-adapter.ts. Uses child_process.execFile to invoke the openshell CLI."
+      },
+      {
+        "path": "examples/05-code-review-swarm.ts",
+        "reason": "Intentional — example script uses execSync('npx tsc --noEmit') to demonstrate automated TypeScript type-checking in a code review pipeline. Not part of the core library."
+      },
+      {
+        "path": "examples/demo-runner.ts",
+        "reason": "Intentional — demo runner uses spawn('npx', ['ts-node', file]) to execute example scripts. This is a developer convenience script, not part of the core library."
+      }
+    ],
+    "filesystemAccess": [
+      {
+        "path": "dist/index.js",
+        "reason": "Intentional — the blackboard uses a file-backed store (data/ directory) as its persistence layer. Filesystem access is the explicit purpose of the local-first architecture."
+      },
+      {
+        "path": "dist/run.js",
+        "reason": "Intentional — run.ts bootstraps the local blackboard and reads/writes the data directory. File I/O is the core mechanism."
+      },
+      {
+        "path": "dist/security.js",
+        "reason": "Intentional — security module writes the HMAC-signed audit log to data/audit_log.jsonl. Append-only filesystem writes are the audit trail mechanism."
+      },
+      {
+        "path": "dist/lib/locked-blackboard.js",
+        "reason": "Intentional — LockedBlackboard uses atomic file rename + fsync for its mutex. Filesystem access is the locking primitive."
+      },
+      {
+        "path": "dist/lib/mcp-tools-extended.js",
+        "reason": "Intentional — extended MCP tools expose blackboard snapshot and audit log query over MCP; these read from the data/ directory."
+      },
+      {
+        "path": "dist/lib/mcp-transport-sse.js",
+        "reason": "Intentional — SSE transport reads config from the filesystem. File access is for configuration loading only."
+      },
+      {
+        "path": "dist/lib/swarm-utils.js",
+        "reason": "Intentional — swarm-utils reads/writes the shared blackboard file and audit log. Filesystem I/O is the persistence layer."
+      }
+    ]
+  }
+}

package/types/agent-adapter.d.ts

@@ -227,6 +227,7 @@ export type AdapterEventType =
   | 'adapter:registered'
   | 'adapter:initialized'
   | 'adapter:shutdown'
+  | 'adapter:deferred'
   | 'adapter:error'
   | 'agent:execution:start'
   | 'agent:execution:complete'