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
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { afterEach, describe, expect, test } from "bun:test";
|
|
2
|
+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
import { portableInvocation } from "../src/setup.ts";
|
|
6
|
+
|
|
7
|
+
const dirs: string[] = [];
|
|
8
|
+
|
|
9
|
+
afterEach(() => {
|
|
10
|
+
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
|
|
11
|
+
});
|
|
12
|
+
|
|
13
|
+
function fixtureDir(): string {
|
|
14
|
+
const dir = mkdtempSync(join(tmpdir(), "winspawn-"));
|
|
15
|
+
dirs.push(dir);
|
|
16
|
+
return dir;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function winEnv(dir: string): NodeJS.ProcessEnv {
|
|
20
|
+
return { PATH: dir, PATHEXT: ".com;.exe;.bat;.cmd" };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
test("non-Windows invocation passes through untouched", () => {
|
|
24
|
+
const inv = portableInvocation("caveman", ["enable", "pi"], "darwin", {});
|
|
25
|
+
expect(inv).toEqual({ command: "caveman", args: ["enable", "pi"] });
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
test("native .exe resolves directly with unchanged args", () => {
|
|
29
|
+
const dir = fixtureDir();
|
|
30
|
+
writeFileSync(join(dir, "headroom.exe"), "");
|
|
31
|
+
const inv = portableInvocation("headroom", ["proxy", "--port", "8787"], "win32", winEnv(dir));
|
|
32
|
+
expect(inv).toEqual({ command: join(dir, "headroom.exe"), args: ["proxy", "--port", "8787"] });
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
test("PATHEXT order prefers .exe over .cmd", () => {
|
|
36
|
+
const dir = fixtureDir();
|
|
37
|
+
writeFileSync(join(dir, "caveman.exe"), "");
|
|
38
|
+
writeFileSync(join(dir, "caveman.cmd"), "ECHO off");
|
|
39
|
+
const inv = portableInvocation("caveman", ["stop"], "win32", winEnv(dir));
|
|
40
|
+
expect(inv).toEqual({ command: join(dir, "caveman.exe"), args: ["stop"] });
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
test("npm node shim resolves to process.execPath plus JS entry", () => {
|
|
44
|
+
const dir = fixtureDir();
|
|
45
|
+
const entry = join(dir, "node_modules", "caveman", "dist", "index.js");
|
|
46
|
+
mkdirSync(join(dir, "node_modules", "caveman", "dist"), { recursive: true });
|
|
47
|
+
writeFileSync(entry, "module.exports = {};");
|
|
48
|
+
writeFileSync(
|
|
49
|
+
join(dir, "caveman.cmd"),
|
|
50
|
+
`@ECHO off\nSETLOCAL\n"%_prog%" "%dp0%\\\\node_modules\\\\caveman\\\\dist\\\\index.js" %*\n`,
|
|
51
|
+
);
|
|
52
|
+
const inv = portableInvocation("caveman", ["enable", "pi"], "win32", winEnv(dir));
|
|
53
|
+
expect(inv).toEqual({ command: process.execPath, args: [entry, "enable", "pi"] });
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
test("nested shim forwards through to the node entry", () => {
|
|
57
|
+
const dir = fixtureDir();
|
|
58
|
+
const entry = join(dir, "inner-entry.js");
|
|
59
|
+
writeFileSync(entry, "module.exports = {};");
|
|
60
|
+
writeFileSync(join(dir, "inner.cmd"), `"%_prog%" "%dp0%\\\\inner-entry.js" %*\n`);
|
|
61
|
+
writeFileSync(join(dir, "outer.cmd"), `"${join(dir, "inner.cmd")}" %*\n`);
|
|
62
|
+
const inv = portableInvocation("outer", [], "win32", winEnv(dir));
|
|
63
|
+
expect(inv).toEqual({ command: process.execPath, args: [entry] });
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
describe("refusals fall back without throwing", () => {
|
|
67
|
+
test("unparseable batch shim returns the shim path", () => {
|
|
68
|
+
const dir = fixtureDir();
|
|
69
|
+
writeFileSync(join(dir, "plain.cmd"), "@ECHO off\r\nECHO hello\r\n");
|
|
70
|
+
const inv = portableInvocation("plain", ["x"], "win32", winEnv(dir));
|
|
71
|
+
expect(inv).toEqual({ command: join(dir, "plain.cmd"), args: ["x"] });
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
test("shim cycle returns the shim path", () => {
|
|
75
|
+
const dir = fixtureDir();
|
|
76
|
+
writeFileSync(join(dir, "a.cmd"), `"${join(dir, "b.cmd")}" %*\n`);
|
|
77
|
+
writeFileSync(join(dir, "b.cmd"), `"${join(dir, "a.cmd")}" %*\n`);
|
|
78
|
+
const inv = portableInvocation("a", [], "win32", winEnv(dir));
|
|
79
|
+
expect(inv).toEqual({ command: join(dir, "a.cmd"), args: [] });
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
test("shim with missing target returns the shim path", () => {
|
|
83
|
+
const dir = fixtureDir();
|
|
84
|
+
writeFileSync(join(dir, "ghost.cmd"), `"%_prog%" "%dp0%\\\\missing\\\\entry.js" %*\n`);
|
|
85
|
+
const inv = portableInvocation("ghost", [], "win32", winEnv(dir));
|
|
86
|
+
expect(inv).toEqual({ command: join(dir, "ghost.cmd"), args: [] });
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
test("unknown command returns the command unchanged", () => {
|
|
90
|
+
const inv = portableInvocation("nope-not-here", ["x"], "win32", winEnv(""));
|
|
91
|
+
expect(inv).toEqual({ command: "nope-not-here", args: ["x"] });
|
|
92
|
+
});
|
|
93
|
+
});
|
package/tsconfig.json
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"target": "ES2022",
|
|
4
|
+
"module": "ESNext",
|
|
5
|
+
"moduleResolution": "bundler",
|
|
6
|
+
"lib": ["ES2022"],
|
|
7
|
+
"types": ["node", "bun"],
|
|
8
|
+
"strict": true,
|
|
9
|
+
"noUncheckedIndexedAccess": true,
|
|
10
|
+
"noEmit": true,
|
|
11
|
+
"skipLibCheck": true,
|
|
12
|
+
"allowImportingTsExtensions": true,
|
|
13
|
+
"verbatimModuleSyntax": true,
|
|
14
|
+
"forceConsistentCasingInFileNames": true
|
|
15
|
+
},
|
|
16
|
+
"include": ["src", "test"]
|
|
17
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
okf_version: "0.2"
|
|
3
|
+
type: WikiPage
|
|
4
|
+
title: Getting started with dual-engine
|
|
5
|
+
tier: beginner
|
|
6
|
+
status: draft
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Getting started with dual-engine
|
|
10
|
+
|
|
11
|
+
Three installs, no configuration file:
|
|
12
|
+
|
|
13
|
+
1. `caveman enable pi` puts the harness layer in place.
|
|
14
|
+
2. `uv tool install --python 3.13 "headroom-ai[proxy]"` puts the wire layer on `PATH`.
|
|
15
|
+
3. Install this package (`pi-dual-engine`) so pi loads `dist/index.js`.
|
|
16
|
+
|
|
17
|
+
Configuration only narrows: unlisted providers keep the derived assignment, an unknown engine name or a duplicated entry is skipped with one notice, and the session still starts.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
okf_version: "0.2"
|
|
3
|
+
type: WikiPage
|
|
4
|
+
title: dual-engine guides and workflows
|
|
5
|
+
tier: intermediate
|
|
6
|
+
status: draft
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Guides and workflows
|
|
10
|
+
|
|
11
|
+
## Engine lifecycle
|
|
12
|
+
|
|
13
|
+
- Readiness is identity, not a listening socket. Caveman must answer `/health/live` with the instance token from its run-state file and report `recovery_via_mcp`; Headroom must answer `/livez` and name its upstreams in the loopback `/health` config block.
|
|
14
|
+
- An engine that already runs is adopted and outlives the session. A process this session started is stopped when the session closes.
|
|
15
|
+
|
|
16
|
+
## Retrieval
|
|
17
|
+
|
|
18
|
+
The model sees one recovery tool. Handles route by shape: `ccr_*` (Caveman) versus `[a-f0-9]{12,24}` (Headroom). Recovered content is not exempt from the harness rewrite.
|
|
19
|
+
|
|
20
|
+
## Assignment report
|
|
21
|
+
|
|
22
|
+
Per-provider engine assignment is reported at session start; unknown or duplicated entries are skipped with one notice each.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
okf_version: "0.2"
|
|
3
|
+
type: WikiPage
|
|
4
|
+
title: dual-engine architecture and internals
|
|
5
|
+
tier: advanced
|
|
6
|
+
status: draft
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Architecture and internals
|
|
10
|
+
|
|
11
|
+
One engine owns any given byte. `families.ts` routes by model `api` token (`anthropic`, `gemini`, `openai`); images, classifiers, and unknown APIs never route. `handles.ts` routes recovery by handle shape without deciding the engine first.
|
|
12
|
+
|
|
13
|
+
Two topologies exist (see `README.md` - The two topologies): harness-only, where Caveman owns everything, and split, where each engine owns its layer. Stacking compression is refused: a byte already owned by one engine is never recompressed by the other.
|
|
14
|
+
|
|
15
|
+
Status semantics distinguish ready, degraded (one engine missing: the session still starts and reports which side is down), and down. Probe, breaker, and session modules own readiness, failure accounting, and lifecycle respectively.
|
package/wiki/index.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
okf_version: "0.2"
|
|
3
|
+
type: WikiPage
|
|
4
|
+
title: dual-engine Package — Documentation
|
|
5
|
+
tier: beginner
|
|
6
|
+
status: draft
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# dual-engine Package — Documentation
|
|
10
|
+
|
|
11
|
+
Curriculum map for the `pi-dual-engine` package.
|
|
12
|
+
|
|
13
|
+
- [Getting started](01-getting-started.md)
|
|
14
|
+
- [Guides and workflows](02-guides-and-workflows.md)
|
|
15
|
+
- [Architecture and internals](03-architecture-and-internals.md)
|