@trigger.dev/core 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/dist/commonjs/v3/otel/userSpanProcessor.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "@opentelemetry/api";
+import type { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/**
+ * Runs a user-supplied span processor ahead of the Trigger.dev processors.
+ *
+ * The user processor can rewrite or remove any attribute, which is how span
+ * content gets redacted before export. The attributes the platform uses to
+ * link a span to its run and to stitch partial and final spans together are
+ * restored afterwards. A throwing processor is reported to the OTel error
+ * handler instead of escaping into `startSpan` or `span.end()`.
+ */
+export declare class UserSpanProcessorWrapper implements SpanProcessor {
+    private readonly _processor;
+    constructor(_processor: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnding(span: Span): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/commonjs/v3/otel/userSpanProcessor.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserSpanProcessorWrapper = void 0;
+const core_1 = require("@opentelemetry/core");
+const semanticInternalAttributes_js_1 = require("../semanticInternalAttributes.js");
+const RUN_LINKING_KEYS = [
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ENVIRONMENT_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ENVIRONMENT_TYPE,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ORGANIZATION_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.PROJECT_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.RUN_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ATTEMPT_NUMBER,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.TASK_SLUG,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.MACHINE_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.WORKER_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.WORKER_VERSION,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.GEN_AI_CONVERSATION_ID,
+];
+const PROTECTED_ATTRIBUTE_KEYS = new Set([
+    ...RUN_LINKING_KEYS,
+    ...RUN_LINKING_KEYS.map((key) => `${semanticInternalAttributes_js_1.SemanticInternalAttributes.METADATA}.${key}`),
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.SPAN_PARTIAL,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.SKIP_SPAN_PARTIAL,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.SPAN_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.SPAN_ATTEMPT,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ENTITY_TYPE,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ENTITY_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.STYLE_ICON,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.STYLE_VARIANT,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ORIGINAL_RUN_ID,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.ATTEMPT_EXECUTION_COUNT,
+    semanticInternalAttributes_js_1.SemanticInternalAttributes.TASK_EVENT_STORE,
+]);
+function snapshotProtectedAttributes(span) {
+    const snapshot = {};
+    for (const [key, value] of Object.entries(span.attributes)) {
+        if (PROTECTED_ATTRIBUTE_KEYS.has(key)) {
+            snapshot[key] = value;
+        }
+    }
+    return snapshot;
+}
+function restoreProtectedAttributes(span, snapshot) {
+    for (const [key, value] of Object.entries(snapshot)) {
+        if (span.attributes[key] !== value) {
+            span.attributes[key] = value;
+        }
+    }
+}
+function guarded(span, callback) {
+    const snapshot = snapshotProtectedAttributes(span);
+    try {
+        callback();
+    }
+    catch (error) {
+        (0, core_1.globalErrorHandler)(error);
+    }
+    restoreProtectedAttributes(span, snapshot);
+}
+/**
+ * Runs a user-supplied span processor ahead of the Trigger.dev processors.
+ *
+ * The user processor can rewrite or remove any attribute, which is how span
+ * content gets redacted before export. The attributes the platform uses to
+ * link a span to its run and to stitch partial and final spans together are
+ * restored afterwards. A throwing processor is reported to the OTel error
+ * handler instead of escaping into `startSpan` or `span.end()`.
+ */
+class UserSpanProcessorWrapper {
+    _processor;
+    constructor(_processor) {
+        this._processor = _processor;
+    }
+    onStart(span, parentContext) {
+        guarded(span, () => this._processor.onStart(span, parentContext));
+    }
+    onEnding(span) {
+        const onEnding = this._processor.onEnding?.bind(this._processor);
+        if (onEnding) {
+            guarded(span, () => onEnding(span));
+        }
+    }
+    onEnd(span) {
+        guarded(span, () => this._processor.onEnd(span));
+    }
+    forceFlush() {
+        return this._processor.forceFlush();
+    }
+    shutdown() {
+        return this._processor.shutdown();
+    }
+}
+exports.UserSpanProcessorWrapper = UserSpanProcessorWrapper;
+//# sourceMappingURL=userSpanProcessor.js.map

package/dist/commonjs/v3/otel/userSpanProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userSpanProcessor.js","sourceRoot":"","sources":["../../../../src/v3/otel/userSpanProcessor.ts"],"names":[],"mappings":";;;AACA,8CAAyD;AAEzD,oFAA8E;AAE9E,MAAM,gBAAgB,GAAG;IACvB,0DAA0B,CAAC,cAAc;IACzC,0DAA0B,CAAC,gBAAgB;IAC3C,0DAA0B,CAAC,eAAe;IAC1C,0DAA0B,CAAC,UAAU;IACrC,0DAA0B,CAAC,MAAM;IACjC,0DAA0B,CAAC,cAAc;IACzC,0DAA0B,CAAC,SAAS;IACpC,0DAA0B,CAAC,UAAU;IACrC,0DAA0B,CAAC,SAAS;IACpC,0DAA0B,CAAC,cAAc;IACzC,0DAA0B,CAAC,sBAAsB;CAClD,CAAC;AAEF,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAS;IAC/C,GAAG,gBAAgB;IACnB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,0DAA0B,CAAC,QAAQ,IAAI,GAAG,EAAE,CAAC;IACjF,0DAA0B,CAAC,YAAY;IACvC,0DAA0B,CAAC,iBAAiB;IAC5C,0DAA0B,CAAC,OAAO;IAClC,0DAA0B,CAAC,YAAY;IACvC,0DAA0B,CAAC,WAAW;IACtC,0DAA0B,CAAC,SAAS;IACpC,0DAA0B,CAAC,UAAU;IACrC,0DAA0B,CAAC,aAAa;IACxC,0DAA0B,CAAC,eAAe;IAC1C,0DAA0B,CAAC,uBAAuB;IAClD,0DAA0B,CAAC,gBAAgB;CAC5C,CAAC,CAAC;AAEH,SAAS,2BAA2B,CAAC,IAAkB;IACrD,MAAM,QAAQ,GAAe,EAAE,CAAC;IAEhC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,IAAI,wBAAwB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,0BAA0B,CAAC,IAAkB,EAAE,QAAoB;IAC1E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;YACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC/B,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,IAAkB,EAAE,QAAoB;IACvD,MAAM,QAAQ,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;IAEnD,IAAI,CAAC;QACH,QAAQ,EAAE,CAAC;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAA,yBAAkB,EAAC,KAAkB,CAAC,CAAC;IACzC,CAAC;IAED,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH;IAC+B,UAAU;IAAvC,YAA6B,UAAyB;0BAAzB,UAAU;IAAkB,CAAC;IAE1D,OAAO,CAAC,IAAU,EAAE,aAAsB;QACxC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,QAAQ,CAAC,IAAU;QACjB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEjE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAkB;QACtB,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;IACpC,CAAC;CACF"}

package/dist/commonjs/v3/otel/utils.d.ts

@@ -1,2 +1,3 @@
 import { type Span } from "@opentelemetry/api";
 export declare function recordSpanException(span: Span, error: unknown): void;
+export declare function carrierFromContext(): Record<string, string>;

package/dist/commonjs/v3/otel/utils.js

@@ -1,24 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordSpanException = recordSpanException;
+exports.carrierFromContext = carrierFromContext;
 const api_1 = require("@opentelemetry/api");
+const errors_js_1 = require("../errors.js");
+const MAX_GENERIC_LENGTH = 5_000;
+function truncateGeneric(value) {
+    return value.length > MAX_GENERIC_LENGTH
+        ? value.slice(0, MAX_GENERIC_LENGTH) + "...[truncated]"
+        : value;
+}
+function serializeFallback(error) {
+    // JSON.stringify can throw (circular refs, BigInt) or return undefined
+    // (symbol, undefined, function). Fall back to String() in both cases so we
+    // never mask the original error being recorded.
+    try {
+        const json = JSON.stringify(error);
+        if (json != null)
+            return json;
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return String(error);
+    }
+    catch {
+        return "[unserializable error]";
+    }
+}
 function recordSpanException(span, error) {
     if (error instanceof Error) {
         span.recordException(sanitizeSpanError(error));
     }
     else if (typeof error === "string") {
-        span.recordException(error.replace(/\0/g, ""));
+        span.recordException(truncateGeneric(error.replace(/\0/g, "")));
     }
     else {
-        span.recordException(JSON.stringify(error).replace(/\0/g, ""));
+        span.recordException(truncateGeneric(serializeFallback(error).replace(/\0/g, "")));
     }
     span.setStatus({ code: api_1.SpanStatusCode.ERROR });
 }
 function sanitizeSpanError(error) {
-    // Create a new error object with the same name, message and stack trace
-    const sanitizedError = new Error(error.message.replace(/\0/g, ""));
+    const sanitizedError = new Error((0, errors_js_1.truncateMessage)(error.message.replace(/\0/g, "")));
     sanitizedError.name = error.name.replace(/\0/g, "");
-    sanitizedError.stack = error.stack?.replace(/\0/g, "");
+    sanitizedError.stack = (0, errors_js_1.truncateStack)(error.stack?.replace(/\0/g, "")) || undefined;
     return sanitizedError;
 }
+function carrierFromContext() {
+    const carrier = {};
+    api_1.propagation.inject(api_1.context.active(), carrier);
+    return carrier;
+}
 //# sourceMappingURL=utils.js.map

package/dist/commonjs/v3/otel/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/v3/otel/utils.ts"],"names":[],"mappings":";;AAEA,kDAUC;AAZD,4CAA+D;AAE/D,SAAgB,mBAAmB,CAAC,IAAU,EAAE,KAAc;IAC5D,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,oBAAc,CAAC,KAAK,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAY;IACrC,wEAAwE;IACxE,MAAM,cAAc,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACnE,cAAc,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpD,cAAc,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEvD,OAAO,cAAc,CAAC;AACxB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/v3/otel/utils.ts"],"names":[],"mappings":";;;;AAAA,4CAAqF;AACrF,4CAA8D;AAE9D,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,MAAM,GAAG,kBAAkB;QACtC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,GAAG,gBAAgB;QACvD,CAAC,CAAC,KAAK,CAAC;AACZ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,uEAAuE;IACvE,2EAA2E;IAC3E,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,wBAAwB,CAAC;IAClC,CAAC;AACH,CAAC;AAED,6BAAoC,IAAU,EAAE,KAAc;IAC5D,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,oBAAc,CAAC,KAAK,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAY;IACrC,MAAM,cAAc,GAAG,IAAI,KAAK,CAAC,IAAA,2BAAe,EAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,cAAc,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpD,cAAc,CAAC,KAAK,GAAG,IAAA,yBAAa,EAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,SAAS,CAAC;IAEnF,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;IACE,MAAM,OAAO,GAAG,EAAE,CAAC;IACnB,iBAAW,CAAC,MAAM,CAAC,aAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAE9C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/commonjs/v3/realtime-streams-api.d.ts

@@ -0,0 +1,6 @@
+import { RealtimeStreamsAPI } from "./realtimeStreams/index.js";
+export declare const realtimeStreams: RealtimeStreamsAPI;
+export * from "./realtimeStreams/types.js";
+export { SessionStreamInstance } from "./realtimeStreams/sessionStreamInstance.js";
+export type { SessionStreamInstanceOptions, InitializeSessionStreamResponseLike, } from "./realtimeStreams/sessionStreamInstance.js";
+export { trimSessionStream, writeSessionControlRecord, writeTurnCompleteRecord, writeUpgradeRequiredRecord, } from "./realtimeStreams/sessionStreamOneshot.js";

package/dist/commonjs/v3/realtime-streams-api.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeUpgradeRequiredRecord = exports.writeTurnCompleteRecord = exports.writeSessionControlRecord = exports.trimSessionStream = exports.SessionStreamInstance = exports.realtimeStreams = void 0;
+// Split module-level variable definition into separate files to allow
+// tree-shaking on each api instance.
+const index_js_1 = require("./realtimeStreams/index.js");
+exports.realtimeStreams = index_js_1.RealtimeStreamsAPI.getInstance();
+__exportStar(require("./realtimeStreams/types.js"), exports);
+var sessionStreamInstance_js_1 = require("./realtimeStreams/sessionStreamInstance.js");
+Object.defineProperty(exports, "SessionStreamInstance", { enumerable: true, get: function () { return sessionStreamInstance_js_1.SessionStreamInstance; } });
+var sessionStreamOneshot_js_1 = require("./realtimeStreams/sessionStreamOneshot.js");
+Object.defineProperty(exports, "trimSessionStream", { enumerable: true, get: function () { return sessionStreamOneshot_js_1.trimSessionStream; } });
+Object.defineProperty(exports, "writeSessionControlRecord", { enumerable: true, get: function () { return sessionStreamOneshot_js_1.writeSessionControlRecord; } });
+Object.defineProperty(exports, "writeTurnCompleteRecord", { enumerable: true, get: function () { return sessionStreamOneshot_js_1.writeTurnCompleteRecord; } });
+Object.defineProperty(exports, "writeUpgradeRequiredRecord", { enumerable: true, get: function () { return sessionStreamOneshot_js_1.writeUpgradeRequiredRecord; } });
+//# sourceMappingURL=realtime-streams-api.js.map

package/dist/commonjs/v3/realtime-streams-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-streams-api.js","sourceRoot":"","sources":["../../../src/v3/realtime-streams-api.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,sEAAsE;AACtE,qCAAqC;AACrC,yDAAgE;AAEnD,QAAA,eAAe,GAAG,6BAAkB,CAAC,WAAW,EAAE,CAAC;AAEhE,6DAA2C;AAC3C,uFAAmF;AAA1E,iIAAA,qBAAqB,OAAA;AAK9B,qFAKmD;AAJjD,4HAAA,iBAAiB,OAAA;AACjB,oIAAA,yBAAyB,OAAA;AACzB,kIAAA,uBAAuB,OAAA;AACvB,qIAAA,0BAA0B,OAAA"}

package/dist/commonjs/v3/realtimeStreams/index.d.ts

@@ -0,0 +1,10 @@
+import type { RealtimeStreamOperationOptions, RealtimeStreamInstance, RealtimeStreamsManager } from "./types.js";
+export declare class RealtimeStreamsAPI implements RealtimeStreamsManager {
+    #private;
+    private static _instance?;
+    private constructor();
+    static getInstance(): RealtimeStreamsAPI;
+    setGlobalManager(manager: RealtimeStreamsManager): boolean;
+    pipe<T>(key: string, source: AsyncIterable<T> | ReadableStream<T>, options?: RealtimeStreamOperationOptions): RealtimeStreamInstance<T>;
+    append<TPart extends BodyInit>(key: string, part: TPart, options?: RealtimeStreamOperationOptions): Promise<void>;
+}

package/dist/commonjs/v3/realtimeStreams/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeStreamsAPI = void 0;
+const globals_js_1 = require("../utils/globals.js");
+const noopManager_js_1 = require("./noopManager.js");
+// Re-export the session-scoped stream instance so the SDK's
+// `SessionOutputChannel.pipe` / `.writer` can construct it without reaching
+// into the core package's internals.
+const API_NAME = "realtime-streams";
+const NOOP_MANAGER = new noopManager_js_1.NoopRealtimeStreamsManager();
+class RealtimeStreamsAPI {
+    static _instance;
+    constructor() { }
+    static getInstance() {
+        if (!this._instance) {
+            this._instance = new RealtimeStreamsAPI();
+        }
+        return this._instance;
+    }
+    setGlobalManager(manager) {
+        return (0, globals_js_1.registerGlobal)(API_NAME, manager);
+    }
+    #getManager() {
+        return (0, globals_js_1.getGlobal)(API_NAME) ?? NOOP_MANAGER;
+    }
+    pipe(key, source, options) {
+        return this.#getManager().pipe(key, source, options);
+    }
+    append(key, part, options) {
+        return this.#getManager().append(key, part, options);
+    }
+}
+exports.RealtimeStreamsAPI = RealtimeStreamsAPI;
+//# sourceMappingURL=index.js.map

package/dist/commonjs/v3/realtimeStreams/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v3/realtimeStreams/index.ts"],"names":[],"mappings":";;;AAAA,oDAAgE;AAChE,qDAA8D;AAO9D,4DAA4D;AAC5D,4EAA4E;AAC5E,qCAAqC;AACrC,MAAM,QAAQ,GAAG,kBAAkB,CAAC;AAEpC,MAAM,YAAY,GAAG,IAAI,2CAA0B,EAAE,CAAC;AAEtD;IACU,MAAM,CAAC,SAAS,CAAsB;IAE9C,gBAAuB,CAAC;IAEjB,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,IAAI,kBAAkB,EAAE,CAAC;QAC5C,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,gBAAgB,CAAC,OAA+B;QAC9C,OAAO,IAAA,2BAAc,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,WAAW;QACT,OAAO,IAAA,sBAAS,EAAC,QAAQ,CAAC,IAAI,YAAY,CAAC;IAC7C,CAAC;IAEM,IAAI,CACT,GAAW,EACX,MAA4C,EAC5C,OAAwC;QAExC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAEM,MAAM,CACX,GAAW,EACX,IAAW,EACX,OAAwC;QAExC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/commonjs/v3/realtimeStreams/manager.d.ts

@@ -0,0 +1,25 @@
+import type { ApiClient } from "../apiClient/index.js";
+import type { RealtimeStreamInstance, RealtimeStreamOperationOptions, RealtimeStreamsManager } from "./types.js";
+export declare class StandardRealtimeStreamsManager implements RealtimeStreamsManager {
+    private apiClient;
+    private baseUrl;
+    private debug;
+    constructor(apiClient: ApiClient, baseUrl: string, debug?: boolean);
+    private activeStreams;
+    private createStreamCache;
+    reset(): void;
+    private getCachedCreateStream;
+    /**
+     * Reactive invalidation: a writer's `wait()` rejecting can mean the
+     * cached S2 credentials have gone stale (expired token, revoked
+     * access, basin retired), so evict the cached `createStream` response
+     * for `(runId, key)` and let the next `pipe()` re-PUT to mint fresh
+     * credentials. Compare by identity so a fresh promise installed by a
+     * concurrent caller isn't accidentally cleared.
+     */
+    private evictCreateStreamIfStale;
+    pipe<T>(key: string, source: AsyncIterable<T> | ReadableStream<T>, options?: RealtimeStreamOperationOptions): RealtimeStreamInstance<T>;
+    append<TPart extends BodyInit>(key: string, part: TPart, options?: RealtimeStreamOperationOptions): Promise<void>;
+    hasActiveStreams(): boolean;
+    waitForAllStreams(timeout?: number): Promise<void>;
+}

package/dist/commonjs/v3/realtimeStreams/manager.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandardRealtimeStreamsManager = void 0;
+const asyncIterableStream_js_1 = require("../streams/asyncIterableStream.js");
+const task_context_api_js_1 = require("../task-context-api.js");
+const streamInstance_js_1 = require("./streamInstance.js");
+class StandardRealtimeStreamsManager {
+    apiClient;
+    baseUrl;
+    debug;
+    constructor(apiClient, baseUrl, debug = false) {
+        this.apiClient = apiClient;
+        this.baseUrl = baseUrl;
+        this.debug = debug;
+    }
+    // Track active streams - using a Set allows multiple streams for the same key to coexist
+    activeStreams = new Set();
+    // Cache of in-flight / resolved `createStream` responses, keyed by
+    // `${runId}:${key}`. S2 v2 access tokens are scoped to the org basin
+    // (default 1-day TTL server-side) so reusing them across repeated
+    // `pipe()` calls for the same `(runId, key)` is safe, and avoids the
+    // per-call PUT that pushes `streamId` onto `TaskRun.realtimeStreams`,
+    // which under chat-agent-style hot-loop writers caused row-lock
+    // contention on the writer DB.
+    createStreamCache = new Map();
+    reset() {
+        this.activeStreams.clear();
+        this.createStreamCache.clear();
+    }
+    getCachedCreateStream(runId, key, requestOptions) {
+        const cacheKey = `${runId}:${key}`;
+        const cached = this.createStreamCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const promise = this.apiClient.createStream(runId, "self", key, requestOptions);
+        this.createStreamCache.set(cacheKey, promise);
+        // Evict on failure so the next call retries instead of returning a
+        // poisoned cache entry forever.
+        promise.catch((err) => {
+            if (this.createStreamCache.get(cacheKey) === promise) {
+                this.createStreamCache.delete(cacheKey);
+            }
+        });
+        return promise;
+    }
+    /**
+     * Reactive invalidation: a writer's `wait()` rejecting can mean the
+     * cached S2 credentials have gone stale (expired token, revoked
+     * access, basin retired), so evict the cached `createStream` response
+     * for `(runId, key)` and let the next `pipe()` re-PUT to mint fresh
+     * credentials. Compare by identity so a fresh promise installed by a
+     * concurrent caller isn't accidentally cleared.
+     */
+    evictCreateStreamIfStale(runId, key, expected) {
+        const cacheKey = `${runId}:${key}`;
+        if (this.createStreamCache.get(cacheKey) === expected) {
+            this.createStreamCache.delete(cacheKey);
+        }
+    }
+    pipe(key, source, options) {
+        // Normalize ReadableStream to AsyncIterable
+        const readableStreamSource = (0, asyncIterableStream_js_1.ensureReadableStream)(source);
+        const runId = getRunIdForOptions(options);
+        if (!runId) {
+            throw new Error("Could not determine the target run ID for the realtime stream. Please specify a target run ID using the `target` option.");
+        }
+        // Create an AbortController for this stream
+        const abortController = new AbortController();
+        // Chain with user-provided signal if present
+        const combinedSignal = options?.signal
+            ? (AbortSignal.any?.([options.signal, abortController.signal]) ?? abortController.signal)
+            : abortController.signal;
+        // Capture which cached promise this writer uses so reactive
+        // invalidation below evicts only if the cache still holds it (a
+        // concurrent caller may have already refreshed it).
+        const activeCreatePromise = this.getCachedCreateStream(runId, key, options?.requestOptions);
+        const streamInstance = new streamInstance_js_1.StreamInstance({
+            apiClient: this.apiClient,
+            baseUrl: this.baseUrl,
+            runId,
+            key,
+            source: readableStreamSource,
+            signal: combinedSignal,
+            requestOptions: options?.requestOptions,
+            target: options?.target,
+            debug: this.debug,
+            createStream: () => activeCreatePromise,
+        });
+        // Register this stream
+        const streamInfo = { wait: () => streamInstance.wait(), abortController };
+        this.activeStreams.add(streamInfo);
+        // Single internal chain that handles activeStreams cleanup AND
+        // reactive invalidation. On rejection we evict the cached
+        // `createStream` entry so the next pipe() for the same `(runId, key)`
+        // re-PUTs and recovers (e.g. when a cached S2 access token expired
+        // mid-process). Customer awaiters still observe the rejection via
+        // the returned `wait()`; this chain just keeps the cleanup path
+        // from surfacing as unhandled.
+        streamInstance.wait().then(() => {
+            this.activeStreams.delete(streamInfo);
+        }, (err) => {
+            this.evictCreateStreamIfStale(runId, key, activeCreatePromise);
+            this.activeStreams.delete(streamInfo);
+        });
+        return {
+            wait: () => streamInstance.wait(),
+            stream: streamInstance.stream,
+        };
+    }
+    async append(key, part, options) {
+        const runId = getRunIdForOptions(options);
+        if (!runId) {
+            throw new Error("Could not determine the target run ID for the realtime stream. Please specify a target run ID using the `target` option.");
+        }
+        const result = await this.apiClient.appendToStream(runId, "self", key, part, options?.requestOptions);
+        if (!result.ok) {
+            throw new Error(`Failed to append to stream: ${result.message ?? "Unknown error"}`);
+        }
+    }
+    hasActiveStreams() {
+        return this.activeStreams.size > 0;
+    }
+    // Waits for all the streams to finish
+    async waitForAllStreams(timeout = 60_000) {
+        if (this.activeStreams.size === 0) {
+            return;
+        }
+        const promises = Array.from(this.activeStreams).map((stream) => stream.wait());
+        // Create a timeout promise that resolves to a special sentinel value
+        const TIMEOUT_SENTINEL = Symbol("timeout");
+        const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeout));
+        // Race between all streams completing/rejecting and the timeout
+        const result = await Promise.race([Promise.all(promises), timeoutPromise]);
+        // Check if we timed out
+        if (result === TIMEOUT_SENTINEL) {
+            // Timeout occurred - abort all active streams
+            const abortedCount = this.activeStreams.size;
+            for (const streamInfo of this.activeStreams) {
+                streamInfo.abortController.abort();
+                this.activeStreams.delete(streamInfo);
+            }
+            throw new Error(`Timeout waiting for streams to finish after ${timeout}ms. Aborted ${abortedCount} active stream(s).`);
+        }
+        // If we reach here, Promise.all completed (either all resolved or one rejected)
+        // Any rejection from Promise.all will have already propagated
+    }
+}
+exports.StandardRealtimeStreamsManager = StandardRealtimeStreamsManager;
+function getRunIdForOptions(options) {
+    if (options?.target) {
+        if (options.target === "parent") {
+            return task_context_api_js_1.taskContext.ctx?.run?.parentTaskRunId ?? task_context_api_js_1.taskContext.ctx?.run?.id;
+        }
+        if (options.target === "root") {
+            return task_context_api_js_1.taskContext.ctx?.run?.rootTaskRunId ?? task_context_api_js_1.taskContext.ctx?.run?.id;
+        }
+        if (options.target === "self") {
+            return task_context_api_js_1.taskContext.ctx?.run?.id;
+        }
+        return options.target;
+    }
+    return task_context_api_js_1.taskContext.ctx?.run?.id;
+}
+//# sourceMappingURL=manager.js.map

