@cleocode/contracts 2026.6.13 → 2026.6.14

package/src/index.ts

@@ -140,12 +140,14 @@ export type {
 export type {
   BoundaryEntry,
   CanonicalHome,
+  ChannelBoundaryEntry,
+  ChannelTrustPosture,
   PerfBudget,
   SafetyBudget,
   ThroughputThreshold,
   WorkloadIntent,
 } from './boundary.js';
-export { BOUNDARY_REGISTRY } from './boundary.js';
+export { BOUNDARY_REGISTRY, CHANNEL_BOUNDARY_REGISTRY } from './boundary.js';
 // === Brain/Memory Types ===
 export type {
   BackupRecoverBrainResult,
@@ -213,6 +215,11 @@ export type {
 } from './code-symbol.js';
 // === Conduit Protocol (agent-to-agent communication) ===
 export type {
+  ChannelAdapter,
+  ChannelConfig,
+  ChannelHealth,
+  ChannelHealthStatus,
+  ChannelSession,
   Conduit,
   ConduitConfig,
   ConduitMessage,
@@ -223,6 +230,8 @@ export type {
   ConduitTopicPublishOptions,
   ConduitTopicSubscribeOptions,
   ConduitUnsubscribe,
+  InboundMsg,
+  OutboundReply,
 } from './conduit.js';
 // === Config Manifest (T9876 / Saga T9855) ===
 export type {
@@ -759,6 +768,10 @@ export type {
   LeaseRenewRequest,
   LeaseRevokedResponse,
   LeaseScope,
+  QueueAdmitDisposition,
+  QueueAdmitRequest,
+  QueueAdmitResultResponse,
+  QueuePriorityClass,
   RateCheckRequest,
   RateResultResponse,
   ToolGrantedResponse,
@@ -786,11 +799,38 @@ export {
   LeaseRenewRequestSchema,
   LeaseRevokedResponseSchema,
   LeaseScopeSchema,
+  QueueAdmitDispositionSchema,
+  QueueAdmitRequestSchema,
+  QueueAdmitResultResponseSchema,
+  QueuePriorityClassSchema,
   RateCheckRequestSchema,
   RateResultResponseSchema,
   ToolGrantedResponseSchema,
   ToolGrantRequestSchema,
 } from './lease-ipc/index.js';
+export type {
+  CatalogAuthType,
+  CatalogModelEntry,
+  CatalogModelStatus,
+  CatalogProvider,
+  CuratedCatalog,
+  ModelsCatalogRowInsert,
+  ModelsCatalogRowSelect,
+} from './llm/catalog-schema.js';
+// === E8 Curated Models Catalog (T11731 · offline-first catalog SSoT) ===
+export {
+  CATALOG_AUTH_TYPES,
+  CATALOG_MODEL_STATUSES,
+  catalogCostSchema,
+  catalogLimitSchema,
+  catalogModalitiesSchema,
+  catalogModelEntrySchema,
+  catalogModelProviderSchema,
+  catalogProviderSchema,
+  curatedCatalogSchema,
+  modelsCatalogRowInsertSchema,
+  modelsCatalogRowSelectSchema,
+} from './llm/catalog-schema.js';
 // === LLM Error Taxonomy (T9270 — Hermes FailoverReason port) ===
 export type { ClassifiedError, FailoverReason } from './llm/failover-reason.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Session + Executor interfaces ===
@@ -826,6 +866,14 @@ export type {
 } from './llm/normalized-response.js';
 // === OAuth types — SSoT shared between core and cleo (T9302) ===
 export type { OAuthMode, OAuthTokens, PkceFlowConfig, ProviderOAuthConfig } from './llm/oauth.js';
+// === Onboarding login engine result envelope (T11724 · M3) ===
+export type {
+  OnboardingAuthMode,
+  OnboardingResult,
+  OnboardingStepName,
+  OnboardingStepResult,
+  OnboardingStepStatus,
+} from './llm/onboarding.js';
 // === Phase 4/5 Plugin LLM facade types (T9305 / T9313) ===
 export type { PluginLlmComplete, PluginLlmContext } from './llm/plugin-llm.js';
 export {
@@ -834,6 +882,23 @@ export {
   PluginModelGateError,
   PluginRateLimitedError,
 } from './llm/plugin-llm.js';
+export type {
+  AiSdkEndpoint,
+  AnthropicMessagesEndpoint,
+  OAuthFlowDef,
+  OpenAICompletionsEndpoint,
+  OpenAIResponsesEndpoint,
+  ProviderDef,
+  ProviderEndpoint,
+  ProviderTransport,
+  RequestQuirk,
+  RequestQuirkKind,
+} from './llm/provider-def.js';
+// === M3 Provider SSoT (T11702 · epic T11667) — declarative ProviderDef ===
+export {
+  PROVIDER_TRANSPORTS,
+  REQUEST_QUIRK_KINDS,
+} from './llm/provider-def.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Provider identity ===
 export type { ApiMode, BuiltinProviderId, ProviderId } from './llm/provider-id.js';
 // === Provider Profile + Plugin Contracts (T9262 — Phase 3 T-LLM-CRED) ===
@@ -1045,10 +1110,19 @@ export type {
   AdminBackupListParams,
   AdminBackupMutateParams,
   AdminCleanupParams,
+  AdminConfigGetParams,
+  AdminConfigGetResult,
+  AdminConfigListParams,
+  AdminConfigListResult,
   AdminConfigPresetsParams,
+  AdminConfigScope,
   AdminConfigSetParams,
   AdminConfigSetPresetParams,
   AdminConfigShowParams,
+  AdminConfigUnsetParams,
+  AdminConfigUnsetResult,
+  AdminConfigValidateParams,
+  AdminConfigValidateResult,
   AdminContextInjectParams,
   AdminContextParams,
   AdminContextPullParams,
@@ -1143,6 +1217,35 @@ export {
   taskTreeEntrySchema,
   taskTreeSchema,
 } from './operations/ensures-schema-registry.js';
+// 5-entity provider-experience op contracts (T11700 · epic T11666) — INPUT
+// contracts consumed by core's INPUT_CONTRACTS registry; OUTPUT contracts already
+// register into OUTPUT_CONTRACTS above.
+export {
+  accountAddInputContract,
+  accountAddOutputContract,
+  accountListInputContract,
+  accountListOutputContract,
+  accountRemoveInputContract,
+  accountRemoveOutputContract,
+  modelQueryInputContract,
+  modelQueryOutputContract,
+  modelShowInputContract,
+  modelShowOutputContract,
+  profileCreateInputContract,
+  profileCreateOutputContract,
+  profileListInputContract,
+  profileListOutputContract,
+  profilePinInputContract,
+  profilePinOutputContract,
+  profileUseInputContract,
+  profileUseOutputContract,
+  providerConnectInputContract,
+  providerConnectOutputContract,
+  providerListInputContract,
+  providerListOutputContract,
+  providerShowInputContract,
+  providerShowOutputContract,
+} from './operations/entities.js';
 // === Operations Types (API wire format, namespaced to avoid collision with domain types) ===
 export * as ops from './operations/index.js';
 // === Operation Input Contracts (T9914 / Saga T9855 / E7) ===
@@ -1473,6 +1576,19 @@ export type {
   ProposeRunResult,
   SentientOps,
 } from './operations/sentient.js';
+// Service-vault CLI op contracts (T11941 · epic T11765 · M2-W4) — INPUT contracts
+// consumed by core's INPUT_CONTRACTS registry; OUTPUT contracts already register
+// into OUTPUT_CONTRACTS above.
+export {
+  serviceConnectInputContract,
+  serviceConnectOutputContract,
+  serviceListInputContract,
+  serviceListOutputContract,
+  serviceRevokeInputContract,
+  serviceRevokeOutputContract,
+  serviceStatusInputContract,
+  serviceStatusOutputContract,
+} from './operations/service.js';
 // Session operation param/result types — re-exported at top level for typed-dispatch consumers
 // (T975 Wave D · ADR-051 migration)
 export type {
@@ -2385,6 +2501,26 @@ export {
   validatorRejectionSchema,
   validatorVerdictSchema,
 } from './validator/index.js';
+// === Universal Service Vault — declarative service-provider registry (T11937 seed + T11938 breadth, epic T11765) ===
+export type {
+  CredentialHeaderRule,
+  HostAuthStrategy,
+  InjectionRule,
+  InjectionValueSource,
+  MetadataHeaderRule,
+  RefreshBodyFormat,
+  RefreshClientAuth,
+  RefreshConfig,
+  RefreshKind,
+  ServiceAuthKind,
+  ServiceHostRule,
+  ServiceProviderDef,
+} from './vault/service-provider.js';
+export {
+  REFRESH_KINDS,
+  SERVICE_AUTH_KINDS,
+  SERVICE_PROVIDERS,
+} from './vault/service-provider.js';
 export type {
   TasksFrontierParamsInput,
   TasksRollupParamsInput,

package/src/lease-ipc/__tests__/freeze.test.ts

@@ -44,6 +44,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'lease_renew',
       'rate_check',
       'tool_grant',
+      'queue_admit',
+      'worker_heartbeat',
     ]);
   });
 
@@ -56,6 +58,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'tool_granted',
       'lease_revoked',
       'child_killed_unresponsive',
+      'queue_admit_result',
+      'heartbeat_ack',
       'error',
     ]);
   });
@@ -81,6 +85,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'lease_renew',
       'rate_check',
       'tool_grant',
+      'queue_admit',
+      'worker_heartbeat',
       'lease_granted',
       'lease_queued',
       'lease_denied',
@@ -88,6 +94,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'tool_granted',
       'lease_revoked',
       'child_killed_unresponsive',
+      'queue_admit_result',
+      'heartbeat_ack',
       'error',
     ]);
   });
