instar 0.28.113 → 0.28.115

package/dist/providers/primitives/transport/warmSessionInbox.js

@@ -0,0 +1,33 @@
+/**
+ * WarmSessionInbox — long-lived agent session, file-based message inbox.
+ *
+ * A persistent agent process that receives messages via a file-system
+ * inbox and processes them sequentially. The session lives across many
+ * messages, retaining context and warm state.
+ *
+ * Used for:
+ *   - Threadline's ListenerSessionManager (long-lived listener for
+ *     incoming agent messages)
+ *   - Interactive-pool fallback path (Phase 3b) — N long-lived `claude`
+ *     REPLs in tmux, work routed through them to draw from subscription
+ *     rather than Agent SDK credit pot
+ *   - Future: any "always-on agent" pattern
+ *
+ * Maps to:
+ *   - Claude: long-lived REPL in tmux + tmux send-keys for prompt injection
+ *   - Codex: long-lived `codex remote-control` + `turn/steer` JSON-RPC
+ *
+ * Inbox file format is provider-agnostic (JSONL with `{message, fromAgent,
+ * timestamp}` entries). The adapter polls the inbox or uses a wake signal
+ * (socket) to detect new messages.
+ *
+ * Lifecycle:
+ *   1. start(options) → spawn the session, return handle
+ *   2. send(handle, message) → append to inbox, agent picks it up
+ *   3. session emits events as it processes
+ *   4. session may be retired when capacity threshold reached
+ *      (compaction risk, message count limit, idle timeout)
+ *   5. retire(handle) → graceful shutdown
+ */
+export {};
+//# sourceMappingURL=warmSessionInbox.js.map

package/dist/providers/primitives/transport/warmSessionInbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmSessionInbox.js","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/warmSessionInbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/providers/registry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Registry — runtime adapter discovery and selection.
+ *
+ * The single point of access for application code that needs a provider.
+ * Adapters register themselves on startup; consumers query by capability
+ * and receive an adapter that can satisfy the request.
+ *
+ * Design:
+ *   - Adapters declare their capabilities up front (no late binding).
+ *   - The registry stores adapters keyed by ProviderId.
+ *   - `resolve()` returns the first adapter matching a capability set,
+ *     or the adapter chosen by an injected `RoutingPolicy`.
+ *   - All resolution is synchronous once adapters are registered;
+ *     registration is async to allow adapters to do setup at register time.
+ */
+import type { ProviderId } from './types.js';
+import type { CapabilityFlag, CapabilitySet } from './capabilities.js';
+import type { RoutingPolicy } from './routing.js';
+/**
+ * Adapter registration record. Adapters implement this contract by
+ * exporting a factory that produces one of these.
+ */
+export interface ProviderAdapter {
+    /** Stable identifier for this adapter. */
+    readonly id: ProviderId;
+    /** Capabilities this adapter supports. */
+    readonly capabilities: CapabilitySet;
+    /**
+     * Optional self-test the registry can run during registration to
+     * validate the adapter is healthy. Resolves on success; rejects with
+     * a ProviderError on failure (the registration is rejected).
+     */
+    readonly selfTest?: () => Promise<void>;
+    /** Optional cleanup hook called when the adapter is unregistered. */
+    readonly dispose?: () => Promise<void>;
+    /**
+     * Get the implementation of a specific primitive by capability flag.
+     * Returns undefined if the capability isn't supported. Callers should
+     * check `capabilities` first or use the registry's `resolve()`.
+     *
+     * The type of the returned implementation is provider-specific; callers
+     * cast at the use site (or use the higher-level helpers below).
+     */
+    readonly primitive: (capability: CapabilityFlag) => unknown;
+}
+export interface ResolveRequest {
+    /** Capabilities the caller requires. */
+    requires: ReadonlyArray<CapabilityFlag>;
+    /**
+     * Optional capabilities (preferred if available, but not required).
+     * Used by the routing policy to break ties.
+     */
+    prefers?: ReadonlyArray<CapabilityFlag>;
+    /**
+     * Optional adapter id pin. If set, only that adapter is considered.
+     * Throws UnsupportedCapabilityError if pinned adapter is missing
+     * required capabilities.
+     */
+    pinTo?: ProviderId;
+    /**
+     * Optional context for the routing policy (cost preference, quota
+     * state, user override, etc.).
+     */
+    routingContext?: Readonly<Record<string, unknown>>;
+}
+export declare class Registry {
+    private adapters;
+    private routingPolicy;
+    /** Register an adapter. Runs selfTest if present. */
+    register(adapter: ProviderAdapter): Promise<void>;
+    /** Unregister an adapter, calling dispose if present. */
+    unregister(id: ProviderId): Promise<void>;
+    /** Set or replace the routing policy. */
+    setRoutingPolicy(policy: RoutingPolicy | null): void;
+    /** List all registered adapter IDs. */
+    list(): ReadonlyArray<ProviderId>;
+    /** Get an adapter by ID directly (no routing). Returns undefined if absent. */
+    get(id: ProviderId): ProviderAdapter | undefined;
+    /**
+     * Find adapters that support the given capability set.
+     * Returns all matching adapters; use `resolve` for routing-based selection.
+     */
+    candidates(required: ReadonlyArray<CapabilityFlag>): ReadonlyArray<ProviderAdapter>;
+    /**
+     * Resolve a request to a specific adapter. Uses the routing policy when
+     * multiple candidates match; falls back to first-match-by-registration
+     * order when no policy is set.
+     *
+     * Throws UnsupportedCapabilityError when no adapter can satisfy the
+     * required capabilities.
+     */
+    resolve(request: ResolveRequest): Promise<ProviderAdapter>;
+    /**
+     * Convenience: resolve and return a specific primitive implementation.
+     * Caller casts to the appropriate primitive type.
+     */
+    resolvePrimitive(capability: CapabilityFlag, request?: Omit<ResolveRequest, 'requires'>): Promise<unknown>;
+}
+/** The application-wide default registry instance. */
+export declare const registry: Registry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/providers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAGnE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,OAAO,CAAC;CAC7D;AAED,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACxC;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,aAAa,CAA8B;IAEnD,qDAAqD;IAC/C,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvD,yDAAyD;IACnD,UAAU,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,yCAAyC;IACzC,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI;IAIpD,uCAAuC;IACvC,IAAI,IAAI,aAAa,CAAC,UAAU,CAAC;IAIjC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS;IAIhD;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC;IAMnF;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IA6ChE;;;OAGG;IACG,gBAAgB,CACpB,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAM,GAC7C,OAAO,CAAC,OAAO,CAAC;CAIpB;AAED,sDAAsD;AACtD,eAAO,MAAM,QAAQ,UAAiB,CAAC"}

