@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/test/context.test.mjs

@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  DEFAULT_RESULT_POLICY,
+  assessContextUsage,
+  compileAgentInstructions,
+  createContextBudget,
+  normalizeResultPolicy,
+  resolveContext,
+  resolveProjectContext,
+} from '../src/context/index.js';
+
+test('default result policy is bounded and callers may request less', () => {
+  assert.deepEqual(DEFAULT_RESULT_POLICY, { max_items: 8, max_chars: 24_000, detail: 'excerpt' });
+  assert.deepEqual(normalizeResultPolicy({ max_items: 3, max_chars: 8_000, detail: 'card' }), { max_items: 3, max_chars: 8_000, detail: 'card' });
+  assert.throws(() => normalizeResultPolicy({ max_items: 9 }), /higher_detail_required:max_items/);
+  assert.throws(() => normalizeResultPolicy({ max_chars: 24_001 }), /higher_detail_required:max_chars/);
+  assert.throws(() => normalizeResultPolicy({ detail: 'full' }), /higher_detail_required:detail/);
+  assert.equal(normalizeResultPolicy({ detail: 'full', max_items: 20, max_chars: 100_000 }, { operation: 'higher-detail' }).detail, 'full');
+});
+
+test('legacy ratio context budget remains compatible for ordinary windows', () => {
+  const budget = createContextBudget({ windowTokens: 250_000 });
+  assert.equal(budget.targetInputTokens, 150_000);
+  assert.equal(budget.hardInputTokens, 212_500);
+  assert.equal(budget.windowChars, 1_000_000);
+  assert.equal(budget.maxSystemChars, 50_000);
+  assert.equal(budget.maxToolSchemaChars, 40_000);
+  assert.equal(budget.maxEvidenceChars, 100_000);
+  assert.equal(budget.maxFileCharsPerRead, 32_768);
+  assert.equal(budget.maxFileCharsPerTurn, 131_072);
+  assert.equal(budget.maxToolResultChars, 24_000);
+});
+
+test('large model capacity is independent from AgentSam working-set and pricing policy', () => {
+  const budget = createContextBudget({
+    windowTokens: 1_050_000,
+    targetInputTokens: 120_000,
+    compactAtTokens: 180_000,
+    interveneAtTokens: 220_000,
+    maxNormalInputTokens: 250_000,
+    pricingThresholdTokens: 272_000,
+    safetyMarginTokens: 22_000,
+  });
+  assert.equal(budget.windowTokens, 1_050_000);
+  assert.equal(budget.targetInputTokens, 120_000);
+  assert.equal(budget.compactAtTokens, 180_000);
+  assert.equal(budget.interveneAtTokens, 220_000);
+  assert.equal(budget.maxNormalInputTokens, 250_000);
+  assert.equal(budget.pricingThresholdTokens, 272_000);
+  assert.ok(budget.targetInputRatio < 0.12);
+
+  assert.equal(assessContextUsage(179_999, budget).shouldCompact, false);
+  assert.equal(assessContextUsage(180_000, budget).shouldCompact, true);
+  assert.equal(assessContextUsage(272_000, budget).pricingThresholdCrossed, false);
+  const crossed = assessContextUsage(272_001, budget);
+  assert.equal(crossed.pricingThresholdCrossed, true);
+  assert.equal(crossed.tokensUntilPricingThreshold, -1);
+});
+
+test('context.resolve separates composition classes and returns an economic receipt', () => {
+  const budget = createContextBudget({
+    windowTokens: 32_000,
+    maxEvidenceChars: 90,
+    maxFileCharsPerRead: 50,
+    maxFileCharsPerTurn: 60,
+    maxToolResultChars: 30,
+  });
+  const pack = resolveContext({
+    objective: 'fix terminal cwd persistence',
+    refs: ['repo:demo'],
+    budget,
+    instructionChars: 20,
+    toolSchemaChars: 12,
+    historyChars: 8,
+    items: [
+      { ref: 'file:low', kind: 'file', priority: 1, content: 'L'.repeat(50) },
+      { ref: 'tool:high', kind: 'tool_result', priority: 10, content: 'T'.repeat(50) },
+      { ref: 'file:high', kind: 'file', priority: 8, content: 'F'.repeat(80) },
+      { ref: 'memory:later', kind: 'memory', priority: 0, content: 'M'.repeat(40) },
+    ],
+  });
+
+  assert.deepEqual(pack.items.map((item) => item.ref), ['tool:high', 'file:high', 'file:low']);
+  assert.equal(pack.items[0].chars, 30);
+  assert.equal(pack.items[1].chars, 50);
+  assert.equal(pack.items[2].chars, 10);
+  assert.equal(pack.receipt.tool_result_chars, 30);
+  assert.equal(pack.receipt.evidence_chars, 60);
+  assert.equal(pack.receipt.instruction_chars, 20);
+  assert.equal(pack.receipt.tool_schema_chars, 12);
+  assert.equal(pack.receipt.history_chars, 8);
+  assert.equal(pack.receipt.chars, 130);
+  assert.equal(pack.receipt.estimate_kind, 'local');
+  assert.equal(pack.receipt.window_tokens, 32_000);
+  assert.equal(pack.receipt.sources_considered, 4);
+  assert.equal(pack.receipt.sources_included, 3);
+  assert.ok(pack.receipt.sources_deferred >= 3);
+  assert.ok(pack.receipt.deferred_refs.includes('memory:later'));
+  assert.deepEqual(pack.receipt.rehydratable_refs, ['tool:high', 'file:high', 'file:low']);
+});
+
+test('AgentSam instructions compile in stable then repository-specific precedence', t => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-instructions-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  fs.mkdirSync(path.join(root, '.git'));
+  fs.writeFileSync(path.join(root, 'AGENTSAM.md'), '# Stable\nbase law\n');
+  fs.writeFileSync(path.join(root, '.agentsamrules'), '# Repo\nlocal law\n');
+  const compiled = compileAgentInstructions(root);
+  assert.deepEqual(compiled.precedence, ['AGENTSAM.md', '.agentsamrules']);
+  assert.equal(compiled.sources.length, 2);
+  assert.ok(compiled.content.indexOf('base law') < compiled.content.indexOf('local law'));
+});
+
+test('project context loads bounded compiled AgentSam instructions', t => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-context-rules-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  fs.mkdirSync(path.join(root, '.git'));
+  fs.writeFileSync(path.join(root, 'AGENTSAM.md'), '# stable\n' + 'a'.repeat(300));
+  fs.writeFileSync(path.join(root, '.agentsamrules'), '# rules\n' + 'x'.repeat(5000) + '\n');
+  const pack = resolveProjectContext({
+    cwd: root,
+    objective: 'inspect repository',
+    budget: createContextBudget({ windowTokens: 8_000, maxSystemChars: 1_000, maxEvidenceChars: 1_000 }),
+    items: [],
+  });
+  assert.equal(pack.rules.found, true);
+  assert.equal(pack.rules.chars, 1_000);
+  assert.equal(pack.rules.truncated, true);
+  assert.equal(pack.receipt.system_chars, 1_000);
+});
+
+test('consumed tool results compact to 4k while preserving rehydration identity', async () => {
+  const { compactConsumedToolResult } = await import('../src/context/index.js');
+  const item = compactConsumedToolResult('x'.repeat(10_000), { ref: 'tool:call_123', hash: 'sha256:abc' });
+  assert.equal(item.ref, 'tool:call_123');
+  assert.equal(item.hash, 'sha256:abc');
+  assert.equal(item.chars, 4_000);
+  assert.equal(item.compacted, true);
+  assert.equal(item.source_chars, 10_000);
+});

