@cleocode/contracts 2026.5.96 → 2026.5.97

package/src/memory/search.ts

@@ -0,0 +1,145 @@
+/**
+ * BRAIN compact-search wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
+ * per result) so agents can scan a wide candidate set cheaply before drilling
+ * into a specific entry.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
+ * depend on the shape without importing core. Unblocks the
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
+ * (T9834).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 2: {@link ./timeline.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+
+// ── BrainCompactHit ─────────────────────────────────────────────────
+
+/**
+ * Single compact hit returned by `searchBrainCompact`.
+ *
+ * Minimal projection of a BRAIN table row designed for cheap scanning —
+ * the full payload is fetched on demand via `fetchBrainEntries` (Layer 3).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainCompactHit {
+  /** Entry identifier (e.g. `D-arch-001`, `P-feat-042`). */
+  id: string;
+  /** Source BRAIN table that produced the hit. */
+  type: 'decision' | 'pattern' | 'learning' | 'observation';
+  /** Display title for the entry. */
+  title: string;
+  /** ISO 8601 creation date. */
+  date: string;
+  /** Legacy relevance score (BM25-only path); omit when `rrfScore` is set. */
+  relevance?: number;
+  /**
+   * RRF-fused score: sum of 1/(rank+60) across all retrieval sources.
+   * Present only when the RRF path is used (`useRRF=true`, default).
+   * Higher = stronger match. Comparable across results in the same query.
+   */
+  rrfScore?: number;
+  /**
+   * BM25-derived score, min-max normalized to [0, 1] across the result set.
+   * 1.0 = best BM25 rank in this query, 0.0 = worst (or not found via FTS).
+   * Present only when the RRF path is used and at least one FTS result exists.
+   */
+  bm25Score?: number;
+  /**
+   * Progressive-disclosure directives for follow-up operations.
+   *
+   * Maps follow-up keys (e.g. `fetch`, `timeline`) to suggested CLI commands.
+   * `Record<string, string>` mirrors the runtime `NextDirectives` alias used
+   * by `@cleocode/core`'s `mvi-helpers`.
+   */
+  _next?: Record<string, string>;
+}
+
+// ── SearchBrainCompactParams ────────────────────────────────────────
+
+/**
+ * Parameters for `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactParams {
+  /** Free-text query (FTS5 + optional vector recall). */
+  query: string;
+  /** Maximum number of hits to return (caller-bounded). */
+  limit?: number;
+  /** Restrict the search to a subset of BRAIN tables. */
+  tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
+  /** ISO 8601 lower-bound date filter (inclusive). */
+  dateStart?: string;
+  /** ISO 8601 upper-bound date filter (inclusive). */
+  dateEnd?: string;
+  /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
+  agent?: string;
+  /**
+   * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
+   * vector search results for higher recall and better ranking.
+   * When false, fall back to FTS5-only search (faster, no embeddings needed).
+   */
+  useRRF?: boolean;
+  /**
+   * T1085: Peer ID filter for CANT agent memory isolation (PSYCHE Wave 2).
+   *
+   * When provided, search results are scoped to entries where:
+   *   `peer_id = peerId OR peer_id = 'global'`
+   *
+   * When omitted, all entries are returned — backward-compatible behavior.
+   */
+  peerId?: string;
+  /**
+   * T1085: When true (default when peerId is provided), include entries with
+   * `peer_id = 'global'` alongside the peer-specific entries.
+   *
+   * Set to false for strict per-peer isolation (no global pool bleed-through).
+   */
+  includeGlobal?: boolean;
+  /**
+   * T1900: ranking mode.
+   *
+   * - `recency`  — ORDER BY created_at DESC, no BM25/RRF contribution.
+   *                Use for recentObservations / recentLearnings where
+   *                chronological freshness matters more than textual match.
+   * - `lexical`  — FTS5 BM25 only (useRRF=false legacy path).
+   * - `hybrid`   — Reciprocal Rank Fusion (default, useRRF=true path).
+   *
+   * @default 'hybrid'
+   */
+  mode?: 'recency' | 'lexical' | 'hybrid';
+  /**
+   * T1900: ISO 8601 timestamp lower-bound filter (inclusive).
+   *
+   * When provided, only rows with `created_at >= since` are returned.
+   * Applies to all modes including recency. Useful with `mode=hybrid`
+   * (e.g., `since=<30d>`) to limit pattern staleness.
+   *
+   * When omitted, no lower-bound date filter is applied.
+   */
+  since?: string;
+}
+
+// ── SearchBrainCompactResult ────────────────────────────────────────
+
+/**
+ * Result envelope returned by `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactResult {
+  /** Ordered compact hits (best match first). */
+  results: BrainCompactHit[];
+  /** Total number of matches before `limit` truncation. */
+  total: number;
+  /** Approximate token cost of the returned payload (~chars/4). */
+  tokensEstimated: number;
+}

