@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/lib/core-client.js

@@ -1,27 +1,79 @@
 import { resolveIamOrigin } from '../../packages/identity/src/contracts/auth-config.js';
+import { resolveAccountAuthority } from './auth.js';
 
 /**
  * IAM CORE client — SDK is a delivery mechanism; intelligence lives server-side.
  *
- * IAM_ORIGIN is the canonical platform authority/API origin. During the
- * migration window IAM_CORE_URL / AGENTSAM_CORE_URL remain compatibility-only
- * fallbacks. Without a CORE backend, consumers get scaffold/local CLI only.
+ * IAM_OAUTH_ISSUER is the canonical platform authority/API origin. IAM_ORIGIN,
+ * IAM_CORE_URL and AGENTSAM_CORE_URL remain compatibility fallbacks.
  */
-
 export function coreBaseUrl(env = process.env) {
-  const explicit = env?.IAM_ORIGIN || env?.IAM_CORE_URL || env?.AGENTSAM_CORE_URL || '';
+  const explicit = env?.IAM_OAUTH_ISSUER || env?.IAM_ORIGIN || env?.IAM_CORE_URL || env?.AGENTSAM_CORE_URL || '';
   return resolveIamOrigin(env, explicit);
 }
 
-export async function postJson(path, body, token) {
-  const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
-  if (token) headers.Authorization = `Bearer ${token}`;
-  const res = await fetch(`${coreBaseUrl()}${path}`, {
+function authOptions(options) {
+  if (typeof options === 'string') return { bearer: options };
+  return options && typeof options === 'object' ? options : {};
+}
+
+export async function resolveCoreAuthority(options = {}) {
+  const resolvedOptions = authOptions(options);
+  const resolver = resolvedOptions.resolveAuthorityImpl || resolveAccountAuthority;
+  const authority = await resolver({
+    env: resolvedOptions.env || process.env,
+    home: resolvedOptions.home,
+    explicit: resolvedOptions.explicit || resolvedOptions.token || '',
+    fetchImpl: resolvedOptions.fetchImpl,
+    issuer: resolvedOptions.issuer,
+    signal: resolvedOptions.signal,
+    nowMs: resolvedOptions.nowMs,
+    skewMs: resolvedOptions.skewMs,
+    refreshImpl: resolvedOptions.refreshImpl,
+    forceRefresh: resolvedOptions.forceRefresh === true,
+  });
+  if (authority?.error) throw new Error(authority.error);
+  if (!authority?.value) throw new Error('account_auth_required');
+  return authority;
+}
+
+async function authorizedHeaders(headers, options = {}) {
+  if (String(options?.bearer || '').trim()) {
+    return { headers: { ...headers, Authorization: `Bearer ${String(options.bearer).trim()}` }, authority: { kind: 'resolved_bearer' } };
+  }
+  const authority = await resolveCoreAuthority(options);
+  return { headers: { ...headers, Authorization: `Bearer ${authority.value}` }, authority };
+}
+
+async function authorizedFetch(url, init, options = {}) {
+  const baseHeaders = init.headers || {};
+  let resolved = await authorizedHeaders(baseHeaders, options);
+  let response = await (options.fetchImpl || fetch)(url, { ...init, headers: resolved.headers });
+  if (response.status === 401 && resolved.authority?.kind === 'browser_oauth' && options.forceRefresh !== true) {
+    resolved = await authorizedHeaders(baseHeaders, { ...options, forceRefresh: true });
+    response = await (options.fetchImpl || fetch)(url, { ...init, headers: resolved.headers });
+  }
+  return response;
+}
+
+async function responseJson(res) {
+  return res.json().catch(() => ({}));
+}
+
+export async function postJson(path, body, options = {}) {
+  const resolvedOptions = authOptions(options);
+  const fetchImpl = resolvedOptions.fetchImpl || fetch;
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  };
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
     method: 'POST',
     headers,
     body: JSON.stringify(body ?? {}),
-  });
-  const data = await res.json().catch(() => ({}));
+    signal: resolvedOptions.signal,
+  }, { ...resolvedOptions, fetchImpl });
+  const data = await responseJson(res);
   if (!res.ok) {
     const msg = data?.error || data?.message || `HTTP ${res.status}`;
     throw new Error(String(msg));
@@ -29,14 +81,25 @@ export async function postJson(path, body, token) {
   return data;
 }
 
-export async function getJson(path, token) {
-  const headers = { Accept: 'application/json' };
-  if (token) headers.Authorization = `Bearer ${token}`;
-  const res = await fetch(`${coreBaseUrl()}${path}`, { headers });
-  const data = await res.json().catch(() => ({}));
+export async function getJson(path, options = {}) {
+  const resolvedOptions = authOptions(options);
+  const fetchImpl = resolvedOptions.fetchImpl || fetch;
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
+    headers: { Accept: 'application/json' },
+    signal: resolvedOptions.signal,
+  }, { ...resolvedOptions, fetchImpl });
+  const data = await responseJson(res);
   if (!res.ok) {
     const msg = data?.error || data?.message || `HTTP ${res.status}`;
-    throw new Error(String(msg));
+    const error = new Error(String(msg));
+    // Previously discarded: status code and which endpoint failed. Both are
+    // known here and cost nothing to keep -- callers (whoami, etc.) can now
+    // surface "Unauthorized (HTTP 401 from /api/sdk/context)" instead of a
+    // bare "Unauthorized" with no way to tell what actually failed.
+    error.status = res.status;
+    error.endpoint = path;
+    error.requestId = res.headers?.get?.('cf-ray') || data?.request_id || null;
+    throw error;
   }
   return data;
 }
