@sapiom/tools 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @sapiom/tools
 
+## 0.17.0
+
+### Minor Changes
+
+- aee376a: Emit `capability.call` usage analytics from the capability transport via `@sapiom/analytics-core`.
+
+  Every capability HTTP call now enqueues one `capability.call` event at the transport choke point, carrying the capability path/name (the routed capability id, e.g. `web.scrape`, or the request path), the request URL path (query strings and fragments are stripped, never recorded), HTTP status, duration, request size, and the transport's attribution fields (agent, trace, metadata). Request and response bodies are never captured. The emitted `sdk_version` comes from a build-time constant generated from package.json, so it survives bundling.
+
+  Analytics ships dark: unless a collector endpoint is configured the emitter is a silent no-op — zero network calls, zero disk writes. Events are enqueued synchronously and delivered in background batches, so nothing is ever awaited, thrown, or slowed on the call path; capability behavior is byte-identical with telemetry on, off, or the collector unreachable. Opt out any time with `SAPIOM_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`.
+
+  Adds `Sapiom.shutdown(): Promise<void>` (additive): flushes buffered events and detaches the emitter's process exit hook. Call it once per client in hosts that construct many clients per process (e.g. an engine worker creating a per-execution client) so exit hooks don't accumulate; it's idempotent, never rejects, resolves immediately when there's nothing to release, and covers clients derived via `withAttribution` (the stub client implements it as an immediate resolve).
+
+### Patch Changes
+
+- Updated dependencies [3f25008]
+- Updated dependencies [55462b3]
+  - @sapiom/analytics-core@0.2.0
+
+## 0.16.0
+
+### Minor Changes
+
+- cc1261e: Rename the composition SDK to **agents** and the coding/LLM capability to **models**.
+
+  **Breaking — the package names changed. Install the new names; the old ones are deprecated.**
+
+  - Packages: `@sapiom/orchestration` → `@sapiom/agent`, `@sapiom/orchestration-core` → `@sapiom/agent-core`, `@sapiom/orchestration-runtime` → `@sapiom/agent-runtime`. (`@sapiom/create-orchestration` is retired — scaffold with the CLI or the developer MCP.)
+  - API: `defineOrchestration` → `defineAgent`; `Orchestration*` types/errors → `Agent*`.
+  - `@sapiom/tools`: the `agent` capability namespace is now `models` (e.g. `sapiom.models.coding`); the `orchestrations` namespace is now `agents`.
+  - CLI: `sapiom orchestrations …` → `sapiom agents …`.
+  - Developer MCP tools: `sapiom_dev_orchestrations_*` → `sapiom_dev_agents_*`.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
 
 // Create a repo, have a coding agent build into it, then publish.
 const repo = await sapiom.repositories.create("landing-page");
