Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions devlog/2026-09-16_billion-context-native-yield/DESIGN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# DESIGN - Yield to billion-context native mode via action-time env re-check

- Task ID: `2026-09-16_billion-context-native-yield`
- Home Repo: `opencode-acp`
- Created: 2026-09-16
- Status: Accepted

## 1. Problem Statement

- **What problem are we solving?** ACP cannot detect that billion-context owns compression in **native** mode (OpenCode 2.x package plugin): every existing self-disable signal (`BILLION_CONTEXT_PROXY` sampled once at setup; `/bili/` prefix in configured provider baseURL) is statically sampled before/without the native-mode ownership marker ever becoming visible. Result: double compression (#405).
- **Why now?**: billion-context PR #824 (native mode, open) ships a synchronous ownership marker specifically so standalone extensions like ACP can back off — ACP must consume it before that PR merges or the double-compression window goes live.

## 2. Goals & Non-Goals

- **Goals**:
- Detect both owner markers (`BILLION_CONTEXT_PROXY` launcher, `BILLION_CONTEXT_NATIVE` native) at action time, not just startup.
- On detection: reuse the existing yield path (deny ACP tools in config hook + no-op all guarded hooks + one-time log); tools additionally throw at execute time.
- Non-latching: unsetting the marker restores ACP (mirrors existing `/bili/` flag semantics).
- Zero state-format/API breakage; hot path stays O(1) with no I/O.
- **Non-Goals**:
- No installer-side reconciliation of third-party plugin entries (billion-context repo scope).
- No health-probe/port-based proxy discovery.
- No changes to compression pipeline internals.

## 3. Current Architecture

- **How it works today**:
```
opencode process start
└─ plugin factory (index.ts)
├─ sample process.env.BILLION_CONTEXT_PROXY ONCE → return {} if set [launcher mode only]
├─ register hooks wrapped in guard(disabledByBiliProxy flag)
└─ config hook: findBiliProxyProviders(baseURL "/bili/") → set flag + deny tools [manual mode only]
```
- **Pain points**: both signals are point-in-time samples. Native mode writes its marker later (module evaluation order vs ACP setup) and never touches baseURL → undetectable.

## 4. Proposed Architecture

- **Overview**:
```
every ACP action re-samples env via detectBiliEnvYield():
setup fast path : marker set → factory returns {} (existing pattern, extended to 2 vars)
guard(hook call) : marker set → no-op + one-time log (NEW lazy branch)
config hook run : marker set → deny 5 tools, skip wiring (NEW lazy branch, shared denyAcpTools helper)
resolveToolContext(): marker set → throw "disabled" error (NEW; single chokepoint for all 5 tools)
```
- **Key components**:
- `lib/bili-proxy.ts`: `detectBiliEnvYield(env?) → "launcher" | "native" | null` (pure, injectable env), `describeBiliEnvYield(source)`, constants `BILI_PROXY_ENV_VAR` / `BILI_NATIVE_ENV_VAR`. Launcher precedence (native bootstrap refuses to run while the launcher var is set).
- `index.ts`: closure-level `noteEnvYield()` dedups logging per source per factory instance (guard runs on every LLM request).
- `lib/compress/types.ts`: `resolveToolContext()` gate — first statement of every tool execute, so one check covers compress/decompress/search_context/acp_status/acp_context_recap without touching the five tool files.
- **Data flow**: no new data structures; `process.env` remains the sole carrier of the cross-plugin contract. Precedence chain when multiple signals are active: any signal yields; for logging/description, `disabledByBiliProxy` (/bili/) branch keeps its own message, env branches use `describeBiliEnvYield`.

## 5. Alternatives Considered

| Option | Verdict | Why |
| ----------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wrap each tool's `execute` in index.ts with a typed wrapper | Rejected | Requires SDK type gymnastics for 5 tools; `resolveToolContext` gives identical coverage at one existing chokepoint with zero signature changes |
| Poll a file/port to discover the native proxy | Rejected | I/O on hot path, race-prone, and the env marker is the agreed synchronous contract already shipped on the billion-context side |
| Latch disable permanently once detected | Rejected | Breaks parity with the existing non-latched `/bili/` semantics (config reload restores ACP); tests assert the restore path |
| Check only in the config hook | Insufficient | Config runs are discrete events; a tool call between the marker landing and the next config run would still act — hence the `resolveToolContext` gate |

## 6. Backward Compatibility

- Persisted state format: unchanged. Internal `dcp` tags: unchanged. Exported APIs: additive only (new exports in `lib/bili-proxy`). Existing log message for `/bili/` detection: verbatim preserved. Launcher-mode behavior: identical outcome, same log wording family.
53 changes: 53 additions & 0 deletions devlog/2026-09-16_billion-context-native-yield/REQ.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# REQ - Yield to billion-context native mode via action-time env re-check

- Task ID: `2026-09-16_billion-context-native-yield`
- Home Repo: `opencode-acp`
- Created: 2026-09-16
- Status: InProgress
- Priority: P1
- Owner: ranxianglei (agent: ework-daemon)
- References: https://github.com/ranxianglei/opencode-acp/issues/405 · source analysis: ranxianglei/billion-context#820 · marker provided by ranxianglei/billion-context PR #824

## 1. Background & Problem Statement

- **Context**: billion-context adds an OpenCode 2.x host-native mode (`opencode-native`, PR #824): a package-installed plugin bootstraps its own proxy and replaces model-API requests at `http.request` time (new Request object pointing at `<proxy>/bili/<url>`; `Request.url` is readonly, #810). If opencode-acp is loaded alongside it, both compress → violates the single-compression-owner principle.
- **Current behavior (symptom)**: ACP's self-disable signals are all sampled statically at setup/config time:
1. `index.ts` setup check reads `BILLION_CONTEXT_PROXY` once — in native mode that var is written only AFTER async proxy bootstrap, so setup misses it.
2. The config hook / `lib/bili-proxy.ts` rely on `/bili/` in provider `baseURL` — native mode never touches configured baseURL, so the signal is invisible.
- Result: launcher mode and manual-wiring mode yield correctly; **native mode has no detectable signal at all** → double compression for users with both plugins installed.
- **Expected behavior**: ACP yields (deny tools + no-op hooks + one-time log) whenever billion-context owns compression in this process, regardless of when the ownership marker appears relative to ACP setup.
- **Impact**: Users with `opencode-acp` + `<configDir>/plugins/billion-context` installed get double compression in native mode until the billion-context installer reconciles third-party entries (`bili plugin install opencode` does not currently remove the opencode-acp entry) — this fix is the safety net.

## 2. Reproduction (if applicable)

- **Environment**: any host with opencode 2.x + ACP plugin + billion-context native plugin installed simultaneously.
- **Minimal reproduction steps**:
1. Install both plugins so both load in one opencode process.
2. Start opencode directly (no `bili` launcher).
3. Observe: ACP stays fully active while the native plugin also compresses via the proxy.
- **Relevant configuration**: none specific — failure is structural (signal timing), independent of ACP config values.

## 3. Constraints & Non-Goals

- **Constraints**:
- Backward compatibility: persisted state format, internal `dcp` tags, exported APIs unchanged. Existing launcher/manual-mode yield behavior must be byte-for-byte preserved (existing tests green).
- Performance requirements: env reads are O(1); guard runs on every LLM request — no new I/O, no log spam (one-time log per source per factory instance).
- Marker contract (billion-context side, verified on branch `2026-09-15_opencode-native-plugin`): `markNativeHost()` sets `process.env.BILLION_CONTEXT_NATIVE = "opencode"` synchronously at module evaluation, first-writer-wins, gated by `nativeBootstrapGate`.
- **Non-Goals** (explicitly out of scope):
- Changing the billion-context installer to remove third-party plugin entries (their repo's problem).
- Detecting the proxy by probing ports/health endpoints (env marker is the agreed synchronous contract).
- Any state-persistence changes.

## 4. Acceptance Criteria (must be testable)

- **Correctness**:
- [x] `detectBiliEnvYield(env?)` pure function returns `"launcher"` / `"native"` / `null` with launcher precedence; unit-tested.
- [x] Setup-time fast path: either marker set before factory run → factory returns `{}` (no hooks/tools), one-time log.
- [x] Marker set AFTER factory run (the #405 race): next config run denies all 5 ACP tools and skips command/primary_tools wiring; all guarded hooks (system/messages/text.complete/command/event) become no-ops.
- [x] Tool execute gate: with either marker set, every ACP tool's execute throws a clear "disabled" error (shared `resolveToolContext` chokepoint covers all five tools).
- [x] `BILLION_CONTEXT_PROXY` is re-read at action time too (launcher marker landing late yields identically).
- [x] Re-enable: unsetting the marker restores full ACP behavior (config wiring + ID injection + tool gate passes).
- [x] Exactly one yield log line per source per factory instance across repeated hook invocations.
- [x] Pre-existing `bili-proxy-integration.test.ts` (manual `/bili/` mode) still passes unchanged.
- **Performance / Stability**:
- [x] No new I/O on the hot path; `npm run typecheck`, `npm test`, `npm run build` all pass.
63 changes: 63 additions & 0 deletions devlog/2026-09-16_billion-context-native-yield/WORKLOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# WORKLOG - Yield to billion-context native mode via action-time env re-check

- Task ID: `2026-09-16_billion-context-native-yield`
- Home Repo: `opencode-acp`
- Status: InProgress
- Updated: 2026-09-16 11:10

## 1. Summary

- **What was done**: Added action-time (lazy) detection of billion-context ownership markers (`BILLION_CONTEXT_PROXY`, `BILLION_CONTEXT_NATIVE`) at every ACP action point — setup fast path, hook guard, config hook, and the shared tool entry point — so ACP yields to billion-context in launcher AND native modes regardless of plugin load order.
- **Why**: In native mode (billion-context #820/#824) the ownership marker is written asynchronously/after ACP setup, and configured provider baseURLs never carry `/bili/`, so all pre-existing static-sampling signals missed it → double compression (#405).
- **Behavior / compatibility changes**: Yes — new yield path for a previously undetectable scenario; all existing behavior (launcher env check, `/bili/` baseURL detection, logs) preserved. No state-format or API changes.
- **Risk level**: Low

## 2. Change Log

### Commits

| Commit | Description |
| ----------- | ------------------------------------------------------------------------------ |
| 278bea6 | feat: yield to billion-context native mode via action-time env re-check (#405) |
| (this rev.) | fix: address PR #406 dual-agent review findings |

### Key Files

- `lib/bili-proxy.ts` — new pure `detectBiliEnvYield(env?)` + `describeBiliEnvYield(source)` + `biliYieldLogMessage(source)` (single source of truth for the console announcement; keeps the launcher wording byte-identical to master) + exported env-var name constants; documents the cross-repo marker timing contract.
- `index.ts` — setup early-return now covers both markers; `guard()` re-samples env per call with one-time log per source; config hook re-samples env each run and denies all 5 ACP tools via extracted `denyAcpTools()` helper (shared with the existing `/bili/` branch).
- `lib/compress/types.ts` — `resolveToolContext()` (first statement of every ACP tool's execute) now throws a clear "disabled" error when either marker is set at action time — defense-in-depth covering all five tools at one chokepoint.
- `tests/bili-native-yield.test.ts` — new: unit tests for the pure detector + integration tests through the real factory (setup fast path ×2 markers, runtime marker → deny/no-op/tool-throws for ALL five tools, launcher parity, re-enable, one-time log).
- `tests/bili-proxy-integration.test.ts` — one line: also `delete process.env.BILLION_CONTEXT_NATIVE` in the pre-import env setup (the new setup fast path would otherwise break this suite if the host env carried the marker).

## 3. Design & Implementation Notes

- Marker contract verified against billion-context branch `2026-09-15_opencode-native-plugin`: `src/agent/native-bootstrap.ts` `markNativeHost()` sets `env.BILLION_CONTEXT_NATIVE = "opencode"` synchronously at module evaluation (before any await, first-writer-wins); called from `src/agent/opencode-native.ts:160` guarded by `nativeBootstrapGate` (which refuses to run when `BILLION_CONTEXT_PROXY` is already set — hence launcher precedence in `detectBiliEnvYield`).
- Why three sampling points: setup = cheap full bail-out when load order favors us; guard/config-hook = covers the race where the native module evaluates after ACP setup (hooks no-op + tools removed from LLM list); `resolveToolContext` = covers the residual window where a tool call lands after the last config run but before opencode re-applies permissions.
- One-time log dedup is per factory instance (closure var `announcedEnvYieldSource`) because `guard()` runs on every LLM request.
- The `/bili/` branch keeps its original log message verbatim (no hidden external dependency assumed, but no reason to churn it).

## 4. Verification

- [x] `npm run typecheck` — clean
- [x] `npm test` — 1273 pass / 0 fail (new file adds 10 tests, all green)
- [x] `npm run build` — success
- [x] Mutation check: with `index.ts` + `lib/compress/types.ts` reverted to master, 7/10 new tests FAIL; with the fix, 10/10 PASS
- [x] `format:check`: repo baseline already fails (~450 files pre-existing drift, left untouched); new files fully prettier-formatted; two targeted prettier fixes applied to tracked files per review (import line in `index.ts`, wrapped signature in `lib/bili-proxy.ts`)

## 5. Review Round (PR #406, dual-agent)

Two independent agents reviewed source + tests. Dispositions:

| Finding | Severity | Disposition |
| ------- | -------- | ----------- |
| Prettier violations introduced in tracked files (import block >100 cols, unwrapped signature) | low | Fixed — collapsed import to one line, wrapped `detectBiliEnvYield` signature |
| Env branch returned before assigning `disabledByBiliProxy` → stale-flag edge when an env marker and a `/bili/` provider appear/disappear together | low | Fixed — flag computed before either branch (invariant documented in code) |
| Launcher log wording drifted from master (hidden external dependency risk) | info | Fixed — `biliYieldLogMessage()` restores the exact master string for launcher |
| Fail-closed tradeoff not documented (marker set but billion-context bootstrap later fails → ACP stays off until restart) | info | Documented in PR body (chosen over fail-open double-compression risk) |
| Tool-gate test covered only 2 of 5 tools | test | Fixed — all five tools exercised through the shared `resolveToolContext` gate |
| Hooks-no-op test missed `command.execute.before` | test | Fixed — invocation added, asserts output parts stay empty |
| Re-enable test lacked try/finally around the env mutation (demonstrated cascade failures) | test | Fixed |
| Sibling `bili-proxy-integration.test.ts` didn't clean `BILLION_CONTEXT_NATIVE` | test | Fixed — one-line delete in pre-import setup |
| `announcedEnvYieldSource` never resets (cosmetic: re-announce if marker toggles off/on within one process lifetime) | info | Accepted — detection itself is live every call; only the announcement dedup is sticky |

Re-verified after fixes: `npm run typecheck` clean, `npm test` 1273/1273, `npm run build` OK, new test file prettier-clean.
Loading
Loading