@sapiom/agent-core - npm Package Compare versions

Comparing version 0.10.4 to 0.10.5

dist/cjs/bundle-error.d.ts

+export declare function describeBundleFailure(sourceDir: string, err: unknown): string;

dist/cjs/bundle-error.js

+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeBundleFailure = describeBundleFailure;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+function describeBundleFailure(sourceDir, err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const nodeModules = node_path_1.default.join(sourceDir, "node_modules");
+    if (!(0, node_fs_1.existsSync)(nodeModules) && /Could not resolve/.test(raw)) {
+        return (`Dependencies are not installed. Run \`npm install\` in ${sourceDir}, then try again. ` +
+            `(esbuild: ${raw})`);
+    }
+    return raw;
+}

dist/cjs/install-deps.d.ts

+export declare function installProjectDependencies(projectDir: string): Promise<boolean>;

dist/cjs/install-deps.js

+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installProjectDependencies = installProjectDependencies;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const INSTALL_TIMEOUT_MS = 120000;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+async function installProjectDependencies(projectDir) {
+    try {
+        await execFileAsync("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], {
+            cwd: projectDir,
+            shell: process.platform === "win32",
+            timeout: INSTALL_TIMEOUT_MS,
+            maxBuffer: MAX_BUFFER_BYTES,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

dist/esm/bundle-error.d.ts

+export declare function describeBundleFailure(sourceDir: string, err: unknown): string;

dist/esm/bundle-error.js

+import { existsSync } from "node:fs";
+import path from "node:path";
+export function describeBundleFailure(sourceDir, err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const nodeModules = path.join(sourceDir, "node_modules");
+    if (!existsSync(nodeModules) && /Could not resolve/.test(raw)) {
+        return (`Dependencies are not installed. Run \`npm install\` in ${sourceDir}, then try again. ` +
+            `(esbuild: ${raw})`);
+    }
+    return raw;
+}

dist/esm/install-deps.d.ts

+export declare function installProjectDependencies(projectDir: string): Promise<boolean>;

dist/esm/install-deps.js

+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const INSTALL_TIMEOUT_MS = 120000;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+export async function installProjectDependencies(projectDir) {
+    try {
+        await execFileAsync("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], {
+            cwd: projectDir,
+            shell: process.platform === "win32",
+            timeout: INSTALL_TIMEOUT_MS,
+            maxBuffer: MAX_BUFFER_BYTES,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

CHANGELOG.md

 # @sapiom/orchestration-core
 
+## 0.10.5
+
+### Patch Changes
+
+- 19b8bbb: Install a new agent's dependencies on scaffold, and turn the Canvas's "Could not resolve …" render error into an actionable "run npm install" hint
+
+  The Canvas step-graph extraction (`check` / `loadDefinition`) esbuild-bundles a project's `index.ts` resolving its imports — `@sapiom/agent`, `zod`, … — from the project's own `node_modules`. A newly-scaffolded (or freshly-cloned) agent whose deps were never installed therefore failed its very first, unprompted Canvas render with a raw esbuild wall (`Could not resolve "@sapiom/agent" … Could not resolve "zod"`), which the failure panel relayed verbatim.
+
+  Two fixes:
+
+  - `scaffold()` gains an opt-in `installDependencies` flag (returned as `dependenciesInstalled`), and the `sapiom_dev_agents_scaffold` MCP tool — the Studio's create path — now passes it, so a new agent opens with a working Canvas. Best-effort and non-fatal: a missing/offline npm still yields a successful scaffold. The `installProjectDependencies` helper (previously demo-only inside the harness's example seed) now lives in `@sapiom/agent-core` and is shared by both.
+  - `check` and `loadDefinition` now route bundle failures through `describeBundleFailure`, which detects the "no `node_modules` + unresolved import" case and returns `Dependencies are not installed. Run \`npm install\` in <dir>, then try again.` (preserving the raw esbuild detail). Every other bundle failure's message is unchanged.
+
 ## 0.10.4
@@ -4,0 +17,0 @@

dist/cjs/check.js

@@ -49,2 +49,3 @@ "use strict";
 const esbuild = __importStar(require("esbuild"));
+const bundle_error_js_1 = require("./bundle-error.js");
 const errors_js_1 = require("./errors.js");
@@ -117,3 +118,3 @@ function runTypecheck(sourceDir) {
                 message: "Failed to bundle the agent.",
-                hint: err instanceof Error ? err.message : String(err),
+                hint: (0, bundle_error_js_1.describeBundleFailure)(sourceDir, err),
             });
@@ -120,0 +121,0 @@ }

dist/cjs/index.d.ts

@@ -9,2 +9,4 @@ export { AgentOperationError } from "./errors.js";
 export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions, } from "./scaffold.js";
+export { installProjectDependencies } from "./install-deps.js";
+export { describeBundleFailure } from "./bundle-error.js";
 export { check } from "./check.js";
@@ -11,0 +13,0 @@ export type { CheckOptions, CheckResult } from "./check.js";

dist/cjs/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalStubDispatcher = exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.redactCredentials = exports.cloneRepo = exports.pushHead = exports.assertDeployable = exports.previewCron = exports.cancelSchedule = exports.getSchedule = exports.listSchedules = exports.createSchedule = exports.sendFeedback = exports.parseSignalPayload = exports.signal = exports.parseSseEvent = exports.parseSseFrame = exports.watchExecution = exports.isExecutionTerminal = exports.waitForExecution = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.decodeExecutionProjection = exports.SSE_EVENT_TYPES = exports.parseJsonInput = exports.run = exports.deploy = exports.clone = exports.link = exports.bundleForDeploy = exports.check = exports.DEFAULT_TEMPLATE = exports.listTemplates = exports.resolveTemplate = exports.resolveVersions = exports.scaffold = exports.CONFIG_FILE = exports.writeConfig = exports.requireConfig = exports.readConfig = exports.DEFAULT_WORKFLOWS_HOST = exports.createClient = exports.GatewayClient = exports.AgentOperationError = void 0;
+exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.redactCredentials = exports.cloneRepo = exports.pushHead = exports.assertDeployable = exports.previewCron = exports.cancelSchedule = exports.getSchedule = exports.listSchedules = exports.createSchedule = exports.sendFeedback = exports.parseSignalPayload = exports.signal = exports.parseSseEvent = exports.parseSseFrame = exports.watchExecution = exports.isExecutionTerminal = exports.waitForExecution = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.decodeExecutionProjection = exports.SSE_EVENT_TYPES = exports.parseJsonInput = exports.run = exports.deploy = exports.clone = exports.link = exports.bundleForDeploy = exports.check = exports.describeBundleFailure = exports.installProjectDependencies = exports.DEFAULT_TEMPLATE = exports.listTemplates = exports.resolveTemplate = exports.resolveVersions = exports.scaffold = exports.CONFIG_FILE = exports.writeConfig = exports.requireConfig = exports.readConfig = exports.DEFAULT_WORKFLOWS_HOST = exports.createClient = exports.GatewayClient = exports.AgentOperationError = void 0;
+exports.LocalStubDispatcher = void 0;
 var errors_js_1 = require("./errors.js");
@@ -21,2 +22,6 @@ Object.defineProperty(exports, "AgentOperationError", { enumerable: true, get: function () { return errors_js_1.AgentOperationError; } });
 Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return scaffold_js_1.DEFAULT_TEMPLATE; } });
