@amalgm/chat 0.1.1 → 0.2.0

package/host/adapters/cursor.js

@@ -0,0 +1,347 @@
+// Cursor Agent Client Protocol adapter. The generic ACP transport lives in
+// ./acp-client.js; this file is the
+// cursor parameterization (binary resolution, model translation, permission
+// auto-grant, first-prompt system preamble).
+//
+// Laws come from ../../dist: event constructors via `createEventConstructors`,
+// the normalizer via `createCursorNormalizer`, `cursorStopReason`, and
+// Effectful tooling and the recorder are sibling host modules.
+
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createEventConstructors } from '../../dist/events/index.js';
+import { createCursorNormalizer, cursorStopReason } from '../../dist/normalizers/cursor.js';
+import { recordNativeEvent } from '../recorder.js';
+import { toAcpMcpServers } from '../tooling/mcp-bundle.js';
+import { executableExists, findOnPath } from '../tooling/native-binaries.js';
+import { prepareHarnessRuntime } from '../tooling/runtime-home.js';
+import { composeSystemPrompt } from '../tooling/system-prompt.js';
+import { requestPermission } from '../permissions.js';
+import { AcpClient } from './acp-client.js';
+import { assertAcpMcpCapabilities, assertAcpPromptCapabilities } from './acp-capabilities.js';
+import {
+  COMMON_REASONING_SETTINGS,
+  COMMON_SPEED_SETTINGS,
+  nativeInputCapabilities,
+  UnsupportedExecutionInputError,
+} from './input-capabilities.js';
+import { acpPromptParts } from './prompt.js';
+
+const events = createEventConstructors({ clockMs: () => Date.now() });
+const { done, errorEvent, warningEvent } = events;
+const { cursorPromptUsage, normalizeCursorUpdate } = createCursorNormalizer(events);
+
+const PROTOCOL_VERSION = 1;
+
+function resolveBinary() {
+  const binaryName = process.platform === 'win32' ? 'cursor-agent.exe' : 'cursor-agent';
+  const homes = [...new Set([process.env.AMALGM_NATIVE_HOME, os.homedir()].filter(Boolean))];
+  const candidates = [
+    process.env.CURSOR_AGENT_BINARY,
+    ...homes.map((home) => path.join(home, '.local', 'bin', binaryName)),
+    '/opt/homebrew/bin/cursor-agent',
+    '/usr/local/bin/cursor-agent',
+    findOnPath('cursor-agent'),
+  ].filter(Boolean);
+  const failures = [];
+  for (const candidate of candidates) {
+    if (!executableExists(candidate)) {
+      failures.push(`${candidate} (missing or not executable)`);
+      continue;
+    }
+    const res = spawnSync(candidate, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
+    if (res.status === 0) return candidate;
+    failures.push(`${candidate} (--version failed: ${res.error?.message || res.status || res.signal || 'unknown'})`);
+  }
+  throw new Error(`Cursor Agent CLI is not available. Checked: ${failures.join(', ') || 'no candidates'}. Install it with: curl https://cursor.com/install -fsS | bash, then run cursor-agent login.`);
+}
+
+// cursor-agent's session/set_model only accepts EXACT ids from availableModels
+// (base name + bracket parameters, e.g. "gpt-5.3-codex[reasoning=medium,fast=false]").
+// Amalgm cliModels are bare base names, so match by base and return the exact id.
+function modelParameters(modelId) {
+  const match = String(modelId || '').match(/\[([^\]]*)\]$/);
+  if (!match) return {};
+  return Object.fromEntries(match[1].split(',').flatMap((entry) => {
+    const [key, value] = entry.split('=').map((part) => part.trim());
+    return key ? [[key, value]] : [];
+  }));
+}
+
+function requestedParameters(settings = []) {
+  const wanted = {};
+  for (const setting of settings) {
+    if (COMMON_REASONING_SETTINGS.includes(setting.configId)) {
+      wanted.reasoning = String(setting.value);
+    }
+    if (COMMON_SPEED_SETTINGS.includes(setting.configId)) {
+      wanted.fast = setting.value === true || setting.value === 'fast' ? 'true' : 'false';
+    }
+  }
+  return wanted;
+}
+
+function settingsMatch(modelId, settings) {
+  const wanted = requestedParameters(settings);
+  const params = modelParameters(modelId);
+  if (wanted.reasoning && params.reasoning !== wanted.reasoning && params.effort !== wanted.reasoning) return false;
+  if (wanted.fast && params.fast !== wanted.fast) return false;
+  return true;
+}
+
+function matchAcpModel(availableModels, requested, settings = []) {
+  const models = Array.isArray(availableModels) ? availableModels : [];
+  const baseOf = (id) => String(id || '').split('[')[0].trim();
+  let clean = String(requested || '').trim().replace(/^cursor\//, '').split('[')[0];
+  if (!clean) return null;
+  if (clean === 'auto' || clean === 'default') clean = 'default';
+  const findBase = (base) => models.find((m) => (
+    baseOf(m.modelId) === base || String(m.name || '').toLowerCase() === base.toLowerCase()
+  ) && settingsMatch(m.modelId, settings));
+  const acpBaseAliases = (base) => {
+    const aliases = [];
+    const claudeVersionFirst = String(base || '').match(/^claude-(4(?:\.\d+)?)-(opus|sonnet)(?:-.+)?$/);
+    if (claudeVersionFirst) {
+      const [, version, family] = claudeVersionFirst;
+      aliases.push(`claude-${family}-${version.replace('.', '-')}`);
+    }
+    return aliases;
+  };
+  let candidate = clean;
+  // Legacy amalgm cursor cliModels carry effort/speed suffixes ("gpt-5.3-codex-high",
+  // "composer-2.5-fast") that ACP model ids do not; strip them until a base matches.
+  for (let i = 0; i < 6; i += 1) {
+    for (const base of [candidate, ...acpBaseAliases(candidate)]) {
+      const match = findBase(base);
+      if (match) return match;
+    }
+    const stripped = candidate.replace(/-(?:extra-high|fast|thinking|none|low|medium|high|xhigh|max)$/, '');
+    if (stripped === candidate) return null;
+    candidate = stripped;
+  }
+  return null;
+}
+
+function pickPermissionOption(options = []) {
+  const byKind = (kind) => options.find((option) => option?.kind === kind);
+  return byKind('allow_always') || byKind('allow_once') || options[0] || null;
+}
+
+function pickRejectOption(options = []) {
+  const byKind = (kind) => options.find((option) => option?.kind === kind);
+  return byKind('reject_once') || byKind('reject_always') || null;
+}
+
+class CursorAdapter {
+  constructor(options = {}) {
+    this.requestPermission = options.requestPermission || null;
+    this.inputCapabilities = nativeInputCapabilities({
+      authModes: ['subscription', 'byok'],
+      modelSettings: [...COMMON_REASONING_SETTINGS, ...COMMON_SPEED_SETTINGS],
+      tools: true,
+    });
+  }
+
+  async create(contract) {
+    const runtime = prepareHarnessRuntime(contract);
+    const binary = resolveBinary();
+    const client = new AcpClient({
+      binary,
+      args: ['acp'],
+      cwd: contract.cwd,
+      env: runtime.env,
+      label: 'Cursor',
+    });
+    const session = {
+      sessionId: contract.sessionId,
+      providerSessionId: contract.providerSessionId || null,
+      client,
+      needsSystemPrompt: false,
+      modelWarning: null,
+      activePrompt: null,
+      cancelRequested: false,
+      permissionMode: contract.permissionMode,
+      capabilities: {},
+    };
+    client.onRequest((method, params) => this.handleAgentRequest(session, method, params));
+    const initialized = await client.request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      clientInfo: { name: 'amalgm-chat', version: '1.0.0' },
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+    });
+    session.capabilities = initialized?.agentCapabilities || {};
+    const mcpServers = toAcpMcpServers(contract);
+    assertAcpMcpCapabilities('cursor', session.capabilities, mcpServers);
+    const sessionParams = { cwd: contract.cwd, mcpServers };
+    let acpSession = null;
+    if (session.providerSessionId) {
+      // session/load replays history as session/update notifications; nothing is
+      // subscribed yet, so the replay is discarded and the turn starts clean.
+      acpSession = await client.request('session/load', {
+        sessionId: session.providerSessionId,
+        ...sessionParams,
+      }, 600000).catch((err) => {
+        console.warn('[Cursor] Failed to load native session; starting a new one:', err.message);
+        return null;
+      });
+    }
+    if (!acpSession) {
+      acpSession = await client.request('session/new', sessionParams);
+      session.providerSessionId = acpSession.sessionId;
+      session.needsSystemPrompt = true;
+    }
+    await this.selectModel(session, acpSession, contract);
+    return session;
+  }
+
+  async selectModel(session, acpSession, contract) {
+    const requested = contract.cliModel || contract.modelId;
+    const models = acpSession?.models || {};
+    const match = matchAcpModel(models.availableModels, requested, contract.modelSettings);
+    if (!match) {
+      throw new UnsupportedExecutionInputError(
+        'cursor',
+        'provider + model settings',
+        `Cursor Agent does not offer the exact selection ${requested}`,
+      );
+    }
+    if (match.modelId === models.currentModelId) return;
+    try {
+      await session.client.request('session/set_model', {
+        sessionId: session.providerSessionId,
+        modelId: match.modelId,
+      }, 30000);
+    } catch (err) {
+      throw new UnsupportedExecutionInputError(
+        'cursor',
+        'provider + model settings',
+        `Cursor Agent rejected ${match.modelId}: ${err.message}`,
+      );
+    }
+  }
+
+  async handleAgentRequest(session, method, params) {
+    recordNativeEvent('cursor.acp.request', { method, params }, {
+      providerSessionId: session.providerSessionId,
+      sessionId: session.sessionId,
+    });
+    if (method === 'session/request_permission') {
+      if (session.cancelRequested) return { outcome: { outcome: 'cancelled' } };
+      let outcome = 'allow_always';
+      if (session.permissionMode === 'ask') {
+        const decision = await requestPermission(this.requestPermission, {
+          adapterId: 'cursor',
+          providerSessionId: session.providerSessionId,
+          kind: 'tool',
+          title: params.title || 'Cursor requests permission',
+          input: params,
+        });
+        outcome = decision.outcome;
+      }
+      const pick = outcome === 'allow_always'
+        ? pickPermissionOption(params.options)
+        : outcome === 'allow_once'
+          ? params.options?.find((option) => option?.kind === 'allow_once') || pickPermissionOption(params.options)
+          : pickRejectOption(params.options);
+      if (!pick) return { outcome: { outcome: 'cancelled' } };
+      return { outcome: { outcome: 'selected', optionId: pick.optionId } };
+    }
+    throw new Error(`Method not supported: ${method}`);
+  }
+
+  async resume(session, contract) {
+    session.permissionMode = contract.permissionMode;
+    if (session.client && !session.client.closed) return session;
+    return this.create({ ...contract, providerSessionId: session.providerSessionId || contract.providerSessionId });
+  }
+
+  async stop(session) {
+    session.cancelRequested = true;
+    if (!session.activePrompt) return;
+    session.client.notify('session/cancel', { sessionId: session.providerSessionId });
+  }
+
+  async destroy(session) {
+    session.client.close();
+  }
+
+  async *prompt(session, input, contract) {
+    assertAcpPromptCapabilities('cursor', session.capabilities, input);
+    const queue = [];
+    let complete = false;
+    let wake = null;
+    const wakeLoop = () => { if (wake) { wake(); wake = null; } };
+    const push = (e) => {
+      if (e.type === 'done' || e.type === 'error') complete = true;
+      queue.push(e);
+      wakeLoop();
+    };
+    const state = { providerSessionId: session.providerSessionId, tools: new Map() };
+    session.cancelRequested = false;
+    session.activePrompt = state;
+    if (session.modelWarning) {
+      push(warningEvent(session.modelWarning, { providerSessionId: session.providerSessionId }));
+      session.modelWarning = null;
+    }
+    const off = session.client.onNotification((msg) => {
+      if (msg.method !== 'session/update') return;
+      const params = msg.params || {};
+      if (params.sessionId && params.sessionId !== session.providerSessionId) return;
+      recordNativeEvent('cursor.acp.update', msg, {
+        providerSessionId: session.providerSessionId,
+        sessionId: contract.sessionId,
+        assistantMessageId: contract.assistantMessageId,
+        updateKind: params.update?.sessionUpdate,
+      });
+      for (const e of normalizeCursorUpdate(params.update || {}, state)) push(e);
+    });
+    let preamble = '';
+    if (session.needsSystemPrompt) {
+      // ACP has no system-prompt slot; a fresh native session gets the composed
+      // instructions as a preamble on its first prompt only.
+      const systemPrompt = composeSystemPrompt(contract);
+      if (systemPrompt) preamble = `<system-instructions>\n${systemPrompt}\n</system-instructions>`;
+      session.needsSystemPrompt = false;
+    }
+    session.client.request('session/prompt', {
+      sessionId: session.providerSessionId,
+      prompt: acpPromptParts(input, preamble),
+    }, 0).then((result) => {
+      recordNativeEvent('cursor.acp.prompt_result', result, {
+        providerSessionId: session.providerSessionId,
+        sessionId: contract.sessionId,
+        assistantMessageId: contract.assistantMessageId,
+      });
+      const usage = cursorPromptUsage(result?.usage, { providerSessionId: session.providerSessionId });
+      if (usage) push(usage);
+      const stopReason = session.cancelRequested ? 'cancelled' : cursorStopReason(result?.stopReason);
+      push(done({ providerSessionId: session.providerSessionId, stopReason }));
+    }).catch((err) => {
+      if (session.cancelRequested) {
+        push(done({ providerSessionId: session.providerSessionId, stopReason: 'cancelled' }));
+        return;
+      }
+      push(errorEvent(err.message, { providerSessionId: session.providerSessionId }));
+      push(done({ providerSessionId: session.providerSessionId, stopReason: 'error' }));
+    });
+    try {
+      while (!complete || queue.length) {
+        if (!queue.length) await new Promise((resolve) => { wake = resolve; });
+        else yield queue.shift();
+      }
+    } finally {
+      off();
+      session.activePrompt = null;
+      session.cancelRequested = false;
+    }
+  }
+}
+
+const __private = {
+  matchAcpModel,
+  pickPermissionOption,
+  resolveBinary,
+};
+
+export { CursorAdapter, __private };

