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,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)