@cleocode/contracts 2026.6.12 → 2026.6.14

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;
@@ -102,7 +104,11 @@ describe('dispatch/operation-def contracts', () => {
     expect(CANONICAL_DOMAINS.length).toBeGreaterThan(0);
     // T9954 — snapshot the current count so accidental additions/removals
     // trip this test and force an explicit human review.
-    expect(CANONICAL_DOMAINS.length).toBe(23);
+    // T11889-D — +1 for the new 'selfimprove' domain (self-dogfooding loop verb).
+    // 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__/sealed-credential.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Type + purity tests for the E10 sealed credential handle (T11752).
+ *
+ * Pins the {@link SealedCredential} / {@link DecryptedToken} contract so that:
+ *   - `SealedCredential` is exactly `{ provider, account, fetch }` with
+ *     `fetch: () => Promise<DecryptedToken>` (AC1).
+ *   - `ResolvedLLM` carries a sealed-credential-typed field (AC2).
+ *   - `DecryptedToken` is a *branded* string — a plain `string` is NOT
+ *     assignable to it, so the secret cannot be silently fabricated and a
+ *     `DecryptedToken` cannot leak into an arbitrary `string` sink without an
+ *     explicit `.value` read (the "never serialized" invariant, AC2).
+ *   - The module is types-only (no runtime export), satisfying contracts
+ *     purity (Gate 10 · AC3).
+ *
+ * @task T11752
+ * @epic T11746
+ */
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ProviderId } from '../llm/provider-id.js';
+import type { DecryptedToken, SealedCredential } from '../llm/sealed-credential.js';
+import type { ResolvedLLM } from '../operations/llm.js';
+
+describe('SealedCredential shape (AC1)', () => {
+  it('is exactly { provider, account, tokenPreview, fetch } — pins the field set', () => {
+    expectTypeOf<keyof SealedCredential>().toEqualTypeOf<
+      'provider' | 'account' | 'tokenPreview' | 'fetch'
+    >();
+  });
+
+  it('provider is a ProviderId', () => {
+    expectTypeOf<SealedCredential['provider']>().toEqualTypeOf<ProviderId>();
+  });
+
+  it('account is a plain (loggable) string', () => {
+    expectTypeOf<SealedCredential['account']>().toEqualTypeOf<string>();
+  });
+
+  it('tokenPreview is a plain (loggable, non-secret) string (T11754)', () => {
+    expectTypeOf<SealedCredential['tokenPreview']>().toEqualTypeOf<string>();
+  });
+
+  it('fetch resolves to a DecryptedToken (never a bare string)', () => {
+    expectTypeOf<SealedCredential['fetch']>().toEqualTypeOf<() => Promise<DecryptedToken>>();
+    expectTypeOf<ReturnType<SealedCredential['fetch']>>().resolves.toEqualTypeOf<DecryptedToken>();
+  });
+
+  it('all fields are readonly (a handle cannot be mutated in place)', () => {
+    // Removing `readonly` from any field would make this fail to compile.
+    expectTypeOf<SealedCredential>().toEqualTypeOf<{
+      readonly provider: ProviderId;
+      readonly account: string;
+      readonly tokenPreview: string;
+      readonly fetch: () => Promise<DecryptedToken>;
+    }>();
+  });
+});
+
+describe('DecryptedToken branding (AC2 — never serialized / never fabricated)', () => {
+  it('is NOT assignable from a plain string (nominal brand)', () => {
+    // A plain string lacks the phantom `__decryptedToken` brand, so it cannot
+    // be passed where a DecryptedToken is required.
+    expectTypeOf<string>().not.toMatchTypeOf<DecryptedToken>();
+  });
+
+  it('is NOT a plain string sink (must read .value explicitly to serialize)', () => {
+    expectTypeOf<DecryptedToken>().not.toEqualTypeOf<string>();
+  });
+
+  it('exposes a readonly plaintext .value of type string', () => {
+    expectTypeOf<DecryptedToken['value']>().toEqualTypeOf<string>();
+  });
+
+  it('carries the phantom brand marker (compile-time only)', () => {
+    expectTypeOf<DecryptedToken['__decryptedToken']>().toEqualTypeOf<'DecryptedToken'>();
+  });
+});
+
+describe('ResolvedLLM.sealedCredential (AC2 · T11753)', () => {
+  it('is the required (non-optional) canonical credential surface', () => {
+    // T11753 promotes the field from optional to required: the resolver ALWAYS
+    // populates it (a handle when a credential resolved, `null` otherwise).
+    expectTypeOf<ResolvedLLM['sealedCredential']>().toEqualTypeOf<SealedCredential | null>();
+  });
+
+  it('the inline credential metadata carries NO plaintext apiKey (T11753)', () => {
+    // The secret-bearing `apiKey` field is structurally removed from the inline
+    // credential — the plaintext crosses ONLY through `sealedCredential.fetch()`.
+    type Cred = NonNullable<ResolvedLLM['credential']>;
+    expectTypeOf<Cred>().not.toHaveProperty('apiKey');
+  });
+});
+
+describe('contracts purity (AC3) — sealed-credential is types-only', () => {
+  it('the module exposes no runtime exports (no decrypt logic in contracts)', async () => {
+    const mod = await import('../llm/sealed-credential.js');
+    // A pure type module compiles to an empty ESM namespace at runtime.
+    expect(Object.keys(mod)).toHaveLength(0);
+  });
+});

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/__tests__/skill-executor-contract.test.ts

@@ -43,6 +43,9 @@ const fakeTools: GuardedToolSurface = {
   async executeShell(_input): Promise<ExecuteShellResult> {
     return { stdout: '', stderr: '', code: 0 };
   },
+  async executePty(_input) {
+    return { stdout: '', stderr: '', code: 0, mode: 'spawn', ptyFellBack: false };
+  },
   async runGit(_input): Promise<ExecuteShellResult> {
     return { stdout: '', stderr: '', code: 0 };
   },

package/src/acceptance-gate.ts

@@ -325,9 +325,8 @@ export type GateResultDetails =
  * Persisted to `lifecycle_gate_results` and summarised in
  * `task.verification.gateResults`.
  *
- * NOTE: Named `AcceptanceGateResult` (not `GateResult`) to avoid collision
- * with the existing {@link GateResult} from `./warp-chain.js` which describes
- * WarpChain LOOM-gate evaluation outcomes.
+ * NOTE: Named `AcceptanceGateResult` (not `GateResult`) for historical
+ * clarity — it describes acceptance-criterion gate outcomes specifically.
  */
 export interface AcceptanceGateResult {
   /** Zero-based index in the task's acceptance array. */

package/src/boundary.ts

@@ -266,25 +266,6 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     rationale:
       'napi binding shim for cant-core + cant-runtime. Loaded via packages/cant/src/native-loader.ts and packages/core/src/system/dependencies.ts. Internal-only — shipped via per-platform packages/cant-napi-* npm packages, not crates.io. cant-router bindings removed (E8 T11432).',
   },
-  {
-    module: 'cant-router',
-    intent: 'cpu-bound',
-    rustCore: 'crates/cant-router',
-    canonicalHome: 'cleocode',
-    perfBudget: {
-      latency_p50_ms: 5,
-      latency_p99_ms: 50,
-    },
-    safetyBudget: {
-      panic_unwind: 'forbidden',
-      root_escape: 'forbidden',
-    },
-    amendments: [],
-    rationale:
-      'Cant Router (984 LOC) — RETIRED from cant-napi dep-set (E8 T11432: zero live TS consumers). ' +
-      'Preserved in the workspace for reference; not linked into the published napi binary. ' +
-      'publish=false. Relocation/deletion tracked in T11432.',
-  },
   {
     module: 'cant-runtime',
     intent: 'cpu-bound',
@@ -368,7 +349,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'Internal Rust test harness (241 LOC) over lafs-core/cleo-conduit-core/cant-core/cant-router/signaldock-core. publish=false intentional — test code never ships.',
+      'Internal Rust test harness over lafs-core/cleo-conduit-core/cant-core. publish=false intentional — test code never ships.',
   },
   {
     module: 'lafs-core',
@@ -910,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)
 // ============================================================