+var install_deps_js_1 = require("./install-deps.js");
+Object.defineProperty(exports, "installProjectDependencies", { enumerable: true, get: function () { return install_deps_js_1.installProjectDependencies; } });
+var bundle_error_js_1 = require("./bundle-error.js");
+Object.defineProperty(exports, "describeBundleFailure", { enumerable: true, get: function () { return bundle_error_js_1.describeBundleFailure; } });
 var check_js_1 = require("./check.js");
@@ -23,0 +28,0 @@ Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_js_1.check; } });

dist/cjs/local/load.d.ts

@@ -1,2 +0,2 @@
-import { type AgentDefinition, type AgentManifest } from '@sapiom/agent';
+import { type AgentDefinition, type AgentManifest } from "@sapiom/agent";
 export interface LoadedDefinition {
@@ -3,0 +3,0 @@ definition: AgentDefinition;

dist/cjs/local/load.js

@@ -46,15 +46,16 @@ "use strict";
 const esbuild = __importStar(require("esbuild"));
+const bundle_error_js_1 = require("../bundle-error.js");
 const errors_js_1 = require("../errors.js");
-const LOCAL_SDK_VERSION = '0.0.0-local';
+const LOCAL_SDK_VERSION = "0.0.0-local";
 async function loadDefinition(sourceDir) {
-    const entryFile = node_path_1.default.join(sourceDir, 'index.ts');
+    const entryFile = node_path_1.default.join(sourceDir, "index.ts");
     if (!(0, node_fs_1.existsSync)(entryFile)) {
         throw new errors_js_1.AgentOperationError({
-            code: 'NO_ENTRY',
+            code: "NO_ENTRY",
             message: `No index.ts found in ${sourceDir}.`,
-            hint: 'Run this from an agent project, or pass its directory.',
+            hint: "Run this from an agent project, or pass its directory.",
         });
     }
-    const tmp = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sapiom-run-'));
-    const bundlePath = node_path_1.default.join(tmp, 'definition.mjs');
+    const tmp = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), "sapiom-run-"));
+    const bundlePath = node_path_1.default.join(tmp, "definition.mjs");
     try {
@@ -66,6 +67,6 @@ try {
                 bundle: true,
-                platform: 'node',
-                target: 'node20',
-                format: 'esm',
-                logLevel: 'silent',
+                platform: "node",
+                target: "node20",
+                format: "esm",
+                logLevel: "silent",
             });
