carthagent 0.0.0-stage → 1.0.7

package/tests/cloud-control-plane.test.mjs

@@ -0,0 +1,144 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHmac } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import { CloudLedger } from '../lib/cloud/ledger.mjs';
+import { CLOUD_PLAN, CloudControlPlane, verifyStripeSignature } from '../lib/cloud/control-plane.mjs';
+
+test('CLI session client-name migration upgrades an existing SQLite schema', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`CREATE TABLE cli_sessions (
+    id TEXT PRIMARY KEY, account_id TEXT NOT NULL, refresh_token_hash TEXT NOT NULL UNIQUE,
+    scopes TEXT NOT NULL, expires_at INTEGER NOT NULL, revoked_at TEXT, created_at TEXT NOT NULL, last_used_at TEXT
+  )`);
+  db.exec(readFileSync(fileURLToPath(new URL('../migrations/003_cloud_cli_session_client_name.sql', import.meta.url)), 'utf8'));
+  db.prepare(`INSERT INTO cli_sessions
+    (id, account_id, refresh_token_hash, scopes, expires_at, created_at)
+    VALUES ('session', 'account', 'hash', 'account:read', 1, '2025-01-01T00:00:00.000Z')`).run();
+  assert.equal(db.prepare('SELECT client_name FROM cli_sessions').get().client_name, 'Carthagent CLI');
+});
+
+function fixture(overrides = {}) {
+  let id = 0;
+  let random = 0;
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  const ledger = new CloudLedger({ id: () => `ledger-${++id}`, clock: () => now });
+  const control = new CloudControlPlane({
+    ledger, clock: () => now, id: () => `control-${++id}`,
+    random: size => Buffer.alloc(size, ++random), tokenSecret: 'test-token-secret',
+    publicUrl: 'https://cloud.test', ...overrides,
+  });
+  return { control, ledger, now };
+}
+
+test('device authorization approves once, grants trial once, and issues scoped rotating tokens', () => {
+  const { control, ledger } = fixture();
+  const account = control.createUserAccount({ email: 'user@example.com' });
+  const device = control.createDeviceAuthorization({ clientName: 'laptop' });
+  assert.equal(device.verificationUri, 'https://cloud.test/activate');
+  assert.throws(() => control.pollDeviceToken({ deviceCode: device.deviceCode }), /authorization_pending/);
+  assert.deepEqual(control.approveDeviceAuthorization({ userCode: device.userCode, accountId: account.accountId }), { approved: true, clientName: 'laptop' });
+  assert.equal(ledger.available(account.accountId), CLOUD_PLAN.trialNanoUsd);
+  const tokens = control.pollDeviceToken({ deviceCode: device.deviceCode });
+  const claims = control.verifyAccessToken(tokens.accessToken, 'gateway:invoke');
+  assert.equal(control.listSessions(account.accountId)[0].client_name, 'laptop');
+  assert.equal(control.listSessions(account.accountId)[0].last_used_at, control.nowIso());
+  assert.equal(claims.sub, account.accountId);
+  assert.throws(() => control.pollDeviceToken({ deviceCode: device.deviceCode }), /invalid_grant/);
+  const refreshed = control.refreshSession({ refreshToken: tokens.refreshToken });
+  assert.notEqual(refreshed.refreshToken, tokens.refreshToken);
+  assert.throws(() => control.refreshSession({ refreshToken: tokens.refreshToken }), /invalid_grant/);
+  control.revokeSession({ sessionId: claims.sid });
+  assert.throws(() => control.verifyAccessToken(refreshed.accessToken), /revoked_token/);
+  assert.equal(control.claimTrial(account.accountId).claimed, false);
+});
+
+test('device denial does not create a session or grant', () => {
+  const { control, ledger } = fixture();
+  const account = control.createUserAccount({ email: 'deny@example.com' });
+  const device = control.createDeviceAuthorization();
+  control.approveDeviceAuthorization({ userCode: device.userCode, accountId: account.accountId, approve: false });
+  assert.throws(() => control.pollDeviceToken({ deviceCode: device.deviceCode }), /access_denied/);
+  assert.equal(ledger.available(account.accountId), 0);
+});
+
+test('account details expose content-free grants, sessions, usage, and account-scoped revocation', () => {
+  const { control, ledger } = fixture();
+  const account = control.createUserAccount({ email: 'account@example.com' });
+  control.claimTrial(account.accountId);
+  const one = control.issueSession(account.accountId, undefined, 'laptop');
+  const two = control.issueSession(account.accountId, undefined, 'desktop');
+  const secondClaims = control.verifyAccessToken(two.accessToken);
+  ledger.appendEntry({ accountId: account.accountId, kind: 'charge', amountNanoUsd: -10, idempotencyKey: 'usage-1', gatewayRequestId: 'request-1', gatewayAttemptId: 'attempt-1', metadata: { alias: 'code', inputTokens: 2, outputTokens: 3, status: 'completed' } });
+  const details = control.account(account.accountId);
+  assert.equal(details.email, 'account@example.com');
+  assert.equal(details.grants[0].source, 'verified_trial');
+  assert.deepEqual(details.sessions.map(session => session.client_name).sort(), ['desktop', 'laptop']);
+  assert.deepEqual(control.usage(account.accountId), [{ createdAt: control.nowIso(), alias: 'code', inputTokens: 2, outputTokens: 3, status: 'completed', chargeNanoUsd: 10, gatewayRequestId: 'request-1', gatewayAttemptId: 'attempt-1' }]);
+  assert.deepEqual(control.revokeAccountSession({ accountId: account.accountId, sessionId: secondClaims.sid }), { revoked: true, sessionId: secondClaims.sid });
+  assert.throws(() => control.verifyAccessToken(two.accessToken), /revoked_token/);
+  assert.doesNotThrow(() => control.verifyAccessToken(one.accessToken));
+  assert.throws(() => control.revokeAccountSession({ accountId: 'other', sessionId: secondClaims.sid }), /session_not_found/);
+});
+
+test('Stripe signatures are verified with timestamp tolerance', () => {
+  const payload = '{"id":"evt_1"}';
+  const timestamp = 1_767_225_600;
+  const secret = 'whsec_test';
+  const digest = createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex');
+  assert.equal(verifyStripeSignature(payload, `t=${timestamp},v1=${digest}`, secret, { now: timestamp * 1000 }), true);
+  assert.throws(() => verifyStripeSignature(payload, `t=${timestamp},v1=bad`, secret, { now: timestamp * 1000 }), /Invalid Stripe signature/);
+});
+
+test('authoritative invoice webhook grants Builder credit exactly once', () => {
+  const secret = 'whsec_test';
+  const { control, ledger } = fixture({ stripeWebhookSecret: secret, stripePriceId: 'price_builder' });
+  const account = control.createUserAccount({ email: 'builder@example.com' });
+  const event = {
+    id: 'evt_invoice_1', type: 'invoice.paid', data: { object: {
+      id: 'in_1', customer: 'cus_1', subscription: 'sub_1', period_start: 1_767_225_600,
+      period_end: 1_769_904_000, metadata: { accountId: account.accountId },
+    } },
+  };
+  const payload = JSON.stringify(event);
+  const timestamp = 1_767_225_600;
+  const signature = `t=${timestamp},v1=${createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex')}`;
+  assert.deepEqual(control.handleStripeWebhook({ payload, signature }), { duplicate: false, processed: true });
+  assert.deepEqual(control.handleStripeWebhook({ payload, signature }), { duplicate: true });
+  assert.equal(ledger.available(account.accountId), CLOUD_PLAN.builderMonthlyNanoUsd);
+  assert.equal(control.subscription(account.accountId).status, 'active');
+});
+
+test('Checkout resolves plan selectors against the configured catalog', async () => {
+  const calls = [];
+  const stripe = {
+    createCheckoutSession: async input => { calls.push(input.line_items); return { id: 'cs_1', url: 'https://checkout.test' }; },
+    createPortalSession: async () => ({ id: 'bps_1', url: 'https://portal.test' }),
+  };
+  const { control } = fixture({ stripe, stripePriceId: 'price_builder', planCatalog: { pro: 'price_pro' } });
+  const account = control.createUserAccount({ email: 'tier@example.com' });
+  await control.createCheckout({ accountId: account.accountId, successUrl: 'https://app/s', cancelUrl: 'https://app/c' });
+  await control.createCheckout({ accountId: account.accountId, successUrl: 'https://app/s', cancelUrl: 'https://app/c', priceId: 'pro' });
+  await control.createCheckout({ accountId: account.accountId, successUrl: 'https://app/s', cancelUrl: 'https://app/c', priceId: 'price_pro' });
+  assert.deepEqual(calls, [[{ price: 'price_builder', quantity: 1 }], [{ price: 'price_pro', quantity: 1 }], [{ price: 'price_pro', quantity: 1 }]]);
+  await assert.rejects(control.createCheckout({ accountId: account.accountId, priceId: 'price_nope' }), /billing_not_configured/);
+});
+
+test('Checkout and portal use server-owned plan and customer references', async () => {
+  const calls = [];
+  const stripe = {
+    createCheckoutSession: async input => { calls.push(['checkout', input]); return { id: 'cs_1', url: 'https://checkout.test' }; },
+    createPortalSession: async input => { calls.push(['portal', input]); return { id: 'bps_1', url: 'https://portal.test' }; },
+  };
+  const { control } = fixture({ stripe, stripePriceId: 'price_server_owned' });
+  const account = control.createUserAccount({ email: 'pay@example.com' });
+  const checkout = await control.createCheckout({ accountId: account.accountId, successUrl: 'https://app/success', cancelUrl: 'https://app/cancel' });
+  assert.equal(checkout.url, 'https://checkout.test');
+  assert.equal(calls[0][1].line_items[0].price, 'price_server_owned');
+  control.upsertSubscription(account.accountId, { id: 'sub_1', customer: 'cus_1', status: 'active' });
+  const portal = await control.createPortal({ accountId: account.accountId, returnUrl: 'https://app/account' });
+  assert.equal(portal.url, 'https://portal.test');
+  assert.equal(calls[1][1].customer, 'cus_1');
+});

