@independo/inderun-web 0.3.0-dev.1 → 0.3.0-dev.10

package/dist/core/engine.js

@@ -1,8 +1,9 @@
 import { getTaskRequestValidationIssues } from "@independo/inderun-contracts";
 import { ProviderRegistry } from "./registry.js";
 import { Router } from "./router.js";
-import { createInternal, toIndeRunException } from "./errors.js";
+import { createCapabilityMismatch, createInternal, createUnavailable, toIndeRunException } from "./errors.js";
 import { NoOpTelemetryService } from "./telemetry.js";
+import { EventGate } from "./event-gate.js";
 /**
  * Main orchestrator SDK entrypoint class.
  * Validates tasks, executes routing rules based on request constraints and connectivity,
@@ -26,6 +27,35 @@ export class IndeRun {
         this.telemetryService =
             telemetryService || this.hostServices.telemetry || new NoOpTelemetryService();
     }
+    /**
+     * Current time from the host clock, falling back to wall-clock time when the
+     * host does not supply one.
+     */
+    now() {
+        return this.hostServices.clock ? this.hostServices.clock.now() : Date.now();
+    }
+    /**
+     * Emits `route_decided` for a completed route selection. Shared by `run()` and
+     * `stream()`: the payload is identical for both modes, and the interaction
+     * mode is already reflected in the plan the router returned.
+     */
+    emitRouteDecided(runId, request, routeSelection, providerCount) {
+        this.safeEmit({
+            type: "route_decided",
+            runId,
+            timestamp: this.now(),
+            payload: {
+                selectedProviderId: routeSelection.routePlan.selectedProviderId,
+                fallbackProviderIds: routeSelection.routePlan.fallbackProviderIds,
+                rejectedProviders: routeSelection.routePlan.rejectedProviders,
+                fallbackAvailable: providerCount > 1,
+                taskKind: request.task.kind,
+                constraints: request.constraints ?? null,
+                preferences: request.preferences ?? null,
+                explanation: routeSelection.explanation
+            }
+        });
+    }
     /**
      * Safely emits a telemetry event by swallowing any internal logging/telemetry system errors.
      * @param event - The telemetry event to emit.
@@ -71,7 +101,7 @@ export class IndeRun {
      * @throws {IndeRunException} Standardized error indicating validation, connection, or provider failures.
      */
     async run(request) {
-        const startTime = this.hostServices.clock ? this.hostServices.clock.now() : Date.now();
+        const startTime = this.now();
         const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
         try {
             // 1. Validate request payload using schema contracts
@@ -86,26 +116,9 @@ export class IndeRun {
                 });
             }
             // 2. Select the route based on constraints and host capabilities
-            const routeSelection = await this.router.selectRoute(request, this.hostServices);
+            const routeSelection = await this.router.selectRoute(request, this.hostServices, "run");
             const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
-            // Emit route_decided event
-            this.safeEmit({
-                type: "route_decided",
-                runId,
-                timestamp: this.hostServices.clock ? this.hostServices.clock.now() : Date.now(),
-                payload: {
-                    selectedProviderId: routeSelection.routePlan.selectedProviderId,
-                    fallbackProviderIds: routeSelection.routePlan.fallbackProviderIds,
-                    rejectedProviders: routeSelection.routePlan.rejectedProviders,
-                    fallbackAvailable: providers.length > 1,
-                    taskKind: request.task.kind,
-                    explanation: routeSelection.explanation,
-                    constraints: request.constraints ?? null,
-                    preferences: request.preferences ?? null,
-                    plannerSource: routeSelection.plannerSource,
-                    plannerUnavailableReason: routeSelection.plannerUnavailableReason ?? null
-                }
-            });
+            this.emitRouteDecided(runId, request, routeSelection, providers.length);
             // 3. Execute the run task using the planned provider chain
             const attemptedProviderIds = [];
             let lastError;
