agentfootprint 11.1.0 → 11.2.0

package/dist/esm/adapters/observability/cloudwatch.js

@@ -41,6 +41,23 @@
 import { lazyRequire } from '../../lib/lazyRequire.js';
 import { toWireJson } from '../../lib/wireJson.js';
 import { rateLimitedConsoleSink } from './deliveryErrors.js';
+import { createOutbox } from './outbox.js';
+/**
+ * What ONE `PutLogEvents` request may carry — CloudWatch Logs' documented
+ * per-request limits (PutLogEvents API reference): "The maximum number of log
+ * events in a batch is 10,000", and "The maximum batch size is 1,048,576
+ * bytes. This size is calculated as the sum of all event messages in UTF-8,
+ * plus 26 bytes for each log event."
+ *
+ * These split a delivery into legal requests; they are NOT triggers.
+ * `maxBatchEvents` / `maxBatchBytes` still decide when a delivery starts,
+ * exactly as before. The split matters because puts now go one at a time
+ * (#223): a slow put lets a backlog build behind it, and without the split
+ * the next delivery sent the whole backlog as one request CloudWatch refuses.
+ */
+const PUT_LOG_EVENTS_MAX_EVENTS = 10_000;
+const PUT_LOG_EVENTS_MAX_BYTES = 1_048_576;
+const PUT_LOG_EVENTS_BYTES_PER_EVENT = 26;
 // ─── Generic base — also used by agentcoreObservability ──────────────
 /**
  * Internal: shared CloudWatch Logs base used by every adapter that
@@ -62,11 +79,8 @@ export function _buildCloudWatchObservability(opts, strategyName) {
     const maxBatchEvents = opts.maxBatchEvents ?? 100;
     const maxBatchBytes = opts.maxBatchBytes ?? 10_240;
     const flushIntervalMs = opts.flushIntervalMs ?? 1000;
-    // Buffered batch — drained by `flush()` / size-trigger / time-trigger.
-    const buffer = [];
-    let bufferBytes = 0;
-    let lastFlushPromise = Promise.resolve();
-    let timer;
+    // Set by `stop()`: no more events accepted. NOT a guard on delivery (8.11.1):
+    // stopping does not authorise throwing away what was already accepted.
     let stopped = false;
     // What we know about the log stream (8.11.0). This is the per-(group,stream)
     // create latch — group and stream are fixed for the life of a strategy, so
@@ -91,14 +105,6 @@ export function _buildCloudWatchObservability(opts, strategyName) {
         client = createCloudWatchClient(opts.region, strategyName, opts._sdk);
         return client;
     }
-    function scheduleTimedFlush() {
-        if (timer || flushIntervalMs <= 0 || stopped)
-            return;
-        timer = setTimeout(() => {
-            timer = undefined;
-            void doFlush();
-        }, flushIntervalMs);
-    }
     /** Route a delivery failure through whatever `_onError` IS RIGHT NOW.
      *  Reading it at call time (rather than capturing a hook at construction)
      *  is the whole fix: a consumer who assigns `_onError` after building the
@@ -114,90 +120,89 @@ export function _buildCloudWatchObservability(opts, strategyName) {
             logEvents: batch,
         });
     }
-    async function doFlush() {
-        // `stopped` is deliberately NOT a guard here (8.11.1). `stop()` stops this
-        // strategy ACCEPTING events and cancels its timer; it does not authorise
-        // throwing away events already accepted. Guarding here made `flush()`
-        // after `stop()` unable to make progress while its loop waited for
-        // progress — an infinite microtask spin that starved the event loop of
-        // the very process trying to shut down. Same stance as `auditExport`:
-        // stop observing, never destroy what was collected.
-        if (buffer.length === 0)
-            return;
-        // Snapshot + clear so concurrent emits during the in-flight put
-        // accumulate into the next batch.
-        const batch = buffer.splice(0);
-        bufferBytes = 0;
+    /** Ship one batch. Throws when it could not — the outbox drops the batch
+     *  and reports it once. Runs inside the outbox's queue, so two puts are
+     *  never in flight at once and CloudWatch's per-stream order holds. */
+    async function shipBatch(batch) {
+        const client = ensureClient();
         try {
-            const client = ensureClient();
-            try {
-                await putBatch(client, batch);
-                streamState = 'created'; // a successful put proves the stream is there
-                return;
-            }
-            catch (err) {
-                // The one recoverable shape: CloudWatch rejects a put into a stream
-                // that doesn't exist. Before 8.11.0 this adapter asserted that
-                // precondition and never established it, so any stream name that
-                // didn't already exist dropped every event, forever, in silence —
-                // and the documented `${HOSTNAME}/${Date.now()}` convention can never
-                // pre-exist, so following the docs guaranteed the bug.
-                if (!isMissingStreamError(err) || streamState === 'unavailable')
-                    throw err;
-                if (!client.createLogStream) {
-                    throw new Error(`log stream '${logStreamName}' does not exist in log group ` +
-                        `'${opts.logGroupName}', and the injected \`_client\` has no ` +
-                        `\`createLogStream\` to create it.`);
-                }
-                try {
-                    await client.createLogStream({
-                        logGroupName: opts.logGroupName,
-                        logStreamName,
-                    });
-                }
-                catch (createErr) {
-                    // Two processes racing to create the same stream is normal and
-                    // expected — whoever lost the race still has a usable stream.
-                    if (!isAlreadyExistsError(createErr)) {
-                        // Anything else (no `logs:CreateLogStream`, or the log GROUP
-                        // itself is missing) will not fix itself. Latch it off so we
-                        // never loop, and say which of the two it probably is.
-                        streamState = 'unavailable';
-                        throw new Error(`could not create log stream '${logStreamName}' in log group ` +
-                            `'${opts.logGroupName}': ${errorMessage(createErr)}. Check that the log ` +
-                            `GROUP exists (this adapter never creates one) and that the role allows ` +
-                            `\`logs:CreateLogStream\`.`);
-                    }
-                }
-                streamState = 'created';
-                // Exactly ONE re-put of the same batch. Not a retry loop: if this
-                // fails the events are gone, and saying so is better than growing a
-                // buffer during an outage.
-                await putBatch(client, batch);
-            }
+            await putBatch(client, batch);
+            streamState = 'created'; // a successful put proves the stream is there
         }
         catch (err) {
-            const cause = errorMessage(err);
-            reportFailure(new Error(`${batch.length} event(s) dropped shipping to log group '${opts.logGroupName}' ` +
-                `stream '${logStreamName}': ${cause}`));
+            // The one recoverable shape: CloudWatch rejects a put into a stream
+            // that doesn't exist. Before 8.11.0 this adapter asserted that
+            // precondition and never established it, so any stream name that
+            // didn't already exist dropped every event, forever, in silence —
+            // and the documented `${HOSTNAME}/${Date.now()}` convention can never
+            // pre-exist, so following the docs guaranteed the bug.
+            if (!isMissingStreamError(err) || streamState === 'unavailable')
+                throw err;
+            await createStream(client);
+            // Exactly ONE re-put of the same batch. Not a retry loop: if this
+            // fails the events are gone, and saying so is better than growing a
+            // buffer during an outage.
+            await putBatch(client, batch);
         }
     }
