carthagent 0.0.0-stage → 1.0.7

package/tests/budget-engine.test.mjs

@@ -0,0 +1,110 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+for (const mode of ['tools', 'seconds', 'repairs']) test(`actual engine stops ${mode}, restores budget and accepts explicit reset offline`, { timeout: 120000 }, async t => {
+  const cwd = mkdtempSync(join(tmpdir(), 'budget café '));
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+  let calls = 0;
+  let secondsResponseClosed = false;
+  const providerRequestTimes = [];
+  const server = createServer((req, res) => {
+    req.resume();
+    req.on('end', () => {
+      calls++;
+      providerRequestTimes.push(performance.now());
+      res.writeHead(200, { 'content-type': 'text/event-stream' });
+      if (mode === 'seconds' && calls === 1) { res.on('close', () => { secondsResponseClosed = true; }); res.flushHeaders(); return; }
+      const chunk = { id: 'local', object: 'chat.completion.chunk', created: 1, model: 'fixture', choices: [{ index: 0, delta: mode === 'seconds' ? { role: 'assistant', content: 'Reset request admitted' } : { role: 'assistant', tool_calls: [{ index: 0, id: `call${calls}`, type: 'function', function: { name: 'read', arguments: JSON.stringify({ path: 'input.txt' }) } }] }, finish_reason: null }] };
+      if (mode === 'repairs') {
+        if (calls === 1) chunk.choices[0].delta.tool_calls[0].function = { name: 'delivery_plan', arguments: JSON.stringify({ goal: 'unfinished fixture', assumptions: [], artifacts: ['.'], steps: ['Implement'], acceptance: [{ requirement: 'fixture', checks: ['check'] }], checks: [{ id: 'check', kind: 'test', argv: [process.execPath, '-e', 'process.exit(0)'], timeoutSeconds: 5 }] }) };
+        else chunk.choices[0].delta = { role: 'assistant', content: 'Incomplete fixture response' };
+      }
+      res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+      chunk.choices = [{ index: 0, delta: {}, finish_reason: mode === 'seconds' || mode === 'repairs' && calls > 1 ? 'stop' : 'tool_calls' }];
+      res.end(`data: ${JSON.stringify(chunk)}\n\ndata: [DONE]\n\n`);
+    });
+  });
+  await new Promise(r => server.listen(0, '127.0.0.1', r));
+  t.after(() => server.close());
+  const agent = join(cwd, 'agent'); mkdirSync(agent);
+  writeFileSync(join(agent, 'models.json'), JSON.stringify({ providers: { localtest: { baseUrl: `http://127.0.0.1:${server.address().port}/v1`, api: 'openai-completions', apiKey: 'dummy', models: [{ id: 'fixture', contextWindow: 128000, maxTokens: 1024 }] } } }));
+  writeFileSync(join(cwd, 'input.txt'), 'café ✓');
+  const session = join(cwd, 'session.jsonl');
+  const cli = fileURLToPath(new URL('../bin/ctg.mjs', import.meta.url));
+  let beforeRestore = -1;
+  let forcedKill = false;
+  async function run(prompt, secondsLimit = mode === 'seconds' ? '5' : '10000', expectBudgetStop = false) {
+    const startedAt = performance.now();
+    let priorEntryCount = 0;
+    try { priorEntryCount = readFileSync(session, 'utf8').split('\n').filter(Boolean).length; } catch { /* Initial session has not been created yet. */ }
+    let budgetStoppedAt = null;
+    const child = spawn(process.execPath, [cli, '-p', '--no-guide', '--provider', 'localtest', '--model', 'fixture', '--session', session, '--max-tools', mode === 'tools' ? '1' : '0', '--max-seconds', secondsLimit, '--max-repairs', mode === 'repairs' ? '1' : '0', prompt], { cwd, env: { ...process.env, PI_OFFLINE: '1', CARTHAGENT_CODING_AGENT_DIR: agent, PI_CODING_AGENT_DIR: agent } });
+    child.stdin.end();
+    let output = ''; child.stdout.on('data', d => output += d); child.stderr.on('data', d => output += d);
+    let timer;
+    let watchdogPhase = expectBudgetStop ? 'startup/budget-stop' : 'child-exit';
+    const armWatchdog = (ms, phase) => {
+      clearTimeout(timer);
+      watchdogPhase = phase;
+      timer = setTimeout(() => { forcedKill = true; child.kill(); }, ms);
+    };
+    const observeBudgetStop = setInterval(() => {
+      try {
+        const freshEntries = readFileSync(session, 'utf8').split('\n').filter(Boolean).slice(priorEntryCount);
+        if (freshEntries.some(line => {
+          const entry = JSON.parse(line);
+          return entry.customType === 'delivery-budget-v1' && entry.data?.stopped;
+        })) {
+          if (budgetStoppedAt === null) {
+            budgetStoppedAt = performance.now();
+            if (expectBudgetStop) armWatchdog(15000, 'budget-stop/shutdown');
+          }
+        }
+      } catch { /* Ignore a partially appended JSONL entry; the next poll retries. */ }
+    }, 20);
+    armWatchdog(expectBudgetStop ? 20000 : 15000, expectBudgetStop ? 'startup/budget-stop' : 'child-exit');
+    const code = await new Promise((resolve, reject) => { child.on('error', reject); child.on('close', resolve); });
+    clearTimeout(timer);
+    clearInterval(observeBudgetStop);
+    const closedAt = performance.now();
+    const newRequestTimes = providerRequestTimes.filter(time => time >= startedAt);
+    const timing = {
+      startupToProviderMs: newRequestTimes.length ? Math.round(newRequestTimes[0] - startedAt) : null,
+      startToBudgetStopMs: budgetStoppedAt === null ? null : Math.round(budgetStoppedAt - startedAt),
+      budgetStopToCloseMs: budgetStoppedAt === null ? null : Math.round(closedAt - budgetStoppedAt),
+      totalMs: Math.round(closedAt - startedAt),
+    };
+    t.diagnostic(`${mode} child phase timing: ${JSON.stringify(timing)}`);
+    assert.equal(forcedKill, false, `child must exit naturally; watchdog phase=${watchdogPhase}; phase timing=${JSON.stringify(timing)}`);
+    // Print mode reports the last assistant error even for a command-only reset.
+    // Reset is verified from persisted state and subsequent successful tool use.
+    assert.equal(code, (mode === 'seconds' || mode === 'repairs') && calls !== beforeRestore ? 0 : 1, `${output}\nrequests=${calls}\nsession=${readFileSync(session, 'utf8').slice(-6000)}`);
+    return readFileSync(session, 'utf8').split('\n').filter(Boolean).map(JSON.parse);
+  }
+  let entries = await run('Read input.txt repeatedly', undefined, true);
+  if (mode === 'seconds') {
+    assert.equal(calls, 1, 'seconds budget must stop without a follow-up request');
+    assert.equal(secondsResponseClosed, true, 'seconds budget must close the active response/socket');
+  }
+  const toolResults = e => e.filter(x => x.type === 'message' && x.message?.role === 'toolResult' && !x.message.isError);
+  assert.equal(toolResults(entries).length, mode === 'seconds' ? 0 : 1);
+  assert.equal(entries.filter(e => e.customType === 'delivery-budget-v1').at(-1).data.stopped, { seconds: 'elapsed-time', tools: 'tool-calls', repairs: 'repair-rounds' }[mode]);
+  assert.ok(calls <= (mode === 'repairs' ? 3 : 2), `unexpected followups: ${calls}`);
+  const before = calls;
+  beforeRestore = calls;
+  entries = await run('Read again');
+  assert.equal(calls, before, 'restored stop must not call provider');
+  assert.equal(toolResults(entries).length, mode === 'seconds' ? 0 : 1);
+  entries = await run('/delivery-budget-reset', '10000');
+  beforeRestore = -1;
+  assert.equal(entries.filter(e => e.customType === 'delivery-budget-v1').at(-1).data.stopped, null);
+  entries = await run('Read again', mode === 'seconds' ? '10000' : undefined);
+  assert.equal(toolResults(entries).length, mode === 'seconds' ? 0 : mode === 'repairs' ? 1 : 2);
+  assert.ok(calls > before, `explicit reset admits a fresh request (before=${before}, after=${calls}, mode=${mode})`);
+});

