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

package/src/core/provider.ts

@@ -1,149 +1,36 @@
 import type {
+  ProviderDescriptor,
+  ProviderDynamicCapabilities,
+  SharedRoutePlan,
   StreamEvent,
   StreamRunHandle,
+  TaskOutput,
   TaskRequest,
   TaskResult
 } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
+import type { ArtifactSink } from "./artifacts.js";
 
-/**
- * Static metadata descriptor defining the capabilities, requirements, and constraints
- * of a provider. This is used by the routing engine and Router to select candidate providers.
- */
-export interface ProviderDescriptor {
-  /**
-   * Unique identifier of the provider (e.g., 'openai', 'apple-foundation-models').
-   */
-  id: string;
-  /**
-   * 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.
-   */
-  transport: "in_process" | "system_service" | "http" | "sse" | "realtime";
-  /**
-   * Optional streaming style, if token or chunk streaming is supported.
-   */
-  streamingStyle?: "tokens" | "chunks" | "snapshots";
-
-  /**
-   * Flags representing the features and modes supported by this provider.
-   */
-  supports: {
-    /** Whether the provider supports Mode 1 run (request/response). */
-    run: boolean;
-    /** Whether the provider supports Mode 2 stream. */
-    streaming: boolean;
-    /** Whether the provider supports Mode 3 realtime session. */
-    realtime: boolean;
-    /** Whether the provider supports tool calling definition. */
-    tools: boolean;
-    /** Whether the provider outputs reasoning events alongside contents. */
-    reasoningEvents: boolean;
-    /** Whether the provider supports structured outputs (JSON schema constraints). */
-    structuredOutput: boolean;
-    /** Whether the provider supports multimodal inputs (images, audio, etc.). */
-    multimodal: boolean;
-  };
-
-  /**
-   * Cancellation capabilities support:
-   * - 'hard': fully stops processing and interrupts remote operations.
-   * - 'soft': stops reading the stream locally, but the remote execution continues.
-   * - 'none': cancellation is unsupported.
-   */
-  cancel: "hard" | "soft" | "none";
-
-  /**
-   * List of supported task kinds (e.g., 'text_to_text', 'embeddings').
-   */
-  tasks: string[];
-
-  /**
-   * Optional input/output resource boundaries.
-   */
-  limits?: {
-    maxInputTokens?: number;
-    maxOutputTokens?: number;
-    maxImageBytes?: number;
-    maxAudioSeconds?: number;
-  };
-
-  /**
-   * Privacy settings regarding data egress.
-   */
-  privacy?: {
-    /** Set to true if the model input leaves the host device. */
-    dataLeavesDevice: boolean;
-    /** Geographic regions where the cloud service executes. */
-    regions?: string[];
-  };
-}
+export type {
+  ArtifactChunk,
+  ArtifactLimits,
+  ArtifactSink,
+  ArtifactSpec,
+  ArtifactWriter
+} from "./artifacts.js";
 
 /**
- * Dynamic capability snapshot evaluated at runtime.
+ * A provider's static declaration, live capability check, and the pair as
+ * `checkCapabilities()` returns it. All three are schema-backed contracts
+ * (`contracts/schemas/provider-*.schema.json`), shared with the Swift and Kotlin
+ * SDKs and with the route planner, so they are re-exported here rather than
+ * declared.
  */