package/src/memory/timeline.ts

@@ -0,0 +1,100 @@
+/**
+ * BRAIN timeline wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
+ * around an anchor entry so an agent can reconstruct the surrounding
+ * memory context cheaply.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
+ * continues to re-export it for internal callers.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+
+// ── BrainAnchor ─────────────────────────────────────────────────────
+
+/**
+ * Anchor entry around which a timeline is built.
+ *
+ * Carries the entry identifier, its source table (`type`), and the full
+ * payload (`data`) so the caller can render the anchor inline with the
+ * neighbor list without an additional `fetchBrainEntries` round trip.
+ *
+ * Originally defined in `packages/core/src/memory/brain-row-types.ts:46`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainAnchor {
+  /** Entry identifier (e.g. `O-abc123`, `D-arch-001`). */
+  id: string;
+  /** Source BRAIN table (e.g. `observation`, `decision`, `pattern`, `learning`). */
+  type: string;
+  /**
+   * Raw row payload as returned by the underlying SQL query.
+   *
+   * Typed as `unknown` because the shape varies by `type`. Callers narrow
+   * via a discriminated read or pass the value through to a renderer that
+   * already understands every BRAIN table shape.
+   */
+  data: unknown;
+}
+
+// ── TimelineBrainParams ─────────────────────────────────────────────
+
+/**
+ * Parameters for `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainParams {
+  /** Anchor entry ID to build the timeline around. */
+  anchor: string;
+  /** Number of chronologically-earlier neighbors to include. */
+  depthBefore?: number;
+  /** Number of chronologically-later neighbors to include. */
+  depthAfter?: number;
+}
+
+// ── TimelineNeighbor ────────────────────────────────────────────────
+
+/**
+ * Compact neighbor projection used in timeline results.
+ *
+ * Each neighbor is reduced to an `{id, type, date}` triple so callers can
+ * cheaply scan a large window before drilling into specific entries via
+ * `fetchBrainEntries`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineNeighbor {
+  /** Entry identifier. */
+  id: string;
+  /** Source BRAIN table (e.g. `observation`, `decision`). */
+  type: string;
+  /** ISO 8601 creation date. */
+  date: string;
+}
+
+// ── TimelineBrainResult ─────────────────────────────────────────────
+
+/**
+ * Result envelope returned by `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainResult {
+  /** The anchor entry, or `null` when the requested ID does not resolve. */
+  anchor: BrainAnchor | null;
+  /** Chronologically-earlier neighbors, oldest first. */
+  before: TimelineNeighbor[];
+  /** Chronologically-later neighbors, newest last. */
+  after: TimelineNeighbor[];
+}

package/src/operations/focus.ts

