@cleocode/core 2026.3.70 → 2026.3.72

package/dist/sessions/snapshot.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Session snapshot serialization and restoration.
+ *
+ * Provides `serializeSession()` and `restoreSession()` for full session
+ * state capture and hydration. Designed for CleoOS agent session persistence:
+ * when an agent dies, CleoOS serializes the session snapshot, and when a new
+ * agent connects, it restores the snapshot to resume seamlessly.
+ *
+ * The snapshot captures everything needed to resume work:
+ * - Full session object (scope, taskWork, notes, stats)
+ * - Handoff data (completed tasks, decisions, next suggested)
+ * - Brain context (recent observations linked to this session)
+ * - Active task state (current focus, blockers)
+ *
+ * @module sessions/snapshot
+ */
+import type { Session } from '@cleocode/contracts';
+import type { DataAccessor } from '../store/data-accessor.js';
+import { type HandoffData } from './handoff.js';
+/** Version of the snapshot schema. Increment on breaking changes. */
+export declare const SNAPSHOT_VERSION = 1;
+/** A decision recorded during the session. */
+export interface SnapshotDecision {
+    /** Decision text. */
+    decision: string;
+    /** Rationale for the decision. */
+    rationale: string;
+    /** Task ID context. */
+    taskId: string;
+    /** When the decision was recorded. */
+    recordedAt: string;
+}
+/** Brain observation linked to this session. */
+export interface SnapshotObservation {
+    /** Observation ID. */
+    id: string;
+    /** Observation text. */
+    text: string;
+    /** Observation type (discovery, change, feature, etc.). */
+    type: string;
+    /** When the observation was created. */
+    createdAt: string;
+}
+/** Active task context at snapshot time. */
+export interface SnapshotTaskContext {
+    /** Task ID currently in focus. */
+    taskId: string;
+    /** Task title. */
+    title: string;
+    /** Task status. */
+    status: string;
+    /** Task priority. */
+    priority: string;
+    /** Task description (truncated to save space). */
+    description: string;
+    /** Acceptance criteria if any. */
+    acceptance?: string;
+}
+/**
+ * Complete session snapshot — everything needed to resume.
+ *
+ * This is the serialization format. It is JSON-safe and can be stored
+ * in a file, database column, or transmitted over the network.
+ */
+export interface SessionSnapshot {
+    /** Schema version for forward compatibility. */
+    version: number;
+    /** When the snapshot was created. */
+    capturedAt: string;
+    /** The full session object. */
+    session: Session;
+    /** Computed handoff data. */
+    handoff: HandoffData;
+    /** Decisions recorded in this session. */
+    decisions: SnapshotDecision[];
+    /** Recent brain observations linked to this session. */
+    observations: SnapshotObservation[];
+    /** Current task context (if a task is focused). */
+    activeTask: SnapshotTaskContext | null;
+    /** Session duration in minutes at snapshot time. */
+    durationMinutes: number;
+}
+/** Options for serializing a session. */
+export interface SerializeOptions {
+    /** Session ID to serialize. If omitted, uses the active session. */
+    sessionId?: string;
+    /** Maximum number of brain observations to include. Default: 10. */
+    maxObservations?: number;
+    /** Maximum description length for active task. Default: 500. */
+    maxDescriptionLength?: number;
+}
+/** Options for restoring a session. */
+export interface RestoreOptions {
+    /** Agent identifier for the new agent taking over. */
+    agent?: string;
+    /** Whether to resume the session (set status to active). Default: true. */
+    activate?: boolean;
+}
+/**
+ * Serialize a session into a complete snapshot.
+ *
+ * Captures the full session state including handoff data, decisions,
+ * brain observations, and active task context. The result is a
+ * JSON-serializable object that can be stored and later restored.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Serialization options
+ * @returns Complete session snapshot
+ */
+export declare function serializeSession(projectRoot: string, options?: SerializeOptions, accessor?: DataAccessor): Promise<SessionSnapshot>;
+/**
+ * Restore a session from a snapshot.
+ *
+ * Hydrates a session from a previously serialized snapshot. The session
+ * is re-inserted into the sessions store and optionally activated.
+ * Brain observations from the snapshot are NOT re-inserted (they already
+ * exist in brain.db) — only the session state is restored.
+ *
+ * @param projectRoot - Project root directory
+ * @param snapshot - The snapshot to restore from
+ * @param options - Restoration options
+ * @returns The restored session
+ */
+export declare function restoreSession(projectRoot: string, snapshot: SessionSnapshot, options?: RestoreOptions, accessor?: DataAccessor): Promise<Session>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/sessions/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/sessions/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAMhE,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,0CAA0C;IAC1C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,wDAAwD;IACxD,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,mDAAmD;IACnD,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,gBAAqB,EAC9B,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,eAAe,CAAC,CAoG1B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,OAAO,CAAC,CAkFlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.70",
+  "version": "2026.3.72",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,10 +37,10 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.3.70",
-    "@cleocode/agents": "2026.3.70",
-    "@cleocode/contracts": "2026.3.70",
-    "@cleocode/skills": "2026.3.70"
+    "@cleocode/adapters": "2026.3.72",
+    "@cleocode/agents": "2026.3.72",
+    "@cleocode/contracts": "2026.3.72",
+    "@cleocode/skills": "2026.3.72"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/cleo.ts

