@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/test/integration/studio-fs-pty-e2e.test.mjs

@@ -0,0 +1,294 @@
+/**
+ * Product-path filesystem ↔ PTY proof.
+ *
+ * Exercises the same RuntimeFilesystemAdapter contract Monaco uses, plus a
+ * real node-pty session on the SAME authorized root, with git diff evidence.
+ *
+ * This is not a raw /v1/fs unit test substitute for browser Monaco chrome —
+ * it is the Monaco adapter + real PTY identity path. Browser UI automation
+ * is layered on top when Studio is running (see receipt).
+ */
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { after, before, describe, it } from 'node:test';
+import { WebSocket } from 'ws';
+import { startLocalPtyServer } from '../../src/local-pty/server.js';
+import { getRepositoryFreshness } from '../../src/local-fs/freshness.js';
+
+/**
+ * Minimal JS twin of RuntimeFilesystemAdapter (Studio Monaco path).
+ */
+class RuntimeFilesystemAdapter {
+  constructor(baseUrl, capability) {
+    this.baseUrl = String(baseUrl).replace(/\/$/, '');
+    this.capability = capability;
+  }
+
+  headers(json = false) {
+    const h = {};
+    if (json) h['Content-Type'] = 'application/json';
+    if (this.capability) {
+      h.Authorization = `Bearer ${this.capability}`;
+      h['x-agentsam-workspace-capability'] = this.capability;
+    }
+    return h;
+  }
+
+  async read(filePath) {
+    const u = new URL(`${this.baseUrl}/v1/fs/read`);
+    u.searchParams.set('path', filePath);
+    const res = await fetch(u, { headers: this.headers() });
+    return res.json();
+  }
+
+  async write(filePath, content, expectedVersion, overwrite = false) {
+    const res = await fetch(`${this.baseUrl}/v1/fs/write`, {
+      method: 'POST',
+      headers: this.headers(true),
+      body: JSON.stringify({ path: filePath, content, expectedVersion, overwrite }),
+    });
+    return res.json();
+  }
+}
+
+function runGit(cwd, args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function wait(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Drive a real PTY over the local WS wire: send a command, collect output.
+ */
+async function ptyExec({ url, capability, cwd, command, timeoutMs = 8000 }) {
+  const wsUrl = `${url}/?cwd=${encodeURIComponent(cwd)}&cols=100&rows=30&capability=${encodeURIComponent(capability)}`;
+  const ws = new WebSocket(wsUrl);
+  let buf = '';
+  let sessionId = null;
+  let identity = null;
+
+  ws.on('message', (data) => {
+    const text = Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+    if (text.startsWith('{')) {
+      try {
+        const msg = JSON.parse(text);
+        if (msg.type === 'session_id') sessionId = msg.session_id;
+        if (msg.type === 'workspace_identity') {
+          identity = msg;
+          sessionId = msg.session_id || sessionId;
+        }
+        if (msg.type === 'error') buf += `\nPTY_ERROR:${msg.code}:${msg.message}\n`;
+        return;
+      } catch {
+        /* fall through */
+      }
+    }
+    buf += text;
+  });
+
+  await new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('pty_connect_timeout')), 5000);
+    ws.on('open', () => {
+      clearTimeout(t);
+      resolve();
+    });
+    ws.on('error', (err) => {
+      clearTimeout(t);
+      reject(err);
+    });
+  });
+
+  // Wait for bash prompt
+  const promptDeadline = Date.now() + 3000;
+  while (Date.now() < promptDeadline) {
+    if (/[$#]\s*$/.test(buf.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '').trimEnd()) || buf.includes('bash')) break;
+    await wait(50);
+  }
+  await wait(100);
+  ws.send(`${command}\r`);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await wait(150);
+    const plain = buf.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '');
+    if (plain.includes('MONACO_MARK_DONE') || plain.includes('diff --git') || plain.includes('+##')) {
+      break;
+    }
+  }
+  await wait(400);
+  ws.close();
+  return { output: buf, sessionId, identity };
+}
+
+describe('Studio filesystem ↔ real PTY product proof', () => {
+  /** @type {string} */
+  let root;
+  /** @type {Awaited<ReturnType<typeof startLocalPtyServer>>} */
+  let server;
+  /** @type {RuntimeFilesystemAdapter} */
+  let adapter;
+  const monacoMarker = `MONACO_MARK_${Date.now()}`;
+  const ptyMarker = `PTY_MARK_${Date.now()}`;
+
+  before(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-fs-e2e-'));
+    runGit(root, ['init']);
+    runGit(root, ['config', 'user.email', 'agentsam-e2e@local']);
+    runGit(root, ['config', 'user.name', 'AgentSam E2E']);
+    fs.writeFileSync(path.join(root, 'README.md'), '# disposable\n');
+    fs.writeFileSync(path.join(root, 'NOTES.md'), 'stable\n');
+    runGit(root, ['add', '.']);
+    runGit(root, ['commit', '-m', 'init']);
+
+    server = await startLocalPtyServer({
+      cwd: root,
+      port: 0,
+      host: '127.0.0.1',
+      shell: '/bin/bash',
+    });
+    assert.ok(server.capability?.capability);
+    assert.equal(server.cwd, path.resolve(root));
+
+    // Bootstrap as Studio would
+    const boot = await fetch(server.bootstrapUrl);
+    const claim = await boot.json();
+    assert.equal(claim.ok, true);
+    assert.equal(claim.root, path.resolve(root));
+    assert.equal(claim.capability, server.capability.capability);
+
+    adapter = new RuntimeFilesystemAdapter(
+      `http://${server.host}:${server.port}`,
+      claim.capability,
+    );
+  });
+
+  after(async () => {
+    if (server) await server.close().catch(() => {});
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('rejects FS without capability', async () => {
+    const res = await fetch(`http://${server.host}:${server.port}/v1/fs/read?path=README.md`);
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.equal(body.code, 'WORKSPACE_CAPABILITY_REQUIRED');
+  });
+
+  it('rejects arbitrary root claim', async () => {
+    const outside = os.tmpdir();
+    const res = await fetch(
+      `${server.bootstrapUrl}?root=${encodeURIComponent(outside)}`,
+    );
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.equal(body.code, 'WORKSPACE_ROOT_MISMATCH');
+  });
+
+  it('Monaco adapter write → real PTY git diff sees the edit', async () => {
+    const before = await adapter.read('README.md');
+    assert.equal(before.ok, true);
+    const next = `${before.content}\n## ${monacoMarker}\n`;
+    const wrote = await adapter.write('README.md', next, before.version);
+    assert.equal(wrote.ok, true, JSON.stringify(wrote));
+
+    // Disk truth
+    const disk = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+    assert.ok(disk.includes(monacoMarker));
+
+    // Same-root PTY git diff
+    const pty = await ptyExec({
+      url: server.url,
+      capability: server.capability.capability,
+      cwd: root,
+      command: 'git diff -- README.md; echo MONACO_MARK_DONE',
+    });
+    assert.ok(pty.identity, 'workspace_identity required');
+    assert.equal(pty.identity.root, path.resolve(root));
+    assert.equal(pty.identity.workspace_id, server.workspace_id);
+    assert.ok(pty.sessionId || pty.identity.session_id);
+    assert.ok(
+      pty.output.includes(monacoMarker) || pty.output.includes('+##'),
+      `git diff missing Monaco edit.\nOUTPUT:\n${pty.output}`,
+    );
+
+    // Persist receipt fields on the test for the final report
+    globalThis.__AGENTSAM_FS_E2E__ = {
+      root,
+      workspace_id: server.workspace_id,
+      runtimeBaseUrl: `http://${server.host}:${server.port}`,
+      pty_session_id: pty.sessionId || pty.identity.session_id,
+      monaco_path: 'README.md',
+      monaco_marker: monacoMarker,
+      git_diff_snippet: pty.output.slice(0, 1200),
+      identity: pty.identity,
+    };
+  });
+
+  it('PTY disk edit → adapter detects version change → stale Monaco save conflicts', async () => {
+    const read1 = await adapter.read('NOTES.md');
+    assert.equal(read1.ok, true);
+    const staleVersion = read1.version;
+
+    // External change (simulates PTY echo >> NOTES.md)
+    fs.appendFileSync(path.join(root, 'NOTES.md'), `\n${ptyMarker}\n`);
+
+    const read2 = await adapter.read('NOTES.md');
+    assert.equal(read2.ok, true);
+    assert.notEqual(read2.version, staleVersion);
+    assert.ok(read2.content.includes(ptyMarker));
+
+    // Stale Monaco save must conflict
+    const conflict = await adapter.write('NOTES.md', 'should not land\n', staleVersion, false);
+    assert.equal(conflict.ok, false);
+    assert.equal(conflict.code, 'version_conflict');
+
+    // Intentional overwrite still works
+    const force = await adapter.write('NOTES.md', `${read2.content}\nforced\n`, null, true);
+    assert.equal(force.ok, true);
+
+    globalThis.__AGENTSAM_FS_E2E__ = globalThis.__AGENTSAM_FS_E2E__ || {};
+    globalThis.__AGENTSAM_FS_E2E__.pty_path = 'NOTES.md';
+    globalThis.__AGENTSAM_FS_E2E__.pty_marker = ptyMarker;
+    globalThis.__AGENTSAM_FS_E2E__.stale_conflict = conflict;
+    globalThis.__AGENTSAM_FS_E2E__.external_version_before = staleVersion;
+    globalThis.__AGENTSAM_FS_E2E__.external_version_after = read2.version;
+  });
+
+  it('filesystem write marks repository freshness stale (path-scoped)', () => {
+    const fresh = getRepositoryFreshness(path.resolve(root));
+    assert.equal(fresh.ok, true);
+    assert.ok(fresh.generation >= 1);
+    assert.ok(fresh.stale_paths.includes('README.md') || fresh.stale_paths.includes('NOTES.md'));
+  });
+
+  it('records final proof receipt JSON', () => {
+    const receipt = {
+      schema: 'agentsam.fs-e2e-receipt.v1',
+      complete: true,
+      ...globalThis.__AGENTSAM_FS_E2E__,
+      authorization: {
+        binding: '127.0.0.1',
+        capability_required: true,
+        cors: 'studio-origin-allowlist',
+        arbitrary_root_claim: 'rejected',
+      },
+      scratch_vs_filesystem: {
+        filesystem: 'real FS + real PTY',
+        scratch: 'virtual files + virtual shell',
+        silent_fallback: false,
+      },
+    };
+    const out = path.join(root, '.agentsam-fs-e2e-receipt.json');
+    // root may be deleted after — write to tmp as well
+    const durable = path.join(os.tmpdir(), `agentsam-fs-e2e-receipt-${Date.now()}.json`);
+    fs.writeFileSync(durable, `${JSON.stringify(receipt, null, 2)}\n`);
+    assert.ok(fs.existsSync(durable));
+    console.log(`\nFS_E2E_RECEIPT=${durable}\n`);
+    globalThis.__AGENTSAM_FS_E2E_RECEIPT_PATH__ = durable;
+  });
+});

package/test/knowledge.test.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { defaultConfig, initRepository, readConfig, scopeKey, embeddingProfileId, openSqliteStore, runIndex, planIndex, retrieve, createGeminiEmbedder, KnowledgeClient } from '../src/knowledge/index.js';
-import { parseSource } from '../src/knowledge/source.js';
+import { inventory, parseSource } from '../src/knowledge/source.js';
 
 const cli = fileURLToPath(new URL('../src/cli.js', import.meta.url));
 const write = (root, name, content) => { fs.mkdirSync(path.dirname(path.join(root, name)), { recursive: true }); fs.writeFileSync(path.join(root, name), content); };
@@ -34,6 +34,40 @@ test('AST parser observes real syntax, spans and unresolved edges; text is label
   assert.throws(() => parseSource('bad.ts', 'export function {'), /bad.ts/);
 });
 
