@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

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(() => {

package/src/models/catalog.js

@@ -0,0 +1,135 @@
+export const MODEL_CATALOG_SCHEMA = 'agentsam-model-catalog-v1';
+
+const ASTRA_SOURCE = 'https://developers.openai.com/api/docs/models/gpt-6-astra';
+
+const GPT_6_ASTRA = Object.freeze({
+  schema_version: 1,
+  model_key: 'openai:gpt-6-astra',
+  provider: 'openai',
+  provider_model_id: 'gpt-6-astra',
+  label: 'GPT-6 Astra',
+  context_window: 1_050_000,
+  max_output_tokens: 128_000,
+  reasoning_efforts: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+  service_tiers: Object.freeze(['default', 'fast', 'flex']),
+  capabilities: Object.freeze({
+    responses: true,
+    streaming: true,
+    function_calling: true,
+    structured_outputs: true,
+    prompt_caching: true,
+    compaction: true,
+    tool_search: true,
+    async_tool_calls: true,
+    mid_turn_steering: true,
+    configuration_update: true,
+    batch: true,
+    fast: true,
+    flex: true,
+  }),
+  pricing: Object.freeze({
+    currency: 'USD',
+    unit: 'per_million_tokens',
+    input: 10,
+    cached_input: 1,
+    cache_write: 12.5,
+    output: 50,
+    thresholds: Object.freeze([
+      Object.freeze({
+        input_tokens_gt: 272_000,
+        applies_to_full_request: true,
+        multipliers: Object.freeze({ input: 2, cached_input: 2, cache_write: 2, output: 1.5 }),
+      }),
+    ]),
+    service_tier_multipliers: Object.freeze({ default: 1, fast: 2, flex: 0.5, batch: 0.5 }),
+    source: ASTRA_SOURCE,
+    as_of: '2026-09-12',
+  }),
+  context_policy: Object.freeze({
+    target_input_tokens: 120_000,
+    compact_at_tokens: 180_000,
+    intervene_at_tokens: 220_000,
+    max_normal_input_tokens: 250_000,
+    pricing_threshold_tokens: 272_000,
+    safety_margin_tokens: 22_000,
+  }),
+  batch: Object.freeze({
+    supported: true,
+    completion_window: '24h',
+    relative_price: 0.5,
+    interactive: false,
+  }),
+  source: Object.freeze({ url: ASTRA_SOURCE, as_of: '2026-09-12' }),
+});
+
+export const MODEL_CATALOG = Object.freeze([GPT_6_ASTRA]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function nonNegativeInteger(value, label) {
+  const number = Number(value ?? 0);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError(`${label} must be a non-negative number`);
+  return Math.floor(number);
+}
+
+export function listModelCatalog(options = {}) {
+  const provider = clean(options.provider).toLowerCase();
+  return MODEL_CATALOG.filter((row) => !provider || row.provider === provider);
+}
+
+export function getModelRecord(value) {
+  const key = clean(value);
+  if (!key) return null;
+  return MODEL_CATALOG.find((row) => row.model_key === key || row.provider_model_id === key) || null;
+}
+
+export function calculateModelCost(model, usage = {}, options = {}) {
+  const record = typeof model === 'string' ? getModelRecord(model) : model;
+  if (!record?.pricing) throw new TypeError('model pricing record is required');
+
+  const totalInput = nonNegativeInteger(usage.input_tokens ?? usage.inputTokens, 'input_tokens');
+  const cachedInput = Math.min(totalInput, nonNegativeInteger(usage.cached_input_tokens ?? usage.cachedInputTokens, 'cached_input_tokens'));
+  const cacheWrite = Math.min(totalInput - cachedInput, nonNegativeInteger(usage.cache_write_tokens ?? usage.cacheWriteTokens, 'cache_write_tokens'));
+  const uncachedInput = Math.max(0, totalInput - cachedInput - cacheWrite);
+  const output = nonNegativeInteger(usage.output_tokens ?? usage.outputTokens, 'output_tokens');
+  const serviceTier = clean(options.serviceTier || usage.service_tier || usage.serviceTier || 'default') || 'default';
+  const tierMultiplier = record.pricing.service_tier_multipliers?.[serviceTier];
+  if (!Number.isFinite(tierMultiplier)) throw new RangeError(`unsupported service tier for ${record.provider_model_id}: ${serviceTier}`);
+
+  const threshold = (record.pricing.thresholds || []).find((row) => totalInput > row.input_tokens_gt) || null;
+  const thresholdMultipliers = threshold?.multipliers || {};
+  const rates = {
+    input: record.pricing.input * (thresholdMultipliers.input || 1) * tierMultiplier,
+    cached_input: record.pricing.cached_input * (thresholdMultipliers.cached_input || 1) * tierMultiplier,
+    cache_write: record.pricing.cache_write * (thresholdMultipliers.cache_write || 1) * tierMultiplier,
+    output: record.pricing.output * (thresholdMultipliers.output || 1) * tierMultiplier,
+  };
+  const components = {
+    input: (uncachedInput * rates.input) / 1_000_000,
+    cached_input: (cachedInput * rates.cached_input) / 1_000_000,
+    cache_write: (cacheWrite * rates.cache_write) / 1_000_000,
+    output: (output * rates.output) / 1_000_000,
+  };
+  const total = Object.values(components).reduce((sum, value) => sum + value, 0);
+
+  return Object.freeze({
+    model_key: record.model_key,
+    service_tier: serviceTier,
+    usage: Object.freeze({
+      input_tokens: totalInput,
+      uncached_input_tokens: uncachedInput,
+      cached_input_tokens: cachedInput,
+      cache_write_tokens: cacheWrite,
+      output_tokens: output,
+    }),
+    threshold_applied: threshold ? Object.freeze({ ...threshold }) : null,
+    rates_per_million: Object.freeze(rates),
+    components_usd: Object.freeze(components),
+    total_usd: total,
+    estimate_kind: usage.estimate_kind === 'provider' ? 'provider' : 'local',
+    pricing_source: record.pricing.source,
+    pricing_as_of: record.pricing.as_of,
+  });
+}