@@ -117,7 +130,7 @@ export class IndeRun {
                         runId,
                         hostServices: this.hostServices
                     });
-                    const endTime = this.hostServices.clock ? this.hostServices.clock.now() : Date.now();
+                    const endTime = this.now();
                     const totalMs = endTime - startTime;
                     result.runId = runId;
                     result.telemetry = {
@@ -150,7 +163,7 @@ export class IndeRun {
                     });
                 }
             }
-            const endTime = this.hostServices.clock ? this.hostServices.clock.now() : Date.now();
+            const endTime = this.now();
             const totalMs = endTime - startTime;
             const exception = toIndeRunException(lastError ?? new Error("No providers were attempted."), {
                 runId,
@@ -169,10 +182,10 @@ export class IndeRun {
                 details: {
                     totalMs: typeof error.details?.totalMs === "number"
                         ? error.details?.totalMs
-                        : (this.hostServices.clock ? this.hostServices.clock.now() : Date.now()) - startTime
+                        : this.now() - startTime
                 }
             });
-            const endTime = this.hostServices.clock ? this.hostServices.clock.now() : Date.now();
+            const endTime = this.now();
             const totalMs = typeof exception.details?.totalMs === "number"
                 ? exception.details?.totalMs
                 : endTime - startTime;
@@ -190,6 +203,262 @@ export class IndeRun {
             throw exception;
         }
     }
