byob-cli 0.2.9 → 0.2.10

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "byob-cli",
-  "version": "0.1.0",
+  "version": "0.2.10",
   "description": "Codex connector for BYOB projects, backed by Agent MCP with project context, deployment helpers, and coding tools.",
   "skills": "./skills/byob_cli/",
   "mcpServers": "./.mcp.json"

package/README.md

@@ -30,6 +30,14 @@ Refresh synced coding skills later without rerunning OAuth or changing MCP confi
 npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
 ```
 
+For Local Codex billed project editing, the BYOB Agent MCP creates a short-lived SSH-style project connection and returns an `ssh_proxy_command` that uses:
+
+```bash
+npx -y byob-cli@0.2.10 codex ssh-proxy '{"ssh_endpoint":"wss://..."}'
+```
+
+Use `byob-cli@0.2.10` or newer for this route. Older published versions do not contain `codex ssh-proxy`, so they cannot bridge the Local Codex billed connection into the running project container.
+
 Or install it globally:
 
 ```bash
@@ -193,6 +201,27 @@ npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_acces
 
 `codex sync-skills` downloads AIR coding-skill resources and rewrites their local skill names with `byob_` prefixes. It does not run OAuth, does not call `codex mcp add`, and does not change the active MCP server config.
 
+### Local Codex Billed SSH Route
+
+When a user chooses **Local Codex billed**, prefer the SSH-backed route from the start of the edit session:
+
+1. Call `byob_codex_status` for the selected project.
+2. If `Local Codex billed` is available, call `byob_codex_connection_create` with `connection_type: "ssh_gateway"`.
+3. Use the returned SSH connection details through `byob-cli@0.2.10` or newer. Do not print tokens, private keys, or the full proxy command in chat.
+4. Connect with the returned SSH proxy and inspect/edit the remote project filesystem directly.
+5. Fall back to Agent MCP coding tools only when the SSH route is unavailable or the host environment cannot launch the proxy.
+
+The proxy command is intentionally a local bridge from OpenSSH stdio to AIR's authenticated WebSocket endpoint:
+
+```bash
+BYOB_CODEX_SSH_TOKEN=<connection_token> \
+ssh -i <temporary_key_file> \
+  -o ProxyCommand="npx -y byob-cli@0.2.10 codex ssh-proxy '{\"ssh_endpoint\":\"<ssh_endpoint>\"}'" \
+  byob@byob-project
+```
+
+Agents should keep this user-facing: say "Local Codex billed connection" or "SSH-backed project connection", not internal labels such as `ssh_gateway`, unless debugging the connector itself. If `npx -y byob-cli codex ssh-proxy` returns `Unknown command: codex`, the installed/published CLI is too old; upgrade to `byob-cli@0.2.10` or newer instead of retrying the same command.
+
 ## Multiple Projects
 
 BYOB grants can cover more than one approved project. There are two supported install shapes.

package/bin/byob.js

@@ -3,6 +3,9 @@
 import { createInterface } from "node:readline";
 import { spawn, spawnSync } from "node:child_process";
 import { copyFileSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import net from "node:net";
+import tls from "node:tls";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -38,6 +41,7 @@ Usage:
   byob config
   byob codex install
   byob codex sync-skills
+  byob codex ssh-proxy [json_args]
 
 Options:
   --air-url <url>       Default: BYOB_AIR_URL or https://air.api.byob.studio
@@ -191,12 +195,49 @@ async function mcpRequest(opts, method, params = {}, requestId = Date.now(), pro
   });
 }
 
