@oxygen-agent/cli 1.1042.30 → 1.1043.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,4 +34,4 @@ oxygen update
34
34
 
35
35
  For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
36
36
 
37
- Version: 1.1042.30
37
+ Version: 1.1043.4
@@ -1315,7 +1315,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1315
1315
  });
1316
1316
  }))
1317
1317
  .addCommand(new Command("status")
1318
- .description("Read each mailbox's stored warm-up state: warmupTruth (state, last send, pause reason, dispatch counters, next_action), renewal and billing. A pure read: no provider call and no change. OXYGEN re-reads warming and error mailboxes on its own; run `warmup sync` for a fresh provider read now. Targets the whole pool unless --mailboxes is given.")
1318
+ .description("Read each mailbox's stored warm-up state: warmupTruth (state, last send, pause reason, dispatch counters, next_action), renewal and billing. A pure read: no provider call and no change. OXYGEN re-reads warming and error mailboxes on its own; `warmup sync` refreshes from the provider now and saves the new state (it may pause a runaway mailbox). Targets the whole pool unless --mailboxes is given.")
1319
1319
  .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
1320
1320
  // Retired when status became a pure read (Plain T-317). Hidden, not
1321
1321
  // removed: an old script passing them gets the server's refusal,
@@ -1339,7 +1339,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1339
1339
  });
1340
1340
  }))
