@cat-factory/kernel 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/domain/catalog.d.ts

@@ -0,0 +1,36 @@
+import type { BlockType, WorkspaceSettings } from './types.js';
+/**
+ * The runtime settings every workspace starts with (lazily seeded on first read).
+ * `waitingEscalationMinutes` is how long a run may wait for human input before its
+ * notification turns red (runs are never auto-failed for waiting); the task limit is
+ * off by default so existing boards keep their unbounded concurrency.
+ */
+export declare const DEFAULT_WORKSPACE_SETTINGS: WorkspaceSettings;
+/**
+ * The built-in merge threshold preset seeded for every workspace, used by any
+ * task that hasn't picked its own. A PR auto-merges only when the `merger`
+ * agent's complexity/risk/impact all stay at or below these ceilings; otherwise a
+ * `merge_review` notification is raised. `ciMaxAttempts` bounds how many times the
+ * `ci-fixer` agent retries before the CI gate gives up.
+ */
+export declare const DEFAULT_MERGE_PRESET: {
+    readonly name: 'Balanced';
+    readonly maxComplexity: 0.5;
+    readonly maxRisk: 0.4;
+    readonly maxImpact: 0.5;
+    readonly ciMaxAttempts: 10;
+    readonly maxRequirementIterations: 6;
+    readonly maxRequirementConcernAllowed: 'none';
+    readonly releaseWatchWindowMinutes: 30;
+    readonly releaseMaxAttempts: 1;
+};
+/** Fallback CI-fixer attempt budget when no preset resolves (defensive default). */
+export declare const DEFAULT_CI_MAX_ATTEMPTS: 10;
+/**
+ * Fallback cap on the iterative requirements-review loop (reviewer passes) when no
+ * preset resolves. One reviewer pass = one iteration; the initial review is iteration 1.
+ */
+export declare const DEFAULT_MAX_REQUIREMENT_ITERATIONS: 6;
+/** Human-facing label per block type, used when titling freshly dropped frames. */
+export declare const BLOCK_TYPE_LABEL: Record<BlockType, string>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/domain/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/domain/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAI9D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAKxC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;aAC/B,IAAI,EAAE,UAAU;aAChB,aAAa,EAAE,GAAG;aAClB,OAAO,EAAE,GAAG;aACZ,SAAS,EAAE,GAAG;aACd,aAAa,EAAE,EAAE;aACjB,wBAAwB,EAAE,CAAC;aAE3B,4BAA4B,EAAE,MAAM;aAKpC,yBAAyB,EAAE,EAAE;aAC7B,kBAAkB,EAAE,CAAC;CACb,CAAA;AAEV,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,IAAqC,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,kCAAkC,GAAgD,CAAA;AAE/F,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAStD,CAAA"}

package/dist/domain/catalog.js

