@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/ui/cli/help.js

@@ -0,0 +1,192 @@
+import pc from 'picocolors';
+import { isCancel, select } from '@clack/prompts';
+import pkg from '../../../package.json' with { type: 'json' };
+
+const HELP_TOPICS = Object.freeze([
+  {
+    id: 'start',
+    label: 'Start / resume',
+    summary: 'Enter Agent Sam, resume work, inspect identity, and choose a model.',
+    rows: [
+      ['agentsam', 'Enter the interactive Agent Sam experience'],
+      ['agentsam resume [session]', 'Resume a saved Agent Sam session'],
+      ['agentsam whoami', 'Show authenticated account and credential status'],
+      ['agentsam models', 'Probe account-visible hosted/local models'],
+      ['agentsam env init <provider>', 'Create a secure local provider profile'],
+    ],
+  },
+  {
+    id: 'work',
+    label: 'Build / inspect',
+    summary: 'Repository intelligence and normal project work.',
+    rows: [
+      ['agentsam inspect', 'Bounded repository index / authority view'],
+      ['agentsam index', 'Incremental AST and optional embeddings'],
+      ['agentsam search "query"', 'Search indexed code/text'],
+      ['agentsam repo snapshot', 'Git composition/churn snapshot'],
+      ['agentsam security', 'Dependency and trust-boundary scan'],
+      ['agentsam merkle', 'Integrity snapshots and comparisons'],
+    ],
+  },
+  {
+    id: 'runtime',
+    label: 'Runtime / terminal',
+    summary: 'Local, remote, sandbox, and deployment controls.',
+    rows: [
+      ['agentsam status', 'Project, Git, DB, API, and PTY status'],
+      ['agentsam start-local', 'Start the local PTY service'],
+      ['agentsam connections', 'Inspect available execution connections'],
+      ['agentsam tunnel', 'Expose local PTY only when remote access is wanted'],
+      ['agentsam deploy', 'Graduate intentionally to cloud infrastructure'],
+      ['agentsam cloudflare', 'Wrangler and Cloudflare runtime diagnostics'],
+    ],
+  },
+  {
+    id: 'inside',
+    label: 'Inside Agent Sam',
+    summary: 'Commands available while the interactive session is running.',
+    rows: [
+      ['/', 'Open the keyboard command picker'],
+      ['/model', 'Choose model, reasoning, and processing tier'],
+      ['/context', 'Show live context economics'],
+      ['/usage', 'Show token/cost/session receipt'],
+      ['/settings', 'Change runtime, terminal, and model policy'],
+      ['/status', 'Show project/runtime health'],
+      ['/help [topic]', 'Show in-session help'],
+      ['/exit', 'Return to the host shell'],
+    ],
+  },
+  {
+    id: 'create',
+    label: 'Create / extend',
+    summary: 'Scaffold and add reusable capabilities.',
+    rows: [
+      ['agentsam create <name> --preset <preset>', 'Create a new AgentSam project'],
+      ['agentsam add <capability>', 'Add a supported capability'],
+      ['agentsam capabilities [id]', 'Inspect capability contracts'],
+      ['agentsam skills [id]', 'Inspect packaged skills'],
+      ['agentsam identity init', 'Add reusable identity surfaces'],
+      ['agentsam dockerize', 'Build supported container targets'],
+    ],
+  },
+]);
+
+const TOPIC_ALIASES = new Map([
+  ['models', 'start'], ['model', 'start'], ['provider', 'start'], ['providers', 'start'], ['resume', 'start'],
+  ['repo', 'work'], ['repository', 'work'], ['inspect', 'work'], ['index', 'work'], ['security', 'work'],
+  ['terminal', 'runtime'], ['connections', 'runtime'], ['remote', 'runtime'], ['sandbox', 'runtime'], ['deploy', 'runtime'],
+  ['slash', 'inside'], ['commands', 'inside'], ['session', 'inside'], ['usage', 'inside'], ['context', 'inside'],
+  ['create', 'create'], ['scaffold', 'create'], ['capabilities', 'create'], ['skills', 'create'],
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim().toLowerCase();
+}
+
+function padRows(rows) {
+  const width = Math.min(42, Math.max(...rows.map(([command]) => command.length), 0));
+  return rows.map(([command, description]) => '    ' + pc.cyan(command.padEnd(width)) + '  ' + pc.dim(description));
+}
+
+export function resolveHelpTopic(value) {
+  const query = clean(value);
+  if (!query) return null;
+  const direct = HELP_TOPICS.find((topic) => topic.id === query || clean(topic.label) === query);
+  if (direct) return direct;
+  const alias = TOPIC_ALIASES.get(query);
+  if (alias) return HELP_TOPICS.find((topic) => topic.id === alias) || null;
+  return HELP_TOPICS.find((topic) =>
+    topic.rows.some(([command, description]) => clean(command).includes(query) || clean(description).includes(query))) || null;
+}
+
+export function renderHelpOverview(version, options = {}) {
+  const lines = [
+    '',
+    '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version),
+    '  ' + pc.dim('Type normally to work with Agent Sam. Use help only when you need the map.'),
+    '',
+    '  ' + pc.bold('Start'),
+    '    ' + pc.cyan('agentsam') + '                         ' + pc.dim('enter the interactive experience'),
+    '    ' + pc.cyan('agentsam resume') + '                  ' + pc.dim('continue saved work'),
+    '    ' + pc.cyan('agentsam help <topic>') + '            ' + pc.dim('focused help'),
+    '',
+    '  ' + pc.bold('Common'),
+    '    ' + pc.cyan('agentsam inspect') + '                 ' + pc.dim('understand this repository'),
+    '    ' + pc.cyan('agentsam models') + '                  ' + pc.dim('see account-visible models'),
+    '    ' + pc.cyan('agentsam status') + '                  ' + pc.dim('check project/runtime health'),
+    '    ' + pc.cyan('agentsam security') + '                ' + pc.dim('scan dependency + trust boundaries'),
+    '    ' + pc.cyan('agentsam deploy') + '                  ' + pc.dim('graduate intentionally'),
+    '',
+    '  ' + pc.dim('Inside Agent Sam: press / for the command picker. Ask the selected model for natural-language help at any time.'),
+  ];
+  if (options.showTopics !== false) {
+    lines.push('', '  ' + pc.dim('Topics: ' + HELP_TOPICS.map((topic) => topic.id).join(' · ') + ' · all'));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function renderHelpTopic(topic, version) {
+  if (!topic) return renderHelpOverview(version);
+  return [
+    '',
+    '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version) + ' ' + pc.dim('·') + ' ' + pc.bold(topic.label),
+    '  ' + pc.dim(topic.summary),
+    '',
+    ...padRows(topic.rows),
+    '',
+    '  ' + pc.dim('Tip: run agentsam help for the map, or agentsam to return to the interactive experience.'),
+    '',
+  ].join('\n');
+}
+
+export function renderAllHelp(version) {
+  const lines = [renderHelpOverview(version, { showTopics: false })];
+  for (const topic of HELP_TOPICS) lines.push(renderHelpTopic(topic, version));
+  return lines.join('');
+}
+
+export async function runHelp(argv = [], options = {}) {
+  const version = String(options.version || pkg.version || 'unknown');
+  const write = options.write || ((value) => process.stdout.write(value));
+  const args = argv.filter((arg) => arg !== '--interactive');
+
+  if (args.includes('--all')) {
+    write(renderAllHelp(version));
+    return;
+  }
+
+  const topicArg = args.find((arg) => !arg.startsWith('-'));
+  if (topicArg) {
+    const topic = resolveHelpTopic(topicArg);
+    if (!topic) {
+      write(renderHelpOverview(version));
+      write('  ' + pc.yellow('No exact help topic matched') + ' ' + topicArg + '\n\n');
+      return;
+    }
+    write(renderHelpTopic(topic, version));
+    return;
+  }
+
+  const interactive = options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!interactive) {
+    write(renderHelpOverview(version));
+    return;
+  }
+
+  const choice = await select({
+    message: 'Agent Sam help',
+    options: [
+      ...HELP_TOPICS.map((topic) => ({ value: topic.id, label: topic.label, hint: topic.summary })),
+      { value: 'all', label: 'All commands', hint: 'Print the complete deterministic help map' },
+      { value: 'exit', label: 'Back', hint: 'Return without printing more help' },
+    ],
+  });
+  if (isCancel(choice) || choice === 'exit') return;
+  if (choice === 'all') write(renderAllHelp(version));
+  else write(renderHelpTopic(resolveHelpTopic(choice), version));
+}
+
+export function listHelpTopics() {
+  return HELP_TOPICS.map((topic) => ({ id: topic.id, label: topic.label, summary: topic.summary }));
+}

package/src/ui/cli/plan.js

@@ -0,0 +1,20 @@
+import pc from 'picocolors';
+
+export function renderPlanUpdate(payload = {}) {
+  const items = Array.isArray(payload.items) ? payload.items : Array.isArray(payload.todos) ? payload.todos : [];
+  if (!items.length) return '';
+  const lines = ['', '  ' + pc.bold(payload.title || 'Plan')];
+  for (const item of items.slice(0, 20)) {
+    const status = String(item.status || 'open');
+    const icon = status === 'complete' || status === 'completed' || status === 'done'
+      ? pc.green('✓')
+      : status === 'running' || status === 'active'
+        ? pc.cyan('●')
+        : status === 'blocked'
+          ? pc.yellow('◆')
+          : pc.dim('○');
+    lines.push(`    ${icon} ${item.title || item.label || item.id || 'task'}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/ui/cli/runtime-events.js

@@ -0,0 +1,110 @@
+import { renderPlanUpdate } from './plan.js';
+import { renderWaitingInput } from './waiting.js';
+import { renderCompactionReceipt } from './compaction.js';
+
+export const RUNTIME_EVENT_ENVELOPE_SCHEMA = 'agentsam-runtime-event-v1';
+
+/**
+ * Transport-neutral event contract shared by standalone and future platform-connected runs.
+ * A platform SSE/WebSocket producer only needs to emit this normalized envelope; the SDK does
+ * not hardcode or invent the platform endpoint that will carry it.
+ */
+export function normalizeRuntimeEventEnvelope(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('runtime event envelope must be an object');
+  }
+  const type = String(value.type || '').trim();
+  if (!type) throw new TypeError('runtime event envelope type is required');
+  const sequence = Number(value.sequence);
+  const envelope = {
+    schema: RUNTIME_EVENT_ENVELOPE_SCHEMA,
+    schema_version: Number.isInteger(Number(value.schema_version)) ? Number(value.schema_version) : 1,
+    type,
+    timestamp: String(value.timestamp || new Date().toISOString()),
+    ...(value.run_id ? { run_id: String(value.run_id) } : {}),
+    ...(Number.isInteger(sequence) && sequence >= 0 ? { sequence } : {}),
+    payload: value.payload && typeof value.payload === 'object' && !Array.isArray(value.payload)
+      ? value.payload
+      : value.payload == null ? {} : { value: value.payload },
+  };
+  return Object.freeze(envelope);
+}
+
+function line(write, text) {
+  if (text) write(text.endsWith('\n') ? text : text + '\n');
+}
+
+export function createCliRuntimePresenter(options = {}) {
+  const activity = options.activity;
+  const write = options.write || process.stdout.write.bind(process.stdout);
+  const state = options.state || {};
+
+  function handle(event = {}) {
+    const envelope = normalizeRuntimeEventEnvelope(event);
+    const { type, payload } = envelope;
+
+    if (type === 'usage.snapshot') {
+      state.usageSnapshot = payload;
+      return;
+    }
+    if (type === 'cost.snapshot') {
+      state.costSnapshot = payload;
+      return;
+    }
+    if (type === 'model.started') {
+      activity?.update(`Thinking · ${payload.model || payload.provider || 'model'}`);
+      return;
+    }
+    if (type === 'tool.search') {
+      activity?.update('Finding relevant tools');
+      return;
+    }
+    if (type === 'tool.started') {
+      activity?.update(`Using ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'tool.completed') {
+      activity?.update(`Tool complete · ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'tool.failed') {
+      activity?.update(`Tool failed · ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'context.compaction.started') {
+      state.compactionStartedAt = Date.now();
+      activity?.update('Compacting context');
+      return;
+    }
+    if (type === 'context.compaction.completed') {
+      const enriched = {
+        ...payload,
+        duration_ms: payload.duration_ms ?? (state.compactionStartedAt ? Date.now() - state.compactionStartedAt : undefined),
+      };
+      state.lastCompaction = enriched;
+      activity?.update('Context ready');
+      return;
+    }
+    if (type === 'plan.updated') {
+      activity?.clear();
+      line(write, renderPlanUpdate(payload));
+      activity?.start('Working');
+      return;
+    }
+    if (type === 'runtime.waiting_input') {
+      activity?.clear();
+      line(write, renderWaitingInput(payload));
+      return;
+    }
+    if (type === 'run.failed' || type === 'error.observed') {
+      activity?.update('Handling error');
+    }
+  }
+
+  function compactionReceipt() {
+    if (!state.lastCompaction) return '';
+    return renderCompactionReceipt(state.lastCompaction);
+  }
+
+  return Object.freeze({ handle, compactionReceipt, state });
+}

package/src/ui/cli/waiting.js

@@ -0,0 +1,16 @@
+import pc from 'picocolors';
+
+export function renderWaitingInput(payload = {}) {
+  const reason = String(payload.reason || payload.awaiting_input_reason || 'input required');
+  const url = String(payload.url || payload.auth_url || '').trim();
+  const code = String(payload.code || payload.user_code || '').trim();
+  const lines = [
+    '',
+    `  ${pc.yellow('◇')} ${pc.bold('Waiting for you')} ${pc.dim('· ' + reason)}`,
+  ];
+  if (url) lines.push(`    Open  ${pc.cyan(url)}`);
+  if (code) lines.push(`    Code  ${pc.bold(code)}`);
+  lines.push(`    ${pc.dim(payload.message || 'Complete the requested step; Agent Sam will continue when the runtime is ready.')}`);
+  lines.push('');
+  return lines.join('\n');
+}

package/src/ui/merkle/render.js

@@ -1,4 +1,4 @@
-import { comparePaths } from '../../lib/merkle/hash.js';
+import { comparePaths } from '../../../packages/agentsam-repository/src/merkle/hash.js';
 
 export const safeText = (value) => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g,
   (char) => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));

package/test/account-session.test.mjs

@@ -0,0 +1,36 @@
+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 { accountSessionPath, clearAccountSession, readAccountSession, resolveAccountSdkKey, saveAccountSession } from '../src/lib/account-session.js';
+
+function tempHome(t) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-account-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+}
+
+test('browser-auth SDK bearer persists in machine-local storage, not project state', t => {
+  const home = tempHome(t);
+  const saved = saveAccountSession({ access_token: 'sdk_machine_session', user_id: 'au_test', account_id: 'acct_test', email: 'dev@example.test' }, { home });
+  assert.equal(saved.user_id, 'au_test');
+  const filename = accountSessionPath({ home });
+  assert.equal(fs.existsSync(filename), true);
+  if (process.platform !== 'win32') assert.equal(fs.statSync(filename).mode & 0o077, 0);
+
+  const loaded = readAccountSession({ home });
+  assert.equal(loaded.sdk_key, 'sdk_machine_session');
+  const resolved = resolveAccountSdkKey({ env: {}, home });
+  assert.equal(resolved.source, 'agentsam_account_session');
+  assert.equal(resolved.value, 'sdk_machine_session');
+  assert.equal(clearAccountSession({ home }), true);
+  assert.equal(readAccountSession({ home }), null);
+});
+
+test('explicit/environment SDK bearer remains higher authority than local session fallback', t => {
+  const home = tempHome(t);
+  saveAccountSession({ access_token: 'sdk_disk' }, { home });
+  assert.equal(resolveAccountSdkKey({ env: { AGENTSAM_SDK_KEY: 'sdk_env' }, home }).value, 'sdk_env');
+  assert.equal(resolveAccountSdkKey({ env: { AGENTSAM_SDK_KEY: 'sdk_env' }, explicit: 'sdk_explicit', home }).value, 'sdk_explicit');
+});

