byob-cli 0.2.9 → 0.2.11

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "byob-cli",
-  "version": "0.1.0",
+  "version": "0.2.11",
   "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 opens the project container as the active Codex workspace. It is powered by `codex ssh-proxy`:
+
+```bash
+npx -y byob-cli@latest codex ssh-proxy '{"ssh_endpoint":"wss://..."}'
+```
+
+Use `byob-cli@latest` for Local Codex billed.
+
 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
+
+When a user chooses **Local Codex billed**, open the BYOB project as the active Codex workspace 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. Hand the returned workspace metadata to the Codex host so `/home/workspace/app_data` becomes the active workspace.
+4. Keep tokens, private keys, and complete proxy commands out of chat.
+5. Use Codex's normal file, shell, and git workflow inside that active workspace.
+
+The underlying proxy command bridges 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@latest codex ssh-proxy '{\"ssh_endpoint\":\"<ssh_endpoint>\"}'" \
+  byob@byob-project
+```
+
+Agents and hosts should keep this user-facing: say "Local Codex billed", not internal labels such as `ssh_gateway`, unless debugging the connector itself.
+
 ## 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.11",
   "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**, open the BYOB project as the active Codex workspace 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 Local Codex billed workspace details through `byob-cli@latest`'s `codex ssh-proxy`.
+
+Local Codex billed 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"; avoid internal enum names unless debugging BYOB itself.
+
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
+
 ## 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, open the BYOB project as the active Codex workspace immediately instead of 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 Local Codex billed workspace metadata through `byob-cli@latest` so Codex edits the remote project container as its active workspace.
+5. Do not print tokens, private keys, or full proxy commands in chat.
+
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
+
 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 that the remote BYOB project container becomes the active Codex workspace. 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 Local Codex billed workspace details with `byob-cli@latest`'s `codex ssh-proxy`.
+5. Keep credentials out of chat, logs, screenshots, and command transcripts.
+
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
+
 ## Project Scope
 
 The user approves specific projects during browser approval. The agent token can only access those project ids.