@@ -44,18 +107,21 @@ export async function getJson(path, token) {
 /**
  * Stream NDJSON from POST /api/sdk/scaffold — calls onEvent for each line.
  */
-export async function streamScaffold(body, token, onEvent) {
-  const res = await fetch(`${coreBaseUrl()}/api/sdk/scaffold`, {
+export async function streamScaffold(body, onEvent, options = {}) {
+  const resolvedOptions = authOptions(options);
+  const fetchImpl = resolvedOptions.fetchImpl || fetch;
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/x-ndjson',
+  };
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}/api/sdk/scaffold`, {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Accept: 'application/x-ndjson',
-      Authorization: `Bearer ${token}`,
-    },
+    headers,
     body: JSON.stringify(body),
-  });
+    signal: resolvedOptions.signal,
+  }, { ...resolvedOptions, fetchImpl });
   if (!res.ok) {
-    const data = await res.json().catch(() => ({}));
+    const data = await responseJson(res);
     throw new Error(data?.error || `scaffold HTTP ${res.status}`);
   }
   if (!res.body) throw new Error('scaffold stream missing');
@@ -71,15 +137,13 @@ export async function streamScaffold(body, token, onEvent) {
     const lines = buf.split('\n');
     buf = lines.pop() || '';
     for (const line of lines) {
-      const t = line.trim();
-      if (!t) continue;
-      let evt;
+      const text = line.trim();
+      if (!text) continue;
       try {
-        evt = JSON.parse(t);
+        await onEvent(JSON.parse(text));
       } catch {
-        continue;
+        /* ignore malformed stream lines */
       }
-      await onEvent(evt);
     }
   }
   const tail = buf.trim();
@@ -87,7 +151,7 @@ export async function streamScaffold(body, token, onEvent) {
     try {
       await onEvent(JSON.parse(tail));
     } catch {
-      /* ignore */
+      /* ignore malformed trailing line */
     }
   }
 }

package/src/lib/deploy/local-studio.js

@@ -120,7 +120,7 @@ export function writeDeployReceipt(appRoot, receipt) {
 export function wranglerDeployCommand(target, { dryRun = false } = {}) {
   const args = ['wrangler', ...target.wranglerArgs];
   if (dryRun) args.push('--dry-run');
-  return { cwd: target.appRoot, args, bin: 'npx' };
+  return { cwd: target.appRoot, args, bin: process.platform === 'win32' ? 'npx.cmd' : 'npx' };
 }
 
 export function isLocalStudioCheckout(cwd = process.cwd()) {
@@ -217,16 +217,17 @@ export async function runLocalStudioDeploy({
   }
 
   const env = { ...process.env, ...envFile.vars };
-  const lock = spawnSync('npm', ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8' });
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const lock = spawnSync(npmCmd, ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
   if (lock.status !== 0) throw new Error(lock.stderr || lock.stdout || 'verify:npm10-lock failed');
   if (!skipBuild) {
-    const build = spawnSync('npm', ['run', 'build'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    const build = spawnSync(npmCmd, ['run', 'build'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
     if (build.status !== 0) throw new Error(build.stderr || build.stdout || 'build failed');
-    const verify = spawnSync('npm', ['run', 'cf:verify-output'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    const verify = spawnSync(npmCmd, ['run', 'cf:verify-output'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
     if (verify.status !== 0) throw new Error(verify.stderr || verify.stdout || 'cf:verify-output failed');
   }
   const cmd = wranglerDeployCommand(target, { dryRun });
-  const deployed = spawnSync(cmd.bin, cmd.args, { cwd: cmd.cwd, env, encoding: 'utf8' });
+  const deployed = spawnSync(cmd.bin, cmd.args, { cwd: cmd.cwd, env, encoding: 'utf8', shell: process.platform === 'win32' });
   const wranglerOut = `${deployed.stdout || ''}\n${deployed.stderr || ''}`;
   const workerVersion = parseWranglerVersionId(wranglerOut);
   if (deployed.status !== 0) {

package/src/lib/detect-context.js

@@ -5,7 +5,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { coreBaseUrl } from './core-client.js';
-import { resolveAccountSdkKey } from './account-session.js';
+import { resolveAccountAuth } from './account-session.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -167,11 +167,9 @@ async function detectCloudflare() {
   };
 }
 
-async function probeSdkBearer(token) {
+async function probeAccountBearer(token) {
   const t = String(token || '').trim();
-  if (!t || !t.startsWith('sdk_')) {
-    return { valid: false, error: 'not_sdk_bearer' };
-  }
+  if (!t) return { valid: false, error: 'account_auth_required' };
   try {
     const res = await fetch(`${coreBaseUrl()}/api/sdk/context`, {
       headers: { Accept: 'application/json', Authorization: `Bearer ${t}` },
@@ -197,7 +195,7 @@ function envPresent(name) {
   return v != null && String(v).trim() !== '';
 }
 
-/** IAM auth for SDK init — only verified sdk_* bearer counts as ready. */
+/** IAM auth for SDK init — accepts a verified account API key or browser session credential. */
 async function detectIam(explicitToken = '') {
   const aux = [];
 
@@ -210,9 +208,9 @@ async function detectIam(explicitToken = '') {
     });
   }
 
-  const workerKey = envPresent('IAM_API_KEY') || envPresent('AGENTSAM_API_KEY');
+  const workerKey = envPresent('IAM_API_KEY');
   if (workerKey) {
-    const name = envPresent('IAM_API_KEY') ? 'IAM_API_KEY' : 'AGENTSAM_API_KEY';
+    const name = 'IAM_API_KEY';
     aux.push({
       var: name,
       role: 'Worker runtime secret',
@@ -221,22 +219,22 @@ async function detectIam(explicitToken = '') {
     });
   }
 
-  const sdkToken = resolveAccountSdkKey({ env: process.env, explicit: explicitToken }).value;
-  if (sdkToken.trim()) {
-    const probe = await probeSdkBearer(sdkToken);
+  const accountAuth = resolveAccountAuth({ env: process.env, explicit: explicitToken });
+  if (accountAuth.value) {
+    const probe = await probeAccountBearer(accountAuth.value);
     if (probe.valid) {
       return {
-        source: 'sdk-key',
+        source: accountAuth.kind || 'account-auth',
         ready: true,
-        detail: `AGENTSAM_SDK_KEY · user ${probe.user_id || '?'}`,
+        detail: `${accountAuth.kind === 'api_key' ? 'AGENTSAM_API_KEY' : 'browser session'} · user ${probe.user_id || '?'}`,
         probe,
         aux,
       };
     }
     return {
-      source: 'sdk-key',
+      source: accountAuth.kind || 'account-auth',
       ready: false,
-      detail: `AGENTSAM_SDK_KEY invalid (${probe.error}) → will open browser`,
+      detail: `${accountAuth.kind === 'api_key' ? 'AGENTSAM_API_KEY' : 'browser session'} invalid (${probe.error}) → will open browser`,
       probe,
       aux,
     };
@@ -247,7 +245,7 @@ async function detectIam(explicitToken = '') {
     return {
       source: 'execos-env',
       ready: false,
-      detail: `IAM_PTY_USER_ID set (ExecOS identity — SDK bearer still needed)`,
+      detail: `IAM_PTY_USER_ID set (ExecOS identity — account auth still needed)`,
       aux,
     };
   }

package/src/lib/dockerize.js

@@ -98,6 +98,7 @@ function generateViteReact(opts) {
 FROM node:20-alpine AS build
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
 COPY . .
 RUN ${buildCmd}
@@ -125,6 +126,7 @@ function generateNodeService(opts) {
 FROM node:20-alpine
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci --omit=dev; else npm install --omit=dev; fi
 COPY . .
 ENV PORT=${port}
@@ -152,6 +154,7 @@ function generateWranglerDev(opts) {
 FROM node:20-alpine
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
 COPY . .
 EXPOSE ${port}

package/src/lib/execution-approvals.js

@@ -33,6 +33,7 @@ export function toolApprovalKey(capabilityId, input = {}) {
   const id = clean(capabilityId);
   const command = clean(input?.command);
   if (id === 'cloudflare.wrangler.native' && /^[A-Za-z0-9._-]+$/.test(command)) return `${id}:${command}`;
+  if (id === 'terminal.exec' && /^[A-Za-z0-9._+-]+$/.test(command)) return `${id}:${command}`;
   return id;
 }
 

package/src/lib/identity-scaffold.js

@@ -9,7 +9,7 @@ const MIGRATION_FILE = path.join(IDENTITY_PKG, 'src', 'migrations', '0001_identi
 const BRANDING_SCRIPT = path.join(IDENTITY_PKG, 'src', 'frontend', 'auth-portal', 'shared', 'company-branding.js');
 
 /**
- * @param {{ projectName: string, brandName?: string, logoUrl?: string, sdkVersion?: string }} config
+ * @param {{ projectName: string, brandName?: string, logoUrl?: string, sdkVersion?: string, provider?: string }} config
  * @returns {Record<string, string>}
  */
 export function buildIdentityAppScaffold(config) {
@@ -17,6 +17,7 @@ export function buildIdentityAppScaffold(config) {
   const brandName = config.brandName || projectName;
   const logoUrl = config.logoUrl || '/brand/logo.svg';
   const sdkVersion = config.sdkVersion || 'alpha';
+  const provider = config.provider || 'inneranimalmedia';
 
   const migrationSql = `${fs.readFileSync(MIGRATION_FILE, 'utf8')}\n${buildCompanySeedSql({ brandName, logoUrl })}\n`;
   const loginHtml = injectBrandingScript(applyBrandTokens(fs.readFileSync(path.join(AUTH_PAGES_DIR, 'login.html'), 'utf8'), {
@@ -95,6 +96,8 @@ migrations_dir = "migrations"
 
 Boring scaffold: **app/frontend** (auth UI) + **backend** (Worker API) + **migrations** (D1).
 
+Provider template: \`${provider}\` (see \`agentsam identity plan --provider ${provider}\`).
+
 ## Quick start
 
 \`\`\`bash

package/src/lib/knowledge-docker.js

@@ -7,7 +7,13 @@ import { CONFIG_PATH, defaultConfig, readConfig } from '../knowledge/config.js';
 
 const sdkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const runtimeFiles = () => {
-  const files = ['services/knowledge/package.json', 'services/knowledge/package-lock.json', 'packages/agentsam-repository/src/merkle/hash.js', 'src/errors/contract.js'];
+  const files = [
+    'services/knowledge/package.json',
+    'services/knowledge/package-lock.json',
+    'packages/agentsam-repository/src/merkle/hash.js',
+    'packages/agentsam-errors/package.json',
+    'src/errors/contract.js',
+  ];
   const walk = dir => { for (const entry of fs.readdirSync(path.join(sdkRoot, dir), { withFileTypes: true })) {
     const file = `${dir}/${entry.name}`;
     if (entry.isDirectory()) walk(file);
@@ -15,6 +21,7 @@ const runtimeFiles = () => {
   } };
   walk('src/knowledge');
   walk('src/rpc/generated');
+  walk('packages/agentsam-errors/src');
   return files.sort();
 };
 
@@ -31,6 +38,7 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
 COPY src ./src
+COPY packages ./packages
 ENV NODE_ENV=production PORT=${port} GIT_OPTIONAL_LOCKS=0
 EXPOSE ${port}
 HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

package/src/lib/local-sessions.js

@@ -2,6 +2,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { findCliProjectRoot } from './cli-preferences.js';
+import { runtimeDatabasePath, SQLITE_RUNTIME_CAPABILITIES } from '../local/runtime-store.js';
+import { createLocalSqliteDatabaseSync } from '../local/sqlite.js';
+import { applyRuntimeMigrationsSync } from '../local/migrations.js';
 
 export const LOCAL_SESSION_SCHEMA = 'agentsam-local-session-v1';
 
@@ -33,13 +37,51 @@ function filenameFor(sessionId, options = {}) {
   return path.join(localSessionDirectory(options), `${validateSessionId(sessionId)}.json`);
 }
 
-function ensureDirectory(options = {}) {
-  const dir = localSessionDirectory(options);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') {
-    try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+function projectRoot(value = {}, options = {}) {
+  return findCliProjectRoot(options.projectRoot || value.project_root || value.cwd || options.cwd || process.cwd());
+}
+
+function withSessionDb(root, fn) {
+  const db = createLocalSqliteDatabaseSync(runtimeDatabasePath(root));
+  try {
+    applyRuntimeMigrationsSync(db);
+    return fn(db);
+  } finally {
+    db.close();
   }
-  return dir;
+}
+
+function safeProviderState(value) {
+  if (!value || typeof value !== 'object') return {};
+  // Opaque response IDs allow provider-side continuation. Message arrays and
+  // compaction input can carry prompts, tool output, or credential values.
+  return {
+    ...(clean(value.provider) ? { provider: clean(value.provider) } : {}),
+    ...(clean(value.previous_response_id) ? { previous_response_id: clean(value.previous_response_id) } : {}),
+    ...(value.has_compacted_input === true ? { has_compacted_input: true } : {}),
+  };
+}
+
+function safeLastError(value) {
+  if (!value || typeof value !== 'object') return null;
+  return {
+    code: clean(value.code) || null,
+    kind: clean(value.kind) || null,
+    source: clean(value.source) || null,
+  };
+}
+
+function safeUsageSnapshot(value) {
+  if (!value || typeof value !== 'object') return null;
+  const inputTokens = Number(value.current_context?.input_tokens);
+  const windowTokens = Number(value.current_context?.window_tokens);
+  return {
+    estimate_kind: value.estimate_kind === 'provider' ? 'provider' : 'local',
+    current_context: {
+      input_tokens: Number.isFinite(inputTokens) ? Math.max(0, inputTokens) : 0,
+      window_tokens: Number.isFinite(windowTokens) ? Math.max(0, windowTokens) : null,
+    },
+  };
 }
 
 function normalizeUsage(value = {}) {
@@ -72,13 +114,18 @@ export function normalizeLocalSession(value = {}) {
   const createdAt = clean(value.created_at) || now();
   const status = clean(value.status) || 'active';
   const updatedAt = clean(value.updated_at) || createdAt;
+  const root = projectRoot(value);
+  const dbPath = runtimeDatabasePath(root);
+  const relativeDbPath = path.relative(root, dbPath);
   return {
     schema_version: LOCAL_SESSION_SCHEMA,
     id: validateSessionId(value.id || createLocalSessionId()),
     status,
+    project_root: root,
+    storage: { runtime: 'sqlite', path: relativeDbPath.startsWith('..') ? dbPath : relativeDbPath, remote: null, capabilities: SQLITE_RUNTIME_CAPABILITIES },
     cwd: path.resolve(clean(value.cwd) || process.cwd()),
-    title: clean(value.title) || sessionTitleFromInput(value.last_input),
-    last_input: clean(value.last_input) || null,
+    title: clean(value.title) || 'Agent Sam session',
+    last_input: null,
     created_at: createdAt,
     updated_at: updatedAt,
     active_elapsed_ms: Math.max(0, Number(value.active_elapsed_ms || 0)),
@@ -88,26 +135,49 @@ export function normalizeLocalSession(value = {}) {
     reasoning_effort: clean(value.reasoning_effort) || null,
     requested_service_tier: clean(value.requested_service_tier) || null,
     actual_service_tier: clean(value.actual_service_tier) || null,
-    provider_state: value.provider_state && typeof value.provider_state === 'object' ? { ...value.provider_state } : {},
-    usage_snapshot: value.usage_snapshot && typeof value.usage_snapshot === 'object' ? structuredClone(value.usage_snapshot) : null,
+    provider_state: safeProviderState(value.provider_state),
+    latest_compaction: value.latest_compaction ? {
+      compaction_id: clean(value.latest_compaction.compaction_id) || null,
+      provider: clean(value.latest_compaction.provider) || null,
+      model: clean(value.latest_compaction.model) || null,
+      created_at: clean(value.latest_compaction.created_at) || null,
+      usage: normalizeUsage(value.latest_compaction.usage),
+      cost_usd: Number(value.latest_compaction.cost_usd || 0),
+    } : null,
+    auto_compact: value.auto_compact !== false,
+    usage_snapshot: safeUsageSnapshot(value.usage_snapshot),
     cumulative_usage: normalizeUsage(value.cumulative_usage || {}),
     total_cost_usd: Number(value.total_cost_usd || 0),
     cost_breakdown_usd: normalizeCostBreakdown(value.cost_breakdown_usd || {}),
     approved_projected_call_cost_usd: Number(value.approved_projected_call_cost_usd || 0),
-    last_error: value.last_error && typeof value.last_error === 'object' ? structuredClone(value.last_error) : null,
+    last_error: safeLastError(value.last_error),
   };
 }
 
 export function saveLocalSession(session, options = {}) {
-  const normalized = normalizeLocalSession({ ...session, updated_at: now() });
-  ensureDirectory(options);
-  const filename = filenameFor(normalized.id, options);
-  const temp = `${filename}.${process.pid}.tmp`;
-  fs.writeFileSync(temp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
-  if (process.platform !== 'win32') {
-    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
-  }
-  fs.renameSync(temp, filename);
+  const normalized = normalizeLocalSession({ ...session, project_root: projectRoot(session, options), updated_at: now() });
+  const compactedInput = session.provider_state?.compacted_input;
+  const serialized = Array.isArray(compactedInput) ? JSON.stringify(compactedInput) : null;
+  if (serialized && Buffer.byteLength(serialized) > 10 * 1024 * 1024) throw new Error('provider_continuation_too_large');
+  if (serialized) normalized.provider_state.has_compacted_input = true;
+  withSessionDb(normalized.project_root, (db) => {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      db.prepare(`
+        INSERT INTO agentsam_project_sessions (id, project_root, cwd, status, title, state_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          cwd = excluded.cwd, status = excluded.status, title = excluded.title,
+          state_json = excluded.state_json, updated_at = excluded.updated_at
+      `).run(normalized.id, normalized.project_root, normalized.cwd, normalized.status,
+        normalized.title, JSON.stringify(normalized), normalized.created_at, normalized.updated_at);
+      if (serialized) db.prepare(`INSERT INTO agentsam_provider_continuations (session_id, provider, output_json, updated_at)
+        VALUES (?, ?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET provider=excluded.provider, output_json=excluded.output_json, updated_at=excluded.updated_at`
+      ).run(normalized.id, normalized.provider_state.provider || '', serialized, normalized.updated_at);
+      else if (!normalized.provider_state.has_compacted_input) db.prepare('DELETE FROM agentsam_provider_continuations WHERE session_id = ?').run(normalized.id);
+      db.exec('COMMIT');
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  });
   return normalized;
 }
 
@@ -116,11 +186,23 @@ export function createLocalSession(value = {}, options = {}) {
 }
 
 export function loadLocalSession(sessionId, options = {}) {
+  const root = projectRoot({}, options);
+  const dbPath = runtimeDatabasePath(root);
+  if (fs.existsSync(dbPath)) {
+    const row = withSessionDb(root, (db) => db.prepare(
+      'SELECT state_json FROM agentsam_project_sessions WHERE id = ? AND project_root = ?'
+    ).get(validateSessionId(sessionId), root));
+    if (row) return normalizeLocalSession(JSON.parse(row.state_json));
+  }
+  // Read-only compatibility with older ~/.agentsam/sessions/*.json state.
+  // Import only when the saved cwd belongs to the selected project; never
+  // create new home-level session files or resume a different project's row.
   const filename = filenameFor(sessionId, options);
   if (!fs.existsSync(filename)) return null;
   const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
   if (parsed?.schema_version !== LOCAL_SESSION_SCHEMA) throw new Error(`unsupported_local_session_schema:${parsed?.schema_version || 'missing'}`);
-  return normalizeLocalSession(parsed);
+  if (projectRoot(parsed) !== root) return null;
+  return saveLocalSession(parsed, { projectRoot: root });
 }
 
 export function updateLocalSession(sessionId, patch = {}, options = {}) {
@@ -130,19 +212,27 @@ export function updateLocalSession(sessionId, patch = {}, options = {}) {
 }
 
 export function listLocalSessions(options = {}) {
+  const root = projectRoot({}, options);
   const dir = localSessionDirectory(options);
-  if (!fs.existsSync(dir)) return [];
-  const cwd = clean(options.cwd) ? path.resolve(options.cwd) : '';
-  const limit = Number.isInteger(options.limit) && options.limit > 0 ? Math.min(options.limit, 100) : 20;
-  const rows = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.startsWith('asess_') || !entry.name.endsWith('.json')) continue;
-    try {
-      const parsed = JSON.parse(fs.readFileSync(path.join(dir, entry.name), 'utf8'));
-      if (parsed?.schema_version !== LOCAL_SESSION_SCHEMA) continue;
-      const session = normalizeLocalSession(parsed);
-      if (!cwd || session.cwd === cwd) rows.push(session);
-    } catch { /* skip corrupt session file */ }
+  if (fs.existsSync(dir)) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.startsWith('asess_') || !entry.name.endsWith('.json')) continue;
+      try { loadLocalSession(entry.name.slice(0, -5), { ...options, projectRoot: root }); }
+      catch { /* legacy corrupt files remain untouched */ }
+    }
   }
-  return rows.sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at))).slice(0, limit);
+  if (!fs.existsSync(runtimeDatabasePath(root))) return [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? Math.min(options.limit, 100) : 20;
+  return withSessionDb(root, (db) => db.prepare(
+    'SELECT state_json FROM agentsam_project_sessions WHERE project_root = ? ORDER BY updated_at DESC LIMIT ?'
+  ).all(root, limit).map((row) => normalizeLocalSession(JSON.parse(row.state_json))));
+}
+
+export function loadSessionContinuation(session) {
+  if (!session?.provider_state?.has_compacted_input) return session?.provider_state || null;
+  return withSessionDb(projectRoot(session), db => {
+    const row = db.prepare('SELECT provider, output_json FROM agentsam_provider_continuations WHERE session_id = ?').get(validateSessionId(session.id));
+    if (!row || row.provider !== session.provider_state.provider) throw new Error('provider_continuation_missing');
+    return { ...session.provider_state, compacted_input: JSON.parse(row.output_json) };
+  });
 }