@cleocode/contracts 2026.5.129 → 2026.5.131

package/src/index.ts

@@ -288,6 +288,29 @@ export type {
   ParsedClaudeCodeCredential,
 } from './credentials.js';
 export { parseClaudeCodeCredentials } from './credentials.js';
+// === Daemon lifecycle + subsystem contracts (T11366 · SG-RUNTIME-UNIFICATION R2) ===
+export type {
+  DaemonLifecycleHooks,
+  HealthStatus,
+  Subsystem,
+  SubsystemDefinition,
+  SubsystemHealth,
+  SubsystemLifecyclePhase,
+  SubsystemState,
+} from './daemon/index.js';
+export {
+  HealthStatusSchema,
+  SUBSYSTEM_LIFECYCLE_PHASES,
+  SubsystemHealthSchema,
+  SubsystemStateSchema,
+  summarizeHealth,
+  toMonitorChildren,
+} from './daemon/index.js';
+// === Daemon-IPC v1.0 (AC8 alias of supervisor-ipc — T11369 · R2 gates R4-R7) ===
+// `daemon-ipc` is the AC8-named re-export barrel over the FROZEN supervisor-ipc
+// v1.0 contract — one contract, two names. The subpath
+// `@cleocode/contracts/daemon-ipc` resolves via the package `./*` export.
+export { DAEMON_IPC_PROTOCOL_VERSION } from './daemon-ipc/index.js';
 // === DataAccessor Interface ===
 export type {
   AcBindingRow,
@@ -610,6 +633,28 @@ export {
   AGENT_TYPES,
   BRAIN_OBSERVATION_TYPES,
 } from './facade.js';
+// === CLEO-native Goal System (T11376 · Epic T11290 · Saga T11283) ===
+export type {
+  FuzzyGoal,
+  GoalAdvanceResult,
+  GoalContinuation,
+  GoalJudge,
+  GoalJudgeVerdict,
+  GoalKind,
+  GoalKindTag,
+  GoalRecord,
+  GoalStatus,
+  TaskCompletionGoal,
+} from './goal.js';
+export {
+  GOAL_STATUSES,
+  GOAL_TARGET_TASK_ID_REGEX,
+  GOAL_TERMINAL_STATUSES,
+  isFuzzyGoal,
+  isTaskCompletionGoal,
+  isTerminalGoalStatus,
+  isValidGoalTargetTaskId,
+} from './goal.js';
 // === Graph Intelligence Types (T512, T529, T1862, T9145) ===
 export type {
   AmbiguousProvenance,
@@ -784,6 +829,22 @@ export type {
   PatternRecord,
   SessionSummary,
 } from './memory.js';
+// === MVI progressive-disclosure primitive (T11349 · Epic T11285 · Saga T11283) ===
+export type {
+  ExpansionHint,
+  MviDigest,
+  NextDirectivesHint,
+  StructuredOpsHint,
+  SuggestedCommandsHint,
+} from './mvi.js';
+export {
+  expansionFromNextDirectives,
+  expansionFromStructuredOps,
+  expansionFromSuggestedCommands,
+  isNextDirectivesHint,
+  isStructuredOpsHint,
+  isSuggestedCommandsHint,
+} from './mvi.js';
 export type {
   Contract,
   ContractCompatibilityMatrix,
@@ -1886,6 +1947,54 @@ export type {
   SignaldockAccessor,
   TelemetryAccessor,
 } from './sub-accessors.js';
+export type {
+  ChildState,
+  ChildStatus,
+  EnvPair,
+  ErrorResponse,
+  HealthRequest,
+  HealthResponse,
+  LifecycleEventKind,
+  LifecycleEventResponse,
+  MonitorRequest,
+  MonitorResponse,
+  RestartedResponse,
+  RestartRequest,
+  SpawnedResponse,
+  SpawnRequest,
+  SupervisorIpcEnvelope,
+  SupervisorIpcRequest,
+  SupervisorIpcRequestEnvelope,
+  SupervisorIpcResponse,
+  SupervisorIpcResponseEnvelope,
+} from './supervisor-ipc/index.js';
+// === Supervisor IPC v1.0 (FROZEN — T11339 · SG-RUNTIME-UNIFICATION R1) ===
+export {
+  ChildStateSchema,
+  ChildStatusSchema,
+  EnvPairSchema,
+  ErrorResponseSchema,
+  HealthRequestSchema,
+  HealthResponseSchema,
+  LifecycleEventKindSchema,
+  LifecycleEventResponseSchema,
+  MonitorRequestSchema,
+  MonitorResponseSchema,
+  RestartedResponseSchema,
+  RestartRequestSchema,
+  SpawnedResponseSchema,
+  SpawnRequestSchema,
+  SUPERVISOR_IPC_CHANNEL_BASENAME,
+  SUPERVISOR_IPC_MESSAGE_KINDS,
+  SUPERVISOR_IPC_PROTOCOL_VERSION,
+  SUPERVISOR_IPC_REQUEST_KINDS,
+  SUPERVISOR_IPC_RESPONSE_KINDS,
+  SupervisorIpcEnvelopeSchema,
+  SupervisorIpcRequestEnvelopeSchema,
+  SupervisorIpcRequestSchema,
+  SupervisorIpcResponseEnvelopeSchema,
+  SupervisorIpcResponseSchema,
+} from './supervisor-ipc/index.js';
 // === Task Types ===
 export type {
   AcceptanceItem,

package/src/mvi.ts

@@ -0,0 +1,236 @@
+/**
+ * MVI (Minimum-Viable-Information) progressive-disclosure primitive.
+ *
+ * CLEO historically grew three *separate* "expansion-hint" conventions, each
+ * answering the same question — *"the agent got a lean result; how does it
+ * drill deeper?"* — in a different wire shape:
+ *
+ * 1. **`_next`** (`core/src/mvi-helpers.ts`) — `Record<string, string>`: a map
+ *    of follow-up *name* → copy-pasteable CLI command
+ *    (`{ full: "cleo show T1", children: "cleo find --parent T1" }`).
+ * 2. **`meta.suggestedNext`** (`core/src/dispatch/suggested-next.ts`, T9920) — a
+ *    flat `ReadonlyArray<string>` of copy-pasteable CLI commands.
+ * 3. **`_nexus.suggestedNext`** (`contracts/operations/nexus-scope.ts`) — a
+ *    `ReadonlyArray<SuggestedNextOp>` of machine-readable, structured operations.
+ *
+ * {@link MviDigest} is the single primitive that unifies them. A digest
+ * describes a *collapsed* collection: a one-line `summary`, the total `count`,
+ * an optional bounded `preview` sample, and exactly one {@link ExpansionHint}
+ * describing how to fetch the rest. The hint is a discriminated union whose
+ * variants are the three legacy conventions — so existing producers can emit a
+ * digest and existing consumers can read one *without any `any` casts*.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/mvi
+ *
+ * @epic T11285 EP-MVI-PRIMITIVE
+ * @task T11349
+ * @saga T11283 SG-COGNITIVE-SUBSTRATE
+ */
+
+import type { SuggestedNextOp } from './operations/nexus-scope.js';
+
+/**
+ * `_next`-style expansion hint: a map of follow-up *name* → CLI command string.
+ *
+ * The `kind` discriminant lets a single {@link MviDigest} carry any of the
+ * three legacy conventions without ambiguity. This variant corresponds to the
+ * `_next` directives built by `core/src/mvi-helpers.ts`.
+ *
+ * @example
+ * ```ts
+ * const hint: NextDirectivesHint = {
+ *   kind: 'next-directives',
+ *   directives: { full: 'cleo show T1', children: 'cleo find --parent T1' },
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface NextDirectivesHint {
+  /** Discriminant: this hint carries `_next`-style named CLI directives. */
+  readonly kind: 'next-directives';
+  /** Map of follow-up operation name → copy-pasteable CLI command string. */
+  readonly directives: Readonly<Record<string, string>>;
+}
+
+/**
+ * `meta.suggestedNext`-style expansion hint: a flat list of CLI commands.
+ *
+ * Corresponds to the `ReadonlyArray<string>` promoted to
+ * `meta.suggestedNext` in T9920 (`core/src/dispatch/suggested-next.ts`).
+ *
+ * @example
+ * ```ts
+ * const hint: SuggestedCommandsHint = {
+ *   kind: 'suggested-commands',
+ *   commands: ['cleo show T1', 'cleo focus T1'],
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface SuggestedCommandsHint {
+  /** Discriminant: this hint carries a flat list of CLI command strings. */
+  readonly kind: 'suggested-commands';
+  /** Copy-pasteable CLI command strings the agent may run next. */
+  readonly commands: ReadonlyArray<string>;
+}
+
+/**
+ * `_nexus.suggestedNext`-style expansion hint: structured machine-readable ops.
+ *
+ * Corresponds to the `ReadonlyArray<SuggestedNextOp>` carried under
+ * `meta._nexus.suggestedNext` (`contracts/operations/nexus-scope.ts`). Display
+ * strings are *derived* from these structured fields, never the reverse.
+ *
+ * @example
+ * ```ts
+ * const hint: StructuredOpsHint = {
+ *   kind: 'structured-ops',
+ *   ops: [{ op: 'nexus.context', args: { name: 'foo' }, scope: 'project',
+ *           effect: 'read', requiresConfirmation: false, reason: 'see callers' }],
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface StructuredOpsHint {
+  /** Discriminant: this hint carries structured, machine-readable operations. */
+  readonly kind: 'structured-ops';
+  /** Structured next-operations. Every `.op` resolves to a known op key. */
+  readonly ops: ReadonlyArray<SuggestedNextOp>;
+}
+
+/**
+ * Unified expansion hint — the discriminated union reconciling CLEO's three
+ * historical progressive-disclosure conventions (`_next`,
+ * `meta.suggestedNext`, `_nexus.suggestedNext`) under one type.
+ *
+ * Narrow on {@link ExpansionHint | the `.kind` discriminant} to access the
+ * variant payload without casts.
+ *
+ * @public
+ */
+export type ExpansionHint = NextDirectivesHint | SuggestedCommandsHint | StructuredOpsHint;
+
+/**
+ * The Minimum-Viable-Information digest: the formalized progressive-disclosure
+ * primitive for any *collapsed* collection in a LAFS envelope.
+ *
+ * Instead of streaming a full collection (and blowing the agent's token
+ * budget), a producer emits a digest: a one-line {@link MviDigest.summary}, the
+ * total {@link MviDigest.count}, an optional bounded {@link MviDigest.preview}
+ * sample, and exactly one {@link MviDigest.expand} hint describing how to fetch
+ * the remainder.
+ *
+ * @typeParam T - Element type of the underlying collection. The optional
+ *   `preview` is a `ReadonlyArray<T>`; the rest of the digest is element-shape
+ *   agnostic, so a producer can describe any collection with one primitive.
+ *
+ * @example
+ * ```ts
+ * const digest: MviDigest<{ id: string }> = {
+ *   summary: '12 child tasks (3 done, 9 pending)',
+ *   count: 12,
+ *   preview: [{ id: 'T1' }, { id: 'T2' }],
+ *   expand: { kind: 'next-directives', directives: { all: 'cleo list --parent T0' } },
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface MviDigest<T = unknown> {
+  /** One-line human/agent-readable summary of the collapsed collection. */
+  readonly summary: string;
+  /** Total number of elements the collection contains (not the preview size). */
+  readonly count: number;
+  /**
+   * A bounded sample of elements for at-a-glance context. Omitted when no
+   * preview is carried (the agent must {@link MviDigest.expand} to see any).
+   *
+   * @defaultValue undefined
+   */
+  readonly preview?: ReadonlyArray<T>;
+  /** Exactly one {@link ExpansionHint} describing how to fetch the remainder. */
+  readonly expand: ExpansionHint;
+}
+
+/**
+ * Adapt a legacy `_next` directives map into the unified {@link ExpansionHint}.
+ *
+ * Lets existing `core/src/mvi-helpers.ts` producers feed a digest without
+ * re-shaping their output by hand.
+ *
+ * @param directives - The `_next`-style name → CLI command map.
+ * @returns A {@link NextDirectivesHint} wrapping the directives verbatim.
+ *
+ * @public
+ */
+export function expansionFromNextDirectives(
+  directives: Readonly<Record<string, string>>,
+): NextDirectivesHint {
+  return { kind: 'next-directives', directives };
+}
+
+/**
+ * Adapt a legacy `meta.suggestedNext` command list into an {@link ExpansionHint}.
+ *
+ * @param commands - The flat `ReadonlyArray<string>` of CLI commands.
+ * @returns A {@link SuggestedCommandsHint} wrapping the commands verbatim.
+ *
+ * @public
+ */
+export function expansionFromSuggestedCommands(
+  commands: ReadonlyArray<string>,
+): SuggestedCommandsHint {
+  return { kind: 'suggested-commands', commands };
+}
+
+/**
+ * Adapt a legacy `_nexus.suggestedNext` op list into an {@link ExpansionHint}.
+ *
+ * @param ops - The structured `ReadonlyArray<SuggestedNextOp>`.
+ * @returns A {@link StructuredOpsHint} wrapping the ops verbatim.
+ *
+ * @public
+ */
+export function expansionFromStructuredOps(ops: ReadonlyArray<SuggestedNextOp>): StructuredOpsHint {
+  return { kind: 'structured-ops', ops };
+}
+
+/**
+ * Type guard: narrow an {@link ExpansionHint} to its `_next`-directives variant.
+ *
+ * @param hint - The hint to test.
+ * @returns `true` when `hint.kind === 'next-directives'`.
+ *
+ * @public
+ */
+export function isNextDirectivesHint(hint: ExpansionHint): hint is NextDirectivesHint {
+  return hint.kind === 'next-directives';
+}
+
+/**
+ * Type guard: narrow an {@link ExpansionHint} to its suggested-commands variant.
+ *
+ * @param hint - The hint to test.
+ * @returns `true` when `hint.kind === 'suggested-commands'`.
+ *
+ * @public
+ */
+export function isSuggestedCommandsHint(hint: ExpansionHint): hint is SuggestedCommandsHint {
+  return hint.kind === 'suggested-commands';
+}
+
+/**
+ * Type guard: narrow an {@link ExpansionHint} to its structured-ops variant.
+ *
+ * @param hint - The hint to test.
+ * @returns `true` when `hint.kind === 'structured-ops'`.
+ *
+ * @public
+ */
+export function isStructuredOpsHint(hint: ExpansionHint): hint is StructuredOpsHint {
+  return hint.kind === 'structured-ops';
+}

