@volter/supercode-orchestrator 0.4.4

package/mcp/hermes-tools.json

@@ -0,0 +1,288 @@
+[
+  {
+    "name": "cronjob",
+    "description": "Manage scheduled cron jobs: action='create' schedules a job from a prompt and/or skills; 'list' inspects jobs; 'update'/'pause'/'resume'/'remove' manage one by job_id (always list first — never guess job IDs); 'run' fires a job immediately in the BACKGROUND (returns a handle at once, outcome re-enters the conversation when done — do not wait or poll; optional 'prompt' adds transient context for that fire only).\n\nJobs run in a fresh session with no current-chat context, so prompts must be self-contained, and the agent's FINAL RESPONSE is what gets delivered — cron runs are autonomous and cannot ask questions. Prefer updating an existing job over creating near-duplicates.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "description": "One of: create, list, update, pause, resume, remove, run. When action=create, the 'schedule' and 'prompt' fields are REQUIRED."
+        },
+        "job_id": {
+          "type": "string",
+          "description": "Required for update/pause/resume/remove/run"
+        },
+        "prompt": {
+          "type": "string",
+          "description": "For create: the full self-contained prompt (paired with any skills as the task instruction). For run: optional transient context for that single fire (never persisted)."
+        },
+        "schedule": {
+          "type": "string",
+          "description": "REQUIRED for create. Schedule forms: (1) recurring interval — '30m', 'every 2h', 'every hour' (EVERY 30 minutes / 2 hours / hour, forever by default); (2) explicit one-shot by duration — 'in 30m', 'in 2h' (fires ONCE that far from now; use this for 'remind me in N minutes' — do NOT hand-compute an absolute timestamp); (3) natural day/time — 'every monday 9am', 'weekdays at 9am', 'every day at 9am' (recurring weekly/daily); (4) cron syntax — '0 9 * * *' (daily 9am); (5) absolute one-shot — ISO timestamp '2026-06-01T09:00:00'."
+        },
+        "name": {
+          "type": "string",
+          "description": "Optional human-friendly name"
+        },
+        "repeat": {
+          "type": "integer",
+          "description": "Optional repeat count. Omit for defaults (once for one-shot, forever for recurring)."
+        },
+        "deliver": {
+          "type": "string",
+          "description": "Where the job's output is POSTED as a one-way message (the job itself always runs in a fresh session with no chat context). Omit to address the chat/topic this job was created from. Otherwise: 'local' (save only, no delivery), 'all' (every connected home channel, resolved at fire time), 'bot-chat' or 'bot-chat:<profile>' (inject into a Bot Chat as a real message), or platform:chat_id:thread_id (e.g. 'telegram:-1001234567890:17585'). Comma-combine like 'origin,all'."
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional ordered skill names loaded before the cron prompt. On update, [] clears."
+        },
+        "script": {
+          "type": "string",
+          "description": "Optional script run each tick; stdout is injected into the agent's prompt as context (with no_agent=True the script IS the job). Relative paths resolve under the home's scripts/; .sh/.bash via bash, else Python. On update, '' clears."
+        },
+        "monitor": {
+          "type": "string",
+          "description": "Optional change-detector that gates the agent: an http(s) URL (fetched each tick) or a script path (same rules as `script`, run each tick) — cheap, no LLM. Output identical to the previous tick skips the agent run entirely; changed output wakes the agent with a diff injected into the prompt. First tick always runs (baseline). Output must be deterministic (no timestamps) or every tick looks changed. Incompatible with no_agent. On update, '' clears."
+        },
+        "no_agent": {
+          "type": "boolean",
+          "default": false,
+          "description": "True = no LLM: the scheduler runs `script` (required) on schedule and delivers its stdout verbatim; empty stdout sends nothing (watchdog pattern). Use for script-only pings with fixed output; keep False for anything needing reasoning."
+        },
+        "context_from": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional job ID(s) whose most recent completed output is injected as context each run — chains jobs (A collects, B processes). For a job's OWN previous output prefer `continuity`. On update, [] clears."
+        },
+        "continuity": {
+          "type": "boolean",
+          "description": "True = each run sees the job's own previous output, so it can dedupe and continue where it left off (scouts, monitors, incremental digests). Default false. On update, false turns it off."
+        },
+        "enabled_toolsets": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional toolset names to restrict the job's agent to (e.g. [\"web\", \"terminal\"]) — cuts token overhead. Infer from the prompt. Omit for all default tools. On update, [] clears."
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Optional absolute existing path to run the job from: injects that directory's AGENTS.md/context files and anchors terminal/file tools there. On update, '' clears."
+        },
+        "attach_to_session": {
+          "type": "boolean",
+          "description": "True = the job's delivery is CONTINUABLE — the user can reply and the agent has the brief in context (threads on thread-capable platforms, mirrored into the DM elsewhere). Use for conversational recurring jobs (briefings); leave unset for fire-and-forget alerts. Scope: the job's own conversation only — the origin chat, the home-channel fallback when deliver='origin' captured no origin (script-created jobs), or the job's single explicit platform:chat target (this flag is the only way to attach an explicit target). Broadcast targets are never attached; no effect when deliver='local'."
+        }
+      },
+      "required": [
+        "action"
+      ]
+    }
+  },
+  {
+    "name": "send_message",
+    "description": "Send a message to a connected messaging platform, or list available targets.\n\nIMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available targets, then send to the correct one.\nIf the user just says a platform name like 'send to telegram', send directly to the home channel without listing first.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "send",
+            "list",
+            "react",
+            "unreact"
+          ],
+          "description": "Action to perform. 'send' (default) sends a message. 'list' returns all available channels/contacts across connected platforms. 'react' attaches an emoji reaction to a message (platforms that support it, e.g. photon/iMessage tapbacks). 'unreact' retracts a previously-added reaction."
+        },
+        "target": {
+          "type": "string",
+          "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', 'platform:chat_id', or 'platform:chat_id:thread_id' for Telegram topics and Discord threads. Examples: 'telegram', 'telegram:-1001234567890:17585', 'discord:999888777:555444333', 'discord:#bot-home', 'slack:#engineering', 'signal:+155****4567', 'matrix:!roomid:server.org', 'matrix:@user:server.org', 'ntfy:alerts-channel' (explicit ntfy topic), 'yuanbao:direct:<account_id>' (DM), 'yuanbao:group:<group_code>' (group chat)"
+        },
+        "message": {
+          "type": "string",
+          "description": "The message text to send. To send an image or file, include MEDIA:<local_path> (e.g. 'MEDIA:/tmp/report.pdf') in the message — the platform will deliver it as a native media attachment."
+        },
+        "emoji": {
+          "type": "string",
+          "description": "For action='react': the emoji to react with (e.g. '❤️'). On iMessage, ❤️👍👎😂‼️❓ render as native tapbacks; other emoji use custom-emoji reactions."
+        },
+        "message_id": {
+          "type": "string",
+          "description": "For action='react'/'unreact': id of the message to react to. Omit to target the most recent message received in that chat (usually the one being replied to)."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "session_search",
+    "description": "Search past Hermes sessions (FTS5 over the local session DB), or read/scroll inside one. Four shapes, picked by args: `query` = discovery (top-N matching sessions, top result fully hydrated); `session_id` + `around_message_id` = scroll (window of messages around an anchor); `session_id` alone = read a whole session — how you resolve an `@session:<profile>/<id>` link (split on '/' into profile + id); no args = browse recent sessions. Results are actual DB messages, no LLM. Searches conversation history ONLY — when the user gave a direct source (URL, file, contact, live system), inspect that first; never conclude 'not found' from history alone. Use for questions about past conversations: 'what did we do about X', 'where did we leave Y'. When referring the user to a session, write its `link` value verbatim inline (it renders as a titled link).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search query (discovery shape). Keywords, phrases, or boolean expressions to find in past sessions. Omit to browse recent sessions. Ignored when session_id + around_message_id are set (scroll shape)."
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Discovery shape only. Max sessions to return (default 3, max 10). Bump to 5–10 when the topic likely spans several sessions and you want to pick the right one to scroll into.",
+          "default": 3
+        },
+        "sort": {
+          "type": "string",
+          "enum": [
+            "newest",
+            "oldest"
+          ],
+          "description": "Discovery shape only. Temporal bias on top of FTS5 ranking: omit for relevance-only (exploratory recall), 'newest' for \"where did we leave X\", 'oldest' for \"how did X start\"."
+        },
+        "detail": {
+          "type": "string",
+          "enum": [
+            "adaptive",
+            "full"
+          ],
+          "description": "Discovery shape only. 'adaptive' (default) fully hydrates the top-ranked result and returns only the exact anchor message for lower-ranked results. 'full' returns bookends and the complete anchored window for every result.",
+          "default": "adaptive"
+        },
+        "session_id": {
+          "type": "string",
+          "description": "Scroll shape. Session to read inside. Use the session_id returned from a prior discovery call. Must be paired with around_message_id."
+        },
+        "around_message_id": {
+          "type": "integer",
+          "description": "Scroll shape. Message id to center the window on — use match_message_id from a discovery result, or any id from a prior window."
+        },
+        "window": {
+          "type": "integer",
+          "description": "Scroll shape only. Messages to return on each side of the anchor (anchor itself always included). Clamped to [1, 20]. Default 5.",
+          "default": 5
+        },
+        "role_filter": {
+          "type": "string",
+          "description": "Optional. Comma-separated roles to include. Discovery defaults to 'user,assistant' (tool output is usually noise). Pass 'user,assistant,tool' to include tool output (debugging tool behaviour) or 'tool' to search tool output only."
+        },
+        "profile": {
+          "type": "string",
+          "description": "Optional. Read sessions from another Hermes profile's database (read-only). Use when resolving an `@session:<profile>/<id>` link: pass the profile segment here with session_id as the id segment. Omit to use the current profile."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "memory",
+    "description": "Save durable facts to persistent memory that survive across sessions. Memory is injected into every future turn, so keep entries compact and high-signal.\n\nHOW: make ALL your changes in ONE call via an 'operations' array (each item: {action, content?, old_text?}). The batch applies atomically and the char limit is checked only on the FINAL result — so a single call can remove/replace stale entries to free room AND add new ones, even when an add alone would overflow. The response reports current/limit chars and confirms completion; one batch call finishes the update, so don't repeat it. Use the bare action/content/old_text fields only for a single lone change.\n\nWHEN: save proactively when the user states a preference, correction, or personal detail, or you learn a stable fact about their environment, conventions, or workflow. Priority: user preferences & corrections > environment facts > procedures. The best memory stops the user repeating themselves.\n\nIF FULL: an add is rejected with the current entries shown. Reissue as ONE batch that removes or shortens enough stale entries and adds the new one together.\n\nTARGETS: 'user' = who the user is (name, role, preferences, style). 'memory' = your notes (environment, conventions, tool quirks, lessons).\n\nSKIP: trivial/obvious info, easily re-discovered facts, raw data dumps, task progress, completed-work logs, temporary TODO state (use session_search for those). Reusable procedures belong in a skill, not memory.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "add",
+            "replace",
+            "remove"
+          ],
+          "description": "The action to perform (single-op shape). Omit when using 'operations'."
+        },
+        "target": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "user"
+          ],
+          "description": "Which memory store: 'memory' for personal notes, 'user' for user profile."
+        },
+        "content": {
+          "type": "string",
+          "description": "The entry content. Required for 'add' and 'replace' (single-op shape). Alias: 'new_text' is also accepted (mirrors old_text)."
+        },
+        "old_text": {
+          "type": "string",
+          "description": "REQUIRED for 'replace' and 'remove' (single-op shape): a short unique substring identifying the existing entry to modify. Omit only for 'add'."
+        },
+        "new_text": {
+          "type": "string",
+          "description": "Alias for 'content' (single-op shape). Provided so the replace/remove old_text/new_text pairing works; if both are set, 'content' wins."
+        },
+        "operations": {
+          "type": "array",
+          "description": "Batch shape: a list of operations applied atomically in one call against the final char budget. Preferred when making multiple changes or consolidating to make room. Each item is {action, content?, old_text?}.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "action": {
+                "type": "string",
+                "enum": [
+                  "add",
+                  "replace",
+                  "remove"
+                ]
+              },
+              "content": {
+                "type": "string",
+                "description": "Entry content for add/replace. Alias: 'new_text'."
+              },
+              "new_text": {
+                "type": "string",
+                "description": "Alias for 'content' in a batch op."
+              },
+              "old_text": {
+                "type": "string",
+                "description": "Substring identifying the entry for replace/remove."
+              }
+            },
+            "required": [
+              "action"
+            ]
+          }
+        }
+      },
+      "required": [
+        "target"
+      ]
+    }
+  },
+  {
+    "name": "skills_list",
+    "description": "List available skills (name + description). Use skill_view(name) to load full content.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Optional category filter to narrow results"
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "skill_view",
+    "description": "Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a 'linked_files' dict showing available references/templates/scripts. To access those, call again with file_path parameter.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The skill name (use skills_list to see available skills). For plugin-provided skills, use the qualified form 'plugin:skill' (e.g. 'superpowers:writing-plans')."
+        },
+        "file_path": {
+          "type": "string",
+          "description": "OPTIONAL: Path to a linked file within the skill (e.g., 'references/api.md', 'templates/config.yaml', 'scripts/validate.py'). Omit to get the main SKILL.md content."
+        }
+      },
+      "required": [
+        "name"
+      ]
+    }
+  }
+]

