Engineering Bridge v1.2.1

Engineering Bridge v1.2.1

v1.2.1 is a Windows compatibility patch for both supported executors: Codex and DSH.

DSH support itself was introduced in v1.2.0. This release focuses on making npm-installed Codex and DSH CLIs launch correctly and safely on Windows.

What changed

• Fixed Windows command resolution for npm-installed:
  • @openai/codex
  • @deepseek-ai/dsh
• Standard Windows npm shims such as codex.cmd and dsh.cmd are now resolved to their official Node entrypoints:
  • @openai/codex/bin/codex.js
  • @deepseek-ai/dsh/lib/bin.js
• Real codex.exe / dsh.exe installations remain directly supported and preferred.
• Both executors continue to run under Bridge's supervised read-only execution boundary.

Safer Windows launch path

The new Windows path does not rely on:

• cmd.exe
• ComSpec
• shell: true

Instead, npm-installed CLIs are launched through process.execPath and their official JavaScript entrypoints.

Codex instructions continue to travel through JSON-RPC stdin, while DSH instructions remain a single argv argument. If a trusted npm target cannot be resolved, Bridge fails closed instead of falling back to shell execution.

Windows verification

This release was validated on a real GitHub Actions windows-latest runner using:

• Node.js 22
• actual npm-installed @openai/codex
• actual npm-installed @deepseek-ai/dsh

The smoke test confirmed:

• real codex.cmd and dsh.cmd npm layouts
• Bridge command discovery on Windows
• successful launch of both official Node CLI entrypoints
• focused Codex / DSH executor tests
• clean build and typecheck

This verifies the Windows npm CLI launch path introduced in v1.2.1. It is not a claim of full certification across every Windows environment, MCP client, or installation method.

Also included from v1.2.0

Engineering Bridge supports both:

• executor: "codex"
• executor: "dsh"

DSH remains pinned to Bridge's read-only execution boundary, including DSH_PERMISSION_MODE=read-only.

---

Release commit: 30e6b74b895d383ebf006e184a4b470c89020cf0

Engineering Bridge v1.1.0

Engineering Bridge v1.1.0 adds refine_controlled_patch.
When a controlled patch proposal has already been reviewed and only needs a small correction, Chat can now refine the existing proposal instead of regenerating the whole patch from the original task.
The refined proposal:
keeps the same base_head
preserves the original proposal
returns a new complete patch proposal
does not modify the workspace
still requires explicit APPLY before any write
This reduces unnecessary Codex re-reasoning and token usage for small fixes to large proposals.
All tests: 50/50 passed.

Engineering Bridge v1.0.0-rc.3

Engineering Bridge v1.0.0-rc.3

This release candidate includes two focused reliability fixes:

• Codex failed turns now surface serverOverloaded details instead of only returning the generic CODEX_EXECUTION_FAILED.
• Controlled APPLY now handles Markdown fence context, stale hunk counts, and zero-context hunks more reliably.

Validation

Final runtime validation passed:

• run_task → supervisor review → accept
• generate_controlled_patch
• real zero-context hunk preflight with git apply --check --recount --unidiff-zero
• successful controlled APPLY
• fresh npm test: 44/44 passed
• git diff --check: passed
• final worktree: clean

Engineering Bridge v1.0.0-rc.1

Engineering Bridge v1.0.0-rc.1

This is the first release candidate for Engineering Bridge V1.

Highlights

• Migrated execution flow to Codex native app-server sessions.
• Added continuous task control through native threads:
  • continue existing sessions
  • steer running tasks
  • interrupt active turns
  • accept completed results

Safety boundaries

• Interactive run_task remains read-only.
• File changes continue through the controlled patch flow:
  • generate patch
  • review diff
  • explicit APPLY

Validation

Validated on macOS with:

• TypeScript checks
• Build verification
• 40/40 automated tests
• Real Codex app-server integration checks:
  • task execution
  • same-thread continuation
  • steering
  • interrupt handling

Status

This is a release candidate.

Community testing, especially cross-platform validation, is welcome before the stable v1.0.0 release.

