@amalgm/chat 0.1.2 → 0.2.1

package/host/model-resolution.js

@@ -0,0 +1,313 @@
+/**
+ * Native model preparation.
+ *
+ * The public execution contract carries the selected provider-scoped identity.
+ * Preparation derives two different host facts from it: the gateway identity
+ * used for usage/auth and the exact token accepted by the selected CLI. These
+ * identities are deliberately never substituted for one another.
+ */
+
+const GATEWAY_PROVIDERS = [
+  'prime-intellect',
+  'arcee-ai',
+  'alibaba',
+  'amazon',
+  'anthropic',
+  'bytedance',
+  'cohere',
+  'cursor',
+  'deepseek',
+  'google',
+  'inception',
+  'kwaipilot',
+  'meituan',
+  'meta',
+  'minimax',
+  'mistral',
+  'moonshotai',
+  'morph',
+  'nvidia',
+  'openai',
+  'perplexity',
+  'xiaomi',
+  'xai',
+  'zai',
+];
+
+const CLAUDE_ALIASES = {
+  haiku: 'anthropic/claude-haiku-4.5',
+  sonnet: 'anthropic/claude-sonnet-5',
+  'sonnet[1m]': 'anthropic/claude-sonnet-5',
+  opus: 'anthropic/claude-opus-4.8',
+  opus1m: 'anthropic/claude-opus-4.8-1m',
+  'opus[1m]': 'anthropic/claude-opus-4.8-1m',
+  fable: 'anthropic/claude-fable-5',
+};
+
+const CLAUDE_CLI_MODELS = {
+  'anthropic/claude-haiku-4.5': 'haiku',
+  'anthropic/claude-sonnet-5': 'sonnet',
+  'anthropic/claude-sonnet-4.6': 'sonnet',
+  'anthropic/claude-opus-4.8': 'opus',
+  'anthropic/claude-opus-4.8-1m': 'opus[1m]',
+  'anthropic/claude-opus-4.7': 'opus',
+  'anthropic/claude-opus-4.7-1m': 'opus[1m]',
+  'anthropic/claude-fable-5': 'claude-fable-5',
+};
+
+const CURSOR_CLI_ALIASES = {
+  'composer-2': 'composer-2.5',
+  'composer-2-fast': 'composer-2.5-fast',
+  'claude-fable-5': 'claude-fable-5-high',
+  'claude-fable-5-thinking': 'claude-fable-5-thinking-high',
+  'claude-opus-4-8': 'claude-opus-4-8-high',
+  'claude-opus-4-8-thinking': 'claude-opus-4-8-thinking-high',
+  'claude-opus-4-7': 'claude-opus-4-7-xhigh',
+  'claude-opus-4-7-thinking': 'claude-opus-4-7-thinking-xhigh',
+  'claude-opus-4-6': 'claude-4.6-opus-high',
+  'claude-opus-4-6-thinking': 'claude-4.6-opus-high-thinking',
+  'claude-opus-4-5': 'claude-4.5-opus-high',
+  'claude-opus-4-5-thinking': 'claude-4.5-opus-high-thinking',
+  'claude-sonnet-5': 'claude-sonnet-5-high',
+  'claude-sonnet-5-thinking': 'claude-sonnet-5-thinking-high',
+  'claude-sonnet-4-6': 'claude-4.6-sonnet-medium',
+  'claude-sonnet-4-6-thinking': 'claude-4.6-sonnet-medium-thinking',
+  'gpt-5.5': 'gpt-5.5-medium',
+  'gpt-5.4': 'gpt-5.4-medium',
+  'gpt-5.4-mini': 'gpt-5.4-mini-medium',
+  'gpt-5.4-nano': 'gpt-5.4-nano-medium',
+  'grok-4.5': 'grok-4.5-xhigh',
+  'glm-5.2': 'glm-5.2-high',
+};
+
+const CURSOR_CANONICAL_ALIASES = {
+  'cursor/composer-2': 'cursor/composer-2.5',
+  'cursor/composer-2-fast': 'cursor/composer-2.5-fast',
+  'anthropic/claude-fable-5': 'anthropic/claude-fable-5-high',
+  'anthropic/claude-fable-5-thinking': 'anthropic/claude-fable-5-thinking-high',
+  'anthropic/claude-opus-4.8': 'anthropic/claude-opus-4.8-high',
+  'anthropic/claude-opus-4.8-thinking': 'anthropic/claude-opus-4.8-thinking-high',
+  'anthropic/claude-opus-4.7': 'anthropic/claude-opus-4.7-xhigh',
+  'anthropic/claude-opus-4.7-thinking': 'anthropic/claude-opus-4.7-thinking-xhigh',
+  'anthropic/claude-opus-4.6': 'anthropic/claude-opus-4.6-high',
+  'anthropic/claude-opus-4.6-thinking': 'anthropic/claude-opus-4.6-high-thinking',
+  'anthropic/claude-opus-4.5': 'anthropic/claude-opus-4.5-high',
+  'anthropic/claude-opus-4.5-thinking': 'anthropic/claude-opus-4.5-high-thinking',
+  'anthropic/claude-sonnet-5': 'anthropic/claude-sonnet-5-high',
+  'anthropic/claude-sonnet-5-thinking': 'anthropic/claude-sonnet-5-thinking-high',
+  'anthropic/claude-sonnet-4.6': 'anthropic/claude-sonnet-4.6-medium',
+  'anthropic/claude-sonnet-4.6-thinking': 'anthropic/claude-sonnet-4.6-medium-thinking',
+  'openai/gpt-5.5': 'openai/gpt-5.5-medium',
+  'openai/gpt-5.4': 'openai/gpt-5.4-medium',
+  'openai/gpt-5.4-mini': 'openai/gpt-5.4-mini-medium',
+  'openai/gpt-5.4-nano': 'openai/gpt-5.4-nano-medium',
+  'google/gemini-3.1-pro-preview': 'google/gemini-3.1-pro',
+  'xai/grok-4.5': 'xai/grok-4.5-xhigh',
+  'zai/glm-5.2': 'zai/glm-5.2-high',
+};
+
+function setting(settings, ...ids) {
+  for (const id of ids) {
+    const match = settings.find((candidate) => candidate.configId === id);
+    if (match) return match.value;
+  }
+  return null;
+}
+
+function selectedModelId(contract) {
+  const { adapterId } = contract.agent;
+  const { providerId, modelId } = contract.model;
+  if ((adapterId === 'opencode' || adapterId === 'pi' || adapterId === 'amp')
+    && providerId === adapterId) {
+    return modelId;
+  }
+  return modelId.startsWith(`${providerId}/`) ? modelId : `${providerId}/${modelId}`;
+}
+
+export function gatewayModelId(raw) {
+  let bare = String(raw || '').trim()
+    .replace(/^opencode-/, '')
+    .replace(/^pi-/, '')
+    .replace(/^vercel\//, '');
+  if (bare.includes('/')) return bare;
+  for (const provider of GATEWAY_PROVIDERS) {
+    const prefix = `${provider}-`;
+    if (bare.startsWith(prefix)) {
+      const model = bare.slice(prefix.length);
+      return `${provider}/${provider === 'anthropic'
+        ? model.replace(/-(\d+)-(\d+)(?=$|-)/, '-$1.$2')
+        : model}`;
+    }
+  }
+  return bare;
+}
+
+function claudeModelId(raw) {
+  const clean = String(raw || '').trim().replace(/^vercel\//i, '').toLowerCase();
+  if (CLAUDE_ALIASES[clean]) return CLAUDE_ALIASES[clean];
+  if (clean.startsWith('claude-code-')) {
+    return claudeModelId(clean.slice('claude-code-'.length));
+  }
+  if (clean.startsWith('anthropic/')) {
+    return clean.replace(/-(\d+)-(\d+)(?=$|-)/, '-$1.$2');
+  }
+  if (clean.startsWith('claude-')) {
+    return `anthropic/${clean.replace(/-(\d+)-(\d+)(?=$|-)/, '-$1.$2')}`;
+  }
+  return clean;
+}
+
+function claudeCliModel(modelId) {
+  const canonical = claudeModelId(modelId);
+  return CLAUDE_CLI_MODELS[canonical] || canonical.replace(/^anthropic\//, '');
+}
+
+function cursorAnthropicCliModel(model) {
+  const versioned = model.match(/^claude-(opus|sonnet)-(4(?:\.\d+)?)(?:-(.+))?$/);
+  if (!versioned) return model.replace(/-(\d+)\.(\d+)(?=$|-)/, '-$1-$2');
+  const [, family, version, rawSuffix] = versioned;
+  const suffix = rawSuffix || '';
+  if (family === 'sonnet' && version === '4.6') {
+    if (!suffix) return 'claude-4.6-sonnet-medium';
+    if (suffix === 'thinking') return 'claude-4.6-sonnet-medium-thinking';
+    return `claude-4.6-sonnet-${suffix}`;
+  }
+  if (family === 'sonnet' && (version === '4.5' || version === '4')) {
+    if (version === '4' && !suffix) return 'claude-sonnet-4';
+    return `claude-${version}-sonnet${suffix ? `-${suffix}` : ''}`;
+  }
+  if (family === 'opus' && version === '4.6') {
+    if (!suffix) return 'claude-4.6-opus-high';
+    if (suffix === 'thinking') return 'claude-4.6-opus-high-thinking';
+    return `claude-4.6-opus-${suffix}`;
+  }
+  if (family === 'opus' && version === '4.5') {
+    if (!suffix) return 'claude-4.5-opus-high';
+    if (suffix === 'thinking') return 'claude-4.5-opus-high-thinking';
+    return `claude-4.5-opus-${suffix}`;
+  }
+  return model.replace(/-(\d+)\.(\d+)(?=$|-)/, '-$1-$2');
+}
+
+function cursorCliModel(raw) {
+  const clean = String(raw || '').trim().replace(/^vercel\//i, '').toLowerCase();
+  const canonical = CURSOR_CANONICAL_ALIASES[clean] || clean;
+  if (canonical.startsWith('cursor/')) {
+    const model = canonical.slice('cursor/'.length);
+    return CURSOR_CLI_ALIASES[model] || model;
+  }
+  if (canonical.startsWith('openai/')) return canonical.slice('openai/'.length);
+  if (canonical.startsWith('google/')) return canonical.slice('google/'.length);
+  if (canonical.startsWith('moonshotai/')) return canonical.slice('moonshotai/'.length);
+  if (canonical.startsWith('zai/')) return canonical.slice('zai/'.length);
+  if (canonical.startsWith('xai/')) {
+    return canonical.slice('xai/'.length).replace(/^grok-4\.20/, 'grok-4-20');
+  }
+  if (canonical.startsWith('anthropic/')) {
+    return cursorAnthropicCliModel(canonical.slice('anthropic/'.length));
+  }
+  return CURSOR_CLI_ALIASES[canonical] || canonical;
+}
+
+function cursorUsageModelId(raw) {
+  const canonical = CURSOR_CANONICAL_ALIASES[String(raw || '').toLowerCase()] || String(raw || '').toLowerCase();
+  if (canonical.startsWith('cursor/')) return canonical;
+  if (canonical.startsWith('openai/')) {
+    const model = canonical.slice('openai/'.length);
+    for (const base of [
+      'gpt-5.5', 'gpt-5.4-mini', 'gpt-5.4-nano', 'gpt-5.4',
+      'gpt-5.3-codex-spark', 'gpt-5.3-codex', 'gpt-5.2-codex', 'gpt-5.2',
+      'gpt-5.1-codex-max', 'gpt-5.1-codex-mini', 'gpt-5.1',
+    ]) {
+      if (model.startsWith(base)) return `openai/${base}`;
+    }
+    return canonical;
+  }
+  if (canonical.startsWith('anthropic/')) {
+    const model = canonical.slice('anthropic/'.length);
+    for (const base of [
+      'claude-fable-5', 'claude-opus-4.8', 'claude-opus-4.7',
+      'claude-opus-4.6', 'claude-opus-4.5', 'claude-sonnet-5',
+      'claude-sonnet-4.6', 'claude-sonnet-4.5', 'claude-sonnet-4',
+    ]) {
+      if (model.startsWith(base)) return `anthropic/${base}`;
+    }
+  }
+  if (canonical.startsWith('moonshotai/kimi-k2.7')) return 'moonshotai/kimi-k2.7-code';
+  if (canonical.startsWith('xai/grok-4.5')) return 'xai/grok-4.5';
+  if (canonical.startsWith('zai/glm-5.2')) return 'zai/glm-5.2';
+  return canonical;
+}
+
+function codexFacts(selected, settings) {
+  let normalizedModelId = selected;
+  let base = selected.replace(/^openai\//, '');
+  let reasoningEffort = setting(settings, 'thought_level', 'reasoning_effort', 'reasoning');
+  const suffix = base.match(/(?:-thinking-|\/)(low|medium|high|xhigh|max|ultra)$/i);
+  if (suffix) {
+    reasoningEffort ||= suffix[1].toLowerCase();
+    base = base.slice(0, -suffix[0].length);
+  }
+  if (!normalizedModelId.includes('/')) normalizedModelId = `openai/${normalizedModelId}`;
+  return {
+    normalizedModelId,
+    usageModelId: `openai/${base}`,
+    cliModel: reasoningEffort ? `${base}/${reasoningEffort}` : base,
+    reasoningEffort: typeof reasoningEffort === 'string' ? reasoningEffort : null,
+  };
+}
+
+export function resolveNativeModel(contract) {
+  const adapterId = contract.agent.adapterId;
+  const selected = selectedModelId(contract);
+  const settings = contract.model.settings || [];
+  const speed = setting(settings, 'speed', 'fast');
+  let normalizedModelId;
+  let usageModelId;
+  let cliModel;
+  let reasoningEffort = setting(settings, 'thought_level', 'reasoning_effort', 'reasoning');
+
+  if (adapterId === 'claude_code') {
+    normalizedModelId = claudeModelId(selected);
+    usageModelId = normalizedModelId === 'anthropic/claude-opus-4.8-1m'
+      ? 'anthropic/claude-opus-4.8'
+      : normalizedModelId;
+    cliModel = claudeCliModel(normalizedModelId);
+  } else if (adapterId === 'codex') {
+    const codex = codexFacts(selected, settings);
+    ({ normalizedModelId, usageModelId, cliModel, reasoningEffort } = codex);
+  } else if (adapterId === 'cursor') {
+    normalizedModelId = selected;
+    usageModelId = cursorUsageModelId(selected);
+    cliModel = cursorCliModel(selected);
+  } else if (adapterId === 'opencode') {
+    normalizedModelId = gatewayModelId(selected);
+    usageModelId = normalizedModelId;
+    cliModel = `vercel/${normalizedModelId}`;
+  } else if (adapterId === 'pi') {
+    normalizedModelId = gatewayModelId(selected);
+    usageModelId = normalizedModelId;
+    cliModel = normalizedModelId;
+  } else {
+    normalizedModelId = selected;
+    usageModelId = selected;
+    cliModel = contract.model.modelId;
+  }
+
+  const slash = usageModelId.indexOf('/');
+  return Object.freeze({
+    selectedModelId: selected,
+    normalizedModelId,
+    usageModelId,
+    cliModel,
+    providerId: slash > 0 ? usageModelId.slice(0, slash) : contract.model.providerId,
+    providerModelId: slash > 0 ? usageModelId.slice(slash + 1) : contract.model.modelId,
+    reasoningEffort: typeof reasoningEffort === 'string' ? reasoningEffort : null,
+    fastMode: speed === true || speed === 'fast',
+  });
+}
+
+/** Backward-compatible named surface for hosts that only need the CLI token. */
+export function nativeModel(contract) {
+  return resolveNativeModel(contract).cliModel;
+}

package/host/native-contract.js

@@ -0,0 +1,185 @@
+import { createHmac, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { authEnvelope } from './auth.js';
+import { amalgmDir } from './lib/runtime-paths.js';
+import { resolveNativeModel } from './model-resolution.js';
+
+export { nativeModel } from './model-resolution.js';
+
+const AUTH_METHOD = {
+  platform: 'amalgm',
+  subscription: 'provider_auth',
+  byok: 'byok',
+};
+
+function sessionAuth(auth, sessionId, localEgressSecret) {
+  if (auth.method !== 'amalgm') return auth;
+  const replace = (value) => typeof value === 'string'
+    ? value.replaceAll(encodeURIComponent('__prepared__'), encodeURIComponent(sessionId))
+    : value;
+  return {
+    ...auth,
+    baseUrl: replace(auth.baseUrl),
+    tokenRef: `session-local-${createHmac('sha256', localEgressSecret).update(sessionId).digest('base64url')}`,
+  };
+}
+
+function requireCurrentComputer(contract, currentComputerId) {
+  if (currentComputerId && contract.computerId !== currentComputerId) {
+    throw new Error(
+      `Prepared execution targets ${contract.computerId}, but this runtime is ${currentComputerId}`,
+    );
+  }
+}
+
+export class InvalidPreparedAuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'InvalidPreparedAuthError';
+    this.code = 'INVALID_PREPARED_AUTH';
+  }
+}
+
+export class NativeExecutionPreparer {
+  constructor(options = {}) {
+    this.currentComputerId = options.currentComputerId || null;
+    this.resolveTools = options.resolveTools || (async (tools) => {
+      if (tools.toolIds.length > 0) {
+        throw new Error('Native runtime requires resolveTools for a non-empty tool selection');
+      }
+      return [];
+    });
+    this.resolveAgent = options.resolveAgent || (async () => ({
+      agentConfig: {},
+      compiledAgentInstructions: '',
+    }));
+    this.validateModel = options.validateModel || (async () => undefined);
+    this.resolveModel = options.resolveModel || resolveNativeModel;
+    this.resolveAuth = options.resolveAuth || ((selection, contract, context) => authEnvelope({
+      harness: contract.agent.adapterId,
+      authMethod: context.authMethod,
+      sessionId: '__prepared__',
+      localBaseUrl: this.resolveLocalBaseUrl(),
+      proxyBaseUrl: this.proxyBaseUrl,
+      amalgmDir: this.amalgmDir,
+      runtimeHomeRoot: this.runtimeHomeRoot,
+      credentialId: selection.mode === 'byok' && selection.bindingId !== 'default'
+        ? selection.bindingId
+        : null,
+      modelId: context.modelId,
+      agentConfigId: contract.agent.installationId,
+    }));
+    this.localBaseUrl = options.localBaseUrl || null;
+    this.amalgmDir = options.amalgmDir || amalgmDir();
+    this.runtimeHomeRoot = path.resolve(
+      options.runtimeHomeRoot || path.join(this.amalgmDir, 'cli-homes'),
+    );
+    this.proxyBaseUrl = options.proxyBaseUrl || process.env.AMALGM_PROXY_URL || '';
+    this.credentialBroker = options.credentialBroker || null;
+    this.localEgressSecret = options.localEgressSecret || randomBytes(32).toString('base64url');
+  }
+
+  resolveLocalBaseUrl() {
+    const value = typeof this.localBaseUrl === 'function'
+      ? this.localBaseUrl()
+      : this.localBaseUrl;
+    return typeof value === 'string' && value.trim() ? value.replace(/\/$/, '') : null;
+  }
+
+  async resolvePreparedAuth(selection, contract, context) {
+    try {
+      return await this.resolveAuth(selection, contract, context);
+    } catch (error) {
+      if (error instanceof InvalidPreparedAuthError) throw error;
+      throw new InvalidPreparedAuthError(
+        error instanceof Error ? error.message : 'Unable to resolve the prepared auth binding',
+      );
+    }
+  }
+
+  async prepare(contract) {
+    requireCurrentComputer(contract, this.currentComputerId);
+    if (!fs.statSync(contract.cwd.path).isDirectory()) {
+      throw new Error(`Prepared cwd is not a directory: ${contract.cwd.path}`);
+    }
+
+    const authMethod = AUTH_METHOD[contract.auth.mode];
+    const model = await this.resolveModel(contract);
+    const [tools, agent, , auth] = await Promise.all([
+      this.resolveTools(contract.tools, contract),
+      this.resolveAgent(contract.agent, contract),
+      this.validateModel(contract.model, contract.agent),
+      this.resolvePreparedAuth(contract.auth, contract, { authMethod, modelId: model.usageModelId }),
+    ]);
+    if (!Array.isArray(tools)) throw new Error('resolveTools must return ACP/native MCP server configs');
+    if (!auth || typeof auth !== 'object') {
+      throw new InvalidPreparedAuthError('resolveAuth must return a prepared auth binding');
+    }
+    if (auth.method !== authMethod) {
+      throw new InvalidPreparedAuthError(
+        `${contract.agent.adapterId} does not support ${contract.auth.mode} auth; no fallback is allowed`,
+      );
+    }
+
+    const preparedAuth = Object.freeze({
+      ...auth,
+      mode: contract.auth.mode,
+      bindingId: contract.auth.bindingId,
+    });
+
+    return Object.freeze({
+      adapterId: contract.agent.adapterId,
+      base: Object.freeze({
+        userId: 'prepared-user',
+        computerId: contract.computerId,
+        agentId: contract.agent.installationId,
+        agentConfigId: contract.agent.installationId,
+        agentRevisionId: contract.agent.revisionId,
+        agentRevision: contract.agent,
+        agentConfig: agent?.agentConfig || {},
+        acpLaunch: agent?.acpLaunch || null,
+        harness: contract.agent.adapterId,
+        authMethod,
+        selectedModelId: model.selectedModelId,
+        modelId: model.normalizedModelId,
+        providerId: model.providerId,
+        providerModelId: model.providerModelId,
+        modelSettings: contract.model.settings,
+        usageModelId: model.usageModelId,
+        cliModel: model.cliModel,
+        reasoningEffort: model.reasoningEffort,
+        fastMode: model.fastMode,
+        contextWindow: null,
+        maxTokens: null,
+        cwd: contract.cwd.path,
+        localBaseUrl: this.resolveLocalBaseUrl(),
+        mcpServers: tools,
+        toolSelection: contract.tools,
+        compiledAgentInstructions: agent?.compiledAgentInstructions || '',
+        permissionMode: contract.permissionMode,
+        executionComputerId: contract.computerId,
+        usageOwner: contract.auth.mode === 'platform' ? 'platform_proxy' : 'local_user',
+        auth: preparedAuth,
+      }),
+    });
+  }
+
+  platformProxy() {
+    if (!this.proxyBaseUrl || !this.credentialBroker) {
+      throw new InvalidPreparedAuthError('Platform proxy is not configured');
+    }
+    return Object.freeze({ baseUrl: this.proxyBaseUrl, credentialBroker: this.credentialBroker });
+  }
+
+  forSession(binding, sessionId, turnId, providerSessionId = null) {
+    return {
+      ...binding.base,
+      sessionId,
+      assistantMessageId: turnId,
+      userMessageId: null,
+      providerSessionId,
+      auth: sessionAuth(binding.base.auth, sessionId, this.localEgressSecret),
+    };
+  }
+}

package/host/native-runtime.js

@@ -0,0 +1,194 @@
+import { toAcpSessionUpdate } from '../dist/acp/index.js';
+import { ClaudeAdapter } from './adapters/claude.js';
+import { CodexAdapter } from './adapters/codex.js';
+import { CursorAdapter } from './adapters/cursor.js';
+import { OpenCodeAdapter } from './adapters/opencode.js';
+import { PiAdapter } from './adapters/pi.js';
+import { AcpAdapter } from './adapters/acp.js';
+import { assertExecutionInput } from './adapters/input-capabilities.js';
+import { NativeExecutionPreparer } from './native-contract.js';
+import { forwardPlatformEgress } from './platform-egress.js';
+import { forwardMcpRelay } from './tooling/mcp-relay.js';
+
+const DEFAULT_ADAPTERS = {
+  acp: (options) => new AcpAdapter(options),
+  claude_code: (options) => new ClaudeAdapter(options),
+  codex: (options) => new CodexAdapter(options),
+  cursor: (options) => new CursorAdapter(options),
+  opencode: (options) => new OpenCodeAdapter(options),
+  pi: (options) => new PiAdapter(options),
+};
+
+export class NativeChatRuntime {
+  constructor(options = {}) {
+    this.adapterFactories = { ...DEFAULT_ADAPTERS, ...(options.adapters || {}) };
+    this.preparer = options.preparer || new NativeExecutionPreparer(options);
+    this.adapterOptions = Object.freeze({
+      requestPermission: options.requestPermission || null,
+    });
+    this.sessions = new Map();
+  }
+
+  async prepareExecution(contract) {
+    const factory = this.adapterFactories[contract.agent.adapterId];
+    if (!factory) throw new Error(`Native adapter is not installed: ${contract.agent.adapterId}`);
+    const adapter = factory(this.adapterOptions);
+    assertExecutionInput(contract.agent.adapterId, contract, adapter.inputCapabilities);
+    const prepared = await this.preparer.prepare(contract);
+    adapter.validatePrepared?.(prepared.base);
+    return Object.freeze({ ...prepared, adapter });
+  }
+
+  async startSession({ sessionId, execution }) {
+    const contract = this.preparer.forSession(execution.binding, sessionId, '__session_start__');
+    const session = {
+      adapter: execution.binding.adapter,
+      native: null,
+      contract,
+      executionRevision: execution.revision,
+    };
+    this.sessions.set(sessionId, session);
+    try {
+      session.native = await execution.binding.adapter.create(contract);
+    } catch (error) {
+      this.sessions.delete(sessionId);
+      throw error;
+    }
+    return session;
+  }
+
+  async resumeSession({ sessionId, execution, checkpoint, messages }) {
+    const providerSessionId = typeof checkpoint?.providerSessionId === 'string'
+      ? checkpoint.providerSessionId
+      : null;
+    const contract = this.preparer.forSession(
+      execution.binding,
+      sessionId,
+      '__session_resume__',
+      providerSessionId,
+    );
+    const session = {
+      adapter: execution.binding.adapter,
+      native: null,
+      contract,
+      executionRevision: execution.revision,
+      recoveryHistory: providerSessionId ? null : messages,
+    };
+    this.sessions.set(sessionId, session);
+    try {
+      session.native = await execution.binding.adapter.create(contract);
+    } catch (error) {
+      this.sessions.delete(sessionId);
+      throw error;
+    }
+    return session;
+  }
+
+  async *prompt(request) {
+    let state = request.session;
+    if (state.executionRevision !== request.execution.revision) {
+      // Opaque provider checkpoints are scoped to the execution that created
+      // them. Reuse after an auth, agent, tool, cwd, or placement change needs
+      // an adapter-specific continuation proof; the reference host has none.
+      await state.adapter.destroy?.(state.native);
+      const contract = this.preparer.forSession(
+        request.execution.binding,
+        request.sessionId,
+        request.turnId,
+        null,
+      );
+      const adapter = request.execution.binding.adapter;
+      state.adapter = adapter;
+      state.contract = contract;
+      state.executionRevision = request.execution.revision;
+      state.native = await adapter.create(contract);
+    }
+
+    const contract = this.preparer.forSession(
+      request.execution.binding,
+      request.sessionId,
+      request.turnId,
+      state.native?.providerSessionId || state.contract.providerSessionId,
+    );
+    state.contract = contract;
+    const prompt = state.recoveryHistory
+      ? promptWithRecoveryHistory(state.recoveryHistory, request.prompt)
+      : request.prompt;
+    state.recoveryHistory = null;
+    let sequence = 0;
+    for await (const event of state.adapter.prompt(state.native, prompt, contract)) {
+      if (state.adapter.outputType === 'acp') {
+        yield event;
+        continue;
+      }
+      const update = toAcpSessionUpdate(event, {
+        conversationId: request.sessionId,
+        turnId: request.turnId,
+        sequence: sequence++,
+      });
+      if (update) yield update;
+    }
+  }
+
+  async interruptTurn({ session }) {
+    await session.adapter.stop?.(session.native);
+  }
+
+  checkpointSession({ session }) {
+    const providerSessionId = session.native?.providerSessionId || session.contract?.providerSessionId;
+    return providerSessionId ? { providerSessionId } : null;
+  }
+
+  async closeSession(_sessionId, session) {
+    this.sessions.delete(_sessionId);
+    await session.adapter.destroy?.(session.native);
+  }
+
+  async forwardEgress(request, response, input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session || session.contract.authMethod !== 'amalgm') {
+      response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      response.end(JSON.stringify({ error: 'No platform-auth Chat session' }));
+      return;
+    }
+    return forwardPlatformEgress({
+      request,
+      response,
+      contract: session.contract,
+      proxy: this.preparer.platformProxy(),
+      upstreamPath: input.upstreamPath,
+    });
+  }
+
+  async forwardMcp(request, response, input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      response.end(JSON.stringify({ error: 'No active Chat session' }));
+      return;
+    }
+    return forwardMcpRelay({
+      req: request,
+      res: response,
+      contract: session.contract,
+      serverName: input.serverName,
+      search: input.search,
+    });
+  }
+}
+
+function promptWithRecoveryHistory(messages, prompt) {
+  const lines = [];
+  for (const message of messages.slice(-40)) {
+    const label = message.role === 'user' ? 'Human' : 'Assistant';
+    const text = typeof message.contentPlain === 'string' ? message.contentPlain.trim() : '';
+    if (text) lines.push(`${label}: ${text}`);
+  }
+  if (lines.length === 0) return prompt;
+  return {
+    parts: [
+      { type: 'text', text: `<conversation_history>\n${lines.join('\n')}\n</conversation_history>\n\n` },
+      ...prompt.parts,
+    ],
+  };
+}