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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The full file-by-file map lives in [reference/architecture.md](reference/archite

### Key Design Decisions

1. **The in-repo kernel is bundled inline** — `kernel/` (the acp-kernel source, consumed as a `file:` devDependency, #2092) is NOT listed in tsup `external`, so `dist/index.js` is self-contained. Exception: `zod` (exact `4.1.8`, matching the opencode host's own zod so V1 plugin-tool shapes interoperate) is a real dependency and stays external — only `dist/agent/opencode-native.js` imports it (lazily, at plugin-tool registration); `dist/index.js` and every other entry remain zod-free. When zod cannot be resolved at runtime the V1 plugin degrades to plain proxy mode instead of failing. Same for `pi-subagents/` (the billion-context-pi-subagents source, #2384): consumed via a `file:` devDependency and inlined into the pi-lane entries; its own build inlines the `typebox` peer, so those bundles stay self-contained too.
1. **The in-repo kernel is bundled inline** — `kernel/` (the acp-kernel source, consumed as a `file:` devDependency, #2092) is NOT listed in tsup `external`, so `dist/index.js` is self-contained. Exception: `zod` (exact `4.6.7`, matching the opencode host's own zod so V1 plugin-tool shapes interoperate; bumped from `4.1.8` to clear GHSA-mrhx-c7xc-m3w5, #4820) is a real dependency and stays external — only `dist/agent/opencode-native.js` imports it (lazily, at plugin-tool registration); `dist/index.js` and every other entry remain zod-free. When zod cannot be resolved at runtime the V1 plugin degrades to plain proxy mode instead of failing. Same for `pi-subagents/` (the billion-context-pi-subagents source, #2384): consumed via a `file:` devDependency and inlined into the pi-lane entries; its own build inlines the `typebox` peer, so those bundles stay self-contained too.
2. **Tags use XML format** — messages carry ACP tags like `<acp tokens="2" type="text">m00001</acp>` (an opening element with `tokens=`/`type=` attributes wrapping a ref id, closed by its end element). In **source files** these angle brackets MUST be written as hex escapes (`\x3c`, `\x3e`) to avoid tooling that strips well-formed tags.
3. **Auto-update**: checks npm registry every 3 min by default (`CHECK_INTERVAL_MS = 3*60*1000`, overridable via `update.checkIntervalMs` / `BILI_UPDATE_CHECK_INTERVAL_MS`, #2030); first check per process ignores throttle. In plugin mode the injected code lives in the HOST process — new code only takes effect after a host restart, and if the injection breaks at runtime, model traffic goes direct (uncompressed) until the host is restarted; since #3581 that state is visible via the panel banner and `/__bili/status` `attribution` field (README Self-update section).
4. **Tee logger**: all proxy logs go through `src/logger.ts` (file + stderr). Do NOT use `console.error` in server-side modules — use `loggerLog()`.
Expand Down
9 changes: 9 additions & 0 deletions TECHNICAL-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -556,3 +556,12 @@ Design:
Behavior change (disclosed): OLD = a wedged standalone proxy lived forever holding its port and every respawn died with an opaque EADDRINUSE; NEW = continuous main-loop silence ≥ 5 min ⇒ one warn at 30 s, one FATAL log line, then `process.exit(1)` so a spawner's normal respawn recovers the port, plus a serving/wedged adjudication + kill guidance appended to every terminal EADDRINUSE message. No new config/env/CLI surface — thresholds are module constants. Plugin-mode behavior is unchanged (watchdog not armed there).

Tests: `tests/event-loop-watchdog.test.ts` (verdict boundary table incl. warn-once semantics; default pin; REAL-worker wedge integration — a synchronous spin blocks the main loop past the hard threshold, the trip fires, both forensic lines land in the log file with the `[v=…]` tag; healthy stream never trips; spawn-failure seam degrades cleanly) + `tests/port-owner.test.ts` additions (wildcard-origin rewrite; serving/wedged/anonymous hint wording; live-responder pid beats stale registry pid; dead holder reads as not-serving; pre-registration "starting" reads as not-serving).

## Dependency audit — zod advisory GHSA-mrhx-c7xc-m3w5 and the jimp nested-zod false positive (#4820)

A fresh-install `npm audit` reports one high-severity advisory, GHSA-mrhx-c7xc-m3w5 (CVE-2023-54404, CVSS 7.5 High, **availability/DoS only** — no confidentiality or integrity impact), against two different chains that must be handled differently:

- **Direct `zod`** (`package.json` `dependencies.zod`, exact pin per KDD #1). Genuinely affected: the vulnerable code is `$ZodArray.handleArrayResult` in `v4/core/schemas.js`, which accumulates every per-element validation issue with no cap or early termination when validating an oversized array against an unconstrained array schema. Bumped `4.1.8 → 4.6.7` (patched line starts at 4.6.6, which adds an `abortEarly`-gated early break plus a `capSize` registration that 4.1.8 lacks). The pin stays EXACT (not a range) so npm can dedupe to one shared instance with the opencode host — the KDD #1 interop guarantee — and is covered by `tests/opencode-native-v1.test.ts`. In our tree this copy is consumed only by `src/agent/opencode-native.ts` (OpenCode V1 plugin tools, lazy opaque import); it is not loaded in the Pi/proxy lanes.
- **Jimp's nested `zod@3.x`** (`optionalDependencies.jimp`; each `@jimp/*` declares `zod ^3.23.8`, so npm nests a 3.x copy under every `node_modules/@jimp/*/node_modules/zod`). This is a **false positive for how we use jimp**, established at source level rather than assumed from the semver range: the vulnerable function exists only in zod's v4 implementation (`v4/core/schemas.js`) and never in v3; `import "zod"` in a 3.25.x install resolves to the v3 core; and `@jimp/*` import plain `"zod"` (never `zod/v4`). So the bug is unreachable through jimp. We therefore do **NOT** force-override jimp's zod 3→4 (a cross-major override with no patched 3.x to converge onto, risking jimp's own validation semantics); we track upstream instead. Reachability limits stay explicit: jimp is optional and lazy-loaded (`src/image-rescale.ts`), degrading to pass-through when absent, reachable only during image processing. Boundary: the bundled v4 preview *inside* a 3.25.x tarball is itself pre-fix — if a future `@jimp` ever imports `zod/v4`, re-evaluate this conclusion.

A hard CI/runtime audit gate is deliberately deferred: it would stay red because of the jimp chain unless we add an exception, and any exception must be narrowly scoped, explained, and revisitable — never a blanket suppression. Revisit once the direct-zod bump has landed and upstream jimp is tracked.
8 changes: 4 additions & 4 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
},
"dependencies": {
"mysql2": "^3.15.3",
"zod": "4.1.8"
"zod": "4.6.7"
},
"optionalDependencies": {
"jimp": "1.6.1"
Expand Down
4 changes: 2 additions & 2 deletions tests/opencode-native-v1.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import {
import { rmrf } from "./tmp-rm.ts";

// Minimal structural stand-in for the host's zod module: only the builders
// jsonSchemaToZodShape touches. Real zod (4.1.8) is exercised implicitly by
// jsonSchemaToZodShape touches. Real zod (4.6.7) is exercised implicitly by
// the shape assertions below via the actual import.
const fakeZ = {
any: () => ({ __fake: "any" }),
Expand Down Expand Up @@ -59,7 +59,7 @@ describe("jsonSchemaToZodShape", () => {

it("produces fields the real host zod accepts in z.object()", async () => {
// The v1 registry wraps our shape with the HOST's zod: simulate with
// the real zod dependency (4.1.8) to prove cross-instance interop.
// the real zod dependency (4.6.7) to prove cross-instance interop.
const real = await import("zod");
const shape = jsonSchemaToZodShape(
{ type: "object", properties: { range: { type: "string" }, limit: { type: "number" } } },
Expand Down
Loading