@sna-sdk/core 0.1.1 → 0.3.0

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

@@ -0,0 +1,120 @@
+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.set-model": {
+        status: "updated" | "no_session";
+        model: string;
+    };
+    "agent.set-permission-mode": {
+        status: "updated" | "no_session";
+        permissionMode: string;
+    };
+    "agent.kill": {
+        status: "killed" | "no_session";
+    };
+    "agent.status": {
+        alive: boolean;
+        sessionId: string | null;
+        ccSessionId: string | null;
+        eventCount: number;
+        config: {
+            provider: string;
+            model: string;
+            permissionMode: string;
+            extraArgs?: string[];
+        } | null;
+    };
+    "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/image-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Image storage — saves base64 images to disk and serves them.
+ *
+ * Storage path: data/images/{sessionId}/{hash}.{ext}
+ * Retrieve via: GET /chat/images/:sessionId/:filename
+ */
+interface SavedImage {
+    filename: string;
+    path: string;
+}
+/**
+ * Save base64 images to disk. Returns filenames for meta storage.
+ */
+declare function saveImages(sessionId: string, images: Array<{
+    base64: string;
+    mimeType: string;
+}>): string[];
+/**
+ * Resolve an image file path. Returns null if not found.
+ */
+declare function resolveImagePath(sessionId: string, filename: string): string | null;
+
+export { type SavedImage, resolveImagePath, saveImages };

package/dist/server/image-store.js

@@ -0,0 +1,34 @@
+import fs from "fs";
+import path from "path";
+import { createHash } from "crypto";
+const IMAGE_DIR = path.join(process.cwd(), "data/images");
+const MIME_TO_EXT = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/svg+xml": "svg"
+};
+function saveImages(sessionId, images) {
+  const dir = path.join(IMAGE_DIR, sessionId);
+  fs.mkdirSync(dir, { recursive: true });
+  return images.map((img) => {
+    const ext = MIME_TO_EXT[img.mimeType] ?? "bin";
+    const hash = createHash("sha256").update(img.base64).digest("hex").slice(0, 12);
+    const filename = `${hash}.${ext}`;
+    const filePath = path.join(dir, filename);
+    if (!fs.existsSync(filePath)) {
+      fs.writeFileSync(filePath, Buffer.from(img.base64, "base64"));
+    }
+    return filename;
+  });
+}
+function resolveImagePath(sessionId, filename) {
+  if (filename.includes("..") || filename.includes("/")) return null;
+  const filePath = path.join(IMAGE_DIR, sessionId, filename);
+  return fs.existsSync(filePath) ? filePath : null;
+}
+export {
+  resolveImagePath,
+  saveImages
+};

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, SessionConfigChangedEvent, 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 };

package/dist/server/routes/agent.js

@@ -5,9 +5,63 @@ import {
 } from "../../core/providers/index.js";
 import { logger } from "../../lib/logger.js";
 import { getDb } from "../../db/schema.js";
+import { httpJson } from "../api-types.js";
+import { saveImages } from "../image-store.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
+  });
+  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) => {
@@ -18,22 +72,15 @@ function createAgentRoutes(sessionManager) {
         cwd: body.cwd,
         meta: body.meta
       });
-      try {
-        const db = getDb();
-        db.prepare(
-          `INSERT OR IGNORE INTO chat_sessions (id, label, type, meta) VALUES (?, ?, 'main', ?)`
-        ).run(session.id, session.label, session.meta ? JSON.stringify(session.meta) : null);
-      } catch {
-      }
       logger.log("route", `POST /sessions \u2192 created "${session.id}"`);
-      return c.json({ status: "created", sessionId: session.id, label: session.label, meta: session.meta });
+      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");
@@ -45,18 +92,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) {
@@ -78,18 +140,24 @@ 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
+        history: body.history,
+        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
@@ -110,21 +178,39 @@ function createAgentRoutes(sessionManager) {
       );
     }
     const body = await c.req.json().catch(() => ({}));