package/test/deploy-health-scan.test.mjs

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { scanTextForSecrets } from '../src/lib/deploy/secret-scan.js';
+import { HEALTH_USER_AGENT, parseWranglerVersionId, probeDeployHealth, resolveHealthOrigin } from '../src/lib/deploy/health.js';
+
+describe('deploy secret scan', () => {
+  it('allows fixture oauth values', () => {
+    const findings = scanTextForSecrets(
+      'CLOUDFLARE_OAUTH_CLIENT_ID=sillynotreal\nCLOUDFLARE_OAUTH_CLIENT_SECRET=sillynotreal-secret\n',
+      { filename: 'apps/local-studio/.env.cloudflare.example' },
+    );
+    assert.equal(findings.length, 0);
+  });
+
+  it('flags live openai-like keys', () => {
+    const findings = scanTextForSecrets('OPENAI_API_KEY=sk-abcdefghijklmnopqrstuvwxyz012345');
+    assert.equal(findings.some((f) => f.label === 'openai-like'), true);
+  });
+});
+
+describe('deploy health', () => {
+  it('parses wrangler version ids', () => {
+    assert.equal(
+      parseWranglerVersionId('Current Version ID: e9747d3a-4db6-4e02-b6fe-aa5a47f1588b'),
+      'e9747d3a-4db6-4e02-b6fe-aa5a47f1588b',
+    );
+  });
+
+  it('reads hostname from wrangler.jsonc', () => {
+    const origin = resolveHealthOrigin({
+      env: {},
+      wranglerConfigText: '{"routes":[{"pattern":"agentsam.inneranimalmedia.com","custom_domain":true}]}',
+    });
+    assert.equal(origin, 'https://agentsam.inneranimalmedia.com');
+  });
+
+  it('treats /health ok:true with connector unconfigured as healthy', async () => {
+    const fetchImpl = async (url) => {
+      if (String(url).endsWith('/health')) {
+        return {
+          status: 200,
+          json: async () => ({ ok: true, connections: { cloudflare: { configured: false } } }),
+        };
+      }
+      return { status: 200, json: async () => ({}) };
+    };
+    const health = await probeDeployHealth('https://agentsam.inneranimalmedia.com', { fetchImpl });
+    assert.equal(health.ok, true);
+    assert.equal(health.results['/health'].appOk, true);
+    assert.equal(health.results['/health'].cloudflareConfigured, false);
+  });
+
+  it('sends a browser-safe User-Agent so WAF does not 403 the probe', async () => {
+    const seen = [];
+    const fetchImpl = async (url, init = {}) => {
+      seen.push({ url, init });
+      return {
+        status: 200,
+        json: async () => ({ ok: true, connections: { cloudflare: { configured: false } } }),
+      };
+    };
+    await probeDeployHealth('https://agentsam.inneranimalmedia.com', { fetchImpl, paths: ['/health'] });
+    assert.equal(seen.length, 1);
+    assert.equal(seen[0].init.headers['User-Agent'], HEALTH_USER_AGENT);
+    assert.match(seen[0].init.headers.Accept, /application\/json/);
+  });
+});