+    /** Create the missing stream, or latch it off for good when retrying cannot
+     *  help. Losing a create race to another process is success. */
+    async function createStream(client) {
+        if (!client.createLogStream) {
+            throw new Error(`log stream '${logStreamName}' does not exist in log group ` +
+                `'${opts.logGroupName}', and the injected \`_client\` has no ` +
+                `\`createLogStream\` to create it.`);
+        }
+        try {
+            await client.createLogStream({ logGroupName: opts.logGroupName, logStreamName });
+        }
+        catch (createErr) {
+            // Two processes racing to create the same stream is normal and
+            // expected — whoever lost the race still has a usable stream.
+            if (!isAlreadyExistsError(createErr)) {
+                // Anything else (no `logs:CreateLogStream`, or the log GROUP itself is
+                // missing) will not fix itself. Latch it off so we never loop, and say
+                // which of the two it probably is.
+                streamState = 'unavailable';
+                throw new Error(`could not create log stream '${logStreamName}' in log group ` +
+                    `'${opts.logGroupName}': ${errorMessage(createErr)}. Check that the log ` +
+                    `GROUP exists (this adapter never creates one) and that the role allows ` +
+                    `\`logs:CreateLogStream\`.`);
+            }
+        }
+        streamState = 'created';
+    }
+    // Buffered log events, and the one queue every put goes through — size
+    // trigger, timer, `flush()`, shutdown (outbox.ts; #223).
+    const outbox = createOutbox({
+        name: strategyName,
+        // When a delivery starts — compared as given, as before.
+        maxItems: maxBatchEvents,
+        maxBytes: maxBatchBytes,
+        // What one put may carry: the oldest events that fit; the rest ship in
+        // the next put, right after, in order. The byte measure is the one `add`
+        // records (UTF-8 message bytes) plus CloudWatch's 26 per event. An event
+        // too large for any request is still sent — alone — as it was before;
+        // CloudWatch refuses it and that one event is reported dropped, without
+        // taking its neighbours with it.
+        maxItemsPerDelivery: PUT_LOG_EVENTS_MAX_EVENTS,
+        maxBytesPerDelivery: PUT_LOG_EVENTS_MAX_BYTES,
+        overheadBytesPerItem: PUT_LOG_EVENTS_BYTES_PER_EVENT,
+        flushIntervalMs,
+        // An un-stopped strategy lingers up to `flushIntervalMs` so the timer can
+        // still ship the tail (see `stop()`).
+        timerHoldsProcess: true,
+        deliver: shipBatch,
+        dropped: (batch, cause) => new Error(`${batch.length} event(s) dropped shipping to log group '${opts.logGroupName}' ` +
+            `stream '${logStreamName}': ${errorMessage(cause)}`),
+        report: reportFailure,
+    });
     function enqueue(event) {
         if (stopped)
             return;
         // The wire rule (`lib/wireJson.ts`) — an Error's custom properties never ship.
         const message = toWireJson(event);
-        const bytes = Buffer.byteLength(message, 'utf8');
-        buffer.push({ timestamp: Date.now(), message });
-        bufferBytes += bytes;
-        if (buffer.length >= maxBatchEvents || bufferBytes >= maxBatchBytes) {
-            // Size trigger — flush immediately. Chain onto last to preserve
-            // CloudWatch's per-stream ordering requirement.
-            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-        }
-        else {
-            scheduleTimedFlush();
-        }
+        outbox.add({ timestamp: Date.now(), message }, Buffer.byteLength(message, 'utf8'));
     }
     const strategy = {
         name: strategyName,
@@ -218,25 +223,14 @@ export function _buildCloudWatchObservability(opts, strategyName) {
          * since 8.11.1: a flush after a stop still ships what was already
          * accepted.
          */
-        async flush() {
-            // BOUNDED BY CONSTRUCTION. Every pass must remove at least one buffered
-            // event; a pass that removes none ends the drain instead of trying
-            // again. The previous shape looped `while (buffer.length > 0)` and
-            // trusted `doFlush()` to make progress — which it stopped doing once
-            // `stop()` had been called, turning shutdown into an infinite microtask
-            // spin (no timer could fire, no deadline could expire, 100% of a core).
-            // A drain that cannot finish must return, never retry forever.
-            for (;;) {
-                const pending = buffer.length;
-                // Chain, never replace: CloudWatch requires per-stream ordering, so a
-                // drain waits for the in-flight put rather than racing it.
-                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-                await lastFlushPromise;
-                if (buffer.length === 0)
-                    return;
-                if (buffer.length >= pending)
-                    return;
-            }
+        flush() {
+            // Resolves once every event accepted before the call is shipped (or
+            // dropped and reported) — one a timed put already had in flight
+            // included — after one more sweep of what arrived while it waited; it
+            // does not chase a producer that keeps emitting. A put that never
+            // settles holds it. Since 8.11.1 delivery ignores `stop()`, so a flush
+            // after a stop still ships and never spins.
+            return outbox.drain();
         },
         /** Stop the flush timer and stop accepting events. **The framework does
          *  not call this for you** — an un-stopped strategy keeps a `setTimeout`
@@ -248,10 +242,7 @@ export function _buildCloudWatchObservability(opts, strategyName) {
          *  `stop()` still ships it (8.11.1). */
         stop() {
             stopped = true;
-            if (timer) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
+            outbox.stop();
         },
         /**
          * Where errors go. Two callers: the dispatch layer (when `exportEvent`

package/dist/esm/adapters/observability/cloudwatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudwatch.js","sourceRoot":"","sources":["../../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloudwatch.js","sourceRoot":"","sources":["../../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;;;;;;;;GAYG;AACH,MAAM,yBAAyB,GAAG,MAAM,CAAC;AACzC,MAAM,wBAAwB,GAAG,SAAS,CAAC;AAC3C,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAiG1C,wEAAwE;AAExE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,6BAA6B,CAC3C,IAAoC,EACpC,YAAoB;IAEpB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CACjB,IAAI,YAAY,+CAA+C;YAC7D,kEAAkE,CACrE,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,gBAAgB,CAAC;IAC7D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,GAAG,CAAC;IAClD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,MAAM,CAAC;IACnD,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC;IAErD,8EAA8E;IAC9E,uEAAuE;IACvE,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,6EAA6E;IAC7E,2EAA2E;IAC3E,+BAA+B;IAC/B,yEAAyE;IACzE,qEAAqE;IACrE,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,6EAA6E;IAC7E,yEAAyE;IACzE,IAAI,WAAW,GAA0C,SAAS,CAAC;IAEnE,gEAAgE;IAChE,iCAAiC;IACjC,MAAM,WAAW,GAAG,sBAAsB,CAAC,YAAY,CAAC,CAAC;IAEzD,gEAAgE;IAChE,8DAA8D;IAC9D,IAAI,MAAM,GAAqC,IAAI,CAAC,OAAO,CAAC;IAC5D,SAAS,YAAY;QACnB,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;gCAI4B;IAC5B,SAAS,aAAa,CAAC,GAAU;QAC/B,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,MAA4B,EAAE,KAA0B;QAC9E,MAAM,MAAM,CAAC,YAAY,CAAC;YACxB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,aAAa;YACb,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;2EAEuE;IACvE,KAAK,UAAU,SAAS,CAAC,KAA0B;QACjD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC9B,WAAW,GAAG,SAAS,CAAC,CAAC,8CAA8C;QACzE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oEAAoE;YACpE,+DAA+D;YAC/D,iEAAiE;YACjE,kEAAkE;YAClE,sEAAsE;YACtE,uDAAuD;YACvD,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,WAAW,KAAK,aAAa;gBAAE,MAAM,GAAG,CAAC;YAC3E,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3B,kEAAkE;YAClE,oEAAoE;YACpE,2BAA2B;YAC3B,MAAM,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED;oEACgE;IAChE,KAAK,UAAU,YAAY,CAAC,MAA4B;QACtD,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,eAAe,aAAa,gCAAgC;gBAC1D,IAAI,IAAI,CAAC,YAAY,yCAAyC;gBAC9D,mCAAmC,CACtC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,eAAe,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,+DAA+D;YAC/D,8DAA8D;YAC9D,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrC,uEAAuE;gBACvE,uEAAuE;gBACvE,mCAAmC;gBACnC,WAAW,GAAG,aAAa,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,gCAAgC,aAAa,iBAAiB;oBAC5D,IAAI,IAAI,CAAC,YAAY,MAAM,YAAY,CAAC,SAAS,CAAC,uBAAuB;oBACzE,yEAAyE;oBACzE,2BAA2B,CAC9B,CAAC;YACJ,CAAC;QACH,CAAC;QACD,WAAW,GAAG,SAAS,CAAC;IAC1B,CAAC;IAED,uEAAuE;IACvE,yDAAyD;IACzD,MAAM,MAAM,GAAG,YAAY,CAAW;QACpC,IAAI,EAAE,YAAY;QAClB,yDAAyD;QACzD,QAAQ,EAAE,cAAc;QACxB,QAAQ,EAAE,aAAa;QACvB,uEAAuE;QACvE,yEAAyE;QACzE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,iCAAiC;QACjC,mBAAmB,EAAE,yBAAyB;QAC9C,mBAAmB,EAAE,wBAAwB;QAC7C,oBAAoB,EAAE,8BAA8B;QACpD,eAAe;QACf,0EAA0E;QAC1E,sCAAsC;QACtC,iBAAiB,EAAE,IAAI;QACvB,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CACxB,IAAI,KAAK,CACP,GAAG,KAAK,CAAC,MAAM,4CAA4C,IAAI,CAAC,YAAY,IAAI;YAC9E,WAAW,aAAa,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,CACtD;QACH,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC;IAEH,SAAS,OAAO,CAAC,KAA0B;QACzC,IAAI,OAAO;YAAE,OAAO;QACpB,+EAA+E;QAC/E,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,MAAM,QAAQ,GAA0B;QACtC,IAAI,EAAE,YAAY;QAClB,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,WAAW,EAAE,OAAO;QACpB;;;;;;;;;;;;;;WAcG;QACH,KAAK;YACH,oEAAoE;YACpE,gEAAgE;YAChE,sEAAsE;YACtE,kEAAkE;YAClE,uEAAuE;YACvE,4CAA4C;YAC5C,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QACD;;;;;;;gDAOwC;QACxC,IAAI;YACF,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,CAAC;QACD;;;;;;;;;;WAUG;QACH,QAAQ,CAAC,GAAU,EAAE,KAA2B;YAC9C,CAAC,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,wEAAwE;AAExE,SAAS,YAAY,CAAC,GAAY;IAChC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAK,GAAyB,EAAE,IAAI,KAAK,2BAA2B;QAAE,OAAO,IAAI,CAAC;IAClF,OAAO,sDAAsD,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,iFAAiF;AACjF,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAK,GAAyB,EAAE,IAAI,KAAK,gCAAgC;QAAE,OAAO,IAAI,CAAC;IACvF,OAAO,gDAAgD,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,wEAAwE;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAoC;IAEpC,OAAO,6BAA6B,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AAC3D,CAAC;AAED,wEAAwE;AAExE,SAAS,sBAAsB,CAC7B,MAA0B,EAC1B,YAAoB,EACpB,QAA8B;IAE9B,IAAI,GAAwB,CAAC;IAC7B,IAAI,QAAQ,EAAE,CAAC;QACb,GAAG,GAAG,QAAQ,CAAC;IACjB,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,GAAG,GAAG,WAAW,CAAsB,iCAAiC,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,oFAAoF;gBAClG,2DAA2D;gBAC3D,2CAA2C,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,oBAAoB,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,uEAAuE;YACrF,mFAAmF,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAE3E,CAAC;IAEF,MAAM,sBAAsB,GAAG,GAAG,CAAC,sBAAsB,CAAC;IAE1D,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,KAAK;YACtB,6DAA6D;YAC7D,kEAAkE;YAClE,MAAM,GAAG,GAAG,IAAK,GAAG,CAAC,mBAAmD,CAAC,KAAK,CAAC,CAAC;YAChF,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,oEAAoE;QACpE,sEAAsE;QACtE,yDAAyD;QACzD,GAAG,CAAC,sBAAsB,IAAI;YAC5B,KAAK,CAAC,eAAe,CAAC,KAAsD;gBAC1E,MAAM,GAAG,GAAG,IAAK,sBAAsD,CAAC,KAAK,CAAC,CAAC;gBAC/E,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;SACF,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/esm/adapters/observability/file.d.ts

@@ -36,10 +36,14 @@
  * `exportEvent` is sync and never touches the disk: it serializes, buffers, and
  * returns. Batches are appended asynchronously on a size trigger
  * (`maxBufferEvents` / `maxBufferBytes`), on a timer (`flushIntervalMs`), and on
- * `flush()`. A hard kill therefore loses at most the buffer — the price of not
- * making telemetry a term in agent-loop latency. Call `flush()` (or
- * `agent.shutdown()`, which does) at process end; see the 8.12.0 lifecycle laws
- * on {@link BaseStrategy.flush}.
+ * `flush()` — all through ONE queue (`outbox.ts`), so one append is in flight
+ * at a time: this sink's appends never interleave, and lines land in dispatch
+ * order (#223). That is not atomicity — a disk that fails partway through an
+ * append (ENOSPC) can still leave part of a line behind, and that batch is
+ * reported dropped. A hard kill loses the buffer and can interrupt the append
+ * in flight — the price of not making telemetry a term in agent-loop latency.
+ * Call `flush()` (or `agent.shutdown()`, which does) at process end; see the
+ * 8.12.0 lifecycle laws on {@link BaseStrategy.flush}.
  *
  * ## Rotation is ONE generation, and that is deliberate
  *

package/dist/esm/adapters/observability/file.js

@@ -36,10 +36,14 @@
  * `exportEvent` is sync and never touches the disk: it serializes, buffers, and
  * returns. Batches are appended asynchronously on a size trigger
  * (`maxBufferEvents` / `maxBufferBytes`), on a timer (`flushIntervalMs`), and on
- * `flush()`. A hard kill therefore loses at most the buffer — the price of not
- * making telemetry a term in agent-loop latency. Call `flush()` (or
- * `agent.shutdown()`, which does) at process end; see the 8.12.0 lifecycle laws
- * on {@link BaseStrategy.flush}.
+ * `flush()` — all through ONE queue (`outbox.ts`), so one append is in flight
+ * at a time: this sink's appends never interleave, and lines land in dispatch
+ * order (#223). That is not atomicity — a disk that fails partway through an
+ * append (ENOSPC) can still leave part of a line behind, and that batch is
+ * reported dropped. A hard kill loses the buffer and can interrupt the append
+ * in flight — the price of not making telemetry a term in agent-loop latency.
+ * Call `flush()` (or `agent.shutdown()`, which does) at process end; see the
+ * 8.12.0 lifecycle laws on {@link BaseStrategy.flush}.
  *
  * ## Rotation is ONE generation, and that is deliberate
  *
@@ -72,6 +76,7 @@
 import { lazyRequire } from '../../lib/lazyRequire.js';
 import { toWireJson } from '../../lib/wireJson.js';
 import { rateLimitedConsoleSink } from './deliveryErrors.js';
+import { createOutbox } from './outbox.js';
 // ─── Public factory ──────────────────────────────────────────────────
 /**
  * NDJSON-to-a-local-file observability strategy. See
@@ -117,27 +122,13 @@ export function fileObservability(opts) {
             `Fix the path or the permission — this sink refuses to start rather than ` +
             `silently drop every event.`);
     }
-    // Buffered lines — drained by `flush()` / size trigger / timer.
-    const buffer = [];
-    let bufferBytes = 0;
-    let lastFlushPromise = Promise.resolve();
-    let timer;
+    // Set by `stop()`: this sink accepts no more events. It is NOT a guard on
+    // writing — `stop()` does not authorise throwing away what was already
+    // accepted, and `flush()` after it still writes (the 8.11.1 stance).
     let stopped = false;
     // The fallback when the consumer wires nothing. Rate-limited; a
     // consumer-supplied sink is not.
     const consoleSink = rateLimitedConsoleSink(strategyName);
-    function scheduleTimedFlush() {
-        if (timer || flushIntervalMs <= 0 || stopped)
-            return;
-        timer = setTimeout(() => {
-            timer = undefined;
-            void doFlush();
-        }, flushIntervalMs);
-        // Never hold the process open for telemetry. `unref` exists on Node's
-        // Timeout and not on the browser's number — feature-detected, so a
-        // non-Node runtime with an injected `_fs` still works.
-        timer.unref?.();
-    }
     /** Route a delivery failure through whatever `_onError` IS RIGHT NOW —
      *  reading it at call time, so a consumer who assigns `_onError` after
      *  construction still receives them (the 8.11.0 fix). */
@@ -159,28 +150,29 @@ export function fileObservability(opts) {
         await fs.rename(path, rotatedPath);
         bytesOnDisk = 0;
     }
-    async function doFlush() {
-        // `stopped` is deliberately NOT a guard here — same stance as the AWS
-        // adapters since 8.11.1. `stop()` stops this strategy ACCEPTING events; it
-        // does not authorise throwing away events already accepted, and a `flush()`
-        // that cannot make progress after a `stop()` is how shutdown spins forever.
-        if (buffer.length === 0)
-            return;
-        // Snapshot + clear so events emitted during the in-flight write accumulate
-        // into the next batch.
-        const batch = buffer.splice(0);
-        const batchBytes = bufferBytes;
-        bufferBytes = 0;
-        const data = `${batch.join('\n')}\n`;
-        try {
-            await rotateIfNeeded(batchBytes);
-            await fs.appendFile(path, data);
-            bytesOnDisk += byteLength(data);
-        }
-        catch (err) {
-            reportFailure(new Error(`${batch.length} event(s) dropped writing to '${path}': ${errorMessage(err)}`));
-        }
+    /** One batch: rotate if it would cross the ceiling, then append. Runs
+     *  inside the outbox's queue, so no other batch — and no other rotation —
+     *  can start until this one settles. */
+    async function writeBatch(lines) {
+        const data = `${lines.join('\n')}\n`;
+        const bytes = byteLength(data);
+        await rotateIfNeeded(bytes);
+        await fs.appendFile(path, data);
+        bytesOnDisk += bytes;
     }
+    // Buffered lines, and the one queue every write goes through — size
+    // trigger, timer, `flush()`, shutdown (outbox.ts; #223).
+    const outbox = createOutbox({
+        name: strategyName,
+        maxItems: maxBufferEvents,
+        maxBytes: maxBufferBytes,
+        flushIntervalMs,
+        // Never hold the process open for a local write.
+        timerHoldsProcess: false,
+        deliver: writeBatch,
+        dropped: (lines, cause) => new Error(`${lines.length} event(s) dropped writing to '${path}': ${errorMessage(cause)}`),
+        report: reportFailure,
+    });
     function enqueue(event) {
         if (stopped)
             return;
@@ -202,17 +194,11 @@ export function fileObservability(opts) {
         // write, and a bare "undefined" line would corrupt the NDJSON stream.
         if (line === undefined)
             return;
-        buffer.push(line);
-        bufferBytes += byteLength(line) + 1; // + the newline this line will carry
-        if (buffer.length >= maxBufferEvents || bufferBytes >= maxBufferBytes) {
-            // Size trigger. Chain onto the last write rather than racing it — the
-            // file's line order IS the dispatch order, and that is the only thing an
-            // offline reader can rely on.
-            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-        }
-        else {
-            scheduleTimedFlush();
-        }
+        // + the newline this line will carry. The outbox decides when it is
+        // written, and writes it after every line accepted before it — the file's
+        // line order IS the dispatch order, the one thing an offline reader can
+        // rely on.
+        outbox.add(line, byteLength(line) + 1);
     }
     const strategy = {
         name: strategyName,
@@ -223,31 +209,22 @@ export function fileObservability(opts) {
          * Write what is buffered. Called for you on shutdown (8.12.0) — by the
          * handle `enable.observability()` returns, by `agent.shutdown()`, and by a
          * `standingAgent` closing. Safe at any time, including after `stop()`.
+         *
+         * Resolves once every event accepted before the call is written (or
+         * dropped and reported) — one a timed write already had in flight
+         * included — after one more sweep of what arrived while it waited. It
+         * does not chase a producer that keeps emitting. A write that never
+         * settles holds it: nothing can cancel an in-flight write.
          */
-        async flush() {
-            // BOUNDED BY CONSTRUCTION — every pass must remove at least one buffered
-            // line; a pass that removes none ends the drain instead of retrying. The
-            // shape the CloudWatch adapter arrived at in 8.11.1, for the same reason:
-            // a drain that cannot finish must return, never spin.
-            for (;;) {
-                const pending = buffer.length;
-                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-                await lastFlushPromise;
-                if (buffer.length === 0)
-                    return;
-                if (buffer.length >= pending)
-                    return;
-            }
+        flush() {
+            return outbox.drain();
         },
         /** Clear the timer and stop accepting events. Terminal: there is no
          *  restart. What it does NOT do is discard the buffer — `flush()` after
          *  `stop()` still writes it. */
         stop() {
             stopped = true;
-            if (timer) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
+            outbox.stop();
         },
         /** Where failures go. Two callers: the dispatch layer (when `exportEvent`
          *  itself throws) and this adapter's own write path. */

package/dist/esm/adapters/observability/file.js.map

@@ -1 +1 @@
-{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../../src/adapters/observability/file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../../src/adapters/observability/file.ts"],"names":[],"mappings":"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"}

package/dist/esm/adapters/observability/outbox.d.ts

@@ -0,0 +1,104 @@
+/**
+ * outbox — the one owner of buffered, timed, serialized delivery for the
+ * batching sinks in this folder: `file`, `cloudwatch` (and `agentcore`, which
+ * is built on it) and `xray`.
+ *
+ * A sink accepts items on its hot path (sync, no I/O) and hands them here. The
+ * outbox decides WHEN a batch leaves and makes sure only one leaves at a time:
+ *
+ *   - **One queue, every trigger.** The size trigger, the timer and `drain()`
+ *     (the sink's `flush()`, and so every shutdown) all queue a delivery on
+ *     the same promise chain. Nothing calls `deliver` any other way.
+ *   - **One delivery in flight.** A delivery starts only after the previous
+ *     one settled. A large `fs.promises.appendFile` is several `write()`s; two
+ *     of them interleaved tear NDJSON lines (reported in #223, where the timer
+ *     bypassed the chain). Whatever a sink does around its write — the file
+ *     sink's rotation — runs inside its delivery, so it can never be skipped
+ *     or reordered either. This keeps ONE sink's deliveries from interleaving;
+ *     it does not make a delivery atomic (a disk that fails partway through an
+ *     append can still leave part of it behind).
+ *   - **Oldest first, within the receiver's limits.** A delivery takes the
+ *     oldest waiting items, so items leave in the order they were accepted.
+ *     When a receiving service limits one request (`maxItemsPerDelivery`,
+ *     `maxBytesPerDelivery` — CloudWatch's PutLogEvents), a delivery takes
+ *     only the oldest items that fit, and the rest go in the next delivery,
+ *     right after. That matters BECAUSE of the queue: a slow delivery lets a
+ *     backlog build behind it, which one request may not be allowed to carry.
+ *     Each part settles on its own — shipped, or dropped and reported.
+ *   - **`drain()` is bounded.** It resolves once every item accepted BEFORE
+ *     the call has settled (delivered, or dropped and reported), one the timer
+ *     already had in flight included — then makes one sweep of what arrived
+ *     while it waited. It never chases a producer that keeps emitting: under
+ *     steady traffic it ends after about two deliveries.
+ *   - **A failed batch is dropped and reported once**, then the next batch
+ *     goes. It is never requeued, so a full disk or an outage cannot grow the
+ *     outbox. The queue never rejects: a failure report that itself throws is
+ *     said on the console instead of becoming an unhandled rejection.
+ *
+ * What it does NOT do: bound a delivery that never settles. A hung disk holds
+ * the queue, and `drain()` with it; nothing can cancel an in-flight write.
+ *
+ * Role: leaf helper for `adapters/observability/*`. Composed as a field,
+ * never inherited.
+ */
+/** What a sink tells its outbox. */
+export interface OutboxOptions<T> {
+    /** The sink's name: it prefixes a refused option and the console line when
+     *  a failure report throws. */
+    readonly name: string;
+    /** Size trigger: deliver once `waiting >= maxItems`. Compared as given —
+     *  the meaning each sink's option had before the outbox, so no value that
+     *  worked is refused: `0` or a negative number triggers on every item,
+     *  `2.5` on the third, `NaN` or `Infinity` never (then only the byte
+     *  trigger, the timer and `drain()` deliver). It never limits what a
+     *  delivery takes. */
+    readonly maxItems: number;
+    /** Size trigger: deliver once `waitingBytes >= maxBytes`, compared as
+     *  given. Omitted → no byte trigger. */
+    readonly maxBytes?: number;
+    /** Most items one delivery takes: a positive whole number — a sink maps its
+     *  own option to one first, and refuses by its own name what cannot map.
+     *  Omitted → everything waiting. */
+    readonly maxItemsPerDelivery?: number;
+    /** Most bytes one delivery may carry, as the receiving service counts them:
+     *  for each item, the `bytes` it was added with plus `overheadBytesPerItem`.
+     *  A delivery always takes at least one item, so an item too large for any
+     *  delivery still goes — alone — and the service's answer decides it.
+     *  Omitted → no byte limit. */
+    readonly maxBytesPerDelivery?: number;
+    /** Bytes the receiving service adds to each item it counts (CloudWatch
+     *  Logs: 26 per event). Default 0. */
+    readonly overheadBytesPerItem?: number;
+    /** Timer trigger for sparse traffic, in ms. `0` disables it: only the size
+     *  trigger and `drain()` deliver. */
+    readonly flushIntervalMs: number;
+    /** Does an armed timer keep the process alive? Each sink decides: the file
+     *  sink says no (a local write is never worth holding a process open for),
+     *  the network sinks say yes (an un-stopped one lingers up to
+     *  `flushIntervalMs` so its timer can still ship the tail). */
+    readonly timerHoldsProcess: boolean;
+    /** Ship one batch. Never called while another call is still in flight. */
+    readonly deliver: (batch: readonly T[]) => Promise<void>;
+    /** Describe a batch `deliver` failed to ship — the report it is dropped
+     *  with. */
+    readonly dropped: (batch: readonly T[], cause: unknown) => Error;
+    /** Where that report goes. Read at call time by the sink, so a consumer
+     *  who assigns `_onError` after construction still receives it. */
+    readonly report: (error: Error) => void;
+}
+/** The three things a sink does with its outbox. */
+export interface Outbox<T> {
+    /** Accept one item. Sync, never throws, never does I/O. `bytes` counts
+     *  toward the byte trigger. Accepting is the SINK's decision — the outbox
+     *  takes what it is given, including after `stop()`. */
+    add(item: T, bytes?: number): void;
+    /** Settle everything accepted before this call — behind whatever is in
+     *  flight — then sweep once what arrived meanwhile. Never rejects. */
+    drain(): Promise<void>;
+    /** Cancel the timer and arm no new one. Discards nothing: `drain()`
+     *  afterwards still delivers what was accepted. */
+    stop(): void;
+}
+/** Build the outbox one sink owns. A per-delivery cap that could take
+ *  nothing is refused: such a delivery could never finish a drain. */
+export declare function createOutbox<T>(opts: OutboxOptions<T>): Outbox<T>;