@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/test/cloudflare-runtime.test.mjs

@@ -0,0 +1,75 @@
+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 { buildWranglerInvocation, listWranglerNativeCommands, runWranglerNative, summarizeCloudflareCpuProfile, summarizeCloudflareCpuProfileFile } from '../src/cloudflare/index.js';
+import { createCapabilityAdapter } from '../src/agent/capability-adapter.js';
+
+function tempRoot() { return fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-cf-')); }
+
+test('Cloudflare native command catalog exposes bounded read operations and never an auth-token secret read', () => {
+  const ids = listWranglerNativeCommands().map((row) => row.id);
+  assert.deepEqual(ids, ['whoami', 'deployments.list', 'versions.list', 'types.check', 'queues.list']);
+  assert.ok(!ids.some((id) => id.includes('token') || id.includes('secret') || id === 'deploy'));
+});
+
+test('Wrangler native invocation is argv-based and cwd/config scoped', () => {
+  const root = tempRoot();
+  fs.writeFileSync(path.join(root, 'wrangler.jsonc'), '{}');
+  const plan = buildWranglerInvocation('deployments.list', { cwd: root, name: 'demo' });
+  assert.equal(plan.cwd, root);
+  assert.deepEqual(plan.args.slice(0, 4), ['deployments', 'list', '--json', '--name']);
+  assert.equal(plan.args[4], 'demo');
+  assert.ok(plan.args.includes('--config'));
+  assert.throws(() => buildWranglerInvocation('whoami', { cwd: root, config: '../outside.toml' }), /outside_cwd/);
+});
+
+test('Wrangler native result preserves JSON and real exit code on failure', async () => {
+  const root = tempRoot();
+  const success = await runWranglerNative('whoami', { cwd: root }, { run: async () => ({ code: 0, stdout: JSON.stringify({ email: 'dev@example.com' }), stderr: '' }) });
+  assert.equal(success.data.email, 'dev@example.com');
+  await assert.rejects(
+    runWranglerNative('versions.list', { cwd: root }, { run: async () => ({ code: 7, stdout: '', stderr: 'upstream failed' }) }),
+    (error) => error.diagnostic?.exit_code === 7 && error.diagnostic?.code === 'wrangler_exit_nonzero',
+  );
+  await assert.rejects(
+    runWranglerNative('deployments.list', { cwd: root }, { run: async () => ({ code: 1, stdout: '', stderr: 'Authentication error [code: 10000]\nRequest ID: req_cf_1\nCF-Ray: ray-123' }) }),
+    (error) => error.diagnostic?.code === '10000' && error.diagnostic?.request_id === 'req_cf_1' && error.diagnostic?.ray_id === 'ray-123',
+  );
+});
+
+test('CPU profile summary ranks self-time hotspots and explicitly rejects production timer inference', () => {
+  const profile = {
+    nodes: [
+      { id: 1, callFrame: { functionName: 'fetch', url: 'worker.js', lineNumber: 0, columnNumber: 0 } },
+      { id: 2, callFrame: { functionName: 'heavyLoop', url: 'worker.js', lineNumber: 10, columnNumber: 2 } },
+      { id: 3, callFrame: { functionName: '(garbage collector)', url: '', lineNumber: -1, columnNumber: -1 } },
+    ],
+    samples: [1, 2, 2, 3],
+    timeDeltas: [100, 1200, 800, 400],
+  };
+  const summary = summarizeCloudflareCpuProfile(profile);
+  assert.equal(summary.top_frames[0].function, 'heavyLoop');
+  assert.equal(summary.top_frames[0].self_us, 2000);
+  assert.equal(summary.garbage_collection_ms, 0.4);
+  assert.match(summary.timer_semantics, /do not advance during CPU-only execution/);
+});
+
+test('CPU profile file cannot escape runtime cwd', () => {
+  const root = tempRoot();
+  fs.writeFileSync(path.join(root, 'profile.cpuprofile'), JSON.stringify({ nodes: [], samples: [], timeDeltas: [] }));
+  assert.equal(summarizeCloudflareCpuProfileFile({ cwd: root, file: 'profile.cpuprofile' }).file, 'profile.cpuprofile');
+  assert.throws(() => summarizeCloudflareCpuProfileFile({ cwd: root, file: '../profile.cpuprofile' }), /outside_cwd/);
+});
+
+test('explicitly executable experimental Cloudflare capabilities enter cards-first discovery without exposing unavailable commands', () => {
+  const adapter = createCapabilityAdapter();
+  const rows = adapter.toolDescriptors();
+  const ids = rows.map((row) => row.name);
+  assert.ok(ids.includes('cloudflare.wrangler.native'));
+  assert.ok(ids.includes('cloudflare.cpu.profile'));
+  assert.ok(!ids.includes('cloudflare.cpu.audit'));
+  assert.ok(!ids.includes('blender.build'));
+  assert.equal(rows.find((row) => row.name === 'cloudflare.wrangler.native').risk, 'read');
+});

package/test/context.test.mjs

@@ -5,6 +5,8 @@ import path from 'node:path';
 import test from 'node:test';
 import {
   DEFAULT_RESULT_POLICY,
+  assessContextUsage,
+  compileAgentInstructions,
   createContextBudget,
   normalizeResultPolicy,
   resolveContext,
@@ -13,18 +15,14 @@ import {
 
 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.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('context budget reserves headroom and caps each ownership class', () => {
+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);
@@ -37,7 +35,33 @@ test('context budget reserves headroom and caps each ownership class', () => {
   assert.equal(budget.maxToolResultChars, 24_000);
 });
 
-test('context.resolve selects high-priority evidence and returns a receipt', () => {
+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,
@@ -49,6 +73,9 @@ test('context.resolve selects high-priority evidence and returns a receipt', ()
     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) },
@@ -61,17 +88,39 @@ test('context.resolve selects high-priority evidence and returns a receipt', ()
   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.evidence_chars, 90);
+  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); // truncated remainders + one deferred source
+  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 automatically loads bounded .agentsamrules as system context', t => {
+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.writeFileSync(path.join(root, '.agentsamrules'), `# rules\n${'x'.repeat(5000)}\n`);
+  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',
@@ -84,7 +133,7 @@ test('project context automatically loads bounded .agentsamrules as system conte
   assert.equal(pack.receipt.system_chars, 1_000);
 });
 
-test('consumed tool results compact to 4k while preserving the evidence ref', async () => {
+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');

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,115 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  ERROR_CODE,
+  ERROR_REASON,
+  canonicalCodeFromGrpcStatus,
+  classifyCloudflareFailure,
+  classifyOAuthFailure,
+  classifyOpenAIError,
+  createErrorEnvelope,
+  createOpenAIHttpError,
+  diagnosticFromError,
+  grpcStatusForCode,
+} 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;
+    },
+  );
+});
+
+
+test('canonical error contract preserves transport-neutral code and reason mappings', () => {
+  const envelope = createErrorEnvelope({
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE,
+    message: 'Local terminal tunnel has no healthy connector.',
+    retryable: true,
+    http_status: 530,
+    provider: 'cloudflare',
+    provider_code: '1033',
+    transport: 'cloudflare_tunnel',
+  });
+  assert.equal(envelope.ok, false);
+  assert.equal(envelope.code, 'UNAVAILABLE');
+  assert.equal(envelope.reason, 'tunnel_connector_unavailable');
+  assert.equal(envelope.http_status, 530);
+  assert.equal(envelope.grpc_status, 14);
+  assert.equal(envelope.retryable, true);
+  assert.equal(canonicalCodeFromGrpcStatus(14), ERROR_CODE.UNAVAILABLE);
+  assert.equal(grpcStatusForCode(ERROR_CODE.UNAUTHENTICATED), 16);
+});
+
+test('Cloudflare and OAuth boundary classifiers map native failures into canonical AgentSam semantics', () => {
+  assert.deepEqual(classifyCloudflareFailure({ httpStatus: 530, cloudflareCode: 1033 }), {
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE,
+    retryable: true,
+  });
+  assert.deepEqual(classifyCloudflareFailure({ httpStatus: 526 }), {
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TLS_CERTIFICATE_INVALID,
+    retryable: false,
+  });
+  assert.deepEqual(classifyOAuthFailure('invalid_grant'), {
+    code: ERROR_CODE.UNAUTHENTICATED,
+    reason: ERROR_REASON.AUTH_INVALID,
+    retryable: false,
+  });
+  assert.deepEqual(classifyOAuthFailure('access_denied'), {
+    code: ERROR_CODE.PERMISSION_DENIED,
+    reason: ERROR_REASON.PERMISSION_DENIED,
+    retryable: false,
+  });
+});

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/fixtures/knowledge-rpc-worker.mjs

