@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/lib/provider-credentials.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PROVIDER_CREDENTIALS = Object.freeze({
+  openai: Object.freeze({ env: 'OPENAI_API_KEY', files: ['openai.env'] }),
+  gemini: Object.freeze({ env: 'GEMINI_API_KEY', files: ['gemini.env'] }),
+  anthropic: Object.freeze({ env: 'ANTHROPIC_API_KEY', files: ['anthropic.env'] }),
+  grok: Object.freeze({ env: 'XAI_API_KEY', files: ['grok.env', 'xai.env'] }),
+  cloudflare: Object.freeze({ env: 'CLOUDFLARE_API_TOKEN', files: ['cloudflare.env'], accountEnv: ['ACCOUNT_ID', 'CLOUDFLARE_ACCOUNT_ID'] }),
+});
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function normalizeCloudflareAccountId(value) {
+  const id = clean(value);
+  if (!id) return '';
+  if (!/^[a-f0-9]{32}$/i.test(id)) throw new Error('invalid_cloudflare_account_id');
+  return id;
+}
+
+function homeDirectory(options = {}) {
+  return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir());
+}
+
+function parseEnvValue(source, variable) {
+  for (const rawLine of String(source || '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match || match[1] !== variable) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    return value;
+  }
+  return '';
+}
+
+function secureFile(filename) {
+  const stat = fs.statSync(filename);
+  if (!stat.isFile()) return { ok: false, error: 'not_a_file' };
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) return { ok: false, error: 'permissions_too_open' };
+  return { ok: true, mode: stat.mode & 0o777 };
+}
+
+function firstEnvValue(source, names = []) {
+  for (const name of names) {
+    const value = clean(parseEnvValue(source, name));
+    if (value) return value;
+  }
+  return '';
+}
+
+function firstRuntimeValue(env, names = []) {
+  for (const name of names) {
+    const value = clean(env?.[name]);
+    if (value) return value;
+  }
+  return '';
+}
+
+export function agentEnvDirectory(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'env.d');
+}
+
+export function agentEnvLoaderPath(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'load-agent-env.sh');
+}
+
+export function ensureAgentEnvLoader(options = {}) {
+  const filename = agentEnvLoaderPath(options);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const source = `# AgentSam provider environment loader. Source this file; do not execute it.
+_agentsam_profile=\"\${1:-}\"
+case \"\$_agentsam_profile\" in
+  openai|anthropic|gemini|grok|cloudflare) ;;
+  *) echo \"usage: source ~/.agentsam/load-agent-env.sh <openai|anthropic|gemini|grok|cloudflare>\" >&2; return 2 2>/dev/null || exit 2 ;;
+esac
+_agentsam_file=\"\${HOME}/.agentsam/env.d/\${_agentsam_profile}.env\"
+if [ ! -f \"\$_agentsam_file\" ]; then
+  echo \"AgentSam provider profile not found: \$_agentsam_file\" >&2
+  return 1 2>/dev/null || exit 1
+fi
+set -a
+. \"\$_agentsam_file\"
+set +a
+if [ \"\$_agentsam_profile\" = cloudflare ]; then
+  if [ -z \"\${ACCOUNT_ID:-}\" ] && [ -n \"\${CLOUDFLARE_ACCOUNT_ID:-}\" ]; then export ACCOUNT_ID=\"\$CLOUDFLARE_ACCOUNT_ID\"; fi
+  if [ -z \"\${CLOUDFLARE_ACCOUNT_ID:-}\" ] && [ -n \"\${ACCOUNT_ID:-}\" ]; then export CLOUDFLARE_ACCOUNT_ID=\"\$ACCOUNT_ID\"; fi
+fi
+unset _agentsam_file _agentsam_profile
+`;
+  fs.writeFileSync(filename, source, { mode: 0o700 });
+  if (process.platform !== 'win32') fs.chmodSync(filename, 0o700);
+  return filename;
+}
+
+function profileTemplate(provider, options = {}) {
+  if (provider === 'cloudflare') {
+    const accountId = normalizeCloudflareAccountId(options.accountId);
+    return `# AgentSam Cloudflare profile\n# ACCOUNT_ID is your Cloudflare account identifier; it is not a secret.\nexport ACCOUNT_ID=\"${accountId}\"\nexport CLOUDFLARE_API_TOKEN=\"\"\n`;
+  }
+  const spec = PROVIDER_CREDENTIALS[provider];
+  if (!spec) throw new Error(`unsupported_provider:${provider}`);
+  return `# AgentSam ${provider} provider profile\nexport ${spec.env}=\"\"\n`;
+}
+
+export function ensureProviderEnvProfile(provider, options = {}) {
+  const spec = providerCredentialSpec(provider);
+  if (!spec) throw new Error(`unsupported_provider:${clean(provider).toLowerCase()}`);
+  const dir = agentEnvDirectory(options);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') fs.chmodSync(dir, 0o700);
+  const filename = path.join(dir, spec.files[0]);
+  let created = false;
+  if (!fs.existsSync(filename)) {
+    fs.writeFileSync(filename, profileTemplate(spec.provider, options), { mode: 0o600 });
+    created = true;
+  } else if (spec.provider === 'cloudflare' && clean(options.accountId)) {
+    const source = fs.readFileSync(filename, 'utf8');
+    const current = firstEnvValue(source, spec.accountEnv || []);
+    if (!current) {
+      const accountId = normalizeCloudflareAccountId(options.accountId);
+      const line = `export ACCOUNT_ID=\"${accountId}\"`;
+      const next = /^(?:export\s+)?ACCOUNT_ID=.*$/m.test(source)
+        ? source.replace(/^(?:export\s+)?ACCOUNT_ID=.*$/m, line)
+        : `${line}\n${source}`;
+      fs.writeFileSync(filename, next, { mode: 0o600 });
+    }
+  }
+  if (process.platform !== 'win32') fs.chmodSync(filename, 0o600);
+  const loader = ensureAgentEnvLoader(options);
+  return Object.freeze({ provider: spec.provider, file: filename, loader, created, source_command: `source ~/.agentsam/load-agent-env.sh ${spec.provider}` });
+}
+
+export function providerCredentialSpec(provider) {
+  const id = clean(provider).toLowerCase();
+  const spec = PROVIDER_CREDENTIALS[id];
+  return spec ? Object.freeze({ provider: id, ...spec }) : null;
+}
+
+export function resolveProviderCredential(provider, options = {}) {
+  const spec = providerCredentialSpec(provider);
+  if (!spec) return Object.freeze({ provider: clean(provider).toLowerCase(), configured: false, source: null, error: 'unsupported_provider', value: '' });
+  const env = options.env || process.env;
+  const accountIdFromEnv = firstRuntimeValue(env, spec.accountEnv || []);
+  const fromEnv = clean(env?.[spec.env]);
+  if (fromEnv) return Object.freeze({ provider: spec.provider, configured: true, source: 'environment', env: spec.env, file: null, error: null, value: fromEnv, account_id: accountIdFromEnv || null });
+
+  const dir = agentEnvDirectory({ ...options, env });
+  for (const basename of spec.files) {
+    const filename = path.join(dir, basename);
+    if (!fs.existsSync(filename)) continue;
+    try {
+      const safety = secureFile(filename);
+      if (!safety.ok) return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: safety.error, value: '' });
+      const source = fs.readFileSync(filename, 'utf8');
+      const value = clean(parseEnvValue(source, spec.env));
+      const accountId = accountIdFromEnv || firstEnvValue(source, spec.accountEnv || []);
+      if (value) return Object.freeze({ provider: spec.provider, configured: true, source: 'agentsam_env_file', env: spec.env, file: filename, error: null, value, account_id: accountId || null });
+      return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: 'credential_variable_missing', value: '' });
+    } catch (error) {
+      return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: error?.message || String(error), value: '' });
+    }
+  }
+  return Object.freeze({ provider: spec.provider, configured: false, source: null, env: spec.env, file: null, error: null, value: '' });
+}
+
+export function describeProviderCredential(provider, options = {}) {
+  const resolved = resolveProviderCredential(provider, options);
+  return Object.freeze({
+    provider: resolved.provider,
+    configured: resolved.configured,
+    source: resolved.source,
+    env: resolved.env || null,
+    file: resolved.file || null,
+    error: resolved.error || null,
+    account_id: resolved.account_id || null,
+  });
+}
+
+export function listProviderCredentialStatus(options = {}) {
+  return Object.freeze(Object.keys(PROVIDER_CREDENTIALS).map((provider) => describeProviderCredential(provider, options)));
+}