+    /**
+     * Orchestrates a Mode 2 streaming execution of a TaskRequest.
+     *
+     * Routes through the same planner as run(), asking it for a `stream` route: the
+     * planner rejects providers that do not declare `supports.streaming` or whose
+     * dynamic capability snapshot says they cannot stream here, and reports why. The
+     * whole returned chain is therefore mode-compatible and subject to the same
+     * privacy, locality, availability, and policy constraints as a Mode 1 route.
+     *
+     * Fallback to the next provider is allowed only before the first content event
+     * has been admitted for the run; once one has been delivered, the run is
+     * committed to that provider and any later provider failure becomes a terminal
+     * error outcome rather than a silent provider swap — partial output spliced from
+     * two providers is undetectable to the caller. Cancellation always forecloses
+     * fallback, regardless of commit state, and is idempotent.
+     * @param request - The canonical task request containing prompts, tasks, and constraints.
+     * @throws {IndeRunException} If validation fails or no eligible streaming provider exists.
+     */
+    async stream(request) {
+        const startTime = this.now();
+        const now = () => this.now();
+        const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
+        const validationIssues = getTaskRequestValidationIssues(request);
+        if (validationIssues.length > 0) {
+            const message = `Validation failed for TaskRequest: ${validationIssues
+                .map((i) => `${i.path} - ${i.message}`)
+                .join("; ")}`;
+            throw createInternal(message, { runId, details: { validationIssues } });
+        }
+        // Route selection failures are the one class of stream error that surfaces as a
+        // rejected promise instead of a terminal event, so they must still carry the
+        // runId — there is no handle for the caller to correlate them with otherwise.
+        let routeSelection;
+        try {
+            routeSelection = await this.router.selectRoute(request, this.hostServices, "stream");
+        }
+        catch (error) {
+            throw toIndeRunException(error, { runId });
+        }
+        const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
+        this.emitRouteDecided(runId, request, routeSelection, providers.length);
+        // Defensive only: streaming eligibility is decided by the route planner, which
+        // throws with its own rejection reasons when nothing can stream. Reaching here
+        // means a planned provider was unregistered between planning and selection.
+        if (providers.length === 0) {
+            throw createCapabilityMismatch("No eligible provider supports streaming for this request.", {
+                runId,
+                details: { taskKind: request.task.kind }
+            });
+        }
+        const controller = new AbortController();
+        const gate = new EventGate(runId);
+        const hostServices = this.hostServices;
+        const safeEmit = this.safeEmit.bind(this);
+        const getStableMessage = this.getStableMessage.bind(this);
+        const handle = {
+            runId,
+            schemaVersion: "1.0",
+            startedAt: startTime,
+            providerId: providers[0].describe().id
+        };
+        async function* run() {
+            const attemptedProviderIds = [];
+            let committed = false;
+            const cancelledOutcome = (partialText) => {
+                const reason = typeof controller.signal.reason === "string" ? controller.signal.reason : undefined;
+                return {
+                    outcome: "cancelled",
+                    runId,
+                    schemaVersion: "1.0",
+                    partialText,
+                    ...(reason !== undefined ? { reason } : {})
+                };
+            };
+            for (const [index, provider] of providers.entries()) {
+                if (controller.signal.aborted) {
+                    break;
+                }
+                const providerId = provider.describe().id;
+                attemptedProviderIds.push(providerId);
+                safeEmit({
+                    type: "stream_attempt_started",
+                    runId,
+                    timestamp: now(),
+                    payload: { providerId, fallbackOccurred: index > 0 }
+                });
+                let partialText = "";
+                try {
+                    const iterable = provider.stream(request, {
+                        runId,
+                        hostServices: hostServices,
+                        signal: controller.signal
+                    });
+                    let terminatedInLoop = false;
+                    for await (const ev of iterable) {
+                        if (controller.signal.aborted) {
+                            break;
+                        }
+                        if (ev.kind === "error") {
+                            throw ev.error;
+                        }
+                        if (ev.kind === "delta" || ev.kind === "snapshot") {
+                            partialText = ev.kind === "delta" ? partialText + ev.text : ev.text;
+                            if (!committed) {
+                                committed = true;
+                                safeEmit({
+                                    type: "stream_attempt_succeeded",
+                                    runId,
+                                    timestamp: now(),
+                                    payload: { providerId, attemptedProviderIds }
+                                });
+                            }
+                            const streamEvent = gate.admit({
+                                timestamp: now(),
+                                type: ev.kind === "delta" ? "content_delta" : "content_snapshot",
+                                payload: { text: ev.text }
+                            });
+                            if (streamEvent)
+                                yield streamEvent;
+                            continue;
+                        }
+                        // ev.kind === "done"
+                        const outcome = {
+                            outcome: "completed",
+                            runId,
+                            schemaVersion: "1.0",
+                            finalText: ev.finalText,
+                            telemetry: { providerUsed: providerId, totalMs: now() - startTime },
+                            ...(ev.finishReason !== undefined ? { finishReason: ev.finishReason } : {}),
+                            ...(ev.usage !== undefined ? { usage: ev.usage } : {})
+                        };
+                        const terminal = gate.terminate(outcome, now());
+                        safeEmit({
+                            type: "stream_completed",
+                            runId,
+                            timestamp: now(),
+                            payload: { providerId, durationMs: now() - startTime, attemptedProviderIds }
+                        });
+                        terminatedInLoop = true;
+                        if (terminal)
+                            yield terminal;
+                        return;
+                    }
+                    if (terminatedInLoop) {
+                        return;
+                    }
+                    if (controller.signal.aborted) {
+                        const terminal = gate.terminate(cancelledOutcome(partialText), now());
+                        safeEmit({
+                            type: "stream_cancelled",
+                            runId,
+                            timestamp: now(),
+                            payload: { providerId, attemptedProviderIds }
+                        });
+                        if (terminal)
+                            yield terminal;
+                        return;
+                    }
+                    // Provider's iterable ended without a terminal "done"/"error" event.
+                    throw new Error(`Provider '${providerId}' stream ended without a terminal event.`);
+                }
+                catch (err) {
+                    if (controller.signal.aborted) {
+                        const terminal = gate.terminate(cancelledOutcome(partialText), now());
+                        safeEmit({
+                            type: "stream_cancelled",
+                            runId,
+                            timestamp: now(),
+                            payload: { providerId, attemptedProviderIds }
+                        });
+                        if (terminal)
+                            yield terminal;
+                        return;
+                    }
+                    const exception = toIndeRunException(err, {
+                        providerId,
+                        runId,
+                        details: { attemptedProviderIds }
+                    });
+                    if (!committed) {
+                        safeEmit({
+                            type: "stream_attempt_failed",
+                            runId,
+                            timestamp: now(),
+                            payload: {
+                                providerId,
+                                errorClass: exception.errorClass,
+                                message: getStableMessage(exception.errorClass)
+                            }
+                        });
+                        continue;
+                    }
+                    const outcome = {
+                        outcome: "error",
+                        runId,
+                        schemaVersion: "1.0",
+                        error: exception.toContractError(),
+                        partialText
+                    };
+                    const terminal = gate.terminate(outcome, now());
+                    safeEmit({
+                        type: "stream_failed",
+                        runId,
+                        timestamp: now(),
+                        payload: {
+                            providerId,
+                            errorClass: exception.errorClass,
+                            message: getStableMessage(exception.errorClass),
+                            attemptedProviderIds
+                        }
+                    });
+                    if (terminal)
+                        yield terminal;
+                    return;
+                }
+            }
+            // Every provider failed pre-commit, or cancellation landed before any attempt started.
+            if (controller.signal.aborted) {
+                const terminal = gate.terminate(cancelledOutcome(""), now());
+                safeEmit({
+                    type: "stream_cancelled",
+                    runId,
+                    timestamp: now(),
+                    payload: { attemptedProviderIds }
+                });
+                if (terminal)
+                    yield terminal;
+                return;
+            }
+            const exception = createUnavailable("All eligible streaming providers failed.", {
+                runId,
+                details: { attemptedProviderIds }
+            });
+            const outcome = {
+                outcome: "error",
+                runId,
+                schemaVersion: "1.0",
+                error: exception.toContractError(),
+                partialText: ""
+            };
+            const terminal = gate.terminate(outcome, now());
+            safeEmit({
+                type: "stream_failed",
+                runId,
+                timestamp: now(),
+                payload: {
+                    errorClass: exception.errorClass,
+                    message: getStableMessage(exception.errorClass),
+                    attemptedProviderIds
+                }
+            });
+            if (terminal)
+                yield terminal;
+        }
+        return { handle, events: run(), cancel: (reason) => controller.abort(reason) };
+    }
     /**
      * Reports each registered provider's static descriptor and current dynamic capability check,
      * without executing a task. Useful for UI that shows live provider availability before a run.

package/dist/core/event-gate.d.ts

@@ -0,0 +1,37 @@
+import type { StreamEvent, StreamTerminalOutcome } from "@independo/inderun-contracts";
+/**
+ * Per-run gatekeeper for Mode 2 streaming. Enforces the two structural guarantees
+ * required by the streaming orchestrator: exactly one terminal outcome is ever
+ * produced for a run, and no event is admitted after that terminal outcome fires.
+ *
+ * Correctness relies on `admit`/`terminate` performing their check-and-set
+ * synchronously with no `await` in between — safe under JS's single-threaded,
+ * run-to-completion semantics even with interleaved `await` resumption elsewhere
+ * (e.g. a provider's async iterator and a caller's `cancel()` racing).
+ */
+export declare class EventGate {
+    private readonly runId;
+    private sequence;
+    private terminated;
+    private terminalOutcome;
+    constructor(runId: string);
+    /**
+     * Admits a non-terminal StreamEvent, assigning it the next monotonic sequence
+     * number. Returns null (suppressing the event) if the run has already terminated.
+     */
+    admit(event: {
+        timestamp: number;
+        type: string;
+        payload?: StreamEvent["payload"];
+    }): StreamEvent | null;
+    /**
+     * Terminates the run with the given outcome. First writer wins: only the first
+     * call produces a terminal StreamEvent and stores the outcome; every subsequent
+     * call (duplicate provider "done", late error after cancel, concurrent cancel()
+     * calls) is a silent no-op that returns null, making repeated cancellation safe.
+     */
+    terminate(outcome: StreamTerminalOutcome, timestamp: number): StreamEvent | null;
+    isTerminated(): boolean;
+    getOutcome(): StreamTerminalOutcome | undefined;
+}
+//# sourceMappingURL=event-gate.d.ts.map

