@cleocode/contracts 2026.6.13 → 2026.6.14

package/dist/llm/provider-def.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Declarative `ProviderDef` contract — the DATA shape of one LLM provider.
+ *
+ * M3 Provider SSoT (epic T11667 · task T11702). `ProviderDef` is the DECLARATIVE,
+ * serializable description of a provider: its identity, aliases, auth methods, wire
+ * endpoint (a discriminated union keyed on the `transport` literal), models.dev
+ * catalog key, default headers, optional OAuth flow, and a single request-quirk hook
+ * signature. It is the contract the `providers` global-DB table (T11703) persists and
+ * the alias resolver (T11704) reads.
+ *
+ * ## ProviderDef vs {@link ProviderProfile} — declarative DATA vs runtime BEHAVIOUR
+ *
+ * The pre-existing {@link ProviderProfile} (T9262 · T11756) is the RUNTIME provider
+ * shape carried in the in-process registry: it bundles live hook FUNCTIONS
+ * (`prepareMessages`, `buildExtraBody`, `buildApiKwargsExtras`, `fetchModels`) that
+ * cannot be serialized into a DB row. `ProviderDef` is the DECLARATIVE projection of
+ * the same provider — only serializable DATA — so it can be a `providers` table row,
+ * shipped as a seed, diffed, and resolved without importing provider-specific code.
+ * The builtin `ProviderProfile` set is the SEED SOURCE for the builtin `ProviderDef`
+ * set (the core mapper derives one from the other); the non-serializable hooks stay
+ * on `ProviderProfile`, reduced here to the single declarative {@link RequestQuirk}
+ * descriptor that records WHICH quirk a provider needs without embedding a closure.
+ *
+ * ## Endpoint is a discriminated union (AC5)
+ *
+ * {@link ProviderEndpoint} is a closed discriminated union keyed on the literal
+ * `transport` field — one variant per wire protocol CLEO knows how to speak. No
+ * `any`/`unknown` shortcut: every variant carries its own typed fields. This is the
+ * declarative analog of {@link ApiMode}; the core transport adapter table (T11767)
+ * maps a `transport` value to its `Transport` constructor.
+ *
+ * ## Contracts purity (Gate 10)
+ *
+ * This module is TYPES ONLY — interfaces, type aliases, and `as const` literal arrays.
+ * It exports NO bodied runtime helper. The builtin-set construction and the seed/upsert
+ * logic live in `@cleocode/core` (T11703 · T11704), never here.
+ *
+ * @module llm/provider-def
+ * @task T11702
+ * @epic T11667
+ * @see ./provider-profile.ts — the RUNTIME provider shape (hooks) this projects from
+ * @see ./provider-id.ts — {@link ApiMode} / {@link BuiltinProviderId} the transport mirrors
+ * @see ./oauth.ts — {@link ProviderOAuthConfig} the OAuth flow placeholder reuses
+ * @see ../../../core/src/store/schema/cleo-global/providers.ts — the persisted table (T11703)
+ */
+import type { StoredAuthTypeWire } from '../operations/llm.js';
+import type { ProviderOAuthConfig } from './oauth.js';
+import type { ProviderId } from './provider-id.js';
+/**
+ * Wire-transport discriminant for a {@link ProviderEndpoint} variant.
+ *
+ * Closed union — one literal per protocol CLEO has a transport for. The
+ * declarative analog of {@link import('./provider-id.js').ApiMode}:
+ *
+ * - `openai-completions` — OpenAI `/chat/completions` shape (OpenAI, OpenRouter,
+ *   Moonshot, Kimi, xAI, Gemini-via-OpenAI-compat) — `ApiMode 'chat_completions'`.
+ * - `openai-responses` — OpenAI Responses API (Codex backend, xAI-responses) —
+ *   `ApiMode 'codex_responses'`.
+ * - `anthropic-messages` — native Anthropic Messages API (prompt-cache + thinking) —
+ *   `ApiMode 'anthropic_messages'`.
+ * - `aisdk` — routed through the Vercel AI-SDK provider factory (the data-driven
+ *   `apiMode → provider` adapter, T11767) rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export declare const PROVIDER_TRANSPORTS: readonly ["openai-completions", "openai-responses", "anthropic-messages", "aisdk"];
+/** TypeScript union derived from {@link PROVIDER_TRANSPORTS}. */
+export type ProviderTransport = (typeof PROVIDER_TRANSPORTS)[number];
+/**
+ * Endpoint for the `openai-completions` transport — the OpenAI
+ * `/chat/completions` wire shape (OpenAI, OpenRouter, Moonshot, Kimi, xAI,
+ * Gemini-via-compat). `baseUrl` has NO trailing slash.
+ *
+ * @task T11702
+ */
+export interface OpenAICompletionsEndpoint {
+    /** Discriminant — the OpenAI chat-completions wire protocol. */
+    readonly transport: 'openai-completions';
+    /** Base URL for the provider's API — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `openai-responses` transport — the OpenAI Responses API
+ * (Codex backend, xAI-responses). `baseUrl` has NO trailing slash.
+ *
+ * @task T11702
+ */
+export interface OpenAIResponsesEndpoint {
+    /** Discriminant — the OpenAI Responses wire protocol. */
+    readonly transport: 'openai-responses';
+    /** Base URL for the Responses endpoint — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `anthropic-messages` transport — the native Anthropic
+ * Messages API (full prompt-cache + extended thinking). `baseUrl` has NO
+ * trailing slash.
+ *
+ * @task T11702
+ */
+export interface AnthropicMessagesEndpoint {
+    /** Discriminant — the native Anthropic Messages wire protocol. */
+    readonly transport: 'anthropic-messages';
+    /** Base URL for the Anthropic API — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `aisdk` transport — the provider is reached through the
+ * Vercel AI-SDK provider factory (the data-driven adapter table, T11767) keyed
+ * by `aiSdkProvider`, rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export interface AiSdkEndpoint {
+    /** Discriminant — routed through the AI-SDK provider factory. */
+    readonly transport: 'aisdk';
+    /** Base URL passed to the AI-SDK provider factory — no trailing slash. */
+    readonly baseUrl: string;
+    /**
+     * The AI-SDK provider-factory key (e.g. `openai-compatible` | `google` |
+     * `bedrock`) the adapter table maps to a `create*` factory. NEVER an inline
+     * client construction — the factory call is the LLM chokepoint (T11783).
+     */
+    readonly aiSdkProvider: string;
+}
+/**
+ * A provider's wire endpoint — a discriminated union keyed on the `transport`
+ * literal (AC5). Exactly one variant per {@link ProviderTransport}; each carries
+ * its own typed fields, with no `any`/`unknown` shortcut.
+ *
+ * @task T11702
+ */
+export type ProviderEndpoint = OpenAICompletionsEndpoint | OpenAIResponsesEndpoint | AnthropicMessagesEndpoint | AiSdkEndpoint;
+/**
+ * Known request-quirk kinds — the DECLARATIVE record of WHICH provider-specific
+ * request adjustment a provider needs, WITHOUT embedding the closure.
+ *
+ * The live closures stay on {@link ProviderProfile} (`buildExtraBody` /
+ * `buildApiKwargsExtras` / `prepareMessages`); a `ProviderDef` row records only
+ * the quirk's stable kind so the table/seed stays serializable. The runtime maps
+ * a {@link RequestQuirk} `kind` back to its hook implementation.
+ *
+ * - `grok-conv-id` — inject the process-scoped `x-grok-conv-id` header (xAI).
+ * - `gemini-thinking-config` — inject `thinking_config` in `extra_body` (Gemini).
+ * - `kimi-reasoning-effort` — top-level `reasoning_effort` kwarg (Kimi Code).
+ * - `moonshot-schema-sanitize` — shallow tool-schema sanitization (Moonshot).
+ * - `openrouter-pareto` — inject the Pareto price-router plugin (OpenRouter).
+ *
+ * @task T11702
+ */
+export declare const REQUEST_QUIRK_KINDS: readonly ["grok-conv-id", "gemini-thinking-config", "kimi-reasoning-effort", "moonshot-schema-sanitize", "openrouter-pareto"];
+/** TypeScript union derived from {@link REQUEST_QUIRK_KINDS}. */
+export type RequestQuirkKind = (typeof REQUEST_QUIRK_KINDS)[number];
+/**
+ * A single declarative request-quirk descriptor (AC4 — the "request-quirk hook
+ * signature"). Records the quirk's stable {@link RequestQuirkKind} so a
+ * `ProviderDef` row stays serializable; the runtime resolves the `kind` to its
+ * hook implementation on {@link ProviderProfile}. The signature the hook MUST
+ * satisfy is `(model: string) => Record<string, unknown>` (the declarative shape
+ * of `buildExtraBody` / `buildApiKwargsExtras`), captured here only as the
+ * documented contract — never as an embedded closure.
+ *
+ * @task T11702
+ */
+export interface RequestQuirk {
+    /** The stable quirk kind this provider needs. */
+    readonly kind: RequestQuirkKind;
+}
+/**
+ * OAuth flow placeholder embedded on a {@link ProviderDef} (AC4).
+ *
+ * For M3 this is the existing {@link ProviderOAuthConfig} shape (PKCE / device-code
+ * endpoints + client id), aliased so the M4 vault work (T10409) can widen it without
+ * a contract rename. A `ProviderDef` carries `oauth` only when the provider supports
+ * an OAuth login flow (anthropic, openai, kimi-code); it is omitted otherwise.
+ *
+ * @task T11702
+ */
+export type OAuthFlowDef = ProviderOAuthConfig;
+/**
+ * Declarative description of one LLM provider — the serializable DATA SSoT.
+ *
+ * The contract persisted as a `providers` table row (T11703) and read by the alias
+ * resolver (T11704). Derived from the runtime {@link ProviderProfile} set: identity
+ * + aliases + auth + endpoint + catalog key + headers + optional OAuth + the
+ * declarative request quirks. Carries NO closures — only serializable DATA.
+ *
+ * @task T11702
+ */
+export interface ProviderDef {
+    /**
+     * Canonical provider id (lower-cased). For builtins this is a
+     * {@link BuiltinProviderId}; plugin providers may use any non-empty string.
+     */
+    readonly id: ProviderId;
+    /** Human-readable display name shown in pickers and diagnostic output. */
+    readonly displayName: string;
+    /**
+     * Alternate names that resolve to this provider (case-insensitive). The SINGLE
+     * source the alias resolver (T11704) reads — `codex`/`chatgpt` → `openai`,
+     * `claude` → `anthropic`, `google` → `gemini`, … An alias colliding with another
+     * provider's primary `id` is a resolution error (T11704 AC2).
+     */
+    readonly aliases: ReadonlyArray<string>;
+    /**
+     * Authentication mechanisms this provider supports (`api_key` | `oauth` |
+     * `aws_sdk`). The {@link StoredAuthTypeWire} wire enum.
+     */
+    readonly authMethods: ReadonlyArray<StoredAuthTypeWire>;
+    /**
+     * The provider's wire endpoint — a discriminated union keyed on `transport`
+     * (AC5). A provider that speaks multiple protocols (e.g. xAI completions +
+     * responses) carries the multiple variants in {@link altEndpoints}.
+     */
+    readonly endpoint: ProviderEndpoint;
+    /**
+     * Additional wire endpoints this provider also speaks, beyond the primary
+     * {@link endpoint}. Collapses the prior per-ApiMode profile duplication into ONE
+     * row (T11703 AC4 — xAI's completions + responses become one `ProviderDef`).
+     * Empty/omitted for single-protocol providers.
+     */
+    readonly altEndpoints?: ReadonlyArray<ProviderEndpoint>;
+    /**
+     * The models.dev catalog provider key joining this provider to the
+     * `models_catalog` table (T11733). Usually equals {@link id}; carried distinctly
+     * because a provider id and its catalog key can differ (e.g. `kimi-code` →
+     * `moonshot`).
+     */
+    readonly modelsDevId: string;
+    /**
+     * HTTP headers sent with every request to this provider, merged into the
+     * client's `defaultHeaders` (e.g. `{ 'anthropic-version': '2023-06-01' }`).
+     * Omitted when the provider needs no pinned headers.
+     */
+    readonly defaultHeaders?: Readonly<Record<string, string>>;
+    /**
+     * Environment variable names that may supply this provider's API key (e.g.
+     * `['ANTHROPIC_API_KEY']`). Resolver chains may check these before the vault.
+     * Omitted when the provider has no env-var credential path.
+     */
+    readonly envVars?: ReadonlyArray<string>;
+    /**
+     * OAuth flow placeholder (AC4) — present only when the provider supports an
+     * OAuth login flow (anthropic, openai, kimi-code). See {@link OAuthFlowDef}.
+     */
+    readonly oauth?: OAuthFlowDef;
+    /**
+     * Declarative request quirks this provider needs (AC4) — the stable
+     * {@link RequestQuirk} descriptors WITHOUT the closures (those stay on
+     * {@link ProviderProfile}). Empty/omitted when the provider needs no quirk.
+     */
+    readonly requestQuirks?: ReadonlyArray<RequestQuirk>;
+}
+//# sourceMappingURL=provider-def.d.ts.map

package/dist/llm/provider-def.d.ts.map

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

package/dist/llm/provider-def.js

@@ -0,0 +1,93 @@
+/**
+ * Declarative `ProviderDef` contract — the DATA shape of one LLM provider.
+ *
+ * M3 Provider SSoT (epic T11667 · task T11702). `ProviderDef` is the DECLARATIVE,
+ * serializable description of a provider: its identity, aliases, auth methods, wire
+ * endpoint (a discriminated union keyed on the `transport` literal), models.dev
+ * catalog key, default headers, optional OAuth flow, and a single request-quirk hook
+ * signature. It is the contract the `providers` global-DB table (T11703) persists and
+ * the alias resolver (T11704) reads.
+ *
+ * ## ProviderDef vs {@link ProviderProfile} — declarative DATA vs runtime BEHAVIOUR
+ *
+ * The pre-existing {@link ProviderProfile} (T9262 · T11756) is the RUNTIME provider
+ * shape carried in the in-process registry: it bundles live hook FUNCTIONS
+ * (`prepareMessages`, `buildExtraBody`, `buildApiKwargsExtras`, `fetchModels`) that
+ * cannot be serialized into a DB row. `ProviderDef` is the DECLARATIVE projection of
+ * the same provider — only serializable DATA — so it can be a `providers` table row,
+ * shipped as a seed, diffed, and resolved without importing provider-specific code.
+ * The builtin `ProviderProfile` set is the SEED SOURCE for the builtin `ProviderDef`
+ * set (the core mapper derives one from the other); the non-serializable hooks stay
+ * on `ProviderProfile`, reduced here to the single declarative {@link RequestQuirk}
+ * descriptor that records WHICH quirk a provider needs without embedding a closure.
+ *
+ * ## Endpoint is a discriminated union (AC5)
+ *
+ * {@link ProviderEndpoint} is a closed discriminated union keyed on the literal
+ * `transport` field — one variant per wire protocol CLEO knows how to speak. No
+ * `any`/`unknown` shortcut: every variant carries its own typed fields. This is the
+ * declarative analog of {@link ApiMode}; the core transport adapter table (T11767)
+ * maps a `transport` value to its `Transport` constructor.
+ *
+ * ## Contracts purity (Gate 10)
+ *
+ * This module is TYPES ONLY — interfaces, type aliases, and `as const` literal arrays.
+ * It exports NO bodied runtime helper. The builtin-set construction and the seed/upsert
+ * logic live in `@cleocode/core` (T11703 · T11704), never here.
+ *
+ * @module llm/provider-def
+ * @task T11702
+ * @epic T11667
+ * @see ./provider-profile.ts — the RUNTIME provider shape (hooks) this projects from
+ * @see ./provider-id.ts — {@link ApiMode} / {@link BuiltinProviderId} the transport mirrors
+ * @see ./oauth.ts — {@link ProviderOAuthConfig} the OAuth flow placeholder reuses
+ * @see ../../../core/src/store/schema/cleo-global/providers.ts — the persisted table (T11703)
+ */
+/**
+ * Wire-transport discriminant for a {@link ProviderEndpoint} variant.
+ *
+ * Closed union — one literal per protocol CLEO has a transport for. The
+ * declarative analog of {@link import('./provider-id.js').ApiMode}:
+ *
+ * - `openai-completions` — OpenAI `/chat/completions` shape (OpenAI, OpenRouter,
+ *   Moonshot, Kimi, xAI, Gemini-via-OpenAI-compat) — `ApiMode 'chat_completions'`.
+ * - `openai-responses` — OpenAI Responses API (Codex backend, xAI-responses) —
+ *   `ApiMode 'codex_responses'`.
+ * - `anthropic-messages` — native Anthropic Messages API (prompt-cache + thinking) —
+ *   `ApiMode 'anthropic_messages'`.
+ * - `aisdk` — routed through the Vercel AI-SDK provider factory (the data-driven
+ *   `apiMode → provider` adapter, T11767) rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export const PROVIDER_TRANSPORTS = [
+    'openai-completions',
+    'openai-responses',
+    'anthropic-messages',
+    'aisdk',
+];
+/**
+ * Known request-quirk kinds — the DECLARATIVE record of WHICH provider-specific
+ * request adjustment a provider needs, WITHOUT embedding the closure.
+ *
+ * The live closures stay on {@link ProviderProfile} (`buildExtraBody` /
+ * `buildApiKwargsExtras` / `prepareMessages`); a `ProviderDef` row records only
+ * the quirk's stable kind so the table/seed stays serializable. The runtime maps
+ * a {@link RequestQuirk} `kind` back to its hook implementation.
+ *
+ * - `grok-conv-id` — inject the process-scoped `x-grok-conv-id` header (xAI).
+ * - `gemini-thinking-config` — inject `thinking_config` in `extra_body` (Gemini).
+ * - `kimi-reasoning-effort` — top-level `reasoning_effort` kwarg (Kimi Code).
+ * - `moonshot-schema-sanitize` — shallow tool-schema sanitization (Moonshot).
+ * - `openrouter-pareto` — inject the Pareto price-router plugin (OpenRouter).
+ *
+ * @task T11702
+ */
+export const REQUEST_QUIRK_KINDS = [
+    'grok-conv-id',
+    'gemini-thinking-config',
+    'kimi-reasoning-effort',
+    'moonshot-schema-sanitize',
+    'openrouter-pareto',
+];
+//# sourceMappingURL=provider-def.js.map

package/dist/llm/provider-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-def.js","sourceRoot":"","sources":["../../src/llm/provider-def.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,OAAO;CACC,CAAC;AA+EX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,cAAc;IACd,wBAAwB;IACxB,uBAAuB;IACvB,0BAA0B;IAC1B,mBAAmB;CACX,CAAC"}

package/dist/llm/system-resolver.d.ts

@@ -110,5 +110,47 @@ export interface ResolveLLMForSystemOptions {
      * @internal
      */
     skipCatalogDefault?: boolean;
+    /**
+     * Raw prompt used to derive a role from complexity when neither an explicit
+     * tier/role nor a role-mapped system label is available (L1 proposer · T11906).
+     *
+     * When the `system` argument is the flat `'default'` label (which maps to NO
+     * role) and `roleOverride` is unset, the resolver runs the L1 complexity
+     * classifier over this prompt and proposes a {@link RoleName} from the
+     * resulting tier (`low → hygiene`, `mid → consolidation`, `high → judgement`).
+     * This is a COMPLEMENT to the resolver — it only supplies a role when one is
+     * otherwise absent; an explicit label, descriptor, or `roleOverride` always
+     * wins. The classifier returns a TIER only and constructs no LLM client.
+     *
+     * Ignored when the role is already determined by the input or `roleOverride`.
+     */
+    complexityPrompt?: string;
+    /**
+     * Explicit encoded system-of-use key for the `llm.systems[key]` granular
+     * override tier (T11759 · M4).
+     *
+     * The flat-label input form derives this key from `system` itself; this option
+     * lets a caller resolving an OPEN-axis system (whose identity is NOT a flat
+     * {@link SystemOfUseLabel}) — e.g. a `.cantbook` node keyed
+     * `cantbook:<playbook>#<nodeId>` — supply that identity as the granular
+     * override + audit key while passing a resolvable background label as
+     * `system`. When set, it OVERRIDES the label-derived key. Omit it and the
+     * pre-T11759 derivation is unchanged.
+     *
+     * @task T11759
+     */
+    systemKey?: string;
+    /**
+     * Optional named profile (a key of `llm.profiles`) that pins the resolution to
+     * a specific provider/model/credential, winning over the role tier (T11759 ·
+     * M4).
+     *
+     * Threaded down to `ResolveLLMForRoleOptions.profileOverride`. A `.cantbook`
+     * stage's `profile:` flows through here. When the named profile is
+     * absent/incomplete, resolution falls through the normal chain unchanged.
+     *
+     * @task T11759
+     */
+    profile?: string;
 }
 //# sourceMappingURL=system-resolver.d.ts.map

package/dist/llm/system-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-resolver.d.ts","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,QAAQ,GACR,eAAe,GACf,SAAS,GACT,SAAS,GACT,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,GAAG,IAAI,CAAC,CAUtE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;IAExB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}
+{"version":3,"file":"system-resolver.d.ts","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,QAAQ,GACR,eAAe,GACf,SAAS,GACT,SAAS,GACT,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,GAAG,IAAI,CAAC,CAUtE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;IAExB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/operations/admin.d.ts

@@ -335,7 +335,7 @@ export interface AdminPresetChange {
  * Query operations are read-only. Mutate operations write to the filesystem,
  * SQLite, or trigger side-effectful system actions.
  */
-export type AdminOp = 'admin.version' | 'admin.health' | 'admin.config.show' | 'admin.config.presets' | 'admin.stats' | 'admin.context' | 'admin.context.pull' | 'admin.runtime' | 'admin.paths' | 'admin.job' | 'admin.dash' | 'admin.log' | 'admin.sequence' | 'admin.help' | 'admin.token' | 'admin.adr.find' | 'admin.adr.show' | 'admin.backup' | 'admin.export' | 'admin.map' | 'admin.roadmap' | 'admin.smoke' | 'admin.smoke.provider' | 'admin.hooks.matrix' | 'admin.init' | 'admin.scaffold-hub' | 'admin.health.mutate' | 'admin.config.set' | 'admin.config.set-preset' | 'admin.backup.mutate' | 'admin.migrate' | 'admin.cleanup' | 'admin.job.cancel' | 'admin.safestop' | 'admin.inject.generate' | 'admin.adr.sync' | 'admin.import' | 'admin.detect' | 'admin.token.mutate' | 'admin.context.inject' | 'admin.map.mutate' | 'admin.install.global';
+export type AdminOp = 'admin.version' | 'admin.health' | 'admin.config.show' | 'admin.config.presets' | 'admin.config.get' | 'admin.config.list' | 'admin.config.validate' | 'admin.stats' | 'admin.context' | 'admin.context.pull' | 'admin.runtime' | 'admin.paths' | 'admin.job' | 'admin.dash' | 'admin.log' | 'admin.sequence' | 'admin.help' | 'admin.token' | 'admin.adr.find' | 'admin.adr.show' | 'admin.backup' | 'admin.export' | 'admin.map' | 'admin.roadmap' | 'admin.smoke' | 'admin.smoke.provider' | 'admin.hooks.matrix' | 'admin.init' | 'admin.scaffold-hub' | 'admin.health.mutate' | 'admin.config.set' | 'admin.config.set-preset' | 'admin.config.unset' | 'admin.backup.mutate' | 'admin.migrate' | 'admin.cleanup' | 'admin.job.cancel' | 'admin.safestop' | 'admin.inject.generate' | 'admin.adr.sync' | 'admin.import' | 'admin.detect' | 'admin.token.mutate' | 'admin.context.inject' | 'admin.map.mutate' | 'admin.install.global';
 /** Parameters for `admin.version` — none required. */
 export type AdminVersionParams = Record<string, never>;
 /** Result of `admin.version`. */
@@ -400,6 +400,90 @@ export interface AdminConfigPresetsResult {
     /** Available strictness presets with their settings. */
     presets: AdminPresetDefinition[];
 }
+/**
+ * Cascade slice selector for the config-as-domain query ops.
+ *
+ * - `'global'`  — read ONLY `~/.cleo/config.json` (precedence 10)
+ * - `'project'` — read ONLY `<project>/.cleo/config.json` (precedence 20)
+ * - `'merged'`  — read the deep-merge `{ ...global, ...project }` (default)
+ *
+ * Mirrors the `ResolveScope` of the `resolveCleoConfig` cascade resolver.
+ *
+ * @task T11917
+ */
+export type AdminConfigScope = 'global' | 'project' | 'merged';
+/** Parameters for `admin.config.get`. */
+export interface AdminConfigGetParams {
+    /** Dot-notation config key to read a single value (required). */
+    key: string;
+    /** Cascade slice to read from. Defaults to `'merged'`. */
+    scope?: AdminConfigScope;
+}
+/**
+ * Result of `admin.config.get`.
+ *
+ * Returns the resolved value for `key`, or `null` when the key is absent in the
+ * selected cascade slice. `found` disambiguates a present `null` value from an
+ * absent key.
+ *
+ * @task T11917
+ */
+export interface AdminConfigGetResult {
+    /** The dot-notation key that was resolved. */
+    key: string;
+    /** Cascade slice the value was resolved against. */
+    scope: AdminConfigScope;
+    /** Resolved value, or `null` when the key is absent. */
+    value: unknown;
+    /** `true` IFF the key resolved to a defined value in the cascade. */
+    found: boolean;
+}
+/** Parameters for `admin.config.list`. */
+export interface AdminConfigListParams {
+    /** Cascade slice to project. Defaults to `'merged'`. */
+    scope?: AdminConfigScope;
+}
+/**
+ * Result of `admin.config.list`.
+ *
+ * Returns the full resolved config object for the selected cascade slice plus
+ * the flattened dot-notation key list for discovery.
+ *
+ * @task T11917
+ */
+export interface AdminConfigListResult {
+    /** Cascade slice the config was resolved against. */
+    scope: AdminConfigScope;
+    /** Full resolved config object for the slice. */
+    config: Record<string, unknown>;
+    /** Flattened dot-notation keys present in the resolved config. */
+    keys: string[];
+}
+/** Parameters for `admin.config.validate`. */
+export interface AdminConfigValidateParams {
+    /**
+     * Scope to validate. Only the cascade-participating scopes are valid —
+     * `'merged'` is rejected because validation runs against a single file's
+     * manifest entry schema. Defaults to `'project'`.
+     */
+    scope?: 'global' | 'project';
+}
+/**
+ * Result of `admin.config.validate`.
+ *
+ * `ok` is `true` IFF the file passed its manifest entry's schema gate (or no
+ * schema was configured). `issues` carries human-readable rejection reasons.
+ *
+ * @task T11917
+ */
+export interface AdminConfigValidateResult {
+    /** Scope that was validated. */
+    scope: 'global' | 'project';
+    /** `true` IFF every gate passed. */
+    ok: boolean;
+    /** Human-readable schema issues. Empty when `ok === true`. */
+    issues: string[];
+}
 /** Parameters for `admin.stats`. */
 export interface AdminStatsParams {
     /** Rolling measurement period in days (default 30). */
@@ -1189,6 +1273,29 @@ export interface AdminConfigSetResult {
     /** New value assigned. */
     value: unknown;
 }
+/** Parameters for `admin.config.unset`. */
+export interface AdminConfigUnsetParams {
+    /** Dot-notation config key to remove (required). */
+    key: string;
+    /** Remove from the global file instead of the project file. */
+    global?: boolean;
+}
+/**
+ * Result of `admin.config.unset`.
+ *
+ * `removed` is `true` IFF the key existed and was deleted; `false` when the key
+ * was already absent (idempotent no-op).
+ *
+ * @task T11917
+ */
+export interface AdminConfigUnsetResult {
+    /** Config key that was targeted. */
+    key: string;
+    /** Scope the key was removed from. */
+    scope: 'project' | 'global';
+    /** `true` IFF a value was actually deleted. */
+    removed: boolean;
+}
 /** Parameters for `admin.config.set-preset`. */
 export interface AdminConfigSetPresetParams {
     /** Preset to apply (`strict`, `standard`, or `minimal`). */
@@ -1627,6 +1734,18 @@ export type AdminOps = {
     op: 'admin.config.presets';
     params: AdminConfigPresetsParams;
     result: AdminConfigPresetsResult;
+} | {
+    op: 'admin.config.get';
+    params: AdminConfigGetParams;
+    result: AdminConfigGetResult;
+} | {
+    op: 'admin.config.list';
+    params: AdminConfigListParams;
+    result: AdminConfigListResult;
+} | {
+    op: 'admin.config.validate';
+    params: AdminConfigValidateParams;
+    result: AdminConfigValidateResult;
 } | {
     op: 'admin.stats';
     params: AdminStatsParams;
@@ -1727,6 +1846,10 @@ export type AdminOps = {
     op: 'admin.config.set-preset';
     params: AdminConfigSetPresetParams;
     result: AdminConfigSetPresetResult;
+} | {
+    op: 'admin.config.unset';
+    params: AdminConfigUnsetParams;
+    result: AdminConfigUnsetResult;
 } | {
     op: 'admin.backup.mutate';
     params: AdminBackupMutateParams;