amalgm 0.1.135 → 0.1.136

package/runtime/scripts/chat-core/adapters/pi.js

@@ -0,0 +1,302 @@
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { done, errorEvent } = require('../events');
+const { promptText } = require('../input');
+const { normalizePiEvent, piSessionStatsUsage } = require('../normalizers/pi');
+const { recordNativeEvent } = require('../recorder');
+const { executableExists, findOnPath } = require('../tooling/native-binaries');
+const { prepareHarnessRuntime } = require('../tooling/runtime-home');
+const { composeSystemPrompt } = require('../tooling/system-prompt');
+
+const GATEWAY_PROVIDER = 'vercel-ai-gateway';
+
+// Pi's RPC protocol is JSONL over stdio, but NOT JSON-RPC: commands are
+// {id?, type, ...}, responses are {id?, type:'response', command, success, data},
+// and events are un-id'd JSON lines. Framing is LF-only by spec.
+class PiRpc {
+  constructor({ binary, args, cwd, env }) {
+    this.id = 1;
+    this.pending = new Map();
+    this.eventHandlers = new Set();
+    this.buffer = '';
+    this.closed = false;
+    this.closeError = null;
+    this.child = spawn(binary, args, {
+      cwd,
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+      windowsHide: true,
+    });
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this.onData(chunk));
+    this.child.stderr.setEncoding('utf8');
+    this.child.stderr.on('data', (chunk) => {
+      const text = String(chunk || '').trim();
+      if (text && process.env.CHAT_CORE_DEBUG) console.warn('[Pi]', text.slice(0, 1000));
+    });
+    this.child.on('error', (err) => this.failAll(err));
+    this.child.on('exit', (code, signal) => {
+      this.failAll(new Error(`pi rpc agent exited (${code ?? signal ?? 'unknown'})`));
+    });
+    this.child.stdin.on('error', (err) => this.failAll(err));
+  }
+
+  failAll(err) {
+    this.closed = true;
+    this.closeError = err;
+    for (const pending of this.pending.values()) pending.reject(err);
+    this.pending.clear();
+  }
+
+  onData(chunk) {
+    this.buffer += chunk;
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() || '';
+    for (const rawLine of lines) {
+      const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      if (process.env.CHAT_CORE_DEBUG_PI === '1') {
+        console.log('[Pi:recv]', JSON.stringify(msg).slice(0, 4000));
+      }
+      if (msg.type === 'response') {
+        const pending = msg.id !== undefined ? this.pending.get(msg.id) : null;
+        if (pending) {
+          this.pending.delete(msg.id);
+          if (msg.success === false) {
+            pending.reject(new Error(msg.error || `pi ${msg.command} failed`));
+          } else {
+            pending.resolve(msg.data ?? {});
+          }
+        }
+        continue;
+      }
+      for (const handler of this.eventHandlers) handler(msg);
+    }
+  }
+
+  request(command, params = {}, timeoutMs = 180000) {
+    if (this.closeError) return Promise.reject(this.closeError);
+    if (this.closed || this.child.exitCode !== null || this.child.signalCode !== null) {
+      return Promise.reject(new Error('pi rpc agent is not running'));
+    }
+    const id = `req-${this.id++}`;
+    return new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0
+        ? setTimeout(() => {
+            this.pending.delete(id);
+            reject(new Error(`pi ${command} timed out`));
+          }, timeoutMs)
+        : null;
+      this.pending.set(id, {
+        resolve: (value) => { if (timer) clearTimeout(timer); resolve(value); },
+        reject: (err) => { if (timer) clearTimeout(timer); reject(err); },
+      });
+      try {
+        this.child.stdin.write(`${JSON.stringify({ id, type: command, ...params })}\n`, (err) => {
+          if (err) this.failAll(err);
+        });
+      } catch (err) {
+        this.failAll(err);
+      }
+    });
+  }
+
+  onEvent(handler) {
+    this.eventHandlers.add(handler);
+    return () => this.eventHandlers.delete(handler);
+  }
+
+  close() {
+    try { this.child.stdin.end(); } catch {}
+    try {
+      if (process.platform !== 'win32' && this.child.pid) process.kill(-this.child.pid, 'SIGTERM');
+      else this.child.kill('SIGTERM');
+    } catch {}
+  }
+}
+
+function resolveBinary() {
+  const binaryName = process.platform === 'win32' ? 'pi.cmd' : 'pi';
+  const homes = [...new Set([process.env.AMALGM_NATIVE_HOME, os.homedir()].filter(Boolean))];
+  const candidates = [
+    process.env.PI_BINARY,
+    ...homes.map((home) => path.join(home, '.npm-global', 'bin', binaryName)),
+    '/opt/homebrew/bin/pi',
+    '/usr/local/bin/pi',
+    findOnPath('pi'),
+  ].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(`Pi CLI is not available. Checked: ${failures.join(', ') || 'no candidates'}. Install it with: npm install -g @mariozechner/pi-coding-agent`);
+}
+
+// Under amalgm auth every gateway request must flow through the local egress
+// proxy. Pi's provider baseUrl is overridden by a tiny extension; the URL rides
+// in on an env var so the extension file itself is static.
+function ensureEgressExtension(runtimeHome) {
+  const file = path.join(runtimeHome, '.pi', 'amalgm-egress-extension.js');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const source = [
+    '// Generated by amalgm chat-core: routes the Vercel AI Gateway provider',
+    '// through the per-session amalgm egress proxy for billing and audit.',
+    'export default function (pi) {',
+    '  const baseUrl = process.env.AMALGM_PI_GATEWAY_BASE_URL;',
+    `  if (baseUrl) pi.registerProvider(${JSON.stringify(GATEWAY_PROVIDER)}, { baseUrl });`,
+    '}',
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, source, { mode: 0o600 });
+  return file;
+}
+
+function thinkingLevelFor(contract) {
+  const effort = String(contract.reasoningEffort || '').toLowerCase();
+  return ['minimal', 'low', 'medium', 'high', 'xhigh'].includes(effort) ? effort : null;
+}
+
+function buildArgs(contract, runtimeHome) {
+  const args = ['--mode', 'rpc', '--provider', GATEWAY_PROVIDER, '--model', contract.cliModel];
+  const thinking = thinkingLevelFor(contract);
+  if (thinking) args.push('--thinking', thinking);
+  const systemPrompt = composeSystemPrompt(contract);
+  if (systemPrompt) args.push('--system-prompt', systemPrompt);
+  if (contract.providerSessionId) args.push('--session', contract.providerSessionId);
+  if (contract.authMethod === 'amalgm') args.push('--extension', ensureEgressExtension(runtimeHome));
+  return args;
+}
+
+class PiAdapter {
+  async create(contract) {
+    const runtime = prepareHarnessRuntime(contract);
+    const binary = resolveBinary();
+    const env = { ...runtime.env };
+    if (contract.authMethod === 'amalgm' && contract.auth.baseUrl) {
+      env.AMALGM_PI_GATEWAY_BASE_URL = contract.auth.baseUrl;
+    }
+    const client = new PiRpc({
+      binary,
+      args: buildArgs(contract, runtime.runtimeHome),
+      cwd: contract.cwd,
+      env,
+    });
+    // Sessions persist as files under the managed home; the file path is the
+    // durable resume handle (pi's --session flag takes a path).
+    const stats = await client.request('get_session_stats', {}, 60000);
+    return {
+      sessionId: contract.sessionId,
+      providerSessionId: stats.sessionFile || contract.providerSessionId || null,
+      client,
+      cancelRequested: false,
+      activePrompt: null,
+    };
+  }
+
+  async resume(session, contract) {
+    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;
+    await session.client.request('abort', {}, 15000).catch(() => {});
+  }
+
+  async destroy(session) {
+    session.client.close();
+  }
+
+  async *prompt(session, input, contract) {
+    const queue = [];
+    let complete = false;
+    let wake = null;
+    const wakeLoop = () => { if (wake) { wake(); wake = null; } };
+    // Unlike the other adapters, an `error` event does NOT complete the turn:
+    // pi still emits agent_end afterwards, and finish() owns the done event.
+    const push = (e) => {
+      if (e.type === 'done') complete = true;
+      queue.push(e);
+      wakeLoop();
+    };
+    const state = { providerSessionId: session.providerSessionId, tools: new Set() };
+    let sawError = false;
+    session.cancelRequested = false;
+    session.activePrompt = state;
+    const finish = async () => {
+      // Attach the post-turn context snapshot before done so the context circle
+      // lands on the final number even if per-message events raced.
+      const stats = await session.client.request('get_session_stats', {}, 30000).catch(() => null);
+      recordNativeEvent('pi.rpc.session_stats', stats, {
+        providerSessionId: session.providerSessionId,
+        sessionId: contract.sessionId,
+        assistantMessageId: contract.assistantMessageId,
+      });
+      const snapshot = stats ? piSessionStatsUsage(stats, { providerSessionId: session.providerSessionId }) : null;
+      if (snapshot) push(snapshot);
+      push(done({
+        providerSessionId: session.providerSessionId,
+        stopReason: session.cancelRequested ? 'cancelled' : sawError ? 'error' : 'end_turn',
+      }));
+    };
+    const off = session.client.onEvent((event) => {
+      recordNativeEvent('pi.rpc.event', event, {
+        providerSessionId: session.providerSessionId,
+        sessionId: contract.sessionId,
+        assistantMessageId: contract.assistantMessageId,
+        eventType: event?.type,
+      });
+      if (event?.type === 'agent_end') {
+        finish().catch(() => push(done({ providerSessionId: session.providerSessionId, stopReason: 'end_turn' })));
+        return;
+      }
+      for (const e of normalizePiEvent(event, state)) {
+        if (e.type === 'error') sawError = true;
+        push(e);
+      }
+    });
+    session.client.request('prompt', { message: promptText(input, contract) }, 0).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;
+    }
+  }
+}
+
+module.exports = {
+  PiAdapter,
+  __private: {
+    PiRpc,
+    buildArgs,
+    ensureEgressExtension,
+    resolveBinary,
+    thinkingLevelFor,
+  },
+};

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