@@ -0,0 +1,55 @@
+// Static catalogs and constants used across the domain.
+/**
+ * The runtime settings every workspace starts with (lazily seeded on first read).
+ * `waitingEscalationMinutes` is how long a run may wait for human input before its
+ * notification turns red (runs are never auto-failed for waiting); the task limit is
+ * off by default so existing boards keep their unbounded concurrency.
+ */
+export const DEFAULT_WORKSPACE_SETTINGS = {
+    waitingEscalationMinutes: 120,
+    taskLimitMode: 'off',
+    taskLimitShared: null,
+    taskLimitPerType: null,
+};
+/**
+ * The built-in merge threshold preset seeded for every workspace, used by any
+ * task that hasn't picked its own. A PR auto-merges only when the `merger`
+ * agent's complexity/risk/impact all stay at or below these ceilings; otherwise a
+ * `merge_review` notification is raised. `ciMaxAttempts` bounds how many times the
+ * `ci-fixer` agent retries before the CI gate gives up.
+ */
+export const DEFAULT_MERGE_PRESET = {
+    name: 'Balanced',
+    maxComplexity: 0.5,
+    maxRisk: 0.4,
+    maxImpact: 0.5,
+    ciMaxAttempts: 10,
+    maxRequirementIterations: 6,
+    // Tolerate nothing by default: any reviewer finding pauses the run for a human.
+    maxRequirementConcernAllowed: 'none',
+    // Post-release-health gate: how long (minutes) the gate watches the deployed
+    // release's monitors/SLOs before declaring it healthy, and how many on-call
+    // investigations may be dispatched while watching (the on-call agent investigates
+    // rather than fixing prod, so 1 pass is the sensible default).
+    releaseWatchWindowMinutes: 30,
+    releaseMaxAttempts: 1,
+};
+/** Fallback CI-fixer attempt budget when no preset resolves (defensive default). */
+export const DEFAULT_CI_MAX_ATTEMPTS = DEFAULT_MERGE_PRESET.ciMaxAttempts;
+/**
+ * Fallback cap on the iterative requirements-review loop (reviewer passes) when no
+ * preset resolves. One reviewer pass = one iteration; the initial review is iteration 1.
+ */
+export const DEFAULT_MAX_REQUIREMENT_ITERATIONS = DEFAULT_MERGE_PRESET.maxRequirementIterations;
+/** Human-facing label per block type, used when titling freshly dropped frames. */
+export const BLOCK_TYPE_LABEL = {
+    frontend: 'Frontend',
+    service: 'Service',
+    api: 'API',
+    database: 'Database',
+    queue: 'Queue',
+    integration: 'Integration',
+    external: 'External',
+    environment: 'Environment',
+};
+//# sourceMappingURL=catalog.js.map

package/dist/domain/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/domain/catalog.ts"],"names":[],"mappings":"AAEA,wDAAwD;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,wBAAwB,EAAE,GAAG;IAC7B,aAAa,EAAE,KAAK;IACpB,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,IAAI;CACvB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,UAAU;IAChB,aAAa,EAAE,GAAG;IAClB,OAAO,EAAE,GAAG;IACZ,SAAS,EAAE,GAAG;IACd,aAAa,EAAE,EAAE;IACjB,wBAAwB,EAAE,CAAC;IAC3B,gFAAgF;IAChF,4BAA4B,EAAE,MAAM;IACpC,6EAA6E;IAC7E,4EAA4E;IAC5E,kFAAkF;IAClF,+DAA+D;IAC/D,yBAAyB,EAAE,EAAE;IAC7B,kBAAkB,EAAE,CAAC;CACb,CAAA;AAEV,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC,aAAa,CAAA;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,oBAAoB,CAAC,wBAAwB,CAAA;AAE/F,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,UAAU;IACpB,WAAW,EAAE,aAAa;CAC3B,CAAA"}

package/dist/domain/errors.d.ts

@@ -0,0 +1,57 @@
+export type DomainErrorCode = 'not_found' | 'validation' | 'conflict' | 'credential_required';
+export declare class DomainError extends Error {
+    readonly code: DomainErrorCode;
+    /**
+     * Optional machine-readable detail the facade surfaces alongside the error
+     * (e.g. which vendor + why a personal credential is required), so a client can
+     * react precisely — prompt for a password vs offer to connect a subscription —
+     * without string-matching the message.
+     */
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: DomainErrorCode, message: string, 
+    /**
+     * Optional machine-readable detail the facade surfaces alongside the error
+     * (e.g. which vendor + why a personal credential is required), so a client can
+     * react precisely — prompt for a password vs offer to connect a subscription —
+     * without string-matching the message.
+     */
+    details?: Record<string, unknown> | undefined);
+}
+/** A referenced entity does not exist (→ 404). */
+export declare class NotFoundError extends DomainError {
+    constructor(entity: string, id: string);
+}
+/** Structurally valid but violates a domain rule (→ 422). */
+export declare class ValidationError extends DomainError {
+    constructor(message: string);
+}
+/** Conflicts with current state (→ 409). */
+export declare class ConflictError extends DomainError {
+    constructor(message: string);
+}
+/**
+ * Why a personal (individual-usage) subscription credential can't be used right now.
+ *  - `no_subscription`     — the user has no stored credential for the vendor.
+ *  - `password_required`   — a credential exists but the request carried no password
+ *                            (or none is cached) to unlock it.
+ *  - `wrong_password`      — the supplied password did not decrypt the credential.
+ *  - `subscription_expired`— the stored subscription's own expiry has passed; renew it.
+ */
+export type CredentialRequiredReason = 'no_subscription' | 'password_required' | 'wrong_password' | 'subscription_expired';
+/**
+ * A user-scoped personal credential is needed before this action can proceed (→ 428
+ * Precondition Required). Carries the vendor + reason so the client prompts for a
+ * password or offers to connect/renew the subscription, rather than failing opaquely.
+ * Used by the individual-usage restricted mode (e.g. Claude personal subscriptions).
+ */
+export declare class CredentialRequiredError extends DomainError {
+    constructor(message: string, details: {
+        vendor: string;
+        reason: CredentialRequiredReason;
+    });
+}
+/** Resolve a maybe-null lookup or throw a {@link NotFoundError}. */
+export declare function assertFound<T>(value: T | null | undefined, entity: string, id: string): T;
+/** Extract a human-readable message from an unknown thrown value. */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/domain/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,qBAAqB,CAAA;AAE7F,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAT5C,YACW,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACM,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA,EAI3C;CACF;AAED,kDAAkD;AAClD,qBAAa,aAAc,SAAQ,WAAW;IAC5C,YAAY,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAErC;CACF;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,4CAA4C;AAC5C,qBAAa,aAAc,SAAQ,WAAW;IAC5C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,CAAA;AAE1B;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;IACtD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,wBAAwB,CAAA;KAAE,EAEzF;CACF;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,CAGzF;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/domain/errors.js

