@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/runtime/index.d.ts

@@ -1,367 +1,17 @@
-export { CatalogModel, ModelCatalog, RouterModel, __resetCatalogCache, buildCatalog, fetchModelCatalog, isChatCapableModel, normalizeModelId } from '../catalog/index.js';
-export { C as CreateTangleRouterModelConfigOptions, D as DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR, c as DEFAULT_TANGLE_ROUTER_BASE_URL, R as ResolveModelOptions, d as ResolveTangleDevOrUserKeyOptions, e as ResolveUserTangleExecutionKeyForUserOptions, f as ResolveUserTangleExecutionKeyOptions, g as ResolvedTangleExecutionKey, h as TangleBillingEnforcementOptions, a as TangleExecutionEnvironment, i as TangleExecutionKeyError, j as TangleExecutionKeyErrorCode, k as TangleExecutionKeyHttpError, b as TangleExecutionKeySource, T as TangleModelConfig, l as createTangleRouterModelConfig, m as isTangleBillingEnforcementDisabled, n as isTangleExecutionKeyError, r as resolveTangleDevOrUserKey, o as resolveTangleExecutionEnvironment, p as resolveTangleModelConfig, q as resolveUserTangleExecutionKey, s as resolveUserTangleExecutionKeyForUser, t as tangleExecutionKeyHttpError, u as trimOrNull } from '../model-CdCDfBA9.js';
-import * as _tangle_network_agent_runtime_tool_loop from '@tangle-network/agent-runtime/tool-loop';
-import { ToolLoopMessage } from '@tangle-network/agent-runtime/tool-loop';
-export { RunToolLoopOptions as AppToolLoopOptions, ToolLoopAssistantToolCall as LoopAssistantToolCall, ToolLoopMessage as LoopMessage, ToolLoopCall as LoopToolCall, StreamToolLoopOptions as StreamAppToolLoopOptions, StreamToolLoopYield as StreamLoopYield, ToolLoopEvent, ToolLoopResult, ToolLoopStopReason, runToolLoop as runAppToolLoop, streamToolLoop as streamAppToolLoop } from '@tangle-network/agent-runtime/tool-loop';
-import { CertifiedProfile } from '@tangle-network/agent-runtime/intelligence';
-import { A as AppToolMcpServer } from '../mcp-xxoZZfor.js';
-import '@tangle-network/agent-interface';
-import '../types-B25Mib1r.js';
-import '../auth-BYtiazA4.js';
-
-/**
- * Events the app's OpenAI-compat stream adapter ({@link toLoopEvents}) yields.
- *
- * This is the app's own `Raw` event type for the streaming loop — the canonical
- * `streamToolLoop<Raw>` is generic over it. It widens the substrate's
- * tool-loop event with `reasoning` (DeepSeek/router `reasoning_content` /
- * `thinking` deltas, rendered as thinking sections) and `usage` (per-message
- * token accounting) — neither belongs in the substrate's loop contract, so they
- * stay here. The adapter maps each into the `streamTurn` seam; `text` and
- * `tool_call` drive the loop, `reasoning` / `usage` pass through to the UI.
- */
-type LoopEvent = {
-    type: 'text';
-    text: string;
-} | {
-    type: 'reasoning';
-    text: string;
-} | {
-    type: 'tool_call';
-    call: _tangle_network_agent_runtime_tool_loop.ToolLoopCall;
-} | {
-    type: 'usage';
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-    };
-} | {
-    type: 'other';
-    event: unknown;
-};
-
-/**
- * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.
- *
- * `streamAppToolLoop` takes a `streamTurn` seam that yields `LoopEvent`s. A
- * sandboxed agent produces those from its container; a browser/edge copilot
- * instead calls a model directly. The Tangle Router, the tcloud SDK, and most
- * providers all speak the OpenAI Chat Completions streaming shape — so the ONE
- * reusable piece is assembling that stream (content deltas + FRAGMENTED
- * tool-call deltas) into `LoopEvent`s. That assembly is the boilerplate every
- * copilot would re-write (and get wrong — OpenAI streams tool-call arguments in
- * pieces across chunks).
- *
- * This does NOT implement an HTTP client beyond a minimal `fetch` + SSE reader
- * (browser/edge/Node-safe, zero deps). For richer transport use the tcloud SDK
- * or the Vercel AI SDK and pipe their stream through {@link toLoopEvents}.
- */
-
-/** Minimal OpenAI Chat Completions streaming chunk (structural — no `openai` dep). */
-interface OpenAIStreamChunk {
-    /** The model that produced this chunk. The Tangle Router reports the DATED
-     *  upstream id here (`gpt-5-2025-08-07`) whether or not it substituted, so
-     *  this is a served-model source only after id folding — see
-     *  {@link OpenAICompatServedModel}. */
-    model?: string;
-    choices?: Array<{
-        delta?: {
-            content?: string | null;
-            /** Reasoning deltas — DeepSeek/router use `reasoning_content`; some proxies use `thinking`. */
-            reasoning_content?: string | null;
-            thinking?: string | null;
-            tool_calls?: Array<{
-                index: number;
-                id?: string;
-                function?: {
-                    name?: string;
-                    arguments?: string;
-                };
-            }>;
-        };
-        finish_reason?: string | null;
-    }>;
-    /** Final-chunk token accounting (requires `stream_options.include_usage`). */
-    usage?: {
-        prompt_tokens?: number;
-        completion_tokens?: number;
-    } | null;
-}
-/**
- * Map an OpenAI-compat streaming chunk iterator to `LoopEvent`s: each content
- * delta → a `text` event; tool-call deltas are accumulated by index across
- * chunks and emitted as one complete `tool_call` event when the stream finishes
- * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than
- * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.
- */
-declare function toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent>;
-/**
- * Which model actually served one direct-router turn.
- *
- * The router substitutes models on purpose — a quota-walled primary comes back
- * `200` answered by a different model — and says so in response headers. This
- * lane used to drop the whole `Response` after taking `.body`, so a turn
- * requested as `claude-sonnet-4-6` and answered by `openai/gpt-5` was recorded
- * by its caller as Claude: per-model quality scoring blamed the wrong model and
- * cost used the wrong price basis.
- *
- * Map this onto the shell's existing attribution contract rather than inventing
- * a second channel — `ChatTurnRouteProducer.modelAttribution()` (`/chat-routes`):
- *
- *     modelAttribution: () => ({ requestedModel, servedModel, echoReceived: true })
- *
- * Leave that contract's `servedSource` unset: its union is sandbox
- * profile-resolution vocabulary with no router analogue.
- */
-interface OpenAICompatServedModel {
-    /** The model id this turn asked for (`OpenAICompatStreamTurnOptions.model`). */
-    requestedModel: string;
-    /** The model the router/provider reports having actually served. */
-    servedModel: string;
-    /** Where `servedModel` was read from. The header is the router's own
-     *  substitution signal; the body is the backstop that survives CORS. */
-    source: 'router_header' | 'response_body';
-    /** True when served differs from requested after id folding. Folded, not
-     *  compared raw: the body reports a dated id on EVERY turn, so `!==` would
-     *  claim a substitution every time. */
-    substituted: boolean;
-    /** `x-tangle-failover` `trigger=` — why the router swapped. Absent when the
-     *  router did not inject the substitute (a caller-supplied fallback chain
-     *  sets the served-model header without the failover one). */
-    trigger?: string;
-    /** `x-tangle-failover` `degraded=`. */
-    degraded?: boolean;
-}
-/** Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools */
-interface OpenAICompatStreamTurnOptions {
-    /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */
-    baseUrl: string;
-    apiKey: string;
-    model: string;
-    /** OpenAI tool definitions — pass `buildAppToolOpenAITools(taxonomy)` so the
-     *  model can call the app tools. Omit for a tool-free copilot. */
-    tools?: unknown[];
-    temperature?: number;
-    fetchImpl?: typeof fetch;
-    /** Extra body fields (e.g. `max_tokens`). */
-    extraBody?: Record<string, unknown>;
-    /**
-     * Called at most ONCE per turn, as soon as the serving model is
-     * determinable, with what actually answered. Never called when neither the
-     * header nor the body names a model — silence means "learned nothing", not
-     * "nothing was substituted".
-     *
-     * `streamTurn` runs once per TOOL turn, so a multi-turn `runAppToolLoop`
-     * fires this once per turn; take the last for row attribution.
-     */
-    onServedModel?: (served: OpenAICompatServedModel) => void;
-}
-/**
- * Build a `streamTurn` that calls an OpenAI-compatible `/chat/completions`
- * endpoint (Tangle Router / tcloud / any compat provider) with `stream: true`
- * and yields `LoopEvent`s via {@link toLoopEvents}. Browser/edge/Node-safe —
- * just `fetch` + an SSE reader. Drop straight into `streamAppToolLoop`:
- *
- *   const cfg = resolveTangleModelConfig()                 // or { baseUrl, apiKey, model }
- *   streamAppToolLoop({ streamTurn: createOpenAICompatStreamTurn({ ...cfg, tools }), executeToolCall, ... })
- */
-declare function createOpenAICompatStreamTurn(opts: OpenAICompatStreamTurnOptions): (messages: ToolLoopMessage[]) => AsyncIterable<LoopEvent>;
-
-/**
- * The resolved per-turn profile surfaces a delivered / certified `AgentProfile`
- * can change.
- *
- * This file used to also carry `createAgentRuntime` — a factory that hand-wired
- * `resolveTangleModelConfig` + `buildAppToolOpenAITools` + `createOpenAICompatStreamTurn`
- * + `createAppToolRuntimeExecutor` + `runAppToolLoop` into one object. It shipped
- * for the whole life of the package and never acquired a consumer (0 references
- * across all nine repos on the fleet's default branches), while every product
- * that drives an in-process model turn composes those five directly or uses
- * `handleChatTurn`. It was removed in 0.44.0; compose the pieces, or see
- * `examples/browser-copilot.md` for the sandbox-free assembly.
- */
-/** The agent's resolved profile surfaces for one turn — the things a delivered
- *  / certified `AgentProfile` can change. Profile-WIDE on purpose: certified
- *  delivery folds prompt-surface + skills into `systemPrompt` AND can add
- *  certified `tool` artifacts to `extraTools`. MCP servers / memory / RAG that
- *  materialize as files or servers deliver through the sandbox-provisioning
- *  seam, not here. */
-interface ResolvedAgentProfile {
-    systemPrompt: string;
-    extraTools: unknown[];
-}
-
-/**
- * `createCertifiedDelivery` — the delivery truck for Tangle Intelligence.
- *
- * Pulls a tenant's CERTIFIED `AgentProfile` from the deployed plane
- * (`GET /v1/profiles/:target/composed`) and applies it to the agent's resolved
- * surfaces each turn, so an approved improvement reaches the running agent with
- * NO redeploy. This is the `composeProfile` transform `createAgentRuntime`
- * accepts — opt-in per product, fail-closed, cached + refreshed.
- *
- * Profile-WIDE by design (not prompt-only): the composed profile carries every
- * promoted artifact type keyed by kind. What's folded where:
- *   - `prompt-surface` + `skill` → the system prompt (via `composeCertifiedPrompt`).
- *   - `tool` artifacts that carry an OpenAI tool definition → `extraTools`
- *     (advertised to the model; the matching executor is supplied by the product
- *     via `executeOtherTool`). Until a `tool` artifact carries a runnable def,
- *     it is surfaced (see `current()`) but not advertised — advertising a tool
- *     with no executor would make the model call into a dead end.
- *   - `mcp` / `memory` / `rag` artifacts materialize as servers/files and deliver
- *     through the SANDBOX-provisioning seam, not this in-process one. The full
- *     certified profile is exposed via `current()` so that seam can consume it.
- *
- * Substrate boundary: THIS module imports `@tangle-network/agent-runtime`; the
- * `createAgentRuntime` core does not (it only consumes the generic transform).
- */
-
-/** Define configuration options for delivering certified artifacts to a specified tenant target */
-interface CertifiedDeliveryConfig {
-    /** The tenant target whose certified artifacts to deliver (the agent id). */
-    target: string;
-    /** Bearer for the plane. Reads `TANGLE_API_KEY` when omitted. */
-    apiKey?: string;
-    /** Plane base URL. Reads `TANGLE_INTELLIGENCE_URL` then the public plane. */
-    baseUrl?: string;
-    /** Min interval between certified-profile pulls. Default 5m. */
-    refreshMs?: number;
-    /** fetch impl (tests / non-global-fetch runtimes). */
-    fetchImpl?: typeof fetch;
-}
-/** Resolve and manage certified profiles with refresh and composition capabilities */
-interface CertifiedDelivery {
-    /** The `composeProfile` transform to pass to `createAgentRuntime`. Applies the
-     *  cached certified profile to the base surfaces; refreshes on the cadence. */
-    composeProfile(base: ResolvedAgentProfile): Promise<ResolvedAgentProfile>;
-    /** Force a pull now (ignores the refresh window). Best-effort. */
-    refresh(): Promise<void>;
-    /** The certified profile currently in effect (null = none promoted / pull
-     *  failed). Lets the sandbox-provisioning seam deliver the file/server
-     *  artifact types this in-process seam doesn't. */
-    current(): CertifiedProfile | null;
-}
-/**
- * Build a certified-delivery transform for one agent target. Fail-closed: a pull
- * error or 404 keeps the last-known certified profile (or null), and the agent
- * runs on its base surfaces — it never breaks because Intelligence is down.
- */
-declare function createCertifiedDelivery(config: CertifiedDeliveryConfig): CertifiedDelivery;
-
-/**
- * Surface-scoped profile overlay — the seam letting any product page (a
- * sequence editor, a brief composer, a dataset view) add MCP servers, a prompt
- * addendum, and permission tightening to the workspace agent profile for turns
- * initiated FROM that surface, without the chat orchestrator knowing any
- * surface's specifics. The orchestrator resolves `(kind, ctx)` through a
- * registry the REQUEST HANDLER constructs per request (construction is a Map
- * build — cheap) and merges the result into the base profile it was about to
- * send to the sandbox. Per-request construction is the trust mechanism, not an
- * optimization target: each `build()` closes over server-trusted request state
- * (env bindings, secrets, the AUTHENTICATED user/workspace), which on Workers
- * exists only per request — a startup-built registry would force identity
- * through the untrusted client `ctx`.
- *
- * SECURITY INVARIANT: the surface `kind` and the ids inside `ctx` arrive on
- * the client request and are pure ROUTING data — never trusted content, never
- * identity. Identity comes from the closure (see above). The registered
- * `build()` runs server-side only: it validates the routing ids against the
- * product's access control, then mints its own URLs from server configuration
- * (`buildHttpMcpServer` in ../tools). A client can therefore never inject an
- * arbitrary MCP url, header, or credential into the agent profile: the
- * overlay's `mcp` values are typed as {@link SurfaceMcpServer} (= the
- * server-built `AppToolMcpServer` entry shape), and only build() constructs
- * them.
- *
- * The credential itself never appears in the overlay. Since the tagged-config
- * contract (`agent-interface` 0.38.0) the `Authorization` header is a
- * `secret-ref` naming a box-environment variable, which the sandbox resolves
- * privately; `build()` supplies that key NAME from server configuration and the
- * product writes the value into `SandboxRuntimeConfig.env` at box creation. The
- * value must be deterministic for the box's lifetime (an HMAC over the
- * workspace id, e.g. `createCapabilityToken` in ../tools), because a freshly
- * random per-request mint would never match what the box already carries.
- */
-
-/** Sandbox permission posture values, ranked deny > ask > allow for merging. */
-type SurfacePermissionValue = 'allow' | 'ask' | 'deny';
-/** The only MCP entry shape an overlay may carry: the server-built bridge
- *  entry from ../tools/mcp (transport, url, headers, and capability token all
- *  assembled server-side). The alias exists so overlay authors reach for the
- *  builders in ../tools rather than hand-rolling `{ url: ctx.url }` shapes
- *  that would let request data become a dialable endpoint. */
-type SurfaceMcpServer = AppToolMcpServer;
-/** What one surface contributes to the agent profile for a single turn. */
-interface SurfaceOverlay {
-    /** MCP servers to mount for this turn, keyed by tool-routing name. Names
-     *  must not collide with the base profile's — see {@link mergeSurfaceOverlay}. */
-    mcp?: Record<string, SurfaceMcpServer>;
-    /** Appended to the base system-prompt addendum with a blank-line separator. */
-    promptAddendum?: string;
-    /** Per-key posture the surface wants for its turns. Merging is monotone
-     *  fail-closed: the stricter of base/overlay wins, so a surface can tighten
-     *  the workspace posture but never relax it. */
-    permissions?: Record<string, SurfacePermissionValue>;
-}
-/**
- * One registered surface kind. `TCtx` is the shape build() expects — a CLAIM
- * about the client payload, not a guarantee: the registry hands build() the
- * request's `ctx` unvalidated, so build() must treat every field as an
- * untrusted id (resolve it through access control that throws on a bad or
- * foreign id) before minting anything from it.
- */
-interface SurfaceKindDefinition<TCtx> {
-    kind: string;
-    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
-}
-/** The variance-erased form a registry accepts (`build` is contravariant in
- *  `TCtx`, so every concrete definition is assignable to this). */
-type AnySurfaceKind = SurfaceKindDefinition<never>;
-/**
- * Declare one surface kind. The `kind` string is the client-visible routing
- * key (e.g. `'sequences'`); `build` is the server-side factory that turns a
- * validated ctx into the overlay for one turn.
- */
-declare function defineSurfaceKind<TCtx>(opts: {
-    kind: string;
-    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
-}): SurfaceKindDefinition<TCtx>;
-/** Resolve and build the overlay for a given surface kind within a turn context */
-interface SurfaceRegistry {
-    /** Build the overlay for one turn. Throws on an unknown kind — an unknown
-     *  surface is a routing bug (client and server registries drifted), and
-     *  silently returning an empty overlay would strip the surface's tools from
-     *  the turn with no signal anywhere. Build errors propagate unwrapped. */
-    resolve(kind: string, ctx: unknown): Promise<SurfaceOverlay>;
-}
-/**
- * Assemble the product's surface registry from its registered kinds. Duplicate
- * kinds throw at construction: two builders behind one routing key would make
- * the mounted toolset depend on registration order.
- */
-declare function createSurfaceRegistry(kinds: readonly AnySurfaceKind[]): SurfaceRegistry;
-/** Base-profile slice the merge reads/writes. Real callers pass their full
- *  profile object; every field outside this slice passes through untouched. */
-interface SurfaceMergeBase {
-    mcp?: Record<string, unknown>;
-    systemPromptAddendum?: string;
-    permissions?: Record<string, SurfacePermissionValue>;
-}
-/**
- * Merge one surface overlay into a base profile, returning a new object
- * (the base is never mutated; untouched nested records are shared by
- * reference).
- *
- * - `mcp`: overlay servers are added under their own names. A name already
- *   present on the base THROWS — a collision is two servers claiming one
- *   routing name, and renaming either silently would corrupt tool routing for
- *   whichever caller expected the original binding.
- * - `systemPromptAddendum`: the overlay's `promptAddendum` appends after a
- *   blank-line separator (no separator when the base has no addendum).
- * - `permissions`: per key the STRICTER value wins (deny > ask > allow). A
- *   surface can tighten the base posture for its turns; a base 'deny' survives
- *   any overlay.
- */
-declare function mergeSurfaceOverlay<TBase extends SurfaceMergeBase>(base: TBase, overlay: SurfaceOverlay): TBase & SurfaceMergeBase;
-
-export { type AnySurfaceKind, type CertifiedDelivery, type CertifiedDeliveryConfig, type LoopEvent, type OpenAICompatServedModel, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type ResolvedAgentProfile, type SurfaceKindDefinition, type SurfaceMcpServer, type SurfaceMergeBase, type SurfaceOverlay, type SurfacePermissionValue, type SurfaceRegistry, createCertifiedDelivery, createOpenAICompatStreamTurn, createSurfaceRegistry, defineSurfaceKind, mergeSurfaceOverlay, toLoopEvents };
+export * from './model-catalog';
+export * from './model';
+export * from './openai-stream';
+export * from './agent';
+export * from './certified-delivery';
+export * from './surface-profile';
+/**
+ * The bounded agent tool-loop — the app-facing aliases of the substrate's
+ * `runToolLoop` / `streamToolLoop`, plus the app's `LoopEvent` raw-event type.
+ *
+ * These live in the leaf `./loop` so the barrel AND its children
+ * (`./agent`, `./openai-stream`) can both import the tool-loop vocabulary
+ * without an import cycle through the barrel. See `./loop` for the full
+ * rationale on the OpenAI function-calling history contract and the
+ * `reasoning` / `usage` widening.
+ */
+export * from './loop';