-function printJson(payload) {
-  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+function publicPreviewUrl(projectId) {
+  const id = String(projectId || "").trim();
+  return id ? `https://preview.${id}.api.byob.studio` : "";
 }
 
-function printMcpResponse(payload) {
-  process.stdout.write(`${JSON.stringify(payload)}\n`);
+function sanitizePreviewUrls(value, projectIdHint = "", { sanitizeText = false } = {}) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizePreviewUrls(item, projectIdHint, { sanitizeText }));
+  }
+  if (!value || typeof value !== "object") {
+    if (sanitizeText && typeof value === "string") {
+      try {
+        const parsed = JSON.parse(value);
+        return JSON.stringify(sanitizePreviewUrls(parsed, projectIdHint, { sanitizeText }), null, 2);
+      } catch {
+        return value;
+      }
+    }
+    return value;
+  }
+
+  const localProjectId = value.project_id || value.id || projectIdHint;
+  const sanitized = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "preview_url") {
+      sanitized[key] = publicPreviewUrl(localProjectId) || item;
+      continue;
+    }
+    sanitized[key] = sanitizePreviewUrls(item, localProjectId, {
+      sanitizeText: sanitizeText && key === "text",
+    });
+  }
+  return sanitized;
+}
+
+function printJson(payload, projectIdHint = "", sanitizeText = false) {
+  const safePayload = sanitizePreviewUrls(payload, projectIdHint, { sanitizeText });
+  process.stdout.write(`${JSON.stringify(safePayload, null, 2)}\n`);
+}
+
+function printMcpResponse(payload, projectIdHint = "", sanitizeText = false) {
+  const safePayload = sanitizePreviewUrls(payload, projectIdHint, { sanitizeText });
+  process.stdout.write(`${JSON.stringify(safePayload)}\n`);
 }
 
 function byobBanner() {
@@ -288,7 +329,8 @@ async function serve(opts) {
         timeoutSeconds: opts.timeout,
         body: request,
       });
