@onlyne/mcp-gateway 0.0.0-stage → 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbydd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @onlyne/mcp-gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An Onlyne node that hosts MCP servers as resources. Each configured server registers as one
+resource whose operations are that server's tools, so an agent reaches MCP through the same
+resource path it uses for every other capability.
+
+The node also runs persistent scheduled tasks. A task executes a locally allowed command or an
+allowed MCP tool and sends a readable result to its controller through Onlyne. These results use
+ordinary messages. They do not create a platform event stream or a resource event log.
+
+## Run
+
+```sh
+bunx onlyne-mcp-gateway ./gateway.json
+```
+
+```json
+{
+  "node": { "id": "urn:onlyne:gateway:mcp" },
+  "server": { "bind": "127.0.0.1", "port": 3992 },
+  "storage": { "path": "./var/mcp/store.json" },
+  "servers": [
+    {
+      "name": "hindsight",
+      "url": "http://localhost:8888/mcp/example-bank/",
+      "timeout_ms": 60000,
+      "controllers": ["urn:onlyne:agent:main"]
+    }
+  ]
+}
+```
+
+`headers` adds per-request headers such as an API key and is never logged. `controllers` lists
+the nodes allowed to call a server's tools; an empty list leaves the node owner alone.
+`language` accepts `en` or `zh-CN` and otherwise follows `ONLYNE_LANG`, `LC_ALL`, or `LANG`.
+
+## Scheduled tasks
+
+Mounts are disabled until the operator configures the `mounts` section:
+
+```json
+{
+  "mounts": {
+    "controllers": ["urn:onlyne:agent:main"],
+    "commands": [
+      { "id": "heartbeat", "command": "/bin/sh", "args": ["-c", "printf 'heartbeat\\n'"], "cwd": "/tmp" }
+    ],
+    "tools": [{ "server": "hindsight", "tool": "recall" }],
+    "tick_ms": 1000
+  }
+}
+```
+
+The node operator defines executable commands and arguments in local configuration. A remote
+mount selects a command id. Remote input cannot replace its executable, arguments, or working
+directory. An MCP mount selects an allowed server and tool. Its controller must also appear in
+that server's `controllers` list. The store records the actor and definition for each change.
+
+Each configured controller owns one scheduler resource named `mounts:<controller node id>`.
+The resource's handler is that controller, so another controller cannot operate its tasks. The
+gateway owner can read the resource. Agents use the existing resource operation path through
+`msg`; hosts may call the authenticated resource HTTP endpoint directly.
+
+The resource exposes these operations:
+
+| Operation | Data | Result |
+|---|---|---|
+| `mount` | `schedule`, `action`, optional `title` | New task |
+| `list` | Optional `include_removed` | This controller's tasks |
+| `inspect` | `task` | Definition, runs, and change records |
+| `update` | `task`, optional `title`, `schedule`, `action` | Updated definition |
+| `runs` | `task`, optional `limit` from 1 to 100 | Recent runs, newest first |
+| `cancel` | `task` | Stops future runs and the scheduler's active command |
+| `resume` | `task` | Re-arms the task |
+| `remove` | `task` | Removes the mount and retains its records |
+
+For example, mount a command every 30 seconds:
+
+```json
+{
+  "operation": "mount",
+  "data": {
+    "title": "Heartbeat",
+    "schedule": { "kind": "interval", "every_ms": 30000 },
+    "action": { "kind": "command", "command": "heartbeat" }
+  }
+}
+```
+
+An interval fires immediately, then measures each interval from its previous start. A one-shot
+schedule uses `{ "kind": "once", "at": "<future ISO timestamp>" }`. Cron uses
+`{ "kind": "cron", "expression": "*/5 * * * *" }`, with five numeric UTC fields and the
+standard `*`, comma, range, and step syntax. Named months and weekdays are rejected. An MCP
+action uses `{ "kind": "mcp", "server": "hindsight", "tool": "recall", "arguments": {} }`.
+
+The store retains each task, its next trigger time, and every run's start, finish, exit code,
+output summary, and failure reason. A task runs once at a time. A missed trigger during an
+active run records a skipped run. On restart, unfinished runs become interrupted records.
+Overdue interval and one-shot tasks receive one catch-up run. Cron resumes at its next future
+UTC occurrence. Updating an active task changes future runs and preserves the active run's
+definition.
+
+Each completed run has a durable push record. Its stable run id is also its message id, so a
+retry reuses the same delivery identity. Results are sent to the controller with
+`response: "none"` and `execution: "existing"`. Pending and uncertain deliveries retry with
+backoff within a 24-hour window. Refused and expired deliveries retain their reason. An
+accepted receipt means the controller saved the message; the controller host confirms model
+consumption through its existing delivery path.
+
+## Terminal
+
+The shared trust terminal shows servers and tool counts, task state and next trigger times,
+the pending push queue, and recent results. `ONLYNE_NO_TUI=1` keeps JSON logs on stdout,
+including when the process runs in a terminal.
+
+## Library use
+
+```ts
+import { createMcpGateway } from '@onlyne/mcp-gateway';
+```
+
+The result carries the node, the connections, and a `fetch` handler.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@onlyne/mcp-gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.0",
+  "description": "Onlyne MCP gateway: one node that hosts MCP servers as resources and exposes their tools as operations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dbydd/onlyne.git",
+    "directory": "packages/mcp-gateway"
+  },
+  "homepage": "https://github.com/dbydd/onlyne#readme",
+  "bugs": "https://github.com/dbydd/onlyne/issues",
+  "keywords": ["onlyne", "mcp", "gateway", "cli"],
+  "publishConfig": { "access": "public" },
+  "engines": { "bun": ">=1.4.3" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": { "onlyne-mcp-gateway": "src/main.ts" },
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun tests/verify.ts && bun tests/mounts-verify.ts",
+    "smoke": "bun tests/mounts-smoke.ts",
+    "smoke:fast": "MOUNT_SMOKE_INTERVAL_MS=3000 bun tests/mounts-smoke.ts"
+  },
+  "dependencies": {
+    "@onlyne/im-gateway": "^3.1.0",
+    "@onlyne/lib": "^3.1.0",
+    "@onlyne/mcp-core": "^3.1.0",
+    "@onlyne/node-host": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,182 @@
+import { OnlyneError, type Json, type NodeId } from '@onlyne/lib';
+import type { Locale } from '@onlyne/node-host/i18n';
+import { t } from './gateway-text.js';
+import { MOUNTS_RESOURCE_PREFIX } from './mounts.js';
+
+/** One configured MCP server: its resource name, URL and per-call settings. */
+export interface ServerConfig {
+  name: string;
+  url: string;
+  /** Extra request headers (an API key, a bank header); never logged. */
+  headers?: Record<string, string>;
+  timeout_ms?: number;
+  /** Who may call this server's tools. Empty means the node owner only. */
+  controllers?: NodeId[];
+}
+
+/** One locally allowlisted executable a scheduled mount may run: the mount names this id only. */
+export interface MountCommandConfig {
+  id: string;
+  command: string;
+  args?: string[];
+  cwd?: string;
+}
+
+/** One MCP tool a scheduled mount may call; the server's own controller list still applies. */
+export interface MountToolConfig { server: string; tool: string }
+
+export interface MountsConfig {
+  /** The nodes that may mount, inspect and cancel tasks on their own scheduler resource. */
+  controllers: NodeId[];
+  commands: MountCommandConfig[];
+  tools: MountToolConfig[];
+  tick_ms: number;
+}
+
+export interface GatewayConfig {
+  node: { id: NodeId };
+  server: { bind: string; port: number };
+  storage_path: string;
+  servers: ServerConfig[];
+  /** Scheduled mounts; absent means the gateway serves no scheduler resource at all. */
+  mounts?: MountsConfig;
+  /** The language of the gateway's own console text; unset follows `ONLYNE_LANG`. */
+  language?: Locale;
+}
+
+const requireObject = (value: Json | undefined, field: string): Record<string, Json> => {
+  if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new OnlyneError('invalid_request', t('config.object', { field }));
+  }
+  return value as Record<string, Json>;
+};
+
+const requireString = (container: Record<string, unknown>, field: string): string => {
+  const value = container[field];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new OnlyneError('invalid_request', t('config.string', { field }));
+  }
+  return value;
+};
+
+const requireStrings = (value: Json | undefined, field: string): string[] => {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.length === 0)) {
+    throw new OnlyneError('invalid_request', t('config.stringList', { field }));
+  }
+  return value as string[];
+};
+
+function parseMounts(raw: Json | undefined, owner: NodeId, serverNames: Set<string>): MountsConfig | undefined {
+  if (raw === undefined) return undefined;
+  const record = requireObject(raw, 'mounts');
+  const controllers = [...new Set(requireStrings(record.controllers, 'mounts.controllers'))];
+  if (controllers.length === 0) {
+    throw new OnlyneError('invalid_request', t('config.mountsControllers'));
+  }
+  if (controllers.includes(owner)) {
+    throw new OnlyneError('invalid_request', t('config.mountsOwner', { owner }));
+  }
+  const commands = (record.commands === undefined ? [] : record.commands);
+  if (!Array.isArray(commands)) throw new OnlyneError('invalid_request', t('config.mountsCommands'));
+  const commandIds = new Set<string>();
+  const parsedCommands = commands.map((entry, index): MountCommandConfig => {
+    const item = requireObject(entry, `mounts.commands[${index}]`);
+    const id = requireString(item, 'id');
+    if (commandIds.has(id)) throw new OnlyneError('invalid_request', t('config.mountsDuplicate', { kind: 'command', id }));
+    commandIds.add(id);
+    const args = item.args === undefined ? [] : requireStrings(item.args, `mounts.commands[${index}].args`);
+    const cwd = item.cwd === undefined ? undefined : requireString(item, 'cwd');
+    return {
+      id,
+      command: requireString(item, 'command'),
+      ...(args.length === 0 ? {} : { args }),
+      ...(cwd === undefined ? {} : { cwd }),
+    };
+  });
+  const tools = (record.tools === undefined ? [] : record.tools);
+  if (!Array.isArray(tools)) throw new OnlyneError('invalid_request', t('config.mountsTools'));
+  const toolIds = new Set<string>();
+  const parsedTools = tools.map((entry, index): MountToolConfig => {
+    const item = requireObject(entry, `mounts.tools[${index}]`);
+    const server = requireString(item, 'server');
+    const tool = requireString(item, 'tool');
+    if (!serverNames.has(server)) {
+      throw new OnlyneError('invalid_request', t('config.mountsToolServer', { server }));
+    }
+    const pair = `${server}\u0000${tool}`;
+    if (toolIds.has(pair)) throw new OnlyneError('invalid_request', t('config.mountsDuplicate', { kind: 'tool', id: `${server}/${tool}` }));
+    toolIds.add(pair);
+    return { server, tool };
+  });
+  const tick = record.tick_ms === undefined ? 1_000 : record.tick_ms;
+  if (typeof tick !== 'number' || !Number.isInteger(tick) || tick < 100 || tick > 60_000) {
+    throw new OnlyneError('invalid_request', t('config.mountTick'));
+  }
+  return { controllers, commands: parsedCommands, tools: parsedTools, tick_ms: tick };
+}
+
+/** `language` is exactly `en` or `zh-CN`: a near miss would silently pick a different console language. */
+const parseLanguage = (value: Json | undefined): Locale | undefined => {
+  if (value === undefined) return undefined;
+  if (value === 'en' || value === 'zh-CN') return value;
+  throw new OnlyneError('invalid_request', t('config.language', { value: JSON.stringify(value) }));
+};
+
+/** Loads the gateway configuration from one JSON file; environment retuning comes later. */
+export async function loadConfig(path: string): Promise<GatewayConfig> {
+  let file: Json | undefined;
+  try {
+    file = JSON.parse(await Bun.file(path).text()) as Json;
+  } catch {
+    throw new OnlyneError('invalid_request', t('config.unreadable', { path }));
+  }
+  const raw = requireObject(file, 'the configuration root');
+  const node = requireObject(raw.node, 'node');
+  const server = requireObject(raw.server, 'server');
+  const storage = requireObject(raw.storage, 'storage');
+  const language = parseLanguage(raw.language);
+  const owner = requireString(node, 'id') as NodeId;
+  const rawServers = raw.servers === undefined ? [] : raw.servers;
+  if (!Array.isArray(rawServers)) {
+    throw new OnlyneError('invalid_request', t('config.servers'));
+  }
+  const servers = rawServers.map((entry, index): ServerConfig => {
+    const item = requireObject(entry, `servers[${index}]`);
+    const rawHeaders = item.headers === undefined ? undefined : requireObject(item.headers, `servers[${index}].headers`);
+    const headers = rawHeaders === undefined
+      ? undefined
+      : Object.fromEntries(Object.entries(rawHeaders).filter((pair): pair is [string, string] => typeof pair[1] === 'string'));
+    const timeout = item.timeout_ms;
+    const controllers = item.controllers;
+    return {
+      name: requireString(item, 'name'),
+      url: requireString(item, 'url'),
+      ...(headers === undefined || Object.keys(headers).length === 0 ? {} : { headers }),
+      ...(typeof timeout === 'number' ? { timeout_ms: timeout } : {}),
+      ...(Array.isArray(controllers)
+        ? { controllers: controllers.filter((value): value is NodeId => typeof value === 'string' && value.length > 0) }
+        : {}),
+    };
+  });
+  const names = new Set<string>();
+  for (const entry of servers) {
+    if (names.has(entry.name)) throw new OnlyneError('invalid_request', t('config.duplicateName', { name: entry.name }));
+    if (entry.name.startsWith(MOUNTS_RESOURCE_PREFIX)) {
+      throw new OnlyneError('invalid_request', t('config.reservedName', { name: entry.name, prefix: MOUNTS_RESOURCE_PREFIX }));
+    }
+    names.add(entry.name);
+  }
+  const mounts = parseMounts(raw.mounts, owner, names);
+  return {
+    node: { id: owner },
+    server: {
+      bind: typeof server.bind === 'string' && server.bind.length > 0 ? server.bind : '127.0.0.1',
+      port: typeof server.port === 'number' ? server.port : 0,
+    },
+    storage_path: requireString(storage, 'path'),
+    servers,
+    ...(mounts === undefined ? {} : { mounts }),
+    ...(language === undefined ? {} : { language }),
+  };
+}

