@sna-sdk/core 0.3.0 → 0.5.0

package/README.md

@@ -9,6 +9,7 @@ Server runtime for [Skills-Native Applications](https://github.com/neuradex/sna)
 - **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
+- **History management** — `agent.resume` auto-loads DB history, `agent.subscribe({ since: 0 })` unified history+realtime channel
 - **One-shot execution** — `POST /agent/run-once` for single-request LLM calls
 - **CLI** — `sna up/down/status`, `sna dispatch`, `sna gen client`, `sna tu` (mock API testing)
 - **Agent providers** — Claude Code and Codex process management
@@ -86,6 +87,11 @@ const db = getDb(); // SQLite instance (data/sna.db)
 | `@sna-sdk/core/lib/sna-run` | `snaRun()` helper for spawning Claude Code |
 | `@sna-sdk/core/testing` | `startMockAnthropicServer()` for testing without real API calls |
 
+**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)
+
 ## Documentation
 
 - [Architecture](https://github.com/neuradex/sna/blob/main/docs/architecture.md)

package/dist/core/providers/cc-history-adapter.d.ts

@@ -0,0 +1,37 @@
+import { HistoryMessage } from './types.js';
+
+/**
+ * History injection for Claude Code via JSONL resume.
+ *
+ * Writes a JSONL session file and passes --resume <filepath> to CC.
+ * CC loads it as real multi-turn conversation history.
+ *
+ * Key discovery: --resume with a .jsonl file path bypasses CC's project
+ * directory lookup and calls loadMessagesFromJsonlPath directly.
+ * This is the only reliable way to inject synthetic history.
+ *
+ * Verified: real Claude Haiku correctly recalls injected context.
+ * Fallback: recalled-conversation XML if file write fails.
+ */
+
+/**
+ * Write a JSONL session file for --resume <filepath>.
+ *
+ * Minimal format (verified working):
+ *   {"parentUuid":null,"isSidechain":false,"type":"user","uuid":"...","timestamp":"...","cwd":"...","sessionId":"...","message":{"role":"user","content":"..."}}
+ *   {"parentUuid":"<prev>","isSidechain":false,"type":"assistant","uuid":"...","timestamp":"...","cwd":"...","sessionId":"...","message":{"role":"assistant","content":[{"type":"text","text":"..."}]}}
+ */
+declare function writeHistoryJsonl(history: HistoryMessage[], opts: {
+    cwd: string;
+}): {
+    filePath: string;
+    extraArgs: string[];
+} | null;
+/**
+ * Pack history into a single assistant stdin message.
+ * CC treats type:"assistant" as context injection (no API call triggered).
+ * Used when file write fails.
+ */
+declare function buildRecalledConversation(history: HistoryMessage[]): string;
+
+export { buildRecalledConversation, writeHistoryJsonl };

package/dist/core/providers/cc-history-adapter.js

@@ -0,0 +1,70 @@
+import fs from "fs";
+import path from "path";
+function writeHistoryJsonl(history, opts) {
+  for (let i = 1; i < history.length; i++) {
+    if (history[i].role === history[i - 1].role) {
+      throw new Error(
+        `History validation failed: consecutive ${history[i].role} at index ${i - 1} and ${i}. Messages must alternate user\u2194assistant. Merge tool results into text before injecting.`
+      );
+    }
+  }
+  try {
+    const dir = path.join(opts.cwd, ".sna", "history");
+    fs.mkdirSync(dir, { recursive: true });
+    const sessionId = crypto.randomUUID();
+    const filePath = path.join(dir, `${sessionId}.jsonl`);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const lines = [];
+    let prevUuid = null;
+    for (const msg of history) {
+      const uuid = crypto.randomUUID();
+      if (msg.role === "user") {
+        lines.push(JSON.stringify({
+          parentUuid: prevUuid,
+          isSidechain: false,
+          type: "user",
+          uuid,
+          timestamp: now,
+          cwd: opts.cwd,
+          sessionId,
+          message: { role: "user", content: msg.content }
+        }));
+      } else {
+        lines.push(JSON.stringify({
+          parentUuid: prevUuid,
+          isSidechain: false,
+          type: "assistant",
+          uuid,
+          timestamp: now,
+          cwd: opts.cwd,
+          sessionId,
+          message: {
+            role: "assistant",
+            content: [{ type: "text", text: msg.content }]
+          }
+        }));
+      }
+      prevUuid = uuid;
+    }
+    fs.writeFileSync(filePath, lines.join("\n") + "\n");
+    return { filePath, extraArgs: ["--resume", filePath] };
+  } catch {
+    return null;
+  }
+}
+function buildRecalledConversation(history) {
+  const xml = history.map((msg) => `<${msg.role}>${msg.content}</${msg.role}>`).join("\n");
+  return JSON.stringify({
+    type: "assistant",
+    message: {
+      role: "assistant",
+      content: [{ type: "text", text: `<recalled-conversation>
+${xml}
+</recalled-conversation>` }]
+    }
+  });
+}
+export {
+  buildRecalledConversation,
+  writeHistoryJsonl
+};

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

@@ -2,6 +2,7 @@ import { spawn, execSync } from "child_process";
 import { EventEmitter } from "events";
 import fs from "fs";
 import path from "path";
+import { writeHistoryJsonl, buildRecalledConversation } from "./cc-history-adapter.js";
 import { logger } from "../../lib/logger.js";
 const SHELL = process.env.SHELL || "/bin/zsh";
 function resolveClaudePath(cwd) {
@@ -79,33 +80,44 @@ class ClaudeCodeProcess {
       this._alive = false;
       this.emitter.emit("error", err);
     });
-    if (options.history?.length) {
-      if (!options.prompt) {
-        throw new Error("history requires a prompt \u2014 the last stdin message must be a user message");
-      }
-      for (const msg of options.history) {
-        if (msg.role === "user") {
-          const line = JSON.stringify({
-            type: "user",
-            message: { role: "user", content: msg.content }
-          });
-          this.proc.stdin.write(line + "\n");
-        } else if (msg.role === "assistant") {
-          const line = JSON.stringify({
-            type: "assistant",
-            message: {
-              role: "assistant",
-              content: [{ type: "text", text: msg.content }]
-            }
-          });
-          this.proc.stdin.write(line + "\n");
-        }
-      }
+    if (options.history?.length && !options._historyViaResume) {
+      const line = buildRecalledConversation(options.history);
+      this.proc.stdin.write(line + "\n");
     }
     if (options.prompt) {
       this.send(options.prompt);
     }
   }
+  /**
+   * 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.
+   */
+  emitTextAsDeltas(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,
+        timestamp: Date.now()
+      });
+    }, t);
+  }
   get alive() {
     return this._alive;
   }
