byob-cli 0.2.11 → 0.2.12

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "byob-cli",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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,7 +30,7 @@ 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`:
+For Local Codex billed project editing, the BYOB Agent MCP returns a workspace handle that the Codex host opens as the active Codex workspace. The host uses `codex ssh-proxy` behind that handle:
 
 ```bash
 npx -y byob-cli@latest codex ssh-proxy '{"ssh_endpoint":"wss://..."}'
@@ -206,8 +206,8 @@ npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_acces
 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.
+2. If `Local Codex billed` is available, call `byob_codex_connection_create` with `mode: "local_codex_billed"`.
+3. Hand the returned `workspace_handle` 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.
 

package/bin/byob.js

@@ -60,6 +60,25 @@ Options:
 `;
 }
 
+function codexUsage() {
+  return `BYOB Codex Commands
+
+Usage:
+  byob codex install
+  byob codex sync-skills
+  byob codex ssh-proxy [json_args]
+
+Commands:
+  install       Authorize BYOB, configure Codex MCP, and install BYOB skills.
+  sync-skills  Refresh BYOB AIR coding skills for an approved project.
+  ssh-proxy    Bridge OpenSSH stdio to a BYOB Local Codex billed workspace.
+
+Local Codex billed workspaces are normally opened by the Codex host from the
+workspace handle returned by BYOB Agent MCP. Agents should not print or manually
+handle raw SSH tokens, private keys, or complete proxy commands.
+`;
+}
+
 function parseArgs(argv) {
   const opts = {
     airUrl: DEFAULT_AIR_URL,
@@ -200,15 +219,23 @@ function publicPreviewUrl(projectId) {
   return id ? `https://preview.${id}.api.byob.studio` : "";
 }
 
-function sanitizePreviewUrls(value, projectIdHint = "", { sanitizeText = false } = {}) {
+function sanitizePreviewUrls(
+  value,
+  projectIdHint = "",
+  { sanitizeText = false, redactPrivateMeta = false } = {},
+) {
   if (Array.isArray(value)) {
-    return value.map((item) => sanitizePreviewUrls(item, projectIdHint, { sanitizeText }));
+    return value.map((item) => sanitizePreviewUrls(item, projectIdHint, { sanitizeText, redactPrivateMeta }));
   }
   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);
+        return JSON.stringify(
+          sanitizePreviewUrls(parsed, projectIdHint, { sanitizeText, redactPrivateMeta }),
+          null,
+          2,
+        );
       } catch {
         return value;
       }
@@ -219,19 +246,42 @@ function sanitizePreviewUrls(value, projectIdHint = "", { sanitizeText = false }
   const localProjectId = value.project_id || value.id || projectIdHint;
   const sanitized = {};
   for (const [key, item] of Object.entries(value)) {
+    if (
+      redactPrivateMeta &&
+      key === "_meta" &&
+      item &&
+      typeof item === "object" &&
+      item.byob_local_codex_workspace
+    ) {
+      sanitized[key] = {
+        ...item,
+        byob_local_codex_workspace: {
+          ...item.byob_local_codex_workspace,
+          ssh: {
+            redacted: true,
+            reason: "Use the workspace_handle with a Codex host; direct CLI display omits raw SSH material.",
+          },
+        },
+      };
+      continue;
+    }
     if (key === "preview_url") {
       sanitized[key] = publicPreviewUrl(localProjectId) || item;
       continue;
     }
     sanitized[key] = sanitizePreviewUrls(item, localProjectId, {
       sanitizeText: sanitizeText && key === "text",
+      redactPrivateMeta,
     });
   }
   return sanitized;
 }
 
 function printJson(payload, projectIdHint = "", sanitizeText = false) {
-  const safePayload = sanitizePreviewUrls(payload, projectIdHint, { sanitizeText });
+  const safePayload = sanitizePreviewUrls(payload, projectIdHint, {
+    sanitizeText,
+    redactPrivateMeta: true,
+  });
   process.stdout.write(`${JSON.stringify(safePayload, null, 2)}\n`);
 }
 
@@ -922,9 +972,14 @@ async function main() {
   }
 
   if (command === "mcp") return serve(opts);
+  if (command === "codex" && (!first || first === "help")) {
+    process.stdout.write(codexUsage());
+    return;
+  }
   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 === "codex") throw new Error(`Unknown codex command: ${first || ""}`);
   if (command === "config") return config(opts);
   if (command === "device-code") return deviceCode(opts);
   if (command === "token") return token(opts, first);

package/package.json

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

package/skills/byob_cli/CODEX_CORE.md

@@ -72,10 +72,10 @@ When the user selects **Local Codex billed**, open the BYOB project as the activ
 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`.
+4. Create a Local Codex billed connection with `byob_codex_connection_create` using `mode: "local_codex_billed"`.
+5. Hand the returned Local Codex billed `workspace_handle` to the Codex host; the host uses `byob-cli@latest`'s `codex ssh-proxy` behind that handle.
 
-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.
+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 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.
 

package/skills/byob_cli/SKILL.md

@@ -57,8 +57,8 @@ For **Local Codex billed** project editing, open the BYOB project as the active
 
 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.
+3. Call `byob_codex_connection_create` with `mode: "local_codex_billed"`.
+4. Hand the returned Local Codex billed `workspace_handle` to the Codex host 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.
@@ -290,8 +290,8 @@ 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`.
+3. If Local Codex billed is available, call `byob_codex_connection_create` with `mode: "local_codex_billed"`.
+4. Hand the returned Local Codex billed `workspace_handle` to the Codex host; the host uses `byob-cli@latest`'s `codex ssh-proxy` behind that handle.
 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.