package/dist/providers/registry.js

@@ -0,0 +1,109 @@
+/**
+ * Registry — runtime adapter discovery and selection.
+ *
+ * The single point of access for application code that needs a provider.
+ * Adapters register themselves on startup; consumers query by capability
+ * and receive an adapter that can satisfy the request.
+ *
+ * Design:
+ *   - Adapters declare their capabilities up front (no late binding).
+ *   - The registry stores adapters keyed by ProviderId.
+ *   - `resolve()` returns the first adapter matching a capability set,
+ *     or the adapter chosen by an injected `RoutingPolicy`.
+ *   - All resolution is synchronous once adapters are registered;
+ *     registration is async to allow adapters to do setup at register time.
+ */
+import { hasAllCapabilities, missingCapability } from './capabilities.js';
+import { UnsupportedCapabilityError } from './errors.js';
+export class Registry {
+    adapters = new Map();
+    routingPolicy = null;
+    /** Register an adapter. Runs selfTest if present. */
+    async register(adapter) {
+        if (this.adapters.has(adapter.id)) {
+            throw new Error(`Adapter already registered: ${adapter.id}`);
+        }
+        if (adapter.selfTest) {
+            await adapter.selfTest();
+        }
+        this.adapters.set(adapter.id, adapter);
+    }
+    /** Unregister an adapter, calling dispose if present. */
+    async unregister(id) {
+        const adapter = this.adapters.get(id);
+        if (!adapter)
+            return;
+        if (adapter.dispose) {
+            await adapter.dispose();
+        }
+        this.adapters.delete(id);
+    }
+    /** Set or replace the routing policy. */
+    setRoutingPolicy(policy) {
+        this.routingPolicy = policy;
+    }
+    /** List all registered adapter IDs. */
+    list() {
+        return Array.from(this.adapters.keys());
+    }
+    /** Get an adapter by ID directly (no routing). Returns undefined if absent. */
+    get(id) {
+        return this.adapters.get(id);
+    }
+    /**
+     * Find adapters that support the given capability set.
+     * Returns all matching adapters; use `resolve` for routing-based selection.
+     */
+    candidates(required) {
+        return Array.from(this.adapters.values()).filter((a) => hasAllCapabilities(a.capabilities, [...required]));
+    }
+    /**
+     * Resolve a request to a specific adapter. Uses the routing policy when
+     * multiple candidates match; falls back to first-match-by-registration
+     * order when no policy is set.
+     *
+     * Throws UnsupportedCapabilityError when no adapter can satisfy the
+     * required capabilities.
+     */
+    async resolve(request) {
+        if (request.pinTo) {
+            const pinned = this.adapters.get(request.pinTo);
+            if (!pinned) {
+                throw new UnsupportedCapabilityError(`pinned-adapter-not-registered:${request.pinTo}`, request.pinTo);
+            }
+            const missing = missingCapability(pinned.capabilities, [...request.requires]);
+            if (missing) {
+                throw new UnsupportedCapabilityError(missing, request.pinTo);
+            }
+            return pinned;
+        }
+        const candidates = this.candidates(request.requires);
+        if (candidates.length === 0) {
+            throw new UnsupportedCapabilityError(request.requires.join(','), '<no-adapter>');
+        }
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
+        if (this.routingPolicy) {
+            const decision = await this.routingPolicy.decide(candidates, request);
+            const chosen = this.adapters.get(decision.chosen);
+            if (!chosen) {
+                throw new Error(`Routing policy returned unknown adapter: ${decision.chosen}`);
+            }
+            return chosen;
+        }
+        // No policy — first candidate by registration order
+        return candidates[0];
+    }
+    /**
+     * Convenience: resolve and return a specific primitive implementation.
+     * Caller casts to the appropriate primitive type.
+     */
+    async resolvePrimitive(capability, request = {}) {
+        const adapter = await this.resolve({ ...request, requires: [capability] });
+        return adapter.primitive(capability);
+    }
+}
+/** The application-wide default registry instance. */
+export const registry = new Registry();
+//# 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/routing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * RoutingPolicy — decide which adapter satisfies a request when multiple
+ * could.
+ *
+ * The interface is defined here; concrete policies live elsewhere (Phase 5
+ * builds the cost-aware policy that drains the Agent SDK credit before
+ * falling back to interactive-pool).
+ *
+ * Routing policies are stateless from the abstraction's view — they take
+ * the candidate list and request, and return a decision. State (current
+ * quota readings, recent failure counts, etc.) lives outside the policy
+ * and is passed in via `request.routingContext`.
+ */
+import type { ProviderId } from './types.js';
+import type { CapabilityFlag } from './capabilities.js';
+import type { ProviderAdapter, ResolveRequest } from './registry.js';
+export interface RoutingPolicy {
+    /**
+     * Choose an adapter from candidates. All candidates already satisfy the
+     * required capabilities. The policy ranks by preference, cost, quota
+     * state, or other criteria.
+     */
+    decide(candidates: ReadonlyArray<ProviderAdapter>, request: ResolveRequest): Promise<RoutingDecision>;
+}
+export interface RoutingDecision {
+    /** ID of the chosen adapter. MUST be one of the candidates. */
+    chosen: ProviderId;
+    /** Brief reason for the choice (for audit / debugging). */
+    reason: string;
+    /** Fallback chain to try if the chosen adapter fails at use time. */
+    fallbacks?: ReadonlyArray<ProviderId>;
+}
+/**
+ * Default policy: first candidate by registration order. Used when no
+ * policy is set. Useful as a base class for more sophisticated policies.
+ */
+export declare class FirstAvailablePolicy implements RoutingPolicy {
+    decide(candidates: ReadonlyArray<ProviderAdapter>, _request: ResolveRequest): Promise<RoutingDecision>;
+}
+/**
+ * Policy that prefers adapters with a specific optional capability.
+ * Useful for "prefer authoritative usage data when available."
+ */
+export declare class PreferCapabilityPolicy implements RoutingPolicy {
+    private readonly preferred;
+    constructor(preferred: CapabilityFlag);
+    decide(candidates: ReadonlyArray<ProviderAdapter>, _request: ResolveRequest): Promise<RoutingDecision>;
+}
+/**
+ * Adapter for composing multiple policies. Tries each in order; first
+ * non-null decision wins. The last policy in the chain MUST always
+ * return a decision (it's the catch-all).
+ */
+export declare class ChainPolicy implements RoutingPolicy {
+    private readonly chain;
+    constructor(chain: ReadonlyArray<RoutingPolicy>);
+    decide(candidates: ReadonlyArray<ProviderAdapter>, request: ResolveRequest): Promise<RoutingDecision>;
+}
+//# sourceMappingURL=routing.d.ts.map

