indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/types/channels/link/dialog.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Dialog bridge — the ask / tell seam over the link transport.
+ *
+ * The agent (and the extensions it hosts) needs to interact with whoever drives
+ * the channel: ask a multiple-choice question, confirm a destructive action,
+ * prompt for free text, flash a notice, set a status line. Rather than a
+ * per-interaction handler ladder, the whole surface reduces to two primitives:
+ *
+ *   - {@link DialogBridge.ask} — one generic round-trip: emit an {@link Ask}
+ *     frame, suspend until a correlated {@link AskAnswer} arrives, and resolve
+ *     with its value (or a caller-supplied fallback when the deadline lapses or
+ *     the driver dismisses the request).
+ *   - {@link DialogBridge.tell} — one generic fire-and-forget: emit a {@link Tell}
+ *     frame and return immediately.
+ *
+ * Concrete dialog methods (select / confirm / input / notify / status / title)
+ * are expressed as a *data table* of named entries keyed by interaction kind, not
+ * as bespoke method bodies. {@link makeDialogMethods} closes that table over a
+ * single bridge so a caller gets typed conveniences while the bridge keeps the
+ * lone round-trip / fire-and-forget implementation.
+ */
+import type { AskAnswer, ChannelTimings, DialogBridge, NdjsonFramer, WritableLine } from "../contract";
+/** Everything {@link createDialogBridge} needs to emit frames and time out. */
+export interface DialogBridgeDeps {
+    /** Sink the ask/tell frames are written to (already framed). */
+    readonly out: WritableLine;
+    /** Framer used to encode each frame to a line. */
+    readonly framer: NdjsonFramer;
+    /** Timings; only {@link ChannelTimings.dialogMs} is consulted here. */
+    readonly timings: ChannelTimings;
+}
+/**
+ * A {@link DialogBridge} whose pending answers are fed by an external reader.
+ *
+ * The bridge itself does not read the stream — the server owns the single
+ * decode loop and routes any inbound {@link AskAnswer} frame to
+ * {@link LinkedDialogBridge.deliver}. This keeps one reader over the transport
+ * (the server) rather than competing consumers.
+ */
+export interface LinkedDialogBridge extends DialogBridge {
+    /**
+     * Resolve the pending {@link DialogBridge.ask} that minted `answer.id`.
+     *
+     * A no-op when no ask is pending under that id (a late or duplicate answer),
+     * so a misbehaving driver cannot throw into the read loop.
+     *
+     * @param answer the inbound answer frame
+     * @returns whether a pending ask was settled by this answer
+     */
+    deliver(answer: AskAnswer): boolean;
+    /**
+     * Reject every still-pending ask with its fallback (used on shutdown), so no
+     * awaiting handler is left suspended when the link closes.
+     */
+    drain(): void;
+}
+/**
+ * Construct a {@link LinkedDialogBridge} over an injected sink + framer.
+ *
+ * `ask` writes an {@link Ask} frame, registers the pending resolver under a
+ * fresh id, and arms a fallback timer; `deliver` settles the matching pending
+ * resolver when the answer returns. `tell` writes a {@link Tell} frame and
+ * returns at once. No stdio, no global state — every dependency is injected.
+ */
+export declare function createDialogBridge(deps: DialogBridgeDeps): LinkedDialogBridge;
+/**
+ * One concrete dialog method expressed as data, not code.
+ *
+ * `kind` is the wire interaction kind; `mode` selects which primitive carries
+ * it (a round-trip `ask` or a fire-and-forget `tell`); `fallback` is the value a
+ * round-trip resolves with on timeout / dismissal (unused for `tell`). The whole
+ * dialog surface is this table — adding an interaction is adding a row.
+ */
+export interface DialogSpec {
+    /** The wire interaction kind (the `Ask.kind` / `Tell.kind`). */
+    readonly kind: string;
+    /** Whether the method round-trips for an answer or is fire-and-forget. */
+    readonly mode: "ask" | "tell";
+    /** The value an `ask` resolves with when no answer arrives in time. */
+    readonly fallback?: unknown;
+}
+/**
+ * The canonical dialog table: every concrete interaction the channel exposes,
+ * each one row of data over the two primitives.
+ *
+ * Replaces a copied switch of bespoke UI-context methods: the bridge has exactly
+ * one round-trip and one fire-and-forget body, and this table names the kinds.
+ */
+export declare const DIALOG_TABLE: Readonly<{
+    select: {
+        kind: string;
+        mode: "ask";
+        fallback: null;
+    };
+    confirm: {
+        kind: string;
+        mode: "ask";
+        fallback: boolean;
+    };
+    input: {
+        kind: string;
+        mode: "ask";
+        fallback: null;
+    };
+    editor: {
+        kind: string;
+        mode: "ask";
+        fallback: null;
+    };
+    notify: {
+        kind: string;
+        mode: "tell";
+    };
+    status: {
+        kind: string;
+        mode: "tell";
+    };
+    title: {
+        kind: string;
+        mode: "tell";
+    };
+}>;
+/** The set of named dialog methods derived from {@link DIALOG_TABLE}. */
+export type DialogMethods = {
+    [K in keyof typeof DIALOG_TABLE]: (typeof DIALOG_TABLE)[K]["mode"] extends "ask" ? (payload?: unknown) => Promise<unknown> : (payload?: unknown) => void;
+};
+/**
+ * Close the {@link DIALOG_TABLE} over one {@link DialogBridge} into typed,
+ * named convenience methods.
+ *
+ * Each `ask` row becomes a thunk that round-trips through `bridge.ask` with the
+ * row fallback; each `tell` row becomes a thunk that fires through `bridge.tell`.
+ * There is no per-method choreography — the bodies are generated from the table.
+ *
+ * @param bridge the round-trip / fire-and-forget primitive pair
+ * @returns the named method object projected from the table
+ */
+export declare function makeDialogMethods(bridge: DialogBridge): DialogMethods;

