@independo/inderun-web 0.3.3 → 0.4.0-rc.2

package/dist/core/provenance.d.ts

@@ -0,0 +1,32 @@
+import type { ExecutionProvenance, IndeRunErrorClass } from "@independo/inderun-contracts";
+import type { ProviderDescriptor } from "./provider.js";
+import type { SharedPlannerRoutePlan } from "./route-planner.js";
+type ExecutionProvenanceAttempt = ExecutionProvenance["attempts"][number];
+/**
+ * Accumulates what one execution did -- each attempt and how it ended -- and renders it as the
+ * normalized {@link ExecutionProvenance} carried on results, terminal outcomes, and errors.
+ *
+ * Everything recorded is either observed by the engine (attempts, their outcomes) or declared or
+ * reported by a provider (descriptor type and model, the model a response names). Nothing is
+ * inferred: an unknown is left absent or reported as `unknown`.
+ */
+export declare class ProvenanceRecorder {
+    private readonly modelProfile;
+    private readonly attempts;
+    private routeRejections;
+    constructor(modelProfile?: string);
+    /** Records the planner's rejections; codes only, never the provider-supplied messages. */
+    routed(routePlan: SharedPlannerRoutePlan): void;
+    /** Records the rejections a routing failure carried out on its exception's details. */
+    routingFailed(details: Record<string, unknown> | undefined): void;
+    /** Records how one provider attempt ended. */
+    attempted(providerId: string, outcome: ExecutionProvenanceAttempt["outcome"], errorClass?: IndeRunErrorClass): void;
+    /**
+     * Renders the record. `attributedTo` is the provider the outcome belongs to -- the one that
+     * produced the result, the one a stream was committed to, or the one running at cancellation --
+     * and is absent when no provider was reached or every attempt failed before a commit.
+     */
+    build(attributedTo?: ProviderDescriptor, reportedModel?: string): ExecutionProvenance;
+}
+export {};
+//# sourceMappingURL=provenance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/core/provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,KAAK,0BAA0B,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAG1E;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAHzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,eAAe,CAAwB;gBAElB,YAAY,GAAE,MAA2B;IAEtE,0FAA0F;IAC1F,MAAM,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI;IAI/C,uFAAuF;IACvF,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI;IASjE,8CAA8C;IAC9C,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,SAAS,CAAC,EAC9C,UAAU,CAAC,EAAE,iBAAiB,GAC7B,IAAI;IAQP;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,EAAE,kBAAkB,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,mBAAmB;CActF"}

package/dist/core/provenance.js

@@ -0,0 +1,71 @@
+import { AUTO_MODEL_PROFILE } from "./model-profiles.js";
+/**
+ * Accumulates what one execution did -- each attempt and how it ended -- and renders it as the
+ * normalized {@link ExecutionProvenance} carried on results, terminal outcomes, and errors.
+ *
+ * Everything recorded is either observed by the engine (attempts, their outcomes) or declared or
+ * reported by a provider (descriptor type and model, the model a response names). Nothing is
+ * inferred: an unknown is left absent or reported as `unknown`.
+ */
+export class ProvenanceRecorder {
+    modelProfile;
+    attempts = [];
+    routeRejections = [];
+    constructor(modelProfile = AUTO_MODEL_PROFILE) {
+        this.modelProfile = modelProfile;
+    }
+    /** Records the planner's rejections; codes only, never the provider-supplied messages. */
+    routed(routePlan) {
+        this.routeRejections = routeRejectionsFrom(routePlan.rejectedProviders);
+    }
+    /** Records the rejections a routing failure carried out on its exception's details. */
+    routingFailed(details) {
+        const rejected = details?.rejectedProviders;
+        if (Array.isArray(rejected)) {
+            this.routeRejections = routeRejectionsFrom(rejected);
+        }
+    }
+    /** Records how one provider attempt ended. */
+    attempted(providerId, outcome, errorClass) {
+        this.attempts.push({
+            providerId,
+            outcome,
+            ...(errorClass !== undefined ? { errorClass } : {})
+        });
+    }
+    /**
+     * Renders the record. `attributedTo` is the provider the outcome belongs to -- the one that
+     * produced the result, the one a stream was committed to, or the one running at cancellation --
+     * and is absent when no provider was reached or every attempt failed before a commit.
+     */
+    build(attributedTo, reportedModel) {
+        return {
+            schemaVersion: "1.0",
+            modelProfile: this.modelProfile,
+            ...(attributedTo !== undefined ? { providerId: attributedTo.id } : {}),
+            locality: attributedTo !== undefined ? localityOf(attributedTo) : "unknown",
+            ...(attributedTo?.model !== undefined ? { configuredModel: attributedTo.model } : {}),
+            ...(attributedTo !== undefined && reportedModel !== undefined ? { reportedModel } : {}),
+            attemptCount: this.attempts.length,
+            fallbackOccurred: this.attempts.length > 1,
+            attempts: [...this.attempts],
+            routeRejections: [...this.routeRejections]
+        };
+    }
+}
+function localityOf(descriptor) {
+    switch (descriptor.type) {
+        case "local":
+            return "on_device";
+        case "edge":
+            return "edge";
+        case "cloud":
+            return "cloud";
+    }
+}
+function routeRejectionsFrom(rejected) {
+    return rejected.map((provider) => ({
+        providerId: provider.providerId,
+        codes: provider.reasons.map((reason) => reason.code)
+    }));
+}