package/dist/providers/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/providers/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,CACJ,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,MAAM,EAAE,UAAU,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IAClD,MAAM,CACV,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;CAO5B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,cAAc;IAEhD,MAAM,CACV,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;CAa5B;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,aAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC;IAE1D,MAAM,CACV,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;CAU5B"}

package/dist/providers/routing.js

@@ -0,0 +1,72 @@
+/**
+ * RoutingPolicy — decide which adapter satisfies a request when multiple
+ * could.
+ *
+ * The interface is defined here; concrete policies live elsewhere (Phase 5
+ * builds the cost-aware policy that drains the Agent SDK credit before
+ * falling back to interactive-pool).
+ *
+ * Routing policies are stateless from the abstraction's view — they take
+ * the candidate list and request, and return a decision. State (current
+ * quota readings, recent failure counts, etc.) lives outside the policy
+ * and is passed in via `request.routingContext`.
+ */
+/**
+ * Default policy: first candidate by registration order. Used when no
+ * policy is set. Useful as a base class for more sophisticated policies.
+ */
+export class FirstAvailablePolicy {
+    async decide(candidates, _request) {
+        const chosen = candidates[0];
+        if (!chosen) {
+            throw new Error('FirstAvailablePolicy called with no candidates');
+        }
+        return { chosen: chosen.id, reason: 'first-available' };
+    }
+}
+/**
+ * Policy that prefers adapters with a specific optional capability.
+ * Useful for "prefer authoritative usage data when available."
+ */
+export class PreferCapabilityPolicy {
+    preferred;
+    constructor(preferred) {
+        this.preferred = preferred;
+    }
+    async decide(candidates, _request) {
+        const withPreferred = candidates.find((c) => c.capabilities.has(this.preferred));
+        if (withPreferred) {
+            return {
+                chosen: withPreferred.id,
+                reason: `prefers-capability:${this.preferred}`,
+            };
+        }
+        return {
+            chosen: candidates[0].id,
+            reason: 'no-preferred-fallback-first',
+        };
+    }
+}
+/**
+ * Adapter for composing multiple policies. Tries each in order; first
+ * non-null decision wins. The last policy in the chain MUST always
+ * return a decision (it's the catch-all).
+ */
+export class ChainPolicy {
+    chain;
+    constructor(chain) {
+        this.chain = chain;
+    }
+    async decide(candidates, request) {
+        for (const policy of this.chain) {
+            try {
+                return await policy.decide(candidates, request);
+            }
+            catch {
+                // try next
+            }
+        }
+        throw new Error('ChainPolicy exhausted with no decision');
+    }
+}
+//# sourceMappingURL=routing.js.map

