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.
Files changed (46) hide show
  1. package/README.md +103 -2
  2. package/biome.json +22 -0
  3. package/dist/index.js +1089 -0
  4. package/package.json +27 -4
  5. package/scripts/smoke.ts +141 -0
  6. package/src/assignment.ts +176 -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 +71 -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 +156 -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
package/README.md CHANGED
@@ -1,3 +1,104 @@
1
- # Temporary Holding Version
1
+ > *Architected and directed by Human Intelligence, **implemented by AI**.*
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # dual-engine
4
+
5
+ A pi extension that runs Caveman and Headroom side by side without stacking compression: one engine owns a given byte, and the model sees one recovery tool.
6
+
7
+ ## Install
8
+
9
+ Three installs, no configuration file:
10
+
11
+ 1. `caveman enable pi` puts the harness layer in place.
12
+ 2. `uv tool install --python 3.13 "headroom-ai[proxy]"` puts the wire layer on `PATH`. The `[proxy]`
13
+ extra carries `fastapi`/`uvicorn`/`openai` and the MCP server; `[mcp]` alone can serve tools but
14
+ cannot run `headroom proxy`. Use `[all]` for Headroom's full engine.
15
+ 3. Install this package (`pi-dual-engine`) so pi loads `dist/index.js`: copy the directory under `~/.pi/agent/extensions/dual-engine/` (its `package.json` carries `pi.extensions`), or add it as a pi package.
16
+
17
+ On the first session the coordinator probes both engines, adopts one that already runs, starts one that is absent, derives which engine owns each provider, registers the Headroom-backed providers for this session only, and reports one retrieval tool. No file is edited, and no port is chosen by hand.
18
+
19
+ ## The two topologies
20
+
21
+ - **T1, derived (default).** The wire family of each model decides the engine. Models whose API and base URL match a family an engine proves are carried by that engine; everything else runs direct. No provider name appears in the derivation. At session start the preferred engine comes up only for the selected provider, so providers nobody selects stay on the engine that already proves them, and upgrade on their first selection.
22
+ - **T2, assigned (opt-in).** Add `config.json` under the extension's state directory to pin one provider to one engine:
23
+
24
+ ```json
25
+ {
26
+ "start": { "caveman": true, "headroom": true },
27
+ "assignment": [{ "provider": "example", "engine": "caveman" }],
28
+ "timeoutMs": 30000
29
+ }
30
+ ```
31
+
32
+ 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.
33
+
34
+ ## Engine lifecycle
35
+
36
+ - 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.
37
+ - An engine that already runs is adopted and outlives the session. A process this session started is the only one it ever stops.
38
+ - `start.enabled` defaults to **true** for both engines. Set `"start": { "caveman": false }` or `{ "headroom": false }` to defer to your own supervisor; the coordinator then reports the engine as unavailable and continues with the other one.
39
+ - Ports: Caveman keeps its own default (8787). Headroom gets one instance per provider, each with one upstream flag per wire family, on a deterministic port derived from the provider id so two sessions agree where to look.
40
+ - A per-port lock names the pid that started the engine; a lock whose pid is dead is taken over, a lock held by a live session is respected. The Headroom lock records the process actually listening on the port, because its launcher forks a worker into its own session.
41
+ - Caveman's own `execute.proxy` setting is authoritative: when it is `false`, `caveman enable pi` declines to spawn a proxy, and the coordinator degrades once to the wire engine instead of overriding that choice.
42
+ - Started engines stop at session end: Headroom by pid, Caveman through its own `caveman stop` door, because its proxy is a child of that door and not of the coordinator.
43
+ - Spawning is lazy in the sense that only the engines a plan needs come up: Caveman once, Headroom for the provider that is being used. A provider the harness engine currently carries is upgraded to the wire engine the first time that provider is selected, if it proves the host.
44
+ - Caveman is started through its own door (`caveman enable pi`), which installs its extension for subsequent sessions. If no Caveman proxy is running in the current session, the coordinator reports it once and continues on Headroom rather than spawning the proxy binary itself.
45
+
46
+ Notices the lifecycle can emit, once per session each:
47
+
48
+ - `<engine> is unavailable (<reason>). The session continues without it.`
49
+ - `headroom could not start for "<provider>" (<reason>); its models run direct.`
50
+ - `Provider "<provider>": <families> routed direct because <engine> cannot carry that family.`
51
+ - `Provider "<provider>" serves no wire family an engine can carry: running direct.`
52
+ - `Conflicting assignments for provider "<provider>": the derived engine applies.`
53
+ - `Unknown engine "<engine>" for provider "<provider>": the derived engine applies.`
54
+ - `Proxy route for "<provider>" failed with <status>; ... stays direct for the session.`
55
+ - `<mcp.json path> declares "headroom"; the user declaration takes precedence.`
56
+ - `Non-chat providers (<names>) are never routed through a compression engine.`
57
+ - `This pi version cannot hide tool declarations, so the single retrieval tool was not registered.`
58
+
59
+ ## Retrieval
60
+
61
+ One `retrieve` tool is model-visible; dispatch is decided by the handle shape, never by trying engines in sequence.
62
+
63
+ | Handle | Path | Why |
64
+ |---|---|---|
65
+ | `ccr_*` | `ctx.executeTool("caveman_retrieve")` | Caveman's extension registers that tool; it owns the CCR store |
66
+ | 12-24 hex | `POST http://127.0.0.1:<port>/v1/retrieve` with `{"hash": handle}` | Headroom keeps one on-disk store per machine, so any live instance serves any handle |
67
+
68
+ The Headroom path deliberately does not depend on an MCP tool name. That name differs by backend (`mcp__headroom__headroom_retrieve` under pi's built-in MCP, a bare `headroom_retrieve` under an adapter that already prefixes by server name), and a server registered at runtime is not guaranteed to connect at all. Both names stay in the hidden set when they do exist. The MCP server is still registered for `headroom_compress` and `headroom_stats`; retrieval no longer needs it.
69
+
70
+ Options on the Headroom path, chosen for the smallest number of round trips: one request per live port, stopping at the first HTTP answer, because a `404` is store-wide and another instance cannot change it; only a transport failure falls through to the next live port; a 2 s bound per attempt; the store's own `detail` is returned verbatim on a miss.
71
+
72
+ ### Recovered content is not exempt from the harness rewrite
73
+
74
+ Caveman's proxy rewrites large tool results on their way into the transcript, and it exempts only its own retrieval tool names (`caveman_retrieve`, `mcp__caveman__caveman_retrieve`, `caveman_caveman_retrieve`). The coordinator's tool is named `retrieve`, so a large JSON recovery is re-encoded as TOON exactly like any other large JSON tool result.
75
+
76
+ The guarantee is therefore semantic, not byte-for-byte: TOON is a lossless JSON round trip, so every field and value survives, and the rewrite is size-gated — a 640-byte source recovery arrives untouched, while a 120-row JSON original comes back re-encoded. No configuration in either engine can exempt a tool name today, so this is recorded rather than worked around.
77
+
78
+ ## Assignment report
79
+
80
+ Every session writes `assignment.json` inside its state directory: one entry per provider with the engine that owns it, the families it carries, and the families left direct:
81
+
82
+ ```json
83
+ { "providers": [{ "provider": "example", "engine": "headroom", "families": ["openai"], "direct": ["gemini"] }] }
84
+ ```
85
+
86
+ `engine: null` means the provider runs direct. The report is rewritten on every session and never touches user configuration.
87
+
88
+ ## Status semantics
89
+
90
+ `/dual-engine` prints one labeled block per engine:
91
+
92
+ ```text
93
+ headroom (adopted, port 8788)
94
+ providers: example
95
+ upstreams: openai@api.example.com
96
+ requests: 12 failures: 0
97
+ ```
98
+
99
+ The two blocks are never summed. Caveman measures harness work on the transcript, Headroom measures wire compression of request bodies; the bases differ, so a combined figure would be a fabricated number. Read each block as that engine's own report.
100
+
101
+ ## Verified behaviour
102
+
103
+ - `bun test` covers handle dispatch, engine derivation, identity probes, lifecycle adoption and ownership, retrieval dispatch, the degradation matrix, and the no-writes guarantee for user configuration.
104
+ - `bun extension/scripts/smoke.ts` starts pi with the built extension, sends one prompt through a stub provider, and asserts the request declares exactly one retrieval tool.
package/biome.json ADDED
@@ -0,0 +1,22 @@
1
+ {
2
+ "$schema": "https://biomejs.dev/schemas/2.3.4/schema.json",
3
+ "formatter": {
4
+ "enabled": true,
5
+ "indentStyle": "space",
6
+ "indentWidth": 2,
7
+ "lineWidth": 110
8
+ },
9
+ "linter": {
10
+ "enabled": true,
11
+ "rules": {
12
+ "recommended": true
13
+ }
14
+ },
15
+ "files": {
16
+ "includes": [
17
+ "src/**",
18
+ "test/**",
19
+ "scripts/**"
20
+ ]
21
+ }
22
+ }