package/dist/core/event-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-gate.d.ts","sourceRoot":"","sources":["../../src/core/event-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAEvF;;;;;;;;;GASG;AACH,qBAAa,SAAS;IAKR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAoC;gBAE9B,KAAK,EAAE,MAAM;IAE1C;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;KAClC,GAAG,WAAW,GAAG,IAAI;IActB;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAgBhF,YAAY,IAAI,OAAO;IAIvB,UAAU,IAAI,qBAAqB,GAAG,SAAS;CAGhD"}

package/dist/core/event-gate.js

@@ -0,0 +1,63 @@
+/**
+ * Per-run gatekeeper for Mode 2 streaming. Enforces the two structural guarantees
+ * required by the streaming orchestrator: exactly one terminal outcome is ever
+ * produced for a run, and no event is admitted after that terminal outcome fires.
+ *
+ * Correctness relies on `admit`/`terminate` performing their check-and-set
+ * synchronously with no `await` in between — safe under JS's single-threaded,
+ * run-to-completion semantics even with interleaved `await` resumption elsewhere
+ * (e.g. a provider's async iterator and a caller's `cancel()` racing).
+ */
+export class EventGate {
+    runId;
+    sequence = 0;
+    terminated = false;
+    terminalOutcome;
+    constructor(runId) {
+        this.runId = runId;
+    }
+    /**
+     * Admits a non-terminal StreamEvent, assigning it the next monotonic sequence
+     * number. Returns null (suppressing the event) if the run has already terminated.
+     */
+    admit(event) {
+        if (this.terminated) {
+            return null;
+        }
+        return {
+            runId: this.runId,
+            schemaVersion: "1.0",
+            sequence: this.sequence++,
+            timestamp: event.timestamp,
+            type: event.type,
+            ...(event.payload !== undefined ? { payload: event.payload } : {})
+        };
+    }
+    /**
+     * Terminates the run with the given outcome. First writer wins: only the first
+     * call produces a terminal StreamEvent and stores the outcome; every subsequent
+     * call (duplicate provider "done", late error after cancel, concurrent cancel()
+     * calls) is a silent no-op that returns null, making repeated cancellation safe.
+     */
+    terminate(outcome, timestamp) {
+        if (this.terminated) {
+            return null;
+        }
+        this.terminated = true;
+        this.terminalOutcome = outcome;
+        return {
+            runId: this.runId,
+            schemaVersion: "1.0",
+            sequence: this.sequence++,
+            timestamp,
+            type: "terminal",
+            payload: outcome
+        };
+    }
+    isTerminated() {
+        return this.terminated;
+    }
+    getOutcome() {
+        return this.terminalOutcome;
+    }
+}

