pi-dual-engine 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +103 -2
  2. package/biome.json +22 -0
  3. package/dist/index.js +1096 -0
  4. package/package.json +27 -4
  5. package/scripts/smoke.ts +141 -0
  6. package/src/assignment.ts +173 -0
  7. package/src/breaker.ts +33 -0
  8. package/src/config.ts +55 -0
  9. package/src/engine-pool.ts +163 -0
  10. package/src/families.ts +58 -0
  11. package/src/handles.ts +31 -0
  12. package/src/headroom-http.ts +58 -0
  13. package/src/index.ts +96 -0
  14. package/src/lifecycle.ts +145 -0
  15. package/src/locks.ts +93 -0
  16. package/src/probe.ts +154 -0
  17. package/src/providers.ts +78 -0
  18. package/src/retrieve.ts +65 -0
  19. package/src/session.ts +150 -0
  20. package/src/setup.ts +230 -0
  21. package/src/state.ts +49 -0
  22. package/src/status.ts +64 -0
  23. package/src/types.ts +47 -0
  24. package/test/assignment.test.ts +193 -0
  25. package/test/boot.ts +84 -0
  26. package/test/breaker.test.ts +92 -0
  27. package/test/coldstart.test.ts +133 -0
  28. package/test/defaults.test.ts +16 -0
  29. package/test/degradation.test.ts +69 -0
  30. package/test/factory.test.ts +158 -0
  31. package/test/fakes.ts +155 -0
  32. package/test/handles.test.ts +37 -0
  33. package/test/harness.ts +39 -0
  34. package/test/headroom-http.test.ts +99 -0
  35. package/test/lifecycle.test.ts +75 -0
  36. package/test/optin.test.ts +41 -0
  37. package/test/ownership.test.ts +160 -0
  38. package/test/probe.test.ts +195 -0
  39. package/test/providers.test.ts +81 -0
  40. package/test/retrieve.test.ts +137 -0
  41. package/test/windows-spawn.test.ts +93 -0
  42. package/tsconfig.json +17 -0
  43. package/wiki/01-getting-started.md +17 -0
  44. package/wiki/02-guides-and-workflows.md +22 -0
  45. package/wiki/03-architecture-and-internals.md +15 -0
  46. package/wiki/index.md +15 -0
