owenloop 0.5.0 → 0.5.2

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 (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -21,6 +21,8 @@
21
21
  import { Engine } from './engine.ts';
22
22
  import type { EngineEvent, EngineListener } from './engine.ts';
23
23
  import type { Store } from './store.ts';
24
+ import { OrderResolver } from './order-resolver.ts';
25
+ import type { OrderInstructionSource } from './order-resolver.ts';
24
26
  import type { WorkflowDef } from './types.ts';
25
27
  export interface CreateEngineOpts {
26
28
  /**
@@ -63,12 +65,26 @@ export interface CreateEngineOpts {
63
65
  onEvent?: EngineListener;
64
66
  /** Where a throwing `onEvent`/subscriber's error goes (default: swallowed). */
65
67
  onListenerError?: (err: unknown, event: EngineEvent) => void;
68
+ /**
69
+ * WP-A3-compatible digest/instruction source (the WP-B1 seam). When
70
+ * supplied, emitted orders take their `defDigest` from this source and
71
+ * resolution reads its verified records; when absent, `createEngine`
72
+ * builds one loaded-definition resolver from the finalized def set —
73
+ * same reference-mode behavior, no legacy branch.
74
+ */
75
+ instructionSource?: OrderInstructionSource;
66
76
  }
67
77
  export interface CreatedEngine {
68
78
  engine: Engine;
69
79
  store: Store;
70
80
  /** The resolved definition set, so a host can introspect what was registered. */
71
81
  defs: Map<string, WorkflowDef>;
82
+ /**
83
+ * The reference-order resolver (WP-B1) — the one resolution path for
84
+ * emitted orders. Identical to `engine.resolver`; returned here so an
85
+ * embedder can resolve without holding the engine object.
86
+ */
87
+ resolver: OrderResolver;
72
88
  }
73
89
  /**
74
90
  * Open a store, resolve definitions, and return a wired `Engine` ready to
@@ -23,7 +23,8 @@ import { dirname, join } from 'node:path';
23
23
  import { Engine } from "./engine.js";
24
24
  import { openStore } from "./store.js";
25
25
  import { dbPathRefusingSymlink, mkdirRefusingSymlink } from "./util.js";
26
- import { finalizeDefs, loadDefs } from "./defs.js";
26
+ import { finalizeDefs, loadDefs, resolveCallsTarget } from "./defs.js";
27
+ import { createDefInstructionSource, OrderResolver } from "./order-resolver.js";
27
28
  /**
28
29
  * Open a store, resolve definitions, and return a wired `Engine` ready to
29
30
  * `createInstance` / `tick` / `green` / … . See `docs/embedding.md`.
@@ -74,12 +75,22 @@ export function createEngine(opts = {}) {
74
75
  mkdirSync(dirname(db), { recursive: true });
75
76
  }
76
77
  const store = openStore(db);
77
- const resolveDef = (name) => {
78
- const d = defs.get(name);
78
+ // WS-6: scope-aware, matching the CLI resolver. An embedder's in-memory def
79
+ // set carries no CAS provenance, so `resolveCallsTarget` takes its plain
80
+ // flat-map branch and behavior here is unchanged; the branch exists so an
81
+ // embedder that DOES hand in store-loaded defs gets the same sibling-first
82
+ // rule `finalizeDefs` already validated the set against.
83
+ const resolveDef = (name, from) => {
84
+ const d = from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
79
85
  if (!d)
80
86
  throw new Error(`unknown workflow definition '${name}'`);
81
87
  return d;
82
88
  };
89
+ // WP-B1: one resolver for reference orders, shared by the engine (emission)
90
+ // and returned to the embedder (resolution). Seeded with the finalized def
91
+ // set so their digests are registered up front; `buildOrder` re-registers
92
+ // each exact pinned snapshot it emits against.
93
+ const instructionSource = opts.instructionSource ?? createDefInstructionSource(defs.values());
83
94
  const engineOpts = {};
84
95
  if (opts.reapTtlMs !== undefined)
85
96
  engineOpts.reapTtlMs = opts.reapTtlMs;
@@ -91,6 +102,7 @@ export function createEngine(opts = {}) {
91
102
  engineOpts.onEvent = opts.onEvent;
92
103
  if (opts.onListenerError !== undefined)
93
104
  engineOpts.onListenerError = opts.onListenerError;
105
+ engineOpts.instructionSource = instructionSource;
94
106
  const engine = new Engine(store, resolveDef, engineOpts);
95
- return { engine, store, defs };
107
+ return { engine, store, defs, resolver: engine.resolver };
96
108
  }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * `~/.owenloop/config.json` — the CONTROL plane's non-secret configuration file.
3
+ *
4
+ * Sole writer: `owenloop login` (`dispatchLogin` in `src/cli.ts`), which records
5
+ * the hub origin it just authenticated against here, best-effort, after the
6
+ * credential itself has already been stored. Sole reader: `owenloop mcp`'s
7
+ * origin ladder (`resolveMcpOrigin` in `src/mcp/serve.ts`), which needs to know
8
+ * which hub the operator is using WITHOUT enumerating the credential store —
9
+ * the store's `keychain` and `external` backends cannot be listed at all (see
10
+ * `listStoredHubOrigins` in `src/hub.ts`), so a value that lived only inside
11
+ * the credential vault would be unreadable to the server on the majority of
12
+ * real installs (macOS defaults to the keychain backend).
13
+ *
14
+ * This is deliberately a SEPARATE file from `src/work-settings.ts`'s
15
+ * `~/.config/owenloop/settings.json` (or `$XDG_CONFIG_HOME/owenloop/settings.json`
16
+ * when set). That file belongs to the EXECUTION plane: `owenloop setup` is its
17
+ * sole writer, and `owenloop work` role resolution and pre-commit verification
18
+ * are its readers. This file belongs to the CONTROL plane: `owenloop login`
19
+ * writes it, `owenloop mcp` reads it. Nothing reconciles the two if they
20
+ * disagree — e.g. after `owenloop login --hub A` followed by
21
+ * `owenloop setup --hub B` — and that is an accepted cost, not an oversight:
22
+ * the two files answer different questions ("what hub does an agent shift run
23
+ * against" vs. "what hub does the human's MCP session talk to") for two
24
+ * independently-evolving call paths, and forcing one file to answer both would
25
+ * couple them for no benefit. This file is also HOME-rooted, not XDG-aware,
26
+ * unlike `settings.json`: `owenloop mcp` is a human-facing control-plane
27
+ * process, and there is no separate "XDG vs. HOME" precedence to resolve here
28
+ * — the caller supplies `home` directly (see `globalConfigPath`), mirroring
29
+ * how `src/cli.ts`'s `workflowHome` resolves the same value.
30
+ *
31
+ * Never holds a secret: `hub` is an origin URL, nothing else. A read failure
32
+ * of any kind (file absent, invalid JSON, wrong shape, blank `hub`, or a
33
+ * `hub` value that does not normalize to a valid http(s) origin) is reported
34
+ * as `null`, never thrown — this file is one rung of a fallback ladder
35
+ * (`resolveMcpOrigin`), and a corrupt or half-written config must not be able
36
+ * to crash `owenloop mcp` at startup; the ladder simply falls through to the
37
+ * next rung instead.
38
+ */
39
+ /** The shape of `~/.owenloop/config.json`. `version` is reserved for a future migration. */
40
+ export interface GlobalConfig {
41
+ version: 1;
42
+ hub: string;
43
+ }
44
+ /** `<home>/.owenloop/config.json` — `home` is the caller-resolved `HOME`/`USERPROFILE` value. */
45
+ export declare function globalConfigPath(home: string): string;
46
+ /**
47
+ * Read and validate `path`. Returns `null` — never throws — when the file is
48
+ * absent, is not valid JSON, is not a JSON object, its `hub` field is
49
+ * missing, non-string, or blank, or `hub` does not normalize to a valid
50
+ * http(s) origin (`normalizeOrigin`, `src/hub.ts` — e.g. `"not a url"` or a
51
+ * bare hostname with no scheme). Callers treat `null` as "this rung has
52
+ * nothing to offer" and fall through to the next one. The `hub` on a non-null
53
+ * return is always normalized (scheme required, trailing slash/path
54
+ * stripped) — the same guarantee every other rung of `resolveMcpOrigin`
55
+ * provides, so callers never need to re-normalize what this returns.
56
+ */
57
+ export declare function readGlobalConfig(path: string): GlobalConfig | null;
58
+ /** Write `config` to `path`, creating its parent directory if needed. Atomic (see `writeFileAtomic`). */
59
+ export declare function writeGlobalConfig(path: string, config: GlobalConfig): void;
@@ -0,0 +1,84 @@
1
+ /**
2
+ * `~/.owenloop/config.json` — the CONTROL plane's non-secret configuration file.
3
+ *
4
+ * Sole writer: `owenloop login` (`dispatchLogin` in `src/cli.ts`), which records
5
+ * the hub origin it just authenticated against here, best-effort, after the
6
+ * credential itself has already been stored. Sole reader: `owenloop mcp`'s
7
+ * origin ladder (`resolveMcpOrigin` in `src/mcp/serve.ts`), which needs to know
8
+ * which hub the operator is using WITHOUT enumerating the credential store —
9
+ * the store's `keychain` and `external` backends cannot be listed at all (see
10
+ * `listStoredHubOrigins` in `src/hub.ts`), so a value that lived only inside
11
+ * the credential vault would be unreadable to the server on the majority of
12
+ * real installs (macOS defaults to the keychain backend).
13
+ *
14
+ * This is deliberately a SEPARATE file from `src/work-settings.ts`'s
15
+ * `~/.config/owenloop/settings.json` (or `$XDG_CONFIG_HOME/owenloop/settings.json`
16
+ * when set). That file belongs to the EXECUTION plane: `owenloop setup` is its
17
+ * sole writer, and `owenloop work` role resolution and pre-commit verification
18
+ * are its readers. This file belongs to the CONTROL plane: `owenloop login`
19
+ * writes it, `owenloop mcp` reads it. Nothing reconciles the two if they
20
+ * disagree — e.g. after `owenloop login --hub A` followed by
21
+ * `owenloop setup --hub B` — and that is an accepted cost, not an oversight:
22
+ * the two files answer different questions ("what hub does an agent shift run
23
+ * against" vs. "what hub does the human's MCP session talk to") for two
24
+ * independently-evolving call paths, and forcing one file to answer both would
25
+ * couple them for no benefit. This file is also HOME-rooted, not XDG-aware,
26
+ * unlike `settings.json`: `owenloop mcp` is a human-facing control-plane
27
+ * process, and there is no separate "XDG vs. HOME" precedence to resolve here
28
+ * — the caller supplies `home` directly (see `globalConfigPath`), mirroring
29
+ * how `src/cli.ts`'s `workflowHome` resolves the same value.
30
+ *
31
+ * Never holds a secret: `hub` is an origin URL, nothing else. A read failure
32
+ * of any kind (file absent, invalid JSON, wrong shape, blank `hub`, or a
33
+ * `hub` value that does not normalize to a valid http(s) origin) is reported
34
+ * as `null`, never thrown — this file is one rung of a fallback ladder
35
+ * (`resolveMcpOrigin`), and a corrupt or half-written config must not be able
36
+ * to crash `owenloop mcp` at startup; the ladder simply falls through to the
37
+ * next rung instead.
38
+ */
39
+ import { existsSync, readFileSync } from 'node:fs';
40
+ import { dirname, join } from 'node:path';
41
+ import { mkdirRefusingSymlink } from "./util.js";
42
+ import { normalizeOrigin, writeFileAtomic } from "./hub.js";
43
+ /** `<home>/.owenloop/config.json` — `home` is the caller-resolved `HOME`/`USERPROFILE` value. */
44
+ export function globalConfigPath(home) {
45
+ return join(home, '.owenloop', 'config.json');
46
+ }
47
+ /**
48
+ * Read and validate `path`. Returns `null` — never throws — when the file is
49
+ * absent, is not valid JSON, is not a JSON object, its `hub` field is
50
+ * missing, non-string, or blank, or `hub` does not normalize to a valid
51
+ * http(s) origin (`normalizeOrigin`, `src/hub.ts` — e.g. `"not a url"` or a
52
+ * bare hostname with no scheme). Callers treat `null` as "this rung has
53
+ * nothing to offer" and fall through to the next one. The `hub` on a non-null
54
+ * return is always normalized (scheme required, trailing slash/path
55
+ * stripped) — the same guarantee every other rung of `resolveMcpOrigin`
56
+ * provides, so callers never need to re-normalize what this returns.
57
+ */
58
+ export function readGlobalConfig(path) {
59
+ if (!existsSync(path))
60
+ return null;
61
+ let parsed;
62
+ try {
63
+ parsed = JSON.parse(readFileSync(path, 'utf8'));
64
+ }
65
+ catch {
66
+ return null;
67
+ }
68
+ if (parsed === null || typeof parsed !== 'object')
69
+ return null;
70
+ const hub = parsed.hub;
71
+ if (typeof hub !== 'string' || hub.trim() === '')
72
+ return null;
73
+ try {
74
+ return { version: 1, hub: normalizeOrigin(hub) };
75
+ }
76
+ catch {
77
+ return null;
78
+ }
79
+ }
80
+ /** Write `config` to `path`, creating its parent directory if needed. Atomic (see `writeFileAtomic`). */
81
+ export function writeGlobalConfig(path, config) {
82
+ mkdirRefusingSymlink(dirname(path));
83
+ writeFileAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
84
+ }
package/dist/src/hub.d.ts CHANGED
@@ -87,6 +87,16 @@
87
87
  * still recognizes byte-identical content and replies `unchanged: true`.
88
88
  */
89
89
  export declare function hashDefForHub(yaml: string): string;
90
+ /**
91
+ * The production hub. The sole fallback rung for every hub-resolution ladder
92
+ * in this package that has one (`src/cli.ts`'s `resolveHub` and
93
+ * `resolveSetupHub`, `src/mcp/serve.ts`'s `resolveMcpOrigin`) — there must be
94
+ * exactly one literal `'https://api.owenloop.com'` in `src/`, and this is it.
95
+ * `resolveAgentHub` (`src/cli.ts`) deliberately has NO fallback to this
96
+ * constant: it mints credentials, and silently minting on the wrong org is
97
+ * not undone by a retry.
98
+ */
99
+ export declare const DEFAULT_HUB = "https://api.owenloop.com";
90
100
  /**
91
101
  * Normalize a hub URL to a bare origin (`scheme://host[:port]`), stripping any
92
102
  * path, query, trailing slash, and fragment. Requires an http(s) scheme. This
@@ -276,12 +286,32 @@ export interface Keychain {
276
286
  set(service: string, account: string, value: string): void;
277
287
  delete(service: string, account: string): void;
278
288
  }
289
+ /** Minimal command seam for the macOS `security` adapter. */
290
+ export interface MacosSecurityCommand {
291
+ args: string[];
292
+ /** Secret-bearing command input. Never include this value in an error. */
293
+ input?: string;
294
+ captureStdout?: boolean;
295
+ }
296
+ export type MacosSecurityRunner = (command: MacosSecurityCommand) => string;
297
+ /**
298
+ * Build the macOS generic-password backend around an injectable `security`
299
+ * command runner. Status 44 (`errSecItemNotFound`) alone means absence. Every
300
+ * other exit, signal, or start failure is a stable, secret-free error.
301
+ */
302
+ export declare function macosKeychain(runner?: MacosSecurityRunner): Keychain;
303
+ /**
304
+ * Every locally available Keychain backend, independent of the ordinary-store
305
+ * override. Defensive logout uses this resolver so `OWENLOOP_NO_KEYCHAIN=1`
306
+ * cannot hide a credential that would become authoritative again when the
307
+ * override is removed. An injected backend remains available on every platform;
308
+ * otherwise only macOS has a platform backend.
309
+ */
310
+ export declare function resolveLocalKeychain(injected?: Keychain): Keychain | undefined;
279
311
  /**
280
- * The default macOS keychain backend (generic passwords under service
281
- * `owenloop:<origin>`, account = the credential slot). The secret is fed through
282
- * the `security -i` command stream on stdin, never as a `-w` argv value, so it
283
- * never appears in `ps`/shell history. Returns `undefined` off macOS or when
284
- * `OWENLOOP_NO_KEYCHAIN=1`, so callers fall back to the 0600 credential file.
312
+ * The default Keychain selected for ordinary reads and writes. Returns
313
+ * `undefined` off macOS or when `OWENLOOP_NO_KEYCHAIN=1` selects the 0600 file
314
+ * store. Logout deliberately uses `resolveLocalKeychain` instead.
285
315
  */
286
316
  export declare function defaultKeychain(env: Record<string, string | undefined>): Keychain | undefined;
287
317
  /**
@@ -380,24 +410,48 @@ export type ReadStoredCredentialOpts = CredentialSlotSelector & {
380
410
  * never `process.env` directly, so a caller passing `opts.env` stays hermetic;
381
411
  * only the top-level default falls back to `process.env`.
382
412
  *
383
- * **When `OWENLOOP_CREDENTIAL_COMMAND` is configured this function can THROW
384
- * instead of returning `null`**, and it does not consult a store at all. The
385
- * command is authoritative, so a nonzero exit, a timeout, empty output, or
386
- * output that is not a well-formed credential is a loud error naming the origin
387
- * and the slot — never a silent fallthrough to a stale local entry. See
388
- * `runCredentialCommand`. When it is NOT configured, behaviour is exactly what
389
- * it has always been.
413
+ * **An authoritative backend failure throws instead of returning `null`.** For
414
+ * `OWENLOOP_CREDENTIAL_COMMAND`, a nonzero exit, timeout, empty output, or
415
+ * malformed credential is a loud error naming the origin and slot. For the
416
+ * macOS Keychain, every `security` failure except status 44 is a stable,
417
+ * secret-free error. Neither backend falls through to a stale file entry.
390
418
  */
391
419
  export declare function readStoredCredential(origin: string, opts: ReadStoredCredentialOpts): Credential | null;
392
420
  /**
393
421
  * Enumerate the hub origins that have a usable `human` credential stored, or
394
422
  * `null` when the active backend cannot be enumerated.
395
423
  *
396
- * Consumer: `owenloop mcp`'s origin inference (`resolveMcpOrigin` in
397
- * `src/mcp/serve.ts`). When the host spawns the server with neither `--hub` nor
398
- * `OWENLOOP_HUB`, the server tries to infer the single hub the user is logged
399
- * in to. That inference is only sound on the FILE backend, which can list its
400
- * `hubs` map; the keychain and external-command backends cannot enumerate:
424
+ * Callers in `src/cli.ts` share a backend-aware discovery layer, while
425
+ * `src/mcp/serve.ts` consumes this fact directly. Their policies deliberately
426
+ * differ, turning the same three possible results (`null`, `[]`, length>1)
427
+ * into different outcomes:
428
+ *
429
+ * - `resolveAgentHub` (`agent new`, `capability bind|unbind|list`, and
430
+ * `crew`'s subcommands) — mutating, mint-like commands. Every non-single
431
+ * result (`null`, `[]`, or length>1) is an immediate `CliError` (exit 2)
432
+ * naming `--hub <origin>` as the fix. There is no `DEFAULT_HUB` fallback
433
+ * here at all: silently minting against the production hub while the
434
+ * operator is logged into a dev hub would mint on the wrong org, and a mint
435
+ * is not undone by a retry.
436
+ * - `resolveSetupHub` (`setup`, `doctor`) — `null` or `[]` fall back to
437
+ * `DEFAULT_HUB` with a printed notice so the operator can see what
438
+ * happened; length>1 is still a `CliError` (exit 2) naming the origins,
439
+ * because guessing among several logged-in hubs would be silently wrong for
440
+ * someone who has more than one.
441
+ * - `resolvePublishingHub` (`connect`, `push`, `publish`) — one file-backed
442
+ * origin is the global fallback; more than one or none is an exit-2 error.
443
+ * For `null`, and only for `null`, this policy may use the validated
444
+ * execution-settings `hubOrigin` after checking the requested credential
445
+ * slot. It never guesses `DEFAULT_HUB`.
446
+ * - `resolveMcpOrigin` (`owenloop mcp`'s origin ladder) — the most lenient:
447
+ * this is rung 4 of 5, tried only after `--hub`, `OWENLOOP_HUB`, and
448
+ * `~/.owenloop/config.json` have all had nothing to offer. `null`, `[]`,
449
+ * and length>1 are ALL just "this rung has nothing to offer either" and
450
+ * fall through silently to rung 5 (`DEFAULT_HUB`) — there is no error path
451
+ * left to reach from here.
452
+ *
453
+ * The backend determines whether enumeration is even possible in the first
454
+ * place, independent of which of the three callers is asking:
401
455
  *
402
456
  * - **file** → the origins in `readCredentialFile(credentialFilePath(env)).hubs`
403
457
  * whose `human` slot parses as a well-formed `Credential` (`parseCredential`).
@@ -412,10 +466,10 @@ export declare function readStoredCredential(origin: string, opts: ReadStoredCre
412
466
  * - **external** → `null`, for the same reason: the command answers a single
413
467
  * `(origin, slot)` query; it has no listing contract.
414
468
  *
415
- * `null` (cannot enumerate), `[]` (nothing stored), and a length>1 result are
416
- * all distinct signals the caller turns into tailored exit-2 messages — this
417
- * function reports the fact, it never decides the outcome. It never logs or
418
- * echoes any credential; only the origin KEYS (never secrets) are returned.
469
+ * This function only reports the fact (and the backend-level reason behind
470
+ * it); it never decides the outcome — that is each caller's job, per the list
471
+ * above. It never logs or echoes any credential; only the origin KEYS (never
472
+ * secrets) are returned.
419
473
  *
420
474
  * `env`/`keychain` are threaded exactly as `readStoredCredential` threads them,
421
475
  * so a caller passing a fixture `env` stays hermetic.
@@ -633,28 +687,38 @@ export interface CapabilityRouteWire {
633
687
  /**
634
688
  * `POST /api/add_capability_route`'s 200 body, narrowed.
635
689
  *
636
- * NESTED exactly as the wire nests it: the row lives under `route`, while
637
- * `alreadyRouted` and `routedCrewCount` live at the BODY's top level. A flat
690
+ * THE FIELD NAMES ARE THE HUB'S, NOT THIS CLI'S. The hub verb
691
+ * (`hub-core/src/verbs/manage-capability-routes.ts`) returns `binding`,
692
+ * `alreadyBound` and `boundCrewCount`; it does NOT return `route`,
693
+ * `alreadyRouted` or `routedCrewCount`, which is what this narrower demanded
694
+ * until now — so `capability bind` failed against every live hub with
695
+ * `malformed success response — missing route`. Both repos migrated their
696
+ * routing vocabulary on the same day and disagreed on the payload names. The
697
+ * hub is the server of record, so the client mirrors it verbatim: an operator
698
+ * correlating stdout against the hub's audit log never has to translate.
699
+ *
700
+ * NESTED exactly as the wire nests it: the row lives under `binding`, while
701
+ * `alreadyBound` and `boundCrewCount` live at the BODY's top level. A flat
638
702
  * interface would blur where each field actually sits.
639
703
  *
640
- * - `alreadyRouted` — was this exact `(capability, crew)` pair already present? The add
704
+ * - `alreadyBound` — was this exact `(capability, crew)` pair already present? The add
641
705
  * is ADDITIVE and idempotent per pair, so a repeat is a 200 no-op, not an
642
- * error, and `route.createdBy`/`createdAt` then echo the ORIGINAL row.
643
- * - `routedCrewCount` — how many **LIVE** crews the capability binds AFTER the write. A
706
+ * error, and `binding.createdBy`/`createdAt` then echo the ORIGINAL row.
707
+ * - `boundCrewCount` — how many **LIVE** crews the capability binds AFTER the write. A
644
708
  * route whose crew row was deleted routes nothing and is not counted.
645
709
  */
646
710
  export interface CapabilityRouteAddedWire {
647
- route: CapabilityRouteWire;
648
- alreadyRouted: boolean;
649
- routedCrewCount: number;
711
+ binding: CapabilityRouteWire;
712
+ alreadyBound: boolean;
713
+ boundCrewCount: number;
650
714
  }
651
715
  /**
652
716
  * Narrow `POST /api/add_capability_route`'s 200 body
653
- * (`{ text, route, alreadyRouted, routedCrewCount }`). Throws on anything
717
+ * (`{ text, binding, alreadyBound, boundCrewCount }`). Throws on anything
654
718
  * malformed, naming the offending FIELD only — same discipline as
655
719
  * `asAgentIdentities`, so no body value is echoed.
656
720
  *
657
- * `route.crewName` is required to be a NON-NULL non-empty string here, on top
721
+ * `binding.crewName` is required to be a NON-NULL non-empty string here, on top
658
722
  * of `asCapabilityRouteRow`'s lenient check. That is not a contradiction: an add
659
723
  * resolves its crew BY NAME, so the crew is live by construction and a `null`
660
724
  * name in THIS response is genuinely malformed — whereas a `null` name in a
@@ -701,10 +765,16 @@ export declare function asCapabilityRouteRemoved(body: unknown): {
701
765
  remainingCrewIds: string[];
702
766
  };
703
767
  /**
704
- * Narrow `GET /api/capability_routes`'s 200 body (`{ text, routes: [...] }`) to a
768
+ * Narrow `GET /api/capability_routes`'s 200 body (`{ text, bindings: [...] }`) to a
705
769
  * typed array. An EMPTY array is valid — that is the "this org has no routes
706
770
  * yet" case, not an error.
707
771
  *
772
+ * THE ARRAY KEY IS `bindings`, WHICH IS THE HUB'S NAME — the endpoint PATH is
773
+ * `capability_routes` but its payload key is not. This narrower demanded
774
+ * `routes` until now, so `capability list` failed against every live hub with
775
+ * `malformed response — expected a \`routes\` array` even on a perfectly good
776
+ * 200. See `CapabilityRouteAddedWire` for why the client mirrors the hub.
777
+ *
708
778
  * Rows are plain `CapabilityRouteWire`, ONE per `(capability, crew)` pair ordered by
709
779
  * `capability, crew_id`, so a capability bound to many crews yields MANY rows — the array
710
780
  * is forwarded as-is and must never be collapsed into a per-capability map. A row