package/dist/core/provider.d.ts

@@ -13,6 +13,14 @@ export interface ProviderDescriptor {
      * Execution target type: 'local' (on-device), 'edge', or 'cloud'.
      */
     type: "local" | "edge" | "cloud";
+    /**
+     * The model this provider instance is bound to, when it can name one. A provider
+     * instance bound to one model is a *target* that model profiles list by `id`.
+     * Cloud providers report the model id they send; platform-managed models report
+     * an opaque platform alias rather than a guessed weight name. Absent means the
+     * provider cannot name its model.
+     */
+    model?: string;
     /**
      * Connection transport layer protocol.
      */
@@ -175,6 +183,11 @@ export type ProviderStreamEvent = {
      */
     finishReason?: TaskResult["finishReason"];
     usage?: TaskResult["usage"];
+    /**
+     * The model identifier the provider's backend reported for this run, when it reports
+     * one. Carried into the terminal outcome's provenance; never inferred from configuration.
+     */
+    reportedModel?: string;
 } | {
     kind: "error";
     error: unknown;

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

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.ts"],"names":[],"mappings":"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"}

package/dist/core/route-planner.d.ts

@@ -81,5 +81,5 @@ export declare function collectProviderRuntimeSnapshots(registryProviders: Provi
  * consumes, applying default constraints/preferences and the current network
  * state.
  */
-export declare function buildSharedPlannerInput(request: TaskRequest, snapshots: ProviderRuntimeSnapshot[], networkOnline: boolean, interactionMode?: InteractionMode): SharedPlannerInput;
+export declare function buildSharedPlannerInput(request: TaskRequest, snapshots: ProviderRuntimeSnapshot[], networkOnline: boolean, interactionMode?: InteractionMode, modelProfile?: SharedPlannerInput["modelProfile"]): SharedPlannerInput;
 //# sourceMappingURL=route-planner.d.ts.map

package/dist/core/route-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../../src/core/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC/B,eAAe,GAAG,sBAAsB,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,aAAa,CAAC,CAAsC;IAC5D,OAAO,CAAC,WAAW,CAAC,CAAqD;IACzE,OAAO,CAAC,SAAS,CAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAoBrD,UAAU;YAOV,YAAY;IA0B1B,OAAO,CAAC,QAAQ;CAOjB;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAapC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,EACtB,eAAe,GAAE,eAAuB,GACvC,kBAAkB,CAuBpB"}
+{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../../src/core/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC/B,eAAe,GAAG,sBAAsB,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,aAAa,CAAC,CAAsC;IAC5D,OAAO,CAAC,WAAW,CAAC,CAAqD;IACzE,OAAO,CAAC,SAAS,CAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAoBrD,UAAU;YAOV,YAAY;IA0B1B,OAAO,CAAC,QAAQ;CAOjB;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAapC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,EACtB,eAAe,GAAE,eAAuB,EACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,GAChD,kBAAkB,CAwBpB"}

package/dist/core/route-planner.js

@@ -94,7 +94,7 @@ export async function collectProviderRuntimeSnapshots(registryProviders, hostSer
  * consumes, applying default constraints/preferences and the current network
  * state.
  */
-export function buildSharedPlannerInput(request, snapshots, networkOnline, interactionMode = "run") {
+export function buildSharedPlannerInput(request, snapshots, networkOnline, interactionMode = "run", modelProfile) {
     const constraints = request.constraints ?? {};
     const preferences = request.preferences ?? {};
     return {
@@ -111,6 +111,7 @@ export function buildSharedPlannerInput(request, snapshots, networkOnline, inter
         preferences: {
             optimizeFor: preferences.optimizeFor ?? "balanced"
         },
+        ...(modelProfile ? { modelProfile } : {}),
         providers: snapshots.map((snapshot) => ({
             descriptor: snapshot.descriptor,
             capabilities: snapshot.capabilities

package/dist/core/router.d.ts

@@ -2,7 +2,7 @@ import type { TaskRequest } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
 import type { ProviderAdapter } from "./provider.js";
 import type { ProviderRegistry } from "./registry.js";
-import { type InteractionMode, type RoutePlanner, type SharedPlannerRoutePlan } from "./route-planner.js";
+import { type InteractionMode, type RoutePlanner, type SharedPlannerInput, type SharedPlannerRoutePlan } from "./route-planner.js";
 /**
  * Output structure from the Router containing the chosen provider and a route selection description.
  */
@@ -45,9 +45,10 @@ export declare class Router {
      *
      * The requested `interactionMode` is a planning input, not a post-filter: the
      * shared planner rejects providers that cannot satisfy it and says why, so the
-     * whole returned chain is mode-compatible.
+     * whole returned chain is mode-compatible. The resolved model profile is a
+     * planning input in the same way: the planner rejects targets outside it.
      */
-    selectRoute(request: TaskRequest, hostServices: HostServices, interactionMode?: InteractionMode): Promise<RouteSelection>;
+    selectRoute(request: TaskRequest, hostServices: HostServices, interactionMode?: InteractionMode, modelProfile?: SharedPlannerInput["modelProfile"]): Promise<RouteSelection>;
     private selectFromSharedPlan;
     private buildSelectionFromRoutePlan;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;;;;;OAaG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,YAAY,EAC1B,eAAe,GAAE,eAAuB,GACvC,OAAO,CAAC,cAAc,CAAC;IAoB1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,2BAA2B;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAkBzB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;;;;;;OAcG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,YAAY,EAC1B,eAAe,GAAE,eAAuB,EACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC;IA0B1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,2BAA2B;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAkBzB"}

package/dist/core/router.js

@@ -24,12 +24,13 @@ export class Router {
      *
      * The requested `interactionMode` is a planning input, not a post-filter: the
      * shared planner rejects providers that cannot satisfy it and says why, so the
-     * whole returned chain is mode-compatible.
+     * whole returned chain is mode-compatible. The resolved model profile is a
+     * planning input in the same way: the planner rejects targets outside it.
      */
-    async selectRoute(request, hostServices, interactionMode = "run") {
+    async selectRoute(request, hostServices, interactionMode = "run", modelProfile) {
         const online = await hostServices.connectivity.isOnline();
         const snapshots = await collectProviderRuntimeSnapshots(this.registry.list(), hostServices);
-        const planInput = buildSharedPlannerInput(request, snapshots, online, interactionMode);
+        const planInput = buildSharedPlannerInput(request, snapshots, online, interactionMode, modelProfile);
         const outcome = await this.planner.planRoute(planInput);
         if (!outcome.routePlan) {
             // There is no second planner to degrade to: routing is the shared Rust

package/dist/facade/text.d.ts

@@ -0,0 +1,123 @@
+import type { ExecutionProvenance, StreamEvent, StreamTerminalOutcome, TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import type { IndeRunApi } from "../core/generated/inderun-api.js";
+/**
+ * The primary text API: `generateText()` and `streamText()`.
+ *
+ * Both are translation only. Each call compiles to exactly one canonical `TaskRequest`
+ * ({@link toTaskRequest}) and calls `run()` or `stream()` on the `IndeRunApi` it is given, so
+ * routing, fallback, cancellation, credentials, telemetry, and error normalization are the
+ * engine's and identical to a direct call. Written against the generated interface rather than
+ * the engine class, so anything that implements `IndeRunApi` -- a bridge included -- gets the
+ * same facade. See `docs/architecture/api-layering.md`.
+ */
+type Message = NonNullable<TaskRequest["messages"]>[number];
+/**
+ * Compact execution policy. Reuses the canonical enum values, so moving a call between the
+ * facade and `run()` never changes what a constraint means.
+ */
+export interface TextExecutionOptions {
+    /** `constraints.privacy`: how strict placement is, e.g. `"local_required"`. */
+    privacy?: NonNullable<TaskRequest["constraints"]>["privacy"];
+    /** `constraints.cloud`: `"forbidden"`, `"allowed"`, or `"required"`. */
+    cloud?: NonNullable<TaskRequest["constraints"]>["cloud"];
+    /** `constraints.timeoutMs`. */
+    timeoutMs?: number;
+    /** `preferences.optimizeFor`. */
+    optimizeFor?: NonNullable<TaskRequest["preferences"]>["optimizeFor"];
+}
+interface TextGenerationCommonOptions {
+    /**
+     * Model profile to route within, as configured on the engine. Omitted or `"auto"` routes
+     * across every registered target. Never a vendor model id.
+     */
+    model?: string;
+    /** Instructions sent as a leading `system` message. */
+    system?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stop?: string[];
+    seed?: number;
+    execution?: TextExecutionOptions;
+    /** Secure-storage slot for provider credentials. Never a raw secret. */
+    authContextRef?: string;
+    telemetry?: TaskRequest["telemetry"];
+    /** Fixes the run id, for correlation. */
+    requestId?: string;
+}
+/** Options for {@link generateText} and {@link streamText}: a prompt or a message list. */
+export type TextGenerationOptions = TextGenerationCommonOptions & ({
+    prompt: string;
+    messages?: never;
+} | {
+    messages: Message[];
+    prompt?: never;
+});
+/** What {@link generateText} returns. */
+export interface GeneratedText {
+    text: string;
+    finishReason: TaskResult["finishReason"];
+    usage?: TaskResult["usage"];
+    runId: string;
+    /** How the run played out; see `ExecutionProvenance`. */
+    provenance?: ExecutionProvenance;
+    /** The canonical result, for anything the summary above leaves out. */
+    taskResult: TaskResult;
+}
+/** How a {@link streamText} run ended, when it did not fail. */
+export interface StreamedText {
+    /** The full text, or the partial text a cancelled run had delivered. */
+    text: string;
+    /** `"cancelled"` when the run was cancelled; otherwise as the provider reported it. */
+    finishReason?: TaskResult["finishReason"];
+    usage?: TaskResult["usage"];
+    runId: string;
+    provenance?: ExecutionProvenance;
+    /** The canonical terminal outcome. */
+    outcome: StreamTerminalOutcome;
+}
+/** What {@link streamText} returns. */
+export interface TextStream {
+    runId: string;
+    /**
+     * Text increments, in order. Ends when the run completes or is cancelled; throws the run's
+     * `IndeRunException` when it fails, and {@link TextStreamRetractedError} when the provider
+     * replaces delivered text (use `fullStream` to render retractions).
+     */
+    textStream: AsyncIterable<string>;
+    /** The canonical `StreamEvent` sequence, terminal included. */
+    fullStream: AsyncIterable<StreamEvent>;
+    /**
+     * Settles with the run's ending: resolves on completion or cancellation, rejects with the
+     * run's `IndeRunException` on failure.
+     */
+    result: Promise<StreamedText>;
+    /** Cancels the run; idempotent. */
+    cancel(reason?: string): void;
+}
+/**
+ * Thrown by `textStream` when the provider replaces text it already delivered with text that
+ * does not extend it, which an append-only text view cannot represent.
+ */
+export declare class TextStreamRetractedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** The canonical `TaskRequest` a facade call compiles to. */
+export declare function toTaskRequest(options: TextGenerationOptions): TaskRequest;
+/**
+ * Generates text in one call: `run()` over the canonical request. Not cancellable, for the same
+ * reason `run()` is not; use {@link streamText} when cancellation matters.
+ * @throws {IndeRunException} Exactly as `run()` does.
+ */
+export declare function generateText(inderun: IndeRunApi, options: TextGenerationOptions): Promise<GeneratedText>;
+/**
+ * Streams text: `stream()` over the canonical request. The run starts immediately and is read
+ * once, into a replay buffer, so `textStream`, `fullStream`, and `result` can each be consumed
+ * in any order (or not at all) without stalling the others.
+ * @throws {IndeRunException} Exactly as `stream()` does: validation and routing refusals reject
+ *   here, before there is a run.
+ */
+export declare function streamText(inderun: IndeRunApi, options: TextGenerationOptions): Promise<TextStream>;
+export {};
+//# sourceMappingURL=text.d.ts.map

package/dist/facade/text.d.ts.map

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

package/dist/facade/text.js

@@ -0,0 +1,234 @@
+import { IndeRunException } from "../core/errors.js";
+import { AUTO_MODEL_PROFILE } from "../core/model-profiles.js";
+/**
+ * Thrown by `textStream` when the provider replaces text it already delivered with text that
+ * does not extend it, which an append-only text view cannot represent.
+ */
+export class TextStreamRetractedError extends Error {
+    runId;
+    constructor(runId) {
+        super(`Run ${runId} replaced text it had already delivered; read fullStream to render retractions.`);
+        this.runId = runId;
+        this.name = "TextStreamRetractedError";
+    }
+}
+/** The canonical `TaskRequest` a facade call compiles to. */
+export function toTaskRequest(options) {
+    const request = { schemaVersion: "1.0", task: { kind: "text_to_text" } };
+    if (options.system !== undefined) {
+        const conversation = options.messages ??
+            (options.prompt !== undefined ? [{ role: "user", content: options.prompt }] : []);
+        request.messages = [{ role: "system", content: options.system }, ...conversation];
+    }
+    else if (options.messages !== undefined) {
+        // An empty list is the engine's to reject, with the same validation error as run().
+        request.messages = options.messages;
+    }
+    else if (options.prompt !== undefined) {
+        request.prompt = options.prompt;
+    }
+    if (options.model !== undefined && options.model !== AUTO_MODEL_PROFILE) {
+        request.modelProfile = options.model;
+    }
+    const generation = {};
+    if (options.maxOutputTokens !== undefined)
+        generation.maxOutputTokens = options.maxOutputTokens;
+    if (options.temperature !== undefined)
+        generation.temperature = options.temperature;
+    if (options.topP !== undefined)
+        generation.topP = options.topP;
+    if (options.stop !== undefined)
+        generation.stop = options.stop;
+    if (options.seed !== undefined)
+        generation.seed = options.seed;
+    if (Object.keys(generation).length > 0)
+        request.generation = generation;
+    const execution = options.execution ?? {};
+    const constraints = {};
+    if (execution.privacy !== undefined)
+        constraints.privacy = execution.privacy;
+    if (execution.cloud !== undefined)
+        constraints.cloud = execution.cloud;
+    if (execution.timeoutMs !== undefined)
+        constraints.timeoutMs = execution.timeoutMs;
+    if (Object.keys(constraints).length > 0)
+        request.constraints = constraints;
+    if (execution.optimizeFor !== undefined) {
+        request.preferences = { optimizeFor: execution.optimizeFor };
+    }
+    if (options.authContextRef !== undefined)
+        request.authContextRef = options.authContextRef;
+    if (options.telemetry !== undefined)
+        request.telemetry = options.telemetry;
+    if (options.requestId !== undefined)
+        request.requestId = options.requestId;
+    return request;
+}
+/**
+ * Generates text in one call: `run()` over the canonical request. Not cancellable, for the same
+ * reason `run()` is not; use {@link streamText} when cancellation matters.
+ * @throws {IndeRunException} Exactly as `run()` does.
+ */
+export async function generateText(inderun, options) {
+    const taskResult = await inderun.run(toTaskRequest(options));
+    return {
+        text: taskResult.output.text,
+        finishReason: taskResult.finishReason,
+        ...(taskResult.usage !== undefined ? { usage: taskResult.usage } : {}),
+        runId: taskResult.runId,
+        ...(taskResult.provenance !== undefined ? { provenance: taskResult.provenance } : {}),
+        taskResult
+    };
+}
+/**
+ * Streams text: `stream()` over the canonical request. The run starts immediately and is read
+ * once, into a replay buffer, so `textStream`, `fullStream`, and `result` can each be consumed
+ * in any order (or not at all) without stalling the others.
+ * @throws {IndeRunException} Exactly as `stream()` does: validation and routing refusals reject
+ *   here, before there is a run.
+ */
+export async function streamText(inderun, options) {
+    const run = await inderun.stream(toTaskRequest(options));
+    const runId = run.handle.runId;
+    const replay = new ReplayBuffer();
+    const result = (async () => {
+        // The terminal event is the last one a run delivers, so it settles everything; a source
+        // that stays open after it (a bridge subscription, say) must not hold the result back.
+        // Releasing the source is not awaited for the same reason.
+        const events = run.events[Symbol.asyncIterator]();
+        try {
+            for (let next = await events.next(); next.done !== true; next = await events.next()) {
+                replay.push(next.value);
+                if (next.value.type === "terminal") {
+                    void events.return?.()?.catch(() => undefined);
+                    break;
+                }
+            }
+            replay.close();
+        }
+        catch (error) {
+            replay.fail(error);
+            throw error;
+        }
+        const terminal = replay.items.find((event) => event.type === "terminal");
+        if (terminal === undefined) {
+            throw new IndeRunException({
+                errorClass: "Internal",
+                message: `Run ${runId} ended without a terminal event.`,
+                runId
+            });
+        }
+        return settle(terminal.payload);
+    })();
+    // Consumers may read only one view; an unread rejection must not surface as unhandled.
+    result.catch(() => undefined);
+    return {
+        runId,
+        fullStream: { [Symbol.asyncIterator]: () => replay.iterate() },
+        textStream: { [Symbol.asyncIterator]: () => textIncrements(replay.iterate(), runId) },
+        result,
+        cancel: (reason) => run.cancel(reason)
+    };
+}
+function settle(outcome) {
+    const provenance = outcome.provenance !== undefined ? { provenance: outcome.provenance } : {};
+    switch (outcome.outcome) {
+        case "completed":
+            return {
+                text: outcome.finalText ?? "",
+                ...(outcome.finishReason !== undefined ? { finishReason: outcome.finishReason } : {}),
+                ...(outcome.usage !== undefined ? { usage: outcome.usage } : {}),
+                runId: outcome.runId,
+                ...provenance,
+                outcome
+            };
+        case "cancelled":
+            return {
+                text: outcome.partialText ?? "",
+                finishReason: "cancelled",
+                runId: outcome.runId,
+                ...provenance,
+                outcome
+            };
+        case "error": {
+            const error = outcome.error;
+            throw new IndeRunException({
+                errorClass: error.errorClass,
+                message: error.message,
+                runId: outcome.runId,
+                ...(error.providerId !== undefined ? { providerId: error.providerId } : {}),
+                ...(error.retryable !== undefined ? { retryable: error.retryable } : {}),
+                ...(error.retryAfterMs !== undefined ? { retryAfterMs: error.retryAfterMs } : {}),
+                ...(error.details !== undefined ? { details: error.details } : {}),
+                ...(outcome.provenance !== undefined ? { provenance: outcome.provenance } : {})
+            });
+        }
+    }
+}
+async function* textIncrements(events, runId) {
+    let text = "";
+    for await (const event of events) {
+        if (event.type === "content_delta") {
+            const delta = event.payload.text;
+            text += delta;
+            yield delta;
+        }
+        else if (event.type === "content_snapshot") {
+            const snapshot = event.payload.text;
+            if (!snapshot.startsWith(text)) {
+                throw new TextStreamRetractedError(runId);
+            }
+            const suffix = snapshot.slice(text.length);
+            text = snapshot;
+            if (suffix.length > 0)
+                yield suffix;
+        }
+        else if (event.type === "terminal") {
+            settle(event.payload);
+            return;
+        }
+    }
+}
+/**
+ * Holds every item read from a single-use source so any number of readers can iterate it from
+ * the start, each at its own pace. Readers that catch up wait for the next item.
+ */
+class ReplayBuffer {
+    items = [];
+    done = false;
+    failure;
+    waiters = [];
+    push(item) {
+        this.items.push(item);
+        this.wake();
+    }
+    close() {
+        this.done = true;
+        this.wake();
+    }
+    fail(error) {
+        this.failure = { error };
+        this.close();
+    }
+    async *iterate() {
+        let index = 0;
+        while (true) {
+            if (index < this.items.length) {
+                yield this.items[index++];
+                continue;
+            }
+            if (this.done) {
+                if (this.failure !== undefined)
+                    throw this.failure.error;
+                return;
+            }
+            await new Promise((resolve) => this.waiters.push(resolve));
+        }
+    }
+    wake() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const wake of waiters)
+            wake();
+    }
+}