package/dist/types/channels/link/driver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Link driver — the generated client over the JSON-RPC link.
+ *
+ * The driver is the mirror of the server: it writes framed requests and reads
+ * framed replies. Crucially it is *generated*, not hand-written — there is no
+ * per-op client method. A {@link Proxy} turns any property access into a thunk
+ * that frames `{ id, method, params } -> awaits { id, result | error }`, so the
+ * driver satisfies the {@link LinkDriver} type projected from a registry with a
+ * single body. Adding an op to the registry adds a callable method to the driver
+ * for free.
+ *
+ * The driver owns the single reader over the inbound stream. Every decoded frame
+ * is one of: a correlated {@link Reply} (settles the pending request under its
+ * id), an uncorrelated {@link Signal} (fanned out to subscribers), or an
+ * {@link Ask} (handed to an answerer that posts an {@link AskAnswer} back). One
+ * reader, three routes — no competing consumers of the transport.
+ */
+import { type Ask, type ChannelTimings, type LinkDriver, type NdjsonFramer, type OpError, type OpRegistry, type ReadableChunks, type Signal, type WritableLine } from "../contract";
+/** The injectable transport pair the driver writes to and reads from. */
+export interface LinkDriverIo {
+    /** Sink the driver writes framed requests to (defaults to the child stdin). */
+    readonly out: WritableLine;
+    /** Source the driver reads framed replies / signals from (defaults to child stdout). */
+    readonly in: ReadableChunks;
+}
+/** Optional overrides for a driver: a framer, the timings, and hooks. */
+export interface LinkDriverConfig {
+    /** Override the NDJSON framer (defaults to the shared one). */
+    readonly framer?: NdjsonFramer;
+    /** Override any subset of the channel timings. */
+    readonly timings?: Partial<ChannelTimings>;
+    /** Invoked for every uncorrelated {@link Signal} the server streams. */
+    readonly onSignal?: (signal: Signal) => void;
+    /**
+     * Invoked when the server asks a question; returns the answer value. When
+     * omitted the driver dismisses every ask (posts `null`), so a non-interactive
+     * driver never wedges the server.
+     */
+    readonly onAsk?: (ask: Ask) => unknown | Promise<unknown>;
+}
+/** A failed reply turned into a throwable error that carries the wire code. */
+export declare class LinkRequestError extends Error {
+    /** The JSON-RPC error code from the {@link OpError}. */
+    readonly code: number;
+    /** The structured detail, when the server supplied any. */
+    readonly data: unknown;
+    constructor(error: OpError);
+}
+/**
+ * A live driver: the generated client plus its lifecycle.
+ *
+ * `client` is the {@link Proxy} typed as a {@link LinkDriver} for the registry
+ * `Ops`; `done` resolves when the inbound stream ends; `close` rejects every
+ * still-pending request and stops the reader.
+ *
+ * @typeParam Ops the {@link OpRegistry} the client type is projected from
+ */
+export interface LinkDriverHandle<Ops extends OpRegistry> {
+    /** The generated, registry-typed client. */
+    readonly client: LinkDriver<Ops>;
+    /** Resolves when the reader loop drains (the inbound stream ended). */
+    readonly done: Promise<void>;
+    /** Reject all pending requests with `reason` and stop accepting replies. */
+    close(reason?: string): void;
+}
+/**
+ * Build a {@link LinkDriverHandle} over an injected transport.
+ *
+ * The returned `client` is a {@link Proxy}: reading property `m` yields a thunk
+ * `(params?) => Promise<result>` that mints an id (prefixed with
+ * {@link REQUEST_ID_PREFIX}), writes the framed request, and resolves when the
+ * matching {@link Reply} arrives (or rejects on a {@link ReplyErr} or timeout).
+ * No method is hand-written; the registry type parameter only shapes the static
+ * face. The reader loop classifies inbound frames into replies, signals, and
+ * asks and routes each.
+ *
+ * @typeParam Ops the registry whose method set types the client
+ * @param io     the injected request sink + reply source
+ * @param config optional framer / timing / hook overrides
+ */
+export declare function createLinkDriver<Ops extends OpRegistry = OpRegistry>(io: LinkDriverIo, config?: LinkDriverConfig): LinkDriverHandle<Ops>;