package/tests/budget.test.mjs

@@ -0,0 +1,23 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { budgetLimits, budgetReason, newBudget } from '../lib/budget.mjs';
+test('budget boundaries and configuration fail closed', () => {
+  for (const value of ['NaN', '-1', '1.5', '1000001']) assert.throws(() => budgetLimits(() => value));
+  const b = newBudget({ tools: 2, seconds: 1, repairs: 1 }, 100);
+  assert.equal(budgetReason(b, 'tool', 1099), null);
+  assert.equal(budgetReason(b, 'tool', 1100), 'elapsed-time');
+  b.tools = 2;
+  assert.equal(budgetReason(b, 'tool', 101), 'tool-calls');
+  b.repairs = 1;
+  assert.equal(budgetReason(b, 'repair', 101), 'repair-rounds');
+  b.stopped = 'tool-calls';
+  assert.equal(budgetReason(b, undefined, 101), 'tool-calls');
+});
+
+test('shared launch arguments validate and forward budgets for both clients', async () => {
+  const { buildEngineArgs } = await import('../lib/engine.mjs');
+  const args = buildEngineArgs({ maxTools: '3', maxSeconds: '0', maxRepairs: '1' });
+  for (const [flag, value] of [['tools', '3'], ['seconds', '0'], ['repairs', '1']]) assert.equal(args[args.indexOf(`--delivery-max-${flag}`) + 1], value);
+  assert.throws(() => buildEngineArgs({ maxTools: '-1' }));
+  assert.throws(() => buildEngineArgs({ maxTools: '0', delivery: false }), /require the delivery extension/);
+});

