feat: add Codex-style tool mode

docs/chatgpt-coding-workflow.md

@@ -119,6 +119,20 @@ Legacy names are available with `DEVSPACE_TOOL_NAMING=legacy`:
 
 Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
 
+The experimental Codex-style surface is enabled with
+`DEVSPACE_TOOL_MODE=codex`. It exposes:
+
+- `open_workspace`
+- `read`
+- `apply_patch`
+- `exec_command`
+- `write_stdin`
+
+In this mode, `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are not
+registered. `exec_command` returns a process session ID when a command is still
+running after its yield window. Use `write_stdin` to poll it, send input, resize
+a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
+
 ## Show Changes
 
 By default, `DEVSPACE_WIDGETS=full`.

docs/codex-tool-mode-qa.md

@@ -0,0 +1,73 @@
+# Codex Tool Mode Manual QA
+
+Run these checks against a disposable Git repository inside an allowed DevSpace
+root. Keep the DevSpace server logs visible during the test.
+
+## Setup
+
+1. Build the current branch with `npm ci && npm run build`.
+2. Start DevSpace with `DEVSPACE_TOOL_MODE=codex devspace serve`.
+3. Connect or refresh the DevSpace connector in ChatGPT.
+4. Open the disposable repository with `open_workspace`.
+5. Confirm the core tools are `open_workspace`, `read`, `apply_patch`,
+   `exec_command`, and `write_stdin`.
+6. Confirm `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are absent.
+7. If `DEVSPACE_WIDGETS=changes`, also expect `show_changes`.
+
+## Apply Patch
+
+1. Add a text file containing multiple lines and a blank line.
+2. Update two separate regions of that file in one patch.
+3. Create a nested file, rename it, and then delete it.
+4. Patch an existing CRLF file and verify it remains CRLF.
+5. Verify executable permissions survive an update and a move.
+6. Try to add `../outside.txt`; confirm the tool rejects the path.
+7. Patch through a symlink targeting an external directory; confirm rejection.
+8. Submit a hunk whose context is absent; confirm no file from that patch changes.
+9. With changes widgets enabled, inspect the aggregate diff.
+
+## Foreground Commands
+
+1. Run `pwd` and confirm it reports the opened workspace.
+2. Run a command in a relative `workingDirectory` and confirm the directory.
+3. Write to stdout and stderr; confirm both appear.
+4. Exit nonzero; confirm `running=false` and the exit code.
+5. Use a small output budget on a noisy command; confirm truncation is reported.
+
+## Background Sessions
+
+1. Start a delayed command with a short yield time.
+2. Confirm `exec_command` returns `running=true` and a `sessionId`.
+3. Poll with empty `chars`; confirm output is not duplicated.
+4. Poll until completion; confirm the final exit code and no `sessionId`.
+5. Poll the completed session again; confirm it is unknown.
+6. Reconnect MCP without restarting DevSpace and confirm polling still works.
+7. Restart DevSpace and confirm old process session IDs are invalid.
+
+## Input, Interrupt, And PTY
+
+1. Start a program that reads stdin without a PTY and send it a line.
+2. Start a long-running process and send `\u0003`; confirm it stops.
+3. Start an interactive program with `tty=true`; confirm it detects a TTY.
+4. Resize a PTY from 80x24 to 120x30 and verify the observed dimensions.
+5. Omit optional dependencies; normal commands must work and `tty=true` must
+   return the explicit `node-pty` error.
+
+## Cleanup
+
+1. Start a non-PTY command that creates a long-running child process.
+2. Stop DevSpace with SIGINT and verify both shell and child exit.
+3. Repeat with a PTY command.
+4. Confirm no process remains after server exit.
+5. Repeat session cycles and check that memory use does not steadily increase.
+
+## Existing Mode Regression
+
+1. Start without `DEVSPACE_TOOL_MODE`; confirm `minimal` remains the default.
+2. Minimal must expose `read`, `write`, `edit`, and `bash`, but not Codex tools
+   or dedicated search tools.
+3. `DEVSPACE_TOOL_MODE=full` must add `grep`, `glob`, and `ls`.
+4. With no explicit mode, `DEVSPACE_MINIMAL_TOOLS=1` maps to minimal and `0`
+   maps to full.
+5. Set `DEVSPACE_TOOL_MODE=codex` with `DEVSPACE_MINIMAL_TOOLS=0`; confirm the
+   explicit Codex mode wins.

docs/configuration.md

@@ -70,8 +70,19 @@ MCP clients discover metadata from:
 
 | Value | Behavior |
 | --- | --- |
-| `minimal` | Default. Disables dedicated search and list tools. Clients use the shell tool with `rg`, `grep`, `find`, `ls`, or `tree` for inspection. |
-| `full` | Enables dedicated `grep`, `glob`, and `ls` tools. |
+| `minimal` | Default. Exposes `open_workspace`, `read`, `write`, `edit`, and `bash`. Clients use `bash` with tools such as `rg`, `find`, and `ls` for inspection. |
+| `full` | Exposes the minimal tools plus dedicated `grep`, `glob`, and `ls` tools. |
+| `codex` | Experimental. Exposes `open_workspace`, `read`, `apply_patch`, `exec_command`, and `write_stdin`. Existing mutation and shell tools are hidden. |
+
+`DEVSPACE_MINIMAL_TOOLS` remains a backward-compatible alias when
+`DEVSPACE_TOOL_MODE` is unset: `1` selects `minimal` and `0` selects `full`.
+The `codex` mode must be selected through `DEVSPACE_TOOL_MODE` and always uses
+its fixed short tool names regardless of `DEVSPACE_TOOL_NAMING`.
+
+Codex-mode commands run without a PTY by default. Set `tty: true` on
+`exec_command` for interactive terminal programs. PTY support uses the optional
+`node-pty` dependency; `write_stdin` can send input, poll output, and resize PTY
+sessions.
 
 ## Widgets
 