@@ -0,0 +1,60 @@
+// Domain-level errors. The core throws these; the facade's error handler maps
+// them to HTTP status codes. Keeping them framework-agnostic means the same core
+// can be wrapped by a different transport (queue consumer, RPC, CLI) unchanged.
+export class DomainError extends Error {
+    code;
+    details;
+    constructor(code, message, 
+    /**
+     * Optional machine-readable detail the facade surfaces alongside the error
+     * (e.g. which vendor + why a personal credential is required), so a client can
+     * react precisely — prompt for a password vs offer to connect a subscription —
+     * without string-matching the message.
+     */
+    details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = new.target.name;
+    }
+}
+/** A referenced entity does not exist (→ 404). */
+export class NotFoundError extends DomainError {
+    constructor(entity, id) {
+        super('not_found', `${entity} '${id}' not found`);
+    }
+}
+/** Structurally valid but violates a domain rule (→ 422). */
+export class ValidationError extends DomainError {
+    constructor(message) {
+        super('validation', message);
+    }
+}
+/** Conflicts with current state (→ 409). */
+export class ConflictError extends DomainError {
+    constructor(message) {
+        super('conflict', message);
+    }
+}
+/**
+ * A user-scoped personal credential is needed before this action can proceed (→ 428
+ * Precondition Required). Carries the vendor + reason so the client prompts for a
+ * password or offers to connect/renew the subscription, rather than failing opaquely.
+ * Used by the individual-usage restricted mode (e.g. Claude personal subscriptions).
+ */
+export class CredentialRequiredError extends DomainError {
+    constructor(message, details) {
+        super('credential_required', message, details);
+    }
+}
+/** Resolve a maybe-null lookup or throw a {@link NotFoundError}. */
+export function assertFound(value, entity, id) {
+    if (value === null || value === undefined)
+        throw new NotFoundError(entity, id);
+    return value;
+}
+/** Extract a human-readable message from an unknown thrown value. */
+export function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/domain/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iFAAiF;AACjF,gFAAgF;AAIhF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB,IAAI;IAQJ,OAAO;IATlB,YACW,IAAqB,EAC9B,OAAe;IACf;;;;;OAKG;IACM,OAAiC;QAE1C,KAAK,CAAC,OAAO,CAAC,CAAA;oBAVL,IAAI;uBAQJ,OAAO;QAGhB,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAA;IAC7B,CAAC;CACF;AAED,kDAAkD;AAClD,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C,YAAY,MAAc,EAAE,EAAU;QACpC,KAAK,CAAC,WAAW,EAAE,GAAG,MAAM,KAAK,EAAE,aAAa,CAAC,CAAA;IACnD,CAAC;CACF;AAED,6DAA6D;AAC7D,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9B,CAAC;CACF;AAED,4CAA4C;AAC5C,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAC5B,CAAC;CACF;AAgBD;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,WAAW;IACtD,YAAY,OAAe,EAAE,OAA6D;QACxF,KAAK,CAAC,qBAAqB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IAChD,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAI,KAA2B,EAAE,MAAc,EAAE,EAAU;IACpF,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC9E,OAAO,KAAK,CAAA;AACd,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC"}

