@mupt-ai/dari-gateway 0.2.0 → 0.2.1

package/dist/runtime/harness_identity/conversation.d.ts

@@ -0,0 +1,33 @@
+import type { SourceProtocol } from "../../interaction/types.js";
+export type HarnessConversationIdentity = {
+    kind: "codex_thread";
+    value: string;
+    parentThreadId?: string;
+    qualifiers?: string[];
+    userTurnId?: string;
+} | {
+    kind: "claude_code_session";
+    value: string;
+    qualifiers?: string[];
+} | {
+    kind: "openai_chat_session";
+    value: string;
+    qualifiers?: string[];
+};
+export type HarnessConversationScope = {
+    organizationId: string;
+    routerId: string;
+    apiKeyId: string | null;
+    attributedUserId: string | null;
+};
+export declare function scopedHarnessSessionId(args: {
+    identity: HarnessConversationIdentity;
+    sourceProtocol: SourceProtocol;
+    scope: HarnessConversationScope;
+}): string;
+export declare function scopedHarnessConversationId(args: {
+    identity: HarnessConversationIdentity;
+    sourceProtocol: SourceProtocol;
+    scope: HarnessConversationScope;
+    conversationPrefix: string;
+}): string;

package/dist/runtime/harness_identity/conversation.js

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+const PREFIX = "hconv_";
+// The conversation id is the fallback provider prompt_cache_key for callers
+// that send none (Codex sends thread metadata, not a cache key). OpenAI rejects
+// a prompt_cache_key longer than 64 characters, so the id must fit that budget.
+const MAX_CONVERSATION_ID_CHARS = 64;
+const DIGEST_CHARS = MAX_CONVERSATION_ID_CHARS - PREFIX.length;
+export function scopedHarnessSessionId(args) {
+    const identity = args.identity.kind === "codex_thread" && args.identity.parentThreadId
+        ? { ...args.identity, value: args.identity.parentThreadId }
+        : args.identity;
+    return scopedHarnessId({ ...args, identity });
+}
+export function scopedHarnessConversationId(args) {
+    return scopedHarnessId(args, args.conversationPrefix);
+}
+function scopedHarnessId(args, conversationPrefix) {
+    const subject = args.scope.apiKeyId !== null
+        ? ["api_key", args.scope.apiKeyId]
+        : args.scope.attributedUserId !== null
+            ? ["user", args.scope.attributedUserId]
+            : ["organization_runtime", args.scope.organizationId];
+    const identity = [
+        args.identity.kind,
+        args.identity.value,
+        ...(args.identity.qualifiers ?? []),
+    ];
+    const digest = createHash("sha256")
+        .update(JSON.stringify([
+        args.scope.organizationId,
+        args.scope.routerId,
+        subject,
+        args.sourceProtocol,
+        ...identity,
+        ...(conversationPrefix === undefined ? [] : [conversationPrefix]),
+    ]))
+        .digest("hex");
+    return `${PREFIX}${digest.slice(0, DIGEST_CHARS)}`;
+}

package/dist/runtime/harness_identity/extract.d.ts

@@ -0,0 +1,8 @@
+import type { AgentRequestContext, InteractionRequestPurpose } from "../../interaction/types.js";
+import type { HarnessConversationIdentity } from "./conversation.js";
+export declare function chatCompletionsConversationIdentity(headers: Headers, promptCacheKey?: string): HarnessConversationIdentity | undefined;
+export declare function openCodeRequestContext(headers: Headers): AgentRequestContext | undefined;
+export declare function codexConversationIdentity(headers: Headers, payload: Record<string, unknown>): HarnessConversationIdentity | undefined;
+export declare function codexRequestPurpose(headers: Headers, payload: Record<string, unknown>): InteractionRequestPurpose | undefined;
+export declare function codexRequestContext(headers: Headers, payload: Record<string, unknown>): AgentRequestContext | undefined;
+export declare function claudeCodeConversationIdentity(headers: Headers, metadataSessionId?: string): HarnessConversationIdentity | undefined;

package/dist/runtime/harness_identity/extract.js