@@ -75,5 +76,5 @@ }
             throw new errors_js_1.AgentOperationError({
-                code: 'BUNDLE_FAILED',
-                message: 'Failed to bundle the agent.',
-                hint: err instanceof Error ? err.message : String(err),
+                code: "BUNDLE_FAILED",
+                message: "Failed to bundle the agent.",
+                hint: (0, bundle_error_js_1.describeBundleFailure)(sourceDir, err),
             });
@@ -85,5 +86,5 @@ }
             throw new errors_js_1.AgentOperationError({
-                code: 'NO_DEFINITION',
-                message: 'No agent was exported from index.ts.',
-                hint: 'Export the result of defineAgent({ … }).',
+                code: "NO_DEFINITION",
+                message: "No agent was exported from index.ts.",
+                hint: "Export the result of defineAgent({ … }).",
             });
@@ -93,10 +94,15 @@ }
             throw new errors_js_1.AgentOperationError({
-                code: 'MULTIPLE_DEFINITIONS',
-                message: 'index.ts exports more than one agent.',
-                hint: 'Export exactly one defineAgent({ … }) result.',
+                code: "MULTIPLE_DEFINITIONS",
+                message: "index.ts exports more than one agent.",
+                hint: "Export exactly one defineAgent({ … }) result.",
             });
         }
         const definition = defs[0];
-        const sha256 = (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(bundlePath)).digest('hex');
-        const manifest = agent_1.agentManifestSchema.parse((0, agent_1.buildManifest)(definition, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        const sha256 = (0, node_crypto_1.createHash)("sha256")
+            .update((0, node_fs_1.readFileSync)(bundlePath))
+            .digest("hex");
+        const manifest = agent_1.agentManifestSchema.parse((0, agent_1.buildManifest)(definition, {
+            sdkVersion: LOCAL_SDK_VERSION,
+            artifact: { sha256, entryFile: "definition.mjs" },
+        }));
         return { definition, manifest };
@@ -103,0 +109,0 @@ }

dist/cjs/scaffold.d.ts

@@ -17,2 +17,3 @@ export declare const DEFAULT_TEMPLATE = "default";
     versions?: ResolvedVersions;
+    installDependencies?: boolean;
 }
@@ -24,3 +25,4 @@ export interface ScaffoldResult {
     gitInitialized: boolean;
+    dependenciesInstalled: boolean;
 }
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