-      printMcpResponse(response);
+      const toolName = request?.method === "tools/call" ? request?.params?.name || "" : "";
+      printMcpResponse(response, projectId, String(toolName).startsWith("byob_"));
     } catch (error) {
       printMcpResponse({
         jsonrpc: "2.0",
@@ -645,7 +687,7 @@ async function callTool(opts, toolName, rawArgs) {
     name: toolName,
     arguments: toolArgs,
   }, Date.now(), projectId);
-  printJson(response);
+  printJson(response, projectId, toolName.startsWith("byob_"));
 }
 
 async function aliasCall(opts, alias, rawArgs) {
@@ -668,8 +710,9 @@ async function projects(opts) {
 }
 
 async function resources(opts) {
-  const response = await mcpRequest(opts, "resources/list");
-  printJson(response);
+  const projectId = requireProject(opts);
+  const response = await mcpRequest(opts, "resources/list", {}, Date.now(), projectId);
+  printJson(response, projectId, true);
 }
 
 async function context(opts, rawArgs) {
@@ -679,7 +722,7 @@ async function context(opts, rawArgs) {
     name: "byob_current_project_context",
     arguments: { project_id: projectId },
   }, Date.now(), projectId);
-  printJson(response);
+  printJson(response, projectId, true);
 }
 
 async function contextResource(opts, rawArgs) {
@@ -693,7 +736,180 @@ async function contextResource(opts, rawArgs) {
     Date.now(),
     projectId,
   );
-  printJson(response);
+  printJson(response, projectId, true);
+}
+
+function truthy(value) {
+  return ["1", "true", "yes", "on"].includes(String(value || "").trim().toLowerCase());
+}
+
+function websocketFrame(opcode, payload = Buffer.alloc(0)) {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  let headerLength = 2;
+  if (body.length >= 126 && body.length <= 65535) headerLength += 2;
+  else if (body.length > 65535) headerLength += 8;
+  const mask = randomBytes(4);
+  const frame = Buffer.alloc(headerLength + 4 + body.length);
+  frame[0] = 0x80 | opcode;
+  if (body.length < 126) {
+    frame[1] = 0x80 | body.length;
+  } else if (body.length <= 65535) {
+    frame[1] = 0x80 | 126;
+    frame.writeUInt16BE(body.length, 2);
+  } else {
+    frame[1] = 0x80 | 127;
+    frame.writeBigUInt64BE(BigInt(body.length), 2);
+  }
+  mask.copy(frame, headerLength);
+  for (let i = 0; i < body.length; i += 1) {
+    frame[headerLength + 4 + i] = body[i] ^ mask[i % 4];
+  }
+  return frame;
+}
+
+function parseWebSocketFrames(buffer, onPayload) {
+  let offset = 0;
+  while (buffer.length - offset >= 2) {
+    const first = buffer[offset];
+    const second = buffer[offset + 1];
+    const opcode = first & 0x0f;
+    const masked = Boolean(second & 0x80);
+    let length = second & 0x7f;
+    let headerLength = 2;
+    if (length === 126) {
+      if (buffer.length - offset < 4) break;
+      length = buffer.readUInt16BE(offset + 2);
+      headerLength = 4;
+    } else if (length === 127) {
+      if (buffer.length - offset < 10) break;
+      const bigLength = buffer.readBigUInt64BE(offset + 2);
+      if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("WebSocket frame too large.");
+      length = Number(bigLength);
+      headerLength = 10;
+    }
+    const maskLength = masked ? 4 : 0;
+    if (buffer.length - offset < headerLength + maskLength + length) break;
+    const mask = masked ? buffer.subarray(offset + headerLength, offset + headerLength + 4) : null;
+    const payloadStart = offset + headerLength + maskLength;
+    const payload = Buffer.from(buffer.subarray(payloadStart, payloadStart + length));
+    if (mask) {
+      for (let i = 0; i < payload.length; i += 1) payload[i] ^= mask[i % 4];
+    }
+    if (opcode === 0x8) return { remaining: Buffer.alloc(0), closed: true };
+    if (opcode === 0x9) onPayload(null, websocketFrame(0xA, payload));
+    else if (opcode === 0x1 || opcode === 0x2 || opcode === 0x0) onPayload(payload, null);
+    offset = payloadStart + length;
+  }
+  return { remaining: buffer.subarray(offset), closed: false };
+}
+
+async function websocketToStdio(endpoint, token, options = {}) {
+  const url = new URL(endpoint);
+  const isTls = url.protocol === "wss:";
+  if (!["ws:", "wss:"].includes(url.protocol)) {
+    throw new Error("SSH endpoint must be a ws:// or wss:// URL.");
+  }
+  const port = Number(url.port || (isTls ? 443 : 80));
+  const tlsCaCert = options.tlsCaCert || process.env.BYOB_CODEX_SSH_CA_CERT || "";
+  const tlsInsecure = Boolean(options.tlsInsecure) || truthy(process.env.BYOB_CODEX_SSH_TLS_INSECURE);
+  const tlsOptions = {};
+  if (isTls) {
+    if (tlsCaCert) tlsOptions.ca = readFileSync(tlsCaCert, "utf8");
+    if (tlsInsecure) tlsOptions.rejectUnauthorized = false;
+  }
+  const socket = isTls
+    ? tls.connect({ host: url.hostname, port, servername: url.hostname, ...tlsOptions })
+    : net.connect({ host: url.hostname, port });
+
+  await new Promise((resolve, reject) => {
+    socket.once(isTls ? "secureConnect" : "connect", resolve);
+    socket.once("error", reject);
+  });
+
+  const key = randomBytes(16).toString("base64");
+  const path = `${url.pathname || "/"}${url.search || ""}`;
+  socket.write(
+    [
+      `GET ${path} HTTP/1.1`,
+      `Host: ${url.host}`,
+      "Upgrade: websocket",
+      "Connection: Upgrade",
+      `Sec-WebSocket-Key: ${key}`,
+      "Sec-WebSocket-Version: 13",
+      token ? `Authorization: Bearer ${token}` : "",
+      "",
+      "",
+    ].filter((line) => line !== null).join("\r\n"),
+  );
+
+  await new Promise((resolve, reject) => {
+    let handshake = Buffer.alloc(0);
+    function onData(chunk) {
+      handshake = Buffer.concat([handshake, chunk]);
+      const end = handshake.indexOf("\r\n\r\n");
+      if (end === -1) return;
+      socket.off("data", onData);
+      const headerText = handshake.subarray(0, end).toString("utf8");
+      if (!/^HTTP\/1\.1 101\b/i.test(headerText)) {
+        reject(new Error(`WebSocket upgrade failed: ${headerText.split(/\r?\n/)[0] || "unknown response"}`));
+        return;
+      }
+      const acceptHeader = headerText
+        .split(/\r?\n/)
+        .find((line) => /^sec-websocket-accept:/i.test(line))
+        ?.split(":")
+        .slice(1)
+        .join(":")
+        .trim();
+      const expectedAccept = createHash("sha1")
+        .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+        .digest("base64");
+      if (acceptHeader !== expectedAccept) {
+        reject(new Error("WebSocket upgrade failed: invalid Sec-WebSocket-Accept header"));
+        return;
+      }
+      const leftover = handshake.subarray(end + 4);
+      if (leftover.length) socket.emit("byob-leftover", leftover);
+      resolve();
+    }
+    socket.on("data", onData);
+    socket.once("error", reject);
+  });
+
+  let frameBuffer = Buffer.alloc(0);
+  const handleChunk = (chunk) => {
+    frameBuffer = Buffer.concat([frameBuffer, chunk]);
+    const parsed = parseWebSocketFrames(frameBuffer, (payload, controlFrame) => {
+      if (controlFrame) socket.write(controlFrame);
+      if (payload) process.stdout.write(payload);
+    });
+    frameBuffer = parsed.remaining;
+    if (parsed.closed) process.exit(0);
+  };
+  socket.on("byob-leftover", handleChunk);
+  socket.on("data", handleChunk);
+  socket.on("close", () => process.exit(0));
+  socket.on("error", (error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  });
+
+  process.stdin.on("data", (chunk) => socket.write(websocketFrame(0x2, chunk)));
+  process.stdin.on("end", () => socket.write(websocketFrame(0x8)));
+  process.stdin.resume();
+  await new Promise((resolve) => socket.once("close", resolve));
+}
+
+async function codexSshProxy(_opts, rawArgs) {
+  const args = parseJsonArg(rawArgs);
+  const endpoint = args.ssh_endpoint || process.env.BYOB_CODEX_SSH_ENDPOINT || "";
+  const tokenEnvVar = args.token_env_var || "BYOB_CODEX_SSH_TOKEN";
+  const token = args.token || process.env[tokenEnvVar] || process.env.BYOB_CODEX_SSH_TOKEN || "";
+  const tlsCaCert = args.tls_ca_cert || args.ca_cert || process.env.BYOB_CODEX_SSH_CA_CERT || "";
+  const tlsInsecure = truthy(args.tls_insecure) || truthy(args.insecure_tls);
+  if (!endpoint) throw new Error("Missing SSH endpoint. Pass {\"ssh_endpoint\":\"wss://...\"} or set BYOB_CODEX_SSH_ENDPOINT.");
+  if (!token) throw new Error(`Missing SSH token. Set ${tokenEnvVar}.`);
+  await websocketToStdio(endpoint, token, { tlsCaCert, tlsInsecure });
 }
 
 async function main() {
@@ -708,6 +924,7 @@ async function main() {
   if (command === "mcp") return serve(opts);
   if (command === "codex" && first === "install") return codexInstall(opts);
   if (command === "codex" && first === "sync-skills") return codexSyncSkills(opts);
+  if (command === "codex" && first === "ssh-proxy") return codexSshProxy(opts, second);
   if (command === "config") return config(opts);
   if (command === "device-code") return deviceCode(opts);
   if (command === "token") return token(opts, first);
@@ -716,8 +933,14 @@ async function main() {
   if (command === "context-resource") return contextResource(opts, first);
   if (command === "resources") return resources(opts);
   if (command === "projects") return projects(opts);
-  if (command === "initialize") return printJson(await mcpRequest(opts, "initialize"));
-  if (command === "tools") return printJson(await mcpRequest(opts, "tools/list"));
+  if (command === "initialize") {
+    const projectId = requireProject(opts);
+    return printJson(await mcpRequest(opts, "initialize", {}, Date.now(), projectId), projectId, true);
+  }
+  if (command === "tools") {
+    const projectId = requireProject(opts);
+    return printJson(await mcpRequest(opts, "tools/list", {}, Date.now(), projectId), projectId, true);
+  }
   if (command === "call") return callTool(opts, first, second);
   if (["status", "start", "deploy", "billing", "credits", "payment-url", "env-status", "grants", "dns"].includes(command)) {
     return aliasCall(opts, command, first);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byob-cli",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Codex connector for BYOB projects, backed by an Agent MCP stdio bridge.",
   "license": "MIT",
   "type": "module",

package/skills/byob_cli/CODEX_CORE.md

@@ -65,6 +65,20 @@ Use coding/container tools for:
 
 Do not add BYOB platform helper tools into user containers. Do not ask for BYOB internal tokens, editor tokens, preview tokens, Git tokens, Cloudflare tokens, service-role keys, or raw MCP credentials.
 
+## Local Codex Billed Route
+
+When the user selects **Local Codex billed**, prefer the SSH-backed project connection before trying lower-fidelity Agent MCP workarounds. The expected path is:
+
+1. Establish active project context.
+2. Ensure the project is started and remote editing is available.
+3. Call `byob_codex_status`.
+4. Create a Local Codex billed connection with `byob_codex_connection_create`.
+5. Use the returned SSH connection through `byob-cli@0.2.10` or newer's `codex ssh-proxy`.
+
+This route should let Codex inspect and edit the remote project filesystem directly, including protected files such as `src/app.html` when the task requires reading them. Keep all returned tokens, private keys, and complete proxy commands out of chat and logs. Use user-facing language like "Local Codex billed connection" or "SSH-backed project connection"; avoid internal enum names unless debugging BYOB itself.
+
+If `npx -y byob-cli codex ssh-proxy` fails with `Unknown command: codex`, treat it as a BYOB CLI version mismatch. The SSH proxy command requires `byob-cli@0.2.10` or newer. Do not continue by repeatedly trying Agent MCP allowlisted command facades for file reads; those facades are designed for build/check/lint/test commands and will reject arbitrary shell/file inspection.
+
 ## Skill Routing
 
 `byob_cli` is the platform/core skill. Load separate synced skills only when the task calls for them. Do not load every skill by default.

package/skills/byob_cli/SKILL.md

@@ -53,6 +53,16 @@ Refresh downloaded coding skills later without rerunning OAuth or changing MCP c
 npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
 ```
 
+For **Local Codex billed** project editing, prefer the SSH-backed project connection immediately instead of first trying to simulate shell/file access through Agent MCP tools:
+
+1. Establish project context with `byob_current_project_context`.
+2. Call `byob_codex_status` and confirm the Local Codex billed option is available.
+3. Call `byob_codex_connection_create` with the Local Codex billed connection type.
+4. Use the returned SSH proxy connection through `byob-cli@0.2.10` or newer to inspect and edit files in the remote project container.
+5. Do not print tokens, private keys, or full proxy commands in chat.
+
+If `npx -y byob-cli codex ssh-proxy` reports `Unknown command: codex`, the local/published CLI is too old for Local Codex billed SSH. Tell the user to use `byob-cli@0.2.10` or newer; do not keep retrying Agent MCP command facades for ordinary file reads. Use Agent MCP project tools as a fallback only when the SSH route is unavailable or the host cannot launch the proxy.
+
 Equivalent raw PRIM flow:
 
 1. Request a device code from PRIM:
@@ -272,6 +282,20 @@ Coding tools are proxied by AIR into the private project container MCP:
 
 Do not assume `byob_*` tools exist inside the user container. They are platform tools and belong to Agent MCP only.
 
+## Local Codex Billed Editing
+
+When the user chooses Local Codex billed, the expected editing path is a short-lived SSH-backed connection into the remote BYOB project container. This gives Codex normal filesystem semantics for reading `src/app.html`, searching source, editing files, and running project-local shell commands through the local Codex account billing path.
+
+Use this flow:
+
+1. Confirm the project is started and `connectivity.can_remote_edit` is true.
+2. Call `byob_codex_status`.
+3. If Local Codex billed is available, call `byob_codex_connection_create` for that mode.
+4. Use the returned SSH connection details with `byob-cli@0.2.10` or newer's `codex ssh-proxy`.
+5. Keep credentials out of chat, logs, screenshots, and command transcripts.
+
+If the SSH proxy cannot be launched because the installed CLI lacks `codex ssh-proxy`, report that as a CLI version mismatch and ask for/choose `byob-cli@0.2.10` or newer. Avoid frustrating loops where Codex repeatedly tries Agent MCP allowlisted commands to read files; those command facades are intentionally limited to build/check/lint/test and are not a replacement for the SSH route.
+
 ## Project Scope
 
 The user approves specific projects during browser approval. The agent token can only access those project ids.