@@ -162,6 +170,74 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
     expect(LeaseIpcEnvelopeSchema.safeParse(wire).success).toBe(true);
   });
 
+  it('parses the exact JSON a Rust queue_admit request envelope serializes (T11630)', () => {
+    const wire = {
+      protocol_version: '1.1.0',
+      id: 'qa-1',
+      direction: 'request',
+      request: {
+        kind: 'queue_admit',
+        provider: 'anthropic',
+        priority_class: 'lead',
+        est_tokens: 1024,
+        child_id: 'worker-1',
+      },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'request') {
+      expect(parsed.data.request.kind).toBe('queue_admit');
+    }
+  });
+
+  it('parses the exact JSON a Rust queue_admit_result response envelope serializes (T11630)', () => {
+    const wire = {
+      protocol_version: '1.1.0',
+      id: 'qa-1',
+      direction: 'response',
+      response: {
+        kind: 'queue_admit_result',
+        disposition: 'deferred',
+        retry_after_ms: 250,
+        tokens_remaining: 0,
+        queue_position: 2,
+      },
+    };
+    expect(LeaseIpcEnvelopeSchema.safeParse(wire).success).toBe(true);
+  });
+
+  it('parses the exact JSON a Rust worker_heartbeat request envelope serializes (T11628)', () => {
+    const wire = {
+      protocol_version: '1.1.0',
+      id: 'hb-1',
+      direction: 'request',
+      request: {
+        kind: 'worker_heartbeat',
+        child_id: 'worker-7',
+        in_flight_llm: true,
+      },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'request') {
+      expect(parsed.data.request.kind).toBe('worker_heartbeat');
+    }
+  });
+
+  it('parses the exact JSON a Rust heartbeat_ack response envelope serializes (T11628)', () => {
+    const wire = {
+      protocol_version: '1.1.0',
+      id: 'hb-1',
+      direction: 'response',
+      response: { kind: 'heartbeat_ack' },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'response') {
+      expect(parsed.data.response.kind).toBe('heartbeat_ack');
+    }
+  });
+
   it('rejects an unknown message kind (proves the union is closed)', () => {
     const wire = {
       protocol_version: '1.1.0',
@@ -212,6 +288,16 @@ function sampleRequestFor(kind: (typeof LEASE_IPC_REQUEST_KINDS)[number]): unkno
       return { kind, scope: 'global', lane: 'bulk', est_bytes: 4096 };
     case 'tool_grant':
       return { kind, tool: 'browser', holder_id: 'h' };
+    case 'queue_admit':
+      return {
+        kind,
+        provider: 'anthropic',
+        priority_class: 'lead',
+        est_tokens: 1024,
+        child_id: 'worker-1',
+      };
+    case 'worker_heartbeat':
+      return { kind, child_id: 'worker-1', in_flight_llm: true };
   }
 }
 
@@ -240,6 +326,16 @@ function sampleResponseFor(kind: (typeof LEASE_IPC_RESPONSE_KINDS)[number]): unk
       return { kind, scope: 'project', lane: 'tasks', holder_id: 'h', reason: 'ttl expired' };
     case 'child_killed_unresponsive':
       return { kind, child_id: 'w1', holder_id: 'h', scope: 'project', reason: 'unresponsive' };
+    case 'queue_admit_result':
+      return {
+        kind,
+        disposition: 'deferred',
+        retry_after_ms: 250,
+        tokens_remaining: 0,
+        queue_position: 2,
+      };
+    case 'heartbeat_ack':
+      return { kind };
     case 'error':
       return { kind, code: 'E_X', message: 'x' };
   }