@@ -0,0 +1,226 @@
+/**
+ * Focus Domain Operations — single-envelope task orientation.
+ *
+ * `cleo focus <id>` aggregates 8 separate orientation calls into one
+ * wire-format envelope covering identity, scope, members, blockers,
+ * the next parallel-safe wave, attached docs, recent git activity, and
+ * scope-filtered brain context.
+ *
+ * Token budget: ≤ 1 500 tokens for a typical task orientation request.
+ *
+ * @task T9973
+ * @epic T9964 E-ORIENT-V2
+ */
+
+import type { MemoryCompactHit } from './memory.js';
+
+// ---------------------------------------------------------------------------
+// Params
+// ---------------------------------------------------------------------------
+
+/**
+ * Parameters for `focus.show`.
+ *
+ * @task T9973
+ */
+export interface FocusShowParams {
+  /** Task, Epic, or Saga ID to orient on (e.g. `T9973`, `T9831`). Required. */
+  id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Result sub-types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal identity block surfaced for the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusIdentity {
+  /** Task / Epic / Saga identifier. */
+  id: string;
+  /** Human-readable title. */
+  title: string;
+  /** Entity tier — `'task'`, `'epic'`, or `'saga'`. */
+  type: string;
+  /** Current lifecycle status. */
+  status: string;
+  /** Parent task / Epic identifier, if any. */
+  parentId?: string | null;
+}
+
+/**
+ * Scope hierarchy resolved from the focused entity's ancestry.
+ *
+ * @task T9973
+ */
+export interface FocusScope {
+  /** Saga ID, when the entity belongs to a Saga. */
+  sagaId?: string;
+  /** Epic ID when the entity is a task or the focused entity itself is an Epic. */
+  epicId?: string;
+  /** Task ID when the focused entity is a task. */
+  taskId?: string;
+}
+
+/**
+ * One member Epic of a Saga, with a rollup status.
+ *
+ * Populated only when `focus.show` is called on a Saga ID.
+ *
+ * @task T9973
+ */
+export interface FocusSagaMember {
+  /** Epic task identifier. */
+  epicId: string;
+  /** Rollup status for the Epic (e.g. `'active'`, `'done'`). */
+  status: string;
+  /** Epic title. */
+  title: string;
+}
+
+/**
+ * One task blocking the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusBlocker {
+  /** ID of the task that is blocking. */
+  id: string;
+  /** Title of the blocking task. */
+  title: string;
+  /** Human-readable reason the dependency is unresolved. */
+  reason: string;
+}
+
+/**
+ * One ready task from the next parallel-safe wave of the parent Epic.
+ *
+ * @task T9973
+ */
+export interface FocusReadyTask {
+  /** Task identifier. */
+  id: string;
+  /** Task title. */
+  title: string;
+  /** Engine-rolled priority. */
+  priority: string;
+  /** Dependency IDs (already satisfied for ready tasks). */
+  depends: string[];
+}
+
+/**
+ * One doc attachment linked to the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusAttachedDoc {
+  /** Attachment identifier (att_* or UUID). */
+  attachmentId: string;
+  /** Human-friendly slug, when assigned. */
+  slug?: string;
+  /** Taxonomy classification, when assigned. */
+  type?: string;
+  /** Storage kind (e.g. `'local-file'`, `'url'`, `'blob'`). */
+  kind: string;
+}
+
+/**
+ * One recent git commit mentioning the focused task ID.
+ *
+ * @task T9973
+ */
+export interface FocusRecentCommit {
+  /** Full 40-character commit SHA. */
+  commitSha: string;
+  /** Commit subject line (first line of the commit message). */
+  message: string;
+  /** ISO 8601 author date. */
+  date: string;
+}
+
+/**
+ * Brain context scoped to the focused entity (≤ 3 entries per category).
+ *
+ * @task T9973
+ */
+export interface FocusBrainContext {
+  /** Recent observations relevant to the focused entity. */
+  observations: MemoryCompactHit[];
+  /** Learnings relevant to the focused entity. */
+  learnings: MemoryCompactHit[];
+  /** Decisions relevant to the focused entity. */
+  decisions: MemoryCompactHit[];
+}
+
+// ---------------------------------------------------------------------------
+// Result
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of `focus.show` — the single-envelope task orientation response.
+ *
+ * All fields except `identity` and `scope` are omitted when the
+ * underlying data source returns nothing (empty arrays, unavailable stores,
+ * git not in repo). Consumers MUST handle optional fields gracefully.
+ *
+ * Token budget: ≤ 1 500 tokens for typical task orientation.
+ *
+ * @task T9973
+ * @epic T9964
+ */
+export interface FocusShowResult {
+  /** Core identity of the focused entity. */
+  identity: FocusIdentity;
+  /** Scope hierarchy (saga → epic → task) derived from ancestry. */
+  scope: FocusScope;
+  /**
+   * Saga member Epics with rollup statuses.
+   * Populated only when `id` resolves to a Saga (`label='saga'`).
+   */
+  members?: FocusSagaMember[];
+  /**
+   * Tasks that are blocking the focused entity.
+   * Empty array when the entity is not blocked.
+   */
+  blockers: FocusBlocker[];
+  /**
+   * Next parallel-safe wave of tasks from the parent Epic.
+   * Omitted when the entity has no parent Epic or the ready-set is empty.
+   */
+  readyWave?: FocusReadyTask[];
+  /**
+   * Docs attached to the focused task/epic.
+   * Omitted when the docs store is unavailable or no attachments exist.
+   */
+  attachedDocs?: FocusAttachedDoc[];
+  /**
+   * Up to 5 most-recent git commits mentioning the focused task ID.
+   * Omitted when git is unavailable or no matching commits are found.
+   */
+  recentActivity?: FocusRecentCommit[];
+  /**
+   * Scope-filtered brain context — up to 3 entries per category.
+   * Omitted when the BRAIN store is unavailable.
+   */
+  brainContext?: FocusBrainContext;
+  /** Estimated token weight of this envelope. */
+  tokensEstimated: number;
+}
+
+// ---------------------------------------------------------------------------
+// Typed op record
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed operation record for the focus domain.
+ *
+ * Maps each operation name to its `[Params, Result]` tuple for compile-time
+ * narrowing in the dispatch layer.
+ *
+ * @task T9973
+ */
+export type FocusOps = {
+  readonly show: readonly [FocusShowParams, FocusShowResult];
+};