package.json

@@ -24,8 +24,9 @@
     "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
     "build:app": "vite build",
     "dev": "node scripts/dev-server.mjs",
+    "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/ui/card-types.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],
@@ -60,5 +61,8 @@
   "overrides": {
     "protobufjs": "7.6.4",
     "ws": "8.21.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
   }
 }

scripts/fix-node-pty-permissions.mjs

@@ -0,0 +1,22 @@
+import { chmod } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.platform === "darwin") {
+  const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  for (const architecture of ["arm64", "x64"]) {
+    const helper = resolve(
+      projectRoot,
+      "node_modules",
+      "node-pty",
+      "prebuilds",
+      `darwin-${architecture}`,
+      "spawn-helper",
+    );
+    try {
+      await chmod(helper, 0o755);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}

src/apply-patch.test.ts

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { chmod, mkdtemp, readFile, stat, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyPatch, parsePatch, replaceFile } from "./apply-patch.js";
+
+const root = await mkdtemp(join(tmpdir(), "devspace-apply-patch-"));
+const replacement = join(root, "replacement.txt");
+const replacementTemporary = join(root, "replacement.tmp");
+await writeFile(replacement, "old\n");
+await writeFile(replacementTemporary, "new\n");
+await replaceFile(replacementTemporary, replacement, true, "win32");
+assert.equal(await readFile(replacement, "utf8"), "new\n");
+await writeFile(join(root, "alpha.txt"), "one\ntwo\nthree\n");
+await writeFile(join(root, "remove.txt"), "remove me\n");
+await writeFile(join(root, "windows.txt"), "first\r\nsecond\r\n");
+
+const result = await applyPatch(
+  root,
+  `*** Begin Patch
+*** Add File: nested/added.txt
++new
++file
+*** Update File: alpha.txt
+@@
+ one
+-two
++changed
+ three
+*** Update File: windows.txt
+@@
+ first
+-second
++updated
+*** Delete File: remove.txt
+*** End Patch`,
+);
+
+assert.deepEqual(result.files, [
+  { path: "nested/added.txt", operation: "add" },
+  { path: "alpha.txt", operation: "update" },
+  { path: "windows.txt", operation: "update" },
+  { path: "remove.txt", operation: "delete" },
+]);
+assert.equal(result.additions, 4);
+assert.equal(result.removals, 3);
+assert.match(result.patch, /diff --git a\/alpha\.txt b\/alpha\.txt/);
+assert.match(result.patch, /-two\n\+changed/);
+assert.equal(await readFile(join(root, "nested/added.txt"), "utf8"), "new\nfile\n");
+assert.equal(await readFile(join(root, "alpha.txt"), "utf8"), "one\nchanged\nthree\n");
+assert.equal(await readFile(join(root, "windows.txt"), "utf8"), "first\r\nupdated\r\n");
+await assert.rejects(readFile(join(root, "remove.txt"), "utf8"), /ENOENT/);
+
+if (process.platform !== "win32") await chmod(join(root, "alpha.txt"), 0o755);
+const moveResult = await applyPatch(
+  root,
+  `*** Begin Patch
+*** Update File: alpha.txt
+*** Move to: moved/alpha.txt
+@@
+-one
++ONE
+ changed
+*** End Patch`,
+);
+assert.deepEqual(moveResult.files, [
+  { path: "moved/alpha.txt", previousPath: "alpha.txt", operation: "move" },
+]);
+assert.equal(await readFile(join(root, "moved/alpha.txt"), "utf8"), "ONE\nchanged\nthree\n");
+if (process.platform !== "win32") {
+  assert.notEqual((await stat(join(root, "moved/alpha.txt"))).mode & 0o111, 0);
+}
+await assert.rejects(readFile(join(root, "alpha.txt"), "utf8"), /ENOENT/);
+
+await assert.rejects(
+  applyPatch(
+    root,
+    `*** Begin Patch
+*** Add File: ../escape.txt
++no
+*** End Patch`,
+  ),
+  /path escapes the workspace/,
+);
+
+const outside = await mkdtemp(join(tmpdir(), "devspace-apply-patch-outside-"));
+await symlink(outside, join(root, "outside-link"), process.platform === "win32" ? "junction" : "dir");
+await assert.rejects(
+  applyPatch(
+    root,
+    `*** Begin Patch
+*** Add File: outside-link/escape.txt
++no
+*** End Patch`,
+  ),
+  /path resolves outside the workspace/,
+);
+
+await assert.rejects(
+  applyPatch(
+    root,
+    `*** Begin Patch
+*** Update File: moved/alpha.txt
+@@
+-not present
++replacement
+*** End Patch`,
+  ),
+  /could not find hunk context/,
+);
+assert.equal(await readFile(join(root, "moved/alpha.txt"), "utf8"), "ONE\nchanged\nthree\n");
+
+await assert.rejects(
+  applyPatch(
+    root,
+    `*** Begin Patch
+*** Add File: should-not-exist.txt
++staged
+*** Update File: moved/alpha.txt
+@@
+-missing context
++replacement
+*** End Patch`,
+  ),
+  /could not find hunk context/,
+);
+await assert.rejects(readFile(join(root, "should-not-exist.txt"), "utf8"), /ENOENT/);
+
+assert.throws(() => parsePatch("*** Begin Patch\n*** End Patch"), /contains no file actions/);
+assert.throws(() => parsePatch("*** Add File: bad.txt\n+x"), /missing .* marker/);