package/dist/domain/models.d.ts

@@ -0,0 +1,204 @@
+import { type ModelCost, type ModelOption, type SubscriptionVendor } from '@cat-factory/contracts';
+import type { HarnessKind, ModelRef } from '../ports/model-provider.js';
+export interface SubscriptionVendorConfig {
+    harness: Extract<HarnessKind, 'claude-code' | 'codex'>;
+    /** Anthropic-compatible base URL for a non-Anthropic claude-code vendor. */
+    baseUrl?: string;
+    /** Short label shown in the picker / credential UI. */
+    label: string;
+    /**
+     * The vendor's subscription credential is licensed for INDIVIDUAL use only, so it may
+     * NOT be pooled on a workspace (any member's runs leasing it) — it is stored per-user
+     * and only its owner's runs may use it. Set from each vendor's own terms of service:
+     *
+     *  - `claude`  — Anthropic consumer Claude (Pro/Max) is individual-use only.
+     *  - `codex`   — a ChatGPT `auth.json` is a per-seat credential; OpenAI prohibits
+     *                credential sharing at EVERY tier (Plus/Pro and Team/Business/
+     *                Enterprise alike — Team/Enterprise just grant more individual seats).
+     *  - `glm`     — Z.ai's GLM Coding Plan is "licensed only to the individual natural
+     *                person" and forbids any organization using its quota.
+     *
+     * This is the right axis even across tiers: the pool models SHARING a subscription
+     * credential, which no consumer tier permits. Genuine org-wide / programmatic access
+     * goes through the DIRECT-PROVIDER API-KEY path (OpenAI/Anthropic keys), which is
+     * unaffected by this flag — so flagging a vendor here routes orgs to API keys, it does
+     * not lock them out. The commercial coding-plan vendors that DO permit org use stay
+     * poolable: `kimi` (Moonshot explicitly permits authorized enterprise use) and
+     * `deepseek` (a commercial API platform serving internal/external end users). See
+     * backend/docs/individual-subscription-usage.md §1 for the per-vendor ToS citations.
+     */
+    individualOnly?: boolean;
+}
+export declare const SUBSCRIPTION_VENDORS: Record<SubscriptionVendor, SubscriptionVendorConfig>;
+export interface ModelVariant {
+    ref: ModelRef;
+    /** Env var whose presence switches this model to its direct provider. */
+    keyEnv: string;
+    /** Short provider label shown in the picker, e.g. `DashScope`. */
+    providerLabel: string;
+}
+/**
+ * A subscription-only variant: the model runs in the Claude Code / Codex harness
+ * authenticated with a pooled subscription token (no Cloudflare/API-key fallback).
+ * The `ref` carries the `harness` the executor dispatches to.
+ */
+export interface SubscriptionVariant {
+    ref: ModelRef;
+    /** Vendor whose pooled token authenticates this model. */
+    vendor: SubscriptionVendor;
+}
+export interface SelectableModel {
+    /** Stable id stored on a block, e.g. `qwen`. */
+    id: string;
+    /** Model-family label shown in the picker, e.g. `Qwen3`. */
+    label: string;
+    /** One-line description shown alongside the label. */
+    description: string;
+    /** Always-available Cloudflare Workers AI variant (absent for subscription-only models). */
+    cloudflare?: ModelRef;
+    /** Optional direct-provider variant, used when its key is configured. */
+    direct?: ModelVariant;
+    /**
+     * Optional subscription variant (Claude Code / Codex). For subscription-ONLY
+     * models (Opus/Sonnet/GPT) it is the only variant; for dual-mode models
+     * (GLM/Kimi) it sits alongside a Cloudflare/direct base and WINS whenever the
+     * workspace has a token for its vendor.
+     */
+    subscription?: SubscriptionVariant;
+}
+export declare const MODEL_CATALOG: SelectableModel[];
+/** Look up a catalog model by id, or `undefined` for an unknown/empty id. */
+export declare function getSelectableModel(id: string | undefined | null): SelectableModel | undefined;
+/**
+ * The total context window (input + output tokens) the catalog declares for a concrete
+ * model ref, matched by provider + model. Returns undefined for a ref the catalog does
+ * not carry or one with no declared window. Used by the LLM proxy to cap a call's
+ * requested output so input + output can't exceed a small-window model's limit — a model
+ * like `@cf/qwen/qwen3-30b-a3b-fp8` (32K total) otherwise rejects the whole request
+ * (Workers AI error 8007 → HTTP 502) when the output floor alone fills the window.
+ */
+export declare function contextWindowFor(ref: {
+    provider: string;
+    model: string;
+}): number | undefined;
+/**
+ * What a deployment + workspace actually has configured, used to resolve a catalog
+ * model to its usable flavour. Replaces the old env-only `keyEnv` predicate: direct
+ * keys now live in the DB API-key pool (account/workspace/user scoped), subscription
+ * vendors in the token pools, and Cloudflare Workers AI is an opt-in provider lib.
+ */
+export interface ProviderCapabilities {
+    /** Direct providers (e.g. `qwen`, `openai`) with ≥1 key in the merged scope pool. */
+    directProviders: Set<string>;
+    /** Subscription vendors with a usable token (pool or personal). */
+    subscriptionVendors: Set<SubscriptionVendor>;
+    /** Whether the opt-in Cloudflare Workers AI lib is registered for this deployment. */
+    cloudflareEnabled: boolean;
+    /**
+     * The dynamic local-runner model ids (`"<provider>:<model>"`, e.g. `ollama:gemma3`) the
+     * resolving USER has enabled. A local model needs no pooled key — the user's configured
+     * endpoint carries the (optional) key — so usability is gated on the SPECIFIC model
+     * being enabled, not merely the runner being configured (a stale pin to a model the user
+     * later un-enabled must NOT pass the start guard).
+     */
+    localModels?: Set<string>;
+}
+/** Resolve the informational list cost for a model ref (e.g. from spend pricing). */
+export type ModelCostResolver = (ref: ModelRef) => ModelCost | undefined;
+/**
+ * Whether a catalog model is selectable for the given capabilities — it has at least
+ * one usable flavour (a configured direct key, an enabled Cloudflare lib, or a
+ * connected subscription vendor). Unknown ids are not usable.
+ */
+export declare function isModelUsable(id: string | undefined | null, caps: ProviderCapabilities): boolean;
+/**
+ * The subscription option for a catalog model id (vendor + ref carrying the
+ * harness), or undefined when the model has no subscription path. The executor
+ * uses this to override a step to its subscription flavour when the workspace has
+ * a pooled token for the vendor — "subscriptions always win".
+ */
+export declare function subscriptionOptionFor(id: string | undefined | null): {
+    vendor: SubscriptionVendor;
+    ref: ModelRef;
+} | undefined;
+/** Whether a vendor's subscription is licensed for individual use only (e.g. `claude`). */
+export declare function isIndividualVendor(vendor: SubscriptionVendor): boolean;
+/** Every vendor flagged individual-usage only — the single source of truth for the
+ *  per-user personal-subscription flow (e.g. activation refresh) so it never drifts
+ *  from {@link SUBSCRIPTION_VENDORS}. */
+export declare const INDIVIDUAL_VENDORS: SubscriptionVendor[];
+/**
+ * The individual-usage vendor a catalog model id runs on, or null. A model triggers
+ * the individual-usage restricted mode (per-user credential, no recurring, etc.) only
+ * when it has a subscription flavour AND that vendor is `individualOnly`. Used by the
+ * engine/controllers to gate a run on the initiator's personal subscription.
+ */
+export declare function individualVendorForModelId(id: string | undefined | null): SubscriptionVendor | null;
+/**
+ * The individual-usage vendor whose PERSONAL credential a run on this catalog model id
+ * will ACTUALLY lease, given whether the run's user already has a personal subscription
+ * for the candidate vendor (`hasPersonalSubscription`). Returns null when no personal
+ * credential is needed. This is the gating-accurate refinement of
+ * {@link individualVendorForModelId}, and mirrors
+ * `ContainerAgentExecutor.resolveEffectiveRef`, so the credential gate prompts for a
+ * password exactly when dispatch will use one:
+ *
+ *  - SUBSCRIPTION-ONLY individual model (Claude / Codex — no Cloudflare/direct base):
+ *    there is no fallback, so the personal credential is always required.
+ *  - DUAL-MODE individual model (e.g. GLM, which also has a Cloudflare base): per-user.
+ *    A user WITH their own personal subscription for the vendor runs on it (gated on
+ *    their password); a user WITHOUT one falls back to the Cloudflare base and is not
+ *    gated. (Individual vendors are never pooled, so there is no shared fallback — only
+ *    the user's own subscription or the base.)
+ *  - Poolable / non-subscription models: never need a personal credential.
+ */
+export declare function personalCredentialVendorForModelId(id: string | undefined | null, hasPersonalSubscription: (vendor: SubscriptionVendor) => boolean): SubscriptionVendor | null;
+/**
+ * The effective catalog for a deployment: each model resolved to the flavour that
+ * is actually in use given which direct-provider keys are configured. Served to
+ * the frontend so the picker can show whether a model runs direct, on Cloudflare,
+ * or on a subscription harness — plus its informational list cost when `costFor`
+ * is supplied. Subscription models are always listed; the frontend gates them on
+ * whether the workspace has a token for the vendor.
+ */
+export declare function effectiveCatalog(caps: ProviderCapabilities, costFor?: ModelCostResolver): ModelOption[];
+/**
+ * Like {@link effectiveCatalog}, but with deployment/user-specific extra models
+ * appended to the static catalog — used to surface a user's locally-run models
+ * (see {@link localSelectableModels}) alongside the built-in catalog.
+ */
+export declare function effectiveCatalogWith(extra: SelectableModel[], caps: ProviderCapabilities, costFor?: ModelCostResolver): ModelOption[];
+/** A user's enabled models for one local runner endpoint. */
+export interface LocalEndpointModels {
+    /** The runner provider id (e.g. `ollama`), also the `ModelRef.provider`. */
+    provider: string;
+    /** The provider label shown in the picker (e.g. `Ollama`). */
+    label: string;
+    /** Enabled model ids on this endpoint. */
+    models: string[];
+}
+/**
+ * Build the dynamic, per-user catalog entries for a set of configured local endpoints.
+ * Each enabled model becomes a `direct`-flavour {@link SelectableModel} with a stable id
+ * `"<provider>:<model>"` and no key requirement (gated by `localModels`).
+ */
+export declare function localSelectableModels(endpoints: LocalEndpointModels[]): SelectableModel[];
+/**
+ * Parse a dynamic local-model id of the form `"<provider>:<model>"` into a {@link ModelRef}.
+ * Splits on the FIRST colon so model ids that themselves contain colons (e.g.
+ * `ollama:qwen2.5-coder:32b`) round-trip correctly. Returns undefined for non-local ids.
+ */
+export declare function parseLocalModelId(id: string | undefined | null): {
+    provider: string;
+    model: string;
+} | undefined;
+/**
+ * Resolve a block's selected model id to the {@link ModelRef} that should run it,
+ * honouring the direct/Cloudflare fallback and carrying the subscription harness
+ * when applicable. Returns `undefined` for an unknown or absent id so the caller
+ * falls back to its default routing.
+ */
+export declare function resolveModelRef(id: string | undefined | null, caps: ProviderCapabilities): ModelRef | undefined;
+/** Every subscription vendor (the full set), for building a permissive capability set. */
+export declare const ALL_SUBSCRIPTION_VENDORS: SubscriptionVendor[];
+//# sourceMappingURL=models.d.ts.map

package/dist/domain/models.d.ts.map

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