package/test/error-diagnostics.test.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { classifyOpenAIError, createOpenAIHttpError, diagnosticFromError } from '../src/errors/index.js';
+import { createOpenAIResponsesAdapter } from '../src/providers/openai-responses.js';
+
+function response(status, body, headers = {}) { return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } }); }
+
+test('OpenAI diagnostics preserve machine code, request id, retry metadata and redact secrets', () => {
+  const error = createOpenAIHttpError({
+    status: 429,
+    body: { error: { type: 'rate_limit_error', code: 'slow_down', message: 'slow down Bearer abc.def.ghi', param: null }, api_key: 'sk-secret-value-123456789' },
+    headers: new Headers({ 'retry-after': '2', 'x-request-id': 'req_123' }),
+    requestedServiceTier: 'fast',
+  });
+  assert.equal(error.diagnostic.http_status, 429);
+  assert.equal(error.diagnostic.type, 'rate_limit_error');
+  assert.equal(error.diagnostic.code, 'slow_down');
+  assert.equal(error.diagnostic.request_id, 'req_123');
+  assert.equal(error.diagnostic.retry_after_ms, 2000);
+  assert.equal(error.diagnostic.retriable, true);
+  assert.equal(error.diagnostic.retry_strategy, 'retry_after_backoff');
+  assert.equal(error.diagnostic.requested_service_tier, 'fast');
+  assert.ok(!JSON.stringify(error.diagnostic).includes('sk-secret-value'));
+  assert.ok(!error.diagnostic.message.includes('abc.def.ghi'));
+});
+
+test('billing and spend errors are explicitly non-retriable while provider overload is retriable', () => {
+  for (const code of ['credit_balance_exhausted', 'organization_spend_limit_exceeded', 'project_spend_limit_exceeded', 'organization_usage_limit_exceeded']) {
+    assert.equal(classifyOpenAIError({ status: 429, code }).retriable, false);
+  }
+  assert.deepEqual(classifyOpenAIError({ status: 503, code: 'server_is_overloaded' }), { category: 'provider_overload', retriable: true, retry_strategy: 'retry_after_backoff' });
+  assert.equal(classifyOpenAIError({ status: 401 }).category, 'authentication');
+});
+
+test('OpenAI retry classifier distinguishes configuration, continuation, rate, server, and operator-action failures', () => {
+  assert.deepEqual(classifyOpenAIError({ status: 400, message: 'Invalid service_tier argument' }), { category: 'service_tier', retriable: false, retry_strategy: 'change_configuration' });
+  assert.deepEqual(classifyOpenAIError({ status: 400, code: 'previous_response_not_found' }), { category: 'continuation', retriable: true, retry_strategy: 'retry_full_context' });
+  assert.deepEqual(classifyOpenAIError({ status: 400, code: 'websocket_connection_limit_reached' }), { category: 'connection_lifetime', retriable: true, retry_strategy: 'reconnect' });
+  assert.deepEqual(classifyOpenAIError({ status: 429, type: 'rate_limit_error', code: 'slow_down' }), { category: 'ramp_rate', retriable: true, retry_strategy: 'retry_after_backoff' });
+  assert.deepEqual(classifyOpenAIError({ status: 500 }), { category: 'provider_server', retriable: true, retry_strategy: 'retry_backoff' });
+  assert.deepEqual(classifyOpenAIError({ status: 403 }), { category: 'authorization_or_region', retriable: false, retry_strategy: 'operator_action' });
+});
+
+test('Responses adapter throws a diagnostic error instead of flattening the provider response', async () => {
+  const adapter = createOpenAIResponsesAdapter({
+    apiKey: 'sk-test',
+    fetchImpl: async () => response(429, { error: { type: 'insufficient_quota', code: 'project_spend_limit_exceeded', message: 'budget reached' } }, { 'x-request-id': 'req_budget' }),
+  });
+  await assert.rejects(
+    adapter.create({ model: 'gpt-6-astra', reasoningEffort: 'low', serviceTier: 'default', input: 'hi' }),
+    (error) => {
+      const d = diagnosticFromError(error);
+      assert.equal(d.code, 'project_spend_limit_exceeded');
+      assert.equal(d.request_id, 'req_budget');
+      assert.equal(d.retriable, false);
+      return true;
+    },
+  );
+});

