@stigg/agent-sdk-js 0.2.0 → 0.3.1

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

@@ -81,10 +81,22 @@ function restate(into, stated) {
  * stream produces one measurement rather than one per event.
  */
 function observeStream(stream, ingest) {
-    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function')
+    if (!stream)
         return;
-    const iterate = stream[Symbol.asyncIterator].bind(stream);
-    stream[Symbol.asyncIterator] = async function* gatedIterator() {
+    // Anthropic's `Stream` keeps an `iterator` factory on the instance and routes everything through
+    // it - `[Symbol.asyncIterator]()` returns `this.iterator()`, and so does `tee()`. Patching the
+    // async iterator alone left a teed stream reading the raw source: Anthropic billed the call and
+    // nothing here metered it. Patch the factory where there is one, and only the factory, or the
+    // vendor's own delegation would run the accounting twice over the same chunks.
+    const makeIterator = typeof stream.iterator === 'function'
+        ? stream.iterator.bind(stream)
+        : undefined;
+    const iterate = typeof stream[Symbol.asyncIterator] === 'function'
+        ? stream[Symbol.asyncIterator].bind(stream)
+        : undefined;
+    if (!makeIterator && !iterate)
+        return;
+    async function* gated(source) {
         // What the stream has said so far, in the vendor's own shape. Kept flat rather than converted
         // per event: both views of the call - the vendor's names and the normalized counters - are
         // derived from it once at the end, so neither can be accumulated out of step with the other.
@@ -95,7 +107,7 @@ function observeStream(stream, ingest) {
         // What the stream actually produced, for the case where it never gets to say.
         let chars = 0;
         try {
-            for await (const event of iterate()) {
+            for await (const event of source) {
                 if (event?.type === 'message_start')
                     stated = restate(stated, event.message?.usage);
                 if (event?.type === 'message_delta') {
@@ -131,7 +143,17 @@ function observeStream(stream, ingest) {
                 ...(estimated ? { estimated: true } : {}),
             });
         }
-    };
+    }
+    if (makeIterator) {
+        stream.iterator = function gatedIterator() {
+            return gated({ [Symbol.asyncIterator]: () => makeIterator() });
+        };
+    }
+    else {
+        stream[Symbol.asyncIterator] = function gatedAsyncIterator() {
+            return gated(iterate());
+        };
+    }
 }
 exports.anthropicRecipe = {
     vendor: 'anthropic',

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

@@ -27,13 +27,19 @@ function meterStream(stream, collect, onComplete) {
     // 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;
+    // The vendor stream classes - Anthropic's and OpenAI's both - keep an `iterator` *factory* on
+    // the instance, and everything else goes through it: `[Symbol.asyncIterator]()` returns
+    // `this.iterator()`, and so does `tee()`. Patching the async iterator alone therefore leaves
+    // `tee()` reading the raw source, which is how a teed stream was charged by the vendor and
+    // metered at nothing here.
+    const makeIterator = typeof stream.iterator === 'function' ? stream.iterator.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)
+    if (!iterate && !advance && !makeIterator)
         return;
     /** Fires once. A stream iterated twice is still one completed stream, and one measurement. */
     let completed = false;
@@ -108,44 +114,59 @@ function meterStream(stream, collect, onComplete) {
             }
         };
     }
-    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;
+    /**
+     * One pass over an iterator, metering as it goes. Shared by both entry points below so that the
+     * accounting is written once: whichever door the caller came through, the usage is read the same
+     * way and `finish()` fires on the same terms.
+     */
+    async function* metered(it) {
+        // 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.
-                    }
+        }
+        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();
             }
+            // Meter what was actually produced, even if the consumer broke out of the loop early.
+            finish();
+        }
+    }
+    if (makeIterator) {
+        // The factory, not the async iterator: `tee()` calls this directly and never touches
+        // `[Symbol.asyncIterator]`, and the vendor's own `[Symbol.asyncIterator]` calls it too - so
+        // one patch here meters every exit, and patching both would count each chunk twice.
+        stream.iterator = function meteredIterator() {
+            return metered(makeIterator());
+        };
+    }
+    else if (iterate) {
+        stream[Symbol.asyncIterator] = function meteredAsyncIterator() {
+            return metered(source());
         };
     }
 }

package/dist/config.js

@@ -88,7 +88,7 @@ function resolveConfig(options = {}) {
             "the Node server SDK's entitlement cache, which invalidates on updates and writes reported " +
             'usage back, so there is no TTL to size. Configure it with `cache` instead.');
     }
