rterm-backend 3.7.6 → 3.8.0

package/bin/gybackend.cjs

@@ -276397,9 +276397,12 @@ var init_compoundingStore = __esm({
     init_betterSqlite3Runtime();
     init_historyStoragePaths();
     COMPOUNDING_DB_FILE = "gyshell-compounding.sqlite";
-    CompoundingStore = class {
+    CompoundingStore = class _CompoundingStore {
       filePath;
       db;
+      /** Avoid sync SQLite on every agent turn (desktop freeze). Invalidated on writes. */
+      promptCache = null;
+      static PROMPT_CACHE_MS = 2e3;
       constructor(options) {
         this.filePath = options?.filePath || import_node_path28.default.join(resolveHistoryStorageDir(), COMPOUNDING_DB_FILE);
         import_node_fs12.default.mkdirSync(import_node_path28.default.dirname(this.filePath), { recursive: true });
@@ -276453,6 +276456,7 @@ var init_compoundingStore = __esm({
       recordLessons(lessons, runId) {
         const now = Date.now();
         const out = [];
+        this.promptCache = null;
         try {
           const sel = this.db.prepare("SELECT * FROM lessons WHERE fingerprint = ?");
           const ins = this.db.prepare(
@@ -276506,6 +276510,7 @@ var init_compoundingStore = __esm({
         }
       }
       upsertEstateFact(input) {
+        this.promptCache = null;
         try {
           const now = Date.now();
           this.db.prepare(
@@ -276552,6 +276557,7 @@ var init_compoundingStore = __esm({
         }
       }
       upsertGoal(input) {
+        this.promptCache = null;
         try {
           this.db.prepare(
             `INSERT INTO goals (id, session_id, text, status, blocked_by, next_probe, updated_at)
@@ -276589,6 +276595,7 @@ var init_compoundingStore = __esm({
         }
       }
       recordProbe(sessionId, tag, hypothesis, command, ok) {
+        this.promptCache = null;
         try {
           this.db.prepare(
             `INSERT INTO probes (session_id, tag, hypothesis, command, ok, at)
@@ -276620,6 +276627,11 @@ var init_compoundingStore = __esm({
        */
       promptBlock(maxChars = 4e3) {
         try {
+          const now = Date.now();
+          if (this.promptCache && now - this.promptCache.at < _CompoundingStore.PROMPT_CACHE_MS) {
+            const cached2 = this.promptCache.text;
+            return cached2.length > maxChars ? cached2.slice(0, maxChars) + "\n\u2026" : cached2;
+          }
           const lessons = this.listLessons(20);
           const facts = this.listEstateFacts();
           const lines = ["# Compounding knowledge (auto)"];
@@ -276641,6 +276653,7 @@ var init_compoundingStore = __esm({
             }
           }
           const text = lines.join("\n");
+          this.promptCache = { at: now, text };
           return text.length > maxChars ? text.slice(0, maxChars) + "\n\u2026" : text;
         } catch {
           return "";
@@ -296488,6 +296501,8 @@ var PSRPTransport = class {
   /** pypsrp WSMan.session_id — one uuid for the life of the transport. */
   sessionId = `uuid:${(0, import_node_crypto3.randomUUID)().toUpperCase()}`;
   http;
+  /** Persistent runspace (v3.8.0): reuse one Microsoft.PowerShell shell across commands. */
+  pool = null;
   constructor(opts) {
     this.http = new WinHttpAuth({
       host: opts.host,
@@ -296511,6 +296526,7 @@ var PSRPTransport = class {
     const wsmv = "http://schemas.microsoft.com/wbem/wsman/1/wsman.xsd";
     return `<s:Envelope xmlns:s="${NS2.s}" xmlns:wsa="${NS2.a}" xmlns:wsman="${NS2.w}" xmlns:wsmv="${wsmv}" xmlns:rsp="${NS2.rsp}" xml:lang="en-US"><s:Header><wsa:Action s:mustUnderstand="true">${action}</wsa:Action><wsmv:DataLocale s:mustUnderstand="false" xml:lang="en-US" /><wsman:Locale s:mustUnderstand="false" xml:lang="en-US" /><wsman:MaxEnvelopeSize s:mustUnderstand="true">512000</wsman:MaxEnvelopeSize><wsa:MessageID>${mid}</wsa:MessageID><wsman:OperationTimeout>PT60.000S</wsman:OperationTimeout><wsa:ReplyTo><wsa:Address s:mustUnderstand="true">${NS2.a}/role/anonymous</wsa:Address></wsa:ReplyTo><wsman:ResourceURI s:mustUnderstand="true">${PSRP_SHELL_URI}</wsman:ResourceURI><wsmv:SessionId s:mustUnderstand="false">${this.sessionId}</wsmv:SessionId><wsa:To>${to}</wsa:To>${extraHeaders}</s:Header><s:Body>${body}</s:Body></s:Envelope>`;
   }
+  /** Test hook: subclasses may override. */
   async post(action, body, extraHeaders) {
     const envelope = this.envelope(action, body, extraHeaders);
     const res = await this.http.post(envelope);
@@ -296524,6 +296540,57 @@ var PSRPTransport = class {
    *   Receive loop (PIPELINE_OUTPUT / ERROR_RECORD / PIPELINE_STATE) → Delete.
    * The script travels inside the PSRP message body — no command-line length limit.
    */
+  /** Open (or return) a persistent runspace pool. */
+  async ensurePool(opts) {
+    if (this.pool) return { shellId: this.pool.shellId, rpid: this.pool.rpid };
+    const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+    const rpid = (0, import_node_crypto3.randomUUID)().toUpperCase();
+    const creation = fragmentMessages([
+      psrpMessage(MSG.SESSION_CAPABILITY, rpid, "00000000-0000-0000-0000-000000000000", sessionCapabilityXml()),
+      psrpMessage(MSG.INIT_RUNSPACEPOOL, rpid, "00000000-0000-0000-0000-000000000000", initRunspacePoolXml())
+    ], 1);
+    const createBody = `<rsp:Shell ShellId="${rpid}"><rsp:InputStreams>stdin pr</rsp:InputStreams><rsp:OutputStreams>stdout</rsp:OutputStreams><creationXml xmlns="http://schemas.microsoft.com/powershell">` + creation.blob.toString("base64") + `</creationXml></rsp:Shell>`;
+    const createHeaders = `<wsman:OptionSet s:mustUnderstand="true"><wsman:Option MustComply="true" Name="protocolversion">2.3</wsman:Option></wsman:OptionSet>`;
+    const created = await this.post(
+      "http://schemas.xmlsoap.org/ws/2004/09/transfer/Create",
+      createBody,
+      createHeaders
+    );
+    this.assertOk(created, "Create");
+    const shellId = extractShellId2(created.body);
+    if (!shellId) throw new Error("PSRP Create succeeded but no ShellId returned.");
+    await this.waitForRunspaceOpened(shellId, deadline, opts?.signal);
+    this.pool = { shellId, rpid, nextObjectId: creation.nextObjectId };
+    return { shellId, rpid };
+  }
+  async closePool() {
+    const p = this.pool;
+    this.pool = null;
+    if (p) await this.deleteShell(p.shellId);
+  }
+  /**
+   * Run a script on the persistent pool (opens one if needed). Does NOT delete
+   * the shell — call closePool() when the tab dies.
+   */
+  async runScriptOnPool(script, opts) {
+    const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+    const pool = await this.ensurePool(opts);
+    const pipelineId = (0, import_node_crypto3.randomUUID)().toUpperCase();
+    const createPipelineMsg = psrpMessage(MSG.CREATE_PIPELINE, pool.rpid, pipelineId, createPipelineXml(script));
+    const frag = fragmentMessages([createPipelineMsg], this.pool.nextObjectId);
+    this.pool.nextObjectId = frag.nextObjectId;
+    const commandBody = `<rsp:CommandLine CommandId="${pipelineId}"><rsp:Command></rsp:Command><rsp:Arguments>${frag.blob.toString("base64")}</rsp:Arguments></rsp:CommandLine>`;
+    const commandHeaders = `<wsman:OptionSet s:mustUnderstand="true"><wsman:Option Name="WINRS_SKIP_CMD_SHELL">False</wsman:Option></wsman:OptionSet>` + this.shellHeaders(pool.shellId);
+    const commanded = await this.post(
+      "http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Command",
+      commandBody,
+      commandHeaders
+    );
+    this.assertOk(commanded, "Command");
+    const commandId = firstText2(commanded.body, "CommandId");
+    if (!commandId) throw new Error("PSRP Command succeeded but no CommandId returned.");
+    return this.receivePipeline(pool.shellId, commandId, deadline, opts);
+  }
   async runScript(script, opts) {
     const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
     const rpid = (0, import_node_crypto3.randomUUID)().toUpperCase();
@@ -296556,63 +296623,76 @@ var PSRPTransport = class {
       this.assertOk(commanded, "Command");
       const commandId = firstText2(commanded.body, "CommandId");
       if (!commandId) throw new Error("PSRP Command succeeded but no CommandId returned.");
-      let stdout = "";
-      let stderr = "";
-      let hadErrors = false;
-      let exitCode = 0;
-      let pipelineDone = false;
-      for (; ; ) {
-        if (opts?.signal?.aborted) throw new Error("AbortError");
-        if (Date.now() > deadline) {
-          throw new Error(`PSRP command timed out after ${opts?.timeoutMs ?? 12e4}ms`);
-        }
-        const receiveBody = `<rsp:Receive><rsp:DesiredStream CommandId="${commandId}">stdout</rsp:DesiredStream></rsp:Receive>`;
-        const receiveHeaders = `<wsman:OptionSet s:mustUnderstand="true"><wsman:Option Name="WSMAN_CMDSHELL_OPTION_KEEPALIVE">True</wsman:Option></wsman:OptionSet>` + this.shellHeaders(shellId);
-        const received = await this.post(
-          "http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Receive",
-          receiveBody,
-          receiveHeaders
-        );
-        this.assertOk(received, "Receive");
-        const streamRe = /<\w*:?Stream\b[^>]*\bName="(?:stdout|stderr|pr)"[^>]*>([\s\S]*?)<\/\w*:?Stream>/gi;
-        let m2;
-        while ((m2 = streamRe.exec(received.body)) !== null) {
-          const b64 = m2[1].replace(/\s+/g, "");
-          if (!b64) continue;
-          for (const raw of unfragmentMessages(import_node_buffer2.Buffer.from(b64, "base64"))) {
-            if (raw.length < 40) continue;
-            const messageType = raw.readUInt32LE(4);
-            const payload = raw.subarray(40).toString("utf8").replace(/^\uFEFF/, "");
-            if (messageType === MSG.PIPELINE_OUTPUT) {
-              const sRe = /<S[^>]*>([\s\S]*?)<\/S>/gi;
-              let sm;
-              while ((sm = sRe.exec(payload)) !== null) stdout += sm[1];
-            } else if (messageType === MSG.ERROR_RECORD) {
-              hadErrors = true;
-              const mRe = payload.match(/<S N="Message">([\s\S]*?)<\/S>/i);
-              stderr += (mRe ? mRe[1] : payload) + "\n";
-            } else if (messageType === MSG.PIPELINE_STATE) {
-              pipelineDone = true;
-              const stateMatch = payload.match(/<I32 N="State">(\d+)<\/I32>/i);
-              if (stateMatch) {
-                if (parseInt(stateMatch[1], 10) === 5) hadErrors = true;
-              }
-              const ec = payload.match(/N="ExitCode"[^>]*>(-?\d+)</i);
-              if (ec) exitCode = parseInt(ec[1], 10);
-            }
-          }
-        }
-        const wsExit = received.body.match(/<\w*:?ExitCode>\s*(-?\d+)\s*<\/\w*:?ExitCode>/i);
-        if (wsExit) exitCode = parseInt(wsExit[1], 10);
-        if (pipelineDone) break;
-        if (/CommandState\/Done/i.test(received.body)) break;
-      }
-      if (exitCode !== 0) hadErrors = true;
-      return { stdout, stderr, exitCode, hadErrors };
+      return await this.receivePipeline(shellId, commandId, deadline, opts);
     } finally {
       await this.deleteShell(shellId);
     }
   }
+  async receivePipeline(shellId, commandId, deadline, opts) {
+    let stdout = "";
+    let stderr = "";
+    let hadErrors = false;
+    let exitCode = 0;
+    let pipelineDone = false;
+    for (; ; ) {
+      if (opts?.signal?.aborted) throw new Error("AbortError");
+      if (Date.now() > deadline) {
+        throw new Error(`PSRP command timed out after ${opts?.timeoutMs ?? 12e4}ms`);
+      }
+      const receiveBody = `<rsp:Receive><rsp:DesiredStream CommandId="${commandId}">stdout</rsp:DesiredStream></rsp:Receive>`;
+      const receiveHeaders = `<wsman:OptionSet s:mustUnderstand="true"><wsman:Option Name="WSMAN_CMDSHELL_OPTION_KEEPALIVE">True</wsman:Option></wsman:OptionSet>` + this.shellHeaders(shellId);
+      const received = await this.post(
+        "http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Receive",
+        receiveBody,
+        receiveHeaders
+      );
+      this.assertOk(received, "Receive");
+      const streamRe = /<\w*:?Stream\b[^>]*\bName="(?:stdout|stderr|pr)"[^>]*>([\s\S]*?)<\/\w*:?Stream>/gi;
+      let m2;
+      while ((m2 = streamRe.exec(received.body)) !== null) {
+        const b64 = m2[1].replace(/\s+/g, "");
+        if (!b64) continue;
+        for (const raw of unfragmentMessages(import_node_buffer2.Buffer.from(b64, "base64"))) {
+          if (raw.length < 40) continue;
+          const messageType = raw.readUInt32LE(4);
+          const payload = raw.subarray(40).toString("utf8").replace(/^\uFEFF/, "");
+          if (messageType === MSG.PIPELINE_OUTPUT) {
+            const sRe = /<S[^>]*>([\s\S]*?)<\/S>/gi;
+            let sm;
+            let extracted = false;
+            while ((sm = sRe.exec(payload)) !== null) {
+              stdout += sm[1];
+              extracted = true;
+            }
+            if (!extracted) {
+              const nRe = /<(?:I32|I64|B|ToString)[^>]*>([\s\S]*?)<\/(?:I32|I64|B|ToString)>/i;
+              const nm = payload.match(nRe);
+              if (nm) stdout += nm[1];
+              else stdout += payload.replace(/<[^>]+>/g, "").trim();
+            }
+          } else if (messageType === MSG.ERROR_RECORD) {
+            hadErrors = true;
+            const mRe = payload.match(/<S N="Message">([\s\S]*?)<\/S>/i);
+            stderr += (mRe ? mRe[1] : payload) + "\n";
+          } else if (messageType === MSG.PIPELINE_STATE) {
+            pipelineDone = true;
+            const stateMatch = payload.match(/<I32 N="State">(\d+)<\/I32>/i);
+            if (stateMatch) {
+              if (parseInt(stateMatch[1], 10) === 5) hadErrors = true;
+            }
+            const ec = payload.match(/N="ExitCode"[^>]*>(-?\d+)</i);
+            if (ec) exitCode = parseInt(ec[1], 10);
+          }
+        }
+      }
+      const wsExit = received.body.match(/<\w*:?ExitCode>\s*(-?\d+)\s*<\/\w*:?ExitCode>/i);
+      if (wsExit) exitCode = parseInt(wsExit[1], 10);
+      if (pipelineDone) break;
+      if (/CommandState\/Done/i.test(received.body)) break;
+    }
+    if (exitCode !== 0) hadErrors = true;
+    return { stdout, stderr, exitCode, hadErrors };
+  }
   /**
    * Drain Receive until RUNSPACEPOOL_STATE reports Opened (state=2).
    * Must run after Create and before Command.
@@ -296817,7 +296897,7 @@ Run commands with exec_command / run_fleet_command. Interactive TUI apps are not
 \x1B[36m\u276F ${command}\x1B[0m\r
 `);
     const ps = this.translateCmdToPowerShell(command, instance.cwd);
-    const result = await transport.runScript(ps, {
+    const result = await transport.runScriptOnPool(ps, {
       timeoutMs: options?.timeoutMs ?? DEFAULT_WINRM_TIMEOUT_MS,
       signal: options?.signal
     });
@@ -296938,6 +297018,9 @@ Run commands with exec_command / run_fleet_command. Interactive TUI apps are not
       void instance.winrm.deleteShell(instance.persistentShellId);
       instance.persistentShellId = void 0;
     }
+    if (instance.psrp) {
+      void instance.psrp.closePool();
+    }
     instance.exitCallback?.(0);
   }
   onData(ptyId, callback) {
@@ -345277,6 +345360,28 @@ var MessagesZodState = external_exports.object({ messages: withLangGraph(externa
 // ../../node_modules/@langchain/langgraph/dist/index.js
 initializeAsyncLocalStorageSingleton();
 
+// ../../packages/backend/src/services/redaction/secretRedact.ts
+var PATTERNS = [
+  { re: /\b(gys_at_[A-Za-z0-9_-]{16,})\b/g, label: "RTERM_TOKEN" },
+  { re: /\b(ghp_[A-Za-z0-9]{20,})\b/g, label: "GITHUB_PAT" },
+  { re: /\b(sk-[A-Za-z0-9_-]{20,})\b/g, label: "API_KEY" },
+  { re: /\b(AKIA[0-9A-Z]{16})\b/g, label: "AWS_KEY" },
+  { re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, label: "PRIVATE_KEY" },
+  { re: /(password|passwd|pwd|secret|token)\s*[:=]\s*["']?([^\s"']{6,})/gi, label: "CREDENTIAL" }
+];
+function redactText(input, extraValues = []) {
+  let out = String(input ?? "");
+  for (const v of extraValues) {
+    const t = String(v || "");
+    if (t.length < 4) continue;
+    out = out.split(t).join(`[REDACTED]`);
+  }
+  for (const p of PATTERNS) {
+    out = out.replace(p.re, `[REDACTED:${p.label}]`);
+  }
+  return out;
+}
+
 // ../../packages/backend/src/services/agentRunLedger.ts
 var import_node_fs3 = __toESM(require("node:fs"), 1);
 var import_node_path5 = __toESM(require("node:path"), 1);
@@ -366951,6 +367056,11 @@ function reconcileToolCalls(toolCalls) {
   }
   return result;
 }
+var TOOL_RESULT_MAX_CHARS = 32768;
+function stringifyToolResult(result) {
+  const raw = typeof result === "string" ? result : JSON.stringify(result);
+  return redactText(clipTextMiddle(raw, TOOL_RESULT_MAX_CHARS));
+}
 function clipTextMiddle(input, maxChars) {
   if (maxChars <= 0) return "";
   if (input.length <= maxChars) return input;
@@ -368873,7 +368983,7 @@ Actually, your intention might be different. Please re-read the description of t
             try {
               const pluginArgs = typeof toolCall.args === "string" ? JSON.parse(toolCall.args) : toolCall.args || {};
               const pluginResult = await pluginHandler(pluginArgs);
-              result = typeof pluginResult === "string" ? pluginResult : JSON.stringify(pluginResult);
+              result = stringifyToolResult(pluginResult);
             } catch (err) {
               result = `Plugin tool "${toolCall.name}" error: ${err.message}`;
             }
@@ -369161,7 +369271,7 @@ Actually, your intention might be different. Please re-read the description of t
         const pluginHandler = this.pluginTools.get(name);
         if (pluginHandler) {
           const result = await pluginHandler(args);
-          return typeof result === "string" ? result : JSON.stringify(result);
+          return stringifyToolResult(result);
         }
         return `Tool "${name}" is not supported in parallel execution mode.`;
       }
@@ -369242,7 +369352,7 @@ Actually, your intention might be different. Please re-read the description of t
           args,
           signal
         );
-        resultText = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        resultText = stringifyToolResult(result);
       } catch (err) {
         if (this.helpers.isAbortError(err)) throw err;
         resultText = err instanceof Error ? err.message : String(err);
@@ -373011,6 +373121,26 @@ var import_websocket_server = __toESM(require_websocket_server(), 1);
 
 // ../../packages/backend/src/services/Gateway/WebSocketGatewayAdapter.ts
 var import_node_module4 = require("node:module");
+
+// ../../packages/backend/src/services/security/tokenScopes.ts
+var SCOPE_FULL = "*";
+function methodAllowed(method, scopes) {
+  if (!scopes || scopes.length === 0) return true;
+  if (scopes.includes(SCOPE_FULL)) return true;
+  const m2 = String(method || "");
+  for (const s of scopes) {
+    if (s === m2) return true;
+    if (s.endsWith(":*")) {
+      const prefix = s.slice(0, -1);
+      if (m2.startsWith(prefix)) return true;
+      if (prefix === "terminals:" && m2.startsWith("terminal:")) return true;
+    }
+    if (s.endsWith("*") && m2.startsWith(s.slice(0, -1))) return true;
+  }
+  return false;
+}
+
+// ../../packages/backend/src/services/Gateway/WebSocketGatewayAdapter.ts
 var import_meta7 = {};
 var nodeRequire = (0, import_node_module4.createRequire)(
   typeof __filename !== "undefined" ? __filename : import_meta7.url
@@ -373021,6 +373151,22 @@ var WebSocketRpcError = class extends Error {
     this.code = code;
   }
 };
+function httpRouteMatches(pattern, pathname) {
+  if (pattern === pathname) return true;
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -1);
+    const base = pattern.slice(0, -2);
+    return pathname === base || pathname.startsWith(prefix) || pathname.startsWith(base + "/");
+  }
+  const a = pattern.split("/").filter(Boolean);
+  const b = pathname.split("/").filter(Boolean);
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].startsWith(":")) continue;
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
 function createDefaultWebSocketServerFactory(httpRoutes) {
   return ({ host, port }) => {
     if (!httpRoutes || httpRoutes.length === 0) {
@@ -373043,7 +373189,7 @@ function createDefaultWebSocketServerFactory(httpRoutes) {
             ).pathname;
           } catch {
           }
-          const route = routes.find((r) => r.path === pathname);
+          const route = routes.find((r) => httpRouteMatches(r.path, pathname));
           if (!route) {
             res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
             res.end("not found");
@@ -373099,6 +373245,7 @@ var WebSocketGatewayAdapter = class {
   server = null;
   transportIdBySocket = /* @__PURE__ */ new Map();
   isSameMachineBySocket = /* @__PURE__ */ new WeakMap();
+  scopesBySocket = /* @__PURE__ */ new WeakMap();
   serverFactory;
   logger;
   start() {
@@ -373196,6 +373343,12 @@ var WebSocketGatewayAdapter = class {
       this.isLoopbackAddress(String(remote))
     );
     this.gateway.registerTransport(transport);
+    const token = this.extractAccessToken(request);
+    const scopeFn = this.options.accessTokenAuth?.scopesForToken;
+    if (token && scopeFn) {
+      const scopes = await scopeFn(token);
+      if (scopes && scopes.length) this.scopesBySocket.set(socket, scopes);
+    }
     state.authorized = true;
     this.logger.info(
       `[WebSocketGatewayAdapter] Client connected: ${remote} (${transport.id})`
@@ -373493,6 +373646,13 @@ var WebSocketGatewayAdapter = class {
     );
   }
   async executeRequest(request, socket) {
+    const scopes = this.scopesBySocket.get(socket);
+    if (scopes && !methodAllowed(request.method, scopes)) {
+      throw new WebSocketRpcError(
+        "FORBIDDEN",
+        `Token is not allowed to call ${request.method}`
+      );
+    }
     const params = request.params ?? {};
     if (request.method.startsWith("observability:")) {
       const bridge = this.options.observabilityBridge;
@@ -384954,8 +385114,9 @@ var IdleTimeoutService = class {
 // ../../packages/backend/src/services/Gateway/restApi.ts
 function matchRestRoute(routes, method, path33) {
   const normalized = path33.replace(/\/+$/, "") || "/";
+  const verb = method.toUpperCase();
   for (const route of routes) {
-    if (route.method !== method.toUpperCase()) continue;
+    if (route.method !== verb) continue;
     const patternParts = route.path.split("/").filter(Boolean);
     const pathParts = normalized.split("/").filter(Boolean);
     if (patternParts.length !== pathParts.length) continue;
@@ -384976,36 +385137,18 @@ function matchRestRoute(routes, method, path33) {
 }
 function defaultRestRoutes() {
   return [
+    { method: "GET", path: "/api/v1/health", gatewayMethod: "gateway:ping", description: "Liveness check" },
+    { method: "GET", path: "/api/v1/methods", gatewayMethod: "gateway:describe", description: "List all gateway RPC methods" },
+    { method: "GET", path: "/api/v1/openapi.json", gatewayMethod: "__openapi", description: "OpenAPI 3 document for this REST overlay + RPC escape hatch" },
+    { method: "GET", path: "/api/v1/terminals", gatewayMethod: "terminal:list", description: "List terminal tabs" },
+    { method: "GET", path: "/api/v1/sessions", gatewayMethod: "session:list", description: "List chat sessions" },
     {
-      method: "GET",
-      path: "/api/v1/health",
-      gatewayMethod: "gateway:ping",
-      description: "Liveness check"
-    },
-    {
-      method: "GET",
-      path: "/api/v1/methods",
-      gatewayMethod: "gateway:describe",
-      description: "List all gateway methods (self-describing)"
-    },
-    {
-      method: "GET",
-      path: "/api/v1/terminals",
-      gatewayMethod: "terminal:list",
-      description: "List terminal tabs"
-    },
-    {
-      method: "GET",
+      method: "POST",
       path: "/api/v1/sessions",
-      gatewayMethod: "session:list",
-      description: "List chat sessions"
-    },
-    {
-      method: "GET",
-      path: "/api/v1/skills",
-      gatewayMethod: "skills:getAll",
-      description: "List loaded skills"
+      gatewayMethod: "gateway:createSession",
+      description: "Create a chat/agent session"
     },
+    { method: "GET", path: "/api/v1/skills", gatewayMethod: "skills:getAll", description: "List loaded skills" },
     {
       method: "GET",
       path: "/api/v1/observability/metrics",
@@ -385022,13 +385165,13 @@ function defaultRestRoutes() {
       method: "GET",
       path: "/api/v1/observability/apm",
       gatewayMethod: "observability:apmSummary",
-      description: "APM summary (LLM + app traces)"
+      description: "APM summary"
     },
     {
       method: "GET",
       path: "/api/v1/history/search",
       gatewayMethod: "history:search",
-      description: "Cross-session history search (?q=...)",
+      description: "Cross-session history search (?q=)",
       buildParams: (_p, body) => {
         const b = body ?? {};
         return { query: b.q ?? b.query ?? "" };
@@ -385048,17 +385191,18 @@ function defaultRestRoutes() {
       method: "GET",
       path: "/api/v1/terminals/:id/buffer",
       gatewayMethod: "terminal:getBufferDelta",
-      description: "Read a terminal tab output delta",
+      description: "Read terminal output delta (?fromOffset=)",
       buildParams: (p, body) => {
         const b = body ?? {};
-        return { terminalId: p.id, fromOffset: b.fromOffset ?? 0 };
+        const n2 = Number(b.fromOffset ?? 0);
+        return { terminalId: p.id, fromOffset: Number.isFinite(n2) ? n2 : 0 };
       }
     },
     {
       method: "POST",
       path: "/api/v1/sessions/:id/chat",
       gatewayMethod: "agent:startTask",
-      description: "Send a message to the agent (blocking)",
+      description: "Send a message (blocking until the run finishes \u2014 prefer chat-async)",
       buildParams: (p, body) => {
         const b = body ?? {};
         return { sessionId: p.id, userInput: b.message ?? b.userInput ?? "" };
@@ -385066,17 +385210,66 @@ function defaultRestRoutes() {
     },
     {
       method: "POST",
-      path: "/api/v1/rpc",
-      gatewayMethod: "",
-      description: "Escape hatch: dispatch any gateway method",
-      buildParams: (_p, body) => {
+      path: "/api/v1/sessions/:id/chat-async",
+      gatewayMethod: "agent:startTaskAsync",
+      description: "Start an agent turn without waiting; subscribe to WS gateway:event for tokens",
+      buildParams: (p, body) => {
         const b = body ?? {};
-        return { __rpcMethod: b.method ?? "", ...b.params ?? {} };
+        return { sessionId: p.id, userInput: b.message ?? b.userInput ?? "" };
       }
+    },
+    {
+      method: "POST",
+      path: "/api/v1/rpc",
+      gatewayMethod: "",
+      description: "Escape hatch: any gateway method {method, params}"
     }
   ];
 }
+function buildOpenApiDocument() {
+  const routes = defaultRestRoutes();
+  const paths = {};
+  for (const r of routes) {
+    if (r.gatewayMethod === "__openapi") continue;
+    const item = paths[r.path] || {};
+    item[r.method.toLowerCase()] = {
+      summary: r.description,
+      operationId: `${r.method}_${r.path.replace(/[^a-zA-Z0-9]+/g, "_")}`,
+      tags: ["rest"],
+      ...r.method === "POST" ? {
+        requestBody: {
+          content: { "application/json": { schema: { type: "object" } } }
+        }
+      } : {},
+      responses: { "200": { description: "OK" }, "401": { description: "Unauthorized" } }
+    };
+    paths[r.path] = item;
+  }
+  const rpcMethods = [...CORE_METHODS, DESCRIBE_METHOD].map((m2) => m2.name);
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: "RTerm HTTP overlay",
+      version: "1.0.0",
+      description: `Thin REST on the same port as the WebSocket JSON-RPC gateway. Streaming agent/PTY traffic stays on ws://. POST /api/v1/rpc reaches every RPC method. Core RPC methods: ${rpcMethods.length}. Categories: ${METHOD_CATEGORIES.join(", ")}.`
+    },
+    paths,
+    "x-gateway-rpc-methods": rpcMethods
+  };
+}
 async function handleRestRequest(routes, dispatch, req) {
+  const verb = req.method.toUpperCase();
+  if (verb === "OPTIONS") {
+    return {
+      status: 204,
+      body: "",
+      headers: {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": "GET, POST, OPTIONS",
+        "access-control-allow-headers": "Authorization, Content-Type"
+      }
+    };
+  }
   const match = matchRestRoute(routes, req.method, req.path);
   if (!match) {
     return {
@@ -385084,12 +385277,18 @@ async function handleRestRequest(routes, dispatch, req) {
       body: { error: "not_found", message: `No REST route for ${req.method} ${req.path}` }
     };
   }
+  if (match.route.gatewayMethod === "__openapi") {
+    return { status: 200, body: buildOpenApiDocument() };
+  }
   let gatewayMethod = match.route.gatewayMethod;
   let params;
   if (gatewayMethod === "") {
     const raw = req.body ?? {};
     if (!raw.method) {
-      return { status: 400, body: { error: "bad_request", message: 'POST /api/v1/rpc needs {"method": "...", "params": {...}}' } };
+      return {
+        status: 400,
+        body: { error: "bad_request", message: 'POST /api/v1/rpc needs {"method": "...", "params": {...}}' }
+      };
     }
     gatewayMethod = raw.method;
     params = raw.params ?? {};
@@ -385105,6 +385304,52 @@ async function handleRestRequest(routes, dispatch, req) {
     return { status, body: { error: "gateway_error", message } };
   }
 }
+var JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+function readJsonBody(req) {
+  return new Promise((resolve2) => {
+    let data = "";
+    req.on?.("data", (d) => {
+      data += String(d ?? "");
+      if (data.length > 2e6) {
+        resolve2({});
+      }
+    });
+    req.on?.("end", () => {
+      try {
+        resolve2(data ? JSON.parse(data) : {});
+      } catch {
+        resolve2({});
+      }
+    });
+  });
+}
+function makeRestCatchAllHandler(opts) {
+  const routes = defaultRestRoutes();
+  return async (req, res) => {
+    const r = req;
+    const s = res;
+    try {
+      if (!await opts.isAuthorized(r)) {
+        s.writeHead?.(401, JSON_HEADERS);
+        s.end?.(JSON.stringify({ error: "unauthorized" }));
+        return;
+      }
+      const url2 = new URL(r.url ?? "/", "http://localhost");
+      const body = r.method === "POST" || r.method === "PUT" ? await readJsonBody(r) : Object.fromEntries(url2.searchParams.entries());
+      const result = await handleRestRequest(routes, opts.dispatch, {
+        method: r.method ?? "GET",
+        path: url2.pathname,
+        body
+      });
+      s.writeHead?.(result.status, { ...JSON_HEADERS, ...result.headers ?? {} });
+      if (result.body === "" || result.body === void 0) s.end?.();
+      else s.end?.(typeof result.body === "string" ? result.body : JSON.stringify(result.body));
+    } catch (e) {
+      s.writeHead?.(500, JSON_HEADERS);
+      s.end?.(JSON.stringify({ error: "internal", message: e instanceof Error ? e.message : String(e) }));
+    }
+  };
+}
 
 // ../../packages/backend/src/services/Gateway/gatewayRateLimit.ts
 var GatewayRateLimiter = class {
@@ -396172,51 +396417,8 @@ async function startGyBackend() {
     return await target.handleRequest(method, params);
   };
   const buildRestHttpRoutesSync = (opts) => {
-    const routes = defaultRestRoutes();
-    const staticRoutes = routes.filter((r) => !r.path.includes(":")).map((route) => ({
-      path: route.path,
-      handler: makeRestHandler(routes, opts)
-    }));
-    return staticRoutes;
+    return [{ path: "/api/v1/*", handler: makeRestCatchAllHandler(opts) }];
   };
-  const makeRestHandler = (routes, opts) => {
-    return async (req, res) => {
-      const r = req;
-      const s = res;
-      try {
-        if (!await opts.isAuthorized(r)) {
-          s.writeHead?.(401, { "content-type": "application/json" });
-          s.end?.(JSON.stringify({ error: "unauthorized" }));
-          return;
-        }
-        const url2 = new URL(r.url ?? "/", "http://localhost");
-        const body = r.method === "POST" ? await readJsonBody(r) : Object.fromEntries(url2.searchParams.entries());
-        const result = await handleRestRequest(routes, opts.dispatch, {
-          method: r.method ?? "GET",
-          path: url2.pathname,
-          body
-        });
-        s.writeHead?.(result.status, { "content-type": "application/json" });
-        s.end?.(JSON.stringify(result.body));
-      } catch (e) {
-        s.writeHead?.(500, { "content-type": "application/json" });
-        s.end?.(JSON.stringify({ error: "internal", message: e instanceof Error ? e.message : String(e) }));
-      }
-    };
-  };
-  const readJsonBody = (req) => new Promise((resolve2) => {
-    let data = "";
-    req.on?.("data", (d) => {
-      data += String(d ?? "");
-    });
-    req.on?.("end", () => {
-      try {
-        resolve2(data ? JSON.parse(data) : {});
-      } catch {
-        resolve2({});
-      }
-    });
-  });
   const wsGatewayControlService = new WebSocketGatewayControlService({
     createAdapter: (host, port, ipFilter) => {
       const adapter = new WebSocketGatewayAdapter(gatewayService, {
@@ -396712,6 +396914,9 @@ async function startGyBackend() {
     console.log(
       `[gybackend] Live dashboard: http://${wsState.host}:${wsState.port}/dashboard`
     );
+    console.log(
+      `[gybackend] REST API: http://${wsState.host}:${wsState.port}/api/v1/health  (OpenAPI /api/v1/openapi.json)`
+    );
   } else {
     console.log("[gybackend] WebSocket RPC endpoint: disabled");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rterm-backend",
-  "version": "3.7.6",
+  "version": "3.8.0",
   "description": "AI-native terminal & agentic-AI operations platform for Forward Deployed Engineers & SREs: AIOps closed-loop remediation, AI SRE, self-healing infrastructure, runbook automation, ChatOps; executes over SSH/WinRM/serial under policy with tamper-evident audit.",
   "keywords": [
     "forward-deployed-engineer",