package/test/eval-context.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import test from 'node:test';
+import { evaluateContextFixture, listContextEvalFixtures } from '../src/eval/index.js';
+
+const repoRoot = path.resolve(new URL('..', import.meta.url).pathname);
+
+test('context eval ships AgentSam-shaped deterministic fixtures and never calls a provider', async () => {
+  const fixtures = listContextEvalFixtures();
+  assert.ok(fixtures.length >= 6);
+  assert.ok(fixtures.includes('continuation-after-compaction'));
+  const report = await evaluateContextFixture({ fixture: 'exact-symbol-callers' });
+  assert.equal(report.live_provider_used, false);
+  assert.equal(report.strategies.length, 3);
+  assert.ok(report.strategies.every(row => row.result === 'PASS'));
+  assert.ok(report.winner);
+});
+
+test('compaction fixture reaches a proactive pressure region and proves explicit rehydration', async () => {
+  const report = await evaluateContextFixture({ fixture: 'continuation-after-compaction', strategy: 'compact' });
+  const row = report.strategies[0];
+  assert.equal(row.result, 'PASS');
+  assert.ok(row.compacted_chars > 0);
+  assert.ok(row.rehydrated_refs.includes('tool:call_previous'));
+  assert.ok(row.active_context_tokens < row.pricing_threshold_tokens);
+});
+
+test('CLI JSON context eval is stable and offline', () => {
+  const result = spawnSync(process.execPath, ['src/cli.js', 'eval', 'context', '--fixture', 'two-file-repair', '--strategy', 'discovery', '--json'], { cwd: repoRoot, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.fixture, 'two-file-repair');
+  assert.equal(report.live_provider_used, false);
+  assert.equal(report.strategies[0].strategy, 'discovery');
+  assert.equal(report.strategies[0].result, 'PASS');
+});

package/test/execution-approvals.test.mjs

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '../src/lib/execution-approvals.js';
+
+function tempHome(t) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-approval-home-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+}
+
+test('execution approvals are exact-command and project scoped', t => {
+  const home = tempHome(t);
+  const one = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-project-a-'));
+  const two = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-project-b-'));
+  t.after(() => fs.rmSync(one, { recursive: true, force: true }));
+  t.after(() => fs.rmSync(two, { recursive: true, force: true }));
+  const key = toolApprovalKey('cloudflare.wrangler.native', { command: 'whoami' });
+  assert.equal(key, 'cloudflare.wrangler.native:whoami');
+  assert.equal(isExecutionApproved({ cwd: one, key }, { home }), false);
+  grantExecutionApproval({ cwd: one, key }, { home });
+  assert.equal(isExecutionApproved({ cwd: one, key }, { home }), true);
+  assert.equal(isExecutionApproved({ cwd: two, key }, { home }), false);
+  assert.equal(isExecutionApproved({ cwd: one, key: 'cloudflare.wrangler.native:versions.list' }, { home }), false);
+});