@@ -0,0 +1,214 @@
+import { isRecord } from "@mupt-ai/dari-router/policy-engine";
+import { HttpError } from "../../http/errors.js";
+const MAX_ID_CHARS = 200;
+export function chatCompletionsConversationIdentity(headers, promptCacheKey) {
+    // x-session-affinity is the authoritative Chat Completions identity.
+    // Fall back to prompt_cache_key from the request body for callers that
+    // send a stable cache key without the affinity header, so append-only
+    // sessions (growing message history) stay grouped under one conversation.
+    const sessionId = boundedIdentity(headers.get("x-session-affinity"), "x-session-affinity") ?? boundedIdentity(promptCacheKey, "prompt_cache_key");
+    if (sessionId === undefined)
+        return undefined;
+    // OpenCode sends a subagent's parent session as its affinity, so subagents
+    // share the parent's session. Scope each one to its own composite identity,
+    // as Claude Code subagents are, so it keeps its own conversation and lease.
+    const subagentId = openCodeSubagentId(headers);
+    return {
+        kind: "openai_chat_session",
+        value: sessionId,
+        ...(subagentId === undefined ? {} : { qualifiers: [subagentId] }),
+    };
+}
+// OpenCode names the session behind every request, and a subagent's parent
+// session too. The `dari opencode` plugin adds the request kind and agent,
+// which OpenCode does not send itself. Like Claude Code's headers, these are
+// client-supplied routing hints, never inferred from prompt text.
+export function openCodeRequestContext(headers) {
+    if (boundedIdentity(headers.get("x-opencode-session-id"), "x-opencode-session-id") === undefined) {
+        return undefined;
+    }
+    const kind = headers.get("x-opencode-request-kind")?.trim();
+    const subagentId = openCodeSubagentId(headers);
+    const requestClass = kind === "compaction" ? "compaction"
+        : kind === "title" || kind === "generate" ? "auxiliary"
+            : subagentId === undefined ? "main" : "subagent";
+    return {
+        requestClass,
+        ...(subagentId === undefined ? {} : {
+            agentId: subagentId,
+            parentAgentId: boundedIdentity(headers.get("x-opencode-parent-session-id"), "x-opencode-parent-session-id"),
+        }),
+        agentType: boundedIdentity(headers.get("x-opencode-agent"), "x-opencode-agent"),
+    };
+}
+function openCodeSubagentId(headers) {
+    const parent = boundedIdentity(headers.get("x-opencode-parent-session-id"), "x-opencode-parent-session-id");
+    return parent === undefined
+        ? undefined
+        : boundedIdentity(headers.get("x-opencode-session-id"), "x-opencode-session-id");
+}
+export function codexConversationIdentity(headers, payload) {
+    const clientMetadata = isRecord(payload.client_metadata)
+        ? payload.client_metadata
+        : undefined;
+    const turnMetadata = codexTurnMetadataCollection(headers, payload);
+    if (turnMetadata.length === 0) {
+        return undefined;
+    }
+    const candidates = [
+        ...turnMetadata.map((metadata) => uuidIdentity(metadata.thread_id, "x-codex-turn-metadata.thread_id")),
+        uuidIdentity(headers.get("thread-id"), "thread-id"),
+        uuidIdentity(clientMetadata?.thread_id, "client_metadata.thread_id"),
+    ].filter((value) => value !== undefined);
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const [threadId] = candidates;
+    if (candidates.some((candidate) => candidate !== threadId)) {
+        throw new HttpError(400, "Codex thread identity fields must agree.", "invalid_request_error", "thread-id");
+    }
+    const userTurnIds = turnMetadata
+        .map((metadata) => uuidIdentity(metadata.turn_id, "x-codex-turn-metadata.turn_id"))
+        .filter((value) => value !== undefined);
+    const [userTurnId] = userTurnIds;
+    if (userTurnIds.some((candidate) => candidate !== userTurnId)) {
+        throw new HttpError(400, "Codex turn identity fields must agree.", "invalid_request_error", "x-codex-turn-metadata.turn_id");
+    }
+    const parentThreadIds = turnMetadata
+        .map((metadata) => uuidIdentity(metadata.parent_thread_id, "x-codex-turn-metadata.parent_thread_id"))
+        .filter((value) => value !== undefined);
+    const [parentThreadId] = parentThreadIds;
+    if (parentThreadIds.some((candidate) => candidate !== parentThreadId)) {
+        throw new HttpError(400, "Codex parent thread identity fields must agree.", "invalid_request_error", "x-codex-turn-metadata.parent_thread_id");
+    }
+    return {
+        kind: "codex_thread",
+        value: threadId,
+        ...(parentThreadId === undefined ? {} : { parentThreadId }),
+        ...(userTurnId === undefined ? {} : { userTurnId }),
+    };
+}
+export function codexRequestPurpose(headers, payload) {
+    const turnMetadata = codexTurnMetadataCollection(headers, payload);
+    return turnMetadata.length > 0 && turnMetadata.every(isCodexMemoryExtraction)
+        ? "memory_extraction"
+        : undefined;
+}
+export function codexRequestContext(headers, payload) {
+    const metadata = codexTurnMetadataCollection(headers, payload);
+    if (metadata.length === 0)
+        return undefined;
+    // HTTP and body projections must agree before either can classify a turn.
+    const kinds = new Set(metadata.map((entry) => entry.request_kind));
+    const agents = new Set(metadata.map((entry) => entry.subagent_kind));
+    if (kinds.size > 1 || agents.size > 1) {
+        throw new HttpError(400, "Codex request classification fields must agree.", "invalid_request_error", "x-codex-turn-metadata");
+    }
+    const [kind] = kinds;
+    const [agentKind] = agents;
+    const entry = metadata[0];
+    const agentId = uuidIdentity(entry.thread_id, "x-codex-turn-metadata.thread_id");
+    const requestClass = kind === "compaction" ? "compaction"
+        : kind === "memory" || kind === "prewarm" ? "auxiliary"
+            : kind === "turn" && agentKind === "memory_consolidation" ? "auxiliary"
+                : kind === "turn" && agentKind === "compact" ? "compaction"
+                    : kind === "turn" && agentKind !== undefined ? "subagent"
+                        : kind === "turn" ? "main" : "unknown";
+    return {
+        requestClass,
+        ...(requestClass === "subagent" && agentId !== undefined ? { agentId } : {}),
+        parentAgentId: uuidIdentity(entry.parent_thread_id, "x-codex-turn-metadata.parent_thread_id"),
+        agentType: boundedIdentity(agentKind, "x-codex-turn-metadata.subagent_kind"),
+    };
+}
+export function claudeCodeConversationIdentity(headers, metadataSessionId) {
+    const candidates = [
+        uuidIdentity(headers.get("x-claude-code-session-id"), "x-claude-code-session-id"),
+        uuidIdentity(metadataSessionId, "metadata.user_id.session_id"),
+    ].filter((value) => value !== undefined);
+    if (candidates.length === 0)
+        return undefined;
+    const [sessionId] = candidates;
+    if (candidates.some((candidate) => candidate !== sessionId)) {
+        throw new HttpError(400, "Claude Code session identity fields must agree.", "invalid_request_error", "x-claude-code-session-id");
+    }
+    // Claude Code reuses the parent session UUID for every subagent, but gives
+    // each subagent a stable agent header. Keep the parent thread on the bare
+    // session identity and scope each subagent to its own composite identity.
+    // Treat this as an opaque Claude identifier. Besides ordinary subagent IDs,
+    // Claude may send labeled agents or Agent Teams identities such as
+    // `reviewer@backend`; Dari only needs a stable, bounded value to hash.
+    const agentId = boundedIdentity(headers.get("x-claude-code-agent-id"), "x-claude-code-agent-id");
+    return {
+        kind: "claude_code_session",
+        value: sessionId,
+        ...(agentId === undefined ? {} : { qualifiers: [agentId] }),
+    };
+}
+function isCodexMemoryExtraction(metadata) {
+    if (metadata.request_kind !== "memory" ||
+        metadata.thread_source !== "memory_consolidation") {
+        return false;
+    }
+    // Codex deliberately omits canonical turn identity for detached phase-1
+    // memory jobs, while compatibility projections still carry the live root
+    // thread UUID. Phase-2 consolidation agents use ordinary turn metadata and
+    // their own thread identities, so they do not match this shape.
+    return [
+        "session_id",
+        "thread_id",
+        "turn_id",
+        "root_turn_id",
+        "window_id",
+        "forked_from_thread_id",
+    ].every((field) => metadata[field] === undefined);
+}
+function codexTurnMetadataCollection(headers, payload) {
+    const clientMetadata = isRecord(payload.client_metadata)
+        ? payload.client_metadata
+        : undefined;
+    return [
+        codexTurnMetadata(headers.get("x-codex-turn-metadata"), "x-codex-turn-metadata"),
+        codexTurnMetadata(clientMetadata?.["x-codex-turn-metadata"], "client_metadata.x-codex-turn-metadata"),
+    ].filter((value) => value !== undefined);
+}
+function boundedIdentity(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new HttpError(400, `${field} must be a string.`, "invalid_request_error", field);
+    }
+    const normalized = value.trim();
+    if (!normalized)
+        return undefined;
+    if (normalized.length > MAX_ID_CHARS) {
+        throw new HttpError(400, `${field} must not exceed ${MAX_ID_CHARS} characters.`, "invalid_request_error", field);
+    }
+    return normalized;
+}
+function uuidIdentity(value, field) {
+    const normalized = boundedIdentity(value, field);
+    if (normalized === undefined)
+        return undefined;
+    const canonical = normalized.toLowerCase();
+    if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(canonical)) {
+        throw new HttpError(400, `${field} must be a UUID.`, "invalid_request_error", field);
+    }
+    return canonical;
+}
+function codexTurnMetadata(raw, field) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "string") {
+        throw new HttpError(400, `${field} must be a JSON string.`, "invalid_request_error", field);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new HttpError(400, `${field} must contain a JSON object.`, "invalid_request_error", field);
+    }
+}