package/host/adapters/input-capabilities.js

@@ -0,0 +1,89 @@
+/**
+ * Adapter input capabilities are declarations, not guesses. The prepared
+ * contract is rejected before launch when a selected input would otherwise be
+ * ignored by the native agent.
+ */
+
+export class UnsupportedExecutionInputError extends Error {
+  constructor(adapterId, field, detail) {
+    super(`${adapterId} cannot apply ${field}: ${detail}`);
+    this.name = 'UnsupportedExecutionInputError';
+    this.code = 'UNSUPPORTED_EXECUTION_INPUT';
+    this.adapterId = adapterId;
+    this.field = field;
+  }
+}
+
+export const COMMON_REASONING_SETTINGS = Object.freeze([
+  'thought_level',
+  'reasoning_effort',
+  'reasoning',
+]);
+
+export const COMMON_SPEED_SETTINGS = Object.freeze(['speed', 'fast']);
+
+export function nativeInputCapabilities(input = {}) {
+  return Object.freeze({
+    authModes: Object.freeze([...(input.authModes || [])]),
+    modelSettings: input.modelSettings === 'negotiated'
+      ? 'negotiated'
+      : Object.freeze([...(input.modelSettings || [])]),
+    tools: input.tools === true,
+    permissionModes: Object.freeze([...(input.permissionModes || ['ask', 'full_access'])]),
+  });
+}
+
+export function assertExecutionInput(adapterId, contract, capabilities) {
+  if (!capabilities) {
+    throw new UnsupportedExecutionInputError(adapterId, 'execution', 'adapter did not declare input capabilities');
+  }
+  if (!capabilities.authModes.includes(contract.auth.mode)) {
+    throw new UnsupportedExecutionInputError(adapterId, 'auth.mode', contract.auth.mode);
+  }
+  if (!capabilities.permissionModes.includes(contract.permissionMode)) {
+    throw new UnsupportedExecutionInputError(adapterId, 'permissionMode', contract.permissionMode);
+  }
+  if (contract.tools.toolIds.length > 0 && !capabilities.tools) {
+    throw new UnsupportedExecutionInputError(adapterId, 'tools', 'selected ordinary/MCP tools are not supported');
+  }
+  if (capabilities.modelSettings !== 'negotiated') {
+    const supported = new Set(capabilities.modelSettings);
+    const unsupported = contract.model.settings.find((setting) => !supported.has(setting.configId));
+    if (unsupported) {
+      throw new UnsupportedExecutionInputError(
+        adapterId,
+        `model.settings.${unsupported.configId}`,
+        'the native adapter has no exact mapping',
+      );
+    }
+    const invalidReasoning = contract.model.settings.find(
+      (setting) => COMMON_REASONING_SETTINGS.includes(setting.configId)
+        && typeof setting.value !== 'string',
+    );
+    if (invalidReasoning) {
+      throw new UnsupportedExecutionInputError(
+        adapterId,
+        `model.settings.${invalidReasoning.configId}`,
+        'the native adapter requires a named reasoning level',
+      );
+    }
+    const invalidSpeed = contract.model.settings.find(
+      (setting) => COMMON_SPEED_SETTINGS.includes(setting.configId)
+        && ![
+          true,
+          false,
+          'fast',
+          'standard',
+          'normal',
+          'default',
+        ].includes(setting.value),
+    );
+    if (invalidSpeed) {
+      throw new UnsupportedExecutionInputError(
+        adapterId,
+        `model.settings.${invalidSpeed.configId}`,
+        `unsupported speed value ${JSON.stringify(invalidSpeed.value)}`,
+      );
+    }
+  }
+}