[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80001":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":12,"stars7d":12,"stars30d":14,"stars90d":13,"forks30d":13,"starsTrendScore":14,"compositeScore":15,"rankGlobal":8,"rankLanguage":8,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":8,"pushedAt":8,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":13,"starSnapshotCount":13,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},80001,"opencode-bridge","goldtetsola\u002Fopencode-bridge","goldtetsola",null,"Python",73,5,1,0,3,2.33,"Other",false,"main",true,[],"2026-06-12 02:03:56","# OpenCode Bridge\n\nOpenCode Bridge lets Codex use open-source models as governed subagents. It routes OSS workers through a local Responses-compatible bridge, gives them scoped runtime tools, records what they did, and returns evidence-backed reports for GPT review.\n\nUse it when you want cheaper or parallel OSS help without handing an OSS model the keys to your repo.\n\n## What You Get\n\n- **Runtime-controlled investigations**: OSS agents can read and search only the paths their mission allows.\n- **Evidence-backed reports**: final answers include files inspected, commands run, findings, caveats, and confidence.\n- **Visible progress**: spawned OSS agents stream safe working commentary such as planned actions, tool runs, coverage updates, and closure decisions.\n- **Patch safety rails**: bounded implementation missions validate patches, apply them in an isolated worktree, verify them, and record rollback data.\n- **Auditable artifacts**: every runtime mission writes JSON reports, traces, summaries, ledgers, and decision logs under `.codex-oss\u002Fmissions\u002F`.\n- **Fail-closed behavior**: missing evidence, invalid reports, blocked paths, contradictions, and provider failures downgrade or escalate instead of pretending success.\n\n## Who This Is For\n\nOpenCode Bridge is for Codex users who want to delegate bounded work to OSS models while keeping GPT in charge of final judgment.\n\nGood uses:\n\n- Ask an OSS investigator to inspect a few files and summarize what it found.\n- Run a low-risk repo scout in parallel while GPT continues the main task.\n- Generate or validate a small patch in an isolated worktree.\n- Burn in runtime behavior with deterministic proof packs.\n\nAvoid it for:\n\n- Authentication, authorization, migrations, recovery paths, CI gates, deployment, or schema authority.\n- Any task where an OSS model's mistake could cause data loss or a security issue.\n- Raw, open-ended \"go change the repo\" work.\n\n## How It Works\n\n```text\nCodex \u002F GPT orchestrator\n  |\n  | spawns a configured OSS subagent\n  v\nOpenCode Bridge on localhost:4000\n  |\n  | validates a MissionV1 contract\n  v\nMission runtime\n  |\n  | owns tools, paths, evidence, validation, audit, and closure\n  v\nOSS model: Kimi, DeepSeek, or Flash\n  |\n  | returns actions or narrative under runtime control\n  v\nEvidence-backed report for GPT review\n```\n\nThe important split is simple:\n\n- **Runtime owns execution.** It decides which tools may run, checks scope, records evidence, validates reports, and closes safely.\n- **OSS model owns reasoning.** It proposes the next action, explains why it wants that action, and drafts findings.\n- **GPT owns judgment.** Treat OSS output as evidence, not final authority.\n\n## Quick Start\n\n### 1. Clone the Repo\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fgoldtetsola\u002Fopencode-bridge.git\ncd opencode-bridge\n```\n\n### 2. Add Your OpenCode Go Key\n\nCreate the local env file:\n\n```bash\nmkdir -p .codex-oss\u002Fenv\ncp opencode-go.env.example .codex-oss\u002Fenv\u002Fopencode-go.env\n```\n\nEdit `.codex-oss\u002Fenv\u002Fopencode-go.env`:\n\n```bash\nOPENCODE_GO_API_KEY=sk-...\n```\n\nDo not commit this file.\n\n### 3. Install the Bridge into a Codex Project\n\nRun this from the bridge repo:\n\n```bash\nbin\u002Fcodex-oss install --project \u002Fpath\u002Fto\u002Fyour\u002Fcodex\u002Fproject\n```\n\nThis adds:\n\n- a local `opencode_bridge` provider block\n- runtime-controlled OSS agent TOMLs\n- raw OSS agent TOMLs for experiments\n- safety rules for subagent handoffs\n\n### 4. Start the Bridge\n\n```bash\nbin\u002Fcodex-oss up --daemon\n```\n\nThe bridge listens on:\n\n```text\nhttp:\u002F\u002F127.0.0.1:4000\u002Fv1\n```\n\n### 5. Check Your Setup\n\n```bash\nbin\u002Fcodex-oss doctor --network\n```\n\nFor JSON output:\n\n```bash\nbin\u002Fcodex-oss doctor --network --json\n```\n\n### 6. Check the Current Claim Surface\n\n```bash\nbin\u002Fcodex-oss claim-status --project . --json\n```\n\nThis tells you which runtime claims are currently supported by fresh artifacts.\n\n## The Most Important Rule\n\nDo **not** set `model_provider = \"opencode_bridge\"` as your top-level Codex provider.\n\nKeep GPT native as the parent session. Only OSS subagent TOMLs should use the bridge provider.\n\nWhy: GPT requests must stay with OpenAI. The bridge is for OSS workers and MissionV1 runtime aliases.\n\n## Agents\n\nAfter installation, your Codex project can use these agents.\n\n### Runtime-Controlled Agents\n\nUse these for normal work.\n\n| Agent | Model alias | Best for |\n|---|---|---|\n| `oss_kimi_investigator` | `mission-a3-kimi` | General read-only investigations |\n| `oss_deepseek_investigator` | `mission-a3-deepseek` | Deeper read-only investigations |\n| `oss_flash_context` | `mission-a2-flash` | Cheap context gathering and lookups |\n\nRuntime-controlled agents require a MissionV1 handoff:\n\n```text\n\u003COSS_HANDOFF_JSON>\n{ ... MissionV1 JSON ... }\n\u003C\u002FOSS_HANDOFF_JSON>\n```\n\nPut exactly one of these blocks in the worker prompt you spawn. Do not copy literal `\u003COSS_HANDOFF_JSON>` examples into project `AGENTS.md` files; every spawned worker inherits those standing instructions, and inherited examples can be mistaken for extra handoff blocks.\n\nUse `fork_turns: \"none\"` or the equivalent \"do not fork context\" option when spawning OSS agents. Full-history forks can inherit GPT settings that conflict with OSS model routing.\n\n### Raw OSS Agents\n\nThese are useful for experiments and low-stakes support work, but they do not get the full MissionV1 runtime control plane.\n\n| Agent | Model |\n|---|---|\n| `oss_kimi_rapid` | `ocg-kimi-k2.6` |\n| `oss_deepseek_pro` | `ocg-deepseek-v4-pro` |\n| `oss_flash_support` | `ocg-deepseek-v4-flash` |\n\nFor serious read-only investigations, prefer the runtime-controlled agents.\n\nRaw workers cannot prove their own routing from inside the task. Treat their files inspected, findings, and caveats as their deliverable. Treat bridge routing and live OSS inference as bridge-owned facts, proven by:\n\n```bash\nbin\u002Fcodex-oss status\nbin\u002Fcodex-oss doctor --live-model\n```\n\nIn `doctor --live-model`, `bridge.oss_inference` is the check that proves the bridge can reach a live OSS model. A raw worker may report its configured model alias, but that is configuration context, not independent proof of transport.\n\n## Ways To Delegate\n\nThe runtime has internal labels because different tasks need different safety rules. You do not need to memorize them.\n\n| Plain name | Internal label | What it does | Current use |\n|---|---|---|\n| Quick lookup | A2 | Fast read\u002Fsearch\u002Fextract tasks | Use today |\n| Read-only investigation | A3 | Scoped investigation with evidence requirements | Use today |\n| Open-ended investigation | A3-open | Ambiguous read-only questions with stricter evidence checks | Use today, monitored |\n| Patch proposal | A4 | Build a proposed patch without applying it to the workspace | Use for low-risk patches |\n| Isolated implementation | A5 | Apply and verify a bounded patch in an isolated worktree | Use for bounded low-risk work |\n| Critical-path rehearsal | A6 | Simulate high-risk work without trusting OSS to change critical paths | Proof\u002Fsimulation only |\n| Raw OSS worker | Raw OSS | Prompt-only worker behavior without the full runtime control plane | Research lane |\n\n## A Minimal MissionV1 Example\n\nUse this shape when asking a runtime-controlled investigator to inspect a file:\n\n```text\n\u003COSS_HANDOFF_JSON>\n{\n  \"schema_version\": \"oss_agent_mission.v1\",\n  \"mission_id\": \"mission_find_runtime_streaming\",\n  \"tier\": \"A3\",\n  \"mode\": \"managed_investigation\",\n  \"objective\": \"Inspect bridge.py and report where managed runtime streaming starts.\",\n  \"risk_tier\": \"low\",\n  \"write_allowed\": false,\n  \"allowed_roots\": [],\n  \"allowed_paths\": [\"bridge.py\"],\n  \"tool_budget\": 3,\n  \"time_budget_seconds\": 60,\n  \"allowed_tool_classes\": [\"read\", \"search\"],\n  \"stop_conditions\": [\"valid_report\", \"budget_exhausted\", \"deadline_reached\"],\n  \"report_schema\": \"managed_investigation_report.v1\",\n  \"required_outputs\": [\n    \"files_inspected\",\n    \"commands_run\",\n    \"findings\",\n    \"uncertainties\",\n    \"confidence\",\n    \"caveats\",\n    \"escalation_recommendation\"\n  ]\n}\n\u003C\u002FOSS_HANDOFF_JSON>\n```\n\nFor reusable handoffs, validate before sending:\n\n```bash\nbin\u002Fcodex-oss validate-handoff path\u002Fto\u002Fhandoff.md\n```\n\nFor generated mission files, prefer the CLI:\n\n```bash\nbin\u002Fcodex-oss mission template --tier A3\nbin\u002Fcodex-oss mission compile mission.json --handoff\n```\n\n## Visible Progress\n\nRuntime-backed OSS agents now stream public progress commentary. This is not hidden chain-of-thought. It is safe working narration generated from runtime state and model-declared action rationale.\n\nYou should see updates like:\n\n```text\nI'm loading the compiled MissionV1 contract.\nI'm asking the OSS model for the next safe investigation action.\nThe model chose rtk_read on bridge.py as the next investigation step.\nI'm running rtk_read on bridge.py.\nI finished rtk_read; exit_code=0. The runtime refreshed coverage from the new evidence.\nCurrent phase is REPORT. Evidence refs now available: file:bridge.py#extract:1, command:0.\n```\n\nThe runtime does **not** stream:\n\n- raw hidden chain-of-thought\n- provider `reasoning_content`\n- full file contents\n- long command output\n- secrets or tokens\n- system\u002Fdeveloper prompts\n\nIf the UI does not show progress, inspect the artifact:\n\n```bash\nbin\u002Fcodex-oss show-trace MISSION_ID\nbin\u002Fcodex-oss show-summary MISSION_ID\n```\n\n## Source-Pack Recovery\n\nFor direct read-only support agents, the bridge first tries to let the OSS model run a normal live agent loop: inspect sources, gather evidence, and produce the final answer. If the model times out, loops, returns intent text, or produces an invalid final report, the bridge may use a gathered source pack to produce an explicit recovery report.\n\nRecovery reports say:\n\n```text\nSynthesis status: SOURCE_PACK_RECOVERY\n```\n\nThat means the bridge preserved useful evidence, but the live OSS synthesis did not complete cleanly. Treat it as a recovery artifact for GPT review, not as a native-feeling successful OSS answer.\n\n## Mission Artifacts\n\nEach runtime mission writes artifacts under:\n\n```text\n.codex-oss\u002Fmissions\u002F\u003Cmission_id>\u002F\n```\n\nCommon files:\n\n| File | Purpose |\n|---|---|\n| `report.json` | Final structured report |\n| `summary.md` | Human-readable mission summary |\n| `visible_commentary.jsonl` | User-facing progress events |\n| `trace.jsonl` | Runtime action trace |\n| `decision_trace.json` | Policy and closure decisions |\n| `ledger.json` | Files inspected, commands run, budget, redaction state |\n| `claim_graph.json` | Investigation claim\u002Fevidence state |\n| `answer_graph.json` | Open-investigation obligation state, when applicable |\n| `implementation_report.json` | Patch\u002Fapply\u002Fverify result for A4\u002FA5 |\n| `semantic_review.json` | Patch review result for implementation missions |\n\nAudit a mission:\n\n```bash\nbin\u002Fcodex-oss audit-mission MISSION_ID --project . --json\n```\n\nExplain why a mission ended the way it did:\n\n```bash\nbin\u002Fcodex-oss explain MISSION_ID --project . --json\n```\n\n## Safety Model\n\nThe runtime blocks or downgrades work when evidence is weak.\n\nFor investigations:\n\n- allowed paths and roots are enforced\n- secrets are redacted before returning observations to the model\n- critical paths are blocked unless explicitly allowed\n- missing required sources block `COMPLETE`\n- unsupported tool arguments are rejected or repaired\n- duplicate reads are suppressed or served from cached evidence\n- contradictions and blocked sources escalate to GPT review\n- hollow `COMPLETE` reports are repaired or downgraded\n\nFor implementation:\n\n- patches are validated before apply\n- raw model diffs are not trusted blindly\n- PatchRecipe and PatchIntent can be turned into runtime-built diffs\n- `git apply --check` runs before apply\n- secret scans and semantic review run before apply\n- A5 applies in an isolated worktree by default\n- verification commands must be allowlisted\n- rollback artifacts are recorded\n\n## CLI Reference\n\n### Setup and Health\n\n```bash\nbin\u002Fcodex-oss install --project PATH\nbin\u002Fcodex-oss up --daemon\nbin\u002Fcodex-oss start --port 4000\nbin\u002Fcodex-oss stop\nbin\u002Fcodex-oss restart --port 4000\nbin\u002Fcodex-oss status\nbin\u002Fcodex-oss doctor --network\n```\n\n### Missions and Artifacts\n\n```bash\nbin\u002Fcodex-oss mission template --tier A3\nbin\u002Fcodex-oss mission compile --help\nbin\u002Fcodex-oss mission run --project .\nbin\u002Fcodex-oss validate-handoff path\u002Fto\u002Fhandoff.md\nbin\u002Fcodex-oss show-trace MISSION_ID\nbin\u002Fcodex-oss show-summary MISSION_ID\nbin\u002Fcodex-oss audit-mission MISSION_ID --project . --json\nbin\u002Fcodex-oss explain MISSION_ID --project . --json\n```\n\n### Proof and Certification\n\n```bash\nbin\u002Fcodex-oss claim-status --project . --json\nbin\u002Fcodex-oss refresh-proofs --project . --suite all --json\nbin\u002Fcodex-oss burnin --project . --suite operational --json\nbin\u002Fcodex-oss certify --project . --target open_investigation --json\n```\n\n### Raw Research Lane\n\n```bash\nbin\u002Fcodex-oss raw-probe --help\nbin\u002Fcodex-oss raw-claim-status --project . --json\n```\n\n## Environment Variables\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `OPENCODE_GO_API_KEY` | OpenCode Go API key for upstream OSS models | Required |\n| `PROXY_PORT` | Local bridge port | `4000` |\n| `PROXY_API_KEY` | Local auth key expected by the bridge | `sk-local-codex-bridge` |\n| `GPT_MODEL_STRATEGY` | What to do if a GPT request hits the bridge | `error` |\n| `MODEL_MAP_JSON` | Override bridge model mapping | built-in map |\n| `FALLBACK_MODEL_MAP_JSON` | Override fallback chains | built-in chains |\n| `UPSTREAM_STREAM` | Use upstream streaming where supported | `1` |\n| `OSS_VISIBLE_TRACE` | Visible commentary mode: `off`, `summary`, `detailed` | `summary` |\n| `OSS_VISIBLE_TRACE_STREAM` | Stream visible commentary to Codex | `1` |\n| `OSS_VISIBLE_TRACE_MAX_EVENTS` | Max visible commentary events per mission | `40` |\n| `REQUEST_DEADLINE_SECONDS` | Default request deadline | `90` |\n| `MAX_GLOBAL_UPSTREAM_CONCURRENCY` | Global upstream request cap | `5` |\n| `MODEL_CONCURRENCY_JSON` | Per-model concurrency caps | built-in defaults |\n\n## Local Development\n\nThis is a Python project with no required package install for the core test suite.\n\nRun core tests:\n\n```bash\npython3 tests\u002Ftest_runtime_contracts.py\npython3 tests\u002Ftest_burnin_harness.py\npython3 tests\u002Ftest_patch_pipeline.py\npython3 tests\u002Ftest_mission_cli.py\n```\n\nRun the bridge in the foreground:\n\n```bash\nbin\u002Fcodex-oss up\n```\n\nRun the bridge as a daemon:\n\n```bash\nbin\u002Fcodex-oss up --daemon\n```\n\nRestart after code changes:\n\n```bash\nbin\u002Fcodex-oss restart --port 4000\n```\n\nVerify the running process matches the source on disk:\n\n```bash\nbin\u002Fcodex-oss doctor --network --json\n```\n\n## Project Structure\n\n```text\nagents\u002F                 Codex agent TOMLs for runtime and raw OSS workers\nbin\u002Fcodex-oss           Main CLI entry point\nbridge.py               Responses-compatible bridge server\ncodex_oss\u002F              Runtime, policy, mission, audit, and implementation code\ndocs\u002F                   Optional local notes and generated docs (ignored by git)\nexamples\u002F               Example inputs and handoffs\norchestration\u002F          Supporting orchestration files\ntests\u002F                  Runtime, bridge, mission, and burn-in tests\nconfig.toml.example     Provider config to merge into Codex config\nopencode-go.env.example API key env template\n```\n\nKey modules:\n\n| Module | Role |\n|---|---|\n| `codex_oss\u002Fmanaged_bridge.py` | Turns Responses requests into MissionV1 runtime runs |\n| `codex_oss\u002Fruntime\u002Floop.py` | A2\u002FA3 plan-act-observe loop and visible commentary |\n| `codex_oss\u002Fanswer_graph.py` | Open-investigation obligations and sufficiency |\n| `codex_oss\u002Fimplementation.py` | A4\u002FA5 patch proposal, validation, apply, verify |\n| `codex_oss\u002Fvisible_commentary.py` | Safe user-facing progress events |\n| `codex_oss\u002Faudit.py` | Mission artifact checks |\n| `codex_oss\u002Ftransport\u002Femitter.py` | Responses JSON\u002FSSE output |\n\n## Troubleshooting\n\n### Bridge is not running\n\nRun:\n\n```bash\nbin\u002Fcodex-oss up --daemon\nbin\u002Fcodex-oss doctor --network\n```\n\n### Bridge is running stale code\n\nRestart it:\n\n```bash\nbin\u002Fcodex-oss restart --port 4000\n```\n\nThen confirm:\n\n```bash\nbin\u002Fcodex-oss doctor --network --json\n```\n\nLook for:\n\n```text\nbridge.source_hash: PASS\nruntime.identity: PASS\n```\n\n### Doctor says the bridge is serving another project\n\nIf `bridge.project_root` points at another repo, a different bridge supervisor still owns the port. Restart from the repo you want to serve:\n\n```bash\nbin\u002Fcodex-oss restart --port 4000\nbin\u002Fcodex-oss doctor --network\n```\n\nCurrent versions clear the port owner during restart so an old source-checkout supervisor cannot quietly serve a target project.\n\n### Runtime agent says MissionV1 is missing\n\nRuntime-controlled agents need exactly one tagged block:\n\n```text\n\u003COSS_HANDOFF_JSON>\n{ \"schema_version\": \"oss_agent_mission.v1\", ... }\n\u003C\u002FOSS_HANDOFF_JSON>\n```\n\nThe older lightweight `OSS_HANDOFF_JSON:` handoff is for raw\u002Flegacy delegation, not MissionV1 runtime agents.\n\nIf this fails with \"Multiple OSS_HANDOFF_JSON blocks\", check the project's `AGENTS.md`. Standing repo instructions should describe the handoff rule, but they should not contain literal `\u003COSS_HANDOFF_JSON>` examples.\n\n### Codex routes GPT through the bridge\n\nRemove any session-wide setting like:\n\n```toml\nmodel_provider = \"opencode_bridge\"\n```\n\nUse the bridge provider only inside OSS agent TOMLs.\n\n### No live commentary appears\n\nFirst check the artifact:\n\n```bash\nbin\u002Fcodex-oss show-trace MISSION_ID\n```\n\nThen check streaming config:\n\n```bash\necho \"$OSS_VISIBLE_TRACE\"\necho \"$OSS_VISIBLE_TRACE_STREAM\"\n```\n\nExpected defaults:\n\n```text\nOSS_VISIBLE_TRACE=summary\nOSS_VISIBLE_TRACE_STREAM=1\n```\n\n### Provider auth fails\n\nCheck the key file:\n\n```bash\npython3 - \u003C\u003C'PY'\nfrom pathlib import Path\npath = Path(\".codex-oss\u002Fenv\u002Fopencode-go.env\")\nprint(\"env file present:\", path.exists())\nprint(\"contains OPENCODE_GO_API_KEY:\", \"OPENCODE_GO_API_KEY=\" in path.read_text() if path.exists() else False)\nPY\n```\n\nDo not paste the key into issues, logs, or chat.\n\n## Current Status\n\nThe runtime-backed path is the supported product path for bounded OSS delegation. Raw OSS editing remains a research lane.\n\nUse `claim-status`, `audit-mission`, and `doctor` when you need proof rather than vibes:\n\n```bash\nbin\u002Fcodex-oss claim-status --project . --json\nbin\u002Fcodex-oss audit-mission MISSION_ID --project . --json\nbin\u002Fcodex-oss doctor --network --json\n```\n\n## License\n\nSee [LICENSE](LICENSE).\n","OpenCode Bridge 是一个允许Codex使用开源模型作为受控子代理的工具。它通过本地兼容的桥梁路由OSS工作者，提供范围内的运行时工具，记录它们的行为，并为GPT审查生成基于证据的报告。其核心功能包括运行时控制的调查、基于证据的报告、可见的工作进度、补丁安全机制以及可审计的工件生成。适用于希望在不直接授权给开源模型的情况下获得更经济或并行帮助的场景，如文件检查与总结、低风险仓库侦察、小规模补丁生成或验证等任务。避免用于涉及认证、授权、迁移或任何可能导致数据丢失或安全问题的任务。通过将执行控制权交给运行时环境，让开源模型负责推理，最终由GPT进行判断，确保了操作的安全性和可控性。",2,"2026-06-11 03:58:50","CREATED_QUERY"]