deepcodex 0.1.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "opencodex",
+  "version": "0.1.0+codex.20260917024812",
+  "description": "Delegates tasks to native DeepSeek Flash subagents inside Codex through a local router.",
+  "author": {
+    "name": "OpenCodex"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "OpenCodex",
+    "shortDescription": "Astra coordinates; DeepSeek Flash executes.",
+    "longDescription": "Keeps the coordinator model and connects DeepSeek Flash as a native subagent, with tracking, tools, and results inside Codex.",
+    "developerName": "OpenCodex",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Check whether OpenCodex is ready.",
+      "Delegate this implementation to Flash with OpenCodex."
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenCodex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# OpenCodex
+
+OpenCodex keeps the coordinator on your selected native Codex model and runs
+DeepSeek Flash as an actual Codex subagent through a local loopback router. The
+subagent appears in the normal collaboration tools (`spawn_agent`,
+`followup_task`, `wait_agent`, `interrupt_agent`) under the model name
+`deepseek-flash`. Nothing is disguised under an OpenAI model name, and the
+native coordinator model is not replaced.
+
+## Requirements
+
+- macOS. The installer and the LaunchAgent service are macOS-only.
+- Node.js >= 22.15. The worker uses `node:sqlite`, `fetch` and
+  `import.meta.resolve`.
+- A Codex CLI on `PATH` whose `codex exec` supports `--ignore-user-config`,
+  `--ephemeral`, `--json` and `--strict-config`. `opencodex doctor` verifies
+  this before anything else is activated.
+- A DeepSeek API key.
+
+## Install globally
+
+Once the package is published to npm:
+
+```sh
+npm install --global opencodex
+opencodex configure
+opencodex doctor
+opencodex install
+```
+
+The global installation adds `opencodex` to npm's global bin directory, which
+must be on your `PATH`. Run it from any directory; no checkout path is needed.
+
+To install the local checkout globally before publication, run these commands
+from the repository, then use the same `opencodex` commands above:
+
+```sh
+pnpm install --frozen-lockfile
+npm install --global .
+```
+
+### 1. `opencodex configure`
+
+`configure` asks for the DeepSeek API key with hidden input on the terminal and
+stores it in `~/.config/opencodex/.env`. It creates the directory with mode
+`0700` and the file with mode `0600`, and it writes the key as plaintext in that
+file rather than in the macOS keychain.
+
+The command does not accept a key argument or piped input, keeping the key out
+of shell history and process arguments. Press Ctrl-C to cancel without changing
+the saved key. Re-running `configure` replaces the key while preserving other
+variables in the file. Run `install` again to reload an already running router.
+
+`config/worker.json` defines the credential file location. `doctor` and `run`
+prefer `DEEPSEEK_API_KEY` from their environment when set; otherwise they read
+the file, as does the installed desktop service. Credentials stay outside the
+repository. The file permissions restrict other users, but programs running as
+your user can still read it.
+
+### 2. `opencodex doctor`
+
+`doctor` checks the local prerequisites without running inference: that a
+compatible Codex CLI is reachable and that the DeepSeek credential is present.
+Run it after `configure` and before `install`; `install` refuses to continue
+unless the doctor reports `ready`.
+Neither `configure` nor `doctor` contacts DeepSeek to validate the key. A `ready`
+result confirms local prerequisites, not provider authentication or account credit.
+
+### 3. `opencodex install`
+
+`install` activates the desktop integration:
+
+- copies a stable runtime (scripts, config, prompts, vendor code and the bundled
+  dependency) to `~/.local/share/opencodex/runtime`;
+- writes private state, the model catalog and receipts to
+  `~/.config/opencodex/desktop`;
+- installs and starts the `com.opencodex.router` LaunchAgent, bound only to
+  `127.0.0.1:4207`;
+- updates `~/.codex/config.toml` with the local provider, the subagent defaults
+  and the generated model catalog, keeping a pre-install backup at
+  `~/.config/opencodex/desktop/config.before.toml`.
+
+The installer refuses to run when an unrelated custom provider is active or when
+an endpoint override is already configured, and it leaves your configuration
+untouched if the service does not become healthy.
+
+After `install`, fully quit and reopen Codex Desktop and start a new task. Tasks
+that were already open keep the provider and model catalog they started with.
+
+## Plugin skill
+
+The delegation skill lives in `skills/delegate-flash/SKILL.md` and is loaded by
+installing the OpenCodex plugin through a Codex marketplace. Installing the npm
+package or running the commands above does not install the skill, and this
+checkout is not a marketplace source by itself.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `opencodex configure` | Prompt for the DeepSeek API key and write `~/.config/opencodex/.env`. |
+| `opencodex doctor` | Check Codex CLI compatibility and credential presence without inference. |
+| `opencodex install` | Install the router runtime, the LaunchAgent and the user-level Codex settings. |
+| `opencodex status` | Query the installed router health endpoint without inference. |
+| `opencodex run --cwd PATH --task-file PATH [--write]` | Run one bounded isolated worker ticket against DeepSeek. Read-only unless `--write` is given. |
+| `opencodex pilot` | Run the opt-in live native-delegation test; consumes Codex and DeepSeek usage. |
+| `opencodex --version`, `opencodex --help` | Print the package version or the command list. |
+
+`run` executes a single ticket and consumes DeepSeek API usage. It takes an
+exclusive per-user lock, so only one worker runs at a time.
+
+## How it works
+
+### Request routing
+
+Codex talks to the router on loopback. The router authenticates each request
+with a capability token generated at install time and stored with mode `0600`,
+then routes by model:
+
+- requests for the child model (`deepseek-flash`) go to the DeepSeek Responses
+  API with the DeepSeek key;
+- requests for any other model in the configured catalog go to the native Codex
+  backend with the client's own authentication headers, which are forwarded only
+  there.
+
+The DeepSeek key is never sent to the native backend, and native Codex
+authentication is never sent to DeepSeek.
+
+### Tool routing
+
+Codex tool definitions, namespaces and history are adapted to what the DeepSeek
+Responses API accepts, and the streaming response is transformed back into the
+Codex collaboration shape. That adaptation is the vendored `codex-router` code
+in `vendor/codex-router`, used under its MIT license.
+
+### Encrypted handoff relay
+
+Subagent tasks can travel from Codex as encrypted `agent_message` payloads that
+the native backend can decode. For each uncached message the router makes a relay
+call to the native model, asking it to return the exact plaintext and not to
+answer the task itself, and then forwards that plaintext to DeepSeek. This is
+why a delegated task consumes both Codex quota and DeepSeek API usage.
+
+### Local data
+
+The router writes bounded receipts to
+`~/.config/opencodex/desktop/receipts.jsonl`: routing decisions, model names,
+tool names, task counts and token usage. Prompts, tool arguments and credentials
+are not recorded. On errors, the receipt message has the DeepSeek key and the
+capability token redacted.
+
+## Tests
+
+```sh
+pnpm test
+```
+
+The default suite is offline: it uses fixtures and spends no provider usage. The
+Codex transport test is skipped unless `OPENCODEX_TEST_CODEX` points at a real
+`codex` binary; when it is set, that test launches the real CLI against a local
+fixture server. Treat it as an optional, deliberate opt-in rather than part of a
+routine run.
+
+## Security notes
+
+- The router listens only on `127.0.0.1` and rejects requests without the
+  generated capability token.
+- Credentials live in `~/.config/opencodex/.env` (`0700` directory, `0600`
+  file), outside the repository.
+- Receipts and router state live in the private `0700` directory
+  `~/.config/opencodex/desktop`.
+- Subagents inherit Codex permissions. A ticket's allowed files are instructions
+  to the worker, not a filesystem sandbox.
+
+## License
+
+MIT; see [LICENSE](LICENSE). Vendored `codex-router` code retains its own
+copyright notice and [MIT license](vendor/codex-router/LICENSE).

package/bin/opencodex.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+const command = args.shift();
+const help = `Usage: opencodex <command>
+
+Commands:
+  configure  Save the DeepSeek key using a hidden terminal prompt
+  install  Activate the local macOS router and configure Codex
+  status   Check the installed router without inference
+  doctor   Check worker prerequisites without inference
+  run      Run an isolated worker ticket (consumes DeepSeek usage)
+  pilot    Test native delegation (consumes Codex and DeepSeek usage)
+
+Requires macOS, Node.js >=22.15 and a compatible Codex CLI.
+Run opencodex configure to save the DeepSeek key in ~/.config/opencodex/.env.
+Installing this npm package does not activate the router or install the skill
+in Codex. Install the plugin through a Codex marketplace to load its skill.
+Use opencodex <command> --help for command options.
+`;
+
+if (!command || command === '--help' || command === '-h') {
+  process.stdout.write(help);
+} else if (command === '--version' || command === '-v') {
+  const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(manifest.version);
+} else {
+  const scripts = { configure: 'credentials.js', install: 'desktop.js', status: 'desktop.js', doctor: 'worker.js', run: 'worker.js', pilot: 'pilot.js' };
+  if (!Object.hasOwn(scripts, command)) {
+    console.error(`Unknown command: ${command}\n${help}`);
+    process.exit(2);
+  }
+  if (command === 'pilot' && args.length) {
+    if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+      console.log('Usage: opencodex pilot\nRuns a live native delegation test; consumes Codex and DeepSeek usage.');
+      process.exit(0);
+    }
+    console.error('Usage: opencodex pilot (no arguments)');
+    process.exit(2);
+  }
+  try {
+    const script = await import(new URL(`../scripts/${scripts[command]}`, import.meta.url));
+    process.exitCode = command === 'pilot' ? await script.run() : await script.main([command, ...args]);
+  } catch (error) {
+    console.error(`OpenCodex failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/config/desktop.json

@@ -0,0 +1,9 @@
+{
+  "port": 4207,
+  "max_requests": null,
+  "request_timeout_ms": 300000,
+  "max_request_bytes": 134217728,
+  "max_response_bytes": 33554432,
+  "service_label": "com.opencodex.router",
+  "service_throttle_seconds": 10
+}

package/config/pilot.json

@@ -0,0 +1,16 @@
+{
+  "parent_model": "gpt-6-astra",
+  "parent_effort": "low",
+  "relay_model": "gpt-6-astra",
+  "native_url": "https://chatgpt.com/backend-api/codex/responses",
+  "timeout_seconds": 300,
+  "request_timeout_ms": 120000,
+  "max_request_bytes": 8388608,
+  "max_response_bytes": 8388608,
+  "max_requests": 20,
+  "port": 0,
+  "relay_cache_entries": 128,
+  "relay_cache_ttl_ms": 900000,
+  "log_max_bytes": 4194304,
+  "startup_timeout_seconds": 10
+}

package/config/worker.json

@@ -0,0 +1,78 @@
+{
+  "credentials": {"env_file": "~/.config/opencodex/.env"},
+  "codex": {
+    "model": "deepseek-flash",
+    "model_provider": "opencodex-deepseek",
+    "model_reasoning_effort": "high",
+    "web_search": "disabled",
+    "approval_policy": "never",
+    "model_providers": {
+      "opencodex-deepseek": {
+        "name": "DeepSeek direct",
+        "base_url": "https://api.deepseek.com",
+        "wire_api": "responses",
+        "env_key": "DEEPSEEK_API_KEY",
+        "requires_openai_auth": false,
+        "supports_websockets": false,
+        "request_max_retries": 0,
+        "stream_max_retries": 0,
+        "stream_idle_timeout_ms": 120000
+      }
+    },
+    "agents": {"enabled": false},
+    "features": {
+      "multi_agent": false,
+      "multi_agent_v2": false,
+      "plugins": false,
+      "apps": false,
+      "hooks": false,
+      "memories": false,
+      "shell_snapshot": false,
+      "context_management": {"experimental_mode": false}
+    },
+    "shell_environment_policy": {
+      "inherit": "core",
+      "ignore_default_excludes": false,
+      "experimental_use_profile": false,
+      "filters": {"DEEPSEEK_API_KEY": "exclude"}
+    },
+    "sandbox_workspace_write": {"network_access": false}
+  },
+  "model_metadata": {
+    "display_name": "DeepSeek Flash (OpenCodex)",
+    "description": "Text worker using the direct DeepSeek API.",
+    "default_reasoning_level": "high",
+    "supported_reasoning_levels": [
+      {"effort": "low", "description": "Simple tasks"},
+      {"effort": "high", "description": "Implementation"},
+      {"effort": "max", "description": "Complex problems"}
+    ],
+    "shell_type": "shell_command",
+    "visibility": "list",
+    "supported_in_api": true,
+    "experimental_supported_tools": [],
+    "supports_image_detail_original": false,
+    "comp_hash": "opencodex-0.1.0",
+    "priority": 1,
+    "context_window": 1048576,
+    "max_context_window": 1048576,
+    "effective_context_window_percent": 95,
+    "default_reasoning_summary": "none",
+    "support_verbosity": false,
+    "apply_patch_tool_type": "freeform",
+    "truncation_policy": {"mode": "tokens", "limit": 10000},
+    "input_modalities": ["text"],
+    "supports_search_tool": false,
+    "supports_experimental_context": false,
+    "use_responses_lite": false
+  },
+  "limits": {
+    "timeout_seconds": 900,
+    "poll_interval_seconds": 0.2,
+    "max_task_bytes": 65536,
+    "max_output_bytes": 8388608,
+    "max_result_chars": 24000,
+    "max_error_chars": 2000,
+    "version_timeout_seconds": 10
+  }
+}

package/node_modules/smol-toml/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) Squirrel Chat et al., All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.