-    return {
+    const config = {
         ...parsed,
         cache: options.cache,
         client: options.client,
@@ -96,4 +96,25 @@ function resolveConfig(options = {}) {
         // Never silent, never fatal. Replace it to route into your own telemetry.
         onError: options.onError ?? ((error, context) => logger.warn(`[stigg] ${context.operation} failed: ${error.message}`)),
     };
+    // The key reads exactly as before and stops being *printed*. `config` is a public property, so
+    // `console.log(stigg)`, `util.inspect`, `JSON.stringify` and any structured logger that walks
+    // the object were all putting a live server key into whatever collects those lines. Hiding the
+    // one field rather than the whole object keeps `baseUrl` and the rest debuggable.
+    Object.defineProperty(config, 'apiKey', { value: parsed.apiKey, enumerable: false, writable: true });
+    // Hiding our own field is not enough. A caller who passes `client` hands over an object that
+    // carries its own copy of the key, so `console.log(stigg.config)` reached it through there -
+    // and no amount of hiding `config.apiKey` helps with somebody else's object. So the config
+    // renders itself: what is useful to debug, and a placeholder where a secret would be.
+    //
+    // It cannot stop `console.log(stigg.config.client)`, which is the caller's own object and theirs
+    // to log. What it stops is this SDK's surfaces printing it for them.
+    const redacted = () => ({
+        ...config,
+        apiKey: config.apiKey ? '[redacted]' : undefined,
+        client: config.client ? '[client supplied by the caller]' : undefined,
+    });
+    for (const key of ['toJSON', Symbol.for('nodejs.util.inspect.custom')]) {
+        Object.defineProperty(config, key, { value: redacted, enumerable: false, writable: false });
+    }
+    return config;
 }

package/dist/core/context.js

@@ -75,6 +75,16 @@ function resolveContext(context, correlationId,
     // names an agent and its entitlement once for every call through the client, so a typo here
     // governs *everything* by the fallback rather than one call.
     assertKnownContext(context, requireCustomer ? 'stiggContext' : "wrap's stiggContext");
+    // A key that deduplicates *one report* cannot be a property of a client. Set at `wrap`, every
+    // call through that client reports under the same key, Stigg dedupes them, and every call after
+    // the first moves no budget at all - silently, because nothing errors and the usage simply
+    // never lands. Refused here rather than ignored, because a caller who passed one meant
+    // something by it.
+    if (!requireCustomer && context.idempotencyKey !== undefined) {
+        throw new Error("wrap's stiggContext cannot set `idempotencyKey` - it deduplicates a single report, so one " +
+            'key shared by every call through the client would bill the first and discard the rest. ' +
+            'Pass it per call instead, or leave it out and let the vendor request id stand in.');
+    }
     const customerId = context.customerId?.trim() ?? '';
     if (!customerId && requireCustomer)
         throw (0, exports.noCustomer)();
@@ -172,7 +182,22 @@ function overrideContext(base, override) {
     let entitlement = base.entitlement;
     let checkedId = base.checkedId;
     if (rebased) {
-        customerId = override.customerId?.trim() || base.customerId;
+        // Absent inherits; present-but-blank throws. `||` used to collapse the two, so a call that
+        // named a customer and got the name wrong - an empty string out of a config, a trimmed-away
+        // id - was billed to the client's default tenant instead. That is someone else's invoice,
+        // and nothing said so. The same mistake on `agentId` has always thrown.
+        if (override.customerId !== undefined) {
+            // `trim()` on its own turns `null` into "Cannot read properties of null" and a number into
+            // "trim is not a function" - the two shapes a JavaScript caller actually passes by accident.
+            // Anything that is not a non-empty string gets the message that says what went wrong.
+            const named = typeof override.customerId === 'string' ? override.customerId.trim() : '';
+            if (!named) {
+                throw new Error('stiggContext.customerId is empty - a call that names a customer must name one. Leave ' +
+                    "the field out to bill the client's own customer; passing an empty value would bill " +
+                    'that customer for work the call said belonged to someone else.');
+            }
+            customerId = named;
+        }
         if (override.entitlement !== undefined) {
             const invalid = (0, types_1.entitlementError)(override.entitlement);
             if (invalid)

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

@@ -135,6 +135,14 @@ export declare const DEFAULT_RECIPES: ({
 })[];
 export declare class StiggAgentSDK {
     readonly config: ResolvedConfig;
+    /**
+     * What this object says about itself when something logs it.
+     *
+     * Without these, `console.log(stigg)` walks the whole object - the config, the engine once it
+     * has started, and the vendor clients each of those holds - and any of them may carry a key.
+     * The redacted view names what is worth seeing and stops there.
+     */
+    toJSON(): Record<string, unknown>;
     private readonly clients;
     /** Every session this SDK handed out, so `flush()` can drain all of them at once. */
     private readonly sessions;

package/dist/stigg-agent-sdk.js

@@ -155,6 +155,19 @@ function toPlacement(input) {
 }
 class StiggAgentSDK {
     config;
+    /**
+     * What this object says about itself when something logs it.
+     *
+     * Without these, `console.log(stigg)` walks the whole object - the config, the engine once it
+     * has started, and the vendor clients each of those holds - and any of them may carry a key.
+     * The redacted view names what is worth seeing and stops there.
+     */
+    toJSON() {
+        return { baseUrl: this.config.baseUrl, apiKey: '[redacted]', started: this.engineState !== undefined };
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.toJSON();
+    }
     clients;
     /** Every session this SDK handed out, so `flush()` can drain all of them at once. */
     sessions = new Set();

package/dist/types.d.ts

@@ -334,7 +334,18 @@ export type ClientOptions = {
     /** Everything this client reports back while it works. See {@link SessionHooks}. */
     hooks?: SessionHooks;
     /** The default context for every call through this client. Any call may override it. */
-    stiggContext?: StiggContext;
+    stiggContext?: ClientContext;
+};
+/**
+ * A client's default context: everything in {@link StiggContext} except `idempotencyKey`.
+ *
+ * That one deduplicates a single report, so a value shared by every call through the client would
+ * bill the first and discard the rest. The runtime refuses it either way - a JavaScript caller
+ * reaches `wrap` without passing through this type - but a TypeScript caller should hear it from
+ * the compiler rather than from production.
+ */
+export type ClientContext = Omit<StiggContext, 'idempotencyKey'> & {
+    idempotencyKey?: never;
 };
 /**
  * `register` - giving an agent an identity, a budget, and a place in the tree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -64,7 +64,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@stigg/node-server-sdk": "6.1.0",
+    "@stigg/node-server-sdk": "6.2.0",
     "@stigg/typescript": "0.1.0-beta.55",
     "zod": "^4.6.1"
   },