@stigg/agent-sdk-js 0.0.0-stage → 0.2.0

package/dist/engine/node-sdk-engine.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The engine half that runs on Stigg's own Node server SDK: cached entitlement reads and usage
+ * ingest. This is the only file in the package that imports it at runtime.
+ *
+ * It knows nothing about entities or chains - the GraphQL surface has no governance on it. What
+ * it brings is the cache, which is the reason the composite keeps ingest (and customer-level
+ * checks) here rather than sending everything to REST - and the reason nothing above this file
+ * caches anything. That cache writes reported usage back from the server's own response,
+ * invalidates on realtime updates, resets usage periods at read time, falls back when Stigg is
+ * unreachable, and optionally lives in Redis so sibling processes share one view.
+ *
+ * All of that is configured through {@link CacheOptions}, which is the Node SDK's own
+ * configuration passed straight through rather than re-described here.
+ */
+import Stigg, { type ClientConfiguration } from '@stigg/node-server-sdk';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, GovernanceEngine } from './engine';
+/**
+ * Caching - all of it, and none of it implemented here.
+ *
+ * This SDK holds no cache. Checks are served by the Node server SDK's entitlement cache, which
+ * already does the hard parts: it writes the server's own measurement responses back into cached
+ * usage, invalidates on realtime updates, applies usage-period resets at read time, and can be
+ * backed by Redis so sibling processes share one view instead of each holding their own.
+ *
+ * So this is a passthrough rather than a parallel design - the field names are the Node SDK's own,
+ * and anything it learns to do lands here without a change. The one thing that does *not* cache is
+ * an attributed governance check: it resolves an entity, which only the governance API can do, so
+ * it is a live call every time. That is the stricter answer, and it is where per-agent budgets are
+ * enforced.
+ */
+export type CacheOptions = Pick<ClientConfiguration, 'redis' | 'memoryCacheMaxSizeBytes' | 'entitlementsFallback' | 'creditEntitlementsFallback' | 'realtimeUpdatesEnabled' | 'enableEdge' | 'offline'>;
+/**
+ * The Node server SDK client itself, for an application that already has one.
+ *
+ * Re-exported from `config.ts` as the public name, so the vendor client stays behind this file.
+ */
+export type NodeSdkClient = Stigg;
+export type NodeSdkEngineOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    /**
+     * Everything about caching, passed through to the Node SDK verbatim. Anything set here wins
+     * over the localhost-aware defaults below - including `enableEdge` and `realtimeUpdatesEnabled`,
+     * which are cache configuration in all but name: the socket is what keeps a cached entitlement
+     * from going stale.
+     */
+    cache?: CacheOptions;
+    /**
+     * An existing client to use instead of building one. Borrowed, never closed.
+     *
+     * This is the only way to be *sure* who owns the client, which matters because
+     * `Stigg.initialize` keeps one global instance per process and hands it back when the API key
+     * matches. Closing a client the application is still using would take its cache and its socket
+     * with it, and nothing from out here can tell a client that was just built from one that was
+     * handed back: the instance exposes neither its configuration nor its identity.
+     */
+    client?: NodeSdkClient;
+};
+export declare class NodeSdkEngine implements GovernanceEngine {
+    readonly capabilities: EngineCapabilities;
+    /**
+     * Whether this engine built the client, and may therefore close it.
+     *
+     * False for a client that was handed in: it belongs to whoever built it, and its lifecycle is
+     * theirs. See `close`.
+     */
+    readonly ownsClient: boolean;
+    private readonly client;
+    constructor(options: NodeSdkEngineOptions);
+    /**
+     * Waits for the cache to be usable.
+     *
+     * Not cosmetic: until the runtime reports itself initialized, every read is treated as a miss
+     * and refetched, so a client that starts serving immediately pays a round trip per check for as
+     * long as initialization takes. Awaited once at startup instead.
+     */
+    ready(): Promise<void>;
+    /**
+     * Loads this customer's entitlements into the cache, so the checks that follow are local.
+     *
+     * The whole map, not one decision: a later check against a different entitlement is warm too,
+     * and each is evaluated against the amount it actually asks for rather than against whatever
+     * amount happened to warm it.
+     */
+    preload(customerId: string): Promise<void>;
+    upsertEntity(): Promise<void>;
+    archiveEntity(): Promise<void>;
+    /**
+     * The two kinds of entitlement are two different endpoints with two different answers, so each
+     * gets its own method and this one only picks. Narrowing on `currencyId` rather than through
+     * `entitlementKind` is what lets each branch read its own id without an assertion: a function
+     * call cannot narrow a union.
+     */
+    check(customerId: string, { entitlement, requestedUsage }: EngineCheckParams): Promise<EngineCheckResult>;
+    /**
+     * `getCreditEntitlement` takes no `requestedUsage` - `CreditEntitlementOptions` has no such
+     * field - so unlike the metered path, nobody at Stigg is asked whether this particular amount is
+     * affordable. Dropping the comparison is not an option: a check for five units against a balance
+     * of two would come back granted and the run would overspend. So the SDK answers it, and says so
+     * in `locallyDerived` rather than letting a verdict it reached by subtraction read like one the
+     * server handed down.
+     */
+    private checkCredit;
+    /** The metered path, where Stigg is asked about this amount and answers for it. */
+    private checkFeature;
+    /** The four calls this client makes; `reportMetrics` decides which of them each metric is. */
+    report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
+    /** The feature path: bulk, because a turn reports several metrics and this client has one call. */
+    private reportUsage;
+    /**
+     * The credit path: the currency is drawn from the customer's wallet with no feature mapping,
+     * so none of the feature-side setup (a metered feature, a credit rate, an entitling
+     * subscription) is involved. Stigg forwards the consumption to governance itself, so per-entity
+     * budgets still decrement.
+     *
+     * `replayed` is always false here: the response carries the wallet's running balance but not
+     * this call's own deduction, so a replayed idempotency key is indistinguishable from a fresh
+     * one. The server still deduplicates on the key - only our ability to report it is lost.
+     */
+    private consumeCredits;
+    /** The raw-events path: one event for the turn, matched by name, and no balance in the answer. */
+    private reportAsEvent;
+    close(): Promise<void>;
+}

