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
@@ -33,6 +33,7 @@
33
33
  */
34
34
  import { spawn } from 'node:child_process';
35
35
  import { createHash } from 'node:crypto';
36
+ import { PAYLOAD_MARKER, PAYLOAD_MAX_BYTES } from "./payload.js";
36
37
  const RETAIN_CAP_BYTES = 1024 * 1024; // 1 MiB retained per stream (for the tail)
37
38
  const TAIL_BYTES = 4096; // last 4 KiB of combined output kept in the receipt
38
39
  const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
@@ -41,11 +42,31 @@ const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
41
42
  * spawn, no I/O — so tests assert the shape without launching anything. POSIX
42
43
  * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
43
44
  */
44
- export function buildCommandPlan(command, cwd) {
45
+ export function buildCommandPlan(command, cwd, env) {
46
+ // Consumed values DO reach the child environment: exec/loop.ts delivers the
47
+ // order's consumed inputs as OWENLOOP_CONSUMES (or OWENLOOP_CONSUMES_FILE).
48
+ // That path inherits resolveCommand's consume-side verification gate — the
49
+ // env block is built only after `resolveCommand` returned, and that call
50
+ // refuses the whole order under `hardRule: true` on absent, unverifiable, or
51
+ // invalid consumed evidence — so no unverified dynamic value is ever placed
52
+ // here. OWENLOOP_BUNDLE_DIR is resolver-derived after the same gate and is
53
+ // not a consumed artifact value at all.
54
+ //
55
+ // Command TEXT stays uninterpolated: `command` is the authored bytes from the
56
+ // verified store, and `/bin/sh -c` expands `$OWENLOOP_CONSUMES` only where the
57
+ // authored text itself asks for it. A consumed value delivered through the
58
+ // environment block never becomes shell syntax. Any FUTURE path that puts a
59
+ // consumed value into command text or argv must re-argue that, and must
60
+ // likewise sit behind the consume-side gate.
45
61
  return {
46
62
  command: '/bin/sh',
47
63
  args: ['-c', command],
48
- options: { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] },
64
+ options: {
65
+ cwd,
66
+ detached: true,
67
+ stdio: ['ignore', 'pipe', 'pipe'],
68
+ ...(env !== undefined ? { env } : {}),
69
+ },
49
70
  };
50
71
  }
51
72
  /** Append `chunk` to a rolling tail buffer keeping only its last `cap` bytes. */
