@cleocode/contracts 2026.6.13 → 2026.6.15

package/src/config.ts

@@ -638,9 +638,10 @@ 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;
   /**
@@ -750,6 +751,98 @@ export interface LeadRollupConfig {
   mode?: LeadRollupMode;
 }
 
+/**
+ * Daemon lifecycle configuration.
+ *
+ * Controls whether the postinstall hook is allowed to auto-enable and start
+ * the cleo-daemon service. When `autoStart` is `false`, postinstall NEVER
+ * enables or starts the service — even on a fresh install. This flag persists
+ * across upgrades so the operator's intent survives `npm install -g`.
+ *
+ * Configure via `~/.local/share/cleo/config.json` (global config):
+ * ```json
+ * { "daemon": { "autoStart": false } }
+ * ```
+ * Or via env var override: `CLEO_DAEMON_DISABLE=1` (per-session, non-persistent).
+ *
+ * @task T11984
+ */
+export interface DaemonConfig {
+  /**
+   * Whether the postinstall hook may auto-enable and start the cleo-daemon.
+   *
+   * - `true` (default): first install enables+starts; upgrade respects the
+   *   current systemd/launchd enabled state.
+   * - `false`: postinstall NEVER enables or starts the daemon. The unit file
+   *   is still written so the operator can activate later via
+   *   `cleo daemon enable`.
+   *
+   * @defaultValue true
+   */
+  autoStart: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Resources config (T11994 · PSI + MemAvailable sensing)
+// ---------------------------------------------------------------------------
+
+/**
+ * PSI pressure thresholds for the ResourceMonitor.
+ *
+ * Values are percentage points (0–100) for `avg10` exponential moving averages.
+ * Defaults sit far below systemd-oomd's Fedora kill line (80%/20s on
+ * user@1000.service).
+ *
+ * @task T11994
+ */
+export interface ResourcesPsiConfig {
+  /**
+   * Enter `hold` state when `some avg10` exceeds this value.
+   * @defaultValue 10
+   */
+  holdSomeAvg10?: number;
+  /**
+   * Enter `backoff` state when `some avg10` exceeds this value.
+   * @defaultValue 20
+   */
+  backoffSomeAvg10?: number;
+  /**
+   * Enter `hold` state when `full avg10` exceeds this value.
+   * @defaultValue 5
+   */
+  holdFullAvg10?: number;
+  /**
+   * Enter `backoff` state when `full avg10` exceeds this value.
+   * @defaultValue 10
+   */
+  backoffFullAvg10?: number;
+}
+
+/**
+ * Resource monitor configuration.
+ *
+ * Optional block — all fields have safe defaults. Maps to the
+ * `resources.*` config namespace (Amendment 5 · T11994).
+ *
+ * @task T11994
+ */
+export interface ResourcesConfig {
+  /**
+   * PSI pressure thresholds (percentage points).
+   *
+   * @defaultValue undefined (monitor uses built-in defaults)
+   */
+  psi?: ResourcesPsiConfig;
+  /**
+   * Minimum free memory headroom in MiB.
+   *
+   * Used in degraded mode (PSI absent) as the sole availability signal.
+   *
+   * @defaultValue 256
+   */
+  headroomMb?: number;
+}
+
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
   /** Configuration schema version string. */
@@ -837,6 +930,28 @@ export interface CleoConfig {
    * @saga T10377
    */
   leadRollup?: LeadRollupConfig;
+  /**
+   * Daemon lifecycle settings.
+   *
+   * When absent, defaults to `{ autoStart: true }` — matching the legacy
+   * install behaviour. Set `autoStart: false` to prevent postinstall from
+   * ever enabling or starting the cleo-daemon (persistent opt-out).
+   *
+   * @defaultValue undefined (treated as { autoStart: true })
+   * @task T11984
+   */
+  daemon?: DaemonConfig;
+  /**
+   * Resource monitor configuration — PSI pressure thresholds and memory
+   * headroom for the daemon-off governor and continuous supervisor mode.
+   *
+   * When absent, the ResourceMonitor uses built-in defaults which sit well
+   * below systemd-oomd's Fedora kill line (80%/20s on user@1000.service).
+   *
+   * @defaultValue undefined (ResourceMonitor uses built-in defaults)
+   * @task T11994
+   */
+  resources?: ResourcesConfig;
 }
 
 /**

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

@@ -104,6 +104,26 @@ export const CANONICAL_DOMAINS = [
   // 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).
    *