@intx/inference 0.1.2 → 0.3.0

package/dist/harness.d.ts

@@ -0,0 +1,147 @@
+import type { ConversationTurn, InferenceEvent, InferenceOptions, InferenceSource } from "@intx/types/runtime";
+import type { AdapterRegistry } from "./adapter.js";
+/**
+ * Default per-call inactivity timeout (ms). Two minutes is conservative
+ * for reasoning-heavy models that emit `inference.thinking.delta` tokens
+ * regularly when actually working — sustained silence past this means
+ * the provider stream has genuinely stalled, not that the model is
+ * thinking. Operators can tune via `InferenceOptions.inactivityTimeoutMs`.
+ */
+export declare const DEFAULT_INACTIVITY_TIMEOUT_MS = 120000;
+/**
+ * Default per-call total wall-clock cap (ms). Matches Anthropic's
+ * documented per-call recommendation and fits within typical CI
+ * timeouts. Operators can tune via `InferenceOptions.totalTimeoutMs`.
+ */
+export declare const DEFAULT_TOTAL_TIMEOUT_MS = 600000;
+export declare const HarnessId: unique symbol;
+/**
+ * Runtime dependencies injected into `runInference`. Code-only — not part of
+ * any persisted schema. Test harnesses substitute `fetch` (and stamp the
+ * `[HarnessId]` tag for per-harness identity) so production `runInference`
+ * never reaches `globalThis.fetch`.
+ *
+ * `fetch` is intentionally typed as a plain function rather than
+ * `typeof globalThis.fetch` — the latter is augmented per-runtime (Bun adds
+ * `preconnect`; Node and the DOM lib do not) and `runInference` only ever
+ * invokes the call signature.
+ *
+ * The `[HarnessId]` tag is enumerable via `Object.getOwnPropertySymbols`
+ * (and `Reflect.ownKeys`, which is the superset). Do not pass `Dependencies`
+ * instances through reflective serializers or expose them across trust
+ * boundaries. (`JSON.stringify` is safe — it walks string keys only.)
+ */
+export type Dependencies = {
+    readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Time-based scheduler used by the harness's per-call timeouts (see
+     * `InferenceOptions.inactivityTimeoutMs` / `totalTimeoutMs`). Production
+     * passes the default wrapper around `setTimeout` / `clearTimeout`; the
+     * deterministic test harness injects a scheduler that wraps its virtual
+     * clock so timeout tests fire at virtual-time-N without sleeping real
+     * wall-clock. Required — every caller must make an explicit choice
+     * between the production scheduler and a virtual one. Use
+     * `createDefaultScheduler()` for the production default.
+     */
+    readonly scheduler: Scheduler;
+    /**
+     * Registry resolving an inference source to its provider adapter.
+     * `runSingleAttempt` consults this on every call via `adapters.resolve`,
+     * so it is required — the caller makes an explicit choice of provider set.
+     * Construct it via `createDependencies(adapters)` (core) or, for the
+     * built-in set, `@intx/inference/providers`' `createDefaultDependencies()`.
+     */
+    readonly adapters: AdapterRegistry;
+    readonly [HarnessId]?: symbol;
+};
+/**
+ * Minimal scheduling abstraction. `setTimeout` returns a canceller; the
+ * canceller is idempotent (multiple calls are safe). The harness uses
+ * this for both the inactivity timer (which is re-armed on every event)
+ * and the total wall-clock cap. `now()` is a monotonic time source in
+ * the same `delayMs` units `setTimeout` accepts — deltas across two
+ * `now()` reads describe elapsed time the same way `setTimeout(...,
+ * delta)` would have measured it.
+ */
+export type Scheduler = {
+    setTimeout(callback: () => void, delayMs: number): () => void;
+    now(): number;
+};
+export declare function createDefaultScheduler(): Scheduler;
+/**
+ * Construct runtime dependencies for `runInference` from an explicit adapter
+ * registry, binding `fetch` to `globalThis.fetch` and `scheduler` to the
+ * production wrapper. The registry is required so the caller makes an explicit
+ * choice of provider set; `@intx/inference/providers`' zero-arg
+ * `createDefaultDependencies()` is the honest default that supplies the
+ * built-in registry.
+ *
+ * @param adapters - Registry resolving inference sources to provider adapters
+ * @returns Fully-populated dependencies
+ */
+export declare function createDependencies(adapters: AdapterRegistry): Dependencies;
+export type InferenceHarnessOptions = {
+    turns: ConversationTurn[];
+    source: InferenceSource;
+    inferenceOptions?: InferenceOptions;
+    signal?: AbortSignal;
+    nextSeq: () => number;
+    deps: Dependencies;
+};
+/**
+ * Run a single inference call with mechanical retry. Wraps
+ * `runSingleAttempt` and consults the configured `RetryPolicy` (or the
+ * default from `createDefaultRetryPolicy`) on every `inference.error`.
+ *
+ * Events from each attempt are buffered until the attempt terminates;
+ * the wrapper only flushes them to the caller once it knows whether
+ * the attempt resolved (`inference.done` or a policy-approved abort)
+ * or whether the attempt's events should be discarded in favour of a
+ * retry. The buffer-and-flush model is what guarantees the caller
+ * sees a single clean event stream — exactly one `inference.start`,
+ * no orphaned partial deltas, no leaked `inference.error`s from
+ * attempts the policy chose to retry. The cost is that no events
+ * reach the caller until the wrapper knows the attempt's terminal
+ * shape, even on a successful first attempt. That trade-off is the
+ * deliberate consequence of making "one clean stream" a hard contract
+ * rather than a best-effort one. Consumers that need token-by-token
+ * partials must pin a custom non-buffering wrapper — no streaming-
+ * partials emission API exists today.
+ *
+ * The buffer is per-call and bounded by the size of one attempt's
+ * event stream — no cross-call accumulation.
+ *
+ * Caller-visible seqs stay contiguous across retries. Each attempt
+ * runs against a private seq allocator; on flush the wrapper
+ * re-stamps the buffered events with seqs from the caller's
+ * `nextSeq`, so a retry that discards an attempt does not leave a
+ * gap in the consumer's seq stream.
+ *
+ * Between attempts the wrapper emits one `inference.retry` event with
+ * the failed attempt's number, the policy-chosen `delayMs`, and the
+ * classified error that triggered the retry. The `setTimeout` await
+ * is driven by `deps.scheduler`, so virtual-clock test harnesses
+ * advance retry delays without sleeping real wall-clock. The
+ * caller-supplied `signal` short-circuits the retry delay: aborting
+ * the signal mid-delay wakes the await immediately and the next
+ * `runSingleAttempt` invocation surfaces `inference.error` of
+ * category `aborted` from its entry-time signal check, which the
+ * default policy aborts on.
+ *
+ * Policy-failure handling: if the policy throws synchronously or its
+ * returned Promise rejects, the wrapper treats the failure as
+ * `{ kind: "abort" }` and surfaces the *original* `inference.error`
+ * to the caller. The policy's own exception is logged at `warn` so
+ * operators can see when a custom policy is failing under load, and
+ * dropped — the inference error is what the caller needs to act on,
+ * not the bug in the policy callback.
+ *
+ * Synchronous throws from `runSingleAttempt` (`ProtocolMismatchError`
+ * raised by the streaming parse or the finalization walk, etc.)
+ * propagate out of `runInference`. The current attempt's buffered
+ * events are discarded along with the throw — those represent
+ * protocol bugs the policy mechanism is not equipped to absorb, and
+ * the caller's `for await` rejects so the failure surfaces rather
+ * than being silently buffered.
+ */
+export declare function runInference(opts: InferenceHarnessOptions): AsyncIterable<InferenceEvent>;