@almadar/agent 2.0.4 → 3.1.0

package/dist/memory/index.d.ts

@@ -11,4 +11,5 @@ export { AgenticSearchEngine, createAgenticSearchEngine, type SearchStrategy, ty
 export { ObservabilityCollector, getObservabilityCollector, resetObservabilityCollector, recordEvent, startObservabilitySession, endObservabilitySession, getPerformanceSnapshot, type ObservableEventType, type ObservableEvent, type SessionTelemetry, type PerformanceSnapshot, type HealthCheckResult, } from '../observability.js';
 export { MultiUserManager, getMultiUserManager, resetMultiUserManager, createUserContext, isAdmin, requireOwnership, type UserContext, type ScopedSessionMetadata, type AccessCheckResult, type UserSessionStats, } from '../multi-user.js';
 export { StateSyncManager, getStateSyncManager, resetStateSyncManager, withSync, debounceSync, type StateChangeType, type StateChangeEvent, type VersionVector, type StateSyncSnapshot, type ConflictResolution, type StateSyncConfig, } from '../state-sync.js';
+export { LocalMemoryBackend, type LocalMemoryBackendOptions, type ErrorResolution, } from './local-memory-backend.js';
 export type { UserFeedback, PatternAffinity, InterruptRecord, ToolApprovalPreference, CheckpointRecord, } from './types.js';

package/dist/memory/local-memory-backend.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Local File-System Memory Backend
+ *
+ * Implements MemoryManager's storage interface backed by `.orb` files
+ * instead of Firestore collections.
+ *
+ * Per the minimal memory strategy, only error resolution files are active
+ * at launch. Other memory types are stubbed (accept writes, return empty
+ * on reads) until evaluation proves their value.
+ *
+ * Storage layout:
+ *   ~/.almadar/memory/
+ *   ├── memory.orb        (schema definition)
+ *   ├── errors.orb        (error resolution instances - ACTIVE)
+ *   ├── preferences.orb   (stubbed until eval)
+ *   ├── sessions.orb      (stubbed until eval)
+ *   ├── projects.orb      (stubbed until eval)
+ *   ├── patterns.orb      (stubbed until eval)
+ *   └── index.orb         (stubbed until eval)
+ */
+import type { UserPreference, GenerationSession, ProjectContext } from './memory-orbital.js';
+import type { PatternAffinity, InterruptRecord, ToolApprovalPreference, CheckpointRecord, UserFeedback } from './types.js';
+export interface LocalMemoryBackendOptions {
+    memoryDir?: string;
+}
+/**
+ * Error resolution record stored in errors.orb.
+ */
+export interface ErrorResolution {
+    id: string;
+    errorSignature: string;
+    errorMessage: string;
+    resolution: string;
+    context: string;
+    createdAt: number;
+    usageCount: number;
+}
+export declare class LocalMemoryBackend {
+    private readonly memoryDir;
+    constructor(options?: LocalMemoryBackendOptions);
+    private filePath;
+    private readInstances;
+    private writeInstances;
+    recordErrorResolution(resolution: Omit<ErrorResolution, 'id' | 'createdAt' | 'usageCount'>): Promise<string>;
+    findErrorResolution(errorSignature: string): Promise<ErrorResolution | null>;
+    searchErrorResolutions(query: string): Promise<ErrorResolution[]>;
+    getAllErrorResolutions(): Promise<ErrorResolution[]>;
+    getUserPreferences(_userId: string): Promise<UserPreference | null>;
+    updateUserPreferences(_userId: string, _preferences: Partial<Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>>): Promise<void>;
+    recordGeneration(_userId: string, session: Omit<GenerationSession, 'id' | 'userId' | 'createdAt'>): Promise<string>;
+    getGenerationSession(sessionId: string): Promise<GenerationSession | null>;
+    getUserGenerationHistory(_userId: string, limit?: number): Promise<GenerationSession[]>;
+    getProjectContext(_appId: string): Promise<ProjectContext | null>;
+    updateProjectContext(_appId: string, _update: Partial<Omit<ProjectContext, 'id' | 'appId'>>): Promise<void>;
+    updatePatternAffinity(_userId: string, _patternId: string, _outcome: 'success' | 'failure' | 'partial', _context?: {
+        entityType?: string;
+        useCase?: string;
+    }): Promise<void>;
+    getPatternAffinity(_userId: string, _patternId: string): Promise<PatternAffinity | null>;
+    getUserPatterns(_userId: string): Promise<PatternAffinity[]>;
+    recordFeedback(_sessionId: string, _feedback: Omit<UserFeedback, 'feedbackId' | 'sessionId' | 'timestamp'>): Promise<void>;
+    recordInterruptDecision(_sessionId: string, _userId: string, _interruptData: {
+        toolName: string;
+        toolArgs: Record<string, unknown>;
+        decision: 'approved' | 'rejected' | 'modified';
+        modifiedArgs?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<void>;
+    getSessionInterrupts(_sessionId: string): Promise<InterruptRecord[]>;
+    getToolApprovalPreference(_userId: string, _toolName: string): Promise<ToolApprovalPreference | null>;
+    shouldAutoApproveTool(_userId: string, _toolName: string): Promise<boolean>;
+    recordCheckpoint(_userId: string, _checkpointData: {
+        checkpointId: string;
+        threadId: string;
+        parentCheckpointId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    getUserCheckpoints(_userId: string, _limit?: number): Promise<CheckpointRecord[]>;
+    getThreadCheckpoints(_threadId: string): Promise<CheckpointRecord[]>;
+}

package/dist/neural/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Neural Pipeline Module
+ *
+ * Schema generation via the Masar server. The neural pipeline (GFlowNet +
+ * LLM fix loop) now runs server-side in the Masar container. This module
+ * provides the HTTP client and shared types.
+ *
+ * @packageDocumentation
+ */
+export type { GoalSpec, NeuralGenerateResult, NeuralPipelineResult, NeuralPipelineOptions, CommandExecutor, PythonExecutor, InferOptions, InferResult, ValidationError, ValidationResult, CompileResult, } from './types.js';
+export { MasarClient } from './masar-client.js';
+export type { MasarClientOptions } from './masar-client.js';

package/dist/neural/index.js

@@ -0,0 +1,86 @@
+// src/neural/masar-client.ts
+var MasarClient = class {
+  constructor(options) {
+    this.baseUrl = (options?.baseUrl ?? process.env["MASAR_URL"] ?? "https://masar-345008351456.europe-west4.run.app").replace(/\/$/, "");
+    this.timeoutMs = options?.timeoutMs ?? 12e4;
+    this.onProgress = options?.onProgress ?? null;
+  }
+  /**
+   * Generate an .orb schema from a natural language prompt.
+   *
+   * Sends the prompt to the Masar server which runs the full neural pipeline
+   * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns
+   * the result.
+   */
+  async generate(prompt) {
+    this.onProgress?.("request", `Sending prompt to Masar at ${this.baseUrl}`);
+    const url = `${this.baseUrl}/generate`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ prompt }),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        return makeErrorResult(
+          `Masar server returned ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`
+        );
+      }
+      const data = await response.json();
+      this.onProgress?.("response", data.success ? "Generation succeeded" : `Generation failed: ${data.error ?? "unknown"}`);
+      return toNeuralPipelineResult(data);
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        return makeErrorResult(`Masar request timed out after ${this.timeoutMs}ms`);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return makeErrorResult(`Masar request failed: ${message}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+function toNeuralPipelineResult(data) {
+  return {
+    success: data.success,
+    validationPass: data.validation_pass,
+    compilationPass: false,
+    goalMatch: data.goal_match ?? 0,
+    totalSteps: data.total_steps ?? 0,
+    fixRounds: data.fix_rounds ?? 0,
+    llmCalls: data.llm_calls ?? 0,
+    durationMs: data.duration_ms ?? 0,
+    schema: data.schema ?? null,
+    schemaPath: null,
+    actions: data.actions ?? [],
+    validationErrors: data.validation_errors ?? [],
+    compilationErrors: [],
+    error: data.error ?? null
+  };
+}
+function makeErrorResult(error) {
+  return {
+    success: false,
+    validationPass: false,
+    compilationPass: false,
+    goalMatch: 0,
+    totalSteps: 0,
+    fixRounds: 0,
+    llmCalls: 0,
+    durationMs: 0,
+    schema: null,
+    schemaPath: null,
+    actions: [],
+    validationErrors: [],
+    compilationErrors: [],
+    error
+  };
+}
+
+export { MasarClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/neural/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/neural/masar-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Masar HTTP Client\n *\n * Calls the Masar server's /generate endpoint via HTTP instead of\n * orchestrating the neural pipeline (GFlowNet + LLM fix loop) directly.\n *\n * The Masar server runs the full pipeline server-side and returns\n * a NeuralPipelineResult-compatible response.\n */\n\nimport type { NeuralPipelineResult } from './types.js';\n\n/** Response shape returned by the Masar /generate endpoint (snake_case from Python). */\ninterface MasarGenerateResponse {\n  success: boolean;\n  schema: string | null;\n  validation_pass: boolean;\n  goal_match: number;\n  total_steps: number;\n  fix_rounds: number;\n  llm_calls: number;\n  duration_ms: number;\n  actions: string[];\n  validation_errors: string[];\n  error: string | null;\n}\n\n/** Options for constructing a MasarClient. */\nexport interface MasarClientOptions {\n  /** Base URL of the Masar server. Defaults to MASAR_URL env var or http://localhost:8080 */\n  baseUrl?: string;\n  /** Request timeout in milliseconds. Defaults to 120000 (2 minutes). */\n  timeoutMs?: number;\n  /** Optional callback for progress updates. */\n  onProgress?: (phase: string, detail: string) => void;\n}\n\n/**\n * HTTP client for the Masar schema generation server.\n *\n * Usage:\n * ```ts\n * const client = new MasarClient();\n * const result = await client.generate('Build a todo app with projects and tasks');\n * ```\n */\nexport class MasarClient {\n  private readonly baseUrl: string;\n  private readonly timeoutMs: number;\n  private readonly onProgress: ((phase: string, detail: string) => void) | null;\n\n  constructor(options?: MasarClientOptions) {\n    this.baseUrl = (options?.baseUrl ?? process.env['MASAR_URL'] ?? 'https://masar-345008351456.europe-west4.run.app').replace(/\\/$/, '');\n    this.timeoutMs = options?.timeoutMs ?? 120_000;\n    this.onProgress = options?.onProgress ?? null;\n  }\n\n  /**\n   * Generate an .orb schema from a natural language prompt.\n   *\n   * Sends the prompt to the Masar server which runs the full neural pipeline\n   * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns\n   * the result.\n   */\n  async generate(prompt: string): Promise<NeuralPipelineResult> {\n    this.onProgress?.('request', `Sending prompt to Masar at ${this.baseUrl}`);\n\n    const url = `${this.baseUrl}/generate`;\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ prompt }),\n        signal: controller.signal,\n      });\n\n      if (!response.ok) {\n        const body = await response.text().catch(() => '');\n        return makeErrorResult(\n          `Masar server returned ${response.status} ${response.statusText}${body ? `: ${body}` : ''}`,\n        );\n      }\n\n      const data: MasarGenerateResponse = await response.json() as MasarGenerateResponse;\n      this.onProgress?.('response', data.success ? 'Generation succeeded' : `Generation failed: ${data.error ?? 'unknown'}`);\n\n      return toNeuralPipelineResult(data);\n    } catch (err: unknown) {\n      if (err instanceof DOMException && err.name === 'AbortError') {\n        return makeErrorResult(`Masar request timed out after ${this.timeoutMs}ms`);\n      }\n      const message = err instanceof Error ? err.message : String(err);\n      return makeErrorResult(`Masar request failed: ${message}`);\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n}\n\n/**\n * Map the Masar server response to a NeuralPipelineResult.\n * Provides defaults for any missing fields so the result always satisfies the full interface.\n */\nfunction toNeuralPipelineResult(data: MasarGenerateResponse): NeuralPipelineResult {\n  return {\n    success: data.success,\n    validationPass: data.validation_pass,\n    compilationPass: false,\n    goalMatch: data.goal_match ?? 0,\n    totalSteps: data.total_steps ?? 0,\n    fixRounds: data.fix_rounds ?? 0,\n    llmCalls: data.llm_calls ?? 0,\n    durationMs: data.duration_ms ?? 0,\n    schema: data.schema ?? null,\n    schemaPath: null,\n    actions: data.actions ?? [],\n    validationErrors: data.validation_errors ?? [],\n    compilationErrors: [],\n    error: data.error ?? null,\n  };\n}\n\nfunction makeErrorResult(error: string): NeuralPipelineResult {\n  return {\n    success: false,\n    validationPass: false,\n    compilationPass: false,\n    goalMatch: 0,\n    totalSteps: 0,\n    fixRounds: 0,\n    llmCalls: 0,\n    durationMs: 0,\n    schema: null,\n    schemaPath: null,\n    actions: [],\n    validationErrors: [],\n    compilationErrors: [],\n    error,\n  };\n}\n"]}

package/dist/neural/masar-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Masar HTTP Client
+ *
+ * Calls the Masar server's /generate endpoint via HTTP instead of
+ * orchestrating the neural pipeline (GFlowNet + LLM fix loop) directly.
+ *
+ * The Masar server runs the full pipeline server-side and returns
+ * a NeuralPipelineResult-compatible response.
+ */
+import type { NeuralPipelineResult } from './types.js';
+/** Options for constructing a MasarClient. */
+export interface MasarClientOptions {
+    /** Base URL of the Masar server. Defaults to MASAR_URL env var or http://localhost:8080 */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 120000 (2 minutes). */
+    timeoutMs?: number;
+    /** Optional callback for progress updates. */
+    onProgress?: (phase: string, detail: string) => void;
+}
+/**
+ * HTTP client for the Masar schema generation server.
+ *
+ * Usage:
+ * ```ts
+ * const client = new MasarClient();
+ * const result = await client.generate('Build a todo app with projects and tasks');
+ * ```
+ */
+export declare class MasarClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly onProgress;
+    constructor(options?: MasarClientOptions);
+    /**
+     * Generate an .orb schema from a natural language prompt.
+     *
+     * Sends the prompt to the Masar server which runs the full neural pipeline
+     * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns
+     * the result.
+     */
+    generate(prompt: string): Promise<NeuralPipelineResult>;
+}

package/dist/neural/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Neural Pipeline Types
+ *
+ * Shared types for the GFlowNet-based schema generation pipeline.
+ */
+/**
+ * Structural goal vector extracted from a natural language prompt.
+ * Used by the GFlowNet to generate schema skeletons.
+ */
+export interface GoalSpec {
+    entities: number;
+    fields: number;
+    traits: number;
+    states: number;
+    transitions: number;
+    pages: number;
+    events: number;
+    effects: number;
+    entityNames: string[];
+    fieldNames: string[];
+    projectName: string;
+}
+export interface NeuralGenerateResult {
+    success: boolean;
+    schema?: Record<string, unknown>;
+    actions?: string[];
+    steps?: number;
+    goalMatch?: number;
+    error?: string;
+}
+export interface NeuralPipelineResult {
+    success: boolean;
+    validationPass: boolean;
+    compilationPass: boolean;
+    goalMatch: number;
+    totalSteps: number;
+    fixRounds: number;
+    llmCalls: number;
+    durationMs: number;
+    /** Generated .orb schema JSON string (returned by Masar server). */
+    schema: string | null;
+    /** @deprecated Use `schema` instead. Legacy field for file-based pipeline. */
+    schemaPath: string | null;
+    actions: string[];
+    validationErrors: string[];
+    compilationErrors: string[];
+    error: string | null;
+}
+export interface NeuralPipelineOptions {
+    provider: string;
+    model: string;
+    /** Working directory for writing schemas */
+    workDir: string;
+    maxFixRounds?: number;
+    samples?: number;
+    temperature?: number;
+    onProgress?: (phase: string, detail: string) => void;
+}
+/**
+ * Abstraction for running shell commands.
+ * Server uses temp files, CLI uses real paths, tests use mocks.
+ */
+export interface CommandExecutor {
+    /**
+     * Run `orbital validate` on a schema string or file path.
+     */
+    validateSchema(schema: string): Promise<ValidationResult>;
+    /**
+     * Run `orbital compile` on a schema file.
+     */
+    compileSchema?(schemaPath: string): Promise<CompileResult>;
+}
+/**
+ * Abstraction for running GFlowNet inference (Python subprocess).
+ */
+export interface PythonExecutor {
+    /**
+     * Run GFlowNet inference on a goal spec.
+     */
+    infer(goal: GoalSpec, options: InferOptions): Promise<InferResult>;
+}
+export interface InferOptions {
+    samples?: number;
+    temperature?: number;
+    bestOf?: boolean;
+}
+export interface InferResult {
+    samples: Array<{
+        schema: Record<string, unknown>;
+        actions: string[];
+        steps: number;
+        goal_match: number;
+        sample_idx: number;
+    }>;
+    goal: GoalSpec;
+    temperature: number;
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface ValidationResult {
+    success: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+export interface CompileResult {
+    success: boolean;
+    errors: string[];
+}

package/dist/persistence/index.d.ts

@@ -5,6 +5,7 @@
  */
 export type { SessionMetadata, SessionRecord, PersistenceMode, Session, } from './types.js';
 export { MemorySessionBackend } from './memory-backend.js';
+export { LocalSessionBackend, type LocalSessionBackendOptions, } from './local-session-backend.js';
 export { FirestoreCheckpointer, type FirestoreCheckpointerOptions, type FirestoreDb, type FirestoreTimestamp, } from './firestore-checkpointer.js';
 export { FirestoreSessionStore, type FirestoreSessionStoreOptions, } from './firestore-session-store.js';
 export { FirestoreStore, type FirestoreStoreOptions, } from './firestore-store.js';

package/dist/persistence/index.js

@@ -1,3 +1,6 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
 import { BaseCheckpointSaver, BaseStore } from '@langchain/langgraph-checkpoint';
 
 // src/persistence/memory-backend.ts
@@ -39,6 +42,194 @@ var MemorySessionBackend = class {
     return this.sessions.has(threadId);
   }
 };
+var DEFAULT_SESSIONS_DIR = path.join(os.homedir(), ".almadar", "sessions");
+var LocalSessionBackend = class {
+  constructor(options = {}) {
+    this.sessionsDir = options.sessionsDir ?? DEFAULT_SESSIONS_DIR;
+    fs.mkdirSync(this.sessionsDir, { recursive: true });
+  }
+  sessionDir(threadId) {
+    return path.join(this.sessionsDir, threadId);
+  }
+  sessionFilePath(threadId) {
+    return path.join(this.sessionDir(threadId), "session.orb");
+  }
+  checkpointFilePath(threadId) {
+    return path.join(this.sessionDir(threadId), "checkpoint.orb");
+  }
+  eventsFilePath(threadId) {
+    return path.join(this.sessionDir(threadId), "events.orb");
+  }
+  /**
+   * Store session metadata as an .orb file.
+   */
+  store(threadId, metadata) {
+    const dir = this.sessionDir(threadId);
+    fs.mkdirSync(dir, { recursive: true });
+    const schema = {
+      name: `session-${threadId}`,
+      version: "1.0.0",
+      orbitals: [
+        {
+          name: "SessionRecord",
+          entity: {
+            name: "Session",
+            fields: [
+              { name: "skill", type: "string" },
+              { name: "workDir", type: "string" },
+              { name: "createdAt", type: "number" },
+              { name: "lastActivityAt", type: "number" },
+              { name: "approveAll", type: "boolean" }
+            ]
+          },
+          instances: [
+            {
+              id: threadId,
+              skill: metadata.skill,
+              workDir: metadata.workDir,
+              createdAt: metadata.createdAt,
+              lastActivityAt: metadata.lastActivityAt,
+              approveAll: metadata.approveAll ?? false
+            }
+          ]
+        }
+      ]
+    };
+    fs.writeFileSync(this.sessionFilePath(threadId), JSON.stringify(schema, null, 2));
+  }
+  /**
+   * Get session metadata from .orb file.
+   */
+  get(threadId) {
+    const filePath = this.sessionFilePath(threadId);
+    if (!fs.existsSync(filePath)) return void 0;
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      const instance = raw?.orbitals?.[0]?.instances?.[0];
+      if (!instance) return void 0;
+      return {
+        skill: instance.skill,
+        workDir: instance.workDir,
+        createdAt: instance.createdAt,
+        lastActivityAt: instance.lastActivityAt,
+        approveAll: instance.approveAll
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Delete session directory.
+   */
+  delete(threadId) {
+    const dir = this.sessionDir(threadId);
+    if (!fs.existsSync(dir)) return false;
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  /**
+   * List all sessions.
+   */
+  list() {
+    if (!fs.existsSync(this.sessionsDir)) return [];
+    const entries = fs.readdirSync(this.sessionsDir, { withFileTypes: true });
+    const records = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const meta = this.get(entry.name);
+      if (meta) {
+        records.push({ threadId: entry.name, ...meta });
+      }
+    }
+    return records.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  }
+  /**
+   * Check if a session exists.
+   */
+  has(threadId) {
+    return fs.existsSync(this.sessionFilePath(threadId));
+  }
+  /**
+   * Store a checkpoint blob for the session.
+   */
+  storeCheckpoint(threadId, checkpoint) {
+    const dir = this.sessionDir(threadId);
+    fs.mkdirSync(dir, { recursive: true });
+    const schema = {
+      name: `checkpoint-${threadId}`,
+      version: "1.0.0",
+      orbitals: [
+        {
+          name: "Checkpoint",
+          entity: {
+            name: "CheckpointData",
+            fields: [{ name: "data", type: "json" }]
+          },
+          instances: [{ id: "latest", data: checkpoint }]
+        }
+      ]
+    };
+    fs.writeFileSync(this.checkpointFilePath(threadId), JSON.stringify(schema, null, 2));
+  }
+  /**
+   * Load the latest checkpoint for a session.
+   */
+  loadCheckpoint(threadId) {
+    const filePath = this.checkpointFilePath(threadId);
+    if (!fs.existsSync(filePath)) return void 0;
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      return raw?.orbitals?.[0]?.instances?.[0]?.data;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Append events to the session's event stream.
+   */
+  appendEvents(threadId, events) {
+    const dir = this.sessionDir(threadId);
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = this.eventsFilePath(threadId);
+    let existing = [];
+    if (fs.existsSync(filePath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        existing = raw?.orbitals?.[0]?.instances ?? [];
+      } catch {
+      }
+    }
+    const merged = [...existing, ...events];
+    const schema = {
+      name: `events-${threadId}`,
+      version: "1.0.0",
+      orbitals: [
+        {
+          name: "EventStream",
+          entity: {
+            name: "Event",
+            fields: [{ name: "data", type: "json" }]
+          },
+          instances: merged
+        }
+      ]
+    };
+    fs.writeFileSync(filePath, JSON.stringify(schema, null, 2));
+  }
+  /**
+   * Read all events for a session.
+   */
+  readEvents(threadId) {
+    const filePath = this.eventsFilePath(threadId);
+    if (!fs.existsSync(filePath)) return [];
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      return raw?.orbitals?.[0]?.instances ?? [];
+    } catch {
+      return [];
+    }
+  }
+};
 var FirestoreCheckpointer = class extends BaseCheckpointSaver {
   constructor(options) {
     super();
@@ -462,9 +653,9 @@ var FirestoreStore = class extends BaseStore {
     let query = this.db.collection(this.collection);
     if (op.matchConditions) {
       for (const condition of op.matchConditions) {
-        const path = condition.path.filter((p) => p !== "*").join("/");
+        const path2 = condition.path.filter((p) => p !== "*").join("/");
         if (condition.matchType === "prefix") {
-          query = query.where("namespaceKey", ">=", path).where("namespaceKey", "<", path + "\uFFFF");
+          query = query.where("namespaceKey", ">=", path2).where("namespaceKey", "<", path2 + "\uFFFF");
         }
       }
     }
@@ -484,6 +675,6 @@ var FirestoreStore = class extends BaseStore {
   }
 };
 
-export { FirestoreCheckpointer, FirestoreSessionStore, FirestoreStore, MemorySessionBackend };
+export { FirestoreCheckpointer, FirestoreSessionStore, FirestoreStore, LocalSessionBackend, MemorySessionBackend };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map