1341
1341
  .addCommand(new Command("sync")
1342
- .description("Read warmup analytics back from the rail each mailbox is enrolled on and save them, refreshing each mailbox's warmupTruth. 0 Oxygen credits, no campaign sends, no change to your configuration; OXYGEN's breaker may pause a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. `warmup status` reads the saved result without a provider call.")
1342
+ .description("Read warmup analytics back from the rail each mailbox is enrolled on and save them, refreshing each mailbox's warmupTruth. 0 Oxygen credits and no campaign sends. It leaves your warm-up settings alone, but it writes: the saved state changes, and OXYGEN's breaker may pause a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. `warmup status` reads the saved result without a provider call.")
1343
1343
  .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to sync. Omit to sync the whole pool.")
1344
1344
  .option("--provider <name>", "Optional machine routing filter. Omit it for OXYGEN Warm-up; pass trulyinbox only to sync inboxes still warming on the retired rail.")
1345
1345
  .option("--dry-run", "Call no provider and save nothing (covered mailboxes show pending).")
@@ -0,0 +1,58 @@
1
+ /**
2
+ * One export contract for the OTLP collector lane, shared by web and worker.
3
+ *
4
+ * The SDK pieces disagree about time unless told otherwise. A BatchSpanProcessor
5
+ * stops waiting for an export at `exportTimeoutMillis` and immediately starts the
6
+ * next batch, but the HTTP request it abandoned is still in flight, and an OTLP
7
+ * exporter built with `concurrencyLimit: 1` answers any second export with
8
+ * `Concurrent export limit reached`, dropping that whole batch unsent. With both
9
+ * timeouts at 5 s, one slow request (a cold TLS connection at container start, a
10
+ * collector-ingress stall) cost the slow batch and then every batch behind it
11
+ * (SigNoz 2026-11-13: ~150k prod / ~200k dev spans in 7 days, mostly
12
+ * `concurrency_limit`). `serializeTelemetryExports` makes that overlap queue
13
+ * instead of fail, and these settings give a slow collector room before a batch
14
+ * is given up.
15
+ */
16
+ /** Per-request budget of the HTTP exporter, retries included. */
17
+ export declare const OTLP_COLLECTOR_EXPORT_TIMEOUT_MS = 10000;
18
+ /**
19
+ * BatchSpanProcessor settings for the collector lane. `exportTimeoutMillis`
20
+ * stays well above the exporter's own budget so the processor does not give up
21
+ * on a batch the exporter is still sending; the queue holds a stall's worth of
22
+ * spans (a full queue is reported as `telemetry.export_dropped`).
23
+ */
24
+ export declare const OTLP_COLLECTOR_SPAN_BATCH: {
25
+ readonly maxQueueSize: 8192;
26
+ readonly maxExportBatchSize: 512;
27
+ readonly scheduledDelayMillis: 2000;
28
+ readonly exportTimeoutMillis: number;
29
+ };
30
+ /** A PeriodicExportingMetricReader rejects a timeout above its interval. */
31
+ export declare function otlpCollectorMetricReaderTimeoutMs(exportIntervalMillis: number): number;
32
+ export declare const TELEMETRY_EXPORT_QUEUE_FULL_MESSAGE = "OTLP export queue full";
33
+ type ExportResultLike = {
34
+ code: number;
35
+ error?: Error | undefined;
36
+ };
37
+ type ExportCallback = (result: ExportResultLike) => void;
38
+ type SerializableExporter = {
39
+ export(items: never, resultCallback: ExportCallback): void;
40
+ shutdown(): Promise<void>;
41
+ forceFlush?(): Promise<void>;
42
+ };
43
+ export type SerializeTelemetryExportsOptions = {
44
+ maxPending?: number | undefined;
45
+ };
46
+ /**
47
+ * Hands `inner` one export at a time. An export that arrives while another is in
48
+ * flight waits its turn (FIFO) instead of reaching the exporter's concurrency
49
+ * limit; only a backlog beyond `maxPending` fails, with a fixed message the
50
+ * export observer classifies as `queue_full`. `forceFlush` and `shutdown` wait for
51
+ * the backlog first, so a BatchSpanProcessor flushing several batches at once
52
+ * (forceFlush, shutdown) delivers all of them.
53
+ *
54
+ * Never throws from `export`: a synchronous throw from `inner` becomes a failed
55
+ * result, which is what the BatchSpanProcessor makes of it anyway.
56
+ */
57
+ export declare function serializeTelemetryExports<E extends SerializableExporter>(inner: E, options?: SerializeTelemetryExportsOptions): E;
58
+ export {};
@@ -0,0 +1,126 @@
1
+ import { forwardExporterMethods } from "./telemetry-export-observer.js";
2
+ /**
3
+ * One export contract for the OTLP collector lane, shared by web and worker.
4
+ *
5
+ * The SDK pieces disagree about time unless told otherwise. A BatchSpanProcessor
6
+ * stops waiting for an export at `exportTimeoutMillis` and immediately starts the
7
+ * next batch, but the HTTP request it abandoned is still in flight, and an OTLP
8
+ * exporter built with `concurrencyLimit: 1` answers any second export with
9
+ * `Concurrent export limit reached`, dropping that whole batch unsent. With both
10
+ * timeouts at 5 s, one slow request (a cold TLS connection at container start, a
11
+ * collector-ingress stall) cost the slow batch and then every batch behind it
12
+ * (SigNoz 2026-11-13: ~150k prod / ~200k dev spans in 7 days, mostly
13
+ * `concurrency_limit`). `serializeTelemetryExports` makes that overlap queue
14
+ * instead of fail, and these settings give a slow collector room before a batch
15
+ * is given up.
16
+ */
17
+ /** Per-request budget of the HTTP exporter, retries included. */
18
+ export const OTLP_COLLECTOR_EXPORT_TIMEOUT_MS = 10_000;
19
+ /**
20
+ * BatchSpanProcessor settings for the collector lane. `exportTimeoutMillis`
21
+ * stays well above the exporter's own budget so the processor does not give up
22
+ * on a batch the exporter is still sending; the queue holds a stall's worth of
23
+ * spans (a full queue is reported as `telemetry.export_dropped`).
24
+ */
25
+ export const OTLP_COLLECTOR_SPAN_BATCH = {
26
+ maxQueueSize: 8_192,
27
+ maxExportBatchSize: 512,
28
+ scheduledDelayMillis: 2_000,
29
+ exportTimeoutMillis: 3 * OTLP_COLLECTOR_EXPORT_TIMEOUT_MS,
30
+ };
31
+ /** A PeriodicExportingMetricReader rejects a timeout above its interval. */
32
+ export function otlpCollectorMetricReaderTimeoutMs(exportIntervalMillis) {
33
+ return Math.min(exportIntervalMillis, 3 * OTLP_COLLECTOR_EXPORT_TIMEOUT_MS);
34
+ }
35
+ // @opentelemetry/core ExportResultCode.FAILED.
36
+ const EXPORT_RESULT_FAILED = 1;
37
+ /** Batches waiting behind an in-flight export; past this a batch fails as `queue_full`. */
38
+ const DEFAULT_MAX_PENDING_EXPORTS = 16;
39
+ export const TELEMETRY_EXPORT_QUEUE_FULL_MESSAGE = "OTLP export queue full";
40
+ // setImmediate runs after every pending microtask; setTimeout is the fallback
41
+ // where it does not exist (edge/browser bundles never build this lane).
42
+ const deferNext = (run) => {
43
+ if (typeof setImmediate === "function")
44
+ setImmediate(run);
45
+ else
46
+ setTimeout(run, 0);
47
+ };
48
+ /**
49
+ * Hands `inner` one export at a time. An export that arrives while another is in
50
+ * flight waits its turn (FIFO) instead of reaching the exporter's concurrency
51
+ * limit; only a backlog beyond `maxPending` fails, with a fixed message the
52
+ * export observer classifies as `queue_full`. `forceFlush` and `shutdown` wait for
53
+ * the backlog first, so a BatchSpanProcessor flushing several batches at once
54
+ * (forceFlush, shutdown) delivers all of them.
55
+ *
56
+ * Never throws from `export`: a synchronous throw from `inner` becomes a failed
57
+ * result, which is what the BatchSpanProcessor makes of it anyway.
58
+ */
59
+ export function serializeTelemetryExports(inner, options = {}) {
60
+ const maxPending = options.maxPending ?? DEFAULT_MAX_PENDING_EXPORTS;
61
+ const pending = [];
62
+ let inFlight = false;
63
+ let idleWaiters = [];
64
+ const settleIdle = () => {
65
+ if (inFlight || pending.length > 0)
66
+ return;
67
+ const waiters = idleWaiters;
68
+ idleWaiters = [];
69
+ for (const resolve of waiters)
70
+ resolve();
71
+ };
72
+ const runNext = () => {
73
+ const next = pending.shift();
74
+ if (!next) {
75
+ inFlight = false;
76
+ settleIdle();
77
+ return;
78
+ }
79
+ inFlight = true;
80
+ let settled = false;
81
+ const done = (result) => {
82
+ if (settled)
83
+ return;
84
+ settled = true;
85
+ try {
86
+ next.callback(result);
87
+ }
88
+ finally {
89
+ // The OTLP delegate reports a result from inside its send promise and
90
+ // releases its concurrency slot only after that promise settles, so the
91
+ // next export must start on a later turn or it meets the limit. Until
92
+ // then `inFlight` stays set and new exports queue.
93
+ deferNext(runNext);
94
+ }
95
+ };
96
+ try {
97
+ inner.export(next.items, done);
98
+ }
99
+ catch (error) {
100
+ done({ code: EXPORT_RESULT_FAILED, error: error instanceof Error ? error : new Error(String(error)) });
101
+ }
102
+ };
103
+ const whenIdle = () => !inFlight && pending.length === 0 ? Promise.resolve() : new Promise((resolve) => idleWaiters.push(resolve));
104
+ const serialized = {};
105
+ forwardExporterMethods(inner, serialized);
106
+ Object.assign(serialized, {
107
+ export(items, resultCallback) {
108
+ if (pending.length >= maxPending) {
109
+ resultCallback({ code: EXPORT_RESULT_FAILED, error: new Error(TELEMETRY_EXPORT_QUEUE_FULL_MESSAGE) });
110
+ return;
111
+ }
112
+ pending.push({ items, callback: resultCallback });
113
+ if (!inFlight)
114
+ runNext();
115
+ },
116
+ async forceFlush() {
117
+ await whenIdle();
118
+ await inner.forceFlush?.();
119
+ },
120
+ async shutdown() {
121
+ await whenIdle();
122
+ await inner.shutdown();
123
+ },
124
+ });
125
+ return serialized;
126
+ }
@@ -72,6 +72,9 @@ export function classifyTelemetryExportError(error) {
72
72
  return { error_code: "timeout" };
73
73
  if (/concurren(?:t|cy) (?:export )?limit/i.test(message))
74
74
  return { error_code: "concurrency_limit" };
75
+ // serializeTelemetryExports (otlp-collector-export) refusing a backlog.
76
+ if (/^OTLP export queue full$/.test(message))
77
+ return { error_code: "queue_full" };
75
78
  if (/retryable status/i.test(message))
76
79
  return { error_code: "http_retryable" };
77
80
  if (/exceeded size limit/i.test(message))
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1042.30";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1043.4";
@@ -1,2 +1,2 @@
1
1
  // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
2
- export const OXYGEN_BUILD_VERSION = "1.1042.30";
2
+ export const OXYGEN_BUILD_VERSION = "1.1043.4";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxygen-agent/cli",
3
- "version": "1.1042.30",
3
+ "version": "1.1043.4",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",