package/dist/types/channels/link/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Link channel — public barrel.
+ *
+ * The link channel is the long-lived, bidirectional half of the channels
+ * subsystem: a JSON-RPC 2.0 server that dispatches framed requests through an
+ * {@link OpRegistry} (`server.ts`), a generated {@link LinkDriver} client built
+ * from a {@link Proxy} rather than hand-written methods (`driver.ts`), and the
+ * ask / tell dialog bridge that both ends share (`dialog.ts`). Consumers import
+ * the link surface from `src/channels/link` rather than the individual modules.
+ */
+export { createLinkServer, type LinkServer, type LinkServerIo, type LinkServerConfig, } from "./server";
+export { createLinkDriver, LinkRequestError, type LinkDriverHandle, type LinkDriverIo, type LinkDriverConfig, } from "./driver";
+export { createDialogBridge, makeDialogMethods, DIALOG_TABLE, type LinkedDialogBridge, type DialogBridgeDeps, type DialogSpec, type DialogMethods, } from "./dialog";

package/dist/types/channels/link/server.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Link server — the data-driven JSON-RPC 2.0 dispatch loop.
+ *
+ * The server owns the single reader over the inbound stream. For each framed
+ * line it decides what the frame is and routes it: a request frame is dispatched
+ * through the {@link OpRegistry} (a map lookup, not a command switch) and its
+ * outcome is framed back as a {@link Reply}; an inbound {@link AskAnswer} frame
+ * is routed to the {@link DialogBridge} to settle a suspended `ask`. One round of
+ * the protocol is `{ id, method, params } -> { id, result | error }`.
+ *
+ * Everything that touches the outside world is injected: the request source, the
+ * reply sink, the framer, and the conductor all arrive through the context and
+ * options, so a test serves the link over an in-memory pipe pair with no stdio.
+ * The dispatch itself is delegated to {@link dispatch} from the ops module, so
+ * the server holds no per-method knowledge.
+ */
+import { type ChannelTimings, type NdjsonFramer, type OpRegistry, type ReadableChunks, type SessionConductor, type WritableLine } from "../contract";
+import { type LinkedDialogBridge } from "./dialog";
+/**
+ * The injectable transport pair the server reads from and writes to.
+ *
+ * Named `io` at the call site; bundles the inbound request source and the
+ * outbound reply/signal sink so tests pass in-memory pipes and production passes
+ * stdin / stdout.
+ */
+export interface LinkServerIo {
+    /** Framed inbound request / answer lines (defaults to stdin). */
+    readonly in: ReadableChunks;
+    /** Framed outbound reply / signal / dialog sink (defaults to stdout). */
+    readonly out: WritableLine;
+}
+/** Optional overrides for a server: a framer and the timings. */
+export interface LinkServerConfig {
+    /** Override the NDJSON framer (defaults to the shared one). */
+    readonly framer?: NdjsonFramer;
+    /** Override any subset of the channel timings. */
+    readonly timings?: Partial<ChannelTimings>;
+}
+/** A running server: a promise that settles when the inbound stream ends. */
+export interface LinkServer {
+    /** Resolves when the request stream is exhausted and the loop has drained. */
+    readonly done: Promise<void>;
+    /** The dialog bridge the running server feeds inbound answers to. */
+    readonly dialog: LinkedDialogBridge;
+}
+/**
+ * Start a link server over an op registry, a conductor, and an injected
+ * transport.
+ *
+ * Builds the shared {@link ChannelContext} (conductor + framer + the freshly
+ * wired {@link DialogBridge}), then consumes the inbound stream with a single
+ * `for await` loop. Each frame is classified:
+ *
+ *   - an answer frame is delivered to the dialog bridge;
+ *   - a request frame is dispatched through `registry`; a request carrying an
+ *     `id` gets exactly one correlated reply (result or error); a notification
+ *     (no `id`) is dispatched for its effect and never replied to;
+ *   - any other frame is ignored (a forward-compatible no-op).
+ *
+ * Parse failures from the framer surface as a thrown error in the loop and are
+ * framed as a {@link OP_ERROR.parse} reply with no id (the offending frame had
+ * none to correlate).
+ *
+ * @param registry the frozen {@link OpRegistry} that drives dispatch
+ * @param conductor the session every op delegates to
+ * @param io        the injected request source + reply sink
+ * @param config    optional framer / timing overrides
+ * @returns a handle whose `done` resolves when the inbound stream ends
+ */
+export declare function createLinkServer(registry: OpRegistry, conductor: SessionConductor, io: LinkServerIo, config?: LinkServerConfig): LinkServer;

