@sna-sdk/core 0.0.10 → 0.1.0

package/README.md

@@ -5,9 +5,10 @@ Server runtime for [Skills-Native Applications](https://github.com/neuradex/sna)
 ## What's included
 
 - **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
-- **Lifecycle CLI** — `sna api:up`, `sna api:down`
+- **Lifecycle CLI** — `sna api:up`, `sna api:down`, `sna dispatch`, `sna validate`
 - **Agent providers** — Claude Code and Codex process management
 
 ## Install
@@ -18,7 +19,29 @@ npm install @sna-sdk/core
 
 ## Usage
 
-### Emit skill events
+### Dispatch skill events (recommended)
+
+```bash
+# CLI
+ID=$(sna dispatch open --skill my-skill)
+sna dispatch $ID start --message "Starting..."
+sna dispatch $ID milestone --message "Step done"
+sna dispatch $ID close --message "Done."
+```
+
+```typescript
+// Programmatic
+import { createDispatchHandle } from "@sna-sdk/core";
+
+const h = createDispatchHandle({ skill: "my-skill" });
+h.start("Starting...");
+h.milestone("Step done");
+await h.close();
+```
+
+### Emit skill events (legacy, deprecated)
+
+> Use `sna dispatch` instead. `emit.js` remains for backward compatibility.
 
 ```bash
 node node_modules/@sna-sdk/core/dist/scripts/emit.js \
@@ -48,7 +71,7 @@ const db = getDb(); // SQLite instance (data/sna.db)
 
 | Import path | Contents |
 |-------------|----------|
-| `@sna-sdk/core` | `DEFAULT_SNA_PORT`, `DEFAULT_SNA_URL`, types |
+| `@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/providers` | Agent provider factory, `ClaudeCodeProvider` |

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

@@ -228,12 +228,47 @@ 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 sdkSettings = {};
+    if (options.permissionMode !== "bypassPermissions") {
+      sdkSettings.hooks = {
+        PreToolUse: [{
+          matcher: ".*",
+          hooks: [{ type: "command", command: `node "${hookScript}"` }]
+        }]
+      };
+    }
+    let extraArgsClean = options.extraArgs ? [...options.extraArgs] : [];
+    const settingsIdx = extraArgsClean.indexOf("--settings");
+    if (settingsIdx !== -1 && settingsIdx + 1 < extraArgsClean.length) {
+      try {
+        const appSettings = JSON.parse(extraArgsClean[settingsIdx + 1]);
+        if (appSettings.hooks) {
+          for (const [event, hooks] of Object.entries(appSettings.hooks)) {
+            if (sdkSettings.hooks && sdkSettings.hooks[event]) {
+              sdkSettings.hooks[event] = [
+                ...sdkSettings.hooks[event],
+                ...hooks
+              ];
+            } else {
+              sdkSettings.hooks[event] = hooks;
+            }
+          }
+          delete appSettings.hooks;
+        }
+        Object.assign(sdkSettings, appSettings);
+      } catch {
+      }
+      extraArgsClean.splice(settingsIdx, 2);
+    }
     const args = [
       "--output-format",
       "stream-json",
       "--input-format",
       "stream-json",
-      "--verbose"
+      "--verbose",
+      "--settings",
+      JSON.stringify(sdkSettings)
     ];
     if (options.model) {
       args.push("--model", options.model);
@@ -241,6 +276,9 @@ class ClaudeCodeProvider {
     if (options.permissionMode) {
       args.push("--permission-mode", options.permissionMode);
     }
+    if (extraArgsClean.length > 0) {
+      args.push(...extraArgsClean);
+    }
     const cleanEnv = { ...process.env, ...options.env };
     delete cleanEnv.CLAUDECODE;
     delete cleanEnv.CLAUDE_CODE_ENTRYPOINT;
@@ -250,7 +288,7 @@ class ClaudeCodeProvider {
       env: cleanEnv,
       stdio: ["pipe", "pipe", "pipe"]
     });
-    logger.log("agent", `spawned claude-code (pid=${proc.pid})`);
+    logger.log("agent", `spawned claude-code (pid=${proc.pid}) \u2192 ${claudePath} ${args.join(" ")}`);
     return new ClaudeCodeProcess(proc, options);
   }
 }

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

@@ -36,6 +36,11 @@ interface SpawnOptions {
     model?: string;
     permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan";
     env?: Record<string, string>;
+    /**
+     * Additional CLI flags passed directly to the agent binary.
+     * e.g. ["--system-prompt", "You are...", "--append-system-prompt", "Also...", "--mcp-config", "path"]
+     */
+    extraArgs?: string[];
 }
 /**
  * Agent provider interface. Each backend (Claude Code, Codex, etc.)

package/dist/db/schema.js

@@ -1,11 +1,14 @@
 import { createRequire } from "node:module";
+import fs from "fs";
 import path from "path";
-const require2 = createRequire(path.join(process.cwd(), "node_modules", "_"));
-const BetterSqlite3 = require2("better-sqlite3");
 const DB_PATH = path.join(process.cwd(), "data/sna.db");
 let _db = null;
 function getDb() {
   if (!_db) {
+    const req = createRequire(import.meta.url);
+    const BetterSqlite3 = req("better-sqlite3");
+    const dir = path.dirname(DB_PATH);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     _db = new BetterSqlite3(DB_PATH);
     _db.pragma("journal_mode = WAL");
     initSchema(_db);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ChatMessage, ChatSession, SkillEvent } from './db/schema.js';
 export { AgentEvent, AgentProcess, AgentProvider, SpawnOptions } from './core/providers/types.js';
-export { Session, SessionInfo, SessionManagerOptions } from './server/session-manager.js';
+export { Session, SessionInfo, SessionManagerOptions, SessionState } from './server/session-manager.js';
+export { DispatchCloseOptions, DispatchEventType, DispatchOpenOptions, DispatchOpenResult, DispatchSendOptions, createHandle as createDispatchHandle, close as dispatchClose, open as dispatchOpen, send as dispatchSend } from './lib/dispatch.js';
 import 'better-sqlite3';
 
 /**

package/dist/index.js

@@ -1,6 +1,11 @@
 const DEFAULT_SNA_PORT = 3099;
 const DEFAULT_SNA_URL = `http://localhost:${DEFAULT_SNA_PORT}`;
+import { open, send, close, createHandle } from "./lib/dispatch.js";
 export {
   DEFAULT_SNA_PORT,
-  DEFAULT_SNA_URL
+  DEFAULT_SNA_URL,
+  createHandle as createDispatchHandle,
+  close as dispatchClose,
+  open as dispatchOpen,
+  send as dispatchSend
 };

package/dist/lib/dispatch.d.ts

@@ -0,0 +1,77 @@
+/**
+ * dispatch.ts — Unified event dispatcher for SNA.
+ *
+ * Single entry point for all skill lifecycle events.
+ * Used by both CLI (`sna dispatch`) and SDK (programmatic).
+ *
+ * Lifecycle:
+ *   dispatch.open({ skill }) → id       (validate + create session, no event written)
+ *   dispatch.send(id, { type, message }) (write event to DB)
+ *   dispatch.close(id)                   (complete + kill session)
+ *   dispatch.close(id, { error })        (error + kill session)
+ *
+ * Responsibilities:
+ *   - Validate skill name against .sna/skills.json (fallback: SKILL.md existence)
+ *   - Write events to SQLite (skill_events table)
+ *   - On close: notify SNA API server to kill background session
+ */
+interface DispatchOpenOptions {
+    skill: string;
+    sessionId?: string;
+    cwd?: string;
+}
+interface DispatchOpenResult {
+    id: string;
+    skill: string;
+    sessionId: string | null;
+}
+type DispatchEventType = "called" | "start" | "progress" | "milestone" | "permission_needed";
+interface DispatchSendOptions {
+    type: DispatchEventType;
+    message: string;
+    data?: string;
+}
+interface DispatchCloseOptions {
+    error?: string;
+    message?: string;
+}
+interface DispatchSession {
+    id: string;
+    skill: string;
+    sessionId: string | null;
+    cwd: string;
+    closed: boolean;
+}
+declare const SEND_TYPES: readonly string[];
+declare function loadSkillsManifest(cwd: string): Record<string, unknown> | null;
+/**
+ * Open a dispatch session. Validates skill name, creates session.
+ * Does NOT write any event — caller decides what to send first.
+ */
+declare function open(opts: DispatchOpenOptions): DispatchOpenResult;
+/**
+ * Send an event within an open dispatch session.
+ */
+declare function send(id: string, opts: DispatchSendOptions): void;
+/**
+ * Close a dispatch session. Emits terminal events and triggers cleanup.
+ */
+declare function close(id: string, opts?: DispatchCloseOptions): Promise<void>;
+/**
+ * Get an active dispatch session (for internal inspection).
+ */
+declare function getSession(id: string): DispatchSession | undefined;
+/**
+ * Convenience: create a dispatch handle with chainable methods.
+ */
+declare function createHandle(opts: DispatchOpenOptions): {
+    id: string;
+    skill: string;
+    called: (message: string) => void;
+    start: (message: string) => void;
+    progress: (message: string) => void;
+    milestone: (message: string) => void;
+    close: (closeOpts?: DispatchCloseOptions) => Promise<void>;
+};
+
+export { type DispatchCloseOptions, type DispatchEventType, type DispatchOpenOptions, type DispatchOpenResult, type DispatchSendOptions, SEND_TYPES, close, createHandle, getSession, loadSkillsManifest, open, send };

package/dist/lib/dispatch.js

@@ -0,0 +1,159 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { getDb } from "../db/schema.js";
+const activeSessions = /* @__PURE__ */ new Map();
+const SEND_TYPES = [
+  "called",
+  "start",
+  "progress",
+  "milestone",
+  "permission_needed"
+];
+function loadSkillsManifest(cwd) {
+  const manifestPath = path.join(cwd, ".sna/skills.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function skillMdExists(cwd, skill) {
+  return fs.existsSync(path.join(cwd, ".claude/skills", skill, "SKILL.md"));
+}
+function generateId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+function writeEvent(sessionId, skill, type, message, data) {
+  const db = getDb();
+  db.prepare(`
+    INSERT INTO skill_events (session_id, skill, type, message, data)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(sessionId, skill, type, message, data ?? null);
+}
+async function notifySessionClose(cwd, sessionId) {
+  if (!sessionId) return;
+  try {
+    const port = fs.readFileSync(path.join(cwd, ".sna/sna-api.port"), "utf8").trim();
+    if (!port) return;
+    await fetch(`http://localhost:${port}/agent/kill?session=${encodeURIComponent(sessionId)}`, {
+      method: "POST",
+      signal: AbortSignal.timeout(3e3)
+    });
+  } catch {
+  }
+}
+const PREFIX = {
+  called: "\u2192",
+  start: "\u25B6",
+  progress: "\xB7",
+  milestone: "\u25C6",
+  permission_needed: "\u26A0",
+  complete: "\u2713",
+  error: "\u2717",
+  success: "\u2713",
+  failed: "\u2717"
+};
+function log(skill, type, message) {
+  const p = PREFIX[type] ?? "\xB7";
+  console.log(`${p} [${skill}] ${message}`);
+}
+function open(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const manifest = loadSkillsManifest(cwd);
+  if (manifest) {
+    if (!(opts.skill in manifest)) {
+      if (skillMdExists(cwd, opts.skill)) {
+        console.warn(
+          `\u26A0 Skill "${opts.skill}" has SKILL.md but is not in .sna/skills.json \u2014 run 'sna gen client'`
+        );
+      } else {
+        const available = Object.keys(manifest).join(", ");
+        throw new Error(
+          `Unknown skill: "${opts.skill}". Available: ${available}.`
+        );
+      }
+    }
+  } else {
+    if (!skillMdExists(cwd, opts.skill)) {
+      throw new Error(
+        `Unknown skill: "${opts.skill}". No .sna/skills.json and no SKILL.md found.`
+      );
+    }
+  }
+  const id = generateId();
+  const sessionId = opts.sessionId ?? process.env.SNA_SESSION_ID ?? null;
+  const session = {
+    id,
+    skill: opts.skill,
+    sessionId,
+    cwd,
+    closed: false
+  };
+  activeSessions.set(id, session);
+  return { id, skill: opts.skill, sessionId };
+}
+function send(id, opts) {
+  const session = activeSessions.get(id);
+  if (!session) {
+    throw new Error(`Dispatch session "${id}" not found. Call dispatch.open() first.`);
+  }
+  if (session.closed) {
+    throw new Error(`Dispatch session "${id}" is already closed.`);
+  }
+  if (!SEND_TYPES.includes(opts.type)) {
+    throw new Error(
+      `Invalid event type: "${opts.type}". Must be one of: ${SEND_TYPES.join(", ")}`
+    );
+  }
+  writeEvent(session.sessionId, session.skill, opts.type, opts.message, opts.data);
+  log(session.skill, opts.type, opts.message);
+}
+async function close(id, opts) {
+  const session = activeSessions.get(id);
+  if (!session) {
+    throw new Error(`Dispatch session "${id}" not found.`);
+  }
+  if (session.closed) {
+    throw new Error(`Dispatch session "${id}" is already closed.`);
+  }
+  session.closed = true;
+  if (opts?.error) {
+    const message = opts.error;
+    writeEvent(session.sessionId, session.skill, "error", message);
+    writeEvent(session.sessionId, session.skill, "failed", message);
+    log(session.skill, "error", message);
+  } else {
+    const message = opts?.message ?? "Done";
+    writeEvent(session.sessionId, session.skill, "complete", message);
+    writeEvent(session.sessionId, session.skill, "success", message);
+    log(session.skill, "complete", message);
+  }
+  await notifySessionClose(session.cwd, session.sessionId);
+  activeSessions.delete(id);
+}
+function getSession(id) {
+  return activeSessions.get(id);
+}
+function createHandle(opts) {
+  const result = open(opts);
+  return {
+    id: result.id,
+    skill: result.skill,
+    called: (message) => send(result.id, { type: "called", message }),
+    start: (message) => send(result.id, { type: "start", message }),
+    progress: (message) => send(result.id, { type: "progress", message }),
+    milestone: (message) => send(result.id, { type: "milestone", message }),
+    close: (closeOpts) => close(result.id, closeOpts)
+  };
+}
+export {
+  SEND_TYPES,
+  close,
+  createHandle,
+  getSession,
+  loadSkillsManifest,
+  open,
+  send
+};