package/mcp/mount.mjs

@@ -0,0 +1,161 @@
+// Where the orchestrator mounts its MCP server in each worker harness
+// (docs/ORCHESTRATOR-IR.md §7; §5's `RuntimeStart` row).
+//
+// The door table and the per-door writers are the harness SDK's
+// (`@volter/supercode-harness-sdk/mcp-doors`, which carries each door's
+// inventory citation); this module keeps what is the orchestrator's own: its
+// server's binding, and the profile's own servers mounted beside it.
+//
+// Only the flag and ACP doors are per-SESSION: they are named at launch. The
+// codex and opencode doors are per-config-home, i.e. per profile, so the
+// per-session half of the binding (`SUPERCODE_ORCHESTRATOR_SURFACE`) is not
+// written into them — the MCP server is spawned BY the worker and inherits the
+// worker's own environment, which `activationEnv` already set per session.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  acpEntry, doorFor, opencodeEntry, readOpencodeConfig, removeTomlBlock, serverToml, tomlString, upsertTomlBlock, withMcpConfigFlag, writeMcpConfigFile,
+} from '@volter/supercode-harness-sdk/mcp-doors';
+import { ORCH_ENV } from '../activation.mjs';
+import { SERVER_NAME } from './tools.mjs';
+import { SOCKET_ENV, socketPathFor } from './server.mjs';
+import { mcpServers } from '../hermes-home.mjs';
+import { KANBAN_ENV } from '../hermes-cli.mjs';
+
+export { MCP_DOORS, doorFor } from '@volter/supercode-harness-sdk/mcp-doors';
+
+/** The stdio server this module mounts. */
+export const SERVER_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'server.mjs');
+
+const slug = (surfaceKey) => (surfaceKey ? String(surfaceKey).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'session' : 'session');
+
+/**
+ * Mount the orchestrator's MCP server for one worker session.
+ *
+ * @param {object} o
+ * @param {string} o.root           orchestrator root
+ * @param {object} o.profile        the Profile (its `dir` and `name` are used)
+ * @param {string} o.harness        worker harness id
+ * @param {string|null} o.surfaceKey  the surface this session is bound to
+ * @param {object|undefined} o.launch the launch the loop resolved, if any
+ * @param {string} [o.socketPath]   defaults to `<root>/orchestrator.sock`
+ * @param {string} [o.serverPath]   defaults to this package's `mcp/server.mjs`
+ * @param {string} [o.program]      the interpreter, defaults to this node
+ * @returns {{door: string, ran: string, launch: object|undefined, mcp_servers: object[]|null, path: string|null}}
+ */
+export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null, launch, socketPath, serverPath = SERVER_PATH, program = process.execPath, vault = new Map(), task = null }) {
+  const door = doorFor(harness);
+  // the profile's own servers (`.mcp.json`, the workers' form; docs/plans/hermes-compat.md row 4), mounted
+  // beside this one through the same door, `${VAR}` resolved from the profile's vault
+  const own = resolveServers(mcpServers(profile.dir), vault);
+  const sock = socketPath ?? socketPathFor(root);
+  const home = join(profile.dir, harness);
+  const env = {
+    [ORCH_ENV.root]: root,
+    [ORCH_ENV.profile]: profile.name,
+    [SOCKET_ENV]: sock,
+  };
+  // a dispatched worker's task (`task`, Hermes's KANBAN_ENV) rides with the session: the door publishes the
+  // board's tools for it (docs/plans/hermes-compat.md row 14)
+  const sessionEnv = { ...env, ...(surfaceKey ? { [ORCH_ENV.surface]: surfaceKey } : {}), ...(task ?? {}) };
+
+  switch (door) {
+    case 'flag': {
+      if (!launch) {
+        return { door, ran: `${harness} takes its MCP config as a launch flag, but no launch was resolved`, launch, mcp_servers: null, path: null };
+      }
+      const file = join(home, `mcp-orchestrator-${slug(surfaceKey)}.json`);
+      mkdirSync(home, { recursive: true });
+      writeMcpConfigFile(file, { ...own, [SERVER_NAME]: { command: program, args: [serverPath], env: sessionEnv } });
+      return { door, ran: `wrote ${file} and passed --mcp-config`, launch: withMcpConfigFlag(launch, file), mcp_servers: null, path: file };
+    }
+
+    case 'toml': {
+      const file = join(home, 'config.toml');
+      mkdirSync(home, { recursive: true });
+      const block = tomlBlock(program, serverPath, env);
+      let text = upsertTomlBlock(existsSync(file) ? readFileSync(file, 'utf8') : '', block, SERVER_NAME);
+      const written = ownNames(home);
+      for (const name of written) if (!(name in own)) text = removeTomlBlock(text, name);
+      for (const [name, server] of Object.entries(own)) {
+        text = upsertTomlBlock(text, serverToml(name, server, fullTrust(profile, name)), name);
+      }
+      writeFileSync(file, text, { mode: 0o600 });
+      recordOwnNames(home, Object.keys(own));
+      return { door, ran: `wrote [mcp_servers.${[SERVER_NAME, ...Object.keys(own)].join('], [mcp_servers.')}] into ${file}`, launch, mcp_servers: null, path: file };
+    }
+
+    case 'json': {
+      const file = join(home, 'opencode.json');
+      mkdirSync(home, { recursive: true });
+      const config = readOpencodeConfig(file);
+      config.mcp = { ...(config.mcp ?? {}) };
+      for (const name of ownNames(home)) if (!(name in own)) delete config.mcp[name];
+      for (const [name, server] of Object.entries(own)) config.mcp[name] = opencodeEntry(server);
+      recordOwnNames(home, Object.keys(own));
+      config.mcp[SERVER_NAME] = opencodeEntry({ command: program, args: [serverPath], env });
+      writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+      return { door, ran: `wrote mcp.${SERVER_NAME} into ${file}`, launch, mcp_servers: null, path: file };
+    }
+
+    case 'none':
+      return { door, ran: `${harness} has no MCP door (it deliberately ships no MCP client); nothing was mounted`, launch, mcp_servers: null, path: null };
+
+    case 'acp':
+    default:
+      return {
+        door: 'acp',
+        ran: `passed ${SERVER_NAME} to session/new's mcpServers`,
+        launch,
+        mcp_servers: [
+          ...Object.entries(own).filter(([, server]) => server.command).map(([name, server]) => acpEntry(name, server)),
+          acpEntry(SERVER_NAME, { command: program, args: [serverPath], env: sessionEnv }),
+        ],
+        path: null,
+      };
+  }
+}
+
+/** The orchestrator's own `[mcp_servers.orchestrator]` block. */
+function tomlBlock(program, serverPath, env) {
+  const lines = [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = ${tomlString(program)}`,
+    `args = [${tomlString(serverPath)}]`,
+  ];
+  for (const [k, v] of Object.entries(env)) lines.push(`env.${k} = ${tomlString(v)}`);
+  // The per-session half rides codex's own env allowlist: the server is a child
+  // of the worker, whose environment the loop set for this session.
+  lines.push(`env_vars = [${[ORCH_ENV.surface, ...KANBAN_ENV].map(tomlString).join(', ')}]`);
+  // the orchestrator's door is Hermes's own tools, which Hermes does not gate; Codex's app-server otherwise
+  // asks its client about each MCP call and rejects the ones nobody answers (measured: `kanban_show` in a
+  // dispatched worker came back "user rejected MCP tool call")
+  lines.push('default_tools_approval_mode = "approve"');
+  return `${lines.join('\n')}\n`;
+}
+
+/** `${VAR}` in a server's strings, from the profile's vault, else this process's environment. */
+function resolveServers(servers, vault) {
+  const sub = (v) => (typeof v === 'string' ? v.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (m, name) => vault.get?.(name) ?? process.env[name] ?? m) : v);
+  const walk = (v) => (Array.isArray(v) ? v.map(walk) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)])) : sub(v));
+  return Object.fromEntries(Object.entries(servers).filter(([name]) => name !== SERVER_NAME).map(([name, server]) => [name, walk(server)]));
+}
+
+/** The profile servers this door last wrote into a config home, so a server dropped from `.mcp.json` is removed. */
+const OWN_FILE = '.mcp-from-profile.json';
+function ownNames(home) { try { return JSON.parse(readFileSync(join(home, OWN_FILE), 'utf8')); } catch { return []; } }
+function recordOwnNames(home, names) { writeFileSync(join(home, OWN_FILE), JSON.stringify(names)); }
+
+/**
+ * Hermes's trust for one of the profile's own servers (`mcp_servers.<name>.trust` in `config.yaml`, read as
+ * Hermes's `_normalize_server_trust` reads it): unset is full; `untrusted`, or any other word, is not, and
+ * Hermes asks before its write-capable tools run. A full-trust server's tools run unasked, as under Hermes;
+ * an untrusted one keeps Codex's own default, where a call nobody approves is rejected: stricter than Hermes,
+ * which would ask, never looser.
+ */
+function fullTrust(profile, name) {
+  const trust = profile?.residue?.config?.mcp_servers?.[name]?.trust;
+  return trust === undefined || trust === null || String(trust).trim().toLowerCase() === 'full';
+}

package/mcp/server.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// The orchestrator's model-facing door: ONE stdio MCP server per worker
+// session, bound to the conversation that spawned it (docs/ORCHESTRATOR-IR.md
+// §7).
+//
+// It is a thin process. Everything it can do is a line on the orchestrator's
+// own Unix socket (`mcp/bridge.mjs`); it holds no state and reads no file of
+// the model's world. The binding — which profile, which surface — arrives in
+// the environment the loop already sets (`activationEnv`), never in a tool
+// argument, so a worker cannot address another conversation by asking.
+//
+// The framing is minimal by hand, no SDK: newline-delimited JSON-RPC 2.0 over
+// stdin/stdout, `initialize` -> `tools/list` -> `tools/call`, mirroring what
+// `crates/harness/src/mcp.rs::handle_request` accepts (notifications carry no
+// id and get no reply; an unknown method is -32601). That module and
+// `supercode mcp serve` are a different server for a different purpose and are
+// untouched by this one.
+
+import { createInterface } from 'node:readline';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { KANBAN_TOOLS, PROTOCOL_VERSION, SERVER_NAME, TOOLS } from './tools.mjs';
+import { KANBAN_ENV, hermesTool } from '../hermes-cli.mjs';
+
+/** Env var naming the socket, when the loop wants one off the root's default. */
+export const SOCKET_ENV = 'SUPERCODE_ORCHESTRATOR_SOCK';
+
+/**
+ * The loop's socket for a root: `<root>/orchestrator.sock`, or SOCKET_ENV where
+ * the embedding keeps the socket off the root (a root on a network filesystem
+ * cannot hold a Unix socket). The CLI's door derives the same path.
+ */
+export function socketPathFor(root, env = process.env) {
+  return env[SOCKET_ENV] || join(root, 'orchestrator.sock');
+}
+
+/** The binding this server was spawned with, from the loop's activation env (and a dispatched task's). */
+export function bindingFromEnv(env = process.env) {
+  const root = env.SUPERCODE_ORCHESTRATOR_ROOT;
+  const profile = env.SUPERCODE_ORCHESTRATOR_PROFILE;
+  const surface = env.SUPERCODE_ORCHESTRATOR_SURFACE ?? null;
+  if (!root || !profile) throw new Error('the orchestrator MCP server needs SUPERCODE_ORCHESTRATOR_ROOT and _PROFILE');
+  const kanban = env.HERMES_KANBAN_TASK ? Object.fromEntries(KANBAN_ENV.filter((k) => env[k]).map((k) => [k, env[k]])) : null;
+  return { root, profile, surface, socket: env[SOCKET_ENV] || socketPathFor(root), kanban };
+}
+
+/** The profile's folder: the root is the `default` profile, `profiles/<name>` the rest (a Hermes home's layout). */
+const profileDir = (binding) => (binding.profile === 'default' ? binding.root : join(binding.root, 'profiles', binding.profile));
+
+/** The tools this door publishes: the orchestrator's, and the board's where a dispatch gave it a task. */
+const published = (binding) => (binding.kanban ? [...TOOLS, ...KANBAN_TOOLS] : TOOLS);
+
+/**
+ * A board tool, answered by Hermes's own handler in this process: the task, its run and its claim are
+ * this worker's environment, as they are a Hermes worker's, never the daemon's.
+ */
+async function kanbanCall(binding, name, args) {
+  try {
+    const out = await hermesTool(profileDir(binding), name, args, { env: binding.kanban });
+    return { ok: true, result: { ran: name, verbatim: typeof out === 'string' ? out : JSON.stringify(out) } };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * One request on the bridge socket: connect, write one JSON line, read one
+ * back. A connection per call keeps this process stateless and means a
+ * restarted loop is picked up on the next tool call, not never.
+ */
+export function ask(binding, verb, args) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(binding.socket);
+    let buffer = '';
+    const fail = (error) => { socket.destroy(); reject(error); };
+    socket.setEncoding('utf8');
+    socket.on('error', fail);
+    socket.on('connect', () => {
+      socket.write(`${JSON.stringify({ verb, args, profile: binding.profile, surface: binding.surface })}\n`);
+    });
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const nl = buffer.indexOf('\n');
+      if (nl < 0) return;
+      socket.end();
+      try { resolve(JSON.parse(buffer.slice(0, nl))); } catch (error) { reject(error); }
+    });
+    socket.on('close', () => { if (!buffer.includes('\n')) reject(new Error('the orchestrator closed the connection without answering')); });
+  });
+}
+
+/** `crates/harness/src/mcp.rs::handle_request`'s shape, in JavaScript. */
+export async function handleRequest(binding, request) {
+  const id = request?.id;
+  const method = request?.method ?? '';
+  const reply = (result) => ({ jsonrpc: '2.0', id, result });
+  switch (method) {
+    case 'initialize':
+      return reply({
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: `supercode-${SERVER_NAME}`, version: '1' },
+      });
+    case 'tools/list':
+      return reply({ tools: published(binding).map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })) });
+    case 'tools/call': {
+      const name = request?.params?.name ?? '';
+      const args = request?.params?.arguments ?? {};
+      if (!published(binding).some((t) => t.name === name)) {
+        return { jsonrpc: '2.0', id, error: { code: -32601, message: `unknown tool \`${name}\`` } };
+      }
+      let answer;
+      if (name.startsWith('kanban_')) answer = await kanbanCall(binding, name, args);
+      else {
+        try { answer = await ask(binding, name, args); }
+        catch (error) { answer = { ok: false, error: `the orchestrator is not answering: ${error.message}` }; }
+      }
+      const text = answer.ok ? (answer.result?.ran ?? JSON.stringify(answer.result)) : `Error: ${answer.error}`;
+      return reply({
+        content: [{ type: 'text', text: answer.ok ? renderResult(answer.result) : text }],
+        isError: !answer.ok,
+        structuredContent: answer.ok ? answer.result : { error: answer.error },
+      });
+    }
+    default:
+      if (id === undefined || id === null) return null; // a notification
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `unknown method \`${method}\`` } };
+  }
+}
+
+/**
+ * Every result names what it did (`ran`) first, then carries its rows; a tool Hermes's own handler served
+ * answers in Hermes's own words (`verbatim`), as Hermes's model reads them.
+ */
+function renderResult(result) {
+  if (typeof result?.verbatim === 'string') return result.verbatim;
+  const { ran, ...rest } = result ?? {};
+  const body = Object.keys(rest).length ? `\n${JSON.stringify(rest, null, 2)}` : '';
+  return `${ran ?? 'done'}${body}`;
+}
+
+export function serveStdio(binding, input = process.stdin, output = process.stdout) {
+  const lines = createInterface({ input });
+  let queue = Promise.resolve();
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let request;
+    try { request = JSON.parse(line); }
+    catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } })}\n`); return; }
+    queue = queue.then(async () => {
+      const response = await handleRequest(binding, request);
+      if (response) output.write(`${JSON.stringify(response)}\n`);
+    });
+  });
+  return lines;
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  serveStdio(bindingFromEnv());
+}