@sapiom/tools 0.15.0 → 0.17.0

package/dist/esm/_client/analytics.js

@@ -0,0 +1,242 @@
+/**
+ * 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.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAnalytics, } from "@sapiom/analytics-core";
+import { VERSION } from "../_generated/version.js";
+/** The one event this package emits: one per capability HTTP call. Dot-form is canonical. */
+export const CAPABILITY_CALL_EVENT = "capability.call";
+/** Get (creating on first use) the holder's emitter. Never throws — `createAnalytics` can't. */
+export function analyticsFor(holder, apiKey) {
+    return (holder.instance ?? (holder.instance = 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.
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export function resolveSdkVersion() {
+    return (cachedSdkVersion ?? (cachedSdkVersion = typeof VERSION === "string" && VERSION.length > 0
+        ? 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:") ? 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/esm/_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/esm/_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/esm/_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/esm/_client/index.js

@@ -17,7 +17,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`.
  */
+import { CAPABILITY_CALL_EVENT, analyticsFor, capabilityCallData, } from "./analytics.js";
 const DEFAULT_AUTH_HEADER = "x-sapiom-api-key";
 function attributionToHeaders(a) {
     const h = {};
@@ -54,6 +59,12 @@ export function attributionFromEnv() {
 }
 export 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 ?? {};
@@ -69,12 +80,30 @@ export 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
@@ -91,14 +120,48 @@ export 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 {
+            analyticsFor(this.analyticsHolder, this.apiKey).track(CAPABILITY_CALL_EVENT, 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 = {}) {

package/dist/esm/_client/index.js.map

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

package/dist/esm/_generated/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * GENERATED FILE — do not edit, not committed. Regenerated from package.json
+ * by `scripts/generate-version.mjs` (wired into the build/test/typecheck
+ * scripts as `gen:version`).
+ */
+export declare const VERSION = "0.17.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/esm/_generated/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../src/_generated/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/dist/esm/_generated/version.js

@@ -0,0 +1,7 @@
+/**
+ * GENERATED FILE — do not edit, not committed. Regenerated from package.json
+ * by `scripts/generate-version.mjs` (wired into the build/test/typecheck
+ * scripts as `gen:version`).
+ */
+export const VERSION = "0.17.0";
+//# sourceMappingURL=version.js.map

package/dist/esm/_generated/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/_generated/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}

package/dist/{cjs/orchestrations → esm/agents}/index.d.ts

@@ -6,7 +6,7 @@
  *   // dispatch another orchestration and pause this step on its result:
  *   const child = await orchestrations.launch({ definition: "enrich-lead", input });
  *   return pauseUntilSignal(child, { resumeStep: "use-result" });
- *   // the resumed step receives an OrchestrationRunResultPayload
+ *   // the resumed step receives an AgentRunResultPayload
  *
  * `launch` returns a handle to pass straight to `pauseUntilSignal` (the waiting
  * step resumes when the run finishes) or to `wait()` inline for standalone use.
@@ -22,10 +22,10 @@ import type { DispatchHandle } from "../dispatch.js";
  * orchestration handle resumes on this; it is the value carried in the handle's
  * `dispatch.resultSignal`.
  */
-export declare const ORCHESTRATIONS_RESULT_SIGNAL = "orchestrations.result";
+export declare const AGENTS_RESULT_SIGNAL = "agents.result";
 /** Run lifecycle status. */
 export type ExecutionStatus = "running" | "paused" | "completed" | "failed" | "cancelled";
-export interface OrchestrationRunSpec {
+export interface AgentRunSpec {
     /** Slug of the deployed orchestration to run (its stable handle). */
     definition: string;
     /** Input passed to the orchestration's entry step. */
@@ -43,7 +43,7 @@ export interface OrchestrationRunSpec {
     at?: string | Date;
 }
 /** A live, awaited run (the standalone `run()`/`wait()` result). */
-export interface OrchestrationRunResult {
+export interface AgentRunResult {
     executionId: string;
     status: ExecutionStatus;
     output: unknown;
@@ -56,12 +56,12 @@ export interface OrchestrationRunResult {
  *
  *   const useResult = defineStep({
  *     name: "use-result",
- *     async run(result: OrchestrationRunResultPayload, ctx) {
+ *     async run(result: AgentRunResultPayload, ctx) {
  *       if (result.status === "failed") { … }
  *     },
  *   });
  */
-export type OrchestrationRunResultPayload<TOutput = unknown> = {
+export type AgentRunResultPayload<TOutput = unknown> = {
     status: "completed";
     executionId: string;
     definition: string;
@@ -78,17 +78,17 @@ export type OrchestrationRunResultPayload<TOutput = unknown> = {
     startedAt: string;
     finishedAt: string;
 };
-/** Thrown by {@link orchestrationResultSchema}.parse on a malformed resume payload. */
-export declare class OrchestrationResultSchemaError extends Error {
+/** Thrown by {@link agentResultSchema}.parse on a malformed resume payload. */
+export declare class AgentResultSchemaError extends Error {
 }
 /**
- * Runtime validator for {@link OrchestrationRunResultPayload}. `parse` returns the
- * value typed on success and throws an {@link OrchestrationResultSchemaError} on any
+ * Runtime validator for {@link AgentRunResultPayload}. `parse` returns the
+ * value typed on success and throws an {@link AgentResultSchemaError} on any
  * divergence. Generic in the caller's expected `output` type — the shape of
  * `output` itself is the child orchestration's contract, not validated here.
  */
-export declare const orchestrationResultSchema: {
-    parse<TOutput = unknown>(value: unknown): OrchestrationRunResultPayload<TOutput>;
+export declare const agentResultSchema: {
+    parse<TOutput = unknown>(value: unknown): AgentRunResultPayload<TOutput>;
 };
 /**
  * A launched-but-not-awaited child run. Satisfies {@link DispatchHandle}, so it can
@@ -103,8 +103,8 @@ export interface RunHandle extends DispatchHandle {
     wait(opts?: {
         timeoutMs?: number;
         pollMs?: number;
-    }): Promise<OrchestrationRunResult>;
+    }): Promise<AgentRunResult>;
 }
-export declare function launch(spec: OrchestrationRunSpec, transport?: Transport, baseUrl?: string): Promise<RunHandle>;
-export declare function run(spec: OrchestrationRunSpec, transport?: Transport, baseUrl?: string): Promise<OrchestrationRunResult>;
+export declare function launch(spec: AgentRunSpec, transport?: Transport, baseUrl?: string): Promise<RunHandle>;
+export declare function run(spec: AgentRunSpec, transport?: Transport, baseUrl?: string): Promise<AgentRunResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOrD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,4BAA4B;AAC5B,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAGhB,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,GAAG,OAAO,IAC/C;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,+EAA+E;AAC/E,qBAAa,sBAAuB,SAAQ,KAAK;CAAG;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;UACtB,OAAO,mBACJ,OAAO,GACb,qBAAqB,CAAC,OAAO,CAAC;CAuBlC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,cAAc;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACnC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7B;AAuDD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,YAAY,EAClB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,SAAS,CAAC,CAuDpB;AAED,wBAAsB,GAAG,CACvB,IAAI,EAAE,YAAY,EAClB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,cAAc,CAAC,CAGzB"}