package/dist/lib/parse-flags.d.ts

@@ -0,0 +1,12 @@
+/**
+ * parse-flags.ts — Shared CLI flag parser for SNA scripts.
+ *
+ * Parses --key value pairs from argv-style arrays.
+ */
+/**
+ * Parse --key value pairs from an argument array.
+ * Handles --flag (without value) by setting it to "true".
+ */
+declare function parseFlags(args: string[]): Record<string, string>;
+
+export { parseFlags };

package/dist/lib/parse-flags.js

@@ -0,0 +1,20 @@
+function parseFlags(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg?.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = "true";
+      }
+    }
+  }
+  return result;
+}
+export {
+  parseFlags
+};

package/dist/scripts/emit.js

@@ -1,51 +1,29 @@
-import { getDb } from "../db/schema.js";
-function parseArgs(args2) {
-  const result = {};
-  for (let i = 0; i < args2.length; i += 2) {
-    const key = args2[i]?.replace(/^--/, "");
-    if (key) result[key] = args2[i + 1] ?? "";
-  }
-  return result;
-}
+import { open, send, close, SEND_TYPES } from "../lib/dispatch.js";
+import { parseFlags } from "../lib/parse-flags.js";
 const [, , ...args] = process.argv;
-const flags = parseArgs(args);
-const VALID_TYPES = [
-  "called",
-  "success",
-  "failed",
-  "permission_needed",
-  "start",
-  "progress",
-  "milestone",
-  "complete",
-  "error"
-];
+const flags = parseFlags(args);
+const CLOSE_SUCCESS_TYPES = ["complete", "success"];
+const CLOSE_ERROR_TYPES = ["error", "failed"];
 if (!flags.skill || !flags.type || !flags.message) {
-  console.error("Usage: tsx node_modules/@sna-sdk/core/src/scripts/emit.ts --skill <name> --type <type> --message <text> [--data <json>]");
-  process.exit(1);
-}
-if (!VALID_TYPES.includes(flags.type)) {
-  console.error(`Invalid type: ${flags.type}. Must be one of: ${VALID_TYPES.join(", ")}`);
+  console.error("DEPRECATED: Use 'sna dispatch' instead.");
+  console.error("Usage: node emit.js --skill <name> --type <type> --message <text>");
   process.exit(1);
 }
