reverseport 0.0.0-stage → 1.2.0

package/port/mcp.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// ReversePort MCP server on stdio (JSON-RPC 2.0, one message per line): ReversePort's tools plus the deep-analysis
+// engine's, through one connection. See src/relay.mjs for what is listed and how the engine is relayed.
+import { StringDecoder } from 'node:string_decoder';
+import { createRelay } from './src/relay.mjs';
+
+const MAX_LINE = 32 * 1024 * 1024;
+const write = msg => process.stdout.write(`${JSON.stringify(msg)}\n`);
+const waiting = new Map(); // our requests to the client → resolver
+let nextId = 1;
+
+const relay = createRelay({
+  notify: msg => write({ jsonrpc: '2.0', ...msg }),
+  request: msg => new Promise(resolve => {
+    const id = `rp-${nextId++}`;
+    waiting.set(id, resolve);
+    write({ jsonrpc: '2.0', id, ...msg });
+  }),
+});
+
+const inFlight = new Set();
+function dispatch(line) {
+  const p = dispatchOne(line);
+  if (p && typeof p.then === 'function') { inFlight.add(p); p.finally(() => inFlight.delete(p)); }
+  return p;
+}
+
+function dispatchOne(line) {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error: each line must be one JSON-RPC message.' } }); }
+  if (msg && msg.method === undefined && msg.id !== undefined && waiting.has(msg.id)) { // client answering our request
+    const resolve = waiting.get(msg.id);
+    waiting.delete(msg.id);
+    return resolve(msg.error ? { error: msg.error } : { result: msg.result });
+  }
+  return relay.handle(msg).then(res => { if (res) write(res); }, e => { process.stderr.write(`reverseport: ${e.stack ?? e.message}\n`); if (msg?.id !== undefined) write({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: e.message } }); });
+}
+
+// initialize starts the engine; everything that arrives meanwhile waits for it, then requests run concurrently.
+let gate = null;
+const decoder = new StringDecoder('utf8');
+let buffer = '';
+process.stdin.on('data', chunk => {
+  buffer += decoder.write(chunk);
+  let i;
+  while ((i = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, i).trim();
+    buffer = buffer.slice(i + 1);
+    if (!line) continue;
+    const isInit = /"method"\s*:\s*"initialize"/.test(line);
+    if (isInit && !gate) gate = dispatch(line);
+    else if (gate) gate.then(() => dispatch(line));
+    else dispatch(line);
+  }
+  if (buffer.length > MAX_LINE) { write({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Request too large (over 32 MiB).' } }); buffer = ''; }
+});
+process.stdin.on('end', async () => {
+  if (buffer.trim()) await (gate ?? Promise.resolve()).then(() => dispatch(buffer.trim()));
+  await gate;
+  await Promise.allSettled([...inFlight]); // let running calls finish before the engine is closed
+  relay.close();
+});

package/port/plugin/mcp-launch.mjs

@@ -0,0 +1,19 @@
+// Plugin entry for the MCP server. Plugins are installed into a cache folder that is replaced on update,
+// so ReversePort's workspace (plans, extracted files, reports) defaults to ~/.reverseport, never the plugin
+// folder. Set REVERSEPORT_HOME to put it elsewhere (e.g. a roomier drive).
+import { isMainModule } from '../src/main-module.mjs';
+
+export async function main() {
+  // A plugin installed from git has no built engine. REVERSEPORT_ENGINE_FETCH=npx lets it run the published engine
+  // through npx instead (downloads the package once); without it the server starts with ReversePort's own tools and
+  // says how to add the engine.
+  if (process.env.REVERSEPORT_ENGINE_FETCH === 'npx' && !process.env.REVERSEPORT_ENGINE_COMMAND) {
+    const { engineCommand } = await import('../src/relay.mjs');
+    const { VERSION } = await import('../src/tools.mjs');
+    if (engineCommand().missing) process.env.REVERSEPORT_ENGINE_COMMAND = JSON.stringify(process.platform === 'win32' ? ['cmd', '/c', 'npx', '-y', `reverseport@${VERSION}`, 'engine', 'mcp'] : ['npx', '-y', `reverseport@${VERSION}`, 'engine', 'mcp']);
+  }
+  process.env.REVERSEPORT_VIA_PLUGIN ??= '1';
+  await import('../mcp.mjs');
+}
+
+if (isMainModule(import.meta.url)) await main();

package/port/server.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// ReversePort over HTTP (localhost only) for agents that do not speak MCP over stdio — every vendor and framework:
+//   GET  /api/health
+//   GET  /api/agent/tools?format=mcp|openai|openai-strict|responses|anthropic|gemini|json-schema
+//   POST /api/agent/call                {name, arguments}
+//   POST /api/agent/tools/{name}        {…arguments}
+//   GET  /api/openapi.json              (GPT Actions, LangChain/LlamaIndex OpenAPI tools, n8n, Semantic Kernel)
+//   POST /mcp                           MCP Streamable HTTP (JSON responses) for URL-based MCP clients
+// The same tools as `reverseport mcp`: ReversePort's own plus the deep-analysis engine's (when built).
+// REVERSEPORT_TOKEN=… requires `Authorization: Bearer …`. Browser pages on localhost may call it (CORS).
+// Reaching it from Docker or a tunnel: REVERSEPORT_HOST=0.0.0.0 plus REVERSEPORT_ALLOWED_HOSTS=host1,host2 — only
+// together with REVERSEPORT_TOKEN; without a token it refuses to listen beyond this machine.
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { VERSION } from './src/tools.mjs';
+import { workspaceRoot } from './src/workspace.mjs';
+import { isMainModule } from './src/main-module.mjs';
+import { createRelay } from './src/relay.mjs';
+import { formatTools, FORMATS, errorPayload, portableSchema } from './src/agent.mjs';
+import { RPError } from './src/util.mjs';
+
+export const DEFAULT_PORT = 32147;
+const LOCAL_ORIGIN = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/;
+const allowedHosts = () => new Set(['127.0.0.1', 'localhost', '[::1]', ...String(process.env.REVERSEPORT_ALLOWED_HOSTS ?? '').split(',').map(h => h.trim().toLowerCase()).filter(Boolean)]);
+const STATUS = { UNKNOWN_TOOL: 404, ENGINE_UNAVAILABLE: 503, ENGINE_OFF: 503, ENGINE_STOPPED: 503, ENGINE_RESTART_LIMIT: 503, NETWORK: 503, SOURCE_ERROR: 502, TOOL_FAILED: 500, TOO_LARGE: 413, UNAUTHORIZED: 401, FORBIDDEN_HOST: 403, FORBIDDEN_ORIGIN: 403 };
+
+export function openapiFor(tools, port) {
+  const paths = {};
+  for (const t of tools) {
+    paths[`/api/agent/tools/${t.name}`] = { post: {
+      operationId: t.name, summary: t.title ?? t.name, description: t.description,
+      requestBody: { required: true, content: { 'application/json': { schema: portableSchema(t.inputSchema) } } },
+      responses: {
+        200: { description: 'Tool result (JSON).', content: { 'application/json': { schema: { type: 'object' } } } },
+        400: { description: 'Error with a next step.', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'object', properties: { code: { type: 'string' }, category: { type: 'string' }, retryable: { type: 'boolean' }, message: { type: 'string' }, remediation: { type: 'object', properties: { action: { type: 'string' } } } } } } } } } },
+      },
+    } };
+  }
+  const secured = !!process.env.REVERSEPORT_TOKEN;
+  return { openapi: '3.1.0', info: { title: 'ReversePort', version: VERSION, description: 'Reverse engineer anything. Port it anywhere. Local tools for agents.' }, servers: [{ url: `http://127.0.0.1:${port}` }], paths,
+    ...(secured ? { components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer' } } }, security: [{ bearer: [] }] } : {}) };
+}
+
+const unwrap = result => {
+  if (result?.structuredContent !== undefined) return result.structuredContent;
+  const text = result?.content?.find(c => c.type === 'text')?.text;
+  try { return JSON.parse(text); } catch { return { content: result?.content ?? [] }; }
+};
+
+export function createServer({ relay } = {}) {
+  const shared = relay ?? createRelay();
+  const ready = shared.ensureStarted();
+  const sessions = new Set();
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const origin = req.headers.origin;
+    const cors = origin && LOCAL_ORIGIN.test(origin) ? { 'access-control-allow-origin': origin, vary: 'origin', 'access-control-expose-headers': 'mcp-session-id' } : {};
+    const json = (status, body, extra = {}) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', ...cors, ...extra }); res.end(JSON.stringify(body)); };
+    const fail = (status, e) => json(status, { error: errorPayload(e) });
+    const host = (req.headers.host ?? '').replace(/:\d+$/, '').toLowerCase();
+    if (!allowedHosts().has(host)) return fail(403, new RPError('FORBIDDEN_HOST', 'ReversePort only answers on localhost (or hosts listed in REVERSEPORT_ALLOWED_HOSTS).'));
+    if (origin && !LOCAL_ORIGIN.test(origin)) return fail(403, new RPError('FORBIDDEN_ORIGIN', 'Only pages on localhost may call ReversePort.'));
+    if (req.method === 'OPTIONS') { res.writeHead(204, { ...cors, 'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS', 'access-control-allow-headers': 'content-type, authorization, mcp-session-id, mcp-protocol-version', 'access-control-max-age': '600' }); return res.end(); }
+    const token = process.env.REVERSEPORT_TOKEN;
+    if (token && req.headers.authorization !== `Bearer ${token}`) return fail(401, new RPError('UNAUTHORIZED', 'Send Authorization: Bearer <REVERSEPORT_TOKEN>.'));
+    const body = async () => {
+      let text = '';
+      for await (const chunk of req) { text += chunk; if (text.length > 32 * 1024 * 1024) throw new RPError('TOO_LARGE', 'Body over 32 MiB.'); }
+      if (!text) return {};
+      try { return JSON.parse(text); } catch { throw new RPError('INVALID_ARGUMENT', 'The body is not valid JSON.'); }
+    };
+    try {
+      await ready;
+      if (req.method === 'GET' && url.pathname === '/api/health') return json(200, { ok: true, name: 'ReversePort', version: VERSION, ...shared.info(), workspace: workspaceRoot() });
+      if (req.method === 'GET' && url.pathname === '/api/agent/tools') {
+        const format = url.searchParams.get('format') ?? 'mcp';
+        if (!FORMATS.includes(format)) throw new RPError('INVALID_ARGUMENT', `Unknown format "${format}". Formats: ${FORMATS.join(', ')}.`);
+        return json(200, formatTools(shared.listTools(), format));
+      }
+      if (req.method === 'GET' && url.pathname === '/api/openapi.json') return json(200, openapiFor(shared.listTools(), req.socket.localPort ?? DEFAULT_PORT));
+      if (req.method === 'POST' && (url.pathname === '/api/agent/call' || url.pathname.startsWith('/api/agent/tools/'))) {
+        const parsed = await body();
+        const name = url.pathname === '/api/agent/call' ? parsed.name : decodeURIComponent(url.pathname.split('/').pop());
+        const args = url.pathname === '/api/agent/call' ? parsed.arguments ?? {} : parsed;
+        const result = await shared.call(name, args);
+        const value = unwrap(result);
+        if (!result?.isError) return json(200, value);
+        return json(STATUS[value?.error?.code] ?? 400, value);
+      }
+      if (url.pathname === '/mcp') {
+        if (req.method === 'GET') return json(405, { error: errorPayload(new RPError('INVALID_ARGUMENT', 'This server answers POST /mcp with JSON; it does not open an event stream.')) }, { allow: 'POST, DELETE' });
+        if (req.method === 'DELETE') { sessions.delete(req.headers['mcp-session-id']); res.writeHead(204, cors); return res.end(); }
+        if (req.method === 'POST') {
+          const parsed = await body();
+          const messages = Array.isArray(parsed) ? parsed : [parsed];
+          const replies = [];
+          let session = req.headers['mcp-session-id'];
+          for (const m of messages) {
+            const r = await shared.handle(m);
+            if (m?.method === 'initialize' && r?.result) { session = crypto.randomUUID(); sessions.add(session); }
+            if (r) replies.push(r);
+          }
+          const extra = session ? { 'mcp-session-id': session } : {};
+          if (!replies.length) { res.writeHead(202, { ...cors, ...extra }); return res.end(); }
+          return json(200, Array.isArray(parsed) ? replies : replies[0], extra);
+        }
+      }
+      return fail(404, new RPError('NOT_FOUND', 'See GET /api/agent/tools, /api/openapi.json or POST /mcp.'));
+    } catch (e) {
+      return fail(STATUS[e.code] ?? 400, e);
+    }
+  });
+}
+
+let server;
+export function start(port = Number(process.env.REVERSEPORT_PORT ?? DEFAULT_PORT)) {
+  const host = process.env.REVERSEPORT_HOST ?? '127.0.0.1';
+  if (!['127.0.0.1', 'localhost', '::1'].includes(host) && !process.env.REVERSEPORT_TOKEN) return Promise.reject(new RPError('UNAUTHORIZED', `Refusing to listen on ${host} without REVERSEPORT_TOKEN: set a token so only your agents can call it.`));
+  server = createServer();
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+if (isMainModule(import.meta.url)) {
+  const s = await start();
+  console.log(`ReversePort ${VERSION} — http://127.0.0.1:${s.address().port}/api/agent/tools  ·  MCP: http://127.0.0.1:${s.address().port}/mcp`);
+}

package/port/src/agent.mjs

@@ -0,0 +1,257 @@
+// Agent experience helpers shared by every door (MCP, HTTP, CLI): one error shape with a next step, tool
+// annotations, tool definitions in every vendor's function-calling format, "did you mean" suggestions and the
+// feedback inbox.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { RPError } from './util.mjs';
+import { workspaceRoot } from './workspace.mjs';
+
+// ---------------------------------------------------------------------------------------------------- errors
+// The same fields and categories as the deep-analysis engine's error contract (code, category, retryable,
+// remediation), so an agent can branch on one shape whichever tool failed. ReversePort's codes are UPPERCASE; the
+// engine's are lowercase.
+const ERRORS = {
+  INVALID_ARGUMENT: ['invalid_input', false, 'Correct the argument named in the message (the tool schema lists every argument), then call again.'],
+  UNKNOWN_TOOL: ['invalid_input', false, 'Use a tool name from tools/list. Engine tools that are not listed can be found with engine_tools.'],
+  NOT_FOUND: ['invalid_input', false, 'Check the path; absolute paths are safest. Ask the user where the file is if you cannot find it.'],
+  NOT_A_FILE: ['invalid_input', false, 'This tool needs a file. For a folder use re_scan.'],
+  NOT_A_FOLDER: ['invalid_input', false, 'This tool needs a folder. For a single file use re_binary, re_archive or re_probe.'],
+  ACCESS_DENIED: ['unavailable', false, 'The file or folder is not readable for this process. Ask the user to grant access or copy it somewhere readable.'],
+  UNSAFE_PATH: ['invalid_input', false, 'Use a path relative to the output project, without "..".'],
+  OUTPUT_NOT_EMPTY: ['invalid_input', false, 'Choose a new or empty output folder; ReversePort never overwrites files it did not create.'],
+  TOO_LARGE: ['resource_constraint', false, 'Narrow the request (match, limit, a subfolder, or a smaller byte range).'],
+  NETWORK: ['unavailable', true, 'A public source could not be reached. Retry later, or continue with the sources that answered (see sources) or with local files.'],
+  PRIVATE_ADDRESS: ['invalid_input', false, 'Lookups only read public web addresses. Use local tools (re_scan, re_binary) for files on this machine.'],
+  BAD_FORMAT: ['unsupported_target', false, 'The file is not in a format this tool reads. re_probe identifies unknown data.'],
+  UNSUPPORTED_SCENE: ['unsupported_target', false, 'Open the scene in Godot and save it as .tscn/.tres, then call again.'],
+  UNSUPPORTED_ARCHIVE: ['unsupported_target', false, 'This pack type is identified but not readable here; port from the project source instead.'],
+  UNSUPPORTED_VERSION: ['unsupported_target', false, 'This format version is not supported; say so to the user and continue with what can be read.'],
+  NOT_A_PCK: ['invalid_input', false, 'No Godot pack found. The pack may be a separate *.pck next to the executable; re_scan the build folder.'],
+  ENCRYPTED: ['unsupported_target', false, 'Encrypted content is reported, never decrypted. Use the project source.'],
+  SOURCE_ERROR: ['unavailable', true, 'A public source answered with an error. Continue with the sources that answered, or retry later.'],
+  ENGINE_UNAVAILABLE: ['unavailable', false, 'Deep-analysis tools need the built engine. Ask the user first, then `npx -y reverseport@latest setup`, or in a git checkout `npm ci && npm run build`, and restart the client. ReversePort\'s own tools keep working meanwhile.'],
+  ENGINE_OFF: ['unavailable', false, 'The engine is turned off with REVERSEPORT_ENGINE=off. Unset it and reconnect to use engine tools; ReversePort\'s own tools keep working.'],
+  ENGINE_STOPPED: ['unavailable', true, 'Call the engine tool again once: the server restarts the engine. If it stops again, tell the user and continue with ReversePort\'s own tools.'],
+  ENGINE_RESTART_LIMIT: ['unavailable', false, 'The engine kept stopping and will not restart in this session. Tell the user, suggest `reverseport doctor` and a client restart, and continue with ReversePort\'s own tools.'],
+  UNKNOWN_PLAN: ['invalid_input', false, 'port_status {} lists the port plans in this workspace; use one of their planIds.'],
+  UNKNOWN_CASE: ['invalid_input', false, 're_case {action:"list"} lists the cases; use one of their caseIds, or init a new one.'],
+  GATE_FAILED: ['invalid_input', false, 'Do what the gate names (save evidence, record a decision, a test or limitations), then move the phase again. re_case {action:"check"} shows every finding.'],
+  UNKNOWN_UNIT: ['invalid_input', false, 'port_status {planId} lists the units; omit unit to get the next one.'],
+  FORBIDDEN_HOST: ['invalid_input', false, 'Call ReversePort on 127.0.0.1 or localhost.'],
+  FORBIDDEN_ORIGIN: ['invalid_input', false, 'Only pages served from localhost may call ReversePort from a browser.'],
+  UNAUTHORIZED: ['invalid_input', false, 'Send the token the user set in REVERSEPORT_TOKEN as Authorization: Bearer <token>.'],
+  TOOL_FAILED: ['execution_failure', true, 'Something unexpected failed. Retry once; if it fails again, tell the user what you were doing and continue with other tools.'],
+};
+const NODE_CODES = { ENOENT: 'NOT_FOUND', EACCES: 'ACCESS_DENIED', EPERM: 'ACCESS_DENIED', EISDIR: 'NOT_A_FILE', ENOTDIR: 'NOT_A_FOLDER', EFBIG: 'TOO_LARGE' };
+
+/** One error object for every door: { code, category, retryable, message, remediation: { action }, details? }. */
+export function errorPayload(e) {
+  const raw = e?.code;
+  const code = ERRORS[raw] ? raw : NODE_CODES[raw] ?? (typeof raw === 'string' && /^[A-Z_]+$/.test(raw) ? raw : 'TOOL_FAILED');
+  const [category, retryable, action] = ERRORS[code] ?? ERRORS.TOOL_FAILED;
+  return { code, category, retryable: typeof e?.retryable === 'boolean' ? e.retryable : retryable, message: String(e?.message ?? e), remediation: { action: e?.remediation ?? action }, ...(e?.details ? { details: e.details } : {}) };
+}
+
+// ---------------------------------------------------------------------------------------------------- suggestions
+export function closest(word, candidates, max = 2) {
+  let best = null, bestD = Infinity;
+  for (const c of candidates) {
+    const d = distance(String(word).toLowerCase(), String(c).toLowerCase());
+    if (d < bestD) { best = c; bestD = d; }
+  }
+  return bestD <= max ? best : null;
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
+// ---------------------------------------------------------------------------------------------------- annotations
+// MCP hints: clients use them to skip approval prompts for reads and to run reads in parallel.
+const READ_ONLY = new Set(['re_scan', 're_graph', 're_symbols', 're_scene', 're_binary', 're_probe', 're_compare', 'port_map', 'port_convert', 'port_status', 'port_verify']);
+const OPEN_WORLD = new Set(['re_lookup']);
+
+export function annotationsFor(name) {
+  const readOnly = READ_ONLY.has(name);
+  return { readOnlyHint: readOnly, destructiveHint: false, idempotentHint: readOnly || name === 'port_unit', openWorldHint: OPEN_WORLD.has(name) };
+}
+
+// ---------------------------------------------------------------------------------------------------- formats
+export const FORMATS = ['mcp', 'openai', 'openai-strict', 'responses', 'anthropic', 'gemini', 'json-schema'];
+
+/** Tool definitions for any agent stack. `tools` are MCP-style: { name, title?, description, inputSchema, annotations? }. */
+export function formatTools(tools, format = 'mcp') {
+  switch (format) {
+    case 'mcp': return tools.map(t => ({ name: t.name, ...(t.title ? { title: t.title } : {}), description: t.description, inputSchema: t.inputSchema, ...(t.annotations ? { annotations: t.annotations } : {}) }));
+    case 'openai': return tools.map(t => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.inputSchema } }));
+    case 'openai-strict': return tools.map(t => { const { parameters, strict } = strictOrPortable(t.inputSchema); return { type: 'function', function: { name: t.name, description: t.description, parameters, strict } }; });
+    case 'responses': return tools.map(t => { const { parameters, strict } = strictOrPortable(t.inputSchema); return { type: 'function', name: t.name, description: t.description, parameters, strict }; });
+    case 'anthropic': return tools.map(t => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
+    case 'gemini': return [{ functionDeclarations: tools.map(t => ({ name: t.name, description: t.description, parameters: geminiSchema(portableSchema(t.inputSchema)) })) }];
+    case 'json-schema': return Object.fromEntries(tools.map(t => [t.name, t.inputSchema]));
+    default: throw new RPError('INVALID_ARGUMENT', `Unknown format "${format}". Formats: ${FORMATS.join(', ')}.`);
+  }
+}
+
+/** Strict when the schema allows it; otherwise the portable schema with strict:false for that one tool. */
+function strictOrPortable(schema) {
+  const portable = portableSchema(schema);
+  return strictCompatible(portable) ? { parameters: strictSchema(portable), strict: true } : { parameters: portable, strict: false };
+}
+
+function strictCompatible(s, depth = 0) {
+  if (!s || typeof s !== 'object' || depth > 5) return false;
+  if (s.type === 'object') return !!s.properties && Object.keys(s.properties).length > 0 && Object.values(s.properties).every(v => strictCompatible(v, depth + 1));
+  if (s.type === 'array') return strictCompatible(s.items, depth + 1);
+  return ['string', 'integer', 'number', 'boolean'].includes(s.type) || (Array.isArray(s.type) && s.type.every(t => ['string', 'integer', 'number', 'boolean', 'null'].includes(t)));
+}
+
+const DROP = new Set(['$schema', '$id', '$defs', 'definitions', 'dependentRequired', 'dependentSchemas', 'dependencies', 'minProperties', 'maxProperties', 'patternProperties', 'propertyNames', 'unevaluatedProperties', 'if', 'then', 'else', 'not', 'format', 'contentEncoding', 'contentMediaType', 'examples', 'default', 'title', 'readOnly', 'writeOnly', 'deprecated', 'pattern']);
+
+/**
+ * A schema every function-calling stack accepts: $ref inlined, unions of simple types folded into type lists, unions
+ * of objects merged, const as enum, and keywords strict validators reject removed (their meaning moves into the
+ * description when it matters). The server still validates the full schema, so nothing is loosened in practice.
+ */
+export function portableSchema(schema, root = schema, depth = 0, seen = new Set()) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema;
+  if (schema.$ref) {
+    const ref = schema.$ref;
+    if (seen.has(ref) || depth > 12) return { type: 'object', description: schema.description ?? 'Recursive structure (see the tool description).' };
+    const target = ref.startsWith('#/') ? ref.slice(2).split('/').reduce((o, k) => o?.[k.replace(/~1/g, '/').replace(/~0/g, '~')], root) : null;
+    if (!target) return { description: schema.description ?? '' };
+    const { $ref, ...rest } = schema;
+    return portableSchema({ ...target, ...rest }, root, depth + 1, new Set([...seen, ref]));
+  }
+  const union = schema.anyOf ?? schema.oneOf;
+  if (union) {
+    const variants = union.map(v => portableSchema(v, root, depth + 1, seen));
+    const { anyOf, oneOf, ...rest } = schema;
+    const base = cleanKeys(rest, root, depth, seen);
+    const nonNull = variants.filter(v => v.type !== 'null');
+    const hasNull = nonNull.length < variants.length;
+    if (nonNull.every(v => typeof v.type === 'string' && v.type !== 'object' && v.type !== 'array')) {
+      const types = [...new Set(nonNull.map(v => v.type))];
+      const enums = nonNull.every(v => v.enum) ? [...new Set(nonNull.flatMap(v => v.enum))] : null;
+      const type = hasNull ? [...types, 'null'] : types.length === 1 ? types[0] : types;
+      return { ...base, type, ...(enums ? { enum: hasNull ? [...enums, null] : enums } : {}), ...(base.description || nonNull[0]?.description ? { description: base.description ?? nonNull[0].description } : {}) };
+    }
+    if (nonNull.every(v => v.type === 'object')) {
+      const properties = {};
+      for (const v of nonNull) Object.assign(properties, v.properties ?? {});
+      const required = nonNull.map(v => new Set(v.required ?? [])).reduce((a, b) => new Set([...a].filter(x => b.has(x))));
+      const note = nonNull.length > 1 ? ' Accepts one of several shapes; give the fields of one of them.' : '';
+      return { ...base, type: 'object', properties, required: [...required], additionalProperties: false, description: `${base.description ?? nonNull[0]?.description ?? ''}${note}`.trim() };
+    }
+    return { ...base, ...nonNull[0], description: `${base.description ?? nonNull[0]?.description ?? ''}`.trim() };
+  }
+  return cleanKeys(schema, root, depth, seen);
+}
+
+function cleanKeys(schema, root, depth, seen) {
+  const out = {};
+  for (const [k, v] of Object.entries(schema)) {
+    if (DROP.has(k)) continue;
+    if (k === 'const') { out.enum = [v]; continue; }
+    if (k === 'properties') out.properties = Object.fromEntries(Object.entries(v).map(([pk, pv]) => [pk, portableSchema(pv, root, depth + 1, seen)]));
+    else if (k === 'items') out.items = Array.isArray(v) ? portableSchema(v[0], root, depth + 1, seen) : portableSchema(v, root, depth + 1, seen);
+    else if (k === 'additionalProperties' && typeof v === 'object') out.additionalProperties = false;
+    else if (k === 'allOf') Object.assign(out, ...v.map(x => portableSchema(x, root, depth + 1, seen)));
+    else out[k] = v;
+  }
+  if (out.enum && !out.type) {
+    const kinds = [...new Set(out.enum.map(v => (v === null ? 'null' : Number.isInteger(v) ? 'integer' : typeof v)))];
+    out.type = kinds.length === 1 ? kinds[0] : kinds;
+  }
+  return out;
+}
+
+/** OpenAI strict mode: every property required, optional ones nullable, no additional properties. Null means "not given". */
+export function strictSchema(s) {
+  if (!s || typeof s !== 'object') return s;
+  if (s.type === 'object') {
+    const props = s.properties ?? {};
+    const required = new Set(s.required ?? []);
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+      const inner = strictSchema(v);
+      out[k] = required.has(k) ? inner : nullable(inner);
+    }
+    return { type: 'object', ...(s.description ? { description: s.description } : {}), properties: out, required: Object.keys(props), additionalProperties: false };
+  }
+  if (s.type === 'array') return dropUnsupported({ ...s, items: strictSchema(s.items) });
+  return dropUnsupported({ ...s });
+}
+
+function nullable(s) {
+  const types = Array.isArray(s.type) ? s.type : [s.type];
+  if (types.includes('null')) return s;
+  if (s.enum) return { ...s, type: [...types, 'null'], enum: [...s.enum, null] };
+  return { ...s, type: [...types, 'null'] };
+}
+
+function dropUnsupported(s) {
+  // Strict mode rejects a few numeric/array bounds on some models; keep them in the description instead.
+  const notes = [];
+  for (const k of ['minimum', 'maximum', 'minItems', 'maxItems']) if (s[k] !== undefined) { notes.push(`${k} ${s[k]}`); delete s[k]; }
+  if (notes.length) s.description = `${s.description ?? ''}${s.description ? ' ' : ''}(${notes.join(', ')})`.trim();
+  return s;
+}
+
+/**
+ * Gemini function declarations (an OpenAPI 3.0 subset): one type per schema with nullable, string-only enums,
+ * objects with declared properties, no additionalProperties. Anything that does not fit becomes a described string
+ * (JSON for free-form objects), which ReversePort parses back.
+ */
+export function geminiSchema(s) {
+  if (!s || typeof s !== 'object') return s;
+  const out = {};
+  let types = Array.isArray(s.type) ? s.type : s.type ? [s.type] : [];
+  if (types.includes('null')) { out.nullable = true; types = types.filter(t => t !== 'null'); }
+  let type = types.length === 1 ? types[0] : types.length ? 'string' : undefined;
+  let note = types.length > 1 ? ` (one of: ${types.join(', ')}; send as text)` : '';
+  if (type === 'object' && (!s.properties || !Object.keys(s.properties).length)) { type = 'string'; note += ' (a JSON object, sent as text)'; }
+  if (type) out.type = type;
+  for (const [k, v] of Object.entries(s)) {
+    if (['additionalProperties', 'title', '$schema', 'type'].includes(k)) continue;
+    if (k === 'properties' && type === 'object') out.properties = Object.fromEntries(Object.entries(v).map(([pk, pv]) => [pk, geminiSchema(pv)]));
+    else if (k === 'required' && type === 'object') out.required = v;
+    else if (k === 'items') out.items = geminiSchema(v);
+    else if (k === 'enum') {
+      const values = v.filter(x => x !== null);
+      if (values.every(x => typeof x === 'string') && type === 'string') out.enum = values;
+      else note += ` (allowed: ${values.join(', ')})`;
+    } else if (k === 'properties' || k === 'required') continue;
+    else out[k] = v;
+  }
+  if (note) out.description = `${out.description ?? ''}${note}`.trim();
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------------- feedback
+/** Agents can say what helped and what got in their way; notes stay local until the user shares them. */
+export async function shareFeedback(args) {
+  const dir = path.join(workspaceRoot(), 'feedback');
+  await fs.mkdir(dir, { recursive: true });
+  const entry = { at: new Date().toISOString(), tool: args.tool ?? null, rating: args.rating ?? null, worked: args.worked ?? null, friction: args.friction ?? null, suggestion: args.suggestion ?? null, agent: args.agent ?? null };
+  const file = path.join(dir, 'feedback.jsonl');
+  await fs.appendFile(file, `${JSON.stringify(entry)}\n`);
+  return { saved: true, file, note: 'Thank you. This note stays on this computer; the user can read it or share it with the maintainers (reverseport feedback).' };
+}
+
+export async function readFeedback() {
+  const file = path.join(workspaceRoot(), 'feedback', 'feedback.jsonl');
+  let text = '';
+  try { text = await fs.readFile(file, 'utf8'); } catch { return { file, entries: [] }; }
+  return { file, entries: text.split('\n').filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean) };
+}