@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.1

package/test/integration/runtime-migrations.test.mjs

@@ -0,0 +1,82 @@
+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 { createLocalSqliteDatabase } from '../../src/local/sqlite.js';
+import { applyRuntimeMigrations } from '../../src/local/migrations.js';
+
+test('portable runtime migration installs AgentSam CLI state tables idempotently', async (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-runtime-migration-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const db = await createLocalSqliteDatabase(path.join(root, 'agentsam.sqlite'));
+  try {
+    const first = await applyRuntimeMigrations(db);
+    assert.equal(first.applied, 1);
+
+    const tables = await db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'agentsam_%' ORDER BY name"
+    ).all();
+    const names = new Set(tables.results.map((row) => row.name));
+    for (const name of [
+      'agentsam_agent_run',
+      'agentsam_approval_queue',
+      'agentsam_compaction_events',
+      'agentsam_context_digest',
+      'agentsam_cron_runs',
+      'agentsam_plans',
+      'agentsam_schema_migrations',
+      'agentsam_todo',
+    ]) assert.equal(names.has(name), true, name);
+
+    const timers = await db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='active_timers'"
+    ).first();
+    assert.equal(timers.name, 'active_timers');
+
+    const second = await applyRuntimeMigrations(db);
+    assert.equal(second.applied, 0);
+    assert.equal(second.results[0].status, 'already_applied');
+  } finally {
+    db.close();
+  }
+});
+
+test('ephemeral context digests expire and refresh while durable digests stay durable', async (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-digest-migration-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const db = await createLocalSqliteDatabase(path.join(root, 'agentsam.sqlite'));
+  try {
+    await applyRuntimeMigrations(db);
+
+    await db.prepare(
+      "INSERT INTO agentsam_context_digest (id,digest_type,source_hash,digest_hash,digest_text) VALUES (?,?,?,?,?)"
+    ).bind('repo_1', 'repo', 's1', 'h1', 'durable').run();
+    const durable = await db.prepare(
+      'SELECT expires_at_unix FROM agentsam_context_digest WHERE id=?'
+    ).bind('repo_1').first();
+    assert.equal(durable.expires_at_unix, null);
+
+    await db.prepare(
+      "INSERT INTO agentsam_context_digest (id,digest_type,source_hash,digest_hash,digest_text) VALUES (?,?,?,?,?)"
+    ).bind('session_1', 'session', 's2', 'h2', 'ephemeral').run();
+    const initial = await db.prepare(
+      'SELECT expires_at_unix FROM agentsam_context_digest WHERE id=?'
+    ).bind('session_1').first();
+    assert.equal(Number(initial.expires_at_unix) > 0, true);
+
+    await db.prepare(
+      'UPDATE agentsam_context_digest SET expires_at_unix = unixepoch() + 60 WHERE id=?'
+    ).bind('session_1').run();
+    await db.prepare(
+      'UPDATE agentsam_context_digest SET hit_count = hit_count + 1 WHERE id=?'
+    ).bind('session_1').run();
+    const refreshed = await db.prepare(
+      'SELECT expires_at_unix, hit_count FROM agentsam_context_digest WHERE id=?'
+    ).bind('session_1').first();
+    assert.equal(refreshed.hit_count, 1);
+    assert.equal(Number(refreshed.expires_at_unix) > Math.floor(Date.now() / 1000) + 2_500_000, true);
+  } finally {
+    db.close();
+  }
+});

package/test/knowledge-service.test.mjs