package/dist/types/channels/oneshot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Oneshot channel — a single non-interactive run to settlement.
+ *
+ * Replaces the print mode. Given a {@link ChannelContext} and an
+ * {@link OneshotRequest}, it submits every prompt to the conductor in order,
+ * streams the answer to the channel sink, and resolves a process exit code.
+ *
+ * The shape (clean final text vs a streamed NDJSON event log) is chosen by
+ * selecting an {@link OneshotStrategy} object rather than branching on a flag
+ * through the runner body: each strategy supplies an optional `onStart`, an
+ * optional `onSignal`, and a mandatory `finish` that turns the settled state
+ * into the exit code. The runner itself is shape-agnostic — it subscribes the
+ * strategy to the conductor signal stream, runs the prompts, and hands the final
+ * state to `finish`.
+ */
+import type { ChannelContext, DialogBridge, OneshotRequest } from "./contract";
+/**
+ * A dialog bridge for a non-interactive oneshot run: no driver is attached to
+ * answer a question, so every `ask` resolves immediately with its caller-supplied
+ * fallback and every `tell` is dropped. Keeps the agent from wedging on a prompt
+ * during a headless single run while never writing dialog frames to the sink.
+ */
+export declare const inertDialog: DialogBridge;
+/**
+ * Run one non-interactive request to settlement.
+ *
+ * Selects the {@link OneshotStrategy} for `opts.shape`, subscribes it to the
+ * conductor signal stream, runs `onStart`, then submits each prompt in order and
+ * awaits its settlement. The state from the final prompt is handed to the
+ * strategy's `finish`, whose return value is the resolved exit code. The
+ * subscription is always torn down before returning.
+ *
+ * @param ctx  the channel context (conductor, sink, framer, dialog) — fully injected
+ * @param opts the request: output shape, the prompts to run, and any images
+ * @returns the process exit code (0 on a clean settlement, 1 on a fault)
+ */
+export declare function runOneshot(ctx: ChannelContext, opts: OneshotRequest): Promise<number>;

