@oharness/engine 0.1.0

package/dist/providers/registry.js

@@ -0,0 +1,195 @@
+import { ConfigError } from "../core/errors.js";
+import { PI_APIS, PiAiProvider } from "./piai.js";
+import { ResilientProvider } from "./resilient.js";
+/**
+ * Holds providers and model specs, and resolves the aliases used by `/model`.
+ *
+ * Model switching lives here rather than in the agent: because conversation
+ * history is stored provider-neutrally, changing models is nothing more than
+ * resolving a different spec for the next request.
+ */
+export class ProviderRegistry {
+    providers = new Map();
+    models = new Map();
+    catalogProviders = {};
+    /**
+     * Build a registry from a catalog.
+     *
+     * Every provider comes from data — which protocol it speaks, where it lives,
+     * which env var holds its key — so adding a vendor never requires a code
+     * change, only a catalog entry.
+     */
+    static fromCatalog(catalog, opts = {}) {
+        const registry = new ProviderRegistry();
+        registry.catalogProviders = catalog.providers;
+        for (const provider of Object.values(catalog.providers)) {
+            // Every provider gets mid-stream resilience: a dropped connection part
+            // way through a long answer should not discard the whole turn.
+            registry.registerProvider(new ResilientProvider(buildProvider(provider, { ...opts.creds?.[provider.id], auth: opts.auth })));
+        }
+        for (const model of catalog.models)
+            registry.registerModel(model);
+        return registry;
+    }
+    /** The catalog entry behind a provider, for `/models` and login hints. */
+    catalogEntry(id) {
+        return this.catalogProviders[id];
+    }
+    listCatalogProviders() {
+        return Object.values(this.catalogProviders);
+    }
+    registerProvider(provider) {
+        this.providers.set(provider.id, provider);
+        return this;
+    }
+    /** Register an OpenAI-compatible vendor under its own provider id. */
+    registerOpenAiCompatible(opts) {
+        return this.registerProvider(new PiAiProvider({ api: "openai-completions", ...opts }));
+    }
+    /** Register (or replace) a provider from a catalog entry. */
+    registerCatalogProvider(entry, creds = {}) {
+        this.catalogProviders[entry.id] = entry;
+        return this.registerProvider(new ResilientProvider(buildProvider(entry, creds)));
+    }
+    registerModel(spec) {
+        this.models.set(spec.id, spec);
+        return this;
+    }
+    getProvider(id) {
+        const provider = this.providers.get(id);
+        if (!provider)
+            throw new ConfigError(`unknown provider: ${id}`);
+        return provider;
+    }
+    /**
+     * Resolve an alias (`sonnet`), a wire model id (`claude-sonnet-5`), or a
+     * fully qualified `provider/model` reference.
+     */
+    resolve(ref) {
+        const direct = this.models.get(ref);
+        if (direct)
+            return direct;
+        const slash = ref.indexOf("/");
+        if (slash !== -1) {
+            const providerId = ref.slice(0, slash);
+            const modelId = ref.slice(slash + 1);
+            const known = [...this.models.values()].find((m) => m.provider === providerId && (m.model === modelId || m.id === modelId));
+            if (known)
+                return known;
+            // Allow arbitrary models on a registered provider without pre-declaring
+            // them — useful for local servers and freshly released models.
+            if (this.providers.has(providerId)) {
+                return unknownModelSpec(providerId, modelId);
+            }
+        }
+        const byWireId = [...this.models.values()].find((m) => m.model === ref);
+        if (byWireId)
+            return byWireId;
+        throw new ConfigError(`unknown model: ${ref}. Known: ${this.listModels().map((m) => m.id).join(", ")}`);
+    }
+    /**
+     * Models worth showing.
+     *
+     * Aliases are excluded: they resolve, but they are the same model under a
+     * shorter name, and listing both turns a discovered roster of 300 into 600.
+     */
+    listModels(opts = {}) {
+        let all = [...this.models.values()];
+        if (!opts.includeAliases)
+            all = all.filter((model) => !model.aliasOf);
+        if (!opts.configuredOnly)
+            return all;
+        return all.filter((m) => this.providers.get(m.provider)?.isConfigured());
+    }
+    listProviders() {
+        return [...this.providers.values()];
+    }
+    hasModel(id) {
+        return this.models.has(id);
+    }
+    /**
+     * Ask providers that support it which models the account can actually use,
+     * and merge the results into the catalog.
+     *
+     * Subscription plans gate models by entitlement, so a static catalog will
+     * happily offer something the account cannot call. Returns the ids added or
+     * updated.
+     */
+    async refreshModels(providerId) {
+        const targets = providerId
+            ? [this.providers.get(providerId)].filter((p) => p !== undefined)
+            : [...this.providers.values()];
+        const changed = [];
+        for (const provider of targets) {
+            if (!provider.listModels)
+                continue;
+            try {
+                for (const spec of await provider.listModels()) {
+                    this.registerModel(spec);
+                    changed.push(spec);
+                    // Also expose a bare alias so `/model kimi-k3` works and not only
+                    // `/model moonshot/kimi-k3`. First provider to claim a name keeps
+                    // it — silently reassigning an alias across vendors would change
+                    // which model a saved config resolves to.
+                    if (!this.models.has(spec.model)) {
+                        this.registerModel({ ...spec, id: spec.model, aliasOf: spec.id });
+                    }
+                }
+            }
+            catch {
+                // A provider that cannot enumerate its models is not fatal; the
+                // catalog entries still work.
+                continue;
+            }
+        }
+        return changed;
+    }
+}
+/**
+ * Conservative defaults for a model we were not told about: assume tools work
+ * (the harness is useless otherwise) but assume nothing about reasoning
+ * controls, since guessing wrong there is a hard 400.
+ */
+function unknownModelSpec(providerId, modelId) {
+    return {
+        id: `${providerId}/${modelId}`,
+        provider: providerId,
+        model: modelId,
+        displayName: modelId,
+        contextWindow: 128_000,
+        maxOutputTokens: 8_192,
+        supportsTools: true,
+        supportsImages: false,
+        supportsParallelToolCalls: true,
+        supportsPromptCache: false,
+        capabilitiesAssumed: true,
+        thinkingMode: "none",
+        effortLevels: [],
+        supportsSampling: true,
+    };
+}
+/** Construct the adapter for a catalog entry's protocol. */
+function buildProvider(entry, creds) {
+    const api = PI_APIS[entry.protocol];
+    if (!api) {
+        throw new ConfigError(`provider ${entry.id} declares unknown protocol ${entry.protocol}`);
+    }
+    return new PiAiProvider({
+        baseUrl: entry.baseUrl,
+        ...creds,
+        // Merge rather than replace: a config adding one custom header must not
+        // drop the attribution/version headers the vendor requires.
+        headers: { ...entry.headers, ...creds.headers },
+        id: entry.id,
+        name: entry.label,
+        api,
+        apiKeyEnv: entry.envVars[0],
+        includeUsage: entry.includeUsage,
+        idempotencyKey: entry.idempotencyKey,
+        maxOutputTokens: entry.maxOutputTokens,
+        discoveryFormat: entry.discovery,
+        // An entry with no env vars is a local server that needs no key.
+        requiresKey: entry.envVars.length > 0,
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"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"}

package/dist/providers/resilient.d.ts

@@ -0,0 +1,46 @@
+import type { Logger } from "../util/logger.ts";
+import type { GenerateRequest, ModelSpec, Provider, StreamEvent } from "./types.ts";
+export interface ResilientOptions {
+    /** Restarts allowed when the stream dies before emitting anything. */
+    maxRestarts?: number;
+    logger?: Logger;
+}
+/**
+ * Wrap a provider so a broken stream does not necessarily lose the turn.
+ *
+ * `postJson` already retries the initial request, but that only covers
+ * failures before the response headers. A stream that dies *mid-generation* —
+ * a dropped connection, a proxy timeout on a long answer — used to throw and
+ * take every token already produced with it.
+ *
+ * The split matters:
+ *
+ * - **Nothing emitted yet** — nothing to lose, so restart the request. The
+ *   model has not committed to an answer and a retry is free apart from input
+ *   tokens.
+ * - **Something emitted** — restarting would duplicate the text already shown
+ *   and re-bill the output. Keep the partial turn and end it with a non-final
+ *   stop reason, so the agent loop can decide whether to continue.
+ *
+ * Restarting after partial output is the tempting option and the wrong one: it
+ * produces two half-answers glued together, and the user has already seen the
+ * first one.
+ */
+export declare class ResilientProvider implements Provider {
+    readonly id: string;
+    readonly name: string;
+    private readonly inner;
+    private readonly opts;
+    private readonly logger;
+    /**
+     * Only defined when the wrapped provider supports discovery — callers test
+     * for its presence, so defining it unconditionally would make every provider
+     * claim it can enumerate models.
+     */
+    readonly listModels?: () => Promise<ModelSpec[]>;
+    constructor(inner: Provider, opts?: ResilientOptions);
+    isConfigured(): boolean;
+    /** The wrapped adapter, for diagnostics and tests. */
+    unwrap(): Provider;
+    stream(request: GenerateRequest): AsyncGenerator<StreamEvent, void, void>;
+}

package/dist/providers/resilient.js

@@ -0,0 +1,117 @@
+import { ProviderError, errorMessage } from "../core/errors.js";
+import { emptyUsage } from "../core/types.js";
+import { createLogger } from "../util/logger.js";
+const DEFAULT_MAX_RESTARTS = 2;
+/**
+ * Wrap a provider so a broken stream does not necessarily lose the turn.
+ *
+ * `postJson` already retries the initial request, but that only covers
+ * failures before the response headers. A stream that dies *mid-generation* —
+ * a dropped connection, a proxy timeout on a long answer — used to throw and
+ * take every token already produced with it.
+ *
+ * The split matters:
+ *
+ * - **Nothing emitted yet** — nothing to lose, so restart the request. The
+ *   model has not committed to an answer and a retry is free apart from input
+ *   tokens.
+ * - **Something emitted** — restarting would duplicate the text already shown
+ *   and re-bill the output. Keep the partial turn and end it with a non-final
+ *   stop reason, so the agent loop can decide whether to continue.
+ *
+ * Restarting after partial output is the tempting option and the wrong one: it
+ * produces two half-answers glued together, and the user has already seen the
+ * first one.
+ */
+export class ResilientProvider {
+    id;
+    name;
+    inner;
+    opts;
+    logger;
+    /**
+     * Only defined when the wrapped provider supports discovery — callers test
+     * for its presence, so defining it unconditionally would make every provider
+     * claim it can enumerate models.
+     */
+    listModels;
+    constructor(inner, opts = {}) {
+        this.inner = inner;
+        this.opts = opts;
+        this.id = inner.id;
+        this.name = inner.name;
+        this.logger = (opts.logger ?? createLogger("provider")).child(`resilient:${inner.id}`);
+        if (inner.listModels)
+            this.listModels = () => inner.listModels();
+    }
+    isConfigured() {
+        return this.inner.isConfigured();
+    }
+    /** The wrapped adapter, for diagnostics and tests. */
+    unwrap() {
+        return this.inner;
+    }
+    async *stream(request) {
+        const maxRestarts = this.opts.maxRestarts ?? DEFAULT_MAX_RESTARTS;
+        for (let attempt = 0;; attempt++) {
+            let emitted = false;
+            let ended = false;
+            try {
+                for await (const event of this.inner.stream(request)) {
+                    // "Emitted" means content the caller can already see. A `start`
+                    // event carries nothing, so a failure right after it is still safe
+                    // to restart.
+                    if (event.type === "text_delta" ||
+                        event.type === "thinking_delta" ||
+                        event.type === "tool_call_start" ||
+                        event.type === "tool_call_delta" ||
+                        event.type === "tool_call_end") {
+                        emitted = true;
+                    }
+                    if (event.type === "end")
+                        ended = true;
+                    yield event;
+                }
+                // A stream that finished without an `end` event was cut short between
+                // the last chunk and the terminator.
+                if (!ended) {
+                    this.logger.warn("stream closed without a terminator", { attempt });
+                    yield {
+                        type: "end",
+                        stopReason: emitted ? "error" : "end_turn",
+                        usage: emptyUsage(),
+                    };
+                }
+                return;
+            }
+            catch (err) {
+                // A caller-initiated abort is intentional; never retry it.
+                if (request.signal?.aborted)
+                    throw err;
+                const retryable = !(err instanceof ProviderError) || err.retryable;
+                if (emitted) {
+                    // Keep what the user already saw rather than replaying it.
+                    this.logger.warn("stream failed after partial output; keeping the partial turn", {
+                        error: errorMessage(err),
+                    });
+                    yield { type: "end", stopReason: "error", usage: emptyUsage() };
+                    return;
+                }
+                if (!retryable || attempt >= maxRestarts)
+                    throw err;
+                this.logger.warn("stream failed before any output; restarting", {
+                    attempt: attempt + 1,
+                    error: errorMessage(err),
+                });
+                await sleep(backoffMs(attempt));
+            }
+        }
+    }
+}
+function backoffMs(attempt) {
+    return Math.min(1_000 * 2 ** attempt, 8_000) + Math.random() * 250;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=resilient.js.map

package/dist/providers/resilient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient.js","sourceRoot":"","sources":["../../src/providers/resilient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAUjD,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,iBAAiB;IACnB,EAAE,CAAS;IACX,IAAI,CAAS;IACL,KAAK,CAAW;IAChB,IAAI,CAAmB;IACvB,MAAM,CAAS;IAChC;;;;OAIG;IACM,UAAU,CAA8B;IAEjD,YAAY,KAAe,EAAE,OAAyB,EAAE;QACtD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACvF,IAAI,KAAK,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,UAAW,EAAE,CAAC;IACpE,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;IACnC,CAAC;IAED,sDAAsD;IACtD,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAGD,KAAK,CAAC,CAAC,MAAM,CAAC,OAAwB;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;QAElE,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,IAAI,KAAK,GAAG,KAAK,CAAC;YAElB,IAAI,CAAC;gBACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;oBACrD,gEAAgE;oBAChE,mEAAmE;oBACnE,cAAc;oBACd,IACE,KAAK,CAAC,IAAI,KAAK,YAAY;wBAC3B,KAAK,CAAC,IAAI,KAAK,gBAAgB;wBAC/B,KAAK,CAAC,IAAI,KAAK,iBAAiB;wBAChC,KAAK,CAAC,IAAI,KAAK,iBAAiB;wBAChC,KAAK,CAAC,IAAI,KAAK,eAAe,EAC9B,CAAC;wBACD,OAAO,GAAG,IAAI,CAAC;oBACjB,CAAC;oBACD,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;wBAAE,KAAK,GAAG,IAAI,CAAC;oBACvC,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,sEAAsE;gBACtE,qCAAqC;gBACrC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;oBACpE,MAAM;wBACJ,IAAI,EAAE,KAAK;wBACX,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU;wBAC1C,KAAK,EAAE,UAAU,EAAE;qBACpB,CAAC;gBACJ,CAAC;gBACD,OAAO;YACT,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,2DAA2D;gBAC3D,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;oBAAE,MAAM,GAAG,CAAC;gBAEvC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,YAAY,aAAa,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC;gBAEnE,IAAI,OAAO,EAAE,CAAC;oBACZ,2DAA2D;oBAC3D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8DAA8D,EAAE;wBAC/E,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC;qBACzB,CAAC,CAAC;oBACH,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;oBAChE,OAAO;gBACT,CAAC;gBAED,IAAI,CAAC,SAAS,IAAI,OAAO,IAAI,WAAW;oBAAE,MAAM,GAAG,CAAC;gBAEpD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,6CAA6C,EAAE;oBAC9D,OAAO,EAAE,OAAO,GAAG,CAAC;oBACpB,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC;iBACzB,CAAC,CAAC;gBACH,MAAM,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC;AACrE,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/providers/types.d.ts

@@ -0,0 +1,182 @@
+import type { AuthResolver, ResolvedAuth } from "../auth/types.ts";
+import type { Message, StopReason, ToolSchema, Usage } from "../core/types.ts";
+/**
+ * A model as the harness knows it: a stable alias plus the capability facts the
+ * agent loop needs in order to build a legal request.
+ */
+export interface ModelSpec {
+    /**
+     * Set when this entry only exists so a bare name resolves.
+     *
+     * Discovery registers `kimi-k3` alongside `moonshot/kimi-k3` so both work in
+     * `/model`. They are one model, so anything listing models for a human must
+     * skip the alias — otherwise every discovered model appears twice.
+     */
+    aliasOf?: string;
+    /** Harness-level alias used by `/model` and config, e.g. "sonnet". */
+    id: string;
+    /** Id of the provider that serves it, e.g. "anthropic". */
+    provider: string;
+    /** The wire model id sent to the API. */
+    model: string;
+    displayName?: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    supportsTools: boolean;
+    supportsImages: boolean;
+    supportsParallelToolCalls: boolean;
+    /** Prompt caching (Anthropic cache_control). */
+    supportsPromptCache: boolean;
+    /**
+     * Set when the capability flags above were assumed rather than published.
+     *
+     * A discovered endpoint that says nothing about its models lands on
+     * defaults, and "we were not told" is not the same fact as "no". It matters
+     * for images in particular: a false `supportsImages` makes the OpenAI
+     * adapter drop the images in a tool result on the floor, so a `read` of a
+     * screenshot would reach an entirely capable model as a caption. Anything
+     * refusing or degrading on a capability must check this first.
+     */
+    capabilitiesAssumed?: boolean;
+    /**
+     * How this model wants reasoning configured. Getting this wrong is a 400,
+     * not a degradation:
+     *  - "adaptive": `{type:"adaptive"}`; a `budget_tokens` config is rejected.
+     *  - "always-on": thinking cannot be turned off; send no thinking config.
+     *  - "budget":   legacy `{type:"enabled", budget_tokens:N}`.
+     *  - "effort":   no thinking block, only an effort/verbosity tier.
+     *  - "none":     the model has no reasoning controls.
+     */
+    thinkingMode: "adaptive" | "always-on" | "budget" | "effort" | "none";
+    /** Effort tiers the model accepts; empty means the parameter is unsupported. */
+    effortLevels: EffortLevel[];
+    /**
+     * Some models reject `thinking: {type:"disabled"}` above a given effort tier.
+     * Undefined means disabling is allowed at any tier this model supports.
+     */
+    maxEffortWithThinkingDisabled?: EffortLevel;
+    /**
+     * Whether `temperature`/`top_p` are accepted. The current Claude and
+     * reasoning-model families reject them outright.
+     */
+    supportsSampling: boolean;
+    costPer1MInput?: number;
+    costPer1MOutput?: number;
+    costPer1MCacheRead?: number;
+    costPer1MCacheWrite?: number;
+}
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
+export interface ThinkingConfig {
+    enabled: boolean;
+    /** Only used by models whose `thinkingMode` is "budget" (or Gemini). */
+    budgetTokens?: number;
+    /** Effort tier; clamped to the model's `effortLevels`. */
+    effort?: EffortLevel;
+    /** Ask the provider to return a readable summary of the reasoning. */
+    display?: "summarized" | "omitted";
+}
+/** Clamp a requested effort tier to what a model actually accepts. */
+export declare function resolveEffort(spec: ModelSpec, requested: EffortLevel | undefined): EffortLevel | undefined;
+export type ToolChoice = {
+    type: "auto";
+} | {
+    type: "none";
+} | {
+    type: "required";
+} | {
+    type: "tool";
+    name: string;
+};
+export interface GenerateRequest {
+    model: ModelSpec;
+    system?: string;
+    messages: Message[];
+    tools?: ToolSchema[];
+    toolChoice?: ToolChoice;
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    thinking?: ThinkingConfig;
+    /** Enable provider prompt caching where supported. */
+    cache?: boolean;
+    signal?: AbortSignal;
+    /** Extra provider-specific body fields, merged last. */
+    extraBody?: Record<string, unknown>;
+}
+export type StreamEvent = {
+    type: "start";
+    model: string;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    text: string;
+} | {
+    type: "thinking_signature";
+    signature: string;
+} | {
+    type: "tool_call_start";
+    id: string;
+    name: string;
+}
+/** Raw JSON fragment of the tool input, for live previews. */
+ | {
+    type: "tool_call_delta";
+    id: string;
+    argsDelta: string;
+} | {
+    type: "tool_call_end";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "usage";
+    usage: Usage;
+} | {
+    type: "end";
+    stopReason: StopReason;
+    usage: Usage;
+};
+export interface Provider {
+    readonly id: string;
+    /** Human-readable name for logs and `/model`. */
+    readonly name: string;
+    /**
+     * Cheap synchronous check for a statically-configured key. A provider
+     * authenticated through a subscription may return false here and still work
+     * — ask `AuthManager.isAuthenticated()` for the authoritative answer.
+     */
+    isConfigured(): boolean;
+    stream(request: GenerateRequest): AsyncGenerator<StreamEvent, void, void>;
+    /**
+     * Report the models this account can actually use. Subscription providers
+     * gate models by entitlement, so a static catalog would over-promise.
+     */
+    listModels?(): Promise<ModelSpec[]>;
+}
+export interface ProviderCredentials {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Number of retries on retryable failures. */
+    maxRetries?: number;
+    /**
+     * Resolves credentials at request time. Required for subscription auth,
+     * where the token in hand at startup may have expired by the next turn.
+     */
+    auth?: AuthResolver;
+}
+/**
+ * Merge resolved credentials into a request's headers.
+ *
+ * `removeHeaders` matters as much as the additions: a provider that sets
+ * `x-api-key` by default must have it stripped when a bearer token is in play,
+ * or the API sees two conflicting credentials.
+ */
+export declare function applyAuthHeaders(base: Record<string, string>, resolved: ResolvedAuth | undefined): Record<string, string>;
+export declare function estimateCost(spec: ModelSpec, usage: Usage): number;

package/dist/providers/types.js

@@ -0,0 +1,50 @@
+/** Clamp a requested effort tier to what a model actually accepts. */
+export function resolveEffort(spec, requested) {
+    if (spec.effortLevels.length === 0)
+        return undefined;
+    if (requested && spec.effortLevels.includes(requested))
+        return requested;
+    if (!requested)
+        return undefined;
+    const order = ["low", "medium", "high", "xhigh", "max"];
+    const wanted = order.indexOf(requested);
+    // Step down to the highest supported tier at or below what was asked for.
+    for (let i = wanted; i >= 0; i--) {
+        const candidate = order[i];
+        if (spec.effortLevels.includes(candidate))
+            return candidate;
+    }
+    return spec.effortLevels[0];
+}
+/**
+ * Merge resolved credentials into a request's headers.
+ *
+ * `removeHeaders` matters as much as the additions: a provider that sets
+ * `x-api-key` by default must have it stripped when a bearer token is in play,
+ * or the API sees two conflicting credentials.
+ */
+export function applyAuthHeaders(base, resolved) {
+    if (!resolved)
+        return base;
+    const merged = { ...base };
+    for (const name of resolved.removeHeaders ?? []) {
+        delete merged[name];
+        delete merged[name.toLowerCase()];
+    }
+    for (const [name, value] of Object.entries(resolved.headers)) {
+        merged[name] = value;
+    }
+    return merged;
+}
+export function estimateCost(spec, usage) {
+    const m = 1_000_000;
+    const inTok = usage.inputTokens ?? 0;
+    const outTok = usage.outputTokens ?? 0;
+    const cacheRead = usage.cacheReadTokens ?? 0;
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+    return ((inTok * (spec.costPer1MInput ?? 0)) / m +
+        (outTok * (spec.costPer1MOutput ?? 0)) / m +
+        (cacheRead * (spec.costPer1MCacheRead ?? spec.costPer1MInput ?? 0)) / m +
+        (cacheWrite * (spec.costPer1MCacheWrite ?? spec.costPer1MInput ?? 0)) / m);
+}
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAuFA,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAC3B,IAAe,EACf,SAAkC;IAElC,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACrD,IAAI,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,KAAK,GAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxC,0EAA0E;IAC1E,KAAK,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AA4ED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAA4B,EAC5B,QAAkC;IAElC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,MAAM,GAA2B,EAAE,GAAG,IAAI,EAAE,CAAC;IACnD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACpC,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7D,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,KAAY;IACxD,MAAM,CAAC,GAAG,SAAS,CAAC;IACpB,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;IAC/C,OAAO,CACL,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QACxC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QAC1C,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QACvE,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAC1E,CAAC;AACJ,CAAC"}

package/dist/schedule/cron.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A five-field cron parser.
+ *
+ * Written rather than pulled in because the harness has no runtime
+ * dependencies, and because the one rule everybody gets wrong — how
+ * day-of-month and day-of-week combine — is worth having under test rather
+ * than inherited.
+ */
+export interface CronFields {
+    minute: Set<number>;
+    hour: Set<number>;
+    dayOfMonth: Set<number>;
+    month: Set<number>;
+    dayOfWeek: Set<number>;
+    /**
+     * True when both day fields are restricted. Standard cron treats that as
+     * OR, not AND: `0 0 1 * 1` fires on the 1st *and* on every Monday. Reading
+     * it as AND is the classic way to build a job that almost never runs.
+     */
+    dayFieldsAreOr: boolean;
+}
+export declare function parseCron(expression: string): CronFields;
+/** Whether a wall-clock instant matches, to the minute. */
+export declare function matches(fields: CronFields, date: Date): boolean;
+/**
+ * The next instant at or after `from` that matches.
+ *
+ * Steps a minute at a time rather than solving the fields analytically: it is
+ * a few thousand iterations at worst, and it stays correct across DST shifts
+ * because it asks the platform's calendar rather than doing date arithmetic.
+ * Returns undefined if nothing matches within four years (e.g. Feb 30).
+ */
+export declare function nextRun(fields: CronFields, from?: Date): Date | undefined;
+/** Describe a schedule in words, for `schedule list`. */
+export declare function describeCron(expression: string): string;