package/dist/runtime/harness_identity/index.d.ts

@@ -0,0 +1,2 @@
+export { scopedHarnessConversationId, scopedHarnessSessionId, type HarnessConversationIdentity, type HarnessConversationScope, } from "./conversation.js";
+export { chatCompletionsConversationIdentity, claudeCodeConversationIdentity, codexConversationIdentity, codexRequestPurpose, codexRequestContext, openCodeRequestContext, } from "./extract.js";

package/dist/runtime/harness_identity/index.js

@@ -0,0 +1,2 @@
+export { scopedHarnessConversationId, scopedHarnessSessionId, } from "./conversation.js";
+export { chatCompletionsConversationIdentity, claudeCodeConversationIdentity, codexConversationIdentity, codexRequestPurpose, codexRequestContext, openCodeRequestContext, } from "./extract.js";

package/dist/runtime/prepare_routed_completion.d.ts

@@ -0,0 +1,33 @@
+import { type RoutingContext } from "../context/routing_context.js";
+import { type InteractionRequest } from "../interaction/types.js";
+import { type RequestTags } from "../platform/platform.js";
+import type { ClientHarness, ResolvedRouter } from "../types.js";
+import type { RoutedRuntimeReporter } from "./runtime_reporter.js";
+import type { RoutedProtocol } from "./routed_protocol.js";
+import { type HarnessConversationIdentity } from "./harness_identity/index.js";
+export type PreparedRoutedCompletion = {
+    requestId: string;
+    routerId: string;
+    receivedAt: Date;
+    interaction: InteractionRequest;
+    protocol: RoutedProtocol;
+    credentials: ResolvedRouter;
+    billable: boolean;
+    tags: RequestTags;
+    harnessConversationIdentity?: HarnessConversationIdentity;
+    routing: RoutingContext;
+    reporter: RoutedRuntimeReporter;
+};
+export declare function prepareRoutedCompletion(args: {
+    routerId: string;
+    apiKey: string;
+    interaction: InteractionRequest;
+    protocol: RoutedProtocol;
+    receivedAt: Date;
+    startedMs: number;
+    requestId: string;
+    clientRequestId: string | null;
+    tagsHeader: string | null;
+    clientHarness?: ClientHarness;
+    harnessConversationIdentity?: HarnessConversationIdentity;
+}): Promise<PreparedRoutedCompletion>;