dist/cjs/scaffold.js

@@ -18,2 +18,3 @@ "use strict";
 const errors_js_1 = require("./errors.js");
+const install_deps_js_1 = require("./install-deps.js");
 const version_fallback_generated_js_1 = require("./version-fallback.generated.js");
@@ -201,4 +202,13 @@ function resolveModuleDir() {
     (0, config_js_1.writeConfig)(targetDir, { starterId: template });
+    const dependenciesInstalled = opts.installDependencies
+        ? await (0, install_deps_js_1.installProjectDependencies)(targetDir)
+        : false;
     const gitInitialized = initGitRepo(targetDir);
-    return { targetDir, template, projectName, gitInitialized };
+    return {
+        targetDir,
+        template,
+        projectName,
+        gitInitialized,
+        dependenciesInstalled,
+    };
 }

dist/esm/check.js

@@ -8,2 +8,3 @@ import { execFileSync } from "node:child_process";
 import * as esbuild from "esbuild";
+import { describeBundleFailure } from "./bundle-error.js";
 import { AgentOperationError } from "./errors.js";
@@ -76,3 +77,3 @@ export function runTypecheck(sourceDir) {
                 message: "Failed to bundle the agent.",
-                hint: err instanceof Error ? err.message : String(err),
+                hint: describeBundleFailure(sourceDir, err),
             });
@@ -79,0 +80,0 @@ }

dist/esm/index.d.ts

@@ -9,2 +9,4 @@ export { AgentOperationError } from "./errors.js";
 export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions, } from "./scaffold.js";
+export { installProjectDependencies } from "./install-deps.js";
+export { describeBundleFailure } from "./bundle-error.js";
 export { check } from "./check.js";
@@ -11,0 +13,0 @@ export type { CheckOptions, CheckResult } from "./check.js";

dist/esm/index.js

@@ -5,2 +5,4 @@ export { AgentOperationError } from "./errors.js";
 export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE, } from "./scaffold.js";
+export { installProjectDependencies } from "./install-deps.js";
+export { describeBundleFailure } from "./bundle-error.js";
 export { check } from "./check.js";
@@ -7,0 +9,0 @@ export { bundleForDeploy } from "./bundle.js";

dist/esm/local/load.d.ts

@@ -1,2 +0,2 @@
-import { type AgentDefinition, type AgentManifest } from '@sapiom/agent';
+import { type AgentDefinition, type AgentManifest } from "@sapiom/agent";
 export interface LoadedDefinition {
@@ -3,0 +3,0 @@ definition: AgentDefinition;

dist/esm/local/load.js

@@ -1,20 +0,21 @@
-import { createHash } from 'node:crypto';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import { buildManifest, isAgentDefinition, agentManifestSchema, } from '@sapiom/agent';
-import * as esbuild from 'esbuild';
-import { AgentOperationError } from '../errors.js';
-const LOCAL_SDK_VERSION = '0.0.0-local';
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildManifest, isAgentDefinition, agentManifestSchema, } from "@sapiom/agent";
+import * as esbuild from "esbuild";
+import { describeBundleFailure } from "../bundle-error.js";
+import { AgentOperationError } from "../errors.js";
+const LOCAL_SDK_VERSION = "0.0.0-local";
 export async function loadDefinition(sourceDir) {
-    const entryFile = path.join(sourceDir, 'index.ts');
+    const entryFile = path.join(sourceDir, "index.ts");
     if (!existsSync(entryFile)) {
         throw new AgentOperationError({
-            code: 'NO_ENTRY',
+            code: "NO_ENTRY",
             message: `No index.ts found in ${sourceDir}.`,
-            hint: 'Run this from an agent project, or pass its directory.',
+            hint: "Run this from an agent project, or pass its directory.",
         });
     }
-    const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-run-'));
-    const bundlePath = path.join(tmp, 'definition.mjs');
+    const tmp = mkdtempSync(path.join(tmpdir(), "sapiom-run-"));
+    const bundlePath = path.join(tmp, "definition.mjs");
     try {
@@ -26,6 +27,6 @@ try {
                 bundle: true,
-                platform: 'node',
-                target: 'node20',
-                format: 'esm',
-                logLevel: 'silent',
+                platform: "node",
+                target: "node20",
+                format: "esm",
+                logLevel: "silent",
             });
@@ -35,5 +36,5 @@ }
             throw new AgentOperationError({
-                code: 'BUNDLE_FAILED',
-                message: 'Failed to bundle the agent.',
-                hint: err instanceof Error ? err.message : String(err),
+                code: "BUNDLE_FAILED",
+                message: "Failed to bundle the agent.",
+                hint: describeBundleFailure(sourceDir, err),
             });