@@ -181,6 +193,7 @@ class ClaudeCodeProcess {
         const content = msg.message?.content;
         if (!Array.isArray(content)) return null;
         const events = [];
+        const textBlocks = [];
         for (const block of content) {
           if (block.type === "thinking") {
             events.push({
@@ -198,15 +211,17 @@ class ClaudeCodeProcess {
           } else if (block.type === "text") {
             const text = (block.text ?? "").trim();
             if (text) {
-              events.push({ type: "assistant", message: text, timestamp: Date.now() });
+              textBlocks.push(text);
             }
           }
         }
-        if (events.length > 0) {
-          for (let i = 1; i < events.length; i++) {
-            this.emitter.emit("event", events[i]);
+        if (events.length > 0 || textBlocks.length > 0) {
+          for (const e of events) {
+            this.emitter.emit("event", e);
+          }
+          for (const text of textBlocks) {
+            this.emitTextAsDeltas(text);
           }
-          return events[0];
         }
         return null;
       }
@@ -341,6 +356,14 @@ class ClaudeCodeProvider {
     if (options.permissionMode) {
       args.push("--permission-mode", options.permissionMode);
     }
+    if (options.history?.length && options.prompt) {
+      const result = writeHistoryJsonl(options.history, { cwd: options.cwd });
+      if (result) {
+        args.push(...result.extraArgs);
+        options._historyViaResume = true;
+        logger.log("agent", `history via JSONL resume \u2192 ${result.filePath}`);
+      }
+    }
     if (extraArgsClean.length > 0) {
       args.push(...extraArgsClean);
     }

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

@@ -5,9 +5,13 @@
  * Codex JSONL, etc.) into these common types.
  */
 interface AgentEvent {
-    type: "init" | "thinking" | "text_delta" | "assistant" | "tool_use" | "tool_result" | "permission_needed" | "milestone" | "interrupted" | "error" | "complete";
+    type: "init" | "thinking" | "text_delta" | "assistant_delta" | "assistant" | "tool_use" | "tool_result" | "permission_needed" | "milestone" | "user_message" | "interrupted" | "error" | "complete";
     message?: string;
     data?: Record<string, unknown>;
+    /** Streaming text delta (for assistant_delta events only) */
+    delta?: string;
+    /** Content block index (for assistant_delta events only) */
+    index?: number;
     timestamp: number;
 }
 /**
@@ -63,6 +67,8 @@ interface SpawnOptions {
      * Must alternate user→assistant. Assistant content is auto-wrapped in array format.
      */
     history?: HistoryMessage[];
+    /** @internal Set by provider when history was injected via JSONL resume. */
+    _historyViaResume?: boolean;
     /**
      * Additional CLI flags passed directly to the agent binary.
      * e.g. ["--system-prompt", "You are...", "--append-system-prompt", "Also...", "--mcp-config", "path"]

package/dist/db/schema.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import fs from "fs";
 import path from "path";
-const DB_PATH = path.join(process.cwd(), "data/sna.db");
+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() {

package/dist/scripts/sna.js

@@ -212,6 +212,9 @@ function cmdTu(args2) {
     case "claude":
       cmdTuClaude(args2.slice(1));
       break;
+    case "claude:oneshot":
+      cmdTuClaudeOneshot(args2.slice(1));
+      break;
     default:
       console.log(`
   sna tu \u2014 Test utilities (mock Anthropic API)
@@ -221,7 +224,8 @@ function cmdTu(args2) {
     sna tu api:down     Stop mock API server
     sna tu api:log      Show mock API request/response log
     sna tu api:log -f   Follow log in real-time (tail -f)
-    sna tu claude ...   Run claude with mock API env vars (proxy)
+    sna tu claude ...          Run claude with mock API env vars (proxy)
+    sna tu claude:oneshot ...  One-shot: mock server \u2192 claude \u2192 results \u2192 cleanup
 
   Flow:
     1. sna tu api:up            \u2192 mock server on random port
@@ -338,6 +342,19 @@ function cmdTuClaude(args2) {
     process.exit(e.status ?? 1);
   }
 }
+function cmdTuClaudeOneshot(args2) {
+  const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+  const oneshotScript = fs.existsSync(path.join(scriptDir, "tu-oneshot.js")) ? path.join(scriptDir, "tu-oneshot.js") : path.join(scriptDir, "tu-oneshot.ts");
+  try {
+    execSync(`node --import tsx "${oneshotScript}" ${args2.map((a) => `"${a}"`).join(" ")}`, {
+      stdio: "inherit",
+      cwd: ROOT,
+      timeout: 9e4
+    });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+}
 function readPidFile(filePath) {
   try {
     return parseInt(fs.readFileSync(filePath, "utf8").trim(), 10) || null;
@@ -784,7 +801,8 @@ Testing:
   sna tu api:down     Stop mock API server
   sna tu api:log      Show mock API request/response log
   sna tu api:log -f   Follow log in real-time
-  sna tu claude ...   Run claude with mock API (isolated env, no account pollution)
+  sna tu claude ...          Run claude with mock API (isolated env)
+  sna tu claude:oneshot ...  One-shot: mock server \u2192 claude \u2192 structured results \u2192 cleanup
 
   Set SNA_CLAUDE_COMMAND to override claude binary in SDK.
   See: docs/testing.md

package/dist/scripts/tu-oneshot.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/scripts/tu-oneshot.js

@@ -0,0 +1,66 @@
+import { startMockAnthropicServer } from "../testing/mock-api.js";
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+async function main() {
+  const ROOT = process.cwd();
+  const STATE_DIR = path.join(ROOT, ".sna");
+  const args = process.argv.slice(2);
+  let claudePath = "claude";
+  const cachedPath = path.join(STATE_DIR, "claude-path");
+  if (fs.existsSync(cachedPath)) {
+    claudePath = fs.readFileSync(cachedPath, "utf8").trim() || claudePath;
+  }
+  const mock = await startMockAnthropicServer();
+  const mockConfigDir = path.join(STATE_DIR, "mock-claude-oneshot");
+  fs.mkdirSync(mockConfigDir, { recursive: true });
+  const env = {
+    PATH: process.env.PATH ?? "",
+    HOME: process.env.HOME ?? "",
+    SHELL: process.env.SHELL ?? "/bin/zsh",
+    TERM: process.env.TERM ?? "xterm-256color",
+    LANG: process.env.LANG ?? "en_US.UTF-8",
+    ANTHROPIC_BASE_URL: `http://localhost:${mock.port}`,
+    ANTHROPIC_API_KEY: "sk-test-mock-oneshot",
+    CLAUDE_CONFIG_DIR: mockConfigDir
+  };
+  const stdoutPath = path.join(STATE_DIR, "mock-claude-stdout.log");
+  const stderrPath = path.join(STATE_DIR, "mock-claude-stderr.log");
+  const proc = spawn(claudePath, args, {
+    env,
+    cwd: ROOT,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  proc.stdout.on("data", (d) => {
+    stdout += d.toString();
+  });
+  proc.stderr.on("data", (d) => {
+    stderr += d.toString();
+  });
+  proc.stdout.pipe(process.stdout);
+  proc.on("exit", (code) => {
+    fs.writeFileSync(stdoutPath, stdout);
+    fs.writeFileSync(stderrPath, stderr);
+    console.log(`
+${"\u2500".repeat(60)}`);
+    console.log(`Mock API: ${mock.requests.length} request(s)`);
+    for (const req of mock.requests) {
+      console.log(`  model=${req.model} stream=${req.stream} messages=${req.messages?.length}`);
+    }
+    console.log(`
+Log files:`);
+    console.log(`  stdout:   ${stdoutPath}`);
+    console.log(`  stderr:   ${stderrPath}`);
+    console.log(`  api log:  ${path.join(STATE_DIR, "mock-api-last-request.json")}`);
+    console.log(`  config:   ${mockConfigDir}`);
+    console.log(`  exit:     ${code}`);
+    mock.close();
+    process.exit(code ?? 0);
+  });
+  setTimeout(() => {
+    proc.kill();
+  }, 6e4);
+}
+main();

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

@@ -25,6 +25,12 @@ interface ApiResponses {
     "agent.send": {
         status: "sent";
     };
+    "agent.resume": {
+        status: "resumed";
+        provider: string;
+        sessionId: string;
+        historyCount: number;
+    };
     "agent.restart": {
         status: "restarted";
         provider: string;
@@ -46,9 +52,16 @@ interface ApiResponses {
     };
     "agent.status": {
         alive: boolean;
+        agentStatus: "idle" | "busy" | "disconnected";
         sessionId: string | null;
         ccSessionId: string | null;
         eventCount: number;
+        messageCount: number;
+        lastMessage: {
+            role: string;
+            content: string;
+            created_at: string;
+        } | null;
         config: {
             provider: string;
             model: string;

package/dist/server/history-builder.d.ts

@@ -0,0 +1,16 @@
+import { HistoryMessage } from '../core/providers/types.js';
+
+/**
+ * Build HistoryMessage[] from chat_messages DB records.
+ *
+ * Filters to user/assistant roles, ensures alternation,
+ * and merges consecutive same-role messages.
+ */
+
+/**
+ * Load conversation history from DB for a session.
+ * Returns alternating user↔assistant messages ready for JSONL injection.
+ */
+declare function buildHistoryFromDb(sessionId: string): HistoryMessage[];
+
+export { buildHistoryFromDb };

package/dist/server/history-builder.js

@@ -0,0 +1,25 @@
+import { getDb } from "../db/schema.js";
+function buildHistoryFromDb(sessionId) {
+  const db = getDb();
+  const rows = db.prepare(
+    `SELECT role, content FROM chat_messages
+     WHERE session_id = ? AND role IN ('user', 'assistant')
+     ORDER BY id ASC`
+  ).all(sessionId);
+  if (rows.length === 0) return [];
+  const merged = [];
+  for (const row of rows) {
+    const role = row.role;
+    if (!row.content?.trim()) continue;
+    const last = merged[merged.length - 1];
+    if (last && last.role === role) {
+      last.content += "\n\n" + row.content;
+    } else {
+      merged.push({ role, content: row.content });
+    }
+  }
+  return merged;
+}
+export {
+  buildHistoryFromDb
+};

package/dist/server/index.d.ts

@@ -1,13 +1,14 @@
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 import { SessionManager } from './session-manager.js';
-export { Session, SessionConfigChangedEvent, SessionInfo, SessionLifecycleEvent, SessionLifecycleState, SessionManagerOptions, StartConfig } from './session-manager.js';
+export { AgentStatus, Session, SessionConfigChangedEvent, SessionInfo, SessionLifecycleEvent, SessionLifecycleState, SessionManagerOptions, StartConfig } from './session-manager.js';
 export { eventsRoute } from './routes/events.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';
+export { buildHistoryFromDb } from './history-builder.js';
 import '../core/providers/types.js';
 import 'hono/utils/http-status';
 import 'ws';

package/dist/server/index.js

@@ -27,6 +27,7 @@ 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";
+import { buildHistoryFromDb } from "./history-builder.js";
 function snaPortRoute(c) {
   const portFile = _path.join(process.cwd(), ".sna/sna-api.port");
   try {
@@ -39,6 +40,7 @@ function snaPortRoute(c) {
 export {
   SessionManager2 as SessionManager,
   attachWebSocket,
+  buildHistoryFromDb,
   createAgentRoutes2 as createAgentRoutes,
   createChatRoutes2 as createChatRoutes,
   createEmitRoute2 as createEmitRoute,