@@ -0,0 +1,16 @@
+process.once('message', payload => {
+  const generation = payload?.request?.generation_id || null;
+  const delay = generation === 'slow' ? 180 : 20;
+  setTimeout(() => {
+    if (generation === 'fail') {
+      process.send?.({ ok: false, error: 'fixture knowledge failure' });
+    } else {
+      process.send?.({ ok: true, result: {
+        operation: payload?.request?.operation || null,
+        repository_id: payload?.config?.repository_id || null,
+        generation_id: generation,
+      } });
+    }
+    setTimeout(() => process.exit(0), 5);
+  }, delay);
+});

package/test/integration/cli-help.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+
+const repoRoot = path.resolve(new URL('../..', import.meta.url).pathname);
+
+function run(...args) {
+  return spawnSync(process.execPath, ['src/cli.js', ...args], { cwd: repoRoot, encoding: 'utf8' });
+}
+
+test('agentsam help is concise, topic-aware, and deterministic outside a TTY', () => {
+  const help = run('help');
+  assert.equal(help.status, 0, help.stderr);
+  assert.doesNotMatch(help.stderr, /Unknown command/);
+  assert.match(help.stdout, /Agent Sam/);
+  assert.match(help.stdout, /Type normally to work with Agent Sam/);
+  assert.match(help.stdout, /agentsam help <topic>/);
+  assert.match(help.stdout, /press \/ for the command picker/i);
+  assert.doesNotMatch(help.stdout, /Inspect options:/);
+
+  const topic = run('help', 'runtime');
+  assert.equal(topic.status, 0, topic.stderr);
+  assert.match(topic.stdout, /Runtime \/ terminal/);
+  assert.match(topic.stdout, /agentsam connections/);
+  assert.match(topic.stdout, /agentsam deploy/);
+
+  const all = run('help', '--all');
+  assert.equal(all.status, 0, all.stderr);
+  assert.match(all.stdout, /Build \/ inspect/);
+  assert.match(all.stdout, /Create \/ extend/);
+
+  const flag = run('--help');
+  assert.equal(flag.status, 0, flag.stderr);
+  assert.match(flag.stdout, /agentsam help <topic>/);
+  assert.doesNotMatch(flag.stdout, /Inspect options:/);
+});