package/src/operations/index.ts

@@ -10,6 +10,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './dialectic.js';
 export * from './docs.js';
+export * from './focus.js';
 export * from './intelligence.js';
 export * from './issues.js';
 export * from './lifecycle.js';

package/src/operations/session.ts

@@ -65,6 +65,11 @@ export interface SessionListParams {
   status?: string;
   limit?: number;
   offset?: number;
+  /**
+   * When true, surface all columns including per-agent fields added in T9975
+   * (agentHandle, scopeKind, scopeId, lastActivity).
+   */
+  all?: boolean;
 }
 /** Result of `session.list`. */
 export interface SessionListResult {
@@ -295,6 +300,27 @@ export interface SessionBriefingShowParams {
   scope?: string;
   /** When true, exit non-zero if any contract violation is detected (T1905). */
   strict?: boolean;
+  /**
+   * Explicit session ID to scope the briefing to (T9975).
+   *
+   * When provided, the briefing resolution uses this session ID instead of
+   * inferring from env vars or most-recent active session. Internal use only.
+   */
+  activeSessionId?: string;
+  /**
+   * When true, include `peerPatterns` in the warm bundle and other verbose
+   * debug fields that are suppressed by default to reduce token count.
+   *
+   * @task T9974
+   */
+  debug?: boolean;
+  /**
+   * When true, include `cold.userProfile` traits in the bundle.
+   * Suppressed by default (large trait dump rarely needed at session start).
+   *
+   * @task T9974
+   */
+  withProfile?: boolean;
 }
 
 /** Compact task entry in a session briefing's next-tasks list. */
@@ -504,6 +530,34 @@ export interface SessionStartParams {
    * and validated on every `CLEO_OWNER_OVERRIDE` call.
    */
   ownerAuthToken?: string;
+  /**
+   * Human-readable agent handle for multi-agent isolation (T9975).
+   *
+   * When provided, the conflict check is scoped per-agent-handle: multiple
+   * sessions with different handles may be active simultaneously, enabling
+   * N-agent parallel execution without briefing surface collisions.
+   *
+   * Stored in `sessions.agent_handle`. Surfaced in `cleo session list --all`.
+   *
+   * @example "agent-A", "worker-T9975", "ct-task-executor"
+   */
+  agentHandle?: string;
+}
+
+// session.adopt
+/** Parameters for `session.adopt`. */
+export interface SessionAdoptParams {
+  /** Session ID to rebind the current env to. */
+  sessionId: string;
+}
+/** Result of `session.adopt`. */
+export interface SessionAdoptResult {
+  /** The session being adopted. */
+  sessionId: string;
+  /** Shell export command to rebind env — print and eval in the calling shell. */
+  exportCommand: string;
+  /** Name of the env variable set. */
+  envVar: 'CLEO_SESSION_ID';
 }
 // session.end
 /** Parameters for `session.end`. */
@@ -690,4 +744,6 @@ export type SessionOps = {
     SessionRecordAssumptionResult,
   ];
   readonly lint: readonly [SessionLintParams, SessionLintResult];
+  /** Rebind env to a specific session (T9975). */
+  readonly adopt: readonly [SessionAdoptParams, SessionAdoptResult];
 };

