@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/src/lib/deploy/health.js

@@ -0,0 +1,57 @@
+export const DEFAULT_HEALTH_ORIGIN = 'https://agentsam.inneranimalmedia.com';
+export const HEALTH_USER_AGENT = 'AgentSam-deploy-health/1';
+
+export function parseWranglerVersionId(output = '') {
+  const text = String(output || '');
+  const m = text.match(/Current Version ID:\s*([0-9a-f-]{36})/i)
+    || text.match(/Version ID:\s*([0-9a-f-]{36})/i);
+  return m ? m[1] : null;
+}
+
+export function resolveHealthOrigin({ env = process.env, wranglerConfigText = '' } = {}) {
+  const fromEnv = String(env.PRODUCT_HOST || env.AGENTSAM_HEALTH_ORIGIN || '').trim();
+  if (fromEnv) return fromEnv.replace(/\/+$/, '');
+  const m = String(wranglerConfigText || '').match(/"pattern"\s*:\s*"([^"]+)"/);
+  if (m) {
+    const host = m[1].trim();
+    if (host.startsWith('http://') || host.startsWith('https://')) return host.replace(/\/+$/, '');
+    return `https://${host.replace(/\/+$/, '')}`;
+  }
+  return DEFAULT_HEALTH_ORIGIN;
+}
+
+export async function probeDeployHealth(origin, { fetchImpl = globalThis.fetch, paths = ['/health', '/'] } = {}) {
+  const results = {};
+  for (const p of paths) {
+    const url = `${String(origin).replace(/\/+$/, '')}${p}`;
+    try {
+      const res = await fetchImpl(url, {
+        redirect: 'manual',
+        headers: {
+          'User-Agent': HEALTH_USER_AGENT,
+          Accept: 'application/json,text/html,*/*',
+        },
+      });
+      let body = null;
+      if (p === '/health') {
+        try { body = await res.json(); } catch { body = null; }
+      }
+      const ok = res.status >= 200 && res.status < 400;
+      results[p] = {
+        status: res.status,
+        ok,
+        ...(body && typeof body === 'object' ? {
+          appOk: body.ok === true,
+          cloudflareConfigured: Boolean(body?.connections?.cloudflare?.configured),
+        } : {}),
+      };
+    } catch (err) {
+      results[p] = { status: 0, ok: false, error: err.message };
+    }
+  }
+  return {
+    origin,
+    results,
+    ok: Object.values(results).every((r) => r.ok),
+  };
+}

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