package/src/lib/scaffold/templates/worker-api/index.js

@@ -2,31 +2,36 @@
  * Worker API template generator.
  */
 
-export function workerApiTemplates({ projectName, routes, cfAccountId }) {
+export function workerApiTemplates({ projectName, routes, cfAccountId, dbKind = 'd1' }) {
   const files = {};
 
+  const pkgScripts = {
+    deploy: 'wrangler deploy',
+    dev: 'wrangler dev',
+    ...(dbKind === 'hyperdrive'
+      ? { 'db:migrate': 'psql "$DATABASE_URL" -f migrations/001_init.sql' }
+      : { 'db:migrate': `wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote` }),
+  };
+
   files['package.json'] = JSON.stringify({
     name: projectName,
     version: '0.1.0',
     private: true,
-    scripts: {
-      deploy: 'wrangler deploy',
-      dev: 'wrangler dev',
-      'db:migrate': `wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote`,
-    },
+    scripts: pkgScripts,
     devDependencies: { wrangler: '^3.0.0' },
+    ...(dbKind === 'hyperdrive' ? { dependencies: { postgres: '^3.4.0' } } : {}),
   }, null, 2);
 
+  const dbBindingBlock = dbKind === 'hyperdrive'
+    ? `[[hyperdrive]]\nbinding = "HYPERDRIVE"\nid = "REPLACE_WITH_YOUR_HYPERDRIVE_ID"\n`
+    : `[[d1_databases]]\nbinding = "DB"\ndatabase_name = "${projectName}"\ndatabase_id = "REPLACE_WITH_YOUR_D1_ID"\n`;
+
   files['wrangler.toml'] = `name = "${projectName}"
 main = "src/index.js"
 compatibility_date = "2024-01-01"
 account_id = "${cfAccountId}"
-
-[[d1_databases]]
-binding = "DB"
-database_name = "${projectName}"
-database_id = "REPLACE_WITH_YOUR_D1_ID"
-`;
+${dbKind === 'hyperdrive' ? 'compatibility_flags = ["nodejs_compat"]\n' : ''}
+${dbBindingBlock}`;
 
   // Entry
   const routeImports = routes.map(r => `import { handle${cap(r)} } from './routes/${r}.js';`).join('\n');
@@ -83,6 +88,37 @@ ${routeMatches}
   }
 
   if (routes.includes('users')) {
+    if (dbKind === 'hyperdrive') {
+    files['src/routes/users.js'] = `import postgres from 'postgres';
+
+export async function handleUsers(request, env) {
+  const sql = postgres(env.HYPERDRIVE.connectionString);
+  const url = new URL(request.url);
+  const id = url.pathname.replace('/users/', '').replace('/users', '') || null;
+
+  if (request.method === 'GET' && !id) {
+    const rows = await sql\`SELECT * FROM users LIMIT 50\`;
+    return Response.json(rows);
+  }
+  if (request.method === 'GET' && id) {
+    const rows = await sql\`SELECT * FROM users WHERE id = \${id}\`;
+    if (!rows[0]) return Response.json({ error: 'Not found' }, { status: 404 });
+    return Response.json(rows[0]);
+  }
+  if (request.method === 'POST') {
+    const body = await request.json();
+    const newId = crypto.randomUUID();
+    await sql\`INSERT INTO users (id, email) VALUES (\${newId}, \${body.email})\`;
+    return Response.json({ id: newId }, { status: 201 });
+  }
+  if (request.method === 'DELETE' && id) {
+    await sql\`DELETE FROM users WHERE id = \${id}\`;
+    return Response.json({ ok: true });
+  }
+  return Response.json({ error: 'Method not allowed' }, { status: 405 });
+}
+`;
+    } else {
     files['src/routes/users.js'] = `export async function handleUsers(request, env) {
   const url = new URL(request.url);
   const id = url.pathname.replace('/users/', '').replace('/users', '') || null;
@@ -109,9 +145,38 @@ ${routeMatches}
   return Response.json({ error: 'Method not allowed' }, { status: 405 });
 }
 `;
+    }
   }
 
   if (routes.includes('content')) {
+    if (dbKind === 'hyperdrive') {
+    files['src/routes/content.js'] = `import postgres from 'postgres';
+
+export async function handleContent(request, env) {
+  const sql = postgres(env.HYPERDRIVE.connectionString);
+  const url = new URL(request.url);
+  const slug = url.pathname.replace('/content/', '').replace('/content', '') || null;
+
+  if (request.method === 'GET' && !slug) {
+    const rows = await sql\`SELECT id, slug, title, status FROM cms_pages LIMIT 50\`;
+    return Response.json(rows);
+  }
+  if (request.method === 'GET' && slug) {
+    const rows = await sql\`SELECT * FROM cms_pages WHERE slug = \${slug}\`;
+    if (!rows[0]) return Response.json({ error: 'Not found' }, { status: 404 });
+    return Response.json(rows[0]);
+  }
+  if (request.method === 'POST') {
+    const body = await request.json();
+    const id = crypto.randomUUID();
+    await sql\`INSERT INTO cms_pages (id, slug, title, template, content_json)
+      VALUES (\${id}, \${body.slug}, \${body.title}, \${body.template ?? 'default'}, \${JSON.stringify(body.content ?? {})})\`;
+    return Response.json({ id }, { status: 201 });
+  }
+  return Response.json({ error: 'Method not allowed' }, { status: 405 });
+}
+`;
+    } else {
     files['src/routes/content.js'] = `export async function handleContent(request, env) {
   const url = new URL(request.url);
   const slug = url.pathname.replace('/content/', '').replace('/content', '') || null;
@@ -136,6 +201,7 @@ ${routeMatches}
   return Response.json({ error: 'Method not allowed' }, { status: 405 });
 }
 `;
+    }
   }
 
   if (routes.includes('webhook')) {
@@ -154,13 +220,17 @@ ${routeMatches}
 `;
   }
 
-  // Migration
+  // Migration — column syntax differs: SQLite (D1) uses INTEGER/unixepoch(), Postgres uses TIMESTAMPTZ/NOW()
+  const createdAtCol = dbKind === 'hyperdrive'
+    ? 'created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()'
+    : 'created_at INTEGER NOT NULL DEFAULT (unixepoch())';
+
   let sql = `-- ${projectName} initial schema\n\n`;
   if (routes.includes('users')) {
     sql += `CREATE TABLE IF NOT EXISTS users (
   id TEXT PRIMARY KEY,
   email TEXT NOT NULL UNIQUE,
-  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+  ${createdAtCol}
 );\n\n`;
   }
   if (routes.includes('content')) {
@@ -171,12 +241,23 @@ ${routeMatches}
   template TEXT NOT NULL DEFAULT 'default',
   content_json TEXT,
   status TEXT NOT NULL DEFAULT 'draft',
-  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+  ${createdAtCol}
 );\n\n`;
   }
 
   files['migrations/001_init.sql'] = sql;
 
+  const deploySteps = dbKind === 'hyperdrive'
+    ? `npm install
+npx wrangler hyperdrive create ${projectName} --connection-string="postgres://user:pass@host:5432/db"
+# paste the returned Hyperdrive id into wrangler.toml as HYPERDRIVE binding
+npx wrangler deploy`
+    : `npm install
+npx wrangler d1 create ${projectName}
+# paste database_id into wrangler.toml
+npx wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote
+npx wrangler deploy`;
+
   files['README.md'] = `# ${projectName}
 
 Scaffolded by [@inneranimalmedia/agentsam-sdk](https://github.com/SamPrimeaux/agentsam-sdk).
@@ -185,14 +266,14 @@ Scaffolded by [@inneranimalmedia/agentsam-sdk](https://github.com/SamPrimeaux/ag
 
 ${routes.map(r => `- \`/${r}\``).join('\n')}
 