package/dist/engine/node-sdk-engine.js

@@ -0,0 +1,262 @@
+"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.NodeSdkEngine = void 0;
+/**
+ * The engine half that runs on Stigg's own Node server SDK: cached entitlement reads and usage
+ * ingest. This is the only file in the package that imports it at runtime.
+ *
+ * It knows nothing about entities or chains - the GraphQL surface has no governance on it. What
+ * it brings is the cache, which is the reason the composite keeps ingest (and customer-level
+ * checks) here rather than sending everything to REST - and the reason nothing above this file
+ * caches anything. That cache writes reported usage back from the server's own response,
+ * invalidates on realtime updates, resets usage periods at read time, falls back when Stigg is
+ * unreachable, and optionally lives in Redis so sibling processes share one view.
+ *
+ * All of that is configured through {@link CacheOptions}, which is the Node SDK's own
+ * configuration passed straight through rather than re-described here.
+ */
+const node_server_sdk_1 = __importStar(require("@stigg/node-server-sdk"));
+const errors_1 = require("../errors");
+const sdk_identity_1 = require("../sdk-identity");
+const report_1 = require("./report");
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/**
+ * Drops keys that were never set, so a spread cannot un-set a default.
+ *
+ * The Node SDK merges its configuration with lodash, which skips an `undefined` source value and
+ * keeps its own default - so `{ enableEdge: false, ...cache }` with an unset `cache.enableEdge`
+ * would land back on `true` and point a local run at an edge service that was never started.
+ */
+const defined = (options) => Object.fromEntries(Object.entries(options ?? {}).filter(([, value]) => value !== undefined));
+function isLocalhost(baseUrl) {
+    if (!baseUrl)
+        return false;
+    try {
+        return LOCAL_HOSTS.has(new URL(baseUrl).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+class NodeSdkEngine {
+    capabilities = {
+        // The SDK serves reads from its own cache, so two processes can each approve the same budget.
+        strictCheck: false,
+        chains: false,
+        provisioning: false,
+    };
+    /**
+     * Whether this engine built the client, and may therefore close it.
+     *
+     * False for a client that was handed in: it belongs to whoever built it, and its lifecycle is
+     * theirs. See `close`.
+     */
+    ownsClient;
+    client;
+    constructor(options) {
+        if (options.client) {
+            this.client = options.client;
+            this.ownsClient = false;
+            return;
+        }
+        this.ownsClient = true;
+        const local = isLocalhost(options.baseUrl);
+        this.client = node_server_sdk_1.default.initialize({
+            apiKey: options.apiKey,
+            // So this traffic is attributable to the agent SDK rather than reading as a plain
+            // node-server-sdk client. Only applies to a client built here: `Stigg.initialize` returns
+            // its existing global instance when the API key matches, and a client handed in through
+            // `options.client` keeps whatever name the application gave it.
+            clientName: sdk_identity_1.AGENT_SDK_CLIENT_NAME,
+            clientVersion: sdk_identity_1.AGENT_SDK_VERSION,
+            ...(options.baseUrl ? { baseUri: options.baseUrl } : {}),
+            ...(options.timeoutMs ? { entitlementsTimeout: options.timeoutMs } : {}),
+            // The edge cache and the realtime socket are separate services from the API, and a Stigg
+            // running on localhost usually serves neither - without this a local run fails on
+            // ECONNREFUSED against services that were never started.
+            enableEdge: !local,
+            realtimeUpdatesEnabled: !local,
+            // Last, so an explicit choice wins over the defaults above.
+            ...defined(options.cache),
+        });
+    }
+    /**
+     * Waits for the cache to be usable.
+     *
+     * Not cosmetic: until the runtime reports itself initialized, every read is treated as a miss
+     * and refetched, so a client that starts serving immediately pays a round trip per check for as
+     * long as initialization takes. Awaited once at startup instead.
+     */
+    async ready() {
+        await this.client.waitForInitialization();
+    }
+    /**
+     * Loads this customer's entitlements into the cache, so the checks that follow are local.
+     *
+     * The whole map, not one decision: a later check against a different entitlement is warm too,
+     * and each is evaluated against the amount it actually asks for rather than against whatever
+     * amount happened to warm it.
+     */
+    async preload(customerId) {
+        await this.client.reloadEntitlements(customerId);
+    }
+    async upsertEntity() {
+        throw new errors_1.GovernanceNotEnabledError('The Node server SDK has no governance surface; entities need the REST client.');
+    }
+    async archiveEntity() {
+        throw new errors_1.GovernanceNotEnabledError('The Node server SDK has no governance surface; entities need the REST client.');
+    }
+    /**
+     * The two kinds of entitlement are two different endpoints with two different answers, so each
+     * gets its own method and this one only picks. Narrowing on `currencyId` rather than through
+     * `entitlementKind` is what lets each branch read its own id without an assertion: a function
+     * call cannot narrow a union.
+     */
+    async check(customerId, { entitlement, requestedUsage }) {
+        try {
+            return entitlement.currencyId !== undefined
+                ? await this.checkCredit(customerId, entitlement.currencyId, requestedUsage)
+                : await this.checkFeature(customerId, entitlement.featureId, requestedUsage);
+        }
+        catch (err) {
+            throw (0, errors_1.asEngineError)('check', err);
+        }
+    }
+    /**
+     * `getCreditEntitlement` takes no `requestedUsage` - `CreditEntitlementOptions` has no such
+     * field - so unlike the metered path, nobody at Stigg is asked whether this particular amount is
+     * affordable. Dropping the comparison is not an option: a check for five units against a balance
+     * of two would come back granted and the run would overspend. So the SDK answers it, and says so
+     * in `locallyDerived` rather than letting a verdict it reached by subtraction read like one the
+     * server handed down.
+     */
+    async checkCredit(customerId, currencyId, requestedUsage) {
+        const state = await this.client.getCreditEntitlement({ customerId, currencyId });
+        const affordable = state.remaining >= requestedUsage;
+        const denial = state.hasAccess ? node_server_sdk_1.AccessDeniedReason.InsufficientCredits : state.accessDeniedReason;
+        return {
+            isGranted: state.hasAccess && affordable,
+            accessDeniedReason: affordable && state.hasAccess ? null : (denial ?? null),
+            locallyDerived: state.hasAccess,
+            usageLimit: state.usageLimit,
+            currentUsage: state.currentUsage,
+            isFallback: state.isFallback,
+            source: 'node-sdk',
+        };
+    }
+    /** The metered path, where Stigg is asked about this amount and answers for it. */
+    async checkFeature(customerId, featureId, requestedUsage) {
+        const state = await this.client.getMeteredEntitlement({ customerId, featureId, options: { requestedUsage } });
+        return {
+            isGranted: state.hasAccess,
+            accessDeniedReason: state.accessDeniedReason ?? null,
+            usageLimit: state.isUnlimited ? null : (state.usageLimit ?? null),
+            currentUsage: state.currentUsage,
+            isFallback: state.isFallback,
+            source: 'node-sdk',
+        };
+    }
+    /** The four calls this client makes; `reportMetrics` decides which of them each metric is. */
+    async report(customerId, params) {
+        return (0, report_1.reportMetrics)(params, {
+            credits: (featureId, value) => this.consumeCredits(customerId, params, featureId, value),
+            creditsAsync: (featureId, value) => this.consumeCredits(customerId, params, featureId, value, 'async'),
+            event: (metrics, dimensions) => this.reportAsEvent(customerId, params, metrics, dimensions),
+            usage: (metrics) => this.reportUsage(customerId, params, metrics),
+        });
+    }
+    /** The feature path: bulk, because a turn reports several metrics and this client has one call. */
+    async reportUsage(customerId, params, metrics) {
+        const acks = await this.client.reportUsageBulk({ usages: (0, report_1.usageEntries)(customerId, params, metrics) });
+        return (0, report_1.usageResult)(acks, metrics, 'node-sdk');
+    }
+    /**
+     * The credit path: the currency is drawn from the customer's wallet with no feature mapping,
+     * so none of the feature-side setup (a metered feature, a credit rate, an entitling
+     * subscription) is involved. Stigg forwards the consumption to governance itself, so per-entity
+     * budgets still decrement.
+     *
+     * `replayed` is always false here: the response carries the wallet's running balance but not
+     * this call's own deduction, so a replayed idempotency key is indistinguishable from a fresh
+     * one. The server still deduplicates on the key - only our ability to report it is lost.
+     */
+    async consumeCredits(customerId, params, featureId, value, mode = 'sync') {
+        // The wallet's own id. A metric only reaches this path when it names the currency the run
+        // checks, so the metric name and the currency are the same string.
+        const consumption = (0, report_1.creditConsumption)(customerId, params, featureId, value);
+        try {
+            // The async form takes the same consumption and reconciles it on Stigg's side, so the
+            // amount is still ours to state - which is why a run reporting to its own currency keeps
+            // an exact local budget in either mode. Only the balance is lost.
+            const ack = mode === 'async' ? undefined : await this.client.consumeCredits(consumption);
+            if (mode === 'async')
+                await this.client.consumeCreditsAsync({ consumptions: [consumption] });
+            return (0, report_1.creditResult)(featureId, value, ack?.credit?.currentUsage, mode, 'node-sdk');
+        }
+        catch (err) {
+            throw (0, errors_1.asEngineError)('ingest', err);
+        }
+    }
+    /** The raw-events path: one event for the turn, matched by name, and no balance in the answer. */
+    async reportAsEvent(customerId, params, metrics, dimensions) {
+        const event = params.event;
+        if (!event)
+            throw (0, report_1.missingEventError)();
+        try {
+            await this.client.reportEvent({
+                customerId,
+                eventName: event.name,
+                // The turn's own key: one event, so no per-feature suffix to keep them apart.
+                idempotencyKey: params.idempotencyKey,
+                dimensions,
+            });
+            // No balance comes back, and aggregation lags by seconds - so `replayed` stays unknown.
+            return { reported: metrics, mode: 'async', source: 'node-sdk' };
+        }
+        catch (err) {
+            throw (0, errors_1.asEngineError)('ingest', err);
+        }
+    }
+    async close() {
+        // The SDK keeps a background cache and sockets alive; without this a CLI never exits. But
+        // only for a client this engine built: `close` nulls the Node SDK's global instance and tears
+        // down the runtime, so closing a borrowed one would take the application's cache and socket
+        // with it.
+        if (this.ownsClient)
+            await this.client.close();
+    }
+}
+exports.NodeSdkEngine = NodeSdkEngine;

package/dist/engine/report.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The shape of an ingest, which both transports share even though none of their calls do.
+ *
+ * Stigg has two ingest APIs and they are not interchangeable. The usage report takes a fixed DTO -
+ * a `featureId` and a whole-number `value` per metric - and aggregates on arrival, so the next
+ * check sees the spend. The event report takes the call as one event and lets Stigg's own meters
+ * turn it into usage seconds later, for a fraction of the latency and a far higher rate limit.
+ * Which one a run wants is a product decision - immediacy against throughput - so the caller
+ * chooses it and this file only carries the choice out.
+ *
+ * What that costs each metric:
+ *
+ * - **`'sync'`** sends one usage report per metric, batched into the one bulk call both clients
+ *   have, because a chat turn otherwise costs four round trips.
+ * - **`'async'`** sends **one event for the whole turn**, every metric on its own dimension. One
+ *   event can feed any number of meters - each picks its number with `aggregation.field` - so
+ *   fanning out per metric would buy nothing and cost a request each.
+ *
+ * A metric named after the run's own credit currency is neither: it draws the wallet directly,
+ * because a usage report takes only a `featureId` and there is no event path from a raw event to
+ * a currency. It follows the mode only in how it waits - `consumeCredits` under `'sync'`, which
+ * answers with a balance, and `consumeCreditsAsync` under `'async'`, which does not.
+ *
+ * That orchestration lives here, and with it the parts of an ingest that are the same whichever
+ * client makes it: the consumption payload, the per-metric idempotency key, and how a bulk ack is
+ * read. Each engine still passes its own calls, so a vendor method is only ever named by the file
+ * that owns that client - but the split between wallet and features, and what a turn is taken to
+ * have cost, cannot come to mean one thing over REST and another over the SDK.
+ */
+import { EngineError } from '../errors';
+import type { IngestMode, Metrics } from '../types';
+import type { EngineOpSource, EngineReportParams, EngineReportResult } from './engine';
+/** What one transport can do with an ingest, as the calls it already knows how to make. */
+export type ReportCalls = {
+    /** Draw the wallet and wait for the balance, for a metric that names the run's currency. */
+    credits: (featureId: string, value: number) => Promise<EngineReportResult>;
+    /** The same draw, reconciled on Stigg's side. No balance comes back. */
+    creditsAsync: (featureId: string, value: number) => Promise<EngineReportResult>;
+    /** One bulk usage report, one entry per metric. */
+    usage: (metrics: Metrics) => Promise<EngineReportResult>;
+    /** One event for the whole turn, carrying every metric as a dimension. */
+    event: (metrics: Metrics, dimensions: Record<string, string | number | boolean>) => Promise<EngineReportResult>;
+};
+/** A draw on the wallet. `consume` and `consumeAsync` take it unchanged, on both transports. */
+export declare const creditConsumption: (customerId: string, params: EngineReportParams, currencyId: string, amount: number) => {
+    customerId: string;
+    currencyId: string;
+    amount: number;
+    idempotencyKey: string;
+    dimensions: Record<string, string>;
+};
+/** One bulk usage report, one entry per metric. REST adds its own `updateBehavior` on top. */
+export declare const usageEntries: (customerId: string, params: EngineReportParams, metrics: Metrics) => {
+    customerId: string;
+    featureId: string;
+    value: number;
+    dimensions: Record<string, string>;
+    idempotencyKey: string;
+}[];
+/**
+ * What a wallet draw amounts to, read the same way whichever client made it.
+ *
+ * Only the call and where the balance sits on its response differ between the transports; this is
+ * everything after that. `creditsConsumed` is the metric's own value because a draw is spent at
+ * par - no feature mapping, no rate - and `replayed` is `false` under `'sync'` rather than
+ * unknown: the response carries the wallet's running balance but not this call's own deduction,
+ * so a replayed key is indistinguishable from a fresh one. Under `'async'` nothing comes back at
+ * all, so it stays undefined.
+ */
+export declare function creditResult(currencyId: string, amount: number, currentUsage: number | null | undefined, mode: IngestMode, source: EngineOpSource): EngineReportResult;
+/** As much of a bulk ack as either client returns: the balance, and what each entry cost. */
+export type UsageAck = {
+    currentUsage?: number | null;
+    credit?: {
+        currentUsage?: number | null;
+        consumed?: number | null;
+    } | null;
+};
+/** What a bulk usage report amounts to, read the same way whichever client answered. */
+export declare function usageResult(acks: readonly UsageAck[], metrics: Metrics, source: EngineOpSource): EngineReportResult;
+export declare function reportMetrics(params: EngineReportParams, calls: ReportCalls): Promise<EngineReportResult>;
+/**
+ * What one event carries, and in which order.
+ *
+ * Three namespaces flatten into one map, so the order is the whole design. Attribution is applied
+ * last and wins outright: a gateway passes vendor fields through, and a vendor field that happened
+ * to be called `agentId` would otherwise re-attribute the bill to an entity that never ran. The
+ * raw block sits under its own prefix beneath both, where it can be metered deliberately but
+ * cannot displace anything.
+ */
+export declare function eventDimensions(params: EngineReportParams, metrics: Metrics): Record<string, string | number | boolean>;
+/**
+ * The one thing the caller has to fix themselves, so it reads the same whichever client found it.
+ *
+ * An in-process run derives the name from the vendor call it wrapped, so this is reachable only
+ * out of process, where there is no recipe to derive it from.
+ */
+export declare function missingEventError(): EngineError;
+/**
+ * A sync report to a feature only a meter can fill.
+ *
+ * The rejection used to be a routing signal - the engines retried it as an event and remembered.
+ * That made the transport a property of the catalog, discovered one rejection at a time, and
+ * silently moved a run onto an eventually-consistent path it never asked for. Now it says so.
+ */
+export declare function meterMismatchError(metrics: Metrics): EngineError;