@cleocode/contracts 2026.6.12 → 2026.6.14

package/src/operations/llm.ts

@@ -10,6 +10,8 @@
  */
 
 import type { BuiltinProviderId, ProviderId } from '../llm/provider-id.js';
+import type { SealedCredential } from '../llm/sealed-credential.js';
+import type { SystemOfUseKind, SystemOfUsePickerEntry } from '../llm/system-of-use.js';
 
 /**
  * @deprecated since Phase 4 (ADR-072). Use {@link ProviderId} from
@@ -196,6 +198,33 @@ export interface CredentialResultWire {
   authType: AuthTypeWire;
 }
 
+/**
+ * Non-secret credential metadata — the E10 (T11753) redacted view of a resolved
+ * credential that {@link ResolvedLLM} carries inline.
+ *
+ * This is {@link CredentialResultWire} with the secret-bearing `apiKey` field
+ * **structurally removed**. The resolver returns this metadata so consumers can
+ * branch on `authType` / `source` / `provider` (e.g. choose OAuth-vs-api_key
+ * header style, surface `cleo llm whoami` diagnostics) WITHOUT any plaintext
+ * crossing the resolver boundary. The plaintext is reachable ONLY via
+ * {@link ResolvedLLM.sealedCredential}'s `fetch()` at the wire.
+ *
+ * @task T11753
+ * @epic T11746
+ */
+export interface CredentialMetadataWire {
+  /** Provider transport this credential is for. */
+  provider: ModelTransport;
+  /**
+   * Which tier produced this credential. `undefined` only when no credential
+   * was resolved (in which case both this and {@link ResolvedLLM.sealedCredential}
+   * are `null`).
+   */
+  source: CredentialSourceWire | undefined;
+  /** Scheme used to present the credential to the provider. */
+  authType: AuthTypeWire;
+}
+
 // ============================================================================
 // Role-based LLM resolution wire types (T9255 — Phase 2 T-llm-1)
 // ============================================================================