package/tests/cloud-gateway.test.mjs

@@ -0,0 +1,147 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CloudLedger } from '../lib/cloud/ledger.mjs';
+import { CloudControlPlane } from '../lib/cloud/control-plane.mjs';
+import {
+  CloudGatewayAuthority, ExperientialGatewayClient, GatewayDispatchError,
+  boundedGatewayRequest, customerChargeNanoUsd, tokenChargeNanoUsd,
+} from '../lib/cloud/gateway.mjs';
+
+function fixture({ upstream, settlementSource } = {}) {
+  let id = 0;
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  const ledger = new CloudLedger({ id: () => `ledger-${++id}`, clock: () => now });
+  const control = new CloudControlPlane({ ledger, id: () => `control-${++id}`, clock: () => now, tokenSecret: 'secret' });
+  const account = control.createUserAccount({ email: 'gateway@example.com' });
+  const gateway = new CloudGatewayAuthority({ control, ledger, id: () => `gateway-${++id}`, clock: () => now, upstream, settlementSource });
+  gateway.publishPricing({ id: 'price-v1', inputNanoUsdPerMillionTokens: 1_000_000, outputNanoUsdPerMillionTokens: 2_000_000, fixedRequestNanoUsd: 50 });
+  gateway.publishAlias({
+    alias: 'carthagent-code', displayName: 'Carthagent Code', upstreamAlias: 'experiential-code', pricingVersionId: 'price-v1', revisionId: 'code-v1',
+    maxInputTokens: 100_000, defaultMaxOutputTokens: 100, maxOutputTokens: 1_000, maximumAttempts: 2,
+  });
+  return { ledger, control, account, gateway };
+}
+
+const upstreamResponse = ({ requestId = 'exp-request-1', body = { usage: { prompt_tokens: 10, completion_tokens: 5 } }, status = 200 } = {}) => new Response(JSON.stringify(body), {
+  status,
+  headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+});
+
+test('pricing rounds each token leg up in integer nano-USD', () => {
+  assert.equal(tokenChargeNanoUsd(1, 1), 1);
+  assert.equal(tokenChargeNanoUsd(1_000_001, 1_000_000), 1_000_001);
+  assert.equal(customerChargeNanoUsd({ input_nano_usd_per_million_tokens: 1_000_000, output_nano_usd_per_million_tokens: 2_000_000, fixed_request_nano_usd: 50 }, [{ inputTokens: 10, outputTokens: 5 }]), 70);
+});
+
+test('request bounding applies a server output cap and rewrites only the model alias', () => {
+  const bounded = boundedGatewayRequest('chat.completions', { model: 'carthagent-code', messages: [{ role: 'user', content: 'hello' }] }, {
+    alias: 'carthagent-code', upstream_alias: 'experiential-code', max_input_tokens: 10_000,
+    default_max_output_tokens: 128, max_output_tokens: 256,
+  });
+  assert.equal(bounded.request.model, 'experiential-code');
+  assert.equal(bounded.request.max_tokens, 128);
+  assert.throws(() => boundedGatewayRequest('responses', { model: 'carthagent-code', input: 'hello', max_output_tokens: 300 }, {
+    alias: 'carthagent-code', upstream_alias: 'experiential-code', max_input_tokens: 10_000,
+    default_max_output_tokens: 128, max_output_tokens: 256,
+  }), /max_output_tokens_exceeded/);
+});
+
+test('aliases and prices are immutable versions while the current revision may advance', () => {
+  const { gateway, ledger } = fixture();
+  assert.deepEqual(gateway.models(), [{ id: 'carthagent-code', name: 'Carthagent Code' }]);
+  assert.throws(() => gateway.publishPricing({ id: 'price-v1', inputNanoUsdPerMillionTokens: 2, outputNanoUsdPerMillionTokens: 2 }), /pricing_version_immutable_conflict/);
+  gateway.publishPricing({ id: 'price-v2', inputNanoUsdPerMillionTokens: 2_000_000, outputNanoUsdPerMillionTokens: 3_000_000 });
+  gateway.publishAlias({
+    alias: 'carthagent-code', displayName: 'Carthagent Code', upstreamAlias: 'experiential-code-v2', pricingVersionId: 'price-v2', revisionId: 'code-v2',
+    maxInputTokens: 100_000, defaultMaxOutputTokens: 100, maxOutputTokens: 1_000,
+  });
+  assert.equal(gateway.resolveAlias('carthagent-code').id, 'code-v2');
+  assert.equal(gateway.db.prepare('SELECT COUNT(*) AS count FROM cloud_model_alias_revisions').get().count, 2);
+  ledger.close();
+});
+
+test('authority reserves before dispatch and settles only from authoritative request and attempt facts', async () => {
+  const events = [];
+  const upstream = { dispatch: async input => { events.push(['dispatch', input.body.model]); return upstreamResponse(); } };
+  const settlementSource = { resolve: async () => ({
+    status: 'terminal', requestId: 'exp-request-1', terminalState: 'completed', attempts: [
+      { attemptId: 'exp-attempt-1', state: 'failed', inputTokens: 100, outputTokens: 0 },
+      { attemptId: 'exp-attempt-2', state: 'completed', inputTokens: 100, outputTokens: 50 },
+    ],
+  }) };
+  const { gateway, ledger, account } = fixture({ upstream, settlementSource });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 10_000_000, idempotencyKey: 'grant' });
+  const before = ledger.available(account.accountId);
+  const handle = await gateway.invoke({ accountId: account.accountId, endpoint: 'chat.completions', operationKey: 'op-1', body: { model: 'carthagent-code', messages: [{ role: 'user', content: 'hello' }], max_tokens: 100 } });
+  assert.equal(events.length, 1);
+  assert.ok(ledger.available(account.accountId) < before);
+  assert.equal(handle.revision.id, 'code-v1');
+  const settled = await gateway.finalize(handle, { responseBody: Buffer.from(await handle.response.text()) });
+  assert.equal(settled.state, 'settled');
+  assert.equal(settled.gateway_request_id, 'exp-request-1');
+  assert.equal(settled.attempts.length, 2);
+  assert.equal(settled.customer_charge_nano_usd, 350);
+  assert.equal(ledger.entries(account.accountId).find(entry => entry.kind === 'charge').gateway_attempt_id, 'exp-attempt-2');
+  ledger.close();
+});
+
+test('known pre-dispatch failures release the full reservation', async () => {
+  const upstream = { dispatch: async () => { throw new GatewayDispatchError('offline', { outcome: 'not_dispatched' }); } };
+  const { gateway, ledger, account } = fixture({ upstream });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 1_000_000, idempotencyKey: 'grant' });
+  const before = ledger.available(account.accountId);
+  await assert.rejects(gateway.invoke({ accountId: account.accountId, endpoint: 'responses', operationKey: 'known-failure', body: { model: 'carthagent-code', input: 'hello' } }), /offline/);
+  assert.equal(ledger.available(account.accountId), before);
+  assert.equal(gateway.db.prepare('SELECT state FROM cloud_gateway_requests WHERE operation_key = ?').get('known-failure').state, 'released_not_dispatched');
+  ledger.close();
+});
+
+test('unknown transport and unknown settlement outcomes fail closed with credit held', async () => {
+  const upstream = { dispatch: async () => { throw new GatewayDispatchError('timeout', { outcome: 'unknown' }); } };
+  const { gateway, ledger, account } = fixture({ upstream });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 1_000_000, idempotencyKey: 'grant' });
+  const before = ledger.available(account.accountId);
+  await assert.rejects(gateway.invoke({ accountId: account.accountId, endpoint: 'responses', operationKey: 'ambiguous', body: { model: 'carthagent-code', input: 'hello' } }), /timeout/);
+  assert.ok(ledger.available(account.accountId) < before);
+  assert.equal(gateway.db.prepare('SELECT state FROM cloud_gateway_requests WHERE operation_key = ?').get('ambiguous').state, 'reconciliation_required');
+  assert.equal(ledger.entries(account.accountId).some(entry => entry.kind === 'reservation_release'), false);
+  ledger.close();
+});
+
+test('missing authoritative attempt identity leaves a successful HTTP result in reconciliation', async () => {
+  const upstream = { dispatch: async () => upstreamResponse() };
+  const settlementSource = { resolve: async () => ({ status: 'pending' }) };
+  const { gateway, ledger, account } = fixture({ upstream, settlementSource });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 1_000_000, idempotencyKey: 'grant' });
+  const handle = await gateway.invoke({ accountId: account.accountId, endpoint: 'responses', operationKey: 'pending', body: { model: 'carthagent-code', input: 'hello' } });
+  const result = await gateway.finalize(handle, { responseBody: Buffer.from(await handle.response.text()) });
+  assert.equal(result.state, 'reconciliation_required');
+  assert.equal(ledger.entries(account.accountId).some(entry => entry.kind === 'charge'), false);
+  ledger.close();
+});
+
+test('a later reconciliation settles against the request frozen pricing revision', async () => {
+  const upstream = { dispatch: async () => upstreamResponse() };
+  const settlementSource = { resolve: async () => ({ status: 'pending' }) };
+  const { gateway, ledger, account } = fixture({ upstream, settlementSource });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 1_000_000, idempotencyKey: 'grant' });
+  const handle = await gateway.invoke({ accountId: account.accountId, endpoint: 'responses', operationKey: 'late', body: { model: 'carthagent-code', input: 'hello', max_output_tokens: 10 } });
+  await gateway.finalize(handle, { responseBody: Buffer.from(await handle.response.text()) });
+  gateway.publishPricing({ id: 'price-v2', inputNanoUsdPerMillionTokens: 9_000_000, outputNanoUsdPerMillionTokens: 9_000_000 });
+  gateway.publishAlias({ alias: 'carthagent-code', displayName: 'Carthagent Code', upstreamAlias: 'new-upstream', pricingVersionId: 'price-v2', revisionId: 'code-v2', maxInputTokens: 100_000, defaultMaxOutputTokens: 100, maxOutputTokens: 1_000 });
+  const reconciled = await gateway.reconcile(handle.id, { status: 'terminal', requestId: 'exp-request-1', terminalState: 'completed', attempts: [{ attemptId: 'late-attempt', state: 'completed', inputTokens: 10, outputTokens: 5 }] });
+  assert.equal(reconciled.state, 'settled');
+  assert.equal(reconciled.pricing_version_id, 'price-v1');
+  assert.equal(reconciled.customer_charge_nano_usd, 70);
+  ledger.close();
+});
+
+test('Experiential client authenticates and sends stable gateway correlation headers', async () => {
+  let seen;
+  const client = new ExperientialGatewayClient({ baseUrl: 'https://gateway.test/v1/', apiKey: 'test-key', fetchImpl: async (url, options) => { seen = { url, options }; return upstreamResponse(); } });
+  await client.dispatch({ endpoint: 'chat.completions', body: { model: 'alias' }, operationKey: 'operation-1', clientRequestId: 'client-1' });
+  assert.equal(seen.url, 'https://gateway.test/v1/chat/completions');
+  assert.equal(seen.options.headers.authorization, 'Bearer test-key');
+  assert.equal(seen.options.headers['idempotency-key'], 'operation-1');
+  assert.equal(seen.options.headers['x-client-request-id'], 'client-1');
+});

