@mupt-ai/dari-gateway 0.3.1 → 0.3.3

package/README.md

@@ -36,27 +36,26 @@ The gateway is the same runtime that serves Dari's hosted routing service. Choos
 
 ## Run
 
-Requires [Bun](https://bun.sh) 1.3 or later.
+Requires [Bun](https://bun.sh) 1.3 or later. Write a `dari-gateway.yaml` (start from [`dari-gateway.example.yaml`](dari-gateway.example.yaml)), then:
 
 ```bash
-cp dari-gateway.example.yaml dari-gateway.yaml   # edit routers and models
 export DARI_GATEWAY_KEYS="$(openssl rand -hex 24)" # keys your clients send
 export ANTHROPIC_API_KEY=... OPENAI_API_KEY=...    # optional with subscriptions
-bun install
-bun run start
+bunx @mupt-ai/dari-gateway
 ```
 
-Or with Docker, from the repository root:
+Or with Docker:
 
 ```bash
-docker build -f dari-gateway/Dockerfile -t dari-gateway .
 docker run -p 8080:8080 \
   -e DARI_GATEWAY_KEYS -e ANTHROPIC_API_KEY \
   -v "$PWD/dari-gateway.yaml:/config/dari-gateway.yaml" \
   -v dari-gateway-data:/data \
-  dari-gateway
+  ghcr.io/mupt-ai/dari-gateway
 ```
 
+From a clone, `bun install && bun run start` or `docker build -t dari-gateway .` run the same thing.
+
 | Variable | Meaning |
 | --- | --- |
 | `DARI_GATEWAY_KEYS` | Required. Comma-separated bearer keys clients authenticate with. |
@@ -64,6 +63,7 @@ docker run -p 8080:8080 \
 | `DARI_GATEWAY_DB` | SQLite database for subscriptions and conversation state. Default `dari-gateway.db`. It stores subscription tokens in plaintext; protect it like a secret. |
 | `DARI_AUTO_ROUTING_API_KEY` | Optional. Select among a router's models with Dari Auto Routing. |
 | `PORT` | Listen port. Default `8080`. |
+| `DARI_GATEWAY_HOST` | Listen address. Default `127.0.0.1`, so only this machine can connect. The container image sets `0.0.0.0`; set it yourself to expose a process on your network. |
 | Provider keys | Each provider's standard variable, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `META_API_KEY`, or `OPENROUTER_API_KEY`. |
 
 ## Configure
@@ -75,8 +75,8 @@ routers:
       - anthropic/claude-sonnet-5-5
       - id: openai/gpt-5.5
         thinking: [medium, high]
-    fallback: true         # retry the next model when a provider fails
     subscriptions: true    # prefer connected subscriptions over API keys
+    sessionPinning: false  # route each session and subagent once, then keep its model
   local:                   # serves /local/v1/...
     models: [local/qwen3-coder]
 
@@ -106,7 +106,7 @@ In gateway mode the CLI makes no calls to Dari's hosted API. `dari credentials s
 
 ## Embed
 
-Deployments with their own storage and accounting compose the runtime with a `GatewayPlatform` (router resolution, conversation state, subscription holds, request records, error reporting) and a selector backend:
+Deployments with their own storage and accounting compose the runtime with a `GatewayPlatform` (router resolution, conversation state, session pins, subscription holds, request records, error reporting) and a selector backend:
 
 ```ts
 import { createPrioritySelectorBackend, createRequestHandler } from "@mupt-ai/dari-gateway";
@@ -120,19 +120,26 @@ The root entry needs no Bun APIs, so any runtime with web-standard `fetch`, `Req
 Platforms can also:
 
 - implement `resolveProviderCredential({ provider, model, routerId, organizationId, apiKey, clientHarness? })` to supply a per-request `{ apiKey, baseUrl?, headers?, subscription? }`, such as a tenant's own key, in place of the router's resolved key. With `subscription` (`"openai_codex"`, `"anthropic_claude_code"`, or `"meta_muse"`), `apiKey` is that plan's access token: Codex's `auth.json` `tokens.access_token`, the token `claude setup-token` prints, or the Model API key a Meta sign-in mints. The platform keeps it fresh. Strict routers serve these supplied plans, but never subscriptions the gateway resolved itself. A plan serves only its own provider's models; a Claude Code plan serves only Claude Code clients, and a Muse Code plan only Muse Code clients (recognized by their `x-client-id`);
-- resolve routers with `strict: true` to serve only the requested `dari/model/<id>` at the requested thinking level, with no selector, lease, fallback, or personal subscription. Set `strict_providers: ["openai"]` on the resolved router to permit any bundled-catalog model from that provider without enumerating `enabled_models`. Use `dari/model/openai/gpt-5.5`; bare IDs and unknown models remain refused. This grant is ignored on non-strict routers and does not discover uncatalogued models;
+- resolve routers with `strict: true` to serve only the requested `dari/model/<id>` at the requested thinking level, with no selector, lease, or personal subscription. Set `strict_providers: ["openai"]` on the resolved router to permit any bundled-catalog model from that provider without enumerating `enabled_models`. Use `dari/model/openai/gpt-5.5`; bare IDs and unknown models remain refused. This grant is ignored on non-strict routers and does not discover uncatalogued models;
+- resolve routers with `session_pinning: true` to route each session once and serve that pair for the rest of the session. Each subagent (Claude Code agent id, Codex subagent thread, OpenCode child session) is routed once on its own. Pins are kept through `readSessionPin` and `writeSessionPin`, keyed by router and an opaque pin key; background requests and `dari/model/<id>` requests never use them;
 - read exact usage from `recordRequest`: the summary carries input, output, cache-read, and cache-write tokens and `total_cost_usd`, preferring the provider's billed cost (`cost_source: "provider"`, from OpenRouter and Vercel AI Gateway). Failed and aborted requests are recorded too;
 - attribute cost with `X-Dari-Tags: run=r1,trial=3`, which is parsed into `RequestRecord.tags` and the `recordUsage` payload's `tags`.
 
 ## Development
 
 ```bash
-(cd ../dari-router && bun install --frozen-lockfile && bun run build)
 bun install --frozen-lockfile
 bun run typecheck
 bun test
 ```
 
+This package depends on the published `@mupt-ai/dari-router`. To test against a local router checkout inside the monorepo, build it and link it after installing:
+
+```bash
+(cd ../dari-router && bun install --frozen-lockfile && bun run build)
+../scripts/link-gateway-router.sh
+```
+
 Tests make no provider or network calls.
 
 ## License

package/dari-gateway.example.yaml

@@ -9,11 +9,12 @@ routers:
       - anthropic/claude-sonnet-5-5
       - id: openai/gpt-5.5
         thinking: [medium, high]
-    # Retry the next model when a provider fails (default true).
-    fallback: true
     # Serve with connected Claude Code / ChatGPT subscriptions before API
     # keys (default true).
     subscriptions: true
+    # Route each session's first turn, then keep that model for the whole
+    # session; each subagent is routed once on its own (default false).
+    sessionPinning: false
 
   local:
     models:

package/dist/context/interaction_fingerprint.js

@@ -59,7 +59,7 @@ export function interactionLooseChain(routerId, request) {
 // transcript step. Growing history and tool changes preserve identity, while
 // unrelated work reusing the same harness session gets a new group.
 export function interactionConversationPrefix(request) {
-    const firstStep = conversationFingerprintSteps(looseFingerprintSteps(request.sourceProtocol, request.items)).at(0);
+    const firstStep = conversationFingerprintSteps(looseFingerprintSteps(request.sourceProtocol, request.items.filter((item) => !isOpenClawRuntimeContext(item)))).at(0);
     return sha256(stableStringify({
         version: CONVERSATION_PREFIX_VERSION,
         firstStep: firstStep === undefined
@@ -67,6 +67,15 @@ export function interactionConversationPrefix(request) {
             : canonicalInteractionFingerprintStep(firstStep),
     }));
 }
+// OpenClaw appends a user message of runtime context (active exec sessions,
+// subagents) to each request and drops it from later history. On a first
+// turn it merges into the first transcript step, so leaving it in would give
+// the first turn a different conversation than the turns after it.
+const OPENCLAW_RUNTIME_CONTEXT = "<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>";
+function isOpenClawRuntimeContext(item) {
+    return item.type === "message" && item.role === "user" && item.content.length > 0 &&
+        item.content.every((part) => part.type === "text" && part.text.trimStart().startsWith(OPENCLAW_RUNTIME_CONTEXT));
+}
 export function interactionPrefixContext(routerId, request, targets) {
     const chainByModel = new Map();
     const itemIndexByHashByModel = new Map();

package/dist/http/auth.js

@@ -4,7 +4,7 @@ export function bearerToken(headers) {
     const value = headers.get("authorization") ?? "";
     const [scheme, token] = value.split(/\s+/, 2);
     if (scheme?.toLowerCase() !== "bearer" || !token) {
-        throw new HttpError(401, "Missing or invalid routing API key.", "authentication_error");
+        throw new HttpError(401, "Missing or invalid API key.", "authentication_error");
     }
     return publicRoutingToken(token);
 }
@@ -14,7 +14,7 @@ export function anthropicToken(headers) {
         return bearerToken(headers);
     const apiKey = headers.get("x-api-key");
     if (!apiKey) {
-        throw new HttpError(401, "Missing or invalid routing API key.", "authentication_error");
+        throw new HttpError(401, "Missing or invalid API key.", "authentication_error");
     }
     return publicRoutingToken(apiKey);
 }

package/dist/http/http2_server.d.ts

@@ -3,4 +3,4 @@ export type Http2RoutingServer = {
     readonly port: number;
     stop(force?: boolean): Promise<void>;
 };
-export declare function startHttp2Server(port: number, handler: Http2RequestHandler): Http2RoutingServer;
+export declare function startHttp2Server(port: number, handler: Http2RequestHandler, hostname?: string): Http2RoutingServer;

package/dist/http/http2_server.js

@@ -8,7 +8,7 @@ const HTTP2_FORBIDDEN_RESPONSE_HEADERS = new Set([
     "transfer-encoding",
     "upgrade",
 ]);
-export function startHttp2Server(port, handler) {
+export function startHttp2Server(port, handler, hostname = "0.0.0.0") {
     const sessions = new Set();
     let closePromise;
     const server = createServer((request, response) => {
@@ -18,10 +18,10 @@ export function startHttp2Server(port, handler) {
         sessions.add(session);
         session.once("close", () => sessions.delete(session));
     });
-    server.listen(port, "0.0.0.0");
+    server.listen(port, hostname);
     const address = server.address();
     if (address === null || typeof address === "string") {
-        throw new Error("HTTP/2 routing server did not bind to a TCP port.");
+        throw new Error("HTTP/2 gateway server did not bind to a TCP port.");
     }
     return {
         port: address.port,

package/dist/http/serve.d.ts

@@ -3,6 +3,7 @@ type StoppableServer = {
 };
 export declare function startServer(listenPort: number, handler: (request: Request) => Promise<Response>, options?: {
     http2?: boolean;
+    hostname?: string;
 }): import("./http2_server.js").Http2RoutingServer | Bun.Server<undefined>;
 /**
  * On SIGTERM/SIGINT: stop accepting work, let active requests finish, drain

package/dist/http/serve.js

@@ -9,13 +9,14 @@ const FORCE_STOP_SETTLE_TIMEOUT_MS = 250;
 const SHUTDOWN_WORK_TIMEOUT_MS = 7_500;
 export function startServer(listenPort, handler, options = {}) {
     if (options.http2) {
-        return startHttp2Server(listenPort, handler);
+        return startHttp2Server(listenPort, handler, options.hostname);
     }
     // The selector runs before the first response byte, and routed models can
     // remain silent while reasoning. Disable Bun's default 10s idle timeout;
     // clients and infrastructure still bound total request lifetime.
     return Bun.serve({
         port: listenPort,
+        hostname: options.hostname,
         fetch: handler,
         idleTimeout: 0,
     });
@@ -31,14 +32,14 @@ export function installShutdownHandlers(server, closeClients) {
             return;
         shuttingDown = true;
         const workDeadlineAtMs = performance.now() + SHUTDOWN_WORK_TIMEOUT_MS;
-        console.info("routing server shutting down", JSON.stringify({ signal }));
+        console.info("gateway server shutting down", JSON.stringify({ signal }));
         try {
             await stopServerForShutdown(server);
         }
         finally {
             const remaining = await drainBackgroundTelemetryFor(Math.max(0, workDeadlineAtMs - performance.now()));
             if (remaining > 0) {
-                console.warn("routing server background drain timed out", JSON.stringify({ remaining_task_count: remaining }));
+                console.warn("gateway server background drain timed out", JSON.stringify({ remaining_task_count: remaining }));
                 captureOperationalError(new Error(`Routing shutdown abandoned ${remaining} background task(s).`), { code: "background_drain_timeout" });
             }
             await closeClients();
@@ -73,6 +74,6 @@ function stopWithin(server, force, timeoutMs) {
     ]);
 }
 function reportServerStopFailure(error) {
-    console.warn("routing server shutdown failed", error instanceof Error ? error.name : "UnknownError");
+    console.warn("gateway server shutdown failed", error instanceof Error ? error.name : "UnknownError");
     captureOperationalError(error, { code: "server_force_stop_failed" });
 }

package/dist/ingress/chat_completions.js

@@ -4,7 +4,7 @@ import { captureRequestError } from "../observability/errors.js";
 import { chatCompletionResponse, chatCompletionsSseStream } from "../protocol/output/chat_completions.js";
 import { chatCompletionsToInteraction } from "../protocol/input/chat_completions.js";
 import { handleRoutedCompletion } from "../runtime/routed_completion.js";
-import { chatCompletionsConversationIdentity, openCodeRequestContext, } from "../runtime/harness_identity/index.js";
+import { chatCompletionsConversationIdentity, openCodeRequestContext, piRequestContext, } from "../runtime/harness_identity/index.js";
 import { parseJsonRequest } from "./json.js";
 import { museCodeClientId } from "./muse_code.js";
 export async function handleChatCompletions(request, routerId, selectorBackend) {
@@ -12,7 +12,7 @@ export async function handleChatCompletions(request, routerId, selectorBackend)
         const apiKey = bearerToken(request.headers);
         const payload = await parseJsonRequest(request);
         const interaction = chatCompletionsToInteraction({ ...payload, source_protocol: "openai_chat" });
-        const agentContext = openCodeRequestContext(request.headers);
+        const agentContext = piRequestContext(request.headers) ?? openCodeRequestContext(request.headers);
         const museClientId = museCodeClientId(request.headers);
         return await handleRoutedCompletion({
             request,

package/dist/ingress/codex.js

@@ -1,3 +1,4 @@
+import { explicitModelId } from "../protocol/input/router_model.js";
 import { bearerToken } from "../http/auth.js";
 import { errorResponse } from "../http/errors.js";
 import { captureRequestError } from "../observability/errors.js";
@@ -7,7 +8,7 @@ import { openAIResponsesToInteraction } from "../protocol/input/openai_responses
 import { parseJsonRequest } from "./json.js";
 import { museCodeClientId } from "./muse_code.js";
 import { handleRoutedCompletion } from "../runtime/routed_completion.js";
-import { codexConversationIdentity, codexRequestPurpose, codexRequestContext, } from "../runtime/harness_identity/index.js";
+import { codexConversationIdentity, codexRequestPurpose, codexRequestContext, museCodeConversationIdentity, } from "../runtime/harness_identity/index.js";
 export async function handleResponses(request, routerId, selectorBackend) {
     try {
         const apiKey = bearerToken(request.headers);
@@ -22,13 +23,16 @@ export async function handleResponses(request, routerId, selectorBackend) {
             ...(agentContext === undefined ? {} : { agentContext }),
             ...(museClientId === undefined ? {} : { museCodeClientId: museClientId }),
         };
-        const harnessConversationIdentity = codexConversationIdentity(request.headers, rawPayload);
+        const codexIdentity = codexConversationIdentity(request.headers, rawPayload);
         // Codex applies its global model_reasoning_effort setting to custom model
         // providers. That preference describes a direct model, not a heterogeneous
         // router, so let Dari select the reasoning effort for verified Codex turns.
         // Parsing above still validates malformed Responses reasoning controls.
-        if (harnessConversationIdentity !== undefined)
+        if (codexIdentity !== undefined && explicitModelId(payload.model) === null) {
             payload.reasoning = undefined;
+        }
+        const harnessConversationIdentity = codexIdentity
+            ?? (museClientId === undefined ? undefined : museCodeConversationIdentity(request.headers));
         return await handleRoutedCompletion({
             request,
             routerId,

package/dist/ingress/codex_models.d.ts

@@ -1,2 +1,2 @@
 import type { ResolvedRouter } from "../types.js";
-export declare function codexModelsResponse(router: Pick<ResolvedRouter, "enabled_models" | "model_configs" | "allow_long_context">, imageInputFor: (model: string) => boolean): Record<string, unknown>;
+export declare function codexModelsResponse(router: Pick<ResolvedRouter, "enabled_models" | "model_configs" | "allow_long_context" | "autorouting_enabled">, imageInputFor: (model: string) => boolean): Record<string, unknown>;

package/dist/ingress/codex_models.js

@@ -22,8 +22,11 @@ function codexCatalogEntry(args) {
         slug: args.slug,
         display_name: args.displayName,
         description: args.description,
-        default_reasoning_level: null,
-        supported_reasoning_levels: [],
+        default_reasoning_level: args.defaultReasoningLevel ?? null,
+        supported_reasoning_levels: (args.reasoningLevels ?? []).map((effort) => ({
+            effort,
+            description: `${effort} thinking`,
+        })),
         shell_type: "shell_command",
         visibility: "list",
         supported_in_api: true,
@@ -61,20 +64,22 @@ function codexCatalogEntry(args) {
         multi_agent_version: null,
     };
 }
-/* `dari/routing` stays first (the Codex launcher patches it); each enabled
-   model follows as `dari/model/<id>` so Codex's /model menu can switch to it. */
+/* `dari/routing` comes first while the router may autoroute (the Codex
+   launcher patches it); each enabled model follows as `dari/model/<id>` so
+   Codex's /model menu can switch to it. The `dari` launchers build every
+   agent's model menu from this list. */
 export function codexModelsResponse(router, imageInputFor) {
     return {
         models: [
-            codexCatalogEntry({
-                slug: CANONICAL_ROUTER_MODEL,
-                displayName: "Dari Routing",
-                description: "Routes Codex HTTP Responses requests through the configured Dari model router.",
-                priority: 0,
-                contextWindow: codexRouterContextWindow(router),
-                hostedWebSearch: codexRouterSupportsHostedWebSearch(router),
-                imageInput: router.enabled_models.some(imageInputFor),
-            }),
+            ...(router.autorouting_enabled === false ? [] : [codexCatalogEntry({
+                    slug: CANONICAL_ROUTER_MODEL,
+                    displayName: "Dari Routing",
+                    description: "Routes Codex HTTP Responses requests through the configured Dari model router.",
+                    priority: 0,
+                    contextWindow: codexRouterContextWindow(router),
+                    hostedWebSearch: codexRouterSupportsHostedWebSearch(router),
+                    imageInput: router.enabled_models.some(imageInputFor),
+                })]),
             ...router.enabled_models.map((model, index) => codexCatalogEntry({
                 slug: explicitModelSlug(model),
                 displayName: model,
@@ -83,6 +88,10 @@ export function codexModelsResponse(router, imageInputFor) {
                 contextWindow: codexRouterContextWindow({ ...router, enabled_models: [model] }),
                 hostedWebSearch: codexRouterSupportsHostedWebSearch({ ...router, enabled_models: [model] }),
                 imageInput: imageInputFor(model),
+                reasoningLevels: router.model_configs?.[model]?.supported_thinking_levels
+                    ?.map((effort) => effort === "off" ? "none" : effort),
+                defaultReasoningLevel: router.model_configs?.[model]?.default_thinking_level === "off"
+                    ? "none" : router.model_configs?.[model]?.default_thinking_level,
             })),
         ],
     };

package/dist/platform/platform.d.ts

@@ -33,6 +33,10 @@ export type GatewayPlatform = {
     writePrefixState(write: PrefixStateWrite): Promise<void>;
     /** Set or clear a conversation's prefetched routing lease. */
     writePendingLease(write: PendingLeaseWrite): Promise<void>;
+    /** The pair a session pinned on a session-pinning router, or null. */
+    readSessionPin(request: SessionPinKey): Promise<SessionPin | null>;
+    /** Pin a session to a pair, replacing any earlier pin. */
+    writeSessionPin(write: SessionPinKey & SessionPin): Promise<void>;
     /**
      * Hold an exhausted personal subscription until it resets. Resolves whether
      * another connected subscription for the same provider can serve a retry.
@@ -84,6 +88,14 @@ export type PendingLeaseWrite = {
         output_text: string | null;
     } | null;
 };
+export type SessionPinKey = {
+    routerId: string;
+    pinKey: string;
+};
+export type SessionPin = {
+    model: string;
+    reasoningEffort: ReasoningEffort;
+};
 export type SubscriptionHold = {
     userId: string;
     credentialId: string | undefined;
@@ -117,8 +129,6 @@ export type RequestSummary = {
     selected_reasoning_effort: ReasoningEffort | null;
     next_model: string | null;
     next_reasoning_effort: ReasoningEffort | null;
-    fallback_model: string | null;
-    fallback_reasoning_effort: ReasoningEffort | null;
     provider_key_source: ProviderKeySource | null;
     message_count: number;
     tool_count: number;
@@ -145,7 +155,7 @@ export type RequestErrorContext = {
     sourceProtocol: SourceProtocol | "openai_models" | "anthropic_models";
     status: number;
 };
-export type OperationalErrorCode = "background_drain_timeout" | "billing_usage_report_failed" | "routing_report_assembly_failed" | "routing_report_barrier_failed" | "server_force_stop_failed" | "stream_report_finalization_failed" | "subscription_unavailable_ingest_failed";
+export type OperationalErrorCode = "background_drain_timeout" | "billing_usage_report_failed" | "routing_report_assembly_failed" | "routing_report_barrier_failed" | "server_force_stop_failed" | "session_pin_write_failed" | "stream_report_finalization_failed" | "subscription_unavailable_ingest_failed";
 export type OperationalErrorContext = {
     code: OperationalErrorCode;
     requestId?: string;

package/dist/protocol/input/openai_responses.js

@@ -499,10 +499,8 @@ function reasoningControls(value) {
     if (!isRecord(value))
         throw new HttpError(400, "reasoning must be an object.", "invalid_request_error", "reasoning");
     const normalizedEffort = normalizedReasoningEffort(value.effort, "reasoning.effort");
-    const summary = value.summary;
-    if (summary !== undefined) {
-        throw new HttpError(400, "reasoning.summary is not supported by this router MVP.", "invalid_request_error", "reasoning.summary");
-    }
+    // Summaries are display-only: clients such as Muse Code ask for them by
+    // default, and the router serves the turn without them.
     return normalizedEffort === undefined ? undefined : { effort: normalizedEffort };
 }
 function normalizedReasoningEffort(value, param) {

package/dist/protocol/output/anthropic_messages_output.d.ts

@@ -1,5 +1,5 @@
 import type { InteractionOutput } from "../../interaction/types.js";
-import type { RoutingDecision } from "@mupt-ai/dari-router/policy-engine";
+import type { ServedDecision } from "../../types.js";
 export declare function anthropicMessageId(requestId: string): string;
 export declare function anthropicContent(output: InteractionOutput): Array<Record<string, unknown>>;
 export declare function anthropicReasoningBlock(item: Extract<InteractionOutput["items"][number], {
@@ -7,4 +7,4 @@ export declare function anthropicReasoningBlock(item: Extract<InteractionOutput[
 }>): Record<string, unknown>;
 export declare function anthropicStopReason(output: Pick<InteractionOutput, "stopReason">): string;
 export declare function anthropicUsage(output: Pick<InteractionOutput, "usage">): Record<string, unknown>;
-export declare function anthropicRouting(decision: RoutingDecision, requestId: string, conversationId?: string): Record<string, unknown>;
+export declare function anthropicRouting(decision: ServedDecision, requestId: string, conversationId?: string): Record<string, unknown>;

package/dist/protocol/output/anthropic_messages_output.js

@@ -103,6 +103,7 @@ export function anthropicRouting(decision, requestId, conversationId) {
         ...(decision.leaseTurnsRemaining === undefined
             ? {}
             : { lease_turns_remaining: decision.leaseTurnsRemaining }),
+        ...(decision.sessionPinned === true ? { session_pinned: true } : {}),
     };
 }
 function toolInput(kind, value) {

package/dist/protocol/output/openai_responses_stream.js

@@ -1,5 +1,5 @@
 import { openAIResponsesOutputItem, openAIResponsesOutputItems, openAIResponsesResponseId, openAIResponsesRouting, openAIResponsesTerminal, openAIResponsesUsage, } from "./openai_responses_output.js";
-import { piMessageToInteractionOutput } from "../../providers/pi_output.js";
+import { piMessageToInteractionOutput, textSignature } from "../../providers/pi_output.js";
 import { isProviderFailureMessage, providerFailureFromEvent, providerFailureMessage, } from "../../runtime/provider_stream_outcome.js";
 import { sseStream } from "./sse_stream.js";
 export function openAIResponsesSseStream(args) {
@@ -78,6 +78,7 @@ class ResponsesAccumulator {
     addedIndexes = new Set();
     completedIndexes = new Set();
     messageIds = new Map();
+    messagePhases = new Map();
     reasoningIds = new Map();
     messagePartStarted = new Set();
     reasoningPartStarted = new Set();
@@ -102,6 +103,8 @@ class ResponsesAccumulator {
             this.activate(index, send);
             if (type === "thinking_start")
                 this.ensureReasoning(index, send);
+            if (type === "text_start")
+                this.rememberMessageSignature(event, index);
             return;
         }
         if (type === "text_delta" && typeof event.delta === "string" && event.delta) {
@@ -273,18 +276,31 @@ class ResponsesAccumulator {
     currentUsage() {
         return openAIResponsesUsage(this.finalOutput ?? this.baseOutput());
     }
+    // Pi signs a Responses text block with its message id and phase at
+    // text_start, so the item is announced with the phase it ends with.
+    rememberMessageSignature(event, index) {
+        const content = isRecord(event.partial) ? event.partial.content : undefined;
+        const block = Array.isArray(content) ? content[event.contentIndex] : undefined;
+        const signature = isRecord(block) ? textSignature(block.textSignature) : null;
+        if (signature?.id && !this.messageIds.has(index))
+            this.messageIds.set(index, signature.id);
+        if (signature?.phase)
+            this.messagePhases.set(index, signature.phase);
+    }
     ensureMessage(index, send) {
         const existing = this.items.get(index);
         if (existing?.type === "message")
             return existing;
         const id = this.messageIds.get(index) ?? streamedItemId("msg", this.responseId, index);
         this.messageIds.set(index, id);
+        const phase = this.messagePhases.get(index);
         const message = {
             type: "message",
             id,
             role: "assistant",
             content: [{ type: "text", text: "" }],
             contentShape: "parts",
+            ...(phase ? { phase } : {}),
             source: this.args.source,
         };
         this.items.set(index, message);
@@ -297,6 +313,7 @@ class ResponsesAccumulator {
                 id,
                 status: "in_progress",
                 content: [],
+                ...(phase ? { phase } : {}),
             },
         });
         this.sendMessagePartAdded(index, id, send);
@@ -363,6 +380,7 @@ class ResponsesAccumulator {
                         id: serialized.id,
                         status: "in_progress",
                         content: [],
+                        ...(item.phase ? { phase: item.phase } : {}),
                     },
                 });
             }

package/dist/providers/execution.d.ts

@@ -7,9 +7,7 @@ import { type ProviderExecution, type StartedCompletion, type StartedStream } fr
 export type ProviderChoice = {
     decision: RoutingDecision;
     execution: ProviderExecution;
-    role: "primary" | "fallback";
 };
-export type ResolveFallbackChoice = () => Promise<ProviderChoice | null>;
 export type PreparedStreamExecution = {
     choice: ProviderChoice;
     started: StartedStream;
@@ -27,7 +25,6 @@ export declare function executeNonStreaming(args: {
     interaction: InteractionRequest;
     primary: ProviderChoice;
     primaryRetries: number;
-    resolveFallback: ResolveFallbackChoice;
     reporter: RoutedRuntimeReporter;
     protocol: RoutedProtocol;
     startedCompletion?: StartedCompletion;
@@ -39,7 +36,6 @@ export declare function completeNonStreaming(args: {
     interaction: InteractionRequest;
     primary: ProviderChoice;
     primaryRetries: number;
-    resolveFallback: ResolveFallbackChoice;
     reporter: RoutedRuntimeReporter;
     protocol: RoutedProtocol;
     startedCompletion?: StartedCompletion;
@@ -51,7 +47,6 @@ export declare function prepareStreamingExecution(args: {
     interaction: InteractionRequest;
     primary: ProviderChoice;
     primaryRetries: number;
-    resolveFallback: ResolveFallbackChoice;
     reporter: RoutedRuntimeReporter;
     startedStream?: StartedStream;
     initialError?: unknown;

package/dist/providers/execution.js

@@ -58,7 +58,7 @@ export async function completeNonStreaming(args) {
             output,
             modelCost: args.reporter.modelCost({
                 model: choice.decision.selectedModel, reasoning_effort: choice.decision.reasoningEffort,
-                role: choice.role, attempt: result.attempt, outcome: "completed", billingOutcome: "completed",
+                attempt: result.attempt, outcome: "completed", billingOutcome: "completed",
                 execution: reportedExecution(choice.execution), message: completion.message,
             }),
             request: args.interaction,
@@ -121,7 +121,6 @@ async function completeWithRetries(args) {
     return runProviderAttemptPlan({
         primary: args.primary,
         retries: args.primaryRetries,
-        resolveFallback: args.resolveFallback,
         primaryInitial: args.startedCompletion,
         isCustomerCanceled: () => customerAbortRequested(args.clientSignal),
         canceledFailure: customerCanceledProviderMessage,
@@ -255,7 +254,6 @@ export async function prepareStreamingExecution(args) {
     const result = await runProviderAttemptPlan({
         primary: args.primary,
         retries: args.primaryRetries,
-        resolveFallback: args.resolveFallback,
         primaryInitial,
         isCustomerCanceled: () => customerAbortRequested(args.clientSignal),
         canceledFailure: customerCanceledProviderMessage,
@@ -307,7 +305,7 @@ async function runStreamSetupAttempt(args) {
                 clientSignal: args.clientSignal,
             });
         // Prime before committing so connection failures and prompt rejections
-        // stay inside the one shared retry/fallback state machine.
+        // stay inside the one shared retry state machine.
         const primed = await primeProviderStream(started.providerStream.events, started.customerAbort);
         if (primed.outcome === "error") {
             started.customerAbort.dispose();
@@ -349,7 +347,6 @@ export async function executeStreaming(args) {
         reporter: args.reporter,
         protocol: args.protocol,
         providerLatencyMs: () => args.failedSetupLatencyMs + Date.now() - started.providerStartedMs,
-        role: args.choice.role,
         attempt: args.attempt,
         reportBarrier: args.reportBarrier,
         delivered: observed.delivered,
@@ -367,7 +364,7 @@ export async function executeStreaming(args) {
         clientSignal: args.clientSignal,
         modelCost: (message, failed) => args.reporter.modelCost({
             model: args.choice.decision.selectedModel, reasoning_effort: args.choice.decision.reasoningEffort,
-            role: args.choice.role, attempt: args.attempt,
+            attempt: args.attempt,
             outcome: failed ? "terminal_error" : "completed",
             billingOutcome: failed ? "provider_failed" : "completed",
             execution: reportedExecution(execution), message,
@@ -396,7 +393,6 @@ function recordProviderAttempt(reporter, choice, attempt, outcome, billingOutcom
     reporter.recordProviderAttempt({
         model: choice.decision.selectedModel,
         reasoning_effort: choice.decision.reasoningEffort,
-        role: choice.role,
         attempt,
         outcome,
         execution: reportedExecution(choice.execution),
@@ -424,7 +420,8 @@ async function providerFailedAttempt(message, latencyMs, execution, responseCapt
     }
     // Retrying an exhausted plan cannot succeed. The platform learns about it
     // before this request returns so the next resolve already serves the
-    // user's next subscription, or the router's subscription fallback model.
+    // user's next subscription, or the model's API credential when the router
+    // allows subscription API fallback for it.
     const switched = execution.subscriptionUserId !== undefined
         && await holdSubscription({
             userId: execution.subscriptionUserId,

package/dist/providers/pi_output.d.ts

@@ -1,2 +1,6 @@
 import type { InteractionOutput, InteractionRequest, ProviderIdentity } from "../interaction/types.js";
 export declare function piMessageToInteractionOutput(message: Record<string, unknown>, source: ProviderIdentity, request: Pick<InteractionRequest, "tools">): InteractionOutput;
+export declare function textSignature(value: unknown): {
+    id?: string;
+    phase?: "commentary" | "final_answer";
+} | null;

package/dist/providers/pi_output.js

@@ -364,7 +364,7 @@ function reasoningText(value, type) {
         return [];
     return value.flatMap((entry) => isRecord(entry) && entry.type === type && typeof entry.text === "string" ? [entry.text] : []);
 }
-function textSignature(value) {
+export function textSignature(value) {
     if (typeof value !== "string" || !value)
         return null;
     try {

package/dist/providers/provider_attempt_runner.d.ts

@@ -31,7 +31,6 @@ export type ProviderAttemptPlanResult<TChoice, TValue> = {
 type RunProviderAttemptPlanArgs<TChoice, TValue, TInitial> = {
     primary: TChoice;
     retries: number;
-    resolveFallback: () => Promise<TChoice | null>;
     primaryInitial?: TInitial;
     isCustomerCanceled: (choice: TChoice) => boolean;
     canceledFailure: () => Record<string, unknown>;
@@ -48,8 +47,8 @@ type RunProviderAttemptPlanArgs<TChoice, TValue, TInitial> = {
 };
 /**
  * Owns the order-sensitive provider plan shared by completion and stream setup:
- * retries within one choice, cancellation fences around asynchronous fallback
- * resolution, and one contiguous attempt record for every failed dispatch.
+ * retries within the choice, cancellation fences between attempts, and one
+ * contiguous attempt record for every failed dispatch.
  */
 export declare function runProviderAttemptPlan<TChoice, TValue, TInitial>(args: RunProviderAttemptPlanArgs<TChoice, TValue, TInitial>): Promise<ProviderAttemptPlanResult<TChoice, TValue>>;
 export {};