subscription-gateway 0.1.0

package/README.md

@@ -0,0 +1,244 @@
+# subscription-gateway — run the platform on a subscription instead of per-token billing
+
+A system service: it takes a request from the platform (or from any other host),
+drives the model loop through the vendor's official SDK on **subscription**
+access, and streams the answer back.
+
+The subscription token lives in **one** place on the machine. Agents do not know
+it — they know the address of an entry point.
+
+---
+
+## What it gives you
+
+- the model loop runs on a subscription instead of per-token billing;
+- the secret does not multiply across the machine: one file, group permissions,
+  rotation in one place;
+- a new agent is connected by a line of configuration, without copying the secret;
+- platform tools can be mixed into the model's tool set through the bridge (see
+  `dsh-tool-bridge`).
+
+---
+
+## When you do NOT need this
+
+**If you have an ordinary API key, you do not need it at all.** The platform can
+reach the provider by itself, and an extra process between it and the vendor only
+adds places where something can go quiet.
+
+The gateway is for the case where access is by **subscription** and the host knows
+nothing about that kind of access.
+
+**And one more case where it is not needed: if you have a single agent.** The
+whole point of moving the token out is that there are several agents. With one, it
+is simpler to keep the secret next to it.
+
+---
+
+## 🔴 The main thing to know before installing: whose hands the agent works with
+
+The SDK is **agentic**. It drives the loop itself and itself runs the shell,
+files, search and web.
+
+So the agent's "hands" are the user the **gateway process** runs as, not the user
+the platform runs as. Everything else follows from that:
+
+- the service is started as **one instance per agent**
+  (`gateway@<agent name>.service`), under that agent's own user name and on its
+  own port;
+- a shared system user does not fit here structurally: it has no access to the
+  agent's home, and every agent on the machine would act as one and the same
+  person;
+- **any right you give to the agent's hands is given to THIS unit.** The
+  platform's rights are beside the point.
+
+That last one is not theory. We lost a work session to it: we gave the agent the
+right to read the system journal, wrote it into the platform's unit, verified it
+against the platform's live process — everything checked out, and the agent's
+refusal stayed. **A right method applied to the wrong object yields confidence,
+not truth.** What must be checked is the process that executes the commands:
+
+```bash
+grep ^Groups: /proc/$(systemctl show -p MainPID --value gateway@<agent>.service)/status
+```
+
+🔴 `id` and `sudo -u <agent>` do **not answer this question**: they spawn a NEW
+process, which takes its groups from the system file, and will show what you want
+rather than what is. A live process fixes its group set when it starts.
+
+---
+
+## Installation
+
+### 0. The code and its dependencies
+
+```bash
+sudo mkdir -p /opt/subscription-gateway
+cd /opt/subscription-gateway
+npm install subscription-gateway            # or copy this package here
+```
+
+The unit template below starts `/opt/subscription-gateway/gateway.mjs`. Put the
+code somewhere else and you have three places to change, all named in the
+comment at the top of the unit file.
+
+**Sign of success:** `node -e "import('./gateway.mjs')"` exits without
+`ERR_MODULE_NOT_FOUND`. The two runtime dependencies — the vendor agent SDK and
+the schema library — must resolve from the directory the unit starts the file
+in; `NODE_PATH` does **not** help here, ES modules ignore it.
+
+### 1. The token in one place, permissions by group
+
+```bash
+sudo groupadd -r gateway-token
+sudo install -d -m 750 -o root -g gateway-token /etc/subscription-gateway
+sudo install -m 640 -o root -g gateway-token /dev/null /etc/subscription-gateway/token
+# put the subscription token into the file
+```
+
+**Sign of success:** the file is readable by a member of the group and not
+readable by anyone else.
+
+🔴 Isolation of the secret is real only against agents **without** `sudo`. An
+agent with `sudo` will read the file anyway — do not imagine a protection that is
+not there.
+
+### 2. The unit template
+
+Install `systemd/gateway@.service` (in this package) and create an instance:
+
+```bash
+sudo systemctl enable --now gateway@<agent>.service
+```
+
+**Sign of success:**
+
+```bash
+curl -s http://127.0.0.1:<port>/health
+{"ok":true,"token":"present","sdk":true}
+```
+
+🔴 Health means the **presence of the secret**, not "the process is alive".
+Without a token the service is up and useless — that must be visible from
+outside, which is why it answers 503 rather than 200.
+
+### 3. The instance environment
+
+`/etc/subscription-gateway/instance-<agent>.env`:
+
+```
+GATEWAY_PORT=<instance port>
+GATEWAY_WORK_DIR=/home/<agent>/workspace
+GATEWAY_MAX_TURNS=120
+GATEWAY_MCP={"<server name>":{"type":"http","url":"http://127.0.0.1:PORT/mcp"}}
+```
+
+| variable | what it sets | default |
+|---|---|---|
+| `GATEWAY_PORT` | loopback port | 8788 |
+| `GATEWAY_TOKEN_FILE` | token file | set by the unit |
+| `GATEWAY_WORK_DIR` | working directory for the tools | `$HOME`, else `/tmp` |
+| `GATEWAY_MAX_TURNS` | upper turn limit within one request | 60 |
+| `GATEWAY_MCP` | external MCP servers, JSON | empty (not an error) |
+
+🔴 **Raise `GATEWAY_MAX_TURNS` deliberately.** We hit it on the 61st turn of a
+long task, and the SDK reported it as `exited with code N` — that is, a code
+without a reason. The gateway now digs the real reason out of the transcript and
+prints `the agent hit the turn limit: reached <N> against a threshold of <M>`, and
+if it does not find it, says "reason not established" instead of a plausible
+invention.
+
+### 4. Check that the subscription answers
+
+Send a short request to `POST /v1/agent-stream` and wait for the model's answer.
+
+**Sign of success:** a stream with text arrived. **Sign of trouble:** every call
+is rejected by a rate limit while the subscription is demonstrably healthy — see
+the next section, that is not about your quota.
+
+---
+
+## 🔴 Why the vendor SDK inside, and not hand-rolled HTTP
+
+The first version assembled the API request by hand: subscription token, the
+required beta flags pulled out of the client binary. **Authorisation worked** — a
+wrong token got 401, ours got 429 — but **every** call was rejected by a rate
+limit while the subscription was entirely healthy: three agents were working on it
+at that very moment.
+
+We went through and discarded four hypotheses: client headers, model binding,
+token expiry, the set of beta flags. The truth was something else — **the raw path
+is simply not served to subscription access**. Same token, same machine, same
+network egress: the SDK answers in four seconds, the hand-rolled request is
+refused.
+
+The general conclusion, and it is worth more than the case itself: **do not
+reinvent the vendor's protocol.** Vendor code knows subtleties that are not in the
+documentation, and it will survive them changing. And a refusal that looks like
+"you are out of quota" may mean "you are knocking at the wrong door".
+
+---
+
+## What does not work, and will not
+
+- **it is never exposed outward.** It listens on loopback only. This is access to
+  the subscription without a password; moving it to an external address is the
+  same as publishing the token;
+- **no confirmations are requested** (`bypassPermissions`): there is nobody to
+  ask, the far end is not a human but the host. The real boundary is the rights of
+  the instance user, and they are set in systemd, not here;
+- **the unit sandbox is deliberately not tightened**: the agent needs its own
+  files and home, and against an agent with `sudo` the unit's restrictions are no
+  boundary anyway;
+- **the gateway does not know what tools it is handing over.** It receives their
+  description from the bridge and proxies the calls back. That is on purpose: the
+  next agent with a different set connects without editing the gateway.
+
+---
+
+## The schema adapter: a place where things are lost silently
+
+Tools arriving from the host are described by a JSON Schema, and the SDK expects a
+schema of its own kind. `jsonschema-to-zod.mjs` translates between them.
+
+🔴 **An unfamiliar shape is a silent loss, not a refusal.** The first version did
+not know the shape "string OR object" (`anyOf`/`oneOf`) and returned "anything" for
+it. The tool still registered, still looked healthy — and failed at call time,
+while parsing arguments.
+
+Test the adapter **against the real schemas of your platform**, not invented ones:
+
+```bash
+node test-schema-adapter.mjs
+```
+
+The bench in this package takes the schemas from a file generated by the platform
+itself and checks that both `anyOf` branches pass while a foreign type does **not**.
+The second half matters more than the first: a schema that has degenerated into
+"anything" lets everything through and thereby hides the error.
+
+---
+
+## Acceptance by your own hand
+
+1. `curl /health` → `{"ok":true,"token":"present","sdk":true}`. Checks that the
+   secret is readable.
+2. `grep ^Groups: /proc/<MainPID>/status` → the required groups **on the live
+   process**. Checks the rights of the agent's hands, and only this method answers
+   that question.
+3. A short request to `/v1/agent-stream` → the model answered. Checks the
+   subscription itself.
+4. `node test-schema-adapter.mjs` → everything green. Checks the schema adapter.
+5. If the bridge is installed alongside: ask the model to call a platform tool and
+   find the call in the host log. The model's answer is not a sign.
+
+🔴 **All five are usable as a run-through after an upgrade** — of the vendor SDK
+and of the platform alike. None of these desynchronisations fails with an error:
+the schema degenerates into "anything", the group is lost on restart, the token
+stays where it was but the path to it changes. All of it looks like healthy work.
+
+---
+
+## License
+
+MIT.