package/dist/core/generated/inderun-api.d.ts

@@ -1,10 +1,14 @@
 import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
-import type { ProviderCapabilitySnapshot } from "../provider.js";
+import type { StreamRun, ProviderCapabilitySnapshot } from "../provider.js";
 export interface IndeRunApi {
     /**
      * Executes a Mode 1 (request/response) text-to-text task against a routed provider and returns the completed TaskResult. Routing (local vs. cloud, which provider) is decided internally from TaskRequest.constraints/preferences — the caller does not select a provider directly. Rejects the request up front on validation failure; otherwise throws an IndeRunException (carrying an IndeRunError) if no eligible provider is found or every attempted provider fails. There is no partial or streaming result in this mode: run() either resolves with a complete TaskResult or throws.
      */
     run(request: TaskRequest): Promise<TaskResult>;
+    /**
+     * Executes a Mode 2 (streaming) text-to-text task and returns a handle to the run, its canonical StreamEvent sequence, and a cancel hook. The requested interaction mode is a routing input rather than a filter applied after routing: providers that cannot stream are rejected during planning with a normalized reason, so a stream and a run over the same registry may legitimately resolve to different provider chains. Two failure surfaces exist deliberately — validation and route-selection failures reject this call, since there is no handle to correlate them with yet, while provider failure, cancellation, and completion all arrive as the single terminal StreamEvent in the returned sequence. Fallback is narrower than run()'s: a provider failure is only fallback-eligible before the first content event has been delivered; once one has, the run is committed to that provider and a later failure becomes a terminal error rather than a silent provider swap. Cancellation forecloses both at any commit state and always produces exactly one cancelled outcome.
+     */
+    stream(request: TaskRequest): Promise<StreamRun>;
     /**
      * Returns a live snapshot of every registered provider's static descriptor and current dynamic availability, without executing a task or producing any side effects. Call this before run() when you need to show which providers/models are currently available — for example a settings screen or provider picker. Availability can change between calls (a local model can unload, cloud credentials can expire), so don't cache the result across a run() call.
      */

package/dist/core/generated/inderun-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inderun-api.d.ts","sourceRoot":"","sources":["../../../src/core/generated/inderun-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C;;OAEG;IACH,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"inderun-api.d.ts","sourceRoot":"","sources":["../../../src/core/generated/inderun-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAE5E,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD;;OAEG;IACH,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC;CAC5D"}

package/dist/core/host.d.ts

@@ -1,2 +1,2 @@
-export type { ClockService, ConnectivityService, DeviceConstraintsService, HostServices, HttpClientService, HttpRequest, HttpResponse, SecureStorageService, TelemetryService, ThermalState } from "@independo/inderun-contracts";
+export type { AbortSignalLike, ClockService, ConnectivityService, DeviceConstraintsService, HostServices, HttpClientService, HttpRequest, HttpResponse, HttpStreamResponse, HttpStreamingClientService, SecureStorageService, TelemetryService, ThermalState } from "@independo/inderun-contracts";
 //# sourceMappingURL=host.d.ts.map

package/dist/core/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAC"}

package/dist/core/provider.d.ts

@@ -1,4 +1,4 @@
-import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import type { StreamEvent, StreamRunHandle, TaskRequest, TaskResult } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
 /**
  * Static metadata descriptor defining the capabilities, requirements, and constraints
@@ -82,6 +82,25 @@ export interface ProviderDynamicCapabilities {
      * Detail message if availability check fails.
      */
     reason?: string;
+    /**
+     * Whether the provider can stream (Mode 2) right now on this host. Leave
+     * undefined to inherit the static `descriptor.supports.streaming` value —
+     * only set it when the runtime environment can take streaming away from a
+     * provider that otherwise declares it (e.g. the host has no chunked HTTP
+     * capability).
+     */
+    streamingAvailable?: boolean;
+    /**
+     * Detail message used when `streamingAvailable` is false. Omit to let the
+     * route planner synthesize a generic message.
+     */
+    streamingUnavailableReason?: string;
+    /**
+     * Whether cancellation is honored right now on this host. Leave undefined to
+     * inherit the static `descriptor.cancel` value (anything other than `"none"`
+     * means available).
+     */
+    cancellationAvailable?: boolean;
 }
 /**
  * One registered provider's identity, fixed capabilities, and live availability,
@@ -118,6 +137,48 @@ export interface RunContext {
      */
     hostServices: HostServices;
 }