package/src/operations/attention.ts

@@ -0,0 +1,117 @@
+/**
+ * Attention Domain Operations Contract (Tier-2 working memory).
+ *
+ * The attention buffer is a per-agent, scope-keyed, decaying working-memory
+ * layer. `cleo attention add` (alias `jot`) writes ONE item, auto-keyed to the
+ * narrowest scope the writing agent resolves (agent > task > epic > saga >
+ * session > global) via the E0 env-first identity resolvers. Because visibility
+ * is the scope key itself, an agent working task `T-A` can never read the
+ * agent/task-scoped items written by an agent working `T-B` — cross-agent
+ * leakage is structurally impossible (Epic T11288).
+ *
+ * CLI identifiers start with `attention.*` and route through the `attention`
+ * domain handler. These operation types are the wire-format API contract.
+ *
+ * @task T11373 — Attention CLI + dispatch op
+ * @epic T11288 EP-TIER2-ATTENTION
+ * @saga T11283 SG-COGNITIVE-SUBSTRATE
+ * @see packages/core/src/memory/attention.ts
+ * @see packages/cleo/src/dispatch/domains/attention.ts
+ */
+
+/**
+ * Scope-kind taxonomy for attention items, ordered NARROWEST → BROADEST.
+ *
+ * Mirrors `BRAIN_ATTENTION_SCOPE_KINDS` in the brain schema; declared here so
+ * the wire contract does not depend on the core schema module.
+ */
+export type AttentionScopeKind = 'agent' | 'task' | 'epic' | 'saga' | 'session' | 'global';
+
+/** Lifecycle status of an attention item. */
+export type AttentionStatus = 'open' | 'consolidated' | 'discarded';
+
+/**
+ * One attention item in wire format.
+ *
+ * Returned by `add`, `show`, and `list`. `tags` is always a parsed string
+ * array (decoded from the JSONB column via `json(col)`), never the raw BLOB.
+ */
+export interface AttentionItem {
+  /** Stable item id (`att_<ts>_<hex>`). */
+  id: string;
+  /** The jot content. */
+  content: string;
+  /** Resolved session id of the writer, if any. */
+  sessionId: string | null;
+  /** Resolved agent identity of the writer, if any. */
+  agentId: string | null;
+  /** Narrowest scope kind the item was keyed to. */
+  scopeKind: AttentionScopeKind;
+  /** Id of the bound scope (task/epic/saga id, agent id, session id, or `global`). */
+  scopeId: string;
+  /** Parsed tag list (decoded from the JSONB column). */
+  tags: string[];
+  /** Creation time, unix epoch milliseconds. */
+  createdAt: number;
+  /** Optional hard TTL, unix epoch milliseconds. */
+  expiresAt: number | null;
+  /** Optional decay score in `[0, 1]`. */
+  decayScore: number | null;
+  /** Lifecycle status. */
+  status: AttentionStatus;
+}
+
+/**
+ * Parameters for `attention.add` (alias `jot`).
+ *
+ * Identity (`sessionId`/`agentId`) and the current task are resolved server-
+ * side from the environment (E0) — callers do NOT pass them by default. The
+ * optional `scope` override escalates the auto-resolved narrowest scope.
+ */
+export interface AttentionAddParams {
+  /** The jot content. Required, non-empty. */
+  content: string;
+  /** Optional tags to attach. */
+  tags?: string[];
+  /**
+   * Optional explicit scope override. When omitted the narrowest resolvable
+   * scope is used. Accepts a scope kind to escalate to (e.g. `epic`, `saga`).
+   */
+  scope?: AttentionScopeKind;
+  /** Optional TTL in seconds from now (sets `expiresAt`). */
+  ttlSeconds?: number;
+}
+
+/**
+ * Parameters for `attention.list` / `attention.show`.
+ *
+ * With no flags the resolved scope chain (narrowest + visible ancestors) of the
+ * calling agent is used. `--scope` restricts to one kind; `--tag` filters by
+ * "contains ALL" membership.
+ */
+export interface AttentionListParams {
+  /** Restrict to one scope kind. */
+  scope?: AttentionScopeKind;
+  /** "Contains ALL" tag filter. */
+  tags?: string[];
+  /** Include non-open items too (default: open only). */
+  includeAll?: boolean;
+  /** Max rows. */
+  limit?: number;
+}
+
+/** Result of `attention.add`. */
+export interface AttentionAddResult {
+  /** The persisted item. */
+  item: AttentionItem;
+}
+
+/** Result of `attention.list` / `attention.show`. */
+export interface AttentionListResult {
+  /** Matching items, newest first. */
+  items: AttentionItem[];
+  /** Total returned (== items.length; the digest carries the live count). */
+  total: number;
+  /** The scope chain the items were resolved against (for transparency). */
+  resolvedScopes: Array<{ kind: AttentionScopeKind; id: string }>;
+}