package/test/indexing-provider.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  REPOSITORY_KNOWLEDGE_PROVIDER_METHODS,
+  assertRepositoryKnowledgeProvider,
+  createRepositoryKnowledgeClient,
+  describeRepositoryKnowledgeProvider,
+} from '../src/indexing/index.js';
+
+function provider() {
+  return Object.fromEntries(REPOSITORY_KNOWLEDGE_PROVIDER_METHODS.map((method) => [method, async (input) => ({ method, input })]));
+}
+
+test('repository knowledge provider is a contract, not a bundled platform implementation', async () => {
+  const impl = provider();
+  assert.equal(assertRepositoryKnowledgeProvider(impl), impl);
+  const client = createRepositoryKnowledgeClient(impl);
+  assert.deepEqual(await client.findSymbol({ name: 'resolveModel' }), { method: 'findSymbol', input: { name: 'resolveModel' } });
+  assert.deepEqual(await client.retrieve({ query: 'session recovery' }), { method: 'retrieve', input: { query: 'session recovery' } });
+  assert.throws(() => assertRepositoryKnowledgeProvider({ status() {} }), /refresh\(\) is required/);
+});
+
+test('provider capabilities describe implementation truth without prescribing storage', () => {
+  assert.deepEqual(describeRepositoryKnowledgeProvider({
+    provider: 'inneranimal-platform', structure: 'tree-sitter', lexical: true, semantic: true, graph: true, history: true, evidence: 'merkle',
+  }), {
+    provider: 'inneranimal-platform', structure: 'tree-sitter', lexical: true, semantic: true, graph: true, history: true, evidence: 'merkle',
+  });
+});

package/test/jr-dev-skill.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+
+const root = path.resolve(import.meta.dirname, '..');
+const skill = path.join(root, 'skills', 'agentsam-jr-dev', 'SKILL.md');
+const fundamentals = path.join(root, 'skills', 'agentsam-jr-dev', 'references', 'web-application-fundamentals.md');
+const logic = path.join(root, 'skills', 'agentsam-jr-dev', 'references', 'real-application-logic.md');
+
+test('agentsam-jr-dev ships as a portable skill with depth references', () => {
+  for (const file of [skill, fundamentals, logic]) {
+    assert.equal(fs.existsSync(file), true, `${file} must exist`);
+  }
+
+  const text = fs.readFileSync(skill, 'utf8');
+  assert.match(text, /name: agentsam-jr-dev/);
+  assert.match(text, /Inspect before teaching repo-specific facts/);
+  assert.match(text, /Real application logic is the standard/);
+  assert.match(text, /Never invent a repo architecture/);
+  assert.match(text, /frontend owns presentation/);
+  assert.match(text, /backend owns trusted execution/);
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  assert.ok(pkg.files.includes('skills'), 'root npm package must include portable skills');
+});