package/dist/commonjs/v3/realtimeStreams/manager.js.map

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

package/dist/commonjs/v3/realtimeStreams/noopManager.d.ts

@@ -0,0 +1,5 @@
+import type { RealtimeStreamOperationOptions, RealtimeStreamInstance, RealtimeStreamsManager } from "./types.js";
+export declare class NoopRealtimeStreamsManager implements RealtimeStreamsManager {
+    pipe<T>(key: string, source: AsyncIterable<T> | ReadableStream<T>, options?: RealtimeStreamOperationOptions): RealtimeStreamInstance<T>;
+    append<TPart extends BodyInit>(key: string, part: TPart, options?: RealtimeStreamOperationOptions): Promise<void>;
+}

package/dist/commonjs/v3/realtimeStreams/noopManager.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopRealtimeStreamsManager = void 0;
+const asyncIterableStream_js_1 = require("../streams/asyncIterableStream.js");
+class NoopRealtimeStreamsManager {
+    pipe(key, source, options) {
+        return {
+            wait: () => Promise.resolve({}),
+            get stream() {
+                return (0, asyncIterableStream_js_1.createAsyncIterableStreamFromAsyncIterable)(source);
+            },
+        };
+    }
+    async append(key, part, options) { }
+}
+exports.NoopRealtimeStreamsManager = NoopRealtimeStreamsManager;
+//# sourceMappingURL=noopManager.js.map