+## Database
+
+${dbKind === 'hyperdrive' ? 'Your own Postgres, via Cloudflare Hyperdrive.' : 'Cloudflare D1 (SQLite).'}
+
 ## Deploy
 
 \`\`\`bash
-npm install
-npx wrangler d1 create ${projectName}
-# paste database_id into wrangler.toml
-npx wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote
-npx wrangler deploy
+${deploySteps}
 \`\`\`
 `;
 

package/src/lib/scaffold/wizards/worker-api.js

@@ -5,6 +5,7 @@
 
 import {
   text,
+  select,
   multiselect,
   confirm,
   spinner,
@@ -42,6 +43,15 @@ export async function runWorkerApiWizard() {
   });
   if (isCancel(routes)) { cancel('Cancelled.'); process.exit(0); }
 
+  const dbKind = await select({
+    message: 'Database?',
+    options: [
+      { value: 'd1', label: 'Cloudflare D1', hint: 'Native, free tier, SQLite' },
+      { value: 'hyperdrive', label: 'Your own Postgres (Hyperdrive)', hint: 'Supabase, Neon, RDS, etc.' },
+    ],
+  });
+  if (isCancel(dbKind)) { cancel('Cancelled.'); process.exit(0); }
+
   const cfAccountId = await text({
     message: 'Cloudflare account ID?',
     placeholder: 'abc123...',
@@ -57,20 +67,26 @@ export async function runWorkerApiWizard() {
   const s = spinner();
   s.start('Generating files...');
 
-  const config = { projectName: projectName.trim(), routes, cfAccountId: cfAccountId.trim() };
+  const config = { projectName: projectName.trim(), routes, cfAccountId: cfAccountId.trim(), dbKind };
   const fileTree = workerApiTemplates(config);
   await writeFileTree(`./${config.projectName}`, fileTree);
 
   s.stop(pc.green(`Files written to ./${config.projectName}/`));
 
-  note(
-    [
-      `cd ${config.projectName}`,
-      `npm install`,
-      `npx wrangler d1 create ${config.projectName}`,
-      `npx wrangler d1 execute ${config.projectName} --file=migrations/001_init.sql --remote`,
-      `npx wrangler deploy`,
-    ].join('\n'),
-    'Next steps'
-  );
+  const nextSteps = dbKind === 'hyperdrive'
+    ? [
+        `cd ${config.projectName}`,
+        `npm install`,
+        `npx wrangler hyperdrive create ${config.projectName} --connection-string="postgres://user:pass@host:5432/db"`,
+        `# paste the returned Hyperdrive id into wrangler.toml`,
+        `npx wrangler deploy`,
+      ]
+    : [
+        `cd ${config.projectName}`,
+        `npm install`,
+        `npx wrangler d1 create ${config.projectName}`,
+        `npx wrangler d1 execute ${config.projectName} --file=migrations/001_init.sql --remote`,
+        `npx wrangler deploy`,
+      ];
+  note(nextSteps.join('\n'), 'Next steps');
 }

package/src/lib/slash-commands.js

@@ -1,35 +1,42 @@
-/**
- * Canonical slash-command surface for Agent Sam SDK CLI / shell UX.
- * Consumed by the interactive `agentsam shell` REPL and presentation layers.
- */
+/** Canonical, implemented slash-command surface for Agent Sam SDK CLI. */
 
 export const SHELL_THEMES = ['NIGHT', 'DAY', 'LAVA', 'VOID'];
 
-/** @type {Array<{ cmd: string, description: string, lane?: string }>} */
 export const SLASH_COMMANDS = [
-  { cmd: '/help', description: 'Show Agent Sam commands' },
+  { cmd: '/model', description: 'Choose exact model, reasoning level, and processing tier', lane: 'model' },
+  { cmd: '/reasoning', description: 'Set reasoning effort for the selected model', lane: 'model' },
+  { cmd: '/fast', description: 'Use provider Fast processing when the selected model supports it', lane: 'model' },
+  { cmd: '/flex', description: 'Use provider Flex processing when the selected model supports it', lane: 'model' },
+  { cmd: '/standard', description: 'Return to Standard provider processing', lane: 'model' },
+  { cmd: '/context', description: 'Show model context economics; add repo for Git bridge context', lane: 'context' },
   { cmd: '/status', description: 'Local project, DB, Git, and PTY health', lane: 'local' },
-  { cmd: '/context', description: 'Current Git repository and revision', lane: 'git' },
+  { cmd: '/models', description: 'Probe providers and provider-verified known models', lane: 'model' },
+  { cmd: '/login', description: 'Sign in to Inner Animal Media and save the machine-local Agent Sam session', lane: 'identity' },
+  { cmd: '/logout', description: 'Sign out locally without deleting provider credentials', lane: 'identity' },
+  { cmd: '/whoami', description: 'Show authenticated account identity and safe credential status', lane: 'identity' },
+  { cmd: '/session', description: 'Show current session usage, cost, and resume receipt', lane: 'observability' },
+  { cmd: '/usage', description: 'Show token usage, spend breakdown, and resume command', lane: 'observability' },
+  { cmd: '/cf', description: 'Cloudflare native reads, Wrangler status, and CPU profile analysis', lane: 'cloudflare' },
+  { cmd: '/settings', description: 'Choose project, runtime, terminal, and model policy' },
   { cmd: '/pwd', description: 'Print working directory', lane: 'terminal' },
   { cmd: '/cd', description: 'Change working directory', lane: 'terminal' },
-  { cmd: '/git', description: 'Git status, diff, branch, commit, and remote', lane: 'git' },
+  { cmd: '/git', description: 'Run an explicit Git subcommand', lane: 'git' },
+  { cmd: '/diff', description: 'Show the current Git diff', lane: 'git' },
   { cmd: '/db', description: 'Local SQLite status and query helpers', lane: 'data' },
-  { cmd: '/agent', description: 'Send a goal to the configured Agent Sam', lane: 'agent' },
-  { cmd: '/models', description: 'Show available model providers and local models' },
-  { cmd: '/settings', description: 'Choose project, runtime, terminal, and model preference' },
+  { cmd: '/agent', description: 'Send a goal to the configured local Agent Sam runtime', lane: 'agent' },
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
+  { cmd: '/clear', description: 'Clear the terminal display', lane: 'terminal' },
+  { cmd: '/help', description: 'Show the factual implemented command catalog' },
   { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];
 
-/** Shell UX rollout phases (gorilla-shell → SDK default CLI experience). */
 export const SHELL_PHASES = [
   { id: '0-prototype', label: 'Visual prototype + demo scenarios', status: 'complete' },
-  { id: 'pty-connection', label: 'Local PTY via agentsam start-local', status: 'current' },
-  { id: 'hud-layer', label: 'Quest log, tool gate, XP HUD', status: 'planned' },
-  { id: 'buddy-system', label: 'In-shell Agent Sam via MCP', status: 'planned' },
+  { id: 'pty-connection', label: 'Local PTY via agentsam start-local', status: 'complete' },
+  { id: 'model-context-controls', label: 'Model, reasoning, processing, and context economics', status: 'complete' },
+  { id: 'run-telemetry', label: 'Provider usage, cost, resumable sessions, and permission receipts', status: 'current' },
   { id: 'dashboard-embed', label: 'Embeddable shell for IAM dashboard', status: 'planned' },
-  { id: 'standalone-pwa', label: 'Installable PWA / SDK default shell', status: 'planned' },
 ];
 
 export function listSlashCommands(opts = {}) {

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;
+}