-export interface ProviderDynamicCapabilities {
-  /**
-   * Whether the provider is available and functional on the host device now.
-   */
-  available: boolean;
-  /**
-   * 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,
- * as of the moment checkCapabilities() was called.
- */
-export interface ProviderCapabilitySnapshot {
-  /**
-   * Stable identifier for this provider, matching the value used in routing
-   * preferences/constraints.
-   */
-  providerId: string;
-  /**
-   * The provider's static, unchanging capability declaration (supported modes,
-   * privacy posture, model info).
-   */
-  descriptor: ProviderDescriptor;
-  /**
-   * The provider's current dynamic availability (e.g. whether it's reachable/loaded
-   * right now) — this is the part that can change between calls.
-   */
-  capabilities: ProviderDynamicCapabilities;
-}
+export type {
+  ProviderCapabilitySnapshot,
+  ProviderDescriptor,
+  ProviderDynamicCapabilities
+} from "@independo/inderun-contracts";
 
 /**
  * Execution context passed to provider run commands.
@@ -158,6 +45,37 @@ export interface RunContext {
    * resolve authContextRef through secure storage and dispatch HTTP requests.
    */
   hostServices: HostServices;
+  /**
+   * The voice the route plan bound this provider to for a speech task: provider-neutral
+   * traits the provider must honour when it picks the voice that speaks. Absent for tasks
+   * without a voice and for providers that do not list their voices, which then choose
+   * under the same rule (ADR 016 §4). The engine has re-checked it against the request's
+   * privacy policy immediately before the attempt.
+   */
+  voice?: NonNullable<SharedRoutePlan["candidates"][number]["voice"]>;
+  /**
+   * Commits the run to this provider. Call it immediately before the attempt's first
+   * externally observable effect — for managed playback, no later than the first moment
+   * sound may reach the user. After commit, a failure ends the run instead of falling back
+   * to another provider, because a second provider would repeat what the user may already
+   * have heard.
+   *
+   * Returns `false` when the run can no longer commit (it was cancelled or has already
+   * ended) and when this attempt is over, e.g. a late callback after the engine fell back to
+   * another provider; the provider must then not start the effect and should end the attempt.
+   * Idempotent: calling it again after a successful commit returns `true`.
+   *
+   * Providers whose output is only delivered at the end (text from `run()`) need not call
+   * it. Text streams commit implicitly on their first content event.
+   */
+  commit(): boolean;
+  /**
+   * Where the provider writes retrievable media for an `artifact` request (ADR 017). The
+   * engine holds the bytes; the provider returns the reference `finish()` gives it in an
+   * `artifact` output. Finishing commits the run. Artifacts this attempt does not return,
+   * or that a failed or cancelled attempt wrote, are discarded by the engine.
+   */
+  artifacts: ArtifactSink;
 }
 
 /**
@@ -202,6 +120,17 @@ export type ProviderStreamEvent =
        */
       reportedModel?: string;
     }
