carthagent 0.0.0-stage → 1.0.7

package/skills/typescript-delivery/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: typescript-delivery
+description: TypeScript and JavaScript implementation guidance for phased delivery. Use for Node.js, browser, and full-stack TS/JS tasks. Covers module systems, testing frameworks, DOM/BOM, npm/ecosystem patterns, and common pitfalls.
+---
+# TypeScript & JavaScript delivery
+
+Read this before implementing any task that targets Node.js, a browser, or a TS/JS runtime. These are the patterns that separate a working delivery from a plausible-looking one.
+
+## Before you write
+
+1. **Check what already exists.** Read `package.json`, `tsconfig.json`, `node_modules/` (if present), and the existing test setup. Match the project's module system (`"type": "module"` vs CommonJS), TypeScript strictness, and test framework — don't introduce a second framework or a different module system.
+2. **Check the Node version.** `node --version` determines which APIs are available (e.g. `structuredClone` needs Node 17+, `fetch` is global in Node 18+). Use `node:test` (built-in, no install) unless the project already uses a different test framework.
+3. **Verify the entry point.** For a Node project, confirm the `main`/`exports`/`bin` fields in `package.json`. For a browser project, confirm the `<script>` tag or bundler entry point exists.
+
+## Module system
+
+- **`"type": "module"`** → use `import`/`export`, `.mjs`/`.js` extensions are equivalent, `require` is unavailable. Use `import.meta.url` for `__dirname` equivalent.
+- **CommonJS (default)** → use `require`/`module.exports`, `.cjs`/`.js` extensions. Don't mix `import` and `require` in the same file.
+- **Dual packages** → if `package.json` has both `main` and `module`, the bundler decides. Don't assume both work identically.
+- **Dynamic `import()`** works in both systems; `require` doesn't work in ESM. For conditional loading, use `await import()`.
+
+## TypeScript specifics
+
+- **`tsc --noEmit`** is the minimum type check. If `tsconfig.json` exists, run it before declaring done.
+- **`strict: true`** means `null`/`undefined` are explicit, `any` is banned by convention, and `unknown` is the safe catch-all. Use `unknown` over `any` for untyped data.
+- **Declaration files** (`.d.ts`) are for types only — no runtime code. `declare module 'x'` declares a type for an untyped package; it doesn't create the module.
+- **`tsconfig.json` `target`/`module`** controls downleveling. `module: "NodeNext"` matches Node's ESM; `module: "CommonJS"` matches CJS. Mismatch causes runtime `require`/`import` errors.
+- **`skipLibCheck: true`** is common but hides type errors in `.d.ts` files — check for actual type errors, not just missing declarations.
+
+## Testing
+
+- **`node:test`** (built-in): `import { test } from 'node:test'; import assert from 'node:assert';`. Run with `node --test tests/`. No install needed.
+- **`vitest` / `jest`**: check `package.json` for the test script and the test file pattern (`*.test.ts`, `*.spec.ts`, `*.test.mjs`). Don't add a second test framework — use what the project already has.
+- **DOM testing**: use `jsdom` or `happy-dom` for headless DOM; don't fake `document`/`window` manually. For real browser testing, use Playwright/Puppeteer if installed.
+- **Browser checks**: carthagent ships a self-contained check tool (path injected into the delivery guidance). Declare it as a `runtime` check in `delivery_plan` — it serves the workspace over HTTP, runs jsdom assertions with real inline-script execution (clicks, text, selectors, console-error detection), and captures a real Firefox screenshot into `artifacts/` when Firefox is installed. No browser download needed.
+- **Async tests**: always `await` promises in tests. An unhandled rejection in a test can pass silently if the test framework doesn't track it. Use `assert.rejects` / `assert.resolves` for error paths.
+
+## Common pitfalls
+
+- **`fetch` is global in Node 18+** but not in older versions. Check `node --version` before using it; polyfill or use `undici`/`node-fetch` if needed.
+- **`path.join` vs `path.resolve`**: `resolve` is absolute, `join` is relative. Use `resolve` for file paths that must be absolute; use `join` for relative paths within a known base.
+- **`fs` vs `fs/promises`**: `fs` is callback-based; `fs/promises` is async/await. Prefer `fs/promises` in modern code. For synchronous operations (init, config loading), use `fs.readFileSync` etc.
+- **JSON parsing**: `JSON.parse` throws on malformed input — wrap it in try/catch when reading user data or config files. `JSON.stringify` is lossy for `undefined`, functions, and `Map`/`Set`.
+- **Timers**: `setTimeout`/`setInterval` return `Timer` objects, not numbers, in Node. `clearTimeout(timer)` is the correct way to cancel. `setTimeout` doesn't block — don't rely on it for sequencing.
+- **`process.exitCode` vs `process.exit()`**: setting `exitCode` lets the process finish pending I/O before exiting; `process.exit()` kills it immediately. Use `exitCode` in libraries; use `exit()` only in CLI entry points.
+- **`console.error` writes to stderr**, `console.log` to stdout. Tests that check output should distinguish stdout from stderr.
+
+## Browser specifics
+
+- **ESM in browsers**: `<script type="module" src="...">` for modules; plain `<script>` for classic scripts. Modules have their own scope — top-level `var`/`let` don't leak to `window`.
+- **`DOMContentLoaded`**: scripts with `defer` or `type="module"` run after DOM is ready. For non-deferred scripts, wait for `DOMContentLoaded` before accessing DOM elements.
+- **`fetch` CORS**: browser `fetch` to a different origin requires CORS headers on the server. `mode: 'no-cors'` gives an opaque response you can't read. For local development, use a local server or a CORS proxy.
+- **`localStorage`/`sessionStorage`**: synchronous, string-only, ~5MB limit. Wrap access in try/catch (private browsing can throw). Don't store objects — `JSON.stringify` them.
+- **Event listeners**: `addEventListener` returns the element, not a cleanup function. Store the listener reference to call `removeEventListener` later. `element.addEventListener('click', handler)` — don't use `onclick` for multiple handlers.
+- **`innerHTML`**: setting it recreates the DOM tree, losing event listeners and state. Prefer `createElement`/`appendChild` or `insertAdjacentHTML` for partial updates.
+
+## Async patterns
+
+- **`async`/`await`**: `await` unwraps a `Promise` or returns the value directly. `Promise.all` runs in parallel; `Promise.allSettled` collects all results even if some reject; `Promise.race` returns the first to settle.
+- **Unhandled rejections**: a `Promise` that rejects without a `.catch()` can crash Node (since v15) or log a warning in browsers. Always attach `.catch()` or `await` inside `try/catch`.
+- **Top-level `await`**: works in ES modules (Node 14.8+, browsers). In CommonJS, wrap in an `async` IIFE or use `.then()`.
+- **`Array.map(async)`**: `map` with async returns an array of Promises, not resolved values. Use `await Promise.all(arr.map(async ...))` to wait for all.
+
+## Packaging & deployment
+
+- **`npm install` vs `npm ci`**: `ci` installs exactly from `package-lock.json` (reproducible); `install` resolves ranges and updates the lockfile. Use `npm ci` in CI/test environments.
+- **`npx`**: runs a package without installing it globally. `npx tsc` uses the project's local TypeScript if installed, or downloads it. Prefer `npx` over `npm install -g` for one-off tools.
+- **`node_modules`**: never commit it. It's excluded from the source fingerprint by default. Use `package.json` + `package-lock.json` to declare dependencies.
+- **`.env` files**: use `dotenv` or `process.env` directly. Never commit `.env` to the repo; add it to `.gitignore`. Read secrets via `process.env.VAR_NAME`, not by importing `.env` as a module.