package/dist/types/channels/ops.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Operation registry — the single declarative source both halves of the link
+ * consume.
+ *
+ * The contract defines {@link defineOps} (freeze a record of {@link Op}s into an
+ * {@link OpRegistry}) and the {@link LinkDriver} type projected from a registry.
+ * This module adds the runtime face the server needs and the driver leans on: a
+ * built registry carries its `methods` list (so a {@link LinkDriver} can be
+ * generated by walking the keys, never hand-written) and a `dispatch` seam that
+ * looks an op up by `method` and runs its `handle` — the data-driven replacement
+ * for a copied command switch.
+ *
+ * Nothing here knows about transport or framing: dispatch takes the already
+ * parsed `method`/`params` and the shared {@link ChannelContext}, runs the op,
+ * and returns its resolved result (or throws {@link UnknownOpError} when no op is
+ * registered). The server frames the outcome into a {@link Reply}; the driver
+ * uses `methods` to build its thunks. One frozen registry drives both.
+ */
+import { defineOps } from "./contract";
+import type { ChannelContext, Op, OpRegistry } from "./contract";
+/** Re-exported so consumers mint registries from one module. */
+export { defineOps };
+/**
+ * Thrown by {@link dispatch} (and {@link OpRegistryHandle.dispatch}) when the
+ * requested `method` has no registered {@link Op}.
+ *
+ * Carries the frozen {@link OP_ERROR.unknownOp} code so the server can frame it
+ * into a {@link ReplyErr} without re-deriving the category, and records the
+ * offending `method` for logging.
+ */
+export declare class UnknownOpError extends Error {
+    /** The JSON-RPC error category for an unregistered method. */
+    readonly code: number;
+    /** The method name that resolved to no operation. */
+    readonly method: string;
+    constructor(method: string);
+}
+/**
+ * Run one operation by name against the shared context.
+ *
+ * Looks `method` up in `registry`, then awaits its `handle(params, ctx)`. The
+ * lone dispatch path for the server: there is no per-method branch, only a map
+ * lookup. Throws {@link UnknownOpError} when the method is not registered and
+ * propagates whatever the handler throws (the server maps that to a
+ * {@link ReplyErr}).
+ *
+ * @param registry the frozen {@link OpRegistry} to dispatch within
+ * @param method   the wire method name to invoke
+ * @param params   the already-parsed request payload (passed through verbatim)
+ * @param ctx      the shared {@link ChannelContext}
+ * @returns the operation result
+ */
+export declare function dispatch(registry: OpRegistry, method: string, params: unknown, ctx: ChannelContext): Promise<unknown>;
+/** Whether `method` resolves to a registered {@link Op} in `registry`. */
+export declare function hasOp(registry: OpRegistry, method: string): boolean;
+/** The sorted wire method names a registry exposes — the driver's method set. */
+export declare function methodsOf<T extends OpRegistry>(registry: T): ReadonlyArray<keyof T & string>;
+/**
+ * A built registry plus its runtime face: the method list and a bound
+ * `dispatch`.
+ *
+ * `methods` is what a generated {@link LinkDriver} walks to build its thunks;
+ * `dispatch` is what the server calls per request. Both are bound to the one
+ * frozen `registry`, so the server-side dispatch and the client-side method set
+ * can never drift from each other.
+ *
+ * @typeParam T the concrete registry shape (preserved for the generated driver)
+ */
+export interface OpRegistryHandle<T extends OpRegistry> {
+    /** The frozen registry — the single source of truth. */
+    readonly registry: T;
+    /** The sorted method names this registry exposes. */
+    readonly methods: ReadonlyArray<keyof T & string>;
+    /** Invoke an op by name against `ctx`; see {@link dispatch}. */
+    dispatch(method: string, params: unknown, ctx: ChannelContext): Promise<unknown>;
+}
+/**
+ * Build an {@link OpRegistryHandle} from a record of operation declarations.
+ *
+ * Freezes the input with {@link defineOps}, then bundles it with its derived
+ * method list and a `dispatch` bound to that frozen registry. This is the lone
+ * sanctioned way to produce the object the server and the driver both consume,
+ * so the dispatch map and the driver method set always derive from one source.
+ *
+ * @param ops a record of method-name → {@link Op}
+ * @returns the frozen registry handle, with the input's exact key/value types
+ *          preserved for the generated {@link LinkDriver}
+ */
+export declare function buildOps<T extends Record<string, Op<any, any>>>(ops: T): OpRegistryHandle<Readonly<T>>;

