owenloop 0.4.0 → 0.5.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 (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,100 @@
1
+ /**
2
+ * PHASE 6, ITEMS 3 + 5 — the `OWENLOOP_*` namespace allowlist for harness
3
+ * children. Vendor-neutral by construction: this module names no harness and no
4
+ * vendor, only owenloop's own environment variables.
5
+ *
6
+ * ── WHAT THE FILTER DOES, EXACTLY ────────────────────────────────────────────
7
+ *
8
+ * It applies to variables whose name begins with `OWENLOOP_`, and to NOTHING
9
+ * else. Within that namespace only the names in `ADMITTED_OWENLOOP_KEYS` are
10
+ * passed to a harness child; every other `OWENLOOP_*` name is removed. Every
11
+ * variable OUTSIDE the namespace — `PATH`, `HOME`, `TMPDIR`, `LANG`,
12
+ * `SSL_CERT_FILE`, corporate proxy variables, `NODE_OPTIONS`, each vendor's own
13
+ * credential and configuration variables — passes through untouched.
14
+ *
15
+ * ── WHY THE SCOPE IS THE NAMESPACE AND NOT THE WHOLE ENVIRONMENT ─────────────
16
+ *
17
+ * Two requirements pull in opposite directions on one mechanism:
18
+ *
19
+ * ITEM 5 wants owenloop's dev-only hub bearer override to stop reaching
20
+ * harness children. A harness child is an ordinary process that inherits its
21
+ * parent's environment, and at least one harness demonstrably persists its
22
+ * start parameters to disk, so credential material in that environment has a
23
+ * real path to a file on the operator's machine.
24
+ *
25
+ * ITEM 3 wants a harness's own OAuth credential variable to KEEP reaching its
26
+ * child, because under launchd the Keychain read can fail and that variable is
27
+ * the fallback credential path. A stranded credential is a harness that cannot
28
+ * start at all.
29
+ *
30
+ * A conventional allowlist — "the child gets only the names on this list" —
31
+ * satisfies both only if the list is exhaustive over everything every vendor
32
+ * binary needs in order to start. That set is unknowable, and it grows with each
33
+ * vendor release. Scoping the allowlist to owenloop's OWN namespace makes the
34
+ * two requirements independent rather than opposed:
35
+ *
36
+ * - owenloop knows every name in the `OWENLOOP_*` namespace and every consumer
37
+ * of every name. That is exactly the knowledge a precise allowlist needs, and
38
+ * exactly the knowledge owenloop does not have about `PATH` or about a
39
+ * vendor's variables.
40
+ * - No vendor credential variable is in the namespace, so no vendor credential
41
+ * can be stranded — not by oversight, not by a later edit. Structurally.
42
+ * - It is still deny-by-default WITHIN the namespace, so an `OWENLOOP_*`
43
+ * variable added by some future phase does not silently start flowing to
44
+ * harness children. Adding one to this set is a deliberate, reviewable act.
45
+ *
46
+ * ── HOW THE ADMITTED SET WAS DERIVED, AND HOW TO RE-DERIVE IT ────────────────
47
+ *
48
+ * The only owenloop process a harness child spawns is the work-holder MCP mount
49
+ * (`owenloop work hold --mcp`), whose argv is built by `src/agent/brief.ts`. Walking
50
+ * the import graph from `src/roles/hold.ts` and collecting every reachable
51
+ * `OWENLOOP_*` read yields these holder inputs:
52
+ *
53
+ * - `OWENLOOP_SHIFT_ID` and `OWENLOOP_SESSION` from `src/roles/hold.ts`;
54
+ * - `OWENLOOP_CREDENTIAL_COMMAND`, `OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS`,
55
+ * and `OWENLOOP_NO_KEYCHAIN` from `src/hub.ts:readStoredCredential()`;
56
+ * - `OWENLOOP_TOKEN` from `src/credentials/resolve.ts`, which is DENIED on
57
+ * purpose — see below.
58
+ *
59
+ * The three credential controls are admitted because the mounted holder uses
60
+ * them to select and configure its credential backend before the MCP server
61
+ * starts. `src/hub.ts:runCredentialCommand()` creates
62
+ * `OWENLOOP_CREDENTIAL_ORIGIN` and `OWENLOOP_CREDENTIAL_SLOT` internally, so
63
+ * those two helper-only names are not inherited from the harness parent.
64
+ *
65
+ * `OWENLOOP_CACHE_DIR` is admitted although it is NOT reachable from `hold`: it
66
+ * is read by `resolveCacheDir` (`src/bundle/cache.ts`), which an agent reaches
67
+ * when its own work runs an owenloop subcommand that touches the bundle cache.
68
+ * It is a directory path, not credential material, and admitting it keeps the
69
+ * worker and anything the agent runs pointed at the same cache.
70
+ *
71
+ * ── THE ONE DENIAL WITH A DELIBERATE CONSEQUENCE ─────────────────────────────
72
+ *
73
+ * `OWENLOOP_TOKEN` is denied, and it IS reachable from `hold`. Left alone that
74
+ * would split the two sides apart: the worker would authenticate to the hub with
75
+ * the override while the child fell back to its credential slot, and an empty
76
+ * slot would surface mid-order as a confusing MCP handshake failure. So
77
+ * `src/roles/agent-run.ts` also ignores `OWENLOOP_TOKEN` when resolving its own
78
+ * bearer. Worker and child then agree, and the failure moves to startup, where
79
+ * `resolveBearer` already refuses with exit code 2 and an actionable message.
80
+ */
81
+ /**
82
+ * The `OWENLOOP_*` names a harness child may see. Everything else in the
83
+ * namespace is removed; everything outside the namespace is untouched.
84
+ *
85
+ * Each entry needs a named consumer that a harness child can actually reach. An
86
+ * entry with no such consumer is a leak with a comment on it.
87
+ */
88
+ export declare const ADMITTED_OWENLOOP_KEYS: ReadonlySet<string>;
89
+ /**
90
+ * A copy of `source` with every non-admitted `OWENLOOP_*` key removed.
91
+ *
92
+ * `source` is a parameter rather than a read of `process.env` so callers and
93
+ * tests can inject a fixture; the input is never mutated. Keys are `delete`d
94
+ * rather than set to `undefined`, because an own key holding `undefined` is not
95
+ * obviously equivalent to an absent key once it crosses a spawn or
96
+ * serialization boundary.
97
+ */
98
+ export declare function filterOwenloopEnv(source: Record<string, string | undefined>): Record<string, string | undefined>;
99
+ /** Whether one variable name may reach a harness child. */
100
+ export declare function isAdmittedChildEnvKey(key: string): boolean;
@@ -0,0 +1,127 @@
1
+ /**
2
+ * PHASE 6, ITEMS 3 + 5 — the `OWENLOOP_*` namespace allowlist for harness
3
+ * children. Vendor-neutral by construction: this module names no harness and no
4
+ * vendor, only owenloop's own environment variables.
5
+ *
6
+ * ── WHAT THE FILTER DOES, EXACTLY ────────────────────────────────────────────
7
+ *
8
+ * It applies to variables whose name begins with `OWENLOOP_`, and to NOTHING
9
+ * else. Within that namespace only the names in `ADMITTED_OWENLOOP_KEYS` are
10
+ * passed to a harness child; every other `OWENLOOP_*` name is removed. Every
11
+ * variable OUTSIDE the namespace — `PATH`, `HOME`, `TMPDIR`, `LANG`,
12
+ * `SSL_CERT_FILE`, corporate proxy variables, `NODE_OPTIONS`, each vendor's own
13
+ * credential and configuration variables — passes through untouched.
14
+ *
15
+ * ── WHY THE SCOPE IS THE NAMESPACE AND NOT THE WHOLE ENVIRONMENT ─────────────
16
+ *
17
+ * Two requirements pull in opposite directions on one mechanism:
18
+ *
19
+ * ITEM 5 wants owenloop's dev-only hub bearer override to stop reaching
20
+ * harness children. A harness child is an ordinary process that inherits its
21
+ * parent's environment, and at least one harness demonstrably persists its
22
+ * start parameters to disk, so credential material in that environment has a
23
+ * real path to a file on the operator's machine.
24
+ *
25
+ * ITEM 3 wants a harness's own OAuth credential variable to KEEP reaching its
26
+ * child, because under launchd the Keychain read can fail and that variable is
27
+ * the fallback credential path. A stranded credential is a harness that cannot
28
+ * start at all.
29
+ *
30
+ * A conventional allowlist — "the child gets only the names on this list" —
31
+ * satisfies both only if the list is exhaustive over everything every vendor
32
+ * binary needs in order to start. That set is unknowable, and it grows with each
33
+ * vendor release. Scoping the allowlist to owenloop's OWN namespace makes the
34
+ * two requirements independent rather than opposed:
35
+ *
36
+ * - owenloop knows every name in the `OWENLOOP_*` namespace and every consumer
37
+ * of every name. That is exactly the knowledge a precise allowlist needs, and
38
+ * exactly the knowledge owenloop does not have about `PATH` or about a
39
+ * vendor's variables.
40
+ * - No vendor credential variable is in the namespace, so no vendor credential
41
+ * can be stranded — not by oversight, not by a later edit. Structurally.
42
+ * - It is still deny-by-default WITHIN the namespace, so an `OWENLOOP_*`
43
+ * variable added by some future phase does not silently start flowing to
44
+ * harness children. Adding one to this set is a deliberate, reviewable act.
45
+ *
46
+ * ── HOW THE ADMITTED SET WAS DERIVED, AND HOW TO RE-DERIVE IT ────────────────
47
+ *
48
+ * The only owenloop process a harness child spawns is the work-holder MCP mount
49
+ * (`owenloop work hold --mcp`), whose argv is built by `src/agent/brief.ts`. Walking
50
+ * the import graph from `src/roles/hold.ts` and collecting every reachable
51
+ * `OWENLOOP_*` read yields these holder inputs:
52
+ *
53
+ * - `OWENLOOP_SHIFT_ID` and `OWENLOOP_SESSION` from `src/roles/hold.ts`;
54
+ * - `OWENLOOP_CREDENTIAL_COMMAND`, `OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS`,
55
+ * and `OWENLOOP_NO_KEYCHAIN` from `src/hub.ts:readStoredCredential()`;
56
+ * - `OWENLOOP_TOKEN` from `src/credentials/resolve.ts`, which is DENIED on
57
+ * purpose — see below.
58
+ *
59
+ * The three credential controls are admitted because the mounted holder uses
60
+ * them to select and configure its credential backend before the MCP server
61
+ * starts. `src/hub.ts:runCredentialCommand()` creates
62
+ * `OWENLOOP_CREDENTIAL_ORIGIN` and `OWENLOOP_CREDENTIAL_SLOT` internally, so
63
+ * those two helper-only names are not inherited from the harness parent.
64
+ *
65
+ * `OWENLOOP_CACHE_DIR` is admitted although it is NOT reachable from `hold`: it
66
+ * is read by `resolveCacheDir` (`src/bundle/cache.ts`), which an agent reaches
67
+ * when its own work runs an owenloop subcommand that touches the bundle cache.
68
+ * It is a directory path, not credential material, and admitting it keeps the
69
+ * worker and anything the agent runs pointed at the same cache.
70
+ *
71
+ * ── THE ONE DENIAL WITH A DELIBERATE CONSEQUENCE ─────────────────────────────
72
+ *
73
+ * `OWENLOOP_TOKEN` is denied, and it IS reachable from `hold`. Left alone that
74
+ * would split the two sides apart: the worker would authenticate to the hub with
75
+ * the override while the child fell back to its credential slot, and an empty
76
+ * slot would surface mid-order as a confusing MCP handshake failure. So
77
+ * `src/roles/agent-run.ts` also ignores `OWENLOOP_TOKEN` when resolving its own
78
+ * bearer. Worker and child then agree, and the failure moves to startup, where
79
+ * `resolveBearer` already refuses with exit code 2 and an actionable message.
80
+ */
81
+ /**
82
+ * The `OWENLOOP_*` names a harness child may see. Everything else in the
83
+ * namespace is removed; everything outside the namespace is untouched.
84
+ *
85
+ * Each entry needs a named consumer that a harness child can actually reach. An
86
+ * entry with no such consumer is a leak with a comment on it.
87
+ */
88
+ export const ADMITTED_OWENLOOP_KEYS = new Set([
89
+ // `resolveCacheDir` — src/bundle/cache.ts. Keeps anything the agent runs on
90
+ // the same bundle cache as the worker. A path, not a secret.
91
+ 'OWENLOOP_CACHE_DIR',
92
+ // `holdShiftId` — src/roles/hold.ts. The fallback when `--shift=` is
93
+ // absent from the mount's argv.
94
+ 'OWENLOOP_SHIFT_ID',
95
+ // `readStoredCredential` — src/hub.ts. Selects the holder's external
96
+ // credential backend rather than falling through to keychain/file defaults.
97
+ 'OWENLOOP_CREDENTIAL_COMMAND',
98
+ // `readStoredCredential` — src/hub.ts. Bounds the external credential helper.
99
+ 'OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS',
100
+ // `readStoredCredential` — src/hub.ts. Forces the 0600 file backend on macOS.
101
+ 'OWENLOOP_NO_KEYCHAIN',
102
+ // `holdSession` — src/roles/hold.ts. The fallback when `--session` is absent.
103
+ 'OWENLOOP_SESSION',
104
+ ]);
105
+ /** The namespace this filter governs. Nothing outside it is ever touched. */
106
+ const NAMESPACE = 'OWENLOOP_';
107
+ /**
108
+ * A copy of `source` with every non-admitted `OWENLOOP_*` key removed.
109
+ *
110
+ * `source` is a parameter rather than a read of `process.env` so callers and
111
+ * tests can inject a fixture; the input is never mutated. Keys are `delete`d
112
+ * rather than set to `undefined`, because an own key holding `undefined` is not
113
+ * obviously equivalent to an absent key once it crosses a spawn or
114
+ * serialization boundary.
115
+ */
116
+ export function filterOwenloopEnv(source) {
117
+ const result = { ...source };
118
+ for (const key of Object.keys(result)) {
119
+ if (key.startsWith(NAMESPACE) && !ADMITTED_OWENLOOP_KEYS.has(key))
120
+ delete result[key];
121
+ }
122
+ return result;
123
+ }
124
+ /** Whether one variable name may reach a harness child. */
125
+ export function isAdmittedChildEnvKey(key) {
126
+ return !key.startsWith(NAMESPACE) || ADMITTED_OWENLOOP_KEYS.has(key);
127
+ }
@@ -0,0 +1,128 @@
1
+ import type { Options, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
+ import type { AgentEvent, HarnessAdapter, StepPermissions } from './contract.ts';
3
+ /**
4
+ * Build the environment the harness child runs under.
5
+ *
6
+ * WHY IT SPREADS RATHER THAN LISTS. The SDK's `Options.env` REPLACES the
7
+ * subprocess environment entirely — it is NOT merged with `process.env` (see
8
+ * that field's own JSDoc in the installed `sdk.d.ts`). Both halves of that bite:
9
+ *
10
+ * - passing only the deltas would blow away `PATH`/`HOME` and break the child;
11
+ * - omitting `env` altogether would let an ambient API key through, which is
12
+ * exactly the bug this function exists to prevent.
13
+ *
14
+ * So the caller ALWAYS sets `env`, and this function always returns a full
15
+ * environment: spread the source, then delete.
16
+ *
17
+ * `source` is a parameter rather than a read of `process.env` so the unit test
18
+ * injects a fixture and never mutates the real environment. The input is not
19
+ * mutated.
20
+ *
21
+ * `delete` is used rather than assigning `undefined`: an own key holding
22
+ * `undefined` is not obviously equivalent to an absent key across the SDK's
23
+ * serialization boundary, and deleting removes the question.
24
+ *
25
+ * TWO INDEPENDENT FILTERS RUN HERE, and conflating them would break one of
26
+ * them:
27
+ *
28
+ * 1. `STRIPPED_ENV_KEYS` — the vendor API-key strip. It is specific to THIS
29
+ * adapter, it is a correctness requirement (an inherited key shadows the
30
+ * subscription and bills credits), and it is under the `allowApiBilling`
31
+ * opt-out.
32
+ * 2. `filterOwenloopEnv` — Phase 6's `OWENLOOP_*` namespace allowlist, shared
33
+ * with the other adapter and NOT under any opt-out. It removes owenloop's
34
+ * own variables that no harness child has a consumer for — the hub bearer
35
+ * override above all — and touches nothing outside that namespace. In
36
+ * particular it cannot reach `CLAUDE_CODE_OAUTH_TOKEN`, which is not an
37
+ * `OWENLOOP_*` name and therefore survives by construction, which is what
38
+ * Phase 6 item 3 needs under launchd.
39
+ *
40
+ * Everything else survives: `PATH`, `HOME`, `TMPDIR`, proxy and TLS variables,
41
+ * and the three admitted `OWENLOOP_*` names the mounted work-holder MCP child
42
+ * actually reads.
43
+ */
44
+ export declare function buildChildEnv(source: Record<string, string | undefined>, opts: {
45
+ allowApiBilling: boolean;
46
+ }): Record<string, string | undefined>;
47
+ /** Whether API billing is allowed, from a machine-level environment toggle.
48
+ * Default is OFF — the strip happens unless the operator opted in. */
49
+ export declare function allowApiBillingFrom(source: Record<string, string | undefined>): boolean;
50
+ /**
51
+ * Resolve the CLI executable: `OWENLOOP_CLAUDE_BIN` → a `claude` on `PATH` →
52
+ * `undefined`.
53
+ *
54
+ * `undefined` means the caller OMITS `pathToClaudeCodeExecutable` entirely and
55
+ * lets the SDK use its own bundled executable. That third case is a decision,
56
+ * not an oversight: the bundled executable is the same CLI reading the same
57
+ * credential store, so subscription auth still works, whereas throwing would
58
+ * make the adapter unusable on a machine where the CLI sits somewhere unusual.
59
+ *
60
+ * The `PATH` walk is done in-process (`accessSync` with `X_OK`) rather than by
61
+ * shelling out: no shell, no extra child, and it is unit-testable against a
62
+ * fixture `PATH` the test builds and `chmod`s itself.
63
+ *
64
+ * `source` is the CHILD environment (a spread of `process.env`), so the override
65
+ * and the `PATH` searched are the same ones the child will see.
66
+ */
67
+ export declare function resolveExecutable(source: Record<string, string | undefined>): string | undefined;
68
+ /** Everything `buildClaudeOptions` reads off a start. `deliver` gets only `cwd`
69
+ * and `owenloopMcp` from the contract, so it passes an empty permission set. */
70
+ export interface ClaudeOptionInputs {
71
+ cwd: string;
72
+ owenloopMcp: {
73
+ command: string;
74
+ args: string[];
75
+ };
76
+ /** Per-start override; wins over `permissions.model`. */
77
+ model?: string;
78
+ /** Per-start override; wins over `permissions.effort`. */
79
+ effort?: string;
80
+ permissions: StepPermissions;
81
+ }
82
+ /** The non-declarative bits a caller supplies per invocation. */
83
+ export interface ClaudeOptionExtras {
84
+ /** The child environment, already built by `buildChildEnv`. Also the source
85
+ * `resolveExecutable` reads the binary override and `PATH` from. */
86
+ env: Record<string, string | undefined>;
87
+ abortController: AbortController;
88
+ onEvent: (e: AgentEvent) => void;
89
+ /** Set on a resume only. Never set on a start. */
90
+ resume?: string;
91
+ }
92
+ /**
93
+ * Map `StartArgs` + the Claude-owned extensions bag onto the SDK's `Options`.
94
+ *
95
+ * The mapping knowledge is PORTED from the legacy compile-time frontmatter
96
+ * builder — the knowledge is correct, only the output format changed. Nothing is
97
+ * imported from `src/adapters/`; the isolation test forbids that dependency
98
+ * direction.
99
+ */
100
+ export declare function buildClaudeOptions(inputs: ClaudeOptionInputs, extra: ClaudeOptionExtras): Options;
101
+ /** What one consumed turn tells the caller. */
102
+ export interface TurnOutcome {
103
+ /** The session id from the `system/init` message, if one arrived. */
104
+ sessionId: string | undefined;
105
+ /** Whether the turn-end (`result`) message arrived. */
106
+ sawResult: boolean;
107
+ }
108
+ /**
109
+ * Drive the SDK message stream to TURN END and map it onto `AgentEvent`s.
110
+ *
111
+ * Resolves at the `result` message — turn end, per the contract — not at process
112
+ * exit, and regardless of whether the result reports an error.
113
+ *
114
+ * `onInit` fires the instant the session id is known, so `start` can emit
115
+ * `{kind:'started'}` BEFORE it resolves: the caller persists the token on that
116
+ * event, which is what leaves a resumable record behind after a mid-turn crash.
117
+ *
118
+ * PHASE 6, ITEM 1 — EXPORTED, AND TYPED ON `AsyncIterable` RATHER THAN `Query`.
119
+ * This is the one function that maps the SDK's message stream onto this
120
+ * project's `AgentEvent` contract, so it is the only place a recorded transcript
121
+ * can prove the mapping still matches a shipped vendor build without spawning
122
+ * the vendor binary. `Query` is an `AsyncGenerator` PLUS control methods
123
+ * (`interrupt`, `setModel`, …) that this function never calls; asking only for
124
+ * what it uses is what lets a fixture drive it. A live `Query` still satisfies
125
+ * the narrower type, so nothing at the call sites changes.
126
+ */
127
+ export declare function consumeTurn(q: AsyncIterable<SDKMessage>, onEvent: (e: AgentEvent) => void, onInit?: (sessionId: string) => void): Promise<TurnOutcome>;
128
+ export declare const claudeAdapter: HarnessAdapter;