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
@@ -65,6 +65,7 @@
65
65
  import { existsSync } from 'node:fs';
66
66
  import { ResumeUnavailableError } from "./contract.js";
67
67
  import { register } from "./registry.js";
68
+ import { normalizeStepPermissions, validateHarnessOptions } from "./permissions.js";
68
69
  import { ADMITTED_OWENLOOP_KEYS, filterOwenloopEnv } from "./child-env.js";
69
70
  import { JsonRpcError, startStdioRpc } from "./jsonrpc-stdio.js";
70
71
  /** The adapter id. Matches the `"codex"` key in `harness-versions.json`, so the
@@ -132,27 +133,79 @@ const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-acce
132
133
  * adapter's call.
133
134
  */
134
135
  const DEFAULT_SANDBOX = 'workspace-write';
135
- /**
136
- * `AskForApproval` values this adapter passes through untouched (the server's
137
- * own vocabulary). Anything else maps to `'never'`.
138
- */
136
+ /** `AskForApproval` values this adapter passes through untouched. */
139
137
  const NATIVE_APPROVAL_POLICIES = new Set(['untrusted', 'on-request', 'never']);
140
- /**
141
- * `permissionMode` → `approvalPolicy`.
142
- *
143
- * `'never'` is the default for everything unrecognized, and that is a decision:
144
- * this runs headless with no human on the other end, so any policy that can
145
- * raise a `requestApproval` server request converts a stalled approval into an
146
- * order that hangs past the worker's lease. The adapter still answers those
147
- * requests defensively (see `handleServerRequest`) — belt and braces, because
148
- * `approvalPolicy` does not govern every request kind.
149
- */
138
+ const UNRESTRICTED_SANDBOX = 'danger-full-access';
139
+ function unsupportedFilesystemMessage(filesystem) {
140
+ return (`filesystem '${filesystem}' is unsupported by this adapter because Codex app-server ` +
141
+ 'configuration layers are outside the thread sandbox');
142
+ }
143
+ const UNSUPPORTED_MAX_TURNS_MESSAGE = 'maxTurns is unsupported by this adapter because Codex app-server has no thread or turn limit parameter';
144
+ function codexPreflight(permissions) {
145
+ const issues = [];
146
+ if (permissions.maxTurns !== undefined) {
147
+ issues.push({ field: 'maxTurns', message: UNSUPPORTED_MAX_TURNS_MESSAGE });
148
+ }
149
+ if (permissions.filesystem === 'read-only' || permissions.filesystem === 'workspace-write') {
150
+ issues.push({
151
+ field: 'filesystem',
152
+ message: unsupportedFilesystemMessage(permissions.filesystem),
153
+ });
154
+ }
155
+ if (permissions.tools !== undefined) {
156
+ issues.push({ field: 'tools', message: 'tool allow-lists are unsupported by this adapter' });
157
+ }
158
+ if (permissions.disallowedTools !== undefined) {
159
+ issues.push({ field: 'disallowedTools', message: 'tool deny-lists are unsupported by this adapter' });
160
+ }
161
+ if (permissions.network === 'owenloop-only') {
162
+ issues.push({
163
+ field: 'network',
164
+ message: "network 'owenloop-only' is unsupported by this adapter",
165
+ });
166
+ }
167
+ if (permissions.filesystem === undefined &&
168
+ permissions.network === 'unrestricted' &&
169
+ permissions.extensions['sandbox'] === 'read-only') {
170
+ issues.push({
171
+ field: 'network',
172
+ message: "network 'unrestricted' cannot be enabled with sandbox 'read-only'; " +
173
+ "use sandbox 'workspace-write' or 'danger-full-access'",
174
+ });
175
+ }
176
+ if (permissions.permissionMode !== undefined &&
177
+ !NATIVE_APPROVAL_POLICIES.has(permissions.permissionMode)) {
178
+ issues.push({
179
+ field: 'permissionMode',
180
+ message: `permissionMode must be one of ${[...NATIVE_APPROVAL_POLICIES].join('|')}`,
181
+ });
182
+ }
183
+ const sandbox = permissions.extensions['sandbox'];
184
+ if (sandbox !== undefined && (typeof sandbox !== 'string' || !SANDBOX_MODES.has(sandbox))) {
185
+ issues.push({
186
+ field: 'sandbox',
187
+ message: `sandbox must be one of ${[...SANDBOX_MODES].join('|')}`,
188
+ });
189
+ }
190
+ if (permissions.filesystem === 'unrestricted' &&
191
+ typeof sandbox === 'string' &&
192
+ SANDBOX_MODES.has(sandbox) &&
193
+ UNRESTRICTED_SANDBOX !== sandbox) {
194
+ issues.push({
195
+ field: 'sandbox',
196
+ message: `sandbox '${sandbox}' conflicts with filesystem 'unrestricted' ` +
197
+ `(which requires '${UNRESTRICTED_SANDBOX}')`,
198
+ });
199
+ }
200
+ return issues;
201
+ }
202
+ /** `permissionMode` → `approvalPolicy`, with no invalid-value fallback. */
150
203
  function toApprovalPolicy(mode) {
151
204
  if (mode === undefined)
152
205
  return 'never';
153
206
  if (NATIVE_APPROVAL_POLICIES.has(mode))
154
207
  return mode;
155
- return 'never';
208
+ throw new Error(`permissionMode must be one of ${[...NATIVE_APPROVAL_POLICIES].join('|')}`);
156
209
  }
