@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.2

package/src/local/migrations.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_MIGRATIONS_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'migrations',
+  'runtime',
+);
+
+function migrationFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /^\d+.*\.sql$/i.test(entry.name))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function ensureLedger(db) {
+  db.exec(`
+CREATE TABLE IF NOT EXISTS agentsam_schema_migrations (
+  id TEXT PRIMARY KEY,
+  applied_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  checksum TEXT
+);
+`);
+}
+
+function checksumSource(source) {
+  let hash = 2166136261;
+  for (let i = 0; i < source.length; i += 1) {
+    hash ^= source.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return 'fnv1a32:' + (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+export async function listAppliedMigrations(db) {
+  ensureLedger(db);
+  const result = await db.prepare(
+    'SELECT id, applied_at_unix, checksum FROM agentsam_schema_migrations ORDER BY id'
+  ).all();
+  return result.results || [];
+}
+
+export async function applyRuntimeMigrations(db, options = {}) {
+  const dir = path.resolve(options.migrationsDir || DEFAULT_MIGRATIONS_DIR);
+  ensureLedger(db);
+  const appliedRows = await listAppliedMigrations(db);
+  const applied = new Map(appliedRows.map((row) => [String(row.id), row]));
+  const results = [];
+
+  for (const filename of migrationFiles(dir)) {
+    const id = filename.replace(/\.sql$/i, '');
+    const source = fs.readFileSync(path.join(dir, filename), 'utf8');
+    const checksum = checksumSource(source);
+    const previous = applied.get(id);
+
+    if (previous) {
+      if (previous.checksum && previous.checksum !== checksum) {
+        throw new Error('migration_checksum_mismatch:' + id);
+      }
+      results.push({ id, filename, status: 'already_applied', checksum });
+      continue;
+    }
+
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      db.exec(source);
+      await db.prepare(
+        'INSERT INTO agentsam_schema_migrations (id, checksum) VALUES (?, ?)'
+      ).bind(id, checksum).run();
+      db.exec('COMMIT');
+      results.push({ id, filename, status: 'applied', checksum });
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      throw new Error('migration_failed:' + id + ':' + (error?.message || error));
+    }
+  }
+
+  return Object.freeze({
+    migrationsDir: dir,
+    total: results.length,
+    applied: results.filter((row) => row.status === 'applied').length,
+    results: Object.freeze(results),
+  });
+}
+
+export function runtimeMigrationsDirectory() {
+  return DEFAULT_MIGRATIONS_DIR;
+}

package/src/local/runtime-store.js

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { createLocalSqliteDatabase } from './sqlite.js';
+import { applyRuntimeMigrations } from './migrations.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function hash(value) { return createHash('sha256').update(String(value || '')).digest('hex'); }
+
+export function runtimeDatabasePath(cwd = process.cwd()) {
+  return path.join(path.resolve(cwd), '.agentsam', 'data', 'agentsam.sqlite');
+}
+
+async function withStore(cwd, fn) {
+  const db = await createLocalSqliteDatabase(runtimeDatabasePath(cwd));
+  try {
+    await applyRuntimeMigrations(db);
+    return await fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+export function createRuntimeRunId() {
+  return `arun_${randomUUID()}`;
+}
+
+export async function startRuntimeRun(value = {}) {
+  const id = clean(value.id) || createRuntimeRunId();
+  await withStore(value.cwd, async (db) => {
+    await db.prepare(`
+      INSERT INTO agentsam_agent_run (
+        id, account_id, source_client, surface, mode, model_key,
+        reasoning_effort, requested_service_tier, status, started_at_unix, updated_at_unix
+      ) VALUES (?, ?, 'agentsam-cli', 'cli', ?, ?, ?, ?, 'running', unixepoch(), unixepoch())
+    `).bind(
+      id,
+      clean(value.account_id) || null,
+      clean(value.mode) || 'agent',
+      clean(value.model_key) || null,
+      clean(value.reasoning_effort) || null,
+      clean(value.service_tier) || null,
+    ).run();
+  });
+  return id;
+}
+
+export async function finishRuntimeRun(value = {}) {
+  if (!clean(value.id)) return;
+  await withStore(value.cwd, async (db) => {
+    const usage = value.usage || {};
+    await db.prepare(`
+      UPDATE agentsam_agent_run
+      SET status = ?,
+          actual_service_tier = COALESCE(?, actual_service_tier),
+          input_tokens = ?,
+          cached_input_tokens = ?,
+          output_tokens = ?,
+          reasoning_tokens = ?,
+          cost_usd = ?,
+          error_code = ?,
+          error_message = ?,
+          completed_at_unix = unixepoch(),
+          updated_at_unix = unixepoch(),
+          latency_ms = ?
+      WHERE id = ?
+    `).bind(
+      clean(value.status) || 'completed',
+      clean(value.actual_service_tier) || null,
+      Number(usage.input_tokens || 0),
+      Number(usage.cached_input_tokens || 0),
+      Number(usage.output_tokens || 0),
+      Number(usage.reasoning_tokens || 0),
+      Math.max(0, Number(value.cost_usd || 0)),
+      clean(value.error_code) || null,
+      clean(value.error_message) || null,
+      Number.isFinite(Number(value.latency_ms)) ? Math.max(0, Math.round(Number(value.latency_ms))) : null,
+      value.id,
+    ).run();
+  });
+}
+
+export async function recordRuntimeCompaction(value = {}) {
+  if (!clean(value.agent_run_id)) return null;
+  const id = clean(value.id) || `cmp_${randomUUID()}`;
+  const summary = clean(value.summary_text);
+  const before = Math.max(0, Math.round(Number(value.tokens_before || 0)));
+  const after = Math.max(0, Math.round(Number(value.tokens_after || 0)));
+  const sourceHash = hash(summary || JSON.stringify(value.metadata || {}));
+
+  await withStore(value.cwd, async (db) => {
+    await db.prepare(`
+      INSERT INTO agentsam_compaction_events (
+        id, account_id, agent_run_id, compaction_type, compaction_scope,
+        compaction_strategy, source_kind, content_hash, provider, model_key,
+        tokens_before, tokens_after, status, summary_text, summary_json,
+        metrics_json, metadata_json, source_stored
+      ) VALUES (?, ?, ?, 'context_summary', 'agent_run', 'summarize', ?, ?, ?, ?, ?, ?, 'completed', ?, ?, ?, ?, ?)
+    `).bind(
+      id,
+      clean(value.account_id) || null,
+      value.agent_run_id,
+      clean(value.source_kind) || 'api',
+      sourceHash,
+      clean(value.provider),
+      clean(value.model_key),
+      before,
+      after,
+      summary,
+      JSON.stringify({ summary }),
+      JSON.stringify({ tokens_before: before, tokens_after: after, tokens_saved: before - after }),
+      JSON.stringify(value.metadata || {}),
+      clean(value.source_stored) || 'local:agentsam_compaction_events',
+    ).run();
+
+    if (summary) {
+      const digestId = `ctx_${randomUUID()}`;
+      const digestHash = hash(`${value.agent_run_id}:${id}:${summary}`);
+      await db.prepare(`
+        INSERT INTO agentsam_context_digest (
+          id, account_id, digest_type, agent_run_id, session_id,
+          source_hash, digest_hash, raw_size_bytes, reduced_size_bytes,
+          token_count, digest_text, generation_model, compaction_event_id
+        ) VALUES (?, ?, 'session', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).bind(
+        digestId,
+        clean(value.account_id) || null,
+        value.agent_run_id,
+        clean(value.session_id) || null,
+        sourceHash,
+        digestHash,
+        Number(value.raw_size_bytes || 0) || null,
+        Buffer.byteLength(summary, 'utf8'),
+        after || Math.ceil(summary.length / 4),
+        summary,
+        clean(value.model_key) || null,
+        id,
+      ).run();
+    }
+  });
+  return id;
+}

package/src/local/sqlite.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { applyRuntimeMigrations } from './migrations.js';
 
 async function loadSqlite() {
   try {
@@ -77,6 +78,7 @@ export async function initializeLocalSqlite({
   const db = await createLocalSqliteDatabase(resolvedDb);
   try {
     db.exec(schema);
+    await applyRuntimeMigrations(db);
   } finally {
     db.close();
   }

package/src/local-pty/server.js

@@ -2,7 +2,10 @@
  * Agent Sam local PTY — localhost WebSocket shell, no tunnel, no IAM.
  * Compatible with iam-pty wire format (raw bytes + JSON resize/slash).
  */
+import fs from 'node:fs';
 import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
 
 const DEFAULT_PORT = 3099;
@@ -17,8 +20,45 @@ function shellForPlatform() {
   return process.env.SHELL || '/bin/zsh';
 }
 
-async function loadPty() {
+export function ensureNodePtySpawnHelperExecutable(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  if (platform !== 'darwin') return Object.freeze({ checked: false, changed: false, path: null });
+
+  const resolveModule = options.resolveModule || ((specifier) => import.meta.resolve(specifier));
+  const fsImpl = options.fs || fs;
+  const entryUrl = resolveModule('node-pty');
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(entryUrl)), '..');
+  const helperPath = path.join(packageRoot, 'prebuilds', `darwin-${arch}`, 'spawn-helper');
+
+  if (!fsImpl.existsSync(helperPath)) {
+    return Object.freeze({ checked: true, changed: false, path: helperPath, missing: true });
+  }
+
+  const stat = fsImpl.statSync(helperPath);
+  if ((stat.mode & 0o111) !== 0) {
+    return Object.freeze({ checked: true, changed: false, path: helperPath });
+  }
+
   try {
+    fsImpl.chmodSync(helperPath, stat.mode | 0o111);
+  } catch (error) {
+    const wrapped = new Error(
+      `node-pty spawn-helper is not executable and Agent Sam could not repair it at ${helperPath}. ` +
+      `Reinstall node-pty with install scripts enabled or make that helper executable. ${error?.message || error}`,
+    );
+    wrapped.code = 'node_pty_spawn_helper_not_executable';
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  return Object.freeze({ checked: true, changed: true, path: helperPath });
+}
+
+async function loadPty(override) {
+  if (override?.spawn) return override;
+  try {
+    ensureNodePtySpawnHelperExecutable();
     const mod = await import('node-pty');
     return mod.default || mod;
   } catch (e) {
@@ -29,12 +69,69 @@ async function loadPty() {
 }
 
 /**
- * @param {{ cwd?: string, port?: number, host?: string }} [opts]
+ * Attach the portable PTY wire protocol to an already-created WebSocket-like transport.
+ * Exported so the release gate can test terminal semantics against an in-memory mock transport.
+ */
+export function attachLocalPtySession({ ws, pty, shell, cwd, cols = 80, rows = 24, env = process.env, sessionId } = {}) {
+  if (!ws?.on || !ws?.send) throw new TypeError('ws transport with on/send is required');
+  if (!pty?.spawn) throw new TypeError('pty transport with spawn is required');
+  const term = pty.spawn(shell, [], {
+    name: 'xterm-256color',
+    cols,
+    rows,
+    cwd,
+    env: { ...env, TERM: 'xterm-256color', AGENTSAM_LOCAL_PTY: '1' },
+  });
+  const id = sessionId || `local_${Date.now().toString(36)}`;
+  const openState = ws.OPEN ?? 1;
+  const isOpen = () => ws.readyState == null || ws.readyState === openState;
+
+  ws.send(JSON.stringify({ type: 'session_id', session_id: id }));
+
+  term.onData((data) => {
+    if (isOpen()) ws.send(data);
+  });
+
+  ws.on('message', (raw) => {
+    const text = raw.toString();
+    try {
+      const msg = JSON.parse(text);
+      if (msg.type === 'resize' && msg.cols && msg.rows) {
+        term.resize(msg.cols, msg.rows);
+        return;
+      }
+      if (msg.type === 'slash' && msg.line) {
+        term.write(`${msg.line}\r`);
+        return;
+      }
+    } catch {
+      /* raw PTY input */
+    }
+    term.write(text);
+  });
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try { term.kill(); } catch { /* ignore */ }
+  };
+  term.onExit(() => {
+    if (isOpen() && ws.close) ws.close();
+  });
+  ws.on('close', cleanup);
+  ws.on('error', cleanup);
+
+  return Object.freeze({ session_id: id, term, cleanup });
+}
+
+/**
+ * @param {{ cwd?: string, port?: number, host?: string, pty?: { spawn: Function } }} [opts]
  */
 export async function startLocalPtyServer(opts = {}) {
-  const pty = await loadPty();
+  const pty = await loadPty(opts.pty);
   const cwd = opts.cwd || process.cwd();
-  const port = parsePort(opts.port ?? process.env.PTY_PORT, DEFAULT_PORT);
+  const requestedPort = opts.port === 0 ? 0 : parsePort(opts.port ?? process.env.PTY_PORT, DEFAULT_PORT);
   const host = opts.host || '127.0.0.1';
   const shell = shellForPlatform();
 
@@ -47,7 +144,7 @@ export async function startLocalPtyServer(opts = {}) {
           ok: true,
           service: 'agentsam-local-pty',
           cwd,
-          port,
+          port: Number(httpServer.address()?.port || requestedPort),
           shell,
         }),
       );
@@ -65,64 +162,29 @@ export async function startLocalPtyServer(opts = {}) {
     const cols = parsePort(url.searchParams.get('cols'), 80);
     const rows = parsePort(url.searchParams.get('rows'), 24);
 
-    const term = pty.spawn(shell, [], {
-      name: 'xterm-256color',
+    attachLocalPtySession({
+      ws,
+      pty,
+      shell,
+      cwd: sessionCwd,
       cols,
       rows,
-      cwd: sessionCwd,
-      env: { ...process.env, TERM: 'xterm-256color', AGENTSAM_LOCAL_PTY: '1' },
-    });
-
-    const sessionId = `local_${Date.now().toString(36)}`;
-    ws.send(JSON.stringify({ type: 'session_id', session_id: sessionId }));
-
-    term.onData((data) => {
-      if (ws.readyState === ws.OPEN) ws.send(data);
-    });
-
-    ws.on('message', (raw) => {
-      const text = raw.toString();
-      try {
-        const msg = JSON.parse(text);
-        if (msg.type === 'resize' && msg.cols && msg.rows) {
-          term.resize(msg.cols, msg.rows);
-          return;
-        }
-        if (msg.type === 'slash' && msg.line) {
-          term.write(`${msg.line}\r`);
-          return;
-        }
-      } catch {
-        /* raw PTY input */
-      }
-      term.write(text);
-    });
-
-    const cleanup = () => {
-      try {
-        term.kill();
-      } catch {
-        /* ignore */
-      }
-    };
-    term.onExit(() => {
-      if (ws.readyState === ws.OPEN) ws.close();
+      env: process.env,
     });
-    ws.on('close', cleanup);
-    ws.on('error', cleanup);
   });
 
   await new Promise((resolve) => {
-    httpServer.listen(port, host, resolve);
+    httpServer.listen(requestedPort, host, resolve);
   });
+  const boundPort = Number(httpServer.address()?.port || requestedPort);
 
   return {
-    port,
+    port: boundPort,
     host,
     cwd,
     shell,
-    url: `ws://${host}:${port}`,
-    healthUrl: `http://${host}:${port}/health`,
+    url: `ws://${host}:${boundPort}`,
+    healthUrl: `http://${host}:${boundPort}/health`,
     close: () =>
       new Promise((resolve, reject) => {
         wss.close(() => {