From 2b68520e180003fbafbdb1cbfb1bd0dabdbfed7d Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Fri, 30 Oct 2026 23:07:53 +0800 Subject: [PATCH] =?UTF-8?q?agent:=20shared=20attach/recovery=20lifecycle?= =?UTF-8?q?=20=E2=80=94=20migrate=20the=20pi=20lane=20(#5241=20phase=201,?= =?UTF-8?q?=20PR-1a)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First lane migration of the approved phase-1 plan (#5241 comment): the verifyAttachAndRecover lifecycle moves from pi-native.ts into a shared native-attach.ts, parameterized by a per-lane NativeLaneSpec (publish / unpublish / onEvent / spawn seam / bootstrap). Pure transposition — the pi lane's observable behavior is unchanged, proven by the phase-0 stake matrix (tests/contract-v2-stake-verify-attach.test.ts) passing untouched. Also lands the one-lane-per-process guard (armNativeLane): the four lane implementations all assume they are alone in the process (same BILLION_CONTEXT_PROXY env var, same global fetch-intercept slot, background timers that outlive any call). Phase-0 probing (#5242) showed two armed lanes in one process overwrite each other within milliseconds. Production never does this — the guard makes the implicit contract explicit and plainly worded. Re-arming the same lane stays legal (tests/restarts); a second, different lane throws. omp/opencode/dsh keep their own copies until their migration PRs; their suites and issue3544 stay green untouched. Net: pi-native.ts -77 lines, one spec + one-line wrapper in their place. --- src/agent/native-attach.ts | 141 +++++++++++++++++++++++++ src/agent/pi-native.ts | 98 +++++------------ tests/native-attach-lane-guard.test.ts | 33 ++++++ 3 files changed, 202 insertions(+), 70 deletions(-) create mode 100644 src/agent/native-attach.ts create mode 100644 tests/native-attach-lane-guard.test.ts diff --git a/src/agent/native-attach.ts b/src/agent/native-attach.ts new file mode 100644 index 0000000000..0b69dcb1cb --- /dev/null +++ b/src/agent/native-attach.ts @@ -0,0 +1,141 @@ +// Shared attach/recovery lifecycle for the native host lanes (#5241 phase 1). +// +// Transplanted verbatim from pi-native.ts (PR-1a): pi/omp/opencode carried +// near-identical copies of this function — dsh carries a thicker variant — so +// every fix had to be applied four times and the same bug class kept +// reappearing on lane after lane (port pinning #926→#4566→#5127, cold-start +// tools #4134→#4998→#5001→#4641; see umbrella #5241). One lane migrates per +// PR; each lane's answers are frozen by the phase-0 stakes +// (tests/contract-v2-stake-verify-attach.test.ts) — a change here that changes +// any lane's observable behavior must update those stakes in the same PR, by +// design. + +import { nativeAttachOrigin, singleFlight } from "./native-bootstrap.js"; +import { observeRoutedOrigin, type NativeInterceptState } from "./native-intercept.js"; +import { fetchProxyVersion, waitForProxyVersion } from "./shared.js"; + +/** Lane-facing event sink: logHostEvent for the process-owned lanes, the + * client-visible event bus for dsh. Level set matches logHostEvent's + * "info" | "error" usage below. */ +export type NativeLaneEventHandler = (level: "info" | "error", message: string) => void; + +/** Everything lane-specific the shared lifecycle needs. Pure transposition: + * pi/omp/opencode differ only in strings and publish side effects today; + * dsh's extras (older-resident rotation #3544, register bookkeeping) arrive + * as additional optional hooks when that lane migrates — never silently + * unified. */ +export interface NativeLaneSpec { + /** Lane tag for log lines (`bili-native(): …`). */ + lane: string; + /** The lane's module-level intercept state singleton. */ + state: NativeInterceptState; + /** Test seam, read at CALL time so `_setSpawnForTest` after arming still + * applies (see pi-native's `_spawnForTest`). */ + spawnForTest: () => (() => Promise) | undefined; + /** Lane bootstrap (ensureProxyRunning wrapper) for the spawn fallback. */ + bootstrap: () => Promise; + /** Publish a live origin on the lane's surfaces — pi/omp/opencode: the + * shared state + BILLION_CONTEXT_PROXY; dsh additionally re-bases its + * register. */ + publish: (origin: string) => void; + /** Drop the published origin (spawn fallback unfreezes the preset env). */ + unpublish: () => void; + /** Lane event sink (logHostEvent / persistClientEvent). */ + onEvent: NativeLaneEventHandler; +} + +// One lane per process (#5241 phase 1). The four lane implementations all +// assume they are alone: they write the SAME process.env.BILLION_CONTEXT_PROXY, +// bind the SAME global fetch-intercept slot and run background timers that +// outlive any single call. Phase-0 probing (#5242) showed two armed lanes in +// one process overwrite each other's proxy env and spawn counters within +// milliseconds. Production never does this (each lane rides its own host +// process) — this guard turns that accident of deployment into an explicit, +// plainly-worded contract before the lanes share one implementation. +let armedLane: string | undefined; + +/** Arm `lane` as this process's native lane. Re-arming the SAME lane is fine + * (tests and restarts do it); arming a DIFFERENT lane throws — see above. */ +export function armNativeLane(lane: string): void { + if (armedLane !== undefined && armedLane !== lane) { + throw new Error( + `bili native lanes are one-per-process: this process already armed the "${armedLane}" lane, refusing to also arm "${lane}" — two lanes in one process overwrite each other's BILLION_CONTEXT_PROXY and fetch intercept (observed in the #5242 phase-0 stakes). Run each lane in its own host process.`, + ); + } + armedLane = lane; +} + +/** Test hook: clear the one-lane guard between suites. */ +export function _resetArmedLaneForTest(): void { + armedLane = undefined; +} + +/** #1135/#1365 (moved from pi-native.ts, lane-generalized): the attached + * origin can go stale — at startup (the owning launcher exited before this + * process started) or at runtime (it exits while this session still rides + * the shared proxy, #1130). Probe before trusting it: healthy → keep + * attaching (a transient blip costs nothing — the session never migrates). + * DEAD + routed-channel evidence (#1365: /bili/-baked model traffic was + * observed at some origin) → the session's context lives at THAT origin, so + * wait for the pinned target to come back (bounded by + * BILI_ATTACH_HEALTH_DEADLINE_MS) instead of spawning — a second instance + * would serve tools while the model channel stays pinned elsewhere and + * every bili tool call 404s against it (unrecoverable split); the env is + * preserved so the user's target stays declared. DEAD with no evidence + * after the grace window (BILI_ATTACH_EVIDENCE_GRACE_MS) → unfreeze the + * preset env and fall back to spawning our own proxy, re-arming respawn as + * a pure spawn. Resolves to the origin the client should use — the + * (recovered) attach origin, the fallback origin, or undefined when nothing + * came up. */ +export async function verifyAttachAndRecover(spec: NativeLaneSpec, attachOrigin: string): Promise { + const { state } = spec; + // #1365: routed evidence outranks the planned origin — probe where the + // model channel actually points, not where the env says it should. An + // EXPLICIT BILLION_CONTEXT_ATTACH outranks both: it names the plugin API + // endpoint directly, and a routed model origin may be a plain model-only + // path (e.g. an admin-gated port) that never exposes the plugin manifest. + const explicitAttachOrigin = nativeAttachOrigin(process.env); + const home = explicitAttachOrigin ?? state.routedOrigin ?? attachOrigin; + const version = await fetchProxyVersion(home).catch(() => undefined); + if (version !== undefined) { + // Restore the readyOrigin short-circuit — a runtime recovery clears + // state.origin before re-probing, and a transient blip must not leave + // it dangling. + spec.publish(home); + return home; + } + const pinned = explicitAttachOrigin ?? state.routedOrigin ?? (await observeRoutedOrigin(state)); + if (pinned !== undefined) { + const back = await waitForProxyVersion(pinned); + if (back !== undefined) { + spec.publish(back); + spec.onEvent("info", `bili-native(${spec.lane}): attach target ${pinned} is healthy again — attached, no second instance spawned`); + return back; + } + spec.onEvent( + "error", + explicitAttachOrigin !== undefined + ? `bili-native(${spec.lane}): explicit attach target ${pinned} unreachable within the health deadline — refusing to spawn a second instance (your declared endpoint stays authoritative). Start your proxy at ${pinned} or unset BILLION_CONTEXT_ATTACH; bili keeps re-checking and self-heals when it comes back.` + : `bili-native(${spec.lane}): attach target ${pinned} is down and this process's model channel is pinned to it — refusing to spawn a second instance (bili tools would 404 against the other one). Start your proxy at ${pinned} or unset BILLION_CONTEXT_PROXY; bili keeps re-checking and self-heals when it comes back.`, + ); + state.origin = undefined; + return undefined; + } + spec.onEvent("error", `bili-native(${spec.lane}): attach target ${attachOrigin} is not healthy — falling back to a spawned proxy`); + spec.unpublish(); + state.attach = false; + state.origin = undefined; + const start = singleFlight(spec.spawnForTest() ?? spec.bootstrap); + state.respawn = start; + // Publish whatever origin lands on BOTH the shared state and the env — + // env readers (compaction reporter, /acp status) must never disagree with + // what the route resolves, whoever produced the origin. + const landed = start().then((o) => { + if (o !== undefined) { + spec.publish(o); + } + return o; + }); + state.ready = landed; + return landed; +} diff --git a/src/agent/pi-native.ts b/src/agent/pi-native.ts index 5a74613f78..d0e190b85f 100644 --- a/src/agent/pi-native.ts +++ b/src/agent/pi-native.ts @@ -33,11 +33,12 @@ import { createBiliPlugin, createPiDirectSendGuard } from "./pi.js"; import { isLegacyBcpEntry, markNativeHost, nativeAttachOrigin, nativeBootstrapGate, nativeProxyScriptPath, proxyEnvOrigin, setNativeOriginWaiter, singleFlight } from "./native-bootstrap.js"; import { loadConfigFile } from "../config.js"; import { getInlineEngine, INLINE_ORIGIN } from "../inline-engine.js"; -import { installNativeFetchIntercept, noteRoutedOrigin, observeRoutedOrigin, readyOrigin, setDeclaredModelEndpoints, type NativeInterceptState } from "./native-intercept.js"; +import { installNativeFetchIntercept, noteRoutedOrigin, readyOrigin, setDeclaredModelEndpoints, type NativeInterceptState } from "./native-intercept.js"; import { loadDeclaredModelEndpoints } from "../model-endpoints.js"; +import { armNativeLane, verifyAttachAndRecover as verifyAttachAndRecoverShared, type NativeLaneSpec } from "./native-attach.js"; import { installInlineTransport } from "./pi-inline.js"; import { installNativeWebSocketIntercept } from "./native-ws-intercept.js"; -import { fetchProxyVersion, fetchStatus, waitForProxyVersion } from "./shared.js"; +import { fetchProxyVersion, fetchStatus } from "./shared.js"; import { logHostEvent } from "./host-log.js"; // Shared plumbing lives in native-bootstrap.ts (side-effect-free — importing @@ -170,75 +171,28 @@ export function _setSpawnForTest(fn?: () => Promise): void { _spawnForTest = fn; } -/** #1135/#1365: the attached origin can go stale — at startup (the owning - * launcher exited before this process started) or at runtime (it exits while - * this session still rides the shared proxy, #1130). Probe before trusting - * it: healthy → keep attaching (a transient blip costs nothing — the session - * never migrates). DEAD + routed-channel evidence (#1365: /bili/-baked model - * traffic was observed at some origin) → the session's context lives at THAT - * origin, so wait for the pinned target to come back (bounded by - * BILI_ATTACH_HEALTH_DEADLINE_MS) instead of spawning — a second instance - * would serve tools while the model channel stays pinned elsewhere and every - * bili tool call 404s against it (unrecoverable split); the env is preserved - * so the user's target stays declared. DEAD with no evidence after the grace - * window (BILI_ATTACH_EVIDENCE_GRACE_MS) → unfreeze the preset env and fall - * back to spawning our own proxy, re-arming respawn as a pure spawn. Resolves - * to the origin the client should use — the (recovered) attach origin, the - * fallback origin, or undefined when nothing came up. */ +/** #1135/#1365: shared since #5241 phase 1 — the lifecycle itself lives in + * native-attach.ts (one implementation for all lanes, behavior frozen by + * tests/contract-v2-stake-verify-attach.test.ts). This lane spec is the + * pi-specific surface: publish = shared state + BILLION_CONTEXT_PROXY. */ +const laneSpec: NativeLaneSpec = { + lane: "pi", + state, + spawnForTest: () => _spawnForTest, + bootstrap, + publish: (origin) => { + state.origin = origin; + process.env.BILLION_CONTEXT_PROXY = origin; + }, + unpublish: () => { + delete process.env.BILLION_CONTEXT_PROXY; + }, + onEvent: (level, message) => logHostEvent(level, "[native-client]", message), +}; + +/** Doc comment moved to native-attach.ts#verifyAttachAndRecover. */ export async function verifyAttachAndRecover(attachOrigin: string): Promise { - // #1365: routed evidence outranks the planned origin — probe where the - // model channel actually points, not where the env says it should. An - // EXPLICIT BILLION_CONTEXT_ATTACH outranks both: it names the plugin API - // endpoint directly, and a routed model origin may be a plain model-only - // path (e.g. an admin-gated port) that never exposes the plugin manifest. - const explicitAttachOrigin = nativeAttachOrigin(process.env); - const home = explicitAttachOrigin ?? state.routedOrigin ?? attachOrigin; - const version = await fetchProxyVersion(home).catch(() => undefined); - if (version !== undefined) { - // Restore the readyOrigin short-circuit — a runtime recovery clears - // state.origin before re-probing, and a transient blip must not leave - // it dangling. - state.origin = home; - process.env.BILLION_CONTEXT_PROXY = home; - return home; - } - const pinned = explicitAttachOrigin ?? state.routedOrigin ?? (await observeRoutedOrigin(state)); - if (pinned !== undefined) { - const back = await waitForProxyVersion(pinned); - if (back !== undefined) { - state.origin = back; - process.env.BILLION_CONTEXT_PROXY = back; - logHostEvent("info", "[native-client]", `bili-native(pi): attach target ${pinned} is healthy again — attached, no second instance spawned`); - return back; - } - logHostEvent( - "error", - "[native-client]", - explicitAttachOrigin !== undefined - ? `bili-native(pi): explicit attach target ${pinned} unreachable within the health deadline — refusing to spawn a second instance (your declared endpoint stays authoritative). Start your proxy at ${pinned} or unset BILLION_CONTEXT_ATTACH; bili keeps re-checking and self-heals when it comes back.` - : `bili-native(pi): attach target ${pinned} is down and this process's model channel is pinned to it — refusing to spawn a second instance (bili tools would 404 against the other one). Start your proxy at ${pinned} or unset BILLION_CONTEXT_PROXY; bili keeps re-checking and self-heals when it comes back.`, - ); - state.origin = undefined; - return undefined; - } - logHostEvent("error", "[native-client]", `bili-native(pi): attach target ${attachOrigin} is not healthy — falling back to a spawned proxy`); - delete process.env.BILLION_CONTEXT_PROXY; - state.attach = false; - state.origin = undefined; - const start = singleFlight(_spawnForTest ?? bootstrap); - state.respawn = start; - // Publish whatever origin lands on BOTH the shared state and the env — - // env readers (compaction reporter, /acp status) must never disagree with - // what the route resolves, whoever produced the origin. - const landed = start().then((o) => { - if (o !== undefined) { - state.origin = o; - process.env.BILLION_CONTEXT_PROXY = o; - } - return o; - }); - state.ready = landed; - return landed; + return verifyAttachAndRecoverShared(laneSpec, attachOrigin); } const plan = planNativePi(process.env, loadConfigFile().pi?.inline); @@ -249,6 +203,10 @@ const plan = planNativePi(process.env, loadConfigFile().pi?.inline); * spawn mode stays test-guarded because bootstrap forks a real proxy. */ export function armNativePi(p: typeof plan): void { if (p.mode === "off") return; + // #5241 phase 1: one native lane per process — a second, different lane + // would overwrite this lane's BILLION_CONTEXT_PROXY and fetch intercept + // (see native-attach.ts). + armNativeLane("pi"); markNativeHost(process.env, "pi"); if (p.mode === "attach") { state.attach = true; diff --git a/tests/native-attach-lane-guard.test.ts b/tests/native-attach-lane-guard.test.ts new file mode 100644 index 0000000000..9087d2cb87 --- /dev/null +++ b/tests/native-attach-lane-guard.test.ts @@ -0,0 +1,33 @@ +// #5241 phase 1: the one-lane-per-process guard that native-attach.ts adds on +// top of the transplanted lifecycle. The guard exists because two armed lanes +// in one process overwrite each other's BILLION_CONTEXT_PROXY and fetch +// intercept (observed in the #5242 phase-0 stakes) — same lane re-arming is +// the normal test/restart pattern and must stay legal. + +import test, { afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { armNativeLane, _resetArmedLaneForTest } from "../src/agent/native-attach.ts"; + +afterEach(() => { + _resetArmedLaneForTest(); +}); + +test("armNativeLane: re-arming the SAME lane is fine (tests and restarts do it)", () => { + armNativeLane("pi"); + armNativeLane("pi"); + armNativeLane("pi"); +}); + +test("armNativeLane: a second, DIFFERENT lane throws a plain-language error", () => { + armNativeLane("pi"); + assert.throws( + () => armNativeLane("opencode"), + /one-per-process.*"pi".*"opencode".*BILLION_CONTEXT_PROXY/s, + ); +}); + +test("armNativeLane: _resetArmedLaneForTest clears the guard", () => { + armNativeLane("pi"); + _resetArmedLaneForTest(); + armNativeLane("dsh"); +});