@@ -88,6 +88,11 @@ test('portable dockerize stages only SDK runtime, preserves identities/tokens, a
     const context = path.join(result.written.versionDir, 'context');
     assert.equal(fs.existsSync(path.join(context, 'customer-secret.js')), false);
     assert.equal(fs.existsSync(path.join(context, 'src/knowledge/service/server.js')), true);
+    assert.equal(fs.existsSync(path.join(context, 'src/knowledge/service/grpc-server.js')), true);
+    assert.equal(fs.existsSync(path.join(context, 'src/rpc/generated/knowledge_pb.js')), true);
+    assert.equal(fs.existsSync(path.join(context, 'src/rpc/generated/knowledge_grpc_pb.js')), true);
+    assert.equal(fs.existsSync(path.join(context, 'src/rpc/generated/package.json')), true);
+    assert.equal(fs.existsSync(path.join(context, 'src/errors/contract.js')), true);
     assert.equal(fs.existsSync(path.join(context, 'package-lock.json')), true);
     const token = fs.readFileSync(result.tokenFile, 'utf8');
     assert.equal(fs.statSync(result.tokenFile).mode & 0o777, 0o600);

package/test/knowledge.test.mjs

@@ -114,6 +114,22 @@ test('source safety and setup preserve repository files; read-only plan creates
   assert.ok(!paths.includes('.env.js')); assert.ok(!paths.includes('ignored/hidden.ts'));
 });
 
+test('index and search derive safe local defaults when knowledge.json is absent', async t => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-configless-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  execFileSync('git', ['remote', 'add', 'origin', 'git@github.com:ExampleOrg/ConfiglessRepo.git'], { cwd: root });
+  write(root, 'src/real.ts', 'export function configlessSymbol() { return 7; }\n');
+  const run = args => JSON.parse(execFileSync(process.execPath, [cli, ...args], { cwd: root, encoding: 'utf8' }));
+  assert.equal(fs.existsSync(path.join(root, '.agentsam/knowledge.json')), false);
+  const plan = run(['index', 'plan']);
+  assert.ok(plan.files >= 1); assert.equal(plan.embedding_inputs, 0);
+  assert.equal(fs.existsSync(path.join(root, '.agentsam/knowledge.json')), false);
+  assert.equal(run(['index', 'run']).published, true);
+  assert.equal(fs.existsSync(path.join(root, '.agentsam/knowledge.json')), false);
+  assert.equal(run(['search', 'configlessSymbol']).hits[0].path, 'src/real.ts');
+});
+
 test('two independent repositories work through the same CLI and exported package', async t => {
   for (const name of ['customer-a', 'customer-b']) {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), name));

package/test/live/terminal-transport.live.test.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { WebSocket } from 'ws';
+
+const liveUrl = String(process.env.AGENTSAM_LIVE_TERMINAL_WS_URL || '').trim();
+
+test('live terminal transport accepts a websocket connection', { skip: !liveUrl }, async (t) => {
+  const ws = new WebSocket(liveUrl, {
+    headers: process.env.AGENTSAM_LIVE_TERMINAL_AUTH
+      ? { authorization: process.env.AGENTSAM_LIVE_TERMINAL_AUTH }
+      : undefined,
+  });
+  t.after(() => { try { ws.close(); } catch {} });
+
+  await Promise.race([
+    new Promise((resolve, reject) => {
+      ws.once('open', resolve);
+      ws.once('error', reject);
+    }),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('live terminal websocket open timed out')), 8000)),
+  ]);
+
+  assert.equal(ws.readyState, WebSocket.OPEN);
+});

package/test/local-sessions.test.mjs

@@ -27,6 +27,10 @@ test('local sessions persist provider-neutral continuation, usage, cost, and las
     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,
+    cost_breakdown_usd: { input: 0.08, cached_input: 0.01, cache_write: 0.003456, output: 0.03 },
+    status: 'paused',
+    active_elapsed_ms: 90_000,
+    active_started_at: null,
   }, { home });
 
   const loaded = loadLocalSession(session.id, { home });
@@ -36,7 +40,9 @@ test('local sessions persist provider-neutral continuation, usage, cost, and las
 
   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, /Spent: \$0\.1235/);
+  assert.match(receipt, /Elapsed: 1m 30s/);
+  assert.match(receipt, /Cost breakdown: input \$0\.0800 · cached \$0\.0100 · cache write \$0\.003456 · output \$0\.0300/);
   assert.match(receipt, new RegExp(`agentsam resume ${session.id}`));
   assert.match(receipt, /Run wrangler whoami/);
 });