+/**
+ * Execution context passed to provider stream commands. Extends RunContext with the
+ * caller-driven cancellation signal; the Engine core owns the AbortController and
+ * threads its signal here, so providers never need to construct their own.
+ */
+export interface ProviderStreamContext extends RunContext {
+    /**
+     * Signals caller-driven cancellation of this stream. Providers with `cancel: "hard"`
+     * should tear down their connection immediately on abort; `cancel: "soft"` providers
+     * may stop relaying events without interrupting underlying local work; `cancel:
+     * "none"` providers may ignore it entirely; the engine enforces the caller-visible
+     * cancellation guarantee at the consumer loop regardless of what the provider does.
+     */
+    signal: AbortSignal;
+}
+/**
+ * A raw, provider-shaped streaming event yielded by ProviderAdapter.stream(). This is
+ * intentionally distinct from the canonical StreamEvent contract: providers emit
+ * provider-shaped deltas here, and the Engine core's Event Gate normalizes these into
+ * StreamEvent/StreamTerminalOutcome, keeping provider-specific mechanics from leaking
+ * through the public API.
+ */
+export type ProviderStreamEvent = {
+    kind: "delta";
+    text: string;
+} | {
+    kind: "snapshot";
+    text: string;
+} | {
+    kind: "done";
+    finalText: string;
+    /**
+     * How generation ended, when the provider reports it. Mirrors
+     * `TaskResult.finishReason` for Mode 1 and surfaces on the `completed`
+     * terminal outcome; omit when the provider gives no signal.
+     */
+    finishReason?: TaskResult["finishReason"];
+    usage?: TaskResult["usage"];
+} | {
+    kind: "error";
+    error: unknown;
+};
 /**
  * Pluggable execution adapter contract that wraps a specific model runtime
  * (system frameworks, local runtimes, or cloud APIs) and exposes normalized APIs.
@@ -135,5 +196,24 @@ export interface ProviderAdapter {
      * Executes a task request in Mode 1 (request/response).
      */
     run(req: TaskRequest, ctx: RunContext): Promise<TaskResult>;