package/test/knowledge-context-pack.test.mjs

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createContextPack } from '../src/knowledge/context-pack.js';
+
+test('knowledge ContextPack includes a measurable selection receipt', () => {
+  const pack = createContextPack({
+    queryId: 'q1',
+    query: { text: 'where is auth?', top_k: 2, token_budget: 2000 },
+    hits: [{ ref: 'file:a', content: 'abcd' }, { ref: 'file:b', content: '12345678' }],
+    diagnostics: { sources_considered: 7, sources_deferred: 5 },
+  });
+  assert.deepEqual(pack.receipt, {
+    chars: 12,
+    estimated_tokens: 3,
+    sources_considered: 7,
+    sources_included: 2,
+    sources_deferred: 5,
+  });
+});

package/test/knowledge.test.mjs

@@ -152,5 +152,5 @@ test('recovered KnowledgeClient contracts remain usable with injected transports
   const client = new KnowledgeClient({ transport: { async request(op, payload) { operations.push([op, payload]); return { query_id: 'test', hits: [] }; } } });
   await client.retrieve({ text: 'find parser', workspace_id: 'customer' });
   await client.index('repository');
-  assert.equal(operations[0][1].top_k, 12); assert.equal(operations[1][0], 'knowledge.index');
+  assert.equal(operations[0][1].top_k, 8); assert.equal(operations[0][1].token_budget, 6000); assert.equal(operations[0][1].result_policy.max_items, 8); assert.equal(operations[1][0], 'knowledge.index');
 });

package/test/local-sessions.test.mjs

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { createLocalSession, listLocalSessions, loadLocalSession, saveLocalSession, sessionTitleFromInput } from '../src/lib/local-sessions.js';
+import { renderSessionReceipt } from '../src/commands/shell.js';
+
+function tempHome(t) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-session-home-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+}
+
+test('local sessions persist provider-neutral continuation, usage, cost, and last-input title', t => {
+  const home = tempHome(t);
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-session-project-'));
+  t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
+  let session = createLocalSession({ cwd, last_input: 'Run wrangler whoami' }, { home });
+  assert.match(session.id, /^asess_[0-9a-f-]{36}$/i);
+  session = saveLocalSession({
+    ...session,
+    title: sessionTitleFromInput('Run wrangler whoami'),
+    model_key: 'openai:gpt-6-astra',
+    actual_service_tier: 'fast',
+    provider_state: { provider: 'openai', previous_response_id: 'resp_123' },
+    usage_snapshot: { current_context: { input_tokens: 21_244, window_tokens: 1_050_000 } },
+    cumulative_usage: { input_tokens: 21_244, cached_input_tokens: 60_544, output_tokens: 219, reasoning_tokens: 31 },
+    total_cost_usd: 0.123456,
+  }, { home });
+
+  const loaded = loadLocalSession(session.id, { home });
+  assert.equal(loaded.provider_state.previous_response_id, 'resp_123');
+  assert.equal(loaded.cumulative_usage.cached_input_tokens, 60_544);
+  assert.equal(listLocalSessions({ home, cwd })[0].id, session.id);
+
+  const receipt = renderSessionReceipt(loaded);
+  assert.match(receipt, /Token usage: total=21,463 input=21,244 \(\+ 60,544 cached\) output=219 reasoning=31/);
+  assert.match(receipt, /Cost: \$0\.1235/);
+  assert.match(receipt, new RegExp(`agentsam resume ${session.id}`));
+  assert.match(receipt, /Run wrangler whoami/);
+});

