@amalgm/chat 0.2.2 → 0.2.4

package/host/tooling/mcp-bundle.js

@@ -1,8 +1,9 @@
 /** Exact prepared MCP-server projection for every native adapter. */
 
-/** Engine `runtime-auth.js getRuntimeToken`, byte-faithful. */
-function getRuntimeToken() {
-  return String(process.env.AMALGM_RUNTIME_TOKEN || '').trim();
+import path from 'node:path';
+
+function getRuntimeToken(contract) {
+  return String(contract?.runtimeToken || '').trim();
 }
 
 export function headerArrayToRecord(headers) {
@@ -22,21 +23,6 @@ function recordToHeaderArray(headers) {
     .map(([name, value]) => ({ name, value: String(value) }));
 }
 
-export function safeName(name) {
-  return String(name || '')
-    .trim()
-    .replace(/[^A-Za-z0-9_.-]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    || 'mcp';
-}
-
-function normalizeType(type) {
-  const clean = String(type || '').toLowerCase();
-  if (clean === 'sse') return 'sse';
-  if (clean === 'stdio') return 'stdio';
-  return 'http';
-}
-
 export class InvalidMcpServerError extends Error {
   constructor(message) {
     super(message);
@@ -45,34 +31,98 @@ export class InvalidMcpServerError extends Error {
   }
 }
 
+function exactName(value) {
+  const name = String(value || '').trim();
+  if (!name) throw new InvalidMcpServerError('ACP MCP server requires a non-empty name');
+  return name;
+}
+
+function immutableClone(value) {
+  const clone = structuredClone(value);
+  const seen = new WeakSet();
+  const freeze = (item) => {
+    if (item == null || typeof item !== 'object' || seen.has(item)) return item;
+    seen.add(item);
+    for (const child of Object.values(item)) freeze(child);
+    return Object.freeze(item);
+  };
+  return freeze(clone);
+}
+
+function clonedMeta(value) {
+  return Object.hasOwn(value, '_meta') ? { _meta: immutableClone(value._meta) } : {};
+}
+
+function entries(value, field) {
+  if (!Array.isArray(value)) {
+    throw new InvalidMcpServerError(`${field} must be an ACP name/value array`);
+  }
+  return value.map((entry) => {
+    const name = String(entry?.name || '').trim();
+    if (!name) throw new InvalidMcpServerError(`${field} has an empty name`);
+    return Object.freeze({
+      name,
+      value: String(entry?.value ?? ''),
+      ...clonedMeta(entry),
+    });
+  });
+}
+
+function meta(server) {
+  return clonedMeta(server);
+}
+
+function transport(server) {
+  return server.type === undefined ? 'stdio' : server.type;
+}
+
 function normalizeServer(server) {
   if (!server || typeof server !== 'object') {
     throw new InvalidMcpServerError('MCP server must be an object');
   }
-  const name = safeName(server.name);
-  const type = normalizeType(server.type);
-  if (type === 'stdio') {
+  const name = exactName(server.name);
+  if (server.type === undefined) {
     const command = String(server.command || '').trim();
-    if (!command) throw new InvalidMcpServerError(`${name} stdio MCP server requires command`);
-    const args = Array.isArray(server.args) ? server.args.map((arg) => String(arg)) : [];
-    const env = Array.isArray(server.env)
-      ? server.env.map((entry) => ({ name: String(entry?.name || ''), value: String(entry?.value || '') }))
-      : recordToHeaderArray(server.env);
-    if (env.some((entry) => !entry.name)) {
-      throw new InvalidMcpServerError(`${name} stdio MCP server has an empty environment variable name`);
+    if (!path.isAbsolute(command)) {
+      throw new InvalidMcpServerError(`${name} ACP stdio MCP server requires an absolute command`);
     }
-    return { name, type, command, args, env };
+    if (!Array.isArray(server.args)) {
+      throw new InvalidMcpServerError(`${name}.args must be an ACP string array`);
+    }
+    return Object.freeze({
+      name,
+      command,
+      args: Object.freeze(server.args.map((arg) => String(arg))),
+      env: Object.freeze(entries(server.env, `${name}.env`)),
+      ...meta(server),
+    });
+  }
+  if (server.type !== 'http' && server.type !== 'sse') {
+    throw new InvalidMcpServerError(`${name} has unsupported ACP MCP transport: ${String(server.type)}`);
   }
   const url = String(server.url || '').trim();
-  if (!url) throw new InvalidMcpServerError(`${name} ${type} MCP server requires url`);
-  return {
+  if (!url) throw new InvalidMcpServerError(`${name} ${server.type} MCP server requires url`);
+  return Object.freeze({
     name,
-    type,
+    type: server.type,
     url,
-    headers: Array.isArray(server.headers)
-      ? server.headers
-      : recordToHeaderArray(server.headers),
-  };
+    headers: Object.freeze(entries(server.headers, `${name}.headers`)),
+    ...meta(server),
+  });
+}
+
+/** Validate and clone the official ACP McpServer union without widening it. */
+export function normalizeAcpMcpServers(servers) {
+  if (!Array.isArray(servers)) throw new InvalidMcpServerError('MCP servers must be an ACP array');
+  const names = new Set();
+  return Object.freeze(servers.map((server) => {
+    const normalized = normalizeServer(server);
+    if (names.has(normalized.name)) {
+      throw new InvalidMcpServerError(`Duplicate ACP MCP server name: ${normalized.name}`);
+    }
+    names.add(normalized.name);
+    return normalized;
+  }));
 }
 
 function localBaseUrl(contract) {
@@ -82,13 +132,7 @@ function localBaseUrl(contract) {
 }
 
 export function mcpServers(contract) {
-  const byName = new Map();
-  const add = (server) => {
-    const normalized = normalizeServer(server);
-    byName.set(normalized.name, normalized);
-  };
-  for (const server of Array.isArray(contract.mcpServers) ? contract.mcpServers : []) add(server);
-  return [...byName.values()];
+  return normalizeAcpMcpServers(contract.mcpServers || []);
 }
 
 function relayUrl(contract, serverName) {
@@ -96,8 +140,8 @@ function relayUrl(contract, serverName) {
 }
 
 export function relayedMcpServers(contract) {
-  const runtimeToken = getRuntimeToken();
-  return mcpServers(contract).map((server) => server.type === 'stdio'
+  const runtimeToken = getRuntimeToken(contract);
+  return mcpServers(contract).map((server) => transport(server) === 'stdio'
     ? server
     : ({
         ...server,
@@ -109,14 +153,14 @@ export function relayedMcpServers(contract) {
 }
 
 export function findMcpRelayTarget(contract, serverName) {
-  const clean = safeName(serverName);
-  return mcpServers(contract).find((server) => server.name === clean && server.type !== 'stdio') || null;
+  const clean = String(serverName || '').trim();
+  return mcpServers(contract).find((server) => server.name === clean && transport(server) !== 'stdio') || null;
 }
 
 export function toClaudeMcpServers(contract) {
   const out = {};
   for (const server of relayedMcpServers(contract)) {
-    if (server.type === 'stdio') {
+    if (transport(server) === 'stdio') {
       out[server.name] = {
         type: 'stdio',
         command: server.command,
@@ -138,7 +182,7 @@ export function toClaudeMcpServers(contract) {
 export function toOpenCodeMcpConfig(contract) {
   const out = {};
   for (const server of relayedMcpServers(contract)) {
-    if (server.type === 'stdio') {
+    if (transport(server) === 'stdio') {
       out[server.name] = {
         type: 'local',
         command: [server.command, ...server.args],
@@ -164,17 +208,22 @@ function tomlString(value) {
   return JSON.stringify(String(value || ''));
 }
 
+export function codexMcpSectionName(name) {
+  return `mcp_servers.${tomlString(name)}`;
+}
+
 export function toCodexMcpToml(contract) {
   const lines = [];
-  const runtimeToken = getRuntimeToken();
+  const runtimeToken = getRuntimeToken(contract);
   for (const server of relayedMcpServers(contract)) {
-    lines.push(`[mcp_servers.${server.name}]`);
-    if (server.type === 'stdio') {
+    const section = codexMcpSectionName(server.name);
+    lines.push(`[${section}]`);
+    if (transport(server) === 'stdio') {
       lines.push(`command = ${tomlString(server.command)}`);
       if (server.args.length) lines.push(`args = ${JSON.stringify(server.args)}`);
       if (server.env.length) {
         lines.push('');
-        lines.push(`[mcp_servers.${server.name}.env]`);
+        lines.push(`[${section}.env]`);
         for (const entry of server.env) lines.push(`${tomlString(entry.name)} = ${tomlString(entry.value)}`);
       }
     } else {
@@ -189,8 +238,8 @@ export function toCodexMcpToml(contract) {
 export function mcpSummary(contract) {
   return mcpServers(contract).map((server) => ({
     name: server.name,
-    type: server.type,
-    ...(server.type === 'stdio'
+    type: transport(server),
+    ...(transport(server) === 'stdio'
       ? { command: server.command, hasEnvironment: server.env.length > 0 }
       : { url: server.url, hasHeaders: server.headers.length > 0 }),
   }));
@@ -198,17 +247,19 @@ export function mcpSummary(contract) {
 
 /** Official ACP MCP-server projection used by Cursor and generic ACP agents. */
 export function toAcpMcpServers(contract) {
-  return relayedMcpServers(contract).map((server) => server.type === 'stdio'
+  return relayedMcpServers(contract).map((server) => transport(server) === 'stdio'
     ? {
         name: server.name,
         command: server.command,
         args: [...server.args],
         env: server.env.map((entry) => ({ ...entry })),
+        ...(Object.hasOwn(server, '_meta') ? { _meta: structuredClone(server._meta) } : {}),
       }
     : {
         type: server.type,
         name: server.name,
         url: server.url,
         headers: server.headers.map((header) => ({ ...header })),
+        ...(Object.hasOwn(server, '_meta') ? { _meta: structuredClone(server._meta) } : {}),
       });
 }

package/host/tooling/system-prompt.js

@@ -15,12 +15,10 @@ function safeBlock(label, render) {
   }
 }
 
-/** Compose machine, project, and exact agent-revision instructions once. */
+/** Compose machine, project, and exact agent-revision instructions at preparation. */
 export function composeSystemPrompt(contract, options = {}) {
   const parts = [];
-  const systemInstructions = contract?.providerSessionId
-    ? ''
-    : safeBlock('system instructions', systemInstructionsBlock);
+  const systemInstructions = safeBlock('system instructions', systemInstructionsBlock);
   const projectContext = safeBlock(
     'project context',
     typeof options.projectContextPromptBlock === 'function'
@@ -33,3 +31,8 @@ export function composeSystemPrompt(contract, options = {}) {
   if (agentInstructions) parts.push(agentInstructions);
   return parts.join('\n\n');
 }
+
+/** Read the already-prepared instruction bundle without performing I/O. */
+export function preparedSystemPrompt(contract) {
+  return trimBlock(contract?.instructions?.text);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/chat",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A provider-agnostic agent chat SDK with ACP content, prepared execution, normalized streams, and usage.",
   "type": "module",
   "license": "UNLICENSED",
@@ -56,6 +56,10 @@
       "types": "./dist/conversations/index.d.ts",
       "default": "./dist/conversations/index.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    },
     "./sqlite": {
       "types": "./host/sqlite/index.d.ts",
       "default": "./host/sqlite/index.js"
@@ -70,6 +74,7 @@
     "AGENTS.md",
     "PURPOSE.md",
     "docs/contracts/acp-and-step-usage.md",
+    "docs/contracts/capabilities-and-instructions.md",
     "docs/contracts/input-and-execution.md",
     "docs/contracts/conversation-persistence.md",
     "docs/contracts/platform-authorization.md",