package/dist/runtime/prepare_routed_completion.js

@@ -0,0 +1,167 @@
+import { interactionConversationPrefix } from "../context/interaction_fingerprint.js";
+import { buildRoutingContext, derivePrefixLookupHashes, } from "../context/routing_context.js";
+import { isBackgroundRequest } from "../interaction/types.js";
+import { executionProviderForModel } from "../models/execution_provider.js";
+import { gatewayPlatform } from "../platform/platform.js";
+import { resolveRouter } from "../strategies/routing.js";
+import { RequestReporter } from "../telemetry/report.js";
+import { RoutingBillingFinalization } from "../telemetry/billing_finalization.js";
+import { requestTags } from "./request_tags.js";
+import { scopedHarnessConversationId, scopedHarnessSessionId, } from "./harness_identity/index.js";
+export async function prepareRoutedCompletion(args) {
+    const tags = requestTags(args.tagsHeader);
+    // Eval relevance draws from the public catalog, which resolve only returns
+    // on request.
+    const resolveRequest = {
+        routerId: args.routerId,
+        apiKey: args.apiKey,
+        includePublicEvalCatalog: true,
+    };
+    // Direct /v1 callers are authenticated by API key, so their canonical
+    // organization router is not known until this resolve completes. Fingerprint
+    // the stable public alias here; prefix lookup remains tenant-safe because the
+    // platform scopes every hash query to the resolved canonical router.
+    const prefixFingerprintRouterId = args.routerId;
+    const background = isBackgroundRequest(args.interaction);
+    const prefixHashes = background ? [] : derivePrefixLookupHashes(prefixFingerprintRouterId, args.interaction);
+    let credentials = await resolveRouter({
+        ...resolveRequest,
+        prefixHashes,
+        clientHarness: args.clientHarness,
+    });
+    const canonicalRouterId = credentials.router_id;
+    const organizationId = credentials.organization_id;
+    const billingFinalization = new RoutingBillingFinalization({
+        requestId: args.requestId,
+        organizationId,
+    });
+    const harnessScope = {
+        organizationId: credentials.organization_id,
+        routerId: credentials.router_id,
+        apiKeyId: credentials.api_key_id,
+        attributedUserId: credentials.attributed_user_id,
+    };
+    const agentSessionId = args.harnessConversationIdentity === undefined
+        ? undefined
+        : scopedHarnessSessionId({
+            // Subagent qualifiers scope a conversation, not the session it belongs to.
+            identity: { ...args.harnessConversationIdentity, qualifiers: undefined },
+            sourceProtocol: args.interaction.sourceProtocol,
+            scope: harnessScope,
+        });
+    const harnessConversationId = args.harnessConversationIdentity === undefined
+        ? undefined
+        : scopedHarnessConversationId({
+            identity: args.harnessConversationIdentity,
+            sourceProtocol: args.interaction.sourceProtocol,
+            scope: harnessScope,
+            conversationPrefix: args.interaction.agentContext === undefined
+                ? interactionConversationPrefix(args.interaction)
+                : JSON.stringify([
+                    args.interaction.agentContext.requestClass,
+                    interactionConversationPrefix(args.interaction),
+                ]),
+        });
+    if (!background && harnessConversationId !== undefined) {
+        // Hash matches may contain only older history after a client rewrites its
+        // tail. Always resolve the trusted conversation too so lease recovery sees
+        // its latest serving row, not just whichever old prefixes still match.
+        // Unrelated work under the same harness session has a different id.
+        const conversationCredentials = await resolveRouter({
+            ...resolveRequest,
+            prefixHashes,
+            conversationId: harnessConversationId,
+            clientHarness: args.clientHarness,
+        });
+        if (conversationCredentials.organization_id !== organizationId ||
+            conversationCredentials.router_id !== canonicalRouterId) {
+            throw new Error("Repeated router resolution changed request ownership.");
+        }
+        credentials = conversationCredentials;
+    }
+    credentials = await withProviderCredentials(credentials, args.apiKey);
+    const billable = true;
+    const routing = await buildRoutingContext({
+        routerId: prefixFingerprintRouterId,
+        interaction: args.interaction,
+        credentials,
+        explicitConversationId: harnessConversationId,
+        receivedAt: args.receivedAt,
+    });
+    const candidateResolution = routing.candidateResolution;
+    const reporter = new RequestReporter({
+        requestId: args.requestId,
+        clientRequestId: args.clientRequestId,
+        tags,
+        credentials,
+        routerId: canonicalRouterId,
+        interaction: args.interaction,
+        harnessConversationIdentity: args.harnessConversationIdentity,
+        leaseDepth: routing.leaseDepth,
+        providerBlockDepthFor: routing.providerBlockDepthFor,
+        zdr: routing.zdr,
+        strategy: candidateResolution.strategy,
+        receivedAt: args.receivedAt,
+        startedMs: args.startedMs,
+        conversationId: routing.conversationId,
+        isNewConversation: routing.isNewConversation,
+        agentSessionId,
+        identityMatchDepth: routing.identityMatchDepth,
+        identityHit: routing.identityHit,
+        hits: routing.hits,
+        costEstimates: routing.reportingCostEstimates,
+        pruning: reportedPruning(candidateResolution.pruning, routing.imageCapabilityPrunedModels),
+        pricing: routing.pricing,
+        chainByModel: routing.prefix.chainByModel,
+        looseChain: routing.prefix.looseChain,
+        targetsByModel: routing.targetsByModel,
+        fingerprints: routing.prefix.fingerprints,
+        billingFinalization,
+    });
+    return {
+        requestId: args.requestId,
+        routerId: canonicalRouterId,
+        receivedAt: args.receivedAt,
+        interaction: args.interaction,
+        protocol: args.protocol,
+        credentials,
+        billable,
+        tags,
+        harnessConversationIdentity: args.harnessConversationIdentity,
+        routing,
+        reporter,
+    };
+}
+// Ask the platform for each enabled model's credential up front, so provider
+// execution and fallback stay synchronous.
+async function withProviderCredentials(credentials, apiKey) {
+    const platform = gatewayPlatform();
+    if (platform.resolveProviderCredential === undefined)
+        return credentials;
+    const resolved = await Promise.all(credentials.enabled_models.map(async (model) => [
+        model,
+        await platform.resolveProviderCredential({
+            provider: executionProviderForModel(credentials, model),
+            model,
+            routerId: credentials.router_id,
+            organizationId: credentials.organization_id,
+            apiKey,
+        }),
+    ]));
+    const provider_credentials = {};
+    for (const [model, credential] of resolved) {
+        if (credential?.apiKey.trim())
+            provider_credentials[model] = credential;
+    }
+    return { ...credentials, provider_credentials };
+}
+// Core's cache-aware pruning audit, extended with the context layer's image
+// capability exclusions. The exclusions survive on their own when custom
+// routing produced no core audit (missing config), so the error path keeps
+// its candidate_pruning trail.
+function reportedPruning(core, imagePruned) {
+    if (imagePruned === undefined)
+        return core;
+    const capability = { capability_pruned_models: imagePruned };
+    return core === null ? capability : { ...core, ...capability };
+}