package/test/local-studio-deploy.test.mjs

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import {
+  DEPLOY_INPUT_GLOBS,
+  loadOptionalCloudflareEnv,
+  resolveLocalStudioDeployable,
+  wranglerDeployCommand,
+  isLocalStudioCheckout,
+  runLocalStudioDeploy,
+} from '../src/lib/deploy/local-studio.js';
+import { productionDeployBlockedReason } from '../src/lib/deploy/git-guard.js';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('local-studio deploy resolver', () => {
+  it('resolves apps/local-studio + backend/wrangler.jsonc from the repo', () => {
+    const target = resolveLocalStudioDeployable(root);
+    assert.equal(target.provider, 'cloudflare');
+    assert.equal(target.app, 'local-studio');
+    assert.equal(path.basename(path.dirname(target.wranglerConfig)), 'backend');
+    assert.deepEqual(target.wranglerArgs, ['deploy', '-c', 'backend/wrangler.jsonc']);
+    assert.equal(isLocalStudioCheckout(root), true);
+    const cmd = wranglerDeployCommand(target, { dryRun: true });
+    assert.equal(cmd.bin, 'npx');
+    assert.equal(cmd.cwd, target.appRoot);
+    assert.deepEqual(cmd.args, ['wrangler', 'deploy', '-c', 'backend/wrangler.jsonc', '--dry-run']);
+  });
+
+  it('fingerprints the cloudflare connector package', () => {
+    assert.equal(DEPLOY_INPUT_GLOBS.includes('packages/connectors/cloudflare'), true);
+    assert.equal(DEPLOY_INPUT_GLOBS.includes('apps/local-studio'), true);
+  });
+
+  it('treats missing .env.cloudflare as optional', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cf-env-'));
+    const loaded = loadOptionalCloudflareEnv(tmp);
+    assert.equal(loaded.loaded, false);
+    assert.deepEqual(loaded.vars, {});
+  });
+
+  it('plan does not invoke wrangler', async () => {
+    const result = await runLocalStudioDeploy({ cwd: root, planOnly: true, execute: false });
+    assert.equal(result.plan.provider, 'cloudflare');
+    assert.equal(result.plan.wranglerConfig, 'apps/local-studio/backend/wrangler.jsonc');
+    assert.equal(result.plan.genericRootDeploy, false);
+    assert.equal(result.receipt.plan, true);
+    assert.equal(result.receipt.promoted, false);
+    assert.equal(result.receipt.wranglerConfig, 'apps/local-studio/backend/wrangler.jsonc');
+    assert.equal(result.receipt.hostname, 'agentsam.inneranimalmedia.com');
+  });
+
+  it('blocks production deploys from feat branches', () => {
+    const reason = productionDeployBlockedReason({
+      ok: true,
+      branch: 'feat/cloudflare-connector-deploy-control',
+      detached: false,
+      head: 'aaa',
+      originMain: 'aaa',
+      dirty: false,
+      tmpCheckout: false,
+      repoRoot: root,
+    });
+    assert.match(reason, /feat\/cloudflare-connector-deploy-control/);
+  });
+
+  it('allows production only when HEAD is a clean origin/main', () => {
+    const reason = productionDeployBlockedReason({
+      ok: true,
+      branch: 'main',
+      detached: false,
+      head: 'abc',
+      originMain: 'abc',
+      dirty: false,
+      tmpCheckout: false,
+      repoRoot: root,
+    });
+    assert.equal(reason, null);
+  });
+});

