@cleocode/contracts 2026.6.12 → 2026.6.14

package/src/conduit.ts

@@ -264,6 +264,206 @@ export interface Conduit {
   readonly agentId: string;
 }
 
+// ============================================================================
+// Channel Adapter (T11952 · epic T11854 · saga T10419)
+// ============================================================================
+//
+// A ChannelAdapter is the boundary between an external conversation surface
+// (a terminal TUI, Telegram chat, Discord channel, …) and the CLEO agent
+// runtime. Each adapter wraps a {@link Transport} (the wire layer) and exposes
+// a uniform, platform-agnostic contract so the Session Store + Delivery Router
+// can route inbound user messages to the agent and route the agent's reply back
+// to the originating channel.
+//
+// The Local-TUI adapter is the FIRST reference adapter (T11952): it rides the
+// in-process {@link Transport} (conduit `LocalTransport`) and works fully
+// offline, daemon-OFF, with no network and no platform credential. Platform
+// adapters (Telegram/Discord/Slack/WhatsApp) implement this same contract but
+// are credential+network gated and out of scope for T11952.
+
+/**
+ * Liveness verdict for a single channel adapter.
+ *
+ * - `connected` — the adapter is connected to its transport and ready to
+ *   receive/send.
+ * - `degraded` — the adapter is reachable but operating with reduced capability
+ *   (e.g. polling fallback, partial subscription).
+ * - `disconnected` — the adapter is not currently connected.
+ * - `error` — the adapter encountered a fatal error; see {@link ChannelHealth.detail}.
+ */
+export type ChannelHealthStatus = 'connected' | 'degraded' | 'disconnected' | 'error';
+
+/**
+ * Health snapshot for a single {@link ChannelAdapter}.
+ *
+ * Surfaced by `cleo channels list` as part of the LAFS RenderableEnvelope and
+ * consumed by the Delivery Router to skip dead channels.
+ */
+export interface ChannelHealth {
+  /** Stable channel identifier (matches {@link ChannelAdapter.id}). */
+  channelId: string;
+  /** Coarse liveness verdict. */
+  status: ChannelHealthStatus;
+  /** Underlying transport name (e.g. `'local'`, `'http'`, `'sse'`). */
+  transport: string;
+  /** Human-readable detail for non-`connected` states (error message, reason). */
+  detail?: string;
+  /** ISO 8601 timestamp the health was sampled. */
+  checkedAt: string;
+}
+
+/**
+ * Per-channel configuration knobs shared by every {@link ChannelAdapter}.
+ *
+ * Platform adapters extend this with credential fields; the Local-TUI adapter
+ * uses only the platform-agnostic subset.
+ *
+ * @see T11854 AC1 — `home_channel`, `require_mention`, `allowed_users`.
+ */
+export interface ChannelConfig {
+  /**
+   * The home channel address replies fall back to when an inbound message has
+   * no explicit reply target (e.g. the default conversation/thread id).
+   */
+  homeChannel?: string;
+  /**
+   * When `true`, the adapter only dispatches inbound messages that explicitly
+   * mention the agent. Defaults to `false` for the Local-TUI adapter (every
+   * line is addressed to the agent).
+   */
+  requireMention?: boolean;
+  /**
+   * Allowlist of sender identifiers permitted to reach the agent. When omitted
+   * or empty, all senders are allowed (the Local-TUI default — a single local
+   * operator).
+   */
+  allowedUsers?: readonly string[];
+}
+
+/**
+ * An inbound message arriving from a channel surface, normalized into the
+ * platform-agnostic shape the Delivery Router consumes.
+ *
+ * It is a thin projection over {@link ConduitMessage} carrying the originating
+ * channel so the router can preserve session affinity.
+ */
+export interface InboundMsg {
+  /** Stable message id (from the underlying transport). */
+  id: string;
+  /** Channel the message originated on (the {@link ChannelAdapter.id}). */
+  channelId: string;
+  /** Sender identifier within the channel (user/agent id). */
+  from: string;
+  /** Message text content. */
+  content: string;
+  /**
+   * Channel-native conversation/thread id used for session affinity. The router
+   * keys the {@link ChannelSession} on `(channelId, sessionKey)`.
+   */
+  sessionKey: string;
+  /** ISO 8601 timestamp the message was received. */
+  timestamp: string;
+  /** Optional structured payload carried alongside the message. */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * An outbound reply the agent emits in response to an {@link InboundMsg}.
+ *
+ * The Delivery Router resolves the target channel + session from the originating
+ * {@link InboundMsg} (or an explicit {@link OutboundReply.channelId}) and calls
+ * {@link ChannelAdapter.send}.
+ */
+export interface OutboundReply {
+  /**
+   * Target channel id. When omitted, the router routes to the channel that
+   * originated the {@link InboundMsg} being replied to (session affinity).
+   */
+  channelId?: string;
+  /**
+   * Target session/thread key. When omitted, the router uses the originating
+   * inbound message's {@link InboundMsg.sessionKey}, then the channel's
+   * {@link ChannelConfig.homeChannel} fallback.
+   */
+  sessionKey?: string;
+  /** Reply text content. */
+  content: string;
+  /** Optional structured payload carried with the reply. */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * A persisted per-channel session-affinity record.
+ *
+ * The Session Store tracks the most recent inbound exchange per
+ * `(channelId, sessionKey)` so the Delivery Router can route an agent reply
+ * back to the originating channel without the caller threading routing state.
+ *
+ * @see T1797 — Session Store + Delivery Router.
+ */
+export interface ChannelSession {
+  /** Channel the session belongs to. */
+  channelId: string;
+  /** Channel-native conversation/thread key. */
+  sessionKey: string;
+  /** Sender identifier of the last inbound message in this session. */
+  lastFrom: string;
+  /** Id of the last inbound message routed for this session. */
+  lastInboundId: string;
+  /** ISO 8601 timestamp the session was last touched. */
+  updatedAt: string;
+}
+
+/**
+ * The platform-agnostic channel boundary contract.
+ *
+ * Every channel (Local-TUI, Telegram, Discord, Slack, WhatsApp, …) implements
+ * this interface. Adapters wrap a {@link Transport} and translate between the
+ * channel-native surface and the normalized {@link InboundMsg} /
+ * {@link OutboundReply} shapes the router consumes.
+ *
+ * Implementations:
+ * - `LocalTuiChannelAdapter` (`@cleocode/core` — rides conduit `LocalTransport`,
+ *   the first reference adapter, T11952).
+ * - Platform adapters (Telegram/Discord/Slack/WhatsApp) — credential+network
+ *   gated, implemented under T11855 (out of scope for T11952).
+ *
+ * @see T11854 AC1 — start/stop/onMessage/sendMessage/health.
+ */
+export interface ChannelAdapter {
+  /** Stable, kebab-case channel identifier (e.g. `'local-tui'`). */
+  readonly id: string;
+  /** Effective per-channel configuration. */
+  readonly config: ChannelConfig;
+
+  /** Start the adapter: connect its transport and begin receiving. */
+  start(): Promise<void>;
+
+  /** Stop the adapter: detach handlers and disconnect its transport. */
+  stop(): Promise<void>;
+
+  /**
+   * Stream of inbound messages from the channel.
+   *
+   * Yields each {@link InboundMsg} as it arrives until {@link ChannelAdapter.stop}
+   * is called (which ends the iterator). Honors {@link ChannelConfig.requireMention}
+   * and {@link ChannelConfig.allowedUsers} filtering before yielding.
+   */
+  receive(): AsyncIterable<InboundMsg>;
+
+  /**
+   * Send a reply back to the channel.
+   *
+   * @param reply - The outbound reply. The adapter resolves the destination
+   *   session via {@link OutboundReply.sessionKey} then
+   *   {@link ChannelConfig.homeChannel}.
+   */
+  send(reply: OutboundReply): Promise<void>;
+
+  /** Sample the adapter's current health. */
+  health(): ChannelHealth;
+}
+
 // ============================================================================
 // Factory
 // ============================================================================

package/src/config/index.ts

@@ -0,0 +1,35 @@
+/**
+ * `@cleocode/contracts/config` — config-domain contract surface.
+ *
+ * Subpath barrel that surfaces the `ConfigManifest` contract (the
+ * {@link ConfigManifestEntry} shape, its Zod validator
+ * {@link configManifestEntrySchema}, and the built-in manifest entries) under a
+ * stable, config-scoped import path. This is the AC3 surface for the
+ * config-as-domain work (T11917): consumers that only need the manifest contract
+ * import from `@cleocode/contracts/config` instead of pulling the full index.
+ *
+ * The types are also re-exported from the package root (`@cleocode/contracts`)
+ * for backwards compatibility — this barrel is an additive, narrower entrypoint.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/config
+ *
+ * @task T11917 — config-as-domain (M5/AC3)
+ * @task T9876 — ConfigManifest contract
+ * @saga T9855
+ */
+
+export type {
+  ConfigManifestEntry,
+  ConfigManifestScope,
+  ConfigScope,
+  DriftDetection,
+} from './manifest.js';
+export {
+  CLEO_CONFIG_MANIFEST,
+  CONFIG_MANIFEST_ENTRIES,
+  configManifestEntrySchema,
+  GLOBAL_CLEO_CONFIG_MANIFEST,
+  PROJECT_CONTEXT_MANIFEST,
+  PROJECT_INFO_MANIFEST,
+} from './manifest.js';

package/src/config.ts

@@ -475,6 +475,29 @@ export interface LlmProfileTuning {
   temperature?: number;
 }
 
+/**
+ * Capability lane a named profile occupies — the hermes "global-base +
+ * granular-override" tiering model (E9 · T11745 · T11748).
+ *
+ * A profile's `tier` is a coarse capability hint a runner can use to pick the
+ * right lane for a turn independently of the role/system axis:
+ *
+ * | Tier         | Meaning                                                          |
+ * |--------------|------------------------------------------------------------------|
+ * | `prime`      | The flagship reasoning lane — orchestration / hard turns.         |
+ * | `aux`        | The auxiliary lane — cheap background subsystems (the hermes      |
+ * |              | `_AUX_TASKS` default model bucket; see {@link LlmProfileConfig.defaultAuxModel}). |
+ * | `background` | The lowest lane — fire-and-forget background work (titles, etc.). |
+ *
+ * Advisory metadata only: it does NOT alter the provider/model resolution
+ * chain in {@link LlmConfig} — it lets callers and diagnostics reason about
+ * which lane a profile belongs to without re-deriving it from the model id.
+ *
+ * @task T11748
+ * @epic T11745
+ */
+export type LlmProfileTier = 'prime' | 'aux' | 'background';
+
 /**
  * A named, reusable LLM profile.
  *
@@ -503,6 +526,67 @@ export interface LlmProfileConfig {
   credentialLabel?: string;
   /** Optional tuning parameters (max tokens, temperature). */
   params?: LlmProfileTuning;
+  /**
+   * Optional capability lane this profile occupies (see {@link LlmProfileTier}).
+   *
+   * Advisory metadata only — does NOT participate in provider/model resolution.
+   * Lets callers/diagnostics reason about a profile's lane (prime/aux/background)
+   * without re-deriving it from the model id. The hermes tiering model.
+   *
+   * @task T11748
+   */
+  tier?: LlmProfileTier;
+  /**
+   * Optional default auxiliary model for this profile — the hermes
+   * `auxiliary.defaultModel` analog (E9 · T11748).
+   *
+   * When this profile is a `prime`/global-base binding, `defaultAuxModel` names
+   * the cheaper model an aux-tier subsystem should use instead of {@link model}
+   * when it has no more-specific binding. Advisory metadata; consumers that want
+   * an aux-tier model read this rather than re-selecting a profile.
+   *
+   * @task T11748
+   */
+  defaultAuxModel?: string;
+}
+
+/**
+ * A per-system LLM binding — the granular override half of the hermes
+ * "global-base + granular-override" model (E9 · T11745 · T11748).
+ *
+ * A {@link LlmConfig.systems} entry pins the provider/model (or a named
+ * {@link LlmProfileConfig}) for ONE encoded system-of-use key (e.g.
+ * `'sentient'`, `'tool:web-search'`, `'skill:ct-cleo'`). It is consulted in the
+ * resolution chain AFTER an explicit role/argument override but BEFORE the
+ * global {@link LlmConfig.defaultProfile} — giving each subsystem a targeted
+ * override without touching the global base.
+ *
+ * Either `profile` (a key of {@link LlmConfig.profiles}) OR an inline
+ * `provider` + `model` tuple supplies the binding; `profile` wins when both are
+ * present. An entry that supplies neither a resolvable `profile` nor a complete
+ * `provider`+`model` tuple is structurally incomplete and is skipped (resolution
+ * falls through to the next tier) — never an error.
+ *
+ * @task T11748
+ * @epic T11745
+ */
+export interface SystemBinding {
+  /**
+   * Optional reference to a named profile in {@link LlmConfig.profiles}. When
+   * set and resolvable, the named profile's provider/model/credentialLabel win
+   * over this entry's inline `provider`/`model`.
+   */
+  profile?: string;
+  /** Inline LLM provider transport for this system (used when `profile` absent). */
+  provider?: LlmProviderTransport;
+  /** Inline full model identifier for this system (used when `profile` absent). */
+  model?: string;
+  /**
+   * Optional credential label pinning this system to a specific credential pool
+   * entry. When omitted, the standard priority-based credential resolution
+   * applies (or the resolved profile's `credentialLabel`).
+   */
+  credentialLabel?: string;
 }
 
 /**
@@ -554,11 +638,32 @@ export interface LlmConfig {
    * role that does NOT pin its own provider/model/profile. This is the
    * user-selectable default binding for background roles — it is NEVER a
    * hardcoded provider in code; the owner re-selects it with
-   * `cleo llm bind --default <profileName>`.
+   * `cleo config set llm.defaultProfile <profileName>`.
    *
    * @task T11617
+   * @task T11723
    */
   defaultProfile?: string;
+  /**
+   * Per-system-of-use LLM overrides — the granular-override half of the hermes
+   * "global-base + granular-override" model (E9 · T11745 · T11748).
+   *
+   * Keyed by an encoded system-of-use key: a flat role-mapped label
+   * (`'sentient'`, `'memory'`, …) or an open-axis key
+   * (`'tool:<name>'` / `'skill:<name>'` / `'cantbook:<node>'` /
+   * `'spawn-unit:<id>'`). Each value is a {@link SystemBinding}.
+   *
+   * Resolution priority for a system-of-use call:
+   *   explicit-arg (role override) → `systems[key]` → `defaultProfile` →
+   *   implicit fallback.
+   *
+   * `systems[key]` is consulted AFTER any explicit role/argument override but
+   * BEFORE the global {@link defaultProfile}, so a subsystem can be pointed at a
+   * targeted model without disturbing the global base.
+   *
+   * @task T11748
+   */
+  systems?: Record<string, SystemBinding>;
 }
 
 /** SignalDock transport mode. */

