amalgm 0.0.0 → 0.0.1

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

@@ -0,0 +1,210 @@
+/**
+ * Agents MCP tools: agents_list, agents_get, talk_to_agent.
+ */
+
+const { textResult, errorResult } = require('../lib/tool-result');
+const {
+  getAllAgentsWithBuiltins,
+  normalizeConversationId,
+  readAgentConvoLog,
+  resolveAgent,
+} = require('./store');
+const { getSelectedModel, DEFAULT_SELECTED_MODELS } = require('../lib/prefs');
+const {
+  handleTalkToAgent,
+  summarizeActiveConversation,
+  MAX_INLINE_MESSAGE_CHARS,
+  DEFAULT_FOREGROUND_TIMEOUT_MS,
+} = require('./talk');
+
+const talkMessageSchema = { type: 'string' };
+const talkSizeNote = MAX_INLINE_MESSAGE_CHARS > 0
+  ? ` Messages over ${MAX_INLINE_MESSAGE_CHARS} characters are stored as local context files and sent to the target agent as file references to avoid opaque transport timeouts.`
+  : '';
+
+module.exports = [
+  {
+    name: 'agents_list',
+    description:
+      'List all available agents (built-in defaults + custom user-created agents). Use this to discover which agents you can talk to via talk_to_agent.',
+    inputSchema: { type: 'object', properties: {} },
+    async handler() {
+      const all = getAllAgentsWithBuiltins();
+      if (all.length === 0) return textResult('No agents available.');
+      const summary = all
+        .map((a) => {
+          const tag = a.builtin ? '[built-in]' : '[custom]';
+          const model = a.builtin
+            ? getSelectedModel(a.baseHarnessId) || a.baseModelId
+            : a.baseModelId ||
+              getSelectedModel(a.baseHarnessId) ||
+              DEFAULT_SELECTED_MODELS[a.baseHarnessId];
+          return `- ${a.name} (${a.id}) ${tag}\n  ${a.description || 'No description'}\n  harness: ${a.baseHarnessId} | model: ${model}`;
+        })
+        .join('\n\n');
+      return textResult(`Available agents:\n\n${summary}`);
+    },
+  },
+  {
+    name: 'agents_get',
+    description:
+      'Get detailed information about a specific agent by ID, including its description, base harness, model, and capabilities.',
+    inputSchema: {
+      type: 'object',
+      properties: { agent_id: { type: 'string' } },
+      required: ['agent_id'],
+    },
+    async handler({ agent_id }) {
+      const agent = resolveAgent(agent_id);
+      if (!agent) return errorResult(`Agent not found: ${agent_id}`);
+      const safe = {
+        id: agent.id,
+        name: agent.name,
+        description: agent.description,
+        baseHarnessId: agent.baseHarnessId,
+        baseModelId: agent.builtin
+          ? getSelectedModel(agent.baseHarnessId) || agent.baseModelId
+          : agent.baseModelId ||
+            getSelectedModel(agent.baseHarnessId) ||
+            DEFAULT_SELECTED_MODELS[agent.baseHarnessId],
+        systemPrompt: agent.systemPrompt ? '(configured)' : '(none)',
+        mcp: {
+          inheritAll: agent.mcp?.inheritAll ?? true,
+          customServerCount: agent.mcp?.customServers?.length ?? 0,
+        },
+        builtin: !!agent.builtin,
+      };
+      return textResult(JSON.stringify(safe, null, 2));
+    },
+  },
+  {
+    name: 'agents_get_conversation',
+    description:
+      'Read the local transcript for an agent conversation by conversation_id. Use this to recover the response if talk_to_agent timed out after the target agent completed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        conversation_id: { type: 'string', description: 'Stable talk_to_agent conversation_id. Preferred over session_id.' },
+        session_id: { type: 'string', description: 'Deprecated alias for conversation_id.' },
+        run_id: { type: 'string', description: 'Optional run_id to filter the transcript.' },
+        limit: { type: 'number', description: 'Maximum transcript entries to return (default: 20).' },
+        include_events: { type: 'boolean', description: 'Include raw status/tool lifecycle events. Defaults to false for a clean user/assistant transcript.' },
+      },
+    },
+    async handler({ conversation_id, session_id, run_id, limit, include_events }) {
+      const conversationId = normalizeConversationId(conversation_id || session_id);
+      if (!conversationId) return errorResult('conversation_id is required and must be a UUID');
+      const requestedLimit = Math.max(1, Number(limit) || 20);
+      const rawEvents = include_events === true || String(include_events || '').toLowerCase() === 'true';
+      const readLimit = rawEvents ? requestedLimit : Math.max(requestedLimit * 4, 50);
+      let entries = readAgentConvoLog(conversationId, readLimit);
+      if (run_id) entries = entries.filter((entry) => entry.runId === run_id);
+      const active = summarizeActiveConversation(conversationId);
+      if (!rawEvents) {
+        entries = entries
+          .filter((entry) => entry.role === 'user' || entry.role === 'assistant')
+          .map((entry) => ({
+            role: entry.role,
+            agent: entry.agentName || entry.agentId || null,
+            conversation_id: conversationId,
+            run_id: entry.runId || null,
+            description: entry.description || null,
+            message: entry.message || '',
+            timestamp: entry.timestamp || null,
+            ...(entry.stopReason ? { stop_reason: entry.stopReason } : {}),
+            ...(Array.isArray(entry.warnings) && entry.warnings.length ? { warnings: entry.warnings } : {}),
+          }))
+          .slice(-requestedLimit);
+        if (active && (!run_id || active.runId === run_id) && active.responsePreview) {
+          entries = [
+            ...entries,
+            {
+              role: 'assistant',
+              agent: active.agentName || active.agentId || null,
+              conversation_id: conversationId,
+              run_id: active.runId || null,
+              description: active.description || null,
+              message: active.responsePreview,
+              timestamp: active.lastEventAt || active.updatedAt || null,
+              streaming: true,
+              chars: active.responsePreviewChars || active.responsePreview.length,
+            },
+          ].slice(-requestedLimit);
+        }
+      }
+      return textResult(JSON.stringify({
+        conversation_id: conversationId,
+        session_id: conversationId,
+        run_id: run_id || null,
+        view: rawEvents ? 'raw' : 'messages',
+        active: active && (!run_id || active.runId === run_id) ? active : null,
+        entries,
+      }, null, 2));
+    },
+  },
+  {
+    name: 'talk_to_agent',
+    description:
+      `Delegate a task to another Amalgm agent. IMPORTANT: for code review, implementation, research, file inspection, tests, or anything that may take more than a few seconds, set run_in_background=true so the tool returns a stable conversation_id immediately instead of risking MCP transport timeout. Foreground mode is only for quick questions: it waits up to ${DEFAULT_FOREGROUND_TIMEOUT_MS}ms, then returns conversation_id/run_id with status timed_out while the peer keeps running. Background mode returns conversation_id/run_id immediately. When a peer is given a return channel, it should call this same tool with response_to_caller=true to deliver its own compact response back to the caller conversation; the bridge posts only a short fallback if the peer does not deliver one. Use conversation_id to continue a multi-turn peer conversation.${talkSizeNote} Poll agents_get_conversation for clean transcript text or raw events; while the peer is still running, the clean transcript includes a streaming assistant preview when visible text has arrived.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'Short 3-5 word task description.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'The task for the agent to perform.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Optional Amalgm agent name or id, e.g. Codex, OpenCode, Claude Code, QA Testing. Defaults to Codex.',
+        },
+        conversation_id: {
+          type: 'string',
+          description: 'Stable peer conversation id to continue. Preferred over session_id.',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Deprecated alias for conversation_id.',
+        },
+        run_in_background: {
+          type: 'boolean',
+          description: 'Use true for long-running peer tasks such as code review, implementation, research, file inspection, or tests. Returns conversation_id/run_id immediately while the peer keeps working.',
+        },
+        response_to_caller: {
+          type: 'boolean',
+          description: 'Peer-only delivery mode. Set true only when responding to the caller conversation named by conversation_id. This appends prompt as the peer-authored completion message and does not launch a new agent turn.',
+        },
+        timeout_ms: {
+          type: 'number',
+          description: `Foreground soft wait budget before returning status timed_out with conversation_id/run_id. Defaults to ${DEFAULT_FOREGROUND_TIMEOUT_MS}. Keep below the caller transport timeout; prefer run_in_background for long tasks.`,
+        },
+        include_metrics: {
+          type: 'boolean',
+          description: 'Include full stream metrics/toolCalls in the response. Defaults to false to avoid context bloat; metric_summary is always included.',
+        },
+        isolation: {
+          type: 'string',
+          enum: ['worktree'],
+          description: 'Optional isolation mode. worktree is accepted as a requested execution isolation hint.',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Working directory for this turn. It is advisory per turn and no longer freezes the session contract.',
+        },
+        agent_id: {
+          type: 'string',
+          description: 'Deprecated alias for agent.',
+        },
+        message: {
+          ...talkMessageSchema,
+          description: 'Deprecated alias for prompt.',
+        },
+      },
+      required: ['description', 'prompt'],
+    },
+    handler: handleTalkToAgent,
+  },
+];

package/runtime/scripts/amalgm-mcp/artifacts/advertise.js

@@ -0,0 +1,132 @@
+const {
+  COMPUTER_AUTH_FILE,
+  COMPUTER_RECORD_FILE,
+  GATEWAY_BASE_URL,
+  GATEWAY_INTERNAL_SECRET,
+  ARTIFACT_ROUTE_SYNC_INTERVAL_MS,
+} = require('../config');
+const { readJson } = require('../lib/storage');
+const { getConnectedRoutes } = require('./store');
+
+let syncQueue = Promise.resolve();
+let routeSyncTimer = null;
+let lastFailure = '';
+const warned = new Set();
+
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
+
+function loadComputerRecord() {
+  const record = readJson(COMPUTER_RECORD_FILE, null);
+  if (!record || typeof record !== 'object') return null;
+  const auth = readJson(COMPUTER_AUTH_FILE, null);
+  if (!auth || typeof auth !== 'object') return record;
+  if (auth.computer_id && record.computer_id && auth.computer_id !== record.computer_id) return record;
+  return {
+    ...record,
+    tunnel_token: record.tunnel_token || auth.tunnel?.token || '',
+  };
+}
+
+async function postArtifactRoutes(computerId, routes, authHeaders) {
+  const response = await fetch(
+    `${GATEWAY_BASE_URL}/internal/computers/${encodeURIComponent(computerId)}/artifact-routes`,
+    {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...authHeaders,
+      },
+      body: JSON.stringify({ routes }),
+    },
+  );
+
+  if (response.ok) {
+    lastFailure = '';
+    return response.json().catch(() => ({ ok: true, routesCount: routes.length }));
+  }
+
+  const text = await response.text().catch(() => '');
+  throw new Error(`Gateway route sync failed (${response.status}): ${text.slice(0, 300)}`);
+}
+
+function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
+  const { throwOnError = false } = options;
+
+  syncQueue = syncQueue
+    .catch(() => undefined)
+    .then(async () => {
+      const record = loadComputerRecord();
+      const computerId =
+        typeof record?.computer_id === 'string' && record.computer_id.trim()
+          ? record.computer_id.trim()
+          : null;
+      if (!computerId) {
+        warnOnce(
+          'missing-computer',
+          `[AmalgmMCP] Skipping artifact route sync: missing computer_id in ${COMPUTER_RECORD_FILE}.`,
+        );
+        return { ok: false, skipped: 'missing-computer' };
+      }
+
+      const tunnelToken =
+        typeof record?.tunnel_token === 'string' && record.tunnel_token.trim()
+          ? record.tunnel_token.trim()
+          : '';
+      const authHeaders = tunnelToken
+        ? { 'x-tunnel-token': tunnelToken }
+        : (GATEWAY_INTERNAL_SECRET ? { 'x-admin-secret': GATEWAY_INTERNAL_SECRET } : null);
+      if (!authHeaders) {
+        warnOnce(
+          'missing-auth',
+          '[AmalgmMCP] Skipping artifact route sync: neither tunnel_token nor AMALGM_GATEWAY_INTERNAL_SECRET is configured.',
+        );
+        return { ok: false, skipped: 'missing-auth' };
+      }
+
+      const routes = getConnectedRoutes();
+
+      try {
+        const payload = await postArtifactRoutes(computerId, routes, authHeaders);
+        if (reason !== 'interval') {
+          console.log(
+            `[AmalgmMCP] Synced artifact routes (${reason}): computer=${computerId} count=${routes.length}`,
+          );
+        }
+        return { ok: true, computerId, routes, payload };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message !== lastFailure || reason !== 'interval') {
+          console.warn(`[AmalgmMCP] Artifact route sync failed (${reason}): ${message}`);
+        }
+        lastFailure = message;
+        if (throwOnError) throw err;
+        return { ok: false, error: message };
+      }
+    });
+
+  return syncQueue;
+}
+
+function startArtifactRouteSyncLoop() {
+  if (routeSyncTimer) return routeSyncTimer;
+
+  void syncArtifactRoutesToGateway('boot');
+  routeSyncTimer = setInterval(() => {
+    void syncArtifactRoutesToGateway('interval');
+  }, ARTIFACT_ROUTE_SYNC_INTERVAL_MS);
+
+  if (typeof routeSyncTimer.unref === 'function') {
+    routeSyncTimer.unref();
+  }
+
+  return routeSyncTimer;
+}
+
+module.exports = {
+  startArtifactRouteSyncLoop,
+  syncArtifactRoutesToGateway,
+};

package/runtime/scripts/amalgm-mcp/artifacts/rest.js

@@ -0,0 +1,103 @@
+/**
+ * /artifacts/* REST routes for the Next.js API and local tunnel runtime.
+ */
+
+const { getConnectedRoutes, loadArtifacts } = require('./store');
+const {
+  deleteArtifact,
+  connectDns,
+  disconnectDns,
+  redeployArtifact,
+  registerArtifact,
+  startArtifact,
+  stopArtifact,
+} = require('./supervisor');
+
+async function handleList(sendJson) {
+  sendJson(200, loadArtifacts());
+}
+
+async function handleRoutes(sendJson) {
+  sendJson(200, { routes: getConnectedRoutes() });
+}
+
+async function handleRegister(body, sendJson) {
+  try {
+    const artifact = await registerArtifact(body || {});
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleRedeploy(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await redeployArtifact(body.artifact_id, body);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleStart(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await startArtifact(body.artifact_id);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleStop(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await stopArtifact(body.artifact_id);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleDelete(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await deleteArtifact(body.artifact_id);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleConnectDns(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await connectDns(body.artifact_id);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleDisconnectDns(body, sendJson) {
+  try {
+    if (!body?.artifact_id) return sendJson(400, { error: 'artifact_id is required' });
+    const artifact = await disconnectDns(body.artifact_id);
+    sendJson(200, { artifact });
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+module.exports = {
+  handleConnectDns,
+  handleDelete,
+  handleDisconnectDns,
+  handleList,
+  handleRedeploy,
+  handleRegister,
+  handleRoutes,
+  handleStart,
+  handleStop,
+};

package/runtime/scripts/amalgm-mcp/artifacts/store.js

@@ -0,0 +1,141 @@
+/**
+ * Artifact storage — ~/.amalgm/artifacts.json
+ *
+ * This is intentionally local-first. The laptop volume is the source of truth;
+ * the public gateway only gets ephemeral route advertisements while the
+ * computer is connected.
+ */
+
+const crypto = require('crypto');
+const {
+  ARTIFACTS_DIR,
+  ARTIFACTS_FILE,
+  ARTIFACTS_DOMAIN,
+  ARTIFACT_PORT_MIN,
+  ARTIFACT_PORT_MAX,
+} = require('../config');
+const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+
+function ensureArtifactsDirs() {
+  ensureDir(ARTIFACTS_DIR);
+  if (!readJson(ARTIFACTS_FILE, null)) {
+    writeJsonAtomic(ARTIFACTS_FILE, { version: 1, artifacts: [] });
+  }
+}
+
+function publicUrlForRef(artifactRef) {
+  return `https://${artifactRef}.${ARTIFACTS_DOMAIN}/`;
+}
+
+function genArtifactRef() {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  const bytes = crypto.randomBytes(12);
+  let out = '';
+  for (let i = 0; i < 12; i += 1) {
+    out += chars[bytes[i] % chars.length];
+  }
+  return out;
+}
+
+function normalizeArtifact(artifact) {
+  const artifactRef = artifact.artifactRef || artifact.artifact_ref || genArtifactRef();
+  const dnsConnected =
+    artifact.dnsConnected !== undefined
+      ? artifact.dnsConnected !== false
+      : artifact.connected !== false;
+
+  return {
+    ...artifact,
+    kind: 'artifact',
+    artifactRef,
+    artifact_ref: artifactRef,
+    publicUrl: artifact.publicUrl || publicUrlForRef(artifactRef),
+    dnsConnected,
+    autostart: artifact.autostart !== false,
+    keepAlive: artifact.keepAlive !== false,
+    desiredState: artifact.desiredState || (artifact.status === 'stopped' ? 'stopped' : 'running'),
+    status: artifact.status || 'stopped',
+    pid: artifact.pid || null,
+    error: artifact.error || null,
+  };
+}
+
+function loadArtifacts() {
+  const data = readJson(ARTIFACTS_FILE, { version: 1, artifacts: [] });
+  const artifacts = Array.isArray(data.artifacts) ? data.artifacts.map(normalizeArtifact) : [];
+  return { version: 1, artifacts };
+}
+
+function saveArtifacts(data) {
+  ensureDir(ARTIFACTS_DIR);
+  writeJsonAtomic(ARTIFACTS_FILE, {
+    version: 1,
+    artifacts: Array.isArray(data.artifacts) ? data.artifacts.map(normalizeArtifact) : [],
+  });
+}
+
+function updateArtifactMeta(artifactId, updates) {
+  const data = loadArtifacts();
+  const artifact = data.artifacts.find((item) => item.id === artifactId);
+  if (!artifact) return null;
+  Object.assign(artifact, updates, { updatedAt: new Date().toISOString() });
+  saveArtifacts(data);
+  return normalizeArtifact(artifact);
+}
+
+function getArtifact(artifactId) {
+  return loadArtifacts().artifacts.find((artifact) => artifact.id === artifactId) || null;
+}
+
+function allocatePort(preferredPort) {
+  if (preferredPort !== undefined && preferredPort !== null) {
+    const parsed = Number(preferredPort);
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) return parsed;
+    return null;
+  }
+
+  const used = new Set(loadArtifacts().artifacts.map((artifact) => Number(artifact.port)));
+  for (let port = ARTIFACT_PORT_MIN; port <= ARTIFACT_PORT_MAX; port += 1) {
+    if (!used.has(port)) return port;
+  }
+  return null;
+}
+
+function allocateUniqueArtifactRef() {
+  const used = new Set(loadArtifacts().artifacts.map((artifact) => artifact.artifactRef));
+  for (let attempt = 0; attempt < 12; attempt += 1) {
+    const candidate = genArtifactRef();
+    if (!used.has(candidate)) return candidate;
+  }
+  throw new Error('Could not allocate artifact DNS ref');
+}
+
+function getConnectedRoutes() {
+  return loadArtifacts()
+    .artifacts
+    .filter((artifact) =>
+      artifact.dnsConnected
+      && artifact.desiredState === 'running'
+      && artifact.status !== 'stopped'
+      && artifact.status !== 'error'
+      && artifact.port
+      && artifact.artifactRef,
+    )
+    .map((artifact) => ({
+      artifact_ref: artifact.artifactRef,
+      port: artifact.port,
+      name: artifact.name,
+    }));
+}
+
+module.exports = {
+  allocatePort,
+  allocateUniqueArtifactRef,
+  ensureArtifactsDirs,
+  getArtifact,
+  getConnectedRoutes,
+  loadArtifacts,
+  publicUrlForRef,
+  saveArtifacts,
+  updateArtifactMeta,
+};