@@ -65,7 +86,7 @@ export function createDefaultRunner(opts = {}) {
65
86
  return {
66
87
  start(command, startOpts) {
67
88
  const startedAt = now();
68
- const plan = buildCommandPlan(command, startOpts.cwd);
89
+ const plan = buildCommandPlan(command, startOpts.cwd, startOpts.env);
69
90
  const hash = createHash('sha256'); // stdout-then-stderr, the ordered form
70
91
  const stderrHash = createHash('sha256'); // stderr alone — the degraded fallback
71
92
  let stdoutBytes = 0;
@@ -79,6 +100,61 @@ export function createDefaultRunner(opts = {}) {
79
100
  const pendingStderr = [];
80
101
  let pendingStderrBytes = 0;
81
102
  let degraded = false;
103
+ // Scan stdout lines independently of the bounded output tails. The
104
+ // scanner retains only the marker prefix plus the payload cap, so a
105
+ // command cannot force the runner to buffer an unbounded stream.
106
+ const payloadMarker = Buffer.from(PAYLOAD_MARKER, 'utf8');
107
+ const payloadLineCap = payloadMarker.length + PAYLOAD_MAX_BYTES + 1; // +1 detects overflow
108
+ let payloadLineBuffer = Buffer.alloc(0);
109
+ let payloadLineCapped = false;
110
+ let payloadLine;
111
+ let payloadOverCap = false;
112
+ const appendPayloadLine = (chunk) => {
113
+ if (payloadLineCapped || chunk.length === 0)
114
+ return;
115
+ const remaining = payloadLineCap - payloadLineBuffer.length;
116
+ if (chunk.length > remaining) {
117
+ payloadLineBuffer = Buffer.concat([payloadLineBuffer, chunk.subarray(0, remaining)]);
118
+ payloadLineCapped = true;
119
+ return;
120
+ }
121
+ payloadLineBuffer = Buffer.concat([payloadLineBuffer, chunk]);
122
+ };
123
+ const finishPayloadLine = () => {
124
+ if (payloadLineBuffer.length === 0)
125
+ return;
126
+ let line = payloadLineBuffer;
127
+ if (line[line.length - 1] === 0x0d)
128
+ line = line.subarray(0, line.length - 1);
129
+ if (line.length < payloadMarker.length || !line.subarray(0, payloadMarker.length).equals(payloadMarker)) {
130
+ payloadLineBuffer = Buffer.alloc(0);
131
+ payloadLineCapped = false;
132
+ return;
133
+ }
134
+ const rawPayload = line.subarray(payloadMarker.length);
135
+ if (payloadLineCapped || rawPayload.length > PAYLOAD_MAX_BYTES) {
136
+ payloadLine = undefined;
137
+ payloadOverCap = true;
138
+ }
139
+ else {
140
+ payloadLine = rawPayload.toString('utf8');
141
+ payloadOverCap = false;
142
+ }
143
+ payloadLineBuffer = Buffer.alloc(0);
144
+ payloadLineCapped = false;
145
+ };
146
+ const scanPayload = (chunk) => {
147
+ let offset = 0;
148
+ while (offset < chunk.length) {
149
+ const newline = chunk.indexOf(0x0a, offset);
150
+ const end = newline === -1 ? chunk.length : newline;
151
+ appendPayloadLine(chunk.subarray(offset, end));
152
+ if (newline === -1)
153
+ break;
154
+ finishPayloadLine();
155
+ offset = newline + 1;
156
+ }
157
+ };
82
158
  let settled = false;
83
159
  let resolveDone;
84
160
  const done = new Promise((r) => {
@@ -87,6 +163,7 @@ export function createDefaultRunner(opts = {}) {
87
163
  const finish = (exitCode, signal, error) => {
88
164
  if (settled)
89
165
  return;
166
+ finishPayloadLine();
90
167
  settled = true;
91
168
  // Flush any stderr that arrived before stdout ended, preserving the
92
169
  // stdout-then-stderr hash ordering (a no-op when degraded — dropped).
@@ -108,6 +185,8 @@ export function createDefaultRunner(opts = {}) {
108
185
  stdoutBytes,
109
186
  stderrBytes,
110
187
  outputTail: tail.toString('utf8'),
188
+ ...(payloadLine !== undefined ? { payloadLine } : {}),
189
+ ...(payloadOverCap ? { payloadOverCap: true } : {}),
111
190
  startedAt,
112
191
  finishedAt,
113
192
  durationMs: finishedAt - startedAt,
@@ -125,8 +204,10 @@ export function createDefaultRunner(opts = {}) {
125
204
  hash.update(chunk);
126
205
  stdoutBytes += chunk.length;
127
206
  stdoutTail = appendTail(stdoutTail, chunk, RETAIN_CAP_BYTES);
207
+ scanPayload(chunk);
128
208
  });
129
209
  child.stdout?.on('end', () => {
210
+ finishPayloadLine();
130
211
  stdoutEnded = true;
131
212
  if (!degraded)
132
213
  for (const c of pendingStderr)
@@ -89,6 +89,13 @@ export const ADMITTED_OWENLOOP_KEYS = new Set([
89
89
  // `resolveCacheDir` — src/bundle/cache.ts. Keeps anything the agent runs on
90
90
  // the same bundle cache as the worker. A path, not a secret.
91
91
  'OWENLOOP_CACHE_DIR',
92
+ // The step agent and anything it runs. Resolves bundle-shipped assets from
93
+ // the verified installed object directory. A path, not credential material.
94
+ 'OWENLOOP_BUNDLE_DIR',
95
+ // The step agent and anything it runs. Identifies the workflow instance.
96
+ 'OWENLOOP_WORKFLOW',
97
+ // The step agent and anything it runs. Identifies the current run.
98
+ 'OWENLOOP_RUN',
92
99
  // `holdShiftId` — src/roles/hold.ts. The fallback when `--shift=` is
93
100
  // absent from the mount's argv.
94
101
  'OWENLOOP_SHIFT_ID',
@@ -1,5 +1,5 @@
1
- import type { Options, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
- import type { AgentEvent, HarnessAdapter, StepPermissions } from './contract.ts';
1
+ import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
+ import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
3
3
  /**
4
4
  * Build the environment the harness child runs under.
5
5
  *
@@ -65,8 +65,7 @@ export declare function allowApiBillingFrom(source: Record<string, string | unde
65
65
  * and the `PATH` searched are the same ones the child will see.
66
66
  */
67
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. */
68
+ /** Everything `buildClaudeOptions` reads for either cold start or resume. */
70
69
  export interface ClaudeOptionInputs {
71
70
  cwd: string;
72
71
  owenloopMcp: {
@@ -86,6 +85,8 @@ export interface ClaudeOptionExtras {
86
85
  env: Record<string, string | undefined>;
87
86
  abortController: AbortController;
88
87
  onEvent: (e: AgentEvent) => void;
88
+ /** Preselected UUID for a cold start. Never set on a resume. */
89
+ sessionId?: string;
89
90
  /** Set on a resume only. Never set on a start. */
90
91
  resume?: string;
91
92
  }
@@ -98,6 +99,16 @@ export interface ClaudeOptionExtras {
98
99
  * direction.
99
100
  */
100
101
  export declare function buildClaudeOptions(inputs: ClaudeOptionInputs, extra: ClaudeOptionExtras): Options;
102
+ export type ClaudeQuery = AsyncIterable<SDKMessage> & Pick<Query, 'close'>;
103
+ export interface ClaudeQueryArgs {
104
+ prompt: string;
105
+ options: Options;
106
+ }
107
+ export type ClaudeQueryFactory = (args: ClaudeQueryArgs) => ClaudeQuery;
108
+ export interface ClaudeStartDependencies {
109
+ createSessionId: () => string;
110
+ loadQuery: () => Promise<ClaudeQueryFactory>;
111
+ }
101
112
  /** What one consumed turn tells the caller. */
102
113
  export interface TurnOutcome {
103
114
  /** The session id from the `system/init` message, if one arrived. */
@@ -111,9 +122,9 @@ export interface TurnOutcome {
111
122
  * Resolves at the `result` message — turn end, per the contract — not at process
112
123
  * exit, and regardless of whether the result reports an error.
113
124
  *
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.
125
+ * `onInit` fires after a matching `system/init` confirms the preselected cold-
126
+ * start session id. `startClaude` emits `{kind:'started'}` before query creation;
127
+ * this callback marks the later provider confirmation, not the persistence gate.
117
128
  *
118
129
  * PHASE 6, ITEM 1 — EXPORTED, AND TYPED ON `AsyncIterable` RATHER THAN `Query`.
119
130
  * This is the one function that maps the SDK's message stream onto this
@@ -124,5 +135,6 @@ export interface TurnOutcome {
124
135
  * what it uses is what lets a fixture drive it. A live `Query` still satisfies
125
136
  * the narrower type, so nothing at the call sites changes.
126
137
  */
127
- export declare function consumeTurn(q: AsyncIterable<SDKMessage>, onEvent: (e: AgentEvent) => void, onInit?: (sessionId: string) => void): Promise<TurnOutcome>;
138
+ export declare function consumeTurn(q: AsyncIterable<SDKMessage>, onEvent: (e: AgentEvent) => void, onInit?: (sessionId: string) => void, expectedSessionId?: string): Promise<TurnOutcome>;
139
+ export declare function startClaude(args: StartArgs, onEvent: (e: AgentEvent) => void, dependencies?: ClaudeStartDependencies): Promise<HarnessSessionRef>;
128
140
  export declare const claudeAdapter: HarnessAdapter;