Engineering Bridge v0.2.0-alpha.3

中文

Engineering Bridge v0.2.0-alpha.3 将公共 STDIO MCP 接口收敛为四个工具：

• run_task
• task_result
• generate_controlled_patch
• apply_controlled_patch

本版本统一使用 task_result 轮询任务状态，规范安全错误输出，并允许 controlled patch 在严格校验下新增普通 100644 文本文件。删除及其他不安全的 patch 形式仍会被拒绝。

同时更新并精简了相关文档，新增 GitHub Actions CI、Bug Report 和 Setup Help issue templates。

English

Engineering Bridge v0.2.0-alpha.3 reduces the public STDIO MCP interface to four tools:

• run_task
• task_result
• generate_controlled_patch
• apply_controlled_patch

This release makes task_result the unified polling interface, standardizes safe error serialization, and allows controlled patches to add ordinary 100644 text files under strict validation. Deletions and other unsafe patch forms remain rejected.

Documentation has also been streamlined and aligned with the current behavior, with GitHub Actions CI, Bug Report, and Setup Help issue templates added.

v0.2.0-alpha.2

Engineering Bridge v0.2.0-alpha.2

中文说明

这是 Engineering Bridge 的一个 alpha 预发布版本。

本版本在保留“只读优先”设计的基础上，加入了受控写入流程，让用户可以先查看 Codex 生成的修改方案和完整补丁，再通过明确的 APPLY 确认执行修改。

Engineering Bridge 用于连接支持 MCP 的聊天客户端与本地 Codex CLI。用户可以直接在聊天窗口中发出任务，由 Bridge 将任务交给本地 Codex 执行，而不必再手工往返搬运提示词、进度和结果。

本版本主要更新

• 新增受控补丁流程：

  • 由 Codex 生成修改 proposal；
  • 用户可以先审阅完整 diff；
  • 只有在明确执行 APPLY 后才会真正修改文件；
  • 如果 Git HEAD 已发生变化，旧 proposal 会被拒绝，避免补丁应用到错误基线。

• 保留原有只读任务流程。

• 为全部 5 个 MCP 工具补充了准确的工具说明。

• 修复 macOS 下 /tmp 与 /private/tmp 实际指向同一路径时，workspace 校验失败的问题。

• 重写中英文 README，使首次访问者可以更容易理解：

  • Bridge 解决什么问题；
  • 聊天客户端、Bridge、Codex CLI 与 MCP/STDIO 各自负责什么；
  • 如何完成第一次只读体验；
  • 如何完成完整的受控写入流程；
  • 当前兼容条件与使用限制。

• 更新架构、安全说明和威胁模型文档。

• 新增 MCP 工具参考和版本说明。

验证结果

本版本已通过：

• TypeScript 类型检查；
• 正式构建；
• 31 项自动化测试；
• npm package dry-run；
• STDIO MCP 初始化；
• 5 个 MCP 工具及其 description 的实际发现；
• macOS /tmp workspace 的真实 proposal 验证；
• 真实 Codex 只读任务；
• 真实 Codex proposal 与明确 APPLY 的完整闭环。

真实写入验收确认：

• 用户批准前，目标文件没有发生变化；
• APPLY 后只修改了预期的一行内容；
• 没有自动执行 git stage；
• 没有自动创建 commit；
• 没有自动 push。

当前限制

这仍然是 alpha 预发布版本。

目前尚未提供：

• npm registry 发布；
• 任务、proposal 和日志的持久化；
• executor cancellation；
• 产品级任务 timeout；
• 调用方身份认证；
• 普通只读任务的操作系统级读取隔离；
• 自动 commit 或自动 push。

使用本项目需要：

• 支持 MCP/STDIO 的客户端；
• 本地可用的 Codex CLI 环境；
• 预先登记允许访问的 workspace。

安装与使用

当前版本通过 GitHub 源码仓库发布，尚未发布到 npm registry。

安装、workspace 登记、MCP 配置、首次只读任务和受控写入示例，请查看：

• README.zh-CN.md：中文说明
• README.md：English documentation

---

English

This is an alpha prerelease of Engineering Bridge.

