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

package/src/generated/telemetry-event.ts

@@ -0,0 +1,29 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Normalized telemetry event emitted by the orchestrator and providers.
+ */
+export type TelemetryEvent = {
+    /**
+     * Event-specific metadata. It must not contain prompt payloads or raw secrets.
+     */
+    payload: { [key: string]: unknown };
+    /**
+     * Opaque run identifier associated with this execution event.
+     */
+    runId: string;
+    /**
+     * Wall-clock event timestamp in Unix epoch milliseconds.
+     */
+    timestamp: number;
+    /**
+     * Telemetry event kind emitted by the orchestrator or provider integration.
+     */
+    type: Type;
+    [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";

package/src/host.ts

@@ -0,0 +1,205 @@
+import type { HttpRequest, HttpResponse, TelemetryEvent } from "./generated/index.js";
+
+/**
+ * Service to inspect and monitor network connectivity status.
+ */
+export interface ConnectivityService {
+  /**
+   * Resolves to true if the host is connected to the network, false otherwise.
+   */
+  isOnline(): Promise<boolean>;
+}
+
+/**
+ * Operating system thermal states denoting system heat and throttling risk.
+ */
+export type ThermalState = "nominal" | "fair" | "serious" | "critical";
+
+/**
+ * Service to inspect host device battery, power, and thermal constraints.
+ */
+export interface DeviceConstraintsService {
+  /**
+   * Retrieves the current thermal state of the device, if supported.
+   */
+  getThermalState?(): Promise<ThermalState>;
+  /**
+   * Checks if the host device has low power mode enabled, if supported.
+   */
+  isLowPowerModeEnabled?(): Promise<boolean>;
+}
+
+/**
+ * Secure storage interface to store and retrieve sensitive credentials/tokens
+ * without exposing them to request payloads.
+ */
+export interface SecureStorageService {
+  /**
+   * Gets a secret by its unique slot identifier.
+   */
+  getSecret(slotId: string): Promise<string | null>;
+  /**
+   * Securely saves a secret under a unique slot identifier.
+   */
+  setSecret(slotId: string, secret: string): Promise<void>;
+  /**
+   * Deletes a secret by its slot identifier.
+   */
+  deleteSecret(slotId: string): Promise<void>;
+}
+
+/**
+ * Service providing clocks for request timeouts and execution timing telemetry.
+ */
+export interface ClockService {
+  /**
+   * Returns current UNIX timestamp in milliseconds.
+   */
+  now(): number;
+  /**
+   * Returns monotonic high-resolution time in milliseconds.
+   */
+  monotonicNow?(): number;
+}
+
+export type { HttpRequest, HttpResponse, TelemetryEvent } from "./generated/index.js";
+
+/**
+ * HttpClient service for cloud provider communication.
+ */
+export interface HttpClientService {
+  /**
+   * Dispatches a normalized HTTP request and returns the normalized response.
+   * @param request - Configuration options for the HTTP request.
+   */
+  send(request: HttpRequest): Promise<HttpResponse>;
+}
+
+/**
+ * The structural subset of the standard `AbortSignal` that IndeRun relies on.
+ *
+ * The contracts package targets a platform-neutral library surface and so has
+ * no DOM lib; a real `AbortSignal` satisfies this shape, so host implementations
+ * and callers can pass one directly.
+ */
+export interface AbortSignalLike {
+  /**
+   * Whether cancellation has already been requested.
+   */
+  readonly aborted: boolean;
+  /**
+   * Registers a cancellation listener.
+   */
+  addEventListener(type: "abort", listener: () => void, options?: { once?: boolean }): void;
+  /**
+   * Removes a previously registered cancellation listener.
+   */
+  removeEventListener(type: "abort", listener: () => void): void;
+}
+
+/**
+ * A streamed HTTP response: the status line and headers are resolved first, and
+ * the body is delivered incrementally as raw byte chunks.
+ *
+ * The head is deliberately separated from the body so a caller can classify a
+ * non-2xx response (mapping it through the normal HTTP error taxonomy) before
+ * deciding to interpret the body as a protocol stream. Chunk boundaries are
+ * transport artifacts and carry no meaning: a chunk may split a protocol frame
+ * or even a multi-byte UTF-8 sequence, so consumers must buffer and decode
+ * incrementally rather than treating a chunk as a unit.
+ */
+export interface HttpStreamResponse {
+  /**
+   * HTTP status code.
+   */
+  status: number;
+  /**
+   * HTTP status text.
+   */
+  statusText: string;
+  /**
+   * Response headers, with lower-cased names.
+   */
+  headers: Record<string, string>;
+  /**
+   * The response body as an incremental sequence of raw byte chunks. Iterating
+   * it to completion, or abandoning it, releases the underlying connection.
+   */
+  body: AsyncIterable<Uint8Array>;
+}
+
+/**
+ * Optional host capability for HTTP responses that must be consumed while they
+ * are still arriving — the transport requirement behind Mode 2 streaming over
+ * the network (for example server-sent events).
+ *
+ * It is a separate service rather than a method on {@link HttpClientService}
+ * because it is genuinely optional: a host that cannot stream simply omits it,
+ * and providers report that as `streamingAvailable: false` in their dynamic
+ * capabilities, which the route planner turns into an inspectable
+ * `streaming_unavailable` rejection.
+ */
+export interface HttpStreamingClientService {
+  /**
+   * Dispatches a normalized HTTP request and resolves once the response head is
+   * available, leaving the body to be consumed incrementally.
+   *
+   * `HttpRequest.timeoutMs` bounds the wait for the response head only — the
+   * time to first byte. It cannot bound total duration, since a stream is
+   * open-ended by nature; use `signal` to stop a stream that runs too long.
+   *
+   * @param request - Normalized HTTP request payload.
+   * @param signal - Optional caller-driven cancellation. Aborting it must tear
+   * down the underlying connection and cause the body iterator to stop.
+   */
+  stream(request: HttpRequest, signal?: AbortSignalLike): Promise<HttpStreamResponse>;
+}
+
+export type TelemetryEventType = TelemetryEvent["type"];
+
+/**
+ * Telemetry service listener hook interface.
+ */
+export interface TelemetryService {
+  /**
+   * Emits a telemetry event.
+   * @param event - The generated telemetry event.
+   */
+  emit(event: TelemetryEvent): void;
+}
+
+/**
+ * Registry of platform-specific host services utilized by the Engine Core.
+ * Evaluates execution capabilities and manages OS-level boundaries.
+ */
+export interface HostServices {
+  /**
+   * Network connectivity service.
+   */
+  connectivity: ConnectivityService;
+  /**
+   * Device constraints service.
+   */
+  deviceConstraints?: DeviceConstraintsService;
+  /**
+   * Secure storage service.
+   */
+  secureStorage?: SecureStorageService;
+  /**
+   * Clock service.
+   */
+  clock?: ClockService;
+  /**
+   * HTTP Client service for performing network requests.
+   */
+  httpClient?: HttpClientService;
+  /**
+   * HTTP client service for responses consumed while still arriving. Absent on
+   * hosts that cannot stream a response body.
+   */
+  streamingHttpClient?: HttpStreamingClientService;
+  /**
+   * Telemetry service to monitor execution steps, latency, and success rates.
+   */
+  telemetry?: TelemetryService;
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+/**
+ * Canonical IndeRun contracts for TypeScript (`@independo/inderun-contracts`).
+ *
+ * Everything here derives from the JSON Schemas in `contracts/schemas/`, which are
+ * the single source of truth across all four languages — the TypeScript types
+ * below, the Kotlin and Swift contract models, and the Rust route-core model are
+ * all generated from them by `pnpm generate`. Do not hand-edit anything under
+ * `src/generated/`; change the schema and regenerate.
+ *
+ * Apps normally do not depend on this package directly: the SDKs re-export the
+ * contract types their own signatures use. Reach for it when you need the schemas
+ * themselves or the runtime validators.
+ */
+
+/** The generated request/response, streaming, routing, and telemetry models. */
+export type * from "./generated/index.js";
+
+/** The JSON Schemas those models were generated from, for runtime use. */
+export {
+  httpRequestSchema,
+  httpResponseSchema,
+  inderunErrorSchema,
+  modelPackageSchema,
+  routePlanSchema,
+  routePlannerInputSchema,
+  streamEventSchema,
+  streamRunSchema,
+  streamTerminalOutcomeSchema,
+  taskRequestSchema,
+  taskResultSchema,
+  telemetryEventSchema
+} from "./generated/index.js";
+/**
+ * Ajv-backed validators for each contract. The `get*ValidationIssues` form returns
+ * a list of human-readable issues (empty when valid); the `validate*` form is the
+ * boolean type guard.
+ */
+export {
+  getHttpRequestValidationIssues,
+  getHttpResponseValidationIssues,
+  getIndeRunErrorValidationIssues,
+  getModelPackageValidationIssues,
+  getRoutePlanValidationIssues,
+  getRoutePlannerInputValidationIssues,
+  getStreamEventValidationIssues,
+  getStreamRunHandleValidationIssues,
+  getStreamTerminalOutcomeValidationIssues,
+  getTaskRequestValidationIssues,
+  getTaskResultValidationIssues,
+  getTelemetryEventValidationIssues,
+  validateHttpRequest,
+  validateHttpResponse,
+  validateIndeRunError,
+  validateModelPackage,
+  validateRoutePlan,
+  validateRoutePlannerInput,
+  validateStreamEvent,
+  validateStreamRunHandle,
+  validateStreamTerminalOutcome,
+  validateTaskRequest,
+  validateTaskResult,
+  validateTelemetryEvent,
+  type ValidationIssue
+} from "./validators.js";
+/**
+ * Narrowed aliases over the generated models: the closed enums the SDKs switch on,
+ * and the routing input/output shapes under the names the engines use.
+ */
+export type {
+  FinishReason,
+  IndeRunErrorClass,
+  ModelPackageFormat,
+  ModelSourceType,
+  SchemaVersion,
+  SharedRoutePlan,
+  SharedRoutePlannerInput,
+  TaskKind,
+  RoutingConstraints,
+  RoutingPreferences
+} from "./types.js";
+
+/**
+ * The host-services contract: the platform capabilities an SDK reads and calls
+ * through. Defined here rather than per-SDK so the three platforms expose the
+ * same seams.
+ */
+export type {
+  AbortSignalLike,
+  ConnectivityService,
+  ThermalState,
+  DeviceConstraintsService,
+  SecureStorageService,
+  ClockService,
+  HttpClientService,
+  HttpStreamResponse,
+  HttpStreamingClientService,
+  TelemetryEventType,
+  TelemetryService,
+  HostServices
+} from "./host.js";

package/src/types.ts

@@ -0,0 +1,32 @@
+import type {
+  IndeRunError,
+  ModelPackage,
+  RoutePlan,
+  RoutePlannerInput,
+  TaskRequest,
+  TaskResult
+} from "./generated/index.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"`). */
+export type TaskKind = TaskRequest["task"]["kind"];
+/** Normalized reason a task finished (e.g. `stop`, `length`, `error`). */
+export type FinishReason = TaskResult["finishReason"];
+/** The shared error taxonomy value carried on `IndeRunError`. */
+export type IndeRunErrorClass = IndeRunError["errorClass"];
+/** Input schema consumed by the shared (Rust/WASM) route planner. */
+export type SharedRoutePlannerInput = RoutePlannerInput;
+/** Route plan produced by the shared route planner. */
+export type SharedRoutePlan = RoutePlan;
+/** Routing constraints (cloud/privacy/timeout) from a task request. */
+export type RoutingConstraints = NonNullable<TaskRequest["constraints"]>;
+/** Routing preferences (e.g. `optimizeFor`) from a task request. */
+export type RoutingPreferences = NonNullable<TaskRequest["preferences"]>;
+/** Serialization format of a model package (`onnx`, `ort`, `genai`). */
+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"];

package/src/validators.ts

@@ -0,0 +1,288 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import type { ErrorObject, ValidateFunction } from "ajv";
+
+import type { IndeRunError } from "./generated/inderun-error.js";
+import type { HttpRequest } from "./generated/http-request.js";
+import type { HttpResponse } from "./generated/http-response.js";
+import type { ModelPackage } from "./generated/model-package.js";
+import type { RoutePlan } from "./generated/route-plan.js";
+import type { RoutePlannerInput } from "./generated/route-planner-input.js";
+import {
+  httpRequestSchema,
+  httpResponseSchema,
+  inderunErrorSchema,
+  modelPackageSchema,
+  routePlanSchema,
+  routePlannerInputSchema,
+  streamEventSchema,
+  streamRunSchema,
+  streamTerminalOutcomeSchema,
+  taskRequestSchema,
+  taskResultSchema,
+  telemetryEventSchema
+} from "./generated/index.js";
+import type { StreamEvent } from "./generated/stream-event.js";
+import type { StreamRunHandle } from "./generated/stream-run.js";
+import type { StreamTerminalOutcome } from "./generated/stream-terminal-outcome.js";
+import type { TaskRequest } from "./generated/task-request.js";
+import type { TaskResult } from "./generated/task-result.js";
+import type { TelemetryEvent } from "./generated/telemetry-event.js";
+
+type Ajv2020Constructor = typeof import("ajv/dist/2020.js").Ajv2020;
+
+export type ValidationIssue = {
+  path: string;
+  message: string;
+  keyword?: string;
+};
+
+const Ajv2020Constructor = Ajv2020 as unknown as Ajv2020Constructor;
+
+const ajv = new Ajv2020Constructor({
+  allErrors: true,
+  strict: true,
+  strictRequired: false,
+  validateSchema: true
+});
+
+const validateTaskRequestSchema = ajv.compile(taskRequestSchema);
+const validateTaskResultSchema = ajv.compile(taskResultSchema);
+const validateIndeRunErrorSchema = ajv.compile(inderunErrorSchema);
+const validateHttpRequestSchema = ajv.compile(httpRequestSchema);
+const validateHttpResponseSchema = ajv.compile(httpResponseSchema);
+const validateTelemetryEventSchema = ajv.compile(telemetryEventSchema);
+const validateRoutePlannerInputSchema = ajv.compile(routePlannerInputSchema);
+const validateRoutePlanSchema = ajv.compile(routePlanSchema);
+const validateModelPackageSchema = ajv.compile(modelPackageSchema);
+const validateStreamRunHandleSchema = ajv.compile(streamRunSchema);
+const validateStreamEventSchema = ajv.compile(streamEventSchema);
+const validateStreamTerminalOutcomeSchema = ajv.compile(streamTerminalOutcomeSchema);
+
+export function validateTaskRequest(value: unknown): value is TaskRequest {
+  return getTaskRequestValidationIssues(value).length === 0;
+}
+
+export function validateTaskResult(value: unknown): value is TaskResult {
+  return getTaskResultValidationIssues(value).length === 0;
+}
+
+export function validateIndeRunError(value: unknown): value is IndeRunError {
+  return getIndeRunErrorValidationIssues(value).length === 0;
+}
+
+export function validateHttpRequest(value: unknown): value is HttpRequest {
+  return getHttpRequestValidationIssues(value).length === 0;
+}
+
+export function validateHttpResponse(value: unknown): value is HttpResponse {
+  return getHttpResponseValidationIssues(value).length === 0;
+}
+
+export function validateTelemetryEvent(value: unknown): value is TelemetryEvent {
+  return getTelemetryEventValidationIssues(value).length === 0;
+}
+
+export function validateRoutePlannerInput(value: unknown): value is RoutePlannerInput {
+  return getRoutePlannerInputValidationIssues(value).length === 0;
+}
+
+export function validateRoutePlan(value: unknown): value is RoutePlan {
+  return getRoutePlanValidationIssues(value).length === 0;
+}
+
+export function validateModelPackage(value: unknown): value is ModelPackage {
+  return getModelPackageValidationIssues(value).length === 0;
+}
+
+export function validateStreamRunHandle(value: unknown): value is StreamRunHandle {
+  return getStreamRunHandleValidationIssues(value).length === 0;
+}
+
+export function validateStreamEvent(value: unknown): value is StreamEvent {
+  return getStreamEventValidationIssues(value).length === 0;
+}
+
+export function validateStreamTerminalOutcome(value: unknown): value is StreamTerminalOutcome {
+  return getStreamTerminalOutcomeValidationIssues(value).length === 0;
+}
+
+export function getTaskRequestValidationIssues(value: unknown): ValidationIssue[] {
+  const issues = getValidationIssues(validateTaskRequestSchema, value, {
+    forbidInlineSecrets: true
+  });
+
+  issues.push(...findRoutingConstraintIssues(value));
+  return issues;
+}
+
+export function getTaskResultValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateTaskResultSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+export function getIndeRunErrorValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateIndeRunErrorSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+export function getHttpRequestValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateHttpRequestSchema, value);
+}
+
+export function getHttpResponseValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateHttpResponseSchema, value);
+}
+
+export function getTelemetryEventValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateTelemetryEventSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+export function getRoutePlannerInputValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateRoutePlannerInputSchema, value);
+}
+
+export function getRoutePlanValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateRoutePlanSchema, value);
+}
+
+export function getModelPackageValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateModelPackageSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+export function getStreamRunHandleValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateStreamRunHandleSchema, value);
+}
+
+export function getStreamEventValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateStreamEventSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+export function getStreamTerminalOutcomeValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateStreamTerminalOutcomeSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
+function getValidationIssues(
+  validateSchema: ValidateFunction,
+  value: unknown,
+  options: { forbidInlineSecrets?: boolean } = {}
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!validateSchema(value)) {
+    issues.push(...formatAjvIssues(validateSchema.errors ?? []));
+  }
+
+  if (options.forbidInlineSecrets) {
+    issues.push(...findInlineSecretKeys(value));
+  }
+
+  return issues;
+}
+
+function formatAjvIssues(errors: ErrorObject[]): ValidationIssue[] {
+  return errors.map((error) => ({
+    path: error.instancePath || "/",
+    message: error.message ?? "Invalid value",
+    keyword: error.keyword
+  }));
+}
+
+function findInlineSecretKeys(value: unknown, path = ""): ValidationIssue[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findInlineSecretKeys(item, `${path}/${index}`));
+  }
+
+  if (!value || typeof value !== "object") {
+    return [];
+  }
+
+  const issues: ValidationIssue[] = [];
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}/${escapeJsonPointerSegment(key)}`;
+    if (isForbiddenSecretKey(key)) {
+      issues.push({
+        path: childPath,
+        message: "Inline secrets are not allowed; use authContextRef instead.",
+        keyword: "forbiddenSecretKey"
+      });
+    }
+    issues.push(...findInlineSecretKeys(child, childPath));
+  }
+
+  return issues;
+}
+
+function findRoutingConstraintIssues(value: unknown): ValidationIssue[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [];
+  }
+
+  const request = value as {
+    constraints?: {
+      cloud?: string;
+      privacy?: string;
+    };
+  };
+
+  const constraints = request.constraints;
+  if (!constraints) {
+    return [];
+  }
+
+  const issues: ValidationIssue[] = [];
+
+  if (constraints.privacy === "local_required" && constraints.cloud === "required") {
+    issues.push({
+      path: "/constraints",
+      message: "privacy=local_required conflicts with cloud=required.",
+      keyword: "routingConstraintConflict"
+    });
+  }
+
+  if (constraints.privacy === "cloud_required" && constraints.cloud === "forbidden") {
+    issues.push({
+      path: "/constraints",
+      message: "privacy=cloud_required conflicts with cloud=forbidden.",
+      keyword: "routingConstraintConflict"
+    });
+  }
+
+  return issues;
+}
+
+function normalizeKey(key: string): string {
+  return key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function isForbiddenSecretKey(key: string): boolean {
+  const normalizedKey = normalizeKey(key);
+
+  if (
+    normalizedKey.includes("authorization") ||
+    normalizedKey.includes("password") ||
+    normalizedKey.includes("secret") ||
+    normalizedKey.includes("apikey")
+  ) {
+    return true;
+  }
+
+  if (normalizedKey.includes("api") && normalizedKey.includes("key")) {
+    return true;
+  }
+
+  return normalizedKey === "token" || normalizedKey.endsWith("token");
+}
+
+function escapeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}