-    if (!body.message) {
+    if (!body.message && !body.images?.length) {
       logger.err("err", `POST /send?session=${sessionId} \u2192 empty message`);
-      return c.json({ status: "error", message: "message is required" }, 400);
+      return c.json({ status: "error", message: "message or images required" }, 400);
+    }
+    const textContent = body.message ?? "(image)";
+    let meta = body.meta ? { ...body.meta } : {};
+    if (body.images?.length) {
+      const filenames = saveImages(sessionId, body.images);
+      meta.images = filenames;
     }
     try {
       const db = getDb();
       db.prepare(`INSERT OR IGNORE INTO chat_sessions (id, label, type) VALUES (?, ?, 'main')`).run(sessionId, session.label ?? sessionId);
-      db.prepare(`INSERT INTO chat_messages (session_id, role, content, meta) VALUES (?, 'user', ?, ?)`).run(sessionId, body.message, body.meta ? JSON.stringify(body.meta) : null);
+      db.prepare(`INSERT INTO chat_messages (session_id, role, content, meta) VALUES (?, 'user', ?, ?)`).run(sessionId, textContent, Object.keys(meta).length > 0 ? JSON.stringify(meta) : null);
     } catch {
     }
     session.state = "processing";
     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" });
+    if (body.images?.length) {
+      const content = [
+        ...body.images.map((img) => ({
+          type: "image",
+          source: { type: "base64", media_type: img.mimeType, data: img.base64 }
+        })),
+        ...body.message ? [{ type: "text", text: body.message }] : []
+      ];
+      logger.log("route", `POST /send?session=${sessionId} \u2192 ${body.images.length} image(s) + "${(body.message ?? "").slice(0, 40)}"`);
+      session.process.send(content);
+    } else {
+      logger.log("route", `POST /send?session=${sessionId} \u2192 "${body.message.slice(0, 80)}"`);
+      session.process.send(body.message);
+    }
+    return httpJson(c, "agent.send", { status: "sent" });
   });
   app.get("/events", (c) => {
     const sessionId = getSessionId(c);
@@ -159,79 +245,97 @@ function createAgentRoutes(sessionManager) {
       }
     });
   });
+  app.post("/restart", async (c) => {
+    const sessionId = getSessionId(c);
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const ccSessionId = sessionManager.getSession(sessionId)?.ccSessionId;
+      const { config } = sessionManager.restartSession(sessionId, body, (cfg) => {
+        const prov = getProvider(cfg.provider);
+        const resumeArgs = ccSessionId ? ["--resume", ccSessionId] : ["--resume"];
+        return prov.spawn({
+          cwd: sessionManager.getSession(sessionId).cwd,
+          model: cfg.model,
+          permissionMode: cfg.permissionMode,
+          env: { SNA_SESSION_ID: sessionId },
+          extraArgs: [...cfg.extraArgs ?? [], ...resumeArgs]
+        });
+      });
+      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("/set-model", async (c) => {
+    const sessionId = getSessionId(c);
+    const body = await c.req.json().catch(() => ({}));
+    if (!body.model) return c.json({ status: "error", message: "model is required" }, 400);
+    const updated = sessionManager.setSessionModel(sessionId, body.model);
+    return httpJson(c, "agent.set-model", { status: updated ? "updated" : "no_session", model: body.model });
+  });
+  app.post("/set-permission-mode", async (c) => {
+    const sessionId = getSessionId(c);
+    const body = await c.req.json().catch(() => ({}));
+    if (!body.permissionMode) return c.json({ status: "error", message: "permissionMode is required" }, 400);
+    const updated = sessionManager.setSessionPermissionMode(sessionId, body.permissionMode);
+    return httpJson(c, "agent.set-permission-mode", { status: updated ? "updated" : "no_session", permissionMode: body.permissionMode });
+  });
   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
+      ccSessionId: session?.ccSessionId ?? null,
+      eventCount: session?.eventCounter ?? 0,
+      config: session?.lastStartConfig ?? null
     });
   });
-  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
 };