toolfunnel 0.3.0

package/tools/scripts/tf-hook-add.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-hook-add.js — management tool: add a hook entry to the hook manifest.
+ *
+ * A first-party "gateway-run" management function: it configures ToolFunnel's
+ * OWN hook manifest (and, optionally, drops an inline hook script into the
+ * scripts copy dir). Discovered via list_tools and executed via run_tool
+ * through the PreToolUse gate — it is NOT a new MCP-protocol command.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
+ *   - Args: { id, event, matcher?, command, script?, timeout?, enabled?=true,
+ *             description?, scriptText? }.
+ *   - Prints EXACTLY ONE JSON object to stdout and exits 0 — ALWAYS exit 0, even
+ *     on a logical error, which is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true,  id, hook, scriptWritten }
+ *   failure: { ok:false, error }
+ *
+ * Ordering note (verified against src/core/hook-loader.js)
+ * -------------------------------------------------------
+ *   HookLoader.writeScript(id, text) resolves the script path from the spec and
+ *   THROWS for an unknown id (getSpec must find the row). Since addEntry rejects
+ *   duplicate ids, this tool only ever creates NEW hooks — so the manifest row
+ *   must be registered FIRST, then the inline script can be written. If the
+ *   inline write fails, the just-added entry is rolled back so the add stays
+ *   atomic (the intent behind a write-then-register ordering).
+ *
+ * Safety invariants:
+ *   - Touches only ToolFunnel's own manifest + scripts dir (resolved from
+ *     __dirname, never a caller-supplied absolute path).
+ *   - NO network. NEVER throws for ordinary conditions — only JSON on stdout.
+ */
+
+const path = require('node:path');
+const { loadManifest } = require('../../src/core/hook-loader');
+
+/**
+ * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/** The hook manifest, relative to ROOT. */
+const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
+ * is treated as an empty object. Returns the parsed value or a parse-error
+ * sentinel so the caller surfaces a clean { ok:false, error }.
+ *
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: {} };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure-ish core: validate args, register the hook, optionally write the inline
+ * script. Never throws for ordinary conditions (addEntry's own validation errors
+ * are caught in main).
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: 'args must be an object { id, event, command, ... }' };
+  }
+
+  const { id, event, matcher, command, script, timeout, description, scriptText } = args;
+
+  // Clear up-front checks for fields addEntry does not (id/event/command are
+  // re-validated by addEntry). scriptText is checked before any mutation so a
+  // bad value never leaves a half-added entry behind.
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+  if (scriptText !== undefined && typeof scriptText !== 'string') {
+    return { ok: false, error: 'scriptText must be a string when provided' };
+  }
+
+  // enabled defaults to TRUE (opt-out) for this tool, unlike the loader's
+  // addEntry default of false — so it is passed explicitly.
+  const enabled = args.enabled === undefined ? true : args.enabled === true;
+
+  // Build the spec from only the supplied optional fields (keeps the manifest
+  // tidy); addEntry stores them verbatim.
+  const spec = { id, event, command, enabled };
+  if (matcher !== undefined) spec.matcher = matcher;
+  if (script !== undefined) spec.script = script;
+  if (timeout !== undefined) spec.timeout = timeout;
+  if (description !== undefined) spec.description = description;
+
+  const loader = loadManifest(MANIFEST);
+
+  // Register first (see Ordering note in the header). addEntry validates
+  // id/event/command and rejects duplicate ids by throwing — caught in main.
+  const stored = loader.addEntry(spec);
+
+  let scriptWritten = false;
+  if (typeof scriptText === 'string') {
+    try {
+      loader.writeScript(id, scriptText);
+      scriptWritten = true;
+    } catch (err) {
+      // Roll the entry back so a failed inline write leaves no orphan row.
+      try {
+        loader.removeEntry(id);
+      } catch (_) {
+        /* best-effort rollback */
+      }
+      return {
+        ok: false,
+        error: `script write failed (entry rolled back): ${(err && err.message) || String(err)}`,
+      };
+    }
+  }
+
+  return { ok: true, id, hook: stored, scriptWritten };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      // addEntry throws on validation / duplicate-id failures — report them as
+      // a logical error, still exit 0.
+      payload = { ok: false, error: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-hook-set.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-hook-set.js — management tool: enable, disable, or remove a hook entry.
+ *
+ * A first-party "gateway-run" management function: it configures ToolFunnel's
+ * OWN hook manifest / enabled-state overlay. Discovered via list_tools and
+ * executed via run_tool through the PreToolUse gate — it is NOT a new
+ * MCP-protocol command.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
+ *   - Args: { id, action: "enable" | "disable" | "remove" }.
+ *   - Prints EXACTLY ONE JSON object to stdout and exits 0 — ALWAYS exit 0, even
+ *     on a logical error, which is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, id, action, enabled }
+ *   remove:         { ok:true, id, action, removed }
+ *   failure:        { ok:false, error }
+ *
+ * Mapping (verified against src/core/hook-loader.js):
+ *   - enable  → loader.setEnabled(id, true)   (persists the state overlay + manifest)
+ *   - disable → loader.setEnabled(id, false)
+ *   - remove  → loader.removeEntry(id)        (returns false if the id was absent;
+ *               that is information, not a fault, so ok stays true)
+ *
+ * Safety invariants:
+ *   - Touches only ToolFunnel's own manifest / state (resolved from __dirname).
+ *   - NO network. NEVER throws for ordinary conditions — only JSON on stdout.
+ */
+
+const path = require('node:path');
+const { loadManifest } = require('../../src/core/hook-loader');
+
+/**
+ * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/** The hook manifest, relative to ROOT. */
+const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
+ * is treated as an empty object. Returns the parsed value or a parse-error
+ * sentinel so the caller surfaces a clean { ok:false, error }.
+ *
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: {} };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure-ish core: validate args and apply the requested action. Never throws for
+ * ordinary conditions (any loader throw is caught in main).
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: 'args must be an object { id, action }' };
+  }
+
+  const { id, action } = args;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+  if (action !== 'enable' && action !== 'disable' && action !== 'remove') {
+    return { ok: false, error: 'action must be one of "enable", "disable", "remove"' };
+  }
+
+  const loader = loadManifest(MANIFEST);
+
+  if (action === 'remove') {
+    const removed = loader.removeEntry(id);
+    return { ok: true, id, action, removed };
+  }
+
+  const desired = action === 'enable';
+  loader.setEnabled(id, desired);
+  return { ok: true, id, action, enabled: desired };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      payload = { ok: false, error: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-list.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-list.js — a READ-ONLY management inventory tool (category "management").
+ *
+ * Purpose
+ * -------
+ * One first-party register function that answers "what is configured, and what is
+ * its live state?" across the three stores the gateway owns:
+ *   - tools → the persisted Tool Register + the ACTIVE/DISABLED + hidden overlay.
+ *   - mcps  → the expose store: upstream MCPs and their curated-direct exposes.
+ *   - hooks → the hook manifest + the per-hook enabled-state overlay.
+ *
+ * It is discovered via list_tools and executed via run_tool through the PreToolUse
+ * gate. It does NOT add new MCP-protocol commands; it is a "gateway-run" script
+ * that reads the gateway's own config files. READ-ONLY: no writes, no network,
+ * no process mutation.
+ *
+ * Contract with the register (registry.js `defaultRunScript`)
+ * -----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
+ *     absent). The only arg is { kind: "tools" | "mcps" | "hooks" }.
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 — ALWAYS exit 0. A bad
+ *     kind, a missing/malformed config, or any other logical error is reported as
+ *     { ok:false, error } (still exit 0), never a crash.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, kind, items:[ ... ] }
+ *   failure: { ok:false, error }
+ *
+ * Per-kind item shapes:
+ *   tools  → register brief { id, name, summary, category } annotated with the
+ *            overlay-derived { enabled, hidden }.
+ *   mcps   → one item per upstream MCP (its full config incl. `enabled`) with its
+ *            curated-direct `exposed` entries nested (each carrying its resolved
+ *            downstream `name` and `enabled` flag). Uses listUpstreams() +
+ *            listExposed() and groups exposes under their owning upstream.
+ *   hooks  → one item per manifest hook (full spec) with `enabled` resolved from
+ *            the persisted overlay (readState) when present, else the manifest flag.
+ *
+ * Safety invariants (defense-in-depth; mirror the isolation rule):
+ *   - READ-ONLY: only reads config files INSIDE the toolfunnel root, resolved from
+ *     THIS script's own location (__dirname) — never a caller-supplied path.
+ *   - NO network, NO writes, NO process mutation.
+ *   - NEVER throws for ordinary conditions — only well-shaped JSON on stdout.
+ */
+
+const path = require('node:path');
+
+const { loadRegistry } = require('../../src/tools/registry');
+const { loadToolState, isToolEnabled, isToolHidden } = require('../../src/tools/tool-state');
+const { loadExposeStore } = require('../../src/mcp/expose-store');
+const { loadManifest } = require('../../src/core/hook-loader');
+
+/**
+ * The toolfunnel root, resolved from THIS file's location so the tool stays inside
+ * the sandbox and is portable wherever the tree is copied.
+ *
+ * This script lives at:  <root>/tools/scripts/tf-list.js
+ * so the root is two directories up from __dirname:  scripts -> tools -> <root>
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Canonical store paths (see the script contract).
+const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
+const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
+const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
+const MANIFEST_PATH = path.join(ROOT, 'hooks', 'hooks.manifest.json');
+const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
+
+/**
+ * Parse the structured args from env. Never throws: a missing/blank/malformed
+ * TOOLFUNNEL_TOOL_ARGS yields {} so the kind check below produces a clean
+ * { ok:false, error } rather than a crash.
+ * @returns {object}
+ */
+function readArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (typeof raw !== 'string' || raw.length === 0) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (_err) {
+    return {};
+  }
+}
+
+/**
+ * tools → register briefs annotated with the overlay's enabled + hidden state. HIDDEN tools are a
+ * manager-view declutter: they are OMITTED by default and only included when args.includeHidden is
+ * true. (This is the manager surface only — `hidden` never affects the lean list / top-level surface
+ * the connected AI sees.)
+ * @param {object} [args]  { includeHidden?: boolean }
+ * @returns {Array<{id,name,summary,category,enabled,hidden}>}
+ */
+function listTools(args) {
+  const includeHidden = !!(args && args.includeHidden === true);
+  const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
+  const state = loadToolState(STATE_PATH);
+  return registry.list()
+    .map((brief) => ({
+      ...brief,
+      enabled: isToolEnabled(state, brief.id),
+      hidden: isToolHidden(state, brief.id),
+    }))
+    .filter((t) => includeHidden || !t.hidden); // declutter: omit hidden unless explicitly asked
+}
+
+/**
+ * mcps → one item per upstream MCP, with its curated-direct exposes nested.
+ * Uses listUpstreams() for the connection config (incl. `enabled`) and
+ * listExposed() for the surfaced tools, grouping each expose under its owning
+ * upstream and resolving the downstream name via exposedName().
+ * @returns {Array<object>}
+ */
+function listMcps() {
+  const store = loadExposeStore(EXPOSE_PATH);
+  const upstreams = store.listUpstreams();
+  const exposed = store.listExposed();
+
+  // Group exposes by their upstream id (every expose references an existing
+  // upstream — addExpose requires it and removeUpstream cascades — but default
+  // to an empty list so an unmatched entry never throws).
+  const byUpstream = new Map();
+  for (const e of exposed) {
+    const annotated = { ...e, name: store.exposedName(e) };
+    const bucket = byUpstream.get(e.upstream);
+    if (bucket) bucket.push(annotated);
+    else byUpstream.set(e.upstream, [annotated]);
+  }
+
+  return upstreams.map((u) => ({
+    ...u,
+    exposed: byUpstream.get(u.id) || [],
+  }));
+}
+
+/**
+ * hooks → one item per manifest hook with `enabled` resolved from the persisted
+ * overlay (readState) when it carries the hook id, else the manifest's own flag.
+ * loadManifest already applies the overlay over the in-memory specs, but we read
+ * the overlay explicitly so the resolved `enabled` is correct regardless of that.
+ * @returns {Array<object>}
+ */
+function listHooks() {
+  const loader = loadManifest(MANIFEST_PATH);
+  const overlay = loader.readState();
+  return loader.hooks.map((h) => {
+    const hasOverride = h && typeof h.id === 'string' &&
+      Object.prototype.hasOwnProperty.call(overlay, h.id);
+    const enabled = hasOverride ? overlay[h.id] === true : h.enabled === true;
+    return { ...h, enabled };
+  });
+}
+
+/**
+ * Build the inventory for the requested kind. Throws on an unknown kind so main()
+ * can surface it as { ok:false, error }.
+ * @param {object} args
+ * @returns {{ ok:true, kind:string, items:Array<object> }}
+ */
+function build(args) {
+  const kind = args && args.kind;
+  let items;
+  switch (kind) {
+    case 'tools':
+      items = listTools(args); // honours args.includeHidden (hidden tools omitted by default)
+      break;
+    case 'mcps':
+      items = listMcps();
+      break;
+    case 'hooks':
+      items = listHooks();
+      break;
+    default:
+      throw new Error(`tf-list: kind must be one of "tools"|"mcps"|"hooks" (got ${JSON.stringify(kind)})`);
+  }
+  return { ok: true, kind, items };
+}
+
+function main() {
+  let payload;
+  try {
+    payload = build(readArgs());
+  } catch (err) {
+    // Any logical error (bad kind, missing/malformed store) becomes a well-shaped
+    // failure line. Still exit 0 — the gated runner treats parseable stdout as ok.
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-log.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-log.js — gateway-run MANAGEMENT tool: enable, disable, or check the activity log.
+ *
+ * A first-party "management" script-tool (discovered via list_tools, executed via
+ * run_tool through the PreToolUse gate). It toggles ToolFunnel's own JSONL audit log
+ * (tool runs + gate allow/deny decisions) via src/core/logger. Logging is DEFAULT OFF.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
+ *     absent). Shape: { action: 'enable'|'disable'|'status', path? }.
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 — ALWAYS. A logical failure
+ *     (bad args) is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, action, enabled, path }
+ *   status:         { ok:true, action, enabled, path, count }   // count = log entries
+ *   failure:        { ok:false, error }
+ */
+
+const logger = require('../../src/core/logger');
+
+/**
+ * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed JSON
+ * or a non-object payload so the caller reports { ok:false, error }.
+ * @returns {object}
+ */
+function parseArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') return {};
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
+  }
+  return parsed;
+}
+
+/**
+ * Perform the action. May throw — main() turns any throw into { ok:false, error }.
+ * @returns {object} the success payload
+ */
+function run() {
+  const args = parseArgs();
+  const action = args.action;
+
+  switch (action) {
+    case 'enable': {
+      const patch = { enabled: true };
+      if (typeof args.path === 'string' && args.path.length > 0) patch.path = args.path;
+      const cfg = logger.setConfig(patch);
+      return { ok: true, action, enabled: cfg.enabled, path: cfg.path };
+    }
+    case 'disable': {
+      const cfg = logger.setConfig({ enabled: false });
+      return { ok: true, action, enabled: cfg.enabled, path: cfg.path };
+    }
+    case 'status': {
+      const cfg = logger.getConfig();
+      const entries = logger.tail();
+      return { ok: true, action, enabled: cfg.enabled, path: cfg.path, count: entries.length };
+    }
+    default:
+      throw new Error(
+        `args.action must be one of enable|disable|status (got ${JSON.stringify(action)})`
+      );
+  }
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-mcp-add.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-mcp-add.js — gateway-run MANAGEMENT tool: register an upstream MCP in the
+ * ExposeStore and (optionally) curate which of its tools are exposed downstream.
+ *
+ * This is a first-party "management" script-tool: it is discovered via list_tools
+ * and executed via run_tool through the PreToolUse gate. It does not add new
+ * MCP-protocol commands — it edits ToolFunnel's own MCP config (mcp/expose.json)
+ * by way of the ExposeStore, the on-disk source of truth the aggregator consumes.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
+ *     absent). Shape:
+ *       {
+ *         id, command,
+ *         args?:[], env?:{}, transport?='stdio', enabled?=true, description?,
+ *         expose?:[ { tool, as?, category?, enabled? } ]
+ *       }
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 — ALWAYS. A logical
+ *     failure (bad args, validation error from the store) is reported as
+ *     { ok:false, error }, never a non-zero exit or a crash.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, upstream:{...}, exposed:[{...}, ...] }
+ *   failure: { ok:false, error }
+ *
+ * Behaviour
+ *   - addUpstream({ id, command, args, env, transport, enabled, description }) —
+ *     the store validates (unique non-empty id, transport==='stdio', non-empty
+ *     command) and persists atomically.
+ *   - For each expose[] item: addExpose({ upstream:id, tool, as, category, enabled }).
+ *     The store requires the upstream to exist (it does — we just added it), a
+ *     non-empty tool, and a unique (upstream,tool) pair.
+ *
+ * Note: there is no cross-step transaction. If the upstream is added but a later
+ * expose[] item fails validation, the upstream (and any earlier exposes) remain
+ * persisted; the failure is reported as { ok:false, error }.
+ */
+
+const path = require('node:path');
+const { loadExposeStore } = require('../../src/mcp/expose-store');
+
+/**
+ * ToolFunnel root, resolved from THIS file's location:
+ *   <root>/tools/scripts/tf-mcp-add.js -> root is two dirs up.
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/** The MCP config (upstreams + expose), per the host path contract. */
+const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
+
+/**
+ * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed
+ * JSON or a non-object payload so the caller reports { ok:false, error }.
+ * @returns {object}
+ */
+function parseArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') return {};
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
+  }
+  return parsed;
+}
+
+/**
+ * Perform the add. May throw — main() turns any throw into { ok:false, error }.
+ * @returns {object} the success payload
+ */
+function run() {
+  const args = parseArgs();
+  const store = loadExposeStore(EXPOSE_PATH);
+
+  // The store's normaliseUpstream already defaults transport/enabled/args/env, but
+  // apply the documented defaults explicitly so the intent is visible here too.
+  const upstream = store.addUpstream({
+    id: args.id,
+    command: args.command,
+    args: args.args,
+    env: args.env,
+    transport: typeof args.transport === 'string' ? args.transport : 'stdio',
+    enabled: typeof args.enabled === 'boolean' ? args.enabled : true,
+    description: args.description,
+  });
+
+  const exposed = [];
+  const exposeList = Array.isArray(args.expose) ? args.expose : [];
+  for (const item of exposeList) {
+    const e = item && typeof item === 'object' && !Array.isArray(item) ? item : {};
+    exposed.push(
+      store.addExpose({
+        upstream: upstream.id,
+        tool: e.tool,
+        as: e.as,
+        category: e.category,
+        enabled: typeof e.enabled === 'boolean' ? e.enabled : true,
+      })
+    );
+  }
+
+  return { ok: true, upstream, exposed };
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();