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

package/src/generated/stream-event.ts

@@ -108,6 +108,7 @@ export type Payload = {
     finalText?:    string;
     finishReason?: FinishReason;
     outcome?:      Outcome;
+    output?:       TaskOutput;
     /**
      * Normalized execution provenance: which target ran, its declared locality, the configured
      * and reported model, and how fallback and routing played out. See
@@ -212,6 +213,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.
      */
@@ -244,12 +252,148 @@ 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";
 
 export type FinishReason = "stop" | "length" | "cancelled" | "error";
 
 export type Outcome = "completed" | "error" | "cancelled";
 
+/**
+ * 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 ArtifactOwner = "engine" | "application";
+
+/**
+ * Completion of managed playback. Required when type is 'playback'. Carries no media.
+ */
+export type PlaybackOutput = {
+    /**
+     * How long audible playback lasted, in milliseconds. For a cancelled run, how long it
+     * played before it was stopped.
+     */
+    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 = {
+    /**
+     * BCP 47 tag of the locale that was spoken.
+     */
+    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";
+
 /**
  * The lifecycle phase reached.
  */

package/src/generated/stream-terminal-outcome.ts

@@ -4,23 +4,25 @@
  * How a Mode 2 stream run ended. Completion, error, and cancellation are mutually exclusive
  * terminal outcomes, enforced here as a closed set of three oneOf branches discriminated by
  * 'outcome' (unlike StreamEvent.type, this set is not open-ended: the three-way terminal
- * outcome is a fixed architectural guarantee, not something new outcome kinds get added
- * to). Exactly one StreamTerminalOutcome is produced per run, and no further StreamEvent is
- * delivered after it (see docs/architecture/architecture.md, 'Cancellation And Fallback').
- * This shape is also embedded by value as the payload of the terminal StreamEvent
- * (stream-event.schema.json) so it can additionally be exposed standalone, e.g. as a
- * completion future/promise a stream handle resolves independently of consuming the full
- * event sequence; the two copies must stay structurally identical. Note on
- * additionalProperties: per this repo's forward-compatible convention every branch permits
- * unknown extra fields, so mutual exclusivity is enforced via the required 'outcome'
- * discriminator plus each branch's own required peer field (finalText/error/partialText)
- * being present, not by forbidding a payload from also carrying an unrelated stray field
- * from another branch's vocabulary.
+ * outcome is a fixed architectural guarantee, not something new outcome kinds get added to;
+ * the payload of each branch may grow additively). Exactly one StreamTerminalOutcome is
+ * produced per run, and no further StreamEvent is delivered after it (see
+ * docs/architecture/architecture.md, 'Cancellation And Fallback'). This shape is also
+ * embedded by value as the payload of the terminal StreamEvent (stream-event.schema.json)
+ * so it can additionally be exposed standalone, e.g. as a completion future/promise a
+ * stream handle resolves independently of consuming the full event sequence; the two copies
+ * must stay structurally identical. Note on additionalProperties: per this repo's
+ * forward-compatible convention every branch permits unknown extra fields, so mutual
+ * exclusivity is enforced via the required 'outcome' discriminator plus each branch's own
+ * required peer field being present (finalText or output / error), and for 'cancelled' by
+ * the discriminator alone, not by forbidding a payload from also carrying an unrelated
+ * stray field from another branch's vocabulary.
  */
 export type StreamTerminalOutcome = {
     /**
-     * The full, cumulative text produced by the run. Equivalent in role to
-     * TaskResult.output.text for Mode 1.
+     * The full, cumulative text produced by a text run. Equivalent in role to
+     * TaskResult.output.text for Mode 1. A text run sets it; a non-text run carries output
+     * instead.
      */
     finalText?: string;
     /**
@@ -42,6 +44,19 @@ export type StreamTerminalOutcome = {
      * further fallback attempt is made, per the engine's cancellation guarantee.
      */
     outcome: Outcome;
+    /**
+     * The normalized output of the run, the same shape run() returns in TaskResult.output. Set
+     * for every non-text run; a text run may set it alongside finalText. See
+     * task-output.schema.json.
+     *
+     * What a cancelled non-text run had already produced: a playback run that committed (audio
+     * may have been heard) carries a playback output, and an artifact run cancelled while the
+     * engine was writing its artifact to an application destination carries that
+     * application-owned artifact, whose bytes the write left at the destination. Absent when
+     * nothing was produced, e.g. an artifact run cancelled before its artifact was handed over,
+     * whose partial media the engine discards. See task-output.schema.json.
+     */
+    output?: TaskOutput;
     /**
      * Normalized execution provenance: which target ran, its declared locality, the configured
      * and reported model, and how fallback and routing played out. See
@@ -76,9 +91,13 @@ export type StreamTerminalOutcome = {
      */
     error?: Error;
     /**
-     * Whatever cumulative text had already been delivered via content_delta/content_snapshot
-     * StreamEvents before the cancellation point. May be empty if cancellation occurred before
-     * any content was produced.
+     * Whatever cumulative text a text run had already delivered before it failed after
+     * committing to its provider. Absent when nothing was delivered.
+     *
+     * Whatever cumulative text a text run had already delivered via
+     * content_delta/content_snapshot StreamEvents before the cancellation point. Always set for
+     * a text run, and empty if cancellation occurred before any content was produced. A
+     * non-text run never sets it.
      */
     partialText?: string;
     /**
@@ -216,6 +235,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.
      */
@@ -248,7 +274,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";
 
 /**
  * How generation ended, mirroring TaskResult.finishReason for Mode 1: 'stop' (natural end),
@@ -261,6 +287,153 @@ export type FinishReason = "stop" | "length" | "cancelled" | "error";
 
 export type Outcome = "completed" | "error" | "cancelled";
 
+/**
+ * The normalized output of the run, the same shape run() returns in TaskResult.output. Set
+ * for every non-text run; a text run may set it alongside finalText. 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.
+ *
+ * What a cancelled non-text run had already produced: a playback run that committed (audio
+ * may have been heard) carries a playback output, and an artifact run cancelled while the
+ * engine was writing its artifact to an application destination carries that
+ * application-owned artifact, whose bytes the write left at the destination. Absent when
+ * nothing was produced, e.g. an artifact run cancelled before its artifact was handed over,
+ * whose partial media the engine discards. See task-output.schema.json.
+ */
+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 ArtifactOwner = "engine" | "application";
+
+/**
+ * Completion of managed playback. Required when type is 'playback'. Carries no media.
+ */
+export type PlaybackOutput = {
+    /**
+     * How long audible playback lasted, in milliseconds. For a cancelled run, how long it
+     * played before it was stopped.
+     */
+    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 = {
+    /**
+     * BCP 47 tag of the locale that was spoken.
+     */
+    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";
+
 /**
  * Required metadata providing an overview of the execution result and performance metrics.
  * Same shape as TaskResult.telemetry.

package/src/generated/task-output.ts

@@ -0,0 +1,137 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * 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 ArtifactOwner = "engine" | "application";
+
+/**
+ * Completion of managed playback. Required when type is 'playback'. Carries no media.
+ */
+export type PlaybackOutput = {
+    /**
+     * How long audible playback lasted, in milliseconds. For a cancelled run, how long it
+     * played before it was stopped.
+     */
+    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 = {
+    /**
+     * BCP 47 tag of the locale that was spoken.
+     */
+    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";