package/test/cli/preferences-runtime.test.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { runtimeOptions } from '../../src/commands/preferences.js';
+
+test('standalone users only see local execution', () => {
+  assert.deepEqual(runtimeOptions({ accountConnected: false }).map((row) => row.value), ['local']);
+});
+
+test('IAM-connected users can choose enrolled remote and sandbox lanes', () => {
+  assert.deepEqual(runtimeOptions({ accountConnected: true }).map((row) => row.value), ['local', 'remote', 'sandbox']);
+});

package/test/cli/runtime-ui.test.mjs

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createInlineActivity } from '../../src/ui/cli/activity.js';
+import { renderCliFooter } from '../../src/ui/cli/footer.js';
+import { createCliRuntimePresenter, normalizeRuntimeEventEnvelope, RUNTIME_EVENT_ENVELOPE_SCHEMA } from '../../src/ui/cli/runtime-events.js';
+import { renderWaitingInput } from '../../src/ui/cli/waiting.js';
+
+test('CLI footer reports unknown context honestly', () => {
+  const text = renderCliFooter({
+    model: 'claude-test',
+    usageSnapshot: {
+      current_context: { input_tokens: 1234, window_tokens: 0 },
+      cumulative: { input_tokens: 5000, output_tokens: 600, cached_input_tokens: 2000 },
+    },
+  });
+  assert.match(text, /claude-test/);
+  assert.match(text, /ctx 1\.2k \/ unknown/);
+  assert.match(text, /↑5k ↓600/);
+  assert.match(text, /cache 2k/);
+});
+
+test('runtime event envelope is the single standalone/platform producer contract', () => {
+  const envelope = normalizeRuntimeEventEnvelope({
+    schema_version: 1,
+    type: 'tool.started',
+    timestamp: '2026-09-18T00:00:00.000Z',
+    run_id: 'run_1',
+    sequence: 3,
+    payload: { capability_id: 'repo.inspect' },
+  });
+  assert.equal(envelope.schema, RUNTIME_EVENT_ENVELOPE_SCHEMA);
+  assert.equal(envelope.schema_version, 1);
+  assert.equal(envelope.type, 'tool.started');
+  assert.equal(envelope.run_id, 'run_1');
+  assert.equal(envelope.sequence, 3);
+  assert.deepEqual(envelope.payload, { capability_id: 'repo.inspect' });
+  assert.throws(() => normalizeRuntimeEventEnvelope({ payload: {} }), /type is required/);
+});
+
+test('runtime presenter turns events into one-line activity and waiting handoff', () => {
+  let output = '';
+  let now = 1_000;
+  const timers = [];
+  const activity = createInlineActivity({
+    write: (value) => { output += value; },
+    interactive: false,
+    now: () => now,
+    setInterval: (fn) => { timers.push(fn); return timers.length; },
+    clearInterval() {},
+  });
+  const state = {};
+  const presenter = createCliRuntimePresenter({ activity, write: (value) => { output += value; }, state });
+  activity.start('Thinking');
+  presenter.handle({ type: 'tool.started', payload: { capability_id: 'repo.inspect' } });
+  presenter.handle({ type: 'usage.snapshot', payload: { current_context: { input_tokens: 10, window_tokens: 100 }, cumulative: {} } });
+  presenter.handle({ type: 'context.compaction.started', payload: { provider: 'test' } });
+  now += 500;
+  presenter.handle({ type: 'context.compaction.completed', payload: { provider: 'test', tokens_before: 80, tokens_after: 20, summary_text: 'kept state' } });
+  presenter.handle({ type: 'runtime.waiting_input', payload: { reason: 'authentication', auth_url: 'https://example.test/auth', user_code: 'ABCD' } });
+  assert.equal(state.usageSnapshot.current_context.input_tokens, 10);
+  assert.equal(state.lastCompaction.tokens_before, 80);
+  assert.match(output, /Waiting for you/);
+  assert.match(output, /https:\/\/example\.test\/auth/);
+  assert.match(output, /ABCD/);
+  assert.match(presenter.compactionReceipt(), /80 → 20/);
+});
+
+test('waiting renderer gives CLI-native auth instructions', () => {
+  const text = renderWaitingInput({ awaiting_input_reason: 'otp', auth_url: 'https://example.test/login', user_code: '123456' });
+  assert.match(text, /Waiting for you/);
+  assert.match(text, /otp/);
+  assert.match(text, /Open/);
+  assert.match(text, /123456/);
+});

