owenloop 0.4.1 → 0.5.1

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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
@@ -0,0 +1,49 @@
1
+ /** Quality-tier resolution and retry escalation for agent orders. */
2
+ /** Shipped quality tiers. A settings tierMap may override any entry. */
3
+ export declare const DEFAULT_TIER_MAP: {
4
+ readonly fast: "haiku";
5
+ readonly standard: "sonnet";
6
+ readonly strong: "opus";
7
+ readonly strongest: "fable";
8
+ };
9
+ /** Reasoning rungs accepted by the neutral start contract. */
10
+ export declare const EFFORT_LADDER: readonly ["low", "medium", "high", "xhigh", "max"];
11
+ export type ModelLane = 'express' | 'standard' | 'deep';
12
+ export interface ModelEscalation {
13
+ model?: string;
14
+ attempts?: number;
15
+ }
16
+ export interface ModelPolicy {
17
+ /** Resolved tier names; this map is merged with DEFAULT_TIER_MAP by createModelPolicy. */
18
+ tierMap: Readonly<Record<string, string>>;
19
+ /** Reject count at which the default policy escalates. */
20
+ escalateAt: number;
21
+ /** Extension namespace containing the authored escalation object. */
22
+ escalationExtensionKey: string;
23
+ }
24
+ export interface PickModelResult {
25
+ model: string;
26
+ effort?: string;
27
+ }
28
+ export interface ModelPolicyOptions {
29
+ tierMap?: Record<string, string>;
30
+ escalateAt?: number;
31
+ escalationExtensionKey?: string;
32
+ }
33
+ export declare const DEFAULT_MODEL_POLICY: ModelPolicy;
34
+ /** Build a normalized policy from optional machine-local settings. */
35
+ export declare function createModelPolicy(options?: ModelPolicyOptions): ModelPolicy;
36
+ /** Resolve a tier name, passing through a literal model id unchanged. */
37
+ export declare function resolveModelTier(model: string, tierMap?: Readonly<Record<string, string>>): string;
38
+ /** Split a trailing positive integer effort suffix from a model string. */
39
+ export declare function parseModelEffort(raw: string): {
40
+ modelPart: string;
41
+ effortIndex?: number;
42
+ };
43
+ /**
44
+ * Pick the model and effort for one agent order.
45
+ *
46
+ * The fourth argument accepts a ModelPolicy. A numeric value is also accepted as
47
+ * the reject threshold for compatibility with the reference function's shape.
48
+ */
49
+ export declare function pickModel(stepYamlModel: string, lane: ModelLane | undefined, judgmentRejects: number, policyOrAt?: ModelPolicy | number, override?: string, escalation?: ModelEscalation): PickModelResult;
@@ -0,0 +1,138 @@
1
+ /** Quality-tier resolution and retry escalation for agent orders. */
2
+ /** Shipped quality tiers. A settings tierMap may override any entry. */
3
+ export const DEFAULT_TIER_MAP = {
4
+ fast: 'haiku',
5
+ standard: 'sonnet',
6
+ strong: 'opus',
7
+ strongest: 'fable',
8
+ };
9
+ /** Reasoning rungs accepted by the neutral start contract. */
10
+ export const EFFORT_LADDER = ['low', 'medium', 'high', 'xhigh', 'max'];
11
+ const TIER_INDEX = {
12
+ fast: 0,
13
+ standard: 1,
14
+ strong: 2,
15
+ strongest: 3,
16
+ };
17
+ /** Tier index -> tier name, so a clamp can resolve to an id at the very end. */
18
+ const TIER_NAMES = ['fast', 'standard', 'strong', 'strongest'];
19
+ export const DEFAULT_MODEL_POLICY = {
20
+ tierMap: DEFAULT_TIER_MAP,
21
+ escalateAt: 3,
22
+ escalationExtensionKey: 'delivery',
23
+ };
24
+ /** Build a normalized policy from optional machine-local settings. */
25
+ export function createModelPolicy(options = {}) {
26
+ return {
27
+ tierMap: { ...DEFAULT_TIER_MAP, ...(options.tierMap ?? {}) },
28
+ escalateAt: options.escalateAt ?? DEFAULT_MODEL_POLICY.escalateAt,
29
+ escalationExtensionKey: options.escalationExtensionKey ?? DEFAULT_MODEL_POLICY.escalationExtensionKey,
30
+ };
31
+ }
32
+ /** Resolve a tier name, passing through a literal model id unchanged. */
33
+ export function resolveModelTier(model, tierMap = DEFAULT_TIER_MAP) {
34
+ return tierMap[model] ?? model;
35
+ }
36
+ /** Split a trailing positive integer effort suffix from a model string. */
37
+ export function parseModelEffort(raw) {
38
+ const separator = raw.lastIndexOf(':');
39
+ if (separator === -1)
40
+ return { modelPart: raw };
41
+ const tail = raw.slice(separator + 1);
42
+ if (!/^[1-9]\d*$/.test(tail))
43
+ return { modelPart: raw };
44
+ return { modelPart: raw.slice(0, separator), effortIndex: Number(tail) };
45
+ }
46
+ function tierForInput(modelPart) {
47
+ return TIER_INDEX[modelPart];
48
+ }
49
+ /**
50
+ * Apply the lane to a tier index, in tier space.
51
+ *
52
+ * express caps at `standard` and deep floors at `strong`, with one exception:
53
+ * the express cap never touches the TOP tier. A step authored at the top tier
54
+ * is there because the judgment it makes is hard, so the lane's cost heuristic
55
+ * must not downgrade it — the lane scales cost, it does not overrule an
56
+ * explicit escalation of quality. The reference implementation gets this for
57
+ * free by leaving the top tier out of its rank table; ranking in tier space
58
+ * gives the top tier a rank, so the exclusion has to be stated here.
59
+ */
60
+ function clampTierForLane(tier, lane) {
61
+ if (lane === 'express' && tier > TIER_INDEX['standard'] && tier !== TIER_INDEX['strongest']) {
62
+ return TIER_INDEX['standard'];
63
+ }
64
+ if (lane === 'deep' && tier < TIER_INDEX['strong'])
65
+ return TIER_INDEX['strong'];
66
+ return tier;
67
+ }
68
+ /** Resolve a tier index back to a concrete model id through the policy map. */
69
+ function modelForTier(tier, tierMap) {
70
+ const name = TIER_NAMES[tier];
71
+ return tierMap[name] ?? name;
72
+ }
73
+ function effortName(index) {
74
+ const clamped = Math.min(Math.max(index, 1), EFFORT_LADDER.length) - 1;
75
+ return EFFORT_LADDER[clamped];
76
+ }
77
+ function withEffort(model, effortIndex) {
78
+ return effortIndex === undefined ? { model } : { model, effort: effortName(effortIndex) };
79
+ }
80
+ function normalizePolicy(policyOrAt) {
81
+ if (typeof policyOrAt === 'number') {
82
+ return createModelPolicy({ escalateAt: policyOrAt });
83
+ }
84
+ if (policyOrAt === undefined)
85
+ return DEFAULT_MODEL_POLICY;
86
+ return createModelPolicy({
87
+ tierMap: { ...policyOrAt.tierMap },
88
+ escalateAt: policyOrAt.escalateAt,
89
+ escalationExtensionKey: policyOrAt.escalationExtensionKey,
90
+ });
91
+ }
92
+ /**
93
+ * Pick the model and effort for one agent order.
94
+ *
95
+ * The fourth argument accepts a ModelPolicy. A numeric value is also accepted as
96
+ * the reject threshold for compatibility with the reference function's shape.
97
+ */
98
+ export function pickModel(stepYamlModel, lane, judgmentRejects, policyOrAt = DEFAULT_MODEL_POLICY, override, escalation) {
99
+ const policy = normalizePolicy(policyOrAt);
100
+ const pinned = typeof override === 'string' && override !== '';
101
+ const rawInput = pinned ? override : stepYamlModel;
102
+ const { modelPart, effortIndex } = parseModelEffort(rawInput);
103
+ let model = resolveModelTier(modelPart, policy.tierMap);
104
+ const inputTier = tierForInput(modelPart);
105
+ if (escalation !== undefined) {
106
+ const attempts = escalation.attempts ?? policy.escalateAt;
107
+ if (judgmentRejects >= attempts) {
108
+ const rung2Raw = typeof escalation.model === 'string' && escalation.model !== '' ? escalation.model : 'strong';
109
+ const { modelPart: rung2Part, effortIndex: rung2Effort } = parseModelEffort(rung2Raw);
110
+ return withEffort(resolveModelTier(rung2Part, policy.tierMap), rung2Effort);
111
+ }
112
+ if (inputTier !== undefined && !pinned) {
113
+ model = modelForTier(clampTierForLane(inputTier, lane), policy.tierMap);
114
+ }
115
+ return withEffort(model, effortIndex);
116
+ }
117
+ const escalate = judgmentRejects >= policy.escalateAt;
118
+ const nextEffort = effortIndex === undefined ? undefined : escalate ? effortIndex + 1 : effortIndex;
119
+ // The lane adjusts the BASE. Track the resulting tier, because escalation
120
+ // below is decided on the CLAMPED tier, not the authored one.
121
+ let currentTier = inputTier;
122
+ if (inputTier !== undefined && !pinned) {
123
+ currentTier = clampTierForLane(inputTier, lane);
124
+ model = modelForTier(currentTier, policy.tierMap);
125
+ }
126
+ // Model escalation fires when there was no effort suffix to bump instead, or
127
+ // once the reject count reaches twice the threshold. It is upward-only and
128
+ // ALWAYS wins over an express cap: a producer stuck on repeated rejects needs
129
+ // more capability more than the lane needs the cheaper tier. Gating this on
130
+ // the POST-clamp tier is what makes escalation beat the cap — gating it on
131
+ // the authored tier would let an express-clamped `strong` step sit at the
132
+ // standard tier forever, however many rejects accumulate.
133
+ const modelEscalates = escalate && (effortIndex === undefined || judgmentRejects >= policy.escalateAt * 2);
134
+ if (modelEscalates && currentTier !== undefined && currentTier < TIER_INDEX['strong']) {
135
+ model = policy.tierMap['strong'] ?? 'strong';
136
+ }
137
+ return withEffort(model, nextEffort);
138
+ }
@@ -0,0 +1,210 @@
1
+ import { markRunSessionsDead } from '../harness/session-store.ts';
2
+ /**
3
+ * `<workRoot>/<workflow>/<run>` — the one place the layout is spelled out.
4
+ * Pure: no I/O, so callers can compute a path without creating anything.
5
+ */
6
+ export declare function runWorkDir(workRoot: string, workflow: string, run: string): string;
7
+ /**
8
+ * Resolve the work root: `OWENLOOP_WORK_ROOT` > `settings.workRoot` >
9
+ * `<cacheDir>/work`. Mirrors `resolveCacheDir`'s precedence shape exactly, so
10
+ * there is one rule to remember for both.
11
+ */
12
+ export declare function resolveWorkRoot(env: Record<string, string | undefined>, settingsWorkRoot: string | undefined, cacheDir: string): string;
13
+ /** `OWENLOOP_WORK_REPO` > `settings.workRepo` > none. */
14
+ export declare function resolveWorkRepo(env: Record<string, string | undefined>, settingsWorkRepo: string | undefined): string | undefined;
15
+ /**
16
+ * Is `dir` inside `root`? The guard that keeps removal to directories owenloop
17
+ * created.
18
+ *
19
+ * Both paths are resolved to absolutes first, so a relative `workRoot` or a
20
+ * `..`-bearing directory cannot smuggle a path outside the root past the check.
21
+ * `dir === root` returns FALSE on purpose: the root itself holds every other
22
+ * run's directory and must never be removed.
23
+ */
24
+ export declare function isUnderWorkRoot(dir: string, workRoot: string): boolean;
25
+ export interface EnsureWorkDirOptions {
26
+ workRoot: string;
27
+ workflow: string;
28
+ run: string;
29
+ /** When set, provision as a git worktree of this repo instead of a plain dir. */
30
+ workRepo?: string;
31
+ /** Branch name for the worktree. Default `owenloop/<workflow>/<run>`. */
32
+ branch?: string;
33
+ /** Progress/warning sink. */
34
+ err?: (line: string) => void;
35
+ /** Injected for tests. Defaults to `node:child_process` `spawnSync`. */
36
+ runGit?: (args: string[], cwd: string) => {
37
+ status: number | null;
38
+ output: string;
39
+ };
40
+ }
41
+ /**
42
+ * Create (or adopt) the per-run work directory and return its absolute path.
43
+ *
44
+ * IDEMPOTENT. Every step of a run calls this, and the second and later calls
45
+ * must be no-ops that hand back the same directory — that is the whole point of
46
+ * a per-run directory. An existing directory is therefore adopted, never
47
+ * recreated and never cleaned.
48
+ *
49
+ * WORKTREE MODE. `git worktree add -b <branch> <dir>` against `workRepo`. A
50
+ * failure DEGRADES to a plain directory rather than failing the order: the agent
51
+ * can still work, it just does not get git isolation, and the reason is reported.
52
+ * The alternative — refusing the order — would turn a misconfigured `workRepo`
53
+ * into a stuck run, which is strictly worse than a degraded one.
54
+ */
55
+ export declare function ensureWorkDir(o: EnsureWorkDirOptions): string;
56
+ /**
57
+ * Default grace window before an idle work directory may be reaped: 1 hour.
58
+ *
59
+ * A run momentarily between orders (delivered, waiting on the next step) still
60
+ * owns its directory, so the sweep must not remove it the instant the child
61
+ * exits. One hour is deliberately coarse — the cost of keeping a stale directory
62
+ * an hour longer is disk, while the cost of removing a live one is a lost
63
+ * working tree.
64
+ */
65
+ export declare const DEFAULT_WORK_DIR_TTL_MS: number;
66
+ export interface ReapGateInput {
67
+ /** The run whose work directory is a candidate. */
68
+ runId: string;
69
+ /** Runs the hub currently reports an OPEN order for. */
70
+ openRunIds: ReadonlySet<string>;
71
+ /** Runs a LIVE `agent-run` child is holding — liveness by `kill(pid,0)`. */
72
+ liveRunIds: ReadonlySet<string>;
73
+ /** When the directory was last observed in use (mtime, or the in-flight record). */
74
+ lastSeenAt: number;
75
+ now: number;
76
+ /** Grace window. A run momentarily between orders must not be reaped. */
77
+ ttlMs: number;
78
+ }
79
+ /**
80
+ * May this run's work directory be removed?
81
+ *
82
+ * PURE — no filesystem, no hub, no clock. That is what lets the truth table be a
83
+ * unit test instead of an integration test.
84
+ *
85
+ * True only when ALL THREE hold:
86
+ * - the hub reports NO open order for the run (`!openRunIds.has(runId)`), and
87
+ * - no live `agent-run` child holds it (`!liveRunIds.has(runId)`), and
88
+ * - the grace window has elapsed (`now - lastSeenAt >= ttlMs`).
89
+ *
90
+ * WHY THE GRACE WINDOW. At the instant a step submits, its downstream orders
91
+ * usually are not open yet. A gate with no TTL would see "no open orders, no live
92
+ * child" in exactly that gap and delete the directory a moment before the next
93
+ * step needs it.
94
+ *
95
+ * WHY THIS RUNS IN THE SHIFT SWEEP AND NOT IN THE WORKER AT EXIT: same reason,
96
+ * from the other side. A worker asking "is anything still open?" as it exits is
97
+ * asking during that gap, every time.
98
+ */
99
+ export declare function isWorkDirReapable(g: ReapGateInput): boolean;
100
+ export interface ReapWorkDirOptions {
101
+ dir: string;
102
+ workRoot: string;
103
+ workRepo?: string;
104
+ err?: (line: string) => void;
105
+ runGit?: (args: string[], cwd: string) => {
106
+ status: number | null;
107
+ output: string;
108
+ };
109
+ }
110
+ /** What `reapWorkDir` did, so a sweep can count and log without re-deriving it. */
111
+ export type ReapResult = 'removed' | 'absent' | 'refused' | 'failed';
112
+ /**
113
+ * Remove one per-run work directory. BEST EFFORT — never throws, so a sweep can
114
+ * call it in a loop without a try/catch per entry.
115
+ *
116
+ * - `'refused'`: the path is not under `workRoot`. This is the guard that keeps
117
+ * a hub-supplied `OrderPacket.workdir` — someone else's directory, which
118
+ * owenloop did not create — out of reach no matter what the gate said.
119
+ * - `'absent'`: nothing there; already gone.
120
+ * - `'removed'` / `'failed'`: the removal ran and did or did not succeed.
121
+ *
122
+ * Worktree mode removes with `git worktree remove --force`; if git refuses (a
123
+ * dirty tree it will not discard, a repo that has forgotten the worktree), it
124
+ * falls back to `git worktree prune` plus `rm -rf`, so the directory goes away
125
+ * and the repo's worktree list does not keep a dangling entry.
126
+ */
127
+ export declare function reapWorkDir(o: ReapWorkDirOptions): ReapResult;
128
+ /** One candidate directory the sweep found on disk. */
129
+ export interface WorkDirEntry {
130
+ workflow: string;
131
+ runId: string;
132
+ dir: string;
133
+ /** Last modification time of the run directory itself, in ms. */
134
+ lastSeenAt: number;
135
+ }
136
+ /**
137
+ * Every `<workRoot>/<workflow>/<run>` directory for the given workflows.
138
+ *
139
+ * SCOPED TO `workflows` ON PURPOSE, not a blind walk of `workRoot`. A shift
140
+ * started with `--workflow wf1` only ever learns which of wf1's orders are open;
141
+ * it knows nothing about wf2's. Letting it consider wf2's directories would mean
142
+ * judging them against an order list that structurally cannot mention them —
143
+ * every one would look abandoned. So the sweep sees only what the caller has
144
+ * evidence about.
145
+ *
146
+ * Unreadable directories are skipped rather than thrown over; the sweep is
147
+ * best-effort throughout.
148
+ */
149
+ export declare function listWorkDirs(workRoot: string, workflows: ReadonlySet<string>): WorkDirEntry[];
150
+ export interface SweepWorkDirsOptions {
151
+ workRoot: string;
152
+ /** Workflows the caller has a current order list for. */
153
+ workflows: ReadonlySet<string>;
154
+ /** Runs the hub reports an open order for, across those workflows. */
155
+ openRunIds: ReadonlySet<string>;
156
+ /** Runs a live `agent-run` child holds. */
157
+ liveRunIds: ReadonlySet<string>;
158
+ now: number;
159
+ ttlMs: number;
160
+ workRepo?: string;
161
+ err?: (line: string) => void;
162
+ /**
163
+ * `<cacheDir>/sessions.jsonl` (`sessionsPath`). PRESENT IN PRODUCTION, and the
164
+ * thing that makes the teardown gate a gate: before a directory is removed,
165
+ * every session of that run is marked `dead` in this file, so the next firing
166
+ * cannot resume into the recreated (empty) directory.
167
+ *
168
+ * Optional only so the pure truth-table tests can drive the gate with no store
169
+ * on disk. Omitting it in production would reopen exactly the hole this field
170
+ * closes.
171
+ */
172
+ sessionsFile?: string;
173
+ /** Injected for tests, so the truth table needs no filesystem. */
174
+ list?: (workRoot: string, workflows: ReadonlySet<string>) => WorkDirEntry[];
175
+ /** Injected for tests. */
176
+ remove?: (o: ReapWorkDirOptions) => ReapResult;
177
+ /** Injected for tests. Defaults to `markRunSessionsDead` from the session store. */
178
+ retire?: typeof markRunSessionsDead;
179
+ }
180
+ /**
181
+ * Apply `isWorkDirReapable` to every candidate, RETIRE that run's sessions, and
182
+ * remove the ones that pass. Returns the directories actually removed, so a
183
+ * caller can log a count.
184
+ *
185
+ * ── SESSION LIFETIME = CWD LIFETIME (the teardown gate) ──
186
+ *
187
+ * Removing the directory is only half the gate. A session record for the same
188
+ * `(workflow, run, step)` outlives the directory in `sessions.jsonl`, and the
189
+ * next firing of that step RECREATES the directory at the same path
190
+ * (`ensureWorkDir` is idempotent by design), which defeats the worker's
191
+ * `dirExists(prev.cwd)` and `prev.cwd === recordCwd` guards on its own. So every
192
+ * session of the run is marked `dead` here — `src/agent/loop.ts` refuses to
193
+ * resume a `dead` record, which is what makes resume impossible past this point
194
+ * BY CONSTRUCTION rather than by a liveness check that can be raced.
195
+ *
196
+ * ORDER IS FAIL-SAFE, RETIRE FIRST: if the retire write fails, the directory is
197
+ * LEFT IN PLACE and the entry is skipped for this sweep, so the invariant "a
198
+ * removed work directory has no live session record" cannot be broken by a
199
+ * crash between the two writes. The opposite order (remove, then retire) has a
200
+ * window in which the invariant is already false. A retire that succeeds and a
201
+ * removal that then fails costs only a cold replay next firing — the safe
202
+ * direction to be wrong.
203
+ *
204
+ * KNOWN LIMITATION, stated rather than hidden: `lastSeenAt` is the run
205
+ * directory's own mtime, which a write deep inside a subdirectory does not
206
+ * update. It is therefore a weak "last touched" signal, and it is deliberately
207
+ * only the THIRD condition — a run with an open order or a live child is already
208
+ * protected by the first two regardless of how stale its mtime looks.
209
+ */
210
+ export declare function sweepWorkDirs(o: SweepWorkDirsOptions): string[];