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

package/dist/bindings/client/providers/openai/openai-recipe.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAIRecipe = exports.openAISurface = void 0;
+/**
+ * The OpenAI recipe - the second vendor, and the proof that the generic wrapper carries its
+ * weight: everything below is response-shape knowledge, with no gate logic repeated.
+ *
+ * Works against any OpenAI-compatible endpoint, a gateway included. Note that a gateway usually
+ * wants the ingest-only gateway binding instead: it sees requests, not runs.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const meter_stream_1 = require("../../../shared/meter-stream");
+const types_1 = require("../../../../types");
+const registry_1 = require("../../core/registry");
+/**
+ * The two surfaces, and where each keeps its usage.
+ *
+ * Chat Completions and Responses are the same API family with different field names, so the only
+ * thing that varies per surface is which extractor reads the counts and where a stream hides them.
+ */
+const SURFACES = [
+    {
+        path: ['chat', 'completions', 'create'],
+        parse: token_usage_1.fromOpenAIUsage,
+        keys: token_usage_1.METRIC_PATHS.openaiChat,
+        metrics: token_usage_1.OPENAI_CHAT_METRICS,
+        // Reported once, on the final chunk.
+        streamed: (chunk) => chunk?.usage,
+    },
+    {
+        path: ['responses', 'create'],
+        parse: token_usage_1.fromResponsesUsage,
+        keys: token_usage_1.METRIC_PATHS.openaiResponses,
+        metrics: token_usage_1.OPENAI_RESPONSES_METRICS,
+        // Reported on the completion event, which carries the whole response rather than a delta.
+        streamed: (chunk) => chunk?.response?.usage ?? chunk?.usage,
+    },
+];
+/** The reader for a surface, so a recipe built on top of this one stays in step with it. */
+const openAISurface = (path) => SURFACES.find((surface) => surface.path.join('.') === path.join('.')) ?? SURFACES[0];
+exports.openAISurface = openAISurface;
+exports.openAIRecipe = {
+    vendor: 'openai',
+    metrics: token_usage_1.OPENAI_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    // Either surface is enough: the recipe governs both, and a client built only for the Responses
+    // API has no `chat.completions` to find.
+    matches: (client) => (0, registry_1.hasMethod)(client, ['chat', 'completions', 'create']) || (0, registry_1.hasMethod)(client, ['responses', 'create']),
+    methods: SURFACES.map(({ path, parse, keys, streamed }) => ({
+        path: [...path],
+        // What OpenAI called it, which is what gets reported, beside the normalized counters. Note
+        // `prompt_tokens` includes the cached tokens reported next to it - the overlap is the
+        // vendor's, kept so the numbers reconcile against its own dashboard.
+        extractUsage: (result) => result?.usage
+            ? { metrics: (0, token_usage_1.pickMetrics)(result.usage, keys), usage: parse(result.usage), raw: result.usage }
+            : undefined,
+        attachStream: (stream, ingest) => {
+            let total = (0, types_1.emptyTokenUsage)();
+            let metrics = {};
+            // As on the non-streamed path, so a streamed turn states its usage just as fully - the
+            // counters this recipe does not name (`total_tokens`, the reasoning-token detail) reach a
+            // meter either way rather than only when the caller happened not to stream.
+            let raw;
+            (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                const usage = streamed(chunk);
+                // Reported once and whole rather than as deltas, so the last one wins outright - which
+                // is also what makes the block safe to keep as it arrived.
+                if (usage) {
+                    total = parse(usage);
+                    metrics = (0, token_usage_1.pickMetrics)(usage, keys);
+                    // Copied, not referenced - it is held until the stream ends, and the chunk it came
+                    // from belongs to the consumer. See the Gemini recipe for the full reasoning.
+                    raw = { ...usage };
+                }
+            }, 
+            // Absent rather than `undefined` when no chunk carried usage - see the Gemini recipe.
+            () => ingest({ metrics, usage: total, ...(raw ? { raw } : {}) }));
+        },
+    })),
+};

package/dist/bindings/client/providers/typesafe/typesafe-recipe.d.ts