package/src/lease-ipc/index.ts

@@ -14,6 +14,7 @@
 
 export type {
   ChildKilledUnresponsiveResponse,
+  HeartbeatAckResponse,
   LeaseAcquireRequest,
   LeaseDeniedResponse,
   LeaseErrorResponse,
@@ -29,14 +30,20 @@ export type {
   LeaseRenewRequest,
   LeaseRevokedResponse,
   LeaseScope,
+  QueueAdmitDisposition,
+  QueueAdmitRequest,
+  QueueAdmitResultResponse,
+  QueuePriorityClass,
   RateCheckRequest,
   RateResultResponse,
   ToolGrantedResponse,
   ToolGrantRequest,
+  WorkerHeartbeatRequest,
 } from './messages.js';
 
 export {
   ChildKilledUnresponsiveResponseSchema,
+  HeartbeatAckResponseSchema,
   LEASE_IPC_MESSAGE_KINDS,
   LEASE_IPC_REQUEST_KINDS,
   LEASE_IPC_RESPONSE_KINDS,
@@ -55,9 +62,14 @@ export {
   LeaseRenewRequestSchema,
   LeaseRevokedResponseSchema,
   LeaseScopeSchema,
+  QueueAdmitDispositionSchema,
+  QueueAdmitRequestSchema,
+  QueueAdmitResultResponseSchema,
+  QueuePriorityClassSchema,
   RateCheckRequestSchema,
   RateResultResponseSchema,
   ToolGrantedResponseSchema,
   ToolGrantRequestSchema,
+  WorkerHeartbeatRequestSchema,
 } from './messages.js';
 export { isFrozenLeaseIpcVersion, LEASE_IPC_PROTOCOL_VERSION } from './version.js';

package/src/lease-ipc/messages.ts

@@ -169,6 +169,66 @@ export const ToolGrantRequestSchema = z
 /** Tool-grant request payload (inferred from {@link ToolGrantRequestSchema}). */
 export type ToolGrantRequest = z.infer<typeof ToolGrantRequestSchema>;
 
+/**
+ * The priority class of a `queue_admit` request (T11630). Mirrors the Rust
+ * `QueuePriorityClass` enum and `cleo_supervisor::llm_queue::PriorityClass`.
+ *
+ * `lead > worker > background` — a lead/orchestrator agent is never starved by a
+ * background consolidation (AC1).
+ */
+export const QueuePriorityClassSchema = z.enum(['lead', 'worker', 'background']);
+
+/** A `queue_admit` priority class (inferred from {@link QueuePriorityClassSchema}). */
+export type QueuePriorityClass = z.infer<typeof QueuePriorityClassSchema>;
+
+/**
+ * Admit (or defer) an outbound LLM call through the supervisor's priority
+ * scheduler + per-provider rate governor (T11630 · AC1-AC4). Mirrors
+ * `QueueAdmitReq`. `[wired]`
+ */
+export const QueueAdmitRequestSchema = z
+  .object({
+    /** Tag discriminating this request variant. */
+    kind: z.literal('queue_admit'),
+    /** The LLM provider id the call targets (rate budget is per-provider). */
+    provider: z.string().min(1),
+    /** The caller's priority class (lead > worker > background). */
+    priority_class: QueuePriorityClassSchema,
+    /** The caller's estimate of the request's token cost (debited on admit). */
+    est_tokens: z.number().int().nonnegative(),
+    /** The child the call belongs to (in-flight tracking — the watchdog seam). */
+    child_id: z.string().min(1),
+  })
+  .strict();
+
+/** Queue-admit request payload (inferred from {@link QueueAdmitRequestSchema}). */
+export type QueueAdmitRequest = z.infer<typeof QueueAdmitRequestSchema>;
+
+/**
+ * A liveness heartbeat from a managed worker (T11628). Mirrors
+ * `WorkerHeartbeatReq`. `[wired]`
+ *
+ * The worker sends this periodically (well inside the watchdog's NORMAL
+ * deadline) so the supervisor knows it is alive. `in_flight_llm` is the worker's
+ * OWN view of whether it is currently waiting on an LLM call: when true the
+ * watchdog grants the EXTENDED deadline even if the call never went through the
+ * `queue_admit` seam, so a slow-but-healthy long call is never false-killed
+ * (AC2 · RISK-7).
+ */
+export const WorkerHeartbeatRequestSchema = z
+  .object({
+    /** Tag discriminating this request variant. */
+    kind: z.literal('worker_heartbeat'),
+    /** The logical id of the heartbeating child (matches the registry key). */
+    child_id: z.string().min(1),
+    /** The worker's own view of whether it is currently inside an LLM call. */
+    in_flight_llm: z.boolean(),
+  })
+  .strict();
+
+/** Worker-heartbeat request payload (inferred from {@link WorkerHeartbeatRequestSchema}). */
+export type WorkerHeartbeatRequest = z.infer<typeof WorkerHeartbeatRequestSchema>;
+
 /**
  * The discriminated union of all client → arbiter lease requests. The `kind`
  * field selects the variant, matching the serde `#[serde(tag = "kind")]`
@@ -180,6 +240,8 @@ export const LeaseIpcRequestSchema = z.discriminatedUnion('kind', [
   LeaseRenewRequestSchema,
   RateCheckRequestSchema,
   ToolGrantRequestSchema,
+  QueueAdmitRequestSchema,
+  WorkerHeartbeatRequestSchema,
 ]);
 
 /** Any lease IPC request (inferred from {@link LeaseIpcRequestSchema}). */
@@ -334,6 +396,55 @@ export const ChildKilledUnresponsiveResponseSchema = z
 /** Child-killed event payload (inferred from {@link ChildKilledUnresponsiveResponseSchema}). */
 export type ChildKilledUnresponsiveResponse = z.infer<typeof ChildKilledUnresponsiveResponseSchema>;
 
+/**
+ * The disposition of a `queue_admit` request (T11630). Mirrors
+ * `QueueAdmitDisposition` in Rust — `admitted` (execute now) or `deferred`
+ * (back off `retry_after_ms` and re-request; AC4 — never a silent drop).
+ */
+export const QueueAdmitDispositionSchema = z.enum(['admitted', 'deferred']);
+
+/** A `queue_admit` disposition (inferred from {@link QueueAdmitDispositionSchema}). */
+export type QueueAdmitDisposition = z.infer<typeof QueueAdmitDispositionSchema>;
+
+/**
+ * Reply to a `queue_admit`: the LLM call was admitted or deferred (T11630).
+ * Mirrors `QueueAdmitResult`.
+ */
+export const QueueAdmitResultResponseSchema = z
+  .object({
+    /** Tag discriminating this response variant. */
+    kind: z.literal('queue_admit_result'),
+    /** Whether the LLM call was admitted or deferred. */
+    disposition: QueueAdmitDispositionSchema,
+    /** Back-off in ms before re-requesting (0 when admitted). */
+    retry_after_ms: z.number().int().nonnegative(),
+    /** Remaining provider token budget after this decision. */
+    tokens_remaining: z.number().int().nonnegative(),
+    /** Number of higher/equal-priority waiters ahead (0 when admitted). */
+    queue_position: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/** Queue-admit result payload (inferred from {@link QueueAdmitResultResponseSchema}). */
+export type QueueAdmitResultResponse = z.infer<typeof QueueAdmitResultResponseSchema>;
+
+/**
+ * Acknowledge a `worker_heartbeat` (T11628). Mirrors `HeartbeatAck`.
+ *
+ * Deliberately carries only its `kind` — the ack's presence (correlated by id)
+ * is the signal that the watchdog recorded the beat and reset the child's
+ * deadline. Matches the Rust unit-struct wire shape `{ "kind": "heartbeat_ack" }`.
+ */
+export const HeartbeatAckResponseSchema = z
+  .object({
+    /** Tag discriminating this response variant. */
+    kind: z.literal('heartbeat_ack'),
+  })
+  .strict();
+
+/** Heartbeat-ack response payload (inferred from {@link HeartbeatAckResponseSchema}). */
+export type HeartbeatAckResponse = z.infer<typeof HeartbeatAckResponseSchema>;
+
 /**
  * An error response correlated to a request. Mirrors the v1.0
  * `crate::ipc::ErrorResult` shape reused by the Rust `LeaseResponse::Error`
@@ -366,6 +477,8 @@ export const LeaseIpcResponseSchema = z.discriminatedUnion('kind', [
   ToolGrantedResponseSchema,
   LeaseRevokedResponseSchema,
   ChildKilledUnresponsiveResponseSchema,
+  QueueAdmitResultResponseSchema,
+  HeartbeatAckResponseSchema,
   LeaseErrorResponseSchema,
 ]);
 
@@ -444,6 +557,8 @@ export const LEASE_IPC_REQUEST_KINDS = [
   'lease_renew',
   'rate_check',
   'tool_grant',
+  'queue_admit',
+  'worker_heartbeat',
 ] as const;
 
 /**
@@ -458,6 +573,8 @@ export const LEASE_IPC_RESPONSE_KINDS = [
   'tool_granted',
   'lease_revoked',
   'child_killed_unresponsive',
+  'queue_admit_result',
+  'heartbeat_ack',
   'error',
 ] as const;