carthagent 0.0.0-stage → 1.0.7

package/lib/planning-view.mjs

@@ -0,0 +1,57 @@
+import { planningStatus } from './planning.mjs';
+import { workflowGraph, architectureGraph } from './workflow.mjs';
+import { evidenceFresh, pendingRequirements, reviewFresh, requiresReview } from './delivery.mjs';
+
+// Shared presentation projection: no I/O and no guessed successful transitions.
+export function planningView(state, hash, { runningCheck } = {}) {
+  const gate = planningStatus(state, hash);
+  if (!state?.plan) return { gate, workflow: null, architecture: null, evidence: [], current: [], blockers: gate.reasons };
+  const plan = state.plan;
+  const evidence = (plan.checks || []).map(check => {
+    const receipt = state.evidence?.[check.id];
+    const status = runningCheck === check.id ? 'active' : !receipt ? 'pending' : !receipt.passed ? 'fail' : evidenceFresh(check, receipt, hash, state) ? 'done' : 'stale';
+    return { id: check.id, status, logPath: receipt?.logPath, code: receipt?.code, executedRevision: receipt?.executedRevision, fingerprint: receipt?.fingerprint };
+  });
+  let workflow;
+  try { workflow = workflowGraph(plan); }
+  catch (error) { workflow = { nodes: [], edges: [], error: error.message }; }
+  const pending = pendingRequirements(state, hash);
+  const allFresh = evidence.length > 0 && evidence.every(e => e.status === 'done') && pending.length === 0;
+  const review = !requiresReview(state) || reviewFresh(state, hash);
+  const statuses = {
+    gate_design: gate.locked ? 'blocked' : 'done',
+    gate_verify: runningCheck ? 'active' : evidence.some(e => e.status === 'fail') ? 'fail' : evidence.some(e => e.status === 'stale') ? 'stale' : allFresh ? 'done' : 'pending',
+    gate_review: review ? 'done' : state.reviewEvidence ? 'stale' : 'pending',
+    gate_deliver: state.status === 'blocked' ? 'blocked' : state.status === 'verified' && allFresh && review && !gate.locked ? 'done' : 'pending',
+  };
+  workflow.nodes = workflow.nodes.map(node => {
+    let status = statuses[node.id] || 'proposed';
+    if (node.type === 'work') {
+      const index = plan.steps.findIndex((s, i) => (typeof s === 'string' ? `legacy_${i + 1}` : s.id) === node.step);
+      status = state.stepStatus?.[`step${index}`] || 'pending';
+      if (status === 'failed') status = 'fail';
+      if (gate.locked && status !== 'done' && status !== 'fail') status = 'blocked';
+    } else if (node.type === 'check') {
+      const receipts = evidence.filter(e => node.checks.includes(e.id));
+      status = receipts.some(e => e.status === 'active') ? 'active' : receipts.some(e => e.status === 'fail') ? 'fail' : receipts.some(e => e.status === 'stale') ? 'stale' : receipts.length && receipts.every(e => e.status === 'done') ? 'done' : 'pending';
+    }
+    return { ...node, status };
+  });
+  const blockers = [...gate.reasons, ...(gate.findings || []).map(f => f.message), ...(gate.reviewFindings || []).filter(f => f.severity === 'blocking').map(f => f.description), ...pending.map(r => `Fresh requirement execution needed: ${r}`)];
+  return { gate, workflow, architecture: architectureGraph(plan), evidence, current: workflow.nodes.filter(n => n.status === 'active').map(n => ({ id: n.id, title: n.title })), blockers, revision: state.revision, provenance: 'Observed receipts and explicit progress; proposed decisions/artifacts are not inferred complete.' };
+}
+
+export function planningViewLines(view, tab = 'workflow') {
+  const lines = [`${tab.toUpperCase()} · ${view.gate.phase} · rev ${view.revision ?? '-'}`];
+  if (tab === 'architecture') {
+    for (const c of view.architecture?.nodes || []) lines.push(`${c.id} [${c.layer}] ${c.title}`, `  excludes: ${(c.excludes || []).join('; ')}`);
+    for (const p of view.architecture?.ports || []) lines.push(`${p.owner} -> port ${p.id} -> ${p.adapter} (injected at ${p.compositionRoot})`);
+  } else if (tab === 'evidence') {
+    for (const e of view.evidence) lines.push(`${e.id}: ${e.status} · executed rev ${e.executedRevision ?? '-'}`, `  ${e.logPath || 'No execution receipt'}`);
+  } else {
+    for (const n of view.workflow?.nodes || []) lines.push(`${n.id} [${n.status}] ${n.title}`);
+    for (const e of view.workflow?.edges || []) lines.push(`${e.from} -> ${e.to}${e.label ? `: ${e.label}` : ''}`);
+  }
+  if (view.blockers.length) lines.push('BLOCKERS', ...view.blockers);
+  return lines;
+}

