@cleocode/core 2026.3.71 → 2026.3.73

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,CAsG1B;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.71",
+  "version": "2026.3.73",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     }
   },
   "dependencies": {
-    "@cleocode/caamp": "^1.8.1",
+    "@cleocode/caamp": "^1.9.1",
     "@cleocode/lafs-protocol": "^1.8.0",
     "@xenova/transformers": "^2.17.2",
     "ajv": "^8.18.0",
@@ -37,10 +37,10 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/agents": "2026.3.71",
-    "@cleocode/adapters": "2026.3.71",
-    "@cleocode/skills": "2026.3.71",
-    "@cleocode/contracts": "2026.3.71"
+    "@cleocode/adapters": "2026.3.73",
+    "@cleocode/agents": "2026.3.73",
+    "@cleocode/contracts": "2026.3.73",
+    "@cleocode/skills": "2026.3.73"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/cleo.ts

@@ -129,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,
@@ -289,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,
+        }),
     };
   }