@sna-sdk/core 0.1.0 → 0.2.3

package/README.md

@@ -6,10 +6,13 @@ Server runtime for [Skills-Native Applications](https://github.com/neuradex/sna)
 
 - **Skill event pipeline** — emit, SSE streaming, and hook scripts
 - **Dispatch** — unified event dispatcher with validation, session lifecycle, and cleanup (`sna dispatch` CLI + programmatic API)
-- **SQLite database** — schema and `getDb()` for `skill_events`
-- **Hono server factory** — `createSnaApp()` with events, emit, agent, and run routes
+- **SQLite database** — schema and `getDb()` for `skill_events`, `chat_sessions`, `chat_messages`
+- **Hono server factory** — `createSnaApp()` with events, emit, agent, chat, and run routes
+- **WebSocket API** — `attachWebSocket()` wrapping all HTTP routes over a single WS connection
+- **One-shot execution** — `POST /agent/run-once` for single-request LLM calls
 - **Lifecycle CLI** — `sna api:up`, `sna api:down`, `sna dispatch`, `sna validate`
 - **Agent providers** — Claude Code and Codex process management
+- **Multi-session** — `SessionManager` with event pub/sub, permission management, and session metadata
 
 ## Install
 
@@ -53,10 +56,14 @@ Event types: `start` | `progress` | `milestone` | `complete` | `error`
 ### Mount server routes
 
 ```ts
-import { createSnaApp } from "@sna-sdk/core/server";
+import { createSnaApp, attachWebSocket } from "@sna-sdk/core/server";
+import { serve } from "@hono/node-server";
 
 const sna = createSnaApp();
-// Provides: GET /events (SSE), POST /emit, GET /health, POST /agent/start
+// HTTP: GET /health, GET /events (SSE), POST /emit, /agent/*, /chat/*
+const server = serve({ fetch: sna.fetch, port: 3099 });
+// WS: ws://localhost:3099/ws — all routes available over WebSocket
+attachWebSocket(server, sessionManager);
 ```
 
 ### Access the database
@@ -71,9 +78,10 @@ const db = getDb(); // SQLite instance (data/sna.db)
 
 | Import path | Contents |
 |-------------|----------|
-| `@sna-sdk/core` | `DEFAULT_SNA_PORT`, `DEFAULT_SNA_URL`, `dispatchOpen`, `dispatchSend`, `dispatchClose`, `createDispatchHandle`, `SEND_TYPES`, `loadSkillsManifest`, types |
-| `@sna-sdk/core/server` | `createSnaApp()`, route handlers, `SessionManager` |
-| `@sna-sdk/core/db/schema` | `getDb()`, `SkillEvent` type |
+| `@sna-sdk/core` | `DEFAULT_SNA_PORT`, `DEFAULT_SNA_URL`, `dispatchOpen`, `dispatchSend`, `dispatchClose`, `createDispatchHandle`, types (`AgentEvent`, `Session`, `SessionInfo`, `ChatSession`, `ChatMessage`, `SkillEvent`, etc.) |
+| `@sna-sdk/core/server` | `createSnaApp()`, `attachWebSocket()`, route handlers, `SessionManager` |
+| `@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 |
 

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

@@ -99,6 +99,11 @@ class ClaudeCodeProcess {
     logger.log("stdin", msg.slice(0, 200));
     this.proc.stdin.write(msg + "\n");
   }
+  interrupt() {
+    if (this._alive) {
+      this.proc.kill("SIGINT");
+    }
+  }
   kill() {
     if (this._alive) {
       this._alive = false;
@@ -196,7 +201,7 @@ class ClaudeCodeProcess {
             timestamp: Date.now()
           };
         }
-        if (msg.subtype === "error" || msg.is_error) {
+        if (msg.subtype?.startsWith("error") || msg.is_error) {
           return {
             type: "error",
             message: msg.result ?? msg.error ?? "Unknown error",
@@ -228,13 +233,14 @@ class ClaudeCodeProvider {
   }
   spawn(options) {
     const claudePath = resolveClaudePath(options.cwd);
-    const hookScript = path.join(options.cwd, "node_modules/@sna-sdk/core/dist/scripts/hook.js");
+    const hookScript = new URL("../../scripts/hook.js", import.meta.url).pathname;
+    const sessionId = options.env?.SNA_SESSION_ID ?? "default";
     const sdkSettings = {};
     if (options.permissionMode !== "bypassPermissions") {
       sdkSettings.hooks = {
         PreToolUse: [{
           matcher: ".*",
-          hooks: [{ type: "command", command: `node "${hookScript}"` }]
+          hooks: [{ type: "command", command: `node "${hookScript}" --session=${sessionId}` }]
         }]
       };
     }

package/dist/core/providers/types.d.ts

@@ -16,6 +16,8 @@ interface AgentEvent {
 interface AgentProcess {
     /** Send a user message to the agent's stdin. */
     send(input: string): void;
+    /** Interrupt the current turn (SIGINT). Process stays alive. */
+    interrupt(): void;
     /** Kill the agent process. */
     kill(): void;
     /** Whether the process is still running. */

package/dist/db/schema.d.ts

@@ -5,6 +5,8 @@ interface ChatSession {
     id: string;
     label: string;
     type: "main" | "background";
+    meta: string | null;
+    cwd: string | null;
     created_at: string;
 }
 interface ChatMessage {

package/dist/db/schema.js

@@ -2,11 +2,20 @@ import { createRequire } from "node:module";
 import fs from "fs";
 import path from "path";
 const DB_PATH = path.join(process.cwd(), "data/sna.db");
+const NATIVE_DIR = path.join(process.cwd(), ".sna/native");
 let _db = null;
+function loadBetterSqlite3() {
+  const nativeEntry = path.join(NATIVE_DIR, "node_modules", "better-sqlite3");
+  if (fs.existsSync(nativeEntry)) {
+    const req2 = createRequire(path.join(NATIVE_DIR, "noop.js"));
+    return req2("better-sqlite3");
+  }
+  const req = createRequire(import.meta.url);
+  return req("better-sqlite3");
+}
 function getDb() {
   if (!_db) {
-    const req = createRequire(import.meta.url);
-    const BetterSqlite3 = req("better-sqlite3");
+    const BetterSqlite3 = loadBetterSqlite3();
     const dir = path.dirname(DB_PATH);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     _db = new BetterSqlite3(DB_PATH);
@@ -23,13 +32,29 @@ function migrateSkillEvents(db) {
     db.exec("DROP TABLE IF EXISTS skill_events");
   }
 }
+function migrateChatSessionsMeta(db) {
+  const cols = db.prepare("PRAGMA table_info(chat_sessions)").all();
+  if (cols.length > 0 && !cols.some((c) => c.name === "meta")) {
+    db.exec("ALTER TABLE chat_sessions ADD COLUMN meta TEXT");
+  }
+  if (cols.length > 0 && !cols.some((c) => c.name === "cwd")) {
+    db.exec("ALTER TABLE chat_sessions ADD COLUMN cwd TEXT");
+  }
+  if (cols.length > 0 && !cols.some((c) => c.name === "last_start_config")) {
+    db.exec("ALTER TABLE chat_sessions ADD COLUMN last_start_config TEXT");
+  }
+}
 function initSchema(db) {
   migrateSkillEvents(db);
+  migrateChatSessionsMeta(db);
   db.exec(`
     CREATE TABLE IF NOT EXISTS chat_sessions (
       id         TEXT PRIMARY KEY,
       label      TEXT NOT NULL DEFAULT '',
       type       TEXT NOT NULL DEFAULT 'main',
+      meta       TEXT,
+      cwd        TEXT,
+      last_start_config TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 

package/dist/lib/logger.d.ts

@@ -5,6 +5,7 @@ declare const tags: {
     readonly stdin: string;
     readonly stdout: string;
     readonly route: string;
+    readonly ws: string;
     readonly err: string;
 };
 type Tag = keyof typeof tags;

package/dist/lib/logger.js

@@ -19,6 +19,7 @@ const tags = {
   stdin: chalk.bold.green(" IN  "),
   stdout: chalk.bold.yellow(" OUT "),
   route: chalk.bold.blue(" API "),
+  ws: chalk.bold.green(" WS  "),
   err: chalk.bold.red(" ERR ")
 };
 const tagPlain = {
@@ -28,6 +29,7 @@ const tagPlain = {
   stdin: " IN  ",
   stdout: " OUT ",
   route: " API ",
+  ws: " WS  ",
   err: " ERR "
 };
 function appendFile(tag, args) {

package/dist/scripts/hook.js

@@ -24,7 +24,7 @@ process.stdin.on("end", async () => {
       allow();
       return;
     }
-    const sessionId = process.env.SNA_SESSION_ID ?? "default";
+    const sessionId = process.argv.find((a) => a.startsWith("--session="))?.slice(10) ?? process.env.SNA_SESSION_ID ?? "default";
     const apiUrl = `http://localhost:${port}`;
     const res = await fetch(`${apiUrl}/agent/permission-request?session=${encodeURIComponent(sessionId)}`, {
       method: "POST",

package/dist/scripts/sna.js

@@ -16,6 +16,7 @@ const SNA_API_LOG_FILE = path.join(STATE_DIR, "sna-api.log");
 const PORT = process.env.PORT ?? "3000";
 const CLAUDE_PATH_FILE = path.join(STATE_DIR, "claude-path");
 const SNA_CORE_DIR = path.join(ROOT, "node_modules/@sna-sdk/core");
+const NATIVE_DIR = path.join(STATE_DIR, "native");
 function ensureStateDir() {
   if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
 }
@@ -76,8 +77,57 @@ async function checkSnaApiHealth(port) {
     return false;
   }
 }
+function ensureNativeDeps() {
+  const marker = path.join(NATIVE_DIR, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node");
+  if (fs.existsSync(marker)) {
+    try {
+      const { createRequire } = require("module");
+      const req = createRequire(path.join(NATIVE_DIR, "noop.js"));
+      const BS3 = req("better-sqlite3");
+      new BS3(":memory:").close();
+      return;
+    } catch (err) {
+      if (!err.message?.includes("NODE_MODULE_VERSION")) return;
+      step("Native binary version mismatch \u2014 reinstalling...");
+    }
+  }
+  let version;
+  try {
+    const pkgPath = require.resolve("better-sqlite3/package.json", { paths: [SNA_CORE_DIR, ROOT] });
+    version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+  } catch {
+    version = "^12.0.0";
+  }
+  step(`Installing isolated better-sqlite3@${version} in .sna/native/`);
+  fs.mkdirSync(NATIVE_DIR, { recursive: true });
+  fs.writeFileSync(path.join(NATIVE_DIR, "package.json"), JSON.stringify({
+    name: "sna-native-deps",
+    private: true,
+    dependencies: { "better-sqlite3": version }
+  }));
+  try {
+    execSync("npm install --no-package-lock --ignore-scripts", { cwd: NATIVE_DIR, stdio: "pipe" });
+    execSync("npx --yes prebuild-install -r napi", {
+      cwd: path.join(NATIVE_DIR, "node_modules", "better-sqlite3"),
+      stdio: "pipe"
+    });
+    step("Native deps ready");
+  } catch (err) {
+    try {
+      execSync("npm rebuild better-sqlite3", { cwd: NATIVE_DIR, stdio: "pipe" });
+      step("Native deps ready (compiled from source)");
+    } catch {
+      console.error(`
+\u2717  Failed to install isolated better-sqlite3: ${err.message}`);
+      console.error(`   Try manually: cd .sna/native && npm install
+`);
+      process.exit(1);
+    }
+  }
+}
 async function cmdApiUp() {
   const standaloneEntry = path.join(SNA_CORE_DIR, "dist/server/standalone.js");
+  ensureNativeDeps();
   const existingPort = process.env.SNA_PORT ?? readSnaApiPort();
   if (existingPort && isPortInUse(existingPort)) {
     const healthy = await checkSnaApiHealth(existingPort);

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

@@ -0,0 +1,105 @@
+import * as hono from 'hono';
+import { Context } from 'hono';
+import { WebSocket } from 'ws';
+import { SessionInfo } from './session-manager.js';
+import '../core/providers/types.js';
+
+interface ApiResponses {
+    "sessions.create": {
+        status: "created";
+        sessionId: string;
+        label: string;
+        meta: Record<string, unknown> | null;
+    };
+    "sessions.list": {
+        sessions: SessionInfo[];
+    };
+    "sessions.remove": {
+        status: "removed";
+    };
+    "agent.start": {
+        status: "started" | "already_running";
+        provider: string;
+        sessionId: string;
+    };
+    "agent.send": {
+        status: "sent";
+    };
+    "agent.restart": {
+        status: "restarted";
+        provider: string;
+        sessionId: string;
+    };
+    "agent.interrupt": {
+        status: "interrupted" | "no_session";
+    };
+    "agent.kill": {
+        status: "killed" | "no_session";
+    };
+    "agent.status": {
+        alive: boolean;
+        sessionId: string | null;
+        eventCount: number;
+    };
+    "agent.run-once": {
+        result: string;
+        usage: Record<string, unknown> | null;
+    };
+    "emit": {
+        id: number;
+    };
+    "permission.respond": {
+        status: "approved" | "denied";
+    };
+    "permission.pending": {
+        pending: Array<{
+            sessionId: string;
+            request: Record<string, unknown>;
+            createdAt: number;
+        }>;
+    };
+    "chat.sessions.list": {
+        sessions: Array<{
+            id: string;
+            label: string;
+            type: string;
+            meta: Record<string, unknown> | null;
+            cwd: string | null;
+            created_at: string;
+        }>;
+    };
+    "chat.sessions.create": {
+        status: "created";
+        id: string;
+        meta: Record<string, unknown> | null;
+    };
+    "chat.sessions.remove": {
+        status: "deleted";
+    };
+    "chat.messages.list": {
+        messages: unknown[];
+    };
+    "chat.messages.create": {
+        status: "created";
+        id: number;
+    };
+    "chat.messages.clear": {
+        status: "cleared";
+    };
+}
+type ApiOp = keyof ApiResponses;
+/**
+ * Type-safe JSON response for HTTP routes.
+ * Ensures the response body matches the defined shape for the operation.
+ */
+declare function httpJson<K extends ApiOp>(c: Context, _op: K, data: ApiResponses[K], status?: number): Response & hono.TypedResponse<any, any, "json">;
+/**
+ * Type-safe reply for WS handlers.
+ * Ensures the response data matches the defined shape for the operation.
+ */
+declare function wsReply<K extends ApiOp>(ws: WebSocket, msg: {
+    type: string;
+    rid?: string;
+}, data: ApiResponses[K]): void;
+
+export { type ApiOp, type ApiResponses, httpJson, wsReply };

package/dist/server/api-types.js

@@ -0,0 +1,13 @@
+function httpJson(c, _op, data, status) {
+  return c.json(data, status);
+}
+function wsReply(ws, msg, data) {
+  if (ws.readyState !== ws.OPEN) return;
+  const out = { ...data, type: msg.type };
+  if (msg.rid != null) out.rid = msg.rid;
+  ws.send(JSON.stringify(out));
+}
+export {
+  httpJson,
+  wsReply
+};

package/dist/server/index.d.ts

@@ -1,14 +1,17 @@
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 import { SessionManager } from './session-manager.js';
-export { Session, SessionInfo, SessionManagerOptions } from './session-manager.js';
+export { Session, SessionInfo, SessionLifecycleEvent, SessionLifecycleState, SessionManagerOptions, StartConfig } from './session-manager.js';
 export { eventsRoute } from './routes/events.js';
-export { emitRoute } from './routes/emit.js';
+export { createEmitRoute, emitRoute } from './routes/emit.js';
 export { createRunRoute } from './routes/run.js';
 export { createAgentRoutes } from './routes/agent.js';
 export { createChatRoutes } from './routes/chat.js';
+export { attachWebSocket } from './ws.js';
 import '../core/providers/types.js';
 import 'hono/utils/http-status';
+import 'ws';
+import 'http';
 
 interface SnaAppOptions {
     /** Commands available via GET /run?skill=<name> */

package/dist/server/index.js

@@ -2,7 +2,7 @@ import _fs from "fs";
 import _path from "path";
 import { Hono } from "hono";
 import { eventsRoute } from "./routes/events.js";
-import { emitRoute } from "./routes/emit.js";
+import { createEmitRoute } from "./routes/emit.js";
 import { createRunRoute } from "./routes/run.js";
 import { createAgentRoutes } from "./routes/agent.js";
 import { createChatRoutes } from "./routes/chat.js";
@@ -12,7 +12,7 @@ function createSnaApp(options = {}) {
   const app = new Hono();
   app.get("/health", (c) => c.json({ ok: true, name: "sna", version: "1" }));
   app.get("/events", eventsRoute);
-  app.post("/emit", emitRoute);
+  app.post("/emit", createEmitRoute(sessionManager));
   app.route("/agent", createAgentRoutes(sessionManager));
   app.route("/chat", createChatRoutes());
   if (options.runCommands) {
@@ -21,11 +21,12 @@ function createSnaApp(options = {}) {
   return app;
 }
 import { eventsRoute as eventsRoute2 } from "./routes/events.js";
-import { emitRoute as emitRoute2 } from "./routes/emit.js";
+import { emitRoute, createEmitRoute as createEmitRoute2 } from "./routes/emit.js";
 import { createRunRoute as createRunRoute2 } from "./routes/run.js";
 import { createAgentRoutes as createAgentRoutes2 } from "./routes/agent.js";
 import { createChatRoutes as createChatRoutes2 } from "./routes/chat.js";
 import { SessionManager as SessionManager2 } from "./session-manager.js";
+import { attachWebSocket } from "./ws.js";
 function snaPortRoute(c) {
   const portFile = _path.join(process.cwd(), ".sna/sna-api.port");
   try {
@@ -37,11 +38,13 @@ function snaPortRoute(c) {
 }
 export {
   SessionManager2 as SessionManager,
+  attachWebSocket,
   createAgentRoutes2 as createAgentRoutes,
   createChatRoutes2 as createChatRoutes,
+  createEmitRoute2 as createEmitRoute,
   createRunRoute2 as createRunRoute,
   createSnaApp,
-  emitRoute2 as emitRoute,
+  emitRoute,
   eventsRoute2 as eventsRoute,
   snaPortRoute
 };

package/dist/server/routes/agent.d.ts

@@ -3,6 +3,26 @@ import { Hono } from 'hono';
 import { SessionManager } from '../session-manager.js';
 import '../../core/providers/types.js';
 
+interface RunOnceOptions {
+    message: string;
+    model?: string;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    permissionMode?: string;
+    cwd?: string;
+    timeout?: number;
+    provider?: string;
+    extraArgs?: string[];
+}
+interface RunOnceResult {
+    result: string;
+    usage: Record<string, unknown> | null;
+}
+/**
+ * One-shot agent execution: create temp session → spawn → wait for result → cleanup.
+ * Used by both HTTP POST /run-once and WS agent.run-once.
+ */
+declare function runOnce(sessionManager: SessionManager, opts: RunOnceOptions): Promise<RunOnceResult>;
 declare function createAgentRoutes(sessionManager: SessionManager): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { createAgentRoutes };
+export { type RunOnceOptions, type RunOnceResult, createAgentRoutes, runOnce };