-const sessionId = process.env.SNA_SESSION_ID;
-if (sessionId) {
-  const db = getDb();
-  db.prepare(`
-    INSERT INTO skill_events (session_id, skill, type, message, data)
-    VALUES (?, ?, ?, ?, ?)
-  `).run(sessionId, flags.skill, flags.type, flags.message, flags.data ?? null);
-}
-const prefix = {
-  called: "\u2192",
-  success: "\u2713",
-  failed: "\u2717",
-  permission_needed: "\u26A0",
-  start: "\u25B6",
-  progress: "\xB7",
-  milestone: "\u25C6",
-  complete: "\u2713",
-  error: "\u2717"
-};
-const p = prefix[flags.type] ?? "\xB7";
-console.log(`${p} [${flags.skill}] ${flags.message}`);
+(async () => {
+  try {
+    const d = open({ skill: flags.skill });
+    if (SEND_TYPES.includes(flags.type)) {
+      send(d.id, { type: flags.type, message: flags.message, data: flags.data });
+    } else if (CLOSE_SUCCESS_TYPES.includes(flags.type)) {
+      await close(d.id, { message: flags.message });
+    } else if (CLOSE_ERROR_TYPES.includes(flags.type)) {
+      await close(d.id, { error: flags.message });
+    } else {
+      console.error(`Unknown type: ${flags.type}`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`\u2717 ${err.message}`);
+    process.exit(1);
+  }
+})();

package/dist/scripts/gen-client.js

@@ -1,15 +1,8 @@
 import fs from "fs";
 import path from "path";
 import { scanSkills } from "../lib/skill-parser.js";
+import { parseFlags } from "../lib/parse-flags.js";
 const ROOT = process.cwd();
-function parseFlags(args) {
-  const flags2 = {};
-  for (let i = 0; i < args.length; i += 2) {
-    const key = args[i]?.replace(/^--/, "");
-    if (key) flags2[key] = args[i + 1] ?? "";
-  }
-  return flags2;
-}
 function tsType(argDef) {
   switch (argDef.type) {
     case "number":
@@ -106,7 +99,16 @@ const code = generateClient(schemas);
 const outDir = path.dirname(outPath);
 if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
 fs.writeFileSync(outPath, code);
+const snaDir = path.join(ROOT, ".sna");
+if (!fs.existsSync(snaDir)) fs.mkdirSync(snaDir, { recursive: true });
+const skillsManifest = {};
+for (const s of schemas) {
+  skillsManifest[s.name] = { description: s.description, args: s.args };
+}
+const manifestPath = path.join(snaDir, "skills.json");
+fs.writeFileSync(manifestPath, JSON.stringify(skillsManifest, null, 2) + "\n");
 console.log(`\u2713 Generated ${outPath}`);
+console.log(`\u2713 Generated ${manifestPath}`);
 console.log(`  ${schemas.length} skills:`);
 for (const s of schemas) {
   const argCount = Object.keys(s.args).length;

package/dist/scripts/hook.js

@@ -1,34 +1,61 @@
-import { getDb } from "../db/schema.js";
+import fs from "fs";
+import path from "path";
 const chunks = [];
 process.stdin.on("data", (chunk) => chunks.push(chunk));
-process.stdin.on("end", () => {
+process.stdin.on("end", async () => {
   try {
     const raw = Buffer.concat(chunks).toString().trim();
-    if (!raw) process.exit(0);
+    if (!raw) {
+      allow();
+      return;
+    }
     const input = JSON.parse(raw);
     const toolName = input.tool_name ?? "unknown";
-    const toolInput = input.tool_input ?? {};
-    const db = getDb();
-    const latestCalled = db.prepare(`
-      SELECT skill FROM skill_events
-      WHERE type = 'called'
-        AND id > COALESCE(
-          (SELECT MAX(id) FROM skill_events WHERE type IN ('success', 'failed')),
-          0
-        )
-      ORDER BY id DESC LIMIT 1
-    `).get();
-    const skillName = latestCalled?.skill ?? "system";
-    const summary = toolName === "Bash" ? String(toolInput.command ?? "").slice(0, 120) : toolName === "Write" ? String(toolInput.file_path ?? "") : toolName === "Edit" || toolName === "MultiEdit" ? String(toolInput.file_path ?? "") : JSON.stringify(toolInput).slice(0, 120);
-    db.prepare(
-      `INSERT INTO skill_events (skill, type, message, data) VALUES (?, ?, ?, ?)`
-    ).run(
-      skillName,
-      "permission_needed",
-      `${toolName}: ${summary}`,
-      JSON.stringify({ tool_name: toolName, tool_input: toolInput })
-    );
+    const safeTools = ["Read", "Glob", "Grep", "Agent", "TodoRead", "TodoWrite"];
+    if (safeTools.includes(toolName)) {
+      allow();
+      return;
+    }
+    const portFile = path.join(process.cwd(), ".sna/sna-api.port");
+    let port;
+    try {
+      port = fs.readFileSync(portFile, "utf8").trim();
+    } catch {
+      allow();
+      return;
+    }
+    const sessionId = process.env.SNA_SESSION_ID ?? "default";
+    const apiUrl = `http://localhost:${port}`;
+    const res = await fetch(`${apiUrl}/agent/permission-request?session=${encodeURIComponent(sessionId)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        tool_name: input.tool_name,
+        tool_input: input.tool_input
+      }),
+      signal: AbortSignal.timeout(3e5)
+      // 5 min timeout
+    });
+    const data = await res.json();
+    if (data.approved) {
+      allow();
+    } else {
+      deny("User denied this tool execution");
+    }
   } catch {
+    allow();
   }
-  process.exit(0);
 });
+function allow() {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow"
+    }
+  }));
+  process.exit(0);
+}
+function deny(reason) {
+  process.stderr.write(reason);
+  process.exit(2);
+}