@@ -0,0 +1,58 @@
1
+ import type { EngineOutcome } from "./retrieve.ts";
2
+
3
+ /**
4
+ * Headroom keeps one on-disk CCR store per machine (`~/.headroom/ccr_store.db`), so any live local
5
+ * instance can serve any handle. That removes the need for a second, engine-specific retrieval tool
6
+ * and the naming question that comes with it: the coordinator posts the handle to the proxy directly.
7
+ */
8
+ const RETRIEVE_TIMEOUT_MS = 2_000;
9
+
10
+ type HeadroomBody = { readonly original_content?: unknown; readonly detail?: unknown };
11
+
12
+ function text(value: string): EngineOutcome["content"] {
13
+ return [{ type: "text", text: value }];
14
+ }
15
+
16
+ /**
17
+ * Recover a Headroom handle over its HTTP endpoint. One request per live port, stopping at the
18
+ * first HTTP answer: a 404 is store-wide, so asking another instance cannot change it, and only a
19
+ * transport failure (a dead instance) is worth the next port.
20
+ */
21
+ export async function retrieveFromHeadroom(
22
+ ports: readonly number[],
23
+ handle: string,
24
+ timeoutMs = RETRIEVE_TIMEOUT_MS,
25
+ ): Promise<EngineOutcome> {
26
+ if (ports.length === 0) {
27
+ return {
28
+ content: text(`No Headroom instance is running this session, so ${handle} cannot be recovered.`),
29
+ isError: true,
30
+ };
31
+ }
32
+
33
+ let lastError = "no instance answered";
34
+ for (const port of ports) {
35
+ let response: Response;
36
+ try {
37
+ response = await fetch(`http://127.0.0.1:${port}/v1/retrieve`, {
38
+ method: "POST",
39
+ headers: { "content-type": "application/json" },
40
+ body: JSON.stringify({ hash: handle }),
41
+ signal: AbortSignal.timeout(timeoutMs),
42
+ });
43
+ } catch (error) {
44
+ lastError = `Headroom on port ${port} did not answer: ${(error as Error).message}`;
45
+ continue;
46
+ }
47
+
48
+ const body = (await response.json().catch(() => undefined)) as HeadroomBody | undefined;
49
+ if (response.ok && typeof body?.original_content === "string") {
50
+ return { content: text(body.original_content), isError: false };
51
+ }
52
+
53
+ const detail = typeof body?.detail === "string" ? body.detail : `HTTP ${response.status}`;
54
+ return { content: text(`Headroom could not recover ${handle}: ${detail}`), isError: true };
55
+ }
56
+
57
+ return { content: text(`No Headroom instance answered for ${handle} (${lastError}).`), isError: true };
58
+ }
package/src/index.ts ADDED
@@ -0,0 +1,96 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { onProviderResponse } from "./breaker.ts";
3
+ import { ensureProvider } from "./engine-pool.ts";
4
+ import { createRetrieveTool, executeEngineTool } from "./retrieve.ts";
5
+ import { retrieveFromHeadroom } from "./headroom-http.ts";
6
+ import { closeSession, openSession } from "./session.ts";
7
+ import {
8
+ type DualEngineOptions,
9
+ buildDeps,
10
+ canHideDeclarations,
11
+ registerHeadroomMcp,
12
+ resolvePaths,
13
+ } from "./setup.ts";
14
+ import type { SessionState } from "./state.ts";
15
+ import { buildStatus, formatStatus } from "./status.ts";
16
+
17
+ const NO_HIDE_NOTICE =
18
+ "This pi version cannot hide tool declarations, so the single retrieval tool was not registered. Caveman and Headroom keep their own retrieval tools.";
19
+
20
+ export function createDualEngine(options: DualEngineOptions = {}) {
21
+ return function dualEngine(pi: ExtensionAPI): void {
22
+ const { deps, flush } = buildDeps(options);
23
+ const { agentDir } = resolvePaths(options);
24
+ let session: SessionState | undefined;
25
+ let registered = false;
26
+
27
+ /** Every live Headroom port this session knows about; any of them can serve any handle. */
28
+ const headroomPorts = (): number[] => (session ? [...new Set(session.ports.values())] : []);
29
+
30
+ pi.registerCommand("dual-engine", {
31
+ description: "Report each compression engine separately: owner, port, providers, requests.",
32
+ handler: async (_args, ctx) => {
33
+ const report = session
34
+ ? buildStatus({ engines: session.engines, assignments: session.plans, counters: session.counters })
35
+ : undefined;
36
+ ctx.ui.notify(report ? formatStatus(report) : "dual-engine: no session state yet.", "info");
37
+ },
38
+ });
39
+
40
+ pi.on("session_start", async (_event, ctx) => {
41
+ flush(ctx);
42
+ // Action methods are unavailable during extension load, so the capability probe runs here.
43
+ const capable = canHideDeclarations(pi);
44
+ if (!capable) {
45
+ ctx.ui.notify(NO_HIDE_NOTICE, "error");
46
+ } else if (!registered) {
47
+ registered = true;
48
+ pi.registerTool(
49
+ createRetrieveTool({
50
+ // Caveman answers through its own registered tool; Headroom answers over HTTP, because
51
+ // its CCR store is on disk and shared, and its MCP tool name depends on the MCP backend.
52
+ resolve: (engine, handle, toolCtx) =>
53
+ engine === "headroom"
54
+ ? retrieveFromHeadroom(headroomPorts(), handle)
55
+ : executeEngineTool(toolCtx, engine, handle),
56
+ }),
57
+ );
58
+ }
59
+ session = await openSession(pi, ctx, deps);
60
+ const port = [...session.ports.values()][0];
61
+ if (port !== undefined) registerHeadroomMcp(pi, ctx, port, agentDir);
62
+ });
63
+
64
+ pi.on("model_select", async (event) => {
65
+ if (session) await ensureProvider(pi, session, event.model.provider, deps);
66
+ });
67
+
68
+ pi.on("after_provider_response", async (event, ctx) => {
69
+ if (!session) return;
70
+ const plan = session.plans.find((entry) => entry.provider === ctx.model?.provider);
71
+ if (plan) {
72
+ const counters = session.counters.get(plan.engine) ?? { requests: 0, failures: 0 };
73
+ counters.requests += 1;
74
+ if (event.status >= 400) counters.failures += 1;
75
+ session.counters.set(plan.engine, counters);
76
+ }
77
+ await onProviderResponse(
78
+ {
79
+ tripped: session.tripped,
80
+ directModels: session.directModels,
81
+ notify: (message) => ctx.ui.notify(message, "warning"),
82
+ },
83
+ { event, model: ctx.model, setModel: (model) => pi.setModel(model) },
84
+ );
85
+ });
86
+
87
+ pi.on("session_shutdown", async () => {
88
+ if (session) closeSession(session, deps);
89
+ session = undefined;
90
+ });
91
+ };
92
+ }
93
+
94
+ export type { DualEngineOptions };
95
+
96
+ export default createDualEngine();
@@ -0,0 +1,145 @@
1
+ import {
2
+ CAVEMAN_DEFAULT_PORT,
3
+ isAlive,
4
+ HEADROOM_BASE_PORT,
5
+ lockPath,
6
+ listeningPid,
7
+ portForKey,
8
+ readLock,
9
+ releaseLock,
10
+ removeLock,
11
+ takeLock,
12
+ writeLock,
13
+ } from "./locks.ts";
14
+ import type { ProbeResult, probeCaveman, probeHeadroom } from "./probe.ts";
15
+ import { hostOf } from "./families.ts";
16
+ import type { EngineState, Family, Upstream } from "./types.ts";
17
+
18
+ export type Spawned = { readonly pid: number | undefined };
19
+
20
+ export type LifecycleDeps = {
21
+ /** The extension's own state directory: locks live here and nothing else is written. */
22
+ readonly stateDir: string;
23
+ readonly cavemanHome: string;
24
+ readonly timeoutMs: number;
25
+ readonly spawn: (command: string, args: readonly string[]) => Spawned;
26
+ readonly kill: (pid: number) => void;
27
+ /** Caveman's own teardown, used only for a proxy this session started through its door. */
28
+ readonly cavemanStop?: () => void;
29
+ readonly probeCaveman: typeof probeCaveman;
30
+ readonly probeHeadroom: typeof probeHeadroom;
31
+ readonly now: () => number;
32
+ readonly sleep: (ms: number) => Promise<void>;
33
+ };
34
+
35
+ export type EnsureRequest =
36
+ | { readonly engine: "caveman"; readonly start: boolean }
37
+ | {
38
+ readonly engine: "headroom";
39
+ readonly key: string;
40
+ readonly start: boolean;
41
+ readonly upstreams: readonly { readonly family: Family; readonly url: string }[];
42
+ };
43
+
44
+ function engineKey(request: EnsureRequest): string {
45
+ return request.engine === "caveman" ? "main" : request.key;
46
+ }
47
+
48
+ /** The upstreams an engine instance must serve for this request to count as ours. */
49
+ function expected(request: EnsureRequest): readonly Upstream[] {
50
+ if (request.engine === "caveman") return [];
51
+ return request.upstreams
52
+ .map((upstream) => ({ family: upstream.family, host: hostOf(upstream.url) }))
53
+ .filter((upstream) => upstream.host !== "");
54
+ }
55
+
56
+ function enginePort(request: EnsureRequest): number {
57
+ return request.engine === "caveman" ? CAVEMAN_DEFAULT_PORT : portForKey(HEADROOM_BASE_PORT, request.key);
58
+ }
59
+
60
+ function spawnEngine(request: EnsureRequest, port: number, deps: LifecycleDeps): Spawned {
61
+ if (request.engine === "caveman") return deps.spawn("caveman", ["enable", "pi"]);
62
+ const args = ["proxy", "--port", String(port)];
63
+ const seen = new Set<Family>();
64
+ for (const upstream of request.upstreams) {
65
+ if (seen.has(upstream.family)) continue;
66
+ seen.add(upstream.family);
67
+ args.push(`--${upstream.family}-api-url`, upstream.url);
68
+ }
69
+ return deps.spawn("headroom", args);
70
+ }
71
+
72
+ async function waitForVerified(
73
+ request: EnsureRequest,
74
+ port: number,
75
+ deps: LifecycleDeps,
76
+ ): Promise<EngineState | undefined> {
77
+ const deadline = deps.now() + deps.timeoutMs;
78
+ for (;;) {
79
+ const result =
80
+ request.engine === "caveman"
81
+ ? await deps.probeCaveman({ port, home: deps.cavemanHome, timeoutMs: 2_000, owned: true })
82
+ : await deps.probeHeadroom({
83
+ port,
84
+ timeoutMs: 2_000,
85
+ owned: true,
86
+ expect: expected(request),
87
+ });
88
+ if (result.ok) return result.state;
89
+ if (deps.now() >= deadline) return undefined;
90
+ await deps.sleep(250);
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Verify, adopt, then start. An adopted engine outlives the session; a stranger on the port is
96
+ * refused; a child that fails verification is stopped again.
97
+ */
98
+ export async function ensureEngine(request: EnsureRequest, deps: LifecycleDeps): Promise<ProbeResult> {
99
+ const port = enginePort(request);
100
+ const adopted =
101
+ request.engine === "caveman"
102
+ ? await deps.probeCaveman({ port, home: deps.cavemanHome, timeoutMs: 2_000, owned: false })
103
+ : await deps.probeHeadroom({ port, timeoutMs: 2_000, owned: false, expect: expected(request) });
104
+ if (adopted.ok) return adopted;
105
+ // Something else owns the port: binding it again cannot succeed, and routing through it would be worse.
106
+ if (adopted.occupied) return adopted;
107
+ if (!request.start) return adopted;
108
+
109
+ const path = lockPath(deps.stateDir, request.engine, engineKey(request));
110
+ const recorded = readLock(path);
111
+ if (!takeLock(path, port, deps.now)) return { ok: false, reason: `another session holds ${path}` };
112
+ const child = spawnEngine(request, port, deps);
113
+ const state = await waitForVerified(request, port, deps);
114
+ if (state) {
115
+ // Record the process that will still be listening later, not the launcher that may exit.
116
+ const pid = request.engine === "headroom" ? (listeningPid(port) ?? child.pid) : child.pid;
117
+ writeLock(path, { pid: pid ?? -1, port, startedAt: deps.now() });
118
+ const tagged =
119
+ request.engine === "caveman"
120
+ ? { ...state, shutdown: "caveman" as const, key: engineKey(request) }
121
+ : { ...state, key: engineKey(request) };
122
+ return { ok: true, state: tagged };
123
+ }
124
+ if (child.pid !== undefined) deps.kill(child.pid);
125
+ if (recorded?.pid === undefined) releaseLock(path);
126
+ return { ok: false, reason: `${request.engine} did not verify within ${deps.timeoutMs} ms` };
127
+ }
128
+
129
+ /** Stop only the pid this session started for an engine it owns. */
130
+ /** Stop only what this session started, and only through the door that created it. */
131
+ export function stopOwned(
132
+ state: EngineState,
133
+ deps: Pick<LifecycleDeps, "stateDir" | "kill" | "cavemanStop">,
134
+ ): void {
135
+ if (!state.owned) return;
136
+ const path = lockPath(
137
+ deps.stateDir,
138
+ state.engine,
139
+ state.key ?? (state.engine === "caveman" ? "main" : String(state.port)),
140
+ );
141
+ const lock = readLock(path);
142
+ if (state.shutdown === "caveman") deps.cavemanStop?.();
143
+ else if (lock && lock.pid > 0 && isAlive(lock.pid)) deps.kill(lock.pid);
144
+ removeLock(path);
145
+ }
package/src/locks.ts ADDED
@@ -0,0 +1,93 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { createServer } from "node:net";
3
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+
6
+ export type Lock = { readonly pid: number; readonly port: number; readonly startedAt: number };
7
+
8
+ export const CAVEMAN_DEFAULT_PORT = 8787;
9
+ export const HEADROOM_BASE_PORT = 8788;
10
+
11
+ export function isAlive(pid: number): boolean {
12
+ try {
13
+ process.kill(pid, 0);
14
+ return true;
15
+ } catch {
16
+ return false;
17
+ }
18
+ }
19
+
20
+ export function readLock(path: string): Lock | undefined {
21
+ try {
22
+ const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<Lock>;
23
+ if (typeof parsed.pid !== "number" || typeof parsed.port !== "number") return undefined;
24
+ return { pid: parsed.pid, port: parsed.port, startedAt: parsed.startedAt ?? 0 };
25
+ } catch {
26
+ return undefined;
27
+ }
28
+ }
29
+
30
+ export function writeLock(path: string, lock: Lock): void {
31
+ mkdirSync(join(path, ".."), { recursive: true });
32
+ const temp = `${path}.${process.pid}.tmp`;
33
+ writeFileSync(temp, JSON.stringify(lock), "utf8");
34
+ renameSync(temp, path);
35
+ }
36
+
37
+ /** Write the lock when free, or when the pid it names is dead. Never when that process is alive. */
38
+ export function takeLock(path: string, port: number, now: () => number): boolean {
39
+ const existing = readLock(path);
40
+ if (existing && existing.pid !== process.pid && isAlive(existing.pid)) return false;
41
+ writeLock(path, { pid: process.pid, port, startedAt: now() });
42
+ return true;
43
+ }
44
+
45
+ export function releaseLock(path: string): void {
46
+ const existing = readLock(path);
47
+ if (existing && existing.pid !== process.pid) return;
48
+ rmSync(path, { force: true });
49
+ }
50
+
51
+ /** Remove a record this session wrote, whoever started the process it names. */
52
+ export function removeLock(path: string): void {
53
+ rmSync(path, { force: true });
54
+ }
55
+
56
+ export function lockPath(stateDir: string, engine: string, key: string): string {
57
+ return join(stateDir, "locks", `${engine}-${key}.json`);
58
+ }
59
+
60
+ /**
61
+ * Deterministic per-key port so two sessions agree on where an engine for that key should be.
62
+ * The slot space is 100 wide: a 20-slot hash collided for two common provider names, and a
63
+ * collision costs that provider its compression for the session (it degrades to direct).
64
+ */
65
+ export function portForKey(base: number, key: string): number {
66
+ let hash = 0;
67
+ for (const char of key) hash = (hash * 31 + char.charCodeAt(0)) % 100;
68
+ return base + hash;
69
+ }
70
+
71
+ /** Real port check: binding a loopback listener fails when something already owns the port. */
72
+ export function portIsFree(port: number): Promise<boolean> {
73
+ return new Promise((resolve) => {
74
+ const server = createServer();
75
+ server.once("error", () => resolve(false));
76
+ server.once("listening", () => server.close(() => resolve(true)));
77
+ server.listen(port, "127.0.0.1");
78
+ });
79
+ }
80
+
81
+ /**
82
+ * The pid actually listening on a loopback port. A launcher can fork a worker into its own session
83
+ * (headroom does), so the spawned pid is not the process to stop later.
84
+ */
85
+ export function listeningPid(port: number): number | undefined {
86
+ try {
87
+ const output = execFileSync("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
88
+ const pid = Number(output.trim().split("\n")[0]);
89
+ return Number.isInteger(pid) && pid > 0 ? pid : undefined;
90
+ } catch {
91
+ return undefined;
92
+ }
93
+ }
package/src/probe.ts ADDED
@@ -0,0 +1,154 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { cavemanFamilyOf, hostOf } from "./families.ts";
4
+ import type { EngineState, Family, Upstream } from "./types.ts";
5
+
6
+ export type ProbeResult =
7
+ | { readonly ok: true; readonly state: EngineState }
8
+ | {
9
+ readonly ok: false;
10
+ readonly reason: string;
11
+ /** True when something answered on the port but its identity is not the one we need. */
12
+ readonly occupied?: boolean;
13
+ };
14
+
15
+ type Json = Record<string, unknown>;
16
+
17
+ const HEADROOM_SERVICE = "headroom-proxy";
18
+ const CAVEMAN_INSTANCE_HEADER = "x-caveman-instance";
19
+
20
+ const FAMILY_CONFIG_KEYS: readonly (readonly [string, Family])[] = [
21
+ ["anthropic_api_url", "anthropic"],
22
+ ["openai_api_url", "openai"],
23
+ ["gemini_api_url", "gemini"],
24
+ ];
25
+
26
+ /** Read a JSON object, or undefined when the file is absent or unreadable. */
27
+ export function readJson(path: string): Json | undefined {
28
+ try {
29
+ const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
30
+ return parsed && typeof parsed === "object" ? (parsed as Json) : undefined;
31
+ } catch {
32
+ return undefined;
33
+ }
34
+ }
35
+
36
+ async function getJson(url: string, timeoutMs: number): Promise<Json> {
37
+ const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
38
+ if (!response.ok) throw new Error(`${url} answered ${response.status}`);
39
+ return (await response.json()) as Json;
40
+ }
41
+
42
+ function upstreamsFromTable(table: unknown, compat: boolean): Upstream[] {
43
+ if (!table || typeof table !== "object") return [];
44
+ const out: Upstream[] = [];
45
+ for (const [key, value] of Object.entries(table as Json)) {
46
+ if (typeof value !== "string") continue;
47
+ const family = cavemanFamilyOf(key, compat);
48
+ const host = hostOf(value);
49
+ if (family && host) out.push({ family, host });
50
+ }
51
+ return out;
52
+ }
53
+
54
+ /** Where a Caveman proxy keeps its run state for one port. */
55
+ export function cavemanStatePath(home: string, port: number): string {
56
+ return join(home, "run", `${port}.json`);
57
+ }
58
+
59
+ /**
60
+ * Readiness is identity, not a listening socket: the run-state file must name this port, the
61
+ * health listener must echo its instance token, and recovery must be served over MCP.
62
+ */
63
+ export async function probeCaveman(options: {
64
+ port: number;
65
+ home: string;
66
+ timeoutMs: number;
67
+ owned: boolean;
68
+ }): Promise<ProbeResult> {
69
+ const statePath = cavemanStatePath(options.home, options.port);
70
+ const recorded = readJson(statePath);
71
+ if (!recorded) return { ok: false, reason: `no Caveman run state at ${statePath}` };
72
+ if (recorded.recovery_via_mcp !== true)
73
+ return { ok: false, reason: "Caveman run state reports recovery_via_mcp false" };
74
+
75
+ let headers: Headers;
76
+ try {
77
+ const response = await fetch(`http://127.0.0.1:${options.port}/health/live`, {
78
+ signal: AbortSignal.timeout(options.timeoutMs),
79
+ });
80
+ if (!response.ok) return { ok: false, reason: `Caveman health answered ${response.status}` };
81
+ headers = response.headers;
82
+ } catch (error) {
83
+ return { ok: false, reason: `Caveman health unreachable: ${(error as Error).message}` };
84
+ }
85
+
86
+ const token = headers.get(CAVEMAN_INSTANCE_HEADER);
87
+ if (!token || token !== recorded.instance_token) {
88
+ return {
89
+ ok: false,
90
+ occupied: true,
91
+ reason: `port ${options.port} answers, but its instance token does not match the Caveman run state`,
92
+ };
93
+ }
94
+
95
+ const upstreams = [
96
+ ...upstreamsFromTable(recorded.provider_upstreams, false),
97
+ ...upstreamsFromTable(recorded.compat_upstreams, true),
98
+ ];
99
+ return { ok: true, state: { engine: "caveman", port: options.port, upstreams, owned: options.owned } };
100
+ }
101
+
102
+ /**
103
+ * Headroom proves itself with `/livez` plus the loopback `/health` config block, which names the
104
+ * upstream each family reaches. A bare listener is never readiness.
105
+ */
106
+ export async function probeHeadroom(options: {
107
+ port: number;
108
+ timeoutMs: number;
109
+ owned: boolean;
110
+ /** Upstreams the caller needs. A proxy serving different ones is a foreign instance, not readiness. */
111
+ expect?: readonly Upstream[];
112
+ }): Promise<ProbeResult> {
113
+ const base = `http://127.0.0.1:${options.port}`;
114
+ try {
115
+ const live = await getJson(`${base}/livez`, options.timeoutMs);
116
+ if (live.service !== HEADROOM_SERVICE) {
117
+ return {
118
+ ok: false,
119
+ occupied: true,
120
+ reason: `port ${options.port} answers but is not a Headroom proxy`,
121
+ };
122
+ }
123
+ const health = await getJson(`${base}/health`, options.timeoutMs);
124
+ if (health.service !== HEADROOM_SERVICE) {
125
+ return { ok: false, reason: `port ${options.port} is not a Headroom proxy` };
126
+ }
127
+ const config = (health.config ?? {}) as Json;
128
+ const upstreams: Upstream[] = [];
129
+ for (const [key, family] of FAMILY_CONFIG_KEYS) {
130
+ const host = hostOf(typeof config[key] === "string" ? (config[key] as string) : undefined);
131
+ if (host) upstreams.push({ family, host });
132
+ }
133
+ if (upstreams.length === 0) {
134
+ return { ok: false, occupied: true, reason: `Headroom on port ${options.port} names no upstream` };
135
+ }
136
+ const served = (upstream: Upstream): string => `${upstream.family}@${upstream.host}`;
137
+ const missing = (options.expect ?? []).filter(
138
+ (expected) =>
139
+ !upstreams.some((upstream) => upstream.family === expected.family && upstream.host === expected.host),
140
+ );
141
+ if (missing.length > 0) {
142
+ return {
143
+ ok: false,
144
+ occupied: true,
145
+ reason: `Headroom on port ${options.port} serves ${upstreams.map(served).join(", ")}; expected ${missing
146
+ .map(served)
147
+ .join(", ")}`,
148
+ };
149
+ }
150
+ return { ok: true, state: { engine: "headroom", port: options.port, upstreams, owned: options.owned } };
151
+ } catch (error) {
152
+ return { ok: false, reason: `Headroom unreachable: ${(error as Error).message}` };
153
+ }
154
+ }
@@ -0,0 +1,78 @@
1
+ import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
2
+ import type { AssignmentPlan, ProviderGroup } from "./assignment.ts";
3
+ import { familyOf } from "./families.ts";
4
+ import type { EngineId } from "./types.ts";
5
+
6
+ export type ProviderApi = { registerProvider(name: string, config: ProviderConfig): void };
7
+
8
+ /** Non-chat models of a provider, carried through untouched so a registration never drops them. */
9
+ export type ModelExtras = ReadonlyMap<string, readonly Record<string, unknown>[]>;
10
+
11
+ /**
12
+ * One provider registration per plan: every carried model points at the engine's proxy, and every
13
+ * family the engine cannot carry keeps its direct base URL.
14
+ */
15
+ export function planProviderConfig(
16
+ plan: AssignmentPlan,
17
+ group: ProviderGroup,
18
+ proxyUrl: string,
19
+ extras: ModelExtras = new Map(),
20
+ ): ProviderConfig {
21
+ const chat = group.models.map((model) => {
22
+ const family = familyOf(model.api);
23
+ const carried = family !== undefined && plan.families.includes(family);
24
+ return {
25
+ id: model.id,
26
+ name: model.name,
27
+ api: model.api,
28
+ reasoning: model.reasoning,
29
+ input: model.input,
30
+ cost: model.cost,
31
+ contextWindow: model.contextWindow,
32
+ maxTokens: model.maxTokens,
33
+ baseUrl: carried ? proxyUrl : model.baseUrl,
34
+ };
35
+ });
36
+ const rest = extras.get(plan.provider) ?? [];
37
+ return { baseUrl: proxyUrl, models: [...chat, ...rest] } as ProviderConfig;
38
+ }
39
+
40
+ export type Registration = {
41
+ readonly provider: string;
42
+ readonly engine: EngineId;
43
+ readonly config: ProviderConfig;
44
+ };
45
+
46
+ export function planRegistrations(
47
+ plans: readonly AssignmentPlan[],
48
+ groups: readonly ProviderGroup[],
49
+ ports: ReadonlyMap<string, number>,
50
+ extras: ModelExtras = new Map(),
51
+ ): Registration[] {
52
+ const registrations: Registration[] = [];
53
+ for (const plan of plans) {
54
+ const port = ports.get(plan.provider);
55
+ const group = groups.find((candidate) => candidate.provider === plan.provider);
56
+ if (port === undefined || !group) continue;
57
+ const config = planProviderConfig(plan, group, `http://127.0.0.1:${port}`, extras);
58
+ registrations.push({ provider: plan.provider, engine: plan.engine, config });
59
+ }
60
+ return registrations;
61
+ }
62
+
63
+ /** Register every plan; a failing registration is reported and never aborts the session. */
64
+ export function registerAll(
65
+ api: ProviderApi,
66
+ registrations: readonly Registration[],
67
+ onError?: (message: string) => void,
68
+ ): void {
69
+ for (const registration of registrations) {
70
+ try {
71
+ api.registerProvider(registration.provider, registration.config);
72
+ } catch (error) {
73
+ onError?.(
74
+ `Could not register "${registration.provider}": ${(error as Error).message}. Its models run direct.`,
75
+ );
76
+ }
77
+ }
78
+ }
@@ -0,0 +1,65 @@
1
+ import type { AgentToolResult, ExtensionToolContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
2
+ import { Type } from "typebox";
3
+ import { RETRIEVAL_TOOL_CANDIDATES, resolveRetrievalTool } from "./families.ts";
4
+ import { dispatchHandle } from "./handles.ts";
5
+ import type { EngineId } from "./types.ts";
6
+
7
+ export type EngineOutcome = {
8
+ readonly content: AgentToolResult<unknown>["content"];
9
+ readonly isError: boolean;
10
+ };
11
+
12
+ export type RetrieveDeps = {
13
+ /** Calls the engine's own retrieval tool. Never rejects for tool failures. */
14
+ readonly resolve: (engine: EngineId, handle: string, ctx: ExtensionToolContext) => Promise<EngineOutcome>;
15
+ };
16
+
17
+ const parameters = Type.Object({
18
+ handle: Type.String({
19
+ description: "Recovery handle from a compression marker: ccr_... or 12-24 lowercase hex.",
20
+ }),
21
+ });
22
+
23
+ function text(value: string): AgentToolResult<unknown> {
24
+ return { content: [{ type: "text", text: value }], details: undefined };
25
+ }
26
+
27
+ /**
28
+ * One model-visible retrieval tool. It owns no store: it dispatches by handle shape and returns
29
+ * the owning engine's result unchanged.
30
+ */
31
+ export function createRetrieveTool(deps: RetrieveDeps): ToolDefinition<typeof parameters> {
32
+ return {
33
+ name: "retrieve",
34
+ label: "Retrieve",
35
+ description:
36
+ "Restore an original compressed by Caveman or Headroom. Pass the recovery handle exactly as it appeared in the marker.",
37
+ parameters,
38
+ prepareLoadout: (loadout) => ({
39
+ hiddenDeclarations: Object.values(RETRIEVAL_TOOL_CANDIDATES)
40
+ .flat()
41
+ .filter((name) => loadout.registered.some((tool) => tool.name === name)),
42
+ }),
43
+ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
44
+ const target = dispatchHandle(params.handle);
45
+ if ("error" in target) {
46
+ const failure = text(target.error);
47
+ return { content: failure.content, details: undefined, isError: true };
48
+ }
49
+ const outcome = await deps.resolve(target.engine, target.handle, ctx);
50
+ return { content: outcome.content, details: undefined, isError: outcome.isError };
51
+ },
52
+ };
53
+ }
54
+
55
+ /** Run the engine's own tool through the same validation, hooks and permission checks. */
56
+ export async function executeEngineTool(
57
+ ctx: ExtensionToolContext,
58
+ engine: EngineId,
59
+ handle: string,
60
+ ): Promise<EngineOutcome> {
61
+ const callable = Array.isArray(ctx.tools) ? ctx.tools : [];
62
+ // Caveman's own retrieval tool takes `recovery_handle`; its schema rejects any other spelling.
63
+ const outcome = await ctx.executeTool(resolveRetrievalTool(engine, callable), { recovery_handle: handle });
64
+ return { content: outcome.result.content, isError: outcome.isError };
65
+ }