pi-dual-engine 0.0.0-stage → 0.2.1
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.
- package/README.md +103 -2
- package/biome.json +22 -0
- package/dist/index.js +1089 -0
- package/package.json +27 -4
- package/scripts/smoke.ts +141 -0
- package/src/assignment.ts +176 -0
- package/src/breaker.ts +33 -0
- package/src/config.ts +55 -0
- package/src/engine-pool.ts +163 -0
- package/src/families.ts +58 -0
- package/src/handles.ts +31 -0
- package/src/headroom-http.ts +58 -0
- package/src/index.ts +96 -0
- package/src/lifecycle.ts +145 -0
- package/src/locks.ts +93 -0
- package/src/probe.ts +154 -0
- package/src/providers.ts +71 -0
- package/src/retrieve.ts +65 -0
- package/src/session.ts +150 -0
- package/src/setup.ts +230 -0
- package/src/state.ts +49 -0
- package/src/status.ts +64 -0
- package/src/types.ts +47 -0
- package/test/assignment.test.ts +193 -0
- package/test/boot.ts +84 -0
- package/test/breaker.test.ts +92 -0
- package/test/coldstart.test.ts +133 -0
- package/test/defaults.test.ts +16 -0
- package/test/degradation.test.ts +69 -0
- package/test/factory.test.ts +158 -0
- package/test/fakes.ts +155 -0
- package/test/handles.test.ts +37 -0
- package/test/harness.ts +39 -0
- package/test/headroom-http.test.ts +99 -0
- package/test/lifecycle.test.ts +75 -0
- package/test/optin.test.ts +41 -0
- package/test/ownership.test.ts +160 -0
- package/test/probe.test.ts +195 -0
- package/test/providers.test.ts +156 -0
- package/test/retrieve.test.ts +137 -0
- package/test/windows-spawn.test.ts +93 -0
- package/tsconfig.json +17 -0
- package/wiki/01-getting-started.md +17 -0
- package/wiki/02-guides-and-workflows.md +22 -0
- package/wiki/03-architecture-and-internals.md +15 -0
- package/wiki/index.md +15 -0
package/package.json
CHANGED
|
@@ -1,6 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-dual-engine",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "One-owner-per-byte coordination between the Caveman harness engine and the Headroom wire engine (dual-engine).",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"pi": {
|
|
7
|
+
"extensions": [
|
|
8
|
+
"./dist/index.js"
|
|
9
|
+
]
|
|
10
|
+
},
|
|
11
|
+
"scripts": {
|
|
12
|
+
"build": "bun build src/index.ts --target=node --format=esm --outdir dist --external @earendil-works/pi-coding-agent --external @earendil-works/pi-ai --external typebox",
|
|
13
|
+
"format": "biome format src test scripts",
|
|
14
|
+
"lint": "biome lint src test scripts && tsc --noEmit",
|
|
15
|
+
"test": "bun test",
|
|
16
|
+
"check": "bun run format && bun run lint && bun run test && bun run build"
|
|
17
|
+
},
|
|
18
|
+
"peerDependencies": {
|
|
19
|
+
"@earendil-works/pi-coding-agent": "^1.4.0",
|
|
20
|
+
"typebox": "^1.3.0"
|
|
21
|
+
},
|
|
22
|
+
"devDependencies": {
|
|
23
|
+
"@biomejs/biome": "2.3.4",
|
|
24
|
+
"@earendil-works/pi-coding-agent": "1.4.0",
|
|
25
|
+
"@types/bun": "^1.4.4",
|
|
26
|
+
"@types/node": "22.19.1",
|
|
27
|
+
"typescript": "5.9.3"
|
|
28
|
+
}
|
|
29
|
+
}
|
package/scripts/smoke.ts
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Headless smoke test: start pi with the built extension in a scratch directory, send one prompt
|
|
3
|
+
* through a stub OpenAI-compatible provider, and assert the request declares exactly one retrieval
|
|
4
|
+
* tool. Exit code 0 means the extension loaded and its loadout took effect.
|
|
5
|
+
*/
|
|
6
|
+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
7
|
+
import { tmpdir } from "node:os";
|
|
8
|
+
import { join } from "node:path";
|
|
9
|
+
|
|
10
|
+
const BUILT = join(import.meta.dir, "..", "dist", "index.js");
|
|
11
|
+
const dir = mkdtempSync(join(tmpdir(), "dual-engine-smoke-"));
|
|
12
|
+
const agentDir = join(dir, "agent");
|
|
13
|
+
mkdirSync(agentDir, { recursive: true });
|
|
14
|
+
|
|
15
|
+
const bodies: Record<string, unknown>[] = [];
|
|
16
|
+
const server = Bun.serve({
|
|
17
|
+
port: 0,
|
|
18
|
+
hostname: "127.0.0.1",
|
|
19
|
+
async fetch(request) {
|
|
20
|
+
if (!request.url.includes("/chat/completions")) return new Response("not found", { status: 404 });
|
|
21
|
+
const body = (await request.json()) as Record<string, unknown>;
|
|
22
|
+
bodies.push(body);
|
|
23
|
+
const model = String(body.model ?? "stub-model");
|
|
24
|
+
const chunk = (delta: Record<string, unknown>, finish: string | null) =>
|
|
25
|
+
`data: ${JSON.stringify({
|
|
26
|
+
id: "chatcmpl-smoke",
|
|
27
|
+
object: "chat.completion.chunk",
|
|
28
|
+
created: 1,
|
|
29
|
+
model,
|
|
30
|
+
choices: [{ index: 0, delta, finish_reason: finish }],
|
|
31
|
+
})}\n\n`;
|
|
32
|
+
const stream = new ReadableStream<Uint8Array>({
|
|
33
|
+
start(controller) {
|
|
34
|
+
const encoder = new TextEncoder();
|
|
35
|
+
controller.enqueue(encoder.encode(chunk({ role: "assistant", content: "ok" }, null)));
|
|
36
|
+
controller.enqueue(encoder.encode(chunk({}, "stop")));
|
|
37
|
+
controller.enqueue(encoder.encode("data: [DONE]\n\n"));
|
|
38
|
+
controller.close();
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
return new Response(stream, { headers: { "content-type": "text/event-stream" } });
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
function writeModels(port: number): void {
|
|
46
|
+
writeFileSync(
|
|
47
|
+
join(agentDir, "models.json"),
|
|
48
|
+
JSON.stringify({
|
|
49
|
+
providers: {
|
|
50
|
+
stub: {
|
|
51
|
+
baseUrl: `http://127.0.0.1:${port}/v1`,
|
|
52
|
+
api: "openai-completions",
|
|
53
|
+
apiKey: "stub-key",
|
|
54
|
+
models: [
|
|
55
|
+
{
|
|
56
|
+
id: "stub-model",
|
|
57
|
+
name: "Stub Model",
|
|
58
|
+
input: ["text"],
|
|
59
|
+
reasoning: false,
|
|
60
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
61
|
+
contextWindow: 8000,
|
|
62
|
+
maxTokens: 512,
|
|
63
|
+
},
|
|
64
|
+
],
|
|
65
|
+
},
|
|
66
|
+
},
|
|
67
|
+
}),
|
|
68
|
+
"utf8",
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function toolNames(body: Record<string, unknown> | undefined): string[] {
|
|
73
|
+
const tools = (body?.tools ?? []) as { function?: { name?: string }; name?: string }[];
|
|
74
|
+
return tools.map((tool) => tool.function?.name ?? tool.name ?? "?");
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
async function main(): Promise<number> {
|
|
78
|
+
const port = server.port;
|
|
79
|
+
if (port === undefined) {
|
|
80
|
+
console.error("smoke: the stub provider server did not receive a port");
|
|
81
|
+
return 1;
|
|
82
|
+
}
|
|
83
|
+
writeModels(port);
|
|
84
|
+
const proc = Bun.spawn({
|
|
85
|
+
cmd: [
|
|
86
|
+
"pi",
|
|
87
|
+
"--print",
|
|
88
|
+
"say hi",
|
|
89
|
+
"--provider",
|
|
90
|
+
"stub",
|
|
91
|
+
"--model",
|
|
92
|
+
"stub-model",
|
|
93
|
+
"--extension",
|
|
94
|
+
BUILT,
|
|
95
|
+
"--no-session",
|
|
96
|
+
"--no-mcp",
|
|
97
|
+
"--no-skills",
|
|
98
|
+
"--no-context-files",
|
|
99
|
+
"--approve",
|
|
100
|
+
],
|
|
101
|
+
cwd: dir,
|
|
102
|
+
env: { ...process.env, PI_CODING_AGENT_DIR: agentDir, DUAL_ENGINE_HOME: join(dir, "state") },
|
|
103
|
+
stdout: "pipe",
|
|
104
|
+
stderr: "pipe",
|
|
105
|
+
});
|
|
106
|
+
const timer = setTimeout(() => proc.kill(), 120_000);
|
|
107
|
+
const [stdout, stderr] = await Promise.all([
|
|
108
|
+
new Response(proc.stdout).text(),
|
|
109
|
+
new Response(proc.stderr).text(),
|
|
110
|
+
]);
|
|
111
|
+
clearTimeout(timer);
|
|
112
|
+
const code = await proc.exited;
|
|
113
|
+
if (code !== 0) {
|
|
114
|
+
console.error(`smoke: pi exited ${code}\n${stderr.slice(-1500)}`);
|
|
115
|
+
return 1;
|
|
116
|
+
}
|
|
117
|
+
if (bodies.length !== 1) {
|
|
118
|
+
console.error(`smoke: expected one provider request, saw ${bodies.length}`);
|
|
119
|
+
return 1;
|
|
120
|
+
}
|
|
121
|
+
const names = toolNames(bodies[0]);
|
|
122
|
+
const retrieval = names.filter((name) => name.toLowerCase().includes("retrieve"));
|
|
123
|
+
if (retrieval.length !== 1 || retrieval[0] !== "retrieve") {
|
|
124
|
+
console.error(
|
|
125
|
+
`smoke: expected exactly one retrieval tool named retrieve, saw ${JSON.stringify(retrieval)}`,
|
|
126
|
+
);
|
|
127
|
+
return 1;
|
|
128
|
+
}
|
|
129
|
+
console.log(
|
|
130
|
+
`smoke: ok (${names.length} tools, retrieval=${retrieval[0]}, output=${stdout.trim().slice(0, 40)})`,
|
|
131
|
+
);
|
|
132
|
+
return 0;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
try {
|
|
136
|
+
const code = await main();
|
|
137
|
+
process.exitCode = code;
|
|
138
|
+
} finally {
|
|
139
|
+
server.stop(true);
|
|
140
|
+
rmSync(dir, { recursive: true, force: true });
|
|
141
|
+
}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import type { EngineId, EngineState, Family, ProviderFamily } from "./types.ts";
|
|
2
|
+
|
|
3
|
+
export type ProviderModel = {
|
|
4
|
+
readonly id: string;
|
|
5
|
+
readonly name: string;
|
|
6
|
+
readonly api: string;
|
|
7
|
+
readonly baseUrl?: string;
|
|
8
|
+
readonly reasoning: boolean;
|
|
9
|
+
readonly input: readonly ("text" | "image")[];
|
|
10
|
+
readonly cost: {
|
|
11
|
+
readonly input: number;
|
|
12
|
+
readonly output: number;
|
|
13
|
+
readonly cacheRead: number;
|
|
14
|
+
readonly cacheWrite: number;
|
|
15
|
+
};
|
|
16
|
+
readonly contextWindow: number;
|
|
17
|
+
readonly maxTokens: number;
|
|
18
|
+
readonly thinkingLevelMap?: Record<string, string | null>;
|
|
19
|
+
readonly compat?: unknown;
|
|
20
|
+
readonly inputLimits?: unknown;
|
|
21
|
+
};
|
|
22
|
+
export type ProviderGroup = { readonly provider: string; readonly models: readonly ProviderModel[] };
|
|
23
|
+
|
|
24
|
+
/** Family preference is policy about wire families, never about provider names. */
|
|
25
|
+
/** The engine that should carry a family when it is available, in preference order. */
|
|
26
|
+
export const PREFERENCE: Record<Family, readonly EngineId[]> = {
|
|
27
|
+
openai: ["headroom", "caveman"],
|
|
28
|
+
anthropic: ["headroom", "caveman"],
|
|
29
|
+
gemini: ["caveman", "headroom"],
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export type AssignmentPlan = {
|
|
33
|
+
readonly provider: string;
|
|
34
|
+
readonly engine: EngineId;
|
|
35
|
+
readonly families: readonly Family[];
|
|
36
|
+
readonly direct: readonly Family[];
|
|
37
|
+
/** One upstream per family, in spawn order; duplicates of a family are not carried. */
|
|
38
|
+
readonly upstreams: readonly { readonly family: Family; readonly url: string }[];
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
export type DeriveResult = {
|
|
42
|
+
readonly plans: readonly AssignmentPlan[];
|
|
43
|
+
readonly notices: readonly string[];
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
function familiesOf(
|
|
47
|
+
group: ProviderGroup,
|
|
48
|
+
familyOf: (api: string) => Family | undefined,
|
|
49
|
+
hostOf: (url: string | undefined) => string,
|
|
50
|
+
) {
|
|
51
|
+
const seen = new Map<string, ProviderFamily & { url: string }>();
|
|
52
|
+
for (const model of group.models) {
|
|
53
|
+
const family = familyOf(model.api);
|
|
54
|
+
const host = hostOf(model.baseUrl);
|
|
55
|
+
if (!family || !host) continue;
|
|
56
|
+
seen.set(`${family}|${host}`, { family, host, url: model.baseUrl ?? "" });
|
|
57
|
+
}
|
|
58
|
+
return [...seen.values()];
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function proves(engine: EngineState, target: ProviderFamily): boolean {
|
|
62
|
+
return engine.upstreams.some(
|
|
63
|
+
(upstream) => upstream.family === target.family && upstream.host === target.host,
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function chooseEngine(
|
|
68
|
+
engines: readonly EngineState[],
|
|
69
|
+
targets: readonly ProviderFamily[],
|
|
70
|
+
): EngineId | undefined {
|
|
71
|
+
let best: { engine: EngineId; covered: number; rank: number } | undefined;
|
|
72
|
+
for (const engine of engines) {
|
|
73
|
+
const covered = targets.filter((target) => proves(engine, target)).length;
|
|
74
|
+
if (covered === 0) continue;
|
|
75
|
+
const rank = targets.reduce((sum, target) => {
|
|
76
|
+
const order = PREFERENCE[target.family];
|
|
77
|
+
const index = order.indexOf(engine.engine);
|
|
78
|
+
return sum + (index === -1 ? order.length : index);
|
|
79
|
+
}, 0);
|
|
80
|
+
const candidate = { engine: engine.engine, covered, rank };
|
|
81
|
+
if (
|
|
82
|
+
!best ||
|
|
83
|
+
candidate.covered > best.covered ||
|
|
84
|
+
(candidate.covered === best.covered && candidate.rank < best.rank)
|
|
85
|
+
) {
|
|
86
|
+
best = candidate;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return best?.engine;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function resolveOverrides(overrides: readonly { readonly provider: string; readonly engine: string }[]): {
|
|
93
|
+
valid: Map<string, EngineId>;
|
|
94
|
+
notices: string[];
|
|
95
|
+
} {
|
|
96
|
+
const notices: string[] = [];
|
|
97
|
+
const valid = new Map<string, EngineId>();
|
|
98
|
+
const counts = new Map<string, number>();
|
|
99
|
+
for (const entry of overrides) {
|
|
100
|
+
counts.set(entry.provider, (counts.get(entry.provider) ?? 0) + 1);
|
|
101
|
+
}
|
|
102
|
+
for (const entry of overrides) {
|
|
103
|
+
if ((counts.get(entry.provider) ?? 0) > 1) {
|
|
104
|
+
if (
|
|
105
|
+
!notices.some((notice) => notice.includes(`Conflicting assignments for provider "${entry.provider}"`))
|
|
106
|
+
) {
|
|
107
|
+
notices.push(`Conflicting assignments for provider "${entry.provider}": the derived engine applies.`);
|
|
108
|
+
}
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (entry.engine !== "caveman" && entry.engine !== "headroom") {
|
|
112
|
+
notices.push(
|
|
113
|
+
`Unknown engine "${entry.engine}" for provider "${entry.provider}": the derived engine applies.`,
|
|
114
|
+
);
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
valid.set(entry.provider, entry.engine);
|
|
118
|
+
}
|
|
119
|
+
return { valid, notices };
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Derive one engine per provider from model metadata and what each engine proved. No provider or
|
|
124
|
+
* model name decides routing; anything unproven runs direct with one notice naming the family.
|
|
125
|
+
*/
|
|
126
|
+
export function deriveAssignments(
|
|
127
|
+
groups: readonly ProviderGroup[],
|
|
128
|
+
engines: readonly EngineState[],
|
|
129
|
+
overrides: readonly { readonly provider: string; readonly engine: string }[],
|
|
130
|
+
helpers: { familyOf: (api: string) => Family | undefined; hostOf: (url: string | undefined) => string },
|
|
131
|
+
): DeriveResult {
|
|
132
|
+
const { valid, notices: overrideNotices } = resolveOverrides(overrides);
|
|
133
|
+
const notices = [...overrideNotices];
|
|
134
|
+
const plans: AssignmentPlan[] = [];
|
|
135
|
+
|
|
136
|
+
for (const group of groups) {
|
|
137
|
+
const targets = familiesOf(group, helpers.familyOf, helpers.hostOf);
|
|
138
|
+
if (targets.length === 0) {
|
|
139
|
+
notices.push(`Provider "${group.provider}" serves no wire family an engine can carry: running direct.`);
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
const engine = valid.get(group.provider) ?? chooseEngine(engines, targets);
|
|
143
|
+
if (!engine) {
|
|
144
|
+
notices.push(
|
|
145
|
+
`Provider "${group.provider}" serves ${targets.map((t) => t.family).join(", ")} with no engine that can carry it: running direct.`,
|
|
146
|
+
);
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
const state = engines.find((candidate) => candidate.engine === engine);
|
|
150
|
+
const carried: { family: Family; url: string }[] = [];
|
|
151
|
+
const direct: Family[] = [];
|
|
152
|
+
for (const target of targets) {
|
|
153
|
+
const already = carried.some((entry) => entry.family === target.family);
|
|
154
|
+
if (state && proves(state, target) && !already)
|
|
155
|
+
carried.push({ family: target.family, url: target.url });
|
|
156
|
+
else if (!direct.includes(target.family)) direct.push(target.family);
|
|
157
|
+
}
|
|
158
|
+
if (carried.length === 0) {
|
|
159
|
+
notices.push(`Provider "${group.provider}" cannot be carried by ${engine}: remaining direct.`);
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
if (direct.length > 0) {
|
|
163
|
+
notices.push(
|
|
164
|
+
`Provider "${group.provider}": ${direct.join(", ")} routed direct because ${engine} cannot carry that family.`,
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
plans.push({
|
|
168
|
+
provider: group.provider,
|
|
169
|
+
engine,
|
|
170
|
+
families: carried.map((entry) => entry.family),
|
|
171
|
+
direct,
|
|
172
|
+
upstreams: carried,
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
return { plans, notices };
|
|
176
|
+
}
|
package/src/breaker.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Api, Model } from "@earendil-works/pi-ai";
|
|
2
|
+
|
|
3
|
+
export type BreakerState = {
|
|
4
|
+
readonly tripped: Set<string>;
|
|
5
|
+
readonly directModels: ReadonlyMap<string, Model<Api>>;
|
|
6
|
+
readonly notify: (message: string) => void;
|
|
7
|
+
};
|
|
8
|
+
|
|
9
|
+
export type BreakerInput = {
|
|
10
|
+
readonly event: { readonly status: number };
|
|
11
|
+
readonly model: Model<Api> | undefined;
|
|
12
|
+
readonly setModel: (model: Model<Api>) => Promise<boolean>;
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Restore the direct endpoint of the selected model once per provider after a proxy-backed route
|
|
17
|
+
* fails. The next turn runs direct; later turns do not route that provider again.
|
|
18
|
+
*/
|
|
19
|
+
export async function onProviderResponse(state: BreakerState, input: BreakerInput): Promise<void> {
|
|
20
|
+
if (input.event.status < 400) return;
|
|
21
|
+
const model = input.model;
|
|
22
|
+
if (!model) return;
|
|
23
|
+
const provider = model.provider;
|
|
24
|
+
const direct = state.directModels.get(provider);
|
|
25
|
+
if (!direct || state.tripped.has(provider)) return;
|
|
26
|
+
state.tripped.add(provider);
|
|
27
|
+
const restored = await input.setModel(direct);
|
|
28
|
+
state.notify(
|
|
29
|
+
`Proxy route for "${provider}" failed with ${input.event.status}; ${
|
|
30
|
+
restored ? "the selected model now uses its direct endpoint" : "restore the direct endpoint manually"
|
|
31
|
+
}. This provider stays direct for the session.`,
|
|
32
|
+
);
|
|
33
|
+
}
|
package/src/config.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { DEFAULT_CONFIG, type CoordinatorConfig, type EngineId } from "./types.ts";
|
|
4
|
+
|
|
5
|
+
export type ConfigLoad = { readonly config: CoordinatorConfig; readonly notices: readonly string[] };
|
|
6
|
+
|
|
7
|
+
const ENGINES: readonly string[] = ["caveman", "headroom"] satisfies EngineId[];
|
|
8
|
+
|
|
9
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
10
|
+
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
function decode(raw: unknown, notices: string[]): CoordinatorConfig {
|
|
14
|
+
if (!isRecord(raw)) {
|
|
15
|
+
if (raw !== undefined) notices.push("Coordinator configuration is not an object: defaults apply.");
|
|
16
|
+
return DEFAULT_CONFIG;
|
|
17
|
+
}
|
|
18
|
+
const start = isRecord(raw.start) ? raw.start : {};
|
|
19
|
+
const assignment: { provider: string; engine: string }[] = [];
|
|
20
|
+
if (Array.isArray(raw.assignment)) {
|
|
21
|
+
for (const entry of raw.assignment) {
|
|
22
|
+
if (isRecord(entry) && typeof entry.provider === "string" && typeof entry.engine === "string") {
|
|
23
|
+
assignment.push({ provider: entry.provider, engine: entry.engine });
|
|
24
|
+
} else {
|
|
25
|
+
notices.push("Skipped a malformed assignment entry: an entry needs a provider and an engine.");
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
const timeoutMs =
|
|
30
|
+
typeof raw.timeoutMs === "number" && raw.timeoutMs > 0 ? raw.timeoutMs : DEFAULT_CONFIG.timeoutMs;
|
|
31
|
+
return {
|
|
32
|
+
start: {
|
|
33
|
+
caveman: typeof start.caveman === "boolean" ? start.caveman : DEFAULT_CONFIG.start.caveman,
|
|
34
|
+
headroom: typeof start.headroom === "boolean" ? start.headroom : DEFAULT_CONFIG.start.headroom,
|
|
35
|
+
},
|
|
36
|
+
assignment,
|
|
37
|
+
timeoutMs,
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Configuration is optional; an absent file narrows nothing and leaves every default in place. */
|
|
42
|
+
export function loadConfig(stateDir: string, notices: string[] = []): ConfigLoad {
|
|
43
|
+
const path = join(stateDir, "config.json");
|
|
44
|
+
let raw: unknown;
|
|
45
|
+
try {
|
|
46
|
+
raw = JSON.parse(readFileSync(path, "utf8"));
|
|
47
|
+
} catch {
|
|
48
|
+
return { config: DEFAULT_CONFIG, notices };
|
|
49
|
+
}
|
|
50
|
+
return { config: decode(raw, notices), notices };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function isKnownEngine(value: string): value is EngineId {
|
|
54
|
+
return ENGINES.includes(value);
|
|
55
|
+
}
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { ProviderGroup } from "./assignment.ts";
|
|
3
|
+
import { PREFERENCE, deriveAssignments } from "./assignment.ts";
|
|
4
|
+
import { familyOf, hostOf } from "./families.ts";
|
|
5
|
+
import { ensureEngine } from "./lifecycle.ts";
|
|
6
|
+
import { planRegistrations, registerAll } from "./providers.ts";
|
|
7
|
+
import type { SessionDeps, SessionState } from "./state.ts";
|
|
8
|
+
import type { EngineId, EngineState, Family } from "./types.ts";
|
|
9
|
+
|
|
10
|
+
export type Discovered = {
|
|
11
|
+
readonly engines: EngineState[];
|
|
12
|
+
readonly headroom: Map<string, EngineState>;
|
|
13
|
+
readonly failures: Map<EngineId, string>;
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
/** Probe what is already running. Nothing is started here: adoption only. */
|
|
17
|
+
export async function discoverEngines(
|
|
18
|
+
groups: readonly ProviderGroup[],
|
|
19
|
+
deps: SessionDeps,
|
|
20
|
+
): Promise<Discovered> {
|
|
21
|
+
const engines: EngineState[] = [];
|
|
22
|
+
const headroom = new Map<string, EngineState>();
|
|
23
|
+
const failures = new Map<EngineId, string>();
|
|
24
|
+
|
|
25
|
+
const caveman = await ensureEngine({ engine: "caveman", start: false }, deps.lifecycle);
|
|
26
|
+
if (caveman.ok) engines.push(caveman.state);
|
|
27
|
+
else failures.set("caveman", caveman.reason);
|
|
28
|
+
|
|
29
|
+
for (const group of groups) {
|
|
30
|
+
const upstreams = group.models
|
|
31
|
+
.map((model) => ({ family: familyOf(model.api), url: model.baseUrl ?? "" }))
|
|
32
|
+
.filter((entry): entry is { family: NonNullable<typeof entry.family>; url: string } =>
|
|
33
|
+
Boolean(entry.family && entry.url),
|
|
34
|
+
)
|
|
35
|
+
.map((entry) => ({ family: entry.family, url: entry.url }));
|
|
36
|
+
const probe = await ensureEngine(
|
|
37
|
+
{ engine: "headroom", key: group.provider, start: false, upstreams },
|
|
38
|
+
deps.lifecycle,
|
|
39
|
+
);
|
|
40
|
+
if (probe.ok) headroom.set(group.provider, probe.state);
|
|
41
|
+
else failures.set("headroom", probe.reason);
|
|
42
|
+
}
|
|
43
|
+
engines.push(...headroom.values());
|
|
44
|
+
return { engines, headroom, failures };
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Start the engines a plan needs, in the order the plans need them. */
|
|
48
|
+
/**
|
|
49
|
+
* Cold start has no proven plan yet, so the preference table drives it: the current provider's
|
|
50
|
+
* families choose the engines that must come up before an assignment can be derived.
|
|
51
|
+
*/
|
|
52
|
+
export async function startNeeded(
|
|
53
|
+
groups: readonly ProviderGroup[],
|
|
54
|
+
currentProvider: string | undefined,
|
|
55
|
+
discovered: Discovered,
|
|
56
|
+
deps: SessionDeps,
|
|
57
|
+
): Promise<void> {
|
|
58
|
+
const families = new Map<string, { family: NonNullable<ReturnType<typeof familyOf>>; url: string }[]>();
|
|
59
|
+
for (const group of groups) {
|
|
60
|
+
families.set(
|
|
61
|
+
group.provider,
|
|
62
|
+
group.models
|
|
63
|
+
.map((model) => ({ family: familyOf(model.api), url: model.baseUrl ?? "" }))
|
|
64
|
+
.filter((entry): entry is { family: NonNullable<ReturnType<typeof familyOf>>; url: string } =>
|
|
65
|
+
Boolean(entry.family && entry.url),
|
|
66
|
+
),
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const wantsCaveman = [...families.values()].some((list) =>
|
|
71
|
+
list.some((entry) => PREFERENCE[entry.family][0] === "caveman"),
|
|
72
|
+
);
|
|
73
|
+
if (wantsCaveman && !hasEngine(discovered, "caveman") && deps.start.caveman) {
|
|
74
|
+
await startCaveman(discovered, deps);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
if (currentProvider !== undefined)
|
|
78
|
+
await startHeadroom(currentProvider, families.get(currentProvider) ?? [], discovered, deps);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function hasEngine(discovered: Discovered, engine: "caveman" | "headroom"): boolean {
|
|
82
|
+
return discovered.engines.some((state) => state.engine === engine);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
async function startCaveman(discovered: Discovered, deps: SessionDeps): Promise<void> {
|
|
86
|
+
const probe = await ensureEngine({ engine: "caveman", start: true }, deps.lifecycle);
|
|
87
|
+
if (probe.ok) {
|
|
88
|
+
discovered.engines.push(probe.state);
|
|
89
|
+
discovered.failures.delete("caveman");
|
|
90
|
+
} else {
|
|
91
|
+
discovered.failures.set("caveman", probe.reason);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
async function startHeadroom(
|
|
96
|
+
provider: string,
|
|
97
|
+
families: readonly { family: Family; url: string }[],
|
|
98
|
+
discovered: Discovered,
|
|
99
|
+
deps: SessionDeps,
|
|
100
|
+
): Promise<void> {
|
|
101
|
+
if (discovered.headroom.has(provider) || !deps.start.headroom) return;
|
|
102
|
+
if (!families.some((entry) => PREFERENCE[entry.family][0] === "headroom")) return;
|
|
103
|
+
const upstreams = [...new Map(families.map((entry) => [entry.family, entry])).values()];
|
|
104
|
+
const probe = await ensureEngine(
|
|
105
|
+
{ engine: "headroom", key: provider, start: true, upstreams },
|
|
106
|
+
deps.lifecycle,
|
|
107
|
+
);
|
|
108
|
+
if (probe.ok) {
|
|
109
|
+
discovered.headroom.set(provider, probe.state);
|
|
110
|
+
discovered.engines.push(probe.state);
|
|
111
|
+
discovered.failures.delete("headroom");
|
|
112
|
+
} else {
|
|
113
|
+
discovered.failures.set("headroom", probe.reason);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* First selection of a provider is when its engine comes up. A provider the harness engine currently
|
|
119
|
+
* carries is upgraded to the wire engine when the family preference wants it and it proves the host.
|
|
120
|
+
*/
|
|
121
|
+
export async function ensureProvider(
|
|
122
|
+
api: ExtensionAPI,
|
|
123
|
+
state: SessionState,
|
|
124
|
+
provider: string,
|
|
125
|
+
deps: SessionDeps,
|
|
126
|
+
): Promise<void> {
|
|
127
|
+
const group = state.groups.find((entry) => entry.provider === provider);
|
|
128
|
+
const families = (group?.models ?? [])
|
|
129
|
+
.map((model) => ({ family: familyOf(model.api), url: model.baseUrl ?? "" }))
|
|
130
|
+
.filter((entry): entry is { family: NonNullable<ReturnType<typeof familyOf>>; url: string } =>
|
|
131
|
+
Boolean(entry.family && entry.url),
|
|
132
|
+
);
|
|
133
|
+
const wanted = families.some((entry) => PREFERENCE[entry.family][0] === "headroom");
|
|
134
|
+
if (!wanted || state.ports.has(provider)) return;
|
|
135
|
+
|
|
136
|
+
const upstreams = [...new Map(families.map((entry) => [entry.family, entry])).values()];
|
|
137
|
+
const probe = await ensureEngine(
|
|
138
|
+
{ engine: "headroom", key: provider, start: deps.start.headroom, upstreams },
|
|
139
|
+
deps.lifecycle,
|
|
140
|
+
);
|
|
141
|
+
if (!probe.ok) {
|
|
142
|
+
deps.notify(
|
|
143
|
+
"warning",
|
|
144
|
+
`headroom could not start for "${provider}" (${probe.reason}); its models run direct.`,
|
|
145
|
+
);
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
state.engines.push(probe.state);
|
|
149
|
+
state.ports.set(provider, probe.state.port);
|
|
150
|
+
if (!state.counters.has("headroom")) state.counters.set("headroom", { requests: 0, failures: 0 });
|
|
151
|
+
|
|
152
|
+
const derived = deriveAssignments(state.groups, state.engines, deps.overrides, { familyOf, hostOf });
|
|
153
|
+
const updated = derived.plans.find((plan) => plan.provider === provider);
|
|
154
|
+
if (!updated) return;
|
|
155
|
+
const index = state.plans.findIndex((plan) => plan.provider === provider);
|
|
156
|
+
if (index >= 0) state.plans[index] = updated;
|
|
157
|
+
if (updated.engine !== "headroom") return;
|
|
158
|
+
registerAll(
|
|
159
|
+
api,
|
|
160
|
+
planRegistrations([updated], state.groups, new Map([[provider, probe.state.port]]), state.extras),
|
|
161
|
+
(message) => deps.notify("warning", message),
|
|
162
|
+
);
|
|
163
|
+
}
|
package/src/families.ts
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { EngineId, Family } from "./types.ts";
|
|
2
|
+
|
|
3
|
+
/** Tokens that identify a wire family from pi's model `api` value. Order matters: first match wins. */
|
|
4
|
+
const FAMILY_TOKENS: readonly (readonly [string, Family])[] = [
|
|
5
|
+
["anthropic", "anthropic"],
|
|
6
|
+
["google", "gemini"],
|
|
7
|
+
["gemini", "gemini"],
|
|
8
|
+
["openai", "openai"],
|
|
9
|
+
];
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The wire family a model `api` belongs to, or undefined when no engine has a wire layer for it.
|
|
13
|
+
* Images, classifiers and unknown APIs never route.
|
|
14
|
+
*/
|
|
15
|
+
export function familyOf(api: string): Family | undefined {
|
|
16
|
+
const value = api.toLowerCase();
|
|
17
|
+
for (const [token, family] of FAMILY_TOKENS) {
|
|
18
|
+
if (value.includes(token)) return family;
|
|
19
|
+
}
|
|
20
|
+
return undefined;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** The host of a base URL, or "" when it does not parse. Routing compares hosts, never paths. */
|
|
24
|
+
export function hostOf(baseUrl: string | undefined): string {
|
|
25
|
+
if (!baseUrl) return "";
|
|
26
|
+
try {
|
|
27
|
+
return new URL(baseUrl).host;
|
|
28
|
+
} catch {
|
|
29
|
+
return "";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Caveman publishes upstreams under its own keys. A key names a wire family; an
|
|
35
|
+
* OpenAI-compatible compat mount is always the openai family.
|
|
36
|
+
*/
|
|
37
|
+
export function cavemanFamilyOf(key: string, compat: boolean): Family | undefined {
|
|
38
|
+
return compat ? "openai" : familyOf(key);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Engine retrieval tools the coordinator hides while keeping them callable. A pi build that owns the
|
|
43
|
+
* MCP server names them `mcp__<server>__<tool>`; an MCP adapter that already prefixes by server name
|
|
44
|
+
* exposes the bare form. Both are listed, so hiding never depends on which backend is loaded.
|
|
45
|
+
*/
|
|
46
|
+
export const RETRIEVAL_TOOL_CANDIDATES: Record<EngineId, readonly [string, ...string[]]> = {
|
|
47
|
+
caveman: ["caveman_retrieve"],
|
|
48
|
+
headroom: ["mcp__headroom__headroom_retrieve", "headroom_retrieve"],
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
/** The name this engine's retrieval tool actually has, preferring the live callable set. */
|
|
52
|
+
export function resolveRetrievalTool(
|
|
53
|
+
engine: EngineId,
|
|
54
|
+
callable: readonly { readonly name: string }[],
|
|
55
|
+
): string {
|
|
56
|
+
const candidates = RETRIEVAL_TOOL_CANDIDATES[engine];
|
|
57
|
+
return candidates.find((name) => callable.some((tool) => tool.name === name)) ?? candidates[0];
|
|
58
|
+
}
|