@sapiom/agent-core 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @sapiom/orchestration-core
 
+## 0.9.0
+
+### Minor Changes
+
+- d661d57: Emit workflow lifecycle usage analytics from the agent package family via `@sapiom/analytics-core` (source `"agent"`).
+
+  - `@sapiom/agent-core`: `link` / `deploy` / `run` emit one `workflow.link` / `workflow.deploy` / `workflow.run` event each, carrying metadata only — workflow name/id, duration, status, and a machine-readable error code on failure (never inputs, outputs, or error messages). The emitter is constructed lazily at the operation call boundary; `GatewayClient` stays env-free. `runLocal` emits the runtime's step lifecycle events flagged `local: true`.
+  - `@sapiom/agent-runtime`: `AgentRunnerCore` accepts an optional `analytics` sink (new `RuntimeAnalytics` host interface — a structural `track()` method, no new dependency) and emits `step.start` / `step.complete` / `step.error` with step name, attempt, and timing. No sink → no events, byte-for-byte previous behavior.
+
+  Telemetry ships dark: without a collector endpoint configured (`SAPIOM_ANALYTICS_ENDPOINT`) every `track` is a silent no-op — zero network calls, zero disk writes. Opt out any time with `SAPIOM_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`. Emission is synchronous enqueue-only and can never change an operation's behavior, results, or errors — collector outages included.
+
+### Patch Changes
+
+- Updated dependencies [3f25008]
+- Updated dependencies [55462b3]
+- Updated dependencies [d661d57]
+- Updated dependencies [aee376a]
+  - @sapiom/analytics-core@0.2.0
+  - @sapiom/agent-runtime@0.4.0
+  - @sapiom/tools@0.17.0
+  - @sapiom/agent@0.6.2
+
+## 0.8.0
+
+### Minor Changes
+
+- 3dfbd10: Ship the `sapiom-agent-authoring` skill with every scaffold, and finish the MCP
+  instructions rename.
+
+  - New canonical skill (`agent-core/skills/sapiom-agent-authoring/SKILL.md`) with a
+    task-shape trigger ("automate a multi-step / scheduled / deployable task"), the full
+    authoring guide (`defineAgent`, directives, pause/resume, stubs), and a bootstrap
+    step for agents whose client doesn't have the sapiom-dev MCP yet.
+  - Both scaffold templates ship it at `.claude/skills/sapiom-agent-authoring/` (auto-loads
+    as a project skill in Claude Code) and `AGENTS.md` points to it, so every scaffolded
+    project self-documents. A sync test keeps template copies identical to the canonical.
+  - `@sapiom/mcp`'s bundled instructions fallback rewritten to the agents/models
+    vocabulary (the rename left it on the old text), thinned to lifecycle + canonical
+    rules + pointers — deep guidance lives in the skill/AGENTS.md/docs.
+
+### Patch Changes
+
+- 020139a: `check()` now recognizes workflow definitions authored against the pre-rename SDK: `@sapiom/agent` exports `isLegacyOrchestrationDefinition`/`LEGACY_ORCHESTRATION_DEFINITION_BRAND` (the `Symbol.for('sapiom.orchestration.definition')` brand the old `defineOrchestration` attached), and `@sapiom/agent-core`'s `check()` accepts either brand in its export detection — the definition shape is unchanged by the rename, so manifests build identically. `check()` also gains a `typecheck` option (default `true`): pass `typecheck: false` to skip the project's `tsc --noEmit` when only the manifest/graph is needed (esbuild still surfaces bundle-level breakage).
+- Updated dependencies [020139a]
+  - @sapiom/agent@0.6.1
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/cjs/analytics.d.ts

@@ -0,0 +1,4 @@
+import { type SapiomAnalytics } from "@sapiom/analytics-core";
+export declare function getOrchestrationAnalytics(): SapiomAnalytics;
+export declare function resetOrchestrationAnalyticsForTesting(): void;
+export declare function telemetryErrorCode(err: unknown): string;

package/dist/cjs/analytics.js

