carthagent 0.0.0-stage → 1.0.7

package/lib/review.mjs

@@ -0,0 +1,114 @@
+/**
+ * Self-review loop: after a substantial change, the user can opt in to a
+ * PR ↔ fresh-context review ↔ fixes loop. The current agent pushes a branch
+ * and opens a PR; `ctg review <pr>` then runs a brand-new agent process with
+ * no shared context to review it, and the working agent applies the findings.
+ *
+ * Default behavior is a single tri-state: ask (offer at the end of a major
+ * change), yes (always start the loop), no (never). Resolution order:
+ * explicit flag (--review / --delivery-review) > ~/.carthagent/config.json > 'ask'.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import { atomicJson } from './delivery.mjs';
+
+export const REVIEW_MODES = ['ask', 'yes', 'no'];
+/** Persistent local PR review admission limit; not a security boundary. */
+export const MAX_REVIEW_ROUNDS = 3;
+
+export function normalizeReviewMode(value) {
+  const s = String(value ?? '').trim().toLowerCase();
+  return REVIEW_MODES.includes(s) ? s : null;
+}
+
+/** carthagent's user-level config file (CARTHAGENT_CONFIG overrides for tests). */
+export function carthagentConfigPath() {
+  return process.env.CARTHAGENT_CONFIG || join(os.homedir(), '.carthagent', 'config.json');
+}
+
+export function loadCarthagentConfig(path = carthagentConfigPath()) {
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return data && typeof data === 'object' ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Merge a patch into ~/.carthagent/config.json atomically. Returns the new config. */
+export function saveCarthagentConfig(patch, path = carthagentConfigPath()) {
+  const config = { ...loadCarthagentConfig(path), ...patch };
+  atomicJson(path, config);
+  return config;
+}
+
+/** flag (explicit CLI/extension flag) > config file > 'ask'. */
+export function resolveReviewMode(flagValue, config = loadCarthagentConfig()) {
+  return normalizeReviewMode(flagValue) ?? normalizeReviewMode(config?.review) ?? 'ask';
+}
+
+/** Resolve sticky theme/model defaults: explicit flag > config > undefined.
+ *  Undefined falls through to the built-in default (carthage theme, agent's
+ *  default model) so we don't pass a stale `--model`/`--theme` to the engine. */
+export function resolveStickyDefaults(opts, config = loadCarthagentConfig()) {
+  return {
+    theme: opts?.theme || config?.theme || undefined,
+    model: opts?.model || config?.model || undefined,
+  };
+}
+
+/**
+ * Pure offer predicate shared by the extension and the console: a self-review
+ * offer is only made in ask mode, once per run, when the run produced a
+ * verified delivery or real file edits, and no loop is already active.
+ */
+export function shouldOfferReview({ mode, verified, writes, loopActive, offeredRuns, runKey }) {
+  if (mode !== 'ask' || loopActive) return false;
+  if (!verified && !(writes > 0)) return false;
+  return !(offeredRuns?.has?.(runKey));
+}
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CTG_BIN = join(ROOT, 'bin', 'ctg.mjs');
+
+/**
+ * Instructions handed to the working agent when a review loop starts (via the
+ * extension's kickoff message or the console's /review + ^y paths).
+ */
+export function reviewKickoff(ctgBin = CTG_BIN) {
+  return `The user opted in to a self-review loop — run it now.
+
+1. Commit the finished work on a review branch (never the default branch), push it, and open a pull request (\`gh pr create --fill\` or equivalent). If the workspace is not a git repo, has no remote, or \`gh\` is unavailable/unauthenticated, tell the user and stop — do not simulate a review.
+2. Run: node "${ctgBin}" review <pr-number-or-url>
+   This spawns a fresh-context reviewer that inspects the PR and prints prioritized findings, ending with VERDICT: APPROVE (exit 0) or VERDICT: CHANGES-REQUESTED (exit 1).
+3. On CHANGES-REQUESTED: address each finding, commit, push, and run the same review command again on the same PR. On APPROVE: summarize the outcome and stop.
+4. Stop after at most ${MAX_REVIEW_ROUNDS} review rounds — the CLI persists admissions per PR in this workspace, including failed attempts. At the limit, summarize remaining findings and escalate to the user instead of looping forever.`;
+}
+
+/** Prompt for the detached fresh-context reviewer subprocess (`ctg review <pr>`). */
+export function reviewerPrompt({ prRef, cwd, meta = {} }) {
+  const context = [
+    meta.title ? `PR title: ${meta.title}` : '',
+    meta.url ? `PR url: ${meta.url}` : '',
+    meta.headRefName ? `branches: ${meta.headRefName} → ${meta.baseRefName}` : '',
+  ].filter(Boolean).join('\n');
+  return `You are a fresh-context code reviewer. Review pull request ${JSON.stringify(String(prRef))} in the repository at ${JSON.stringify(cwd)}.
+${context ? context + '\n' : ''}
+Inspect the change with \`gh pr view\`, \`gh pr diff\` and \`gh pr checks\` for this PR, and read the touched files in the working tree for surrounding context. Do not modify files, commit, push, or check out branches — review only.
+
+Hunt for: correctness bugs and broken edge cases, security issues, missing test coverage for changed behavior, and violations of this repository's existing conventions. Skip style nitpicks that tooling already enforces. Verify every claim against the actual code before reporting it — no speculative findings.
+
+Report format: a prioritized findings list, each entry \`file:line — severity — issue — suggested fix\` (mark uncertain findings as uncertain). Put the complete findings list at the END of your reply so it survives output truncation, then finish with exactly one line:
+VERDICT: APPROVE — no blocking findings
+VERDICT: CHANGES-REQUESTED — at least one blocking finding`;
+}
+
+/** Extract the reviewer's verdict from its output tail — the LAST VERDICT line
+ *  wins, so format examples quoted earlier can't shadow the real verdict. */
+export function parseVerdict(output) {
+  const last = String(output ?? '').trim().split(/\r?\n/).at(-1);
+  const match = /^VERDICT:\s*(APPROVE|CHANGES-REQUESTED)(?:\s+—\s+[^\r\n]+)?$/i.exec(last);
+  return match ? match[1].toUpperCase() : null;
+}

package/lib/scenarios.mjs

@@ -0,0 +1,99 @@
+/**
+ * Scenario manifests: pluggable task profiles for the evaluation runner.
+ *
+ * Each scenarios/<name>/ directory holds a scenario.json plus its graders,
+ * seed files, and context. The harness (evaluate.mjs) stays domain-agnostic —
+ * a game, a CLI task, or any future domain is just another manifest, i.e. a
+ * selectable path through the same delivery plan → check → finish pipeline.
+ *
+ * scenario.json shape:
+ *   {
+ *     "name": "game",
+ *     "description": "…",
+ *     "prompt": "the single user prompt",              // or { "file": "prompt.md" }
+ *     "setup": "text appended to the shared execution context (both modes)",
+ *     "context": ["context.md"],                        // files joined into --delivery-context (custom mode)
+ *     "skills": ["game-development"],                   // skill dirs whose SKILL.md is inlined into context
+ *     "seeds": [{ "from": "seed/file.ts", "to": "src/index.ts" }],
+ *     "runtimes": { "python": "/path/to/python" },       // extra runtime placeholders (optional)
+ *     "developmentChecks": [check],                     // required validators during the run
+ *     "holdoutChecks": [check],                         // scored after the run, unseen by the model
+ *   }
+ *
+ * check = { "id", "kind", "argv": [...], "timeoutSeconds" } — argv supports
+ * placeholders: {python} {node} {root} {home} {cwd} {scenario}, plus any key
+ * declared in the scenario's "runtimes" map (e.g. {rust}, {go}).
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+
+export function listScenarios(root) {
+  const dir = join(root, 'scenarios');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && existsSync(join(dir, d.name, 'scenario.json')))
+    .map(d => d.name);
+}
+
+export function loadScenario(root, name) {
+  const scenariosRoot = resolve(root, 'scenarios');
+  const dir = resolve(scenariosRoot, name);
+  const local = relative(scenariosRoot, dir);
+  if (!name || local === '..' || local.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(local)) throw Error(`Invalid scenario name: ${JSON.stringify(name)}`);
+  const manifestPath = join(dir, 'scenario.json');
+  if (!existsSync(manifestPath)) {
+    const known = listScenarios(root);
+    throw Error(`Unknown scenario ${JSON.stringify(name)}. Available: ${known.join(', ') || '(none — expected scenarios/<name>/scenario.json beside evaluate.mjs)'}`);
+  }
+  const m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (typeof m.name === 'string' && m.name !== name) throw Error(`Scenario ${name} manifest name mismatch: ${m.name}`);
+  const prompt = typeof m.prompt === 'string'
+    ? m.prompt
+    : m.prompt?.file ? readFileSync(join(dir, m.prompt.file), 'utf8').trim()
+    : null;
+  if (!prompt) throw Error(`Scenario ${name} needs a prompt (string or {file})`);
+
+  const check = c => {
+    if (!c.id || !Array.isArray(c.argv) || !c.argv.every(a => typeof a === 'string' && a.length)) throw Error(`Scenario ${name}: invalid check ${JSON.stringify(c?.id)}`);
+    return { kind: 'runtime', timeoutSeconds: 90, ...c };
+  };
+  const developmentChecks = (m.developmentChecks || []).map(check);
+  const holdoutChecks = (m.holdoutChecks || []).map(check);
+  if (!developmentChecks.length && !holdoutChecks.length) throw Error(`Scenario ${name} declares no checks`);
+
+  // Resolve everything path-shaped relative to the scenario dir now; {cwd}
+  // and {python} stay as placeholders — they differ per trial run.
+  const contextParts = [];
+  for (const skill of m.skills || []) {
+    const skillDir = join(root, 'skills', skill);
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) throw Error(`Scenario ${name}: missing skill ${skillDir}`);
+    contextParts.push(readFileSync(skillMd, 'utf8'), `Skill-relative assets/scripts resolve under: ${skillDir}`);
+  }
+  for (const file of m.context || []) contextParts.push(readFileSync(join(dir, file), 'utf8'));
+
+  return {
+    name,
+    dir,
+    description: m.description || '',
+    prompt,
+    setup: m.setup || '',
+    context: contextParts.join('\n\n'),
+    seeds: (m.seeds || []).map(s => ({
+      from: expandPlaceholders(s.from, { root, home: root, scenario: dir }),
+      to: s.to,
+    })),
+    developmentChecks,
+    holdoutChecks,
+    needsPython: JSON.stringify(m).includes('{python}'),
+    runtimes: m.runtimes || {},
+  };
+}
+
+/** Substitute {python} {node} {root} {home} {cwd} {scenario} and any scenario-declared runtime keys in a string/argv. */
+export function expandPlaceholders(value, vars) {
+  const sub = s => s.replace(/\{(\w+)\}/g, (_, k) => vars[k] ?? `{${k}}`);
+  if (typeof value === 'string') return sub(value);
+  if (Array.isArray(value)) return value.map(v => expandPlaceholders(v, vars));
+  return value;
+}

package/lib/ship-auth.mjs

@@ -0,0 +1,44 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { CloudClient, cloudControlUrl, oauthCredentials } from './cloud/client.mjs';
+import { CARTHAGENT_SHIP_PROVIDER_ID } from './providers/names.mjs';
+
+// Refresh a little early so a token minted minutes ago does not expire
+// mid-request; the engine applies its own refresh to managed dispatch anyway.
+const REFRESH_SKEW_MS = 60_000;
+
+export function shipAgentDir(env = process.env) {
+  return env.CARTHAGENT_CODING_AGENT_DIR || env.PI_CODING_AGENT_DIR || join(os.homedir(), '.carthagent', 'agent');
+}
+
+export function readShipAuth({ agentDir = shipAgentDir(), providerId = CARTHAGENT_SHIP_PROVIDER_ID } = {}) {
+  try {
+    const auth = JSON.parse(readFileSync(join(agentDir, 'auth.json'), 'utf8'));
+    return auth?.[providerId] ?? null;
+  } catch { return null; }
+}
+
+/**
+ * Resolve a usable Carthagent Ship access token from the engine credential
+ * store (auth.json), refreshing through the control plane when the stored
+ * access token is near expiry. Returns null when no Ship OAuth credential
+ * exists. The refreshed credential is written back so the engine's own
+ * dispatch sees it too.
+ */
+export async function resolveShipAccessToken({ agentDir = shipAgentDir(), providerId = CARTHAGENT_SHIP_PROVIDER_ID, env = process.env, fetchImpl = globalThis.fetch, now = Date.now, signal } = {}) {
+  const authPath = join(agentDir, 'auth.json');
+  let auth;
+  try { auth = JSON.parse(readFileSync(authPath, 'utf8')); } catch { return null; }
+  const credential = auth?.[providerId];
+  if (credential?.type !== 'oauth' || typeof credential.access !== 'string' || typeof credential.refresh !== 'string') return null;
+  if (Number(credential.expires) > now() + REFRESH_SKEW_MS) return credential.access;
+  const client = new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl });
+  const tokens = await client.refresh({ refreshToken: credential.refresh, signal });
+  const next = oauthCredentials(tokens, now());
+  auth[providerId] = { type: 'oauth', ...next };
+  const temp = `${authPath}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(auth, null, 2));
+  renameSync(temp, authPath);
+  return next.access;
+}

package/lib/ship-jev.mjs

@@ -0,0 +1,59 @@
+import { ADVISOR_QUESTIONS } from './plan-advisor.mjs';
+import { cloudGatewayUrl } from './providers/experiential.mjs';
+import { resolveShipAccessToken } from './ship-auth.mjs';
+
+const MAX_BODY_BYTES = 64000;
+const MAX_RESPONSE_BYTES = 65536;
+
+/**
+ * Jev plan advice through Carthagent Ship's managed /v1/jev endpoint.
+ * The backend forwards to Experiential's free System One endpoint
+ * (jev-latest) outside the billing gateway, so advice never draws on
+ * the caller's managed usage. Same Noul wire shape as the other adapters.
+ */
+export function createShipJev({ accessToken, baseUrl, fetchImpl = globalThis.fetch, timeoutMs = 15000, signal } = {}) {
+  if (typeof accessToken !== 'string' || !accessToken.trim()) throw Error('Ship credential required');
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) throw Error('Ship endpoint URL required');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw Error('Invalid Jev timeout');
+  const url = `${baseUrl.replace(/\/+$/, '')}/jev`;
+  return { async classify(plan) {
+    const body = JSON.stringify({ state: { goal: plan.goal, acceptance: plan.acceptance, checks: plan.checks, outputs: plan.outputs, assumptions: plan.assumptions, design: plan.design, workflow: plan.workflow }, questions: ADVISOR_QUESTIONS });
+    if (Buffer.byteLength(body) > MAX_BODY_BYTES) throw Error('Jev input exceeds 64KB');
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Error('Jev timeout')); }, timeoutMs); });
+    try { return await Promise.race([timeout, (async () => {
+      const response = await fetchImpl(url, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json', authorization: `Bearer ${accessToken}` }, body, signal: AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]) });
+      if (!response.ok) { await response.body?.cancel(); throw Error('Jev HTTP failure'); }
+      const reader = response.body?.getReader(); if (!reader) throw Error('Missing Jev body');
+      let size = 0; const chunks = [];
+      try { for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.byteLength; if (size > MAX_RESPONSE_BYTES) { await reader.cancel(); throw Error('Jev response too large'); } chunks.push(Buffer.from(value)); } }
+      finally { reader.releaseLock(); }
+      const payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (typeof payload.model !== 'string' || !/jev/i.test(payload.model)) throw Error('Invalid Jev model');
+      const probabilities = {};
+      for (const key of Object.keys(ADVISOR_QUESTIONS)) {
+        const answer = payload.answers?.[key];
+        if (answer?.type !== 'noul' || !Number.isFinite(answer.noul) || answer.noul < 0 || answer.noul > 1) throw Error('Invalid Jev answer');
+        probabilities[key] = answer.noul;
+      }
+      const usage = payload.usage;
+      return { model: payload.model, probabilities, usage: usage ? { inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? null, outputTokens: usage.output_tokens ?? usage.completion_tokens ?? null } : null, costUsd: Number.isFinite(usage?.cost) && usage.cost >= 0 ? usage.cost : 0 };
+    })()]); } finally { clearTimeout(timer); controller.abort(); }
+  } };
+}
+
+/**
+ * Ship advisor with lazy credential resolution: the stored OAuth access token
+ * (refreshed when needed) is fetched once per advisor, so classify calls see
+ * the current credential without holding provider keys locally.
+ */
+export function createShipAdvisor({ env = process.env, fetchImpl = globalThis.fetch, signal, agentDir, now } = {}) {
+  let tokenPromise = null;
+  return { async classify(plan) {
+    tokenPromise ??= resolveShipAccessToken({ env, fetchImpl, agentDir, now, signal });
+    const accessToken = await tokenPromise;
+    if (!accessToken) throw Error('Ship credential unavailable');
+    return createShipJev({ accessToken, baseUrl: cloudGatewayUrl(env), fetchImpl, signal }).classify(plan);
+  } };
+}

package/lib/ship-telemetry.mjs

@@ -0,0 +1,183 @@
+/**
+ * Carthagent Ship telemetry context — the metadata-only headers the control
+ * plane uses for product analytics (threads, installs, run modes). No prompt
+ * or response content is ever collected, and everything here is best-effort:
+ * a missing or unreadable install id never blocks a request.
+ */
+import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { shipAgentDir } from './ship-auth.mjs';
+import { CARTHAGENT_SHIP_PROVIDER_ID } from './providers/names.mjs';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RUN_MODES = new Set(['interactive', 'print', 'rpc']);
+// Same env keys the console treats as a usable BYOK credential.
+const BYOK_ENV_KEYS = [
+  'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY',
+  'OPENROUTER_API_KEY', 'XAI_API_KEY', 'EXPLABS_API_KEY',
+  'GROQ_API_KEY', 'MISTRAL_API_KEY', 'DEEPSEEK_API_KEY',
+];
+
+export function installIdPath(agentDir = shipAgentDir()) {
+  return join(agentDir, 'install-id');
+}
+
+function publishInstallId(path, value) {
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${value}\n`, { mode: 0o600, flag: 'wx' });
+    renameSync(temp, path);
+  } finally {
+    try { unlinkSync(temp); } catch { /* rename already consumed it */ }
+  }
+}
+
+function deterministicRepairId(agentDir) {
+  const hex = createHash('sha256').update(`${resolve(agentDir)}\0ship-install-id-repair`).digest('hex').slice(0, 32).split('');
+  hex[12] = '4';
+  hex[16] = 'a';
+  const value = hex.join('');
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+
+function readUuid(path) {
+  try {
+    const value = String(readFileSync(path, 'utf8')).trim().toLowerCase();
+    return UUID.test(value) ? value : '';
+  } catch { return ''; }
+}
+
+function publishImmutable(path, value) {
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${value}\n`, { mode: 0o600, flag: 'wx' });
+    try { linkSync(temp, path); } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  } finally {
+    try { unlinkSync(temp); } catch { /* link already removed or temp absent */ }
+  }
+}
+
+/** Persistent anonymous install id: minted on first run, reused after. */
+export function shipInstallId({ agentDir = shipAgentDir(), id = randomUUID } = {}) {
+  const path = installIdPath(agentDir);
+  const seed = `${path}.seed`;
+  const recovery = `${seed}.recovery`;
+  const existing = readUuid(path);
+  try {
+    mkdirSync(agentDir, { recursive: true });
+    // Recovery is an immutable create-only hard link. Priority preserves an
+    // established recovery/seed identity, then a valid legacy primary, and
+    // only then mints. Corrupt copies are never rewritten or lock-stolen.
+    const recoveryId = readUuid(recovery);
+    const seedId = readUuid(seed);
+    const candidate = recoveryId || seedId || existing || String(id()).toLowerCase();
+    const minted = UUID.test(candidate) ? candidate : deterministicRepairId(agentDir);
+    try { publishImmutable(recovery, minted); } catch { /* fall back to shared legacy identity or deterministic ID */ }
+    const publishedRecovery = readUuid(recovery);
+    // A newly minted value is usable only if an immutable shared copy was
+    // published and read back. Unsupported hard links fall back to an already
+    // persisted identity, or a deterministic per-directory UUID, never this
+    // process's random candidate.
+    const identity = publishedRecovery || recoveryId || seedId || existing || deterministicRepairId(agentDir);
+    // Keep the original seed useful when it is absent; never replace a
+    // malformed seed. The recovery seed above remains the canonical fallback.
+    try { publishImmutable(seed, identity); } catch { /* existing seed or storage error */ }
+    const canonicalIdentity = readUuid(recovery) || readUuid(seed) || existing || identity;
+    publishInstallId(path, canonicalIdentity);
+    return canonicalIdentity;
+  } catch {
+    return existing || readUuid(recovery) || readUuid(seed) || deterministicRepairId(agentDir); // storage remains best-effort
+  }
+}
+
+const hasCredential = credential => {
+  if (typeof credential === 'string') return Boolean(credential.trim());
+  if (!credential || typeof credential !== 'object') return false;
+  return ['key', 'apiKey', 'api_key', 'access', 'refresh'].some(field => typeof credential[field] === 'string' && credential[field].trim());
+};
+
+/** 'ship' | 'byok' | 'ship+byok' | 'none' from the local credential store. */
+export function providerMode({ agentDir = shipAgentDir(), env = process.env } = {}) {
+  let ship = false;
+  let byok = BYOK_ENV_KEYS.some(key => env?.[key]?.trim());
+  try {
+    const stored = JSON.parse(readFileSync(join(agentDir, 'auth.json'), 'utf8'));
+    if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
+      for (const [providerId, credential] of Object.entries(stored)) {
+        if (!hasCredential(credential)) continue;
+        // Only the OAuth credential is a Ship account; a direct api_key under
+        // this provider id goes through the BYOK gateway.
+        if (providerId === CARTHAGENT_SHIP_PROVIDER_ID && credential?.type === 'oauth') ship = true;
+        else byok = true;
+      }
+    }
+  } catch { /* no stored oauth/api-key credentials */ }
+  try {
+    const providers = JSON.parse(readFileSync(join(agentDir, 'models.json'), 'utf8'))?.providers;
+    if (providers && typeof providers === 'object' && !Array.isArray(providers)) {
+      // Any credentialed models.json provider is a direct (BYOK) credential —
+      // Ship OAuth lives in auth.json only.
+      for (const providerId of Object.keys(providers)) {
+        if (hasCredential(providers[providerId])) byok = true;
+      }
+    }
+  } catch { /* no persisted model-store credentials */ }
+  return ship && byok ? 'ship+byok' : ship ? 'ship' : byok ? 'byok' : 'none';
+}
+
+/** Headers for the daily release check — doubles as the install ping. */
+export function installPingHeaders({ env = process.env, agentDir = shipAgentDir(env), version = null } = {}) {
+  return {
+    'x-carthagent-install-id': shipInstallId({ agentDir }),
+    'x-carthagent-version': version || '',
+    'x-carthagent-os': process.platform,
+    'x-carthagent-arch': process.arch,
+    'x-carthagent-node': process.versions.node,
+    'x-carthagent-provider-mode': providerMode({ agentDir, env }),
+  };
+}
+
+// Per-process Ship request context. The console sets CARTHAGENT_RUN_MODE when
+// it spawns the engine; the extension fills the session fields on lifecycle
+// events, and every managed request is stamped with the current values.
+const sessionContext = { threadId: null, turn: 0, installId: null };
+
+/** Adopt the engine's session id as the Ship thread id (minted if absent). */
+export function noteEngineSession(sessionId, { id = randomUUID } = {}) {
+  const next = UUID.test(String(sessionId || '')) ? String(sessionId).toLowerCase() : String(id()).toLowerCase();
+  // A session_start for the same id (extension reload) keeps the turn count.
+  if (sessionContext.threadId === next) return;
+  sessionContext.threadId = next;
+  sessionContext.turn = 0;
+}
+
+/** Each user turn starts a new engine run — advance the turn counter. */
+export function noteAgentTurn() {
+  sessionContext.turn += 1;
+}
+
+/** Headers stamped on every managed Ship gateway request. */
+export function shipRequestHeaders({ env = process.env, agentDir = shipAgentDir(env), version = null } = {}) {
+  if (!sessionContext.threadId) noteEngineSession(null);
+  sessionContext.installId ??= shipInstallId({ agentDir });
+  const headers = {
+    'x-carthagent-thread-id': sessionContext.threadId,
+    'x-carthagent-turn': String(sessionContext.turn),
+    'x-carthagent-install-id': sessionContext.installId,
+    'x-carthagent-version': version || '',
+    'x-carthagent-os': process.platform,
+  };
+  const runMode = String(env.CARTHAGENT_RUN_MODE || '').trim();
+  if (RUN_MODES.has(runMode)) headers['x-carthagent-run-mode'] = runMode;
+  return headers;
+}
+
+/** Test hook: clear the per-process context. */
+export function resetShipContext() {
+  sessionContext.threadId = null;
+  sessionContext.turn = 0;
+  sessionContext.installId = null;
+}