This release adds a controlled-write workflow while preserving the project's read-only-first design. Users can review a Codex-generated proposal and its complete patch before explicitly confirming the change with APPLY.

Engineering Bridge connects an MCP-capable chat client to a local Codex CLI executor. It allows users to submit tasks from a chat interface without manually relaying prompts, progress updates, and results between tools.

Highlights

• Added a controlled patch workflow:

  • Codex generates a proposed change;
  • users can review the complete diff;
  • files are modified only after an explicit APPLY confirmation;
  • stale proposals are rejected when the Git base HEAD has changed.

• Preserved the existing read-only task workflow.

• Added accurate descriptions for all five MCP tools.

• Fixed macOS workspace validation when /tmp and /private/tmp resolve to the same canonical path.

• Reworked the English and Chinese READMEs to explain:

  • what problem the Bridge solves;
  • the roles of the chat client, Bridge, Codex CLI, and MCP/STDIO;
  • the first read-only workflow;
  • the complete controlled-write workflow;
  • compatibility requirements and current limitations.

• Updated the architecture, security, and threat-model documentation.

• Added an MCP tool reference and release notes.

Validation

This release passed:

• TypeScript type checking;
• production build;
• all 31 automated tests;
• npm package dry-run validation;
• STDIO MCP initialization;
• discovery of all five MCP tools and their descriptions;
• a real macOS /tmp workspace proposal test;
• a real Codex read-only task;
• a real Codex proposal and explicit APPLY flow.

The end-to-end write validation confirmed that:

• no files changed before approval;
• only the expected line changed after APPLY;
• no files were automatically staged;
• no commit was automatically created;
• no push was performed.

Current limitations

This remains an alpha prerelease.

It does not currently provide:

• npm registry publishing;
• task, proposal, or log persistence;
• executor cancellation;
• product-level task timeouts;
• caller authentication;
• OS-level read containment for ordinary read-only tasks;
• automatic commit or push operations.

A compatible MCP/STDIO client, a locally available Codex CLI environment, and a registered workspace are required.

Installation and usage

This version is distributed through the GitHub source repository and is not yet published to the npm registry.

For installation, workspace registration, MCP configuration, and first-use examples, see:

• README.zh-CN.md for Chinese documentation
• README.md for English documentation

Engineering Bridge v0.2.0-alpha.1

Engineering Bridge v0.2.0-alpha.1

This release completes the first real end-to-end validation of controlled write support.

Controlled write

• Write access remains disabled by default.
• Write access can be enabled separately for selected workspaces with allow_write: true.
• Changes are first generated as a candidate Git patch for human review.
• A patch is applied only after the user explicitly confirms with the exact word APPLY.
• Engineering Bridge never automatically runs git add, git commit, or git push.

Fix

• Normalize controlled patch output to exactly one trailing LF before it is stored and presented for review.
• This prevents valid patches without a final newline from being rejected by git apply.
• Ordinary read-only task output remains unchanged.

Validation

• Real local Codex patch generation completed successfully.
• Explicit confirmation gating was verified.
• Patch application changed only the reviewed file.
• No automatic staging, commit, or push occurred.
• Typecheck, build, and all 28 tests passed.

---

本版本完成了受控写入能力的首次真实端到端验收。

受控写入

• 写入权限仍然默认关闭。
• 可通过 allow_write: true 为指定 workspace 单独开启。
• 所有修改先生成候选 Git 补丁，交由用户审阅。
• 只有用户明确回复精确的 APPLY 后，补丁才会应用。
• Engineering Bridge 不会自动执行 git add、git commit 或 git push。

修复

• 候选补丁在保存和展示前统一规范为恰好一个结尾换行。
• 修复合法补丁因缺少末尾换行而被 git apply 拒绝的问题。
• 普通只读任务的原始输出不受影响。

验证

• 已通过真实本机 Codex 生成候选补丁。
• 已验证明确确认门禁。
• 已验证应用时只修改审阅过的文件。
• 未发生自动暂存、提交或推送。
• Typecheck、构建及全部 28 项测试通过。