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

package/dist/sdk-identity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a Stigg deployment can tell this SDK's traffic apart from everything else's.
+ *
+ * There is no analytics pipeline here and this is not one: nothing is emitted, nothing is batched,
+ * nothing fires on a schedule. Adoption is read off the requests the SDK was already making, which
+ * is the same answer the Node server SDK and the sidecar give - identity rides along on headers,
+ * so there is no second network path to fail, no payload to review for what it collects, and
+ * nothing to disable.
+ *
+ * Without this, an agent-sdk install is invisible: its GraphQL half reports as a plain
+ * `node-server-sdk` client, and its REST half carries no Stigg identity at all.
+ */
+/**
+ * This package's own version, read from its manifest rather than restated here - a constant would
+ * have to be remembered on every release, and the one release where it is not is the release the
+ * numbers quietly stop meaning anything.
+ *
+ * `dist/sdk-identity.js` and `src/sdk-identity.ts` both sit one directory under the package root,
+ * so the same relative path works built and from source.
+ */
+export declare const AGENT_SDK_VERSION: string;
+/**
+ * Deliberately not `SourceType.AgentSdk`: that enum lives in Stigg's GraphQL schema, the API
+ * groups on it, and there is no member for this SDK. Adding one is a server change that has to
+ * land first, so the client name is what carries the distinction in the meantime - exactly the
+ * trade the sidecar made when it started naming itself.
+ */
+export declare const AGENT_SDK_CLIENT_NAME = "agent-sdk-js";
+/**
+ * The REST client's equivalent, since it has no client-awareness convention of its own.
+ *
+ * Named into the `X-SDK-` family the GraphQL transport already sends, so both halves of one
+ * agent-sdk process are recognizable the same way. Nothing on the server branches on these; they
+ * arrive as trace tags, which is all identity needs to be.
+ */
+export declare const AGENT_SDK_REST_HEADERS: Record<string, string>;

package/dist/sdk-identity.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * How a Stigg deployment can tell this SDK's traffic apart from everything else's.
+ *
+ * There is no analytics pipeline here and this is not one: nothing is emitted, nothing is batched,
+ * nothing fires on a schedule. Adoption is read off the requests the SDK was already making, which
+ * is the same answer the Node server SDK and the sidecar give - identity rides along on headers,
+ * so there is no second network path to fail, no payload to review for what it collects, and
+ * nothing to disable.
+ *
+ * Without this, an agent-sdk install is invisible: its GraphQL half reports as a plain
+ * `node-server-sdk` client, and its REST half carries no Stigg identity at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_SDK_REST_HEADERS = exports.AGENT_SDK_CLIENT_NAME = exports.AGENT_SDK_VERSION = void 0;
+/**
+ * This package's own version, read from its manifest rather than restated here - a constant would
+ * have to be remembered on every release, and the one release where it is not is the release the
+ * numbers quietly stop meaning anything.
+ *
+ * `dist/sdk-identity.js` and `src/sdk-identity.ts` both sit one directory under the package root,
+ * so the same relative path works built and from source.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+exports.AGENT_SDK_VERSION = require('../package.json').version;
+/**
+ * Deliberately not `SourceType.AgentSdk`: that enum lives in Stigg's GraphQL schema, the API
+ * groups on it, and there is no member for this SDK. Adding one is a server change that has to
+ * land first, so the client name is what carries the distinction in the meantime - exactly the
+ * trade the sidecar made when it started naming itself.
+ */
+exports.AGENT_SDK_CLIENT_NAME = 'agent-sdk-js';
+/**
+ * The REST client's equivalent, since it has no client-awareness convention of its own.
+ *
+ * Named into the `X-SDK-` family the GraphQL transport already sends, so both halves of one
+ * agent-sdk process are recognizable the same way. Nothing on the server branches on these; they
+ * arrive as trace tags, which is all identity needs to be.
+ */
+exports.AGENT_SDK_REST_HEADERS = {
+    'X-SDK-CLIENT-NAME': exports.AGENT_SDK_CLIENT_NAME,
+    'X-SDK-CLIENT-VERSION': exports.AGENT_SDK_VERSION,
+};