package/gateway.mjs

@@ -0,0 +1,430 @@
+/**
+ * Anthropic subscription gateway — a shared system service of the machine.
+ *
+ * WHY. There are several agents on the machine, each under its own user. If
+ * every one of them kept the subscription token, the secret would multiply
+ * across the machine. Here it lives in ONE place, under its own user, and the
+ * agents get an entry point. A new agent is connected by a line of
+ * configuration and knows nothing about the token.
+ *
+ * 🔴 WHY THE OFFICIAL SDK INSIDE AND NOT HAND-ROLLED HTTP (lesson of 2026-08-19).
+ * At first the gateway assembled the API request by hand: subscription token,
+ * two beta flags pulled out of the client binary. Authorisation worked (a wrong
+ * token got 401, ours got 429), but EVERY call was rejected by a rate limit
+ * while the subscription was entirely healthy: three agents were working on it
+ * at that very moment. We went through and discarded four hypotheses — client
+ * headers, model binding, token expiry, the set of beta flags. The truth was
+ * something else: the raw path is simply not served to subscription access. Same
+ * token, same machine, same network egress — the SDK answers in four seconds, a
+ * hand-rolled request is refused.
+ * The general conclusion: DO NOT REINVENT THE VENDOR'S PROTOCOL. Vendor code
+ * knows subtleties that are not in the documentation, and it will survive them
+ * changing.
+ *
+ * 🔴 INDEPENDENCE FROM ANY OTHER MACHINE. The SDK is installed HERE, the token is
+ * HERE, and the machine has its own network egress. No central node takes part
+ * in the chain and any such node may be switched off — a direct requirement of
+ * the owner, verified with a live call.
+ *
+ * BOUNDARIES. Listens on loopback only. It is never exposed outward: this is
+ * access to our subscription without a password.
+ *
+ * 🔴 THE ENGINE EXECUTES THE TOOLS, NOT THE PLATFORM — AND THE CHOICE OF USER
+ * FOLLOWS FROM THAT. The SDK is agentic: it drives the loop itself and itself
+ * runs the shell, files, search and web. So the agent's "hands" are the user
+ * THIS process runs as. That is why the service is started as an INSTANCE PER
+ * AGENT (`...@<agent name>.service`), under the agent's own user name and on its
+ * own port. A shared system user does not fit here structurally: it has no
+ * access to the agent's home, and every agent on the machine would act as one
+ * and the same person, treading on each other.
+ * What DOES stay shared: the token file — one per machine, no secret in the
+ * agent's configuration, rotation in one place.
+ * What you must NOT imagine: an agent with sudo will read the token file
+ * anyway. Isolation of the secret is real against agents WITHOUT sudo.
+ *
+ * THE RIGHTS BOUNDARY. No confirmations are requested (`bypassPermissions`):
+ * there is nobody here to ask, the far end is not a human but the platform. The
+ * real boundary is the rights of the instance user, and it is set in systemd,
+ * not here.
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+import { query, createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { shape } from './jsonschema-to-zod.mjs';
+
+const PORT = Number(process.env.GATEWAY_PORT || 8788);
+const HOST = '127.0.0.1';
+const TOKEN_FILE = process.env.GATEWAY_TOKEN_FILE || '/etc/subscription-gateway/token';
+const DEFAULT_MODEL = 'claude-opus-5';
+const DEFAULT_MAX_TURNS = Number(process.env.GATEWAY_MAX_TURNS || 60);
+/**
+ * External tool servers (MCP) for this instance's agent. Set through the
+ * GATEWAY_MCP variable as JSON: {"<server name>":{"type":"http","url":"..."}}.
+ * Empty — the agent works without them, and that is not an error.
+ */
+const MCP_SERVERS = (() => {
+  const raw = process.env.GATEWAY_MCP;
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(raw);
+    return v && Object.keys(v).length ? v : null;
+  } catch (e) {
+    // Ignoring this silently is not allowed: the agent would be left without
+    // memory, and it would look like "memory does not work" rather than "I wrote
+    // the line wrong".
+    console.error(`[subscription-gateway] 🔴 GATEWAY_MCP could not be parsed: ${e?.message}`);
+    return null;
+  }
+})();
+
+/** Default working directory for the tools — the instance user's home. */
+const WORK_DIR = process.env.GATEWAY_WORK_DIR || process.env.HOME || '/tmp';
+
+const log = (m) => console.error(`[subscription-gateway] ${m}`);
+
+/**
+ * "exited with code N" from the SDK is only a code without a reason; the truth
+ * is in the session transcript. We look for attachment.type == "max_turns_reached"
+ * and return a human-readable line with the numbers. Not found — the original
+ * text plus an explicit "reason not established", WITHOUT inventing a plausible
+ * one.
+ *
+ * 🔴 The strings matched here — 'exited with code', 'returned an error result',
+ * 'max_turns_reached' — are the SDK'S OWN wording and protocol constants. They
+ * are not ours to translate or prettify: change them and the match silently
+ * stops finding anything, leaving a code without a reason again.
+ */
+function explainExit(err, sessionId, cwd) {
+  const raw = String(err?.message ?? err);
+  if (!/(?:exited with code|returned an error result)/.test(raw)) return raw;
+  try {
+    const slug = cwd.replaceAll('/', '-');
+    const file = `${process.env.HOME || WORK_DIR}/.claude/projects/${slug}/${sessionId}.jsonl`;
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+      if (!line.includes('max_turns_reached')) continue;
+      const a = JSON.parse(line)?.attachment;
+      if (a?.type === 'max_turns_reached') {
+        return `the agent hit the turn limit: reached ${a.turnCount} against a threshold of ${a.maxTurns} (max_turns_reached)`;
+      }
+    }
+  } catch {
+    return `${raw} — reason not established (the transcript could not be read)`;
+  }
+  return `${raw} — reason not established (no max_turns_reached entry in the fresh transcript)`;
+}
+
+/** The token is read on EVERY request: rotating the secret needs no restart. */
+function readToken() {
+  try {
+    return fs.readFileSync(TOKEN_FILE, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** A short caption for a tool call: what exactly it does, in one line. */
+function briefOf(input) {
+  if (!input || typeof input !== 'object') return '';
+  const v = input.command ?? input.file_path ?? input.pattern ?? input.url ?? input.path ?? input.query;
+  return typeof v === 'string' ? v.slice(0, 200) : '';
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const parts = [];
+    req.on('data', (c) => parts.push(c));
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(parts).toString('utf8') || '{}'));
+      } catch (e) {
+        reject(e);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Assemble one text prompt out of the messages.
+ *
+ * A deliberate simplification: the SDK takes the prompt as a string. History is
+ * glued together with role labels — the model understands them, and the platform
+ * keeps its own history anyway. When there is time for it, real message passing
+ * will appear here instead of gluing.
+ *
+ * 🔴 THESE ROLE LABELS ARE MODEL-FACING TEXT, NOT DISPLAY TEXT. They go into the
+ * prompt, so changing them changes what the model reads. If your platform speaks
+ * another language, change them deliberately and together, not one of the two.
+ */
+function buildPrompt(messages) {
+  const parts = [];
+  for (const m of messages ?? []) {
+    const who = m.role === 'assistant' ? 'Assistant' : 'User';
+    const c = m.content;
+    const text =
+      typeof c === 'string'
+        ? c
+        : Array.isArray(c)
+          ? c.filter((b) => b?.type === 'text').map((b) => b.text).join('\n')
+          : '';
+    if (text) parts.push(`${who}: ${text}`);
+  }
+  return parts.join('\n\n');
+}
+
+/**
+ * THE PLATFORM TOOL BRIDGE.
+ *
+ * The engine executes the tools, so its own set is the only one the model sees.
+ * Platform plugins do not reach it at all. The bridge builds an MCP server out of
+ * the description sent by the platform and proxies the calls back.
+ *
+ * 🔴 THE GATEWAY DOES NOT KNOW WHAT THESE TOOLS ARE. Names, descriptions and
+ * schemas arrive from the other side; there is only transport here. The next
+ * agent with a different tool set connects without editing this file — that is
+ * what makes it a general solution rather than a patch for one case.
+ *
+ * TRANSPORT sdk, NOT stdio: an sdk server lives in this same process and spawns
+ * no child. Everything the SDK passes to a child process goes as the
+ * --mcp-config argument and is readable by any user of the machine through
+ * /proc/<pid>/cmdline (mode 444) — verified with a live observer on 2026-08-22.
+ * That is why the bridge TICKET does not leak with sdk: it stays in the memory of
+ * two processes and in the request body over loopback.
+ *
+ * 🔴 WHAT EXACTLY THE GATEWAY CARRIES. Not an identity and not a shared secret,
+ * but a ONE-TIME TICKET issued by the platform for this turn. The gateway does
+ * not know whose it is: there is not a single agent-identity field in this file,
+ * neither in the code nor in the comments (we deliberately avoid writing even the
+ * name of that field here: otherwise a grep check would find its own caveat and
+ * take it for an occurrence). The platform retrieves the identity by the ticket
+ * from its own table. So there is nothing here to assert somebody else's identity
+ * with — neither for the model nor for the gateway itself.
+ */
+function buildBridgeServer(bridge) {
+  if (!bridge?.url || !bridge?.ticket || !Array.isArray(bridge.tools) || !bridge.tools.length) return null;
+
+  // 🔴 THE GATEWAY DOES NOT KNOW WHOSE REQUEST THIS IS, AND MUST NOT. It carries
+  // an opaque one-time ticket issued by the platform for this turn and presents it
+  // at the door. The platform retrieves the identity by that ticket from its own
+  // table. The identity is NOT transmitted: whoever asserts it must not be the one
+  // who assigns it. The ticket lives in the CLOSURE of this handler — with the sdk
+  // transport it goes neither into a command line nor into the environment
+  // (measured: 0 hits across 275 inspected processes).
+  const callBridge = async (toolName, args) => {
+    const r = await fetch(bridge.url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-bridge-ticket': bridge.ticket },
+      body: JSON.stringify({ tool: toolName, args }),
+    });
+    if (!r.ok) throw new Error(`the bridge answered ${r.status}`);
+    const out = await r.json();
+    if (out?.ok !== true) throw new Error(String(out?.error ?? 'the bridge refused without a reason'));
+    return out.value;
+  };
+
+  const tools = [];
+  for (const t of bridge.tools) {
+    let inputShape;
+    try {
+      inputShape = shape(t.inputSchema ?? { type: 'object', properties: {} });
+    } catch (e) {
+      // A tool whose schema we cannot assemble is NOT exposed "as is": the model
+      // would get a tool with no parameter shape and would fail at execution
+      // time. The skip is loud, the rest keep working.
+      log(`🔴 tool ${t.name} skipped: ${e?.message}`);
+      continue;
+    }
+    tools.push(
+      tool(
+        t.name,
+        t.description ?? '',
+        inputShape,
+        async (args) => {
+          try {
+            const value = await callBridge(t.name, args ?? {});
+            return { content: [{ type: 'text', text: JSON.stringify(value ?? null) }] };
+          } catch (e) {
+            // The refusal is returned as text, not as an exception: the model
+            // must read the reason and decide what to do, not see the tool cut
+            // off. 🔴 This text is model-facing.
+            return { content: [{ type: 'text', text: `REFUSED: ${e?.message ?? e}` }], isError: true };
+          }
+        },
+      ),
+    );
+  }
+  if (!tools.length) return null;
+
+  // alwaysLoad: otherwise the tools go behind a catalogue search and are not
+  // visible in the system header — and the header is precisely our acceptance sign.
+  return createSdkMcpServer({ name: bridge.name || 'dsh', version: '0.1.0', tools, alwaysLoad: true });
+}
+
+/**
+ * Merge the tool servers WITHOUT letting the bridge overwrite somebody else's
+ * server with its own name.
+ *
+ * 🔴 THE NAMING RULE (2026-08-22): server names must not coincide — neither with
+ * ones already connected here, nor between the root and subagent levels. The
+ * price of a collision is silent, and it goes both ways:
+ *   * here a plain spread would overwrite a same-named server entirely, and the
+ *     model would get the bridge in its place without ever learning of it;
+ *   * for a subagent (experiment B, 2026-08-22) a server bearing THE ROOT'S NAME
+ *     comes up with its own environment yet the root's one answers anyway — from
+ *     the start-up alone it looks as if the configuration works.
+ * Therefore a collision means refusing to connect the bridge, not a quiet
+ * substitution: without the bridge the agent works worse, with a substituted
+ * server it works wrongly.
+ */
+function mergeMcpServers(base, bridgeName, bridgeServer) {
+  const servers = { ...(base ?? {}) };
+  if (!bridgeServer) return { servers, mounted: false, conflict: null };
+  if (Object.prototype.hasOwnProperty.call(servers, bridgeName)) {
+    return { servers, mounted: false, conflict: bridgeName };
+  }
+  servers[bridgeName] = bridgeServer;
+  return { servers, mounted: true, conflict: null };
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.url === '/health') {
+    const ok = Boolean(readToken());
+    res.writeHead(ok ? 200 : 503, { 'content-type': 'application/json' });
+    // Health means the PRESENCE OF THE SECRET, not "the process is alive":
+    // without a token the service is up but useless, and that must be visible
+    // from outside.
+    // 🔴 The `token` field is API SURFACE, not a log line: the README documents
+    // this exact response and acceptance step 1 compares against it. If you change
+    // the wording, change the README and anything scripted against it in the same
+    // pass — the HTTP status is the machine-readable part, this field is not.
+    res.end(JSON.stringify({ ok, token: ok ? 'present' : 'MISSING', sdk: true }));
+    return;
+  }
+
+  if (req.method !== 'POST' || req.url !== '/v1/agent-stream') {
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'unknown path; /v1/agent-stream and /health exist' }));
+    return;
+  }
+
+  const token = readToken();
+  if (!token) {
+    res.writeHead(503, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: { type: 'no_credential', message: 'no subscription token' } }));
+    log('🔴 request rejected: the token could not be read');
+    return;
+  }
+
+  let body;
+  try {
+    body = await readBody(req);
+  } catch {
+    res.writeHead(400, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: { type: 'bad_json', message: 'the request body could not be parsed' } }));
+    return;
+  }
+
+  // A stream of events as JSON lines: one line, one event. The format is our own
+  // and deliberately simple; translating it into the platform's protocol is the
+  // job of a module on the agent's side.
+  res.writeHead(200, {
+    'content-type': 'application/x-ndjson; charset=utf-8',
+    'cache-control': 'no-cache',
+  });
+  const send = (o) => res.write(JSON.stringify(o) + '\n');
+
+  const started = Date.now();
+  const cwd = body.cwd || WORK_DIR;
+  const sessionId = crypto.randomUUID(); // Node >=19; we run v24, the global exists
+
+  // The platform tool bridge: connected ONLY when the other side has sent a
+  // descriptor with a ticket. Without one the behaviour is exactly as before.
+  let bridgeServer = null;
+  try {
+    bridgeServer = buildBridgeServer(body.bridge);
+  } catch (e) {
+    // A failure to build the bridge must not bring down the request itself:
+    // without tools the agent works worse, but it works. Staying silent about it
+    // is not allowed.
+    log(`🔴 the bridge was not built: ${e?.message}`);
+  }
+  const bridgeName = body.bridge?.name || 'dsh';
+  const merged = mergeMcpServers(MCP_SERVERS, bridgeName, bridgeServer);
+  const mcpAll = merged.servers;
+  // The "connected" line is printed AFTER the merge and only on success: it is
+  // our acceptance sign, and it must not lie.
+  if (merged.mounted) log(`bridge connected: tools ${body.bridge.tools.length}, server "${bridgeName}" (the ticket carries the identity, the gateway does not know it)`);
+  else if (merged.conflict) log(`🔴 bridge NOT connected: the server name "${merged.conflict}" is already taken by another tool server`);
+  try {
+    const iter = query({
+      prompt: buildPrompt(body.messages),
+      options: {
+        model: body.model || DEFAULT_MODEL,
+        // A loop with tools: one turn is only enough for a conversation. We keep
+        // a limit so that a jammed agent does not spin forever, but a generous one.
+        maxTurns: Number(body.maxTurns) > 0 ? Number(body.maxTurns) : DEFAULT_MAX_TURNS,
+        permissionMode: 'bypassPermissions',
+        sessionId,
+        // 🔴 EXTERNAL TOOL SERVERS ARE CONNECTED HERE, NOT IN THE PLATFORM
+        // (2026-08-19, it cost an hour). The engine executes the tools, so its
+        // own set is the only one the agent sees. A client plugin on the platform
+        // side connects without errors, appears in the plugin set — and does not
+        // reach the agent at all: in this arrangement the platform is only a chassis.
+        ...(Object.keys(mcpAll).length ? { mcpServers: mcpAll } : {}),
+        ...(body.cwd ? { cwd: body.cwd } : { cwd: WORK_DIR }),
+        ...(body.system ? { systemPrompt: { type: 'preset', preset: 'claude_code', append: body.system } } : {}),
+        env: { ...process.env, CLAUDE_CODE_OAUTH_TOKEN: token },
+      },
+    });
+
+    let model = null;
+    for await (const m of iter) {
+      if (m.type === 'assistant') {
+        model = m.message?.model ?? model;
+        for (const b of m.message?.content ?? []) {
+          if (b.type === 'text') send({ type: 'text', text: b.text });
+          else if (b.type === 'thinking') send({ type: 'thinking', text: b.thinking });
+          // Tool work is emitted outward as an EVENT rather than as silence:
+          // otherwise a long stretch looks like a hang and the platform has
+          // nothing to show. The tool input is not forwarded in full — there can
+          // be secrets and megabytes in it; only the name and a short caption.
+          else if (b.type === 'tool_use') send({ type: 'tool', name: b.name, brief: briefOf(b.input) });
+        }
+        const u = m.message?.usage;
+        if (u) {
+          send({
+            type: 'usage',
+            inputTokens: u.input_tokens ?? 0,
+            outputTokens: u.output_tokens ?? 0,
+            cacheReadTokens: u.cache_read_input_tokens,
+            cacheWriteTokens: u.cache_creation_input_tokens,
+          });
+        }
+      }
+    }
+    send({ type: 'done', model, tookMs: Date.now() - started });
+  } catch (e) {
+    // The error is returned IN THE STREAM rather than as silence: a stream cut
+    // off without a reason reads as "the model went quiet", and the investigation
+    // starts from nothing.
+    const message = explainExit(e, sessionId, cwd);
+    log(`🔴 call failed: ${message}`);
+    send({ type: 'error', message: message.slice(0, 500) });
+  } finally {
+    res.end();
+  }
+});
+
+server.listen(PORT, HOST, () => {
+  log(`listening on ${HOST}:${PORT}; token from ${TOKEN_FILE}; engine — the official SDK`);
+  if (!readToken()) log('🔴 warning: the token is NOT readable right now, requests will be rejected');
+});
+
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => {
+    log(`${sig} received, shutting down`);
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 5000).unref();
+  });
+}