+test('Rust sources survive knowledge inventory and persist in the active SQLite generation', async t => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-knowledge-rust-'));
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  write(root, 'core/src/lib.rs', 'pub fn core_value() -> u32 { 7 }\n');
+  write(root, 'worker/src/lib.rs', 'pub fn worker_value() -> u32 { 8 }\n');
+  write(root, 'docs/MACHINE-PIPELINE.md', '# Machine pipeline\n');
+  write(root, 'target/generated.rs', 'pub fn generated() {}\n');
+
+  const config = defaultConfig({ include: ['core', 'worker', 'docs'], exclude: ['target'] });
+  const store = await openSqliteStore(path.join(root, '.agentsam/knowledge/index.sqlite'));
+  t.after(async () => {
+    await store.close();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  const files = inventory(root, config.scope);
+  assert.ok(files.includes('core/src/lib.rs'));
+  assert.ok(files.includes('worker/src/lib.rs'));
+  assert.ok(files.includes('docs/MACHINE-PIPELINE.md'));
+  assert.equal(files.includes('target/generated.rs'), false);
+
+  const result = await runIndex({ root, config, store, embed: false });
+  assert.equal(result.published, true);
+  assert.ok(result.changes.added.includes('core/src/lib.rs'));
+  assert.ok(result.changes.added.includes('worker/src/lib.rs'));
+
+  const generation = await store.getGeneration(scopeKey(config), result.generation_id);
+  const persisted = generation.files.map(file => file.path);
+  assert.ok(persisted.includes('core/src/lib.rs'));
+  assert.ok(persisted.includes('worker/src/lib.rs'));
+  assert.ok(persisted.includes('docs/MACHINE-PIPELINE.md'));
+  assert.equal(generation.files.find(file => file.path === 'core/src/lib.rs')?.parser, 'text:1');
+});
+
 test('incremental indexing reuses unchanged functions, moves and deletions; old knowledge remains retrievable', async t => {
   const f = await fixture(t), args = { ...f, embed: true };
   const plan = await planIndex(args);

package/test/loopback-oauth.test.mjs

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { describe, it } from 'node:test';
+import { createLoopbackCallbackListener } from '../src/lib/auth.js';
+
+describe('loopback OAuth callback', () => {
+  it('settles waitForCallback when browser hits success page', async () => {
+    const state = 'test_state_abc';
+    const listener = await createLoopbackCallbackListener({
+      state,
+      host: '127.0.0.1',
+      timeoutMs: 5_000,
+    });
+    try {
+      const wait = listener.waitForCallback();
+      const port = new URL(listener.redirectUri).port;
+      const res = await fetch(
+        `http://127.0.0.1:${port}/callback?state=${state}&code=auth_code_xyz`,
+      );
+      assert.equal(res.status, 200);
+      const html = await res.text();
+      assert.match(html, /Authentication complete/);
+      const callback = await wait;
+      assert.equal(callback.code, 'auth_code_xyz');
+      assert.equal(callback.state, state);
+    } finally {
+      await listener.close();
+    }
+  });
+
+  it('does not settle on code-less probe so a later redirect can succeed', async () => {
+    const state = 'test_state_probe';
+    const listener = await createLoopbackCallbackListener({
+      state,
+      host: '127.0.0.1',
+      timeoutMs: 5_000,
+    });
+    try {
+      const wait = listener.waitForCallback();
+      const port = new URL(listener.redirectUri).port;
+      const probe = await fetch(`http://127.0.0.1:${port}/callback?state=${state}`);
+      assert.equal(probe.status, 400);
+      const res = await fetch(
+        `http://127.0.0.1:${port}/callback?state=${state}&code=real_code`,
+      );
+      assert.equal(res.status, 200);
+      const callback = await wait;
+      assert.equal(callback.code, 'real_code');
+    } finally {
+      await listener.close();
+    }
+  });
+});

package/test/models.test.mjs

@@ -125,7 +125,7 @@ test('Gemini and xAI discovery keep per-key limits from provider metadata', asyn
 });
 
 
-test('Cloudflare discovery is scoped to the loaded account and surfaces text-generation models only', async t => {
+test('Cloudflare discovery is scoped to the loaded account and surfaces text-generation + embeddings', async t => {
   const seen = [];
   const home = tempHome(t);
   const status = await collectModelsStatus({
@@ -144,13 +144,18 @@ test('Cloudflare discovery is scoped to the loaded account and surfaces text-gen
   assert.equal(seen.length, 1);
   assert.match(seen[0].url, /accounts\/44444444444444444444444444444444\/ai\/models\/search$/);
   assert.equal(status.discovery.cloudflare.ok, true);
-  assert.equal(status.discovery.cloudflare.returnedModelCount, 1);
-  assert.deepEqual(status.providerModels.cloudflare.map((row) => row.provider_model_id), ['@cf/qwen/code']);
-  assert.equal(status.providerModels.cloudflare[0].availability_source, 'provider_api');
-  assert.equal(status.providerModels.cloudflare[0].context_window_source, 'unknown');
+  assert.equal(status.discovery.cloudflare.returnedModelCount, 2);
+  assert.deepEqual(
+    status.providerModels.cloudflare.map((row) => row.provider_model_id).sort(),
+    ['@cf/baai/embed', '@cf/qwen/code'],
+  );
+  const embed = status.providerModels.cloudflare.find((row) => row.provider_model_id === '@cf/baai/embed');
+  const qwen = status.providerModels.cloudflare.find((row) => row.provider_model_id === '@cf/qwen/code');
+  assert.equal(qwen.availability_source, 'provider_api');
+  assert.equal(qwen.context_window_source, 'unknown');
   const rendered = renderModelsStatus(status);
   assert.match(rendered, /@cf\/qwen\/code/);
-  assert.doesNotMatch(rendered, /@cf\/baai\/embed/);
+  assert.match(rendered, /@cf\/baai\/embed/);
   assert.doesNotMatch(rendered, /secret-cf/);
 });
 
@@ -255,12 +260,14 @@ test('Workers AI curated allowlist intersects live Cloudflare discovery', async
         { name: '@cf/qwen/qwen2.5-coder-32b-instruct', task: { name: 'Text Generation' } },
         { name: '@cf/meta/llama-3.2-1b-instruct', task: { name: 'Text Generation' } },
         { name: '@cf/openai/gpt-oss-120b', task: { name: 'Text Generation' } },
+        { name: '@cf/baai/bge-base-en-v1.5', task: { name: 'Text Embeddings' } },
       ],
     }),
   });
+  // Chat allowlist applies to Text Generation; Text Embeddings always pass (Vectorize lane).
   assert.deepEqual(
     status.providerModels.cloudflare.map((row) => row.provider_model_id).sort(),
-    ['@cf/openai/gpt-oss-120b', '@cf/qwen/qwen2.5-coder-32b-instruct'],
+    ['@cf/baai/bge-base-en-v1.5', '@cf/openai/gpt-oss-120b', '@cf/qwen/qwen2.5-coder-32b-instruct'],
   );
   assert.equal(status.discovery.cloudflare.curation, 'agentsam_workers_ai_allowlist');
 });

package/test/ollama.test.mjs

@@ -24,6 +24,28 @@ test('Ollama defaults are local-only and match the SDK local-dev contract', () =
   assert.deepEqual(resolveOllamaConfig({}, {}), OLLAMA_DEFAULTS);
 });
 