package/test/merkle-persistence.test.mjs

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  MERKLE_SNAPSHOT_SCHEMA_SQL,
+  MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  MERKLE_SNAPSHOT_TABLE,
+  MERKLE_WEBSITE_ASSETS_BINDING,
+  buildMerklePersistencePlan,
+  merklePersistenceUpsertSql,
+  merkleSnapshotStorageKey,
+  resolveWranglerMerklePersistence,
+} from '../src/lib/merkle/index.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+test('portable Merkle persistence names one table, prefix, and logical asset role', () => {
+  assert.equal(MERKLE_SNAPSHOT_TABLE, 'agentsam_fs_merkle_snapshots');
+  assert.equal(MERKLE_SNAPSHOT_STORAGE_PREFIX, 'agentsam_fs_merkle_snapshots');
+  assert.equal(MERKLE_WEBSITE_ASSETS_BINDING, 'WEBSITE_ASSETS');
+  assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /metadata_root TEXT/);
+  assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /classifier_format TEXT/);
+  assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /storage_bucket TEXT/);
+});
+
+test('snapshot storage keys stay beneath the canonical prefix and encode repo identity', () => {
+  const key = merkleSnapshotStorageKey({
+    ownerUserId: 'au_example',
+    repoId: 'github:owner/repo',
+    snapshotId: 'mrs_example',
+  });
+  assert.equal(key, 'agentsam_fs_merkle_snapshots/au_example/github%3Aowner%2Frepo/mrs_example.json');
+  const escaped = merkleSnapshotStorageKey({ ownerUserId: '../oops', repoId: 'repo', snapshotId: 'snap' });
+  assert.ok(!escaped.includes('/../'));
+  assert.ok(escaped.includes('..%2Foops'));
+});
+
+test('Wrangler persistence resolves logical WEBSITE_ASSETS and DB bindings', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-wrangler-'));
+  const config = path.join(dir, 'wrangler.toml');
+  fs.writeFileSync(config, `name = "fixture"\n\n[[d1_databases]]\nbinding = "DB"\ndatabase_name = "fixture-db"\ndatabase_id = "db-id"\n\n[[r2_buckets]]\nbinding = "WEBSITE_ASSETS"\nbucket_name = "fixture-assets"\n`);
+  try {
+    const resolved = resolveWranglerMerklePersistence({ configPath: config });
+    assert.equal(resolved.r2_binding, 'WEBSITE_ASSETS');
+    assert.equal(resolved.storage_bucket, 'fixture-assets');
+    assert.equal(resolved.d1_binding, 'DB');
+    assert.equal(resolved.database_name, 'fixture-db');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('persistence plan keeps content, policy, and metadata identities separate', () => {
+  const snapshot = {
+    format: 'agentsam-merkle', version: 1, algorithm: 'sha256',
+    rootHash: `sha256:${'1'.repeat(64)}`,
+    policyHash: `sha256:${'2'.repeat(64)}`,
+    entries: [{ path: 'src/a.js', type: 'file', size: 10, hash: `sha256:${'4'.repeat(64)}` }],
+    stats: { files: 1, directories: 1, symlinks: 0, bytes: 10 },
+    semantic: {
+      format: 'agentsam-filemeta', version: 1, rootHash: `sha256:${'3'.repeat(64)}`,
+      classifier: { format: 'agentsam-filemeta', version: 1, source: 'path+package+ast' }, entries: [],
+    },
+  };
+  const plan = buildMerklePersistencePlan({
+    snapshot, root: process.cwd(), ownerUserId: 'au_test', repoId: 'github:owner/repo', source: 'github',
+    captureKind: 'agent', connectionId: 'conn_test',
+    wrangler: { storage_bucket: 'customer-assets', r2_binding: 'WEBSITE_ASSETS', database_name: 'customer-db', d1_binding: 'DB' },
+  });
+  assert.equal(plan.row.root_hash, snapshot.rootHash);
+  assert.equal(plan.row.policy_hash, snapshot.policyHash);
+  assert.equal(plan.row.metadata_root, snapshot.semantic.rootHash);
+  assert.equal(plan.row.classifier_format, 'agentsam-filemeta');
+  assert.equal(plan.row.storage_bucket, 'customer-assets');
+  assert.match(plan.row.storage_key, /^agentsam_fs_merkle_snapshots\//);
+  const sql = merklePersistenceUpsertSql(plan.row);
+  assert.match(sql, /INSERT INTO agentsam_fs_merkle_snapshots/);
+  assert.match(sql, /metadata_root/);
+  assert.match(sql, /classifier_source/);
+});
+
+test('non-deploy persistence requires execution provenance', () => {
+  const snapshot = {
+    format: 'agentsam-merkle', version: 1, algorithm: 'sha256', rootHash: `sha256:${'1'.repeat(64)}`,
+    policyHash: `sha256:${'2'.repeat(64)}`, entries: [], stats: { files: 0, directories: 0, symlinks: 0, bytes: 0 },
+  };
+  assert.throws(() => buildMerklePersistencePlan({
+    snapshot, root: process.cwd(), ownerUserId: 'au_test', repoId: 'github:owner/repo', captureKind: 'agent',
+    wrangler: { storage_bucket: 'customer-assets', r2_binding: 'WEBSITE_ASSETS', database_name: 'customer-db', d1_binding: 'DB' },
+  }), /execution_provenance_required/);
+});