@@ -45,5 +46,5 @@ }
             throw new AgentOperationError({
-                code: 'NO_DEFINITION',
-                message: 'No agent was exported from index.ts.',
-                hint: 'Export the result of defineAgent({ … }).',
+                code: "NO_DEFINITION",
+                message: "No agent was exported from index.ts.",
+                hint: "Export the result of defineAgent({ … }).",
             });
@@ -53,10 +54,15 @@ }
             throw new AgentOperationError({
-                code: 'MULTIPLE_DEFINITIONS',
-                message: 'index.ts exports more than one agent.',
-                hint: 'Export exactly one defineAgent({ … }) result.',
+                code: "MULTIPLE_DEFINITIONS",
+                message: "index.ts exports more than one agent.",
+                hint: "Export exactly one defineAgent({ … }) result.",
             });
         }
         const definition = defs[0];
-        const sha256 = createHash('sha256').update(readFileSync(bundlePath)).digest('hex');
-        const manifest = agentManifestSchema.parse(buildManifest(definition, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        const sha256 = createHash("sha256")
+            .update(readFileSync(bundlePath))
+            .digest("hex");
+        const manifest = agentManifestSchema.parse(buildManifest(definition, {
+            sdkVersion: LOCAL_SDK_VERSION,
+            artifact: { sha256, entryFile: "definition.mjs" },
+        }));
         return { definition, manifest };
@@ -63,0 +69,0 @@ }

dist/esm/scaffold.d.ts

@@ -17,2 +17,3 @@ export declare const DEFAULT_TEMPLATE = "default";
     versions?: ResolvedVersions;
+    installDependencies?: boolean;
 }
@@ -24,3 +25,4 @@ export interface ScaffoldResult {
     gitInitialized: boolean;
+    dependenciesInstalled: boolean;
 }
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

dist/esm/scaffold.js

@@ -7,2 +7,3 @@ import { execFileSync } from "node:child_process";
 import { AgentOperationError } from "./errors.js";
+import { installProjectDependencies } from "./install-deps.js";
 import { VERSION_FALLBACK } from "./version-fallback.generated.js";
@@ -190,4 +191,13 @@ function resolveModuleDir() {
     writeConfig(targetDir, { starterId: template });
+    const dependenciesInstalled = opts.installDependencies
+        ? await installProjectDependencies(targetDir)
+        : false;
     const gitInitialized = initGitRepo(targetDir);
-    return { targetDir, template, projectName, gitInitialized };
+    return {
+        targetDir,
+        template,
+        projectName,
+        gitInitialized,
+        dependenciesInstalled,
+    };
 }

package.json

 {
   "name": "@sapiom/agent-core",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Pure, stateless core functions for scaffolding, validating, and operating Sapiom agents — shared by the CLI and MCP packages.",
@@ -40,5 +40,5 @@ "license": "MIT",
     "esbuild": "^0.28.1",
-    "@sapiom/agent": "^0.9.3",
     "@sapiom/agent-runtime": "^0.4.3",
     "@sapiom/analytics-core": "^0.2.1",
+    "@sapiom/agent": "^0.9.3",
     "@sapiom/tools": "^0.26.2"
@@ -45,0 +45,0 @@ },

New alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

505898

1.47%

Number of package files

138

6.15%

Lines of code

5887

2.12%

Worsened metrics

Number of low supply chain risk alerts

31

3.33%

Number of medium supply chain risk alerts

18

12.5%

No dependency changes