package/dist/stigg-agent-sdk.d.ts

@@ -0,0 +1,300 @@
+import { type ResolvedConfig, type StiggAgentSDKOptions } from './config';
+import { type EngineResolution, type GovernanceEngine } from './engine/engine';
+import type { StiggContext } from './core/context';
+import type { SessionSummary } from './core/session';
+import type { Metrics, ClientOptions, DeregisterInput, AccessDecision, WrappedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
+import type { GovernanceHeaders } from './headers';
+/**
+ * Recipes are data - method paths and usage extractors - so wiring them here costs nothing at
+ * runtime and pulls in no vendor package. An orchestration adapter is different: it needs its
+ * framework loaded, so it stays an explicit subpath import.
+ */
+/**
+ * Order matters: the gateways are matched before the plain OpenAI adapter, because every one of
+ * them *is* an OpenAI client by shape and only the base URL says which. The bare adapter would
+ * otherwise claim them and lose what only a gateway knows - the model that actually served after
+ * routing, and the gateway's own request id.
+ *
+ * Matching them costs nothing in units: they report what the gateway stated and leave what it is
+ * worth to the run's mapper, like every other vendor. Billing the `cost` they add rather than the
+ * tokens is that mapper's business, and stays the caller's to decide.
+ */
+export declare const DEFAULT_RECIPES: ({
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: string[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("./types").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    }[];
+} | {
+    vendor: string;
+    metrics: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+    totalTokensMetric: "totalTokenCount";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["models", "generateContent"];
+        extractUsage: (result: any) => import("./types").Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    } | {
+        path: readonly ["models", "generateContentStream"];
+        extractUsage: (result: any) => import("./types").Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    })[];
+} | {
+    vendor: string;
+    metrics: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+    totalTokensMetric: "totalTokenCount";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["sendMessage"];
+        event: string;
+        extractUsage: (result: any) => import("./types").Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    } | {
+        path: readonly ["sendMessageStream"];
+        event: string;
+        extractUsage: (result: any) => import("./types").Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    })[];
+} | {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: ("create" | "chat" | "completions" | "responses")[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("./types").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    }[];
+} | import("./bindings/client/core/types").ClientRecipe<"cached_tokens" | "prompt_tokens" | "completion_tokens" | "input_tokens" | "output_tokens" | "total_tokens" | "cost"> | {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: ("create" | "chat" | "completions")[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("./types").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
+    }[];
+} | {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        attachStream: (stream: unknown, ingest: (measurement: import("./types").Measurement) => void) => void;
+        extractUsage?: undefined;
+    } | {
+        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        extractUsage: (result: import("./bindings/client/providers/mistral/types").MistralCompletionResponse | undefined) => import("./types").Measurement | undefined;
+        attachStream?: undefined;
+    })[];
+} | {
+    vendor: string;
+    metrics: readonly ["prompt_eval_count", "eval_count", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["chat"];
+        extractUsage: (result: import("./bindings/client/providers/ollama/types").OllamaResponse | undefined) => import("./types").Measurement | undefined;
+        attachStream: (stream: unknown, ingest: (measurement: import("./types").Measurement) => void) => void;
+    } | {
+        path: readonly ["generate"];
+        extractUsage: (result: import("./bindings/client/providers/ollama/types").OllamaResponse | undefined) => import("./types").Measurement | undefined;
+        attachStream: (stream: unknown, ingest: (measurement: import("./types").Measurement) => void) => void;
+    })[];
+} | import("./bindings/client/core/types").ClientRecipe<"totalTokens" | "inputTokens" | "outputTokens" | "cacheReadInputTokens" | "cacheWriteInputTokens"> | {
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: string[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("./types").TokenUsage;
+            raw: any;
+        } | undefined;
+    }[];
+})[];
+export declare class StiggAgentSDK {
+    readonly config: ResolvedConfig;
+    private readonly clients;
+    /** Every session this SDK handed out, so `flush()` can drain all of them at once. */
+    private readonly sessions;
+    /** The session the no-client paths share. Built on first use. */
+    private loose?;
+    /**
+     * `customer:agent` -> what was last said about that agent, so a repeat of the same description
+     * is not written again per run. The value is a fingerprint of the describable attributes, not
+     * an id: the id is in the key.
+     */
+    private readonly registered;
+    /**
+     * Bare registrations still on the wire, so the burst of runs that opens a process writes once
+     * rather than once each. Only the memoized path is shared - see `register`.
+     */
+    private readonly registering;
+    private started?;
+    /**
+     * When the attempt currently in `started` rejected, or undefined while it is pending or has
+     * resolved. What makes a failed probe expire rather than persist - see `ensureStarted`.
+     */
+    private startFailedAt?;
+    private engineState?;
+    /**
+     * Synchronous - nothing here touches the network. The engine is built on the first call that
+     * needs it, so there is no awaited setup step to forget; `await init()` forces it early.
+     *
+     * Where this SDK sends its traffic comes first, because it is the only thing that cannot be
+     * inferred: a server key, a `{ baseUrl }` target that needs none, or nothing at all to read
+     * `STIGG_SERVER_API_KEY`. A key that belongs to somewhere other than
+     * the hosted API names that URL second - the two together are one idea, so neither is buried
+     * among the tuning knobs that follow.
+     *
+     * Construct one per environment and share it - the engine's cache and its connection pool are
+     * per instance, so a second one for the same environment is wasted rather than wrong.
+     */
+    constructor(options?: StiggAgentSDKOptions);
+    /** The shorthand, for a server key with nothing else to say about where it points. */
+    constructor(apiKey: string, options?: Omit<StiggAgentSDKOptions, 'apiKey'>);
+    /** Releases what this SDK's engine holds open. */
+    close(): Promise<void>;
+    /**
+     * Forces the engine to resolve now and reports which client serves what. Optional - every
+     * async call below does it anyway - but useful when you want the answer before the first run.
+     */
+    init(): Promise<EngineResolution>;
+    /** Undefined until the engine has resolved. `init()` returns it directly. */
+    get resolution(): EngineResolution | undefined;
+    /** Available after the engine has resolved; the bindings that need it only run after that. */
+    get engine(): GovernanceEngine;
+    /**
+     * Gives the agent an identity, a budget, and a place in the tree, and returns the agent id to
+     * open a run against.
+     *
+     * The id is the one you passed: nothing about the run depends on this call having happened, so
+     * returning it is a convenience rather than a handle. Skip `register` entirely and the agent
+     * has no entity - the run still works, and checks and usage apply to the customer instead.
+     *
+     * Idempotent, and remembered per process: an upsert is cheap, but it is still a write, so
+     * calling this on a hot path does not repeat it. A call carrying a budget or a parent always
+     * writes, because that is a deliberate change rather than a formality.
+     *
+     * `run.start(runOptions, agentOptions)` calls this for you with the run's own scope, which is
+     * the usual way in; reach for it directly to provision an agent no run is about to use.
+     */
+    register(input: RegisterInput): Promise<string>;
+    /**
+     * Removes the agent's entity. Optional, mirrors `register`, and never relied on: it may never
+     * fire - a crash, an abandoned stream, an interrupt that is never resumed - which is why warm
+     * state has a TTL rather than waiting to be released.
+     */
+    deregister(input: DeregisterInput): Promise<void>;
+    /**
+     * Governs a vendor client and hands back a copy whose calls are checked and metered.
+     *
+     * The whole lifecycle, in one step. `stiggContext` here is the default for every call through
+     * this client; any single call overrides it by putting its own `stiggContext` in the vendor's
+     * parameters. The client you passed is never mutated, so it keeps working ungoverned.
+     *
+     * The vendor is recognised from the client's own shape and base URL rather than named; pass
+     * `recipe` only for a vendor the built-ins cannot identify.
+     *
+     * Warms the entitlement cache before returning when the context names both a customer and an
+     * entitlement, so the calls that follow read local state. Nothing is cached in this package -
+     * see {@link GovernanceSession.warmUp} for which cache that is and when there is one at all.
+     */
+    wrap<T extends object, O extends ClientOptions>(client: T, options?: O): WrappedClient<T, O['stiggContext'], PathsOf<O['recipe'], T>>;
+    /**
+     * Hangs the governance handle off the wrapped client. Refuses to overwrite a `stigg` the vendor
+     * already has: silently replacing one of its own properties would be a worse surprise.
+     */
+    private attachGovernance;
+    /**
+     * The gate, with no client to wrap - what a framework binding reaches for, and what the gateway
+     * example checks with before it proxies.
+     */
+    check(context: StiggContext, requestedUsage?: number): Promise<AccessDecision>;
+    /** The meter, with no client to wrap. Metrics already in Stigg's own vocabulary. */
+    report(context: StiggContext, metrics: Metrics): Promise<IngestResult>;
+    /** The `x-stigg-*` attribution for work continuing in another process, with no client involved. */
+    governanceHeaders(context: StiggContext): GovernanceHeaders;
+    /**
+     * The policy a context falls back to when neither the call nor `wrap` named one.
+     *
+     * Both fields are always set - the config schema defaults them - so this is the one place a
+     * constructor option becomes the behaviour of a call. Before it existed the options were parsed,
+     * stored, and never read: every context fell through to the context module's own defaults, and a
+     * client constructed with `checkErrorAction: 'deny'` failed open on every call it gated.
+     */
+    private get contextDefaults();
+    private newSession;
+    /** The session the no-client paths share, built on first use so an unused SDK builds none. */
+    private standalone;
+    /**
+     * Returns the decision when `err` is a governance refusal, so a catch block is one line and the
+     * caller needs no import to tell a denial from a real failure.
+     */
+    denial(err: unknown): AccessDecision | undefined;
+    /**
+     * The gateway side of the split lifecycle: ingest usage a proxy observed, attributed from the
+     * headers the application sent with the request. Ingest only - a gateway sees requests, not
+     * runs, so there is nothing here to check against.
+     */
+    ingestFromHeaders(headers: Record<string, string | string[] | undefined>, input: IngestContext & {
+        usage: unknown;
+        idempotencyKey: string;
+        /** This report's outcome, including a failed one. The gateway's stand-in for a run hook. */
+        onIngest?: (result: IngestResult) => void;
+    }): Promise<IngestResult>;
+    /**
+     * A probe that failed with nobody waiting on it.
+     *
+     * `wrap()` returns before the engine resolves, so this is the one path where a startup failure
+     * has no caller to reject towards. Swallowing it silently would leave a client that looks
+     * governed and cannot check; letting it reject unobserved ends the process.
+     */
+    private reportStartupFailure;
+    /** `onError` is the application's too, and there is nowhere left to report its failure to. */
+    private reportIngestFailure;
+    /**
+     * Drains every wrapped client's in-flight ingests. Explicit because an exit hook does not fire
+     * in a request-scoped or serverless runtime.
+     *
+     * A single client drains on its own with `client.stigg.flush()`; this is the process-wide one,
+     * for a shutdown that does not know which clients exist.
+     */
+    flush(options?: {
+        close?: boolean;
+    }): Promise<SessionSummary[]>;
+    /**
+     * Builds the engine once, on first need. Concurrent callers share the same attempt.
+     *
+     * A *failed* attempt is shared too, but only for {@link RETRY_START_AFTER_MS}. A rejected
+     * promise is still a promise, so memoizing one unconditionally outlives the failure that caused
+     * it: under the default `checkErrorAction: 'allow'` the process stops enforcing any budget at
+     * all, and under `'deny'` it refuses every call - neither saying anything a log would show.
+     *
+     * Holding the failure briefly rather than discarding it on sight is the other half: callers
+     * inside the window get the same rejection immediately and their own `checkErrorAction` decides
+     * the outcome, so an outage is re-probed on a timer instead of once per request.
+     */
+    private ensureStarted;
+}