@@ -10,6 +10,8 @@ const AUTH_BY_HARNESS = {
   claude_code: ['amalgm', 'byok', 'provider_auth'],
   codex: ['amalgm', 'byok', 'provider_auth'],
   opencode: ['amalgm', 'byok', 'provider_auth'],
+  cursor: ['provider_auth'],
+  pi: ['amalgm', 'byok', 'provider_auth'],
 };
 
 function shellValue(raw) {
@@ -35,6 +37,7 @@ function readByokFile(amalgmDir) {
 function byokKeyFor(harness, values) {
   if (harness === 'claude_code') return values.ANTHROPIC_API_KEY || '';
   if (harness === 'codex') return values.OPENAI_API_KEY || values.CODEX_API_KEY || '';
+  if (harness === 'pi') return values.AI_GATEWAY_API_KEY || '';
   return '';
 }
 
@@ -53,7 +56,7 @@ function resolveByokCredential(amalgmDir, { credentialId, harness, modelId }) {
     if (credential) return credential;
     if (preferred === 'ai_gateway') return null;
   }
-  if (harness === 'opencode' && preferred !== 'ai_gateway') {
+  if ((harness === 'opencode' || harness === 'pi') && preferred !== 'ai_gateway') {
     const gatewayCredential = resolveCredential(amalgmDir, { harness, providerKind: 'ai_gateway' });
     if (gatewayCredential) return gatewayCredential;
   }
@@ -155,7 +158,11 @@ function authEnvelope({ harness, authMethod, sessionId, localBaseUrl, proxyToken
       ? '/anthropic'
       : harness === 'opencode'
         ? '/ai_gateway/v3/ai'
-        : '/openai/v1';
+        // Pi's provider client appends its own API paths (/v1/messages or
+        // /v1/chat/completions), which the proxy serves under /ai_gateway.
+        : harness === 'pi'
+          ? '/ai_gateway'
+          : '/openai/v1';
     forwardBaseUrl = `${String(proxyBaseUrl || '').replace(/\/$/, '')}${providerPath}`;
     baseUrl = `${String(localBaseUrl || '').replace(/\/$/, '')}/egress/${encodeURIComponent(sessionId)}${providerPath}`;
     tokenRef = `session-local-${fingerprint(`${sessionId}:${proxyToken}`) || 'token'}`;
@@ -167,7 +174,13 @@ function authEnvelope({ harness, authMethod, sessionId, localBaseUrl, proxyToken
       throw new Error(`No BYOK credential configured for ${harness}`);
     }
     tokenFingerprint = fingerprint(tokenRef);
-    baseUrl = credential?.baseUrl || (harness === 'claude_code' ? 'https://api.anthropic.com' : 'https://api.openai.com/v1');
+    baseUrl = credential?.baseUrl || (
+      harness === 'claude_code'
+        ? 'https://api.anthropic.com'
+        : harness === 'pi'
+          ? 'https://ai-gateway.vercel.sh'
+          : 'https://api.openai.com/v1'
+    );
   } else if (method === 'provider_auth') {
     tokenFingerprint = providerAuthFingerprint(harness);
   }
@@ -229,6 +242,10 @@ function runtimeEnv(contract, baseEnv = process.env) {
     } else if (contract.harness === 'opencode') {
       env.AI_GATEWAY_API_KEY = contract.auth.tokenRef || '';
       if (contract.auth.baseUrl) env.AI_GATEWAY_BASE_URL = contract.auth.baseUrl;
+    } else if (contract.harness === 'pi') {
+      // Pi keys the vercel-ai-gateway provider on this env var; base-URL
+      // overrides ride through the generated egress extension instead.
+      env.AI_GATEWAY_API_KEY = contract.auth.tokenRef || '';
     } else {
       env.OPENAI_API_KEY = contract.auth.tokenRef || '';
       if (contract.auth.baseUrl) env.OPENAI_BASE_URL = contract.auth.baseUrl;

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

@@ -25,6 +25,8 @@ function uniqueStrings(value) {
 function harnessToAgent(harness) {
   if (harness === 'codex') return 'codex';
   if (harness === 'opencode') return 'opencode';
+  if (harness === 'cursor') return 'cursor';
+  if (harness === 'pi') return 'pi';
   return 'claude';
 }
 

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

@@ -14,10 +14,52 @@ function agentToHarness(agent) {
   if (clean === 'claude') return 'claude_code';
   if (clean === 'codex') return 'codex';
   if (clean === 'opencode') return 'opencode';
+  if (clean === 'cursor') return 'cursor';
+  if (clean === 'pi') return 'pi';
   if (clean === 'claude_code') return 'claude_code';
   return clean || 'claude_code';
 }
 
+// First-party providers on the Vercel AI Gateway (multi-word first so the
+// dash-separated legacy ids match longest-prefix).
+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',
+];
+
+// 'pi-anthropic-claude-sonnet-4.6' / 'vercel/anthropic/x' -> 'anthropic/claude-sonnet-4.6'
+function gatewayModelId(raw) {
+  let bare = String(raw || '').replace(/^pi-/, '').replace(/^vercel\//, '');
+  if (bare.includes('/')) return bare;
+  for (const provider of GATEWAY_PROVIDERS) {
+    const prefix = `${provider}-`;
+    if (bare.startsWith(prefix)) return `${provider}/${bare.slice(prefix.length)}`;
+  }
+  return bare;
+}
+
 function canonicalModel(modelId, harness) {
   const raw = String(modelId || '').trim();
   if (!raw) {
@@ -102,6 +144,11 @@ function canonicalModel(modelId, harness) {
     }
     return raw;
   }
+  // Cursor is provider_auth-only and reports no usage, so the model id is a
+  // display/runtime identity, not a billing identity; keep it as sent.
+  if (harness === 'cursor') return raw;
+  // Pi bills against the gateway model identity ('anthropic/claude-sonnet-4.6').
+  if (harness === 'pi') return gatewayModelId(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}`;
@@ -148,6 +195,14 @@ function cliModelFor({ harness, modelId, cliModel, reasoningEffort }) {
     }
     return effort ? `${base}/${effort}` : base;
   }
+  if (harness === 'cursor') {
+    // The adapter matches this against cursor-agent's ACP availableModels.
+    return clean.replace(/^cursor\//, '');
+  }
+  if (harness === 'pi') {
+    // Pi's vercel-ai-gateway provider takes bare '<provider>/<model>' ids.
+    return gatewayModelId(clean);
+  }
   if (harness === 'opencode') {
     const bare = clean.replace(/^opencode-/, '');
     const gatewayProviders = [
@@ -398,7 +453,7 @@ function createContract(payload, options = {}) {
   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)) {
+  if (!['claude_code', 'codex', 'opencode', 'cursor', 'pi'].includes(harness)) {
     throw new Error(`Unsupported harness for clean chat core: ${harness}`);
   }
   const authMethod = coerceAuth(harness, payload.authMethod || 'amalgm');

package/runtime/scripts/chat-core/normalizers/cursor.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const {
+  errorEvent,
+  reasoningDelta,
+  textDelta,
+  toolCompleted,
+  toolStarted,
+  toolUpdated,
+  usageFinal,
+} = require('../events');
+
+// ACP tool kinds -> amalgm tool kinds (tool-shape.js vocabulary).
+const ACP_TOOL_KINDS = {
+  read: 'file_read',
+  edit: 'file_edit',
+  delete: 'file_edit',
+  move: 'file_write',
+  search: 'search',
+  execute: 'bash',
+  fetch: 'browser',
+  think: 'unknown',
+  switch_mode: 'unknown',
+  other: 'unknown',
+};
+
+// ACP PromptResponse stopReason -> amalgm done stopReason.
+function cursorStopReason(stopReason) {
+  const clean = String(stopReason || '').trim();
+  if (!clean || clean === 'end_turn') return 'end_turn';
+  if (clean === 'cancelled') return 'cancelled';
+  if (clean === 'refusal') return 'refusal';
+  if (clean === 'max_tokens' || clean === 'max_turn_requests') return clean;
+  return 'end_turn';
+}
+
+function contentText(content) {
+  if (!content || typeof content !== 'object') return '';
+  if (typeof content.text === 'string') return content.text;
+  return '';
+}
+
+// ACP ToolCallContent[] -> a renderable output value.
+function toolOutput(content) {
+  if (!Array.isArray(content) || content.length === 0) return undefined;
+  const texts = [];
+  const diffs = [];
+  for (const item of content) {
+    if (!item || typeof item !== 'object') continue;
+    if (item.type === 'diff') {
+      diffs.push({ path: item.path, oldText: item.oldText ?? null, newText: item.newText ?? '' });
+    } else if (item.type === 'content') {
+      const text = contentText(item.content);
+      if (text) texts.push(text);
+    } else if (item.type === 'terminal' && item.terminalId) {
+      texts.push(`[terminal ${item.terminalId}]`);
+    }
+  }
+  if (diffs.length && texts.length) return { diffs, text: texts.join('\n') };
+  if (diffs.length) return diffs.length === 1 ? diffs[0] : { diffs };
+  if (texts.length) return texts.join('\n');
+  return undefined;
+}
+
+function rawOutputValue(rawOutput) {
+  if (rawOutput === undefined || rawOutput === null) return undefined;
+  if (typeof rawOutput !== 'object') return rawOutput;
+  if (typeof rawOutput.stdout === 'string' || typeof rawOutput.stderr === 'string') {
+    const text = [rawOutput.stdout, rawOutput.stderr].filter(Boolean).join('\n').trimEnd();
+    return {
+      ...(text ? { text } : {}),
+      ...(rawOutput.exitCode !== undefined ? { exitCode: rawOutput.exitCode } : {}),
+    };
+  }
+  return rawOutput;
+}
+
+function toolData(state, toolCallId, update = {}) {
+  const known = state.tools.get(toolCallId) || {};
+  const next = {
+    toolName: update.title || known.toolName || 'Tool',
+    kind: ACP_TOOL_KINDS[update.kind] || known.kind || undefined,
+    input: update.rawInput !== undefined ? update.rawInput : known.input,
+  };
+  state.tools.set(toolCallId, next);
+  return next;
+}
+
+// One ACP session/update notification -> amalgm events. `state` carries
+// providerSessionId and per-turn tool bookkeeping; it is created per prompt.
+function normalizeCursorUpdate(update, state) {
+  const base = { providerSessionId: state.providerSessionId };
+  const kind = update?.sessionUpdate;
+  if (kind === 'agent_message_chunk') {
+    const text = contentText(update.content);
+    return text ? [textDelta(text, base)] : [];
+  }
+  if (kind === 'agent_thought_chunk') {
+    const text = contentText(update.content);
+    return text ? [reasoningDelta(text, base)] : [];
+  }
+  if (kind === 'tool_call') {
+    const data = toolData(state, update.toolCallId, update);
+    return [toolStarted(update.toolCallId, { ...base, ...data })];
+  }
+  if (kind === 'tool_call_update') {
+    const data = toolData(state, update.toolCallId, update);
+    // Shell/execute results arrive as rawOutput ({exitCode, stdout, stderr});
+    // file edits arrive as content diff items.
+    const output = toolOutput(update.content) ?? rawOutputValue(update.rawOutput);
+    if (update.status === 'completed' || update.status === 'failed') {
+      state.tools.delete(update.toolCallId);
+      return [toolCompleted(update.toolCallId, {
+        ...base,
+        ...data,
+        ...(output !== undefined ? { output } : {}),
+        isError: update.status === 'failed',
+        ...(update.status === 'failed' ? { error: output || 'Tool call failed' } : {}),
+      })];
+    }
+    return [toolUpdated(update.toolCallId, {
+      ...base,
+      toolName: data.toolName,
+      kind: data.kind,
+      ...(update.rawInput !== undefined ? { inputDelta: update.rawInput } : {}),
+      ...(output !== undefined ? { output } : {}),
+    })];
+  }
+  if (kind === 'usage_update') {
+    // Cursor does not emit these today; mapped so context tracking lights up
+    // the moment the agent ships the ACP session-usage extension.
+    return [usageFinal({
+      usedTokens: update.used,
+      maxTokens: update.size,
+      costUsd: update.cost?.amount ?? null,
+      operation: 'context_snapshot',
+      billable: false,
+      exact: false,
+      source: 'cursor_acp_usage_update',
+    }, base)];
+  }
+  if (kind === 'error') {
+    return [errorEvent(update.message || 'Cursor agent error', base)];
+  }
+  // Intentionally ignored: user_message_chunk (session/load replay),
+  // session_info_update (amalgm owns titles), available_commands_update,
+  // current_mode_update, config_options_update, plan.
+  return [];
+}
+
+// ACP PromptResponse.usage (session-usage RFD) -> exact turn usage. Cursor does
+// not populate this today; the mapping is here for when it does.
+function cursorPromptUsage(usage, base = {}) {
+  if (!usage || typeof usage !== 'object') return null;
+  const total = Number(usage.total_tokens ?? usage.totalTokens);
+  if (!Number.isFinite(total) || total <= 0) return null;
+  return usageFinal({
+    inputTokens: usage.input_tokens ?? usage.inputTokens,
+    outputTokens: usage.output_tokens ?? usage.outputTokens,
+    cacheReadTokens: usage.cached_read_tokens ?? usage.cacheReadTokens,
+    cacheWriteTokens: usage.cached_write_tokens ?? usage.cacheWriteTokens,
+    thoughtTokens: usage.thought_tokens ?? usage.thoughtTokens,
+    operation: 'chat_turn',
+    billable: true,
+    exact: true,
+    source: 'cursor_acp_prompt_usage',
+  }, base);
+}
+
+module.exports = {
+  cursorPromptUsage,
+  cursorStopReason,
+  normalizeCursorUpdate,
+};

package/runtime/scripts/chat-core/normalizers/normalizer_spec.md

@@ -21,6 +21,44 @@ Cell legend: ✅ handled · ⚠️ handled, with gaps · ❌ dropped · `TBD` no
 
 ---
 
+## Cursor (ACP) — added 2026-07-01
+
+Cursor rides the generic ACP client (`../adapters/acp-client.js`) + `cursor.js` in this dir. Because amalgm's event vocabulary already mirrors ACP `session/update`, the normalizer is a thin shim rather than a per-event translation table:
+
+| ACP | Amalgm | Notes |
+|---|---|---|
+| `agent_message_chunk` | `text.delta` | ✅ |
+| `agent_thought_chunk` | `reasoning.delta` | ✅ (composer-2.5 emits these) |
+| `tool_call` / `tool_call_update` | `tool.started/updated/completed` | ✅ ACP kinds map to amalgm kinds (`execute`→`bash`, `edit`→`file_edit`, …); shell results arrive in `rawOutput` `{exitCode, stdout, stderr}`, file edits as `content` diff items |
+| `session/request_permission` | auto-answered `allow_always` (parity with bypassPermissions) | ⚠️ not yet surfaced as a first-class `permission_request` event |
+| `PromptResponse.stopReason` | `done` | ✅ `end_turn`/`cancelled`/`refusal`/`max_tokens` |
+| `usage_update` / `PromptResponse.usage` | `usage.final` | ⚠️ mapped but **cursor emits neither today** — no token usage exists for this harness; snapshots are `billable:false, exact:false`, prompt usage would be `exact:true chat_turn` the day Cursor ships the ACP session-usage extension |
+| `session_info_update`, `available_commands_update`, `plan`, `current_mode_update`, `user_message_chunk` (session/load replay) | dropped | ❌ intentional |
+
+Sessions: one `cursor-agent acp` process per amalgm session; resume = `session/load` (full history replay is discarded — nothing subscribes during `create`). Model selection: `session/set_model` accepts ONLY exact ids from `availableModels` (base + bracket params); `matchAcpModel` resolves amalgm cliModels (bare base names, legacy effort/speed suffixes stripped) to those ids. Auth: provider_auth only — the login token lives in the macOS Keychain, so the managed home gets a `Library/Keychains` alias (`syncCursorProviderAuth`).
+
+---
+
+## Pi (native RPC) — added 2026-07-01
+
+Pi speaks its own JSONL RPC (`pi --mode rpc`, NOT JSON-RPC: commands `{id, type}`, responses `{type:'response'}`, un-id'd events). Adapter: `../adapters/pi.js` (`PiRpc` mirrors codex's `JsonLineRpc` pattern); normalizer: `pi.js` in this dir.
+
+| Pi RPC | Amalgm | Notes |
+|---|---|---|
+| `message_update` `text_delta` / `thinking_delta` | `text.delta` / `reasoning.delta` | ✅ |
+| `message_update` error (reason ≠ aborted) | `error` | ✅ from `message.errorMessage` |
+| `tool_execution_start/update/end` | `tool.started/updated/completed` | ✅ update carries accumulated output, not deltas |
+| `message_end` (assistant) | `usage.final` `chat_step` `exact:true` | ✅ **best usage of any harness**: input/output/cacheRead/cacheWrite + native USD `cost.total` per message |
+| `get_session_stats` after `agent_end` | `usage.final` `context_snapshot` `billable:false` | ✅ context circle from `contextUsage.tokens/contextWindow` |
+| `compaction_start/end` | `compaction.started/finished` | ✅ `tokensBefore` → preTokens |
+| `auto_retry_start` / `extension_error` | `warning` | ✅ |
+| `agent_end` | `done` | ✅ adapter-driven so the final context snapshot lands first |
+| `toolcall_*` deltas, turn/queue events | dropped | ❌ intentional (steer/follow_up unused so far) |
+
+Billing: `finalizeTurnUsage` has a pi branch — turn = sum of exact `chat_step` records, native gateway cost summed into `costUsd`/`marketCostUsd` (no catalog re-derivation). Sessions: append-only files under `<home>/.pi/agent/sessions/`; providerSessionId = session FILE PATH, resume = spawn with `--session <path>`. Models: built-in `vercel-ai-gateway` provider (`AI_GATEWAY_API_KEY`), cliModel = bare `<provider>/<model>` gateway id. Auth: all three — amalgm rides a generated extension (`.pi/amalgm-egress-extension.js`) that re-points the provider baseUrl at `/egress/<sid>/ai_gateway` (pi appends `/v1/messages` itself, which the proxy parses for usage); byok uses ai_gateway credentials; provider_auth copies `~/.pi/agent/{auth,models,settings}.json`. No MCP: pi's tools are built-in read/bash/edit/write (+ extensions) — MCP relay does not apply yet.
+
+---
+
 ## 1. Text parts
 
 Streamed assistant text. The user-visible response.