@sna-sdk/core 0.1.0 → 0.2.3

package/dist/server/routes/agent.js

@@ -5,9 +5,62 @@ import {
 } from "../../core/providers/index.js";
 import { logger } from "../../lib/logger.js";
 import { getDb } from "../../db/schema.js";
+import { httpJson } from "../api-types.js";
 function getSessionId(c) {
   return c.req.query("session") ?? "default";
 }
+const DEFAULT_RUN_ONCE_TIMEOUT = 12e4;
+async function runOnce(sessionManager, opts) {
+  const sessionId = `run-once-${crypto.randomUUID().slice(0, 8)}`;
+  const timeout = opts.timeout ?? DEFAULT_RUN_ONCE_TIMEOUT;
+  const session = sessionManager.createSession({
+    id: sessionId,
+    label: "run-once",
+    cwd: opts.cwd ?? process.cwd()
+  });
+  const provider = getProvider(opts.provider ?? "claude-code");
+  const extraArgs = opts.extraArgs ? [...opts.extraArgs] : [];
+  if (opts.systemPrompt) extraArgs.push("--system-prompt", opts.systemPrompt);
+  if (opts.appendSystemPrompt) extraArgs.push("--append-system-prompt", opts.appendSystemPrompt);
+  const proc = provider.spawn({
+    cwd: session.cwd,
+    prompt: opts.message,
+    model: opts.model ?? "claude-sonnet-4-6",
+    permissionMode: opts.permissionMode ?? "bypassPermissions",
+    env: { SNA_SESSION_ID: sessionId },
+    extraArgs: extraArgs.length > 0 ? extraArgs : void 0
+  });
+  sessionManager.setProcess(sessionId, proc);
+  try {
+    const result = await new Promise((resolve, reject) => {
+      const texts = [];
+      let usage = null;
+      const timer = setTimeout(() => {
+        reject(new Error(`run-once timed out after ${timeout}ms`));
+      }, timeout);
+      const unsub = sessionManager.onSessionEvent(sessionId, (_cursor, e) => {
+        if (e.type === "assistant" && e.message) {
+          texts.push(e.message);
+        }
+        if (e.type === "complete") {
+          clearTimeout(timer);
+          unsub();
+          usage = e.data ?? null;
+          resolve({ result: texts.join("\n"), usage });
+        }
+        if (e.type === "error") {
+          clearTimeout(timer);
+          unsub();
+          reject(new Error(e.message ?? "Agent error"));
+        }
+      });
+    });
+    return result;
+  } finally {
+    sessionManager.killSession(sessionId);
+    sessionManager.removeSession(sessionId);
+  }
+}
 function createAgentRoutes(sessionManager) {
   const app = new Hono();
   app.post("/sessions", async (c) => {
@@ -15,17 +68,18 @@ function createAgentRoutes(sessionManager) {
     try {
       const session = sessionManager.createSession({
         label: body.label,
-        cwd: body.cwd
+        cwd: body.cwd,
+        meta: body.meta
       });
       logger.log("route", `POST /sessions \u2192 created "${session.id}"`);
-      return c.json({ status: "created", sessionId: session.id, label: session.label });
+      return httpJson(c, "sessions.create", { status: "created", sessionId: session.id, label: session.label, meta: session.meta });
     } catch (e) {
       logger.err("err", `POST /sessions \u2192 ${e.message}`);
       return c.json({ status: "error", message: e.message }, 409);
     }
   });
   app.get("/sessions", (c) => {
-    return c.json({ sessions: sessionManager.listSessions() });
+    return httpJson(c, "sessions.list", { sessions: sessionManager.listSessions() });
   });
   app.delete("/sessions/:id", (c) => {
     const id = c.req.param("id");
@@ -37,18 +91,33 @@ function createAgentRoutes(sessionManager) {
       return c.json({ status: "error", message: "Session not found" }, 404);
     }
     logger.log("route", `DELETE /sessions/${id} \u2192 removed`);
-    return c.json({ status: "removed" });
+    return httpJson(c, "sessions.remove", { status: "removed" });
+  });
+  app.post("/run-once", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    if (!body.message) {
+      return c.json({ status: "error", message: "message is required" }, 400);
+    }
+    try {
+      const result = await runOnce(sessionManager, body);
+      return httpJson(c, "agent.run-once", result);
+    } catch (e) {
+      logger.err("err", `POST /run-once \u2192 ${e.message}`);
+      return c.json({ status: "error", message: e.message }, 500);
+    }
   });
   app.post("/start", async (c) => {
     const sessionId = getSessionId(c);
     const body = await c.req.json().catch(() => ({}));
-    const session = sessionManager.getOrCreateSession(sessionId);
+    const session = sessionManager.getOrCreateSession(sessionId, {
+      cwd: body.cwd
+    });
     if (session.process?.alive && !body.force) {
       logger.log("route", `POST /start?session=${sessionId} \u2192 already_running`);
-      return c.json({
+      return httpJson(c, "agent.start", {
         status: "already_running",
         provider: "claude-code",
-        sessionId: session.process.sessionId
+        sessionId: session.process.sessionId ?? session.id
       });
     }
     if (session.process?.alive) {
@@ -70,18 +139,23 @@ function createAgentRoutes(sessionManager) {
       }
     } catch {
     }
+    const providerName = body.provider ?? "claude-code";
+    const model = body.model ?? "claude-sonnet-4-6";
+    const permissionMode = body.permissionMode ?? "acceptEdits";
+    const extraArgs = body.extraArgs;
     try {
       const proc = provider.spawn({
         cwd: session.cwd,
         prompt: body.prompt,
-        model: body.model ?? "claude-sonnet-4-6",
-        permissionMode: body.permissionMode ?? "acceptEdits",
+        model,
+        permissionMode,
         env: { SNA_SESSION_ID: sessionId },
-        extraArgs: body.extraArgs
+        extraArgs
       });
       sessionManager.setProcess(sessionId, proc);
+      sessionManager.saveStartConfig(sessionId, { provider: providerName, model, permissionMode, extraArgs });
       logger.log("route", `POST /start?session=${sessionId} \u2192 started`);
-      return c.json({
+      return httpJson(c, "agent.start", {
         status: "started",
         provider: provider.name,
         sessionId: session.id
@@ -116,7 +190,7 @@ function createAgentRoutes(sessionManager) {
     sessionManager.touch(sessionId);
     logger.log("route", `POST /send?session=${sessionId} \u2192 "${body.message.slice(0, 80)}"`);
     session.process.send(body.message);
-    return c.json({ status: "sent" });
+    return httpJson(c, "agent.send", { status: "sent" });
   });
   app.get("/events", (c) => {
     const sessionId = getSessionId(c);
@@ -151,79 +225,79 @@ function createAgentRoutes(sessionManager) {
       }
     });
   });
+  app.post("/restart", async (c) => {
+    const sessionId = getSessionId(c);
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const { config } = sessionManager.restartSession(sessionId, body, (cfg) => {
+        const prov = getProvider(cfg.provider);
+        return prov.spawn({
+          cwd: sessionManager.getSession(sessionId).cwd,
+          model: cfg.model,
+          permissionMode: cfg.permissionMode,
+          env: { SNA_SESSION_ID: sessionId },
+          extraArgs: [...cfg.extraArgs ?? [], "--resume"]
+        });
+      });
+      logger.log("route", `POST /restart?session=${sessionId} \u2192 restarted`);
+      return httpJson(c, "agent.restart", {
+        status: "restarted",
+        provider: config.provider,
+        sessionId
+      });
+    } catch (e) {
+      logger.err("err", `POST /restart?session=${sessionId} \u2192 ${e.message}`);
+      return c.json({ status: "error", message: e.message }, 500);
+    }
+  });
+  app.post("/interrupt", async (c) => {
+    const sessionId = getSessionId(c);
+    const interrupted = sessionManager.interruptSession(sessionId);
+    return httpJson(c, "agent.interrupt", { status: interrupted ? "interrupted" : "no_session" });
+  });
   app.post("/kill", async (c) => {
     const sessionId = getSessionId(c);
     const killed = sessionManager.killSession(sessionId);
-    return c.json({ status: killed ? "killed" : "no_session" });
+    return httpJson(c, "agent.kill", { status: killed ? "killed" : "no_session" });
   });
   app.get("/status", (c) => {
     const sessionId = getSessionId(c);
     const session = sessionManager.getSession(sessionId);
-    return c.json({
+    return httpJson(c, "agent.status", {
       alive: session?.process?.alive ?? false,
       sessionId: session?.process?.sessionId ?? null,
       eventCount: session?.eventCounter ?? 0
     });
   });
-  const pendingPermissions = /* @__PURE__ */ new Map();
   app.post("/permission-request", async (c) => {
     const sessionId = getSessionId(c);
     const body = await c.req.json().catch(() => ({}));
     logger.log("route", `POST /permission-request?session=${sessionId} \u2192 ${body.tool_name}`);
-    const session = sessionManager.getSession(sessionId);
-    if (session) session.state = "permission";
-    const result = await new Promise((resolve) => {
-      pendingPermissions.set(sessionId, {
-        resolve,
-        request: body,
-        createdAt: Date.now()
-      });
-      setTimeout(() => {
-        if (pendingPermissions.has(sessionId)) {
-          pendingPermissions.delete(sessionId);
-          resolve(false);
-        }
-      }, 3e5);
-    });
+    const result = await sessionManager.createPendingPermission(sessionId, body);
     return c.json({ approved: result });
   });
   app.post("/permission-respond", async (c) => {
     const sessionId = getSessionId(c);
     const body = await c.req.json().catch(() => ({}));
     const approved = body.approved ?? false;
-    const pending = pendingPermissions.get(sessionId);
-    if (!pending) {
+    const resolved = sessionManager.resolvePendingPermission(sessionId, approved);
+    if (!resolved) {
       return c.json({ status: "error", message: "No pending permission request" }, 404);
     }
-    pending.resolve(approved);
-    pendingPermissions.delete(sessionId);
-    const session = sessionManager.getSession(sessionId);
-    if (session) session.state = "processing";
     logger.log("route", `POST /permission-respond?session=${sessionId} \u2192 ${approved ? "approved" : "denied"}`);
-    return c.json({ status: approved ? "approved" : "denied" });
+    return httpJson(c, "permission.respond", { status: approved ? "approved" : "denied" });
   });
   app.get("/permission-pending", (c) => {
     const sessionId = c.req.query("session");
     if (sessionId) {
-      const pending = pendingPermissions.get(sessionId);
-      if (!pending) return c.json({ pending: null });
-      return c.json({
-        pending: {
-          sessionId,
-          request: pending.request,
-          createdAt: pending.createdAt
-        }
-      });
+      const pending = sessionManager.getPendingPermission(sessionId);
+      return httpJson(c, "permission.pending", { pending: pending ? [{ sessionId, ...pending }] : [] });
     }
-    const all = Array.from(pendingPermissions.entries()).map(([id, p]) => ({
-      sessionId: id,
-      request: p.request,
-      createdAt: p.createdAt
-    }));
-    return c.json({ pending: all });
+    return httpJson(c, "permission.pending", { pending: sessionManager.getAllPendingPermissions() });
   });
   return app;
 }
 export {
-  createAgentRoutes
+  createAgentRoutes,
+  runOnce
 };

package/dist/server/routes/chat.js

@@ -1,14 +1,19 @@
 import { Hono } from "hono";
 import { getDb } from "../../db/schema.js";
+import { httpJson } from "../api-types.js";
 function createChatRoutes() {
   const app = new Hono();
   app.get("/sessions", (c) => {
     try {
       const db = getDb();
-      const sessions = db.prepare(
-        `SELECT id, label, type, created_at FROM chat_sessions ORDER BY created_at DESC`
+      const rows = db.prepare(
+        `SELECT id, label, type, meta, cwd, created_at FROM chat_sessions ORDER BY created_at DESC`
       ).all();
-      return c.json({ sessions });
+      const sessions = rows.map((r) => ({
+        ...r,
+        meta: r.meta ? JSON.parse(r.meta) : null
+      }));
+      return httpJson(c, "chat.sessions.list", { sessions });
     } catch (e) {
       return c.json({ status: "error", message: e.message, stack: e.stack }, 500);
     }
@@ -19,9 +24,9 @@ function createChatRoutes() {
     try {
       const db = getDb();
       db.prepare(
-        `INSERT OR IGNORE INTO chat_sessions (id, label, type) VALUES (?, ?, ?)`
-      ).run(id, body.label ?? id, body.type ?? "background");
-      return c.json({ status: "created", id });
+        `INSERT OR IGNORE INTO chat_sessions (id, label, type, meta) VALUES (?, ?, ?, ?)`
+      ).run(id, body.label ?? id, body.type ?? "background", body.meta ? JSON.stringify(body.meta) : null);
+      return httpJson(c, "chat.sessions.create", { status: "created", id, meta: body.meta ?? null });
     } catch (e) {
       return c.json({ status: "error", message: e.message }, 500);
     }
@@ -34,7 +39,7 @@ function createChatRoutes() {
     try {
       const db = getDb();
       db.prepare(`DELETE FROM chat_sessions WHERE id = ?`).run(id);
-      return c.json({ status: "deleted" });
+      return httpJson(c, "chat.sessions.remove", { status: "deleted" });
     } catch (e) {
       return c.json({ status: "error", message: e.message }, 500);
     }
@@ -46,7 +51,7 @@ function createChatRoutes() {
       const db = getDb();
       const query = sinceParam ? db.prepare(`SELECT * FROM chat_messages WHERE session_id = ? AND id > ? ORDER BY id ASC`) : db.prepare(`SELECT * FROM chat_messages WHERE session_id = ? ORDER BY id ASC`);
       const messages = sinceParam ? query.all(id, parseInt(sinceParam, 10)) : query.all(id);
-      return c.json({ messages });
+      return httpJson(c, "chat.messages.list", { messages });
     } catch (e) {
       return c.json({ status: "error", message: e.message, stack: e.stack }, 500);
     }
@@ -69,7 +74,7 @@ function createChatRoutes() {
         body.skill_name ?? null,
         body.meta ? JSON.stringify(body.meta) : null
       );
-      return c.json({ status: "created", id: result.lastInsertRowid });
+      return httpJson(c, "chat.messages.create", { status: "created", id: Number(result.lastInsertRowid) });
     } catch (e) {
       return c.json({ status: "error", message: e.message }, 500);
     }
@@ -79,7 +84,7 @@ function createChatRoutes() {
     try {
       const db = getDb();
       db.prepare(`DELETE FROM chat_messages WHERE session_id = ?`).run(id);
-      return c.json({ status: "cleared" });
+      return httpJson(c, "chat.messages.clear", { status: "cleared" });
     } catch (e) {
       return c.json({ status: "error", message: e.message }, 500);
     }

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

@@ -1,11 +1,21 @@
 import * as hono_utils_http_status from 'hono/utils/http-status';
 import * as hono from 'hono';
 import { Context } from 'hono';
+import { SessionManager } from '../session-manager.js';
+import '../../core/providers/types.js';
 
+/**
+ * Create an emit route handler that broadcasts to WS subscribers.
+ */
+declare function createEmitRoute(sessionManager: SessionManager): (c: Context) => Promise<Response & hono.TypedResponse<any, any, "json">>;
+/**
+ * Legacy plain handler (no broadcast). Kept for backward compatibility
+ * when consumers import emitRoute directly without SessionManager.
+ */
 declare function emitRoute(c: Context): Promise<(Response & hono.TypedResponse<{
     error: string;
 }, 400, "json">) | (Response & hono.TypedResponse<{
     id: number;
 }, hono_utils_http_status.ContentfulStatusCode, "json">)>;
 
-export { emitRoute };
+export { createEmitRoute, emitRoute };

package/dist/server/routes/emit.js

@@ -1,4 +1,29 @@
 import { getDb } from "../../db/schema.js";
+import { httpJson } from "../api-types.js";
+function createEmitRoute(sessionManager) {
+  return async (c) => {
+    const body = await c.req.json();
+    const { skill, type, message, data, session_id } = body;
+    if (!skill || !type || !message) {
+      return c.json({ error: "missing fields" }, 400);
+    }
+    const db = getDb();
+    const result = db.prepare(
+      `INSERT INTO skill_events (session_id, skill, type, message, data) VALUES (?, ?, ?, ?, ?)`
+    ).run(session_id ?? null, skill, type, message, data ?? null);
+    const id = Number(result.lastInsertRowid);
+    sessionManager.broadcastSkillEvent({
+      id,
+      session_id: session_id ?? null,
+      skill,
+      type,
+      message,
+      data: data ?? null,
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return httpJson(c, "emit", { id });
+  };
+}
 async function emitRoute(c) {
   const { skill, type, message, data } = await c.req.json();
   if (!skill || !type || !message) {
@@ -11,5 +36,6 @@ async function emitRoute(c) {
   return c.json({ id: result.lastInsertRowid });
 }
 export {
+  createEmitRoute,
   emitRoute
 };

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

@@ -8,6 +8,12 @@ import { AgentProcess, AgentEvent } from '../core/providers/types.js';
  */
 
 type SessionState = "idle" | "processing" | "waiting" | "permission";
+interface StartConfig {
+    provider: string;
+    model: string;
+    permissionMode: string;
+    extraArgs?: string[];
+}
 interface Session {
     id: string;
     process: AgentProcess | null;
@@ -15,7 +21,9 @@ interface Session {
     eventCounter: number;
     label: string;
     cwd: string;
+    meta: Record<string, unknown> | null;
     state: SessionState;
+    lastStartConfig: StartConfig | null;
     createdAt: number;
     lastActivityAt: number;
 }
@@ -25,6 +33,7 @@ interface SessionInfo {
     alive: boolean;
     state: SessionState;
     cwd: string;
+    meta: Record<string, unknown> | null;
     eventCount: number;
     createdAt: number;
     lastActivityAt: number;
@@ -32,15 +41,31 @@ interface SessionInfo {
 interface SessionManagerOptions {
     maxSessions?: number;
 }
+type SessionLifecycleState = "started" | "killed" | "exited" | "crashed" | "restarted";
+interface SessionLifecycleEvent {
+    session: string;
+    state: SessionLifecycleState;
+    code?: number | null;
+}
 declare class SessionManager {
     private sessions;
     private maxSessions;
+    private eventListeners;
+    private pendingPermissions;
+    private skillEventListeners;
+    private permissionRequestListeners;
+    private lifecycleListeners;
     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. */
     createSession(opts?: {
         id?: string;
         label?: string;
         cwd?: string;
+        meta?: Record<string, unknown> | null;
     }): Session;
     /** Get a session by ID. */
     getSession(id: string): Session | undefined;
@@ -51,6 +76,41 @@ declare class SessionManager {
     }): Session;
     /** Set the agent process for a session. Subscribes to events. */
     setProcess(sessionId: string, proc: AgentProcess): void;
+    /** Subscribe to real-time events for a session. Returns unsubscribe function. */
+    onSessionEvent(sessionId: string, cb: (cursor: number, event: AgentEvent) => void): () => void;
+    /** Subscribe to skill events broadcast. Returns unsubscribe function. */
+    onSkillEvent(cb: (event: Record<string, unknown>) => void): () => void;
+    /** Broadcast a skill event to all subscribers (called after DB insert). */
+    broadcastSkillEvent(event: Record<string, unknown>): void;
+    /** Subscribe to permission request notifications. Returns unsubscribe function. */
+    onPermissionRequest(cb: (sessionId: string, request: Record<string, unknown>, createdAt: number) => void): () => void;
+    /** Subscribe to session lifecycle events (started/killed/exited/crashed). Returns unsubscribe function. */
+    onSessionLifecycle(cb: (event: SessionLifecycleEvent) => void): () => void;
+    private emitLifecycle;
+    /** Create a pending permission request. Returns a promise that resolves when approved/denied. */
+    createPendingPermission(sessionId: string, request: Record<string, unknown>): Promise<boolean>;
+    /** Resolve a pending permission request. Returns false if no pending request. */
+    resolvePendingPermission(sessionId: string, approved: boolean): boolean;
+    /** Get a pending permission for a specific session. */
+    getPendingPermission(sessionId: string): {
+        request: Record<string, unknown>;
+        createdAt: number;
+    } | null;
+    /** Get all pending permissions across sessions. */
+    getAllPendingPermissions(): Array<{
+        sessionId: string;
+        request: Record<string, unknown>;
+        createdAt: number;
+    }>;
+    /** Kill the agent process in a session (session stays, can be restarted). */
+    /** Save the start config for a session (called by start handlers). */
+    saveStartConfig(id: string, config: StartConfig): void;
+    /** Restart session: kill → re-spawn with merged config + --resume. */
+    restartSession(id: string, overrides: Partial<StartConfig>, spawnFn: (config: StartConfig) => AgentProcess): {
+        config: StartConfig;
+    };
+    /** Interrupt the current turn (SIGINT). Process stays alive, returns to waiting. */
+    interruptSession(id: string): boolean;
     /** Kill the agent process in a session (session stays, can be restarted). */
     killSession(id: string): boolean;
     /** Remove a session entirely. Cannot remove "default". */
@@ -66,4 +126,4 @@ declare class SessionManager {
     get size(): number;
 }
 
-export { type Session, type SessionInfo, SessionManager, type SessionManagerOptions, type SessionState };
+export { type Session, type SessionInfo, type SessionLifecycleEvent, type SessionLifecycleState, SessionManager, type SessionManagerOptions, type SessionState, type StartConfig };