amalgm 0.0.0 → 0.0.1

package/runtime/scripts/amalgm-mcp/agents/talk.js

@@ -0,0 +1,1156 @@
+/**
+ * talk_to_agent — multi-turn agent conversations.
+ *
+ * Delegates to the local chat-server. On the first turn it creates a Supabase
+ * session row (if configured) so the UI can pick it up. On follow-up turns
+ * (conversation_id/session_id provided), chat-core reuses the frozen runtime session
+ * while it is still alive.
+ *
+ * Conversation lines are additionally appended to
+ * ~/.amalgm/agent-convos/{sessionId}.jsonl as a local trace.
+ */
+
+const crypto = require('crypto');
+const path = require('path');
+const os = require('os');
+
+const { AMALGM_COMPUTER_ID, AMALGM_USER_ID, DEFAULT_CWD, STORAGE_DIR } = require('../config');
+const { runThroughChatServer } = require('../lib/chat-runner');
+const {
+  hasSupabase,
+  supabaseInsert,
+  supabasePatch,
+  supabaseSelect,
+} = require('../lib/supabase');
+const {
+  hydrateModelPreferences,
+  getSelectedModel,
+  resolveModelSelection,
+  DEFAULT_SELECTED_MODELS,
+} = require('../lib/prefs');
+const { textResult, errorResult } = require('../lib/tool-result');
+const { ensureDir } = require('../lib/storage');
+const {
+  appendAgentConvoLog,
+  normalizeConversationId,
+  resolveAgentByNameOrId,
+} = require('./store');
+const {
+  chatInputToLegacyFields,
+  getChatInputText,
+  normalizeChatInput,
+} = require('../../../lib/chatInput');
+const credentialAdapter = require('../../credential-adapter');
+const { buildLocalMcpServerConfigs } = require('../lib/mcp-resolver');
+
+const MAX_INLINE_MESSAGE_CHARS = Number(
+  process.env.AMALGM_TALK_TO_AGENT_MAX_INLINE_CHARS
+    || process.env.AMALGM_TALK_TO_AGENT_MAX_MESSAGE_CHARS
+    || 2800,
+);
+const AGENT_TO_AGENT_PROMPT =
+  'Agent-to-agent call: keep visible assistant text answer-focused. Do not narrate tool-use intent, pre-tool status, or private planning in plain text; use tools silently and report results when useful.';
+const AGENT_CONTEXT_DIR = path.join(STORAGE_DIR, 'agent-context');
+const DEFAULT_FOREGROUND_TIMEOUT_MS = Number(
+  process.env.AMALGM_TALK_TO_AGENT_FOREGROUND_TIMEOUT_MS || 120_000,
+);
+const MAX_FOREGROUND_TIMEOUT_MS = Number(
+  process.env.AMALGM_TALK_TO_AGENT_MAX_FOREGROUND_TIMEOUT_MS || 300_000,
+);
+const HEARTBEAT_INTERVAL_MS = Number(
+  process.env.AMALGM_TALK_TO_AGENT_HEARTBEAT_MS || 15_000,
+);
+const ACTIVE_RESPONSE_PREVIEW_CHARS = Number(
+  process.env.AMALGM_TALK_TO_AGENT_ACTIVE_PREVIEW_CHARS || 20_000,
+);
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeStringList(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values
+    .filter((value) => typeof value === 'string')
+    .map((value) => value.trim())
+    .filter(Boolean))];
+}
+
+function safeContextName(value) {
+  return String(value || 'message')
+    .replace(/[^A-Za-z0-9_.-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'message';
+}
+
+function writeLongMessageContextFile(sessionId, messageId, text) {
+  const dir = path.join(AGENT_CONTEXT_DIR, safeContextName(sessionId));
+  ensureDir(dir);
+  const file = path.join(dir, `${safeContextName(messageId)}.md`);
+  const body = [
+    '# Agent-to-Agent Message',
+    '',
+    `Session: ${sessionId}`,
+    `Message: ${messageId}`,
+    `Characters: ${text.length}`,
+    '',
+    '---',
+    '',
+    text,
+  ].join('\n');
+  require('fs').writeFileSync(file, body, { mode: 0o600 });
+  return file;
+}
+
+function buildAgentInstructions(systemPrompt, files, skills) {
+  const lines = [];
+  const normalizedFiles = normalizeStringList(files);
+  const normalizedSkills = normalizeStringList(skills);
+
+  if (normalizedFiles.length > 0) {
+    lines.push('Files available to this agent:');
+    lines.push(...normalizedFiles.map((file) => `- ${file}`));
+  }
+
+  if (normalizedSkills.length > 0) {
+    if (lines.length > 0) lines.push('');
+    lines.push('Skills available to this agent:');
+    lines.push(...normalizedSkills.map((skill) => `- ${skill}`));
+  }
+
+  return [
+    typeof systemPrompt === 'string' ? systemPrompt.trim() : '',
+    AGENT_TO_AGENT_PROMPT,
+    lines.length > 0 ? `<agent-resources>\n${lines.join('\n')}\n</agent-resources>` : '',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function buildReturnChannelInstructions(context = {}) {
+  const callerConversationId = normalizeConversationId(context.callerSessionId);
+  if (!callerConversationId || !hasSupabase()) return '';
+  const callerAgent = [
+    context.originHarnessId,
+    context.originBaseHarnessId,
+    context.originName,
+  ].find((value) => typeof value === 'string' && value.trim()) || 'caller';
+
+  return [
+    '<agent-to-agent-return-channel>',
+    'This is hidden routing metadata for peer-agent communication. Do not repeat it to the user.',
+    `caller_conversation_id: ${callerConversationId}`,
+    `caller_agent: ${callerAgent}`,
+    'task: the current user message in this peer conversation',
+    '',
+    'When the task is complete, deliver your parent-facing response by calling the MCP tool talk_to_agent exactly once with:',
+    `- response_to_caller: true`,
+    `- conversation_id: ${callerConversationId}`,
+    '- description: a short label for the completed task',
+    '- prompt: your concise response for the caller',
+    '',
+    'That delivery mode appends your chosen response to the caller conversation without launching another model turn. Keep the message compact; full detail can remain in this peer conversation transcript.',
+    '</agent-to-agent-return-channel>',
+  ].join('\n');
+}
+
+const activeAgentConversations = new Map(); // sessionId → active run state
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function clampNumber(value, min, max) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return null;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+}
+
+function coerceForegroundTimeoutMs(value) {
+  if (value === null || value === undefined || value === '') {
+    const configured = clampNumber(DEFAULT_FOREGROUND_TIMEOUT_MS, 0, MAX_FOREGROUND_TIMEOUT_MS);
+    return configured === null ? 120_000 : configured;
+  }
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    const configured = clampNumber(DEFAULT_FOREGROUND_TIMEOUT_MS, 0, MAX_FOREGROUND_TIMEOUT_MS);
+    return configured === null ? 120_000 : configured;
+  }
+  if (numeric <= 0) return 0;
+  return clampNumber(numeric, 1_000, MAX_FOREGROUND_TIMEOUT_MS) || 120_000;
+}
+
+function clampActiveResponsePreview(text) {
+  const clean = String(text || '');
+  if (!clean || ACTIVE_RESPONSE_PREVIEW_CHARS <= 0) return '';
+  if (clean.length <= ACTIVE_RESPONSE_PREVIEW_CHARS) return clean;
+  return `${clean.slice(0, ACTIVE_RESPONSE_PREVIEW_CHARS).trimEnd()}\n\n... (streaming preview truncated; wait for completion or increase limit)`;
+}
+
+function includeMetricsFlag(value) {
+  return value === true || String(value || '').toLowerCase() === 'true';
+}
+
+function appendStatusLog(sessionId, event, fields = {}) {
+  appendAgentConvoLog(sessionId, {
+    role: 'status',
+    event,
+    timestamp: nowIso(),
+    ...fields,
+  });
+}
+
+function updateActiveConversation(sessionId, patch = {}) {
+  const current = activeAgentConversations.get(sessionId);
+  if (!current) return null;
+  const next = {
+    ...current,
+    ...patch,
+    updatedAt: nowIso(),
+  };
+  activeAgentConversations.set(sessionId, next);
+  return next;
+}
+
+function summarizeActiveConversation(sessionId) {
+  const state = activeAgentConversations.get(sessionId);
+  if (!state) return null;
+  const {
+    abortController,
+    ...safeState
+  } = state;
+  return safeState;
+}
+
+function metricSummary(metrics) {
+  if (!metrics) return null;
+  return {
+    textChunks: metrics.textChunks || 0,
+    reasoningChunks: metrics.reasoningChunks || 0,
+    toolEvents: metrics.toolEvents || 0,
+    usageEvents: metrics.usageEvents || 0,
+    sawComplete: metrics.sawComplete === true,
+    sawError: metrics.sawError === true,
+    wallTimeMs: metrics.wallTimeMs || 0,
+    toolCallCount: Array.isArray(metrics.toolCalls) ? metrics.toolCalls.length : 0,
+  };
+}
+
+function responsePayload({
+  agent,
+  description,
+  sessionId,
+  runId,
+  status,
+  isNewConversation,
+  longMessageContext,
+  outputText,
+  stopReason,
+  usage,
+  metrics,
+  warnings,
+  recovery,
+  includeMetrics,
+  extra = {},
+}) {
+  return {
+    agent: agent.name,
+    agent_id: agent.id,
+    description,
+    conversation_id: sessionId,
+    session_id: sessionId,
+    run_id: runId,
+    status,
+    ...(outputText !== undefined ? { response: outputText } : {}),
+    is_new_conversation: isNewConversation,
+    ...(stopReason !== undefined ? { stop_reason: stopReason } : {}),
+    usage: usage || null,
+    metric_summary: metricSummary(metrics),
+    ...(includeMetrics ? { metrics: metrics || null } : {}),
+    warnings: warnings || [],
+    long_message: longMessageContext,
+    active: summarizeActiveConversation(sessionId),
+    recovery,
+    ...extra,
+  };
+}
+
+function agentErrorResult({
+  agent,
+  description,
+  sessionId,
+  runId,
+  isNewConversation,
+  longMessageContext,
+  error,
+  status = 'error',
+  includeMetrics,
+}) {
+  return errorResult(
+    JSON.stringify(
+      responsePayload({
+        agent,
+        description,
+        sessionId,
+        runId,
+        status,
+        isNewConversation,
+        longMessageContext,
+        warnings: [error],
+        recovery:
+          'Use agents_get_conversation with this conversation_id/run_id to inspect progress and recover any later transcript.',
+        includeMetrics,
+        extra: { error },
+      }),
+      null,
+      2,
+    ),
+  );
+}
+
+function summarizeStreamEvent(event) {
+  if (!event || typeof event !== 'object') return null;
+  if (event._type === 'update' && (event.sessionUpdate === 'tool_call' || event.sessionUpdate === 'tool_call_update')) {
+    return {
+      type: event.sessionUpdate,
+      toolCallId: event.toolCallId || null,
+      title: event.title || null,
+      kind: event.kind || null,
+      status: event.status || null,
+    };
+  }
+  if (event._type === 'update' && event.sessionUpdate === 'agent_message_chunk') {
+    return { type: 'agent_message_chunk' };
+  }
+  if (event._type === 'update' && event.sessionUpdate === 'agent_thought_chunk') {
+    return { type: 'agent_thought_chunk' };
+  }
+  if (event._type === 'update' && event.sessionUpdate === 'usage_update') {
+    return { type: 'usage_update' };
+  }
+  if (event._type === 'complete') {
+    return { type: 'complete', stopReason: event.stopReason || null };
+  }
+  if (event._type === 'error') {
+    return { type: 'error', message: event.message || null };
+  }
+  return { type: event._type || 'unknown' };
+}
+
+function coerceAuthMethodForHarness(harnessId, authMethod) {
+  const supported = credentialAdapter.SUPPORTED_AUTH_BY_HARNESS?.[harnessId] || ['amalgm'];
+  return supported.includes(authMethod) ? authMethod : supported[0] || 'amalgm';
+}
+
+async function appendAsyncCompletionToCallerSession({
+  callerSessionId,
+  agent,
+  agentSessionId,
+  runId,
+  description,
+  stopReason,
+  warnings,
+}) {
+  if (!callerSessionId || !hasSupabase()) return;
+  const text = [
+    `Agent completed: ${description || agent.name}`,
+    '',
+    `Agent: ${agent.name}`,
+    `Conversation: ${agentSessionId}`,
+    `Run: ${runId}`,
+    stopReason ? `Stop reason: ${stopReason}` : '',
+    warnings?.length ? `Warnings: ${warnings.join(' ')}` : '',
+    '',
+    'The peer response is stored in its conversation transcript.',
+    'Use agents_get_conversation with this conversation_id to read it, or talk_to_agent with this conversation_id to continue.',
+  ].filter((line) => line !== '').join('\n');
+
+  await supabaseInsert('messages', {
+    id: crypto.randomUUID(),
+    session_id: callerSessionId,
+    role: 'assistant',
+    parts: [{ type: 'text', text }],
+    content_plain: text,
+    origin: 'agent',
+    origin_id: agentSessionId,
+    metadata: {
+      callback: true,
+      agentId: agent.id,
+      agentName: agent.name,
+      agentSessionId,
+      runId,
+      description,
+    },
+  }).catch(() => {});
+  await supabasePatch('sessions', 'id', callerSessionId, {
+    last_message_at: new Date().toISOString(),
+    new_messages: true,
+  }).catch(() => {});
+}
+
+async function deliverResponseToCallerSession({
+  targetSessionId,
+  sourceSessionId,
+  description,
+  text,
+}) {
+  if (!hasSupabase()) {
+    return errorResult('response_to_caller requires a Supabase-backed caller conversation.');
+  }
+  if (!targetSessionId) {
+    return errorResult('conversation_id is required when response_to_caller=true.');
+  }
+  if (!sourceSessionId) {
+    return errorResult('response_to_caller can only be used from inside a running peer agent conversation.');
+  }
+  if (!text || !String(text).trim()) {
+    return errorResult('prompt is required when response_to_caller=true.');
+  }
+
+  const targetRows = await supabaseSelect(
+    'sessions',
+    `id=eq.${targetSessionId}&user_id=eq.${AMALGM_USER_ID}&select=id,title,harness,metadata`,
+  );
+  const targetSession = Array.isArray(targetRows) ? targetRows[0] : null;
+  if (!targetSession) {
+    return errorResult('Caller conversation was not found or is not owned by this user.');
+  }
+
+  const sourceRows = await supabaseSelect(
+    'sessions',
+    `id=eq.${sourceSessionId}&user_id=eq.${AMALGM_USER_ID}&select=id,title,harness,origin,origin_id,metadata`,
+  );
+  const sourceSession = Array.isArray(sourceRows) ? sourceRows[0] : null;
+  if (!sourceSession) {
+    return errorResult('Peer conversation was not found or is not owned by this user.');
+  }
+  if (sourceSession.origin !== 'agent' || sourceSession.origin_id !== targetSessionId) {
+    return errorResult('Peer conversation is not linked to the requested caller conversation.');
+  }
+
+  const messageText = String(text).trim();
+  const deliveredAt = nowIso();
+  const sourceMetadata = isObject(sourceSession.metadata) ? sourceSession.metadata : {};
+  const sourceAgentId = sourceMetadata.agentId || sourceSession.harness || null;
+  const sourceAgentName = sourceMetadata.agentName || sourceSession.title || sourceSession.harness || 'Peer agent';
+
+  const inserted = await supabaseInsert('messages', {
+    id: crypto.randomUUID(),
+    session_id: targetSessionId,
+    role: 'assistant',
+    parts: [{ type: 'text', text: messageText }],
+    content_plain: messageText,
+    origin: 'agent',
+    origin_id: sourceSessionId,
+    metadata: {
+      responseToCaller: true,
+      sourceConversationId: sourceSessionId,
+      sourceAgentId,
+      sourceAgentName,
+      sourceHarness: sourceSession.harness || null,
+      description,
+    },
+  });
+  if (!inserted) {
+    return errorResult('Failed to deliver response to caller conversation.');
+  }
+
+  await supabasePatch('sessions', 'id', targetSessionId, {
+    last_message_at: deliveredAt,
+    new_messages: true,
+  }).catch(() => {});
+
+  updateActiveConversation(sourceSessionId, {
+    callerResponseDelivered: true,
+    callerResponseDeliveredAt: deliveredAt,
+    callerResponseTarget: targetSessionId,
+    callerResponseText: messageText,
+    callerResponseDescription: description || null,
+  });
+  appendStatusLog(sourceSessionId, 'caller_response_delivered', {
+    targetConversationId: targetSessionId,
+    description,
+    messageChars: messageText.length,
+  });
+
+  return textResult(JSON.stringify({
+    status: 'delivered',
+    response_to_caller: true,
+    conversation_id: targetSessionId,
+    session_id: targetSessionId,
+    source_conversation_id: sourceSessionId,
+    description,
+  }, null, 2));
+}
+
+async function handleTalkToAgent(args, context = {}) {
+  const {
+    agent: requestedAgent,
+    agent_id,
+    description,
+    prompt,
+    message,
+    conversation_id,
+    session_id,
+    cwd,
+    chatInput,
+    mode,
+    run_in_background,
+    response_to_caller,
+    timeout_ms,
+    include_metrics,
+    isolation,
+  } = args || {};
+  const taskPrompt = prompt || message;
+  if (!taskPrompt && !chatInput) {
+    return errorResult('prompt is required.');
+  }
+  const requestedConversationId = conversation_id || session_id;
+  const normalizedConversationId = requestedConversationId
+    ? normalizeConversationId(requestedConversationId)
+    : null;
+  if (requestedConversationId && !normalizedConversationId) {
+    return errorResult('conversation_id must be a UUID.');
+  }
+  const taskDescription =
+    typeof description === 'string' && description.trim()
+      ? description.trim()
+      : String(taskPrompt || '').trim().split(/\s+/).slice(0, 5).join(' ') || 'Peer response';
+  const responseToCaller =
+    response_to_caller === true || String(response_to_caller || '').toLowerCase() === 'true';
+
+  if (responseToCaller) {
+    return deliverResponseToCallerSession({
+      targetSessionId: normalizedConversationId,
+      sourceSessionId: normalizeConversationId(context.callerSessionId),
+      description: taskDescription,
+      text: taskPrompt,
+    });
+  }
+
+  await hydrateModelPreferences();
+  const agentLookup = requestedAgent || agent_id || 'Codex';
+  const agent = resolveAgentByNameOrId(agentLookup);
+  if (!agent) {
+    return errorResult(
+      `Agent not found: ${agentLookup}. Use agents_list to see available agents.`,
+    );
+  }
+  const isNewConversation = !normalizedConversationId;
+  const sessionId = normalizedConversationId || crypto.randomUUID();
+  const userMessageId = crypto.randomUUID();
+  const assistantMessageId = crypto.randomUUID();
+  const runId = assistantMessageId;
+  const asyncMode = run_in_background === true || String(mode || '').toLowerCase() === 'async';
+  const includeMetrics = includeMetricsFlag(include_metrics);
+  const foregroundTimeoutMs = coerceForegroundTimeoutMs(timeout_ms);
+
+  // Chat-server agent ID derives from the agent's base harness.
+  const agentIdMap = { claude_code: 'claude', codex: 'codex', opencode: 'opencode', pi: 'pi', amp: 'amp', cursor: 'cursor' };
+  const chatAgentId = agentIdMap[agent.baseHarnessId] || 'claude';
+  const defaultAuthMethod = coerceAuthMethodForHarness(
+    agent.baseHarnessId,
+    agent.authMethod
+    || (credentialAdapter.VALID_HARNESS_IDS.includes(agent.baseHarnessId)
+      ? credentialAdapter.getPersistedAuthMode(agent.baseHarnessId)
+      : 'amalgm'),
+  );
+  const agentFiles = normalizeStringList(agent.files);
+  const agentSkills = normalizeStringList(agent.skills);
+  const agentMcpAppIds = normalizeStringList(agent.mcp?.appIds ?? agent.mcpAppIds);
+  const baseAgentSystemPrompt = buildAgentInstructions(
+    agent.systemPrompt,
+    agentFiles,
+    agentSkills,
+  );
+  const returnChannelInstructions = buildReturnChannelInstructions(context);
+  const agentSystemPrompt = [
+    baseAgentSystemPrompt,
+    returnChannelInstructions,
+  ].filter(Boolean).join('\n\n');
+  const fallbackModelId = agent.builtin
+    ? agent.baseModelId
+    : agent.baseModelId || DEFAULT_SELECTED_MODELS[agent.baseHarnessId] || null;
+  const normalizedChatInput = normalizeChatInput({
+    ...(isObject(chatInput) ? chatInput : {}),
+    agent: {
+      ...((isObject(chatInput) && isObject(chatInput.agent)) ? chatInput.agent : {}),
+      harness:
+        ((isObject(chatInput) && isObject(chatInput.agent) && chatInput.agent.harness) || null)
+        || agent.baseHarnessId,
+      model:
+        ((isObject(chatInput) && isObject(chatInput.agent) && chatInput.agent.model) || null)
+        || fallbackModelId,
+      authMethod: coerceAuthMethodForHarness(
+        agent.baseHarnessId,
+        ((isObject(chatInput) && isObject(chatInput.agent) && chatInput.agent.authMethod) || null)
+        || defaultAuthMethod,
+      ),
+      customAgentId: agent.builtin ? null : agent.id,
+      systemPrompt:
+        ((isObject(chatInput) && isObject(chatInput.agent) && chatInput.agent.systemPrompt) || null)
+        || agentSystemPrompt
+        || null,
+    },
+    tools: {
+      ...((isObject(chatInput) && isObject(chatInput.tools)) ? chatInput.tools : {}),
+      mcpAppIds: normalizeStringList([
+        ...agentMcpAppIds,
+        ...((((isObject(chatInput) && isObject(chatInput.tools) && Array.isArray(chatInput.tools.mcpAppIds))
+          ? chatInput.tools.mcpAppIds
+          : []))),
+      ]),
+    },
+    execution: {
+      ...((isObject(chatInput) && isObject(chatInput.execution)) ? chatInput.execution : {}),
+      cwd:
+        ((isObject(chatInput) && isObject(chatInput.execution) && chatInput.execution.cwd) || null)
+        || cwd
+        || DEFAULT_CWD,
+    },
+  }, {
+    prompt: taskPrompt,
+    harness: agent.baseHarnessId,
+    modelId: fallbackModelId,
+    authMethod: defaultAuthMethod,
+    cwd,
+    systemPrompt: agentSystemPrompt,
+  });
+  const legacyChatFields = chatInputToLegacyFields(normalizedChatInput, {
+    prompt: taskPrompt,
+    harness: agent.baseHarnessId,
+    modelId: fallbackModelId,
+    authMethod: defaultAuthMethod,
+    cwd,
+    systemPrompt: agentSystemPrompt,
+  });
+  let userPromptText = getChatInputText(normalizedChatInput, taskPrompt) || legacyChatFields.prompt;
+  let longMessageContext = null;
+  if (MAX_INLINE_MESSAGE_CHARS > 0 && userPromptText.length > MAX_INLINE_MESSAGE_CHARS) {
+    const contextPath = writeLongMessageContextFile(sessionId, userMessageId, userPromptText);
+    longMessageContext = {
+      path: contextPath,
+      chars: userPromptText.length,
+      threshold: MAX_INLINE_MESSAGE_CHARS,
+    };
+    const contextPrompt = [
+      `The caller sent a long agent-to-agent message (${userPromptText.length} characters).`,
+      `It is stored in a local context file: ${contextPath}`,
+      '',
+      'Read that file fully before responding. Treat it as the caller\'s message for this turn.',
+      'Do not mention private tool-use narration; answer the request after reading the file.',
+    ].join('\n');
+    legacyChatFields.prompt = contextPrompt;
+    normalizedChatInput.parts = [{ type: 'text', text: contextPrompt }];
+    normalizedChatInput.files = [
+      ...(Array.isArray(normalizedChatInput.files) ? normalizedChatInput.files : []),
+      { path: contextPath, name: 'agent-to-agent-message.md' },
+    ];
+  }
+
+  console.log(
+    `[AmalgmMCP:Agent] ${isNewConversation ? 'Starting' : 'Continuing'} conversation with ${agent.name} (${agent.id}), session: ${sessionId}`,
+  );
+
+  appendAgentConvoLog(sessionId, {
+    role: 'user',
+    agentId: agent.id,
+    runId,
+    description: taskDescription,
+    isolation: isolation || null,
+    message: userPromptText,
+    timestamp: new Date().toISOString(),
+    isNewConversation,
+    ...(longMessageContext ? { longMessageContext } : {}),
+  });
+  appendStatusLog(sessionId, 'queued', {
+    agentId: agent.id,
+    agentName: agent.name,
+    runId,
+    description: taskDescription,
+    asyncMode,
+    foregroundTimeoutMs: asyncMode ? 0 : foregroundTimeoutMs,
+  });
+
+  if (isNewConversation && hasSupabase()) {
+    try {
+      const callerSessionId = context.callerSessionId || null;
+      let parentOrigin =
+        context.originName || context.originHarnessId || context.originBaseHarnessId
+          ? {
+              originName: context.originName || undefined,
+              originHarnessId: context.originHarnessId || undefined,
+              originBaseHarnessId: context.originBaseHarnessId || undefined,
+            }
+          : null;
+
+      if (callerSessionId && !parentOrigin) {
+        const rows = await supabaseSelect(
+          'sessions',
+          `id=eq.${callerSessionId}&user_id=eq.${AMALGM_USER_ID}&select=id,title,harness,metadata`,
+        );
+        const parentSession = Array.isArray(rows) ? rows[0] : null;
+        if (parentSession) {
+          parentOrigin = {
+            originName: parentSession.title || undefined,
+            originHarnessId: parentSession.harness || undefined,
+            originBaseHarnessId: parentSession.metadata?.baseHarnessId || undefined,
+          };
+        }
+      }
+
+      await supabaseInsert('sessions', {
+        id: sessionId,
+        user_id: AMALGM_USER_ID,
+        computer_id: AMALGM_COMPUTER_ID,
+        container_id: os.hostname() || 'agent-conversation',
+        harness: agent.id,
+        title: taskDescription || 'New Chat',
+        status: 'in-progress',
+        origin: 'agent',
+        origin_id: callerSessionId,
+        metadata: {
+          agentId: agent.id,
+          agentName: agent.name,
+          taskDescription,
+          baseHarnessId: agent.baseHarnessId,
+          baseModelId: agent.builtin
+            ? getSelectedModel(agent.baseHarnessId) || agent.baseModelId
+            : agent.baseModelId ||
+              getSelectedModel(agent.baseHarnessId) ||
+              DEFAULT_SELECTED_MODELS[agent.baseHarnessId],
+          isAgentConversation: true,
+          builtin: !!agent.builtin,
+          systemPrompt: baseAgentSystemPrompt || '',
+          ...(returnChannelInstructions
+            ? {
+                returnChannel: {
+                  deliveryTool: 'talk_to_agent',
+                  mode: 'response_to_caller',
+                  callerConversationId: normalizeConversationId(context.callerSessionId),
+                },
+              }
+            : {}),
+          files: agentFiles,
+          skills: agentSkills,
+          mcpAppIds: agentMcpAppIds,
+          ...(parentOrigin || {}),
+        },
+      });
+    } catch (err) {
+      console.error('[AmalgmMCP:Agent] DB session creation failed:', err.message);
+    }
+  }
+
+  const abortController = new AbortController();
+  activeAgentConversations.set(sessionId, {
+    agentId: agent.id,
+    agentName: agent.name,
+    runId,
+    description: taskDescription,
+    status: 'queued',
+    startedAt: nowIso(),
+    updatedAt: nowIso(),
+    lastEventAt: null,
+    counters: {
+      textChunks: 0,
+      reasoningChunks: 0,
+      toolEvents: 0,
+      usageEvents: 0,
+      heartbeats: 0,
+    },
+    abortController,
+  });
+
+  try {
+    const { modelId: uiModelId, cliModel, reasoningEffort } = resolveModelSelection(
+      agent.baseHarnessId,
+      legacyChatFields.modelId || fallbackModelId,
+    );
+    const mcpServers = await buildLocalMcpServerConfigs(legacyChatFields.mcpAppIds || []);
+
+    const chatPayload = {
+      chatInput: normalizedChatInput,
+      prompt: legacyChatFields.prompt,
+      userId: AMALGM_USER_ID,
+      computerId: AMALGM_COMPUTER_ID,
+      codeSessionId: sessionId,
+      assistantMessageId,
+      userMessageId,
+      userParts: legacyChatFields.userParts,
+      agentId: chatAgentId,
+      modelId: uiModelId,
+      cliModel,
+      ...(reasoningEffort ? { reasoningEffort } : {}),
+      cwd: legacyChatFields.cwd || DEFAULT_CWD,
+      authMethod: legacyChatFields.authMethod || defaultAuthMethod,
+      mcpServers,
+      ...(legacyChatFields.systemPrompt ? { systemPrompt: legacyChatFields.systemPrompt } : {}),
+      ...(longMessageContext ? { longMessageContext } : {}),
+      ...(!isNewConversation ? { resumeSessionId: sessionId } : {}),
+      ...(context.callerSessionId
+        ? { origin: 'agent', originId: context.callerSessionId }
+        : {}),
+      ...(context.originName ? { originName: context.originName } : {}),
+      ...(context.originHarnessId ? { originHarnessId: context.originHarnessId } : {}),
+      ...(context.originBaseHarnessId
+        ? { originBaseHarnessId: context.originBaseHarnessId }
+        : {}),
+    };
+
+    let notifyCallerOnCompletion = asyncMode;
+    const finishTurn = async () => {
+      let heartbeatTimer = null;
+      const startedAt = Date.now();
+      const seenLifecycle = {
+        text: false,
+        reasoning: false,
+      };
+      try {
+        updateActiveConversation(sessionId, { status: 'starting' });
+        appendStatusLog(sessionId, 'harness_started', {
+          agentId: agent.id,
+          agentName: agent.name,
+          runId,
+          description: taskDescription,
+        });
+
+        if (HEARTBEAT_INTERVAL_MS > 0) {
+          heartbeatTimer = setInterval(() => {
+            const active = updateActiveConversation(sessionId, {
+              status: 'running',
+              counters: {
+                ...(summarizeActiveConversation(sessionId)?.counters || {}),
+                heartbeats:
+                  ((summarizeActiveConversation(sessionId)?.counters || {}).heartbeats || 0) + 1,
+              },
+            });
+            appendStatusLog(sessionId, 'still_running', {
+              agentId: agent.id,
+              agentName: agent.name,
+              runId,
+              description: taskDescription,
+              elapsedMs: Date.now() - startedAt,
+              active,
+            });
+          }, HEARTBEAT_INTERVAL_MS);
+          if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref();
+        }
+
+        const { outputText, stopReason, usage, metrics } = await runThroughChatServer(
+          chatPayload,
+          abortController.signal,
+          {
+            onEvent(event, eventMetrics) {
+              const summary = summarizeStreamEvent(event);
+              if (!summary) return;
+              const counters = {
+                textChunks: eventMetrics.textChunks || 0,
+                reasoningChunks: eventMetrics.reasoningChunks || 0,
+                toolEvents: eventMetrics.toolEvents || 0,
+                usageEvents: eventMetrics.usageEvents || 0,
+                heartbeats:
+                  (summarizeActiveConversation(sessionId)?.counters || {}).heartbeats || 0,
+              };
+              updateActiveConversation(sessionId, {
+                status: summary.type === 'complete' ? 'finalizing' : 'running',
+                lastEventAt: nowIso(),
+                counters,
+                ...(summary.type === 'agent_message_chunk'
+                  ? {
+                      responsePreview: clampActiveResponsePreview(eventMetrics.outputText),
+                      responsePreviewChars: String(eventMetrics.outputText || '').length,
+                    }
+                  : {}),
+              });
+
+              if (summary.type === 'tool_call' || summary.type === 'tool_call_update') {
+                appendStatusLog(sessionId, 'tool_event', {
+                  agentId: agent.id,
+                  agentName: agent.name,
+                  runId,
+                  description: taskDescription,
+                  streamEvent: summary,
+                });
+                return;
+              }
+              if (summary.type === 'agent_message_chunk' && !seenLifecycle.text) {
+                seenLifecycle.text = true;
+                appendStatusLog(sessionId, 'agent_text_started', {
+                  agentId: agent.id,
+                  agentName: agent.name,
+                  runId,
+                  description: taskDescription,
+                });
+                return;
+              }
+              if (summary.type === 'agent_thought_chunk' && !seenLifecycle.reasoning) {
+                seenLifecycle.reasoning = true;
+                appendStatusLog(sessionId, 'agent_reasoning_started', {
+                  agentId: agent.id,
+                  agentName: agent.name,
+                  runId,
+                  description: taskDescription,
+                });
+                return;
+              }
+              if (summary.type === 'complete' || summary.type === 'error') {
+                appendStatusLog(sessionId, summary.type === 'complete' ? 'stream_complete' : 'stream_error', {
+                  agentId: agent.id,
+                  agentName: agent.name,
+                  runId,
+                  description: taskDescription,
+                  streamEvent: summary,
+                });
+              }
+            },
+          },
+        );
+        const activeAfterTurn = summarizeActiveConversation(sessionId);
+        const deliveredResponseText = String(activeAfterTurn?.callerResponseText || '').trim();
+        const finalOutputText = String(outputText || '').trim() ? outputText : deliveredResponseText;
+        const warnings = [];
+        if (!String(finalOutputText || '').trim()) {
+          warnings.push(
+            metrics?.toolEvents > 0
+              ? 'Agent completed without visible text after tool activity; check the session log or workspace diff before retrying.'
+              : 'Agent completed with an empty text response; retry this same session if you need an answer.',
+          );
+        }
+        if (metrics && metrics.sawComplete === false) {
+          warnings.push('Chat stream ended without an explicit completion frame.');
+        }
+
+        appendAgentConvoLog(sessionId, {
+          role: 'assistant',
+          agentId: agent.id,
+          agentName: agent.name,
+          runId,
+          description: taskDescription,
+          message: finalOutputText,
+          timestamp: new Date().toISOString(),
+          stopReason,
+          usage,
+          metrics,
+          warnings,
+        });
+        updateActiveConversation(sessionId, {
+          status: 'completed',
+          completedAt: nowIso(),
+          counters: {
+            textChunks: metrics?.textChunks || 0,
+            reasoningChunks: metrics?.reasoningChunks || 0,
+            toolEvents: metrics?.toolEvents || 0,
+            usageEvents: metrics?.usageEvents || 0,
+            heartbeats:
+              (summarizeActiveConversation(sessionId)?.counters || {}).heartbeats || 0,
+          },
+        });
+
+        console.log(
+          `[AmalgmMCP:Agent] ${agent.name} responded (${finalOutputText.length} chars, session: ${sessionId})`,
+        );
+
+        if (
+          notifyCallerOnCompletion &&
+          !summarizeActiveConversation(sessionId)?.callerResponseDelivered
+        ) {
+          await appendAsyncCompletionToCallerSession({
+            callerSessionId: context.callerSessionId,
+            agent,
+            agentSessionId: sessionId,
+            runId,
+            description: taskDescription,
+            stopReason,
+            warnings,
+          });
+        }
+
+        return textResult(
+          JSON.stringify(
+            responsePayload({
+              agent,
+              description: taskDescription,
+              sessionId,
+              runId,
+              status: 'completed',
+              isNewConversation,
+              longMessageContext,
+              outputText: finalOutputText,
+              stopReason,
+              usage,
+              metrics,
+              warnings,
+              recovery:
+                'Use agents_get_conversation with this conversation_id if the caller times out or needs the local transcript.',
+              includeMetrics,
+              extra: deliveredResponseText && !String(outputText || '').trim()
+                ? { response_source: 'return_channel' }
+                : {},
+            }),
+            null,
+            2,
+          ),
+        );
+      } catch (err) {
+        updateActiveConversation(sessionId, {
+          status: err.name === 'AbortError' ? 'cancelled' : 'error',
+          error: err.message,
+          completedAt: nowIso(),
+        });
+        appendAgentConvoLog(sessionId, {
+          role: 'error',
+          agentId: agent.id,
+          runId,
+          description: taskDescription,
+          error: err.message,
+          timestamp: new Date().toISOString(),
+        });
+        if (err.name === 'AbortError') {
+          return agentErrorResult({
+            agent,
+            description: taskDescription,
+            sessionId,
+            runId,
+            isNewConversation,
+            longMessageContext,
+            error: `Conversation with ${agent.name} was cancelled.`,
+            status: 'cancelled',
+            includeMetrics,
+          });
+        }
+        return agentErrorResult({
+          agent,
+          description: taskDescription,
+          sessionId,
+          runId,
+          isNewConversation,
+          longMessageContext,
+          error: `Failed to talk to ${agent.name}: ${err.message}`,
+          includeMetrics,
+        });
+      } finally {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        activeAgentConversations.delete(sessionId);
+      }
+    };
+
+    const turnPromise = finishTurn();
+
+    if (asyncMode) {
+      turnPromise.catch((err) => {
+        appendAgentConvoLog(sessionId, {
+          role: 'error',
+          agentId: agent.id,
+          runId,
+          description: taskDescription,
+          error: err.message,
+          timestamp: new Date().toISOString(),
+        });
+        activeAgentConversations.delete(sessionId);
+      });
+      return textResult(
+        JSON.stringify(
+          responsePayload({
+            agent,
+            description: taskDescription,
+            sessionId,
+            runId,
+            status: 'running',
+            isNewConversation,
+            longMessageContext,
+            recovery:
+              'Use agents_get_conversation with this conversation_id to poll for the assistant response.',
+            includeMetrics,
+          }),
+          null,
+          2,
+        ),
+      );
+    }
+
+    if (foregroundTimeoutMs > 0) {
+      const timeoutResult = await Promise.race([
+        turnPromise.then((result) => ({ type: 'done', result })),
+        new Promise((resolve) => setTimeout(() => resolve({ type: 'timeout' }), foregroundTimeoutMs)),
+      ]);
+      if (timeoutResult.type === 'done') {
+        return timeoutResult.result;
+      }
+      notifyCallerOnCompletion = true;
+      appendStatusLog(sessionId, 'foreground_wait_timeout', {
+        agentId: agent.id,
+        agentName: agent.name,
+        runId,
+        description: taskDescription,
+        timeoutMs: foregroundTimeoutMs,
+        active: summarizeActiveConversation(sessionId),
+      });
+      updateActiveConversation(sessionId, { status: 'running' });
+      return textResult(
+        JSON.stringify(
+          responsePayload({
+            agent,
+            description: taskDescription,
+            sessionId,
+            runId,
+            status: 'timed_out',
+            isNewConversation,
+            longMessageContext,
+            recovery:
+              'The agent is still running. Use agents_get_conversation with this conversation_id/run_id to poll; a short completion notification will also be posted back to the caller session when available.',
+            includeMetrics,
+            extra: {
+              timeout_ms: foregroundTimeoutMs,
+            },
+          }),
+          null,
+          2,
+        ),
+      );
+    }
+
+    return await turnPromise;
+  } catch (err) {
+    appendAgentConvoLog(sessionId, {
+      role: 'error',
+      agentId: agent?.id || agentLookup,
+      runId,
+      description: taskDescription,
+      error: err.message,
+      timestamp: new Date().toISOString(),
+    });
+    activeAgentConversations.delete(sessionId);
+    if (err.name === 'AbortError') {
+      return agentErrorResult({
+        agent,
+        description: taskDescription,
+        sessionId,
+        runId,
+        isNewConversation,
+        longMessageContext,
+        error: `Conversation with ${agent.name} was cancelled.`,
+        status: 'cancelled',
+        includeMetrics,
+      });
+    }
+    return agentErrorResult({
+      agent,
+      description: taskDescription,
+      sessionId,
+      runId,
+      isNewConversation,
+      longMessageContext,
+      error: `Failed to talk to ${agent.name}: ${err.message}`,
+      includeMetrics,
+    });
+  }
+}
+
+module.exports = {
+  handleTalkToAgent,
+  activeAgentConversations,
+  summarizeActiveConversation,
+  MAX_INLINE_MESSAGE_CHARS,
+  DEFAULT_FOREGROUND_TIMEOUT_MS,
+};