@@ -0,0 +1,33 @@
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const typesafeRecipe: {
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: string[];
+        extractUsage: (result: any) => {
+            metrics: import("../../../..").Metrics;
+            usage: import("../../../..").TokenUsage;
+            raw: any;
+        } | undefined;
+    }[];
+};
+/**
+ * A pre-call estimate from the size of the document being asked about.
+ *
+ * Opt-in, like every estimate here, but note what makes this one different from a chat vendor's:
+ * there is no `max_tokens` to read, and the output is not where the money goes. A batch of
+ * questions against one document runs input-heavy by a wide margin - the document is sent once
+ * and each question adds almost nothing - so the state is the only part worth estimating, and
+ * estimating it is unusually reliable because it is already in hand before the call.
+ *
+ * `charsPerToken` is the usual rough divisor for English prose. Deliberately a floor: an estimate
+ * that overshoots denies calls the budget could have afforded, and the ingest that follows
+ * corrects the balance either way.
+ */
+export declare const estimateFromState: (tokensPerUnit?: number, charsPerToken?: number) => (params: any) => number;
+/** One of the metric names TypeSafe reports. */
+export type TypeSafeMetric = MetricsOf<typeof typesafeRecipe>;
+/** What a mapper reads off a TypeSafe call: those names, each possibly absent. */
+export type TypeSafeMetrics = MetricsFor<typeof typesafeRecipe>;

package/dist/bindings/client/providers/typesafe/typesafe-recipe.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateFromState = exports.typesafeRecipe = void 0;
+/**
+ * The TypeSafe recipe - the smallest one here, and worth reading for what it leaves out.
+ *
+ * TypeSafe is not chat-shaped. One `systemOne` call carries a document and a whole set of typed
+ * questions and comes back, once, with every answer and a single usage record. So there is one
+ * method to gate, no second call style reaching the wire through it, and no `attachStream`:
+ * nothing streams, so there is no later report to accumulate.
+ *
+ * The metrics are the two the API reports. That was checked against the wire, not inferred from
+ * the SDK's types - the response body carries `model`, `answers` and `usage`, and `usage` carries
+ * `input_tokens` and `output_tokens` and nothing else. No cache counters, because there is no
+ * prompt to cache across turns; no `cost`, because TypeSafe is not a gateway reselling someone
+ * else's model.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const estimate_1 = require("../../../shared/estimate");
+const registry_1 = require("../../core/registry");
+exports.typesafeRecipe = {
+    vendor: 'typesafe',
+    metrics: token_usage_1.TYPESAFE_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    // One distinctive method is the whole surface. Unlike Anthropic there is no second call style
+    // to prove, because `systemOne` is the only thing that reaches the wire carrying usage.
+    matches: (client) => (0, registry_1.hasMethod)(client, ['systemOne']),
+    methods: [
+        {
+            path: ['systemOne'],
+            // Both views of the call: TypeSafe's own names, which is what gets reported, and the
+            // normalized counters. The flat reader covers this shape exactly - the two cache counters
+            // it also looks for are absent here, which reads as zero, which is true.
+            extractUsage: (result) => result?.usage
+                ? {
+                    // No total is published here either, so one is added up from the two counters
+                    // that are - disjoint, so the sum is the whole call.
+                    metrics: (0, token_usage_1.withComputedTotal)((0, token_usage_1.pickMetrics)(result.usage, token_usage_1.METRIC_PATHS.typesafe), token_usage_1.COMPUTED_TOTALS.typesafe),
+                    usage: (0, token_usage_1.fromFlatTokenUsage)(result.usage),
+                    // Kept whole for an event to carry, the same as every other recipe.
+                    raw: result.usage,
+                }
+                : undefined,
+        },
+    ],
+};
+/**
+ * A pre-call estimate from the size of the document being asked about.
+ *
+ * Opt-in, like every estimate here, but note what makes this one different from a chat vendor's:
+ * there is no `max_tokens` to read, and the output is not where the money goes. A batch of
+ * questions against one document runs input-heavy by a wide margin - the document is sent once
+ * and each question adds almost nothing - so the state is the only part worth estimating, and
+ * estimating it is unusually reliable because it is already in hand before the call.
+ *
+ * `charsPerToken` is the usual rough divisor for English prose. Deliberately a floor: an estimate
+ * that overshoots denies calls the budget could have afforded, and the ingest that follows
+ * corrects the balance either way.
+ */
+const estimateFromState = (tokensPerUnit = 1, charsPerToken = 4) => {
+    // Its own divisor, refused on the same terms as the rate: a zero here divides inside the
+    // reading, which `requestedUnits` would clamp back to one unit just as quietly.
+    (0, estimate_1.requirePositiveRate)('charsPerToken', charsPerToken);
+    return (0, estimate_1.estimateUnits)((params) => {
+        const state = params?.state;
+        // Nothing to measure lands on the floor of one unit, like a call that named no ceiling.
+        if (state == null)
+            return 0;
+        const characters = typeof state === 'string' ? state.length : JSON.stringify(state).length;
+        return characters / charsPerToken;
+    }, tokensPerUnit);
+};
+exports.estimateFromState = estimateFromState;

