@cleocode/core 2026.6.13 → 2026.6.15

package/dist/llm/entity-ops.d.ts

@@ -0,0 +1,299 @@
+/**
+ * 5-entity provider-experience engine ops (T11700 · epic T11666).
+ *
+ * The CORE engine layer behind the addressable provider-experience surface the
+ * North-Star design needs (§2 — Provider / Alias / Account / Model / Profile).
+ * Each function takes a single typed `params` object and returns a
+ * `Promise<EngineResult<T>>` so the dispatch handlers (`packages/cleo`) stay thin
+ * delegates (Gate-6) and the result is wrapped uniformly.
+ *
+ * ## What this module is (and is NOT)
+ *
+ * This is the THIN composition layer: it delegates to the ALREADY-MERGED
+ * accessors rather than re-implementing storage:
+ *
+ *   - **Account** (the credential pool — secret-bearing): reuses the proven
+ *     `cli-ops.ts` engine ops (`llmAdd` / `llmList` / `llmRemove`), which redact
+ *     every secret to a `tokenPreview` (last-4) via the sealed-handle. NO raw
+ *     token EVER leaves this module.
+ *   - **Provider** (the `providers` table, #1039): reads the declarative provider
+ *     rows + the case-insensitive alias index via `openDualScopeDb('global')`.
+ *   - **Model** (the `models_catalog` table, #1037): queries the catalog rows via
+ *     the SAME global chokepoint.
+ *   - **Profile** (the named binding `account + model (+ params + role)`): persists
+ *     into config under `llm.profiles[name]` — the resolver-consumed SSoT
+ *     (`role-resolver.ts`) — via `setConfigValue` / `loadConfig`.
+ *
+ * ## Secrets never surfaced
+ *
+ * `accountAdd` accepts a SECRET token, but its result is the SAME redacted view
+ * `accountList` returns — `tokenPreview` ONLY. Every error string is scrubbed via
+ * `safeErrMessage` (the `cli-ops.ts` redaction). There is no code path that
+ * returns a plaintext secret.
+ *
+ * @module llm/entity-ops
+ * @epic T11666
+ * @task T11700
+ */
+import { type EngineResult, type ModelTransport, type StoredAuthTypeWire } from '@cleocode/contracts';
+/** Parameters for `account.add` — store a pooled credential (SECRET-BEARING). */
+export interface AccountAddParams {
+    /** LLM provider transport key. */
+    provider: ModelTransport;
+    /** API key / OAuth bearer token to persist. SECRET — never echoed. */
+    token: string;
+    /** Account label, unique within the provider (default: `'default'`). */
+    label?: string;
+    /** Optional override for the provider base URL. */
+    baseUrl?: string;
+    /** Explicit auth-type override (auto-detected from the token prefix when omitted). */
+    authType?: StoredAuthTypeWire;
+    /** Optional priority override (lower wins). */
+    priority?: number;
+}
+/**
+ * `account.add` — store a pooled credential, returning the redacted NON-SECRET view.
+ *
+ * Delegates to {@link llmAdd} (the proven pool writer) so the result is the
+ * already-redacted `tokenPreview` view. NO raw token is ever surfaced.
+ *
+ * @task T11700
+ */
+export declare function accountAdd(params: AccountAddParams): Promise<EngineResult<{
+    account: unknown;
+    detectedAuthType: StoredAuthTypeWire;
+}>>;
+/** Parameters for `account.list`. */
+export interface AccountListParams {
+    /** Optional provider filter; lists all providers when omitted. */
+    provider?: ModelTransport;
+}
+/**
+ * `account.list` — list redacted accounts, optionally filtered by provider.
+ *
+ * Delegates to {@link llmList}; the view carries `tokenPreview` ONLY — the
+ * decrypted secret is NEVER present in any field.
+ *
+ * @task T11700
+ */
+export declare function accountList(params: AccountListParams): Promise<EngineResult<{
+    accounts: unknown[];
+}>>;
+/** Parameters for `account.remove`. */
+export interface AccountRemoveParams {
+    /** LLM provider transport key. */
+    provider: ModelTransport;
+    /** Account label to remove. */
+    label: string;
+}
+/**
+ * `account.remove` — delete a `(provider, label)` account from the pool.
+ *
+ * Returns the canonical `{count, deleted}` mutate envelope.
+ *
+ * @task T11700
+ */
+export declare function accountRemove(params: AccountRemoveParams): Promise<EngineResult<{
+    count: number;
+    deleted: string[];
+}>>;
+/** The NON-SECRET declarative provider view returned by list/show. */
+interface ProviderView {
+    id: string;
+    displayName: string;
+    aliases: string[];
+    authMethods: string[];
+    modelsDevId: string;
+    source: string;
+}
+/** Parameters for `provider.list` (no declared params). */
+export type ProviderListParams = Record<string, never>;
+/**
+ * `provider.list` — list every declarative provider as a NON-SECRET view.
+ *
+ * @task T11700
+ */
+export declare function providerList(_params: ProviderListParams): Promise<EngineResult<{
+    providers: ProviderView[];
+}>>;
+/** Parameters for `provider.show`. */
+export interface ProviderShowParams {
+    /** Provider id OR a case-insensitive alias. */
+    provider: string;
+}
+/**
+ * `provider.show` — resolve ONE provider by id or case-insensitive alias.
+ *
+ * The alias index is the declarative `aliases` JSON column on each row; the
+ * lookup matches the id first, then any alias (case-insensitive).
+ *
+ * @task T11700
+ */
+export declare function providerShow(params: ProviderShowParams): Promise<EngineResult<{
+    provider: ProviderView;
+    resolvedFrom: string;
+}>>;
+/** Parameters for `provider.connect`. */
+export interface ProviderConnectParams {
+    /** Provider id or alias to connect. */
+    provider: string;
+    /** Direct API key / bearer token to store (token-direct mode). SECRET. */
+    token?: string;
+    /** Account label to create (default: `'default'`). */
+    label?: string;
+    /** Explicit auth-type override. */
+    authType?: StoredAuthTypeWire;
+}
+/**
+ * `provider.connect` — connect a provider by storing a token as one of its accounts.
+ *
+ * Resolves the provider (id or alias), then delegates to {@link accountAdd} for
+ * the secret-bearing write. The result is the NON-SECRET account identity — the
+ * raw token NEVER crosses this boundary.
+ *
+ * @task T11700
+ */
+export declare function providerConnect(params: ProviderConnectParams): Promise<EngineResult<{
+    count: number;
+    created: string[];
+    account: unknown;
+}>>;
+/** A NON-SECRET catalog model view returned by query/show. */
+interface ModelView {
+    id: string;
+    providerId: string;
+    name: string;
+    family: string;
+    releaseDate: string;
+    contextLimit: number | null;
+    outputLimit: number | null;
+    status: string;
+}
+/** Parameters for `model.query`. */
+export interface ModelQueryParams {
+    /** Optional provider filter (models.dev id). */
+    provider?: string;
+    /** Optional cap on the number of rows returned (newest-first). */
+    limit?: number;
+}
+/**
+ * `model.query` — read the `models_catalog` table, newest-first by release date.
+ *
+ * Optionally filtered by provider (models.dev id) and capped by `limit`. Reads
+ * through the global chokepoint (`openDualScopeDb('global')`).
+ *
+ * @task T11700
+ */
+export declare function modelQuery(params: ModelQueryParams): Promise<EngineResult<{
+    models: ModelView[];
+    count: number;
+}>>;
+/** Parameters for `model.show`. */
+export interface ModelShowParams {
+    /** Model id (catalog key) to resolve. */
+    model: string;
+}
+/**
+ * `model.show` — resolve ONE catalog model by id.
+ *
+ * Returns `{ found: false, model: null }` (not an error) when the id is absent,
+ * mirroring the `admin.config.get` "found" convention.
+ *
+ * @task T11700
+ */
+export declare function modelShow(params: ModelShowParams): Promise<EngineResult<{
+    found: boolean;
+    model: ModelView | null;
+}>>;
+/** The persisted profile binding echoed back to callers. */
+interface ProfileView {
+    name: string;
+    provider: string;
+    model: string;
+    credentialLabel: string | null;
+    role: string | null;
+}
+/** Parameters for `profile.create`. */
+export interface ProfileCreateParams {
+    /** Profile name (the addressable handle). */
+    name: string;
+    /** Provider transport the bound account belongs to. */
+    provider: ModelTransport;
+    /** Model id to bind (validated against the catalog). */
+    model: string;
+    /** Account label to pin (the credential binding). Validated to exist. */
+    label?: string;
+    /** Optional role this profile occupies. */
+    role?: string;
+}
+/**
+ * `profile.create` — bind an account + model into a named profile.
+ *
+ * Validates the binding: (1) when a `label` is supplied, the account
+ * `(provider, label)` MUST exist; (2) the `model` MUST be in the catalog for the
+ * provider (soft-passes when the catalog snapshot is absent). Persists into
+ * `llm.profiles[name]` — the resolver-consumed SSoT.
+ *
+ * @task T11700
+ */
+export declare function profileCreate(params: ProfileCreateParams): Promise<EngineResult<{
+    count: number;
+    created: string[];
+    profile: ProfileView;
+}>>;
+/** Parameters for `profile.list` (no declared params). */
+export type ProfileListParams = Record<string, never>;
+/**
+ * `profile.list` — list every named profile from `llm.profiles`.
+ *
+ * @task T11700
+ */
+export declare function profileList(_params: ProfileListParams): Promise<EngineResult<{
+    profiles: Array<{
+        name: string;
+        provider: string;
+        model: string;
+        credentialLabel: string | null;
+    }>;
+}>>;
+/** Parameters for `profile.pin`. */
+export interface ProfilePinParams {
+    /** Profile name to pin (must exist). */
+    name: string;
+    /** Role to pin to this profile. */
+    role: string;
+}
+/**
+ * `profile.pin` — pin a role to a named profile (`llm.roles[role].profile`).
+ *
+ * The role MUST be a valid background role; the profile MUST already exist.
+ *
+ * @task T11700
+ */
+export declare function profilePin(params: ProfilePinParams): Promise<EngineResult<{
+    count: number;
+    updated: string[];
+    role: string;
+    profile: string;
+}>>;
+/** Parameters for `profile.use`. */
+export interface ProfileUseParams {
+    /** Profile name to mark as default (must exist). */
+    name: string;
+}
+/**
+ * `profile.use` — set a named profile as the global default binding
+ * (`llm.defaultProfile`).
+ *
+ * The profile MUST already exist.
+ *
+ * @task T11700
+ */
+export declare function profileUse(params: ProfileUseParams): Promise<EngineResult<{
+    count: number;
+    updated: string[];
+    profile: string;
+    scope: 'global';
+}>>;
+export {};
+//# sourceMappingURL=entity-ops.d.ts.map

package/dist/llm/entity-ops.d.ts.map

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