package/lib/planning.mjs

@@ -0,0 +1,155 @@
+import { validateWorkflow } from './workflow.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+
+// Pure design policy. Callers supply the observed source snapshot; this module
+// never reads files, invokes a model, executes checks, or persists reports.
+export const designDigest = plan => createHash('sha256').update(JSON.stringify(plan)).digest('hex');
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const list = value => Array.isArray(value) ? value : [];
+const safe = value => text(value) && /^[a-z][a-z0-9_-]{0,63}$/.test(value);
+
+export function validateDesign(plan) {
+  const findings = validateWorkflow(plan || {});
+  const fail = (code, message, target = 'design') => findings.push({ code, target, message, severity: 'blocking' });
+  const design = plan?.design;
+  if (!design || typeof design !== 'object' || Array.isArray(design)) {
+    fail('missing-design', 'Declare architecture, injection contracts, scenarios and risks before generating code.');
+    return findings;
+  }
+  for (const field of ['components', 'ports', 'scenarios', 'risks']) if (!Array.isArray(design[field])) fail('array', `${field} must be an array.`, field);
+  const components = list(design.components), ports = list(design.ports), scenarios = list(design.scenarios);
+  const requirements = list(plan.acceptance).map(a => a.requirement);
+  const checks = new Set(list(plan.checks).map(c => c.id));
+  const ids = (items, name) => {
+    const seen = new Set();
+    for (const item of items) {
+      if (!item || !safe(item.id) || seen.has(item.id)) fail('identity', `${name} IDs must be unique safe identifiers.`, name);
+      seen.add(item?.id);
+    }
+    return seen;
+  };
+  const componentIds = ids(components, 'components');
+  ids(ports, 'ports'); ids(scenarios, 'scenarios'); ids(list(design.risks), 'risks');
+  if (!components.length) fail('components', 'At least one cohesive component is required.');
+  for (const c of components.filter(Boolean)) {
+    if (!text(c.responsibility) || !list(c.excludes).length || list(c.excludes).some(x => !text(x))) fail('srp', 'Declare one responsibility and explicit non-responsibilities.', c.id);
+    if (!['core', 'adapter', 'composition', 'presentation'].includes(c.layer)) fail('layer', 'Use core, adapter, composition or presentation.', c.id);
+    if (!Array.isArray(c.dependencies) || c.dependencies.some(id => !componentIds.has(id) || id === c.id)) fail('dependencies', `Dependencies must reference other components. Invalid: ${JSON.stringify(list(c.dependencies).filter(id => !componentIds.has(id) || id === c.id))}; allowed: ${JSON.stringify([...componentIds].filter(id => id !== c.id))}.`, c.id);
+    if (!list(c.requirements).length || c.requirements.some(r => !requirements.includes(r))) fail('ownership', `Component must reference exact acceptance requirements. Unknown: ${JSON.stringify(list(c.requirements).filter(r => !requirements.includes(r)))}. Copy plan.acceptance text; do not rewrite obligations.`, c.id);
+    if (c.layer === 'core' && list(c.dependencies).some(id => components.find(other => other?.id === id)?.layer === 'adapter')) fail('inversion', 'Core policy must depend on ports, not concrete adapters.', c.id);
+  }
+  const visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) { fail('cycle', 'Component dependencies contain a cycle.', id); return; }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of list(components.find(c => c?.id === id)?.dependencies)) if (componentIds.has(dep)) visit(dep);
+    visiting.delete(id); visited.add(id);
+  }
+  for (const id of componentIds) visit(id);
+  for (const p of ports.filter(Boolean)) {
+    if (!componentIds.has(p.owner) || !componentIds.has(p.adapter) || components.find(c => c?.id === p.adapter)?.layer !== 'adapter' || components.find(c => c?.id === p.compositionRoot)?.layer !== 'composition') fail('port-binding', 'Ports need an owner, concrete adapter and composition root.', p.id);
+    for (const field of ['input', 'output', 'errors', 'injection', 'testDouble', 'integrationAssertion']) if (!text(p[field])) fail('port-contract', `Port needs ${field}.`, p.id);
+  }
+  for (const c of components.filter(Boolean)) {
+    if (!Array.isArray(c.externalDependencies) || c.externalDependencies.some(id => !ports.some(p => p?.id === id && p.owner === c.id))) fail('injection', 'Every external dependency must name an owned injection port (or use an explicit empty list).', c.id);
+  }
+  for (const s of scenarios.filter(Boolean)) {
+    if (!requirements.includes(s.requirement)) fail('scenario-requirement', `Scenario must name an exact acceptance requirement. Unknown: ${JSON.stringify(s.requirement)}. Copy plan.acceptance text; do not rewrite obligations.`, s.id);
+    if (!['positive', 'boundary', 'failure'].includes(s.kind)) fail('scenario-kind', 'Use positive, boundary or failure.', s.id);
+    if (!list(s.path).length || s.path.some(id => !componentIds.has(id))) fail('scenario-path', `Scenario needs a path through declared components. Invalid: ${JSON.stringify(list(s.path).filter(id => !componentIds.has(id)))}; allowed: ${JSON.stringify([...componentIds])}.`, s.id);
+    if (!list(s.checks).length || s.checks.some(id => !checks.has(id))) fail('scenario-checks', `Scenario needs existing executable check IDs. Invalid: ${JSON.stringify(list(s.checks).filter(id => !checks.has(id)))}; allowed: ${JSON.stringify([...checks])}.`, s.id);
+    for (const field of ['input', 'expected', 'assertion']) if (!text(s[field])) fail('scenario-contract', `Scenario needs concrete ${field}.`, s.id);
+  }
+  for (const requirement of requirements) {
+    if (!components.some(c => list(c?.requirements).includes(requirement))) fail('unowned', `No component owns: ${requirement}`);
+    for (const kind of ['positive', 'negative']) if (!scenarios.some(s => s?.requirement === requirement && (kind === 'positive' ? s.kind === 'positive' : ['boundary', 'failure'].includes(s.kind)))) fail('coverage', `Missing ${kind} scenario: ${requirement}`);
+  }
+  for (const risk of list(design.risks).filter(Boolean)) {
+    if (!text(risk.description) || !['open', 'resolved'].includes(risk.status) || typeof risk.blocking !== 'boolean') fail('risk', 'Risks need description, status and blocking flag.', risk.id);
+    if (risk.status === 'open' && risk.blocking) fail('risk-open', risk.description, risk.id);
+    if (risk.status === 'resolved' && !text(risk.evidence)) fail('risk-evidence', 'Resolved risks require evidence.', risk.id);
+  }
+  return findings;
+}
+
+function identity(state, hash) {
+  if (!state?.plan || !text(hash)) throw Error('Plan and observed source fingerprint are required.');
+  return { runId: state.runId, revision: state.revision, digest: designDigest(state.plan), fingerprint: hash };
+}
+function matches(receipt, state, hash) {
+  return receipt && Object.entries(identity(state, hash)).every(([key, value]) => receipt[key] === value);
+}
+export function validatePlanning(state, hash, now = new Date().toISOString()) {
+  const findings = validateDesign(state.plan);
+  state.planning ||= { history: [] };
+  state.planning.validation = { ...identity(state, hash), findings, at: now };
+  state.planning.history.push({ event: 'validation', receipt: structuredClone(state.planning.validation) });
+  return state.planning.validation;
+}
+export function inspectPlanning(state, hash, now = new Date().toISOString()) {
+  if (!matches(state.planning?.validation, state, hash) || state.planning.validation.findings.length) throw Error('Fresh passing validation required before plan inspection.');
+  const capture = { ...identity(state, hash), id: randomUUID(), at: now, plan: structuredClone(state.plan), previousFindings: structuredClone(state.planning.review?.findings || []), unresolved: structuredClone(state.planning.openFindings || []), provenance: 'Harness captured plan; reading and semantic review remain model-authored.' };
+  state.planning.capture = capture;
+  delete state.planning.approval;
+  delete state.planning.started;
+  return structuredClone(capture);
+}
+export function recordPlanReview(state, hash, review, now = new Date().toISOString()) {
+  if (!matches(state.planning?.validation, state, hash)) throw Error('Validate the current plan and snapshot first.');
+  if (state.planning.validation.findings.length) throw Error('Repair blocking design findings before review.');
+  if (!matches(state.planning.capture, state, hash)) throw Error('No current plan capture: call delivery_design action=inspect, then pass its result.id as review.captureId. Revision or source changes make earlier captures stale.');
+  if (review?.captureId !== state.planning.capture.id) throw Error(`review.captureId must be the id from the latest inspect result (${state.planning.capture.id}); received ${JSON.stringify(review?.captureId ?? null)}. Earlier captureIds are stale — reuse this id or re-inspect.`);
+  if (!list(review?.challenges).length || review.challenges.some(x => !text(x))) throw Error('Record concrete adversarial challenges.');
+  if (!Array.isArray(review.findings)) throw Error('review.findings must be an array. Findings need severity, description and advisory disposition.');
+  for (const [i, finding] of review.findings.entries()) {
+    if (!finding || !text(finding.description)) throw Error(`review.findings[${i}].description must be nonempty. Findings need severity, description and advisory disposition.`);
+    if (!['blocking', 'advisory'].includes(finding.severity)) throw Error(`review.findings[${i}].severity expected blocking|advisory; received ${JSON.stringify(finding.severity)}. Findings need severity, description and advisory disposition.`);
+    if (finding.severity === 'advisory' && !text(finding.disposition)) throw Error(`review.findings[${i}].disposition required for advisory. Findings need severity, description and advisory disposition.`);
+  }
+  const resolutions = list(review.resolutions);
+  const open = state.planning.openFindings || [];
+  for (const finding of open) {
+    const resolution = resolutions.find(r => r?.id === finding.id);
+    if (resolution && (state.revision <= finding.revision || !text(resolution.change) || !text(resolution.evidence))) throw Error('Blocking findings require a later design revision, explicit change and resolution evidence.');
+  }
+  if (resolutions.some(r => !r || !open.some(f => f.id === r.id))) throw Error('Resolution references an unknown blocking finding.');
+  const walkthroughs = list(review.walkthroughs);
+  if (list(state.plan.design?.scenarios).some(s => !walkthroughs.some(w => w?.scenario === s.id && text(w.trace) && text(w.assertion)))) throw Error('Walk through every scenario with a trace and assertion.');
+  if (!Array.isArray(review.limitations) || review.limitations.some(x => !text(x))) throw Error('Declare review limitations.');
+  if (walkthroughs.length !== list(state.plan.design?.scenarios).length || new Set(walkthroughs.map(w => w.scenario)).size !== walkthroughs.length) throw Error('Walkthrough IDs must be unique and match exactly the declared scenarios.');
+  const findings = review.findings.map(f => ({ ...structuredClone(f), id: randomUUID(), revision: state.revision }));
+  state.planning.openFindings = [...open.filter(f => !resolutions.some(r => r.id === f.id)), ...findings.filter(f => f.severity === 'blocking')];
+  const receipt = { ...identity(state, hash), ...structuredClone(review), findings, provenance: 'model-authored; not independent assurance', at: now };
+  // Caller-controlled content cannot override receipt identity.
+  Object.assign(receipt, identity(state, hash));
+  state.planning.review = receipt;
+  state.planning.history.push({ event: 'review', receipt: structuredClone(receipt) });
+  delete state.planning.approval;
+  return receipt;
+}
+export function approvePlanning(state, hash, now = new Date().toISOString()) {
+  if ((state.plan.verification ?? 'required') !== 'required') throw Error('Informational plans cannot authorize implementation.');
+  if (!matches(state.planning?.validation, state, hash) || validateDesign(state.plan).length) throw Error('Fresh passing design validation is required.');
+  if (!matches(state.planning?.review, state, hash) || (state.planning.openFindings?.length || state.planning.review.findings.some(f => f.severity === 'blocking'))) throw Error('Fresh review with no blocking findings is required.');
+  state.planning.approval = { ...identity(state, hash), at: now };
+  state.planning.history.push({ event: 'approved', receipt: { ...state.planning.approval } });
+  return state.planning.approval;
+}
+export function planningStatus(state, hash) {
+  if (!state?.plan) return { locked: true, phase: 'discovery', reasons: ['Create and test a design before generating code.'] };
+  if (state.workflowMode === 'standard') {
+    const required = (state.plan.verification ?? 'required') === 'required';
+    return { locked: !required, phase: required ? 'implementation' : 'informational', reasons: required ? [] : ['Informational contracts cannot authorize implementation.'], enforcement: 'Standard contract mode; final evidence and review remain required. Not an OS sandbox.' };
+  }
+  const approval = state.planning?.approval;
+  const samePlan = approval && approval.runId === state.runId && approval.revision === state.revision && approval.digest === designDigest(state.plan);
+  const started = samePlan && state.planning?.started?.approvalAt === approval.at;
+  const unlocked = (state.plan.verification ?? 'required') === 'required' && samePlan && (started || approval.fingerprint === hash);
+  return { locked: !unlocked, phase: unlocked ? (started ? 'implementation' : 'approved') : 'design-validation', reasons: unlocked ? [] : ['Implementation locked: validate, review and approve this plan revision on the current source snapshot.'], findings: state.planning?.validation?.findings || [], reviewFindings: [...(state.planning?.openFindings || []), ...(state.planning?.review?.findings || []).filter(f => f.severity !== 'blocking')], enforcement: 'Fail-closed participating-tool gate; not an OS sandbox. External processes and host access are outside this boundary.' };
+}
+export function startImplementation(state, hash, now = new Date().toISOString()) {
+  if (planningStatus(state, hash).locked) throw Error('Implementation locked: test and approve the plan before code, tests or commands.');
+  if (state.workflowMode === 'standard') return;
+  state.planning.started ||= { approvalAt: state.planning.approval.at, at: now };
+}

