ferry-codex 0.1.1__tar.gz

ferry_codex-0.1.1/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "ferry",
+  "interface": {
+    "displayName": "Ferry"
+  },
+  "plugins": [
+    {
+      "name": "ferry",
+      "source": {
+        "source": "local",
+        "path": "./plugins/ferry"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

ferry_codex-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scrimper 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.

ferry_codex-0.1.1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: ferry-codex
+Version: 0.1.1
+Summary: Keep Codex as the lead while bounded work runs on your own models.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PunkGo/ferry
+Project-URL: Repository, https://github.com/PunkGo/ferry
+Project-URL: Issues, https://github.com/PunkGo/ferry/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp==2.0.0
+Requires-Dist: packaging>=24
+Dynamic: license-file
+
+# Ferry
+
+<p align="center">
+  <strong>Keep Codex as the lead. Delegate bounded work to your own models.</strong>
+</p>
+
+<p align="center">
+  English · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+Ferry adds controlled worker delegation to Codex. Your main Codex session keeps
+the project context, scopes the task, and judges the result. Bounded execution
+can stay on a native Codex worker or run on an explicitly selected custom model
+such as DeepSeek.
+
+If you like the lead-and-worker feel of Claude Code agent teams, Ferry brings
+that delegation pattern to Codex while letting workers use providers already
+configured on your machine. Ferry is not a second agent harness or a shared
+peer-to-peer team runtime. Codex remains the lead and final judge.
+
+> **Ferry work, not judgment.**
+
+## Why Ferry
+
+Frontier models are worth using for hard reasoning, planning, and review. They
+are not always the economical choice for a bounded implementation task.
+
+Ferry lets you keep the Codex harness you already trust and spend expensive
+model capacity where judgment matters. A lower-cost custom model can implement
+a focused change; Codex then inspects the real diff, runs the checks, and decides
+whether to accept, steer, rework, interrupt, or stop.
+
+![Codex leads while Ferry routes bounded work to a native or custom-model worker](diagrams/ferry-cost-control.svg)
+
+## Before you install: prove the provider in Codex
+
+First, follow the official
+[Codex custom-provider guide](https://developers.openai.com/codex/config-advanced#custom-model-providers)
+to configure and test your provider. Ferry does not configure models, endpoints,
+authentication, or credentials. The exact provider, model, and authentication
+must already work in Codex before Ferry uses them.
+
+### DeepSeek example
+
+After following the Codex guide, if your working provider is named `deepseek`,
+verify it directly through Codex. Replace the model id if your configuration
+uses a different one.
+
+```sh
+export DEEPSEEK_API_KEY="YOUR_KEY"
+
+codex exec -s read-only \
+  -c 'model_provider="deepseek"' \
+  -m deepseek-v4-pro \
+  'Reply with exactly DEEPSEEK_CODEX_OK.'
+```
+
+Continue only after Codex returns `DEEPSEEK_CODEX_OK`. Ferry will never silently
+fall back to the owner model when an explicitly requested provider is missing,
+misconfigured, or reports a different native provider identity.
+
+## Install
+
+Requirements: Python 3.10+, `pipx`, and an existing Codex CLI installation.
+
+```sh
+pipx install ferry-codex
+ferry setup
+```
+
+Start a fresh Codex session. Ferry reuses your host `codex` executable; it does
+not bundle Python or install a second Codex CLI.
+
+## Use
+
+Ask Codex in natural language. There are no Ferry worker commands to learn.
+
+Delegate to a native Codex worker:
+
+```text
+Use Ferry to delegate this bounded task to a native worker: update the parser,
+run its focused tests, and do not touch unrelated files.
+```
+
+Delegate to the DeepSeek provider you already proved in Codex:
+
+```text
+Use Ferry with my configured DeepSeek provider and deepseek-v4-pro for this
+bounded implementation. Keep this Codex thread as lead and independently verify
+the resulting diff and tests.
+```
+
+Correct or stop live work in the same conversation:
+
+```text
+Steer the Ferry worker: preserve the public API and limit the change to src/parser.py.
+```
+
+```text
+Interrupt the Ferry worker now.
+```
+
+The worker's report is delivery data. Codex checks the actual worktree and runs
+the real acceptance commands before accepting it.
+
+## Manage the integration
+
+```sh
+ferry status
+```
+
+Close every Codex session using Ferry before upgrading or uninstalling.
+
+```sh
+pipx upgrade ferry-codex && ferry setup
+```
+
+```sh
+ferry uninstall && pipx uninstall ferry-codex
+```
+
+These commands manage only the Ferry package and Codex plugin integration. They
+do not delete Codex threads, provider configuration, credentials, or project
+files.
+
+## Support and security
+
+Ferry's native-worker, OpenAI, DeepSeek, steer, interrupt, pipx lifecycle, and
+Windows paths have versioned conformance evidence. See [SUPPORT.md](SUPPORT.md)
+for the exact tested matrix.
+
+Report security issues through [SECURITY.md](SECURITY.md). Contributions are
+welcome after reading [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

ferry_codex-0.1.1/README.md

@@ -0,0 +1,137 @@
+# Ferry
+
+<p align="center">
+  <strong>Keep Codex as the lead. Delegate bounded work to your own models.</strong>
+</p>
+
+<p align="center">
+  English · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+Ferry adds controlled worker delegation to Codex. Your main Codex session keeps
+the project context, scopes the task, and judges the result. Bounded execution
+can stay on a native Codex worker or run on an explicitly selected custom model
+such as DeepSeek.
+
+If you like the lead-and-worker feel of Claude Code agent teams, Ferry brings
+that delegation pattern to Codex while letting workers use providers already
+configured on your machine. Ferry is not a second agent harness or a shared
+peer-to-peer team runtime. Codex remains the lead and final judge.
+
+> **Ferry work, not judgment.**
+
+## Why Ferry
+
+Frontier models are worth using for hard reasoning, planning, and review. They
+are not always the economical choice for a bounded implementation task.
+
+Ferry lets you keep the Codex harness you already trust and spend expensive
+model capacity where judgment matters. A lower-cost custom model can implement
+a focused change; Codex then inspects the real diff, runs the checks, and decides
+whether to accept, steer, rework, interrupt, or stop.
+
+![Codex leads while Ferry routes bounded work to a native or custom-model worker](diagrams/ferry-cost-control.svg)
+
+## Before you install: prove the provider in Codex
+
+First, follow the official
+[Codex custom-provider guide](https://developers.openai.com/codex/config-advanced#custom-model-providers)
+to configure and test your provider. Ferry does not configure models, endpoints,
+authentication, or credentials. The exact provider, model, and authentication
+must already work in Codex before Ferry uses them.
+
+### DeepSeek example
+
+After following the Codex guide, if your working provider is named `deepseek`,
+verify it directly through Codex. Replace the model id if your configuration
+uses a different one.
+
+```sh
+export DEEPSEEK_API_KEY="YOUR_KEY"
+
+codex exec -s read-only \
+  -c 'model_provider="deepseek"' \
+  -m deepseek-v4-pro \
+  'Reply with exactly DEEPSEEK_CODEX_OK.'
+```
+
+Continue only after Codex returns `DEEPSEEK_CODEX_OK`. Ferry will never silently
+fall back to the owner model when an explicitly requested provider is missing,
+misconfigured, or reports a different native provider identity.
+
+## Install
+
+Requirements: Python 3.10+, `pipx`, and an existing Codex CLI installation.
+
+```sh
+pipx install ferry-codex
+ferry setup
+```
+
+Start a fresh Codex session. Ferry reuses your host `codex` executable; it does
+not bundle Python or install a second Codex CLI.
+
+## Use
+
+Ask Codex in natural language. There are no Ferry worker commands to learn.
+
+Delegate to a native Codex worker:
+
+```text
+Use Ferry to delegate this bounded task to a native worker: update the parser,
+run its focused tests, and do not touch unrelated files.
+```
+
+Delegate to the DeepSeek provider you already proved in Codex:
+
+```text
+Use Ferry with my configured DeepSeek provider and deepseek-v4-pro for this
+bounded implementation. Keep this Codex thread as lead and independently verify
+the resulting diff and tests.
+```
+
+Correct or stop live work in the same conversation:
+
+```text
+Steer the Ferry worker: preserve the public API and limit the change to src/parser.py.
+```
+
+```text
+Interrupt the Ferry worker now.
+```
+
+The worker's report is delivery data. Codex checks the actual worktree and runs
+the real acceptance commands before accepting it.
+
+## Manage the integration
+
+```sh
+ferry status
+```
+
+Close every Codex session using Ferry before upgrading or uninstalling.
+
+```sh
+pipx upgrade ferry-codex && ferry setup
+```
+
+```sh
+ferry uninstall && pipx uninstall ferry-codex
+```
+
+These commands manage only the Ferry package and Codex plugin integration. They
+do not delete Codex threads, provider configuration, credentials, or project
+files.
+
+## Support and security
+
+Ferry's native-worker, OpenAI, DeepSeek, steer, interrupt, pipx lifecycle, and
+Windows paths have versioned conformance evidence. See [SUPPORT.md](SUPPORT.md)
+for the exact tested matrix.
+
+Report security issues through [SECURITY.md](SECURITY.md). Contributions are
+welcome after reading [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

ferry_codex-0.1.1/ferry_codex/__init__.py

@@ -0,0 +1,5 @@
+"""Ferry's installed-distribution integration surface."""
+
+from .build_identity import FULL_VERSION, PUBLIC_VERSION
+
+__all__ = ["FULL_VERSION", "PUBLIC_VERSION"]

ferry_codex-0.1.1/ferry_codex/build_backend.py

@@ -0,0 +1,121 @@
+"""Release-only build identity guard around the standards-based setuptools backend."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+ROOT = Path(__file__).resolve().parents[1]
+IDENTITY = ROOT / "ferry_codex" / "build_identity.py"
+EGG_INFO = ROOT / "ferry_codex.egg-info"
+BYTECODE = ROOT / "ferry_codex" / "__pycache__"
+EGG_INFO_FILES = {"PKG-INFO", "SOURCES.txt", "dependency_links.txt", "entry_points.txt", "requires.txt", "top_level.txt"}
+
+
+def _clear_backend_byproducts() -> None:
+    """Remove only the exact, regular setuptools/Python byproducts this backend creates."""
+    if EGG_INFO.exists() or EGG_INFO.is_symlink():
+        if EGG_INFO.is_symlink() or not EGG_INFO.is_dir():
+            raise RuntimeError(f"refusing unexpected generated path: {EGG_INFO}")
+        entries = list(EGG_INFO.rglob("*"))
+        files = {item.relative_to(EGG_INFO).as_posix() for item in entries if item.is_file()}
+        if any(item.is_symlink() or item.is_dir() or not item.is_file() for item in entries) or files - EGG_INFO_FILES:
+            raise RuntimeError(f"refusing unexpected setuptools byproduct contents: {EGG_INFO}")
+        shutil.rmtree(EGG_INFO)
+    if BYTECODE.exists() or BYTECODE.is_symlink():
+        if BYTECODE.is_symlink() or not BYTECODE.is_dir():
+            raise RuntimeError(f"refusing unexpected generated path: {BYTECODE}")
+        modules = {item.stem for item in (ROOT / "ferry_codex").glob("*.py")}
+        for item in BYTECODE.rglob("*"):
+            if item.is_symlink() or item.is_dir() or not item.is_file():
+                raise RuntimeError(f"refusing unexpected Python bytecode byproduct: {BYTECODE}")
+            match = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)\.cpython-\d+(?:\.opt-\d+)?\.pyc", item.name)
+            if match is None or match.group(1) not in modules:
+                raise RuntimeError(f"refusing unexpected Python bytecode byproduct: {BYTECODE}")
+        shutil.rmtree(BYTECODE)
+
+
+def _run_hook(action):
+    """Run one PEP 517 hook without allowing cleanup to erase its original cause."""
+    try:
+        result = action()
+    except BaseException as primary:
+        try:
+            _clear_backend_byproducts()
+        except BaseException as cleanup:
+            raise RuntimeError(f"PEP 517 hook failed: {primary}; cleanup failed: {cleanup}") from primary
+        raise
+    _clear_backend_byproducts()
+    return result
+
+
+def _release_commit() -> str:
+    _clear_backend_byproducts()
+    requested = os.environ.get("FERRY_BUILD_COMMIT")
+    if not requested or not re.fullmatch(r"[0-9a-f]{40}", requested):
+        raise RuntimeError("set FERRY_BUILD_COMMIT to the exact lowercase 40-character release commit")
+    observed = subprocess.run(("git", "-C", str(ROOT), "rev-parse", "HEAD"), check=True, text=True, stdout=subprocess.PIPE).stdout.strip()
+    dirty = subprocess.run(("git", "-C", str(ROOT), "status", "--porcelain"), check=True, text=True, stdout=subprocess.PIPE).stdout
+    if observed != requested or dirty:
+        raise RuntimeError("release artifacts require a clean checkout at FERRY_BUILD_COMMIT")
+    return requested
+
+
+def _source_sdist_commit() -> str | None:
+    """Only an unpacked sdist may reuse its immutable embedded source commit."""
+    if (ROOT / ".git").exists() or not (ROOT / "PKG-INFO").is_file():
+        return None
+    match = re.search(r'SOURCE_COMMIT = "([0-9a-f]{40})"', IDENTITY.read_text(encoding="utf-8"))
+    return match.group(1) if match else None
+
+
+@contextmanager
+def _embedded_identity() -> Iterator[None]:
+    commit = _release_commit()
+    original = IDENTITY.read_text(encoding="utf-8")
+    replacement = re.sub(r'SOURCE_COMMIT = ".*"', f'SOURCE_COMMIT = "{commit}"', original)
+    IDENTITY.write_text(replacement, encoding="utf-8")
+    try:
+        yield
+    finally:
+        IDENTITY.write_text(original, encoding="utf-8")
+
+
+def build_wheel(wheel_directory: str, config_settings=None, metadata_directory=None) -> str:
+    from setuptools import build_meta as backend
+    # A wheel directly from a checkout must bind to that clean checkout.  A wheel
+    # from an sdist instead reuses the immutable identity already embedded there.
+    def action():
+        if _source_sdist_commit() is not None:
+            return backend.build_wheel(wheel_directory, config_settings, metadata_directory)
+        with _embedded_identity():
+            return backend.build_wheel(wheel_directory, config_settings, metadata_directory)
+    return _run_hook(action)
+
+
+def build_sdist(sdist_directory: str, config_settings=None) -> str:
+    from setuptools import build_meta as backend
+    def action():
+        with _embedded_identity():
+            return backend.build_sdist(sdist_directory, config_settings)
+    return _run_hook(action)
+
+
+def prepare_metadata_for_build_wheel(metadata_directory: str, config_settings=None) -> str:
+    from setuptools import build_meta as backend
+    return _run_hook(lambda: backend.prepare_metadata_for_build_wheel(metadata_directory, config_settings))
+
+
+def get_requires_for_build_wheel(config_settings=None):
+    from setuptools import build_meta as backend
+    return _run_hook(lambda: backend.get_requires_for_build_wheel(config_settings))
+
+
+def get_requires_for_build_sdist(config_settings=None):
+    from setuptools import build_meta as backend
+    return _run_hook(lambda: backend.get_requires_for_build_sdist(config_settings))

ferry_codex-0.1.1/ferry_codex/build_identity.py

@@ -0,0 +1,8 @@
+"""Build identity embedded in source and replaced in release artifacts."""
+
+PUBLIC_VERSION = "0.1.1"
+# A release build replaces this with the exact clean source commit.  Keeping the
+# source marker explicit prevents an unpacked checkout from masquerading as an
+# immutable distribution.
+SOURCE_COMMIT = "3ca3f13b6ef4bb758af20421f9274a5fc4a27199"
+FULL_VERSION = f"{PUBLIC_VERSION}+{SOURCE_COMMIT[:12]}"

ferry_codex-0.1.1/ferry_codex/cli.py

@@ -0,0 +1,34 @@
+"""The intentionally small public Ferry console seam."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .build_identity import FULL_VERSION
+from .integration import IntegrationError, setup, status, uninstall
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ferry", description="Reconcile Ferry's installed Codex plugin integration.")
+    parser.add_argument("--version", action="version", version=FULL_VERSION)
+    parser.add_argument("--ferry-home", type=Path, help=argparse.SUPPRESS)
+    parser.add_argument("--codex", help=argparse.SUPPRESS)
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    for name in ("setup", "status", "uninstall"):
+        subcommands.add_parser(name)
+    args = parser.parse_args(argv)
+    try:
+        {"setup": setup, "status": status, "uninstall": uninstall}[args.command](ferry_home=args.ferry_home, codex=args.codex)
+    except IntegrationError as exc:
+        print(f"ferry: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f"ferry: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())