package/dist/bindings/proxy/headers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The gateway binding is generic on purpose: a gateway sees HTTP requests, not SDK calls, so
+ * there is nothing vendor-specific to adapt. What travels is attribution.
+ */
+export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from '../../headers';
+export type { GovernanceHeaders, ParsedGovernanceHeaders } from '../../headers';

package/dist/bindings/proxy/headers.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = void 0;
+/**
+ * The gateway binding is generic on purpose: a gateway sees HTTP requests, not SDK calls, so
+ * there is nothing vendor-specific to adapt. What travels is attribution.
+ */
+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; } });
+// Attribution to send with a request is `run.headers()` on the handle itself - the run owns the
+// three values, so a free function here could only copy them back out of it.

package/dist/bindings/proxy/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ingest-only, by design.
+ *
+ * A gateway is out-of-process and sees requests, not runs: it cannot provision, cannot check
+ * against run-scoped state, and cannot archive. What works is splitting the lifecycle across the
+ * boundary - the application provisions and checks in-process, the attribution travels as
+ * headers, and the gateway ingests against it. Governance never leaves the process.
+ *
+ * Both halves of that are methods, not free functions: `run.headers()` writes the attribution and
+ * `stigg.ingestFromHeaders(...)` reads it back. This module is the header contract and the input
+ * shape they agree on.
+ */
+export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
+export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';
+export type * from './types';
+/**
+ * The proxy's one vendor-shaped decision, re-exported from where it is implemented so it sits
+ * beside the call that takes it. A proxy has no response object to adapt - there is no recipe out
+ * here - so naming the shape it observed is the whole of what it can say about the vendor.
+ */
+export type { ObservedVendor } from '../shared/token-usage';

package/dist/bindings/proxy/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = void 0;
+/**
+ * Ingest-only, by design.
+ *
+ * A gateway is out-of-process and sees requests, not runs: it cannot provision, cannot check
+ * against run-scoped state, and cannot archive. What works is splitting the lifecycle across the
+ * boundary - the application provisions and checks in-process, the attribution travels as
+ * headers, and the gateway ingests against it. Governance never leaves the process.
+ *
+ * Both halves of that are methods, not free functions: `run.headers()` writes the attribution and
+ * `stigg.ingestFromHeaders(...)` reads it back. This module is the header contract and the input
+ * shape they agree on.
+ */
+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; } });

package/dist/bindings/proxy/types.d.ts

@@ -0,0 +1,8 @@
+/** What this binding accepts: the run's context, plus what only the request itself can say. */
+import type { IngestContext } from '../../types';
+export type ProxyIngestInput = IngestContext & {
+    /** Whatever the vendor reported; the shape is recognised on the way in. */
+    usage: unknown;
+    /** The gateway's own request id is the natural key - it is stable across its retries. */
+    idempotencyKey: string;
+};

package/dist/bindings/proxy/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/bindings/shared/estimate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Turning a vendor's own request parameters into "how many units should this call ask for".
+ *
+ * Every vendor states a ceiling for the answer it is about to generate, under its own name -
+ * `max_tokens`, `config.maxOutputTokens`, a document whose length stands in for one - and what
+ * happens to that number afterwards is identical: divide by the rate, round up, never ask for
+ * less than one. Only the reading differs, so only the reading stays with the recipe.
+ *
+ * All of these are opt-in. The default asks for a single unit, because an estimate that
+ * overshoots denies calls the budget could have afforded, and the ingest that follows corrects
+ * the balance anyway.
+ */
+/**
+ * Refuses a rate that cannot divide, where it is configured rather than where it is used.
+ *
+ * Zero divides to `Infinity` and a negative to less than one; `requestedUnits` in the wrapper
+ * clamps both back to asking for a single unit, so a misconfigured rate would gate on nothing and
+ * never say so. Failing here makes that a startup error instead of a quiet one, per call, forever.
+ */
+export declare function requirePositiveRate(name: string, value: number): void;
+/**
+ * The shared half: a rate, a reading, and the arithmetic between them.
+ *
+ * `read` returns the vendor's ceiling in tokens, or 0 where the call named none - which lands on
+ * the same floor of one unit rather than needing a case of its own.
+ */
+export declare function estimateUnits(read: (params: any) => number, tokensPerUnit: number): (params: any) => number;