package/lib/probe-diagnostics.mjs

@@ -0,0 +1,13 @@
+// Advisory only: diagnose repeated infrastructure failures without granting
+// permission, suppressing evidence, executing commands or weakening checks.
+export function probeDiagnostics(previous = { failures: 0, family: null }, event) {
+  if (!['bash', 'delivery_check'].includes(event.toolName)) return { state: previous };
+  const text = (event.content || []).filter(item => item.type === 'text').map(item => item.text).join('\n');
+  const failed = event.isError === true || /(?:exit(?:ed)? (?:with )?code[: ]+[1-9]|\bERR_(?:MODULE|UNKNOWN|PACKAGE)|Cannot find (?:module|package)|"passed"\s*:\s*false|ℹ fail [1-9]|\btest failed\b)/i.test(text);
+  if (!failed) return { state: { failures: 0, family: null } };
+  const family = /module|loader|tsx|import|registerHooks|register\(/i.test(text) ? 'module-loader' : 'execution';
+  const failures = previous.family === family ? previous.failures + 1 : 1;
+  const state = { failures: Math.min(failures, 1000), family };
+  if (failures !== 2 && failures !== 4) return { state };
+  return { state, message: `Diagnostic checkpoint: ${failures} consecutive ${family} failures. Before another executable probe, state ONE observed failure and ONE changed hypothesis; preserve the original exit code and inspect complete stderr. Do not use pipelines that turn a failed test into exit 0. Prefer existing test tooling or node:test plus existing TypeScript transpilation and mocked imports over custom loader chains. Separate product defects from test infrastructure. Do not change unrelated dependencies, hide failures with stubs, or repeatedly revise the design for probe guesses. Fix the minimal mechanism, rerun the real suite, then reserve time for final review/handoff. This advice grants no execution or approval authority.` };
+}

package/lib/providers/experiential.mjs

@@ -0,0 +1,292 @@
+import os from 'node:os';
+import { CloudClient, cloudControlUrl, oauthCredentials, openBrowser } from '../cloud/client.mjs';
+import { streamSimple as streamOpenAiCompletions } from '../../vendor/agent/chunks/openai-completions-EKZT2IH2.js';
+import { shipAgentDir } from '../ship-auth.mjs';
+import { shipInstallId, shipRequestHeaders } from '../ship-telemetry.mjs';
+import { packageVersion } from '../update.mjs';
+import { CARTHAGENT_SHIP_PROVIDER_ID, CARTHAGENT_SHIP_PROVIDER_NAME } from './names.mjs';
+
+const DEFAULT_BASE_URL = 'https://api.experientiallabs.ai/v1';
+const PROVIDER_ID = CARTHAGENT_SHIP_PROVIDER_ID;
+const MANAGED_CLOUD_NON_RETRYABLE_ERRORS = /\b(?:idempotency_key_reused|request_reconciliation_required)\b/i;
+
+const OPENAI_REASONING_LEVELS = Object.freeze({
+  off: 'none', minimal: null, low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max',
+});
+const REQUIRED_REASONING_LEVEL = Object.freeze({
+  off: null, minimal: null, low: null, medium: 'medium', high: null, xhigh: null, max: null,
+});
+const MERCURY_REASONING_LEVELS = Object.freeze({
+  off: null, minimal: null, low: 'low', medium: 'medium', high: 'high', xhigh: null, max: null,
+});
+const DEEPSEEK_REASONING_LEVELS = Object.freeze({
+  off: null, minimal: null, low: 'low', medium: null, high: 'high', xhigh: null, max: 'max',
+});
+// SkyPilot's DeepSeek accepts reasoning off; a non-null off level makes the
+// engine send thinking:{type:'disabled'} (the mapped string itself is not
+// emitted — 'none' also works upstream, but the wire form is the thinking flag).
+const SKYPILOT_DEEPSEEK_LEVELS = Object.freeze({
+  off: 'none', minimal: null, low: 'low', medium: null, high: 'high', xhigh: null, max: 'max',
+});
+// Kimi K3 and GLM 5.3 always reason; 'off' is unavailable upstream.
+const TIERED_REASONING_LEVELS = Object.freeze({
+  off: null, minimal: null, low: 'low', medium: null, high: 'high', xhigh: null, max: 'max',
+});
+// Beam always reasons but accepts the full low→max effort ladder; 'minimal',
+// 'none', and the thinking flag are rejected upstream, so they stay unmapped.
+const BEAM_REASONING_LEVELS = Object.freeze({
+  off: null, minimal: null, low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max',
+});
+// Mercury 3 accepts only 'instant' | 'low' | 'medium' | 'high'. 'instant' is its
+// real no-reasoning mode (the thinking flag is ignored upstream), and 'xhigh'/
+// 'max' are rejected, so they stay unmapped.
+const MERCURY3_REASONING_LEVELS = Object.freeze({
+  off: 'instant', minimal: 'low', low: 'low', medium: 'medium', high: 'high', xhigh: null, max: null,
+});
+
+// Experiential's /models response is intentionally OpenAI-compatible and often
+// identity-only. Keep the capability facts needed by the engine here rather
+// than guessing from the selected model at request time.
+const EXPERIENTIAL_MODEL_PROFILES = Object.freeze({
+  'gpt-5.6-luna': { name: 'GPT-5.6 Luna', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'gpt-5.6-luna-pro': { name: 'GPT-5.6 Luna Pro', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'gpt-5.6-sol': { name: 'GPT-5.6 Sol', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'gpt-5.6-terra': { name: 'GPT-5.6 Terra', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'gpt-6-astra': { name: 'GPT-6 Astra', reasoning: true, thinkingLevelMap: { ...OPENAI_REASONING_LEVELS, off: null }, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'gpt-6-luna': { name: 'GPT-6 Luna', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'deepseek-v4-flash': { name: 'DeepSeek V4 Flash', reasoning: true, thinkingLevelMap: DEEPSEEK_REASONING_LEVELS, contextWindow: 1_000_000, maxTokens: 384_000, input: ['text'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: true, thinkingFormat: 'deepseek' } },
+  'gpt-6-sol': { name: 'GPT-6 Sol', reasoning: true, thinkingLevelMap: OPENAI_REASONING_LEVELS, contextWindow: 1_050_000, maxTokens: 128_000, input: ['text', 'image'], compat: { supportsReasoningEffort: true } },
+  'mercury-2': { name: 'Mercury 2', reasoning: true, thinkingLevelMap: MERCURY_REASONING_LEVELS, contextWindow: 128_000, maxTokens: 50_000, input: ['text'], compat: { supportsReasoningEffort: true } },
+  'kimi-k2-thinking': { name: 'Kimi K2 Thinking', reasoning: true, thinkingLevelMap: REQUIRED_REASONING_LEVEL, contextWindow: 262_144, maxTokens: 98_304, input: ['text'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, thinkingFormat: 'deepseek' } },
+  'qwen3-max-thinking': { name: 'Qwen3 Max Thinking', reasoning: true, thinkingLevelMap: REQUIRED_REASONING_LEVEL, contextWindow: 262_144, maxTokens: 65_536, input: ['text'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, thinkingFormat: 'qwen' } },
+  'sonar-reasoning-pro': { name: 'Sonar Reasoning Pro', reasoning: true, thinkingLevelMap: REQUIRED_REASONING_LEVEL, input: ['text'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: false } },
+  'deepseek-v4.1-flash': { name: 'DeepSeek V4.1 Flash', reasoning: true, thinkingLevelMap: SKYPILOT_DEEPSEEK_LEVELS, contextWindow: 1_048_576, maxTokens: 32_768, input: ['text', 'image'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: true, thinkingFormat: 'deepseek' } },
+  'glm-5.3-flash': { name: 'GLM 5.3 Flash', reasoning: true, thinkingLevelMap: TIERED_REASONING_LEVELS, contextWindow: 1_048_576, maxTokens: 32_768, input: ['text', 'image'], compat: { supportsReasoningEffort: true, thinkingFormat: 'zai' } },
+  'glm-5.3': { name: 'GLM 5.3', reasoning: true, thinkingLevelMap: TIERED_REASONING_LEVELS, contextWindow: 1_048_576, maxTokens: 32_768, input: ['text'], compat: { supportsReasoningEffort: true, thinkingFormat: 'zai' } },
+  'kimi-k3': { name: 'Kimi K3', reasoning: true, thinkingLevelMap: TIERED_REASONING_LEVELS, contextWindow: 1_048_576, maxTokens: 32_768, input: ['text'], compat: { supportsDeveloperRole: false, supportsReasoningEffort: true, thinkingFormat: 'deepseek' } },
+  'beam-1.0-501b-a23b': { name: 'Beam 1.0 501B A23B', reasoning: true, thinkingLevelMap: BEAM_REASONING_LEVELS, contextWindow: 1_048_576, maxTokens: 32_768, input: ['text'], compat: { supportsReasoningEffort: true } },
+  'mercury-3': { name: 'Mercury 3', reasoning: true, thinkingLevelMap: MERCURY3_REASONING_LEVELS, contextWindow: 1_048_576, maxTokens: 131_072, input: ['text'], compat: { supportsReasoningEffort: true } },
+});
+
+const MODEL_METADATA_FIELDS = ['reasoning', 'thinkingLevelMap', 'contextWindow', 'maxTokens', 'input', 'output', 'compat'];
+
+export const EXPERIENTIAL_PROVIDER_ID = PROVIDER_ID;
+export const EXPERIENTIAL_PROVIDER_NAME = CARTHAGENT_SHIP_PROVIDER_NAME;
+export const EXPERIENTIAL_API_KEY_ENV = 'EXPLABS_API_KEY';
+export const EXPERIENTIAL_GATEWAY_URL_ENV = 'EXP_GATEWAY_URL';
+
+export function experientialBaseUrl(env = process.env) {
+  const gatewayOverride = env?.[EXPERIENTIAL_GATEWAY_URL_ENV]?.trim();
+  return (gatewayOverride || DEFAULT_BASE_URL).replace(/\/+$/, '');
+}
+
+export function cloudGatewayUrl(env = process.env) {
+  return `${cloudControlUrl(env).replace(/\/v1$/, '')}/v1`;
+}
+
+export function isCloudAccessToken(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) return false;
+  try {
+    const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    return typeof claims.sub === 'string' && typeof claims.sid === 'string'
+      && String(claims.scope || '').split(' ').includes('gateway:invoke');
+  } catch { return false; }
+}
+
+export function createCloudOperationIdentity(id = globalThis.crypto?.randomUUID?.bind(globalThis.crypto)) {
+  if (typeof id !== 'function') throw new Error('Managed Cloud requests require UUID support.');
+  const operationKey = id();
+  if (typeof operationKey !== 'string' || !operationKey.trim()) throw new Error('Managed Cloud operation identity is invalid.');
+  return operationKey.trim();
+}
+
+export function isManagedCloudNonRetryableError(message) {
+  return MANAGED_CLOUD_NON_RETRYABLE_ERRORS.test(String(message || ''));
+}
+
+export function managedCloudRequestOptions(options = {}, id) {
+  const operationKey = createCloudOperationIdentity(id);
+  const inheritedHeaders = options.requestHeaders && typeof options.requestHeaders === 'object'
+    ? options.requestHeaders : {};
+  return {
+    ...options,
+    // The gateway currently reserves before dispatch but cannot replay or wait
+    // for an existing operation. Retrying this identity would therefore return
+    // idempotency_key_reused/request_reconciliation_required instead of the
+    // original result. Keep one physical HTTP attempt until replay exists.
+    maxRetries: 0,
+    requestHeaders: {
+      ...inheritedHeaders,
+      'Idempotency-Key': operationKey,
+      'X-Client-Request-Id': operationKey,
+      // Metadata-only Ship telemetry: thread, turn, install, client build.
+      ...shipRequestHeaders({ version: packageVersion() }),
+    },
+    onPayload: async (payload, activeModel) => {
+      const next = await options.onPayload?.(payload, activeModel);
+      const body = { ...(next ?? payload), metadata: { ...(next ?? payload).metadata, operation_key: operationKey } };
+      // The engine emits thinking:{type:'disabled'} whenever no effort is
+      // selected, but always-reasoning upstreams (off level unavailable,
+      // thinkingLevelMap.off === null) reject it outright. Omit the field so
+      // the model reasons at its default instead.
+      if (body.thinking?.type === 'disabled' && activeModel?.thinkingLevelMap?.off === null) {
+        delete body.thinking;
+      }
+      return body;
+    },
+  };
+}
+
+export function experientialModelDefinition(model) {
+  const id = typeof model === 'string' ? model : model?.id;
+  if (typeof id !== 'string' || !id.trim()) return null;
+  const normalizedId = id.trim();
+  // Managed aliases may be namespace-qualified (for example openai/gpt-6-luna)
+  // while direct Experiential discovery returns the upstream id.
+  const profileId = normalizedId.split('/').at(-1);
+  const profile = EXPERIENTIAL_MODEL_PROFILES[normalizedId] || EXPERIENTIAL_MODEL_PROFILES[profileId] || {};
+  const suppliedName = typeof model === 'object' && typeof model.name === 'string' && model.name.trim()
+    ? model.name.trim() : '';
+  const definition = { id: normalizedId, name: suppliedName || profile.name || normalizedId, ...profile };
+
+  // Preserve authoritative metadata if a future Experiential response starts
+  // publishing it. Stored catalogs also pass through here during offline load.
+  if (model && typeof model === 'object') {
+    for (const field of MODEL_METADATA_FIELDS) if (model[field] !== undefined) definition[field] = model[field];
+    // Managed aliases publish their operating caps (contextWindow = the usable
+    // input window, maxTokens = the output ceiling). The model profile may
+    // declare a smaller real capability, so keep the stricter value: engine
+    // auto-compaction and the output budget then respect both bounds.
+    for (const field of ['contextWindow', 'maxTokens']) {
+      if (typeof model[field] === 'number' && typeof profile[field] === 'number') {
+        definition[field] = Math.min(model[field], profile[field]);
+      }
+    }
+  }
+
+  // Cover explicit fixed-thinking aliases that can be added to the provider
+  // before this curated table is updated. This is capability resolution, not
+  // context/pricing inference: the name itself declares that reasoning is on.
+  if (definition.reasoning === undefined && /(?:^|[-_.])(?:thinking|reasoning)(?:$|[-_.])/i.test(normalizedId)) {
+    definition.reasoning = true;
+    definition.thinkingLevelMap = REQUIRED_REASONING_LEVEL;
+  }
+  return definition;
+}
+
+export function parseExperientialModels(payload) {
+  const data = Array.isArray(payload?.data) ? payload.data : [];
+  const seen = new Set();
+  const models = [];
+  for (const item of data) {
+    const model = experientialModelDefinition(item);
+    if (!model || seen.has(model.id)) continue;
+    seen.add(model.id);
+    models.push(model);
+  }
+  return models.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function cloudOAuth({ env = process.env, fetchImpl = globalThis.fetch, sleep, now = Date.now, openBrowserImpl = openBrowser } = {}) {
+  const client = new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl, sleep });
+  return {
+    name: 'Carthagent Ship account',
+    async login(interaction) {
+      const tokens = await client.authorizeDevice({
+        clientName: `Carthagent CLI (${os.hostname()})`,
+        installId: shipInstallId({ agentDir: shipAgentDir(env) }),
+        signal: interaction.signal,
+        notify: event => {
+          if (event.type === 'device_code') interaction.onDeviceCode?.({
+            userCode: event.userCode,
+            verificationUri: event.verificationUri,
+            intervalSeconds: event.intervalSeconds,
+            expiresInSeconds: event.expiresInSeconds,
+          });
+          else if (event.type === 'auth_url') {
+            Promise.resolve(openBrowserImpl?.(event.url)).catch(() => false);
+            interaction.onAuth?.({ url: event.url, instructions: `${event.instructions} The URL is also shown if Carthagent cannot open it automatically.` });
+          }
+          else if (event.type === 'progress') interaction.onProgress?.(event.message);
+        },
+      });
+      return oauthCredentials(tokens, now());
+    },
+    async refreshToken(credentials, signal) {
+      return oauthCredentials(await client.refresh({ refreshToken: credentials.refresh, signal }), now());
+    },
+    getApiKey(credentials) { return credentials.access; },
+  };
+}
+
+export function experientialProviderConfig({ env = process.env, fetchImpl = globalThis.fetch, sleep, now, openBrowserImpl } = {}) {
+  const oauth = cloudOAuth({ env, fetchImpl, sleep, now, openBrowserImpl });
+  const baseUrl = experientialBaseUrl(env);
+  const dynamicModels = [];
+  const installModels = models => {
+    dynamicModels.splice(0, dynamicModels.length, ...models);
+  };
+  return {
+    name: EXPERIENTIAL_PROVIDER_NAME,
+    baseUrl,
+    api: 'openai-completions',
+    apiKey: `$${EXPERIENTIAL_API_KEY_ENV}`,
+    authHeader: true,
+    oauth,
+    streamSimple(model, context, options = {}) {
+      const managed = isCloudAccessToken(options.apiKey);
+      const requestOptions = managed ? managedCloudRequestOptions(options) : options;
+      const stream = streamOpenAiCompletions(managed ? { ...model, baseUrl: cloudGatewayUrl(env) } : model, context, requestOptions);
+      if (!managed) return stream;
+      const result = stream.result.bind(stream);
+      stream.result = async () => {
+        const message = await result();
+        if (message?.stopReason === 'error' && isManagedCloudNonRetryableError(message.errorMessage)) {
+          message.errorMessage = `Carthagent Ship cannot safely replay this operation yet. ${message.errorMessage}`;
+        }
+        return message;
+      };
+      return stream;
+    },
+    models: dynamicModels,
+    async refreshModels(context) {
+      const storedModels = Array.isArray(context.stored) ? context.stored : (Array.isArray(context.stored?.models) ? context.stored.models : []);
+      if (storedModels.length) {
+        const restored = storedModels.map(experientialModelDefinition).filter(Boolean);
+        if (context.publish) await context.publish({ update: () => installModels(restored) });
+        else installModels(restored);
+      }
+      if (!context.allowNetwork) return storedModels;
+      const managed = context.credential?.type === 'oauth';
+      const key = context.credential?.type === 'api_key' ? context.credential.key
+        : managed ? context.credential.access : '';
+      if (!key) return storedModels;
+      if (typeof fetchImpl !== 'function') throw new Error('Carthagent Ship model discovery requires fetch support.');
+      const response = await fetchImpl(`${managed ? cloudGatewayUrl(env) : baseUrl}/models`, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${key}` },
+        signal: context.signal,
+      });
+      if (!response.ok) {
+        const detail = String(await response.text()).trim().slice(0, 240);
+        throw new Error(`Carthagent Ship model discovery failed (${response.status})${detail ? `: ${detail}` : ''}`);
+      }
+      const models = parseExperientialModels(await response.json());
+      if (!models.length) throw new Error('Carthagent Ship returned no models for this account.');
+      if (context.publish) {
+        await context.publish({
+          persist: { models, checkedAt: Date.now() },
+          update: () => installModels(models),
+        });
+      } else installModels(models);
+      return models;
+    },
+  };
+}
+
+export function registerExperientialProvider(runtime, options) {
+  if (!runtime || typeof runtime.registerProvider !== 'function') throw new TypeError('A ModelRuntime is required.');
+  runtime.registerProvider(PROVIDER_ID, experientialProviderConfig(options));
+  return runtime;
+}