march-cli 0.1.32 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",

package/src/agent/output/binary-output-sink.mjs

@@ -0,0 +1,17 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { openFileWithDefaultApp } from "../../platform/open-file.mjs";
+
+const sinkStorage = new AsyncLocalStorage();
+
+export function withBinaryOutputSink(sink, fn) {
+  return sinkStorage.run(sink, fn);
+}
+
+export async function sendBinaryOutput(binary, { openFile = openFileWithDefaultApp } = {}) {
+  const sink = sinkStorage.getStore();
+  if (sink?.sendBinary) return sink.sendBinary(binary);
+  if (!binary.path && !binary.url) throw new Error("send_binary requires a path or url");
+  if (binary.url) throw new Error("send_binary url output is only supported by gateway sinks");
+  await openFile(binary.path);
+  return { target: "local", opened: true };
+}

package/src/agent/output/send-binary-tool.mjs

@@ -0,0 +1,84 @@
+import { statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../tool-result.mjs";
+import { sendBinaryOutput } from "./binary-output-sink.mjs";
+
+const SUPPORTED_TYPES = new Set(["image", "video", "audio", "file"]);
+const MIME_BY_EXT = new Map([
+  [".png", "image/png"], [".jpg", "image/jpeg"], [".jpeg", "image/jpeg"], [".webp", "image/webp"], [".gif", "image/gif"],
+  [".mp4", "video/mp4"], [".mov", "video/quicktime"], [".webm", "video/webm"],
+  [".mp3", "audio/mpeg"], [".wav", "audio/wav"], [".ogg", "audio/ogg"], [".opus", "audio/ogg"],
+]);
+
+export function createSendBinaryTool({ engine, sendBinary = sendBinaryOutput } = {}) {
+  return defineTool({
+    name: "send_binary",
+    label: "Send Binary",
+    description: "Send or display an existing binary artifact. In the TUI this opens local files with the system default app; in a gateway it sends image/video/audio/file media through the platform.",
+    promptSnippet: "send_binary(type, path|url, caption?, mimeType?) - Send/display an existing image, video, audio, or file artifact.",
+    promptGuidelines: [
+      "Use send_binary when the user asks you to send, show, open, or deliver an existing media/file artifact.",
+      "Do not use send_binary to generate media; first create or locate the artifact, then send it.",
+    ],
+    parameters: Type.Object({
+      type: Type.String({ enum: [...SUPPORTED_TYPES], description: "Binary type: image, video, audio, or file" }),
+      path: Type.Optional(Type.String({ description: "Local file path, absolute or relative to the workspace" })),
+      url: Type.Optional(Type.String({ description: "Remote URL to send through gateway platforms" })),
+      caption: Type.Optional(Type.String({ description: "Optional caption to send with the media" })),
+      mimeType: Type.Optional(Type.String({ description: "Optional MIME type override" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      try {
+        const binary = normalizeBinaryOutput(params, { engine });
+        const sinkResult = await sendBinary(binary);
+        return toolJson({ success: true, ...binary, sink: sinkResult }, { binary, sink: sinkResult });
+      } catch (err) {
+        return toolJson({ success: false, error: err.message }, { error: true });
+      }
+    },
+  });
+}
+
+export function normalizeBinaryOutput(params, { engine } = {}) {
+  const type = clean(params.type);
+  if (!SUPPORTED_TYPES.has(type)) throw new Error("send_binary type must be one of: image, video, audio, file");
+  const rawPath = clean(params.path);
+  const url = clean(params.url);
+  if (rawPath && url) throw new Error("send_binary accepts either path or url, not both");
+  if (!rawPath && !url) throw new Error("send_binary requires path or url");
+
+  if (url) {
+    assertHttpUrl(url);
+    return { type, url, caption: clean(params.caption), mimeType: clean(params.mimeType) };
+  }
+
+  const path = engine?.resolvePath ? engine.resolvePath(rawPath) : rawPath;
+  const stat = statSync(path);
+  if (!stat.isFile()) throw new Error(`send_binary path is not a file: ${path}`);
+  return {
+    type,
+    path,
+    filename: basename(path),
+    caption: clean(params.caption),
+    mimeType: clean(params.mimeType) ?? MIME_BY_EXT.get(extname(path).toLowerCase()) ?? "application/octet-stream",
+    sizeBytes: stat.size,
+  };
+}
+
+function assertHttpUrl(value) {
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new Error(`send_binary url is invalid: ${value}`); }
+  if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("send_binary url must use http or https");
+}
+
+function clean(value) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  return text || null;
+}
+
+function toolJson(payload, details = {}) {
+  return toolText(JSON.stringify(payload, null, 2), details);
+}

package/src/agent/tools.mjs

@@ -3,6 +3,7 @@ import { createContextStatsTool } from "./context-stats-tool.mjs";
 import { createEditFileTool } from "./file-edit-tool.mjs";
 import { createReadFileTool } from "./file-tools/read-file-tool.mjs";
 import { createReadImageTool } from "./file-tools/read-image-tool.mjs";
+import { createSendBinaryTool } from "./output/send-binary-tool.mjs";
 import { createScreenTool } from "./screen-tools/screen-tool.mjs";
 import { createListWindowsTool } from "./screen-tools/list-windows-tool.mjs";
 import { toolText } from "./tool-result.mjs";
@@ -17,12 +18,14 @@ export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shel
   const editFileTool = createEditFileTool({ engine, ui, lspService });
   const readFileTool = createReadFileTool({ engine });
   const readImageTool = createReadImageTool({ engine, getCurrentModel });
+  const sendBinaryTool = createSendBinaryTool({ engine });
   const screenTool = createScreenTool({ getCurrentModel });
   const listWindowsTool = createListWindowsTool();
 
   const tools = [
     readFileTool,
     readImageTool,
+    sendBinaryTool,
     screenTool,
     listWindowsTool,
     contextStatsTool,

package/src/cli/args.mjs

@@ -28,7 +28,7 @@ export function parseCliArgs(argv) {
     allowPositionals: true,
   });
 
-  const commandName = ["login", "provider", "websearch", "memory", "browser"].includes(positionals[0]) ? positionals[0] : null;
+  const commandName = ["login", "provider", "websearch", "memory", "browser", "gateway"].includes(positionals[0]) ? positionals[0] : null;
 
   return {
     command: commandName ? { name: commandName, args: positionals.slice(1) } : null,
@@ -73,6 +73,8 @@ Usage:
   march browser install    Install the developer browser extension
   march browser status     Show browser daemon/extension status
   march browser restart    Restart the browser daemon
+  march gateway setup      Configure gateway interactively
+  march gateway status     Show gateway configuration status
 
 Options:
   -m, --model <id>     Initial model ID override

package/src/cli/commands/help-command.mjs

@@ -1,6 +1,6 @@
 export function formatHelpLines() {
   return [
-    "Commands: /new, /exit, /help, /hotkeys, /templates, /export jsonl, /export html, /export gist <jsonl|html>, /settings, /extensions, /providers, /providers <name>, /model, /models, /session, /status, /shell, /shell spawn [name], /save, /name, /copy",
+    "Commands: /new, /exit, /help, /hotkeys, /templates, /do, /discuss, /mode, /export jsonl, /export html, /export gist <jsonl|html>, /settings, /extensions, /providers, /providers <name>, /model, /models, /session, /status, /shell, /shell spawn [name], /save, /name, /copy",
     "Sessions: /session opens previous sessions and restores the selected one.",
     "Shortcuts: Tab = toggle Do/Discuss, Esc = abort turn, Ctrl+C = abort turn / press twice to exit when idle, Ctrl+O = toggle tool output, Alt+S = shell pane, Alt+N = next shell, Alt+K/J = shell scroll, PageUp/PageDown = output scroll, Ctrl+G = external editor, Shift+Tab = thinking selector, Ctrl+T = thinking selector, Ctrl+L = model selector",
   ];

package/src/cli/commands/mode-command.mjs

@@ -0,0 +1,21 @@
+import { MODES, formatModeLabel } from "../input/mode-state.mjs";
+
+export function parseModeCommand(input) {
+  const trimmed = String(input ?? "").trim();
+  if (trimmed === "/mode") return { type: "show" };
+  if (trimmed === "/do") return { type: "set", mode: MODES.DO };
+  if (trimmed === "/discuss") return { type: "set", mode: MODES.DISCUSS };
+  return { type: "none" };
+}
+
+export function handleModeCommand(command, { modeState } = {}) {
+  if (!modeState || typeof modeState.get !== "function") {
+    return ["Mode switching is unavailable in this runtime."];
+  }
+
+  if (command.type === "set") {
+    modeState.set(command.mode);
+  }
+
+  return [`Mode: ${formatModeLabel(modeState.get())}`];
+}

package/src/cli/repl-loop.mjs

@@ -87,6 +87,7 @@ export async function runInteractiveRepl({
       keybindingDiagnostics: keybindingConfig.diagnostics,
       promptTemplates: promptTemplateConfig.templates,
       promptTemplateDiagnostics: promptTemplateConfig.diagnostics,
+      modeState,
       renderStartupBanner,
       configHomeDir,
     });

package/src/cli/slash-commands.mjs

@@ -11,6 +11,7 @@ import { handleSettingsCommand, parseSettingsCommand } from "../config/settings-
 import { handleSessionNameCommand, parseSessionNameCommand } from "./session/session-name-command.mjs";
 import { handleShellCommand, parseShellCommand } from "./shell/shell-command.mjs";
 import { handleProviderCommand, parseProviderCommand } from "./commands/provider-command.mjs";
+import { handleModeCommand, parseModeCommand } from "./commands/mode-command.mjs";
 import { formatHelpLines } from "./commands/help-command.mjs";
 
 export async function handleSlashCommand(trimmed, {
@@ -25,6 +26,7 @@ export async function handleSlashCommand(trimmed, {
   keybindingDiagnostics = [],
   promptTemplates = [],
   promptTemplateDiagnostics = [],
+  modeState = null,
   renderStartupBanner = null,
   settingsHomeDir,
   configHomeDir = settingsHomeDir,
@@ -66,6 +68,12 @@ export async function handleSlashCommand(trimmed, {
     return { handled: true };
   }
 
+  const modeCommand = parseModeCommand(trimmed);
+  if (modeCommand.type !== "none") {
+    for (const line of handleModeCommand(modeCommand, { modeState })) ui.writeln(line);
+    return { handled: true };
+  }
+
   if (trimmed === "/hotkeys") {
     for (const line of formatHotkeysPanel(keybindings, keybindingDiagnostics)) ui.writeln(line);
     return { handled: true };

package/src/cli/startup/configured-command.mjs

@@ -0,0 +1,17 @@
+import { runBrowserCommand } from "../../browser/cli/command.mjs";
+import { runGatewayCommand } from "../../gateway/command.mjs";
+
+export async function runConfiguredCliCommand(args, { config, cwd, stateRoot }) {
+  if (args.command?.name === "browser") {
+    try {
+      return { handled: true, code: await runBrowserCommand(args, { stateRoot }) };
+    } catch (err) {
+      process.stderr.write(`Error: ${err.message}\n`);
+      return { handled: true, code: 1 };
+    }
+  }
+  if (args.command?.name === "gateway" && args.command.args?.[0] !== "run") {
+    return { handled: true, code: await runGatewayCommand(args, { config, cwd }) };
+  }
+  return { handled: false, code: null };
+}

package/src/cli/startup/gateway-daemon-command.mjs

@@ -0,0 +1,21 @@
+import { runGatewayCommand } from "../../gateway/command.mjs";
+import { createGatewayRunnerBridge } from "../../gateway/runner-bridge.mjs";
+import { closeMarchRuntime } from "./runtime-close.mjs";
+
+export async function maybeRunGatewayDaemonCommand(args, {
+  config,
+  cwd,
+  runner,
+  currentProject,
+  memoryStore,
+  ui,
+  logger,
+} = {}) {
+  if (args.command?.name !== "gateway" || args.command.args?.[0] !== "run") return { handled: false, code: null };
+  const bridge = createGatewayRunnerBridge({ runner, cwd });
+  try {
+    return { handled: true, code: await runGatewayCommand(args, { config, cwd, getRunner: bridge.getRunner, currentProject }) };
+  } finally {
+    await closeMarchRuntime({ runner, memoryStore, ui, logger });
+  }
+}

package/src/config/loader.mjs

@@ -59,6 +59,7 @@ function mergeLayers(layers) {
     trimBatch: null,
     memoryRoot: null,
     notifications: { turnEnd: true, desktop: true, bell: false, command: null, minDurationMs: 0, sound: true },
+    gateway: { enabled: false, defaultWorkspace: null, workspaces: {}, platforms: {} },
     remoteMemories: [],
   };
   for (const layer of layers) {
@@ -88,6 +89,9 @@ function mergeLayers(layers) {
       };
     }
     if (layer.memoryRoot) result.memoryRoot = layer.memoryRoot;
+    if (layer.gateway && typeof layer.gateway === "object" && !Array.isArray(layer.gateway)) {
+      result.gateway = mergeGateway(result.gateway, layer.gateway);
+    }
     if (Array.isArray(layer.remoteMemories)) result.remoteMemories = mergeRemoteMemories(result.remoteMemories, layer.remoteMemories);
   }
   return result;
@@ -127,6 +131,33 @@ function mergeHostedTools(current, next) {
   return merged;
 }
 
+function mergeGateway(current, next) {
+  const merged = {
+    ...current,
+    workspaces: { ...(current.workspaces ?? {}) },
+    platforms: { ...(current.platforms ?? {}) },
+  };
+  if (typeof next.enabled === "boolean") merged.enabled = next.enabled;
+  if (next.defaultWorkspace != null) merged.defaultWorkspace = next.defaultWorkspace;
+  if (next.default_workspace != null) merged.defaultWorkspace = next.default_workspace;
+  if (next.workspaces && typeof next.workspaces === "object" && !Array.isArray(next.workspaces)) {
+    merged.workspaces = { ...merged.workspaces, ...next.workspaces };
+  }
+  if (next.platforms && typeof next.platforms === "object" && !Array.isArray(next.platforms)) {
+    merged.platforms = mergeGatewayPlatforms(merged.platforms, next.platforms);
+  }
+  return merged;
+}
+
+function mergeGatewayPlatforms(current, next) {
+  const merged = { ...current };
+  for (const [id, profile] of Object.entries(next)) {
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) continue;
+    merged[id] = { ...(merged[id] ?? {}), ...profile };
+  }
+  return merged;
+}
+
 function mergeProviders(current, next) {
   const merged = { ...current };
   for (const [id, profile] of Object.entries(next)) {

package/src/gateway/command-router.mjs

@@ -0,0 +1,44 @@
+import { handleSlashCommand } from "../cli/slash-commands.mjs";
+import { parseWorkspaceCommand, handleWorkspaceCommand } from "./workspace-command.mjs";
+
+export async function handleGatewaySlashCommand(input, {
+  runner,
+  session,
+  sessionStore,
+  slashCommandHandler = handleSlashCommand,
+} = {}) {
+  const trimmed = String(input ?? "").trim();
+  if (!trimmed.startsWith("/")) return { handled: false, lines: [] };
+
+  const workspaceCommand = parseWorkspaceCommand(trimmed);
+  if (workspaceCommand.type !== "none") {
+    return {
+      handled: true,
+      lines: handleWorkspaceCommand(workspaceCommand, { session, sessionStore }),
+    };
+  }
+
+  const ui = createCollectingUi();
+  const result = await slashCommandHandler(trimmed, {
+    ui,
+    runner,
+    modeState: session.modeState,
+    sessionState: { sessionId: session.marchSessionId },
+    sessionSource: "gateway",
+  });
+
+  return {
+    ...result,
+    handled: Boolean(result?.handled),
+    lines: ui.lines,
+  };
+}
+
+function createCollectingUi() {
+  const lines = [];
+  return {
+    lines,
+    writeln(line = "") { lines.push(String(line)); },
+    clearOutput() {},
+  };
+}

package/src/gateway/command.mjs

@@ -0,0 +1,107 @@
+import { normalizeGatewayConfig } from "./config.mjs";
+import { runGatewayDaemon } from "./daemon.mjs";
+import { createDefaultGatewayPlatformRegistry } from "./platform-registry.mjs";
+import { runGatewaySetupCommand } from "./setup/command.mjs";
+
+export async function runGatewayCommand(args, {
+  config,
+  cwd = process.cwd(),
+  input = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  platformRegistry = createDefaultGatewayPlatformRegistry(),
+  getRunner,
+  currentProject = "",
+} = {}) {
+  const [subcommand = "status", ...rest] = args.command?.args ?? [];
+  const gatewayConfig = normalizeGatewayConfig(config, { cwd });
+
+  if (subcommand === "setup") {
+    return await runGatewaySetupCommand({ cwd, input, output: stdout });
+  }
+  if (subcommand === "status") {
+    writeLines(stdout, formatGatewayStatus(gatewayConfig, platformRegistry));
+    return 0;
+  }
+  if (subcommand === "workspaces") {
+    writeLines(stdout, formatGatewayWorkspaces(gatewayConfig));
+    return 0;
+  }
+  if (subcommand === "platforms") {
+    writeLines(stdout, formatGatewayPlatforms(gatewayConfig, platformRegistry));
+    return 0;
+  }
+  if (subcommand === "run") {
+    const platform = rest[0] ?? firstEnabledPlatform(gatewayConfig);
+    if (!platform) {
+      stderr.write("Error: no gateway platform configured.\n");
+      return 1;
+    }
+    if (gatewayConfig.platforms[platform]?.enabled !== true) {
+      stderr.write(`Error: gateway platform '${platform}' is not enabled in config.\n`);
+      return 1;
+    }
+    if (!platformRegistry.has(platform)) {
+      stderr.write(`Error: gateway platform '${platform}' is not implemented in this build.\n`);
+      return 1;
+    }
+    if (typeof getRunner !== "function") {
+      stderr.write("Error: gateway runner bridge is not wired for this command path yet.\n");
+      return 1;
+    }
+    await runGatewayDaemon({ platform, platformRegistry, gatewayConfig, getRunner, currentProject });
+    return 0;
+  }
+
+
+  stderr.write("Usage: march gateway [setup|status|workspaces|platforms|run [platform]]\n");
+  return 1;
+}
+
+function formatGatewayStatus(gatewayConfig, platformRegistry) {
+  return [
+    `Gateway: ${gatewayConfig.enabled ? "enabled" : "disabled"}`,
+    `Default workspace: ${gatewayConfig.defaultWorkspace ?? "not configured"}`,
+    `Configured workspaces: ${Object.keys(gatewayConfig.workspaces).length}`,
+    `Configured platforms: ${Object.keys(gatewayConfig.platforms).length}`,
+    `Implemented platforms: ${platformRegistry.list().join(", ") || "none"}`,
+    ...formatDiagnostics(gatewayConfig.diagnostics),
+  ];
+}
+
+function formatGatewayWorkspaces(gatewayConfig) {
+  const workspaces = Object.values(gatewayConfig.workspaces);
+  if (workspaces.length === 0) return ["No gateway workspaces configured."];
+  return [
+    "Gateway workspaces:",
+    ...workspaces.map((workspace) => {
+      const marker = workspace.alias === gatewayConfig.defaultWorkspace ? "*" : " ";
+      return `${marker} ${workspace.alias}: ${workspace.root}`;
+    }),
+  ];
+}
+
+function formatGatewayPlatforms(gatewayConfig, platformRegistry) {
+  const platformIds = Object.keys(gatewayConfig.platforms).sort();
+  if (platformIds.length === 0) return ["No gateway platforms configured."];
+  return [
+    "Gateway platforms:",
+    ...platformIds.map((id) => {
+      const enabled = gatewayConfig.platforms[id]?.enabled === true ? "enabled" : "disabled";
+      const implemented = platformRegistry.has(id) ? "implemented" : "not implemented";
+      return `- ${id}: ${enabled}, ${implemented}`;
+    }),
+  ];
+}
+
+function firstEnabledPlatform(gatewayConfig) {
+  return Object.entries(gatewayConfig.platforms).find(([, value]) => value?.enabled === true)?.[0] ?? null;
+}
+
+function formatDiagnostics(diagnostics = []) {
+  return diagnostics.map((entry) => `${entry.type}: ${entry.message}`);
+}
+
+function writeLines(stream, lines) {
+  for (const line of lines) stream.write(`${line}\n`);
+}

package/src/gateway/config.mjs

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+
+export function normalizeGatewayConfig(config = {}, { cwd = process.cwd() } = {}) {
+  const raw = config.gateway && typeof config.gateway === "object" && !Array.isArray(config.gateway)
+    ? config.gateway
+    : {};
+  const diagnostics = [];
+  const workspaces = normalizeWorkspaces(raw.workspaces, { cwd, diagnostics });
+  const defaultWorkspace = raw.defaultWorkspace ?? raw.default_workspace ?? null;
+  const defaultWorkspaceAlias = resolveDefaultWorkspace(defaultWorkspace, { cwd, workspaces, diagnostics });
+
+  return {
+    enabled: raw.enabled === true,
+    defaultWorkspace: defaultWorkspaceAlias,
+    workspaces,
+    platforms: raw.platforms && typeof raw.platforms === "object" && !Array.isArray(raw.platforms) ? { ...raw.platforms } : {},
+    diagnostics,
+  };
+}
+
+export function resolveGatewayWorkspace(gatewayConfig, alias = null) {
+  const workspaceAlias = alias ?? gatewayConfig?.defaultWorkspace ?? null;
+  if (!workspaceAlias) return null;
+  return gatewayConfig?.workspaces?.[workspaceAlias] ?? null;
+}
+
+function normalizeWorkspaces(rawWorkspaces, { cwd, diagnostics }) {
+  const workspaces = {};
+  if (!rawWorkspaces || typeof rawWorkspaces !== "object" || Array.isArray(rawWorkspaces)) return workspaces;
+  for (const [alias, value] of Object.entries(rawWorkspaces)) {
+    const cleanAlias = normalizeAlias(alias);
+    if (!cleanAlias) {
+      diagnostics.push({ type: "warning", message: `Ignored gateway workspace with invalid alias: ${alias}` });
+      continue;
+    }
+    const root = typeof value === "string" ? value : value?.root;
+    if (typeof root !== "string" || root.trim() === "") {
+      diagnostics.push({ type: "warning", message: `Ignored gateway workspace without root: ${alias}` });
+      continue;
+    }
+    workspaces[cleanAlias] = { alias: cleanAlias, root: resolve(cwd, root) };
+  }
+  return workspaces;
+}
+
+function resolveDefaultWorkspace(defaultWorkspace, { cwd, workspaces, diagnostics }) {
+  if (typeof defaultWorkspace !== "string" || defaultWorkspace.trim() === "") return null;
+  const value = defaultWorkspace.trim();
+  const alias = normalizeAlias(value);
+  if (alias && workspaces[alias]) return alias;
+
+  // Explicit default paths are accepted, but future /workspace set remains alias-only.
+  const defaultAlias = "default";
+  workspaces[defaultAlias] = { alias: defaultAlias, root: resolve(cwd, value) };
+  diagnostics.push({ type: "info", message: "Gateway defaultWorkspace used an explicit path; registered it as workspace alias 'default'." });
+  return defaultAlias;
+}
+
+function normalizeAlias(alias) {
+  const value = String(alias ?? "").trim();
+  return /^[a-zA-Z0-9_-]+$/.test(value) ? value : null;
+}

package/src/gateway/daemon.mjs

@@ -0,0 +1,41 @@
+import { createGatewayMessageHandler } from "./handler.mjs";
+import { createGatewayMessageQueue } from "./runtime/queue.mjs";
+import { GatewaySessionStore } from "./session-store.mjs";
+
+export async function runGatewayDaemon({
+  platform,
+  platformRegistry,
+  gatewayConfig,
+  getRunner,
+  currentProject = "",
+  signal,
+  logger = console,
+} = {}) {
+  if (!platform) throw new Error("Gateway daemon requires a platform id");
+  if (!platformRegistry) throw new Error("Gateway daemon requires a platform registry");
+  if (typeof getRunner !== "function") throw new Error("Gateway daemon requires a runner factory");
+
+  const platformConfig = gatewayConfig?.platforms?.[platform] ?? {};
+  const adapter = platformRegistry.create(platform, { config: platformConfig });
+  if (typeof adapter.send !== "function") throw new Error(`Gateway platform '${platform}' requires a send function`);
+  if (typeof adapter.sendBinary !== "function") throw new Error(`Gateway platform '${platform}' requires a sendBinary function`);
+  const sessionStore = new GatewaySessionStore({ gatewayConfig });
+  const handleMessage = createGatewayMessageHandler({
+    sessionStore,
+    getRunner,
+    currentProject,
+    outputSinkForMessage: (message) => ({
+      sendBinary: (binary) => adapter.sendBinary({ chatId: message.chatId, binary, replyToMessageId: message.messageId }),
+    }),
+  });
+  const queue = createGatewayMessageQueue({
+    handleMessage,
+    logger,
+    send: async (message, result) => {
+      await adapter.send({ chatId: message.chatId, lines: result?.lines ?? [], replyToMessageId: message.messageId });
+    },
+  });
+
+  logger.info?.(`[gateway] starting ${platform}`);
+  await adapter.start({ handleMessage: (message) => queue.enqueue(message), signal });
+}

package/src/gateway/handler.mjs

@@ -0,0 +1,29 @@
+import { appendModeReminder } from "../cli/input/mode-state.mjs";
+import { withBinaryOutputSink } from "../agent/output/binary-output-sink.mjs";
+import { normalizeGatewayMessage } from "./message.mjs";
+import { handleGatewaySlashCommand } from "./command-router.mjs";
+
+export function createGatewayMessageHandler({ sessionStore, getRunner, currentProject = "", outputSinkForMessage = null }) {
+  return async function handleGatewayMessage(input) {
+    const message = normalizeGatewayMessage(input);
+    const session = sessionStore.getOrCreate(message);
+    const runner = await getRunner(session);
+
+    if (message.text.startsWith("/")) {
+      const commandResult = await handleGatewaySlashCommand(message.text, { runner, session, sessionStore });
+      if (commandResult.handled) {
+        return { type: "command", session, lines: commandResult.lines };
+      }
+    }
+
+    if (!session.workspaceRoot) {
+      return { type: "error", session, lines: ["Error: no gateway workspace configured for this chat."] };
+    }
+
+    const prompt = appendModeReminder(message.text, session.modeState.get());
+    const sink = outputSinkForMessage?.(message, session);
+    const runTurn = () => runner.runTurn(prompt, message.text, { currentProject });
+    const result = sink ? await withBinaryOutputSink(sink, runTurn) : await runTurn();
+    return { type: "turn", session, result, lines: result?.draft ? [result.draft] : [] };
+  };
+}

package/src/gateway/message.mjs

@@ -0,0 +1,37 @@
+export function normalizeGatewayMessage(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Gateway message must be an object");
+  }
+  const platform = cleanRequiredString(input.platform, "platform");
+  const chatId = cleanRequiredString(input.chatId ?? input.chat_id, "chatId");
+  const userId = cleanRequiredString(input.userId ?? input.user_id, "userId");
+  const text = typeof input.text === "string" ? input.text.trim() : "";
+  if (!text) throw new Error("Gateway message text is required");
+
+  return {
+    platform,
+    chatId,
+    userId,
+    threadId: cleanOptionalString(input.threadId ?? input.thread_id),
+    messageId: cleanOptionalString(input.messageId ?? input.message_id),
+    text,
+    receivedAt: input.receivedAt ?? input.received_at ?? new Date().toISOString(),
+  };
+}
+
+export function gatewaySessionKey(message) {
+  const thread = message.threadId ? `:thread:${message.threadId}` : "";
+  return `${message.platform}:chat:${message.chatId}${thread}`;
+}
+
+function cleanRequiredString(value, field) {
+  const clean = cleanOptionalString(value);
+  if (!clean) throw new Error(`Gateway message ${field} is required`);
+  return clean;
+}
+
+function cleanOptionalString(value) {
+  if (value == null) return null;
+  const clean = String(value).trim();
+  return clean || null;
+}