@sna-sdk/core 0.6.1 → 0.7.1

package/README.md

@@ -84,13 +84,18 @@ const db = getDb(); // SQLite instance (data/sna.db)
 | `@sna-sdk/core/server/routes/agent` | `createAgentRoutes()`, `runOnce()` |
 | `@sna-sdk/core/db/schema` | `getDb()`, `ChatSession`, `ChatMessage`, `SkillEvent` types |
 | `@sna-sdk/core/providers` | Agent provider factory, `ClaudeCodeProvider` |
-| `@sna-sdk/core/lib/sna-run` | `snaRun()` helper for spawning Claude Code |
+| `@sna-sdk/core/lib/sna-run` | `sna` object with `sna.run()` — awaitable skill invocation |
 | `@sna-sdk/core/testing` | `startMockAnthropicServer()` for testing without real API calls |
+| `@sna-sdk/core/electron` | `startSnaServer()` — launch SNA server from Electron main process (asar-aware) |
+| `@sna-sdk/core/node` | `startSnaServer()` — launch SNA server from Node.js (Next.js, Express, etc.) |
 
 **Environment Variables:**
 - `SNA_DB_PATH` — Override SQLite database location (default: `process.cwd()/data/sna.db`)
 - `SNA_CLAUDE_COMMAND` — Override claude binary path
 - `SNA_PORT` — API server port (default: 3099)
+- `SNA_SQLITE_NATIVE_BINDING` — Absolute path to `better_sqlite3.node` native binary; bypasses `bindings` module resolution for Electron packaged apps
+- `SNA_MAX_SESSIONS` — Maximum concurrent agent sessions (default: 5)
+- `SNA_PERMISSION_MODE` — Default permission mode for spawned agents (`acceptEdits` | `bypassPermissions` | `default`)
 
 ## Documentation
 

package/dist/core/providers/claude-code.js

@@ -35,13 +35,20 @@ function resolveClaudePath(cwd) {
     return "claude";
   }
 }
-class ClaudeCodeProcess {
+const _ClaudeCodeProcess = class _ClaudeCodeProcess {
   constructor(proc, options) {
     this.emitter = new EventEmitter();
     this._alive = true;
     this._sessionId = null;
     this._initEmitted = false;
     this.buffer = "";
+    /**
+     * FIFO event queue — ALL events (deltas, assistant, complete, etc.) go through
+     * this queue. A fixed-interval timer drains one item at a time, guaranteeing
+     * strict ordering: deltas → assistant → complete, never out of order.
+     */
+    this.eventQueue = [];
+    this.drainTimer = null;
     this.proc = proc;
     proc.stdout.on("data", (chunk) => {
       this.buffer += chunk.toString();
@@ -56,7 +63,7 @@ class ClaudeCodeProcess {
             this._sessionId = msg.session_id;
           }
           const event = this.normalizeEvent(msg);
-          if (event) this.emitter.emit("event", event);
+          if (event) this.enqueue(event);
         } catch {
         }
       }
@@ -69,10 +76,11 @@ class ClaudeCodeProcess {
         try {
           const msg = JSON.parse(this.buffer);
           const event = this.normalizeEvent(msg);
-          if (event) this.emitter.emit("event", event);
+          if (event) this.enqueue(event);
         } catch {
         }
       }
+      this.flushQueue();
       this.emitter.emit("exit", code);
       logger.log("agent", `process exited (code=${code})`);
     });
@@ -88,35 +96,58 @@ class ClaudeCodeProcess {
       this.send(options.prompt);
     }
   }
+  // ~67 events/sec
   /**
-   * Split completed assistant text into chunks and emit assistant_delta events
-   * at a fixed rate (~270 chars/sec), followed by the final assistant event.
-   *
-   * CHUNK_SIZE chars every CHUNK_DELAY_MS → natural TPS feel regardless of length.
+   * Enqueue an event for ordered emission.
+   * Starts the drain timer if not already running.
    */