package/test/models.test.mjs

@@ -21,7 +21,7 @@ test('model inventory reports configured API providers without exposing credenti
     home,
     discoverRemote: false,
     env: {
-      OPENAI_API_KEY: 'secret-openai', GEMINI_API_KEY: '', XAI_API_KEY: 'secret-xai', ANTHROPIC_API_KEY: 'secret-anthropic',
+      OPENAI_API_KEY: 'secret-openai', GEMINI_API_KEY: '', XAI_API_KEY: 'secret-xai', ANTHROPIC_API_KEY: 'secret-anthropic', CLOUDFLARE_API_TOKEN: 'secret-cf', ACCOUNT_ID: '33333333333333333333333333333333',
       OLLAMA_BASE_URL: 'http://127.0.0.1:11434', OLLAMA_MODEL: 'qwen:test', OLLAMA_EMBED_MODEL: 'embed:test',
     },
     fetchImpl: async () => response({ models: [{ name: 'qwen:test' }, { name: 'embed:test' }] }),
@@ -30,12 +30,26 @@ test('model inventory reports configured API providers without exposing credenti
   assert.equal(status.providers.find((row) => row.id === 'gemini').configured, false);
   assert.equal(status.providers.find((row) => row.id === 'grok').configured, true);
   assert.equal(status.providers.find((row) => row.id === 'anthropic').configured, true);
+  assert.equal(status.providers.find((row) => row.id === 'cloudflare').configured, true);
   assert.equal(status.local.online, true);
   assert.deepEqual(status.local.models.map((row) => row.name), ['qwen:test', 'embed:test']);
   const rendered = renderModelsStatus(status);
   assert.match(rendered, /OpenAI/);
   assert.match(rendered, /qwen:test/);
-  assert.doesNotMatch(rendered, /secret-openai|secret-xai|secret-anthropic/);
+  assert.doesNotMatch(rendered, /secret-openai|secret-xai|secret-anthropic|secret-cf/);
+});
+
+test('static/reference metadata never invents hosted model availability', async () => {
+  const status = await collectModelsStatus({
+    env: { OPENAI_API_KEY: 'secret-openai', OLLAMA_BASE_URL: 'http://127.0.0.1:11434' },
+    fetchImpl: async () => response({ models: [] }),
+    providerFetchImpl: async () => response({ data: [{ id: 'some-other-model' }] }),
+  });
+
+  assert.deepEqual(status.availableModels.map((row) => row.provider_model_id), ['some-other-model']);
+  const referenceOnly = status.catalogModels.find((row) => row.provider_model_id === 'gpt-6-astra');
+  assert.equal(referenceOnly?.availability, 'unverified');
+  assert.equal(referenceOnly?.availability_source, 'sdk_reference');
 });
 
 test('exact hosted model availability is verified against the provider inventory', async () => {
@@ -46,6 +60,89 @@ test('exact hosted model availability is verified against the provider inventory
   });
   assert.equal(status.discovery.openai.ok, true);
   assert.equal(status.discovery.openai.returnedModelCount, 2);
-  assert.deepEqual(status.availableModels.map((row) => row.provider_model_id), ['gpt-6-astra']);
-  assert.equal(status.catalogModels[0].availability, 'available');
+  assert.deepEqual(status.availableModels.map((row) => row.provider_model_id), ['gpt-6-astra', 'some-other-model']);
+  assert.equal(status.availableModels[0].availability_source, 'provider_api');
+  assert.equal(status.availableModels[0].context_window_source, 'sdk_reference');
+});
+
+
+
+
+test('Gemini and xAI discovery keep per-key limits from provider metadata', async () => {
+  const seen = [];
+  const status = await collectModelsStatus({
+    env: {
+      GEMINI_API_KEY: 'gem-key',
+      XAI_API_KEY: 'xai-key',
+      OLLAMA_BASE_URL: 'http://127.0.0.1:11434',
+    },
+    fetchImpl: async () => response({ models: [] }),
+    providerFetchImpl: async (url, options) => {
+      seen.push(url);
+      if (url.includes('generativelanguage.googleapis.com')) {
+        return response({ models: [{
+          name: 'models/gemini-test',
+          baseModelId: 'gemini-test',
+          displayName: 'Gemini Test',
+          inputTokenLimit: 123456,
+          outputTokenLimit: 8192,
+          supportedGenerationMethods: ['generateContent'],
+          thinking: true,
+        }] });
+      }
+      if (url.includes('api.x.ai')) {
+        return response({ data: [{
+          id: 'grok-test',
+          context_length: 256000,
+          prompt_text_token_price: 1000,
+          cached_prompt_text_token_price: 500,
+          completion_text_token_price: 4000,
+        }] });
+      }
+      throw new Error('unexpected URL ' + url);
+    },
+  });
+
+  const gemini = status.providerModels.gemini[0];
+  assert.equal(gemini.provider_model_id, 'gemini-test');
+  assert.equal(gemini.context_window, 123456);
+  assert.equal(gemini.context_window_source, 'provider_api');
+  assert.deepEqual(gemini.reasoning_efforts, ['auto', 'low', 'medium', 'high']);
+
+  const grok = status.providerModels.grok[0];
+  assert.equal(grok.provider_model_id, 'grok-test');
+  assert.equal(grok.context_window, 256000);
+  assert.equal(grok.pricing.input, 1);
+  assert.equal(grok.pricing.output, 4);
+  assert.equal(seen.some((url) => url.includes('generativelanguage.googleapis.com')), true);
+  assert.equal(seen.some((url) => url.includes('api.x.ai')), true);
+});
+
+
+test('Cloudflare discovery is scoped to the loaded account and surfaces text-generation models only', async t => {
+  const seen = [];
+  const home = tempHome(t);
+  const status = await collectModelsStatus({
+    home,
+    env: { CLOUDFLARE_API_TOKEN: 'secret-cf', ACCOUNT_ID: '44444444444444444444444444444444', OLLAMA_BASE_URL: 'http://127.0.0.1:11434' },
+    fetchImpl: async () => response({ models: [] }),
+    providerFetchImpl: async (url, options) => {
+      seen.push({ url, auth: options.headers.authorization });
+      return response({ success: true, result: [
+        { name: '@cf/qwen/code', task: { name: 'Text Generation' }, description: 'coding' },
+        { name: '@cf/baai/embed', task: { name: 'Text Embeddings' }, description: 'embeddings' },
+      ] });
+    },
+  });
+  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');
+  const rendered = renderModelsStatus(status);
+  assert.match(rendered, /@cf\/qwen\/code/);
+  assert.doesNotMatch(rendered, /@cf\/baai\/embed/);
+  assert.doesNotMatch(rendered, /secret-cf/);
 });

