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

package/src/generated/task-request.ts

@@ -1,9 +1,13 @@
 /* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
 
 /**
- * The request payload for a Mode 1 (request/response) text-to-text execution. At least one
- * of `prompt` (single-turn) or `messages` (multi-turn) must be present — both may be
- * present together, though callers should typically supply just one;
+ * The request payload for a run() or stream() execution. The common envelope
+ * (schemaVersion, requestId, task, modelProfile, constraints, preferences, telemetry,
+ * authContextRef) is task-agnostic; each task kind owns its payload (ADR 016).
+ * text_to_text: at least one of `prompt` (single-turn) or `messages` (multi-turn) must be
+ * present — both may be present together, though callers should typically supply just one —
+ * and `speech`/`delivery` are forbidden. text_to_speech: `speech` and `delivery` are
+ * required and `prompt`, `messages` and `generation` are forbidden.
  * `constraints`/`preferences` steer routing but never select a provider directly.
  */
 export type TaskRequest = {
@@ -16,6 +20,12 @@ export type TaskRequest = {
      * Request-level routing constraints used by the planner.
      */
     constraints?: Constraints;
+    /**
+     * How the result of a non-text task must reach the application (ADR 016). Required for
+     * non-text tasks and forbidden for text_to_text, whose output is implicitly inline. A
+     * provider never substitutes playback for an artifact or the reverse.
+     */
+    delivery?: OutputDeliveryRequest;
     /**
      * Optional configuration for fine-tuning how the AI model generates its response.
      */
@@ -49,8 +59,13 @@ export type TaskRequest = {
      */
     schemaVersion: "1.0";
     /**
-     * A descriptor specifying the type of work to be performed. For text-to-text, the kind must
-     * be 'text_to_text'.
+     * The text_to_speech payload. Required for text_to_speech and forbidden for every other
+     * kind.
+     */
+    speech?: SpeechInput;
+    /**
+     * A descriptor specifying the type of work to be performed. The kind selects which payload
+     * the request must carry.
      */
     task: Task;
     /**
@@ -73,7 +88,10 @@ export type Constraints = {
      */
     privacy?: Privacy;
     /**
-     * Optional routing timeout budget in milliseconds.
+     * Optional timeout budget in milliseconds, passed to the planner and to providers. It
+     * bounds the time until the run commits to a provider -- its first content, its first
+     * possible audible effect, or its artifact handoff -- not the duration of audio it plays.
+     * The engines add no timers of their own.
      */
     timeoutMs?: number;
     [property: string]: unknown;
@@ -89,6 +107,36 @@ export type Cloud = "forbidden" | "allowed" | "required";
  */
 export type Privacy = "local_required" | "local_preferred" | "cloud_allowed" | "cloud_required";
 
+/**
+ * How the result of a non-text task must reach the application (ADR 016). Required for
+ * non-text tasks and forbidden for text_to_text, whose output is implicitly inline. A
+ * provider never substitutes playback for an artifact or the reverse.
+ */
+export type OutputDeliveryRequest = {
+    /**
+     * Only valid with 'artifact' delivery: an opaque reference to an application destination
+     * the engine writes the finished artifact to, resolved by the host's artifact-destination
+     * service (ADR 017) -- never a raw path or URL, like authContextRef for credentials. The
+     * result's artifact is then application-owned and the engine keeps no copy. A host without
+     * the service refuses the request before routing.
+     */
+    destinationRef?: string;
+    /**
+     * Only valid with 'artifact' delivery: the acceptable media types, always a hard
+     * requirement. Absent means the provider chooses and the artifact reports what it produced.
+     */
+    mediaTypes?: [string, ...string[]];
+    mode:        OutputDelivery;
+    [property: string]: unknown;
+}
+
+/**
+ * How a task's result reaches the application: 'inline' content in the result (text),
+ * 'playback' as a managed, audible effect on the device with no retrievable bytes, or
+ * 'artifact' as retrievable media.
+ */
+export type OutputDelivery = "inline" | "playback" | "artifact";
+
 /**
  * Optional configuration for fine-tuning how the AI model generates its response.
  */
@@ -154,18 +202,83 @@ export type Preferences = {
 export type OptimizeFor = "privacy" | "latency" | "cost" | "balanced";
 
 /**
- * A descriptor specifying the type of work to be performed. For text-to-text, the kind must
- * be 'text_to_text'.
+ * The text_to_speech payload. Required for text_to_speech and forbidden for every other
+ * kind.
+ */
+export type SpeechInput = {
+    /**
+     * BCP 47 tag of the language to speak, e.g. 'de-AT'.
+     */
+    locale: string;
+    /**
+     * 'language' (default): the primary language subtag is a hard requirement and the region is
+     * a preference. 'exact': the full tag is a hard requirement.
+     */
+    localeMatch?: LocaleMatch;
+    /**
+     * Plain text to speak. Markup such as SSML is out of scope.
+     */
+    text: string;
+    /**
+     * Provider-neutral voice traits. A 'preferred' voice (default) shapes which voice speaks
+     * and is never a reason to fail; a 'required' one takes part in routing and is never
+     * relaxed silently. Carries no provider voice identifier.
+     */
+    voice?: SpeechVoice;
+    [property: string]: unknown;
+}
+
+/**
+ * 'language' (default): the primary language subtag is a hard requirement and the region is
+ * a preference. 'exact': the full tag is a hard requirement.
+ */
+export type LocaleMatch = "exact" | "language";
+
+/**
+ * Provider-neutral voice traits. A 'preferred' voice (default) shapes which voice speaks
+ * and is never a reason to fail; a 'required' one takes part in routing and is never
+ * relaxed silently. Carries no provider voice identifier.
+ */
+export type SpeechVoice = {
+    gender?: VoiceGender;
+    /**
+     * 'preferred' (default) or 'required'. A required voice must name at least one trait.
+     */
+    requirement?: RequirementLevel;
+    [property: string]: unknown;
+}
+
+/**
+ * Perceived gender of a voice, as the platform reports it.
+ */
+export type VoiceGender = "female" | "male" | "neutral";
+
+/**
+ * 'preferred' (default) or 'required'. A required voice must name at least one trait.
+ */
+export type RequirementLevel = "required" | "preferred";
+
+/**
+ * A descriptor specifying the type of work to be performed. The kind selects which payload
+ * the request must carry.
  */
 export type Task = {
     /**
-     * The standard task category. Currently supports 'text_to_text' for prompt-based
-     * interactions.
+     * The operation: 'text_to_text' (prompt-based text generation) or 'text_to_speech' (speech
+     * synthesis from text). A consumer built against an older revision rejects a kind it does
+     * not know through validation.
      */
-    kind: "text_to_text";
+    kind: TaskKind;
     [property: string]: unknown;
 }
 
+/**
+ * The operation: 'text_to_text' (prompt-based text generation) or 'text_to_speech' (speech
+ * synthesis from text). A consumer built against an older revision rejects a kind it does
+ * not know through validation.
+ */
+export type TaskKind = "text_to_text" | "text_to_speech";
+
 /**
  * Execution preferences for tracking usage and performance metrics.
  */

package/src/generated/task-result.ts

@@ -1,12 +1,14 @@
 /* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
 
 /**
- * The response payload for a completed text-to-text execution. A full execution failure
- * (validation, routing, or every attempted provider failing) is surfaced by run() throwing
- * an IndeRunError instead of returning a TaskResult; finishReason and telemetry.errorClass
- * are reserved for a provider reporting a non-fatal, degraded outcome on an
- * otherwise-successful result (finishReason 'error' is produced by the Android ML Kit GenAI
- * provider; telemetry.errorClass is not currently set by any provider in this codebase).
+ * The response payload for a completed run() execution, for every task kind; output.type
+ * tells the content representation apart (text, managed playback, retrievable artifact). A
+ * full execution failure (validation, routing, or every attempted provider failing) is
+ * surfaced by run() throwing an IndeRunError instead of returning a TaskResult;
+ * finishReason and telemetry.errorClass are reserved for a provider reporting a non-fatal,
+ * degraded outcome on an otherwise-successful result (finishReason 'error' is produced by
+ * the Android ML Kit GenAI provider; telemetry.errorClass is not currently set by any
+ * provider in this codebase).
  */
 export type TaskResult = {
     /**
@@ -18,9 +20,9 @@ export type TaskResult = {
      */
     finishReason: FinishReason;
     /**
-     * The normalized content returned from the selected provider.
+     * The normalized output of the selected provider. See task-output.schema.json.
      */
-    output: Output;
+    output: TaskOutput;
     /**
      * Normalized execution provenance: which target ran, its declared locality, the configured
      * and reported model, and how fallback and routing played out. See
@@ -56,20 +58,143 @@ export type TaskResult = {
 export type FinishReason = "stop" | "length" | "cancelled" | "error";
 
 /**
- * The normalized content returned from the selected provider.
+ * The normalized output of the selected provider. See task-output.schema.json.
+ *
+ * The normalized output of a run, shared by TaskResult and the completed and cancelled
+ * stream terminal outcomes (ADR 016). 'type' describes the content representation, not the
+ * task: 'text' carries inline text, 'playback' reports a managed, audible effect that has
+ * no retrievable bytes, and 'artifact' references retrievable media (ADR 017). A playback
+ * output is never an artifact, and an artifact output never implies that anything was
+ * played.
+ */
+export type TaskOutput = {
+    /**
+     * The retrievable media the run produced. Required when type is 'artifact'.
+     */
+    artifact?: MediaArtifact;
+    /**
+     * Completion of managed playback. Required when type is 'playback'. Carries no media.
+     */
+    playback?: PlaybackOutput;
+    /**
+     * The locale and voice traits a text-to-speech run actually used, so an unmet preference is
+     * visible without being an error.
+     */
+    speech?: SpeechOutput;
+    /**
+     * The text the run produced. Required when type is 'text'.
+     */
+    text?: string;
+    /**
+     * The content representation: 'text', 'playback' or 'artifact'.
+     */
+    type: TaskOutputType;
+    [property: string]: unknown;
+}
+
+/**
+ * The retrievable media the run produced. Required when type is 'artifact'.
+ *
+ * A reference to retrievable media a run produced (ADR 017). It carries no bytes and no
+ * location: an engine-owned artifact is read through the engine by id, and an
+ * application-owned one was written to an application destination. Media-neutral: audio,
+ * images and video share this shape and differ only in mediaType.
+ */
+export type MediaArtifact = {
+    /**
+     * Size of the media in bytes. Always set for an artifact the engine materialized.
+     */
+    byteLength?: number;
+    /**
+     * The request's delivery.destinationRef the bytes were written to. Set exactly when owner
+     * is 'application'.
+     */
+    destinationRef?: string;
+    /**
+     * Duration of time-based media in milliseconds, where the producer knows it.
+     */
+    durationMs?: number;
+    /**
+     * Opaque, engine-issued identifier. Never a path, URL or provider identifier.
+     */
+    id: string;
+    /**
+     * How long the engine keeps the bytes. 'until_disposed': until the application disposes the
+     * artifact or the process ends; the artifact outlives the run that produced it.
+     */
+    lifetime: "until_disposed";
+    /**
+     * IANA media type of the bytes, e.g. 'audio/wav'. Encoding parameters ride on the media
+     * type (e.g. 'audio/L16;rate=22050').
+     */
+    mediaType: string;
+    /**
+     * 'engine': the engine holds the bytes and the application reads them by id until it
+     * disposes the artifact. 'application': the bytes were written to the application
+     * destination named by destinationRef and the engine holds nothing.
+     */
+    owner: ArtifactOwner;
+    [property: string]: unknown;
+}
+
+/**
+ * How long the engine keeps the bytes. 'until_disposed': until the application disposes the
+ * artifact or the process ends; the artifact outlives the run that produced it.
+ */
+
+/**
+ * 'engine': the engine holds the bytes and the application reads them by id until it
+ * disposes the artifact. 'application': the bytes were written to the application
+ * destination named by destinationRef and the engine holds nothing.
  */
-export type Output = {
+export type ArtifactOwner = "engine" | "application";
+
+/**
+ * Completion of managed playback. Required when type is 'playback'. Carries no media.
+ */
+export type PlaybackOutput = {
     /**
-     * The actual text generated by the execution.
+     * How long audible playback lasted, in milliseconds. For a cancelled run, how long it
+     * played before it was stopped.
      */
-    text: string;
+    durationMs?: number;
+    [property: string]: unknown;
+}
+
+/**
+ * The locale and voice traits a text-to-speech run actually used, so an unmet preference is
+ * visible without being an error.
+ */
+export type SpeechOutput = {
     /**
-     * Output payload category (e.g., 'text' for Mode 1 text-to-text).
+     * BCP 47 tag of the locale that was spoken.
      */
-    type: "text";
+    locale: string;
+    /**
+     * Provider-neutral traits of the voice that spoke. Carries no provider voice identifier.
+     */
+    voice?: SpeechOutputVoice;
+    [property: string]: unknown;
+}
+
+/**
+ * Provider-neutral traits of the voice that spoke. Carries no provider voice identifier.
+ */
+export type SpeechOutputVoice = {
+    gender?: VoiceGender;
     [property: string]: unknown;
 }
 
+/**
+ * Perceived gender of a voice, as the platform reports it.
+ */
+export type VoiceGender = "female" | "male" | "neutral";
+
+/**
+ * The content representation: 'text', 'playback' or 'artifact'.
+ */
+export type TaskOutputType = "text" | "playback" | "artifact";
+
 /**
  * Normalized execution provenance: which target ran, its declared locality, the configured
  * and reported model, and how fallback and routing played out. See
@@ -136,6 +261,13 @@ export type ExecutionProvenance = {
 }
 
 export type ExecutionProvenanceAttempt = {
+    /**
+     * Whether the run committed to this provider during the attempt: its first content was
+     * delivered, it signalled the first possible audible effect, or it handed over an artifact.
+     * After commit a failure ends the run instead of falling back. Absent means the attempt did
+     * not commit.
+     */
+    committed?: boolean;
     /**
      * Normalized error class of a failed attempt.
      */
@@ -177,7 +309,7 @@ export type ExecutionProvenanceRouteRejection = {
     [property: string]: unknown;
 }
 
-export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile";
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile" | "input_not_supported" | "output_delivery_not_supported" | "output_format_not_supported" | "locale_not_supported" | "voice_not_available";
 
 /**
  * Required metadata providing an overview of the execution result and performance metrics.

package/src/generated/telemetry-event.ts

@@ -19,11 +19,11 @@ export type TelemetryEvent = {
     /**
      * Telemetry event kind emitted by the orchestrator or provider integration.
      */
-    type: Type;
+    type: TelemetryEventType;
     [property: string]: unknown;
 }
 
 /**
  * Telemetry event kind emitted by the orchestrator or provider integration.
  */
-export type Type = "route_decided" | "attempt_succeeded" | "attempt_failed" | "stream_attempt_started" | "stream_attempt_succeeded" | "stream_attempt_failed" | "stream_completed" | "stream_failed" | "stream_cancelled";
+export type TelemetryEventType = "route_decided" | "attempt_succeeded" | "attempt_failed" | "stream_attempt_started" | "stream_attempt_succeeded" | "stream_attempt_failed" | "stream_completed" | "stream_failed" | "stream_cancelled";

package/src/host.ts

@@ -1,4 +1,9 @@
-import type { HttpRequest, HttpResponse, TelemetryEvent } from "./generated/index.js";
+import type {
+  HttpRequest,
+  HttpResponse,
+  MediaArtifact,
+  TelemetryEvent
+} from "./generated/index.js";
 
 /**
  * Service to inspect and monitor network connectivity status.
@@ -168,6 +173,25 @@ export interface TelemetryService {
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Resolves the opaque `delivery.destinationRef` of an artifact request to a place the
+ * application chose -- a file it will hand to a player, a cache it manages -- and writes the
+ * finished artifact there (ADR 017). A request names a reference, never a path, so a request
+ * that came from a webview cannot address arbitrary storage.
+ */
+export interface ArtifactDestinationService {
+  /**
+   * Whether `destinationRef` names a destination this host can write the requested media to.
+   * Called before routing; `false` refuses the request.
+   */
+  accepts(destinationRef: string, mediaTypes: readonly string[] | undefined): Promise<boolean>;
+  /**
+   * Writes the finished artifact's bytes to the destination. A failure fails the run: it is
+   * committed by then, so it never falls back.
+   */
+  write(destinationRef: string, artifact: MediaArtifact, bytes: Uint8Array): Promise<void>;
+}
+
 /**
  * Registry of platform-specific host services utilized by the Engine Core.
  * Evaluates execution capabilities and manages OS-level boundaries.
@@ -202,4 +226,9 @@ export interface HostServices {
    * Telemetry service to monitor execution steps, latency, and success rates.
    */
   telemetry?: TelemetryService;
+  /**
+   * Application destinations for artifact requests that carry `delivery.destinationRef`.
+   * Absent means the host has none, and such a request is refused before routing.
+   */
+  artifactDestinations?: ArtifactDestinationService;
 }

package/src/index.ts

@@ -12,21 +12,27 @@
  * themselves or the runtime validators.
  */
 
-/** The generated request/response, streaming, routing, and telemetry models. */
+/** The generated request/response, streaming, routing, provider-capability, and telemetry models. */
 export type * from "./generated/index.js";
 
 /** The JSON Schemas those models were generated from, for runtime use. */
 export {
+  artifactReadRequestSchema,
   executionProvenanceSchema,
   httpRequestSchema,
   httpResponseSchema,
   inderunErrorSchema,
+  mediaArtifactSchema,
   modelPackageSchema,
+  providerCapabilitySnapshotSchema,
+  providerDescriptorSchema,
+  providerDynamicCapabilitiesSchema,
   routePlanSchema,
   routePlannerInputSchema,
   streamEventSchema,
   streamRunSchema,
   streamTerminalOutcomeSchema,
+  taskOutputSchema,
   taskRequestSchema,
   taskResultSchema,
   telemetryEventSchema
@@ -37,16 +43,22 @@ export {
  * boolean type guard.
  */
 export {
+  getArtifactReadRequestValidationIssues,
   getExecutionProvenanceValidationIssues,
   getHttpRequestValidationIssues,
   getHttpResponseValidationIssues,
   getIndeRunErrorValidationIssues,
+  getMediaArtifactValidationIssues,
   getModelPackageValidationIssues,
+  getProviderCapabilitySnapshotValidationIssues,
+  getProviderDescriptorValidationIssues,
+  getProviderDynamicCapabilitiesValidationIssues,
   getRoutePlanValidationIssues,
   getRoutePlannerInputValidationIssues,
   getStreamEventValidationIssues,
   getStreamRunHandleValidationIssues,
   getStreamTerminalOutcomeValidationIssues,
+  getTaskOutputValidationIssues,
   getTaskRequestValidationIssues,
   getTaskResultValidationIssues,
   getTelemetryEventValidationIssues,
@@ -54,15 +66,21 @@ export {
   validateHttpRequest,
   validateHttpResponse,
   validateIndeRunError,
+  validateMediaArtifact,
   validateModelPackage,
+  validateProviderCapabilitySnapshot,
+  validateProviderDescriptor,
+  validateProviderDynamicCapabilities,
   validateRoutePlan,
   validateRoutePlannerInput,
   validateStreamEvent,
   validateStreamRunHandle,
   validateStreamTerminalOutcome,
+  validateTaskOutput,
   validateTaskRequest,
   validateTaskResult,
   validateTelemetryEvent,
+  validateArtifactReadRequest,
   type ValidationIssue
 } from "./validators.js";
 /**
@@ -70,14 +88,22 @@ export {
  * and the routing input/output shapes under the names the engines use.
  */
 export type {
+  CancelSemantics,
   FinishReason,
   IndeRunErrorClass,
+  ArtifactTaskOutput,
   ModelPackageFormat,
   ModelSourceType,
+  PlaybackTaskOutput,
+  ProviderTransport,
+  ProviderType,
   SchemaVersion,
   SharedRoutePlan,
   SharedRoutePlannerInput,
+  SpeechTaskRequest,
   TaskKind,
+  TextTaskOutput,
+  TextTaskRequest,
   RoutingConstraints,
   RoutingPreferences
 } from "./types.js";
@@ -89,6 +115,7 @@ export type {
  */
 export type {
   AbortSignalLike,
+  ArtifactDestinationService,
   ConnectivityService,
   ThermalState,
   DeviceConstraintsService,

package/src/types.ts

@@ -1,18 +1,23 @@
 import type {
   IndeRunError,
+  MediaArtifact,
   ModelPackage,
+  ProviderDescriptor,
   RoutePlan,
   RoutePlannerInput,
+  TaskOutput,
   TaskRequest,
   TaskResult
 } from "./generated/index.js";
+import type { PlaybackOutput } from "./generated/task-output.js";
+import type { OutputDeliveryRequest, SpeechInput } from "./generated/task-request.js";
 
 // Convenience aliases derived from the generated schema types, so consumers can
 // name individual fields without reaching into the generated index signatures.
 
 /** Contract schema version (e.g. `"1.0"`) carried by every task request. */
 export type SchemaVersion = TaskRequest["schemaVersion"];
-/** Supported task kinds (currently `"text_to_text"`). */
+/** Supported task kinds (`"text_to_text"`, `"text_to_speech"`). */
 export type TaskKind = TaskRequest["task"]["kind"];
 /** Normalized reason a task finished (e.g. `stop`, `length`, `error`). */
 export type FinishReason = TaskResult["finishReason"];
@@ -30,3 +35,35 @@ export type RoutingPreferences = NonNullable<TaskRequest["preferences"]>;
 export type ModelPackageFormat = ModelPackage["format"];
 /** How a model package's files are supplied to a provider (`registry`, `bundled`, ...). */
 export type ModelSourceType = NonNullable<ModelPackage["source"]>["sourceType"];
+/** Execution placement a provider declares (`local`, `edge`, `cloud`). */
+export type ProviderType = ProviderDescriptor["type"];
+/** Cancellation guarantee a provider declares (`hard`, `soft`, `none`). */
+export type CancelSemantics = ProviderDescriptor["cancel"];
+/** How the engine reaches a provider (`in_process`, `system_service`, `http`, ...). */
+export type ProviderTransport = ProviderDescriptor["transport"];
+
+// Per-task narrowings (ADR 016). Code generation cannot express the schema's per-kind
+// `if`/`then` requirements, so every task payload is optional on the generated types; these
+// aliases restate them for code that has already established the kind.
+
+/** A `text_to_text` request: `prompt` and/or `messages`, never a non-text payload. */
+export type TextTaskRequest = TaskRequest & {
+  task: { kind: "text_to_text" };
+  speech?: never;
+  delivery?: never;
+};
+/** A `text_to_speech` request: the `speech` payload and a playback or artifact delivery. */
+export type SpeechTaskRequest = TaskRequest & {
+  task: { kind: "text_to_speech" };
+  speech: SpeechInput;
+  delivery: OutputDeliveryRequest & { mode: "playback" | "artifact" };
+  prompt?: never;
+  messages?: never;
+  generation?: never;
+};
+/** Inline text output. */
+export type TextTaskOutput = TaskOutput & { type: "text"; text: string };
+/** Completion of managed playback; carries no media. */
+export type PlaybackTaskOutput = TaskOutput & { type: "playback"; playback: PlaybackOutput };
+/** A reference to retrievable media (ADR 017). */
+export type ArtifactTaskOutput = TaskOutput & { type: "artifact"; artifact: MediaArtifact };