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

package/dist/errors.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGovernanceNotEnabled = exports.isEngineError = exports.GovernanceNotEnabledError = exports.EngineError = exports.AccessDeniedError = void 0;
+exports.isAccessDenied = isAccessDenied;
+exports.isMeterMismatchError = isMeterMismatchError;
+exports.asEngineError = asEngineError;
+exports.isTransportFailure = isTransportFailure;
+exports.asGovernanceError = asGovernanceError;
+exports.looksLikeGovernanceNotEnabled = looksLikeGovernanceNotEnabled;
+const MARKER = Symbol.for('stigg.agent-sdk.error');
+const mark = (err, kind) => {
+    Object.defineProperty(err, MARKER, { value: kind, enumerable: false });
+    return err;
+};
+const isKind = (err, kind) => typeof err === 'object' && err !== null && err[MARKER] === kind;
+/**
+ * Thrown only where there is no return path for a decision - inside a wrapped client method,
+ * which must hand back the vendor's own response type or nothing at all. Everywhere else a
+ * denial is a returned `AccessDecision`.
+ */
+class AccessDeniedError extends Error {
+    decision;
+    constructor(decision) {
+        const by = decision.deniedBy ? ` by ${decision.deniedBy}` : '';
+        super(`Denied${by}: ${decision.reason ?? 'no budget remaining'}`);
+        this.name = 'AccessDeniedError';
+        this.decision = decision;
+        mark(this, 'denied');
+    }
+}
+exports.AccessDeniedError = AccessDeniedError;
+/** Anything the engine could not complete: transport, timeout, 4xx/5xx, bad input. */
+class EngineError extends Error {
+    status;
+    operation;
+    /**
+     * What the server had already accepted when this failed.
+     *
+     * An ingest is up to two calls - the features, then the wallet - so a rejection on the second
+     * leaves the first one's spend sitting at Stigg. Reporting that turn as nothing landed would
+     * understate a bill the customer is going to see, which is the one direction a meter must not
+     * be wrong in.
+     */
+    reported;
+    /**
+     * Whether what landed was a replay. Carried with `reported`, because counting those metrics
+     * again is the one thing a caller must not do with keys Stigg had already seen - and
+     * `undefined` means here what it means everywhere: the event API could not say.
+     */
+    replayed;
+    constructor(operation, message, options) {
+        super(`${operation}: ${message}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'EngineError';
+        this.operation = operation;
+        this.status = options?.status;
+        this.reported = options?.reported;
+        this.replayed = options?.replayed;
+        mark(this, 'engine');
+    }
+}
+exports.EngineError = EngineError;
+/**
+ * Per-agent budgets are not enabled for this Stigg environment. An account state, not a transient
+ * failure, and the class keeps the platform's own name because that is what has to be turned on.
+ *
+ * The message says what to do rather than what is missing. "Governance is not enabled" names an
+ * internal capability to someone who was trying to charge for agent usage and has no reason to
+ * know the two are the same thing - so the first line is the fix, and the feature name follows it
+ * for whoever has to go and find the setting.
+ */
+class GovernanceNotEnabledError extends Error {
+    constructor(detail = 'Per-agent budgets are not enabled for this Stigg environment, so an agent cannot be ' +
+        'given an identity or a budget. Enable Governance for the account to use them - or drop ' +
+        '`agentId` and the budget fields, and checks and usage apply to the customer instead.') {
+        super(detail);
+        this.name = 'GovernanceNotEnabledError';
+        mark(this, 'not-enabled');
+    }
+}
+exports.GovernanceNotEnabledError = GovernanceNotEnabledError;
+/** Returns the decision when `err` is a governance denial - the one-liner for a binding catch. */
+function isAccessDenied(err) {
+    if (isKind(err, 'denied'))
+        return err.decision;
+    // Vendor SDKs wrap callback errors, so the denial can arrive one level down.
+    const cause = err?.cause;
+    if (cause && isKind(cause, 'denied'))
+        return cause.decision;
+    return undefined;
+}
+const isEngineError = (err) => isKind(err, 'engine');
+exports.isEngineError = isEngineError;
+const isGovernanceNotEnabled = (err) => isKind(err, 'not-enabled');
+exports.isGovernanceNotEnabled = isGovernanceNotEnabled;
+/**
+ * True when Stigg refused a usage report because the feature is backed by a raw-events meter.
+ * Ingest forks by meter type, and this error is the definitive signal for which fork to take -
+ * `meterType` alone does not say (a raw-events feature can report `INCREMENTAL`).
+ */
+function isMeterMismatchError(err) {
+    const any = err;
+    const code = any?.code ?? any?.error?.code ?? '';
+    if (code.startsWith('CannotReportUsageForEntitlementWithMeter'))
+        return true;
+    const message = any?.message ?? '';
+    return message.includes('report usage for entitlement with meter') || message.includes('use reportEvent');
+}
+/** Whatever a client threw, as the seam's own error - keeping the status where there was one. */
+function asEngineError(operation, err, partial) {
+    const status = err?.status;
+    // Re-wrapping must not drop a partial acknowledgement: the run handle wraps again on its way
+    // out, and whatever landed is just as true one frame up.
+    const landed = partial ?? (err instanceof EngineError ? { reported: err.reported, replayed: err.replayed } : {});
+    return new EngineError(operation, err instanceof Error ? err.message : String(err), {
+        status,
+        cause: err,
+        reported: landed.reported,
+        replayed: landed.replayed,
+    });
+}
+/**
+ * True when a failure looks like "this transport is not answering" rather than "Stigg refused".
+ *
+ * The distinction decides whether another transport is worth trying: a 404 on the GraphQL
+ * endpoint or a refused connection says nothing about the request, while a 400 or a 403 says the
+ * request itself is wrong and would be wrong on any transport. Deliberately narrow - demoting on
+ * a business error would hide a real problem behind a silent re-route.
+ */
+function isTransportFailure(err) {
+    const any = err;
+    if (any?.status && [404, 500, 502, 503, 504].includes(any.status))
+        return true;
+    const code = any?.cause?.code ?? '';
+    if (['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'ECONNRESET', 'EAI_AGAIN'].includes(code))
+        return true;
+    const message = `${any?.message ?? ''} ${any?.cause?.message ?? ''}`;
+    if (/status code (404|5\d\d)/i.test(message))
+        return true;
+    return /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|socket hang up|fetch failed|network error/i.test(message);
+}
+/**
+ * The seam's error for an operation that only governance can serve.
+ *
+ * Entities and assignments exist nowhere else, so a 403 on one of them is the account saying the
+ * feature is off - a state the caller can act on - rather than a call that failed. Every other
+ * failure is an ordinary engine error.
+ */
+function asGovernanceError(operation, err) {
+    if (looksLikeGovernanceNotEnabled(err))
+        return new GovernanceNotEnabledError();
+    return asEngineError(operation, err);
+}
+/** Recognizes the account-state 403 in whatever shape the transport surfaced it. */
+function looksLikeGovernanceNotEnabled(err) {
+    if ((0, exports.isGovernanceNotEnabled)(err))
+        return true;
+    const any = err;
+    if (any?.code === 'GovernanceNotEnabled' || any?.error?.code === 'GovernanceNotEnabled')
+        return true;
+    return any?.status === 403 && (any.message ?? '').includes('Governance is not enabled');
+}

package/dist/headers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The wire convention for splitting the run lifecycle across a process boundary.
+ *
+ * A gateway is out-of-process and sees requests, not runs. These headers are what lets the
+ * application keep governance in-process while something downstream still ingests against the
+ * right entity - so the convention belongs to the core, not to any one binding.
+ */
+export declare const GOVERNANCE_HEADERS: {
+    readonly customer: "x-stigg-customer-id";
+    readonly dimensions: "x-stigg-dimensions";
+    readonly run: "x-stigg-run-id";
+    /**
+     * Which key in `dimensions` names the agent, when one does.
+     *
+     * Sent because the far end cannot work it out. Governance resolves an entity per attribution
+     * key, and which keys those are is declared on the entity types in the account - so a receiver
+     * holding only `{ agentId: 'a-1', region: 'eu' }` cannot tell the attribution from the
+     * metadata. Guessing either way is wrong in a direction that costs money: treat every
+     * dimension as attribution and an ordinary `region` rounds the draw up; treat none as
+     * attribution and a real agent's budget stops counting.
+     */
+    readonly attributionKey: "x-stigg-attribution-key";
+};
+/**
+ * What `run.headers()` produces - all three, always.
+ *
+ * Built rather than parsed, so the type says so: an empty map or an unrelated one is not a set of
+ * governance headers, and there is no point discovering that at the far end of a request. The
+ * receiving side is deliberately looser, because what arrives there is whatever was sent.
+ */
+export type GovernanceHeaders = Record<(typeof GOVERNANCE_HEADERS)[keyof typeof GOVERNANCE_HEADERS], string>;
+export type ParsedGovernanceHeaders = {
+    customerId: string;
+    dimensions: Record<string, string>;
+    runId?: string;
+    /** The key under which `dimensions` names the agent, when the sender named one. */
+    attributionKey?: string;
+};
+/** The receiving side. Returns undefined when the request carries no attribution to act on. */
+export declare function parseGovernanceHeaders(headers: Record<string, string | string[] | undefined>): ParsedGovernanceHeaders | undefined;

package/dist/headers.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GOVERNANCE_HEADERS = void 0;
+exports.parseGovernanceHeaders = parseGovernanceHeaders;
+/**
+ * The wire convention for splitting the run lifecycle across a process boundary.
+ *
+ * A gateway is out-of-process and sees requests, not runs. These headers are what lets the
+ * application keep governance in-process while something downstream still ingests against the
+ * right entity - so the convention belongs to the core, not to any one binding.
+ */
+exports.GOVERNANCE_HEADERS = {
+    customer: 'x-stigg-customer-id',
+    dimensions: 'x-stigg-dimensions',
+    run: 'x-stigg-run-id',
+    /**
+     * Which key in `dimensions` names the agent, when one does.
+     *
+     * Sent because the far end cannot work it out. Governance resolves an entity per attribution
+     * key, and which keys those are is declared on the entity types in the account - so a receiver
+     * holding only `{ agentId: 'a-1', region: 'eu' }` cannot tell the attribution from the
+     * metadata. Guessing either way is wrong in a direction that costs money: treat every
+     * dimension as attribution and an ordinary `region` rounds the draw up; treat none as
+     * attribution and a real agent's budget stops counting.
+     */
+    attributionKey: 'x-stigg-attribution-key',
+};
+/** The receiving side. Returns undefined when the request carries no attribution to act on. */
+function parseGovernanceHeaders(headers) {
+    // Node lowercases what it receives, but a map built by hand or converted from `Headers` keeps
+    // whatever case the sender used, and losing attribution over it would be silent.
+    // What a header is worth, whichever container it arrived in: `'c'` and `['c']` are the same
+    // value under this function's own argument type, so comparing the containers would call them a
+    // disagreement. A header present but blank is a header that is not set.
+    const valueOf = (raw) => {
+        const first = Array.isArray(raw) ? raw[0] : raw;
+        return first?.trim() ? first.trim() : undefined;
+    };
+    const lookup = new Map();
+    const ambiguous = new Set();
+    for (const [key, raw] of Object.entries(headers)) {
+        const name = key.toLowerCase();
+        const value = valueOf(raw);
+        // Two spellings of one header, disagreeing. Folding case makes them the same name, and
+        // letting the last one win would attribute the request to whichever the map happened to
+        // iterate second - a silently wrong customer reads exactly like a right one.
+        if (lookup.has(name) && lookup.get(name) !== value)
+            ambiguous.add(name);
+        lookup.set(name, value);
+    }
+    const read = (name) => (ambiguous.has(name) ? undefined : lookup.get(name));
+    const customerId = read(exports.GOVERNANCE_HEADERS.customer);
+    if (!customerId)
+        return undefined;
+    let dimensions = {};
+    const raw = read(exports.GOVERNANCE_HEADERS.dimensions);
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            // `JSON.parse` succeeds on `null`, arrays and scalars, none of which are a dimensions map.
+            if (isDimensions(parsed))
+                dimensions = parsed;
+        }
+        catch {
+            // A malformed header must not cost the request; usage just loses its entity attribution.
+            dimensions = {};
+        }
+    }
+    // Only honoured when it names a dimension that is actually there: a key with nothing under it
+    // attributes to no entity, and treating it as though it did would round a draw up for nothing.
+    const attributionKey = read(exports.GOVERNANCE_HEADERS.attributionKey);
+    return {
+        customerId,
+        dimensions,
+        runId: read(exports.GOVERNANCE_HEADERS.run),
+        ...(attributionKey && dimensions[attributionKey] ? { attributionKey } : {}),
+    };
+}
+const isDimensions = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === 'string');

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Public surface.
+ *
+ * Importing this file pulls in no vendor package. The recipes below are exported from here, but
+ * each one is duck-typed against the shape a vendor returns rather than written against its SDK,
+ * so `@anthropic-ai/sdk`, `openai` and the rest stay out of the dependency tree entirely.
+ *
+ * What is exported here is the vocabulary, the client, and the seams worth extending: a recipe,
+ * a metrics mapper, a `GovernanceEngine`. The implementations behind those seams - the concrete
+ * engines, decision construction, config resolution, the metric tables - live in
+ * `@stigg/agent-sdk-js/internal`, under a weaker compatibility promise.
+ */
+export { StiggAgentSDK } from './stigg-agent-sdk';
+export type { StiggContext } from './core/context';
+export type { SessionSummary, HookContext, IngestOptions, SessionHooks } from './core/session';
+export { RAW_PREFIX, flattenRaw } from './core/dimensions';
+export type { CacheOptions, ErrorContext, NodeSdkClient, StiggAgentSDKOptions } from './config';
+export { describeDecision, remedyMessage } from './decision-text';
+export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
+export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';
+export { consoleLogger, noopLogger } from './logger';
+export type { Logger } from './logger';
+export { EngineError, AccessDeniedError, GovernanceNotEnabledError, isEngineError, isAccessDenied, isGovernanceNotEnabled, looksLikeGovernanceNotEnabled, } from './errors';
+export type { EngineCapabilities, EngineChainNode, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EventIngest, EntityPlacement, GovernanceEngine, } from './engine/engine';
+export { unitsPerTokens, vendorMetrics, emptyTokenUsage, entitlementId, entitlementKind, entitlementRef, toMeasurement, } from './types';
+export type { AgentBudget, AgentOptions, AgentScope, ClientGovernance, CheckErrorAction, ClientOptions, DecisionSource, DeregisterInput, Entitlement, AccessDecision, Remedy, WrappedClient, IngestContext, IngestMode, IngestResult, Measurement, RegisterInput, GatedSurface, ChatOf, CallContext, TokenUsage, Metrics, MetricsMapper, } from './types';
+export { wrapClient } from './bindings/client/core/wrap-client';
+export { createClientRegistry, hasMethod } from './bindings/client/core/registry';
+export type { ClientRecipe, ClientRegistry, MethodRecipe, MetricsFor, MetricsOf, MeteredResponse, } from './bindings/client/core/types';
+export type { ObservedVendor } from './bindings/shared/token-usage';
+export { anthropicRecipe, estimateFromMaxTokens } from './bindings/client/providers/anthropic/anthropic-recipe';
+export type { AnthropicMetric, AnthropicMetrics } from './bindings/client/providers/anthropic/anthropic-recipe';
+export { openAIRecipe } from './bindings/client/providers/openai/openai-recipe';
+export type { OpenAIMetric, OpenAIMetrics } from './bindings/client/providers/openai/openai-recipe';
+export { geminiRecipe, geminiChatRecipe, estimateFromMaxOutputTokens, } from './bindings/client/providers/gemini/gemini-recipe';
+export type { GeminiMetric, GeminiMetrics } from './bindings/client/providers/gemini/gemini-recipe';
+export { openrouterRecipe } from './bindings/client/gateways/openrouter/openrouter-recipe';
+export type { OpenRouterMetric, OpenRouterMetrics } from './bindings/client/gateways/openrouter/openrouter-recipe';
+export type { OpenRouterRecipeOptions } from './bindings/client/gateways/openrouter/types';
+export { litellmRecipe } from './bindings/client/gateways/litellm/litellm-recipe';
+export type { LiteLLMMetric, LiteLLMMetrics } from './bindings/client/gateways/litellm/litellm-recipe';
+export type { LiteLLMRecipeOptions } from './bindings/client/gateways/litellm/types';
+export { groqRecipe } from './bindings/client/providers/groq/groq-recipe';
+export type { GroqMetric, GroqMetrics } from './bindings/client/providers/groq/groq-recipe';
+export { mistralRecipe } from './bindings/client/providers/mistral/mistral-recipe';
+export type { MistralMetric, MistralMetrics } from './bindings/client/providers/mistral/mistral-recipe';
+export { ollamaRecipe } from './bindings/client/providers/ollama/ollama-recipe';
+export type { OllamaMetric, OllamaMetrics } from './bindings/client/providers/ollama/ollama-recipe';
+export { bedrockRecipe } from './bindings/client/gateways/bedrock/bedrock-recipe';
+export type { BedrockMetricName, BedrockMetrics } from './bindings/client/gateways/bedrock/bedrock-recipe';
+export type { BedrockRecipeOptions } from './bindings/client/gateways/bedrock/types';
+export { typesafeRecipe, estimateFromState } from './bindings/client/providers/typesafe/typesafe-recipe';
+export type { TypeSafeMetric, TypeSafeMetrics } from './bindings/client/providers/typesafe/typesafe-recipe';
+export { weightedMetrics } from './bindings/shared/weighted-metrics';
+export type { WeightedMetricsOptions } from './bindings/shared/weighted-metrics';
+export type { ProxyIngestInput } from './bindings/proxy';
+export { normalizedMetrics, normalizeUsage } from './bindings/shared/token-usage';

package/dist/index.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.bedrockRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
+/**
+ * Public surface.
+ *
+ * Importing this file pulls in no vendor package. The recipes below are exported from here, but
+ * each one is duck-typed against the shape a vendor returns rather than written against its SDK,
+ * so `@anthropic-ai/sdk`, `openai` and the rest stay out of the dependency tree entirely.
+ *
+ * What is exported here is the vocabulary, the client, and the seams worth extending: a recipe,
+ * a metrics mapper, a `GovernanceEngine`. The implementations behind those seams - the concrete
+ * engines, decision construction, config resolution, the metric tables - live in
+ * `@stigg/agent-sdk-js/internal`, under a weaker compatibility promise.
+ */
+var stigg_agent_sdk_1 = require("./stigg-agent-sdk");
+Object.defineProperty(exports, "StiggAgentSDK", { enumerable: true, get: function () { return stigg_agent_sdk_1.StiggAgentSDK; } });
+// What an event carries off the vendor's own usage object, for anyone building the payload by hand.
+var dimensions_1 = require("./core/dimensions");
+Object.defineProperty(exports, "RAW_PREFIX", { enumerable: true, get: function () { return dimensions_1.RAW_PREFIX; } });
+Object.defineProperty(exports, "flattenRaw", { enumerable: true, get: function () { return dimensions_1.flattenRaw; } });
+var decision_text_1 = require("./decision-text");
+Object.defineProperty(exports, "describeDecision", { enumerable: true, get: function () { return decision_text_1.describeDecision; } });
+Object.defineProperty(exports, "remedyMessage", { enumerable: true, get: function () { return decision_text_1.remedyMessage; } });
+var headers_1 = require("./headers");
+Object.defineProperty(exports, "GOVERNANCE_HEADERS", { enumerable: true, get: function () { return headers_1.GOVERNANCE_HEADERS; } });
+Object.defineProperty(exports, "parseGovernanceHeaders", { enumerable: true, get: function () { return headers_1.parseGovernanceHeaders; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "consoleLogger", { enumerable: true, get: function () { return logger_1.consoleLogger; } });
+Object.defineProperty(exports, "noopLogger", { enumerable: true, get: function () { return logger_1.noopLogger; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "EngineError", { enumerable: true, get: function () { return errors_1.EngineError; } });
+Object.defineProperty(exports, "AccessDeniedError", { enumerable: true, get: function () { return errors_1.AccessDeniedError; } });
+Object.defineProperty(exports, "GovernanceNotEnabledError", { enumerable: true, get: function () { return errors_1.GovernanceNotEnabledError; } });
+Object.defineProperty(exports, "isEngineError", { enumerable: true, get: function () { return errors_1.isEngineError; } });
+Object.defineProperty(exports, "isAccessDenied", { enumerable: true, get: function () { return errors_1.isAccessDenied; } });
+Object.defineProperty(exports, "isGovernanceNotEnabled", { enumerable: true, get: function () { return errors_1.isGovernanceNotEnabled; } });
+Object.defineProperty(exports, "looksLikeGovernanceNotEnabled", { enumerable: true, get: function () { return errors_1.looksLikeGovernanceNotEnabled; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "unitsPerTokens", { enumerable: true, get: function () { return types_1.unitsPerTokens; } });
+Object.defineProperty(exports, "vendorMetrics", { enumerable: true, get: function () { return types_1.vendorMetrics; } });
+Object.defineProperty(exports, "emptyTokenUsage", { enumerable: true, get: function () { return types_1.emptyTokenUsage; } });
+Object.defineProperty(exports, "entitlementId", { enumerable: true, get: function () { return types_1.entitlementId; } });
+Object.defineProperty(exports, "entitlementKind", { enumerable: true, get: function () { return types_1.entitlementKind; } });
+Object.defineProperty(exports, "entitlementRef", { enumerable: true, get: function () { return types_1.entitlementRef; } });
+Object.defineProperty(exports, "toMeasurement", { enumerable: true, get: function () { return types_1.toMeasurement; } });
+// Bindings: the generic halves only.
+var wrap_client_1 = require("./bindings/client/core/wrap-client");
+Object.defineProperty(exports, "wrapClient", { enumerable: true, get: function () { return wrap_client_1.wrapClient; } });
+var registry_1 = require("./bindings/client/core/registry");
+Object.defineProperty(exports, "createClientRegistry", { enumerable: true, get: function () { return registry_1.createClientRegistry; } });
+Object.defineProperty(exports, "hasMethod", { enumerable: true, get: function () { return registry_1.hasMethod; } });
+var anthropic_recipe_1 = require("./bindings/client/providers/anthropic/anthropic-recipe");
+Object.defineProperty(exports, "anthropicRecipe", { enumerable: true, get: function () { return anthropic_recipe_1.anthropicRecipe; } });
+Object.defineProperty(exports, "estimateFromMaxTokens", { enumerable: true, get: function () { return anthropic_recipe_1.estimateFromMaxTokens; } });
+var openai_recipe_1 = require("./bindings/client/providers/openai/openai-recipe");
+Object.defineProperty(exports, "openAIRecipe", { enumerable: true, get: function () { return openai_recipe_1.openAIRecipe; } });
+// Two recipes for one vendor, because a `GoogleGenAI` client and a `Chat` it created share no
+// method - and a chat holds the *unwrapped* models module privately, so wrapping the client alone
+// would leave every conversation ungoverned. Wrap the chat as well: `stigg.wrap(ai.chats.create(…))`.
+var gemini_recipe_1 = require("./bindings/client/providers/gemini/gemini-recipe");
+Object.defineProperty(exports, "geminiRecipe", { enumerable: true, get: function () { return gemini_recipe_1.geminiRecipe; } });
+Object.defineProperty(exports, "geminiChatRecipe", { enumerable: true, get: function () { return gemini_recipe_1.geminiChatRecipe; } });
+Object.defineProperty(exports, "estimateFromMaxOutputTokens", { enumerable: true, get: function () { return gemini_recipe_1.estimateFromMaxOutputTokens; } });
+// A default: it reports the same token counters as every other vendor, and adds what only a
+// gateway knows - the model that served, the request id, and the `cost` it charged. Billing that
+// cost instead of the tokens is a mapper away, and never inferred from a base URL:
+// `weightedMetrics(openrouterRecipe(), 'credits', { cost: 1 })`.
+var openrouter_recipe_1 = require("./bindings/client/gateways/openrouter/openrouter-recipe");
+Object.defineProperty(exports, "openrouterRecipe", { enumerable: true, get: function () { return openrouter_recipe_1.openrouterRecipe; } });
+// A default too, on the same terms. Its `cost` comes from `x-litellm-response-cost`, which a
+// streamed call cannot carry because headers precede the body - so a run billing cost gets
+// nothing from a stream. Name it at `wrap(client, { recipe })` to give it your proxy's base URL.
+var litellm_recipe_1 = require("./bindings/client/gateways/litellm/litellm-recipe");
+Object.defineProperty(exports, "litellmRecipe", { enumerable: true, get: function () { return litellm_recipe_1.litellmRecipe; } });
+// Built in, and matched by hostname ahead of `openAIRecipe` so its traffic reports as `groq.*`.
+// A provider that speaks the OpenAI wire format: same counters, its own vendor name, and one
+// surface, because `chat.completions.create` is the only generation endpoint Groq serves.
+var groq_recipe_1 = require("./bindings/client/providers/groq/groq-recipe");
+Object.defineProperty(exports, "groqRecipe", { enumerable: true, get: function () { return groq_recipe_1.groqRecipe; } });
+// Built in. Eight generation surfaces over one usage block, reported under the *wire's* names
+// rather than the camelCase its generated SDK renames them to - see the recipe for why, and for
+// the two call styles it cannot reach (the standalone `funcs/` form, and a stream read by hand).
+var mistral_recipe_1 = require("./bindings/client/providers/mistral/mistral-recipe");
+Object.defineProperty(exports, "mistralRecipe", { enumerable: true, get: function () { return mistral_recipe_1.mistralRecipe; } });
+// Built in. A self-hosted engine rather than a vendor that bills: `chat` and `generate` are flat
+// methods on the client, and the counters they report measure the customer's own capacity, since
+// there is no invoice behind them. See the recipe for the surfaces it declines and why.
+var ollama_recipe_1 = require("./bindings/client/providers/ollama/ollama-recipe");
+Object.defineProperty(exports, "ollamaRecipe", { enumerable: true, get: function () { return ollama_recipe_1.ollamaRecipe; } });
+// A default too, and the gateway that states no price. Bedrock's client is a command bus rather
+// than a method tree, so the recipe gates `send` and reads the command to tell inference from the
+// rest of the API; it reports Bedrock's own token counters and no `cost`, because there is none on
+// the response to report. See the recipe for what that means for a run that wanted to bill spend.
+var bedrock_recipe_1 = require("./bindings/client/gateways/bedrock/bedrock-recipe");
+Object.defineProperty(exports, "bedrockRecipe", { enumerable: true, get: function () { return bedrock_recipe_1.bedrockRecipe; } });
+// Built in as well. One method, no stream, and two counters - see the recipe for why a
+// question-answering API has neither a cache counter nor a cost to report.
+var typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe-recipe");
+Object.defineProperty(exports, "typesafeRecipe", { enumerable: true, get: function () { return typesafe_recipe_1.typesafeRecipe; } });
+Object.defineProperty(exports, "estimateFromState", { enumerable: true, get: function () { return typesafe_recipe_1.estimateFromState; } });
+var weighted_metrics_1 = require("./bindings/shared/weighted-metrics");
+Object.defineProperty(exports, "weightedMetrics", { enumerable: true, get: function () { return weighted_metrics_1.weightedMetrics; } });
+var token_usage_1 = require("./bindings/shared/token-usage");
+Object.defineProperty(exports, "normalizedMetrics", { enumerable: true, get: function () { return token_usage_1.normalizedMetrics; } });
+Object.defineProperty(exports, "normalizeUsage", { enumerable: true, get: function () { return token_usage_1.normalizeUsage; } });

package/dist/internal.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal surface - `@stigg/agent-sdk-js/internal`.
+ *
+ * Everything here is an implementation detail: the concrete engines behind the `GovernanceEngine`
+ * seam, the pure functions that build a decision, config resolution, and the metric tables the
+ * recipes are written against. It is exported because the tests and anyone extending the SDK need
+ * to reach it, and reaching into `dist/` by path is worse than a named door.
+ *
+ * The contract is weaker than `index.ts`: these names can change in a minor release. Anything you
+ * can do from the public barrel, do from there instead.
+ */
+export { createGovernanceEngine } from './engine/create-engine';
+export type { CreatedEngine, EngineClientOptions } from './engine/create-engine';
+export { CompositeEngine } from './engine/composite-engine';
+export { NodeSdkEngine } from './engine/node-sdk-engine';
+export { RestGovernanceEngine } from './engine/rest-governance-engine';
+export { describeResolution } from './engine/engine';
+export type { EngineOpSource } from './engine/engine';
+export { withDecisionText, policyDecision, remedyFor, toDecision, unenforcedDecision } from './engine/decision';
+export type { DecisionContext } from './engine/decision';
+export { resolveConfig } from './config';
+export type { ResolvedConfig, EngineConfig } from './config';
+export { isTransportFailure, isMeterMismatchError, asEngineError } from './errors';
+export { prefixed } from './logger';
+export { noCustomer, overrideContext, resolveContext, isEnforced } from './core/context';
+export type { ResolvedContext } from './core/context';
+export { GovernanceSession } from './core/session';
+export type { SessionDeps } from './core/session';
+export { ANTHROPIC_METRICS, GEMINI_METRICS, MISTRAL_METRICS, MISTRAL_METRIC_NAME_MAP, OLLAMA_METRICS, TYPESAFE_METRICS, GATEWAY_METRICS, OPENAI_CHAT_METRICS, OPENAI_METRICS, OPENAI_RESPONSES_METRICS, METRIC_PATHS, metricName, metricNamesMatchPaths, pickMetrics, pickRenamedMetrics, addMetrics, addTokenUsage, fromFlatTokenUsage, fromGeminiUsage, fromLangChainUsage, fromMistralUsage, fromOllamaUsage, fromOpenAIUsage, fromResponsesUsage, observedMeasurement, } from './bindings/shared/token-usage';
+export type { ObservedVendor } from './bindings/shared/token-usage';
+export { DEFAULT_RECIPES } from './stigg-agent-sdk';
+export { meterStream } from './bindings/shared/meter-stream';
+export { eventNameFor } from './bindings/client/core/types';

package/dist/internal.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Internal surface - `@stigg/agent-sdk-js/internal`.
+ *
+ * Everything here is an implementation detail: the concrete engines behind the `GovernanceEngine`
+ * seam, the pure functions that build a decision, config resolution, and the metric tables the
+ * recipes are written against. It is exported because the tests and anyone extending the SDK need
+ * to reach it, and reaching into `dist/` by path is worse than a named door.
+ *
+ * The contract is weaker than `index.ts`: these names can change in a minor release. Anything you
+ * can do from the public barrel, do from there instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventNameFor = exports.meterStream = exports.DEFAULT_RECIPES = exports.observedMeasurement = exports.fromResponsesUsage = exports.fromOpenAIUsage = exports.fromOllamaUsage = exports.fromMistralUsage = exports.fromLangChainUsage = exports.fromGeminiUsage = exports.fromFlatTokenUsage = exports.addTokenUsage = exports.addMetrics = exports.pickRenamedMetrics = exports.pickMetrics = exports.metricNamesMatchPaths = exports.metricName = exports.METRIC_PATHS = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_METRICS = exports.OPENAI_CHAT_METRICS = exports.GATEWAY_METRICS = exports.TYPESAFE_METRICS = exports.OLLAMA_METRICS = exports.MISTRAL_METRIC_NAME_MAP = exports.MISTRAL_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.GovernanceSession = exports.isEnforced = exports.resolveContext = exports.overrideContext = exports.noCustomer = exports.prefixed = exports.asEngineError = exports.isMeterMismatchError = exports.isTransportFailure = exports.resolveConfig = exports.unenforcedDecision = exports.toDecision = exports.remedyFor = exports.policyDecision = exports.withDecisionText = exports.describeResolution = exports.RestGovernanceEngine = exports.NodeSdkEngine = exports.CompositeEngine = exports.createGovernanceEngine = void 0;
+// The engine seam's implementations. The interface itself is public - see `index.ts`.
+var create_engine_1 = require("./engine/create-engine");
+Object.defineProperty(exports, "createGovernanceEngine", { enumerable: true, get: function () { return create_engine_1.createGovernanceEngine; } });
+var composite_engine_1 = require("./engine/composite-engine");
+Object.defineProperty(exports, "CompositeEngine", { enumerable: true, get: function () { return composite_engine_1.CompositeEngine; } });
+var node_sdk_engine_1 = require("./engine/node-sdk-engine");
+Object.defineProperty(exports, "NodeSdkEngine", { enumerable: true, get: function () { return node_sdk_engine_1.NodeSdkEngine; } });
+var rest_governance_engine_1 = require("./engine/rest-governance-engine");
+Object.defineProperty(exports, "RestGovernanceEngine", { enumerable: true, get: function () { return rest_governance_engine_1.RestGovernanceEngine; } });
+var engine_1 = require("./engine/engine");
+Object.defineProperty(exports, "describeResolution", { enumerable: true, get: function () { return engine_1.describeResolution; } });
+// Engine result -> the structured refusal, as pure functions.
+var decision_1 = require("./engine/decision");
+Object.defineProperty(exports, "withDecisionText", { enumerable: true, get: function () { return decision_1.withDecisionText; } });
+Object.defineProperty(exports, "policyDecision", { enumerable: true, get: function () { return decision_1.policyDecision; } });
+Object.defineProperty(exports, "remedyFor", { enumerable: true, get: function () { return decision_1.remedyFor; } });
+Object.defineProperty(exports, "toDecision", { enumerable: true, get: function () { return decision_1.toDecision; } });
+Object.defineProperty(exports, "unenforcedDecision", { enumerable: true, get: function () { return decision_1.unenforcedDecision; } });
+// Config resolution: the target and the options, as the transport actually needs them.
+var config_1 = require("./config");
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+// Error predicates that describe transport and enablement, not the caller's contract.
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "isTransportFailure", { enumerable: true, get: function () { return errors_1.isTransportFailure; } });
+Object.defineProperty(exports, "isMeterMismatchError", { enumerable: true, get: function () { return errors_1.isMeterMismatchError; } });
+Object.defineProperty(exports, "asEngineError", { enumerable: true, get: function () { return errors_1.asEngineError; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "prefixed", { enumerable: true, get: function () { return logger_1.prefixed; } });
+// Context resolution: the split that keeps a gated call's own overhead to a property read.
+var context_1 = require("./core/context");
+Object.defineProperty(exports, "noCustomer", { enumerable: true, get: function () { return context_1.noCustomer; } });
+Object.defineProperty(exports, "overrideContext", { enumerable: true, get: function () { return context_1.overrideContext; } });
+Object.defineProperty(exports, "resolveContext", { enumerable: true, get: function () { return context_1.resolveContext; } });
+Object.defineProperty(exports, "isEnforced", { enumerable: true, get: function () { return context_1.isEnforced; } });
+var session_1 = require("./core/session");
+Object.defineProperty(exports, "GovernanceSession", { enumerable: true, get: function () { return session_1.GovernanceSession; } });
+// What each vendor calls its counters, and where they are read from. A recipe is written against
+// these; a consumer reads `recipe.metrics` instead.
+var token_usage_1 = require("./bindings/shared/token-usage");
+Object.defineProperty(exports, "ANTHROPIC_METRICS", { enumerable: true, get: function () { return token_usage_1.ANTHROPIC_METRICS; } });
+Object.defineProperty(exports, "GEMINI_METRICS", { enumerable: true, get: function () { return token_usage_1.GEMINI_METRICS; } });
+Object.defineProperty(exports, "MISTRAL_METRICS", { enumerable: true, get: function () { return token_usage_1.MISTRAL_METRICS; } });
+Object.defineProperty(exports, "MISTRAL_METRIC_NAME_MAP", { enumerable: true, get: function () { return token_usage_1.MISTRAL_METRIC_NAME_MAP; } });
+Object.defineProperty(exports, "OLLAMA_METRICS", { enumerable: true, get: function () { return token_usage_1.OLLAMA_METRICS; } });
+Object.defineProperty(exports, "TYPESAFE_METRICS", { enumerable: true, get: function () { return token_usage_1.TYPESAFE_METRICS; } });
+Object.defineProperty(exports, "GATEWAY_METRICS", { enumerable: true, get: function () { return token_usage_1.GATEWAY_METRICS; } });
+Object.defineProperty(exports, "OPENAI_CHAT_METRICS", { enumerable: true, get: function () { return token_usage_1.OPENAI_CHAT_METRICS; } });
+Object.defineProperty(exports, "OPENAI_METRICS", { enumerable: true, get: function () { return token_usage_1.OPENAI_METRICS; } });
+Object.defineProperty(exports, "OPENAI_RESPONSES_METRICS", { enumerable: true, get: function () { return token_usage_1.OPENAI_RESPONSES_METRICS; } });
+Object.defineProperty(exports, "METRIC_PATHS", { enumerable: true, get: function () { return token_usage_1.METRIC_PATHS; } });
+Object.defineProperty(exports, "metricName", { enumerable: true, get: function () { return token_usage_1.metricName; } });
+Object.defineProperty(exports, "metricNamesMatchPaths", { enumerable: true, get: function () { return token_usage_1.metricNamesMatchPaths; } });
+Object.defineProperty(exports, "pickMetrics", { enumerable: true, get: function () { return token_usage_1.pickMetrics; } });
+Object.defineProperty(exports, "pickRenamedMetrics", { enumerable: true, get: function () { return token_usage_1.pickRenamedMetrics; } });
+Object.defineProperty(exports, "addMetrics", { enumerable: true, get: function () { return token_usage_1.addMetrics; } });
+Object.defineProperty(exports, "addTokenUsage", { enumerable: true, get: function () { return token_usage_1.addTokenUsage; } });
+Object.defineProperty(exports, "fromFlatTokenUsage", { enumerable: true, get: function () { return token_usage_1.fromFlatTokenUsage; } });
+Object.defineProperty(exports, "fromGeminiUsage", { enumerable: true, get: function () { return token_usage_1.fromGeminiUsage; } });
+Object.defineProperty(exports, "fromLangChainUsage", { enumerable: true, get: function () { return token_usage_1.fromLangChainUsage; } });
+Object.defineProperty(exports, "fromMistralUsage", { enumerable: true, get: function () { return token_usage_1.fromMistralUsage; } });
+Object.defineProperty(exports, "fromOllamaUsage", { enumerable: true, get: function () { return token_usage_1.fromOllamaUsage; } });
+Object.defineProperty(exports, "fromOpenAIUsage", { enumerable: true, get: function () { return token_usage_1.fromOpenAIUsage; } });
+Object.defineProperty(exports, "fromResponsesUsage", { enumerable: true, get: function () { return token_usage_1.fromResponsesUsage; } });
+Object.defineProperty(exports, "observedMeasurement", { enumerable: true, get: function () { return token_usage_1.observedMeasurement; } });
+// The recipes `wrap` matches against when no recipe is named. Exposed so a caller - the examples'
+// own offline seeding, above all - can enumerate what this package governs without keeping a
+// second copy of the list that silently falls behind each time a vendor is added.
+var stigg_agent_sdk_1 = require("./stigg-agent-sdk");
+Object.defineProperty(exports, "DEFAULT_RECIPES", { enumerable: true, get: function () { return stigg_agent_sdk_1.DEFAULT_RECIPES; } });
+var meter_stream_1 = require("./bindings/shared/meter-stream");
+Object.defineProperty(exports, "meterStream", { enumerable: true, get: function () { return meter_stream_1.meterStream; } });
+var types_1 = require("./bindings/client/core/types");
+Object.defineProperty(exports, "eventNameFor", { enumerable: true, get: function () { return types_1.eventNameFor; } });

package/dist/logger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The smallest logger the SDK can depend on. Structural, so any console-shaped object - or a
+ * pino/winston child - satisfies it without an adapter.
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** What `logger: 'none'` resolves to, for a process that wants the SDK silent. */
+export declare const noopLogger: Logger;
+export declare const consoleLogger: Logger;
+/** Prefixes every line, so example output shows which subsystem spoke. */
+export declare const prefixed: (logger: Logger, prefix: string) => Logger;

package/dist/logger.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefixed = exports.consoleLogger = exports.noopLogger = void 0;
+const noop = () => undefined;
+/** What `logger: 'none'` resolves to, for a process that wants the SDK silent. */
+exports.noopLogger = { debug: noop, info: noop, warn: noop, error: noop };
+exports.consoleLogger = {
+    debug: (message, ...args) => console.debug(message, ...args),
+    info: (message, ...args) => console.log(message, ...args),
+    warn: (message, ...args) => console.warn(message, ...args),
+    error: (message, ...args) => console.error(message, ...args),
+};
+/** Prefixes every line, so example output shows which subsystem spoke. */
+const prefixed = (logger, prefix) => ({
+    debug: (message, ...args) => logger.debug(`${prefix} ${message}`, ...args),
+    info: (message, ...args) => logger.info(`${prefix} ${message}`, ...args),
+    warn: (message, ...args) => logger.warn(`${prefix} ${message}`, ...args),
+    error: (message, ...args) => logger.error(`${prefix} ${message}`, ...args),
+});
+exports.prefixed = prefixed;