package/dist/commonjs/v3/realtimeStreams/noopManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noopManager.js","sourceRoot":"","sources":["../../../../src/v3/realtimeStreams/noopManager.ts"],"names":[],"mappings":";;;AACA,8EAA+F;AAO/F;IACS,IAAI,CACT,GAAW,EACX,MAA4C,EAC5C,OAAwC;QAExC,OAAO;YACL,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,IAAI,MAAM;gBACR,OAAO,IAAA,mEAA0C,EAAC,MAAM,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;IAEM,KAAK,CAAC,MAAM,CACjB,GAAW,EACX,IAAW,EACX,OAAwC,IACxB,CAAC;CACpB"}

package/dist/commonjs/v3/realtimeStreams/sessionStreamInstance.d.ts

@@ -0,0 +1,41 @@
+import type { ApiClient } from "../apiClient/index.js";
+import type { AsyncIterableStream } from "../streams/asyncIterableStream.js";
+import type { AnyZodFetchOptions } from "../zodfetch.js";
+import type { StreamsWriter, StreamWriteResult } from "./types.js";
+export type InitializeSessionStreamResponseLike = {
+    headers?: Record<string, string>;
+};
+export type SessionStreamInstanceOptions<T> = {
+    apiClient: ApiClient;
+    baseUrl: string;
+    sessionId: string;
+    io: "out" | "in";
+    source: ReadableStream<T>;
+    signal?: AbortSignal;
+    requestOptions?: AnyZodFetchOptions;
+    debug?: boolean;
+    /**
+     * Optional override for the initialize-session-stream call. Defaults to
+     * `apiClient.initializeSessionStream(sessionId, io, requestOptions)`. The
+     * channel passes a cached version so repeated `pipe()` / `writer()`
+     * calls for the same `(sessionId, io)` share a single PUT instead of
+     * hammering the server on every chunk.
+     */
+    initializeSession?: () => Promise<InitializeSessionStreamResponseLike>;
+};
+/**
+ * Session-scoped parallel to {@link StreamInstance}. Calls
+ * `initializeSessionStream` to fetch S2 credentials for the session's
+ * channel, then pipes `source` directly to S2 via {@link StreamsWriterV2}.
+ *
+ * Sessions are S2-only — there's no v1 (Redis) fallback — so this
+ * skips the version-detection dance `StreamInstance` does.
+ */
+export declare class SessionStreamInstance<T> implements StreamsWriter {
+    private options;
+    private streamPromise;
+    constructor(options: SessionStreamInstanceOptions<T>);
+    private initializeWriter;
+    wait(): Promise<StreamWriteResult>;
+    get stream(): AsyncIterableStream<T>;
+}

