amalgm 0.0.0 → 0.0.1

package/runtime/scripts/chat-core/contract.js

@@ -0,0 +1,326 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { AMALGM_DIR, DEFAULT_CWD, PROXY_BASE_URL, PROXY_TOKEN } = require('../chat-server/config');
+const { authEnvelope, coerceAuth, fingerprint } = require('./auth');
+
+function agentToHarness(agent) {
+  const clean = String(agent || '').trim();
+  if (clean === 'claude') return 'claude_code';
+  if (clean === 'codex') return 'codex';
+  if (clean === 'opencode') return 'opencode';
+  if (clean === 'claude_code') return 'claude_code';
+  return clean || 'claude_code';
+}
+
+function canonicalModel(modelId, harness) {
+  const raw = String(modelId || '').trim();
+  if (!raw) {
+    throw new Error(`modelId is required for ${harness}`);
+  }
+  if (harness === 'claude_code') {
+    const cleaned = raw.replace(/^vercel\//i, '').toLowerCase();
+    const aliases = {
+      'haiku': 'anthropic/claude-haiku-4.5',
+      'sonnet': 'anthropic/claude-sonnet-4.6',
+      'sonnet[1m]': 'anthropic/claude-sonnet-4.6',
+      'opus': 'anthropic/claude-opus-4.7',
+      'opus1m': 'anthropic/claude-opus-4.7-1m',
+      'opus[1m]': 'anthropic/claude-opus-4.7-1m',
+      'claude-code-haiku': 'anthropic/claude-haiku-4.5',
+      'claude-code-sonnet': 'anthropic/claude-sonnet-4.6',
+      'claude-code-sonnet-45': 'anthropic/claude-sonnet-4.6',
+      'claude-code-opus': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-45': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-46': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-47': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4.5': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4-5': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4.6': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4-6': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4.7': 'anthropic/claude-opus-4.7',
+      'claude-code-opus-4-7': 'anthropic/claude-opus-4.7',
+      'claude-code-opus1m': 'anthropic/claude-opus-4.7-1m',
+      'claude-code-opus-1m': 'anthropic/claude-opus-4.7-1m',
+      'claude-code-opus-4.7-1m': 'anthropic/claude-opus-4.7-1m',
+      'claude-code-opus-4-7-1m': 'anthropic/claude-opus-4.7-1m',
+      'claude-code-sonnet-4.5': 'anthropic/claude-sonnet-4.6',
+      'claude-code-sonnet-4-5': 'anthropic/claude-sonnet-4.6',
+      'claude-code-sonnet-4.6': 'anthropic/claude-sonnet-4.6',
+      'claude-code-sonnet-4-6': 'anthropic/claude-sonnet-4.6',
+      'claude-code-haiku-4.5': 'anthropic/claude-haiku-4.5',
+      'claude-code-haiku-4-5': 'anthropic/claude-haiku-4.5',
+      'claude-haiku-4-5': 'anthropic/claude-haiku-4.5',
+      'claude-sonnet-4-5': 'anthropic/claude-sonnet-4.6',
+      'claude-sonnet-4-6': 'anthropic/claude-sonnet-4.6',
+      'claude-opus-4-5': 'anthropic/claude-opus-4.7',
+      'claude-opus-4-6': 'anthropic/claude-opus-4.7',
+      'claude-opus-4-7': 'anthropic/claude-opus-4.7',
+      'claude-opus-4-7-1m': 'anthropic/claude-opus-4.7-1m',
+      'claude-opus-4.7-1m': 'anthropic/claude-opus-4.7-1m',
+      'anthropic/claude-haiku-4-5': 'anthropic/claude-haiku-4.5',
+      'anthropic/claude-haiku-4.5': 'anthropic/claude-haiku-4.5',
+      'anthropic/claude-sonnet-4-5': 'anthropic/claude-sonnet-4.6',
+      'anthropic/claude-sonnet-4-6': 'anthropic/claude-sonnet-4.6',
+      'anthropic/claude-sonnet-4.5': 'anthropic/claude-sonnet-4.6',
+      'anthropic/claude-sonnet-4.6': 'anthropic/claude-sonnet-4.6',
+      'anthropic/claude-opus-4-5': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4-6': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4-7': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4-7-1m': 'anthropic/claude-opus-4.7-1m',
+      'anthropic/claude-opus-4.5': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4.6': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4.7': 'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4.7-1m': 'anthropic/claude-opus-4.7-1m',
+    };
+    if (aliases[cleaned]) return aliases[cleaned];
+    if (cleaned.startsWith('anthropic/')) return cleaned.replace(/-(\d+)-(\d+)(?=$|-)/, '-$1.$2');
+    if (cleaned.startsWith('claude-')) {
+      return `anthropic/${cleaned.replace(/-(\d+)-(\d+)(?=$|-)/, '-$1.$2')}`;
+    }
+    return raw;
+  }
+  if (raw.startsWith('opencode-openai-')) return `openai/${raw.slice('opencode-openai-'.length)}`;
+  if (raw.startsWith('codex-openai-')) return `openai/${raw.slice('codex-openai-'.length)}`;
+  if (raw.startsWith('claude-')) return `anthropic/${raw}`;
+  if (/^gpt-|^o\d|^o-/i.test(raw)) return `openai/${raw}`;
+  return raw;
+}
+
+function cliModelFor({ harness, modelId, cliModel, reasoningEffort }) {
+  const clean = String(cliModel || modelId || '').trim();
+  if (harness === 'claude_code') {
+    const canonical = canonicalModel(clean, harness);
+    const aliases = {
+      'anthropic/claude-haiku-4.5': 'haiku',
+      'anthropic/claude-sonnet-4.6': 'sonnet',
+      'anthropic/claude-opus-4.7': 'opus',
+      'anthropic/claude-opus-4.7-1m': 'opus[1m]',
+      'haiku': 'haiku',
+      'sonnet': 'sonnet',
+      'opus': 'opus',
+      'opus1m': 'opus[1m]',
+      'opus[1m]': 'opus[1m]',
+    };
+    return aliases[canonical] || aliases[clean.toLowerCase()] || clean;
+  }
+  if (harness === 'codex') {
+    let base = clean.replace(/^openai\//, '');
+    let effort = reasoningEffort;
+    const slashEffort = base.match(/\/(low|medium|high|xhigh)$/i);
+    if (slashEffort) {
+      effort ||= slashEffort[1].toLowerCase();
+      base = base.slice(0, -slashEffort[0].length);
+    }
+    const thinkingEffort = base.match(/-thinking-(low|medium|high|xhigh)$/i);
+    if (!cliModel && thinkingEffort) {
+      effort ||= thinkingEffort[1].toLowerCase();
+      base = base.slice(0, -thinkingEffort[0].length);
+    }
+    return effort ? `${base}/${effort}` : base;
+  }
+  if (harness === 'opencode') {
+    const bare = clean.replace(/^opencode-/, '');
+    const gatewayProviders = [
+      'prime-intellect',
+      'arcee-ai',
+      'alibaba',
+      'amazon',
+      'anthropic',
+      'bytedance',
+      'cohere',
+      'cursor',
+      'deepseek',
+      'google',
+      'inception',
+      'kwaipilot',
+      'meituan',
+      'meta',
+      'minimax',
+      'mistral',
+      'openai',
+      'perplexity',
+      'xiaomi',
+      'xai',
+      'zai',
+    ];
+    if (bare.startsWith('vercel/')) return bare;
+    const slashProvider = bare.split('/')[0];
+    if (gatewayProviders.includes(slashProvider)) return `vercel/${bare}`;
+    for (const provider of gatewayProviders) {
+      const prefix = `${provider}-`;
+      if (bare.startsWith(prefix)) return `vercel/${provider}/${bare.slice(prefix.length)}`;
+    }
+    return bare;
+  }
+  return clean;
+}
+
+function normalizeMcpHeader(header) {
+  return {
+    name: String(header?.name || '').toLowerCase(),
+    valueFingerprint: fingerprint(header?.value || ''),
+  };
+}
+
+function normalizeMcpServer(server) {
+  return {
+    name: String(server?.name || ''),
+    type: String(server?.type || 'http'),
+    url: String(server?.url || ''),
+    headers: Array.isArray(server?.headers)
+      ? server.headers.map(normalizeMcpHeader).sort((a, b) => a.name.localeCompare(b.name))
+      : [],
+  };
+}
+
+function frozenRuntimeFields(input) {
+  const authIdentity = input.authMethod === 'amalgm'
+    ? 'platform_proxy'
+    : input.auth?.tokenFingerprint || null;
+  const mcpServers = (Array.isArray(input.mcpServers) ? input.mcpServers : [])
+    .map(normalizeMcpServer)
+    .sort((a, b) => `${a.name}\0${a.type}\0${a.url}`.localeCompare(`${b.name}\0${b.type}\0${b.url}`));
+  return {
+    sessionId: input.sessionId,
+    computerId: input.computerId,
+    harness: input.harness,
+    authMethod: input.authMethod,
+    auth: authIdentity,
+    systemPrompt: fingerprint(input.systemPrompt || ''),
+    mcpServers: fingerprint(JSON.stringify(mcpServers)),
+  };
+}
+
+function runtimeKey(input) {
+  return fingerprint(JSON.stringify(frozenRuntimeFields(input)));
+}
+
+function positiveOrNull(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function changedRuntimeFields(current, next) {
+  const currentFields = current?.runtimeFields || frozenRuntimeFields(current || {});
+  const nextFields = next?.runtimeFields || frozenRuntimeFields(next || {});
+  const keys = [...new Set([...Object.keys(currentFields), ...Object.keys(nextFields)])];
+  return keys.filter((key) => currentFields[key] !== nextFields[key]);
+}
+
+function frozenContractChangedError(current, next) {
+  const changed = changedRuntimeFields(current, next);
+  const label = changed.length ? ` (${changed.join(', ')})` : '';
+  const err = new Error(
+    `Frozen session contract changed${label}; start a new session for auth/harness/computer/system-prompt/MCP changes`,
+  );
+  err.code = 'FROZEN_SESSION_CONTRACT_CHANGED';
+  err.changedFields = changed;
+  return err;
+}
+
+function expandHome(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  if (raw === '~') return os.homedir();
+  if (raw.startsWith(`~${path.sep}`)) return path.join(os.homedir(), raw.slice(2));
+  if (raw.startsWith('~/')) return path.join(os.homedir(), raw.slice(2));
+  return raw;
+}
+
+function existingDirectory(candidate) {
+  if (!candidate) return null;
+  try {
+    return fs.statSync(candidate).isDirectory() ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCwd(rawCwd, options = {}) {
+  const fallback = existingDirectory(expandHome(options.cwd))
+    || existingDirectory(expandHome(DEFAULT_CWD))
+    || existingDirectory(process.cwd())
+    || os.homedir();
+  const expanded = expandHome(rawCwd);
+  if (!expanded) return fallback;
+  const absolute = path.isAbsolute(expanded) ? expanded : path.resolve(fallback, expanded);
+  return existingDirectory(absolute) || fallback;
+}
+
+function nullableString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function createContract(payload, options = {}) {
+  const sessionId = payload.codeSessionId || payload.sessionId;
+  if (!sessionId) throw new Error('codeSessionId is required');
+  const assistantMessageId = payload.assistantMessageId;
+  if (!assistantMessageId) throw new Error('assistantMessageId is required');
+  const harness = agentToHarness(payload.harness || payload.agentId || payload.agent);
+  if (!['claude_code', 'codex', 'opencode'].includes(harness)) {
+    throw new Error(`Unsupported harness for clean chat core: ${harness}`);
+  }
+  const authMethod = coerceAuth(harness, payload.authMethod || 'amalgm');
+  const modelId = canonicalModel(payload.modelId || payload.cliModel, harness);
+  const reasoningEffort = payload.reasoningEffort || null;
+  const cliModel = cliModelFor({ harness, modelId, cliModel: payload.cliModel, reasoningEffort });
+  const cwd = resolveCwd(payload.cwd, options);
+  const localBaseUrl = options.localBaseUrl || `http://127.0.0.1:${options.port || process.env.CHAT_SERVER_PORT || 8084}`;
+  const auth = authEnvelope({
+    harness,
+    authMethod,
+    sessionId,
+    localBaseUrl,
+    proxyToken: options.proxyToken || PROXY_TOKEN,
+    proxyBaseUrl: options.proxyBaseUrl || PROXY_BASE_URL || 'https://amalgm-api-proxy-v2.fly.dev',
+    amalgmDir: options.amalgmDir || AMALGM_DIR || path.join(process.env.HOME || '.', '.amalgm'),
+    credentialId: payload.credentialId || payload.byokCredentialId || null,
+    modelId,
+  });
+  const contract = {
+    sessionId,
+    userId: payload.userId || options.userId || 'unknown-user',
+    computerId: payload.computerId || process.env.AMALGM_CONTAINER_ID || 'local-computer',
+    assistantMessageId,
+    userMessageId: payload.userMessageId || null,
+    agentId: payload.agentId || (harness === 'claude_code' ? 'claude' : harness),
+    harness,
+    authMethod: auth.method,
+    modelId,
+    usageModelId: modelId,
+    providerSessionId: nullableString(payload.providerSessionId || payload.provider_session_id),
+    cliModel,
+    reasoningEffort,
+    contextWindow: positiveOrNull(payload.contextWindow),
+    maxTokens: positiveOrNull(payload.maxTokens),
+    cwd,
+    localBaseUrl,
+    mcpServers: Array.isArray(payload.mcpServers) ? payload.mcpServers : [],
+    systemPrompt: payload.systemPrompt || '',
+    usageOwner: auth.method === 'amalgm' ? 'platform_proxy' : 'local_user',
+    auth,
+  };
+  contract.runtimeFields = frozenRuntimeFields(contract);
+  contract.runtimeKey = runtimeKey(contract);
+  return contract;
+}
+
+function assertSameContract(current, next) {
+  if (!current) return;
+  if (current.runtimeKey !== next.runtimeKey) {
+    throw frozenContractChangedError(current, next);
+  }
+}
+
+module.exports = {
+  agentToHarness,
+  assertSameContract,
+  canonicalModel,
+  changedRuntimeFields,
+  cliModelFor,
+  createContract,
+  frozenRuntimeFields,
+};

package/runtime/scripts/chat-core/credentials/store.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STORE_VERSION = 1;
+const CIPHER = 'aes-256-gcm';
+const KEY_BYTES = 32;
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+
+const DEFAULT_BASE_URL_BY_PROVIDER = {
+  anthropic_compatible: 'https://api.anthropic.com',
+  openai_compatible: 'https://api.openai.com/v1',
+  ai_gateway: 'https://ai-gateway.vercel.sh/v1',
+};
+
+function credentialsPath(amalgmDir) {
+  return path.join(amalgmDir || path.join(os.homedir(), '.amalgm'), '.credentials');
+}
+
+function machineSecret() {
+  const pieces = [
+    os.hostname(),
+    os.userInfo().username,
+    os.homedir(),
+    process.platform,
+  ];
+  return pieces.filter(Boolean).join(':');
+}
+
+function deriveKey(salt) {
+  return crypto.scryptSync(machineSecret(), salt, KEY_BYTES);
+}
+
+function encryptSecret(plaintext) {
+  const salt = crypto.randomBytes(SALT_BYTES);
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(CIPHER, deriveKey(salt), iv);
+  const data = Buffer.concat([cipher.update(String(plaintext), 'utf8'), cipher.final()]);
+  return {
+    alg: CIPHER,
+    salt: salt.toString('base64url'),
+    iv: iv.toString('base64url'),
+    tag: cipher.getAuthTag().toString('base64url'),
+    data: data.toString('base64url'),
+  };
+}
+
+function decryptSecret(encrypted) {
+  if (!encrypted || encrypted.alg !== CIPHER) throw new Error('Unsupported credential encryption format');
+  const salt = Buffer.from(encrypted.salt, 'base64url');
+  const iv = Buffer.from(encrypted.iv, 'base64url');
+  const tag = Buffer.from(encrypted.tag, 'base64url');
+  const data = Buffer.from(encrypted.data, 'base64url');
+  const decipher = crypto.createDecipheriv(CIPHER, deriveKey(salt), iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+}
+
+function idFor() {
+  return `cred_${crypto.randomUUID().replace(/-/g, '').slice(0, 18)}`;
+}
+
+function keyHint(key) {
+  const clean = String(key || '').trim();
+  return clean ? `...${clean.slice(-4)}` : null;
+}
+
+function keyFingerprint(key) {
+  const clean = String(key || '').trim();
+  return clean ? crypto.createHash('sha256').update(clean).digest('hex').slice(0, 16) : null;
+}
+
+function normalizeBaseUrl(baseUrl, providerKind) {
+  const fallback = DEFAULT_BASE_URL_BY_PROVIDER[providerKind] || DEFAULT_BASE_URL_BY_PROVIDER.openai_compatible;
+  const raw = String(baseUrl || fallback).trim() || fallback;
+  return raw.replace(/\/+$/, '');
+}
+
+function inferProviderKind({ baseUrl, key }) {
+  const url = String(baseUrl || '').toLowerCase();
+  const token = String(key || '').trim();
+  if (url.includes('anthropic') || token.startsWith('sk-ant-')) return 'anthropic_compatible';
+  if (url.includes('ai-gateway.vercel') || url.includes('gateway.vercel') || token.startsWith('v0_')) return 'ai_gateway';
+  return 'openai_compatible';
+}
+
+function sanitizeCredential(record) {
+  return {
+    id: record.id,
+    name: record.name,
+    providerKind: record.providerKind,
+    keyHint: record.keyHint || null,
+    tokenFingerprint: record.tokenFingerprint || null,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  };
+}
+
+function emptyStore() {
+  return { version: STORE_VERSION, credentials: [] };
+}
+
+function readStore(amalgmDir) {
+  const file = credentialsPath(amalgmDir);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return emptyStore();
+    if (!Array.isArray(parsed.credentials)) return emptyStore();
+    return {
+      version: parsed.version || STORE_VERSION,
+      credentials: parsed.credentials,
+    };
+  } catch {
+    return emptyStore();
+  }
+}
+
+function writeStore(amalgmDir, store) {
+  const file = credentialsPath(amalgmDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch {}
+}
+
+function listCredentials(amalgmDir) {
+  return readStore(amalgmDir).credentials.map(sanitizeCredential);
+}
+
+function upsertCredential(amalgmDir, input = {}) {
+  const rawKey = String(input.key || input.apiKey || '').trim();
+  if (!rawKey) throw new Error('Key is required');
+  const providerKind = input.providerKind || inferProviderKind({ baseUrl: input.baseUrl, key: rawKey });
+  const baseUrl = normalizeBaseUrl(input.baseUrl, providerKind);
+  const name = String(input.name || '').trim() || defaultName(providerKind, baseUrl);
+  const now = new Date().toISOString();
+  const store = readStore(amalgmDir);
+  const id = String(input.id || '').trim() || idFor();
+  const existing = store.credentials.find((item) => item.id === id);
+  const record = {
+    id,
+    name,
+    providerKind,
+    baseUrl,
+    keyHint: keyHint(rawKey),
+    tokenFingerprint: keyFingerprint(rawKey),
+    encryptedKey: encryptSecret(rawKey),
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+  };
+  const next = store.credentials.filter((item) => item.id !== id);
+  next.push(record);
+  writeStore(amalgmDir, { version: STORE_VERSION, credentials: next });
+  return sanitizeCredential(record);
+}
+
+function deleteCredential(amalgmDir, id) {
+  const store = readStore(amalgmDir);
+  const next = store.credentials.filter((item) => item.id !== id);
+  writeStore(amalgmDir, { version: STORE_VERSION, credentials: next });
+  return { ok: true, deleted: next.length !== store.credentials.length };
+}
+
+function providerKindsForHarness(harness) {
+  if (harness === 'claude_code') return ['anthropic_compatible'];
+  if (harness === 'codex') return ['openai_compatible'];
+  if (harness === 'opencode') return ['ai_gateway', 'openai_compatible', 'anthropic_compatible'];
+  return [];
+}
+
+function resolveCredential(amalgmDir, { credentialId, harness, providerKind } = {}) {
+  const store = readStore(amalgmDir);
+  const allowed = providerKind ? [providerKind] : providerKindsForHarness(harness);
+  const record = credentialId
+    ? store.credentials.find((item) => item.id === credentialId)
+    : store.credentials.find((item) => allowed.includes(item.providerKind));
+  if (!record) return null;
+  if (allowed.length && !allowed.includes(record.providerKind)) {
+    throw new Error(`Credential ${record.name || record.id} is not compatible with ${harness}`);
+  }
+  return {
+    ...sanitizeCredential(record),
+    baseUrl: record.baseUrl || normalizeBaseUrl('', record.providerKind),
+    key: decryptSecret(record.encryptedKey),
+  };
+}
+
+function defaultName(providerKind, baseUrl) {
+  if (providerKind === 'anthropic_compatible') return 'Anthropic';
+  if (providerKind === 'ai_gateway') return 'Vercel AI Gateway';
+  try {
+    const host = new URL(baseUrl).hostname.replace(/^api\./, '');
+    return host || 'OpenAI Compatible';
+  } catch {
+    return 'OpenAI Compatible';
+  }
+}
+
+module.exports = {
+  DEFAULT_BASE_URL_BY_PROVIDER,
+  credentialsPath,
+  deleteCredential,
+  inferProviderKind,
+  listCredentials,
+  normalizeBaseUrl,
+  providerKindsForHarness,
+  resolveCredential,
+  upsertCredential,
+};

package/runtime/scripts/chat-core/egress.js

@@ -0,0 +1,87 @@
+'use strict';
+
+function metadataHeaders(contract, turn) {
+  return {
+    'x-amalgm-session-id': contract.sessionId,
+    'x-amalgm-message-id': turn?.assistantMessageId || turn?.turnId || '',
+    'x-amalgm-turn-id': turn?.turnId || '',
+    'x-amalgm-agent-id': contract.agentId,
+    'x-amalgm-harness-id': contract.harness,
+    'x-amalgm-auth-method': contract.authMethod,
+    'x-amalgm-model-id': contract.usageModelId || contract.modelId,
+    'x-amalgm-cwd': contract.cwd || '',
+    'x-amalgm-usage-owner': contract.usageOwner,
+  };
+}
+
+function parseEgressPath(pathname) {
+  const parts = String(pathname || '').split('/').filter(Boolean);
+  if (parts[0] !== 'egress' || !parts[1]) return null;
+  return {
+    sessionId: decodeURIComponent(parts[1]),
+    upstreamPath: `/${parts.slice(2).join('/')}`,
+  };
+}
+
+function responseHeaders(response) {
+  const headers = {};
+  for (const [key, value] of response.headers.entries()) {
+    if (!['connection', 'content-encoding', 'transfer-encoding'].includes(key.toLowerCase())) headers[key] = value;
+  }
+  return headers;
+}
+
+async function forwardEgress({ req, res, contract, turn, proxyBaseUrl, proxyToken, upstreamPath }) {
+  const authHeader = String(req.headers.authorization || '');
+  const apiKeyHeader = String(req.headers['x-api-key'] || '');
+  const bearerToken = authHeader.replace(/^Bearer\s+/i, '').trim();
+  const providedToken = bearerToken || apiKeyHeader.trim();
+  if (!contract.auth?.tokenRef || providedToken !== contract.auth.tokenRef) {
+    res.writeHead(401, { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' });
+    res.end(JSON.stringify({ error: 'Invalid egress token' }));
+    return;
+  }
+  const base = String(proxyBaseUrl || '').replace(/\/$/, '');
+  const path = upstreamPath || req.url;
+  const body = ['GET', 'HEAD'].includes(req.method) ? undefined : req;
+  const headers = {};
+  for (const [key, value] of Object.entries(req.headers || {})) {
+    const lower = key.toLowerCase();
+    if (['host', 'authorization', 'x-api-key', 'connection', 'content-length', 'accept-encoding'].includes(lower)) continue;
+    headers[lower] = Array.isArray(value) ? value[0] : value;
+  }
+  const response = await fetch(`${base}${path}`, {
+    method: req.method,
+    headers: {
+      ...headers,
+      ...metadataHeaders(contract, turn),
+      Authorization: `Bearer ${proxyToken}`,
+    },
+    body,
+    duplex: body ? 'half' : undefined,
+  });
+  if (process.env.CHAT_CORE_DEBUG_EGRESS === '1') {
+    console.warn('[ChatCore:egress]', req.method, `${base}${path}`, response.status, {
+      sessionId: contract.sessionId,
+      harness: contract.harness,
+      model: contract.usageModelId || contract.modelId,
+      messageId: turn?.assistantMessageId || turn?.turnId || '',
+    });
+  }
+  res.writeHead(response.status, responseHeaders(response));
+  if (response.body) {
+    const reader = response.body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(Buffer.from(value));
+    }
+  }
+  res.end();
+}
+
+module.exports = {
+  forwardEgress,
+  metadataHeaders,
+  parseEgressPath,
+};