Skip to content
Open
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
141 changes: 141 additions & 0 deletions src/agent/native-attach.ts
Original file line number Diff line number Diff line change
@@ -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>): …`). */
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<string | undefined>) | undefined;
/** Lane bootstrap (ensureProxyRunning wrapper) for the spawn fallback. */
bootstrap: () => Promise<string | undefined>;
/** 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<string | undefined> {
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;
}
98 changes: 28 additions & 70 deletions src/agent/pi-native.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -170,75 +171,28 @@ export function _setSpawnForTest(fn?: () => Promise<string | undefined>): 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<string | undefined> {
// #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);
Expand All @@ -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;
Expand Down
33 changes: 33 additions & 0 deletions tests/native-attach-lane-guard.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
Loading