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

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

@@ -0,0 +1,242 @@
+import { type ResolvedConfig, type StiggAgentSDKOptions, type StiggTarget } from './config';
+import { type EngineResolution, type GovernanceEngine } from './engine/engine';
+import type { StiggContext } from './core/context';
+import type { GovernanceSummary } from './core/session';
+import type { Metrics, ClientOptions, DeregisterInput, GovernanceDecision, GovernedClient, 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 ["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?;
+    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`. See {@link StiggTarget}. 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(target?: StiggTarget, baseUrl?: string, options?: StiggAgentSDKOptions);
+    /** The same, for a target that already carries its URL - or one on the hosted API. */
+    constructor(target?: StiggTarget, options?: StiggAgentSDKOptions);
+    /** 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): GovernedClient<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<GovernanceDecision>;
+    /** 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): GovernanceDecision | 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<GovernanceSummary[]>;
+    /** Builds the engine once, on first need. Concurrent callers share the same attempt. */
+    private ensureStarted;
+}