-  emitTextAsDeltas(text) {
+  enqueue(event) {
+    this.eventQueue.push(event);
+    if (!this.drainTimer) {
+      this.drainTimer = setInterval(() => this.drainOne(), _ClaudeCodeProcess.DRAIN_INTERVAL_MS);
+    }
+  }
+  /** Emit one event from the front of the queue. Stop timer when empty. */
+  drainOne() {
+    const event = this.eventQueue.shift();
+    if (event) {
+      this.emitter.emit("event", event);
+    }
+    if (this.eventQueue.length === 0 && this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+  }
+  /** Flush all remaining queued events immediately (used on process exit). */
+  flushQueue() {
+    if (this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+    while (this.eventQueue.length > 0) {
+      this.emitter.emit("event", this.eventQueue.shift());
+    }
+  }
+  /**
+   * Split completed assistant text into delta chunks and enqueue them,
+   * followed by the final assistant event. All go through the FIFO queue
+   * so subsequent events (complete, etc.) are guaranteed to come after.
+   */
+  enqueueTextAsDeltas(text) {
     const CHUNK_SIZE = 4;
-    const CHUNK_DELAY_MS = 15;
-    let t = 0;
     for (let i = 0; i < text.length; i += CHUNK_SIZE) {
-      const chunk = text.slice(i, i + CHUNK_SIZE);
-      setTimeout(() => {
-        this.emitter.emit("event", {
-          type: "assistant_delta",
-          delta: chunk,
-          index: 0,
-          timestamp: Date.now()
-        });
-      }, t);
-      t += CHUNK_DELAY_MS;
-    }
-    setTimeout(() => {
-      this.emitter.emit("event", {
-        type: "assistant",
-        message: text,
+      this.enqueue({
+        type: "assistant_delta",
+        delta: text.slice(i, i + CHUNK_SIZE),
+        index: 0,
         timestamp: Date.now()
       });
-    }, t);
+    }
+    this.enqueue({
+      type: "assistant",
+      message: text,
+      timestamp: Date.now()
+    });
   }
   get alive() {
     return this._alive;
@@ -217,10 +248,10 @@ class ClaudeCodeProcess {
         }
         if (events.length > 0 || textBlocks.length > 0) {
           for (const e of events) {
-            this.emitter.emit("event", e);
+            this.enqueue(e);
           }
           for (const text of textBlocks) {
-            this.emitTextAsDeltas(text);
+            this.enqueueTextAsDeltas(text);
           }
         }
         return null;
@@ -288,7 +319,9 @@ class ClaudeCodeProcess {
         return null;
     }
   }
-}
+};
+_ClaudeCodeProcess.DRAIN_INTERVAL_MS = 15;
+let ClaudeCodeProcess = _ClaudeCodeProcess;
 class ClaudeCodeProvider {
   constructor() {
     this.name = "claude-code";

package/dist/db/schema.js

@@ -5,6 +5,14 @@ const DB_PATH = process.env.SNA_DB_PATH ?? path.join(process.cwd(), "data/sna.db
 const NATIVE_DIR = path.join(process.cwd(), ".sna/native");
 let _db = null;
 function loadBetterSqlite3() {
+  const modulesPath = process.env.SNA_MODULES_PATH;
+  if (modulesPath) {
+    const entry = path.join(modulesPath, "better-sqlite3");
+    if (fs.existsSync(entry)) {
+      const req2 = createRequire(path.join(modulesPath, "noop.js"));
+      return req2("better-sqlite3");
+    }
+  }
   const nativeEntry = path.join(NATIVE_DIR, "node_modules", "better-sqlite3");
   if (fs.existsSync(nativeEntry)) {
     const req2 = createRequire(path.join(NATIVE_DIR, "noop.js"));

package/dist/electron/index.cjs

@@ -57,32 +57,6 @@ Ensure "@sna-sdk/core" is listed in asarUnpack in your electron-builder config.`
   }
   return script;
 }
-function resolveNativeBinding(override) {
-  if (override) {
-    if (!import_fs.default.existsSync(override)) {
-      console.warn(`[sna] SNA nativeBinding override not found: ${override}`);
-      return void 0;
-    }
-    return override;
-  }
-  const BINDING_REL = import_path.default.join("better-sqlite3", "build", "Release", "better_sqlite3.node");
-  const resourcesPath = process.resourcesPath;
-  if (resourcesPath) {
-    const unpackedBase = import_path.default.join(resourcesPath, "app.asar.unpacked", "node_modules");
-    const candidates = [
-      import_path.default.join(unpackedBase, BINDING_REL),
-      // nested under @sna-sdk/core if hoisting differs
-      import_path.default.join(unpackedBase, "@sna-sdk", "core", "node_modules", BINDING_REL)
-    ];
-    for (const c of candidates) {
-      if (import_fs.default.existsSync(c)) return c;
-    }
-  }
-  const selfPath = (0, import_url.fileURLToPath)(importMetaUrl);
-  const local = import_path.default.resolve(import_path.default.dirname(selfPath), "../../node_modules", BINDING_REL);
-  if (import_fs.default.existsSync(local)) return local;
-  return void 0;
-}
 function buildNodePath() {
   const resourcesPath = process.resourcesPath;
   if (!resourcesPath) return void 0;
@@ -97,8 +71,13 @@ async function startSnaServer(options) {
   const readyTimeout = options.readyTimeout ?? 15e3;
   const { onLog } = options;
   const standaloneScript = resolveStandaloneScript();
-  const nativeBinding = resolveNativeBinding(options.nativeBinding);
   const nodePath = buildNodePath();
+  let consumerModules;
+  try {
+    const bsPkg = require.resolve("better-sqlite3/package.json", { paths: [process.cwd()] });
+    consumerModules = import_path.default.resolve(bsPkg, "../..");
+  } catch {
+  }
   const env = {
     ...process.env,
     SNA_PORT: String(port),
@@ -106,7 +85,8 @@ async function startSnaServer(options) {
     ...options.maxSessions != null ? { SNA_MAX_SESSIONS: String(options.maxSessions) } : {},
     ...options.permissionMode ? { SNA_PERMISSION_MODE: options.permissionMode } : {},
     ...options.model ? { SNA_MODEL: options.model } : {},
-    ...nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: nativeBinding } : {},
+    ...options.nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: options.nativeBinding } : {},
+    ...consumerModules ? { SNA_MODULES_PATH: consumerModules } : {},
     ...nodePath ? { NODE_PATH: nodePath } : {},
     // Consumer overrides last so they can always win
     ...options.env ?? {}

package/dist/electron/index.d.ts

@@ -29,10 +29,10 @@ import { ChildProcess } from 'child_process';
  *
  *   asarUnpack: ["node_modules/@sna-sdk/core/**"]
  *
- * The better-sqlite3 native binding used by the forked process must be
- * compiled for the system Node.js (not Electron). If your app uses
- * electron-rebuild, set options.nativeBinding to a Node.js-compiled
- * .node file, or let SNA manage its own native install via `sna api:up`.
+ * The forked server process runs on Electron's Node.js. The launcher
+ * automatically detects the consumer app's electron-rebuilt native modules
+ * and passes their path to the server process, so better-sqlite3 just works
+ * without any manual configuration.
  */
 
 interface SnaServerOptions {

package/dist/electron/index.js

@@ -16,32 +16,6 @@ Ensure "@sna-sdk/core" is listed in asarUnpack in your electron-builder config.`
   }
   return script;
 }
-function resolveNativeBinding(override) {
-  if (override) {
-    if (!fs.existsSync(override)) {
-      console.warn(`[sna] SNA nativeBinding override not found: ${override}`);
-      return void 0;
-    }
-    return override;
-  }
-  const BINDING_REL = path.join("better-sqlite3", "build", "Release", "better_sqlite3.node");
-  const resourcesPath = process.resourcesPath;
-  if (resourcesPath) {
-    const unpackedBase = path.join(resourcesPath, "app.asar.unpacked", "node_modules");
-    const candidates = [
-      path.join(unpackedBase, BINDING_REL),
-      // nested under @sna-sdk/core if hoisting differs
-      path.join(unpackedBase, "@sna-sdk", "core", "node_modules", BINDING_REL)
-    ];
-    for (const c of candidates) {
-      if (fs.existsSync(c)) return c;
-    }
-  }
-  const selfPath = fileURLToPath(import.meta.url);
-  const local = path.resolve(path.dirname(selfPath), "../../node_modules", BINDING_REL);
-  if (fs.existsSync(local)) return local;
-  return void 0;
-}
 function buildNodePath() {
   const resourcesPath = process.resourcesPath;
   if (!resourcesPath) return void 0;
@@ -56,8 +30,13 @@ async function startSnaServer(options) {
   const readyTimeout = options.readyTimeout ?? 15e3;
   const { onLog } = options;
   const standaloneScript = resolveStandaloneScript();
-  const nativeBinding = resolveNativeBinding(options.nativeBinding);
   const nodePath = buildNodePath();
+  let consumerModules;
+  try {
+    const bsPkg = require.resolve("better-sqlite3/package.json", { paths: [process.cwd()] });
+    consumerModules = path.resolve(bsPkg, "../..");
+  } catch {
+  }
   const env = {
     ...process.env,
     SNA_PORT: String(port),
@@ -65,7 +44,8 @@ async function startSnaServer(options) {
     ...options.maxSessions != null ? { SNA_MAX_SESSIONS: String(options.maxSessions) } : {},
     ...options.permissionMode ? { SNA_PERMISSION_MODE: options.permissionMode } : {},
     ...options.model ? { SNA_MODEL: options.model } : {},
-    ...nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: nativeBinding } : {},
+    ...options.nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: options.nativeBinding } : {},
+    ...consumerModules ? { SNA_MODULES_PATH: consumerModules } : {},
     ...nodePath ? { NODE_PATH: nodePath } : {},
     // Consumer overrides last so they can always win
     ...options.env ?? {}

package/dist/node/index.cjs

@@ -57,32 +57,6 @@ Ensure "@sna-sdk/core" is listed in asarUnpack in your electron-builder config.`
   }
   return script;
 }
-function resolveNativeBinding(override) {
-  if (override) {
-    if (!import_fs.default.existsSync(override)) {
-      console.warn(`[sna] SNA nativeBinding override not found: ${override}`);
-      return void 0;
-    }
-    return override;
-  }
-  const BINDING_REL = import_path.default.join("better-sqlite3", "build", "Release", "better_sqlite3.node");
-  const resourcesPath = process.resourcesPath;
-  if (resourcesPath) {
-    const unpackedBase = import_path.default.join(resourcesPath, "app.asar.unpacked", "node_modules");
-    const candidates = [
-      import_path.default.join(unpackedBase, BINDING_REL),
-      // nested under @sna-sdk/core if hoisting differs
-      import_path.default.join(unpackedBase, "@sna-sdk", "core", "node_modules", BINDING_REL)
-    ];
-    for (const c of candidates) {
-      if (import_fs.default.existsSync(c)) return c;
-    }
-  }
-  const selfPath = (0, import_url.fileURLToPath)(importMetaUrl);
-  const local = import_path.default.resolve(import_path.default.dirname(selfPath), "../../node_modules", BINDING_REL);
-  if (import_fs.default.existsSync(local)) return local;
-  return void 0;
-}
 function buildNodePath() {
   const resourcesPath = process.resourcesPath;
   if (!resourcesPath) return void 0;
@@ -97,8 +71,13 @@ async function startSnaServer(options) {
   const readyTimeout = options.readyTimeout ?? 15e3;
   const { onLog } = options;
   const standaloneScript = resolveStandaloneScript();
-  const nativeBinding = resolveNativeBinding(options.nativeBinding);
   const nodePath = buildNodePath();
+  let consumerModules;
+  try {
+    const bsPkg = require.resolve("better-sqlite3/package.json", { paths: [process.cwd()] });
+    consumerModules = import_path.default.resolve(bsPkg, "../..");
+  } catch {
+  }
   const env = {
     ...process.env,
     SNA_PORT: String(port),
@@ -106,7 +85,8 @@ async function startSnaServer(options) {
     ...options.maxSessions != null ? { SNA_MAX_SESSIONS: String(options.maxSessions) } : {},
     ...options.permissionMode ? { SNA_PERMISSION_MODE: options.permissionMode } : {},
     ...options.model ? { SNA_MODEL: options.model } : {},
-    ...nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: nativeBinding } : {},
+    ...options.nativeBinding ? { SNA_SQLITE_NATIVE_BINDING: options.nativeBinding } : {},
+    ...consumerModules ? { SNA_MODULES_PATH: consumerModules } : {},
     ...nodePath ? { NODE_PATH: nodePath } : {},
     // Consumer overrides last so they can always win
     ...options.env ?? {}

package/dist/scripts/sna.js

@@ -379,6 +379,14 @@ function isPortInUse(port) {
 }
 function resolveAndCacheClaudePath() {
   const SHELL = process.env.SHELL || "/bin/zsh";
+  try {
+    const resolved = execSync(`${SHELL} -l -c "which claude"`, { encoding: "utf8" }).trim();
+    if (resolved) {
+      fs.writeFileSync(CLAUDE_PATH_FILE, resolved);
+      return resolved;
+    }
+  } catch {
+  }
   const candidates = [
     "/opt/homebrew/bin/claude",
     "/usr/local/bin/claude",
@@ -392,13 +400,7 @@ function resolveAndCacheClaudePath() {
     } catch {
     }
   }
-  try {
-    const resolved = execSync(`${SHELL} -l -c "which claude"`, { encoding: "utf8" }).trim();
-    fs.writeFileSync(CLAUDE_PATH_FILE, resolved);
-    return resolved;
-  } catch {
-    return "claude";
-  }
+  return "claude";
 }
 function openBrowser(url) {
   try {

package/dist/server/api-types.d.ts

@@ -14,6 +14,10 @@ interface ApiResponses {
     "sessions.list": {
         sessions: SessionInfo[];
     };
+    "sessions.update": {
+        status: "updated";
+        session: string;
+    };
     "sessions.remove": {
         status: "removed";
     };

package/dist/server/routes/agent.js

@@ -125,7 +125,6 @@ function createAgentRoutes(sessionManager) {
     if (session.process?.alive) {
       session.process.kill();
     }
-    session.eventBuffer.length = 0;
     const provider = getProvider(body.provider ?? "claude-code");
     try {
       const db = getDb();

package/dist/server/session-manager.d.ts

@@ -73,18 +73,25 @@ declare class SessionManager {
     private lifecycleListeners;
     private configChangedListeners;
     private stateChangedListeners;
+    private metadataChangedListeners;
     constructor(options?: SessionManagerOptions);
     /** Restore session metadata from DB (cwd, label, meta). Process state is not restored. */
     private restoreFromDb;
     /** Persist session metadata to DB. */
     private persistSession;
-    /** Create a new session. Throws if max sessions reached. */
+    /** Create a new session. Throws if session already exists or max sessions reached. */
     createSession(opts?: {
         id?: string;
         label?: string;
         cwd?: string;
         meta?: Record<string, unknown> | null;
     }): Session;
+    /** Update an existing session's metadata. Throws if session not found. */
+    updateSession(id: string, opts: {
+        label?: string;
+        meta?: Record<string, unknown> | null;
+        cwd?: string;
+    }): Session;
     /** Get a session by ID. */
     getSession(id: string): Session | undefined;
     /** Get or create a session (used for "default" backward compat). */
@@ -110,6 +117,8 @@ declare class SessionManager {
     /** Subscribe to session config changes. Returns unsubscribe function. */
     onConfigChanged(cb: (event: SessionConfigChangedEvent) => void): () => void;
     private emitConfigChanged;
+    onMetadataChanged(cb: (sessionId: string) => void): () => void;
+    private emitMetadataChanged;
     onStateChanged(cb: (event: {
         session: string;
         agentStatus: AgentStatus;

package/dist/server/session-manager.js

@@ -12,6 +12,7 @@ class SessionManager {
     this.lifecycleListeners = /* @__PURE__ */ new Set();
     this.configChangedListeners = /* @__PURE__ */ new Set();
     this.stateChangedListeners = /* @__PURE__ */ new Set();
+    this.metadataChangedListeners = /* @__PURE__ */ new Set();
     this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
     this.restoreFromDb();
   }
@@ -64,26 +65,11 @@ class SessionManager {
     } catch {
     }
   }
-  /** Create a new session. Throws if max sessions reached. */
+  /** Create a new session. Throws if session already exists or max sessions reached. */
   createSession(opts = {}) {
     const id = opts.id ?? crypto.randomUUID().slice(0, 8);
     if (this.sessions.has(id)) {
-      const existing = this.sessions.get(id);
-      let changed = false;
-      if (opts.cwd && opts.cwd !== existing.cwd) {
-        existing.cwd = opts.cwd;
-        changed = true;
-      }
-      if (opts.label && opts.label !== existing.label) {
-        existing.label = opts.label;
-        changed = true;
-      }
-      if (opts.meta !== void 0 && opts.meta !== existing.meta) {
-        existing.meta = opts.meta ?? null;
-        changed = true;
-      }
-      if (changed) this.persistSession(existing);
-      return existing;
+      throw new Error(`Session "${id}" already exists`);
     }
     const aliveCount = Array.from(this.sessions.values()).filter((s) => s.process?.alive).length;
     if (aliveCount >= this.maxSessions) {
@@ -107,6 +93,17 @@ class SessionManager {
     this.persistSession(session);
     return session;
   }
+  /** Update an existing session's metadata. Throws if session not found. */
+  updateSession(id, opts) {
+    const session = this.sessions.get(id);
+    if (!session) throw new Error(`Session "${id}" not found`);
+    if (opts.label !== void 0) session.label = opts.label;
+    if (opts.meta !== void 0) session.meta = opts.meta;
+    if (opts.cwd !== void 0) session.cwd = opts.cwd;
+    this.persistSession(session);
+    this.emitMetadataChanged(id);
+    return session;
+  }
   /** Get a session by ID. */
   getSession(id) {
     return this.sessions.get(id);
@@ -128,12 +125,23 @@ class SessionManager {
     const session = this.sessions.get(sessionId);
     if (!session) throw new Error(`Session "${sessionId}" not found`);
     session.process = proc;
-    this.setSessionState(sessionId, session, "processing");
     session.lastActivityAt = Date.now();
+    session.eventBuffer.length = 0;
+    try {
+      const db = getDb();
+      const row = db.prepare(
+        `SELECT COUNT(*) as c FROM chat_messages WHERE session_id = ?`
+      ).get(sessionId);
+      session.eventCounter = row.c;
+    } catch {
+    }
     proc.on("event", (e) => {
-      if (e.type === "init" && e.data?.sessionId && !session.ccSessionId) {
-        session.ccSessionId = e.data.sessionId;
-        this.persistSession(session);
+      if (e.type === "init") {
+        if (e.data?.sessionId && !session.ccSessionId) {
+          session.ccSessionId = e.data.sessionId;
+          this.persistSession(session);
+        }
+        this.setSessionState(sessionId, session, "waiting");
       }
       if (e.type !== "assistant_delta") {
         session.eventBuffer.push(e);
@@ -142,7 +150,9 @@ class SessionManager {
         }
       }
       session.eventCounter++;
-      if (e.type === "complete" || e.type === "error" || e.type === "interrupted") {
+      if (e.type === "thinking" || e.type === "tool_use" || e.type === "assistant_delta") {
+        this.setSessionState(sessionId, session, "processing");
+      } else if (e.type === "complete" || e.type === "error" || e.type === "interrupted") {
         this.setSessionState(sessionId, session, "waiting");
       }
       this.persistEvent(sessionId, e);
@@ -223,6 +233,14 @@ class SessionManager {
   emitConfigChanged(sessionId, config) {
     for (const cb of this.configChangedListeners) cb({ session: sessionId, config });
   }
+  // ── Session metadata change pub/sub ─────────────────────────────
+  onMetadataChanged(cb) {
+    this.metadataChangedListeners.add(cb);
+    return () => this.metadataChangedListeners.delete(cb);
+  }
+  emitMetadataChanged(sessionId) {
+    for (const cb of this.metadataChangedListeners) cb(sessionId);
+  }
   // ── Agent status change pub/sub ────────────────────────────────
   onStateChanged(cb) {
     this.stateChangedListeners.add(cb);
@@ -303,7 +321,6 @@ class SessionManager {
       extraArgs: overrides.extraArgs ?? base.extraArgs
     };
     if (session.process?.alive) session.process.kill();
-    session.eventBuffer.length = 0;
     const proc = spawnFn(config);
     this.setProcess(id, proc);
     session.lastStartConfig = config;

package/dist/server/standalone.js

@@ -18,6 +18,14 @@ var DB_PATH = process.env.SNA_DB_PATH ?? path.join(process.cwd(), "data/sna.db")
 var NATIVE_DIR = path.join(process.cwd(), ".sna/native");
 var _db = null;
 function loadBetterSqlite3() {
+  const modulesPath = process.env.SNA_MODULES_PATH;
+  if (modulesPath) {
+    const entry = path.join(modulesPath, "better-sqlite3");
+    if (fs.existsSync(entry)) {
+      const req2 = createRequire(path.join(modulesPath, "noop.js"));
+      return req2("better-sqlite3");
+    }
+  }
   const nativeEntry = path.join(NATIVE_DIR, "node_modules", "better-sqlite3");
   if (fs.existsSync(nativeEntry)) {
     const req2 = createRequire(path.join(NATIVE_DIR, "noop.js"));
@@ -402,13 +410,20 @@ function resolveClaudePath(cwd) {
     return "claude";
   }
 }
-var ClaudeCodeProcess = class {
+var _ClaudeCodeProcess = class _ClaudeCodeProcess {
   constructor(proc, options) {
     this.emitter = new EventEmitter();
     this._alive = true;
     this._sessionId = null;
     this._initEmitted = false;
     this.buffer = "";
+    /**
+     * FIFO event queue — ALL events (deltas, assistant, complete, etc.) go through
+     * this queue. A fixed-interval timer drains one item at a time, guaranteeing
+     * strict ordering: deltas → assistant → complete, never out of order.
+     */
+    this.eventQueue = [];
+    this.drainTimer = null;
     this.proc = proc;
     proc.stdout.on("data", (chunk) => {
       this.buffer += chunk.toString();
@@ -423,7 +438,7 @@ var ClaudeCodeProcess = class {
             this._sessionId = msg.session_id;
           }
           const event = this.normalizeEvent(msg);
-          if (event) this.emitter.emit("event", event);
+          if (event) this.enqueue(event);
         } catch {
         }
       }
@@ -436,10 +451,11 @@ var ClaudeCodeProcess = class {
         try {
           const msg = JSON.parse(this.buffer);
           const event = this.normalizeEvent(msg);
-          if (event) this.emitter.emit("event", event);
+          if (event) this.enqueue(event);
         } catch {
         }
       }
+      this.flushQueue();
       this.emitter.emit("exit", code);
       logger.log("agent", `process exited (code=${code})`);
     });
@@ -455,35 +471,58 @@ var ClaudeCodeProcess = class {
       this.send(options.prompt);
     }
   }
+  // ~67 events/sec
   /**
-   * Split completed assistant text into chunks and emit assistant_delta events
-   * at a fixed rate (~270 chars/sec), followed by the final assistant event.
-   *
-   * CHUNK_SIZE chars every CHUNK_DELAY_MS → natural TPS feel regardless of length.
+   * Enqueue an event for ordered emission.
+   * Starts the drain timer if not already running.
    */
-  emitTextAsDeltas(text) {
+  enqueue(event) {
+    this.eventQueue.push(event);
+    if (!this.drainTimer) {
+      this.drainTimer = setInterval(() => this.drainOne(), _ClaudeCodeProcess.DRAIN_INTERVAL_MS);
+    }
+  }
+  /** Emit one event from the front of the queue. Stop timer when empty. */
+  drainOne() {
+    const event = this.eventQueue.shift();
+    if (event) {
+      this.emitter.emit("event", event);
+    }
+    if (this.eventQueue.length === 0 && this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+  }
+  /** Flush all remaining queued events immediately (used on process exit). */
+  flushQueue() {
+    if (this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+    while (this.eventQueue.length > 0) {
+      this.emitter.emit("event", this.eventQueue.shift());
+    }
+  }
+  /**
+   * Split completed assistant text into delta chunks and enqueue them,
+   * followed by the final assistant event. All go through the FIFO queue
+   * so subsequent events (complete, etc.) are guaranteed to come after.
+   */
+  enqueueTextAsDeltas(text) {
     const CHUNK_SIZE = 4;
-    const CHUNK_DELAY_MS = 15;
-    let t = 0;
     for (let i = 0; i < text.length; i += CHUNK_SIZE) {
-      const chunk = text.slice(i, i + CHUNK_SIZE);
-      setTimeout(() => {
-        this.emitter.emit("event", {
-          type: "assistant_delta",
-          delta: chunk,
-          index: 0,
-          timestamp: Date.now()
-        });
-      }, t);
-      t += CHUNK_DELAY_MS;
-    }
-    setTimeout(() => {
-      this.emitter.emit("event", {
-        type: "assistant",
-        message: text,
+      this.enqueue({
+        type: "assistant_delta",
+        delta: text.slice(i, i + CHUNK_SIZE),
+        index: 0,
         timestamp: Date.now()
       });
-    }, t);
+    }
+    this.enqueue({
+      type: "assistant",
+      message: text,
+      timestamp: Date.now()
+    });
   }
   get alive() {
     return this._alive;
@@ -584,10 +623,10 @@ var ClaudeCodeProcess = class {
         }
         if (events.length > 0 || textBlocks.length > 0) {
           for (const e of events) {
-            this.emitter.emit("event", e);
+            this.enqueue(e);
           }
           for (const text of textBlocks) {
-            this.emitTextAsDeltas(text);
+            this.enqueueTextAsDeltas(text);
           }
         }
         return null;
@@ -656,6 +695,8 @@ var ClaudeCodeProcess = class {
     }
   }
 };
+_ClaudeCodeProcess.DRAIN_INTERVAL_MS = 15;
+var ClaudeCodeProcess = _ClaudeCodeProcess;
 var ClaudeCodeProvider = class {
   constructor() {
     this.name = "claude-code";
@@ -946,7 +987,6 @@ function createAgentRoutes(sessionManager2) {
     if (session.process?.alive) {
       session.process.kill();
     }
-    session.eventBuffer.length = 0;
     const provider2 = getProvider(body.provider ?? "claude-code");
     try {
       const db = getDb();
@@ -1373,6 +1413,7 @@ var SessionManager = class {
     this.lifecycleListeners = /* @__PURE__ */ new Set();
     this.configChangedListeners = /* @__PURE__ */ new Set();
     this.stateChangedListeners = /* @__PURE__ */ new Set();
+    this.metadataChangedListeners = /* @__PURE__ */ new Set();
     this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
     this.restoreFromDb();
   }
@@ -1425,26 +1466,11 @@ var SessionManager = class {
     } catch {
     }
   }
-  /** Create a new session. Throws if max sessions reached. */
+  /** Create a new session. Throws if session already exists or max sessions reached. */
   createSession(opts = {}) {
     const id = opts.id ?? crypto.randomUUID().slice(0, 8);
     if (this.sessions.has(id)) {
-      const existing = this.sessions.get(id);
-      let changed = false;
-      if (opts.cwd && opts.cwd !== existing.cwd) {
-        existing.cwd = opts.cwd;
-        changed = true;
-      }
-      if (opts.label && opts.label !== existing.label) {
-        existing.label = opts.label;
-        changed = true;
-      }
-      if (opts.meta !== void 0 && opts.meta !== existing.meta) {
-        existing.meta = opts.meta ?? null;
-        changed = true;
-      }
-      if (changed) this.persistSession(existing);
-      return existing;
+      throw new Error(`Session "${id}" already exists`);
     }
     const aliveCount = Array.from(this.sessions.values()).filter((s) => s.process?.alive).length;
     if (aliveCount >= this.maxSessions) {
@@ -1468,6 +1494,17 @@ var SessionManager = class {
     this.persistSession(session);
     return session;
   }
+  /** Update an existing session's metadata. Throws if session not found. */
+  updateSession(id, opts) {
+    const session = this.sessions.get(id);
+    if (!session) throw new Error(`Session "${id}" not found`);
+    if (opts.label !== void 0) session.label = opts.label;
+    if (opts.meta !== void 0) session.meta = opts.meta;
+    if (opts.cwd !== void 0) session.cwd = opts.cwd;
+    this.persistSession(session);
+    this.emitMetadataChanged(id);
+    return session;
+  }
   /** Get a session by ID. */
   getSession(id) {
     return this.sessions.get(id);
@@ -1489,12 +1526,23 @@ var SessionManager = class {
     const session = this.sessions.get(sessionId);
     if (!session) throw new Error(`Session "${sessionId}" not found`);
     session.process = proc;
-    this.setSessionState(sessionId, session, "processing");
     session.lastActivityAt = Date.now();
+    session.eventBuffer.length = 0;
+    try {
+      const db = getDb();
+      const row = db.prepare(
+        `SELECT COUNT(*) as c FROM chat_messages WHERE session_id = ?`
+      ).get(sessionId);
+      session.eventCounter = row.c;
+    } catch {
+    }
     proc.on("event", (e) => {
-      if (e.type === "init" && e.data?.sessionId && !session.ccSessionId) {
-        session.ccSessionId = e.data.sessionId;
-        this.persistSession(session);
+      if (e.type === "init") {
+        if (e.data?.sessionId && !session.ccSessionId) {
+          session.ccSessionId = e.data.sessionId;
+          this.persistSession(session);
+        }
+        this.setSessionState(sessionId, session, "waiting");
       }
       if (e.type !== "assistant_delta") {
         session.eventBuffer.push(e);
@@ -1503,7 +1551,9 @@ var SessionManager = class {
         }
       }
       session.eventCounter++;
-      if (e.type === "complete" || e.type === "error" || e.type === "interrupted") {
+      if (e.type === "thinking" || e.type === "tool_use" || e.type === "assistant_delta") {
+        this.setSessionState(sessionId, session, "processing");
+      } else if (e.type === "complete" || e.type === "error" || e.type === "interrupted") {
         this.setSessionState(sessionId, session, "waiting");
       }
       this.persistEvent(sessionId, e);
@@ -1584,6 +1634,14 @@ var SessionManager = class {
   emitConfigChanged(sessionId, config) {
     for (const cb of this.configChangedListeners) cb({ session: sessionId, config });
   }
+  // ── Session metadata change pub/sub ─────────────────────────────
+  onMetadataChanged(cb) {
+    this.metadataChangedListeners.add(cb);
+    return () => this.metadataChangedListeners.delete(cb);
+  }
+  emitMetadataChanged(sessionId) {
+    for (const cb of this.metadataChangedListeners) cb(sessionId);
+  }
   // ── Agent status change pub/sub ────────────────────────────────
   onStateChanged(cb) {
     this.stateChangedListeners.add(cb);
@@ -1664,7 +1722,6 @@ var SessionManager = class {
       extraArgs: overrides.extraArgs ?? base.extraArgs
     };
     if (session.process?.alive) session.process.kill();
-    session.eventBuffer.length = 0;
     const proc = spawnFn(config);
     this.setProcess(id, proc);
     session.lastStartConfig = config;
@@ -1841,15 +1898,22 @@ function attachWebSocket(server2, sessionManager2) {
   });
   wss.on("connection", (ws) => {
     logger.log("ws", "client connected");
-    const state = { agentUnsubs: /* @__PURE__ */ new Map(), skillEventUnsub: null, skillPollTimer: null, permissionUnsub: null, lifecycleUnsub: null, configChangedUnsub: null, stateChangedUnsub: null };
+    const state = { agentUnsubs: /* @__PURE__ */ new Map(), skillEventUnsub: null, skillPollTimer: null, permissionUnsub: null, lifecycleUnsub: null, configChangedUnsub: null, stateChangedUnsub: null, metadataChangedUnsub: null };
+    const pushSnapshot = () => send(ws, { type: "sessions.snapshot", sessions: sessionManager2.listSessions() });
+    pushSnapshot();
     state.lifecycleUnsub = sessionManager2.onSessionLifecycle((event) => {
       send(ws, { type: "session.lifecycle", ...event });
+      pushSnapshot();
     });
     state.configChangedUnsub = sessionManager2.onConfigChanged((event) => {
       send(ws, { type: "session.config-changed", ...event });
     });
     state.stateChangedUnsub = sessionManager2.onStateChanged((event) => {
       send(ws, { type: "session.state-changed", ...event });
+      pushSnapshot();
+    });
+    state.metadataChangedUnsub = sessionManager2.onMetadataChanged(() => {
+      pushSnapshot();
     });
     ws.on("message", (raw) => {
       let msg;
@@ -1883,6 +1947,8 @@ function attachWebSocket(server2, sessionManager2) {
       state.configChangedUnsub = null;
       state.stateChangedUnsub?.();
       state.stateChangedUnsub = null;
+      state.metadataChangedUnsub?.();
+      state.metadataChangedUnsub = null;
     });
   });
   return wss;
@@ -1894,6 +1960,8 @@ function handleMessage(ws, msg, sm, state) {
       return handleSessionsCreate(ws, msg, sm);
     case "sessions.list":
       return wsReply(ws, msg, { sessions: sm.listSessions() });
+    case "sessions.update":
+      return handleSessionsUpdate(ws, msg, sm);
     case "sessions.remove":
       return handleSessionsRemove(ws, msg, sm);
     // ── Agent lifecycle ───────────────────────────────
@@ -1969,6 +2037,20 @@ function handleSessionsCreate(ws, msg, sm) {
     replyError(ws, msg, e.message);
   }
 }
+function handleSessionsUpdate(ws, msg, sm) {
+  const id = msg.session;
+  if (!id) return replyError(ws, msg, "session is required");
+  try {
+    sm.updateSession(id, {
+      label: msg.label,
+      meta: msg.meta,
+      cwd: msg.cwd
+    });
+    wsReply(ws, msg, { status: "updated", session: id });
+  } catch (e) {
+    replyError(ws, msg, e.message);
+  }
+}
 function handleSessionsRemove(ws, msg, sm) {
   const id = msg.session;
   if (!id) return replyError(ws, msg, "session is required");
@@ -1987,7 +2069,6 @@ function handleAgentStart(ws, msg, sm) {
     return;
   }
   if (session.process?.alive) session.process.kill();
-  session.eventBuffer.length = 0;
   const provider2 = getProvider(msg.provider ?? "claude-code");
   try {
     const db = getDb();
@@ -2223,18 +2304,26 @@ function handleAgentSubscribe(ws, msg, sm, state) {
       }
     } catch {
     }
-  }
-  const bufferStart = typeof msg.since === "number" && msg.since > 0 ? msg.since : session.eventCounter;
-  if (!includeHistory) cursor = bufferStart;
-  if (cursor < session.eventCounter) {
-    const startIdx = Math.max(0, session.eventBuffer.length - (session.eventCounter - cursor));
-    const events = session.eventBuffer.slice(startIdx);
-    for (const event of events) {
-      cursor++;
-      send(ws, { type: "agent.event", session: sessionId, cursor, event });
+    if (cursor < session.eventCounter) {
+      const unpersisted = session.eventCounter - cursor;
+      const bufferSlice = session.eventBuffer.slice(-unpersisted);
+      for (const event of bufferSlice) {
+        cursor++;
+        send(ws, { type: "agent.event", session: sessionId, cursor, event });
+      }
     }
   } else {
-    cursor = session.eventCounter;
+    cursor = typeof msg.since === "number" && msg.since > 0 ? msg.since : session.eventCounter;
+    if (cursor < session.eventCounter) {
+      const startIdx = Math.max(0, session.eventBuffer.length - (session.eventCounter - cursor));
+      const events = session.eventBuffer.slice(startIdx);
+      for (const event of events) {
+        cursor++;
+        send(ws, { type: "agent.event", session: sessionId, cursor, event });
+      }
+    } else {
+      cursor = session.eventCounter;
+    }
   }
   const unsub = sm.onSessionEvent(sessionId, (eventCursor, event) => {
     send(ws, { type: "agent.event", session: sessionId, cursor: eventCursor, event });
@@ -2496,7 +2585,7 @@ root.use("*", async (c, next) => {
   await next();
 });
 var sessionManager = new SessionManager({ maxSessions });
-sessionManager.createSession({ id: "default", cwd: process.cwd() });
+sessionManager.getOrCreateSession("default", { cwd: process.cwd() });
 var provider = getProvider("claude-code");
 logger.log("sna", "spawning agent...");
 var agentProcess = provider.spawn({ cwd: process.cwd(), permissionMode, model: defaultModel });

package/dist/server/ws.d.ts

@@ -13,6 +13,7 @@ import '../core/providers/types.js';
  *   Server → Client:  { type: "sessions.list", rid: "1", sessions: [...] }
  *   Server → Client:  { type: "error", rid: "1", message: "..." }
  *   Server → Client:  { type: "agent.event", session: "abc", cursor: 42, event: {...} }  (push)
+ *   Server → Client:  { type: "sessions.snapshot", sessions: [...] }                   (auto-push on connect + state change)
  *   Server → Client:  { type: "session.lifecycle", session: "abc", state: "killed" }   (auto-push)
  *   Server → Client:  { type: "skill.event", data: {...} }  (push)
  *

package/dist/server/ws.js

@@ -31,15 +31,22 @@ function attachWebSocket(server, sessionManager) {
   });
   wss.on("connection", (ws) => {
     logger.log("ws", "client connected");
-    const state = { agentUnsubs: /* @__PURE__ */ new Map(), skillEventUnsub: null, skillPollTimer: null, permissionUnsub: null, lifecycleUnsub: null, configChangedUnsub: null, stateChangedUnsub: null };
+    const state = { agentUnsubs: /* @__PURE__ */ new Map(), skillEventUnsub: null, skillPollTimer: null, permissionUnsub: null, lifecycleUnsub: null, configChangedUnsub: null, stateChangedUnsub: null, metadataChangedUnsub: null };
+    const pushSnapshot = () => send(ws, { type: "sessions.snapshot", sessions: sessionManager.listSessions() });
+    pushSnapshot();
     state.lifecycleUnsub = sessionManager.onSessionLifecycle((event) => {
       send(ws, { type: "session.lifecycle", ...event });
+      pushSnapshot();
     });
     state.configChangedUnsub = sessionManager.onConfigChanged((event) => {
       send(ws, { type: "session.config-changed", ...event });
     });
     state.stateChangedUnsub = sessionManager.onStateChanged((event) => {
       send(ws, { type: "session.state-changed", ...event });
+      pushSnapshot();
+    });
+    state.metadataChangedUnsub = sessionManager.onMetadataChanged(() => {
+      pushSnapshot();
     });
     ws.on("message", (raw) => {
       let msg;
@@ -73,6 +80,8 @@ function attachWebSocket(server, sessionManager) {
       state.configChangedUnsub = null;
       state.stateChangedUnsub?.();
       state.stateChangedUnsub = null;
+      state.metadataChangedUnsub?.();
+      state.metadataChangedUnsub = null;
     });
   });
   return wss;
@@ -84,6 +93,8 @@ function handleMessage(ws, msg, sm, state) {
       return handleSessionsCreate(ws, msg, sm);
     case "sessions.list":
       return wsReply(ws, msg, { sessions: sm.listSessions() });
+    case "sessions.update":
+      return handleSessionsUpdate(ws, msg, sm);
     case "sessions.remove":
       return handleSessionsRemove(ws, msg, sm);
     // ── Agent lifecycle ───────────────────────────────
@@ -159,6 +170,20 @@ function handleSessionsCreate(ws, msg, sm) {
     replyError(ws, msg, e.message);
   }
 }
+function handleSessionsUpdate(ws, msg, sm) {
+  const id = msg.session;
+  if (!id) return replyError(ws, msg, "session is required");
+  try {
+    sm.updateSession(id, {
+      label: msg.label,
+      meta: msg.meta,
+      cwd: msg.cwd
+    });
+    wsReply(ws, msg, { status: "updated", session: id });
+  } catch (e) {
+    replyError(ws, msg, e.message);
+  }
+}
 function handleSessionsRemove(ws, msg, sm) {
   const id = msg.session;
   if (!id) return replyError(ws, msg, "session is required");
@@ -177,7 +202,6 @@ function handleAgentStart(ws, msg, sm) {
     return;
   }
   if (session.process?.alive) session.process.kill();
-  session.eventBuffer.length = 0;
   const provider = getProvider(msg.provider ?? "claude-code");
   try {
     const db = getDb();
@@ -413,18 +437,26 @@ function handleAgentSubscribe(ws, msg, sm, state) {
       }
     } catch {
     }
-  }
-  const bufferStart = typeof msg.since === "number" && msg.since > 0 ? msg.since : session.eventCounter;
-  if (!includeHistory) cursor = bufferStart;
-  if (cursor < session.eventCounter) {
-    const startIdx = Math.max(0, session.eventBuffer.length - (session.eventCounter - cursor));
-    const events = session.eventBuffer.slice(startIdx);
-    for (const event of events) {
-      cursor++;
-      send(ws, { type: "agent.event", session: sessionId, cursor, event });
+    if (cursor < session.eventCounter) {
+      const unpersisted = session.eventCounter - cursor;
+      const bufferSlice = session.eventBuffer.slice(-unpersisted);
+      for (const event of bufferSlice) {
+        cursor++;
+        send(ws, { type: "agent.event", session: sessionId, cursor, event });
+      }
     }
   } else {
-    cursor = session.eventCounter;
+    cursor = typeof msg.since === "number" && msg.since > 0 ? msg.since : session.eventCounter;
+    if (cursor < session.eventCounter) {
+      const startIdx = Math.max(0, session.eventBuffer.length - (session.eventCounter - cursor));
+      const events = session.eventBuffer.slice(startIdx);
+      for (const event of events) {
+        cursor++;
+        send(ws, { type: "agent.event", session: sessionId, cursor, event });
+      }
+    } else {
+      cursor = session.eventCounter;
+    }
   }
   const unsub = sm.onSessionEvent(sessionId, (eventCursor, event) => {
     send(ws, { type: "agent.event", session: sessionId, cursor: eventCursor, event });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sna-sdk/core",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Skills-Native Application runtime — server, providers, session management, database, and CLI",
   "type": "module",
   "bin": {
@@ -102,12 +102,14 @@
   ],
   "dependencies": {
     "@hono/node-server": "^1.19.11",
-    "better-sqlite3": "^12.6.2",
     "chalk": "^5.0.0",
     "hono": "^4.12.7",
     "js-yaml": "^4.1.0",
     "ws": "^8.20.0"
   },
+  "peerDependencies": {
+    "better-sqlite3": ">=11.0.0"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",