+  | {
+      /**
+       * The run's normalized output, for tasks whose output is not streamed text
+       * (playback completion, a media artifact). Ends the stream like `done`; handing it
+       * over commits the run if the provider has not already called `commit()`.
+       */
+      kind: "result";
+      output: TaskOutput;
+      finishReason?: TaskResult["finishReason"];
+      reportedModel?: string;
+    }
   | { kind: "error"; error: unknown };
 
 /**

package/src/core/route-planner.ts

@@ -4,6 +4,7 @@ import type {
   TaskRequest
 } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
+import { taskProfileFor } from "./task-profiles.js";
 import type {
   ProviderAdapter,
   ProviderDescriptor,
@@ -55,13 +56,13 @@ export interface RoutePlanner {
 }
 
 /**
- * A provider paired with the descriptor/capability projection the shared route
- * planner consumes.
+ * A provider paired with its descriptor and the dynamic capabilities the shared
+ * route planner consumes (already folded by {@link toSharedPlannerCapabilities}).
  */
 export interface ProviderRuntimeSnapshot {
   provider: ProviderAdapter;
-  descriptor: SharedPlannerInput["providers"][number]["descriptor"];
-  capabilities: SharedPlannerInput["providers"][number]["capabilities"];
+  descriptor: ProviderDescriptor;
+  capabilities: ProviderDynamicCapabilities;
 }
 
 /**
@@ -161,7 +162,7 @@ export async function collectProviderRuntimeSnapshots(
 
       return {
         provider,
-        descriptor: toSharedPlannerDescriptor(descriptor),
+        descriptor,
         capabilities: toSharedPlannerCapabilities(capabilities, descriptor, provider)
       };
     })
@@ -184,9 +185,7 @@ export function buildSharedPlannerInput(
   const preferences = request.preferences ?? {};
 
   return {
-    task: {
-      kind: request.task.kind
-    },
+    task: plannerTask(request),
     interactionMode,
     constraints: {
       privacy: constraints.privacy ?? "cloud_allowed",
@@ -205,27 +204,13 @@ export function buildSharedPlannerInput(
   };
 }
 
-function toSharedPlannerDescriptor(
-  descriptor: ProviderDescriptor
-): SharedPlannerInput["providers"][number]["descriptor"] {
-  return {
-    id: descriptor.id,
-    type: descriptor.type,
-    supports: {
-      run: descriptor.supports.run,
-      streaming: descriptor.supports.streaming
-    },
-    cancel: descriptor.cancel,
-    tasks: descriptor.tasks,
-    ...(descriptor.privacy
-      ? {
-          privacy: {
-            dataLeavesDevice: descriptor.privacy.dataLeavesDevice,
-            ...(descriptor.privacy.regions ? { regions: descriptor.privacy.regions } : {})
-          }
-        }
-      : {})
-  };
+/**
+ * Projects the request's task onto the requirements the planner can check, through the
+ * kind's task profile. A kind without a profile carries the kind alone, which the planner
+ * matches against declarations and nothing else.
+ */
+function plannerTask(request: TaskRequest): SharedPlannerInput["task"] {
+  return taskProfileFor(request.task.kind)?.plannerTask(request) ?? { kind: request.task.kind };
 }
 
 /**
@@ -241,7 +226,7 @@ function toSharedPlannerCapabilities(
   capabilities: ProviderDynamicCapabilities,
   descriptor: ProviderDescriptor,
   provider: ProviderAdapter
-): SharedPlannerInput["providers"][number]["capabilities"] {
+): ProviderDynamicCapabilities {
   const declaresStreaming = capabilities.streamingAvailable ?? descriptor.supports.streaming;
   const implementsStream = typeof provider.stream === "function";
   const streamingAvailable = declaresStreaming && implementsStream;
@@ -251,13 +236,12 @@ function toSharedPlannerCapabilities(
       ? `Provider '${descriptor.id}' declares streaming but does not implement stream().`
       : undefined);
 
+  // Spread rather than pick, so a field added to the schema reaches the planner
+  // without touching this function.
+  const { streamingUnavailableReason: _declaredReason, ...rest } = capabilities;
   return {
-    available: capabilities.available,
-    ...(capabilities.reason ? { reason: capabilities.reason } : {}),
+    ...rest,
     streamingAvailable,
-    ...(!streamingAvailable && streamingUnavailableReason ? { streamingUnavailableReason } : {}),
-    ...(capabilities.cancellationAvailable !== undefined
-      ? { cancellationAvailable: capabilities.cancellationAvailable }
-      : {})
+    ...(!streamingAvailable && streamingUnavailableReason ? { streamingUnavailableReason } : {})
   };
 }

package/src/core/router.ts

@@ -2,6 +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 { BoundVoice } from "./task-profiles.js";
 import {
   createCapabilityMismatch,
   createInternal,
@@ -19,6 +20,18 @@ import {
   WasmRoutePlanner
 } from "./route-planner.js";
 
+/**
+ * One provider in the planned chain, with the voice the plan bound it to (speech only).
+ */
+export interface RouteCandidate {
+  provider: ProviderAdapter;
+  /**
+   * The voice this provider must use, chosen by the planner within the request's privacy
+   * policy. Absent when the task has no voice or the provider does not list its voices.
+   */
+  voice?: BoundVoice;
+}
+
 /**
  * Output structure from the Router containing the chosen provider and a route selection description.
  */