@@ -0,0 +1,97 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrchestrationAnalytics = getOrchestrationAnalytics;
+exports.resetOrchestrationAnalyticsForTesting = resetOrchestrationAnalyticsForTesting;
+exports.telemetryErrorCode = telemetryErrorCode;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_url_1 = require("node:url");
+const analytics_core_1 = require("@sapiom/analytics-core");
+const errors_js_1 = require("./errors.js");
+function resolveModuleDir() {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    try {
+        const metaUrl = eval("import.meta.url");
+        if (typeof metaUrl === "string")
+            return path.dirname((0, node_url_1.fileURLToPath)(metaUrl));
+    }
+    catch {
+    }
+    return "";
+}
+function readOwnVersion() {
+    try {
+        const moduleDir = resolveModuleDir();
+        for (const levelsUp of ["..", path.join("..", "..")]) {
+            const candidate = path.join(moduleDir, levelsUp, "package.json");
+            if (!fs.existsSync(candidate))
+                continue;
+            const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+            if (parsed.name === "@sapiom/agent-core" &&
+                typeof parsed.version === "string") {
+                return parsed.version;
+            }
+        }
+    }
+    catch {
+    }
+    return "0.0.0";
+}
+let instance = null;
+function getOrchestrationAnalytics() {
+    if (instance === null) {
+        instance = (0, analytics_core_1.createAnalytics)({
+            source: "agent",
+            sdkName: "@sapiom/agent-core",
+            sdkVersion: readOwnVersion(),
+        });
+    }
+    return instance;
+}
+function resetOrchestrationAnalyticsForTesting() {
+    const previous = instance;
+    instance = null;
+    if (previous)
+        void previous.shutdown();
+}
+function telemetryErrorCode(err) {
+    if (err instanceof errors_js_1.AgentOperationError)
+        return err.code;
+    if (err instanceof Error)
+        return err.name;
+    return "UnknownError";
+}

package/dist/cjs/check.d.ts

@@ -1,5 +1,6 @@
 export interface CheckOptions {
     sourceDir: string;
+    typecheck?: boolean;
 }
 export interface CheckResult {
     name: string;

package/dist/cjs/check.js

@@ -76,9 +76,11 @@ async function check(opts) {
         });
     }
     const warnings = [];