package/test/cli-preferences.test.mjs

@@ -6,20 +6,41 @@ import test from 'node:test';
 import { CLI_PREFERENCES_SCHEMA, detectCliProject, readCliPreferences, writeCliPreferences } from '../src/lib/cli-preferences.js';
 import { renderBootSummary } from '../src/ui/boot.js';
 
-test('CLI preferences are project-local and explicitly non-authoritative for routing', () => {
+test('CLI preferences persist local model/runtime controls without becoming routing authority', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-cli-prefs-'));
   fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'demo-project' }));
-  const written = writeCliPreferences(root, { runtime: 'sandbox', terminal: 'zsh', modelPreference: 'ollama:qwen2.5-coder' });
+  const written = writeCliPreferences(root, {
+    trustedDirectory: true,
+    runtime: 'sandbox',
+    terminal: 'zsh',
+    modelPreference: 'openai:gpt-6-astra',
+    reasoningEffort: 'high',
+    serviceTier: 'fast',
+  });
   assert.equal(written.schemaVersion, CLI_PREFERENCES_SCHEMA);
   assert.equal(written.modelAuthority, 'preference-only');
+  assert.equal(written.trustedDirectory, true);
   assert.deepEqual(readCliPreferences(root), written);
-
   const identity = detectCliProject(root);
   assert.equal(identity.project, 'demo-project');
   assert.equal(identity.root, root);