-const run = await sapiom.agent.coding.run({
+const run = await sapiom.models.coding.run({
   task: "Build a one-page marketing site in index.html.",
   gitRepository: repo, // cloned into the run's sandbox at /workspace/landing-page
 });
@@ -105,6 +105,28 @@ const { downloadUrl } = await fileStorage.getDownloadUrl(
 );
 ```
 
+## Usage analytics
+
+The SDK can emit anonymous usage analytics — one `capability.call` event per
+capability request, carrying the capability name, the request URL path (query
+strings are stripped, never recorded), HTTP status, duration, and request size
+(never request or response bodies). Events describe calls to Sapiom's own API
+only; nothing is captured about any third-party traffic.
+
+By default nothing is sent anywhere: the emitter (see
+[`@sapiom/analytics-core`](https://github.com/sapiom/sapiom-js/tree/main/packages/analytics-core))
+is a no-op unless a collector endpoint is configured. Delivery is batched in the background and can
+never throw, block, or slow a capability call. Opt out any time with
+`SAPIOM_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`.
+
+If your process constructs many clients over its lifetime (one per execution,
+for example), call `await client.shutdown()` when you're done with each one: it
+flushes any buffered events and detaches the emitter's process exit hook.
+It's idempotent, never rejects, resolves immediately when there's nothing to
+release, and covers every client derived via `withAttribution`. One-shot
+scripts don't need it — events flush on process exit. Capability calls made
+after shutdown still work; they just no longer emit analytics.
+
 ## License
 
 MIT

package/dist/cjs/_client/analytics.d.ts

@@ -0,0 +1,66 @@
+import { type SapiomAnalytics } from "@sapiom/analytics-core";
+import type { Attribution } from "./index.js";
+/** The one event this package emits: one per capability HTTP call. Dot-form is canonical. */
+export declare const CAPABILITY_CALL_EVENT = "capability.call";
+/**
+ * Lazily-created emitter shared by a Transport and every transport derived
+ * from it via `withAttribution` — one emitter (one batch queue, one exit
+ * hook) per client, no matter how many attributed views are derived.
+ */
+export interface AnalyticsHolder {
+    instance?: SapiomAnalytics;
+}
+/** Get (creating on first use) the holder's emitter. Never throws — `createAnalytics` can't. */
+export declare function analyticsFor(holder: AnalyticsHolder, apiKey: string | undefined): SapiomAnalytics;
+/** Everything the Transport knows about one finished (or failed) capability HTTP call. */
+export interface CapabilityCallInfo {
+    url: string;
+    /** `RequestInit.method`; absent means GET (fetch semantics). */
+    method: string | undefined;
+    /** `RequestInit.body` — only its SIZE is recorded, never its content. */
+    requestBody: unknown;
+    durationMs: number;
+    /** HTTP status; absent when the fetch itself threw (network-level failure). */
+    status?: number;
+    ok: boolean;
+    /** The thrown value when the fetch failed before producing a response. */
+    error?: unknown;
+    /** The transport's attribution — execution context, recorded as-is. */
+    attribution: Attribution;
+}
+/**
+ * Build the `capability.call` event `data`. All requests are Sapiom-bound, so
+ * request metadata (method, sizes, attribution) is captured; per-field size
+ * caps are enforced downstream by the emitter (~16 KB). The recorded `url` is
+ * the request URL PATH only — query strings and fragments are stripped, so a
+ * caller putting a secret in a query parameter can never leak it into an
+ * event. Request/response BODIES are never captured — only the request body size.
+ */
+export declare function capabilityCallData(info: CapabilityCallInfo): Record<string, unknown>;
+/**
+ * Derive the capability name from the request URL:
+ * - a routed call (`POST <core>/v1/capabilities/<id>`) → the capability id
+ *   (`web.scrape`, `email.verify`, …);
+ * - anything else (service-gateway capabilities) → the URL path, which is the
+ *   stable per-operation identifier on those hosts (`/v1/sandboxes`, …);
+ * - an unparseable URL → the raw string (capped downstream).
+ */
+export declare function capabilityFromUrl(url: string): string;
+/**
+ * The request URL with query string and fragment stripped (origin + pathname),
+ * consistent with {@link capabilityFromUrl}. Query parameters are deliberately
+ * never recorded: today's capabilities carry no secrets there, but a future or
+ * direct `transport.fetch(urlWithSecretQuery)` must not silently exfiltrate one.
+ */
+export declare function urlWithoutQuery(url: string): string;
+/**
+ * This package's own version. Primary source is the build-time constant
+ * generated from package.json (`src/_generated/version.ts`, regenerated by
+ * `gen:version` on every build/test/typecheck) — a constant survives bundlers,
+ * which inline it where no package.json exists on disk near the bundled
+ * module. The runtime package.json walk-up remains only as a fallback for the
+ * (should-be-impossible) case of an empty constant, and degrades to
+ * `"unknown"` rather than ever throwing.
+ */
+export declare function resolveSdkVersion(): string;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/cjs/_client/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/_client/analytics.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,6FAA6F;AAC7F,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,gGAAgG;AAChG,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,eAAe,CASjB;AAMD,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,yEAAyE;IACzE,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,kBAAkB,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASrD;AAUD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQnD;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C"}

package/dist/cjs/_client/analytics.js

@@ -0,0 +1,283 @@
+"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.CAPABILITY_CALL_EVENT = void 0;
+exports.analyticsFor = analyticsFor;
+exports.capabilityCallData = capabilityCallData;
+exports.capabilityFromUrl = capabilityFromUrl;
+exports.urlWithoutQuery = urlWithoutQuery;
+exports.resolveSdkVersion = resolveSdkVersion;
+/**
+ * Usage analytics for `@sapiom/tools` — the Transport (this package's single
+ * HTTP choke point) enqueues ONE `capability.call` event per capability HTTP
+ * call through `@sapiom/analytics-core`.
+ *
+ * Non-negotiables, guaranteed regardless of configuration:
+ * - Live by default: the emitter delivers to the hosted Sapiom collector unless
+ *   opted out. Opt out with `SAPIOM_TELEMETRY_DISABLED=1`, `DO_NOT_TRACK=1`,
+ *   or `disabled: true` in the config — any of these makes the emitter a
+ *   complete no-op (zero network calls, zero disk writes, no notice).
+ *   `SAPIOM_ANALYTICS_ENDPOINT` overrides the destination (useful in tests).
+ * - Enqueue-only on the call path: `track()` is synchronous, delivery is
+ *   batched off the call path, and no failure here can surface to a caller.
+ */
+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 version_js_1 = require("../_generated/version.js");
+/** The one event this package emits: one per capability HTTP call. Dot-form is canonical. */
+exports.CAPABILITY_CALL_EVENT = "capability.call";
+/** Get (creating on first use) the holder's emitter. Never throws — `createAnalytics` can't. */
+function analyticsFor(holder, apiKey) {
+    return (holder.instance ?? (holder.instance = (0, analytics_core_1.createAnalytics)({
+        source: "tools",
+        sdkName: "@sapiom/tools",
+        sdkVersion: resolveSdkVersion(),
+        // Sent as `x-sapiom-api-key` on collector batches so the server can
+        // enrich events with the tenant — never placed in event payloads.
+        apiKey,
+    })));
+}
+/**
+ * Build the `capability.call` event `data`. All requests are Sapiom-bound, so
+ * request metadata (method, sizes, attribution) is captured; per-field size
+ * caps are enforced downstream by the emitter (~16 KB). The recorded `url` is
+ * the request URL PATH only — query strings and fragments are stripped, so a
+ * caller putting a secret in a query parameter can never leak it into an
+ * event. Request/response BODIES are never captured — only the request body size.
+ */
+function capabilityCallData(info) {
+    const data = {
+        capability: capabilityFromUrl(info.url),
+        method: (info.method ?? "GET").toUpperCase(),
+        url: urlWithoutQuery(info.url),
+        ok: info.ok,
+        duration_ms: info.durationMs,
+    };
+    if (info.status !== undefined)
+        data.status = info.status;
+    const requestBytes = bodySize(info.requestBody);
+    if (requestBytes !== undefined)
+        data.request_bytes = requestBytes;
+    if (info.error !== undefined) {
+        data.error = errorLabel(info.error);
+        const message = errorMessage(info.error);
+        if (message !== undefined)
+            data.error_message = message;
+    }
+    const a = info.attribution;
+    if (a.agentId)
+        data.agent_id = a.agentId;
+    if (a.agentName)
+        data.agent_name = a.agentName;
+    if (a.traceId)
+        data.trace_id = a.traceId;
+    if (a.traceExternalId)
+        data.trace_external_id = a.traceExternalId;
+    if (a.metadata)
+        data.attribution_metadata = a.metadata;
+    return data;
+}
+/** Matches the routed-capability seam's path shape: `/v1/capabilities/<id>`. */
+const ROUTED_CAPABILITY_PATH = /^\/v1\/capabilities\/([^/]+)\/?$/;
+/**
+ * Derive the capability name from the request URL:
+ * - a routed call (`POST <core>/v1/capabilities/<id>`) → the capability id
+ *   (`web.scrape`, `email.verify`, …);
+ * - anything else (service-gateway capabilities) → the URL path, which is the
+ *   stable per-operation identifier on those hosts (`/v1/sandboxes`, …);
+ * - an unparseable URL → the raw string (capped downstream).
+ */
+function capabilityFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const routed = ROUTED_CAPABILITY_PATH.exec(parsed.pathname);
+        if (routed)
+            return safeDecode(routed[1]);
+        return parsed.pathname || url;
+    }
+    catch {
+        return url;
+    }
+}
+function safeDecode(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/**
+ * The request URL with query string and fragment stripped (origin + pathname),
+ * consistent with {@link capabilityFromUrl}. Query parameters are deliberately
+ * never recorded: today's capabilities carry no secrets there, but a future or
+ * direct `transport.fetch(urlWithSecretQuery)` must not silently exfiltrate one.
+ */
+function urlWithoutQuery(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        // Unparseable — strip conservatively at the first `?` or `#`.
+        return url.split(/[?#]/)[0] ?? url;
+    }
+}
+/** Size in bytes of a request body when cheaply knowable (string / Blob / buffer views). */
+function bodySize(body) {
+    try {
+        if (typeof body === "string")
+            return Buffer.byteLength(body);
+        if (body !== null && typeof body === "object") {
+            const { size, byteLength } = body;
+            if (typeof size === "number")
+                return size;
+            if (typeof byteLength === "number")
+                return byteLength;
+        }
+    }
+    catch {
+        // Analytics never throws; an unknown body simply has no recorded size.
+    }
+    return undefined;
+}
+function errorLabel(error) {
+    if (error instanceof Error)
+        return error.name || "Error";
+    return typeof error;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : undefined;
+}
+// ---------------------------------------------------------------------------
+// SDK version
+// ---------------------------------------------------------------------------
+let cachedSdkVersion = null;
+/**
+ * This package's own version. Primary source is the build-time constant
+ * generated from package.json (`src/_generated/version.ts`, regenerated by
+ * `gen:version` on every build/test/typecheck) — a constant survives bundlers,
+ * which inline it where no package.json exists on disk near the bundled
+ * module. The runtime package.json walk-up remains only as a fallback for the
+ * (should-be-impossible) case of an empty constant, and degrades to
+ * `"unknown"` rather than ever throwing.
+ */
+function resolveSdkVersion() {
+    return (cachedSdkVersion ?? (cachedSdkVersion = typeof version_js_1.VERSION === "string" && version_js_1.VERSION.length > 0
+        ? version_js_1.VERSION
+        : readOwnPackageVersion()));
+}
+function readOwnPackageVersion() {
+    try {
+        let dir = resolveModuleDir();
+        for (let hops = 0; dir !== ""; hops++) {
+            if (hops >= 8)
+                break;
+            const version = versionIfOwnPackage(path.join(dir, "package.json"));
+            if (version !== undefined)
+                return version;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // Version resolution must never break a capability call.
+    }
+    return "unknown";
+}
+/** The `version` of the manifest at `manifestPath` iff it is this package's own. */
+function versionIfOwnPackage(manifestPath) {
+    try {
+        const raw = fs.readFileSync(manifestPath, "utf8");
+        const manifest = JSON.parse(raw);
+        if (manifest.name === "@sapiom/tools" &&
+            typeof manifest.version === "string") {
+            return manifest.version;
+        }
+    }
+    catch {
+        // Missing or unparseable manifest at this level — keep walking up.
+    }
+    return undefined;
+}
+/**
+ * Directory of this compiled module, resolved for BOTH build formats:
+ *   - CommonJS build (and ts-jest) → `__dirname` (a real global);
+ *   - ESM build → recovered from a stack trace, where V8 reports this module
+ *     as a `file://` URL.
+ *
+ * The stack route is used because a literal `import.meta` is a hard compile
+ * error (TS1343) in this single source file's CommonJS compilation, and
+ * `eval("import.meta.url")` throws at runtime — eval'd code is parsed as a
+ * script, where `import.meta` is invalid. A stack frame is the one anchor
+ * available to both formats; any failure degrades to `"unknown"`, never throws.
+ */
+function resolveModuleDir() {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    try {
+        const file = ownFileFromStack();
+        if (file !== undefined) {
+            return path.dirname(file.startsWith("file:") ? (0, node_url_1.fileURLToPath)(file) : file);
+        }
+    }
+    catch {
+        // No usable anchor — version resolution degrades to "unknown".
+    }
+    return "";
+}
+/**
+ * This module's own file (path or `file://` URL), read from the top-most
+ * user frame of a fresh stack — which is this function itself, i.e. this file.
+ */
+function ownFileFromStack() {
+    const stack = new Error().stack;
+    if (typeof stack !== "string")
+        return undefined;
+    for (const line of stack.split("\n").slice(1)) {
+        // V8 frames: "    at fn (file:///p/analytics.js:1:2)" / "    at /p/analytics.js:1:2"
+        const match = /(?:\(|at )((?:file:\/\/)?[^\s()]+):\d+:\d+\)?\s*$/.exec(line);
+        const file = match?.[1];
+        if (!file || file.startsWith("node:") || file === "<anonymous>")
+            continue;
+        return file;
+    }
+    return undefined;
+}
+//# sourceMappingURL=analytics.js.map

package/dist/cjs/_client/analytics.js.map

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

package/dist/cjs/_client/index.d.ts

@@ -1,23 +1,3 @@
-/**
- * Auth + transport core for `@sapiom/tools` — the private "runtime half" every
- * capability namespace wraps. Capability modules call THIS; they never import each
- * other's runtime, so the cross-capability mesh (`repo.pushFromSandbox(sandbox)`)
- * has no package/module cycles. See docs/plans/capability-authoring-sdk.md.
- *
- * The credential resolves from one of two sources, same surface either way:
- *   - explicit:  createClient({ apiKey })  — standalone / open-source use
- *   - ambient:   SAPIOM_API_KEY (env), which the workflow engine injects per
- *                execution so step authors write zero auth plumbing.
- *
- * Attribution (which agent / trace a call belongs to) is execution context the
- * runtime owns, NOT a parameter of any operation — so it lives here on the
- * transport, set once and injected on every request, never threaded through
- * capability methods. The engine sets it per execution by constructing the
- * per-execution client; `withAttribution(...)` is a quiet escape hatch for the
- * router / standalone cases. Capability method signatures deliberately have no
- * attribution argument: that absence keeps LLM-authored step code from setting
- * (and getting wrong) context it doesn't own.
- */
 /**
  * Per-request attribution recorded with the gateway transaction. Every field is
  * optional and maps 1:1 to an `x-sapiom-*` header the collapsed flow understands.
@@ -85,6 +65,12 @@ export declare class Transport {
      * which injects `SAPIOM_CAPABILITY_RESUME_TOKEN` — keeps working unchanged.
      */
     readonly resumeToken: string | undefined;
+    /**
+     * Lazily-created usage-analytics emitter (see `./analytics.ts`). Not readonly:
+     * `withAttribution` re-points the derived transport at ITS holder so one client
+     * keeps one emitter no matter how many attributed views are derived from it.
+     */
+    private analyticsHolder;
     constructor(config?: TransportConfig);
     /**
      * A new transport sharing this one's credential, fetch, and resume token, with
@@ -93,6 +79,20 @@ export declare class Transport {
      * step-authoring code reaches for.
      */
     withAttribution(attribution: Attribution): Transport;
+    /**
+     * Flush and shut down this client's usage-analytics emitter: buffered events
+     * are delivered best-effort and the emitter's `beforeExit` hook is detached.
+     * Resolves immediately when no emitter was ever created (no calls made, or
+     * analytics disabled); idempotent; never rejects. One call covers every
+     * transport derived via {@link withAttribution} (they share the emitter).
+     *
+     * Call this once per client in hosts that construct MANY clients in one
+     * process — e.g. an engine worker building a per-execution client — so exit
+     * hooks don't accumulate across executions. One-shot processes don't need
+     * it: the emitter flushes on process exit by itself. Capability calls made
+     * after shutdown still work; they just no longer emit analytics.
+     */
+    shutdown(): Promise<void>;
     /**
      * Authenticated raw fetch — capabilities that need streaming or custom
      * response handling (filesystem, log streams) use this and inspect the
@@ -104,6 +104,14 @@ export declare class Transport {
      * instead (the value is identical — the Transport owns the key either way).
      */
     fetch(url: string, init?: RequestInit, options?: TransportRequestOptions): Promise<Response>;
+    /**
+     * Enqueue ONE `capability.call` usage event for a finished (or failed) HTTP
+     * call. Synchronous — nothing on the call path is awaited — and never throws;
+     * a silent no-op unless a collector endpoint is configured (see `./analytics.ts`).
+     * `request()` funnels through `fetch()`, so every capability call is counted
+     * exactly once.
+     */
+    private trackCapabilityCall;
     /** Authenticated JSON request — parses the body and throws on a non-2xx status. */
     request<T>(url: string, init?: RequestInit, options?: TransportRequestOptions): Promise<T>;
 }

package/dist/cjs/_client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,yFAAyF;IACzF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,kBAAkB,GAAG,WAAW,CAAC;AAI1D,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAYD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CAShD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE7B,MAAM,GAAE,eAAoB;IAUxC;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS;IASpD;;;;;;;;;OASG;IACG,KAAK,CACT,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC;IAiBpB,mFAAmF;IAC7E,OAAO,CAAC,CAAC,EACb,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC;CAmBd;AAID,wBAAgB,gBAAgB,IAAI,SAAS,CAE5C;AAED,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_client/index.ts"],"names":[],"mappings":"AA+BA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,yFAAyF;IACzF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,kBAAkB,GAAG,WAAW,CAAC;AAI1D,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAYD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CAShD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAuB;gBAElC,MAAM,GAAE,eAAoB;IAUxC;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS;IAWpD;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;;;;;;OASG;IACG,KAAK,CACT,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC;IA0BpB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA0B3B,mFAAmF;IAC7E,OAAO,CAAC,CAAC,EACb,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC;CAmBd;AAID,wBAAgB,gBAAgB,IAAI,SAAS,CAE5C;AAED,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC"}

package/dist/cjs/_client/index.js

@@ -1,4 +1,8 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCoreBaseUrl = exports.capabilityCall = exports.Transport = void 0;
+exports.attributionFromEnv = attributionFromEnv;
+exports.defaultTransport = defaultTransport;
 /**
  * Auth + transport core for `@sapiom/tools` — the private "runtime half" every
  * capability namespace wraps. Capability modules call THIS; they never import each
@@ -18,11 +22,12 @@
  * router / standalone cases. Capability method signatures deliberately have no
  * attribution argument: that absence keeps LLM-authored step code from setting
  * (and getting wrong) context it doesn't own.
+ *
+ * Being the single HTTP choke point also makes this the (one) instrumentation
+ * seam: every call enqueues a `capability.call` usage event — synchronously,
+ * never awaited, live by default. See `./analytics.ts`.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveCoreBaseUrl = exports.capabilityCall = exports.Transport = void 0;
-exports.attributionFromEnv = attributionFromEnv;
-exports.defaultTransport = defaultTransport;
+const analytics_js_1 = require("./analytics.js");
 const DEFAULT_AUTH_HEADER = "x-sapiom-api-key";
 function attributionToHeaders(a) {
     const h = {};
@@ -59,6 +64,12 @@ function attributionFromEnv() {
 }
 class Transport {
     constructor(config = {}) {
+        /**
+         * Lazily-created usage-analytics emitter (see `./analytics.ts`). Not readonly:
+         * `withAttribution` re-points the derived transport at ITS holder so one client
+         * keeps one emitter no matter how many attributed views are derived from it.
+         */
+        this.analyticsHolder = {};
         this.apiKey = config.apiKey ?? process.env.SAPIOM_API_KEY ?? undefined;
         this.fetchImpl = config.fetch ?? globalThis.fetch;
         this.attribution = config.attribution ?? {};
@@ -74,12 +85,30 @@ class Transport {
      * step-authoring code reaches for.
      */
     withAttribution(attribution) {
-        return new Transport({
+        const derived = new Transport({
             apiKey: this.apiKey,
             fetch: this.fetchImpl,
             attribution: { ...this.attribution, ...attribution },
             resumeToken: this.resumeToken,
         });
+        derived.analyticsHolder = this.analyticsHolder;
+        return derived;
+    }
+    /**
+     * Flush and shut down this client's usage-analytics emitter: buffered events
+     * are delivered best-effort and the emitter's `beforeExit` hook is detached.
+     * Resolves immediately when no emitter was ever created (no calls made, or
+     * analytics disabled); idempotent; never rejects. One call covers every
+     * transport derived via {@link withAttribution} (they share the emitter).
+     *
+     * Call this once per client in hosts that construct MANY clients in one
+     * process — e.g. an engine worker building a per-execution client — so exit
+     * hooks don't accumulate across executions. One-shot processes don't need
+     * it: the emitter flushes on process exit by itself. Capability calls made
+     * after shutdown still work; they just no longer emit analytics.
+     */
+    async shutdown() {
+        await this.analyticsHolder.instance?.shutdown();
     }
     /**
      * Authenticated raw fetch — capabilities that need streaming or custom
@@ -96,14 +125,48 @@ class Transport {
             throw new Error("@sapiom/tools: no tenant credential. Pass createClient({ apiKey }) for standalone use, " +
                 "or run inside a Sapiom workflow (the engine injects SAPIOM_API_KEY).");
         }
-        return this.fetchImpl(url, {
-            ...init,
-            headers: {
-                [options.authHeader ?? DEFAULT_AUTH_HEADER]: this.apiKey,
-                ...attributionToHeaders(this.attribution),
-                ...(init.headers ?? {}),
-            },
-        });
+        const startedAt = Date.now();
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                ...init,
+                headers: {
+                    [options.authHeader ?? DEFAULT_AUTH_HEADER]: this.apiKey,
+                    ...attributionToHeaders(this.attribution),
+                    ...(init.headers ?? {}),
+                },
+            });
+        }
+        catch (error) {
+            this.trackCapabilityCall(url, init, startedAt, undefined, error);
+            throw error;
+        }
+        this.trackCapabilityCall(url, init, startedAt, response);
+        return response;
+    }
+    /**
+     * Enqueue ONE `capability.call` usage event for a finished (or failed) HTTP
+     * call. Synchronous — nothing on the call path is awaited — and never throws;
+     * a silent no-op unless a collector endpoint is configured (see `./analytics.ts`).
+     * `request()` funnels through `fetch()`, so every capability call is counted
+     * exactly once.
+     */
+    trackCapabilityCall(url, init, startedAt, response, error) {
+        try {
+            (0, analytics_js_1.analyticsFor)(this.analyticsHolder, this.apiKey).track(analytics_js_1.CAPABILITY_CALL_EVENT, (0, analytics_js_1.capabilityCallData)({
+                url,
+                method: init.method,
+                requestBody: init.body,
+                durationMs: Date.now() - startedAt,
+                status: response?.status,
+                ok: response?.ok ?? false,
+                error,
+                attribution: this.attribution,
+            }));
+        }
+        catch {
+            // Usage analytics must never affect a capability call.
+        }
     }
     /** Authenticated JSON request — parses the body and throws on a non-2xx status. */
     async request(url, init = {}, options = {}) {