gsjos 0.0.0-stage → 0.6.2

package/src/client.mjs

@@ -0,0 +1,171 @@
+// The API-client core. Both faces (CLI, MCP) go through this and nothing else.
+//
+// Auth is a workspace-scoped API key — NOT a user password and not a
+// service-role key. The server binds each key to a workspace agent identity, so
+// every request runs under the same row-level security as a human member.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { verbByName } from "./verbs.mjs";
+
+const CONFIG_PATH = join(homedir(), ".gsjos", "config.json");
+
+export function loadConfig() {
+  const fromFile = existsSync(CONFIG_PATH)
+    ? JSON.parse(readFileSync(CONFIG_PATH, "utf8"))
+    : {};
+  return {
+    // Environment wins over the file: a droplet gets its credentials injected,
+    // a laptop gets them from `gsjos login`.
+    apiUrl: process.env.GSJOS_API_URL || fromFile.apiUrl || "http://localhost:3000",
+    apiKey: process.env.GSJOS_API_KEY || fromFile.apiKey || "",
+    workspace: process.env.GSJOS_WORKSPACE || fromFile.workspace || "",
+  };
+}
+
+export function saveConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+  return CONFIG_PATH;
+}
+
+export const configPath = () => CONFIG_PATH;
+
+export class GsjosError extends Error {
+  constructor(message, status, code = null, details = null) {
+    super(message);
+    this.status = status;
+    /** The API's stable machine-readable code — `insufficient_scope`,
+     *  `rate_limited`, `invalid_value`. Branch on this, never on the message. */
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/** One HTTP call against /api/v1. Throws GsjosError with the server's own
+ *  message — the API returns useful errors (e.g. which status values are legal),
+ *  and swallowing them would defeat the guardrail design.
+ *
+ *  Pass `{ raw: true }` to get the whole envelope including `next_cursor`,
+ *  rather than just `data`.
+ *
+ *  `idempotencyKey` is forwarded as the `Idempotency-Key` header. The API
+ *  replays the original response for 24h rather than re-running the handler, so
+ *  a script that creates a TAM can be re-run without creating a second one. */
+export async function call(config, { method, path, query, body }, { raw = false, idempotencyKey } = {}) {
+  if (!config.apiKey) {
+    throw new GsjosError("No API key. Run `gsjos login`, or set GSJOS_API_KEY.", 401);
+  }
+
+  const url = new URL(`/api/v1${path}`, config.apiUrl);
+  if (config.workspace) url.searchParams.set("workspace", config.workspace);
+  for (const [k, v] of Object.entries(query ?? {})) {
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  }
+
+  // Strip undefined so a PATCH never sends a field the caller did not name —
+  // the API distinguishes "absent" from "set to null".
+  const payload = body
+    ? Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined))
+    : undefined;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(payload ? { "Content-Type": "application/json" } : {}),
+        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+      },
+      body: payload ? JSON.stringify(payload) : undefined,
+    });
+  } catch (e) {
+    throw new GsjosError(`Could not reach ${config.apiUrl}: ${e.message}`, 0);
+  }
+
+  const text = await res.text();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+
+  if (!res.ok) {
+    // The error shape is `{ error: { code, message, details? } }`. Older
+    // deployments returned a bare string, so both are accepted — a CLI that
+    // printed "[object Object]" against a server one version behind would be a
+    // uniquely unhelpful failure.
+    const err = json?.error;
+    const message = typeof err === "string" ? err : err?.message ?? text ?? `HTTP ${res.status}`;
+    const code = typeof err === "object" && err ? err.code ?? null : null;
+    const details = typeof err === "object" && err ? err.details ?? null : null;
+
+    if (res.status === 429) {
+      const wait = res.headers.get("retry-after");
+      throw new GsjosError(wait ? `${message} (retry after ${wait}s)` : message, 429, code ?? "rate_limited", details);
+    }
+    throw new GsjosError(message, res.status, code, details);
+  }
+
+  if (raw) return json ?? {};
+
+  // An envelope always carries `data`, and `data: null` is a real answer — an
+  // empty queue. Falling back to `?? json` there returns the envelope itself,
+  // which is truthy, so "nothing to do" reads as work and the caller acts on a
+  // command that does not exist. Check for the key, not the value.
+  if (json && typeof json === "object" && "data" in json) return json.data;
+  return json;
+}
+
+/** Walk every page of a list endpoint and return the rows as one array.
+ *
+ *  Keyset pagination means this is exact: no row is skipped or repeated even
+ *  while the workspace is being written to underneath the walk. That is the
+ *  whole reason `--all` can be offered at all. */
+export async function walkAll(config, verb, args) {
+  // `--limit` becomes the page size rather than a cap: with `--all` the caller
+  // has already said they want everything, so the only thing left for limit to
+  // mean is how much to fetch at a time. Default to the server's maximum —
+  // fewer, larger pages is strictly cheaper for a full walk.
+  const pageSize = Number(args.limit) > 0 ? Number(args.limit) : 200;
+  const rows = [];
+  let cursor;
+  let seen = 0;
+
+  for (;;) {
+    const page = await call(config, verb.request({ ...args, cursor, limit: pageSize }), { raw: true });
+    const batch = Array.isArray(page?.data) ? page.data : [];
+    rows.push(...batch);
+
+    const next = page?.next_cursor ?? null;
+    if (!next) return rows;
+    // A cursor that does not advance would loop forever and quietly eat the
+    // machine's memory. It can only mean a server bug, so say so rather than
+    // hanging.
+    if (next === cursor) {
+      throw new GsjosError(`${verb.name}: the server returned the same cursor twice — stopping after ${rows.length} rows.`, 500);
+    }
+    cursor = next;
+
+    if (++seen > 10000) {
+      throw new GsjosError(`${verb.name}: stopped after 10000 pages. Narrow the query.`, 500);
+    }
+  }
+}
+
+/** Run a verb by name. The single execution path both faces share. */
+export async function runVerb(config, name, args, { idempotencyKey } = {}) {
+  const verb = verbByName(name);
+  if (!verb) throw new GsjosError(`Unknown verb '${name}'.`, 400);
+
+  for (const [argName, spec] of Object.entries(verb.args)) {
+    if (spec.required && (args[argName] === undefined || args[argName] === "")) {
+      throw new GsjosError(`${name}: '${argName}' is required (${spec.desc}).`, 400);
+    }
+  }
+
+  if (verb.paginated && (args.all === true || args.all === "true")) {
+    const { all: _all, ...rest } = args;
+    return walkAll(config, verb, rest);
+  }
+  return call(config, verb.request(args), { idempotencyKey });
+}