package/dist/runtime/provider_stream_lifecycle.d.ts

@@ -0,0 +1,31 @@
+import type { ProviderStreamOutcome } from "./provider_stream_outcome.js";
+type LifecycleArgs = {
+    partialResponse: () => Record<string, unknown>;
+    onFinal?: (outcome: ProviderStreamOutcome) => void;
+    onAbort?: () => void;
+    cancelSignal?: AbortSignal;
+    terminalOutcome?: () => ProviderStreamOutcome | null;
+};
+/**
+ * Owns the cancel/terminal race shared by every hosted streaming protocol.
+ * A provider terminal already observed always wins. Otherwise a client cancel
+ * aborts the provider and finalizes the delivered partial as aborted.
+ */
+export declare class ProviderStreamLifecycle {
+    private readonly args;
+    private clientCanceled;
+    private bodyCanceled;
+    private finalized;
+    private detachCancelSignal;
+    constructor(args: LifecycleArgs);
+    get canWrite(): boolean;
+    get shouldStopConsuming(): boolean;
+    cancel(terminalOutcome: ProviderStreamOutcome | null, bodyCanceled?: boolean): void;
+    finish(args: {
+        outcome: ProviderStreamOutcome;
+        beforeClose?: (outcome: ProviderStreamOutcome) => Promise<void> | void;
+        close: () => void;
+    }): Promise<void>;
+    private finalize;
+}
+export {};