package/src/operations/docs.ts

@@ -102,7 +102,13 @@ export type DocsType = BuiltinDocKind;
 export interface DocsAttachmentRow {
   /** Attachment identifier (UUID-like string). */
   id: string;
-  /** SHA-256 hash of content; truncated to 8 chars in list views. */
+  /**
+   * Full SHA-256 hex digest of the content (64 chars). The machine envelope
+   * always carries the complete hash so consumers can do exact content-equality
+   * checks; human/table rendering may abbreviate it for display. (T11294 —
+   * truncating it here previously forced the Manual-Write-Sweep into O(docs)
+   * `docs fetch` spawns to recover the real digest.)
+   */
   sha256: string;
   /** Attachment kind / storage mode. */
   kind: AttachmentKind;

package/src/operations/focus.ts

@@ -12,8 +12,25 @@
  * @epic T9964 E-ORIENT-V2
  */
 
+import type { MviDigest } from '../mvi.js';
+import type { AttentionScopeKind } from './attention.js';
 import type { MemoryCompactHit } from './memory.js';
 
+/**
+ * A minimal preview element for the attention digest (T11374 · Epic T11288).
+ *
+ * The MVI digest preview carries only the few fields an agent needs to glance
+ * at a jot — the full item is one `cleo attention show` away (the expand hint).
+ */
+export interface AttentionDigestPreviewItem {
+  /** Item id. */
+  id: string;
+  /** Truncated jot content. */
+  content: string;
+  /** Scope kind the jot is keyed to. */
+  scopeKind: AttentionScopeKind;
+}
+
 // ---------------------------------------------------------------------------
 // Params
 // ---------------------------------------------------------------------------
@@ -205,6 +222,15 @@ export interface FocusShowResult {
    * Omitted when the BRAIN store is unavailable.
    */
   brainContext?: FocusBrainContext;
+  /**
+   * Tier-2 attention digest — a budget-bounded MVI summary of the open
+   * working-memory jots visible to the calling agent in this scope (T11374 ·
+   * Epic T11288). Carries a one-line summary, the live count, a tiny preview,
+   * and the `cleo attention show` expand hint — never a full dump. Omitted when
+   * there are zero open items (the empty-attention contract) or the buffer is
+   * unavailable.
+   */
+  attentionDigest?: MviDigest<AttentionDigestPreviewItem>;
   /** Estimated token weight of this envelope. */
   tokensEstimated: number;
 }

package/src/operations/index.ts

@@ -7,6 +7,7 @@
 
 export * from './admin.js';
 export * from './agent-operation-contract.js';
+export * from './attention.js';
 export * from './brain.js';
 export * from './conduit.js';
 export * from './dialectic.js';

package/src/operations/session.ts

@@ -581,6 +581,17 @@ export interface SessionEndParams {
    * @task T140 @epic T134
    */
   sessionSummary?: import('../config.js').SessionSummaryInput;
+  /**
+   * Explicit session id to end (T11346 · Epic T11284).
+   *
+   * When omitted, session-end targets the CALLER's session resolved env-first
+   * (`CLEO_SESSION_ID` → … → most-recent active). When provided, this id
+   * overrides env/active resolution. Either way, one agent can no longer end a
+   * different concurrently-active agent's session implicitly.
+   *
+   * @task T11346
+   */
+  sessionId?: string;
 }
 /** Result of `session.end`. */
 export interface SessionEndResult {

package/src/sdk-tool.ts

@@ -10,7 +10,7 @@
  * - MUST be pure or side-effect-isolated (testable without running an agent).
  * - SHOULD be deterministic given identical inputs.
  *
- * Canonical location: `packages/core/src/tools/sdk/`
+ * Canonical location: `packages/core/src/sdk/`
  *
  * Distinct from Category A (Agent Tool — LLM-callable primitive registered in
  * AgentToolRegistry) and Category C (Domain Utility — internal to a specific