package/tests/acceptance-review.test.mjs

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { acceptanceReviewerPrompt } from '../lib/acceptance-review.mjs';
+test('workspace reviewer preserves original request and challenges integration without domain specialization', () => {
+  const request = 'Persist submitted orders and reject unauthorized callers';
+  const prompt = acceptanceReviewerPrompt(request);
+  assert.ok(prompt.endsWith(request));
+  assert.match(prompt, /Do not modify product source/);
+  assert.match(prompt, /Test normal execution separately/);
+  assert.match(prompt, /producer\/consumer representation agreement/);
+  assert.doesNotMatch(prompt, /Panda3D|voxel|Minecraft|camera|terrain/);
+  assert.throws(() => acceptanceReviewerPrompt(''), /required/);
+});

package/tests/auth.test.mjs

@@ -0,0 +1,234 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import {
+  authTypeLabel,
+  authTypes,
+  applyAuthEvent,
+  createCloudBillingLink,
+  filterLoginProviders,
+  formatCloudAccount,
+  hasConfiguredProvider,
+  loadCloudAccount,
+  loadCloudAccountUsage,
+  loadCloudUsage,
+  loginAndRefresh,
+  loginProviderFocus,
+  loginProviderList,
+  loadAuthRuntime,
+  newAuthState,
+} from '../lib/tui/auth.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const root = join(__dirname, '..');
+
+/** Minimal stand-in for the engine's ModelRuntime. */
+function fakeRuntime(providers, status = {}) {
+  return {
+    getProviders: () => providers,
+    getProviderAuthStatus: id => status[id] || { configured: false },
+  };
+}
+
+test('hasConfiguredProvider requires a usable credential, not an empty credential file', () => {
+  const agentDir = mkdtempSync(join(tmpdir(), 'carthagent-auth-check-'));
+  try {
+    assert.equal(hasConfiguredProvider({}, agentDir), false);
+    writeFileSync(join(agentDir, 'auth.json'), '{}');
+    writeFileSync(join(agentDir, 'models.json'), JSON.stringify({ providers: { custom: { baseUrl: 'https://example.test', models: [{ id: 'x' }] } } }));
+    assert.equal(hasConfiguredProvider({}, agentDir), false);
+
+    writeFileSync(join(agentDir, 'auth.json'), JSON.stringify({ openai: { type: 'api_key', key: 'stored-key' } }));
+    assert.equal(hasConfiguredProvider({}, agentDir), true);
+
+    writeFileSync(join(agentDir, 'auth.json'), '{ invalid json');
+    writeFileSync(join(agentDir, 'models.json'), JSON.stringify({ providers: { custom: { apiKey: 'configured-key' } } }));
+    assert.equal(hasConfiguredProvider({}, agentDir), true);
+    assert.equal(hasConfiguredProvider({ ANTHROPIC_API_KEY: ' env-key ' }, join(agentDir, 'missing')), true);
+  } finally {
+    rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('authTypes reports advertised methods, subscription first', () => {
+  assert.deepEqual(authTypes({ auth: { apiKey: {} } }), ['api_key']);
+  assert.deepEqual(authTypes({ auth: { oauth: {} } }), ['oauth']);
+  assert.deepEqual(authTypes({ auth: { oauth: {}, apiKey: {} } }), ['oauth', 'api_key']);
+  assert.deepEqual(authTypes({}), []);
+  assert.deepEqual(authTypes(undefined), []);
+});
+
+test('authTypeLabel names the two login methods', () => {
+  assert.equal(authTypeLabel('oauth'), 'subscription (OAuth)');
+  assert.equal(authTypeLabel('oauth', 'experiential-labs'), 'browser sign-in');
+  assert.equal(authTypeLabel('api_key'), 'API key');
+});
+
+test('loginProviderList skips providers without a login method', () => {
+  const runtime = fakeRuntime([
+    { id: 'anthropic', name: 'Anthropic', auth: { oauth: {}, apiKey: {} } },
+    { id: 'noauth', name: 'No Auth', auth: {} },
+    { id: 'deepseek', name: 'DeepSeek', auth: { apiKey: {} } },
+  ]);
+  const rows = loginProviderList(runtime);
+  assert.deepEqual(rows.map(r => r.id), ['anthropic', 'deepseek']);
+  assert.deepEqual(rows[0].types, ['oauth', 'api_key']);
+  assert.deepEqual(rows[1].types, ['api_key']);
+});
+
+test('loginProviderList keeps stable product ordering regardless of connected state', () => {
+  const runtime = fakeRuntime(
+    [
+      { id: 'zeta', name: 'Zeta', auth: { apiKey: {} } },
+      { id: 'openrouter', name: 'OpenRouter', auth: { apiKey: {} } },
+      { id: 'experiential-labs', name: 'Carthagent Ship', auth: { oauth: {}, apiKey: {} } },
+      { id: 'anthropic', name: 'Anthropic', auth: { apiKey: {} } },
+      { id: 'alpha', name: 'Alpha', auth: { apiKey: {} } },
+    ],
+    { zeta: { configured: true }, openrouter: { configured: true } }
+  );
+  const rows = loginProviderList(runtime);
+  assert.deepEqual(rows.map(r => r.id), ['experiential-labs', 'anthropic', 'openrouter', 'alpha', 'zeta']);
+  assert.equal(rows[0].recommended, true);
+  assert.deepEqual(rows[0].types, ['oauth', 'api_key']);
+  assert.equal(rows[1].configured, false);
+  assert.equal(rows.at(-1).configured, true);
+});
+
+test('loginProviderFocus prefers the active provider without reordering rows', () => {
+  const rows = [
+    { id: 'experiential-labs', recommended: true },
+    { id: 'anthropic', recommended: false },
+  ];
+  assert.equal(loginProviderFocus(rows), 0);
+  assert.equal(loginProviderFocus(rows, 'anthropic'), 1);
+  assert.deepEqual(rows.map(row => row.id), ['experiential-labs', 'anthropic']);
+});
+
+test('loginProviderList tolerates a runtime that throws on auth status', () => {
+  const runtime = {
+    getProviders: () => [{ id: 'x', name: 'X', auth: { apiKey: {} } }],
+    getProviderAuthStatus: () => { throw new Error('boom'); },
+  };
+  assert.deepEqual(loginProviderList(runtime).map(r => r.id), ['x']);
+});
+
+test('filterLoginProviders matches id or name, case-insensitively', () => {
+  const rows = [{ id: 'anthropic', name: 'Anthropic' }, { id: 'google', name: 'Google Gemini' }];
+  assert.equal(filterLoginProviders(rows, '').length, 2);
+  assert.equal(filterLoginProviders(rows, '   ').length, 2);
+  assert.deepEqual(filterLoginProviders(rows, 'anth').map(r => r.id), ['anthropic']);
+  assert.deepEqual(filterLoginProviders(rows, 'GEM').map(r => r.id), ['google']);
+  assert.deepEqual(filterLoginProviders(rows, 'zzz'), []);
+});
+
+test('applyAuthEvent folds login notify events into popup fields', () => {
+  const state = newAuthState();
+  applyAuthEvent(state, { type: 'auth_url', url: 'https://x/y', instructions: 'do it' });
+  assert.equal(state.url, 'https://x/y');
+  assert.equal(state.instructions, 'do it');
+  assert.match(state.message, /authorization URL/i);
+
+  applyAuthEvent(state, { type: 'device_code', userCode: 'ABCD-1234', verificationUri: 'https://verify' });
+  assert.deepEqual(state.deviceCode, { userCode: 'ABCD-1234', verificationUri: 'https://verify' });
+
+  applyAuthEvent(state, { type: 'progress', message: 'working' });
+  assert.equal(state.message, 'working');
+
+  applyAuthEvent(state, { type: 'info', message: 'note', links: [{ url: 'https://l', label: 'L' }] });
+  assert.equal(state.message, 'note');
+  assert.equal(state.links.length, 1);
+
+  // unknown / empty events are harmless
+  applyAuthEvent(state, null);
+  applyAuthEvent(state, undefined);
+  applyAuthEvent(state, { type: 'mystery' });
+  assert.equal(state.url, 'https://x/y');
+});
+
+test('newAuthState starts in the provider-picking phase', () => {
+  const state = newAuthState();
+  assert.equal(state.phase, 'providers');
+  assert.deepEqual(state.providers, []);
+  assert.equal(state.error, '');
+  assert.equal(state.busy, false);
+});
+
+test('loginAndRefresh exposes dynamic provider models immediately after login', async () => {
+  const calls = [];
+  const signal = new AbortController().signal;
+  const runtime = {
+    login: async (...args) => { calls.push(['login', ...args]); return { type: 'api_key', key: 'k' }; },
+    refresh: async options => { calls.push(['refresh', options]); },
+  };
+  const result = await loginAndRefresh(runtime, 'experiential-labs', 'api_key', { signal });
+  assert.equal(result.key, 'k');
+  assert.equal(calls[0][0], 'login');
+  assert.deepEqual(calls[1][1], { providers: ['experiential-labs'], allowNetwork: true, signal });
+});
+
+test('Cloud account helpers use the runtime OAuth credential for account and billing actions', async () => {
+  const calls = [];
+  const runtime = {
+    isUsingOAuth: () => false,
+    checkAuth: async id => id === 'experiential-labs' ? { source: 'OAuth', type: 'oauth' } : null,
+    getAuth: async () => ({ auth: { apiKey: 'access-token' } }),
+  };
+  const fetchImpl = async (url, options) => {
+    calls.push({ url, options });
+    return new Response(JSON.stringify(url.includes('/account/usage')
+      ? { accountId: 'acct', data: [{ alias: 'gpt-5.6-luna', inputTokens: 2, outputTokens: 3, createdAt: '2027-01-01T00:00:00.000Z' }] }
+      : url.endsWith('/account')
+        ? { accountId: 'acct', balance: { availableNanoUsd: 1_000_000_000 }, subscription: { status: 'none' }, sessions: [] }
+        : { url: 'https://stripe.test' }), { status: 200 });
+  };
+  const env = { CARTHAGENT_CLOUD_URL: 'https://cloud.test' };
+  const account = await loadCloudAccount(runtime, { env, fetchImpl });
+  const usage = await loadCloudUsage(runtime, { env, fetchImpl });
+  const combined = await loadCloudAccountUsage(runtime, { env, fetchImpl });
+  const billing = await createCloudBillingLink(runtime, 'checkout', { env, fetchImpl });
+  assert.equal(account.accountId, 'acct');
+  assert.equal(usage.data[0].inputTokens, 2);
+  assert.equal(combined.account.accountId, 'acct');
+  assert.equal(combined.usage.data[0].outputTokens, 3);
+  assert.equal(billing.url, 'https://stripe.test');
+  assert.ok(calls.every(call => call.options.headers.authorization === 'Bearer access-token'));
+  assert.match(formatCloudAccount(account), /Credit: \$1\.00/);
+  await assert.rejects(loadCloudAccount({ checkAuth: async () => null }, { env, fetchImpl }), /cloud_login_required/);
+});
+
+test('loadAuthRuntime lazily imports vendored engine and discovers OAuth/API providers', async () => {
+  const runtime = await loadAuthRuntime();
+  assert.ok(runtime && typeof runtime === 'object');
+  const providers = loginProviderList(runtime);
+  assert.ok(providers.length >= 41);
+  assert.equal(providers[0].id, 'experiential-labs');
+  assert.equal(providers[0].recommended, true);
+  const oauthProviders = providers.filter(p => p.types.includes('oauth')).map(p => p.id).sort();
+  assert.deepEqual(oauthProviders, [
+    'anthropic',
+    'experiential-labs',
+    'github-copilot',
+    'kimi-coding',
+    'openai-codex',
+    'openrouter',
+    'radius',
+    'xai',
+  ]);
+});
+
+test('vendor engine does not install redundant engine or schema packages', () => {
+  const chunkPath = join(root, 'vendor', 'agent', 'chunks', 'chunk-JVUZSMYM.js');
+  const content = readFileSync(chunkPath, 'utf8');
+  assert.doesNotMatch(content, /from\s*['"]@earendil-works\/chord/);
+  assert.match(content, /from\s*['"]\.\/chord-context\.js['"]/);
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  for (const name of ['@earendil-works/chord', 'typebox']) {
+    assert.equal(manifest.dependencies?.[name], undefined);
+    assert.equal(manifest.devDependencies?.[name], undefined);
+  }
+});

package/tests/bounded-summary.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { boundedSummary, summaryByteBudget, compactionThreshold, serializedContextTokens } from '../vendor/agent/bounded-summary.mjs';
+
+const model = {contextWindow:150000,maxTokens:32768};
+const ctx = text => ({systemPrompt:'Summarize only.',messages:[{role:'user',content:[{type:'text',text}],timestamp:0}]});
+const ok = text => ({stopReason:'stop',content:[{type:'text',text}],usage:{input:10,output:3,totalTokens:13,cost:{total:0.01}}});
+
+test('large Unicode history is covered completely in bounded map/reduce requests', async () => {
+  const text = '🙂漢字"\\\n'.repeat(40000) + 'IMPORTANT FINAL INSTRUCTION';
+  const fragments = [], ids = [], requests = [];
+  const result = await boundedSummary(model,ctx(text),{maxTokens:12000},async (context,options)=>{
+    assert.ok(Buffer.byteLength(JSON.stringify(context)) <= summaryByteBudget(model));
+    assert.ok(options.maxTokens >= 16);
+    ids.push(options.sessionId); requests.push(context);
+    const prompt=context.messages[0].content[0].text;
+    if(prompt.includes('<fragment>')) fragments.push(prompt.split('<fragment>\n')[1].split('\n</fragment>')[0]);
+    return ok('Compact checkpoint with paths, constraints and next steps.');
+  });
+  assert.equal(fragments.join(''),text);
+  assert.ok(requests.length>2);
+  assert.equal(new Set(ids).size,ids.length);
+  assert.equal(result.usage.totalTokens,requests.length*13);
+  assert.equal(result.content[0].text,'Compact checkpoint with paths, constraints and next steps.');
+});
+
+test('request_too_large response halves the budget and recovers', async () => {
+  let failures=0,calls=0;
+  const result=await boundedSummary({contextWindow:5000},ctx('x'.repeat(15000)),{},async context=>{
+    calls++;
+    if(Buffer.byteLength(JSON.stringify(context))>5500){failures++;return {stopReason:'error',errorMessage:'400: request_too_large',content:[]};}
+    return ok('short summary');
+  });
+  assert.ok(failures>0);assert.ok(calls>failures);assert.equal(result.content[0].text,'short summary');
+});
+
+test('small requests stay single-call; cancellation and incomplete responses fail closed', async () => {
+  let calls=0;
+  await boundedSummary(model,ctx('small'),{},async()=>{calls++;return ok('summary');});
+  assert.equal(calls,1);
+  const controller=new AbortController();controller.abort();
+  await assert.rejects(boundedSummary(model,ctx('small'),{signal:controller.signal},()=>{throw Error('should not call');}),/abort/i);
+  for(const response of [{stopReason:'length',content:[{type:'text',text:'partial'}]},{stopReason:'stop',content:[]},{stopReason:'error',errorMessage:'401 unauthorized'}]) {
+    await assert.rejects(boundedSummary(model,ctx('small'),{},async()=>response));
+  }
+});
+
+test('compaction starts with 30 percent headroom and both engine paths are wired', () => {
+  assert.equal(compactionThreshold(150000,16384),105000);
+  assert.equal(summaryByteBudget({...model,maxRequestBytes:100000}),50000);
+  const source=readFileSync(new URL('../vendor/agent/chunks/chunk-JVUZSMYM.js',import.meta.url),'utf8');
+  assert.equal(source.split('contextTokens>compactionThreshold(').length-1,2);
+  assert.equal(source.split('response=await boundedSummary(model,{systemPrompt:SUMMARIZATION_SYSTEM_PROMPT2').length-1,2);
+  assert.match(source,/return boundedSummary\(model,context,requestOptions/);
+  const unicode=[{role:'user',content:'漢字🙂'.repeat(100)}];
+  assert.equal(serializedContextTokens(unicode),Math.ceil(Buffer.byteLength(JSON.stringify(unicode))/4));
+  assert.equal(source.split('Math.max(usageTokens+trailingTokens,serializedContextTokens(messages))').length-1,2);
+});
+
+test('cancellation between chunks stops requests; errors do not silently drop history', async () => {
+  const controller=new AbortController();let calls=0;
+  await assert.rejects(boundedSummary({contextWindow:2000},ctx('history '.repeat(3000)),{signal:controller.signal},async()=>{
+    calls++;controller.abort();return ok('summary');
+  }),/abort/i);
+  assert.equal(calls,1);
+  await assert.rejects(boundedSummary(model,ctx('small'),{},async()=>{throw Error('400 request_too_large');}),/request_too_large|budget/);
+});

package/tests/browser-bin.test.mjs

@@ -0,0 +1,91 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { deflateRawSync } from 'node:zlib';
+import { extractZip, findBrowser, findChromium, bundledBinaryPath, ensureBundledBrowser, isSandboxFailure } from '../lib/browser-bin.mjs';
+
+/** Build a minimal zip archive in memory: [{name, data, method}] → Buffer. */
+function buildZip(entries) {
+  const local = [];
+  const central = [];
+  let offset = 0;
+  for (const { name, data, method } of entries) {
+    const nameBuf = Buffer.from(name, 'utf8');
+    const raw = Buffer.from(data);
+    const stored = method === 8 ? deflateRawSync(raw) : raw;
+    const lh = Buffer.alloc(30);
+    lh.writeUInt32LE(0x04034b50, 0); lh.writeUInt16LE(20, 4); lh.writeUInt16LE(0, 6);
+    lh.writeUInt16LE(method, 8); lh.writeUInt16LE(0, 10); lh.writeUInt16LE(0, 12);
+    lh.writeUInt32LE(0, 14); lh.writeUInt32LE(stored.length, 18); lh.writeUInt32LE(raw.length, 22);
+    lh.writeUInt16LE(nameBuf.length, 26); lh.writeUInt16LE(0, 28);
+    local.push(lh, nameBuf, stored);
+    const ch = Buffer.alloc(46);
+    ch.writeUInt32LE(0x02014b50, 0); ch.writeUInt16LE(20, 4); ch.writeUInt16LE(20, 6);
+    ch.writeUInt16LE(method, 10); ch.writeUInt32LE(stored.length, 20); ch.writeUInt32LE(raw.length, 24);
+    ch.writeUInt16LE(nameBuf.length, 28); ch.writeUInt32LE(offset, 42);
+    central.push(Buffer.concat([ch, nameBuf]));
+    offset += 30 + nameBuf.length + stored.length;
+  }
+  const cd = Buffer.concat(central);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0); eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10); eocd.writeUInt32LE(cd.length, 12); eocd.writeUInt32LE(offset, 16);
+  return Buffer.concat([...local, cd, eocd]);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'browser-bin-test-'));
+test.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+test('extractZip extracts stored and deflated entries', () => {
+  const zip = join(tmp, 'ok.zip');
+  writeFileSync(zip, buildZip([
+    { name: 'pkg/a.txt', data: 'stored café', method: 0 },
+    { name: 'pkg/deep/b.txt', data: 'deflated café '.repeat(50), method: 8 },
+  ]));
+  const out = join(tmp, 'out');
+  const files = extractZip(zip, out);
+  assert.equal(files.length, 2);
+  assert.equal(readFileSync(join(out, 'pkg/a.txt'), 'utf8'), 'stored café');
+  assert.equal(readFileSync(join(out, 'pkg/deep/b.txt'), 'utf8'), 'deflated café '.repeat(50));
+});
+
+test('extractZip rejects traversal and absolute entries', () => {
+  for (const name of ['../escape', 'a/../../x', '/abs', 'C:/win']) {
+    const zip = join(tmp, `bad-${name.length}.zip`);
+    writeFileSync(zip, buildZip([{ name, data: 'x', method: 0 }]));
+    assert.throws(() => extractZip(zip, join(tmp, 'badout')), /refusing entry/);
+  }
+});
+
+test('findBrowser honors CARTHAGENT_BROWSER, bundled path, then system/firefox', () => {
+  const custom = join(tmp, 'custom-shell');
+  writeFileSync(custom, 'fake');
+  assert.equal(findBrowser({ env: { CARTHAGENT_BROWSER: custom, PATH: '' } }), custom);
+  const bundled = bundledBinaryPath();
+  const found = findBrowser({ env: { PATH: '' } });
+  // System browsers are host-dependent: bundled when present, else whatever
+  // the host provides (CI images ship /usr/bin/firefox) or null.
+  if (existsSync(bundled)) assert.equal(found, bundled);
+  else assert.ok(found === null || /firefox/i.test(found));
+  const chromium = findChromium({ env: { PATH: '' } });
+  if (existsSync(bundled)) assert.equal(chromium, bundled);
+  else assert.equal(chromium, null);
+});
+
+test('isSandboxFailure matches AppArmor/userns sandbox errors only', () => {
+  assert.equal(isSandboxFailure('! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces with AppArmor'), true);
+  assert.equal(isSandboxFailure('cannot run as root without --no-sandbox'), true);
+  assert.equal(isSandboxFailure('DevTools listening on ws://127.0.0.1'), false);
+  assert.equal(isSandboxFailure(''), false);
+});
+
+test('ensureBundledBrowser short-circuits when binary exists and honors base', async () => {
+  const base = join(tmp, 'custom-root');
+  const bin = bundledBinaryPath({ base });
+  mkdirSync(join(bin, '..'), { recursive: true });
+  writeFileSync(bin, 'fake');
+  const resolved = await ensureBundledBrowser({ base, fetchImpl: async () => { throw Error('must not fetch'); } });
+  assert.equal(resolved, bin);
+});

package/tests/browser.test.mjs

@@ -0,0 +1,96 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { serveDir, domCheck } from '../lib/browser.mjs';
+
+function fixture(t, html = '<!doctype html><div id="app">hello</div>') {
+  const dir = mkdtempSync(join(tmpdir(), 'carthagent browser '));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeFileSync(join(dir, 'index.html'), html);
+  return dir;
+}
+
+test('serveDir serves files over HTTP with correct MIME and blocks traversal', async t => {
+  const dir = fixture(t);
+  const srv = await serveDir(dir);
+  t.after(() => srv.close());
+  const res = await fetch(`${srv.url}/index.html`);
+  assert.equal(res.status, 200);
+  assert.match(res.headers.get('content-type'), /text\/html/);
+  assert.match(await res.text(), /hello/);
+  const esc = await fetch(`${srv.url}/%2e%2e%2fpackage.json`);
+  assert.equal(esc.status, 403);
+  const missing = await fetch(`${srv.url}/nope.html`);
+  assert.equal(missing.status, 404);
+});
+
+test('domCheck executes inline scripts and asserts on selectors, text, and clicks', async () => {
+  const html = `<!doctype html><body>
+    <div id="word">_ _</div><div id="kb"></div>
+    <script>
+      const kb = document.getElementById('kb');
+      'AB'.split('').forEach(ch => {
+        const b = document.createElement('button'); b.id = 'key-' + ch; b.textContent = ch;
+        b.onclick = () => { document.getElementById('word').textContent = ch + ' _'; };
+        kb.appendChild(b);
+      });
+    </script></body>`;
+  const r = await domCheck(html, [
+    { selector: '#kb button', count: 2 },
+    { selector: '#word', text: '_ _' },
+    { action: 'click', selector: '#key-A', then: { selector: '#word', text: 'A _' } },
+    { console: 'error-free' },
+  ]);
+  assert.equal(r.pass, true);
+  assert.deepEqual(r.failures, []);
+  assert.deepEqual(r.consoleErrors, []);
+});
+
+test('domCheck reports failures for missing elements, wrong counts, bad text, and console errors', async () => {
+  const html = `<!doctype html><body><div id="x">nope</div><script>console.error('boom');</script></body>`;
+  const r = await domCheck(html, [
+    { selector: '#missing' },
+    { selector: '#x', text: 'expected' },
+    { selector: 'div', count: 5 },
+    { console: 'error-free' },
+  ]);
+  assert.equal(r.pass, false);
+  assert.equal(r.failures.length, 4);
+  assert.ok(r.failures.some(f => f.includes('not found')));
+  assert.ok(r.failures.some(f => f.includes('does not match')));
+  assert.ok(r.failures.some(f => f.includes('console errors')));
+});
+
+test('domCheck rejects unsupported module execution but permits explicit static inspection', async () => {
+  for (const script of ['<script type="module">throw new Error("Broken app")</script>', '<script type="MODULE" src="/app.mjs"></script>']) {
+    const html = `<div id="app">café</div>${script}`;
+    const result = await domCheck(html, [{ selector: '#app' }, { console: 'error-free' }], { waitMs: 0 });
+    assert.equal(result.pass, false);
+    assert.match(result.failures.join(' '), /Unsupported module scripts/);
+    result.window.close();
+    const staticResult = await domCheck(html, [{ selector: '#app', text: 'café' }], { runScripts: false });
+    assert.equal(staticResult.pass, true);
+    staticResult.window.close();
+  }
+});
+
+test('domCheck supports eval assertions and type/key actions', async () => {
+  const html = `<!doctype html><body>
+    <input id="in"><div id="out"></div>
+    <script>
+      document.getElementById('in').addEventListener('input', e => {
+        document.getElementById('out').textContent = 'typed:' + e.target.value;
+      });
+      document.addEventListener('keydown', e => {
+        if (e.key === 'Enter') document.getElementById('out').textContent = 'enter!';
+      });
+    </script></body>`;
+  const r = await domCheck(html, [
+    { action: 'type', selector: '#in', value: 'abc', then: { selector: '#out', text: 'typed:abc' } },
+    { action: 'key', key: 'Enter', then: { selector: '#out', text: 'enter!' } },
+    { eval: 'document.title', expect: '' },
+  ]);
+  assert.equal(r.pass, true);
+});