package/dist/runtime/loop.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The bounded agent tool-loop — owned by `@tangle-network/agent-runtime`.
+ *
+ * A model turn may emit tool calls (integration-hub actions, the app tools from
+ * `../tools`, delegation). The loop streams a turn, collects the executable tool
+ * calls, dispatches each, appends the results to history in OpenAI
+ * function-calling shape, and re-runs so the model reads them — bounded by
+ * `maxToolTurns`, a wall-clock `deadlineMs`, and a `maxCostUsd` budget.
+ *
+ * The history shape is the OpenAI function-calling contract: the assistant turn
+ * that emitted tool calls is preserved as an `assistant` message carrying its
+ * `tool_calls` array, and each result is its own `{ role: 'tool', tool_call_id,
+ * content }` message keyed to the call. A strict model (Claude, and any
+ * OpenAI-compatible provider that validates tool history) needs this to read its
+ * own tool use back; folding results into a `user` message makes such models
+ * re-issue the same call in a loop.
+ *
+ * The loop is substrate-owned (`runToolLoop` / `streamToolLoop`); the app
+ * supplies `streamTurn` (wrapping its model endpoint) and `executeToolCall`
+ * (routing to its integration + app-tool executors). The app-facing names below
+ * are 1:1 aliases of the canonical symbols, kept so this package's consumers and
+ * the in-package `createAgentRuntime` read against a single, stable vocabulary.
+ *
+ * This is the LEAF the runtime barrel and its children both import — keeping the
+ * tool-loop vocabulary out of any import cycle. The barrel re-exports it.
+ */
+export { runToolLoop as runAppToolLoop, streamToolLoop as streamAppToolLoop, } from '@tangle-network/agent-runtime/tool-loop';
+export type { ToolLoopCall as LoopToolCall, ToolLoopAssistantToolCall as LoopAssistantToolCall, ToolLoopMessage as LoopMessage, ToolLoopEvent, ToolLoopStopReason, ToolLoopResult, RunToolLoopOptions as AppToolLoopOptions, StreamToolLoopOptions as StreamAppToolLoopOptions, StreamToolLoopYield as StreamLoopYield, } from '@tangle-network/agent-runtime/tool-loop';
+/**
+ * Events the app's OpenAI-compat stream adapter ({@link toLoopEvents}) yields.
+ *
+ * This is the app's own `Raw` event type for the streaming loop — the canonical
+ * `streamToolLoop<Raw>` is generic over it. It widens the substrate's
+ * tool-loop event with `reasoning` (DeepSeek/router `reasoning_content` /
+ * `thinking` deltas, rendered as thinking sections) and `usage` (per-message
+ * token accounting) — neither belongs in the substrate's loop contract, so they
+ * stay here. The adapter maps each into the `streamTurn` seam; `text` and
+ * `tool_call` drive the loop, `reasoning` / `usage` pass through to the UI.
+ */
+export type LoopEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool_call';
+    call: import('@tangle-network/agent-runtime/tool-loop').ToolLoopCall;
+} | {
+    type: 'usage';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+} | {
+    type: 'other';
+    event: unknown;
+};