157
210
  function isPlainMap(v) {
158
211
  return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -221,8 +274,9 @@ function owenloopMount(mcp) {
221
274
  * Deliberately unmapped, so a reader sees intent rather than oversight:
222
275
  * - `permissions.tools` / `permissions.disallowedTools`: 0.146.0 has no
223
276
  * per-thread built-in-tool allow-list; the sandbox and the approval policy
224
- * are the levers it does have.
277
+ * are the levers it does have. Adapter preflight refuses both fields.
225
278
  * - `permissions.maxTurns`: no `thread/start` or `turn/start` equivalent.
279
+ * Adapter preflight and this direct-call boundary both refuse the field.
226
280
  * - `permissions.effort`: not a `ThreadStartParams` field — it is a
227
281
  * `turn/start` param, so it lands in `buildTurnStartParams`.
228
282
  * - every `extensions` key other than `mcpServers`, `codexConfig` and
@@ -232,7 +286,18 @@ function owenloopMount(mcp) {
232
286
  * gets warned about.
233
287
  */
234
288
  export function buildThreadStartParams(args, onEvent) {
289
+ // Retained for source compatibility with callers that previously received
290
+ // fallback diagnostics. Invalid explicit policy now throws instead.
291
+ void onEvent;
292
+ if (args.permissions.maxTurns !== undefined) {
293
+ throw new Error(UNSUPPORTED_MAX_TURNS_MESSAGE);
294
+ }
235
295
  const ext = args.permissions.extensions;
296
+ const sandbox = resolveSandbox(args.permissions);
297
+ if (args.permissions.network === 'unrestricted' && sandbox === 'read-only') {
298
+ throw new Error("network 'unrestricted' cannot be enabled with sandbox 'read-only'; " +
299
+ "use sandbox 'workspace-write' or 'danger-full-access'");
300
+ }
236
301
  // The escape hatch: any other config key, without re-opening the contract.
237
302
  // `mcp_servers` is merged in AFTER it, so the owenloop mount always wins.
238
303
  const extraConfig = isPlainMap(ext['codexConfig']) ? { ...ext['codexConfig'] } : {};
@@ -247,19 +312,18 @@ export function buildThreadStartParams(args, onEvent) {
247
312
  [OWENLOOP_MCP_NAME]: owenloopMount(args.owenloopMcp),
248
313
  };
249
314
  const config = { ...extraConfig, mcp_servers: mcpServers };
315
+ if (args.permissions.network === 'unrestricted' && sandbox === 'workspace-write') {
316
+ const authored = isPlainMap(config['sandbox_workspace_write'])
317
+ ? config['sandbox_workspace_write']
318
+ : {};
319
+ config['sandbox_workspace_write'] = { ...authored, network_access: true };
320
+ }
250
321
  const params = {
251
322
  cwd: args.cwd,
252
323
  config,
253
324
  approvalPolicy: toApprovalPolicy(args.permissions.permissionMode),
254
- sandbox: resolveSandbox(ext['sandbox'], onEvent),
325
+ sandbox,
255
326
  };
256
- if (args.permissions.permissionMode !== undefined &&
257
- !NATIVE_APPROVAL_POLICIES.has(args.permissions.permissionMode)) {
258
- onEvent?.({
259
- kind: 'progress',
260
- text: `permissionMode '${args.permissions.permissionMode}' has no approval-policy equivalent; using 'never'`,
261
- });
262
- }
263
327
  // Phase 1's precedence rule, verbatim: the per-start override beats the
264
328
  // normalized step-def value. Omit the KEY entirely when neither is set —
265
329
  // sending `model: null` would pin the thread to a null model rather than
@@ -269,17 +333,26 @@ export function buildThreadStartParams(args, onEvent) {
269
333
  params['model'] = model;
270
334
  return params;
271
335
  }
272
- /** Validate an `extensions.sandbox` override, dropping anything illegal loudly. */
273
- function resolveSandbox(raw, onEvent) {
336
+ /** Resolve supported neutral filesystem policy, then the legacy adapter override. */
337
+ function resolveSandbox(permissions) {
338
+ if (permissions.filesystem === 'read-only' || permissions.filesystem === 'workspace-write') {
339
+ throw new Error(unsupportedFilesystemMessage(permissions.filesystem));
340
+ }
341
+ if (permissions.filesystem === 'unrestricted') {
342
+ const mapped = UNRESTRICTED_SANDBOX;
343
+ const raw = permissions.extensions['sandbox'];
344
+ if (raw !== undefined && raw !== mapped) {
345
+ throw new Error(`sandbox '${String(raw)}' conflicts with filesystem 'unrestricted' ` +
346
+ `(which requires '${mapped}')`);
347
+ }
348
+ return mapped;
349
+ }
350
+ const raw = permissions.extensions['sandbox'];
274
351
  if (raw === undefined)
275
352
  return DEFAULT_SANDBOX;
276
353
  if (typeof raw === 'string' && SANDBOX_MODES.has(raw))
277
354
  return raw;
278
- onEvent?.({
279
- kind: 'progress',
280
- text: `ignoring unrecognized sandbox '${String(raw)}'; using '${DEFAULT_SANDBOX}'`,
281
- });
282
- return DEFAULT_SANDBOX;
355
+ throw new Error(`sandbox must be one of ${[...SANDBOX_MODES].join('|')}`);
283
356
  }
284
357
  /**
285
358
  * Build the `turn/start` params. PURE — exported for tests.
@@ -306,9 +379,9 @@ export function buildTurnStartParams(threadId, text, effort) {
306
379
  * `sandbox`, `model` and `config`, and a resumed thread that does not re-supply
307
380
  * them reverts to the server's defaults.
308
381
  *
309
- * PHASE 4 CLOSED CONTRACT OBSERVATION 1. `deliver`'s third argument used to carry
310
- * only `cwd` and `owenloopMcp`, so a resume in a different process from the start
311
- * (the normal case for a re-offered step) had nothing to rebuild `approvalPolicy`
382
+ * PHASE 4 CLOSED CONTRACT OBSERVATION 1. `deliver`'s third argument originally
383
+ * carried only `cwd` and `owenloopMcp`, so a resume in a different process from
384
+ * the start had nothing to rebuild `approvalPolicy`
312
385
  * / `sandbox` / `model` from and silently reverted to server defaults. It now
313
386
  * carries the normalized `StepPermissions`, so this function derives the SAME
314
387
  * params `buildThreadStartParams` would, and `args` WINS over `base` on every
@@ -758,9 +831,61 @@ async function runTurn(client, gate, params) {
758
831
  // `turn/completed` that already settled the gate.
759
832
  await Promise.all([client.request('turn/start', params, TURN_START_TIMEOUT_MS), gate.promise]);
760
833
  }
834
+ const KNOWN_FIELDS = new Set([
835
+ 'name',
836
+ 'description',
837
+ 'tools',
838
+ 'disallowedTools',
839
+ 'filesystem',
840
+ 'network',
841
+ 'permissionMode',
842
+ 'maxTurns',
843
+ 'model',
844
+ 'effort',
845
+ 'sandbox',
846
+ 'mcpServers',
847
+ 'codexConfig',
848
+ ]);
849
+ function lintStep(bag, step) {
850
+ const findings = [
851
+ ...validateHarnessOptions(bag, step),
852
+ ...codexPreflight(normalizeStepPermissions(bag)).map((issue) => ({
853
+ severity: 'error',
854
+ step,
855
+ message: issue.message,
856
+ ...(issue.field !== undefined ? { field: issue.field } : {}),
857
+ })),
858
+ ];
859
+ const error = (field, message) => {
860
+ findings.push({ severity: 'error', step, field, message });
861
+ };
862
+ const warning = (field, message) => {
863
+ findings.push({ severity: 'warning', step, field, message });
864
+ };
865
+ for (const key of Object.keys(bag)) {
866
+ if (!KNOWN_FIELDS.has(key)) {
867
+ warning(key, `unknown field '${key}' — known fields: ${[...KNOWN_FIELDS].join(', ')}`);
868
+ }
869
+ }
870
+ for (const field of ['mcpServers', 'codexConfig']) {
871
+ if (field in bag && !isPlainMap(bag[field]))
872
+ error(field, `${field} must be a map`);
873
+ }
874
+ if (isPlainMap(bag['mcpServers']) && 'owenloop' in bag['mcpServers']) {
875
+ warning('mcpServers', 'mcpServers.owenloop is reserved and is replaced by the worker at start');
876
+ }
877
+ if (isPlainMap(bag['codexConfig']) &&
878
+ isPlainMap(bag['codexConfig']['mcp_servers']) &&
879
+ 'owenloop' in bag['codexConfig']['mcp_servers']) {
880
+ warning('codexConfig', 'codexConfig.mcp_servers.owenloop is reserved and is replaced by the worker at start');
881
+ }
882
+ return findings;
883
+ }
761
884
  export const codexAdapter = {
762
885
  id: HARNESS_ID,
763
886
  resumeTier: 'native-token',
887
+ preflight: codexPreflight,
888
+ lintStep,
764
889
  /**
765
890
  * The command a human runs to re-open this thread in an interactive terminal.
766
891
  *
@@ -816,12 +941,6 @@ export const codexAdapter = {
816
941
  return ref;
817
942
  },
818
943
  async deliver(ref, message, args, onEvent) {
819
- // A rollout records its cwd; a vanished worktree cannot host the resumed
820
- // turn, and finding that out from the server takes a spawn plus a handshake.
821
- if (!existsSync(args.cwd)) {
822
- throw new ResumeUnavailableError(`resume cwd no longer exists: ${args.cwd}`);
823
- }
824
- const gate = createTurnGate(onEvent);
825
944
  const previous = SESSIONS.get(ref.token);
826
945
  // PHASE 4: the map is no longer the source of truth for thread configuration.
827
946
  // `args.permissions` is, and `buildThreadResumeParams` maps it. `startParams`
@@ -829,6 +948,16 @@ export const codexAdapter = {
829
948
  // miss is now an ordinary cross-process resume rather than a degraded one —
830
949
  // which is why the "minimal thread configuration" warning is gone.
831
950
  const startParams = previous?.startParams;
951
+ // Match cold start: validate all thread configuration before checking the
952
+ // worktree, disposing an existing session, or spawning a replacement
953
+ // app-server. Unsupported policy is the first direct-call boundary.
954
+ const resumeParams = buildThreadResumeParams(ref.token, args, startParams, onEvent);
955
+ // A rollout records its cwd; a vanished worktree cannot host the resumed
956
+ // turn, and finding that out from the server takes a spawn plus a handshake.
957
+ if (!existsSync(args.cwd)) {
958
+ throw new ResumeUnavailableError(`resume cwd no longer exists: ${args.cwd}`);
959
+ }
960
+ const gate = createTurnGate(onEvent);
832
961
  if (previous !== undefined) {
833
962
  // ALWAYS a fresh app-server, even when this process still holds a live one.
834
963
  // A live client's notifications are bound to the gate it was opened with,
@@ -839,7 +968,6 @@ export const codexAdapter = {
839
968
  await previous.client.dispose();
840
969
  }
841
970
  const { client, reportExit } = await openClient(args.cwd, onEvent, gate);
842
- const resumeParams = buildThreadResumeParams(ref.token, args, startParams, onEvent);
843
971
  try {
844
972
  await client.request('thread/resume', resumeParams, SETUP_TIMEOUT_MS);
845
973
  }
@@ -86,13 +86,18 @@ export type AgentEvent = {
86
86
  *
87
87
  * Produced by `normalizeStepPermissions` (`./permissions.ts`).
88
88
  */
89
+ export type FilesystemPermission = 'read-only' | 'workspace-write' | 'unrestricted';
90
+ export type NetworkPermission = 'owenloop-only' | 'unrestricted';
89
91
  export interface StepPermissions {
90
- /** Allowed tool names. Absent (not `[]`) when the step named none. */
92
+ /** Allowed tool names. Absent when the step named no allow-list; `[]` means no built-in tools. */
91
93
  tools?: string[];
92
- /** Denied tool names. Absent (not `[]`) when the step named none. */
94
+ /** Denied tool names. Absent when the step named no deny-list; an explicit `[]` is preserved. */
93
95
  disallowedTools?: string[];
94
- /** Opaque, passed through verbatim; each adapter maps it to its own
95
- * vocabulary. Not validated here — `owenloop work lint` already validates the bag. */
96
+ /** Filesystem authority requested by the workflow definition. */
97
+ filesystem?: FilesystemPermission;
98
+ /** Network authority requested by the workflow definition. */
99
+ network?: NetworkPermission;
100
+ /** Opaque adapter permission mode. Each adapter validates its own vocabulary. */
96
101
  permissionMode?: string;
97
102
  /** Only ever a positive integer; anything else was dropped in normalization. */
98
103
  maxTurns?: number;
@@ -103,6 +108,12 @@ export interface StepPermissions {
103
108
  * no adapter needs a null check. */
104
109
  extensions: Record<string, unknown>;
105
110
  }
111
+ /** One fail-closed adapter preflight refusal. */
112
+ export interface PermissionIssue {
113
+ /** The normalized permission field or extension key responsible, when one exists. */
114
+ field?: string;
115
+ message: string;
116
+ }
106
117
  /** Everything an adapter needs to launch one step agent. */
107
118
  export interface StartArgs {
108
119
  /** The fully rendered step prompt. */
@@ -124,13 +135,19 @@ export interface StartArgs {
124
135
  /** Per-start override for reasoning effort. Same precedence rule as `model`. */
125
136
  effort?: string;
126
137
  /**
127
- * The stdio mount for owenloop's own work-holder MCP surface (bare
128
- * `get_order`/`submit`).
138
+ * The stdio mount for owenloop's own born-bound work-holder MCP surface. The
139
+ * default server registers `get_order`, `submit`, and `reject`. An adapter that
140
+ * enforces a restricted session may append the hold role's positive selector so
141
+ * the mounted server registers only the policy's exact subset. The command is
142
+ * the current Node executable and the first argv item is this installation's
143
+ * resolved `bin/owenloop.mjs`, so PATH cannot select a different Owenloop
144
+ * installation.
129
145
  *
130
146
  * BUILT BY THE WORKER, NOT BY AN ADAPTER: `src/agent/brief.ts` constructs the
131
147
  * born-bound `hold --order <workflow>/<run> --origin <url> --as <account>
132
- * --shift=<cid> --mcp` argv from the live order. An adapter mounts it
133
- * verbatim and never constructs it — the order id, origin, and account ride
148
+ * --shift=<cid> --mcp` argv from the live order. An adapter preserves the
149
+ * born-bound command and identity arguments; an adapter may append only a
150
+ * policy-owned tool-surface selector. The order id, origin, and account ride
134
151
  * argv, never the prompt.
135
152
  */
136
153
  owenloopMcp: {
@@ -194,12 +211,20 @@ export interface HarnessAdapter {
194
211
  /** Registry key — the adapter's own harness id. Stable across versions. */
195
212
  id: string;
196
213
  resumeTier: ResumeTier;
214
+ /**
215
+ * Mandatory permission preflight. Returns every restriction this adapter cannot
216
+ * enforce exactly. The worker calls this before start or resume; a non-empty
217
+ * result means no provider process may be started.
218
+ */
219
+ preflight(permissions: StepPermissions): PermissionIssue[];
197
220
  /**
198
221
  * Launch a NEW session. Resolves at turn end with the session ref.
199
222
  *
200
- * Emits `{kind:'started', ref}` BEFORE it resolves, and the caller is
201
- * expected to persist the token on THAT event rather than on the resolve —
202
- * so a mid-turn crash still leaves a resumable record behind.
223
+ * Emits `{kind:'started', ref}` BEFORE provider work begins and before it
224
+ * resolves. The callback is a synchronous persistence gate: an adapter must
225
+ * not start delivery until the callback returns, and a thrown callback must
226
+ * abort/abandon the turn. The caller persists the token on that event so a
227
+ * mid-turn crash leaves an authoritative active record behind.
203
228
  */
204
229
  start(args: StartArgs, onEvent: (e: AgentEvent) => void): Promise<HarnessSessionRef>;
205
230
  /**
@@ -57,6 +57,7 @@ export function createFakeAdapter(spec = {}) {
57
57
  id,
58
58
  resumeTier: spec.resumeTier ?? 'native-token',
59
59
  calls,
60
+ preflight: () => [],
60
61
  async start(args, onEvent) {
61
62
  calls.push({ kind: 'start', args });
62
63
  const script = spec.start ?? EMPTY_SCRIPT;
@@ -252,6 +252,13 @@ export function startStdioRpc(opts) {
252
252
  child.stdin.on('error', (err) => opts.onStderr(`[stdin error] ${err.message}`));
253
253
  child.on('error', (err) => {
254
254
  opts.onStderr(`[spawn error] ${err.message}`);
255
+ // Node 22 emits `error` followed by `close`, but no `exit`, when the
256
+ // executable does not exist. Mark that pre-spawn failure terminal so
257
+ // `dispose()` does not wait on an `exit` event that can never arrive. Do
258
+ // not invoke `onExit`: the caller that owns the failed startup still has
259
+ // the original error and can report its safe, specific message once.
260
+ if (child.pid === undefined)
261
+ exited = true;
255
262
  core.rejectAll(err);
256
263
  });
257
264
  child.on('exit', (code, signal) => {
@@ -27,12 +27,13 @@
27
27
  * Field rules are carried over from the legacy compile layer's `KNOWN_FIELDS` /
28
28
  * `RESERVED_KEYS` / `isStringOrStringArray`; the live copies now sit in this
29
29
  * directory's per-harness adapter module (grep them there — `src/adapters/` was
30
- * deleted in Phase 5, and do not trust a line number). Six of the sixteen are
30
+ * deleted in Phase 5, and do not trust a line number). Eight of the eighteen are
31
31
  * harness-neutral and get lifted; two are reserved and are stripped; the other
32
32
  * eight have no neutral meaning and land in `extensions`, along with every key
33
33
  * the bag carries that the known list does not mention.
34
34
  */
35
- import type { StepPermissions } from './contract.ts';
35
+ import type { PermissionIssue, StepPermissions } from './contract.ts';
36
+ import type { LintFinding } from './types.ts';
36
37
  /**
37
38
  * Translate one step's bag into `StepPermissions`.
38
39
  *
@@ -50,7 +51,7 @@ import type { StepPermissions } from './contract.ts';
50
51
  * non-empty string.
51
52
  *
52
53
  * `extensions` is lossless by construction: every bag key that is neither
53
- * lifted (the six neutral fields) nor reserved (`name`/`description`) lands
54
+ * lifted (the eight neutral fields) nor reserved (`name`/`description`) lands
54
55
  * there verbatim, including keys the known-field list has never heard of. Lint
55
56
  * stays the place that warns about unknown keys.
56
57
  *
@@ -60,3 +61,15 @@ import type { StepPermissions } from './contract.ts';
60
61
  export declare function normalizeStepPermissions(bag: Record<string, unknown> | undefined, step?: {
61
62
  model?: string;
62
63
  }): StepPermissions;
64
+ /**
65
+ * Validate the reserved, harness-neutral `x.harness` fields before normalization.
66
+ * Unknown keys remain opaque and produce no finding here.
67
+ */
68
+ export declare function validateHarnessOptions(bag: Record<string, unknown>, step: string): LintFinding[];
69
+ /**
70
+ * Validate a normalized permission object at the final dispatch boundary.
71
+ * The stale-extension check catches caches produced before filesystem/network
72
+ * became first-class restrictions; running such a cache would silently ignore
73
+ * the authored restriction.
74
+ */
75
+ export declare function preflightStepPermissions(permissions: StepPermissions): PermissionIssue[];
@@ -1,5 +1,17 @@
1
- /** The six fields with a harness-neutral meaning — lifted out of the bag. */
2
- const NEUTRAL_KEYS = ['tools', 'disallowedTools', 'permissionMode', 'maxTurns', 'model', 'effort'];
1
+ /** Fields with a harness-neutral meaning — lifted out of the bag. */
2
+ const NEUTRAL_KEYS = [
3
+ 'tools',
4
+ 'disallowedTools',
5
+ 'filesystem',
6
+ 'network',
7
+ 'permissionMode',
8
+ 'maxTurns',
9
+ 'model',
10
+ 'effort',
11
+ ];
12
+ const FILESYSTEM_VALUES = new Set(['read-only', 'workspace-write', 'unrestricted']);
13
+ const NETWORK_VALUES = new Set(['owenloop-only', 'unrestricted']);
14
+ const STALE_RESTRICTION_KEYS = ['filesystem', 'network'];
3
15
  /** Generated/reserved frontmatter keys. Stripped: an adapter must never see an
4
16
  * author's attempt at them. They do NOT reach `extensions`. */
5
17
  const RESERVED_KEYS = ['name', 'description'];
@@ -12,21 +24,17 @@ function isPlainMap(v) {
12
24
  * Normalize a tool list. The bag legitimately accepts EITHER a comma-separated
13
25
  * string or a string array. A string is split on `,` with each entry trimmed and
14
26
  * empties dropped; an array is copied with non-string entries dropped. Returns
15
- * `undefined` when nothing survives, so the key is ABSENT rather than `[]` —
16
- * "no `tools` key" and "an empty allow-list" mean different things to a harness.
27
+ * `[]` when the field was explicitly present but names no tools. This preserves
28
+ * the security-relevant distinction between an absent allow-list and `tools: []`.
17
29
  */
18
30
  function toolList(v) {
19
- let out;
20
31
  if (typeof v === 'string') {
21
- out = v.split(',').map((s) => s.trim()).filter((s) => s !== '');
32
+ return v.split(',').map((s) => s.trim()).filter((s) => s !== '');
22
33
  }
23
- else if (Array.isArray(v)) {
24
- out = v.filter((e) => typeof e === 'string' && e !== '');
34
+ if (Array.isArray(v)) {
35
+ return v.filter((e) => typeof e === 'string' && e !== '');
25
36
  }
26
- else {
27
- return undefined;
28
- }
29
- return out.length > 0 ? out : undefined;
37
+ return undefined;
30
38
  }
31
39
  /** A non-empty string, verbatim and unvalidated; otherwise `undefined`. */
32
40
  function nonEmptyString(v) {
@@ -54,7 +62,7 @@ function positiveInt(v) {
54
62
  * non-empty string.
55
63
  *
56
64
  * `extensions` is lossless by construction: every bag key that is neither
57
- * lifted (the six neutral fields) nor reserved (`name`/`description`) lands
65
+ * lifted (the eight neutral fields) nor reserved (`name`/`description`) lands
58
66
  * there verbatim, including keys the known-field list has never heard of. Lint
59
67
  * stays the place that warns about unknown keys.
60
68
  *
@@ -76,6 +84,12 @@ export function normalizeStepPermissions(bag, step) {
76
84
  const disallowedTools = toolList(src['disallowedTools']);
77
85
  if (disallowedTools !== undefined)
78
86
  out.disallowedTools = disallowedTools;
87
+ if (typeof src['filesystem'] === 'string' && FILESYSTEM_VALUES.has(src['filesystem'])) {
88
+ out.filesystem = src['filesystem'];
89
+ }
90
+ if (typeof src['network'] === 'string' && NETWORK_VALUES.has(src['network'])) {
91
+ out.network = src['network'];
92
+ }
79
93
  const permissionMode = nonEmptyString(src['permissionMode']);
80
94
  if (permissionMode !== undefined)
81
95
  out.permissionMode = permissionMode;
@@ -91,3 +105,78 @@ export function normalizeStepPermissions(bag, step) {
91
105
  out.effort = effort;
92
106
  return out;
93
107
  }
108
+ function typeName(v) {
109
+ if (v === null)
110
+ return 'null';
111
+ if (Array.isArray(v))
112
+ return 'array';
113
+ return typeof v;
114
+ }
115
+ function isStringOrStringArray(v) {
116
+ return typeof v === 'string' || (Array.isArray(v) && v.every((entry) => typeof entry === 'string'));
117
+ }
118
+ /**
119
+ * Validate the reserved, harness-neutral `x.harness` fields before normalization.
120
+ * Unknown keys remain opaque and produce no finding here.
121
+ */
122
+ export function validateHarnessOptions(bag, step) {
123
+ const findings = [];
124
+ const error = (field, message) => {
125
+ findings.push({ severity: 'error', step, field, message });
126
+ };
127
+ const check = (field, ok, expected) => {
128
+ if (field in bag && !ok(bag[field])) {
129
+ error(field, `${field} must be ${expected}, got ${typeName(bag[field])}`);
130
+ }
131
+ };
132
+ check('tools', isStringOrStringArray, 'a string or string[]');
133
+ check('disallowedTools', isStringOrStringArray, 'a string or string[]');
134
+ check('permissionMode', (v) => typeof v === 'string' && v !== '', 'a non-empty string');
135
+ check('model', (v) => typeof v === 'string' && v !== '', 'a non-empty string');
136
+ check('effort', (v) => typeof v === 'string' && v !== '', 'a non-empty string');
137
+ check('maxTurns', (v) => typeof v === 'number' && Number.isInteger(v) && v > 0, 'a positive integer');
138
+ for (const key of RESERVED_KEYS) {
139
+ if (key in bag)
140
+ error(key, `'${key}' is generated and cannot be set in the bag`);
141
+ }
142
+ if ('filesystem' in bag && !FILESYSTEM_VALUES.has(bag['filesystem'])) {
143
+ error('filesystem', `filesystem must be one of ${[...FILESYSTEM_VALUES].join('|')}`);
144
+ }
145
+ if ('network' in bag && !NETWORK_VALUES.has(bag['network'])) {
146
+ error('network', `network must be one of ${[...NETWORK_VALUES].join('|')}`);
147
+ }
148
+ if (isStringOrStringArray(bag['tools']) && isStringOrStringArray(bag['disallowedTools'])) {
149
+ const allowed = new Set(toolList(bag['tools']) ?? []);
150
+ const denied = new Set(toolList(bag['disallowedTools']) ?? []);
151
+ const overlap = [...allowed].filter((tool) => denied.has(tool)).sort();
152
+ if (overlap.length > 0) {
153
+ error('tools', `tools and disallowedTools overlap: ${overlap.join(', ')}`);
154
+ }
155
+ }
156
+ return findings;
157
+ }
158
+ /**
159
+ * Validate a normalized permission object at the final dispatch boundary.
160
+ * The stale-extension check catches caches produced before filesystem/network
161
+ * became first-class restrictions; running such a cache would silently ignore
162
+ * the authored restriction.
163
+ */
164
+ export function preflightStepPermissions(permissions) {
165
+ const issues = [];
166
+ const overlap = (permissions.tools ?? [])
167
+ .filter((tool) => (permissions.disallowedTools ?? []).includes(tool))
168
+ .sort();
169
+ if (overlap.length > 0) {
170
+ issues.push({ field: 'tools', message: `tools and disallowedTools overlap: ${overlap.join(', ')}` });
171
+ }
172
+ for (const key of STALE_RESTRICTION_KEYS) {
173
+ if (key in permissions.extensions) {
174
+ issues.push({
175
+ field: key,
176
+ message: `restriction '${key}' is buried in permissions.extensions from an old cache and would be ignored; ` +
177
+ 'rerun `owenloop work prepare`',
178
+ });
179
+ }
180
+ }
181
+ return issues;
182
+ }