package/dist/bindings/shared/estimate.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Turning a vendor's own request parameters into "how many units should this call ask for".
+ *
+ * Every vendor states a ceiling for the answer it is about to generate, under its own name -
+ * `max_tokens`, `config.maxOutputTokens`, a document whose length stands in for one - and what
+ * happens to that number afterwards is identical: divide by the rate, round up, never ask for
+ * less than one. Only the reading differs, so only the reading stays with the recipe.
+ *
+ * All of these are opt-in. The default asks for a single unit, because an estimate that
+ * overshoots denies calls the budget could have afforded, and the ingest that follows corrects
+ * the balance anyway.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePositiveRate = requirePositiveRate;
+exports.estimateUnits = estimateUnits;
+/**
+ * Refuses a rate that cannot divide, where it is configured rather than where it is used.
+ *
+ * Zero divides to `Infinity` and a negative to less than one; `requestedUnits` in the wrapper
+ * clamps both back to asking for a single unit, so a misconfigured rate would gate on nothing and
+ * never say so. Failing here makes that a startup error instead of a quiet one, per call, forever.
+ */
+function requirePositiveRate(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a finite positive number - got ${value}, which estimates every call wrongly.`);
+    }
+}
+/**
+ * The shared half: a rate, a reading, and the arithmetic between them.
+ *
+ * `read` returns the vendor's ceiling in tokens, or 0 where the call named none - which lands on
+ * the same floor of one unit rather than needing a case of its own.
+ */
+function estimateUnits(read, tokensPerUnit) {
+    requirePositiveRate('tokensPerUnit', tokensPerUnit);
+    return (params) => Math.max(1, Math.ceil(read(params) / tokensPerUnit));
+}

package/dist/bindings/shared/meter-stream.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wrapping a stream so it can be metered, which every vendor needs and none of them differ on.
+ *
+ * What they *do* differ on is where the usage is: Anthropic accumulates it across two event types,
+ * Chat Completions puts it on the last chunk, the Responses API nests it under a completion event,
+ * and a gateway adds a cost and the model that served. So the mechanism is shared and the reading
+ * stays with the recipe that knows the shape.
+ *
+ * Two properties this owes every recipe, both of which it once got wrong:
+ *
+ *  - **One completed stream meters once.** `onComplete` fires on the first ending and never
+ *    again, however many times the object is iterated.
+ *  - **Every way out of the stream is metered.** `for await` is the usual one, but an async
+ *    generator - which is exactly what Gemini's `generateContentStream` resolves to - also
+ *    exposes `next()` as public API, and a caller driving it by hand used to be metered at
+ *    nothing at all.
+ */
+export declare function meterStream(stream: any, collect: (chunk: any) => void, onComplete: () => void): void;

package/dist/bindings/shared/meter-stream.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meterStream = meterStream;
+/**
+ * Wrapping a stream so it can be metered, which every vendor needs and none of them differ on.
+ *
+ * What they *do* differ on is where the usage is: Anthropic accumulates it across two event types,
+ * Chat Completions puts it on the last chunk, the Responses API nests it under a completion event,
+ * and a gateway adds a cost and the model that served. So the mechanism is shared and the reading
+ * stays with the recipe that knows the shape.
+ *
+ * Two properties this owes every recipe, both of which it once got wrong:
+ *
+ *  - **One completed stream meters once.** `onComplete` fires on the first ending and never
+ *    again, however many times the object is iterated.
+ *  - **Every way out of the stream is metered.** `for await` is the usual one, but an async
+ *    generator - which is exactly what Gemini's `generateContentStream` resolves to - also
+ *    exposes `next()` as public API, and a caller driving it by hand used to be metered at
+ *    nothing at all.
+ */
+function meterStream(stream, collect, onComplete) {
+    if (!stream)
+        return;
+    // Captured before anything is patched, so the patched methods below can drive the vendor's own
+    // iterator without re-entering themselves. A bare generator's `[Symbol.asyncIterator]()`
+    // returns *itself*, so without this the loop would call whatever `next` currently holds - by
+    // then the patched one - and either recurse or count every chunk twice.
+    const iterate = typeof stream[Symbol.asyncIterator] === 'function' ? stream[Symbol.asyncIterator].bind(stream) : undefined;
+    const advance = typeof stream.next === 'function' ? stream.next.bind(stream) : undefined;
+    // Closing by hand ends a stream as surely as running it out, so these are captured too - and
+    // for the same reason: `source()` drives them, and binding them after the patch would have it
+    // calling itself.
+    const closers = ['return', 'throw']
+        .map((key) => ({ key, original: typeof stream[key] === 'function' ? stream[key].bind(stream) : undefined }))
+        .filter((entry) => !!entry.original);
+    if (!iterate && !advance)
+        return;
+    /** Fires once. A stream iterated twice is still one completed stream, and one measurement. */
+    let completed = false;
+    const finish = () => {
+        if (completed)
+            return;
+        completed = true;
+        onComplete();
+    };
+    // Reading a chunk is instrumentation: a vendor that changes shape must not break the loop the
+    // caller is standing in. The recipe reports what it could not read.
+    const observe = (value) => {
+        try {
+            collect(value);
+        }
+        catch {
+            // Deliberately swallowed - `onComplete` still runs, and meters whatever was collected.
+        }
+    };
+    /**
+     * The vendor's own iterator, resolved once and shared by both patched paths - so a caller that
+     * takes a few chunks by hand and then falls into a `for await` keeps reading one stream rather
+     * than opening a second.
+     *
+     * Lazy on purpose: for the vendors whose `[Symbol.asyncIterator]()` builds a reader, calling it
+     * eagerly would open a connection for a stream the caller may never consume.
+     */
+    let inner;
+    /** Whether reading ever began. Closing a stream nobody read meters nothing, not a zero. */
+    const started = () => inner !== undefined;
+    const source = () => {
+        if (!inner) {
+            const it = iterate ? iterate() : stream;
+            inner =
+                // A generator hands back itself, and its `next` is patched below - so drive the original.
+                it === stream
+                    ? { next: advance, return: closers.find((entry) => entry.key === 'return')?.original }
+                    : { next: it.next.bind(it), return: typeof it.return === 'function' ? it.return.bind(it) : undefined };
+        }
+        return inner;
+    };
+    if (advance) {
+        // The hand-driven path. Public API on any generator, and metered at nothing until now.
+        stream.next = async (...args) => {
+            try {
+                const result = await source().next(...args);
+                if (result?.done)
+                    finish();
+                else
+                    observe(result?.value);
+                return result;
+            }
+            catch (err) {
+                // The stream ended, badly - but what it produced before it failed was still produced,
+                // and still cost the customer. `for await` meters that through its own `finally`; this
+                // path had no equivalent and dropped the whole measurement on the floor.
+                finish();
+                throw err;
+            }
+        };
+    }
+    // `return()` and `throw()` are how a hand-driven consumer stops early, and either one is the
+    // end of the stream. Without this the usage read up to that point was never reported.
+    for (const { key, original } of closers) {
+        stream[key] = async (...args) => {
+            try {
+                return await original(...args);
+            }
+            finally {
+                if (started())
+                    finish();
+            }
+        };
+    }
+    if (iterate) {
+        stream[Symbol.asyncIterator] = async function* metered() {
+            const it = source();
+            // Whether the source ran itself out, as opposed to the consumer walking away from it. Only
+            // the second case owes it a `return()` - see the `finally`.
+            let exhausted = false;
+            try {
+                while (true) {
+                    const { value, done } = await it.next();
+                    if (done) {
+                        exhausted = true;
+                        return;
+                    }
+                    observe(value);
+                    yield value;
+                }
+            }
+            finally {
+                // Closes the vendor's stream when the consumer broke out early, which is what `for await`
+                // did on the way out. Without it an abandoned stream holds its connection open.
+                //
+                // Only then, though. The iteration protocol closes an iterator on *abrupt* completion and
+                // deliberately not when it ran itself out, so a source that already finished is never
+                // asked to close - driving `next()` by hand means saying that explicitly rather than
+                // inheriting it. Calling `return()` on a spent iterator is a no-op for a plain generator,
+                // but a vendor is free to implement it as "abort the request", and aborting a stream that
+                // has already delivered its last chunk is a cancellation nobody asked for.
+                if (!exhausted) {
+                    try {
+                        await it.return?.();
+                    }
+                    catch {
+                        // A source that objects to being closed must not mask the caller's own exit path.
+                    }
+                }
+                // Meter what was actually produced, even if the consumer broke out of the loop early.
+                finish();
+            }
+        };
+    }
+}