package/dist/types/channels/session-ops.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Session ops — the concrete operation registry that drives the link.
+ *
+ * This is the single declarative source of every operation the link server
+ * dispatches and the {@link LinkDriver} client is generated from. Each op binds a
+ * wire `method` name to a `handle` that delegates to the {@link SessionConductor}
+ * carried on the {@link ChannelContext}; there is no per-method dispatch ladder
+ * and no hand-written parallel client method. Adding a row here adds both a
+ * server-handled method and a callable driver method.
+ *
+ * The ops also own the {@link LinkSnapshot} projection: the conductor exposes its
+ * internal {@link ConductorState}, and {@link projectSnapshot} reshapes that into
+ * the flat, serializable wire vocabulary a remote driver mirrors without holding
+ * a live conductor.
+ */
+import type { ConductorState, LinkSnapshot, Op, ThinkingLevel } from "./contract";
+/**
+ * Project a conductor {@link ConductorState} onto the wire {@link LinkSnapshot}.
+ *
+ * The snapshot is the link vocabulary: flat, serializable, and derived from — not
+ * a passthrough of — the conductor state. Busy flags are read off the coarse
+ * phase, the model and session identity off the state and its head, and the
+ * cumulative usage carried straight through.
+ *
+ * @param state the immutable conductor state
+ * @param extra optional fields the conductor does not surface on its state
+ */
+export declare function projectSnapshot(state: ConductorState, extra?: {
+    readonly thinking?: ThinkingLevel;
+    readonly sessionFile?: string;
+    readonly autoCondense?: boolean;
+    readonly messageCount?: number;
+    readonly queuedCount?: number;
+}): LinkSnapshot;
+/** Parameters for the {@link sessionOps.submit} op. */
+export interface SubmitParams {
+    /** The user message text for this turn. */
+    readonly input: string;
+}
+/** Parameters for the {@link sessionOps.resume} op. */
+export interface ResumeParams {
+    /** The persisted session to restore. */
+    readonly sessionId: string;
+}
+/** Parameters for the {@link sessionOps.cycleModel} op. */
+export interface CycleModelParams {
+    /** Canonical id of the model to switch to. */
+    readonly modelId: string;
+}
+/** One model entry returned by the {@link sessionOps.listModels} op. */
+export interface ModelEntry {
+    /** Canonical model id. */
+    readonly id: string;
+    /** Whether this is the model currently bound to the session. */
+    readonly active: boolean;
+}
+/**
+ * The frozen link op set: every operation a driver can invoke, each delegating
+ * to the conductor on the context.
+ *
+ *   - `submit`     — run a user turn to settlement and reply with a snapshot.
+ *   - `abort`      — cancel the in-flight turn and reply with a snapshot.
+ *   - `snapshot`   — read the current state, projected to a {@link LinkSnapshot}.
+ *   - `resume`     — restore a persisted session and reply with a snapshot.
+ *   - `listModels` — list the model bound to the session (the active entry).
+ *   - `cycleModel` — rotate the active model and reply with a snapshot.
+ *
+ * The map is consumed verbatim by the server (data-driven dispatch) and by the
+ * generated {@link LinkDriver} (its method set is exactly these keys).
+ */
+export declare const SESSION_OPS: Readonly<{
+    submit: Op<SubmitParams, LinkSnapshot>;
+    abort: Op<void, LinkSnapshot>;
+    snapshot: Op<void, LinkSnapshot>;
+    resume: Op<ResumeParams, LinkSnapshot>;
+    listModels: Op<void, readonly ModelEntry[]>;
+    cycleModel: Op<CycleModelParams, LinkSnapshot>;
+}>;
+/** The concrete op-set type, for typing a {@link LinkDriver} over this surface. */
+export type SessionOps = typeof SESSION_OPS;

