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.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /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;
|