package/dist/runtime/model-catalog.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Model catalogue — computed live from the Tangle Router, never hand-curated.
+ * Lifted from tuner-agent so every agent app's model picker shares one
+ * filter/dedupe/rank/feature pipeline instead of re-deriving it.
+ *
+ * The router's /models endpoint returns every routeable model (~200), which is
+ * unusable as a picker list: it mixes chat models with TTS/embedding/realtime
+ * endpoints, dated snapshots alias their parents, and provider-prefixed ids
+ * duplicate canonical ones. This module turns that into a product catalogue:
+ *
+ *   filter (chat-capable, routeable) → dedupe (snapshot/prefix/:free aliases)
+ *   → rank (provider tier, family, version) → feature (best model per family)
+ *   → default (env override or first featured)
+ *
+ * Freshness is automatic: everything is derived from the live router response,
+ * so new models surface as soon as the router lists them. The only static
+ * knowledge here is slow-moving: provider display order and family name
+ * patterns (e.g. "claude-sonnet-*", "gpt-N"). A new Sonnet or GPT release
+ * outranks its predecessor by version comparison with zero code change; only
+ * a brand-new *family name* (rare) needs a one-line rule addition.
+ */
+export interface RouterModel {
+    id: string;
+    name?: string;
+    description?: string;
+    _provider?: string;
+    pricing?: {
+        prompt?: string | null;
+        completion?: string | null;
+    };
+    context_length?: number;
+    architecture?: {
+        modality?: string;
+        input_modalities?: string[];
+        output_modalities?: string[];
+    };
+    supported_parameters?: string[];
+    routeability?: {
+        status?: string;
+        routeable?: boolean;
+        provider?: string;
+    };
+}
+/** Define the structure and capabilities of a catalog item with optional pricing and feature flags */
+export interface CatalogModel {
+    id: string;
+    name: string;
+    provider: string;
+    description?: string;
+    contextLength?: number;
+    pricing?: {
+        prompt?: string;
+        completion?: string;
+    };
+    supportsTools: boolean;
+    supportsReasoning: boolean;
+    featured: boolean;
+}
+/** Define a catalog containing models with a default ID and fetch timestamp */
+export interface ModelCatalog {
+    defaultModelId: string | null;
+    fetchedAt: string;
+    models: CatalogModel[];
+}
+/** Strip provider prefix, :free suffix, and trailing date stamps. */
+export declare function normalizeModelId(id: string): string;
+/**
+ * Can this router entry serve a text chat turn?
+ *
+ * The router lists every routeable endpoint, which is not the same list a chat
+ * picker should show: measured against the live catalogue (504 entries), this
+ * rejects 35 — image generators, TTS voices, embedding models, and the
+ * audio-IN transcription endpoints (`whisper-1`, `gpt-4o-transcribe`, …) that
+ * emit text but cannot take a text prompt.
+ *
+ * A model whose metadata omits either modality list is KEPT. The router is the
+ * source of that metadata and it is occasionally sparse; dropping a usable
+ * model because a field is missing is the worse failure of the two.
+ *
+ * Exported because a picker needs the same answer `buildCatalog` uses — the
+ * fleet had this predicate copied into a product component, where its narrower
+ * spelling let the 10 transcription endpoints through.
+ */
+export declare function isChatCapableModel(m: RouterModel): boolean;
+/**
+ * Pure catalogue pipeline. `preferredDefault` (typically the MODEL_NAME env
+ * var) wins when it survives filtering; otherwise the first featured model.
+ */
+export declare function buildCatalog(raw: RouterModel[], opts?: {
+    preferredDefault?: string;
+}): ModelCatalog;
+/**
+ * Fetch the router model list and build the catalogue, with an in-isolate
+ * cache (TTL 5 min). On router failure a stale catalogue is served rather
+ * than erroring the picker.
+ */
+export declare function fetchModelCatalog(cfg: {
+    baseUrl: string;
+    apiKey: string;
+    preferredDefault?: string;
+}): Promise<ModelCatalog>;
+/** Test-only: clear the catalogue cache. */
+export declare function __resetCatalogCache(): void;