package/dist/types/conductor/catalog/catalog.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Model catalog — `ModelCatalog`.
+ *
+ * A transform pipeline over the framework model list. The framework publishes
+ * its catalog per provider via `getModels(provider)` from `indusagi/ai`; each
+ * entry is a rich {@link Model} record. This module **re-derives** that data
+ * into the conductor's own normalized shape — a {@link CatalogCard} — through a
+ * validate → normalize → key pipeline, then exposes a small lookup surface
+ * (`all`, `byProvider`, `get`) keyed by a canonical `"provider/modelId"` id.
+ *
+ * This replaces pi's `model-registry` / `ModelRegistry`. It is intentionally
+ * *not* a re-export of the framework registry: the field order and shape are
+ * the conductor's, the data is run back through a zod gate, and the public
+ * methods read differently. The full framework {@link Model} is retained on each
+ * card so the conductor can hand a complete model object to the agent without a
+ * second registry round-trip.
+ */
+import { type KnownProvider, type Model } from "indusagi/ai";
+import type { ModelCardRef } from "../contract";
+/**
+ * One normalized entry in the catalog.
+ *
+ * Extends the lightweight {@link ModelCardRef} identity projection with the
+ * extra capability facets the matcher filters on, plus the original framework
+ * {@link Model}. `ref` is the slice a UI lists/labels with; `model` is the full
+ * record the conductor binds to the agent.
+ */
+export interface CatalogCard {
+    /** Canonical `"provider/modelId"` identifier — the catalog key. */
+    readonly id: string;
+    /** Owning provider slug. */
+    readonly provider: KnownProvider | string;
+    /** Provider-scoped model id (e.g. `"claude-sonnet-4"`). */
+    readonly modelId: string;
+    /** Human-readable display name. */
+    readonly name: string;
+    /** Whether the model exposes a reasoning/thinking budget. */
+    readonly reasoning: boolean;
+    /** Whether the model accepts image input. */
+    readonly acceptsImages: boolean;
+    /** Context window size in tokens (0 when the framework omits it). */
+    readonly contextTokens: number;
+    /** The framework model record, retained verbatim for binding. */
+    readonly model: Model<Model<string>["api"]>;
+}
+/** Project a {@link CatalogCard} down to its public {@link ModelCardRef} slice. */
+export declare function toCardRef(card: CatalogCard): ModelCardRef;
+/** Compose the canonical catalog key from a provider + model id. */
+export declare function canonicalId(provider: string, modelId: string): string;
+/** Injection seam for tests: how the catalog sources its raw data. */
+export interface CatalogSource {
+    /** Enumerate the providers to scan. */
+    readonly providers: () => readonly (KnownProvider | string)[];
+    /** Pull the raw model list for one provider. */
+    readonly models: (provider: string) => readonly Model<string>[];
+}
+/**
+ * A normalized, validated view of the framework model list.
+ *
+ * Construct once (the build pipeline runs eagerly in the constructor) and query
+ * many times. The instance is immutable after construction; call
+ * {@link ModelCatalog.refreshed} to rebuild against the current framework state.
+ */
+export declare class ModelCatalog {
+    #private;
+    /**
+     * @param source raw-data seam; defaults to the live `indusagi/ai` registry.
+     */
+    constructor(source?: CatalogSource);
+    /** Total number of cards in the catalog. */
+    get size(): number;
+    /** Every card, in insertion order (provider scan order). */
+    all(): readonly CatalogCard[];
+    /** Cards owned by one provider (empty array if the provider has none). */
+    byProvider(provider: KnownProvider | string): readonly CatalogCard[];
+    /** The providers that contributed at least one card, in scan order. */
+    providers(): readonly string[];
+    /**
+     * Look up one card by its canonical `"provider/modelId"` id. Also accepts a
+     * bare provider-scoped model id when it is unambiguous across providers.
+     */
+    get(id: string): CatalogCard | undefined;
+    /** True when the canonical id resolves to a card. */
+    has(id: string): boolean;
+    /** Rebuild against the current framework state, returning a fresh catalog. */
+    refreshed(source?: CatalogSource): ModelCatalog;
+}