package/src/daemon.mjs

@@ -0,0 +1,333 @@
+// The daemon face — what makes agents able to run longer than an HTTP request.
+//
+// The OS is deployed serverless. A route handler cannot hold a WebSocket open,
+// cannot outlive its timeout, and has no fixed egress IP to allowlist at a
+// tenant's firewall. So the OS never dials into the box. It enqueues work, and
+// this process — running ON the box, next to the runtime — claims it over a
+// connection it opens outbound.
+//
+// The consequences are the point: a tenant box needs no public hostname, no
+// certificate, no exposed admin port, and works behind NAT. The only credential
+// it holds is a workspace API key, which is RLS-scoped to that one workspace.
+
+import { hostname } from "node:os";
+import { readFileSync } from "node:fs";
+import { call, GsjosError } from "./client.mjs";
+import { executeCommand } from "./runtime.mjs";
+
+const GATEWAY_URL = process.env.OPENCLAW_GATEWAY_URL || "ws://127.0.0.1:18789";
+const GATEWAY_TOKEN = process.env.OPENCLAW_GATEWAY_TOKEN || "";
+
+/** Deltas are batched before being written. Realtime fans out every UPDATE, so
+ *  a write per token would be pure amplification for no perceptible gain. */
+const FLUSH_MS = 400;
+/** Quiet gap after the last token that counts as end-of-turn, when the gateway
+ *  sends no explicit completion marker. Reported so it can be retired. */
+const QUIET_GAP_MS = 5_000;
+const FIRST_TOKEN_TIMEOUT_MS = 180_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const log = (...a) => console.log(new Date().toISOString(), ...a);
+
+function requireWebSocket() {
+  if (typeof WebSocket === "undefined") {
+    throw new Error("This Node build has no global WebSocket. Node 22+ is required for `gsjos daemon`.");
+  }
+}
+
+function connectParams(token) {
+  // `webchat` mode demands a browser Origin allowlist; a backend process must
+  // identify as `backend` or the gateway refuses the handshake.
+  return {
+    minProtocol: 3,
+    maxProtocol: 4,
+    client: { id: "gateway-client", version: "0.2.0", platform: "node", mode: "backend" },
+    // `id` is validated against a fixed allowlist by the gateway; "gateway-client"
+    // is the accepted value for a backend client. A custom string is rejected with
+    // "invalid connect params: at /client/id".
+    role: "operator",
+    scopes: ["operator.read", "operator.write"],
+    auth: { token },
+    userAgent: "gsjos-daemon/0.2.0",
+  };
+}
+
+/** Run one turn against the local gateway, streaming deltas to `onDelta`.
+ *  Resolves with { output, endReason }; rejects on protocol or auth failure. */
+function runTurn({ sessionKey, message, onDelta }) {
+  requireWebSocket();
+  if (!GATEWAY_TOKEN) throw new Error("OPENCLAW_GATEWAY_TOKEN is not set");
+
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(GATEWAY_URL);
+    let output = "";
+    let sawReply = false;
+    let settled = false;
+    let connectId = "", sendId = "", createId = "";
+    let triedCreate = false;
+    let quietTimer = null;
+
+    const finish = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      if (quietTimer) clearTimeout(quietTimer);
+      try { ws.close(); } catch { /* already closing */ }
+      fn(arg);
+    };
+    const done = (endReason) => finish(resolve, { output, endReason });
+    const fail = (msg) => finish(reject, new Error(msg));
+
+    const arm = () => {
+      if (quietTimer) clearTimeout(quietTimer);
+      quietTimer = setTimeout(
+        () => (sawReply ? done("quiet-gap") : fail("the agent produced no output in time")),
+        sawReply ? QUIET_GAP_MS : FIRST_TOKEN_TIMEOUT_MS,
+      );
+    };
+
+    const rpc = (method, params) => {
+      const id = crypto.randomUUID();
+      ws.send(JSON.stringify({ type: "req", id, method, params }));
+      return id;
+    };
+
+    ws.onopen = () => { connectId = rpc("connect", connectParams(GATEWAY_TOKEN)); };
+
+    ws.onmessage = (raw) => {
+      let f;
+      try { f = JSON.parse(String(raw.data)); } catch { return; }
+
+      if (f.type === "res" && f.id === connectId) {
+        if (f.ok === false) {
+          // The gateway distinguishes "wrong token" from "not ready yet" and
+          // says which. A restart answers UNAVAILABLE/retryable with a suggested
+          // delay; treating that as a permanent failure burns a run for a
+          // condition that clears in seconds.
+          const e = f.error ?? {};
+          const err = new Error("gateway rejected the token: " + JSON.stringify(e));
+          err.retryable = e.retryable === true || e.code === "UNAVAILABLE";
+          err.retryAfterMs = Number(e.retryAfterMs) || 1000;
+          return finish(reject, err);
+        }
+        sendId = rpc("sessions.send", { key: sessionKey, message });
+        return arm();
+      }
+
+      if (f.type === "res" && f.id === sendId) {
+        if (f.ok === false) {
+          const detail = JSON.stringify(f.error ?? {});
+          if (!triedCreate && /session not found/i.test(detail)) {
+            triedCreate = true;
+            createId = rpc("sessions.create", { key: sessionKey });
+            return;
+          }
+          return fail("sessions.send failed: " + detail);
+        }
+        // A success response after tokens have streamed marks completion;
+        // before any token it is only an ack.
+        if (sawReply) done("send-response");
+        return;
+      }
+
+      if (f.type === "res" && f.id === createId) {
+        if (f.ok === false) return fail("sessions.create failed: " + JSON.stringify(f.error ?? {}));
+        sendId = rpc("sessions.send", { key: sessionKey, message });
+        return arm();
+      }
+
+      if (f.type !== "event" || !f.payload) return;
+      const p = f.payload;
+
+      if (f.event === "chat") {
+        if (typeof p.deltaText === "string" && p.deltaText.length > 0) {
+          sawReply = true;
+          output = p.replace === true ? p.deltaText : output + p.deltaText;
+          onDelta(output);
+        }
+        if (p.final === true || p.done === true || p.complete === true) return done("final-event");
+        return arm();
+      }
+
+      if ((f.event === "session" || f.event === "sessions.state") && sawReply) {
+        if (p.state === "idle" || p.status === "idle" || p.busy === false) done("idle-event");
+      }
+    };
+
+    ws.onerror = () => fail("gateway unreachable at " + GATEWAY_URL);
+    ws.onclose = () => (sawReply ? done("socket-close") : fail("gateway closed before replying"));
+  });
+}
+
+/** Claim one management command and execute it. Returns true if work was done.
+ *
+ *  Commands are drained BEFORE runs each tick, deliberately: a sync that
+ *  installs or repairs an agent should land before the next turn is handed to
+ *  that agent, or the turn runs against a definition the OS already replaced. */
+async function processCommand(config, instanceId, { reap = false } = {}) {
+  const cmd = await call(config, {
+    method: "POST", path: "/runtime/claim",
+    body: { claimedBy: instanceId, reap },
+  });
+  if (!cmd) return false;
+
+  let result, failure = null;
+  try {
+    result = await executeCommand(config, cmd);
+    if (result?.error) failure = result.error;
+  } catch (e) {
+    failure = e.message;
+  }
+
+  await call(config, {
+    method: "PATCH", path: "/runtime/" + cmd.id,
+    body: { status: failure ? "failed" : "done", result: result ?? null, error: failure },
+  }).catch(() => { /* the reaper will requeue it */ });
+
+  log(failure
+    ? "command " + String(cmd.id).slice(0, 8) + " failed: " + failure
+    : "command " + String(cmd.id).slice(0, 8) + " done");
+  return true;
+}
+
+/** Claim one run and execute it. Returns true if work was done. */
+async function processOne(config, instanceId, { reap = false } = {}) {
+  const claimed = await call(config, {
+    method: "POST", path: "/runs/claim",
+    body: { claimedBy: instanceId, runtime: "openclaw", reap },
+  });
+  if (!claimed?.run) return false;
+
+  const { run, agent } = claimed;
+  const label = agent?.slug ?? String(run.agent_id ?? "").slice(0, 8) ?? "agent";
+  log("run " + run.id.slice(0, 8) + " -> " + label);
+
+  const sessionKey = sessionKeyForRun(run, agent, config.workspace);
+
+  let lastFlush = 0;
+  let lastWritten = "";
+  const flush = async (text, force) => {
+    const now = Date.now();
+    if (!force && (now - lastFlush < FLUSH_MS || text === lastWritten)) return;
+    lastFlush = now;
+    lastWritten = text;
+    try {
+      await call(config, { method: "PATCH", path: "/runs/" + run.id, body: { output: text } });
+    } catch (e) {
+      // A dropped progress write must not kill the turn; the final write retries.
+      log("  ! progress write failed: " + e.message);
+    }
+  };
+
+  try {
+    // A gateway that is mid-restart refuses with retryable=true and a suggested
+    // delay. Wait it out rather than failing the run — bounded, so a gateway
+    // that never comes up still surfaces as a failure instead of hanging.
+    let attempt = 0;
+    const turn = async () => {
+      for (;;) {
+        try {
+          return await runTurn({ sessionKey, message: run.input, onDelta: (t) => { void flush(t, false); } });
+        } catch (e) {
+          if (!e.retryable || ++attempt > 6) throw e;
+          log("  gateway not ready, retrying in " + e.retryAfterMs + "ms (" + attempt + "/6)");
+          await sleep(e.retryAfterMs);
+        }
+      }
+    };
+    const { output, endReason } = await turn();
+    await call(config, {
+      method: "PATCH", path: "/runs/" + run.id,
+      body: { status: "done", output, endReason },
+    });
+    log("done " + run.id.slice(0, 8) + " (" + output.length + " chars, ended by " + endReason + ")");
+  } catch (e) {
+    await call(config, {
+      method: "PATCH", path: "/runs/" + run.id,
+      body: { status: "failed", error: e.message },
+    }).catch(() => { /* the reaper will requeue it */ });
+    log("failed " + run.id.slice(0, 8) + ": " + e.message);
+  }
+  return true;
+}
+
+/** The loop. Polls for queued work; backs off when the queue is empty so an
+ *  idle tenant costs almost nothing, and drains greedily when it is not. */
+/** The package's own version, read rather than restated.
+ *
+ *  The worker is started as `npx -y gsjos daemon`, with no version
+ *  pinned — so "which build is actually running on the box" is a real question
+ *  with no other way to answer it. Printing it on startup makes `docker logs`
+ *  the answer. Falls back rather than throwing: an unreadable package.json is
+ *  not a reason to refuse to run. */
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+/** Which conversation this run belongs to.
+ *
+ *  A chat run arrives with a key already set by the OS, because that is a human
+ *  conversation and continuity is the whole point of it. Everything else — cron,
+ *  webhook, event, manual — gets a session of its own, keyed by the run.
+ *
+ *  Falling back to one session per TRIGGER TYPE looked harmless and was not: a
+ *  daily cron appends to the same session every morning, so after a month the
+ *  agent starts its run carrying twenty-nine previous ones. Context grows
+ *  without bound, every turn gets slower and dearer, and what the agent does
+ *  today quietly depends on what it saw last week. Observed directly — five
+ *  unrelated probe runs, and the agent listed all five back in order.
+ *
+ *  The OS is the memory. An agent reads the person, the thread and the pipeline
+ *  through gsjos at run time rather than remembering them, so a fresh session
+ *  loses nothing that matters and costs less. */
+export function sessionKeyForRun(run, agent, workspace) {
+  if (run.session_key) return run.session_key;
+  return "agent:" + (agent?.slug ?? "main") + ":" + (workspace || "ws")
+    + "-" + run.trigger_type + "-" + run.id;
+}
+
+export async function startDaemon(config, { pollMs = 2000, maxIdleMs = 15000 } = {}) {
+  const instanceId = hostname() + "-" + process.pid;
+  let stopping = false;
+  let idleFor = pollMs;
+
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      if (stopping) process.exit(1);
+      stopping = true;
+      log(sig + " - finishing the current run, then stopping.");
+    });
+  }
+
+  log("gsjos daemon v" + VERSION + "  " + instanceId);
+  log("  os:      " + config.apiUrl + "  (workspace: " + (config.workspace || "default") + ")");
+  log("  gateway: " + GATEWAY_URL);
+  if (!GATEWAY_TOKEN) log("  ! OPENCLAW_GATEWAY_TOKEN is not set - turns will fail");
+
+  let first = true;
+  while (!stopping) {
+    try {
+      // The first claim also reaps runs abandoned by a previous instance.
+      // Management first, then a turn. Both share one poll so an idle host
+      // makes one request per tick rather than two.
+      const didCommand = await processCommand(config, instanceId, { reap: first });
+      const didRun = didCommand ? false : await processOne(config, instanceId, { reap: first });
+      const worked = didCommand || didRun;
+      first = false;
+      idleFor = worked ? pollMs : Math.min(idleFor * 1.5, maxIdleMs);
+      if (!worked) await sleep(idleFor);
+    } catch (e) {
+      const status = e instanceof GsjosError ? e.status : 0;
+      if (status === 401 || status === 403) {
+        log("fatal: " + e.message);
+        process.exit(1);
+      }
+      log("poll error: " + e.message);
+      await sleep(Math.min(idleFor * 2, maxIdleMs));
+    }
+  }
+  log("stopped.");
+}

