byob-cli 0.2.10 → 0.2.12

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "byob-cli",
-  "version": "0.2.10",
+  "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,13 +30,13 @@ 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:
+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@0.2.10 codex ssh-proxy '{"ssh_endpoint":"wss://..."}'
+npx -y byob-cli@latest 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.
+Use `byob-cli@latest` for Local Codex billed.
 
 Or install it globally:
 
@@ -201,26 +201,26 @@ 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
+### Local Codex Billed
 
-When a user chooses **Local Codex billed**, prefer the SSH-backed route from the start of the edit session:
+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. 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.
+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.
 
-The proxy command is intentionally a local bridge from OpenSSH stdio to AIR's authenticated WebSocket endpoint:
+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@0.2.10 codex ssh-proxy '{\"ssh_endpoint\":\"<ssh_endpoint>\"}'" \
+  -o ProxyCommand="npx -y byob-cli@latest 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.
+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
 

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.10",
+  "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

@@ -67,17 +67,17 @@ Do not add BYOB platform helper tools into user containers. Do not ask for BYOB
 
 ## 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:
+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 SSH connection through `byob-cli@0.2.10` or newer'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.
 
-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.
+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.
 
-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.
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
 
 ## Skill Routing
 

package/skills/byob_cli/SKILL.md

@@ -53,15 +53,15 @@ 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:
+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 SSH proxy connection through `byob-cli@0.2.10` or newer to inspect and edit files in the remote project container.
+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.
 
-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.
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
 
 Equivalent raw PRIM flow:
 
@@ -284,17 +284,17 @@ Do not assume `byob_*` tools exist inside the user container. They are platform
 
 ## 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.
+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 SSH connection details with `byob-cli@0.2.10` or newer'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.
 
-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.
+After the workspace is open, use Codex's normal file, shell, git, and verification workflow inside the remote project.
 
 ## Project Scope