package/dist/types/conductor/catalog/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Model catalog subsystem — public barrel.
+ *
+ * Bundles the {@link ModelCatalog} (a normalized, validated transform over the
+ * framework model list) and the {@link ModelMatcher} (a scored-candidate query
+ * resolver). Consumers import both — plus the {@link CatalogCard} shape and the
+ * `canonicalId` / `toCardRef` helpers — from `src/conductor/catalog` rather than
+ * reaching into the individual modules.
+ *
+ * This pairing replaces pi's `model-registry` + `model-resolver`; the catalog
+ * key, card shape, and resolution algorithm are all the conductor's own.
+ */
+export { ModelCatalog, canonicalId, toCardRef, type CatalogCard, type CatalogSource, } from "./catalog";
+export { ModelMatcher, type ResolveInput, } from "./matcher";

package/dist/types/conductor/catalog/matcher.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Model matcher — `ModelMatcher`.
+ *
+ * A scored-candidate resolver over a {@link ModelCatalog}. Given a free-form
+ * query (a string, or a structured {@link MatchQuery}), it produces the single
+ * best-matching {@link ModelCardRef}, or `undefined` when nothing clears the bar.
+ *
+ * It is an independent implementation: resolution is a *prioritized scoring
+ * pipeline*, not a chain of single-purpose match helpers with recursive
+ * colon-splitting. Each candidate card is scored against the query by a set of
+ * independent strategy probes (exact-canonical, exact-id, provider-prefix,
+ * alias-substring, glob), the capability filters gate the field, and the highest
+ * scorer (with deterministic tie-breaks) wins. Every helper name here is fresh.
+ */
+import type { MatchQuery, ModelCardRef } from "../contract";
+import { type CatalogCard, type ModelCatalog } from "./catalog";
+/** Either a raw selector string or the structured {@link MatchQuery}. */
+export type ResolveInput = string | MatchQuery;
+/**
+ * Resolves model queries against a {@link ModelCatalog} by scored candidates.
+ *
+ * Construct once with a catalog, then call {@link ModelMatcher.resolve} per
+ * query. The matcher holds no mutable state; it is safe to share.
+ */
+export declare class ModelMatcher {
+    #private;
+    constructor(catalog: ModelCatalog);
+    /**
+     * Resolve a query to the single best {@link ModelCardRef}, or `undefined`.
+     *
+     * Pipeline:
+     *   1. lift the input to a {@link MatchQuery};
+     *   2. honor an explicit `provider`+`modelId` *pin* (highest tier) up front;
+     *   3. gate every card through {@link clearsConstraints};
+     *   4. with no pattern, return the leading surviving candidate (default pick);
+     *   5. otherwise score each survivor via {@link probePattern} + {@link tieBonus}
+     *      and return the top scorer (deterministic tie-break by tier, bonus, id).
+     */
+    resolve(input: ResolveInput): ModelCardRef | undefined;
+    /** As {@link resolve}, but returns the full {@link CatalogCard}. */
+    resolveCard(input: ResolveInput): CatalogCard | undefined;
+    /**
+     * Resolve, returning *all* surviving candidates ranked best-first (the field
+     * a "did you mean" picker would show). Useful for ambiguous selectors.
+     */
+    resolveAll(input: ResolveInput): readonly ModelCardRef[];
+}