@independo/inderun-contracts 0.3.0-dev.8 → 0.3.0

package/src/generated/stream-event.ts

@@ -0,0 +1,154 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * The canonical Mode 2 streaming event union, discriminated by 'type'. Every variant shares
+ * an envelope of schemaVersion, runId, sequence, timestamp, and type. 'sequence' is the
+ * ordering authority for events within a run (a monotonically increasing integer starting
+ * at 0 per runId) — consumers must order by 'sequence', not by arrival order, since a
+ * bridge hop (e.g. a future Capacitor bridge) could reorder delivery. Known event types are
+ * split into user-visible content ('content_delta', 'content_snapshot') and
+ * mechanical/diagnostic types ('lifecycle', 'diagnostic', 'terminal') so SDKs can
+ * distinguish what belongs in a chat UI from what is orchestration detail. Forward
+ * compatibility: this union closes with an open 'unknown_event' branch so a consumer built
+ * against an older revision of this schema does not hard-fail when a newer, additive minor
+ * revision introduces a new known type; per contracts/README.md's schema evolution policy,
+ * SDKs must treat an unrecognized 'type' as ignore-or-pass-through-for-diagnostics, never
+ * as a hard error. All three engines implement this union (see
+ * docs/architecture/architecture.md).
+ */
+export type StreamEvent = {
+    /**
+     * Event-specific diagnostic metadata. It must not contain prompt payloads or raw secrets,
+     * matching the same guardrail as TelemetryEvent.payload.
+     *
+     * Structurally identical to StreamTerminalOutcome
+     * (contracts/schemas/stream-terminal-outcome.schema.json), duplicated by value here rather
+     * than by $ref, matching this repo's schema convention of no cross-file references. Keep
+     * both shapes in sync; a cross-check test asserts a shared fixture validates against both
+     * schemas.
+     *
+     * Optional event-specific payload for the unrecognized type. It must not contain prompt
+     * payloads or raw secrets.
+     */
+    payload?: Payload;
+    /**
+     * Opaque run identifier this event belongs to, matching StreamRunHandle.runId.
+     */
+    runId: string;
+    /**
+     * Contract schema version used to interpret this event payload.
+     */
+    schemaVersion: "1.0";
+    /**
+     * Zero-based, monotonically increasing event index within this run. The ordering authority;
+     * do not rely on delivery/arrival order.
+     *
+     * Zero-based, monotonically increasing event index within this run. This is always the
+     * highest sequence number for the run: the terminal event.
+     */
+    sequence: number;
+    /**
+     * Wall-clock event timestamp in Unix epoch milliseconds.
+     */
+    timestamp: number;
+    /**
+     * User-visible content: an incremental text increment since the previous content_delta or
+     * content_snapshot event. Mirrors ProviderDescriptor.streamingStyle 'tokens'/'chunks'
+     * (packages/inderun-web/src/core/provider.ts) — providers reporting either style normalize
+     * to content_delta.
+     *
+     * User-visible content: the full cumulative text produced so far. Mirrors
+     * ProviderDescriptor.streamingStyle 'snapshots' (packages/inderun-web/src/core/provider.ts)
+     * — providers reporting that style normalize to content_snapshot rather than content_delta.
+     * Retraction: a provider of any streamingStyle may additionally emit a content_snapshot to
+     * withdraw content it has already delivered, since a snapshot replaces the run's cumulative
+     * text rather than appending to it; an empty one therefore resets that text to nothing.
+     * This is how a provider whose backend rejects an in-flight response after partial delivery
+     * — an on-device safety/policy check, for example — tells consumers to discard what they
+     * have, so a consumer must handle content_snapshot even when the provider's declared style
+     * is 'tokens' or 'chunks'.
+     *
+     * Mechanical/diagnostic: a run lifecycle transition (e.g. provider selection, execution
+     * start). Not user-visible content; not part of the generated text.
+     *
+     * Mechanical/diagnostic: free-form orchestration or provider diagnostic detail. Not
+     * user-visible content.
+     *
+     * Terminal: the last event of the run, carrying the mutually-exclusive
+     * completion/error/cancellation outcome. No further StreamEvent is delivered for this runId
+     * after this event.
+     *
+     * Forward-compatibility catch-all: any event type not among the known constants above.
+     * Exists so a consumer validating against this revision of the schema does not hard-fail
+     * when a future additive revision introduces a new known event type; SDKs must ignore or
+     * pass through such events for diagnostics rather than treating them as an error.
+     */
+    type: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Event-specific diagnostic metadata. It must not contain prompt payloads or raw secrets,
+ * matching the same guardrail as TelemetryEvent.payload.
+ *
+ * Optional event-specific payload for the unrecognized type. It must not contain prompt
+ * payloads or raw secrets.
+ */
+export type Payload = {
+    /**
+     * The incremental text produced since the previous content event.
+     *
+     * The full cumulative text produced by the run so far.
+     */
+    text?: string;
+    /**
+     * The lifecycle phase reached.
+     */
+    phase?:         Phase;
+    finalText?:     string;
+    finishReason?:  FinishReason;
+    outcome?:       Outcome;
+    runId?:         string;
+    schemaVersion?: "1.0";
+    telemetry?:     Telemetry;
+    usage?:         Usage;
+    error?:         Error;
+    partialText?:   string;
+    reason?:        string;
+    [property: string]: unknown;
+}
+
+export type Error = {
+    details?:      { [key: string]: unknown };
+    errorClass:    ErrorClass;
+    message:       string;
+    providerId?:   string;
+    retryable?:    boolean;
+    retryAfterMs?: number;
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+}
+
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+
+export type FinishReason = "stop" | "length" | "cancelled" | "error";
+
+export type Outcome = "completed" | "error" | "cancelled";
+
+/**
+ * The lifecycle phase reached.
+ */
+export type Phase = "provider_selected" | "started";
+
+export type Telemetry = {
+    providerUsed: string;
+    totalMs:      number;
+    [property: string]: unknown;
+}
+
+export type Usage = {
+    inputTokens?:  number;
+    outputTokens?: number;
+    totalTokens?:  number;
+    [property: string]: unknown;
+}

package/src/generated/stream-run.ts

@@ -0,0 +1,32 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * The serializable acknowledgment returned when a Mode 2 stream is opened, before any
+ * StreamEvent has arrived. This is the identity/correlation contract only: the live,
+ * consumable stream itself is a platform-idiomatic construct (an AsyncIterable<StreamEvent>
+ * in TypeScript, a Flow<StreamEvent> in Kotlin, an AsyncThrowingStream<StreamEvent, Error>
+ * in Swift) that is never serialized and is out of scope for this schema. Design seam only;
+ * no engine or provider implementation exists yet (see docs/architecture/architecture.md).
+ */
+export type StreamRunHandle = {
+    /**
+     * Identifier of the provider selected to service this stream, if routing has completed by
+     * the time the handle is returned. Absent while route selection is still pending.
+     */
+    providerId?: string;
+    /**
+     * A unique, opaque identifier assigned by the engine for this stream run. Every StreamEvent
+     * and the terminal StreamTerminalOutcome for this run carry the same runId, matching the
+     * identity convention used by TaskResult.runId and IndeRunError.runId.
+     */
+    runId: string;
+    /**
+     * Contract schema version used to interpret this handle payload.
+     */
+    schemaVersion: "1.0";
+    /**
+     * Wall-clock time the stream run was opened, in Unix epoch milliseconds.
+     */
+    startedAt: number;
+    [property: string]: unknown;
+}

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

@@ -0,0 +1,186 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * 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.
+ */
+export type StreamTerminalOutcome = {
+    /**
+     * The full, cumulative text produced by the run. Equivalent in role to
+     * TaskResult.output.text for Mode 1.
+     */
+    finalText?: string;
+    /**
+     * How generation ended, mirroring TaskResult.finishReason for Mode 1: 'stop' (natural end),
+     * 'length' (hit maxOutputTokens), 'error' (provider reported a non-fatal issue on an
+     * otherwise completed run). 'cancelled' is included so this enum stays identical to
+     * TaskResult.finishReason, but it is unreachable here: cancellation is its own terminal
+     * outcome branch. Optional: providers that do not report a finish reason omit it.
+     */
+    finishReason?: FinishReason;
+    /**
+     * The stream completed normally: every provider-generated event was delivered before this
+     * outcome was produced.
+     *
+     * The stream ended in failure: validation, routing (no eligible provider), or every
+     * attempted provider failing.
+     *
+     * The stream was cancelled. No further StreamEvent is delivered after this outcome, and no
+     * further fallback attempt is made, per the engine's cancellation guarantee.
+     */
+    outcome: Outcome;
+    /**
+     * The stream run this outcome terminates, matching StreamRunHandle.runId and every
+     * StreamEvent.runId for the run.
+     */
+    runId: string;
+    /**
+     * Contract schema version used to interpret this outcome payload.
+     */
+    schemaVersion: "1.0";
+    /**
+     * Required metadata providing an overview of the execution result and performance metrics.
+     * Same shape as TaskResult.telemetry.
+     */
+    telemetry?: Telemetry;
+    /**
+     * Optional metadata regarding the quantity of tokens processed by the provider. Same shape
+     * as TaskResult.usage.
+     */
+    usage?: Usage;
+    /**
+     * The normalized error for this failure. Structurally identical to IndeRunError
+     * (contracts/schemas/inderun-error.schema.json), duplicated by value here rather than by
+     * $ref, matching this repo's schema convention of no cross-file references. Keep both
+     * shapes in sync; a cross-check test asserts a shared fixture validates against both
+     * schemas.
+     */
+    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.
+     */
+    partialText?: string;
+    /**
+     * Optional human-readable reason the run was cancelled (e.g. caller-initiated abort). Not a
+     * machine-taxonomy field; use errorClass on the 'error' outcome branch for failure
+     * classification.
+     */
+    reason?: string;
+    [property: string]: unknown;
+}
+
+/**
+ * The normalized error for this failure. Structurally identical to IndeRunError
+ * (contracts/schemas/inderun-error.schema.json), duplicated by value here rather than by
+ * $ref, matching this repo's schema convention of no cross-file references. Keep both
+ * shapes in sync; a cross-check test asserts a shared fixture validates against both
+ * schemas.
+ */
+export type Error = {
+    /**
+     * Optional structured diagnostic details. It must not contain raw secrets.
+     */
+    details?: { [key: string]: unknown };
+    /**
+     * Normalized error taxonomy, identical to IndeRunError.errorClass: CapabilityMismatch
+     * (request needs something no eligible provider supports), Offline/Unavailable (provider
+     * unreachable or not ready), AuthError (credential/auth failure), RateLimited (provider
+     * throttled the request), Timeout (provider exceeded its execution budget), Internal
+     * (unexpected engine-side failure).
+     */
+    errorClass: ErrorClass;
+    /**
+     * Human-readable error message suitable for logs and developer diagnostics.
+     */
+    message: string;
+    /**
+     * Identifier of the provider associated with the failure, if execution reached a provider.
+     */
+    providerId?: string;
+    /**
+     * Whether retrying the same request may succeed.
+     */
+    retryable?: boolean;
+    /**
+     * Optional suggested delay before retrying, in milliseconds.
+     */
+    retryAfterMs?: number;
+    /**
+     * Contract schema version used to interpret the error payload.
+     */
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+}
+
+/**
+ * Normalized error taxonomy, identical to IndeRunError.errorClass: CapabilityMismatch
+ * (request needs something no eligible provider supports), Offline/Unavailable (provider
+ * unreachable or not ready), AuthError (credential/auth failure), RateLimited (provider
+ * throttled the request), Timeout (provider exceeded its execution budget), Internal
+ * (unexpected engine-side failure).
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+
+/**
+ * How generation ended, mirroring TaskResult.finishReason for Mode 1: 'stop' (natural end),
+ * 'length' (hit maxOutputTokens), 'error' (provider reported a non-fatal issue on an
+ * otherwise completed run). 'cancelled' is included so this enum stays identical to
+ * TaskResult.finishReason, but it is unreachable here: cancellation is its own terminal
+ * outcome branch. Optional: providers that do not report a finish reason omit it.
+ */
+export type FinishReason = "stop" | "length" | "cancelled" | "error";
+
+export type Outcome = "completed" | "error" | "cancelled";
+
+/**
+ * Required metadata providing an overview of the execution result and performance metrics.
+ * Same shape as TaskResult.telemetry.
+ */
+export type Telemetry = {
+    /**
+     * The identifier for the specific provider that handled the request (e.g.,
+     * 'openai_compatible_cloud').
+     */
+    providerUsed: string;
+    /**
+     * Measured execution duration in milliseconds, including route selection and result
+     * processing.
+     */
+    totalMs: number;
+    [property: string]: unknown;
+}
+
+/**
+ * Optional metadata regarding the quantity of tokens processed by the provider. Same shape
+ * as TaskResult.usage.
+ */
+export type Usage = {
+    /**
+     * Number of input tokens consumed, as reported by the provider.
+     */
+    inputTokens?: number;
+    /**
+     * Number of output tokens generated, as reported by the provider.
+     */
+    outputTokens?: number;
+    /**
+     * Aggregated token count for this request, as reported by the provider.
+     */
+    totalTokens?: number;
+    [property: string]: unknown;
+}

package/src/generated/task-request.ts

@@ -0,0 +1,183 @@
+/* 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;
+ * `constraints`/`preferences` steer routing but never select a provider directly.
+ */
+export type TaskRequest = {
+    /**
+     * A unique identifier used to retrieve credentials from a secure local storage. Raw
+     * sensitive keys (API keys, etc.) should NEVER be placed directly in the request payload.
+     */
+    authContextRef?: string;
+    /**
+     * Request-level routing constraints used by the planner.
+     */
+    constraints?: Constraints;
+    /**
+     * Optional configuration for fine-tuning how the AI model generates its response.
+     */
+    generation?: Generation;
+    /**
+     * A list of interaction messages for multi-turn conversation or chat-style execution.
+     */
+    messages?: [Message, ...Message[]];
+    /**
+     * Soft routing preferences used for deterministic provider ordering.
+     */
+    preferences?: Preferences;
+    /**
+     * A simple, single-turn text prompt used to trigger a response from the AI model.
+     */
+    prompt?: string;
+    /**
+     * Optional identifier for tracking or correlating this specific execution attempt.
+     */
+    requestId?: string;
+    /**
+     * Contract schema version used to interpret the request payload.
+     */
+    schemaVersion: "1.0";
+    /**
+     * A descriptor specifying the type of work to be performed. For text-to-text, the kind must
+     * be 'text_to_text'.
+     */
+    task: Task;
+    /**
+     * Execution preferences for tracking usage and performance metrics.
+     */
+    telemetry?: Telemetry;
+    [property: string]: unknown;
+}
+
+/**
+ * Request-level routing constraints used by the planner.
+ */
+export type Constraints = {
+    /**
+     * Cloud execution constraint.
+     */
+    cloud?: Cloud;
+    /**
+     * Privacy requirement or preference for execution placement.
+     */
+    privacy?: Privacy;
+    /**
+     * Optional routing timeout budget in milliseconds.
+     */
+    timeoutMs?: number;
+    [property: string]: unknown;
+}
+
+/**
+ * Cloud execution constraint.
+ */
+export type Cloud = "forbidden" | "allowed" | "required";
+
+/**
+ * Privacy requirement or preference for execution placement.
+ */
+export type Privacy = "local_required" | "local_preferred" | "cloud_allowed" | "cloud_required";
+
+/**
+ * Optional configuration for fine-tuning how the AI model generates its response.
+ */
+export type Generation = {
+    /**
+     * The maximum number of tokens to generate in a single response.
+     */
+    maxOutputTokens?: number;
+    /**
+     * A fixed seed for deterministic generation (where supported by the underlying provider).
+     */
+    seed?: number;
+    /**
+     * Sequence tokens that should terminate the generation process.
+     */
+    stop?: string[];
+    /**
+     * Controls the randomness of the output. Range: 0 (most deterministic) to 2 (highest
+     * variance).
+     */
+    temperature?: number;
+    /**
+     * Nucleus sampling parameter for controlling diversity vs focus in the output.
+     */
+    topP?: number;
+    [property: string]: unknown;
+}
+
+/**
+ * An individual message in a conversation.
+ */
+export type Message = {
+    /**
+     * The actual text content of the message.
+     */
+    content: string;
+    /**
+     * The role of the author (e.g., 'user', 'assistant').
+     */
+    role: Role;
+    [property: string]: unknown;
+}
+
+/**
+ * The role of the author (e.g., 'user', 'assistant').
+ */
+export type Role = "system" | "user" | "assistant";
+
+/**
+ * Soft routing preferences used for deterministic provider ordering.
+ */
+export type Preferences = {
+    /**
+     * Primary optimization goal when multiple providers remain eligible.
+     */
+    optimizeFor?: OptimizeFor;
+    [property: string]: unknown;
+}
+
+/**
+ * Primary optimization goal when multiple providers remain eligible.
+ */
+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'.
+ */
+export type Task = {
+    /**
+     * The standard task category. Currently supports 'text_to_text' for prompt-based
+     * interactions.
+     */
+    kind: "text_to_text";
+    [property: string]: unknown;
+}
+
+/**
+ * Execution preferences for tracking usage and performance metrics.
+ */
+export type Telemetry = {
+    /**
+     * Whether the user consents to telemetry collection for this specific request.
+     */
+    consent?: boolean;
+    /**
+     * The granularity of the collected metrics (off, minimal, or debug).
+     */
+    level?: Level;
+    /**
+     * Optional key-value pairs for correlating telemetry data with specific features or users.
+     */
+    tags?: { [key: string]: string };
+    [property: string]: unknown;
+}
+
+/**
+ * The granularity of the collected metrics (off, minimal, or debug).
+ */
+export type Level = "off" | "minimal" | "debug";

package/src/generated/task-result.ts

@@ -0,0 +1,114 @@
+/* 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).
+ */
+export type TaskResult = {
+    /**
+     * How generation ended: 'stop' (natural end), 'length' (hit maxOutputTokens), or
+     * 'cancelled'. 'error' is reserved for a provider reporting a non-fatal issue on an
+     * otherwise-returned result — the Android ML Kit GenAI provider produces it when Gemini
+     * Nano reports a finish reason that is neither a natural stop nor the token limit. A full
+     * execution failure is instead surfaced by run() throwing an IndeRunError.
+     */
+    finishReason: FinishReason;
+    /**
+     * The normalized content returned from the selected provider.
+     */
+    output: Output;
+    /**
+     * A unique, opaque identifier assigned by the engine for this specific execution attempt.
+     */
+    runId: string;
+    /**
+     * Contract schema version used to interpret the result payload.
+     */
+    schemaVersion: "1.0";
+    /**
+     * Required metadata providing an overview of the execution result and performance metrics.
+     */
+    telemetry: Telemetry;
+    /**
+     * Optional metadata regarding the quantity of tokens processed by the provider.
+     */
+    usage?: Usage;
+    [property: string]: unknown;
+}
+
+/**
+ * How generation ended: 'stop' (natural end), 'length' (hit maxOutputTokens), or
+ * 'cancelled'. 'error' is reserved for a provider reporting a non-fatal issue on an
+ * otherwise-returned result — the Android ML Kit GenAI provider produces it when Gemini
+ * Nano reports a finish reason that is neither a natural stop nor the token limit. A full
+ * execution failure is instead surfaced by run() throwing an IndeRunError.
+ */
+export type FinishReason = "stop" | "length" | "cancelled" | "error";
+
+/**
+ * The normalized content returned from the selected provider.
+ */
+export type Output = {
+    /**
+     * The actual text generated by the execution.
+     */
+    text: string;
+    /**
+     * Output payload category (e.g., 'text' for Mode 1 text-to-text).
+     */
+    type: "text";
+    [property: string]: unknown;
+}
+
+/**
+ * Required metadata providing an overview of the execution result and performance metrics.
+ */
+export type Telemetry = {
+    /**
+     * Present only if a provider reports a degraded outcome on an otherwise-successful result;
+     * no provider in this codebase currently sets this. Distinct from run() throwing — a thrown
+     * IndeRunError never produces a TaskResult at all.
+     */
+    errorClass?: ErrorClass;
+    /**
+     * The identifier for the specific provider that handled the request (e.g.,
+     * 'openai_compatible_cloud').
+     */
+    providerUsed: string;
+    /**
+     * Measured execution duration in milliseconds, including route selection and result
+     * processing.
+     */
+    totalMs: number;
+    [property: string]: unknown;
+}
+
+/**
+ * Present only if a provider reports a degraded outcome on an otherwise-successful result;
+ * no provider in this codebase currently sets this. Distinct from run() throwing — a thrown
+ * IndeRunError never produces a TaskResult at all.
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+
+/**
+ * Optional metadata regarding the quantity of tokens processed by the provider.
+ */
+export type Usage = {
+    /**
+     * Number of input tokens consumed, as reported by the provider.
+     */
+    inputTokens?: number;
+    /**
+     * Number of output tokens generated, as reported by the provider.
+     */
+    outputTokens?: number;
+    /**
+     * Aggregated token count for this request, as reported by the provider.
+     */
+    totalTokens?: number;
+    [property: string]: unknown;
+}