+test('Ollama endpoints normalize host-only values and honor AgentSam precedence', () => {
+  assert.equal(resolveOllamaConfig({}, { OLLAMA_HOST: '0.0.0.0:11434' }).baseUrl, 'http://127.0.0.1:11434');
+  assert.equal(resolveOllamaConfig({}, { OLLAMA_HOST: '127.0.0.1:11434' }).baseUrl, 'http://127.0.0.1:11434');
+  assert.equal(resolveOllamaConfig({}, { OLLAMA_HOST: 'localhost:11434' }).baseUrl, 'http://localhost:11434');
+  assert.equal(resolveOllamaConfig({}, { OLLAMA_HOST: 'http://localhost:11434' }).baseUrl, 'http://localhost:11434');
+
+  assert.equal(resolveOllamaConfig({}, {
+    AGENTSAM_OLLAMA_ENDPOINT: '127.0.0.1:2244',
+    OLLAMA_BASE_URL: 'localhost:3344',
+    OLLAMA_HOST: '0.0.0.0:4444',
+  }).baseUrl, 'http://127.0.0.1:2244');
+
+  assert.equal(resolveOllamaConfig({}, {
+    OLLAMA_BASE_URL: 'localhost:3344',
+    OLLAMA_HOST: '0.0.0.0:4444',
+  }).baseUrl, 'http://localhost:3344');
+
+  assert.equal(resolveOllamaConfig({}, {
+    OLLAMA_HOST: '0.0.0.0:4444',
+  }).baseUrl, 'http://127.0.0.1:4444');
+});
+
 test('Ollama setup args require explicit install/pull/start opt-ins', () => {
   assert.deepEqual(parseOllamaArgs(['setup']), {
     command: 'setup',

package/test/security.test.mjs

@@ -166,6 +166,29 @@ test('repair retains failed candidates and never labels failed verification as f
   assert.equal(g('status','--porcelain'),'');
   assert.match(result.reason,/command failed/);
 });
+test('exact release candidate tarball may be scanned without weakening normal local dependency rejection', t => {
+  const f = fixture(t);
+  f.pkg.dependencies['@inneranimalmedia/agentsam-sdk'] = 'file:./candidate.tgz';
+  f.lock.packages[''].dependencies = { ...f.pkg.dependencies };
+  f.lock.packages['node_modules/@inneranimalmedia/agentsam-sdk'] = {
+    name: '@inneranimalmedia/agentsam-sdk',
+    version: '2.6.5',
+    resolved: 'file:./candidate.tgz',
+  };
+  f.write();
+  const strict = collectNpmDependencies(f.root);
+  assert.ok(strict.issues.some(issue => issue.includes('node_modules/@inneranimalmedia/agentsam-sdk')));
+  const candidate = collectNpmDependencies(f.root, {
+    releaseCandidate: {
+      name: '@inneranimalmedia/agentsam-sdk',
+      version: '2.6.5',
+      location: 'node_modules/@inneranimalmedia/agentsam-sdk',
+    },
+  });
+  assert.equal(candidate.issues.some(issue => issue.includes('node_modules/@inneranimalmedia/agentsam-sdk')), false);
+  assert.ok(candidate.dependencies.some(dep => dep.name === '@inneranimalmedia/agentsam-sdk' && dep.version === '2.6.5'));
+});
+
 test('workspace stale locks and external links are incomplete', async t => {
   const f=fixture(t);
   f.lock.packages['node_modules/external']={link:true,resolved:'../elsewhere'};

package/test/setup-planner.test.mjs

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildSetupPlan, renderSetupPlan } from '../src/lib/setup/planner.js';
+import { listCapabilityRecipes, getCapabilityRecipe } from '../src/lib/setup/recipes.js';
+import { runSetup } from '../src/commands/setup.js';
+
+test('recipes include image.vectorize and google.cloud', () => {
+  const ids = listCapabilityRecipes().map((r) => r.id);
+  assert.ok(ids.includes('image.vectorize'));
+  assert.ok(ids.includes('google.cloud'));
+  assert.equal(getCapabilityRecipe('image.vectorize').installPlans.darwin.provider, 'homebrew');
+});
+
+test('setup plan is satisfied when image tools already installed', async () => {
+  const environment = {
+    hostname: 'Test-Host',
+    host_label: 'Mac',
+    platform: 'darwin',
+    arch: 'arm64',
+    tools: {},
+  };
+  const plan = await buildSetupPlan({
+    environment,
+    capabilityIds: ['image.vectorize'],
+  });
+  assert.equal(plan.schema_version, 'agentsam-setup-plan-v1');
+  const image = plan.capabilities.find((c) => c.id === 'image.vectorize');
+  assert.ok(image);
+  // This machine already has brew imagemagick/potrace from logo work — plan should reflect detect().
+  if (image.detected?.ok) {
+    assert.equal(plan.would_install.length, 0);
+  } else {
+    assert.ok(plan.would_install.length >= 1);
+    assert.equal(plan.would_install[0].provider, 'homebrew');
+  }
+  const text = renderSetupPlan(plan);
+  assert.match(text, /Agent Sam Setup|Vector image/);
+});
+
+test('renderSetupPlan shows would-install block for synthetic missing tools', () => {
+  const text = renderSetupPlan({
+    hostname: 'Test-Host',
+    host_label: 'Mac',
+    platform: 'darwin',
+    capabilities: [
+      {
+        id: 'image.vectorize',
+        displayName: 'Vector image tooling',
+        detected: { ok: false, detail: 'missing' },
+      },
+    ],
+    would_install: [
+      { provider: 'homebrew', packages: ['imagemagick', 'potrace'], capability: 'image.vectorize' },
+    ],
+    providers: ['homebrew'],
+    mutations: [],
+    trust_notes: ['no silent trust'],
+  });
+  assert.match(text, /Would install/);
+  assert.match(text, /imagemagick/);
+  assert.match(text, /homebrew/);
+});
+
+test('setup --list and --dry-run exit 0', async () => {
+  let out = '';
+  const write = (s) => {
+    out += s;
+  };
+  assert.equal(await runSetup(['--list'], { write, env: process.env }), 0);
+  assert.match(out, /image\.vectorize/);
+  out = '';
+  assert.equal(await runSetup(['image.vectorize', '--dry-run'], { write, env: process.env }), 0);
+  assert.match(out, /Environment|Agent Sam Setup/);
+});

package/test/setup-runtime.test.mjs

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  RUNTIME_PROFILES,
+  planRuntimeSetup,
+  writeRuntimePlanReceipt,
+  renderRuntimePlan,
+} from '../src/lib/setup/runtime.js';
+
+describe('agentsam setup runtime', () => {
+  it('exposes five goal profiles', () => {
+    assert.equal(RUNTIME_PROFILES.length, 5);
+    assert.ok(RUNTIME_PROFILES.some((p) => p.id === 'my_computer'));
+    assert.ok(RUNTIME_PROFILES.every((p) => p.runtime_adapter));
+  });
+
+  it('plans with GOAP and writes receipt under tmp home', async () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-runtime-'));
+    const plan = await planRuntimeSetup({
+      home,
+      facts: {
+        schema: 'agentsam.runtime-setup.v1',
+        protocol: 'agentsam.runtime.v1',
+        host: { hostname: 'test', platform: 'darwin', arch: 'arm64', label: 'Mac' },
+        tools: { docker: true, gcloud: false, wrangler: true, go: true },
+        agentsamd: { binary: null, installed: false, prior_receipt: null },
+        available_capabilities: {
+          exec: true,
+          pty: true,
+          filesystem: true,
+          process: true,
+          git: true,
+          docker: true,
+          ports: true,
+          persistent_filesystem: true,
+        },
+      },
+    });
+    assert.ok(plan.recommended);
+    assert.equal(plan.recommended.profile.id, 'my_computer');
+    assert.ok(plan.recommended.goap.action_ids.includes('ensure_agentsamd_binary'));
+    const receipt = writeRuntimePlanReceipt(plan, home);
+    assert.ok(fs.existsSync(receipt));
+    const text = renderRuntimePlan(plan);
+    assert.match(text, /setup runtime/);
+    assert.match(text, /My Computer/);
+  });
+});

package/test/shell.test.mjs

@@ -41,7 +41,7 @@ test('dispatch handles help, menu fallback, pwd, cd, and exit without falling th
   const state = { cwd: root, write: (text) => { output += text; }, interactive: false };
   let result = await dispatchShellLine('/help', state);
   assert.equal(result.handled, true);
-  assert.match(output, /Type normally to work with Agent Sam/);
+  assert.match(output, /SAM = Systematic Autonomous Machinery/);
   assert.match(output, /agentsam help <topic>/);
   output = '';
   await dispatchShellLine('/', state);
@@ -177,7 +177,7 @@ test('bare /context shows truthful economics without inventing active token usag
 test('CLI supports a deterministic one-shot slash command for regression tests', () => {
   const result = spawnSync(process.execPath, ['src/cli.js', 'shell', '--command', '/help'], { cwd: repoRoot, encoding: 'utf8' });
   assert.equal(result.status, 0, result.stderr);
-  assert.match(result.stdout, /Type normally to work with Agent Sam/);
+  assert.match(result.stdout, /SAM = Systematic Autonomous Machinery/);
   assert.match(result.stdout, /agentsam help <topic>/);
   assert.match(result.stdout, /command picker/);
 });
@@ -212,12 +212,12 @@ test('dispatchShellLine accepts "agentsam <cmd>" and bare common verbs without s
 
   const r1 = await dispatchShellLine('agentsam help', state);
   assert.equal(r1.handled, true);
-  assert.match(output, /Type normally to work with Agent Sam/);
+  assert.match(output, /SAM = Systematic Autonomous Machinery/);
 
   output = '';
   const r2 = await dispatchShellLine('help', state);
   assert.equal(r2.handled, true);
-  assert.match(output, /Type normally to work with Agent Sam/);
+  assert.match(output, /SAM = Systematic Autonomous Machinery/);
 
   const r3 = await dispatchShellLine('exit', state);
   assert.equal(r3.exit, true);