package/tests/cli.test.mjs

@@ -0,0 +1,245 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, chmodSync, copyFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, delimiter } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { approveFixture } from './helpers/tested-design.mjs';
+import { createReport, latestReport, saveReport } from '../lib/reports.mjs';
+import { buildEngineArgs } from '../lib/engine.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = join(root, 'bin', 'ctg.mjs');
+
+function fixture(t) {
+  const cwd = mkdtempSync(join(tmpdir(), 'carthagent cli '));
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+  writeFileSync(join(cwd, 'app.mjs'), 'console.log("app")\n');
+  return cwd;
+}
+
+function run(cwd, ...args) {
+  return spawnSync(process.execPath, [cli, ...args], { cwd, encoding: 'utf8' });
+}
+
+test('status reads the newest persisted extension report', t => {
+  const cwd = fixture(t);
+  createReport(cwd, {
+    status: 'implementing',
+    plan: {
+      goal: 'CLI fixture', assumptions: [], artifacts: ['.'], steps: ['Check'],
+      acceptance: [{ requirement: 'Runs', checks: ['smoke'] }],
+      checks: [{ id: 'smoke', kind: 'runtime', argv: [process.execPath, 'app.mjs'], timeoutSeconds: 10 }]
+    },
+    evidence: {}
+  }, 'session');
+  const result = run(cwd, 'status');
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /CLI fixture/);
+  assert.match(result.stdout, /pending:smoke/);
+});
+
+test('check executes declared argv and persists fresh evidence', t => {
+  const cwd = fixture(t);
+  createReport(cwd, {
+    status: 'implementing',
+    plan: {
+      goal: 'CLI fixture', assumptions: [], artifacts: ['.'], steps: ['Check'],
+      acceptance: [{ requirement: 'Runs', checks: ['smoke'] }],
+      checks: [{ id: 'smoke', kind: 'runtime', argv: [process.execPath, 'app.mjs'], timeoutSeconds: 10 }]
+    },
+    evidence: {}
+  }, 'session');
+  const report = latestReport(cwd);
+  saveReport(report.path, approveFixture(report.state, cwd));
+  const result = run(cwd, 'check', 'all');
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /passed/);
+  assert.equal(latestReport(cwd).state.evidence.smoke.passed, true);
+});
+
+test('structured headless mode forwards JSON events and status offers a parseable snapshot', t => {
+  assert.deepEqual(buildEngineArgs({ json: true, delivery: false }).slice(0, 2), ['--mode', 'json']);
+  assert.equal(buildEngineArgs({ delivery: false }).includes('--mode'), false);
+  const result = run(fixture(t), 'status', '--json');
+  assert.equal(result.status, 0, result.stderr);
+  const snapshot = JSON.parse(result.stdout);
+  assert.equal(snapshot.version, 1);
+  assert.equal(snapshot.state, null);
+  assert.equal(snapshot.completionIssues, null);
+  assert.match(snapshot.currentFingerprint, /^[a-f0-9]{64}$/);
+});
+
+test('check fails clearly when no delivery report exists', t => {
+  const result = run(fixture(t), 'check');
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /No delivery report/);
+});
+
+test('guidance routing is not a user-facing command and Ship account commands are documented', t => {
+  const result = run(fixture(t), '--help');
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stdout, /\broute\b|\bprofiles\b/);
+  assert.match(result.stdout, /account.*Ship credit/);
+  assert.match(result.stdout, /billing.*checkout\|portal/);
+  assert.match(result.stdout, /logout-cloud/);
+});
+
+test('Cloud account commands fail closed when no browser session is stored', t => {
+  const cwd = fixture(t);
+  const env = { ...process.env, CARTHAGENT_CODING_AGENT_DIR: join(cwd, 'agent'), PI_CODING_AGENT_DIR: join(cwd, 'agent') };
+  for (const args of [['account'], ['billing'], ['logout-cloud']]) {
+    const result = spawnSync(process.execPath, [cli, ...args], { cwd, env, encoding: 'utf8' });
+    assert.equal(result.status, 1, result.stderr);
+    assert.match(result.stderr, /not signed in/);
+  }
+});
+
+test('review shows and persists the self-review default', t => {
+  const cwd = fixture(t);
+  const env = { ...process.env, CARTHAGENT_CONFIG: join(cwd, 'config.json') };
+  const runEnv = (...args) => spawnSync(process.execPath, [cli, ...args], { cwd, env, encoding: 'utf8' });
+  assert.match(runEnv('review').stdout, /self-review default:.*ask/);
+  assert.equal(runEnv('review', 'no').status, 0);
+  assert.match(runEnv('review').stdout, /self-review default:.*no/);
+  assert.equal(JSON.parse(readFileSync(join(cwd, 'config.json'), 'utf8')).review, 'no');
+  assert.equal(runEnv('review', 'bogus').status, 2);
+});
+
+/** Fake `gh` + fake engine CLI so `ctg review <pr>` runs end-to-end offline. */
+function reviewFixture(t, verdictLine) {
+  const cwd = fixture(t);
+  const bin = join(cwd, 'bin');
+  mkdirSync(join(cwd, 'bin'), { recursive: true });
+  const gh = join(bin, 'gh');
+  writeFileSync(gh, `#!/bin/sh
+if [ "$1" = "pr" ] && [ "$2" = "view" ]; then echo '{"title":"Fixture PR","url":"https://example.test/pr/14","headRefName":"feat","baseRefName":"main","headRefOid":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'; exit 0; fi
+exit 0
+`);
+  chmodSync(gh, 0o755);
+  // Native executable fixture: Windows cannot execute a POSIX shebang shim.
+  if (process.platform === 'win32') {
+    copyFileSync(process.execPath, join(bin, 'gh.exe'));
+    writeFileSync(join(cwd, 'gh-preload.cjs'), `if (require('node:path').basename(process.execPath).toLowerCase() === 'gh.exe') { console.log(JSON.stringify({title:'Fixture PR',url:'https://example.test/pr/14',headRefName:'feat',baseRefName:'main',headRefOid:'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})); process.exit(0); }`);
+  }
+  const reviewer = join(cwd, 'reviewer.mjs');
+  writeFileSync(reviewer, `const prompt = process.argv.at(-1); const snapshot = /snapshot:"([a-f0-9]+)"/.exec(prompt)?.[1]; const head = /head:"([a-f0-9]+)"/.exec(prompt)?.[1]; console.log('fixture findings'); console.log('REVIEW_JSON: ' + JSON.stringify({version:1,snapshot,head,findings:${JSON.stringify(verdictLine.includes('CHANGES-REQUESTED') ? [{file:'app.mjs',line:1,severity:'blocking',issue:'fixture issue',fix:'fixture fix'}] : [])}})); console.log('${verdictLine}');\n`);
+  const env = { ...process.env, CARTHAGENT_CONFIG: join(cwd, 'config.json'), CARTHAGENT_CLI: reviewer, PATH: `${bin}${delimiter}${process.env.PATH}` };
+  if (process.platform === 'win32') env.NODE_OPTIONS = `${env.NODE_OPTIONS || ''} --require ${JSON.stringify(join(cwd, 'gh-preload.cjs'))}`;
+  return { cwd, env };
+}
+
+test('ctg review <pr> exits 0 when the fresh reviewer approves', t => {
+  const { cwd, env } = reviewFixture(t, 'VERDICT: APPROVE');
+  const result = spawnSync(process.execPath, [cli, 'review', '14'], { cwd, env, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /fixture findings/);
+  assert.match(result.stdout, /VERDICT: APPROVE/);
+});
+
+test('ctg review <pr> exits 1 on requested changes and 2 without a verdict', t => {
+  const { cwd, env } = reviewFixture(t, 'VERDICT: CHANGES-REQUESTED');
+  const result = spawnSync(process.execPath, [cli, 'review', '14'], { cwd, env, encoding: 'utf8' });
+  assert.equal(result.status, 1, result.stderr);
+  const silent = reviewFixture(t, 'analysis but no verdict line');
+  const bad = spawnSync(process.execPath, [cli, 'review', '14'], { cwd: silent.cwd, env: silent.env, encoding: 'utf8' });
+  assert.equal(bad.status, 2);
+  assert.match(bad.stderr, /no VERDICT/);
+});
+
+test('review persists admission limits across fresh CLI processes', t => {
+  const { cwd, env } = reviewFixture(t, 'VERDICT: CHANGES-REQUESTED');
+  for (let i = 0; i < 3; i++) {
+    const result = spawnSync(process.execPath, [cli, 'review', '14'], { cwd, env, encoding: 'utf8' });
+    assert.equal(result.status, 1, result.stderr);
+  }
+  const exhausted = spawnSync(process.execPath, [cli, 'review', '14'], { cwd, env, encoding: 'utf8' });
+  assert.equal(exhausted.status, 2);
+  assert.match(exhausted.stderr, /round limit/);
+  assert.doesNotMatch(exhausted.stdout, /fixture findings/);
+});
+
+test('review rejects source mutation and invalid execution bounds', t => {
+  const { cwd, env } = reviewFixture(t, 'VERDICT: APPROVE');
+  writeFileSync(join(cwd, 'reviewer.mjs'), `import {writeFileSync} from 'node:fs'; writeFileSync('changed.txt', 'café'); console.log('VERDICT: APPROVE');`);
+  const changed = spawnSync(process.execPath, [cli, 'review', '14'], { cwd, env, encoding: 'utf8' });
+  assert.equal(changed.status, 2);
+  assert.match(changed.stderr, /snapshot changed/);
+  for (const value of ['0', '301', 'Infinity', 'invalid']) {
+    const invalid = spawnSync(process.execPath, [cli, 'review', '14', '--timeout', value], { cwd, env, encoding: 'utf8' });
+    assert.equal(invalid.status, 2);
+    assert.match(invalid.stderr, /integer from 1 to 300/);
+  }
+});
+
+test('buildEngineArgs always loads the Experiential provider extension', () => {
+  const args = buildEngineArgs({ isolate: true, delivery: false });
+  const extensionPaths = args.flatMap((arg, index) => arg === '-e' ? [args[index + 1]] : []);
+  assert.ok(extensionPaths.some(path => path.endsWith(join('extensions', 'experiential.ts'))));
+});
+
+test('review modes launch the real bundled engine without unknown flags', t => {
+  const cwd = fixture(t);
+  for (const review of ['ask', 'yes', 'no']) {
+    const result = spawnSync(process.execPath, [join(root, 'vendor/agent/cli.js'),
+      '--offline', ...buildEngineArgs({ review, isolate: true }),
+      '--list-models', 'carthagent-no-such-model-123'], {
+      cwd, encoding: 'utf8', timeout: 15000,
+      env: { ...process.env, PI_CODING_AGENT_DIR: join(cwd, 'agent') },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stderr, /Unknown option|Failed to load extension/);
+    assert.match(result.stdout + result.stderr, /No models (matching|available)/);
+  }
+});
+
+test('ctg --list-models renders stored identity-only Cloud metadata as unknown', t => {
+  const cwd = fixture(t);
+  const agentDir = join(cwd, 'agent');
+  mkdirSync(agentDir, { recursive: true });
+  writeFileSync(join(agentDir, 'auth.json'), JSON.stringify({
+    'experiential-labs': { type: 'api_key', key: 'fixture-credential' },
+  }));
+  writeFileSync(join(agentDir, 'models-store.json'), JSON.stringify({
+    'experiential-labs': {
+      models: [{ id: 'carthagent-code', name: 'carthagent-code' }],
+      checkedAt: 1,
+    },
+  }));
+  const result = spawnSync(process.execPath, [cli, '--list-models', 'Carthagent Ship'], {
+    cwd,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PI_OFFLINE: '1',
+      CARTHAGENT_CODING_AGENT_DIR: agentDir,
+      PI_CODING_AGENT_DIR: agentDir,
+    },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Carthagent Ship\s+carthagent-code\s+\?\s+\?\s+\?\s+\?/);
+  assert.doesNotMatch(result.stdout, /experiential/i);
+  assert.doesNotMatch(result.stderr, /Cannot read properties|Failed to load extension/);
+});
+
+test('vendored agent engine is bundled and loads ModelRuntime cleanly', async () => {
+  const agentPath = join(root, 'vendor', 'agent', 'index.js');
+  const agent = await import(pathToFileURL(agentPath).href);
+  assert.equal(typeof agent.ModelRuntime, 'function');
+  const runtime = await agent.ModelRuntime.create({});
+  assert.ok(runtime && typeof runtime === 'object');
+  assert.ok(Array.isArray(runtime.snapshot?.all));
+  assert.ok(runtime.snapshot.all.length > 0);
+  const providers = new Set(runtime.snapshot.all.map(m => m.provider));
+  assert.ok(providers.size >= 35);
+});
+
+test('CLI rejects invalid, missing and disabled-extension budget options', t => {
+  const cwd = fixture(t);
+  for (const args of [['--max-tools'], ['--max-seconds', 'NaN', 'task'], ['--no-delivery', '--max-tools', '1', 'task']]) {
+    const result = spawnSync(process.execPath, [cli, '-p', ...args], { cwd, encoding: 'utf8', timeout: 10000 });
+    assert.equal(result.status, 1, result.stderr);
+    assert.match(result.stderr, /Missing value|must be an integer|require the delivery/);
+  }
+});

package/tests/clipboard.test.mjs

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { clipboardCommands, clipboardWriteCommands, sanitizePaste, writeClipboard } from '../lib/tui/clipboard.mjs';
+
+test('clipboardCommands picks the platform clipboard tool', () => {
+  assert.deepEqual(clipboardCommands('darwin', {}), [['pbpaste', []]]);
+  assert.equal(clipboardCommands('win32', {})[0][0], 'powershell.exe');
+  const linux = clipboardCommands('linux', {});
+  assert.deepEqual(linux.map(c => c[0]), ['wl-paste', 'xclip', 'xsel']);
+});
+
+test('clipboardCommands adds PowerShell for WSL', () => {
+  const wsl = clipboardCommands('linux', { WSL_DISTRO_NAME: 'Ubuntu' });
+  assert.equal(wsl.at(-1)[0], 'powershell.exe');
+  const notWsl = clipboardCommands('linux', {});
+  assert.ok(!notWsl.some(c => c[0] === 'powershell.exe'));
+});
+
+test('clipboardWriteCommands picks the platform clipboard tool', () => {
+  assert.deepEqual(clipboardWriteCommands('darwin', {}), [['pbcopy', []]]);
+  const win32 = clipboardWriteCommands('win32', {});
+  assert.deepEqual(win32.map(c => c[0]), ['powershell.exe']);
+  const linux = clipboardWriteCommands('linux', {});
+  assert.deepEqual(linux.map(c => c[0]), ['wl-copy', 'xclip', 'xsel']);
+});
+
+test('clipboardWriteCommands adds PowerShell for WSL', () => {
+  const wsl = clipboardWriteCommands('linux', { WSL_DISTRO_NAME: 'Ubuntu' });
+  assert.equal(wsl.at(-1)[0], 'powershell.exe');
+  const notWsl = clipboardWriteCommands('linux', {});
+  assert.ok(!notWsl.some(c => c[0] === 'clip.exe' || c[0] === 'powershell.exe'));
+});
+
+test('writeClipboard resolves safely when tools are absent', async () => {
+  // On Linux test runner without display/tools or non-existent platform, writeClipboard resolves false without rejecting
+  const res = await writeClipboard('test text', { platform: 'unknown-platform' });
+  assert.equal(res, false);
+});
+
+test('writeClipboard pipes text to child stdin and resolves true', async () => {
+  // Test piping using node command
+  const res = await writeClipboard('hello from carthagent', {
+    commands: [[process.execPath, ['-e', 'process.stdin.resume(); process.stdin.on("data", () => process.exit(0))']]],
+  });
+  assert.equal(res, true);
+});
+
+test('Windows and WSL clipboard routes declare Unicode encodings', () => {
+  for (const [platform, env] of [['win32', {}], ['linux', { WSL_INTEROP: 'yes' }]]) {
+    const commands = clipboardWriteCommands(platform, env);
+    assert.ok(!commands.some(c => c[0] === 'clip.exe'));
+    assert.match(commands.find(c => c[0] === 'powershell.exe')[1].at(-1), /InputEncoding.*UTF8Encoding/);
+    assert.match(clipboardCommands(platform, env).find(c => c[0] === 'powershell.exe')[1].at(-1), /OutputEncoding.*UTF8Encoding/);
+  }
+});
+
+test('clipboard subprocess receives exact UTF-8 Unicode bytes without BOM', async () => {
+  const text = '● MESSAGES │ café ✓\n┬ · 日本語 😀';
+  {
+    const expected = Buffer.from(text, 'utf8').toString('hex');
+    const script = 'const chunks=[]; process.stdin.on("data", c=>chunks.push(c)); process.stdin.on("end",()=>{process.exitCode=Buffer.concat(chunks).toString("hex")===process.argv[1]?0:1;});';
+    assert.equal(await writeClipboard(text, { commands: [[process.execPath, ['-e', script, expected]]] }), true);
+  }
+});
+
+test('sanitizePaste strips whitespace and control bytes for single-line fields', () => {
+  assert.equal(sanitizePaste('  sk-abc\n\n'), 'sk-abc');
+  assert.equal(sanitizePaste('sk-abc\r\ndef'), 'sk-abcdef');
+  assert.equal(sanitizePaste('a\tb c'), 'abc');
+  assert.equal(sanitizePaste('code\u0007\u001b'), 'code');
+  assert.equal(sanitizePaste(null), '');
+  assert.equal(sanitizePaste(undefined), '');
+});
+
+test('sanitizePaste keeps newlines but drops control junk in multiline mode', () => {
+  assert.equal(sanitizePaste('line1\r\nline2', { multiline: true }), 'line1\nline2');
+  assert.equal(sanitizePaste('a\u0007b', { multiline: true }), 'ab');
+  assert.equal(sanitizePaste('  keep spaces  ', { multiline: true }), '  keep spaces  ');
+});

package/tests/cloud-client.test.mjs

@@ -0,0 +1,129 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CloudClient, cloudControlUrl, cloudManagedUsageRecovery, formatCloudAccount, formatCloudUsage, formatNanoUsd, oauthCredentials, openBrowser } from '../lib/cloud/client.mjs';
+
+function response(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+test('browser opening uses platform launchers and rejects non-HTTP targets', async () => {
+  const calls = [];
+  const spawnImpl = (command, args) => {
+    calls.push({ command, args });
+    return { once(event, callback) { if (event === 'spawn') queueMicrotask(callback); return this; }, unref() {} };
+  };
+  assert.equal(await openBrowser('https://cloud.test/path?a=1', { platform: 'linux', env: {}, spawnImpl }), true);
+  assert.equal(calls[0].command, 'xdg-open');
+  assert.deepEqual(calls[0].args, ['https://cloud.test/path?a=1']);
+  assert.equal(await openBrowser('file:///tmp/secret', { spawnImpl }), false);
+});
+
+test('Cloud client resolves the control-plane URL and formats integer nano-USD', () => {
+  assert.equal(cloudControlUrl({}), 'https://api.carthagent.xyz');
+  assert.equal(cloudControlUrl({ CARTHAGENT_CLOUD_URL: ' https://preview.test/v1/ ' }), 'https://preview.test/v1');
+  assert.equal(formatNanoUsd(1_230_000_000), '$1.23');
+  assert.equal(formatNanoUsd(-10_000_000), '-$0.01');
+  assert.equal(formatNanoUsd(1.5), 'unavailable');
+});
+
+test('Cloud device flow reports the code, tolerates pending, and returns rotating credentials', async () => {
+  const calls = [];
+  let polls = 0;
+  const client = new CloudClient({
+    baseUrl: 'https://cloud.test', sleep: async () => {},
+    fetchImpl: async (url, options) => {
+      calls.push({ url, options });
+      if (url.endsWith('/v1/device/authorizations')) return response(201, {
+        deviceCode: 'ctgd_secret', userCode: 'ABCDE-12345', verificationUri: 'https://cloud.test/activate',
+        verificationUriComplete: 'https://cloud.test/activate?code=ABCDE-12345', expiresIn: 600, interval: 1,
+      });
+      polls++;
+      if (polls === 1) return response(428, { error: 'authorization_pending' });
+      return response(200, { accessToken: 'access', refreshToken: 'refresh', expiresIn: 900 });
+    },
+  });
+  const events = [];
+  const tokens = await client.authorizeDevice({ notify: event => events.push(event), signal: new AbortController().signal });
+  assert.equal(tokens.accessToken, 'access');
+  assert.equal(events[0].type, 'device_code');
+  assert.equal(events[0].verificationUri, 'https://cloud.test/activate?code=ABCDE-12345');
+  assert.ok(events.some(event => event.type === 'progress'));
+  assert.equal(calls.length, 3);
+});
+
+test('Cloud client surfaces denial, expiry, cancellation, and HTTP errors without secrets', async () => {
+  const denied = new CloudClient({ baseUrl: 'https://cloud.test', fetchImpl: async url => url.endsWith('/authorizations')
+    ? response(201, { deviceCode: 'secret-device', userCode: 'DENY-1', verificationUri: 'https://verify', expiresIn: 60, interval: 1 })
+    : response(401, { error: 'access_denied' }) });
+  await assert.rejects(denied.authorizeDevice(), error => error.code === 'access_denied' && !error.message.includes('secret-device'));
+
+  const controller = new AbortController();
+  controller.abort(new Error('cancelled'));
+  await assert.rejects(new CloudClient().authorizeDevice({ signal: controller.signal }), /cancelled/);
+
+  const expired = new CloudClient({
+    baseUrl: 'https://cloud.test', sleep: async () => {},
+    fetchImpl: async url => url.endsWith('/authorizations')
+      ? response(201, { deviceCode: 'd', userCode: 'E', verificationUri: 'https://verify', expiresIn: -1, interval: 1 })
+      : response(428, { error: 'authorization_pending' }),
+  });
+  await assert.rejects(expired.authorizeDevice(), error => error.code === 'expired_token');
+});
+
+test('Cloud client sends account, billing, and session requests with bearer auth', async () => {
+  const requests = [];
+  const client = new CloudClient({ baseUrl: 'https://cloud.test', fetchImpl: async (url, options) => {
+    requests.push({ url, options });
+    return response(200, url.includes('/account/usage') ? { accountId: 'a', data: [] } : url.endsWith('/account') ? { accountId: 'a', balance: { availableNanoUsd: 1_000_000_000 }, subscription: { status: 'active' }, sessions: [] } : { url: 'https://stripe.test' });
+  } });
+  const account = await client.account({ accessToken: 'access' });
+  const usage = await client.usage({ accessToken: 'access', limit: 500 });
+  await client.checkout({ accessToken: 'access', successUrl: 'https://return', cancelUrl: 'https://return' });
+  await client.portal({ accessToken: 'access', returnUrl: 'https://return' });
+  await client.revokeSession({ accessToken: 'access', sessionId: 'session/1' });
+  assert.equal(account.accountId, 'a');
+  assert.deepEqual(usage.data, []);
+  assert.match(requests[1].url, /\/v1\/account\/usage\?limit=200$/);
+  assert.ok(requests.every(item => item.options.headers.authorization === 'Bearer access'));
+  assert.match(requests.at(-1).url, /session%2F1$/);
+});
+
+test('OAuth and account formatters keep token expiration and account UX deterministic', () => {
+  assert.deepEqual(oauthCredentials({ accessToken: 'a', refreshToken: 'r', expiresIn: 900 }, 1_000), { access: 'a', refresh: 'r', expires: 901_000 });
+  assert.match(formatCloudAccount({ accountId: 'acct', balance: { availableNanoUsd: 1_000_000_000 }, subscription: { status: 'none' }, sessions: [{}, { revoked_at: 'x' }] }), /Credit: \$1\.00 available[\s\S]*Plan: Free[\s\S]*1 active, 1 revoked/);
+  const managed = formatCloudAccount({
+    accountId: 'paid', balance: { availableNanoUsd: 8_000_000_000 },
+    subscription: { status: 'active', current_period_end: 1_800_000_000 },
+    managedUsage: {
+      planName: 'Pro',
+      periodEnd: 1_800_000_000,
+      monthly: { allowanceNanoUsd: 8_000_000_000, reservedNanoUsd: 250_000_000, availableNanoUsd: 6_750_000_000 },
+      daily: { limitNanoUsd: 500_000_000, reservedNanoUsd: 50_000_000, availableNanoUsd: 300_000_000, resetsAt: '2027-01-02T00:00:00.000Z' },
+    }, sessions: [],
+  });
+  assert.match(managed, /Plan: Pro \(active\)/);
+  assert.match(managed, /monthly\s+16%\s+▓▓▓░░░░░░░░░░░░░\s+renews Jan 15/);
+  assert.match(managed, /daily\s+40%\s+▓▓▓▓▓▓░░░░░░░░░░\s+resets 00:00 UTC/);
+  const usage = { data: [
+    { createdAt: '2027-01-01T12:00:00.000Z', alias: 'gpt-6-luna', inputTokens: 1200, outputTokens: 34, status: 'completed' },
+    { createdAt: '2027-01-01T11:00:00.000Z', alias: 'deepseek-v4-flash', inputTokens: 800, outputTokens: 6, status: 'failed' },
+  ] };
+  assert.match(formatCloudUsage(usage), /𐤀\s+SHIP · USAGE/);
+  assert.match(formatCloudUsage(usage), /last 5\s+gpt-6-luna · 1\.2k in \/ 34 out/);
+  assert.match(formatCloudUsage(usage), /deepseek-v4-flash · 800 in \/ 6 out · failed/);
+  assert.match(formatCloudUsage(usage, { account: { managedUsage: { planName: 'Pro', periodEnd: 1_800_000_000,
+    monthly: { allowanceNanoUsd: 21_000_000_000, availableNanoUsd: 12_600_000_000 },
+    daily: { limitNanoUsd: 1_200_000_000, availableNanoUsd: 1_200_000_000, resetsAt: '2027-01-02T00:00:00.000Z' } } } }),
+    /PRO · USAGE[\s\S]*monthly\s+40%[\s\S]*renews Jan 15[\s\S]*daily\s+0%/);
+  assert.match(formatCloudUsage(usage, { byok: true }), /external provider — not counted here/);
+  assert.match(formatCloudUsage({ data: [] }), /no settled requests yet/);
+  assert.match(formatCloudAccount({ accountId: 'acct', balance: { availableNanoUsd: 1_000_000_000 }, subscription: { status: 'none' }, sessions: [] }, { usage }), /SHIP · USAGE/);
+});
+
+test('managed usage recovery distinguishes daily, monthly, subscription, and credit paths', () => {
+  assert.match(cloudManagedUsageRecovery('daily_limit_reached'), /00:00 UTC/);
+  assert.match(cloudManagedUsageRecovery('monthly_allowance_exhausted'), /billing portal/);
+  assert.match(cloudManagedUsageRecovery({ code: 'subscription_inactive' }), /subscription is inactive/);
+  assert.match(cloudManagedUsageRecovery('insufficient_quota'), /billing checkout/);
+  assert.equal(cloudManagedUsageRecovery('upstream timeout'), null);
+});