package/src/operations/tasks.ts

@@ -35,6 +35,7 @@ import type {
   TaskTreeNode,
   TaskView,
 } from '../tasks.js';
+import type { DocsType } from './docs.js';
 
 export type { TaskPriority, TaskStatus };
 
@@ -146,17 +147,56 @@ export interface TasksShowParams {
   /** When true, include IVTR phase history. */
   ivtrHistory?: boolean;
 }
+
+/**
+ * Minimal attachment entry surfaced in the `tasks.show` envelope.
+ *
+ * A lightweight projection of a docs attachment — enough to identify and
+ * navigate to the full attachment via `cleo docs fetch <slug|id>`, without
+ * the full byte payload.
+ *
+ * Fields are a subset of {@link import('./docs.js').DocsAttachmentRow}:
+ *   - `attachmentId` — store ID (att_* or UUID)
+ *   - `slug`         — human-friendly name (present when set on `cleo docs add`)
+ *   - `type`         — taxonomy classification (e.g. 'adr', 'research')
+ *   - `kind`         — storage kind ('local-file', 'url', 'blob', etc.)
+ *
+ * @task T9966
+ * @epic T9964
+ */
+export interface TaskShowAttachmentEntry {
+  /** Attachment identifier (att_* or UUID). */
+  attachmentId: string;
+  /** Human-friendly slug, unique per project. Present when assigned at add time. */
+  slug?: string;
+  /** Taxonomy classification. Present when assigned at add time. */
+  type?: DocsType;
+  /** Storage kind — discriminant for the full attachment variant. */
+  kind: string;
+}
+
 /**
  * Result of `tasks.show` — the full task record plus its canonical view
  * projection. `view` is null when the task has no lifecycle pipeline.
  *
  * @task T1703
+ * @task T9966 — attachments[] always present (empty array when none)
  */
 export interface TasksShowResult {
   /** Full task record (string-widened for dispatch layer serialization). */
   task: TaskRecord;
   /** Canonical task view projection produced by `computeTaskView`. Null when unavailable. */
   view: TaskView | null;
+  /**
+   * Attachments linked to this task via the docs store.
+   *
+   * Always an array — empty (`[]`) when no attachments exist. Never `null`.
+   * Each entry carries enough context to navigate to the full attachment
+   * via `cleo docs fetch <slug|attachmentId>`.
+   *
+   * @task T9966
+   */
+  attachments: TaskShowAttachmentEntry[];
 }
 
 // tasks.tree dispatch params (with optional withBlockers flag — dispatch alias)