package/src/cron.ts

@@ -0,0 +1,122 @@
+import { OnlyneError } from '@onlyne/lib';
+
+/**
+ * A parsed five-field cron expression. Every field becomes a sorted list of the values it
+ * admits, so matching is a membership test and never a re-parse. Time is UTC: a mounted task
+ * must fire at the same instant after a restart, in every process, on every host.
+ */
+export interface CronSchedule {
+  readonly minutes: readonly number[];
+  readonly hours: readonly number[];
+  readonly days: readonly number[];
+  readonly months: readonly number[];
+  readonly weekdays: readonly number[];
+  /** Which of the day fields the expression restricts; both restricted match either (Vixie). */
+  readonly domRestricted: boolean;
+  readonly dowRestricted: boolean;
+}
+
+const FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  // 7 is Sunday: accepted as an input alias only, and normalized before the schedule is stored.
+  { name: 'day-of-week', min: 0, max: 7 },
+] as const;
+
+/** `7` is Sunday in the day-of-week field; the schedule normalizes it to `0`. */
+const WEEKDAY_ALIAS: Record<string, number> = { '7': 0 };
+
+const RANGE = /^(\d+)-(\d+)$/;
+const NUMBER = /^\d+$/;
+
+function parseField(text: string, spec: (typeof FIELDS)[number]): number[] {
+  if (text.length === 0) throw cronError(`The ${spec.name} field is empty.`);
+  const values = new Set<number>();
+  for (const part of text.split(',')) {
+    if (part.length === 0) throw cronError(`The ${spec.name} field holds an empty list item.`);
+    const [rangeText = '', stepText, extra] = part.split('/');
+    if (extra !== undefined) throw cronError(`The ${spec.name} field step has more than one slash.`);
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (!Number.isInteger(step) || step <= 0) throw cronError(`The ${spec.name} field step is a positive integer.`);
+    let from: number;
+    let to: number;
+    if (rangeText === '*') {
+      from = spec.min;
+      to = spec.max;
+    } else if (NUMBER.test(rangeText)) {
+      from = Number(rangeText);
+      // A bare number with a step names the range from that number to the field maximum.
+      to = stepText === undefined ? from : spec.max;
+    } else {
+      const range = RANGE.exec(rangeText);
+      if (range === null) throw cronError(`The ${spec.name} field value ${JSON.stringify(rangeText)} is not a number, range or '*'.`);
+      from = Number(range[1]);
+      to = Number(range[2]);
+    }
+    const low = from;
+    const high = to;
+    if (low < spec.min || low > spec.max || high < spec.min || high > spec.max) {
+      throw cronError(`The ${spec.name} field allows ${spec.min}..${spec.max}, not ${from}..${to}.`);
+    }
+    if (low > high) throw cronError(`The ${spec.name} field range ${from}-${to} runs backwards.`);
+    for (let value = low; value <= high; value += step) values.add(WEEKDAY_ALIAS[String(value)] ?? value);
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+function cronError(message: string): OnlyneError {
+  return new OnlyneError('invalid_request', message);
+}
+
+/** Parses one five-field expression; throwing `invalid_request` names the offending field. */
+export function parseCron(expression: string): CronSchedule {
+  if (typeof expression !== 'string') throw cronError('A cron expression is a string.');
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== FIELDS.length) {
+    throw cronError(`A cron expression has ${FIELDS.length} fields (minute hour day month weekday), not ${parts.length}.`);
+  }
+  const [minutes, hours, days, months, weekdays] = parts.map((part, index) => parseField(part, FIELDS[index]!));
+  return {
+    minutes: minutes!, hours: hours!, days: days!, months: months!, weekdays: weekdays!,
+    domRestricted: parts[2] !== '*',
+    dowRestricted: parts[4] !== '*',
+  };
+}
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+/** Five years covers every Gregorian recurrence, including 29 February on a weekday. */
+const HORIZON_DAYS = 366 * 5;
+
+/**
+ * The first instant strictly after `fromMs` that the expression admits, to the minute, in UTC.
+ * `undefined` means no occurrence inside the five-year horizon (for example `0 0 31 2 *`).
+ */
+export function nextCronTime(schedule: CronSchedule, fromMs: number): number | undefined {
+  const dayStart = Math.floor(fromMs / DAY_MS) * DAY_MS;
+  for (let day = 0; day < HORIZON_DAYS; day++) {
+    const base = dayStart + day * DAY_MS;
+    const date = new Date(base);
+    const month = date.getUTCMonth() + 1;
+    if (!schedule.months.includes(month)) continue;
+    const dom = date.getUTCDate();
+    const dow = date.getUTCDay();
+    const domMatch = schedule.days.includes(dom);
+    const dowMatch = schedule.weekdays.includes(dow);
+    // Vixie cron: a restricted day-of-month and a restricted day-of-week combine with OR.
+    const dayMatch = schedule.domRestricted && schedule.dowRestricted
+      ? domMatch || dowMatch
+      : domMatch && dowMatch;
+    if (!dayMatch) continue;
+    for (const hour of schedule.hours) {
+      for (const minute of schedule.minutes) {
+        const at = base + hour * HOUR_MS + minute * MINUTE_MS;
+        if (at > fromMs) return at;
+      }
+    }
+  }
+  return undefined;
+}

package/src/exec.ts

@@ -0,0 +1,163 @@
+import { OnlyneError } from '@onlyne/lib';
+
+/** Output kept per stream: enough for one readable result line, bounded so a chatty script cannot bloat the store. */
+export const OUTPUT_CAP = 4_096;
+/** How long a cancelled or stopping run gets to exit before the subtree is killed outright. */
+const KILL_GRACE_MS = 1_500;
+
+export interface CommandResult {
+  exit_code: number | null;
+  stdout: string;
+  stderr: string;
+  output_bytes: number;
+}
+
+export interface CommandTarget {
+  command: string;
+  args?: readonly string[];
+  cwd?: string;
+}
+
+/** A handle the scheduler keeps so it can signal exactly the process it started, never a name match. */
+export interface RunningChild {
+  cancelled: boolean;
+  pid?: number;
+}
+
+const safeKill = (pid: number, signal: NodeJS.Signals): void => {
+  // Never signal this process or init: a scheduler cancel must not take the gateway down.
+  if (pid <= 1 || pid === process.pid) return;
+  try { process.kill(pid, signal); } catch { /* the process is already gone */ }
+};
+
+/** The parent the kernel currently reports for a pid, used to prove the process is still ours. */
+function parentOf(pid: number): number | undefined {
+  try {
+    const text = Bun.spawnSync({
+      cmd: ['ps', '-o', 'ppid=', '-p', String(pid)], stdout: 'pipe', stderr: 'ignore',
+    }).stdout.toString().trim();
+    const parent = Number(text);
+    return Number.isInteger(parent) ? parent : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The live descendants of `pid`, read from `ps` once per signal so the list is the kernel's
+ * current view and not a stale snapshot from before the parent exited. Every pid is exact;
+ * nothing is matched by name.
+ */
+async function descendantsOf(pid: number): Promise<number[]> {
+  let output: string;
+  try {
+    output = Bun.spawnSync({
+      cmd: ['ps', '-axo', 'pid=,ppid='], stdout: 'pipe', stderr: 'ignore',
+    }).stdout.toString();
+  } catch {
+    return [];
+  }
+  const children = new Map<number, number[]>();
+  for (const line of output.split('\n')) {
+    const [childText, parentText] = line.trim().split(/\s+/);
+    const child = Number(childText);
+    const parent = Number(parentText);
+    if (!Number.isInteger(child) || !Number.isInteger(parent)) continue;
+    const list = children.get(parent) ?? [];
+    list.push(child);
+    children.set(parent, list);
+  }
+  const found: number[] = [];
+  const queue = [...(children.get(pid) ?? [])];
+  while (queue.length > 0) {
+    const next = queue.shift()!;
+    if (next === process.pid || found.includes(next)) continue;
+    found.push(next);
+    queue.push(...(children.get(next) ?? []));
+  }
+  return found;
+}
+
+/** Signals the process group the scheduler built: the exact child first, then its verified descendants. */
+export async function signalTree(child: RunningChild, signal: NodeJS.Signals): Promise<void> {
+  const pid = child.pid;
+  if (pid === undefined) return;
+  // A pid that no longer descends from this process has exited and its number may now belong to
+  // an unrelated process: drop the handle instead of signalling whatever took the slot.
+  if (parentOf(pid) !== process.pid) {
+    child.pid = undefined;
+    return;
+  }
+  const descendants = await descendantsOf(pid);
+  for (const descendant of descendants.reverse()) safeKill(descendant, signal);
+  safeKill(pid, signal);
+}
+
+/**
+ * Stops one run: SIGTERM for a clean exit, then SIGKILL of the same subtree while its root is
+ * still alive after the grace period. The escalation is not awaited by the caller, so a cancel
+ * answers as soon as the signal is sent; the run settles when its process actually exits.
+ */
+export function stopChild(child: RunningChild): void {
+  if (child.cancelled) return;
+  child.cancelled = true;
+  const pid = child.pid;
+  if (pid === undefined) return;
+  void signalTree(child, 'SIGTERM');
+  const timer = setTimeout(() => {
+    // Re-derive from the live root: a dead root's pid may already belong to another process,
+    // and a reused pid must never receive this run's signal.
+    if (child.pid === pid) void signalTree(child, 'SIGKILL');
+  }, KILL_GRACE_MS);
+  timer.unref?.();
+}
+
+async function drain(stream: ReadableStream<Uint8Array>, cap: number): Promise<{ text: string; bytes: number }> {
+  const decoder = new TextDecoder();
+  let text = '';
+  let bytes = 0;
+  for await (const chunk of stream as unknown as AsyncIterable<Uint8Array>) {
+    bytes += chunk.byteLength;
+    text += decoder.decode(chunk, { stream: true });
+    if (text.length > cap) text = text.slice(-cap);
+  }
+  text += decoder.decode();
+  if (text.length > cap) text = text.slice(-cap);
+  return { text, bytes };
+}
+
+/**
+ * Runs one allowlisted executable with argv directly, never through a shell: no quoting, no
+ * metacharacters, no remote string ever reaches `/bin/sh`. The child's pid is recorded before
+ * any output is read so a cancel that arrives first still has a handle to signal.
+ */
+export async function runCommand(target: CommandTarget, child: RunningChild): Promise<CommandResult> {
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn({
+      cmd: [target.command, ...(target.args ?? [])],
+      cwd: target.cwd ?? process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    throw new OnlyneError('invalid_request', `The command ${target.command} could not be started: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  child.pid = proc.pid;
+  try {
+    const [stdout, stderr] = await Promise.all([
+      drain(proc.stdout as ReadableStream<Uint8Array>, OUTPUT_CAP),
+      drain(proc.stderr as ReadableStream<Uint8Array>, OUTPUT_CAP),
+      proc.exited,
+    ]);
+    return {
+      exit_code: proc.exitCode ?? null,
+      stdout: stdout.text,
+      stderr: stderr.text,
+      output_bytes: stdout.bytes + stderr.bytes,
+    };
+  } finally {
+    // The child is gone; releasing the handle keeps a late cancel from signalling a reused pid.
+    if (proc.exitCode !== null) child.pid = undefined;
+  }
+}