package/dist/providers/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/providers/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2BH;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAC/B,KAAK,CAAC,MAAM,CACV,UAA0C,EAC1C,QAAwB;QAExB,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC1D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAE1D,KAAK,CAAC,MAAM,CACV,UAA0C,EAC1C,QAAwB;QAExB,MAAM,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACjF,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO;gBACL,MAAM,EAAE,aAAa,CAAC,EAAE;gBACxB,MAAM,EAAE,sBAAsB,IAAI,CAAC,SAAS,EAAE;aAC/C,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,CAAC,CAAE,CAAC,EAAE;YACzB,MAAM,EAAE,6BAA6B;SACtC,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,KAAmC;QAAnC,UAAK,GAAL,KAAK,CAA8B;IAAG,CAAC;IAEpE,KAAK,CAAC,MAAM,CACV,UAA0C,EAC1C,OAAuB;QAEvB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,WAAW;YACb,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/providers/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared types for the provider portability substrate.
+ *
+ * These types are imported by every primitive interface and every adapter.
+ * Adding to this file ripples through the whole substrate, so keep it tight —
+ * if a type is used by only one primitive, define it in that primitive's file.
+ */
+/**
+ * Stable identifier for a provider adapter. Convention: kebab-case, scope
+ * with the underlying provider's name first (e.g. `anthropic-headless`,
+ * `anthropic-interactive-pool`, `openai-codex`, `local-ollama`).
+ *
+ * Branded so it can't be confused with arbitrary strings.
+ */
+export type ProviderId = string & {
+    readonly __brand: 'ProviderId';
+};
+/** Construct a ProviderId without unsafe assertions at call sites. */
+export declare function providerId(id: string): ProviderId;
+/**
+ * Opaque handle to a session held by a specific provider adapter. The handle
+ * is meaningful only to the adapter that issued it. Application code passes
+ * it back to the same adapter for operations on the session.
+ *
+ * Implementations should treat the handle as a tagged tuple of (provider, id)
+ * internally — the type system enforces that the same adapter handles both
+ * the issue and the use, but the value itself is just a string at runtime.
+ */
+export type SessionHandle = string & {
+    readonly __brand: 'SessionHandle';
+};
+/** Construct a SessionHandle without unsafe assertions. */
+export declare function sessionHandle(value: string): SessionHandle;
+/**
+ * Abstract model tier. Adapters resolve to concrete provider models —
+ * Anthropic: haiku/sonnet/opus. OpenAI: gpt-mini/gpt/gpt-pro. Etc.
+ *
+ * The tier semantics matter, not the exact model:
+ *   - `fast`: cheapest, fastest, suitable for classification and routing
+ *   - `balanced`: default for most agentic work
+ *   - `capable`: best reasoning for hard cases (planning, deep review)
+ *
+ * Legacy instar aliases (haiku/sonnet/opus) are accepted but normalized to
+ * the abstract tiers above.
+ */
+export type ModelTier = 'fast' | 'balanced' | 'capable';
+/**
+ * Token usage report from a single call. Adapters fill the fields they have
+ * authoritative data for; consumers must tolerate `null` and partial data.
+ */
+export interface UsageReport {
+    inputTokens: number;
+    outputTokens: number;
+    /** Cached tokens (Anthropic prompt cache, OpenAI cached prefix) when applicable. */
+    cachedTokens?: number;
+    /** Reasoning/thinking tokens for models that expose them separately. */
+    reasoningTokens?: number;
+    /** Estimated cost in USD if the adapter has pricing knowledge. */
+    estimatedCostUsd?: number;
+}
+/**
+ * Escape hatch for adapter-specific data that consumers may want but isn't
+ * part of the canonical contract. Stable keys per adapter (the adapter's
+ * `ProviderId` should appear as the top-level key) so consumers know how to
+ * interpret without leaking the adapter's identity through type signatures.
+ *
+ * Example:
+ *   { 'anthropic-headless': { rateLimitWindow: 'weekly', resetsAt: '...' } }
+ */
+export type ProviderSpecific = Readonly<Record<string, unknown>>;
+/**
+ * Standard cancellation/timeout options. Most primitive methods accept this
+ * shape under their `options` parameter; consolidating it here keeps the
+ * primitive interfaces aligned.
+ */
+export interface CancellationOptions {
+    /** AbortSignal for cooperative cancellation. */
+    signal?: AbortSignal;
+    /** Hard timeout in milliseconds. Adapter SHOULD honor; consumer should not assume. */
+    timeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAErE,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAEjD;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAE3E,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAE1D;AAID;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAIxD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAIjE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/providers/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared types for the provider portability substrate.
+ *
+ * These types are imported by every primitive interface and every adapter.
+ * Adding to this file ripples through the whole substrate, so keep it tight —
+ * if a type is used by only one primitive, define it in that primitive's file.
+ */
+/** Construct a ProviderId without unsafe assertions at call sites. */
+export function providerId(id) {
+    return id;
+}
+/** Construct a SessionHandle without unsafe assertions. */
+export function sessionHandle(value) {
+    return value;
+}
+//# 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":"AAAA;;;;;;GAMG;AAaH,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAgB,CAAC;AAC1B,CAAC;AAeD,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAsB,CAAC;AAChC,CAAC"}

package/dist/providers/uxConfirm/FrameworkModelRouter.d.ts

@@ -0,0 +1,97 @@
+/**
+ * FrameworkModelRouter — Phase 5b composition root.
+ *
+ * Wires together TaskClassifier, PreferenceStore, TriggerGate,
+ * TelegramConfirmer, CostStateTracker, and the catalog into the
+ * full suggest-and-confirm flow described in
+ * `specs/provider-portability/10-suggest-and-confirm-ux.md`.
+ *
+ * The router answers the question: "given this task, what framework
+ * and model should run it?" — emitting a structured `RouteResult`
+ * that downstream routing (Phase 5c `CostAwareRoutingPolicy`) uses
+ * to pick the concrete adapter.
+ *
+ * Locked behavior (per Justin's Telegram answers 2026-05-15):
+ *   1. Telegram-only — non-Telegram origins auto-default with note.
+ *   2. Sticky-yes with "(auto-picked X)" surfaced via `source: cached-silent`.
+ *   3. Re-ask only on three triggers — implemented by `TriggerGate`.
+ *   4. Override via slash OR inline phrasing — implemented by `TelegramConfirmer`.
+ */
+import type { CostStateTracker } from '../costAwareRouting.js';
+import type { PreferenceStore, ConfidenceLevel } from './PreferenceStore.js';
+import type { TaskClassifier } from './TaskClassifier.js';
+import type { TelegramConfirmer } from './TelegramConfirmer.js';
+/**
+ * Abstract over the fitness catalogs Phase 5a produced. The router
+ * doesn't read markdown — the catalog provider is the bridge.
+ */
+export interface CatalogProvider {
+    /** Current catalog version. Bumps when fitness data changes meaningfully. */
+    currentVersion(): string;
+    /**
+     * Default framework+model for a task pattern (used when the user
+     * has no cached preference OR when reply times out). The catalog
+     * provider picks based on whatever scoring it implements.
+     */
+    defaultFor(taskPattern: string): {
+        framework: string;
+        model: string;
+        confidence: ConfidenceLevel;
+    };
+    /**
+     * Catalog's current confidence for a specific (pattern, framework, model)
+     * tuple. Used by the trigger gate to detect confidence-dropped triggers.
+     */
+    confidenceFor(taskPattern: string, framework: string, model: string): ConfidenceLevel;
+}
+export interface RouteInput {
+    /** Stable user identifier used as the cache key prefix. */
+    userId: string;
+    /** Full task prompt for classification. */
+    taskPrompt: string;
+    /** Optional classification bias tags. */
+    taskTags?: ReadonlyArray<string>;
+    /** Short description for the confirmation prompt's header. */
+    taskDescription: string;
+    /**
+     * Telegram topic the task originated from. When null/undefined, the
+     * router skips the UX entirely and returns the catalog default with
+     * `source: auto-defaulted-no-topic` (background work, autonomous loops).
+     */
+    telegramTopicId?: string | null;
+}
+export type RouteSource = 'cached-silent' | 'confirmed' | 'confirmed-one-shot' | 'overridden-this-task' | 'overridden-this-pattern' | 'reset-defaulted' | 'auto-defaulted-no-topic' | 'auto-defaulted-no-reply' | 'auto-defaulted-unclassified';
+export interface RouteResult {
+    framework: string;
+    model: string;
+    taskPattern: string;
+    source: RouteSource;
+    /**
+     * The (framework, model) that the catalog reports as default for this
+     * pattern, separately from the chosen pick. Used by the dashboard's
+     * historical view + audit trail.
+     */
+    catalogDefault: {
+        framework: string;
+        model: string;
+        confidence: ConfidenceLevel;
+    };
+}
+export interface FrameworkModelRouterOptions {
+    classifier: TaskClassifier;
+    store: PreferenceStore;
+    confirmer: TelegramConfirmer;
+    costStateTracker: CostStateTracker;
+    catalog: CatalogProvider;
+}
+export declare class FrameworkModelRouter {
+    private readonly classifier;
+    private readonly store;
+    private readonly confirmer;
+    private readonly costStateTracker;
+    private readonly catalog;
+    constructor(options: FrameworkModelRouterOptions);
+    route(input: RouteInput): Promise<RouteResult>;
+    private writeCache;
+}
+//# sourceMappingURL=FrameworkModelRouter.d.ts.map

package/dist/providers/uxConfirm/FrameworkModelRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrameworkModelRouter.d.ts","sourceRoot":"","sources":["../../../src/providers/uxConfirm/FrameworkModelRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAA4B,MAAM,sBAAsB,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,wBAAwB,CAAC;AAQpF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,cAAc,IAAI,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG;QAC/B,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,eAAe,CAAC;KAC7B,CAAC;IACF;;;OAGG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;CACvF;AAMD,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,WAAW,GACX,oBAAoB,GACpB,sBAAsB,GACtB,yBAAyB,GACzB,iBAAiB,GACjB,yBAAyB,GACzB,yBAAyB,GACzB,6BAA6B,CAAC;AAElC,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,cAAc,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,eAAe,CAAA;KAAE,CAAC;CACnF;AAMD,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,OAAO,EAAE,eAAe,CAAC;CAC1B;AA6BD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,OAAO,EAAE,2BAA2B;IAQ1C,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IA4KpD,OAAO,CAAC,UAAU;CAOnB"}