@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

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

package/src/lib/local-status.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { tryResolveGitContext } from './git-context.js';
 import { inspectLocalSqlite } from '../local/sqlite.js';
+import { getCreatedWithVersion, getDefaultProfile, getDeployTarget, getLocalDatabasePath, getProjectName, getProjectPreset, getRepositoryId, tryReadProjectConfig } from './project-config.js';
 
 export function findAgentSamProjectRoot(startDir = process.cwd()) {
   let dir = path.resolve(startDir);
@@ -14,16 +15,6 @@ export function findAgentSamProjectRoot(startDir = process.cwd()) {
   return path.resolve(startDir);
 }
 
-function readProjectConfig(root) {
-  const configPath = path.join(root, '.agentsam', 'config.json');
-  if (!fs.existsSync(configPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
 async function probe(url) {
   try {
     const response = await fetch(url, { signal: AbortSignal.timeout(500) });
@@ -35,12 +26,12 @@ async function probe(url) {
 
 export async function collectLocalStatus(cwd = process.cwd()) {
   const root = findAgentSamProjectRoot(cwd);
-  const config = readProjectConfig(root);
+  const config = tryReadProjectConfig(root);
   const git = tryResolveGitContext({ cwd: root });
 
   let db = { ok: false, exists: false, tables: [] };
   if (config) {
-    db = await inspectLocalSqlite(path.join(root, config.db_path || '.agentsam/data/agentsam.sqlite'));
+    db = await inspectLocalSqlite(path.join(root, getLocalDatabasePath(config)));
   }
 
   const devPort = config?.dev_port ?? 8787;
@@ -54,11 +45,12 @@ export async function collectLocalStatus(cwd = process.cwd()) {
     schemaVersion: 'agentsam-local-status-v1',
     configured: Boolean(config),
     root,
-    project: config?.project || path.basename(root),
-    lane: config?.lane || null,
-    agent: config?.agent || null,
-    deployTarget: config?.deploy_target || null,
-    scaffoldVersion: config?.scaffold_version || null,
+    project: getProjectName(config, path.basename(root)),
+    repositoryId: getRepositoryId(config),
+    lane: getProjectPreset(config),
+    agent: getDefaultProfile(config),
+    deployTarget: getDeployTarget(config),
+    scaffoldVersion: getCreatedWithVersion(config),
     git: git
       ? {
           repo: git.repoFullName || null,

package/src/lib/merkle/cloudflare-persistence.js

@@ -0,0 +1,321 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { resolveGitContext } from '../git-context.js';
+import {
+  MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  MERKLE_SNAPSHOT_TABLE,
+  MERKLE_WEBSITE_ASSETS_BINDING,
+  merkleSnapshotStorageKey,
+  normalizeMerkleStoragePrefix,
+} from './persistence.js';
+
+const D1_BINDING = 'DB';
+const CAPTURE_KINDS = new Set(['deploy', 'manual', 'agent', 'index']);
+const SOURCES = new Set(['github', 'gitlab', 'bitbucket', 'local', 'upload']);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function stripJsonComments(input) {
+  let out = '';
+  let string = false;
+  let quote = '';
+  let escaped = false;
+  let line = false;
+  let block = false;
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    const next = input[i + 1];
+    if (line) {
+      if (char === '\n') { line = false; out += char; }
+      continue;
+    }
+    if (block) {
+      if (char === '*' && next === '/') { block = false; i += 1; }
+      continue;
+    }
+    if (string) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === quote) string = false;
+      continue;
+    }
+    if (char === '"' || char === "'") { string = true; quote = char; out += char; continue; }
+    if (char === '/' && next === '/') { line = true; i += 1; continue; }
+    if (char === '/' && next === '*') { block = true; i += 1; continue; }
+    out += char;
+  }
+  return out;
+}
+
+function parseTomlBindings(text) {
+  const rows = { r2_buckets: [], d1_databases: [] };
+  let current = null;
+  let currentType = null;
+  const flush = () => {
+    if (current && currentType) rows[currentType].push(current);
+    current = null;
+    currentType = null;
+  };
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    const header = line.match(/^\[\[(?:env\.([^.\]]+)\.)?(r2_buckets|d1_databases)\]\]$/);
+    if (header) {
+      flush();
+      currentType = header[2];
+      current = { environment: header[1] || null };
+      continue;
+    }
+    if (/^\[/.test(line)) { flush(); continue; }
+    if (!current || !line || line.startsWith('#')) continue;
+    const match = line.match(/^([A-Za-z0-9_]+)\s*=\s*["']([^"']*)["']/);
+    if (match) current[match[1]] = match[2];
+  }
+  flush();
+  return rows;
+}
+
+function rowsFromJson(parsed, environment) {
+  const base = parsed && typeof parsed === 'object' ? parsed : {};
+  const env = environment && base.env?.[environment] && typeof base.env[environment] === 'object'
+    ? base.env[environment]
+    : {};
+  return {
+    r2_buckets: [...(env.r2_buckets || []), ...(base.r2_buckets || [])],
+    d1_databases: [...(env.d1_databases || []), ...(base.d1_databases || [])],
+  };
+}
+
+export function readWranglerPersistenceBindings(configPath, { environment = null } = {}) {
+  const filename = path.resolve(configPath);
+  const text = fs.readFileSync(filename, 'utf8');
+  const ext = path.extname(filename).toLowerCase();
+  let rows;
+  if (ext === '.json' || ext === '.jsonc') rows = rowsFromJson(JSON.parse(stripJsonComments(text)), environment);
+  else rows = parseTomlBindings(text);
+  const scoped = (items) => {
+    if (!environment) return items.filter((row) => !row.environment);
+    const envRows = items.filter((row) => row.environment === environment);
+    return envRows.length ? envRows : items.filter((row) => !row.environment);
+  };
+  return { configPath: filename, r2_buckets: scoped(rows.r2_buckets), d1_databases: scoped(rows.d1_databases) };
+}
+
+export function resolveWranglerMerklePersistence({
+  configPath,
+  environment = null,
+  r2Binding = MERKLE_WEBSITE_ASSETS_BINDING,
+  d1Binding = D1_BINDING,
+  r2Only = false,
+} = {}) {
+  if (!clean(configPath)) throw new Error('wrangler_config_required');
+  const rows = readWranglerPersistenceBindings(configPath, { environment });
+  const r2 = rows.r2_buckets.find((row) => clean(row.binding) === clean(r2Binding));
+  if (!r2?.bucket_name) throw new Error(`wrangler_r2_binding_not_found:${r2Binding}`);
+  const d1 = rows.d1_databases.find((row) => clean(row.binding) === clean(d1Binding));
+  if (!r2Only && !d1?.database_name) throw new Error(`wrangler_d1_binding_not_found:${d1Binding}`);
+  return {
+    config_path: rows.configPath,
+    environment: environment || null,
+    r2_binding: r2Binding,
+    storage_bucket: String(r2.bucket_name),
+    d1_binding: r2Only ? null : d1Binding,
+    database_name: r2Only ? null : String(d1.database_name),
+  };
+}
+
+function providerRepoId(git) {
+  const host = clean(git?.remoteHost).toLowerCase();
+  const fullName = clean(git?.repoFullName);
+  if (!fullName) return null;
+  if (host === 'github.com') return `github:${fullName}`;
+  if (host === 'gitlab.com') return `gitlab:${fullName}`;
+  if (host === 'bitbucket.org') return `bitbucket:${fullName}`;
+  return null;
+}
+
+function safeId(value) {
+  return clean(value).replace(/[^A-Za-z0-9._-]+/g, '').slice(0, 96);
+}
+
+function snapshotIdFor({ snapshot, repoId, captureKind, deploymentId }) {
+  const deployment = safeId(deploymentId);
+  if (captureKind === 'deploy' && deployment) return `mrs_dep_${deployment.toLowerCase()}`;
+  const digest = createHash('sha256')
+    .update([repoId, snapshot.rootHash, snapshot.semantic?.rootHash || '', captureKind].join('\0'))
+    .digest('hex');
+  return `mrs_${digest.slice(0, 24)}`;
+}
+
+function sqlEsc(value) {
+  return String(value ?? '').replaceAll("'", "''");
+}
+
+function sqlText(value) {
+  return value == null || value === '' ? 'NULL' : `'${sqlEsc(value)}'`;
+}
+
+function sqlInt(value) {
+  return value == null || value === '' || !Number.isFinite(Number(value)) ? 'NULL' : String(Math.trunc(Number(value)));
+}
+
+export function buildMerklePersistencePlan({
+  snapshot,
+  root = process.cwd(),
+  ownerUserId,
+  repoId,
+  source = 'local',
+  captureKind = 'manual',
+  connectionId = null,
+  runtimeLeaseId = null,
+  deploymentId = null,
+  workerVersionId = null,
+  referenceLabel = null,
+  storagePrefix = MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  wrangler,
+} = {}) {
+  if (!snapshot?.rootHash || !Array.isArray(snapshot?.entries)) throw new Error('merkle_snapshot_required');
+  const owner = clean(ownerUserId);
+  if (!owner) throw new Error('owner_user_id_required');
+  if (!CAPTURE_KINDS.has(captureKind)) throw new Error(`capture_kind_invalid:${captureKind}`);
+  if (!SOURCES.has(source)) throw new Error(`source_invalid:${source}`);
+  if (captureKind !== 'deploy' && !clean(connectionId) && !clean(runtimeLeaseId)) throw new Error('execution_provenance_required');
+  let git = null;
+  try { git = resolveGitContext({ cwd: root }); } catch { git = null; }
+  const resolvedRepoId = clean(repoId) || providerRepoId(git);
+  if (!resolvedRepoId) throw new Error('repo_id_required');
+  const snapshotId = snapshotIdFor({ snapshot, repoId: resolvedRepoId, captureKind, deploymentId });
+  const prefix = normalizeMerkleStoragePrefix(storagePrefix);
+  const storageKey = merkleSnapshotStorageKey({ ownerUserId: owner, repoId: resolvedRepoId, snapshotId, prefix });
+  const createdAt = Math.floor(Date.now() / 1000);
+  const classifier = snapshot.semantic?.classifier || null;
+  const row = {
+    snapshot_id: snapshotId,
+    owner_user_id: owner,
+    repo_id: resolvedRepoId,
+    repository: git?.remoteUrl || null,
+    source,
+    manifest_format: snapshot.format || 'agentsam-merkle',
+    manifest_version: snapshot.version || 1,
+    hash_algorithm: snapshot.algorithm || 'sha256',
+    root_hash: snapshot.rootHash,
+    policy_hash: snapshot.policyHash || null,
+    resolved_commit_sha: git?.revisionSha || null,
+    resolved_tree_sha: null,
+    git_branch: git?.branch || null,
+    working_tree_dirty: git?.dirty ? 1 : 0,
+    connection_id: clean(connectionId) || null,
+    runtime_lease_id: clean(runtimeLeaseId) || null,
+    storage_backend: 'r2',
+    storage_bucket: wrangler.storage_bucket,
+    storage_key: storageKey,
+    entry_count: snapshot.entries.length,
+    file_count: snapshot.stats?.files ?? null,
+    directory_count: snapshot.stats?.directories ?? null,
+    symlink_count: snapshot.stats?.symlinks ?? 0,
+    total_bytes: snapshot.stats?.bytes ?? null,
+    capture_kind: captureKind,
+    deployment_id: clean(deploymentId) || null,
+    worker_version_id: clean(workerVersionId) || null,
+    reference_label: clean(referenceLabel) || `${captureKind}:${snapshotId}`,
+    created_at: createdAt,
+    persisted_at: createdAt,
+    metadata_root: snapshot.semantic?.rootHash || null,
+    classifier_format: classifier?.format || null,
+    classifier_version: classifier?.version ?? null,
+    classifier_source: classifier?.source || null,
+  };
+  return { snapshot_id: snapshotId, storage_key: storageKey, row, wrangler, prefix };
+}
+
+export function merklePersistenceUpsertSql(row) {
+  return `INSERT INTO ${MERKLE_SNAPSHOT_TABLE} (
+  snapshot_id, owner_user_id, repo_id, repository, source,
+  manifest_format, manifest_version, hash_algorithm, root_hash, policy_hash,
+  resolved_commit_sha, resolved_tree_sha, git_branch, working_tree_dirty,
+  connection_id, runtime_lease_id, storage_backend, storage_bucket, storage_key,
+  entry_count, file_count, directory_count, symlink_count, total_bytes,
+  capture_kind, deployment_id, worker_version_id, reference_label,
+  created_at, persisted_at, metadata_root, classifier_format, classifier_version, classifier_source
+) VALUES (
+  ${sqlText(row.snapshot_id)}, ${sqlText(row.owner_user_id)}, ${sqlText(row.repo_id)}, ${sqlText(row.repository)}, ${sqlText(row.source)},
+  ${sqlText(row.manifest_format)}, ${sqlInt(row.manifest_version)}, ${sqlText(row.hash_algorithm)}, ${sqlText(row.root_hash)}, ${sqlText(row.policy_hash)},
+  ${sqlText(row.resolved_commit_sha)}, ${sqlText(row.resolved_tree_sha)}, ${sqlText(row.git_branch)}, ${sqlInt(row.working_tree_dirty)},
+  ${sqlText(row.connection_id)}, ${sqlText(row.runtime_lease_id)}, ${sqlText(row.storage_backend)}, ${sqlText(row.storage_bucket)}, ${sqlText(row.storage_key)},
+  ${sqlInt(row.entry_count)}, ${sqlInt(row.file_count)}, ${sqlInt(row.directory_count)}, ${sqlInt(row.symlink_count)}, ${sqlInt(row.total_bytes)},
+  ${sqlText(row.capture_kind)}, ${sqlText(row.deployment_id)}, ${sqlText(row.worker_version_id)}, ${sqlText(row.reference_label)},
+  ${sqlInt(row.created_at)}, ${sqlInt(row.persisted_at)}, ${sqlText(row.metadata_root)}, ${sqlText(row.classifier_format)}, ${sqlInt(row.classifier_version)}, ${sqlText(row.classifier_source)}
+)
+ON CONFLICT(snapshot_id) DO UPDATE SET
+  storage_backend=excluded.storage_backend,
+  storage_bucket=excluded.storage_bucket,
+  storage_key=excluded.storage_key,
+  persisted_at=excluded.persisted_at,
+  deployment_id=excluded.deployment_id,
+  worker_version_id=excluded.worker_version_id,
+  reference_label=excluded.reference_label,
+  metadata_root=excluded.metadata_root,
+  classifier_format=excluded.classifier_format,
+  classifier_version=excluded.classifier_version,
+  classifier_source=excluded.classifier_source;`;
+}
+
+function wranglerArgs(base, wrangler) {
+  const args = [...base, '--config', wrangler.config_path];
+  if (wrangler.environment) args.push('--env', wrangler.environment);
+  return args;
+}
+
+export function persistMerkleSnapshotCloudflare({
+  snapshotPath,
+  snapshot,
+  plan,
+  wranglerBin = process.env.WRANGLER_BIN || 'wrangler',
+  r2Only = false,
+  dryRun = false,
+} = {}) {
+  const filename = path.resolve(snapshotPath);
+  if (!fs.existsSync(filename)) throw new Error('snapshot_file_not_found');
+  const result = {
+    provider: 'cloudflare',
+    binding: plan.wrangler.r2_binding,
+    storage_bucket: plan.row.storage_bucket,
+    storage_key: plan.row.storage_key,
+    database_binding: plan.wrangler.d1_binding,
+    database_name: plan.wrangler.database_name,
+    table: r2Only ? null : MERKLE_SNAPSHOT_TABLE,
+    snapshot_id: plan.row.snapshot_id,
+    row: plan.row,
+    dry_run: Boolean(dryRun),
+  };
+  if (dryRun) return result;
+
+  const object = `${plan.row.storage_bucket}/${plan.row.storage_key}`;
+  execFileSync(wranglerBin, wranglerArgs(['r2', 'object', 'put', object, '--file', filename, '--remote'], plan.wrangler), {
+    stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+  });
+  if (r2Only) return result;
+
+  const tmp = path.join(os.tmpdir(), `agentsam-merkle-persist-${process.pid}-${Date.now()}.sql`);
+  fs.writeFileSync(tmp, `${merklePersistenceUpsertSql(plan.row)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    execFileSync(wranglerBin, wranglerArgs(['d1', 'execute', plan.wrangler.database_name, '--remote', '--yes', `--file=${tmp}`], plan.wrangler), {
+      stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+    });
+  } catch (error) {
+    try {
+      execFileSync(wranglerBin, wranglerArgs(['r2', 'object', 'delete', object, '--remote'], plan.wrangler), {
+        stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+      });
+    } catch {}
+    throw error;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+  return result;
+}

package/src/lib/merkle/filemeta.js

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+import { comparePaths } from './hash.js';
+
+export const FILEMETA_FORMAT = 'agentsam-filemeta';
+export const FILEMETA_VERSION = 1;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+function semanticDigest(type, value) {
+  return 'sha256:' + createHash('sha256')
+    .update(`agentsam-filemeta:${type}:v1\0`)
+    .update(JSON.stringify(canonical(value)))
+    .digest('hex');
+}
+
+export function metadataRoot(entries, classifier) {
+  return semanticDigest('root', { classifier, entries: [...entries].sort((a, b) => comparePaths(a.path, b.path)) });
+}
+
+export function validateSemanticMetadata(value, contentEntries = []) {
+  const fail = (message) => { throw new Error(`Invalid semantic metadata: ${message}`); };
+  if (!value || value.format !== FILEMETA_FORMAT || value.version !== FILEMETA_VERSION || value.algorithm !== 'sha256') fail('unsupported format/version');
+  if (!value.classifier || !Array.isArray(value.entries)) fail('missing classifier/entries');
+  const content = new Map(contentEntries.filter((entry) => entry.type !== 'directory').map((entry) => [entry.path, entry]));
+  const seen = new Set();
+  for (const entry of value.entries) {
+    if (!entry || typeof entry.path !== 'string' || seen.has(entry.path)) fail('invalid/duplicate path');
+    seen.add(entry.path);
+    if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777) fail(`invalid mode: ${entry.path}`);
+    if (!/^sha256:[a-f0-9]{64}$/.test(entry.hash || '')) fail(`invalid hash: ${entry.path}`);
+    const source = content.get(entry.path);
+    if (source && source.hash !== entry.hash) fail(`content hash mismatch: ${entry.path}`);
+    if (source?.type === 'file' && source.size !== entry.size) fail(`file size mismatch: ${entry.path}`);
+  }
+  if (content.size && seen.size !== content.size) fail('entry count does not match content tree');
+  const rootHash = metadataRoot(value.entries, value.classifier);
+  if (rootHash !== value.rootHash) fail('metadata root mismatch');
+  return { ...value, rootHash, entries: [...value.entries].sort((a, b) => comparePaths(a.path, b.path)) };
+}

package/src/lib/merkle/git-ignore.js

@@ -0,0 +1,24 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+
+/**
+ * Resolve Git-ignored paths using Git itself so every Merkle-backed consumer can
+ * build evidence from the same checkout policy. Non-Git directories simply
+ * return an empty list and still receive the protocol's built-in excludes.
+ */
+export async function gitIgnoredPaths(root) {
+  try {
+    const result = await execute('git', ['status', '--porcelain=v1', '--ignored=matching'], {
+      cwd: root,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return [...new Set(result.stdout.split('\n')
+      .filter((line) => line.startsWith('!! '))
+      .map((line) => line.slice(3).trim().replace(/\/$/, ''))
+      .filter((value) => value && !value.includes('\\') && !value.split('/').includes('..')))];
+  } catch {
+    return [];
+  }
+}

package/src/lib/merkle/hash.js

@@ -4,6 +4,7 @@ export const comparePaths = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from
 export const digest = (type, value) => 'sha256:' + createHash('sha256')
   .update(`agentsam-merkle:${type}:v1\0`).update(value).digest('hex');
 export const linkHash = (target) => digest('symlink', target);
+export const policyHash = (policy) => digest('policy', JSON.stringify(policy));
 export const directoryHash = (children) => digest('directory', JSON.stringify(
   [...children].sort((a, b) => comparePaths(a.name, b.name)).map(({ name, type, hash }) => [name, type, hash]),
 ));

package/src/lib/merkle/index.js

@@ -2,3 +2,25 @@ export { buildMerkleTree } from './tree.js';
 export { saveSnapshot, readSnapshot, validateSnapshot } from './snapshot.js';
 export { diffTrees } from './diff.js';
 export { DEFAULT_IGNORES, normalizePolicy } from './policy.js';
+export { policyHash } from './hash.js';
+export async function buildSemanticMetadata(...args) {
+  const semantic = await import('./semantic.js');
+  return semantic.buildSemanticMetadata(...args);
+}
+export { validateSemanticMetadata, metadataRoot, FILEMETA_FORMAT, FILEMETA_VERSION } from './filemeta.js';
+
+export {
+  MERKLE_SNAPSHOT_SCHEMA_SQL,
+  MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  MERKLE_SNAPSHOT_TABLE,
+  MERKLE_WEBSITE_ASSETS_BINDING,
+  merkleSnapshotStorageKey,
+  normalizeMerkleStoragePrefix,
+} from './persistence.js';
+export {
+  buildMerklePersistencePlan,
+  merklePersistenceUpsertSql,
+  persistMerkleSnapshotCloudflare,
+  readWranglerPersistenceBindings,
+  resolveWranglerMerklePersistence,
+} from './cloudflare-persistence.js';

package/src/lib/merkle/persistence.js

@@ -0,0 +1,72 @@
+export const MERKLE_SNAPSHOT_TABLE = 'agentsam_fs_merkle_snapshots';
+export const MERKLE_SNAPSHOT_STORAGE_PREFIX = 'agentsam_fs_merkle_snapshots';
+export const MERKLE_WEBSITE_ASSETS_BINDING = 'WEBSITE_ASSETS';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function safeSegment(value, name) {
+  const segment = clean(value);
+  if (!segment) throw new Error(`${name}_required`);
+  if (segment === '.' || segment === '..' || /[\u0000-\u001f\u007f]/.test(segment)) {
+    throw new Error(`${name}_invalid`);
+  }
+  return encodeURIComponent(segment);
+}
+
+export function normalizeMerkleStoragePrefix(value = MERKLE_SNAPSHOT_STORAGE_PREFIX) {
+  const prefix = clean(value || MERKLE_SNAPSHOT_STORAGE_PREFIX).replace(/^\/+|\/+$/g, '');
+  if (!prefix || prefix.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error('merkle_storage_prefix_invalid');
+  }
+  return prefix;
+}
+
+/**
+ * Provider-neutral object key. The host chooses which physical bucket is bound
+ * to the logical WEBSITE_ASSETS role; the SDK never owns cloud credentials.
+ */
+export function merkleSnapshotStorageKey({ ownerUserId, repoId, snapshotId, prefix = MERKLE_SNAPSHOT_STORAGE_PREFIX } = {}) {
+  return `${normalizeMerkleStoragePrefix(prefix)}/${safeSegment(ownerUserId, 'owner_user_id')}/${safeSegment(repoId, 'repo_id')}/${safeSegment(snapshotId, 'snapshot_id')}.json`;
+}
+
+/** Portable D1/SQLite schema for hosts that opt into persisted Merkle snapshots. */
+export const MERKLE_SNAPSHOT_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${MERKLE_SNAPSHOT_TABLE} (
+  snapshot_id TEXT PRIMARY KEY NOT NULL,
+  owner_user_id TEXT NOT NULL,
+  repo_id TEXT NOT NULL,
+  repository TEXT,
+  source TEXT NOT NULL CHECK (source IN ('github','gitlab','bitbucket','local','upload')),
+  manifest_format TEXT NOT NULL DEFAULT 'agentsam-merkle',
+  manifest_version INTEGER NOT NULL DEFAULT 1,
+  hash_algorithm TEXT NOT NULL DEFAULT 'sha256',
+  root_hash TEXT NOT NULL,
+  policy_hash TEXT,
+  resolved_commit_sha TEXT,
+  resolved_tree_sha TEXT,
+  git_branch TEXT,
+  working_tree_dirty INTEGER NOT NULL DEFAULT 0,
+  connection_id TEXT,
+  runtime_lease_id TEXT,
+  storage_backend TEXT NOT NULL DEFAULT 'r2' CHECK (storage_backend IN ('r2','local_fs','inline','none')),
+  storage_bucket TEXT,
+  storage_key TEXT,
+  entry_count INTEGER,
+  file_count INTEGER,
+  directory_count INTEGER,
+  symlink_count INTEGER,
+  total_bytes INTEGER,
+  capture_kind TEXT NOT NULL DEFAULT 'manual' CHECK (capture_kind IN ('deploy','manual','agent','index')),
+  deployment_id TEXT,
+  worker_version_id TEXT,
+  reference_label TEXT,
+  created_at INTEGER NOT NULL,
+  persisted_at INTEGER,
+  metadata_root TEXT,
+  classifier_format TEXT,
+  classifier_version INTEGER,
+  classifier_source TEXT,
+  CHECK (storage_backend IN ('inline','none') OR (storage_bucket IS NOT NULL AND storage_key IS NOT NULL)),
+  CHECK (connection_id IS NOT NULL OR runtime_lease_id IS NOT NULL OR capture_kind = 'deploy')
+);`;