package/jsonschema-to-zod.mjs

@@ -0,0 +1,95 @@
+/**
+ * JSON Schema → zod raw shape. A minimal subset: exactly what zod.toJSONSchema
+ * produces on the platform's schemas.
+ *
+ * WHY. tool() from the SDK requires zod, and zod cannot travel over a wire. The
+ * platform hands the schema over as JSON Schema, and the gateway rebuilds zod
+ * from it.
+ *
+ * 🔴 THE BOUNDARY. An unknown type does NOT silently become "anything": such a
+ * substitution would give the model a tool with no parameter shape, and a failure
+ * would look like working. An unknown type is an exception, the tool is not
+ * exposed, and the gateway writes the reason.
+ */
+import { z } from 'zod'
+
+const node = (s, path) => {
+  if (!s || typeof s !== 'object') throw new Error(`${path}: empty schema`)
+  if (Array.isArray(s.enum)) {
+    if (!s.enum.every((v) => typeof v === 'string')) throw new Error(`${path}: the enum is not made of strings`)
+    return z.enum(s.enum)
+  }
+  // The platform's branded strings (SessionId, GoalId) are described as an
+  // intersection of "string AND unknown", and on the wire that is an allOf with
+  // an empty second member. We take the single typed member: zod has no empty
+  // schema, and the type must not be lost.
+  // A branching shape: this is how the platform describes a parameter that takes
+  // either a string or an object (schedule_create.at). Without this branch the
+  // adapter would not understand a node WITHOUT a type field and would refuse —
+  // and the gateway would then silently fail to expose the tool at all. The
+  // refusal would be loud in the gateway log and invisible to the model: the tool
+  // is simply absent.
+  // THE BOUNDARY: there must be at least two branches, and each must assemble on
+  // its own. One branch is not a choice but a typo; a branch that will not
+  // assemble is a loss of shape, that is, exactly what this whole file guards
+  // against.
+  const branches = Array.isArray(s.oneOf) ? s.oneOf : Array.isArray(s.anyOf) ? s.anyOf : undefined
+  if (branches) {
+    const kw = Array.isArray(s.oneOf) ? 'oneOf' : 'anyOf'
+    if (branches.length < 2) throw new Error(`${path}: ${kw} of ${branches.length} branch is not a choice`)
+    return z.union(branches.map((v, i) => node(v, `${path}|${kw}[${i}]`)))
+  }
+  if (Array.isArray(s.allOf)) {
+    const typed = s.allOf.filter((m) => m && typeof m === 'object' && m.type !== undefined)
+    if (typed.length !== 1) throw new Error(`${path}: allOf with ${typed.length} typed members is not supported`)
+    return node(typed[0], path)
+  }
+  switch (s.type) {
+    case 'string': return bounds(z.string(), s, 'length')
+    case 'number': return bounds(z.number(), s, 'value')
+    case 'integer': return bounds(z.number().int(), s, 'value')
+    case 'boolean': return z.boolean()
+    case 'array': return bounds(z.array(node(s.items, `${path}[]`)), s, 'length')
+    case 'object': return z.object(shape(s, path))
+    default: throw new Error(`${path}: type ${JSON.stringify(s.type)} is not supported`)
+  }
+}
+
+/**
+ * Value and length bounds. Without them the schema QUIETLY weakens: a positive
+ * number becomes any number, and the model sees a different contract from the one
+ * the platform will enforce. It will get a refusal at execution time, and the
+ * reason will be far from obvious.
+ */
+const bounds = (t, s, kind) => {
+  if (kind === 'value') {
+    if (typeof s.minimum === 'number') t = t.min(s.minimum)
+    if (typeof s.maximum === 'number') t = t.max(s.maximum)
+    if (typeof s.exclusiveMinimum === 'number') t = t.gt(s.exclusiveMinimum)
+    if (typeof s.exclusiveMaximum === 'number') t = t.lt(s.exclusiveMaximum)
+    return t
+  }
+  const min = s.minLength ?? s.minItems
+  const max = s.maxLength ?? s.maxItems
+  if (typeof min === 'number') t = t.min(min)
+  if (typeof max === 'number') t = t.max(max)
+  return t
+}
+
+export const shape = (schema, path = '$') => {
+  if (schema?.type !== 'object') throw new Error(`${path}: an object was expected`)
+  const required = new Set(schema.required ?? [])
+  const out = {}
+  for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+    let t = node(sub, `${path}.${key}`)
+    // THE ORDER MATTERS. optional() first, describe() second: the SDK's converter
+    // reads the description from the OUTER node, so with describe().optional() the
+    // parameter description is SILENTLY lost — the schema stays valid and the
+    // model does not see the explanation of an optional field. Verified with
+    // tools/list against a stub.
+    if (!required.has(key)) t = t.optional()
+    if (typeof sub.description === 'string') t = t.describe(sub.description)
+    out[key] = t
+  }
+  return out
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "subscription-gateway",
+  "version": "0.1.0",
+  "description": "Subscription gateway for DeepSeek Harness — runs the model loop through the vendor's official agent SDK, so the platform works on a subscription seat instead of a metered API key, with the token kept in one place on the machine.",
+  "type": "module",
+  "main": "gateway.mjs",
+  "files": [
+    "gateway.mjs",
+    "jsonschema-to-zod.mjs",
+    "schedule.json",
+    "test-schema-adapter.mjs",
+    "systemd",
+    "README.md"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "subscription",
+    "gateway",
+    "agent-sdk",
+    "mcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iia-arg/dsh-plugins.git",
+    "directory": "packages/subscription-gateway"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.238",
+    "zod": "^4.0.0"
+  }
+}