@@ -31,6 +44,10 @@ export interface RouteSelection {
    * Ordered fallback providers to try if the primary provider fails before producing a final result.
    */
   fallbackProviders: ProviderAdapter[];
+  /**
+   * The whole chain in attempt order (`provider` first), each with its bound voice.
+   */
+  candidates: RouteCandidate[];
   /**
    * The shared route plan used to select this provider chain.
    */
@@ -113,20 +130,26 @@ export class Router {
     snapshots: ProviderRuntimeSnapshot[],
     routePlan: SharedPlannerRoutePlan
   ): RouteSelection {
-    const orderedProviders = routePlan.candidates
-      .map((candidate) =>
-        snapshots.find((snapshot) => snapshot.descriptor.id === candidate.providerId)
-      )
-      .filter((snapshot): snapshot is ProviderRuntimeSnapshot => snapshot !== undefined);
+    const candidates = routePlan.candidates.flatMap((candidate): RouteCandidate[] => {
+      const snapshot = snapshots.find((s) => s.descriptor.id === candidate.providerId);
+      if (snapshot === undefined) return [];
+      return [
+        {
+          provider: snapshot.provider,
+          ...(candidate.voice !== undefined ? { voice: candidate.voice } : {})
+        }
+      ];
+    });
 
-    const selected = orderedProviders[0];
+    const selected = candidates[0];
     if (!selected) {
       throw createInternal("Route plan selected a provider that is no longer registered.");
     }
 
     return {
       provider: selected.provider,
-      fallbackProviders: orderedProviders.slice(1).map((snapshot) => snapshot.provider),
+      fallbackProviders: candidates.slice(1).map((candidate) => candidate.provider),
+      candidates,
       routePlan,
       explanation: routePlan.explanation.summary
     };

package/src/core/task-profiles.ts

@@ -0,0 +1,145 @@
+import type {
+  SharedRoutePlan,
+  SharedRoutePlannerInput,
+  TaskOutput,
+  TaskRequest
+} from "@independo/inderun-contracts";
+import { createCapabilityMismatch, createInternal, type IndeRunException } from "./errors.js";
+
+/** How a task's result reaches the application: `inline`, `playback` or `artifact`. */
+export type OutputDelivery = NonNullable<TaskRequest["delivery"]>["mode"];
+/** The provider-neutral voice a route candidate is bound to. */
+export type BoundVoice = NonNullable<SharedRoutePlan["candidates"][number]["voice"]>;
+
+/**
+ * What the engine needs to know about one task kind (ADR 016). This table is the only
+ * place the engine branches on `task.kind`: which kinds it executes, the projection onto
+ * the planner's task requirements, and the output delivery a result must have. (Per-kind
+ * request requirements are the schema's `if`/`then` branches, checked by the validator.) Everything else — routing, fallback, cancellation, provenance — is task-agnostic,
+ * so a new task adds an entry here rather than a second execution path.
+ *
+ * The Swift (`TaskProfiles.swift`) and Kotlin (`TaskProfiles.kt`) engines keep the same
+ * table; `contracts/fixtures/task-contracts/` holds the planner projection all three must
+ * produce for each request.
+ */
+export interface TaskProfile {
+  /** The `task.kind` this profile describes. */
+  readonly kind: string;
+  /** Projects the request onto the requirements the shared planner can check. */
+  plannerTask(request: TaskRequest): SharedRoutePlannerInput["task"];
+  /** The output delivery the request asks for: `inline` for text, else `delivery.mode`. */
+  delivery(request: TaskRequest): OutputDelivery;
+}
+
+const textToText: TaskProfile = {
+  kind: "text_to_text",
+  plannerTask: () => ({ kind: "text_to_text", inputs: ["text"] }),
+  delivery: () => "inline"
+};
+
+const textToSpeech: TaskProfile = {
+  kind: "text_to_speech",
+  plannerTask: (request) => {
+    // The schema requires both for this kind; validation runs before projection.
+    const speech = request.speech!;
+    const delivery = request.delivery!;
+    return {
+      kind: "text_to_speech",
+      inputs: ["text"],
+      delivery: {
+        mode: delivery.mode,
+        ...(delivery.mediaTypes !== undefined ? { mediaTypes: [...delivery.mediaTypes] } : {})
+      },
+      locale: { tag: speech.locale, match: speech.localeMatch ?? "language" },
+      ...(speech.voice !== undefined
+        ? {
+            voice: {
+              ...(speech.voice.gender !== undefined ? { gender: speech.voice.gender } : {}),
+              requirement: speech.voice.requirement ?? "preferred"
+            }
+          }
+        : {})
+    };
+  },
+  delivery: (request) => request.delivery!.mode
+};
+
+const taskProfiles = new Map<string, TaskProfile>([
+  [textToText.kind, textToText],
+  [textToSpeech.kind, textToSpeech]
+]);
+
+/**
+ * Adds a task profile. Internal and not exported from the package: a real task needs its
+ * schema kind and payload first (ADR 016). It exists so a test can prove a third task runs
+ * through routing, execution and output normalization without changing the engine.
+ * @internal
+ */
+export function registerTaskProfile(profile: TaskProfile): void {
+  taskProfiles.set(profile.kind, profile);
+}
+
+/** The profile for `kind`, or `undefined` when this engine cannot execute the task. */
+export function taskProfileFor(kind: string): TaskProfile | undefined {
+  return taskProfiles.get(kind);
+}
+
+/**
+ * Re-checks, immediately before an attempt, that the voice the plan bound for this
+ * provider still satisfies the request's privacy policy. The planner already chose the
+ * voice inside that policy; repeating the check here keeps privacy enforceable at the
+ * last point before data reaches the provider, independent of how the plan was produced.
+ * A violation fails the attempt before commit, so the run may fall back.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the voice is allowed.
+ */
+export function recheckBoundVoice(
+  request: TaskRequest,
+  providerId: string,
+  voice: BoundVoice | undefined
+): IndeRunException | undefined {
+  if (voice?.networkRequired !== true || request.constraints?.privacy !== "local_required") {
+    return undefined;
+  }
+  return createCapabilityMismatch(
+    `Provider '${providerId}' was bound to a voice that sends data off the device, which privacy=local_required forbids.`,
+    { providerId, details: { code: "privacy_recheck_failed" } }
+  );
+}
+
+/**
+ * Checks a provider's output against the delivery the request asked for: inline text for
+ * `inline`, a playback completion for `playback`, a media artifact for `artifact` whose
+ * media type is one the request accepts. A provider never substitutes one for another
+ * (ADR 016 §4), so a mismatch is a provider fault, not a result.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the output matches.
+ */
+export function checkOutput(
+  request: TaskRequest,
+  delivery: OutputDelivery,
+  output: TaskOutput | undefined,
+  providerId: string
+): IndeRunException | undefined {
+  const expected = { inline: "text", playback: "playback", artifact: "artifact" }[delivery];
+  const matches =
+    output?.type === expected &&
+    (expected === "text"
+      ? typeof output.text === "string"
+      : expected === "playback"
+        ? output.playback !== undefined
+        : output.artifact !== undefined && acceptsMediaType(request, output.artifact.mediaType));
+  if (matches) return undefined;
+  return createInternal(
+    `Provider '${providerId}' returned ${output === undefined ? "no output" : `a '${output.type}' output`} for a '${delivery}' request.`,
+    { providerId, details: { code: "output_mismatch" } }
+  );
+}
+
+/** Whether `mediaType` (parameters ignored, case-insensitive) is one the request accepts. */
+function acceptsMediaType(request: TaskRequest, mediaType: string): boolean {
+  const accepted = request.delivery?.mediaTypes;
+  if (accepted === undefined) return true;
+  const base = (type: string) => type.split(";")[0]!.trim().toLowerCase();
+  return accepted.some((type) => base(type) === base(mediaType));
+}

package/src/facade/text.ts

@@ -176,7 +176,9 @@ export async function generateText(
 ): Promise<GeneratedText> {
   const taskResult = await inderun.run(toTaskRequest(options));
   return {
-    text: taskResult.output.text,
+    // A text run always produces text output; the generated type is optional only because
+    // TaskOutput also describes playback and artifacts (ADR 016).
+    text: taskResult.output.text ?? "",
     finishReason: taskResult.finishReason,
     ...(taskResult.usage !== undefined ? { usage: taskResult.usage } : {}),
     runId: taskResult.runId,
@@ -245,7 +247,7 @@ function settle(outcome: StreamTerminalOutcome): StreamedText {
   switch (outcome.outcome) {
     case "completed":
       return {
-        text: outcome.finalText ?? "",
+        text: outcome.finalText ?? outcome.output?.text ?? "",
         ...(outcome.finishReason !== undefined ? { finishReason: outcome.finishReason } : {}),
         ...(outcome.usage !== undefined ? { usage: outcome.usage } : {}),
         runId: outcome.runId,
@@ -254,7 +256,7 @@ function settle(outcome: StreamTerminalOutcome): StreamedText {
       };
     case "cancelled":
       return {
-        text: outcome.partialText ?? "",
+        text: outcome.partialText ?? outcome.output?.text ?? "",
         finishReason: "cancelled",
         runId: outcome.runId,
         ...provenance,

package/src/index.ts

@@ -54,7 +54,12 @@ export { AUTO_MODEL_PROFILE, type ModelProfiles } from "./core/model-profiles.js
  */
 export { IndeRun, type IndeRunOptions, type StreamHandleResult } from "./core/engine.js";
 export type { IndeRunApi } from "./core/generated/inderun-api.js";
-export type { ProviderCapabilitySnapshot, StreamRun } from "./core/provider.js";
+export type {
+  ArtifactChunk,
+  ArtifactLimits,
+  ProviderCapabilitySnapshot,
+  StreamRun
+} from "./core/provider.js";
 
 /**
  * The contract types this SDK's own signatures take and return.

package/src/providers/onnx/runtime.ts

@@ -8,12 +8,12 @@ import type { ModelPackage, TaskRequest, TaskResult } from "@independo/inderun-c
  * flattens every failure into a single `capability_unavailable` route rejection and carries the
  * reason as human-readable text.
  */
-export interface OnnxRuntimeAvailability {
+export type OnnxRuntimeAvailability = {
   /** Whether the runtime can execute the given model package on this host right now. */
   available: boolean;
   /** Human-readable detail describing why the runtime is unavailable. */
   reason?: string;
-}
+};
 
 /**
  * Normalized conversation turn handed to an ONNX text generation runtime.