-
   const summary = renderBootSummary({ identity, preferences: written });
   assert.match(summary, /Agent Sam/);
   assert.match(summary, /demo-project/);
-  assert.match(summary, /qwen2\.5-coder/);
+  assert.match(summary, /openai:gpt-6-astra/);
+  assert.match(summary, /high/);
+  assert.match(summary, /fast/);
+});
+
+test('legacy v1 local preferences migrate in memory without inventing trust', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-cli-legacy-'));
+  fs.mkdirSync(path.join(root, '.agentsam'));
+  fs.writeFileSync(path.join(root, '.agentsam', 'cli.json'), JSON.stringify({
+    schemaVersion: 'agentsam-cli-preferences-v1', runtime: 'local', terminal: 'zsh', modelPreference: 'auto', modelAuthority: 'preference-only',
+  }));
+  const read = readCliPreferences(root);
+  assert.equal(read.schemaVersion, CLI_PREFERENCES_SCHEMA);
+  assert.equal(read.trustedDirectory, false);
+  assert.equal(read.reasoningEffort, 'auto');
+  assert.equal(read.serviceTier, 'default');
 });

package/test/cloudflare-connector.test.mjs

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { handleCloudflareConnectionRequest } from '../packages/connectors/cloudflare/src/routes.js';
+import { rejectUntrustedOwnerHints } from '../packages/connectors/cloudflare/src/owner.js';
+
+function req(url, { method = 'GET', headers = {}, body } = {}) {
+  return new Request(url, { method, headers, body });
+}
+
+describe('cloudflare connector routes', () => {
+  it('rejects unauthenticated status', async () => {
+    const res = await handleCloudflareConnectionRequest(
+      req('https://agentsam.inneranimalmedia.com/api/connections/cloudflare'),
+      {},
+    );
+    assert.equal(res.status, 401);
+    const json = await res.json();
+    assert.equal(json.error, 'unauthenticated');
+  });
+
+  it('rejects browser-submitted owner hints', () => {
+    const url = new URL('https://agentsam.inneranimalmedia.com/api/connections/cloudflare?account_id=evil');
+    assert.throws(
+      () => rejectUntrustedOwnerHints(req(url.toString()), url, {}),
+      /untrusted_owner_hint/,
+    );
+  });
+
+  it('returns 503 on start when only fixture credentials exist', async () => {
+    const env = {
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+      sessions: new Map([['sess_1', 'user-sam']]),
+    };
+    const res = await handleCloudflareConnectionRequest(
+      req('https://agentsam.inneranimalmedia.com/api/connections/cloudflare/start', {
+        headers: { cookie: 'agentsam_session=sess_1' },
+      }),
+      env,
+    );
+    assert.equal(res.status, 503);
+    const json = await res.json();
+    assert.equal(json.error, 'not_configured');
+    assert.equal(json.fixture, true);
+  });
+
+  it('status stays safe and does not treat fixture as production configured', async () => {
+    const env = {
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+      sessions: new Map([['sess_1', 'user-sam']]),
+    };
+    const res = await handleCloudflareConnectionRequest(
+      req('https://agentsam.inneranimalmedia.com/api/connections/cloudflare', {
+        headers: { authorization: 'Bearer sess_1' },
+      }),
+      env,
+    );
+    assert.equal(res.status, 200);
+    const json = await res.json();
+    assert.equal(json.ok, true);
+    assert.equal(json.configured, false);
+    assert.equal(json.fixture, true);
+    assert.equal(JSON.stringify(json).includes('sillynotreal-secret'), false);
+  });
+
+  it('rejects owner_id in the JSON body', async () => {
+    const env = { sessions: new Map([['sess_1', 'user-sam']]) };
+    const res = await handleCloudflareConnectionRequest(
+      req('https://agentsam.inneranimalmedia.com/api/connections/cloudflare/disconnect', {
+        method: 'POST',
+        headers: { cookie: 'agentsam_session=sess_1', 'content-type': 'application/json' },
+        body: JSON.stringify({ owner_id: 'evil' }),
+      }),
+      env,
+    );
+    assert.equal(res.status, 400);
+    const json = await res.json();
+    assert.equal(json.error, 'untrusted_owner_hint');
+  });
+
+  it('rejects callback without a stored oauth state', async () => {
+    const env = {
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'real-client-secret-value',
+      oauthState: new Map(),
+    };
+    const res = await handleCloudflareConnectionRequest(
+      req('https://agentsam.inneranimalmedia.com/api/connections/cloudflare/callback?code=abc&state=missing'),
+      env,
+    );
+    assert.equal(res.status, 403);
+    const json = await res.json();
+    assert.equal(json.error, 'cloudflare_connection_forbidden');
+  });
+});