@@ -16,26 +16,26 @@
 
 import path from 'node:path';
 import type {
+  AdminAPI,
+  AgentsAPI,
+  CleoInitOptions,
   DataAccessor,
-  ExternalTask,
-  ExternalTaskLink,
-  ReconcileOptions,
-  ReconcileResult,
-  Task,
-  TaskPriority,
-  TaskSize,
-  TaskStatus,
-  TaskType,
+  IntelligenceAPI,
+  LifecycleAPI,
+  MemoryAPI,
+  NexusAPI,
+  OrchestrationAPI,
+  ReleaseAPI,
+  SessionsAPI,
+  StickyAPI,
+  SyncAPI,
+  TasksAPI,
 } from '@cleocode/contracts';
 // Admin
 import { exportTasks } from './admin/export.js';
-import type { ImportParams } from './admin/import.js';
 import { importTasks } from './admin/import.js';
 // Agents
 import {
-  type AgentCapacity,
-  type AgentHealthStatus,
-  type AgentInstanceRow,
   checkAgentHealth,
   deregisterAgent,
   detectCrashedAgents,
@@ -43,16 +43,10 @@ import {
   heartbeat,
   isOverloaded,
   listAgentInstances,
-  type RegisterAgentOptions,
   registerAgent,
 } from './agents/index.js';
 // Intelligence
-import {
-  type BlastRadius,
-  calculateBlastRadius,
-  type ImpactReport,
-  predictImpact,
-} from './intelligence/index.js';
+import { calculateBlastRadius, predictImpact } from './intelligence/index.js';
 // Lifecycle
 import {
   checkGate,
@@ -66,7 +60,6 @@ import {
   skipStage,
   startStage,
 } from './lifecycle/index.js';
-import type { BrainObservationType } from './memory/brain-retrieval.js';
 // Memory
 import {
   fetchBrainEntries,
@@ -74,7 +67,6 @@ import {
   searchBrainCompact,
   timelineBrain,
 } from './memory/brain-retrieval.js';
-import type { HybridSearchOptions } from './memory/brain-search.js';
 import { hybridSearch, searchBrain } from './memory/brain-search.js';
 // Nexus
 import { discoverRelated, searchAcrossProjects } from './nexus/discover.js';
@@ -137,6 +129,8 @@ import {
   startSession,
   suspendSession,
 } from './sessions/index.js';
+// Session snapshots (Phase 3: persistence)
+import { restoreSession, serializeSession } from './sessions/snapshot.js';
 // Sticky
 import {
   addSticky,
@@ -162,237 +156,24 @@ import { showTask } from './tasks/show.js';
 import { updateTask } from './tasks/update.js';
 
 // ============================================================================
-// Domain API interfaces
-// ============================================================================
-
-export interface TasksAPI {
-  add(params: {
-    title: string;
-    description: string;
-    parent?: string;
-    priority?: TaskPriority;
-    type?: TaskType;
-    size?: TaskSize;
-    phase?: string;
-    labels?: string[];
-    depends?: string[];
-    notes?: string;
-  }): Promise<unknown>;
-  find(params: {
-    query?: string;
-    id?: string;
-    status?: TaskStatus;
-    limit?: number;
-  }): Promise<unknown>;
-  show(taskId: string): Promise<unknown>;
-  list(params?: {
-    status?: TaskStatus;
-    priority?: TaskPriority;
-    parentId?: string;
-    phase?: string;
-    limit?: number;
-  }): Promise<unknown>;
-  update(params: {
-    taskId: string;
-    title?: string;
-    status?: TaskStatus;
-    priority?: TaskPriority;
-    description?: string;
-    notes?: string;
-  }): Promise<unknown>;
-  complete(params: { taskId: string; notes?: string }): Promise<unknown>;
-  delete(params: { taskId: string; force?: boolean }): Promise<unknown>;
-  archive(params?: { before?: string; taskIds?: string[]; dryRun?: boolean }): Promise<unknown>;
-  /** Start working on a specific task (sets focus). */
-  start(taskId: string): Promise<unknown>;
-  /** Stop working on the current task (clears focus). */
-  stop(): Promise<{ previousTask: string | null }>;
-  /** Get the current task work state. */
-  current(): Promise<unknown>;
-}
-
-export interface SessionsAPI {
-  start(params: {
-    name: string;
-    scope: string;
-    agent?: string;
-    startTask?: string;
-  }): Promise<unknown>;
-  end(params?: { note?: string }): Promise<unknown>;
-  status(): Promise<unknown>;
-  resume(sessionId: string): Promise<unknown>;
-  list(params?: { status?: string; limit?: number }): Promise<unknown>;
-  find(params?: {
-    status?: string;
-    scope?: string;
-    query?: string;
-    limit?: number;
-  }): Promise<unknown>;
-  show(sessionId: string): Promise<unknown>;
-  suspend(sessionId: string, reason?: string): Promise<unknown>;
-  briefing(params?: { maxNextTasks?: number; scope?: string }): Promise<unknown>;
-  handoff(sessionId: string, options?: { note?: string; nextAction?: string }): Promise<unknown>;
-  gc(maxAgeHours?: number): Promise<unknown>;
-  recordDecision(params: {
-    sessionId: string;
-    taskId: string;
-    decision: string;
-    rationale: string;
-    alternatives?: string[];
-  }): Promise<unknown>;
-  recordAssumption(params: {
-    assumption: string;
-    confidence: 'high' | 'medium' | 'low';
-    sessionId?: string;
-    taskId?: string;
-  }): Promise<unknown>;
-  contextDrift(params?: { sessionId?: string }): Promise<unknown>;
-  decisionLog(params?: { sessionId?: string; taskId?: string }): Promise<unknown>;
-  lastHandoff(scope?: { type: string; epicId?: string }): Promise<unknown>;
-}
-
-export interface MemoryAPI {
-  observe(params: { text: string; title?: string; type?: BrainObservationType }): Promise<unknown>;
-  find(params: {
-    query: string;
-    limit?: number;
-    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
-  }): Promise<unknown>;
-  fetch(params: { ids: string[] }): Promise<unknown>;
-  timeline(params: { anchor: string; depthBefore?: number; depthAfter?: number }): Promise<unknown>;
-  search(query: string, options?: { limit?: number }): Promise<unknown>;
-  hybridSearch(query: string, options?: HybridSearchOptions): Promise<unknown>;
-}
-
-export interface OrchestrationAPI {
-  start(epicId: string): Promise<unknown>;
-  analyze(epicId: string): Promise<unknown>;
-  readyTasks(epicId: string): Promise<unknown>;
-  nextTask(epicId: string): Promise<unknown>;
-  context(epicId: string): Promise<unknown>;
-  dependencyGraph(tasks: Task[]): unknown;
-  epicStatus(epicId: string, title: string, children: Task[]): unknown;
-  progress(tasks: Task[]): unknown;
-}
-
-export interface LifecycleAPI {
-  status(epicId: string): Promise<unknown>;
-  startStage(epicId: string, stage: string): Promise<unknown>;
-  completeStage(epicId: string, stage: string, artifacts?: string[]): Promise<unknown>;
-  skipStage(epicId: string, stage: string, reason: string): Promise<unknown>;
-  checkGate(epicId: string, targetStage: string): Promise<unknown>;
-  history(epicId: string): Promise<unknown>;
-  resetStage(epicId: string, stage: string, reason: string): Promise<unknown>;
-  passGate(epicId: string, gateName: string, agent?: string): Promise<unknown>;
-  failGate(epicId: string, gateName: string, reason?: string): Promise<unknown>;
-  stages: readonly string[];
-}
-
-export interface ReleaseAPI {
-  prepare(params: { version: string; tasks?: string[]; notes?: string }): Promise<unknown>;
-  commit(params: { version: string }): Promise<unknown>;
-  tag(params: { version: string }): Promise<unknown>;
-  push(params: { version: string; remote?: string; explicitPush?: boolean }): Promise<unknown>;
-  rollback(params: { version: string; reason?: string }): Promise<unknown>;
-  calculateVersion(current: string, bumpType: string): string;
-  bumpVersion(): Promise<unknown>;
-}
-
-export interface AdminAPI {
-  export(params?: Record<string, unknown>): Promise<unknown>;
-  import(params: Omit<ImportParams, 'cwd'>): Promise<unknown>;
-}
-
-export interface StickyAPI {
-  add(params: {
-    content: string;
-    tags?: string[];
-    priority?: string;
-    color?: string;
-  }): Promise<unknown>;
-  show(stickyId: string): Promise<unknown>;
-  list(params?: {
-    status?: string;
-    color?: string;
-    priority?: string;
-    limit?: number;
-  }): Promise<unknown>;
-  archive(stickyId: string): Promise<unknown>;
-  purge(stickyId: string): Promise<unknown>;
-  convert(params: {
-    stickyId: string;
-    targetType: 'task' | 'memory' | 'task_note' | 'session_note';
-    title?: string;
-    memoryType?: string;
-    taskId?: string;
-  }): Promise<unknown>;
-}
-
-export interface NexusAPI {
-  init(): Promise<unknown>;
-  register(params: { path: string; name?: string; permissions?: string }): Promise<unknown>;
-  unregister(params: { name: string }): Promise<unknown>;
-  list(): Promise<unknown>;
-  show(params: { name: string }): Promise<unknown>;
-  sync(params?: { name?: string }): Promise<unknown>;
-  discover(params: { query: string; method?: string; limit?: number }): Promise<unknown>;
-  search(params: { pattern: string; project?: string; limit?: number }): Promise<unknown>;
-  setPermission(params: { name: string; level: 'read' | 'write' | 'execute' }): Promise<unknown>;
-  sharingStatus(): Promise<unknown>;
-}
-
-export interface SyncAPI {
-  /** Reconcile external tasks with CLEO as SSoT. */
-  reconcile(params: {
-    externalTasks: ExternalTask[];
-    providerId: string;
-    dryRun?: boolean;
-    conflictPolicy?: ReconcileOptions['conflictPolicy'];
-    defaultPhase?: string;
-    defaultLabels?: string[];
-  }): Promise<ReconcileResult>;
-  /** Get all external task links for a provider. */
-  getLinks(providerId: string): Promise<ExternalTaskLink[]>;
-  /** Get all external task links for a CLEO task. */
-  getTaskLinks(taskId: string): Promise<ExternalTaskLink[]>;
-  /** Remove all external task links for a provider. */
-  removeProviderLinks(providerId: string): Promise<number>;
-}
-
-export interface AgentsAPI {
-  /** Register a new agent instance. */
-  register(options: RegisterAgentOptions): Promise<AgentInstanceRow>;
-  /** Deregister an agent instance. */
-  deregister(agentId: string): Promise<AgentInstanceRow | null>;
-  /** Get health status for a specific agent. */
-  health(agentId: string): Promise<AgentHealthStatus | null>;
-  /** Detect agents that have crashed (missed heartbeats). */
-  detectCrashed(thresholdMs?: number): Promise<AgentInstanceRow[]>;
-  /** Record a heartbeat for an agent. */
-  recordHeartbeat(agentId: string): Promise<unknown>;
-  /** Get capacity info for an agent. */
-  capacity(agentId: string): Promise<AgentCapacity | null>;
-  /** Check if system is overloaded (available capacity below threshold). */
-  isOverloaded(threshold?: number): Promise<boolean>;
-  /** List all agent instances with optional filters. */
-  list(params?: { status?: string; agentType?: string }): Promise<AgentInstanceRow[]>;
-}
-
-export interface IntelligenceAPI {
-  /** Predict impact of a change description on related tasks. */
-  predictImpact(change: string): Promise<ImpactReport>;
-  /** Calculate blast radius for a task change. */
-  blastRadius(taskId: string): Promise<BlastRadius>;
-}
-
-// ============================================================================
-// Init options
+// Domain API interfaces — re-exported from @cleocode/contracts/facade
 // ============================================================================
 
-export interface CleoInitOptions {
-  store?: DataAccessor;
-  caamp?: boolean;
-}
+export type {
+  AdminAPI,
+  AgentsAPI,
+  CleoInitOptions,
+  IntelligenceAPI,
+  LifecycleAPI,
+  MemoryAPI,
+  NexusAPI,
+  OrchestrationAPI,
+  ReleaseAPI,
+  SessionsAPI,
+  StickyAPI,
+  SyncAPI,
+  TasksAPI,
+} from '@cleocode/contracts';
 
 // ============================================================================
 // Cleo facade class
@@ -510,6 +291,16 @@ export class Cleo {
       contextDrift: (p) => getContextDrift(root, p),
       decisionLog: (p) => getDecisionLog(root, { sessionId: p?.sessionId, taskId: p?.taskId }),
       lastHandoff: (scope) => getLastHandoff(root, scope),
+      serialize: (p) =>
+        serializeSession(root, {
+          sessionId: p?.sessionId,
+          maxObservations: p?.maxObservations,
+        }),
+      restore: (snapshot, p) =>
+        restoreSession(root, snapshot as import('./sessions/snapshot.js').SessionSnapshot, {
+          agent: p?.agent,
+          activate: p?.activate,
+        }),
     };
   }
 

package/src/index.ts

@@ -299,6 +299,16 @@ export {
   sessionStatus,
   startSession,
 } from './sessions/index.js';
+export type {
+  RestoreOptions,
+  SerializeOptions,
+  SessionSnapshot,
+  SnapshotDecision,
+  SnapshotObservation,
+  SnapshotTaskContext,
+} from './sessions/snapshot.js';
+// Session snapshots (Phase 3: persistence)
+export { restoreSession, serializeSession } from './sessions/snapshot.js';
 export { getMigrationStatus as getSystemMigrationStatus } from './system/migrate.js';
 export { checkStorageMigration } from './system/storage-preflight.js';
 // Task work