package/src/mcp.mjs

@@ -0,0 +1,140 @@
+// MCP server (stdio) — the second face over the same verbs.
+//
+// Newline-delimited JSON-RPC 2.0 on stdin/stdout, implemented directly so the
+// package stays dependency-free: an agent droplet can `npx gsjos mcp`
+// with nothing else installed, and there is no SDK version to drift.
+//
+// IMPORTANT: stdout is the protocol channel. Anything written to it that is not
+// a JSON-RPC message corrupts the stream, so all diagnostics go to stderr.
+
+import { readFileSync } from "node:fs";
+import { VERBS, toolName, verbByToolName } from "./verbs.mjs";
+import { runVerb, GsjosError } from "./client.mjs";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+/** Read the real version rather than restating it here, where it went stale at
+ *  0.2.0 while the package shipped 0.4.x. A client that reports the server
+ *  version in a bug report should not be reporting fiction. Falls back rather
+ *  than throwing: an unreadable package.json is not a reason to refuse to run. */
+const version = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const SERVER_INFO = { name: "gsjos", version };
+
+/** JSON Schema for a verb's arguments, from the same arg specs the CLI parses. */
+function inputSchema(verb) {
+  const properties = {};
+  const required = [];
+  for (const [name, spec] of Object.entries(verb.args)) {
+    properties[name] = spec.type === "list"
+      ? { type: "array", items: { type: "string" }, description: spec.desc }
+      // `objects` is how a caller sends MANY rows in one call. An agent asked to
+      // save fifty companies should make one tool call, not fifty — fifty is
+      // slow, and it is fifty chances to lose track half way.
+      : spec.type === "objects"
+      ? { type: "array", items: { type: "object", additionalProperties: true }, description: spec.desc }
+      : { type: spec.type === "number" ? "number" : "string", description: spec.desc };
+    if (spec.required) required.push(name);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+const toolList = () => VERBS.map((verb) => ({
+  name: toolName(verb),
+  description: verb.summary,
+  inputSchema: inputSchema(verb),
+  annotations: { readOnlyHint: verb.kind === "read" },
+}));
+
+export function startMcpServer(config) {
+  const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+  async function handle(msg) {
+    const { id, method, params } = msg;
+    // Notifications carry no id and must not be answered.
+    const isNotification = id === undefined || id === null;
+
+    switch (method) {
+      case "initialize":
+        return reply(id, {
+          // Echo the client's protocol version when we can speak it, so a
+          // client pinned to an older revision still negotiates cleanly.
+          protocolVersion: params?.protocolVersion ?? PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: SERVER_INFO,
+          instructions:
+            "Operate a gsjmedia OS workspace. Call `schema` first — it returns the status vocabularies, "
+            + "legal pipeline stages, and writable fields for this workspace. Promotion from person to lead "
+            + "is automatic: log an inbound interaction rather than creating a lead. Illegal status values "
+            + "are rejected by the database, and the error names the legal set.",
+        });
+
+      case "notifications/initialized":
+      case "notifications/cancelled":
+        return;
+
+      case "ping":
+        return reply(id, {});
+
+      case "tools/list":
+        return reply(id, { tools: toolList() });
+
+      case "tools/call": {
+        const verb = verbByToolName(params?.name);
+        if (!verb) return fail(id, -32602, `Unknown tool '${params?.name}'`);
+        try {
+          const data = await runVerb(config, verb.name, params?.arguments ?? {});
+          return reply(id, {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            structuredContent: data && typeof data === "object" && !Array.isArray(data) ? data : undefined,
+          });
+        } catch (e) {
+          // A failed tool call is a RESULT with isError, not a protocol error —
+          // the agent needs to read the message and correct itself. The API's
+          // errors name the legal values, which is exactly what it needs.
+          return reply(id, {
+            content: [{ type: "text", text: e instanceof GsjosError ? e.message : String(e?.message ?? e) }],
+            isError: true,
+          });
+        }
+      }
+
+      default:
+        if (isNotification) return;
+        return fail(id, -32601, `Method '${method}' is not supported`);
+    }
+  }
+
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+        continue;
+      }
+      handle(msg).catch((e) => {
+        if (msg.id !== undefined && msg.id !== null) fail(msg.id, -32603, String(e?.message ?? e));
+      });
+    }
+  });
+
+  process.stdin.on("end", () => process.exit(0));
+  process.stderr.write(`gsjos mcp — ${VERBS.length} tools, workspace '${config.workspace || "(default)"}' at ${config.apiUrl}\n`);
+}