package/dist/commonjs/v3/realtimeStreams/sessionStreamInstance.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStreamInstance = void 0;
+const streamsWriterV2_js_1 = require("./streamsWriterV2.js");
+/**
+ * Session-scoped parallel to {@link StreamInstance}. Calls
+ * `initializeSessionStream` to fetch S2 credentials for the session's
+ * channel, then pipes `source` directly to S2 via {@link StreamsWriterV2}.
+ *
+ * Sessions are S2-only — there's no v1 (Redis) fallback — so this
+ * skips the version-detection dance `StreamInstance` does.
+ */
+class SessionStreamInstance {
+    options;
+    streamPromise;
+    constructor(options) {
+        this.options = options;
+        this.streamPromise = this.initializeWriter();
+        // Same detached-writer guard as `StreamsWriterV2`: the error is still
+        // surfaced by `wait()` / `stream`.
+        this.streamPromise.catch(() => { });
+    }
+    async initializeWriter() {
+        const initializeFn = this.options.initializeSession ??
+            (() => this.options.apiClient.initializeSessionStream(this.options.sessionId, this.options.io, this.options?.requestOptions));
+        const response = await initializeFn();
+        const headers = response.headers ?? {};
+        const accessToken = headers["x-s2-access-token"];
+        const basin = headers["x-s2-basin"];
+        const streamName = headers["x-s2-stream-name"];
+        const endpoint = headers["x-s2-endpoint"];
+        const flushIntervalMs = headers["x-s2-flush-interval-ms"]
+            ? parseInt(headers["x-s2-flush-interval-ms"])
+            : undefined;
+        const maxRetries = headers["x-s2-max-retries"]
+            ? parseInt(headers["x-s2-max-retries"])
+            : undefined;
+        if (!accessToken || !basin || !streamName) {
+            throw new Error("Session stream initialize did not return S2 credentials — server may be configured for v1 realtime streams, which sessions do not support.");
+        }
+        return new streamsWriterV2_js_1.StreamsWriterV2({
+            basin,
+            stream: streamName,
+            accessToken,
+            endpoint,
+            source: this.options.source,
+            signal: this.options.signal,
+            debug: this.options.debug,
+            flushIntervalMs,
+            maxRetries,
+        });
+    }
+    async wait() {
+        const writer = await this.streamPromise;
+        return writer.wait();
+    }
+    get stream() {
+        // eslint-disable-next-line no-this-alias
+        const self = this;
+        return new ReadableStream({
+            async start(controller) {
+                const streamWriter = await self.streamPromise;
+                const iterator = streamWriter[Symbol.asyncIterator]();
+                while (true) {
+                    if (self.options.signal?.aborted) {
+                        controller.close();
+                        break;
+                    }
+                    const { done, value } = await iterator.next();
+                    if (done) {
+                        controller.close();
+                        break;
+                    }
+                    controller.enqueue(value);
+                }
+            },
+        });
+    }
+}
+exports.SessionStreamInstance = SessionStreamInstance;
+//# sourceMappingURL=sessionStreamInstance.js.map