@@ -204,22 +233,28 @@ export interface CredentialResultWire {
  * Which configuration tier produced a {@link ResolvedLLM}.
  *
  * Resolution chain order:
- *   1. `role`               — `config.llm.roles[role]` (explicit override)
- *   2. `profile`            — `config.llm.profiles[roles[role].profile]`
- *   3. `default`            — `config.llm.default` (canonical default)
- *   4. `default-profile`    — `config.llm.profiles[config.llm.defaultProfile]`
- *   5. `implicit-fallback`  — hard-coded fallback inside the resolver
+ *   1. `role`                — `config.llm.roles[role]` (explicit override)
+ *   2. `profile`             — `config.llm.profiles[roles[role].profile]`
+ *   3. `system`              — `config.llm.systems[systemKey]` (granular override)
+ *   4. `default`             — `config.llm.default` (canonical default)
+ *   5. `default-profile`     — `config.llm.profiles[config.llm.defaultProfile]`
+ *   6. `registered-default`  — `registerSystemOfUse()` default (below user config)
+ *   7. `implicit-fallback`   — hard-coded fallback inside the resolver
  *
  * Useful for `cleo llm whoami` diagnostics.
  *
  * @task T9306
  * @task T11617 (`profile`, `default-profile`)
+ * @task T11748 (`system`)
+ * @task T11751 (`registered-default`)
  */
 export type ResolutionSource =
   | 'role'
   | 'profile'
+  | 'system'
   | 'default'
   | 'default-profile'
+  | 'registered-default'
   | 'implicit-fallback';
 
 /**
@@ -256,10 +291,33 @@ export interface ResolvedLLM {
    */
   client: unknown;
   /**
-   * Resolved credential. `null` when no tier produced a token. Callers
-   * MUST handle this case.
+   * Resolved credential **metadata** — provider / source / authType only.
+   * `null` when no tier produced a credential (in which case
+   * {@link sealedCredential} is also `null`). Callers MUST handle this case.
+   *
+   * E10 (T11753): the secret-bearing `apiKey` field has been **removed** — this
+   * is now a {@link CredentialMetadataWire}, NOT the old
+   * {@link CredentialResultWire}. The plaintext token never rides on this
+   * envelope; obtain it ONLY via {@link sealedCredential}'s `fetch()` at the
+   * wire. Branch on `authType` / `source` here for header-style / diagnostics.
    */
-  credential: CredentialResultWire | null;
+  credential: CredentialMetadataWire | null;
+  /**
+   * Sealed credential handle — the E10 on-demand-decrypt credential surface
+   * (T11752 · T11753 · T11746). `null` when no tier produced a credential
+   * (paired with `credential === null`); non-null exactly when a usable
+   * credential was resolved.
+   *
+   * The plaintext token is materialized ONLY by calling
+   * {@link SealedCredential.fetch} at the wire (`transportForProvider` /
+   * `session-factory.ts`) or daemon worker-injection — never returned up this
+   * envelope. This is the canonical credential surface; the old inline
+   * `credential.apiKey` plaintext is gone.
+   *
+   * @task T11752
+   * @task T11753
+   */
+  sealedCredential: SealedCredential | null;
   /** Which config path produced this resolution. */
   source: ResolutionSource;
   /** When `roles[role].credentialLabel` was set, the label that was used. */
@@ -278,6 +336,34 @@ export interface ResolveLLMForRoleOptions {
    * Defaults to `process.cwd()`.
    */
   projectRoot?: string;
+  /**
+   * Optional encoded system-of-use key (e.g. `'sentient'`, `'tool:web-search'`)
+   * that activates the `llm.systems[key]` override tier in the resolution chain
+   * (E9 · T11748).
+   *
+   * When set, `llm.systems[systemKey]` is consulted AFTER any explicit
+   * role/argument override but BEFORE the global `llm.defaultProfile`. Threaded
+   * down by `resolveLLMForSystem`; direct role callers leave it unset and the
+   * system tier is skipped — preserving role-resolution behaviour unchanged.
+   *
+   * @task T11748
+   */
+  systemKey?: string;
+  /**
+   * Optional named profile (a key of `llm.profiles`) that pins this resolution
+   * to a specific provider/model/credential, winning over the role tier
+   * (T11759 · M4).
+   *
+   * When set and the profile resolves, it is the HIGHEST-priority tier of
+   * {@link selectProviderModel} — above `roles[role]` and the `systems[key]`
+   * override — so an explicit caller pin (e.g. a `.cantbook` stage's
+   * `profile:`) cannot be silently overridden by background role config. When
+   * the named profile is absent or structurally incomplete, resolution falls
+   * through to the normal chain unchanged. Direct role callers leave it unset.
+   *
+   * @task T11759
+   */
+  profileOverride?: string;
 }
 
 // ============================================================================
@@ -570,6 +656,32 @@ export interface LlmWhoamiResult {
   entries: LlmWhoamiEntry[];
 }
 
+/**
+ * Parameters for `llm.systems-of-use` (query — the profile-picker enumeration).
+ *
+ * Reserved for future filters (e.g. by {@link SystemOfUsePickerEntry.kind}).
+ *
+ * @task T11751
+ */
+export interface LlmSystemsOfUseParams {
+  /** Optional kind filter — when set, only that axis is enumerated. */
+  kind?: SystemOfUseKind;
+}
+
+/**
+ * Result envelope for `llm.systems-of-use` (query · T11751 · AC2).
+ *
+ * The merged picker surface: every builtin {@link SystemOfUse} plus every
+ * runtime-registered system (`registerSystemOfUse`), so the TUI / Studio
+ * profile picker can enumerate them from ONE op.
+ *
+ * @task T11751
+ */
+export interface LlmSystemsOfUseResult {
+  /** One entry per builtin or registered system-of-use. */
+  entries: SystemOfUsePickerEntry[];
+}
+
 // ProviderProfile interface lives in ./llm/provider-profile.ts (T9262).
 // The generated catalog (packages/core/src/llm/generated/provider-profiles.ts)
 // imports the canonical type from the contracts package and emits each

package/src/operations/output-contracts-data.ts

@@ -24,10 +24,30 @@
  * @task T11692 — DHQ-057: per-operation output schema SSoT
  */
 
+import {
+  accountAddOutputContract,
+  accountListOutputContract,
+  accountRemoveOutputContract,
+  modelQueryOutputContract,
+  modelShowOutputContract,
+  profileCreateOutputContract,
+  profileListOutputContract,
+  profilePinOutputContract,
+  profileUseOutputContract,
+  providerConnectOutputContract,
+  providerListOutputContract,
+  providerShowOutputContract,
+} from './entities.js';
 import type {
   OperationOutputContract,
   OperationOutputContractRegistry,
 } from './output-contract.js';
+import {
+  serviceConnectOutputContract,
+  serviceListOutputContract,
+  serviceRevokeOutputContract,
+  serviceStatusOutputContract,
+} from './service.js';
 
 // ---------------------------------------------------------------------------
 // tasks.show — the operation that bit us (DHQ-057 reproduction)
@@ -334,6 +354,224 @@ const tasksCompleteOutputContract: OperationOutputContract = {
   fieldPointers: ['/data/updated/0', '/data/status', '/data/count'],
 };
 
+// ---------------------------------------------------------------------------
+// tasks.reorder-rank / tasks.bulk-move / tasks.assignee — bulk Kanban mutate
+// ops (T11786 · epic T11556). These ops have NO MUTATE_PROJECTION_PLANS entry,
+// so their raw core result is returned under `envelope.data` unchanged.
+// ---------------------------------------------------------------------------
+
+/**
+ * OUTPUT contract for `tasks.reorder-rank`.
+ *
+ * Grounded in `TasksReorderRankResult`: `{ ranked, skipped, count }`. `ranked`
+ * is the new top-to-bottom order; `skipped` lists request IDs that did not
+ * resolve to a task.
+ */
+const tasksReorderRankOutputContract: OperationOutputContract = {
+  operation: 'tasks.reorder-rank',
+  shapeNote:
+    'Re-ranked IDs (new order) at /data/ranked; unresolved request IDs at /data/skipped; count at /data/count.',
+  dataSchema: {
+    type: 'object',
+    required: ['ranked', 'skipped', 'count'],
+    additionalProperties: true,
+    properties: {
+      ranked: {
+        type: 'array',
+        description: 'Task IDs whose position was written, in the new top-to-bottom order.',
+        items: { type: 'string' },
+      },
+      skipped: {
+        type: 'array',
+        description: 'Request IDs that did not resolve to a task (no-op for these).',
+        items: { type: 'string' },
+      },
+      count: { type: 'number', description: 'Number of tasks re-ranked.' },
+    },
+  },
+  fieldPointers: ['/data/ranked/0', '/data/skipped/0', '/data/count'],
+};
+
+/**
+ * OUTPUT contract for `tasks.bulk-move`.
+ *
+ * Grounded in `TasksBulkMoveResult`: `{ moved, status?, pipelineStage?, count }`.
+ */
+const tasksBulkMoveOutputContract: OperationOutputContract = {
+  operation: 'tasks.bulk-move',
+  shapeNote:
+    'Moved task IDs at /data/moved (all-or-nothing); applied status/stage at /data/status and /data/pipelineStage; count at /data/count.',
+  dataSchema: {
+    type: 'object',
+    required: ['moved', 'count'],
+    additionalProperties: true,
+    properties: {
+      moved: {
+        type: 'array',
+        description: 'Task IDs successfully moved (atomic — empty only when count is 0).',
+        items: { type: 'string' },
+      },
+      status: { type: 'string', description: 'The status applied, when supplied.' },
+      pipelineStage: { type: 'string', description: 'The pipeline stage applied, when supplied.' },
+      count: { type: 'number', description: 'Number of tasks moved.' },
+    },
+  },
+  fieldPointers: ['/data/moved/0', '/data/status', '/data/pipelineStage', '/data/count'],
+};
+
+/**
+ * OUTPUT contract for `tasks.assignee`.
+ *
+ * Grounded in `TasksAssigneeResult`: `{ taskId, assignee, assigned }`. `assignee`
+ * is null when cleared; `assigned` is the boolean verb result.
+ */
+const tasksAssigneeOutputContract: OperationOutputContract = {
+  operation: 'tasks.assignee',
+  shapeNote:
+    'The new assignee is at /data/assignee (null when cleared); /data/assigned is true on set, false on clear.',
+  dataSchema: {
+    type: 'object',
+    required: ['taskId', 'assignee', 'assigned'],
+    additionalProperties: true,
+    properties: {
+      taskId: { type: 'string', description: 'The task ID whose assignee changed.' },
+      assignee: {
+        type: ['string', 'null'],
+        description: 'The new assignee value (null when cleared).',
+      },
+      assigned: { type: 'boolean', description: 'True when an assignee was set; false on clear.' },
+    },
+  },
+  fieldPointers: ['/data/taskId', '/data/assignee', '/data/assigned'],
+};
+
+// ---------------------------------------------------------------------------
+// admin.config.* — config-as-domain (T11917 · M5/AC3 · ConfigManifest cascade)
+// ---------------------------------------------------------------------------
+
+/**
+ * OUTPUT contract for `admin.config.get`.
+ *
+ * Grounded in `AdminConfigGetResult`: `{ key, scope, value, found }`. The
+ * resolved value lives at `/data/value`; `found` disambiguates a present `null`
+ * value from an absent key.
+ */
+const adminConfigGetOutputContract: OperationOutputContract = {
+  operation: 'admin.config.get',
+  shapeNote:
+    'The resolved value is at /data/value (may be null). /data/found is false when the key is absent.',
+  dataSchema: {
+    type: 'object',
+    required: ['key', 'scope', 'value', 'found'],
+    additionalProperties: true,
+    properties: {
+      key: { type: 'string', description: 'The dot-notation key that was resolved.' },
+      scope: {
+        type: 'string',
+        description: 'Cascade slice the value was resolved against.',
+        enum: ['global', 'project', 'merged'],
+      },
+      value: { description: 'Resolved value, or null when the key is absent.' },
+      found: { type: 'boolean', description: 'True IFF the key resolved to a defined value.' },
+    },
+  },
+  fieldPointers: ['/data/key', '/data/scope', '/data/value', '/data/found'],
+};
+
+/**
+ * OUTPUT contract for `admin.config.list`.
+ *
+ * Grounded in `AdminConfigListResult`: `{ scope, config, keys }`. The full
+ * resolved config object is at `/data/config`; flattened keys are at
+ * `/data/keys`.
+ */
+const adminConfigListOutputContract: OperationOutputContract = {
+  operation: 'admin.config.list',
+  shapeNote:
+    'The full resolved config is at /data/config (an object); flattened dot-notation keys are at /data/keys (an array).',
+  dataSchema: {
+    type: 'object',
+    required: ['scope', 'config', 'keys'],
+    additionalProperties: true,
+    properties: {
+      scope: {
+        type: 'string',
+        description: 'Cascade slice the config was resolved against.',
+        enum: ['global', 'project', 'merged'],
+      },
+      config: {
+        type: 'object',
+        description: 'Full resolved config object for the slice.',
+        additionalProperties: true,
+      },
+      keys: {
+        type: 'array',
+        description: 'Flattened dot-notation keys present in the resolved config.',
+        items: { type: 'string' },
+      },
+    },
+  },
+  fieldPointers: ['/data/scope', '/data/keys/0', '/data/keys'],
+};
+
+/**
+ * OUTPUT contract for `admin.config.validate`.
+ *
+ * Grounded in `AdminConfigValidateResult`: `{ scope, ok, issues }`. `ok` is the
+ * pass/fail verdict; `issues` carries human-readable rejection reasons.
+ */
+const adminConfigValidateOutputContract: OperationOutputContract = {
+  operation: 'admin.config.validate',
+  shapeNote:
+    'The pass/fail verdict is at /data/ok; rejection reasons are at /data/issues (empty when ok=true).',
+  dataSchema: {
+    type: 'object',
+    required: ['scope', 'ok', 'issues'],
+    additionalProperties: true,
+    properties: {
+      scope: {
+        type: 'string',
+        description: 'Scope that was validated.',
+        enum: ['global', 'project'],
+      },
+      ok: { type: 'boolean', description: 'True IFF every gate passed.' },
+      issues: {
+        type: 'array',
+        description: 'Human-readable schema issues. Empty when ok=true.',
+        items: { type: 'string' },
+      },
+    },
+  },
+  fieldPointers: ['/data/scope', '/data/ok', '/data/issues/0', '/data/issues'],
+};
+
+/**
+ * OUTPUT contract for `admin.config.unset`.
+ *
+ * Grounded in `AdminConfigUnsetResult`: `{ key, scope, removed }`. `removed` is
+ * `true` IFF the key existed and was deleted (idempotent: `false` when absent).
+ */
+const adminConfigUnsetOutputContract: OperationOutputContract = {
+  operation: 'admin.config.unset',
+  shapeNote:
+    '/data/removed is true IFF a value was deleted; false when the key was already absent (idempotent).',
+  dataSchema: {
+    type: 'object',
+    required: ['key', 'scope', 'removed'],
+    additionalProperties: true,
+    properties: {
+      key: { type: 'string', description: 'The dot-notation key that was targeted.' },
+      scope: {
+        type: 'string',
+        description: 'Scope the key was removed from.',
+        enum: ['project', 'global'],
+      },
+      removed: { type: 'boolean', description: 'True IFF a value was actually deleted.' },
+    },
+  },
+  fieldPointers: ['/data/key', '/data/scope', '/data/removed'],
+};
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -353,4 +591,30 @@ export const OUTPUT_CONTRACTS: OperationOutputContractRegistry = {
   'tasks.add-batch': tasksAddBatchOutputContract,
   'tasks.update': tasksUpdateOutputContract,
   'tasks.complete': tasksCompleteOutputContract,
+  // T11786 (epic T11556) — bulk Kanban mutate ops.
+  'tasks.reorder-rank': tasksReorderRankOutputContract,
+  'tasks.bulk-move': tasksBulkMoveOutputContract,
+  'tasks.assignee': tasksAssigneeOutputContract,
+  'admin.config.get': adminConfigGetOutputContract,
+  'admin.config.list': adminConfigListOutputContract,
+  'admin.config.validate': adminConfigValidateOutputContract,
+  'admin.config.unset': adminConfigUnsetOutputContract,
+  // service-vault CLI verbs (T11941 · epic T11765 · M2-W4)
+  'service.connect': serviceConnectOutputContract,
+  'service.list': serviceListOutputContract,
+  'service.revoke': serviceRevokeOutputContract,
+  'service.status': serviceStatusOutputContract,
+  // 5-entity provider-experience ops (T11700 · epic T11666)
+  'account.add': accountAddOutputContract,
+  'account.list': accountListOutputContract,
+  'account.remove': accountRemoveOutputContract,
+  'provider.list': providerListOutputContract,
+  'provider.show': providerShowOutputContract,
+  'provider.connect': providerConnectOutputContract,
+  'model.query': modelQueryOutputContract,
+  'model.show': modelShowOutputContract,
+  'profile.create': profileCreateOutputContract,
+  'profile.list': profileListOutputContract,
+  'profile.pin': profilePinOutputContract,
+  'profile.use': profileUseOutputContract,
 };