package/tests/cloud-http.test.mjs

@@ -0,0 +1,102 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import express from 'express';
+import { CloudLedger } from '../lib/cloud/ledger.mjs';
+import { CloudControlPlane } from '../lib/cloud/control-plane.mjs';
+import { cloudRouter } from '../lib/cloud/http.mjs';
+import { CloudGatewayAuthority } from '../lib/cloud/gateway.mjs';
+
+async function fixture(t, { withGateway = false } = {}) {
+  let id = 0;
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  const ledger = new CloudLedger({ id: () => `l-${++id}`, clock: () => now });
+  const control = new CloudControlPlane({ ledger, id: () => `c-${++id}`, clock: () => now, random: size => Buffer.alloc(size, 7), tokenSecret: 'secret', publicUrl: 'https://cloud.test' });
+  const account = control.createUserAccount({ email: 'api@example.com' });
+  let gateway = null;
+  if (withGateway) {
+    gateway = new CloudGatewayAuthority({
+      control, ledger, id: () => `g-${++id}`, clock: () => now,
+      upstream: { dispatch: async () => new Response(JSON.stringify({ usage: { prompt_tokens: 12, completion_tokens: 3 } }), { status: 200, headers: { 'content-type': 'application/json', 'x-request-id': 'exp-http-request' } }) },
+      settlementSource: { resolve: async () => ({ status: 'terminal', requestId: 'exp-http-request', terminalState: 'completed', attempts: [{ attemptId: 'exp-http-attempt', state: 'completed', inputTokens: 12, outputTokens: 3 }] }) },
+    });
+    gateway.publishPricing({ id: 'http-price', inputNanoUsdPerMillionTokens: 1_000_000, outputNanoUsdPerMillionTokens: 2_000_000 });
+    gateway.publishAlias({ alias: 'carthagent-code', displayName: 'Carthagent Code', upstreamAlias: 'upstream-code', pricingVersionId: 'http-price', revisionId: 'http-revision', maxInputTokens: 100_000, defaultMaxOutputTokens: 100, maxOutputTokens: 1_000 });
+  }
+  const app = express();
+  app.use(cloudRouter(control, { gateway, authenticateBrowser: async req => req.get('x-test-account') === account.accountId ? account : null }));
+  const server = app.listen(0, '127.0.0.1');
+  await new Promise(resolve => server.once('listening', resolve));
+  t.after(() => { server.close(); ledger.close(); });
+  return { base: `http://127.0.0.1:${server.address().port}`, account, control, gateway, ledger };
+}
+
+const json = body => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+test('HTTP device flow returns OAuth-style pending, token, account, and revoke responses', async t => {
+  const { base, account } = await fixture(t);
+  const device = await (await fetch(`${base}/v1/device/authorizations`, json({ clientName: 'test cli' }))).json();
+  const pending = await fetch(`${base}/v1/device/token`, json({ deviceCode: device.deviceCode }));
+  assert.equal(pending.status, 428);
+  const approved = await fetch(`${base}/v1/device/authorizations/${device.userCode}/approve`, {
+    ...json({ approve: true }), headers: { ...json({}).headers, 'x-test-account': account.accountId },
+  });
+  assert.equal(approved.status, 200);
+  const tokens = await (await fetch(`${base}/v1/device/token`, json({ deviceCode: device.deviceCode }))).json();
+  const accountResponse = await fetch(`${base}/v1/account`, { headers: { authorization: `Bearer ${tokens.accessToken}` } });
+  assert.equal(accountResponse.status, 200);
+  const accountBody = await accountResponse.json();
+  assert.equal(accountBody.balance.availableNanoUsd, 1_000_000_000);
+  assert.equal(accountBody.email, 'api@example.com');
+  assert.equal(accountBody.grants[0].source, 'verified_trial');
+  const balance = await (await fetch(`${base}/v1/account/balance`, { headers: { authorization: `Bearer ${tokens.accessToken}` } })).json();
+  assert.equal(balance.grants[0].remainingNanoUsd, 1_000_000_000);
+  const sessions = await (await fetch(`${base}/v1/account/sessions`, { headers: { authorization: `Bearer ${tokens.accessToken}` } })).json();
+  assert.equal(sessions.currentSessionId, sessions.data[0].id);
+  assert.equal(sessions.data[0].client_name, 'test cli');
+  assert.equal((await fetch(`${base}/v1/token/revoke`, { method: 'POST', headers: { authorization: `Bearer ${tokens.accessToken}` } })).status, 200);
+  assert.equal((await fetch(`${base}/v1/account`, { headers: { authorization: `Bearer ${tokens.accessToken}` } })).status, 401);
+});
+
+test('HTTP gateway exposes authenticated aliases and proxies a settled OpenAI-compatible request', async t => {
+  const { base, account, control, ledger } = await fixture(t, { withGateway: true });
+  ledger.grant({ accountId: account.accountId, amountNanoUsd: 1_000_000, idempotencyKey: 'http-credit' });
+  const tokens = control.issueSession(account.accountId);
+  const headers = { authorization: `Bearer ${tokens.accessToken}`, 'content-type': 'application/json', 'idempotency-key': 'http-operation' };
+  const modelsResponse = await fetch(`${base}/v1/models`, { headers });
+  assert.equal(modelsResponse.status, 200);
+  assert.deepEqual((await modelsResponse.json()).data.map(model => model.id), ['carthagent-code']);
+  const response = await fetch(`${base}/v1/chat/completions`, { method: 'POST', headers, body: JSON.stringify({ model: 'carthagent-code', messages: [{ role: 'user', content: 'hello' }], max_tokens: 10 }) });
+  assert.equal(response.status, 200);
+  assert.equal(response.headers.get('x-request-id'), 'exp-http-request');
+  assert.deepEqual(await response.json(), { usage: { prompt_tokens: 12, completion_tokens: 3 } });
+  const usage = await (await fetch(`${base}/v1/account/usage`, { headers })).json();
+  assert.deepEqual(usage.data.map(item => ({ alias: item.alias, inputTokens: item.inputTokens, outputTokens: item.outputTokens })), [{ alias: 'carthagent-code', inputTokens: 12, outputTokens: 3 }]);
+  const request = ledger.db.prepare('SELECT * FROM cloud_gateway_requests WHERE operation_key = ?').get('http-operation');
+  assert.equal(request.state, 'settled');
+  assert.equal(request.gateway_request_id, 'exp-http-request');
+});
+
+test('HTTP account sessions can be listed and revoked only by their account', async t => {
+  const { base, account, control } = await fixture(t);
+  const current = control.issueSession(account.accountId, undefined, 'current');
+  control.random = size => Buffer.alloc(size, 8);
+  const other = control.issueSession(account.accountId, undefined, 'other device');
+  const otherClaims = control.verifyAccessToken(other.accessToken);
+  const headers = { authorization: `Bearer ${current.accessToken}` };
+  const response = await fetch(`${base}/v1/account/sessions/${otherClaims.sid}`, { method: 'DELETE', headers });
+  assert.equal(response.status, 200);
+  assert.throws(() => control.verifyAccessToken(other.accessToken), /revoked_token/);
+  const missing = await fetch(`${base}/v1/account/sessions/not-found`, { method: 'DELETE', headers });
+  assert.equal(missing.status, 404);
+});
+
+test('HTTP gateway rejects exhausted credit before upstream dispatch', async t => {
+  const { base, account, control } = await fixture(t, { withGateway: true });
+  const tokens = control.issueSession(account.accountId);
+  const response = await fetch(`${base}/v1/responses`, {
+    method: 'POST', headers: { authorization: `Bearer ${tokens.accessToken}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ model: 'carthagent-code', input: 'hello' }),
+  });
+  assert.equal(response.status, 429);
+  assert.equal((await response.json()).error.code, 'insufficient_quota');
+});

package/tests/cloud-ledger.test.mjs

@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CloudLedger, nanoUsd, validateFinancialMetadata } from '../lib/cloud/ledger.mjs';
+
+const NANO = 1_000_000_000;
+function ledger() {
+  let next = 0;
+  return new CloudLedger({ id: () => `id-${++next}`, clock: () => new Date('2026-01-01T00:00:00.000Z') });
+}
+
+test('ledger uses safe integer nano-USD and rejects customer-content metadata', () => {
+  assert.equal(nanoUsd(NANO), NANO);
+  assert.throws(() => nanoUsd(1.2), /safe integer/);
+  assert.throws(() => validateFinancialMetadata({ prompt: 'secret' }), /customer content/);
+  assert.throws(() => validateFinancialMetadata({ toolArguments: 'secret' }), /customer content/);
+  assert.deepEqual(validateFinancialMetadata({ alias: 'carthagent-fast', inputTokens: 12, success: true }), { alias: 'carthagent-fast', inputTokens: 12, success: true });
+});
+
+test('grant and reservation are idempotent and reserve before dispatch', () => {
+  const store = ledger();
+  store.grant({ accountId: 'acct', amountNanoUsd: 10 * NANO, idempotencyKey: 'grant:1', source: 'trial' });
+  store.grant({ accountId: 'acct', amountNanoUsd: 10 * NANO, idempotencyKey: 'grant:1', source: 'trial' });
+  assert.equal(store.available('acct'), 10 * NANO);
+  const reservation = store.reserve({ accountId: 'acct', maximumNanoUsd: 3 * NANO, idempotencyKey: 'request:1' });
+  assert.equal(store.reserve({ accountId: 'acct', maximumNanoUsd: 3 * NANO, idempotencyKey: 'request:1' }).id, reservation.id);
+  assert.equal(store.available('acct'), 7 * NANO);
+  assert.throws(() => store.reserve({ accountId: 'acct', maximumNanoUsd: 8 * NANO, idempotencyKey: 'request:2' }), /insufficient_credit/);
+  store.close();
+});
+
+test('settlement charges measured usage and releases unused reservation', () => {
+  const store = ledger();
+  store.grant({ accountId: 'acct', amountNanoUsd: 10 * NANO, idempotencyKey: 'grant:1' });
+  const reservation = store.reserve({ accountId: 'acct', maximumNanoUsd: 4 * NANO, idempotencyKey: 'reserve:1' });
+  const charge = store.settle({
+    reservationId: reservation.id,
+    actualNanoUsd: 1_500_000_000,
+    requestId: 'xpl-request-1',
+    attemptId: 'xpl-attempt-1',
+    idempotencyKey: 'settle:1',
+    metadata: { alias: 'carthagent-code', inputTokens: 100, outputTokens: 20, status: 'ok' },
+  });
+  assert.equal(charge.gateway_request_id, 'xpl-request-1');
+  assert.equal(store.available('acct'), 8_500_000_000);
+  const entries = store.entries('acct');
+  assert.deepEqual(entries.map(entry => entry.kind), ['credit_grant', 'reservation', 'charge', 'reservation_release']);
+  assert.equal(entries.find(entry => entry.kind === 'charge').metadata.alias, 'carthagent-code');
+  assert.equal(JSON.stringify(entries).includes('prompt'), false);
+  assert.equal(store.settle({ reservationId: reservation.id, actualNanoUsd: 1_500_000_000, requestId: 'xpl-request-1', idempotencyKey: 'settle:1' }).id, charge.id);
+  store.close();
+});
+
+test('failed dispatch releases the complete reservation', () => {
+  const store = ledger();
+  store.grant({ accountId: 'acct', amountNanoUsd: 2 * NANO, idempotencyKey: 'grant:1' });
+  const reservation = store.reserve({ accountId: 'acct', maximumNanoUsd: NANO, idempotencyKey: 'reserve:1' });
+  const release = store.release({ reservationId: reservation.id, idempotencyKey: 'release:1' });
+  assert.equal(release.amount_nano_usd, NANO);
+  assert.equal(store.available('acct'), 2 * NANO);
+  assert.equal(store.release({ reservationId: reservation.id, idempotencyKey: 'release:1' }).id, release.id);
+  store.close();
+});
+
+test('earliest-expiring grants are consumed first', () => {
+  let now = new Date('2026-01-01T00:00:00.000Z');
+  let next = 0;
+  const store = new CloudLedger({ id: () => `id-${++next}`, clock: () => now });
+  store.grant({ accountId: 'acct', amountNanoUsd: NANO, idempotencyKey: 'later', expiresAt: '2026-03-01T00:00:00.000Z' });
+  store.grant({ accountId: 'acct', amountNanoUsd: NANO, idempotencyKey: 'sooner', expiresAt: '2026-02-01T00:00:00.000Z' });
+  const reservation = store.reserve({ accountId: 'acct', maximumNanoUsd: 1_500_000_000, idempotencyKey: 'reserve' });
+  store.settle({ reservationId: reservation.id, actualNanoUsd: 1_500_000_000, requestId: 'request', idempotencyKey: 'settle' });
+  now = new Date('2026-02-15T00:00:00.000Z');
+  assert.equal(store.available('acct'), 500_000_000);
+  store.close();
+});

package/tests/codegraph-query.test.mjs

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createCodeIndex } from '../lib/codegraph.mjs';
+import { queryCodeIndex, boundedCodeNavResult } from '../lib/codegraph-query.mjs';
+import { buildEngineArgs } from '../lib/engine.mjs';
+import { needsImplementation } from '../lib/planning-access.mjs';
+
+test('navigation is allowed before approval but unknown tools stay locked; scan flag forwards', () => {
+  assert.equal(needsImplementation('code_nav'), false);
+  assert.equal(needsImplementation('untrusted_graph'), true);
+  const args = buildEngineArgs({ codegraphMaxFiles: '123' });
+  assert.equal(args[args.indexOf('--codegraph-max-files') + 1], '123');
+  for (const value of ['-1', '0', '1.2', 'x']) assert.throws(() => buildEngineArgs({ codegraphMaxFiles: value }), /positive/);
+});
+test('graph pages enumerate all candidates; filters disambiguate call-site scope', async t => {
+  const dir = mkdtempSync(join(tmpdir(), 'graph-pages-')); t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeFileSync(join(dir, 'a.ts'), 'class A { run() { save(); save(); } }');
+  writeFileSync(join(dir, 'b.ts'), 'class B { run() { save(); } }');
+  const index = await createCodeIndex(dir);
+  const first = queryCodeIndex(index, { op: 'callers', name: 'save', limit: 1 });
+  assert.equal(first.total, 3); assert.equal(first.truncated, true); assert.equal(first.nextOffset, 1);
+  assert.match(first.semantics, /not resolved/);
+  const rest = queryCodeIndex(index, { op: 'callers', name: 'save', offset: 1, limit: 2 });
+  assert.equal(rest.returned, 2); assert.equal(rest.nextOffset, null);
+  const scoped = queryCodeIndex(index, { op: 'callers', name: 'save', path: 'b.ts', container: 'B' });
+  assert.equal(scoped.total, 1); assert.equal(scoped.results[0].file, 'b.ts');
+  assert.equal(queryCodeIndex(index, { op: 'definition', name: 'run', container: 'A' }).total, 1);
+  assert.equal(queryCodeIndex(index, { op: 'definition', name: 'run', path: join(dir, 'a.ts') }).total, 1);
+  assert.throws(() => queryCodeIndex(index, { op: 'symbols', name: 'run', path: dir }), /directory/);
+  assert.match(queryCodeIndex(index, { op: 'symbols', name: 'absent' }).next, /find\/ls/);
+});
+test('coverage counts remain stable across refreshes and disclose capped indexing', async t => {
+  const dir = mkdtempSync(join(tmpdir(), 'graph-coverage-')); t.after(() => rmSync(dir, { recursive: true, force: true }));
+  for (const file of ['a', 'b', 'c']) writeFileSync(join(dir, file + '.ts'), `function ${file}() {}`);
+  const index = await createCodeIndex(dir, { maxFiles: 1 });
+  const before = index.stats(); await index.refresh(); await index.refresh();
+  assert.equal(index.stats().skipped, 2); assert.equal(index.stats().discovered, 3);
+  assert.equal(index.stats().complete, false); assert.equal(index.stats().parsed, before.parsed);
+  assert.equal(queryCodeIndex(index, { op: 'symbols', name: 'a' }).coverage.complete, false);
+});
+test('unreadable directories mark coverage incomplete', { skip: process.platform === 'win32' || process.getuid?.() === 0 }, async t => {
+  const dir = mkdtempSync(join(tmpdir(), 'graph-unreadable-'));
+  writeFileSync(join(dir, 'a.ts'), 'function a() {}');
+  mkdirSync(join(dir, 'private')); writeFileSync(join(dir, 'private', 'b.ts'), 'function hidden() {}');
+  chmodSync(join(dir, 'private'), 0o000);
+  t.after(() => { chmodSync(join(dir, 'private'), 0o755); rmSync(dir, { recursive: true, force: true }); });
+  const index = await createCodeIndex(dir);
+  assert.equal(index.stats().unreadable, 1); assert.equal(index.stats().complete, false);
+  assert.deepEqual(queryCodeIndex(index, { op: 'definition', name: 'hidden' }).coverage, { files: 1, discovered: 1, skipped: 0, unreadable: 1, parseErrors: 0, complete: false });
+  chmodSync(join(dir, 'private'), 0o755); await index.refresh();
+  assert.equal(index.stats().unreadable, 0); assert.equal(index.stats().complete, true);
+});
+test('oversized graph records keep a parseable envelope and pagination', async t => {
+  const dir = mkdtempSync(join(tmpdir(), 'graph-oversized-')); t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeFileSync(join(dir, 'big.ts'), `function ${'x'.repeat(30000)}() {}\nfunction xsmall() {}`);
+  const index = await createCodeIndex(dir);
+  const serialized = boundedCodeNavResult(index, { op: 'symbols', name: 'x' });
+  assert.ok(Buffer.byteLength(serialized) <= 23000);
+  const page = JSON.parse(serialized);
+  assert.equal(page.total, 2); assert.equal(page.returned, 1); assert.equal(page.nextOffset, 1);
+  assert.match(page.clipped, /shortened/); assert.match(page.results[0].name, /30000 chars/);
+  assert.equal(JSON.parse(boundedCodeNavResult(index, { op: 'symbols', name: 'x', offset: 1 })).results[0].name, 'xsmall');
+});