package/dist/runtime/provider_stream_lifecycle.js

@@ -0,0 +1,88 @@
+/**
+ * Owns the cancel/terminal race shared by every hosted streaming protocol.
+ * A provider terminal already observed always wins. Otherwise a client cancel
+ * aborts the provider and finalizes the delivered partial as aborted.
+ */
+export class ProviderStreamLifecycle {
+    args;
+    clientCanceled = false;
+    bodyCanceled = false;
+    finalized = false;
+    detachCancelSignal = () => { };
+    constructor(args) {
+        this.args = args;
+        const cancelSignal = args.cancelSignal;
+        if (cancelSignal !== undefined) {
+            const cancelFromSignal = () => {
+                this.cancel(args.terminalOutcome?.() ?? null, false);
+            };
+            if (cancelSignal.aborted) {
+                cancelFromSignal();
+            }
+            else {
+                cancelSignal.addEventListener("abort", cancelFromSignal, { once: true });
+                this.detachCancelSignal = () => {
+                    cancelSignal.removeEventListener("abort", cancelFromSignal);
+                };
+            }
+        }
+    }
+    get canWrite() {
+        return !this.clientCanceled;
+    }
+    get shouldStopConsuming() {
+        return this.clientCanceled;
+    }
+    cancel(terminalOutcome, bodyCanceled = true) {
+        if (this.clientCanceled) {
+            this.bodyCanceled ||= bodyCanceled;
+            return;
+        }
+        this.clientCanceled = true;
+        this.bodyCanceled = bodyCanceled;
+        if (terminalOutcome !== null) {
+            this.finalize(terminalOutcome);
+            return;
+        }
+        this.args.onAbort?.();
+        this.finalize({
+            status: "aborted",
+            message: null,
+            responseBody: this.args.partialResponse(),
+        });
+    }
+    async finish(args) {
+        if (this.clientCanceled) {
+            if (!this.bodyCanceled) {
+                try {
+                    args.close();
+                }
+                catch {
+                    // Bun may also cancel the body while dispatching request abort.
+                }
+            }
+            return;
+        }
+        if (!this.finalized) {
+            try {
+                await args.beforeClose?.(args.outcome);
+            }
+            catch (error) {
+                console.error("stream finalization barrier failed", error);
+            }
+        }
+        // The client can cancel while beforeClose is awaiting persistence. In that
+        // race cancel() has already finalized the provider terminal outcome.
+        if (this.finalized)
+            return;
+        args.close();
+        this.finalize(args.outcome);
+    }
+    finalize(outcome) {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        this.detachCancelSignal();
+        this.args.onFinal?.(outcome);
+    }
+}

package/dist/runtime/provider_stream_outcome.d.ts

@@ -0,0 +1,23 @@
+import type { InteractionOutput } from "../interaction/types.js";
+export type ProviderStreamOutcome = {
+    status: "completed";
+    message: Record<string, unknown>;
+    output: InteractionOutput;
+} | {
+    status: "provider_error";
+    message: Record<string, unknown>;
+} | {
+    status: "aborted";
+    message: null;
+    responseBody: Record<string, unknown>;
+};
+export declare function isProviderFailureMessage(message: Record<string, unknown>): boolean;
+export declare function providerFailureFromEvent(event: Record<string, unknown>): Record<string, unknown>;
+export declare function providerFailureFromCaught(error: unknown): Record<string, unknown>;
+/**
+ * A terminal provider message remains the source of truth for exact usage even
+ * when translating that message into a client protocol response fails.
+ */
+export declare function providerFailureFromTerminal(error: unknown, terminalMessage: Record<string, unknown>): Record<string, unknown>;
+export declare function providerFailure(message: string): Record<string, unknown>;
+export declare function providerFailureMessage(message: Record<string, unknown>): string;