package/test/integration/knowledge-rpc.test.mjs

@@ -0,0 +1,112 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultConfig } from '../../src/knowledge/config.js';
+import { createKnowledgeJobEngine } from '../../src/knowledge/service/job-engine.js';
+import { startKnowledgeHttpServer } from '../../src/knowledge/service/server.js';
+import { startKnowledgeGrpcServer } from '../../src/knowledge/service/grpc-server.js';
+import { createKnowledgeServiceClient } from '../../src/knowledge/service/client.js';
+import { createKnowledgeGrpcClient } from '../../src/knowledge/service/grpc-client.js';
+import { grpc } from '../../src/knowledge/service/grpc-codec.js';
+
+const fixtureWorker = fileURLToPath(new URL('../fixtures/knowledge-rpc-worker.mjs', import.meta.url));
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function waitFor(client, id, wanted = new Set(['completed', 'failed'])) {
+  for (let i = 0; i < 200; i++) {
+    const job = await client.job(id);
+    if (wanted.has(job.status)) return job;
+    await sleep(10);
+  }
+  throw new Error(`Job ${id} did not reach ${[...wanted].join('/')}.`);
+}
+
+async function collect(stream) {
+  const events = [];
+  for await (const event of stream) events.push(event);
+  return events;
+}
+
+test('knowledge HTTP and gRPC adapters share auth, validation, idempotency, lifecycle, cancellation, and durable jobs', async t => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-rpc-'));
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+  const root = path.join(tmp, 'repo');
+  const stateDir = path.join(tmp, 'state');
+  fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'src', 'sample.js'), 'export const sample = true;\n');
+  const config = defaultConfig({ include: ['src'] });
+  const repositories = { sample: { root, config } };
+  const token = 'r'.repeat(64);
+  const engine = createKnowledgeJobEngine({ stateDir, repositories, workerPath: fixtureWorker, jobTimeoutMs: 2_000 });
+  const http = await startKnowledgeHttpServer({ engine, token, port: 0 });
+  const rpcServer = await startKnowledgeGrpcServer({ engine, token, port: 0 });
+  const httpClient = createKnowledgeServiceClient({ baseUrl: `http://127.0.0.1:${http.address.port}`, token });
+  const rpc = createKnowledgeGrpcClient({ target: rpcServer.target, token });
+  const unauthorized = createKnowledgeGrpcClient({ target: rpcServer.target, token: 'x'.repeat(64) });
+  t.after(async () => {
+    unauthorized.close();
+    rpc.close();
+    await rpcServer.close();
+    await http.close();
+    await engine.close();
+  });
+
+  const repos = await rpc.repositories();
+  assert.deepEqual(repos.repositories, ['sample']);
+  assert.equal(repos.repository_details[0].repository_id, config.repository_id);
+  assert.equal(repos.embeddings_enabled, false);
+  await assert.rejects(unauthorized.repositories(), error => error.status === 401 && error.grpcCode === grpc.status.UNAUTHENTICATED);
+  await assert.rejects(
+    rpc.submit({ repository: 'sample', operation: 'bogus' }),
+    error => error.status === 400 && error.grpcCode === grpc.status.INVALID_ARGUMENT,
+  );
+
+  const request = { repository: 'sample', operation: 'index', generation_id: 'equivalent' };
+  const fromHttp = await httpClient.submit(request, 'cross-transport');
+  const fromGrpc = await rpc.submit(request, 'cross-transport');
+  assert.equal(fromGrpc.id, fromHttp.id);
+  await assert.rejects(
+    rpc.submit({ ...request, scope: 'different' }, 'cross-transport'),
+    error => error.status === 409 && error.grpcCode === grpc.status.ABORTED,
+  );
+  const completed = await waitFor(rpc, fromGrpc.id);
+  assert.equal(completed.status, 'completed');
+  assert.equal((await httpClient.job(fromGrpc.id)).result.repository_id, completed.result.repository_id);
+
+  const blocker = await rpc.submit({ repository: 'sample', operation: 'index', generation_id: 'slow' }, 'blocker');
+  await waitFor(rpc, blocker.id, new Set(['running']));
+  const watched = await rpc.submit({ repository: 'sample', operation: 'index', generation_id: 'watch' }, 'watched');
+  const lifecycle = await collect(rpc.watch(watched.id));
+  assert.deepEqual(lifecycle.map(event => event.job.status), ['queued', 'running', 'completed']);
+  assert.deepEqual(lifecycle.map(event => event.sequence), [1, 2, 3]);
+
+  const failed = await rpc.submit({ repository: 'sample', operation: 'index', generation_id: 'fail' }, 'failed');
+  const failureEvents = await collect(rpc.watch(failed.id));
+  assert.equal(failureEvents.at(-1).job.status, 'failed');
+  assert.match(failureEvents.at(-1).job.error, /fixture knowledge failure/);
+
+  const cancellable = await rpc.submit({ repository: 'sample', operation: 'index', generation_id: 'slow' }, 'cancel-watch');
+  const controller = new AbortController();
+  const iterator = rpc.watch(cancellable.id, { signal: controller.signal })[Symbol.asyncIterator]();
+  const first = await iterator.next();
+  assert.equal(first.done, false);
+  controller.abort();
+  const afterAbort = await iterator.next();
+  assert.equal(afterAbort.done, true);
+  assert.equal((await waitFor(rpc, cancellable.id)).status, 'completed');
+
+  const deadlineJob = await rpc.submit({ repository: 'sample', operation: 'index', generation_id: 'slow' }, 'deadline-watch');
+  let deadlineError = null;
+  try {
+    await collect(rpc.watch(deadlineJob.id, { timeoutMs: 15 }));
+  } catch (error) {
+    deadlineError = error;
+  }
+  assert.ok(deadlineError);
+  assert.equal(deadlineError.grpcCode, grpc.status.DEADLINE_EXCEEDED);
+  assert.equal(deadlineError.status, 504);
+  assert.equal((await waitFor(rpc, deadlineJob.id)).status, 'completed');
+});