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

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

@@ -0,0 +1,44 @@
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const typesafeRecipe: {
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    /**
+     * `systemOne` is the whole surface - unlike Anthropic there is no second call style to prove,
+     * because it is the only thing that reaches the wire carrying usage.
+     *
+     * The exclusion names the one client that collides: `ollama` ships a `systemone` method whose
+     * request and response are the *same shape* as this one, so casing would otherwise be the only
+     * thing between them. Excluding that client by its own three-marker guard - rather than
+     * demanding extra methods here - keeps this recipe claiming anything that exposes `systemOne`,
+     * a thin adapter or a test double included, while making the two guards mutually exclusive
+     * whatever order a registry consults them in.
+     */
+    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,83 @@
+"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");
+const ollama_recipe_1 = require("../ollama/ollama-recipe");
+exports.typesafeRecipe = {
+    vendor: 'typesafe',
+    metrics: token_usage_1.TYPESAFE_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    /**
+     * `systemOne` is the whole surface - unlike Anthropic there is no second call style to prove,
+     * because it is the only thing that reaches the wire carrying usage.
+     *
+     * The exclusion names the one client that collides: `ollama` ships a `systemone` method whose
+     * request and response are the *same shape* as this one, so casing would otherwise be the only
+     * thing between them. Excluding that client by its own three-marker guard - rather than
+     * demanding extra methods here - keeps this recipe claiming anything that exposes `systemOne`,
+     * a thin adapter or a test double included, while making the two guards mutually exclusive
+     * whatever order a registry consults them in.
+     */
+    matches: (client) => (0, registry_1.hasMethod)(client, ['systemOne']) && !ollama_recipe_1.ollamaRecipe.matches(client),
+    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/base-url.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Reading a client's `baseURL`, which is the only thing that says which vendor is on the far end.
+ *
+ * Shape cannot answer that question: every OpenAI-compatible endpoint has the same methods, so
+ * `matches` falls back to the URL, and a wrong answer there does not throw - it silently meters
+ * one vendor's traffic under another vendor's name and bills the wrong party. That is what makes
+ * these few lines the most consequential ones in a binding, and why they live in one place rather
+ * than being written out per recipe.
+ *
+ * The subdomain rule below is the part worth getting exactly right, and the part a hand-written
+ * copy tends to get wrong. Five recipes match on a host - Groq, OpenRouter, LiteLLM, Databricks
+ * and Cloudflare - and two of them need a *set* of host suffixes rather than one, with Databricks
+ * needing the path as well, because its host families cover every Databricks API and most of them
+ * are not inference.
+ *
+ * This is deliberately not in `token-usage.ts`. That file is the vocabulary of what a response
+ * counts, and a hostname is not a counter.
+ */
+/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
+export declare function hostOf(url: string): string;
+/** The path, lowercased and without trailing slashes, or '' when the URL will not parse. */
+export declare function pathOf(url: string): string;
+/**
+ * Whether a URL is served by `expected` or a subdomain of it.
+ *
+ * The dot is the whole point. A substring test lets `api.vendor.com.attacker.net` through, and an
+ * `endsWith` without it lets `notvendor.com` match `vendor.com` - both are somebody else's domain,
+ * and claiming either attributes their traffic to this vendor.
+ */
+export declare function matchesHost(url: string, expected: string): boolean;
+/**
+ * The same test against several hosts, for a platform that serves one product from more than one
+ * domain - Databricks has a hostname per cloud, and none of them is more canonical than the rest.
+ */
+export declare function matchesAnyHost(url: string, expected: readonly string[]): boolean;
+/**
+ * Whether `candidate` is the configured endpoint, or something underneath it.
+ *
+ * A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different deployment
+ * with a different price list. Compare the origin, then the path one whole segment at a time.
+ */
+export declare function withinBaseUrl(configured: string, candidate: string): boolean;
+/** A client's configured base URL, when it has one this can read. */
+export declare function baseUrlOf(client: unknown): string | undefined;

package/dist/bindings/shared/base-url.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Reading a client's `baseURL`, which is the only thing that says which vendor is on the far end.
+ *
+ * Shape cannot answer that question: every OpenAI-compatible endpoint has the same methods, so
+ * `matches` falls back to the URL, and a wrong answer there does not throw - it silently meters
+ * one vendor's traffic under another vendor's name and bills the wrong party. That is what makes
+ * these few lines the most consequential ones in a binding, and why they live in one place rather
+ * than being written out per recipe.
+ *
+ * The subdomain rule below is the part worth getting exactly right, and the part a hand-written
+ * copy tends to get wrong. Five recipes match on a host - Groq, OpenRouter, LiteLLM, Databricks
+ * and Cloudflare - and two of them need a *set* of host suffixes rather than one, with Databricks
+ * needing the path as well, because its host families cover every Databricks API and most of them
+ * are not inference.
+ *
+ * This is deliberately not in `token-usage.ts`. That file is the vocabulary of what a response
+ * counts, and a hostname is not a counter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hostOf = hostOf;
+exports.pathOf = pathOf;
+exports.matchesHost = matchesHost;
+exports.matchesAnyHost = matchesAnyHost;
+exports.withinBaseUrl = withinBaseUrl;
+exports.baseUrlOf = baseUrlOf;
+/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/** The path, lowercased and without trailing slashes, or '' when the URL will not parse. */
+function pathOf(url) {
+    try {
+        return new URL(url).pathname.toLowerCase().replace(/\/+$/, '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Whether a URL is served by `expected` or a subdomain of it.
+ *
+ * The dot is the whole point. A substring test lets `api.vendor.com.attacker.net` through, and an
+ * `endsWith` without it lets `notvendor.com` match `vendor.com` - both are somebody else's domain,
+ * and claiming either attributes their traffic to this vendor.
+ */
+function matchesHost(url, expected) {
+    const host = hostOf(url);
+    const want = expected.toLowerCase();
+    if (!host || !want)
+        return false;
+    return host === want || host.endsWith(`.${want}`);
+}
+/**
+ * The same test against several hosts, for a platform that serves one product from more than one
+ * domain - Databricks has a hostname per cloud, and none of them is more canonical than the rest.
+ */
+function matchesAnyHost(url, expected) {
+    return expected.some((host) => matchesHost(url, host));
+}
+/**
+ * Whether `candidate` is the configured endpoint, or something underneath it.
+ *
+ * A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different deployment
+ * with a different price list. Compare the origin, then the path one whole segment at a time.
+ */
+function withinBaseUrl(configured, candidate) {
+    try {
+        const want = new URL(configured);
+        const got = new URL(candidate);
+        if (want.origin !== got.origin)
+            return false;
+        const base = want.pathname.replace(/\/+$/, '');
+        const path = got.pathname.replace(/\/+$/, '');
+        return path === base || path.startsWith(`${base}/`);
+    }
+    catch {
+        return false;
+    }
+}
+/** A client's configured base URL, when it has one this can read. */
+function baseUrlOf(client) {
+    const configured = client?.baseURL;
+    return typeof configured === 'string' ? configured : undefined;
+}

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();
+            }
+        };
+    }
+}