@sapiom/agent-core 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @sapiom/orchestration-core
 
+## 0.9.1
+
+### Patch Changes
+
+- 7fa17d1: Align agent run and schedule requests with the current API endpoints. This also fixes `@sapiom/tools` `schedules` operations (create/list/get/cancel), which were targeting an outdated endpoint. Public function signatures are unchanged.
+- Updated dependencies [7fa17d1]
+  - @sapiom/tools@0.17.1
+
+## 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

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/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/cjs/schedule.js

@@ -7,11 +7,11 @@ exports.cancelSchedule = cancelSchedule;
 exports.previewCron = previewCron;
 async function createSchedule(opts, client) {
     const { definition, ...body } = opts;
-    return client.post(`/${encodeURIComponent(definition)}/triggers`, body);
+    return client.post(`/definitions/${encodeURIComponent(definition)}/triggers`, body);
 }
 async function listSchedules(opts, client) {
     const { definition, ...filters } = opts;
-    return client.get(`/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
+    return client.get(`/definitions/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
 }
 async function getSchedule(id, client) {
     return client.get(`/triggers/${encodeURIComponent(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/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;

package/dist/esm/schedule.js

@@ -1,10 +1,10 @@
 export async function createSchedule(opts, client) {
     const { definition, ...body } = opts;
-    return client.post(`/${encodeURIComponent(definition)}/triggers`, body);
+    return client.post(`/definitions/${encodeURIComponent(definition)}/triggers`, body);
 }
 export async function listSchedules(opts, client) {
     const { definition, ...filters } = opts;
-    return client.get(`/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
+    return client.get(`/definitions/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
 }
 export async function getSchedule(id, client) {
     return client.get(`/triggers/${encodeURIComponent(id)}`);