+    /**
+     * Executes a task request in Mode 2 (streaming). Optional: only providers declaring
+     * `describe().supports.streaming === true` are expected to implement this.
+     */
+    stream?(req: TaskRequest, ctx: ProviderStreamContext): AsyncIterable<ProviderStreamEvent>;
+}
+/**
+ * What `IndeRun.stream()` returns: the run's identity, its canonical event
+ * sequence, and a cancel hook.
+ *
+ * `events` terminates in exactly one terminal `StreamEvent`, per the Event
+ * Gate's guarantee, and is single-use — the run is driven once, not restarted
+ * per consumer. `cancel()` is idempotent: repeated or concurrent calls produce
+ * exactly one `cancelled` terminal outcome.
+ */
+export interface StreamRun {
+    handle: StreamRunHandle;
+    events: AsyncIterable<StreamEvent>;
+    cancel(reason?: string): void;
 }
 //# sourceMappingURL=provider.d.ts.map

package/dist/core/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC;;OAEG;IACH,SAAS,EAAE,YAAY,GAAG,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IACzE;;OAEG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IAEnD;;OAEG;IACH,QAAQ,EAAE;QACR,mEAAmE;QACnE,GAAG,EAAE,OAAO,CAAC;QACb,mDAAmD;QACnD,SAAS,EAAE,OAAO,CAAC;QACnB,6DAA6D;QAC7D,QAAQ,EAAE,OAAO,CAAC;QAClB,6DAA6D;QAC7D,KAAK,EAAE,OAAO,CAAC;QACf,wEAAwE;QACxE,eAAe,EAAE,OAAO,CAAC;QACzB,kFAAkF;QAClF,gBAAgB,EAAE,OAAO,CAAC;QAC1B,6EAA6E;QAC7E,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IAEF;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAEjC;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,6DAA6D;QAC7D,gBAAgB,EAAE,OAAO,CAAC;QAC1B,2DAA2D;QAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,kBAAkB,CAAC;IAC/B;;;OAGG;IACH,YAAY,EAAE,2BAA2B,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;IAC/B;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACvE;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7D"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.ts"],"names":[],"mappings":"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"}