-    const typecheckSkip = runTypecheck(sourceDir);
-    if (typecheckSkip)
-        warnings.push(typecheckSkip);
+    if (opts.typecheck !== false) {
+        const typecheckSkip = runTypecheck(sourceDir);
+        if (typecheckSkip)
+            warnings.push(typecheckSkip);
+    }
     const tmp = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sapiom-check-'));
     const bundlePath = node_path_1.default.join(tmp, 'definition.mjs');
     try {
@@ -103,8 +105,9 @@ async function check(opts) {
         const mod = await Promise.resolve(`${`file://${bundlePath}?t=${Date.now()}`}`).then(s => __importStar(require(s)));
         const defs = [];
         for (const value of Object.values(mod)) {
-            if ((0, agent_1.isAgentDefinition)(value) && !defs.includes(value))
+            if (((0, agent_1.isAgentDefinition)(value) || (0, agent_1.isLegacyOrchestrationDefinition)(value)) && !defs.includes(value)) {
                 defs.push(value);
+            }
         }
         if (defs.length === 0) {
             throw new errors_js_1.AgentOperationError({

package/dist/cjs/deploy.js

@@ -7,6 +7,7 @@ exports.deploy = deploy;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
+const analytics_js_1 = require("./analytics.js");
 const bundle_js_1 = require("./bundle.js");
 const errors_js_1 = require("./errors.js");
 const git_js_1 = require("./git.js");
@@ -15,6 +16,31 @@ const POLL_DELAYS_MS = [1000, 2000, 3000, 5000, 5000, 8000, 10000];
 const POLL_BUDGET_MS = 300000;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function deploy(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await deployOperation(opts, client);
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.deploy', {
+            workflow_id: opts.definitionId,
+            branch: opts.branch ?? 'main',
+            build_run_id: result.buildRunId,
+            build_status: result.status,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.deploy', {
+            workflow_id: opts.definitionId,
+            branch: opts.branch ?? 'main',
+            status: 'error',
+            error_code: (0, analytics_js_1.telemetryErrorCode)(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function deployOperation(opts, client) {
     const { projectDir, definitionId, branch = 'main' } = opts;
     (0, git_js_1.assertDeployable)(projectDir);
     const { code, dependencies } = await (0, bundle_js_1.bundleForDeploy)(projectDir);

package/dist/cjs/link.js

@@ -1,8 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.link = link;
+const analytics_js_1 = require("./analytics.js");
 const errors_js_1 = require("./errors.js");
 async function link(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await linkOperation(opts, client);
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.link', {
+            workflow_id: result.definitionId,
+            workflow_name: result.name,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.link', {
+            workflow_name: opts.name,
+            status: 'error',
+            error_code: (0, analytics_js_1.telemetryErrorCode)(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function linkOperation(opts, client) {
     const list = await client.get('/definitions');
     let def = list.find((d) => d.name === opts.name || d.slug === opts.name);
     if (!def) {

package/dist/cjs/local/run-local.js

@@ -9,6 +9,7 @@ exports.runLocalFromDir = runLocalFromDir;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const agent_runtime_1 = require("@sapiom/agent-runtime");
+const analytics_js_1 = require("../analytics.js");
 const errors_js_1 = require("../errors.js");
 const dispatcher_js_1 = require("./dispatcher.js");
 const load_js_1 = require("./load.js");
@@ -39,10 +40,16 @@ async function runLocal(opts) {
     const dispatcher = new dispatcher_js_1.LocalStubDispatcher(opts.definition, stubs);
     const signals = new Map();
     dispatcher.setSignals(signals);
+    const analytics = (0, analytics_js_1.getOrchestrationAnalytics)();
     const core = new agent_runtime_1.AgentRunnerCore({
         store,
         dispatcher,
         observer: agent_runtime_1.NOOP_OBSERVER,
+        analytics: {
+            track(eventType, data) {
+                analytics.track(eventType, { ...data, local: true });
+            },
+        },
     });
     dispatcher.setCore(core);
     dispatcher.setMaxAttempts(max);

package/dist/cjs/run.js

@@ -2,8 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = run;
 exports.parseJsonInput = parseJsonInput;
+const analytics_js_1 = require("./analytics.js");
 const errors_js_1 = require("./errors.js");
 async function run(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await runOperation(opts, client);
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.run', {
+            workflow_id: opts.definitionId,
+            execution_id: result.executionId,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        (0, analytics_js_1.getOrchestrationAnalytics)().track('workflow.run', {
+            workflow_id: opts.definitionId,
+            status: 'error',
+            error_code: (0, analytics_js_1.telemetryErrorCode)(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function runOperation(opts, client) {
     const { definitionId, input = {} } = opts;
     const res = await client.post('/executions', { definitionId, input });
     const executionId = res.executionId ?? res.id;

package/dist/esm/analytics.d.ts

@@ -0,0 +1,4 @@
+import { type SapiomAnalytics } from "@sapiom/analytics-core";
+export declare function getOrchestrationAnalytics(): SapiomAnalytics;
+export declare function resetOrchestrationAnalyticsForTesting(): void;
+export declare function telemetryErrorCode(err: unknown): string;

package/dist/esm/analytics.js

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAnalytics } from "@sapiom/analytics-core";
+import { AgentOperationError } from "./errors.js";
+function resolveModuleDir() {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    try {
+        const metaUrl = eval("import.meta.url");
+        if (typeof metaUrl === "string")
+            return path.dirname(fileURLToPath(metaUrl));
+    }
+    catch {
+    }
+    return "";
+}
+function readOwnVersion() {
+    try {
+        const moduleDir = resolveModuleDir();
+        for (const levelsUp of ["..", path.join("..", "..")]) {
+            const candidate = path.join(moduleDir, levelsUp, "package.json");
+            if (!fs.existsSync(candidate))
+                continue;
+            const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+            if (parsed.name === "@sapiom/agent-core" &&
+                typeof parsed.version === "string") {
+                return parsed.version;
+            }
+        }
+    }
+    catch {
+    }
+    return "0.0.0";
+}
+let instance = null;
+export function getOrchestrationAnalytics() {
+    if (instance === null) {
+        instance = createAnalytics({
+            source: "agent",
+            sdkName: "@sapiom/agent-core",
+            sdkVersion: readOwnVersion(),
+        });
+    }
+    return instance;
+}
+export function resetOrchestrationAnalyticsForTesting() {
+    const previous = instance;
+    instance = null;
+    if (previous)
+        void previous.shutdown();
+}
+export function telemetryErrorCode(err) {
+    if (err instanceof AgentOperationError)
+        return err.code;
+    if (err instanceof Error)
+        return err.name;
+    return "UnknownError";
+}

package/dist/esm/check.d.ts

@@ -1,5 +1,6 @@
 export interface CheckOptions {
     sourceDir: string;
+    typecheck?: boolean;
 }
 export interface CheckResult {
     name: string;

package/dist/esm/check.js

@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { assertValidGraph, buildManifest, isAgentDefinition, agentManifestSchema } from '@sapiom/agent';
+import { assertValidGraph, buildManifest, isAgentDefinition, isLegacyOrchestrationDefinition, agentManifestSchema, } from '@sapiom/agent';
 import * as esbuild from 'esbuild';
 import { AgentOperationError } from './errors.js';
 function runTypecheck(sourceDir) {
@@ -37,9 +37,11 @@ export async function check(opts) {
         });
     }
     const warnings = [];
-    const typecheckSkip = runTypecheck(sourceDir);
-    if (typecheckSkip)
-        warnings.push(typecheckSkip);
+    if (opts.typecheck !== false) {
+        const typecheckSkip = runTypecheck(sourceDir);
+        if (typecheckSkip)
+            warnings.push(typecheckSkip);
+    }
     const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-check-'));
     const bundlePath = path.join(tmp, 'definition.mjs');
     try {
@@ -64,8 +66,9 @@ export async function check(opts) {
         const mod = await import(`file://${bundlePath}?t=${Date.now()}`);
         const defs = [];
         for (const value of Object.values(mod)) {
-            if (isAgentDefinition(value) && !defs.includes(value))
+            if ((isAgentDefinition(value) || isLegacyOrchestrationDefinition(value)) && !defs.includes(value)) {
                 defs.push(value);
+            }
         }
         if (defs.length === 0) {
             throw new AgentOperationError({

package/dist/esm/deploy.js

@@ -1,6 +1,7 @@
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { getOrchestrationAnalytics, telemetryErrorCode } from './analytics.js';
 import { bundleForDeploy } from './bundle.js';
 import { AgentOperationError } from './errors.js';
 import { assertDeployable, pushSynthesizedTree } from './git.js';
@@ -9,6 +10,31 @@ const POLL_DELAYS_MS = [1000, 2000, 3000, 5000, 5000, 8000, 10000];
 const POLL_BUDGET_MS = 300000;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function deploy(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await deployOperation(opts, client);
+        getOrchestrationAnalytics().track('workflow.deploy', {
+            workflow_id: opts.definitionId,
+            branch: opts.branch ?? 'main',
+            build_run_id: result.buildRunId,
+            build_status: result.status,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        getOrchestrationAnalytics().track('workflow.deploy', {
+            workflow_id: opts.definitionId,
+            branch: opts.branch ?? 'main',
+            status: 'error',
+            error_code: telemetryErrorCode(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function deployOperation(opts, client) {
     const { projectDir, definitionId, branch = 'main' } = opts;
     assertDeployable(projectDir);
     const { code, dependencies } = await bundleForDeploy(projectDir);

package/dist/esm/link.js

@@ -1,5 +1,28 @@
+import { getOrchestrationAnalytics, telemetryErrorCode } from './analytics.js';
 import { AgentOperationError } from './errors.js';
 export async function link(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await linkOperation(opts, client);
+        getOrchestrationAnalytics().track('workflow.link', {
+            workflow_id: result.definitionId,
+            workflow_name: result.name,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        getOrchestrationAnalytics().track('workflow.link', {
+            workflow_name: opts.name,
+            status: 'error',
+            error_code: telemetryErrorCode(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function linkOperation(opts, client) {
     const list = await client.get('/definitions');
     let def = list.find((d) => d.name === opts.name || d.slug === opts.name);
     if (!def) {

package/dist/esm/local/run-local.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { DEFAULT_MAX_ATTEMPTS_PER_STEP, InMemoryExecutionStore, NOOP_OBSERVER, AgentRunnerCore, } from "@sapiom/agent-runtime";
+import { getOrchestrationAnalytics } from "../analytics.js";
 import { AgentOperationError } from "../errors.js";
 import { LocalStubDispatcher } from "./dispatcher.js";
 import { loadDefinition } from "./load.js";
@@ -31,10 +32,16 @@ export async function runLocal(opts) {
     const dispatcher = new LocalStubDispatcher(opts.definition, stubs);
     const signals = new Map();
     dispatcher.setSignals(signals);
+    const analytics = getOrchestrationAnalytics();
     const core = new AgentRunnerCore({
         store,
         dispatcher,
         observer: NOOP_OBSERVER,
+        analytics: {
+            track(eventType, data) {
+                analytics.track(eventType, { ...data, local: true });
+            },
+        },
     });
     dispatcher.setCore(core);
     dispatcher.setMaxAttempts(max);

package/dist/esm/run.js

@@ -1,5 +1,28 @@
+import { getOrchestrationAnalytics, telemetryErrorCode } from './analytics.js';
 import { AgentOperationError } from './errors.js';
 export async function run(opts, client) {
+    const startedAt = Date.now();
+    try {
+        const result = await runOperation(opts, client);
+        getOrchestrationAnalytics().track('workflow.run', {
+            workflow_id: opts.definitionId,
+            execution_id: result.executionId,
+            status: 'success',
+            duration_ms: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (err) {
+        getOrchestrationAnalytics().track('workflow.run', {
+            workflow_id: opts.definitionId,
+            status: 'error',
+            error_code: telemetryErrorCode(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        throw err;
+    }
+}
+async function runOperation(opts, client) {
     const { definitionId, input = {} } = opts;
     const res = await client.post('/executions', { definitionId, input });
     const executionId = res.executionId ?? res.id;