package/schedule.json

@@ -0,0 +1,81 @@
+[
+  {
+    "pkg": "dsh-schedule",
+    "name": "schedule_create",
+    "description": "Create one reminder in the current session. Supply a non-empty prompt and exactly one selector: a positive safe-integer after_seconds delay, at as a strict offset date-time or local date/time object, or safe-integer every_seconds of at least 300. Fixed-rate reminders stay creation-aligned, skip missed occurrences, and batch one latest occurrence per overdue rule. Delivery is session-local: the reminder runs on time only while this session is live and otherwise becomes overdue until the session is resumed.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "prompt": {
+          "type": "string",
+          "description": "Reminder content to present when the target becomes due."
+        },
+        "after_seconds": {
+          "type": "number",
+          "description": "Positive safe-integer delay in seconds."
+        },
+        "every_seconds": {
+          "type": "number",
+          "description": "Fixed-rate safe-integer interval in seconds, at least 300."
+        },
+        "at": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "date": {
+                  "type": "string"
+                },
+                "time": {
+                  "type": "string"
+                },
+                "time_zone": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "date",
+                "time",
+                "time_zone"
+              ]
+            }
+          ],
+          "description": "Absolute target as strict offset RFC 3339 or local date/time with an explicit IANA zone."
+        }
+      },
+      "required": [
+        "prompt"
+      ]
+    }
+  },
+  {
+    "pkg": "dsh-schedule",
+    "name": "schedule_list",
+    "description": "List every active reminder in the current session in creation order, including its exact id, UTC target, scheduled or overdue state, and session-local delivery mode.",
+    "parameters": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  {
+    "pkg": "dsh-schedule",
+    "name": "schedule_delete",
+    "description": "Delete one active reminder in the current session by the exact id returned by schedule_create or schedule_list. Unknown or already-finished ids return deleted false.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Exact session-local schedule id."
+        }
+      },
+      "required": [
+        "id"
+      ]
+    }
+  }
+]

