@cleocode/contracts 2026.6.13 → 2026.6.15

package/src/__tests__/operation-def.test.ts

@@ -68,6 +68,8 @@ type _OperationDefShape = {
   requiredParams: string[];
   params?: ParamDef[];
   mcpExposed?: boolean;
+  // T11921 — opt-in streaming marker for the gateway HTTP/SSE transport.
+  streaming?: boolean;
   // T11692 (DHQ-033 / DHQ-057) — optional schema-first input/output contracts.
   inputSchema?: OperationInputContract<unknown>;
   outputSchema?: OperationOutputContract;
@@ -103,7 +105,10 @@ describe('dispatch/operation-def contracts', () => {
     // T9954 — snapshot the current count so accidental additions/removals
     // trip this test and force an explicit human review.
     // T11889-D — +1 for the new 'selfimprove' domain (self-dogfooding loop verb).
-    expect(CANONICAL_DOMAINS.length).toBe(24);
+    // T11939 — +1 for the new 'service' domain (universal service-vault OAuth flow).
+    // T11700 — +4 for the 5-entity provider experience: 'account', 'provider',
+    //          'model', 'profile' (North-Star §2 addressable provider surface).
+    expect(CANONICAL_DOMAINS.length).toBe(29);
   });
 
   it('CANONICAL_DOMAINS contains the four sentinel newly-promoted domains', () => {

package/src/__tests__/provider-def.test.ts

@@ -0,0 +1,93 @@
+/**
+ * T11702 — `ProviderDef` declarative contract shape.
+ *
+ * Type-level + value-level assertions that the contract is a closed, discriminated,
+ * serializable shape (the endpoint union is keyed on the `transport` literal, no
+ * `any`/`unknown` shortcut). No DB, no network.
+ *
+ * @task T11702
+ * @epic T11667
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  PROVIDER_TRANSPORTS,
+  type ProviderDef,
+  type ProviderEndpoint,
+  REQUEST_QUIRK_KINDS,
+} from '../llm/provider-def.js';
+
+describe('ProviderDef contract (T11702)', () => {
+  it('exposes the closed transport discriminant set', () => {
+    expect([...PROVIDER_TRANSPORTS]).toEqual([
+      'openai-completions',
+      'openai-responses',
+      'anthropic-messages',
+      'aisdk',
+    ]);
+  });
+
+  it('exposes the closed request-quirk-kind set', () => {
+    expect(REQUEST_QUIRK_KINDS).toContain('grok-conv-id');
+    expect(REQUEST_QUIRK_KINDS).toContain('gemini-thinking-config');
+    expect(REQUEST_QUIRK_KINDS).toContain('moonshot-schema-sanitize');
+  });
+
+  it('accepts a fully-populated declarative provider def with an OAuth flow + alt endpoint', () => {
+    const def: ProviderDef = {
+      id: 'openai',
+      displayName: 'OpenAI Codex (ChatGPT)',
+      aliases: ['codex', 'chatgpt', 'openai-codex'],
+      authMethods: ['api_key', 'oauth'],
+      endpoint: { transport: 'openai-completions', baseUrl: 'https://api.openai.com/v1' },
+      altEndpoints: [{ transport: 'openai-responses', baseUrl: 'https://api.openai.com/v1' }],
+      modelsDevId: 'openai',
+      oauth: {
+        mode: 'pkce',
+        clientId: 'app_test',
+        tokenEndpoint: 'https://auth.openai.com/oauth/token',
+        authorizationEndpoint: 'https://auth.openai.com/oauth/authorize',
+      },
+      requestQuirks: [{ kind: 'openrouter-pareto' }],
+    };
+    // Round-trips through JSON — the shape is serializable (no closures).
+    const roundTripped = JSON.parse(JSON.stringify(def)) as ProviderDef;
+    expect(roundTripped.id).toBe('openai');
+    expect(roundTripped.endpoint.transport).toBe('openai-completions');
+    expect(roundTripped.altEndpoints?.[0]?.transport).toBe('openai-responses');
+    expect(roundTripped.oauth?.mode).toBe('pkce');
+  });
+
+  it('narrows the endpoint discriminated union on the transport literal', () => {
+    const endpoints: ProviderEndpoint[] = [
+      { transport: 'anthropic-messages', baseUrl: 'https://api.anthropic.com' },
+      { transport: 'aisdk', baseUrl: 'https://example.com', aiSdkProvider: 'google' },
+    ];
+    for (const ep of endpoints) {
+      if (ep.transport === 'aisdk') {
+        // Only the aisdk variant carries aiSdkProvider — narrowing proves the union.
+        expect(ep.aiSdkProvider).toBe('google');
+      } else {
+        expect(ep.baseUrl.startsWith('https://')).toBe(true);
+      }
+    }
+  });
+
+  it('accepts a minimal def (no optional fields)', () => {
+    const def: ProviderDef = {
+      id: 'bedrock',
+      displayName: 'AWS Bedrock',
+      aliases: ['aws-bedrock'],
+      authMethods: ['aws_sdk'],
+      endpoint: {
+        transport: 'aisdk',
+        baseUrl: 'https://bedrock.example',
+        aiSdkProvider: 'bedrock',
+      },
+      modelsDevId: 'bedrock',
+    };
+    expect(def.oauth).toBeUndefined();
+    expect(def.requestQuirks).toBeUndefined();
+    expect(def.altEndpoints).toBeUndefined();
+  });
+});

package/src/__tests__/service-provider.test.ts

@@ -0,0 +1,129 @@
+/**
+ * T11937 seed + T11938 BREADTH — service-provider registry contract.
+ *
+ * Asserts the declarative `SERVICE_PROVIDERS` registry: the two pattern seeds
+ * (github + google) keep their precise shape (T11937), and the full ~40-service
+ * census (T11938) is well-formed — every entry self-consistent on its key, every
+ * provider carrying a NON-EMPTY `hostRules` array, and every OAuth (non-`api-key`)
+ * provider carrying either a `refresh` config or an explicit re-auth shape. The
+ * registry is DATA (no runtime helper) — this test is the only consumer that
+ * exercises its shape.
+ *
+ * @task T11937
+ * @task T11938
+ * @epic T11765
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  REFRESH_KINDS,
+  SERVICE_AUTH_KINDS,
+  SERVICE_PROVIDERS,
+  type ServiceProviderDef,
+} from '../vault/service-provider.js';
+
+describe('SERVICE_PROVIDERS registry (T11937 seed + T11938 breadth)', () => {
+  it('contains the full ~40-service census (≥ 38 providers, T11938 AC1)', () => {
+    // 2 seeds (github, google) + ~37 breadth entries = ~40 declarative providers.
+    expect(Object.keys(SERVICE_PROVIDERS).length).toBeGreaterThanOrEqual(38);
+  });
+
+  it('includes a representative spread across provider families', () => {
+    const keys = Object.keys(SERVICE_PROVIDERS);
+    // Seeds + Google family + Atlassian + api-key + JWT/client-credentials.
+    for (const expected of [
+      'github',
+      'google',
+      'gmail',
+      'notion',
+      'dropbox',
+      'jira',
+      'confluence',
+      'supabase',
+      'todoist',
+      'resend',
+      'cloudflare',
+      'github-app',
+      'mongodb-atlas',
+      'vertex-ai',
+    ]) {
+      expect(keys).toContain(expected);
+    }
+  });
+
+  it('each entry is well-formed and self-consistent on its key', () => {
+    for (const [key, def] of Object.entries(SERVICE_PROVIDERS) as Array<
+      [string, ServiceProviderDef]
+    >) {
+      expect(def.provider).toBe(key);
+      expect(def.displayName.length).toBeGreaterThan(0);
+      expect(def.description.length).toBeGreaterThan(0);
+      expect(SERVICE_AUTH_KINDS).toContain(def.authKind);
+    }
+  });
+
+  it('every provider declares a NON-EMPTY hostRules array (T11938 AC4)', () => {
+    for (const [key, def] of Object.entries(SERVICE_PROVIDERS) as Array<
+      [string, ServiceProviderDef]
+    >) {
+      expect(Array.isArray(def.hostRules), `${key} must declare hostRules`).toBe(true);
+      expect(def.hostRules.length, `${key} hostRules must be non-empty`).toBeGreaterThan(0);
+      for (const rule of def.hostRules) {
+        expect(rule.host.length).toBeGreaterThan(0);
+        expect(['bearer', 'basic-x-access-token', 'header']).toContain(rule.strategy);
+      }
+    }
+  });
+
+  it('every OAuth (non api-key) provider declares a refresh config OR an oauth re-auth shape (T11938 AC4)', () => {
+    for (const [key, def] of Object.entries(SERVICE_PROVIDERS) as Array<
+      [string, ServiceProviderDef]
+    >) {
+      if (def.authKind === 'api-key') {
+        // api-key services have no token to refresh — refresh MUST be absent.
+        expect(def.refresh, `${key} (api-key) must not declare refresh`).toBeUndefined();
+        continue;
+      }
+      // An OAuth provider must be refreshable OR at least carry a full oauth
+      // block the flow can re-authorize against.
+      const hasRefresh = def.refresh !== undefined;
+      const hasOAuth = def.oauth !== undefined;
+      expect(hasRefresh || hasOAuth, `${key} must declare refresh or oauth`).toBe(true);
+      if (hasRefresh && def.refresh) {
+        expect(REFRESH_KINDS).toContain(def.refresh.kind);
+        expect(def.refresh.tokenUrl.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('declares the three special-case refresh-kind discriminants (T11938 AC3)', () => {
+    const kinds = new Set(
+      Object.values(SERVICE_PROVIDERS)
+        .map((d) => d.refresh?.kind)
+        .filter((k): k is NonNullable<typeof k> => k !== undefined),
+    );
+    expect(kinds.has('github-app')).toBe(true);
+    expect(kinds.has('client-credentials')).toBe(true);
+    expect(kinds.has('refresh-token')).toBe(true);
+  });
+
+  it('github is a classic OAuth2 web flow with complete endpoints (T11937)', () => {
+    const gh = SERVICE_PROVIDERS['github'];
+    expect(gh).toBeDefined();
+    expect(gh?.authKind).toBe('oauth2');
+    expect(gh?.oauth?.authorizationEndpoint).toContain('github.com');
+    expect(gh?.oauth?.tokenEndpoint).toContain('github.com');
+    expect(gh?.oauth?.clientId.length).toBeGreaterThan(0);
+    expect(gh?.defaultScopes).toContain('repo');
+  });
+
+  it('google is an installed-app OAuth2 + PKCE flow that requests offline access (T11937)', () => {
+    const g = SERVICE_PROVIDERS['google'];
+    expect(g).toBeDefined();
+    expect(g?.authKind).toBe('oauth2-pkce');
+    expect(g?.oauth?.authorizationEndpoint).toContain('accounts.google.com');
+    expect(g?.oauth?.tokenEndpoint).toContain('oauth2.googleapis.com');
+    // Google needs access_type=offline + prompt=consent to issue a refresh token.
+    expect(g?.oauth?.extraAuthParams?.['access_type']).toBe('offline');
+  });
+});

package/src/boundary.ts

@@ -891,6 +891,75 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
   },
 ] as const;
 
+// ============================================================
+// Channel Boundary Registry (T11952 · epic T11854 · saga T10419)
+// ============================================================
+
+/**
+ * Trust posture for an inbound channel sender.
+ *
+ * - `verified` — sender messages bypass the HITL approval gate and dispatch
+ *   directly to the agent.
+ * - `unverified` — sender messages route through the resumeToken approval gate
+ *   before dispatch (T11854 AC5).
+ */
+export type ChannelTrustPosture = 'verified' | 'unverified';
+
+/**
+ * One row in {@link CHANNEL_BOUNDARY_REGISTRY}. Declares a messaging channel's
+ * delivery boundary: which transport it rides, whether it crosses the network,
+ * whether a platform credential is required, and the default trust posture for
+ * inbound senders.
+ *
+ * This is the channel-layer companion to the ADR-078 module {@link BoundaryEntry}.
+ * Where {@link BoundaryEntry} governs Rust/TS package layering (one row per
+ * crate/package, validated against the filesystem), a {@link ChannelBoundaryEntry}
+ * governs the conversation-surface boundary (one row per channel adapter) and is
+ * NOT filesystem-validated — channels are runtime concepts, not on-disk modules.
+ *
+ * @see T11854 AC4 — every channel registers a boundary entry in boundary.ts.
+ * @see ConduitMessage — the wire shape channels exchange.
+ */
+export interface ChannelBoundaryEntry {
+  /** Stable, kebab-case channel id (e.g. `'local-tui'`, `'telegram'`). */
+  channel: string;
+  /** Underlying conduit transport the adapter rides (e.g. `'local'`, `'http'`). */
+  transport: string;
+  /** Whether the channel originates outbound network traffic. */
+  networkEgress: 'none' | 'required';
+  /** Whether the channel requires a platform credential to operate. */
+  credentialRequired: boolean;
+  /** Default trust posture applied to inbound senders lacking explicit verification. */
+  defaultTrust: ChannelTrustPosture;
+  /** 1-2 sentence rationale for the channel's boundary posture. */
+  rationale: string;
+}
+
+/**
+ * Canonical registry of messaging-channel boundaries.
+ *
+ * The Local-TUI adapter (T11952) is the first reference channel: it rides the
+ * in-process conduit `LocalTransport`, never touches the network, needs no
+ * platform credential, and treats the single local operator as a verified
+ * sender. Platform adapters (Telegram/Discord/Slack/WhatsApp — T11855) append
+ * their own entries as they land.
+ *
+ * Entries are kept alphabetical by `channel` for diff-friendliness.
+ *
+ * @see T11854 AC4
+ */
+export const CHANNEL_BOUNDARY_REGISTRY: readonly ChannelBoundaryEntry[] = [
+  {
+    channel: 'local-tui',
+    transport: 'local',
+    networkEgress: 'none',
+    credentialRequired: false,
+    defaultTrust: 'verified',
+    rationale:
+      'In-process stdin/stdout terminal channel riding the conduit LocalTransport (conduit.db). Fully offline, daemon-OFF, no network, no platform credential; the single local operator is a verified sender.',
+  },
+] as const;
+
 // ============================================================
 // TOOLS-vs-SKILLS boundary (E3 · T11409 · SG-PACKAGE-ARCH)
 // ============================================================

package/src/branch-lock.ts

@@ -102,6 +102,10 @@ export interface WorktreeCleanupResult {
   removed: number;
   /** Paths that were removed. */
   removedPaths: string[];
+  /** Number of worktrees quarantined (dirty/unpushed — preserved, not deleted). */
+  quarantined: number;
+  /** Paths that were quarantined. */
+  quarantinedPaths: string[];
   /** Paths that failed to remove (with reasons). */
   errors: Array<{ path: string; reason: string }>;
 }

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';