@sna-sdk/core 0.6.1 → 0.7.2

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();
@@ -254,7 +253,7 @@ function createAgentRoutes(sessionManager) {
         } else {
           cursor = session.eventCounter;
         }
-        while (queue.length > 0 && queue[0].cursor <= cursor) queue.shift();
+        while (queue.length > 0 && queue[0].cursor !== -1 && queue[0].cursor <= cursor) queue.shift();
         while (!signal.aborted) {
           if (queue.length === 0) {
             await Promise.race([
@@ -268,7 +267,11 @@ function createAgentRoutes(sessionManager) {
           if (queue.length > 0) {
             while (queue.length > 0) {
               const item = queue.shift();
-              await stream.writeSSE({ id: String(item.cursor), data: JSON.stringify(item.event) });
+              if (item.cursor === -1) {
+                await stream.writeSSE({ data: JSON.stringify(item.event) });
+              } else {
+                await stream.writeSSE({ id: String(item.cursor), data: JSON.stringify(item.event) });
+              }
             }
           } else {
             await stream.writeSSE({ data: "" });

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). */
@@ -101,6 +108,12 @@ declare class SessionManager {
     /** Broadcast a skill event to all subscribers (called after DB insert). */
     broadcastSkillEvent(event: Record<string, unknown>): void;
     /** Push a synthetic event into a session's event stream (for user message broadcast). */
+    /**
+     * Push an externally-persisted event into the session.
+     * The caller is responsible for DB persistence — this method only updates
+     * the in-memory counter/buffer and notifies listeners.
+     * eventCounter increments to stay in sync with the DB row count.
+     */
     pushEvent(sessionId: string, event: AgentEvent): void;
     /** Subscribe to permission request notifications. Returns unsubscribe function. */
     onPermissionRequest(cb: (sessionId: string, request: Record<string, unknown>, createdAt: number) => void): () => void;
@@ -110,6 +123,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;
@@ -156,6 +171,7 @@ declare class SessionManager {
     touch(id: string): void;
     /** Persist an agent event to chat_messages. */
     private getMessageStats;
+    /** Persist an agent event to chat_messages. Returns true if a row was inserted. */
     private persistEvent;
     /** Kill all sessions. Used during shutdown. */
     killAll(): void;