package/test/ollama.test.mjs

@@ -8,6 +8,7 @@ import {
   ollamaInstallPlan,
   parseOllamaArgs,
   probeOllama,
+  probeOllamaModel,
   resolveOllamaConfig,
   updateProjectOllamaConfig,
   upsertOllamaEnvFile,
@@ -82,6 +83,26 @@ test('status probe recognizes configured chat and embedding models', async () =>
   assert.equal(status.embed_ready, true);
 });
 
+test('local model metadata is accepted only after Ollama itself verifies the model', async () => {
+  let seenBody = null;
+  const fakeFetch = async (url, init) => {
+    assert.match(url, /\/api\/show$/);
+    seenBody = JSON.parse(init.body);
+    return new Response(JSON.stringify({
+      model_info: { 'qwen2.context_length': 32768 },
+      capabilities: ['completion', 'tools'],
+      details: { family: 'qwen2' },
+    }), { status: 200, headers: { 'content-type': 'application/json' } });
+  };
+
+  const result = await probeOllamaModel('qwen2.5-coder', OLLAMA_DEFAULTS, fakeFetch);
+  assert.equal(seenBody.model, 'qwen2.5-coder');
+  assert.equal(result.ok, true);
+  assert.equal(result.context_window, 32768);
+  assert.equal(result.context_window_source, 'local_runtime');
+  assert.deepEqual(result.capabilities, ['completion', 'tools']);
+});
+
 test('automatic install plans use local package managers, never a remote shell script', () => {
   assert.deepEqual(ollamaInstallPlan('darwin', { brew: true }), {
     command: 'brew', args: ['install', 'ollama'], manager: 'homebrew',

package/test/portable-context.test.mjs

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import {
   normalizeGitRemote,
   resolveGitContext,
-} from '../src/lib/git-context.js';
+} from '../packages/agentsam-repository/src/git-context.js';
 import {
   buildBridgeHeaders,
   createBridgeClient,

package/test/provider-credentials.test.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
-import { describeProviderCredential, resolveProviderCredential } from '../src/lib/provider-credentials.js';
+import { describeProviderCredential, ensureProviderEnvProfile, resolveProviderCredential } from '../src/lib/provider-credentials.js';
 
 function fixtureHome(t) {
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-credentials-'));
@@ -50,3 +50,47 @@ test('AgentSam refuses provider credential files with broad POSIX permissions',
   assert.equal(resolved.error, 'permissions_too_open');
   assert.equal(resolved.value, '');
 });
+
+
+test('provider env profiles create a secure reusable source loader without embedding secrets', { skip: process.platform === 'win32' }, t => {
+  const home = fixtureHome(t);
+  const openai = ensureProviderEnvProfile('openai', { home });
+  assert.equal(openai.source_command, 'source ~/.agentsam/load-agent-env.sh openai');
+  assert.equal(fs.statSync(openai.file).mode & 0o777, 0o600);
+  assert.equal(fs.statSync(openai.loader).mode & 0o777, 0o700);
+  assert.match(fs.readFileSync(openai.file, 'utf8'), /OPENAI_API_KEY=""/);
+  assert.doesNotMatch(fs.readFileSync(openai.loader, 'utf8'), /sk-|secret-/);
+
+  const cloudflare = ensureProviderEnvProfile('cloudflare', { home });
+  const source = fs.readFileSync(cloudflare.file, 'utf8');
+  assert.match(source, /ACCOUNT_ID=""/);
+  assert.match(source, /CLOUDFLARE_API_TOKEN=""/);
+});
+
+test('Cloudflare credential status carries non-secret account identity from the provider profile', t => {
+  const home = fixtureHome(t);
+  const profile = path.join(home, '.agentsam', 'env.d', 'cloudflare.env');
+  fs.writeFileSync(profile, 'export ACCOUNT_ID="0123456789abcdef0123456789abcdef"\nexport CLOUDFLARE_API_TOKEN="token-secret"\n', { mode: 0o600 });
+  if (process.platform !== 'win32') fs.chmodSync(profile, 0o600);
+  const resolved = resolveProviderCredential('cloudflare', { env: {}, home });
+  assert.equal(resolved.account_id, '0123456789abcdef0123456789abcdef');
+  const safe = describeProviderCredential('cloudflare', { env: {}, home });
+  assert.equal(safe.account_id, '0123456789abcdef0123456789abcdef');
+  assert.doesNotMatch(JSON.stringify(safe), /token-secret/);
+});
+
+
+test('Cloudflare profile account backfill never overwrites an existing token or account choice', t => {
+  const home = fixtureHome(t);
+  const profile = path.join(home, '.agentsam', 'env.d', 'cloudflare.env');
+  fs.writeFileSync(profile, 'export ACCOUNT_ID=""\nexport CLOUDFLARE_API_TOKEN="keep-me"\n', { mode: 0o600 });
+  ensureProviderEnvProfile('cloudflare', { home, accountId: '11111111111111111111111111111111' });
+  let source = fs.readFileSync(profile, 'utf8');
+  assert.match(source, /ACCOUNT_ID="11111111111111111111111111111111"/);
+  assert.match(source, /CLOUDFLARE_API_TOKEN="keep-me"/);
+
+  ensureProviderEnvProfile('cloudflare', { home, accountId: '22222222222222222222222222222222' });
+  source = fs.readFileSync(profile, 'utf8');
+  assert.match(source, /ACCOUNT_ID="11111111111111111111111111111111"/);
+  assert.doesNotMatch(source, /22222222222222222222222222222222/);
+});

package/test/release-hygiene.test.mjs

@@ -6,15 +6,23 @@ import test from 'node:test';
 const root = path.resolve(import.meta.dirname, '..');
 const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
 
-test('2.6 release metadata and public terminal vocabulary are aligned', () => {
+test('release candidate metadata and public terminal vocabulary are aligned', () => {
   const pkg = JSON.parse(read('package.json'));
   const manifest = read('agentsam.yaml');
   const readme = read('README.md');
+  const escapedVersion = pkg.version.replaceAll('.', '\\.');
 
-  assert.equal(pkg.version, '2.6.0');
-  assert.match(manifest, /target_version: "2.6.0"/);
-  assert.match(manifest, /state: release_candidate/);
-  assert.match(manifest, /current_latest: "2.5.0"/);
+  assert.match(
+    manifest,
+    new RegExp(`packages:[\\s\\S]*?root_sdk:[\\s\\S]*?version: "${escapedVersion}"`),
+  );
+  assert.match(
+    manifest,
+    new RegExp(`release:[\\s\\S]*?root_sdk:[\\s\\S]*?target_version: "${escapedVersion}"`),
+  );
+  assert.match(manifest, /state: (candidate|published)/);
+  assert.match(manifest, /current_latest: "\d+\.\d+\.\d+"/);
+  assert.match(manifest, /verification_command: npm run verify:release/);
   assert.doesNotMatch(manifest, /^\s*- tui\s*$/m);
   assert.doesNotMatch(readme, /agentsam tui|CLI\/TUI/);
 });

package/test/responses-runner.test.mjs

@@ -13,7 +13,7 @@ function usage(input = 10_000, cumulative = input) {
     estimate_kind: 'provider', provider_authoritative: true,
   };
 }
-function cost(total = 0.1) { return { total_usd: total }; }
+function cost(total = 0.1) { return { total_usd: total, components_usd: { input: total * 0.5, cached_input: total * 0.1, cache_write: total * 0.1, output: total * 0.3 } }; }
 
 test('capability adapter hydrates packaged JSON schemas and tool surface exposes only selected executable schemas', () => {
   const adapter = createCapabilityAdapter();
@@ -73,6 +73,8 @@ test('runner owns cwd, executes selected tool, preserves call_id and returns pro
   assert.equal(result.output_text, 'done');
   assert.equal(result.response_id, 'resp_2');
   assert.equal(result.total_cost_usd, 0.5);
+  assert.equal(result.cost_breakdown_usd.input, 0.25);
+  assert.equal(result.cost_breakdown_usd.output, 0.15);
   assert.equal(result.continuation.compact_before_next_turn, false);
   assert.ok(events.some(event => event.type === 'tool.search'));
   assert.ok(events.some(event => event.type === 'tool.completed'));

package/test/shell.test.mjs

@@ -22,12 +22,15 @@ test('interactive prompt derives username and cwd instead of hardcoding Agent Sa
   assert.equal(renderShellPrompt('/tmp/demo', env), 'alice /tmp/demo > ');
 });
 
-test('shell catalog only advertises implemented core controls', () => {
+test('shell startup stays quiet and points to the picker', () => {
   const catalog = renderShellCatalog();
-  for (const command of ['/model', '/reasoning', '/fast', '/flex', '/standard', '/context', '/cf', '/diff', '/clear', '/exit']) {
+  for (const command of ['/model', '/usage', '/help', '/exit']) {
     assert.match(catalog, new RegExp(command.replace('/', '\\/')));
   }
-  assert.match(catalog, /scrollable command picker/);
+  assert.match(catalog, /command picker/);
+  assert.match(catalog, /Type normally to work with the selected model/);
+  assert.doesNotMatch(catalog, /Slash commands \(/);
+  assert.doesNotMatch(catalog, /\/reasoning\s+Set reasoning/);
 });
 
 test('dispatch handles help, menu fallback, pwd, cd, and exit without falling through to host shell', async () => {
@@ -38,10 +41,11 @@ 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, /Slash commands/);
+  assert.match(output, /Type normally to work with Agent Sam/);
+  assert.match(output, /agentsam help <topic>/);
   output = '';
   await dispatchShellLine('/', state);
-  assert.match(output, /Agent Sam Terminal/);
+  assert.match(output, /command picker/);
   output = '';
   await dispatchShellLine('/pwd', state);
   assert.equal(output.trim(), root);
@@ -53,6 +57,44 @@ test('dispatch handles help, menu fallback, pwd, cd, and exit without falling th
   assert.equal(result.exit, true);
 });
 
+test('/usage renders the current session receipt without ending the session', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-shell-usage-'));
+  let output = '';
+  const state = {
+    cwd: root, interactive: false, write: (text) => { output += text; },
+    session: {
+      id: 'asess_00000000-0000-4000-8000-000000000001', title: 'Usage test', model_key: 'openai:gpt-6-astra',
+      cumulative_usage: { input_tokens: 21_244, cached_input_tokens: 60_544, output_tokens: 219 },
+      total_cost_usd: 0.42, cost_breakdown_usd: { input: 0.2, cached_input: 0.02, output: 0.2 },
+    },
+  };
+  const result = await dispatchShellLine('/usage', state);
+  assert.equal(result.exit, false);
+  assert.match(output, /Token usage: total=21,463 input=21,244 \(\+ 60,544 cached\) output=219/);
+  assert.match(output, /Spent: \$0\.4200/);
+  assert.match(output, /agentsam resume asess_00000000-0000-4000-8000-000000000001/);
+});
+
+test('/logout signs out locally and emits the same resumable usage receipt', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-shell-logout-'));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-shell-home-'));
+  let output = '';
+  const state = {
+    cwd: root, home, interactive: false, write: (text) => { output += text; },
+    session: {
+      id: 'asess_00000000-0000-4000-8000-000000000002', title: 'Logout test', model_key: 'openai:gpt-6-astra',
+      cumulative_usage: { input_tokens: 100, cached_input_tokens: 50, output_tokens: 25 },
+      total_cost_usd: 0.0125, cost_breakdown_usd: { input: 0.005, cached_input: 0.0025, output: 0.005 },
+    },
+  };
+  const result = await dispatchShellLine('/logout', state);
+  assert.equal(result.exit, false);
+  assert.match(output, /No local Agent Sam IAM session was stored/);
+  assert.match(output, /Token usage: total=125 input=100 \(\+ 50 cached\) output=25/);
+  assert.match(output, /Spent: \$0\.0125/);
+  assert.match(output, /agentsam resume asess_00000000-0000-4000-8000-000000000002/);
+});
+
 test('reasoning and service-tier commands persist only supported controls for an exact model', async () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-shell-model-'));
   fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'model-demo' }));
@@ -88,7 +130,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, /Agent Sam Terminal/);
-  assert.match(result.stdout, /\/model/);
-  assert.match(result.stdout, /\/exit/);
+  assert.match(result.stdout, /Type normally to work with Agent Sam/);
+  assert.match(result.stdout, /agentsam help <topic>/);
+  assert.match(result.stdout, /command picker/);
 });