package/systemd/60-journal-read.conf

@@ -0,0 +1,20 @@
+# 🔴 JOURNAL READ ACCESS FOR THE AGENT'S HANDS.
+#
+# WHY HERE AND NOT IN THE PLATFORM'S UNIT. The platform WRITES to the journal,
+# but the agent's commands are executed by the ENGINE — a descendant of THIS unit
+# (see the comment on User=%i in the main file). So the one who reads the journal
+# must be the one who executes, not the one who writes. Our first attempt added
+# the group to the platform: the method was right, the object was the neighbouring
+# one, and the refusal stayed.
+# The class: a right method applied to the wrong object yields confidence, not truth.
+#
+# 🔴 BOTH GROUPS ARE LISTED ON PURPOSE. The token group is set in the main unit and
+# gives the gateway access to the shared token file — losing it means cutting the
+# gateway off from the subscription. We write the full set explicitly instead of
+# relying on it being merged with the main unit.
+#
+# VERIFY BY THE LIVE PROCESS ONLY: grep ^Groups: /proc/<MainPID>/status.
+# `id` and `sudo -u` spawn a NEW process and will show what you want rather than
+# what is.
+[Service]
+SupplementaryGroups=gateway-token systemd-journal

package/systemd/gateway@.service

@@ -0,0 +1,34 @@
+# Subscription gateway — ONE INSTANCE PER AGENT.
+#
+# 🔴 %i is the agent's USER name, and that is not cosmetic: the SDK is agentic,
+# it runs the shell and files itself, so the agent's "hands" are the process of
+# THIS unit. Any right that must be given to the agent's hands is given here, and
+# NOT in the platform's unit. Verify by the live process only:
+# /proc/<MainPID>/status.
+#
+# The paths below follow the package name. If you change them, change them in
+# three places: EnvironmentFile, GATEWAY_TOKEN_FILE and ExecStart.
+[Unit]
+Description=Subscription gateway — agent instance %i
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# The engine executes the tools ITSELF, so the agent's "hands" are THIS user.
+User=%i
+Group=%i
+# Access to the shared token file and the engine directory is by group, not by a
+# copy of the secret.
+SupplementaryGroups=gateway-token
+EnvironmentFile=/etc/subscription-gateway/instance-%i.env
+Environment=GATEWAY_TOKEN_FILE=/etc/subscription-gateway/token
+ExecStart=/usr/local/bin/node /opt/subscription-gateway/gateway.mjs
+Restart=on-failure
+RestartSec=5
+# The sandbox here is DELIBERATELY not tightened: the agent needs its own files
+# and home, and for an agent with sudo the unit's restrictions are no boundary
+# anyway. The real boundary is the rights of the instance user.
+
+[Install]
+WantedBy=multi-user.target