package/src/data-accessor.ts

@@ -468,9 +468,30 @@ export interface DataAccessor {
 
   // ---- Fine-grained session operations ----
 
-  /** Get the currently active session (status='active', most recent). */
+  /**
+   * Get the currently active session (status='active', most recent).
+   *
+   * SCAN-meaning: answers "is there any active session?" — NOT "who am I".
+   * Identity-meaning callers MUST use {@link DataAccessor.resolveCurrentSession}
+   * (T11640), which resolves the caller's OWN session via the
+   * connection-handle → `CLEO_SESSION_ID` → most-recent-active precedence.
+   */
   getActiveSession(): Promise<Session | null>;
 
+  /**
+   * Resolve the CALLER's current session (T11640 · Epic T11638).
+   *
+   * Identity-meaning resolution for accessor-based consumers, mirroring the
+   * standalone `resolveCurrentSession` in `@cleocode/core`. Precedence:
+   *   1. daemon connection handle (the connection bound at accept-time),
+   *   2. env-named session (`CLEO_SESSION_ID`),
+   *   3. most-recent-active row (legacy single-process fallback).
+   *
+   * Use this — NOT {@link DataAccessor.getActiveSession} — anywhere the meaning
+   * is "the session of whoever issued THIS request".
+   */
+  resolveCurrentSession(): Promise<Session | null>;
+
   /** Upsert a single session (targeted write). */
   upsertSingleSession(session: Session): Promise<void>;
 

package/src/dispatch/__tests__/tasks-gateway-crud-ops.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Registry regression tests for the E1-GATEWAY-CRUD epic (T11556).
+ *
+ *  - T11784: `tasks.update` OperationDef.params enumerates EVERY mutable field
+ *    declared in `TASKS_UPDATE_INPUT_SCHEMA`, and carries the inline
+ *    input/output schemas — so dispatch introspection (`--describe`, the SDK
+ *    `describeOperation`) no longer hides the real update surface behind a
+ *    `taskId`-only param list.
+ *  - T11786: the three bulk task mutate ops (`reorder-rank`, `bulk-move`,
+ *    `assignee`) are registered as `mutate` ops with the expected required
+ *    params and inline output schemas.
+ *  - T11785: the first streaming task op (`tasks.subscribe`) is registered as a
+ *    `query` op flagged `streaming: true`.
+ *
+ * @task T11784
+ * @task T11785
+ * @task T11786
+ * @epic T11556
+ */
+
+import { describe, expect, it } from 'vitest';
+import { TASKS_UPDATE_INPUT_SCHEMA } from '../../operations/tasks.js';
+import { OPERATIONS } from '../operations-registry.js';
+
+function findOp(gateway: 'query' | 'mutate', operation: string) {
+  return OPERATIONS.find(
+    (o) => o.domain === 'tasks' && o.gateway === gateway && o.operation === operation,
+  );
+}
+
+describe('T11784 — tasks.update OperationDef params parity', () => {
+  const update = findOp('mutate', 'update');
+
+  it('registers tasks.update as a mutate op', () => {
+    expect(update).toBeDefined();
+  });
+
+  it('enumerates every mutable field from TASKS_UPDATE_INPUT_SCHEMA', () => {
+    const schemaFields = Object.keys(
+      (TASKS_UPDATE_INPUT_SCHEMA.properties ?? {}) as Record<string, unknown>,
+    );
+    const paramNames = new Set((update?.params ?? []).map((p) => p.name));
+    // Every schema property must be a declared param (no silent-dropped fields).
+    for (const field of schemaFields) {
+      expect(paramNames.has(field), `tasks.update param "${field}" missing from OperationDef`).toBe(
+        true,
+      );
+    }
+    // taskId is the only required param.
+    expect(update?.requiredParams).toEqual(['taskId']);
+    expect((update?.params ?? []).filter((p) => p.required).map((p) => p.name)).toEqual(['taskId']);
+  });
+
+  it('carries the inline input + output schemas', () => {
+    expect(update?.inputSchema?.operation).toBe('tasks.update');
+    expect(update?.outputSchema?.operation).toBe('tasks.update');
+    // The output contract points at the bare-string updated-id pointer.
+    expect(update?.outputSchema?.fieldPointers).toContain('/data/updated/0');
+  });
+});
+
+describe('T11786 — bulk task mutate ops', () => {
+  it('registers tasks.reorder-rank with orderedIds required + output schema', () => {
+    const op = findOp('mutate', 'reorder-rank');
+    expect(op).toBeDefined();
+    expect(op?.requiredParams).toEqual(['orderedIds']);
+    expect(op?.outputSchema?.operation).toBe('tasks.reorder-rank');
+    expect(op?.outputSchema?.fieldPointers).toContain('/data/ranked/0');
+  });
+
+  it('registers tasks.bulk-move with taskIds required + output schema', () => {
+    const op = findOp('mutate', 'bulk-move');
+    expect(op).toBeDefined();
+    expect(op?.requiredParams).toEqual(['taskIds']);
+    expect(op?.outputSchema?.operation).toBe('tasks.bulk-move');
+    expect(op?.outputSchema?.fieldPointers).toContain('/data/moved/0');
+  });
+
+  it('registers tasks.assignee with taskId required + output schema', () => {
+    const op = findOp('mutate', 'assignee');
+    expect(op).toBeDefined();
+    expect(op?.requiredParams).toEqual(['taskId']);
+    expect(op?.outputSchema?.operation).toBe('tasks.assignee');
+    expect(op?.outputSchema?.fieldPointers).toContain('/data/assignee');
+  });
+});
+
+describe('T11785 — streaming task op', () => {
+  it('registers tasks.subscribe as a query op flagged streaming', () => {
+    const op = findOp('query', 'subscribe');
+    expect(op).toBeDefined();
+    expect(op?.streaming).toBe(true);
+    // No required params — subscribe is open by default (optional root/ticks scope).
+    expect(op?.requiredParams).toEqual([]);
+    const paramNames = (op?.params ?? []).map((p) => p.name);
+    expect(paramNames).toContain('root');
+    expect(paramNames).toContain('ticks');
+  });
+});

package/src/dispatch/identity.ts

@@ -99,6 +99,31 @@ export const CANONICAL_DOMAINS = [
   // T11373: 'cleo attention add|show|list' (alias 'jot') — Tier-2 scope-keyed
   // working-memory buffer (Epic T11288 · Saga T11283).
   'attention',
+  // T11889 (T11889-D): 'cleo selfimprove run' — the self-dogfooding loop verb.
+  // Boots ONE sandbox → replays a canned scenario → diffs vs golden → on a
+  // regression emits ONE leased `selfimprove_dhq` row + ONE DRAFT PR. Default
+  // OFF (requires --execute); the engine lives in CORE (P5 self-improvement spec).
+  'selfimprove',
+  // T11939 (epic T11765 · M2): 'cleo service auth-url|exchange|refresh|self-heal'
+  // — the universal service-vault OAuth flow. auth-url builds a PKCE auth URL;
+  // exchange persists encrypted tokens; refresh/self-heal renew them honoring the
+  // per-provider RefreshConfig. The flow lives in CORE (store/service-oauth.ts),
+  // driven by the declarative SERVICE_PROVIDERS registry (contracts).
+  'service',
+  // T11700 (epic T11666 · M3 · North-Star §2): the 5-entity provider experience —
+  // the addressable Provider / Alias / Account / Model / Profile surface.
+  //   'account'  — 'cleo account add|list|remove' (the credential pool; add is
+  //                secret-bearing/cli-only, MCP-default-denied).
+  //   'provider' — 'cleo provider list|show|connect' (the declarative providers
+  //                table #1039 + alias resolution; connect is secret-bearing).
+  //   'model'    — 'cleo model query|show' (the models_catalog table #1037; QUERY-ONLY).
+  //   'profile'  — 'cleo profile create|list|pin|use' (the named account+model
+  //                binding persisted into llm.profiles[name], the resolver SSoT).
+  // Each dispatches to the CORE entity-ops layer (llm/entity-ops.ts).
+  'account',
+  'provider',
+  'model',
+  'profile',
 ] as const;
 
 /**

package/src/dispatch/operation-def.ts

@@ -95,6 +95,27 @@ export interface OperationDef {
    */
   mcpExposed?: boolean;
 
+  /**
+   * Whether this operation is a **streaming** operation served over the gateway
+   * HTTP/SSE transport as `GET /v1/<domain>/<operation>` (T11921).
+   *
+   * **Default-deny**: absent / `false` means the operation is unary only — it is
+   * dispatched via the POST path and returns a single LAFS envelope. When
+   * `streaming: true`, the `/v1` HTTP listener routes a `GET` to the same
+   * `(domain, operation)` pair through {@link createSseStream}, emitting a
+   * sequence of `GatewayStreamEvent` frames (`data` … terminated by `done` or
+   * `error`) over a `text/event-stream` body. This is the realtime transport the
+   * Studio Kanban (T11929) and Pi-TUI (T11936) consume.
+   *
+   * A streaming op is still a normal registry entry (it has a `gateway`, a
+   * `domain`, an `operation`, a `tier`), so it co-exists with the unary POST
+   * routes and is discoverable by every existing registry helper — only the wire
+   * framing (a long-lived SSE body vs a single JSON response) differs.
+   *
+   * @task T11921 — gateway SSE streaming on `/v1`
+   */
+  streaming?: boolean;
+
   /**
    * Schema-first INPUT contract for this operation (DHQ-033 / T11692).
    *