@@ -0,0 +1,283 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { assertProductionDeployAllowed, inspectDeployGit } from './git-guard.js';
+import { assertNoDeploySecrets } from './secret-scan.js';
+import { parseWranglerVersionId, probeDeployHealth, resolveHealthOrigin } from './health.js';
+
+export const LOCAL_STUDIO_REL = 'apps/local-studio';
+export const WRANGLER_CONFIG_REL = 'backend/wrangler.jsonc';
+export const DEPLOY_INPUT_GLOBS = Object.freeze([
+  'apps/local-studio',
+  'packages/agentsam-contracts',
+  'packages/agentsam-workbench',
+  'packages/connectors/cloudflare',
+]);
+
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'apps/local-studio/backend/wrangler.jsonc'))) return dir;
+    if (fs.existsSync(path.join(dir, 'backend/wrangler.jsonc')) && path.basename(dir) === 'local-studio') {
+      return path.dirname(path.dirname(dir));
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return start;
+    dir = parent;
+  }
+}
+
+export function resolveLocalStudioDeployable(cwd = process.cwd()) {
+  const repoRoot = findRepoRoot(cwd);
+  const appRoot = path.join(repoRoot, LOCAL_STUDIO_REL);
+  const wranglerConfig = path.join(appRoot, WRANGLER_CONFIG_REL);
+  if (!fs.existsSync(wranglerConfig)) {
+    throw new Error(`wrangler config missing: ${wranglerConfig}`);
+  }
+  return {
+    repoRoot,
+    appRoot,
+    wranglerConfig,
+    wranglerArgs: ['deploy', '-c', WRANGLER_CONFIG_REL],
+    provider: 'cloudflare',
+    app: 'local-studio',
+  };
+}
+
+export function loadOptionalCloudflareEnv(appRoot) {
+  const file = path.join(appRoot, '.env.cloudflare');
+  if (!fs.existsSync(file)) return { loaded: false, vars: {} };
+  const vars = {};
+  for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return { loaded: true, vars };
+}
+
+function hashFile(file) {
+  const h = crypto.createHash('sha256');
+  h.update(fs.readFileSync(file));
+  return h.digest('hex');
+}
+
+function walkFiles(dir, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.output' || ent.name === '.wrangler' || ent.name === '.git') continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkFiles(full, acc);
+    else acc.push(full);
+  }
+  return acc;
+}
+
+export function computeDeployFingerprint(repoRoot) {
+  const h = crypto.createHash('sha256');
+  const files = [];
+  for (const rel of DEPLOY_INPUT_GLOBS) {
+    walkFiles(path.join(repoRoot, rel), files);
+  }
+  files.sort();
+  for (const file of files) {
+    const rel = path.relative(repoRoot, file).split(path.sep).join('/');
+    h.update(rel);
+    h.update('\0');
+    h.update(hashFile(file));
+    h.update('\n');
+  }
+  return h.digest('hex');
+}
+
+export function readBaselineFingerprint(appRoot) {
+  const receipt = path.join(appRoot, '.agentsam/deploy-merkle/latest.receipt.json');
+  if (!fs.existsSync(receipt)) return null;
+  try {
+    const json = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    return json.deployProjectionHash || json.fingerprint || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeDeployReceipt(appRoot, receipt) {
+  const dir = path.join(appRoot, '.agentsam/deploy-merkle');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, receipt.promoted ? 'latest.receipt.json' : 'pending.receipt.json');
+  fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + '\n');
+  return file;
+}
+
+export function wranglerDeployCommand(target, { dryRun = false } = {}) {
+  const args = ['wrangler', ...target.wranglerArgs];
+  if (dryRun) args.push('--dry-run');
+  return { cwd: target.appRoot, args, bin: 'npx' };
+}
+
+export function isLocalStudioCheckout(cwd = process.cwd()) {
+  try {
+    resolveLocalStudioDeployable(cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runLocalStudioDeploy({
+  cwd = process.cwd(),
+  dryRun = false,
+  planOnly = false,
+  skipBuild = false,
+  execute = true,
+  skipSecretScan = false,
+  probeHealth = null,
+} = {}) {
+  const target = resolveLocalStudioDeployable(cwd);
+  if (path.resolve(cwd) === target.repoRoot && !target.wranglerConfig.endsWith(path.join('backend', 'wrangler.jsonc')) && !target.wranglerConfig.endsWith('backend/wrangler.jsonc')) {
+    throw new Error('refusing generic repo-root wrangler deploy');
+  }
+  const envFile = loadOptionalCloudflareEnv(target.appRoot);
+  const fingerprint = computeDeployFingerprint(target.repoRoot);
+  const baseline = readBaselineFingerprint(target.appRoot);
+  const gitInfo = inspectDeployGit(target.repoRoot);
+  const wranglerText = fs.readFileSync(target.wranglerConfig, 'utf8');
+  const healthOrigin = resolveHealthOrigin({ env: { ...process.env, ...envFile.vars }, wranglerConfigText: wranglerText });
+  const plan = {
+    provider: 'cloudflare',
+    app: 'local-studio',
+    wranglerConfig: path.relative(target.repoRoot, target.wranglerConfig).split(path.sep).join('/'),
+    wranglerArgs: target.wranglerArgs,
+    cwd: path.relative(target.repoRoot, target.appRoot).split(path.sep).join('/') || '.',
+    envLoaded: envFile.loaded,
+    fingerprint,
+    baseline,
+    skip: Boolean(baseline && baseline === fingerprint && !dryRun && !planOnly),
+    genericRootDeploy: false,
+    productionGitRequired: Boolean(execute && !dryRun && !planOnly),
+    healthOrigin,
+    git: {
+      branch: gitInfo.branch,
+      head: gitInfo.head,
+      originMain: gitInfo.originMain,
+      equal: Boolean(gitInfo.head && gitInfo.head === gitInfo.originMain),
+    },
+  };
+  if (!skipSecretScan) {
+    plan.secretScan = assertNoDeploySecrets([
+      target.wranglerConfig,
+      path.join(target.appRoot, '.env.cloudflare.example'),
+      path.join(target.appRoot, 'backend/worker/index.js'),
+      path.join(target.repoRoot, 'packages/connectors/cloudflare/src/index.js'),
+    ]);
+  }
+  if (plan.skip) {
+    const receipt = {
+      ok: true,
+      skipped: true,
+      reason: 'unchanged_deploy_fingerprint',
+      deployProjectionHash: fingerprint,
+      promoted: false,
+      git: plan.git,
+      wranglerConfig: plan.wranglerConfig,
+      hostname: healthOrigin.replace(/^https?:\/\//, ''),
+    };
+    writeDeployReceipt(target.appRoot, receipt);
+    return { target, plan, receipt };
+  }
+  if (!execute || planOnly) {
+    return {
+      target,
+      plan,
+      receipt: {
+        ok: true,
+        skipped: false,
+        plan: true,
+        dryRun,
+        deployProjectionHash: fingerprint,
+        promoted: false,
+        git: plan.git,
+        wranglerConfig: plan.wranglerConfig,
+        hostname: healthOrigin.replace(/^https?:\/\//, ''),
+      },
+    };
+  }
+
+  if (!dryRun) {
+    plan.git = assertProductionDeployAllowed(target.repoRoot);
+    plan.git.equal = plan.git.head === plan.git.originMain;
+  }
+
+  const env = { ...process.env, ...envFile.vars };
+  const lock = spawnSync('npm', ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8' });
+  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' });
+    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' });
+    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 wranglerOut = `${deployed.stdout || ''}\n${deployed.stderr || ''}`;
+  const workerVersion = parseWranglerVersionId(wranglerOut);
+  if (deployed.status !== 0) {
+    const receipt = {
+      ok: false,
+      skipped: false,
+      deployProjectionHash: fingerprint,
+      promoted: false,
+      git: plan.git,
+      workerVersion,
+      error: wranglerOut,
+    };
+    writeDeployReceipt(target.appRoot, receipt);
+    throw new Error(receipt.error || 'wrangler deploy failed');
+  }
+  let health = null;
+  if (!dryRun) {
+    const probe = probeHealth || probeDeployHealth;
+    health = await probe(healthOrigin);
+    if (!health.ok) {
+      const receipt = {
+        ok: false,
+        skipped: false,
+        deployProjectionHash: fingerprint,
+        promoted: false,
+        git: plan.git,
+        workerVersion,
+        hostname: healthOrigin.replace(/^https?:\/\//, ''),
+        health,
+        error: 'postdeploy_health_failed',
+      };
+      writeDeployReceipt(target.appRoot, receipt);
+      throw new Error('postdeploy_health_failed');
+    }
+  }
+  const receipt = {
+    ok: true,
+    skipped: false,
+    dryRun,
+    deployProjectionHash: fingerprint,
+    promoted: !dryRun,
+    provider: 'cloudflare',
+    app: 'local-studio',
+    wranglerConfig: plan.wranglerConfig,
+    git: plan.git,
+    worker: 'agentsam-sdk',
+    workerVersion,
+    hostname: healthOrigin.replace(/^https?:\/\//, ''),
+    health,
+    originMainEqual: Boolean(plan.git?.head && plan.git.head === plan.git.originMain),
+  };
+  writeDeployReceipt(target.appRoot, receipt);
+  return { target, plan, receipt };
+}

package/src/lib/deploy/secret-scan.js

@@ -0,0 +1,65 @@
+/** Scan deployable files for live secrets. Fixtures and .example placeholders are allowed. */
+import fs from 'node:fs';
+
+const FIXTURES = new Set([
+  'sillynotreal',
+  'sillynotreal-secret',
+  'CHANGEME',
+  'replace-me',
+  'your-token-here',
+  '***',
+]);
+
+const LIVE_PATTERNS = [
+  { re: /\bsk-[A-Za-z0-9]{20,}\b/g, label: 'openai-like' },
+  { re: /\bxai-[A-Za-z0-9]{20,}\b/g, label: 'xai-like' },
+  { re: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-like' },
+];
+
+const ASSIGN_RE = /((?:CLOUDFLARE_OAUTH_CLIENT_SECRET|CLOUDFLARE_API_TOKEN|IAM_CLIENT_SECRET|VAULT_MASTER_KEY)\s*=\s*)([^\s#]+)/g;
+
+function isExample(filename = '') {
+  return filename.endsWith('.example') || filename.includes('.env.cloudflare.example');
+}
+
+export function scanTextForSecrets(text, { filename = '' } = {}) {
+  const findings = [];
+  const src = String(text || '');
+  for (const { re, label } of LIVE_PATTERNS) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(src))) {
+      if (FIXTURES.has(m[0])) continue;
+      findings.push({ filename, label, preview: `${m[0].slice(0, 5)}…` });
+    }
+  }
+  if (isExample(filename)) return findings;
+  ASSIGN_RE.lastIndex = 0;
+  let m;
+  while ((m = ASSIGN_RE.exec(src))) {
+    const val = m[2].replace(/^[\'"]|[\'"]$/g, '');
+    if (!val || FIXTURES.has(val) || val.includes('your-') || val.length < 16) continue;
+    findings.push({ filename, label: 'assigned-secret', preview: `${m[1].trim()}[redacted]` });
+  }
+  return findings;
+}
+
+export function scanFilesForSecrets(files = []) {
+  const findings = [];
+  for (const file of files) {
+    if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    findings.push(...scanTextForSecrets(fs.readFileSync(file, 'utf8'), { filename: file }));
+  }
+  return findings;
+}
+
+export function assertNoDeploySecrets(files = []) {
+  const findings = scanFilesForSecrets(files);
+  if (findings.length) {
+    const err = new Error('secret_scan_failed: ' + findings.map((f) => f.label).join(', '));
+    err.code = 'secret_scan_failed';
+    err.findings = findings;
+    throw err;
+  }
+  return { ok: true, findings: [] };
+}

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 { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+import { resolveAccountSdkKey } from './account-session.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -221,7 +221,7 @@ async function detectIam(explicitToken = '') {
     });
   }
 
-  const sdkToken = resolveSdkKey(process.env, explicitToken);
+  const sdkToken = resolveAccountSdkKey({ env: process.env, explicit: explicitToken }).value;
   if (sdkToken.trim()) {
     const probe = await probeSdkBearer(sdkToken);
     if (probe.valid) {

package/src/lib/execution-approvals.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SCHEMA = 'agentsam-execution-approvals-v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function homeDirectory(options = {}) { return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir()); }
+function approvalsPath(options = {}) { return path.join(homeDirectory(options), '.agentsam', 'execution-approvals.json'); }
+
+function readStore(options = {}) {
+  const filename = approvalsPath(options);
+  if (!fs.existsSync(filename)) return { schema_version: SCHEMA, approvals: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    if (parsed?.schema_version !== SCHEMA || !Array.isArray(parsed.approvals)) return { schema_version: SCHEMA, approvals: [] };
+    return parsed;
+  } catch { return { schema_version: SCHEMA, approvals: [] }; }
+}
+
+function writeStore(store, options = {}) {
+  const filename = approvalsPath(options);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
+  }
+  fs.renameSync(temp, filename);
+}
+
+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}`;
+  return id;
+}
+
+export function isExecutionApproved({ cwd, key }, options = {}) {
+  const root = path.resolve(clean(cwd) || process.cwd());
+  const target = clean(key);
+  if (!target) return false;
+  return readStore(options).approvals.some((row) => row?.cwd === root && row?.key === target);
+}
+
+export function grantExecutionApproval({ cwd, key, label = '' }, options = {}) {
+  const root = path.resolve(clean(cwd) || process.cwd());
+  const target = clean(key);
+  if (!target) throw new Error('execution_approval_key_required');
+  const store = readStore(options);
+  const approvals = store.approvals.filter((row) => !(row?.cwd === root && row?.key === target));
+  approvals.push({ cwd: root, key: target, label: clean(label) || target, created_at: new Date().toISOString() });
+  writeStore({ schema_version: SCHEMA, approvals }, options);
+  return { cwd: root, key: target, persisted: true };
+}
+
+export function listExecutionApprovals(options = {}) {
+  return readStore(options).approvals.map((row) => ({ ...row }));
+}

package/src/lib/local-sessions.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const LOCAL_SESSION_SCHEMA = 'agentsam-local-session-v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function now() { return new Date().toISOString(); }
+
+export function localSessionDirectory(options = {}) {
+  const home = path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir());
+  return path.join(home, '.agentsam', 'sessions');
+}
+
+export function createLocalSessionId() {
+  return `asess_${randomUUID()}`;
+}
+
+export function sessionTitleFromInput(input, maxChars = 72) {
+  const compact = clean(input).replace(/\s+/g, ' ');
+  if (!compact) return 'New Agent Sam session';
+  return compact.length <= maxChars ? compact : `${compact.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…`;
+}
+
+function validateSessionId(sessionId) {
+  const id = clean(sessionId);
+  if (!/^asess_[0-9a-f-]{36}$/i.test(id)) throw new Error(`invalid_session_id:${id || 'empty'}`);
+  return id;
+}
+
+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 */ }
+  }
+  return dir;
+}
+
+function normalizeUsage(value = {}) {
+  return {
+    input_tokens: Number(value.input_tokens || 0),
+    output_tokens: Number(value.output_tokens || 0),
+    cached_input_tokens: Number(value.cached_input_tokens || 0),
+    cache_write_tokens: Number(value.cache_write_tokens || 0),
+    reasoning_tokens: Number(value.reasoning_tokens || 0),
+  };
+}
+
+export function normalizeLocalSession(value = {}) {
+  const createdAt = clean(value.created_at) || now();
+  return {
+    schema_version: LOCAL_SESSION_SCHEMA,
+    id: validateSessionId(value.id || createLocalSessionId()),
+    status: clean(value.status) || 'active',
+    cwd: path.resolve(clean(value.cwd) || process.cwd()),
+    title: clean(value.title) || sessionTitleFromInput(value.last_input),
+    last_input: clean(value.last_input) || null,
+    created_at: createdAt,
+    updated_at: clean(value.updated_at) || createdAt,
+    model_key: clean(value.model_key) || null,
+    provider_model_id: clean(value.provider_model_id) || null,
+    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,
+    cumulative_usage: normalizeUsage(value.cumulative_usage || {}),
+    total_cost_usd: Number(value.total_cost_usd || 0),
+    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,
+  };
+}
+
+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);
+  return normalized;
+}
+
+export function createLocalSession(value = {}, options = {}) {
+  return saveLocalSession(normalizeLocalSession({ ...value, id: value.id || createLocalSessionId(), created_at: now(), updated_at: now() }), options);
+}
+
+export function loadLocalSession(sessionId, options = {}) {
+  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);
+}
+
+export function updateLocalSession(sessionId, patch = {}, options = {}) {
+  const current = loadLocalSession(sessionId, options);
+  if (!current) throw new Error(`session_not_found:${sessionId}`);
+  return saveLocalSession({ ...current, ...patch, id: current.id, created_at: current.created_at }, options);
+}
+
+export function listLocalSessions(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 */ }
+  }
+  return rows.sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at))).slice(0, limit);
+}