package/test-schema-adapter.mjs

@@ -0,0 +1,61 @@
+// A bench for the schema adapter, taken FROM THE PACKAGE FILE. It checks exactly
+// what the adapter was fixed for: shapes that occur in the platform's schemas and
+// that the first version did not know — it lost them SILENTLY, returning z.any().
+import { shape } from './jsonschema-to-zod.mjs'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+let ok = 0, bad = 0
+const t = (name, cond, got) => {
+  if (cond) { ok++; console.log(`  ok   ${name}`) }
+  else { bad++; console.log(`  FAIL ${name}${got === undefined ? '' : ` — got ${JSON.stringify(got)}`}`) }
+}
+const passes = (z, v) => { const r = z.safeParse(v); return r.success }
+
+console.log('\n=== A. Real platform schedule schemas ===')
+// The schemas are taken from a file generated BY THE PLATFORM ITSELF: the path is
+// an argument, because what must be checked is your installation, not the one the
+// bench was written on.
+const SCHEDULE_FILE = process.argv[2] ?? `${dirname(fileURLToPath(import.meta.url))}/schedule.json`
+const SCHEDULE = JSON.parse(readFileSync(SCHEDULE_FILE, 'utf8'))
+for (const tool of SCHEDULE) {
+  const s = shape(tool.parameters)
+  t(`${tool.name}: the schema assembled, fields ${Object.keys(s).length}`, Object.keys(s).length > 0 || tool.name === 'schedule_list')
+}
+
+console.log('\n=== B. The oneOf shape — the reason the adapter was fixed ===')
+{
+  // at: a string OR an object — exactly what the platform hands over
+  const s = shape({
+    type: 'object',
+    properties: { at: { anyOf: [{ type: 'string' }, { type: 'object', properties: { date: { type: 'string' } }, required: ['date'] }] } },
+  })
+  t('the string branch passes', passes(s.at, '2026-08-23T10:00:00Z'))
+  t('the object branch passes', passes(s.at, { date: '2026-08-23' }))
+  t('a foreign type does NOT pass (it did not degenerate into any)', !passes(s.at, 42), s.at?._def?.typeName)
+}
+
+console.log('\n=== C. Required and optional ===')
+{
+  const s = shape({
+    type: 'object',
+    properties: { prompt: { type: 'string' }, after_seconds: { type: 'number' } },
+    required: ['prompt'],
+  })
+  t('required with no value — refused', !passes(s.prompt, undefined))
+  t('optional with no value — passes', passes(s.after_seconds, undefined))
+  t('optional with a value — passes', passes(s.after_seconds, 300))
+}
+
+console.log('\n=== D. Descriptions reach the model ===')
+{
+  // 🔴 This literal appears twice on purpose — as the input and as the expected
+  // output. Change one without the other and the check goes red on healthy code.
+  const DESCRIPTION = 'the exact identifier'
+  const s = shape({ type: 'object', properties: { id: { type: 'string', description: DESCRIPTION } }, required: ['id'] })
+  t('the field description was carried over', s.id?.description === DESCRIPTION, s.id?.description)
+}
+
+console.log(`\nTOTAL: passed ${ok}, failed ${bad}`)
+process.exit(bad ? 1 : 0)