owenloop 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
|
@@ -0,0 +1,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[];
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 4 — per-RUN agent working directories, and the gate that removes them.
|
|
3
|
+
*
|
|
4
|
+
* ── WHAT A WORK DIRECTORY IS ──
|
|
5
|
+
*
|
|
6
|
+
* One directory per RUN, at `<workRoot>/<workflow>/<run>/`. Every step of a run
|
|
7
|
+
* shares it. That is deliberate and load-bearing twice over:
|
|
8
|
+
*
|
|
9
|
+
* 1. A downstream step can read what an upstream step wrote, which per-STEP
|
|
10
|
+
* directories would make impossible without copying.
|
|
11
|
+
* 2. The removal question collapses from "does any pending downstream step
|
|
12
|
+
* consume this output?" (a `consumes` / `expected_outputs` walk, with a false
|
|
13
|
+
* negative for any step the hub has not offered yet) into "does this run
|
|
14
|
+
* still have an open order?" — one set membership test.
|
|
15
|
+
*
|
|
16
|
+
* ── THE THREE-STEP CWD PRECEDENCE ──
|
|
17
|
+
*
|
|
18
|
+
* 1. `OrderPacket.workdir`, when the hub set it. The hub always wins.
|
|
19
|
+
* 2. Otherwise `<workRoot>/<workflow>/<run>/`, created on first use.
|
|
20
|
+
* 3. Otherwise (no `workRoot` resolvable) the dispatching process's own cwd,
|
|
21
|
+
* which is the pre-Phase-4 behaviour.
|
|
22
|
+
*
|
|
23
|
+
* A directory reached by rule 1 is the HUB's, not owenloop's, and `reapWorkDir`
|
|
24
|
+
* refuses to touch it — see `isUnderWorkRoot`.
|
|
25
|
+
*
|
|
26
|
+
* ── PLAIN DIR VS GIT WORKTREE ──
|
|
27
|
+
*
|
|
28
|
+
* `workRepo` (a settings key, machine-local) decides. Unset ⇒ `mkdir -p`. Set ⇒
|
|
29
|
+
* `git worktree add`. It is machine-local rather than workflow-declared because
|
|
30
|
+
* nothing in `src/bundle/types.ts` or `src/hub/types.ts` lets a workflow declare
|
|
31
|
+
* a repo, and adding a field there would be a hub protocol change — an explicit
|
|
32
|
+
* effort non-goal.
|
|
33
|
+
*
|
|
34
|
+
* Failure stance: provisioning propagates its failure (a worker with no place to
|
|
35
|
+
* work should say so); REMOVAL is best-effort and never throws, because it runs
|
|
36
|
+
* inside the shift sweep and a sweep must not die over a directory.
|
|
37
|
+
*/
|
|
38
|
+
import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
|
|
39
|
+
import { spawnSync } from 'node:child_process';
|
|
40
|
+
import { isAbsolute, join, relative, resolve } from 'node:path';
|
|
41
|
+
import { markRunSessionsDead } from "../harness/session-store.js";
|
|
42
|
+
/**
|
|
43
|
+
* `<workRoot>/<workflow>/<run>` — the one place the layout is spelled out.
|
|
44
|
+
* Pure: no I/O, so callers can compute a path without creating anything.
|
|
45
|
+
*/
|
|
46
|
+
export function runWorkDir(workRoot, workflow, run) {
|
|
47
|
+
return join(workRoot, workflow, run);
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Resolve the work root: `OWENLOOP_WORK_ROOT` > `settings.workRoot` >
|
|
51
|
+
* `<cacheDir>/work`. Mirrors `resolveCacheDir`'s precedence shape exactly, so
|
|
52
|
+
* there is one rule to remember for both.
|
|
53
|
+
*/
|
|
54
|
+
export function resolveWorkRoot(env, settingsWorkRoot, cacheDir) {
|
|
55
|
+
const override = env['OWENLOOP_WORK_ROOT'];
|
|
56
|
+
if (override !== undefined && override.trim() !== '')
|
|
57
|
+
return override;
|
|
58
|
+
if (settingsWorkRoot !== undefined && settingsWorkRoot.trim() !== '')
|
|
59
|
+
return settingsWorkRoot;
|
|
60
|
+
return join(cacheDir, 'work');
|
|
61
|
+
}
|
|
62
|
+
/** `OWENLOOP_WORK_REPO` > `settings.workRepo` > none. */
|
|
63
|
+
export function resolveWorkRepo(env, settingsWorkRepo) {
|
|
64
|
+
const override = env['OWENLOOP_WORK_REPO'];
|
|
65
|
+
if (override !== undefined && override.trim() !== '')
|
|
66
|
+
return override;
|
|
67
|
+
if (settingsWorkRepo !== undefined && settingsWorkRepo.trim() !== '')
|
|
68
|
+
return settingsWorkRepo;
|
|
69
|
+
return undefined;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Is `dir` inside `root`? The guard that keeps removal to directories owenloop
|
|
73
|
+
* created.
|
|
74
|
+
*
|
|
75
|
+
* Both paths are resolved to absolutes first, so a relative `workRoot` or a
|
|
76
|
+
* `..`-bearing directory cannot smuggle a path outside the root past the check.
|
|
77
|
+
* `dir === root` returns FALSE on purpose: the root itself holds every other
|
|
78
|
+
* run's directory and must never be removed.
|
|
79
|
+
*/
|
|
80
|
+
export function isUnderWorkRoot(dir, workRoot) {
|
|
81
|
+
const rel = relative(resolve(workRoot), resolve(dir));
|
|
82
|
+
return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
|
|
83
|
+
}
|
|
84
|
+
function defaultRunGit(args, cwd) {
|
|
85
|
+
const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
|
|
86
|
+
return { status: r.status, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Create (or adopt) the per-run work directory and return its absolute path.
|
|
90
|
+
*
|
|
91
|
+
* IDEMPOTENT. Every step of a run calls this, and the second and later calls
|
|
92
|
+
* must be no-ops that hand back the same directory — that is the whole point of
|
|
93
|
+
* a per-run directory. An existing directory is therefore adopted, never
|
|
94
|
+
* recreated and never cleaned.
|
|
95
|
+
*
|
|
96
|
+
* WORKTREE MODE. `git worktree add -b <branch> <dir>` against `workRepo`. A
|
|
97
|
+
* failure DEGRADES to a plain directory rather than failing the order: the agent
|
|
98
|
+
* can still work, it just does not get git isolation, and the reason is reported.
|
|
99
|
+
* The alternative — refusing the order — would turn a misconfigured `workRepo`
|
|
100
|
+
* into a stuck run, which is strictly worse than a degraded one.
|
|
101
|
+
*/
|
|
102
|
+
export function ensureWorkDir(o) {
|
|
103
|
+
const dir = runWorkDir(o.workRoot, o.workflow, o.run);
|
|
104
|
+
if (existsSync(dir))
|
|
105
|
+
return dir;
|
|
106
|
+
if (o.workRepo !== undefined && o.workRepo !== '') {
|
|
107
|
+
mkdirSync(join(dir, '..'), { recursive: true });
|
|
108
|
+
const branch = o.branch ?? `owenloop/${o.workflow}/${o.run}`;
|
|
109
|
+
const git = o.runGit ?? defaultRunGit;
|
|
110
|
+
const added = git(['worktree', 'add', '-b', branch, dir], o.workRepo);
|
|
111
|
+
if (added.status === 0)
|
|
112
|
+
return dir;
|
|
113
|
+
// A re-run against an existing branch is the common second failure; try once
|
|
114
|
+
// without `-b` before giving up on worktree mode.
|
|
115
|
+
const reused = git(['worktree', 'add', dir, branch], o.workRepo);
|
|
116
|
+
if (reused.status === 0)
|
|
117
|
+
return dir;
|
|
118
|
+
o.err?.(`owenloop work: git worktree add for ${o.workflow}/${o.run} failed (${added.output || 'no output'}) — using a plain directory instead`);
|
|
119
|
+
}
|
|
120
|
+
mkdirSync(dir, { recursive: true });
|
|
121
|
+
return dir;
|
|
122
|
+
}
|
|
123
|
+
// ---- the removal gate -------------------------------------------------------
|
|
124
|
+
/**
|
|
125
|
+
* Default grace window before an idle work directory may be reaped: 1 hour.
|
|
126
|
+
*
|
|
127
|
+
* A run momentarily between orders (delivered, waiting on the next step) still
|
|
128
|
+
* owns its directory, so the sweep must not remove it the instant the child
|
|
129
|
+
* exits. One hour is deliberately coarse — the cost of keeping a stale directory
|
|
130
|
+
* an hour longer is disk, while the cost of removing a live one is a lost
|
|
131
|
+
* working tree.
|
|
132
|
+
*/
|
|
133
|
+
export const DEFAULT_WORK_DIR_TTL_MS = 60 * 60 * 1000;
|
|
134
|
+
/**
|
|
135
|
+
* May this run's work directory be removed?
|
|
136
|
+
*
|
|
137
|
+
* PURE — no filesystem, no hub, no clock. That is what lets the truth table be a
|
|
138
|
+
* unit test instead of an integration test.
|
|
139
|
+
*
|
|
140
|
+
* True only when ALL THREE hold:
|
|
141
|
+
* - the hub reports NO open order for the run (`!openRunIds.has(runId)`), and
|
|
142
|
+
* - no live `agent-run` child holds it (`!liveRunIds.has(runId)`), and
|
|
143
|
+
* - the grace window has elapsed (`now - lastSeenAt >= ttlMs`).
|
|
144
|
+
*
|
|
145
|
+
* WHY THE GRACE WINDOW. At the instant a step submits, its downstream orders
|
|
146
|
+
* usually are not open yet. A gate with no TTL would see "no open orders, no live
|
|
147
|
+
* child" in exactly that gap and delete the directory a moment before the next
|
|
148
|
+
* step needs it.
|
|
149
|
+
*
|
|
150
|
+
* WHY THIS RUNS IN THE SHIFT SWEEP AND NOT IN THE WORKER AT EXIT: same reason,
|
|
151
|
+
* from the other side. A worker asking "is anything still open?" as it exits is
|
|
152
|
+
* asking during that gap, every time.
|
|
153
|
+
*/
|
|
154
|
+
export function isWorkDirReapable(g) {
|
|
155
|
+
if (g.openRunIds.has(g.runId))
|
|
156
|
+
return false;
|
|
157
|
+
if (g.liveRunIds.has(g.runId))
|
|
158
|
+
return false;
|
|
159
|
+
return g.now - g.lastSeenAt >= g.ttlMs;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Remove one per-run work directory. BEST EFFORT — never throws, so a sweep can
|
|
163
|
+
* call it in a loop without a try/catch per entry.
|
|
164
|
+
*
|
|
165
|
+
* - `'refused'`: the path is not under `workRoot`. This is the guard that keeps
|
|
166
|
+
* a hub-supplied `OrderPacket.workdir` — someone else's directory, which
|
|
167
|
+
* owenloop did not create — out of reach no matter what the gate said.
|
|
168
|
+
* - `'absent'`: nothing there; already gone.
|
|
169
|
+
* - `'removed'` / `'failed'`: the removal ran and did or did not succeed.
|
|
170
|
+
*
|
|
171
|
+
* Worktree mode removes with `git worktree remove --force`; if git refuses (a
|
|
172
|
+
* dirty tree it will not discard, a repo that has forgotten the worktree), it
|
|
173
|
+
* falls back to `git worktree prune` plus `rm -rf`, so the directory goes away
|
|
174
|
+
* and the repo's worktree list does not keep a dangling entry.
|
|
175
|
+
*/
|
|
176
|
+
export function reapWorkDir(o) {
|
|
177
|
+
if (!isUnderWorkRoot(o.dir, o.workRoot))
|
|
178
|
+
return 'refused';
|
|
179
|
+
if (!existsSync(o.dir))
|
|
180
|
+
return 'absent';
|
|
181
|
+
if (o.workRepo !== undefined && o.workRepo !== '') {
|
|
182
|
+
const git = o.runGit ?? defaultRunGit;
|
|
183
|
+
try {
|
|
184
|
+
const removed = git(['worktree', 'remove', '--force', o.dir], o.workRepo);
|
|
185
|
+
if (removed.status === 0)
|
|
186
|
+
return 'removed';
|
|
187
|
+
git(['worktree', 'prune'], o.workRepo);
|
|
188
|
+
}
|
|
189
|
+
catch (e) {
|
|
190
|
+
o.err?.(`owenloop work: git worktree remove ${o.dir} failed (${String(e)}) — falling back to rm`);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
try {
|
|
194
|
+
rmSync(o.dir, { recursive: true, force: true });
|
|
195
|
+
return 'removed';
|
|
196
|
+
}
|
|
197
|
+
catch (e) {
|
|
198
|
+
o.err?.(`owenloop work: could not remove work directory ${o.dir}: ${String(e)} (ignored)`);
|
|
199
|
+
return 'failed';
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Every `<workRoot>/<workflow>/<run>` directory for the given workflows.
|
|
204
|
+
*
|
|
205
|
+
* SCOPED TO `workflows` ON PURPOSE, not a blind walk of `workRoot`. A shift
|
|
206
|
+
* started with `--workflow wf1` only ever learns which of wf1's orders are open;
|
|
207
|
+
* it knows nothing about wf2's. Letting it consider wf2's directories would mean
|
|
208
|
+
* judging them against an order list that structurally cannot mention them —
|
|
209
|
+
* every one would look abandoned. So the sweep sees only what the caller has
|
|
210
|
+
* evidence about.
|
|
211
|
+
*
|
|
212
|
+
* Unreadable directories are skipped rather than thrown over; the sweep is
|
|
213
|
+
* best-effort throughout.
|
|
214
|
+
*/
|
|
215
|
+
export function listWorkDirs(workRoot, workflows) {
|
|
216
|
+
const out = [];
|
|
217
|
+
for (const workflow of workflows) {
|
|
218
|
+
const wfDir = join(workRoot, workflow);
|
|
219
|
+
let runs;
|
|
220
|
+
try {
|
|
221
|
+
runs = readdirSync(wfDir);
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
continue; // no directory for this workflow yet
|
|
225
|
+
}
|
|
226
|
+
for (const runId of runs) {
|
|
227
|
+
const dir = join(wfDir, runId);
|
|
228
|
+
try {
|
|
229
|
+
const st = statSync(dir);
|
|
230
|
+
if (!st.isDirectory())
|
|
231
|
+
continue;
|
|
232
|
+
out.push({ workflow, runId, dir, lastSeenAt: st.mtimeMs });
|
|
233
|
+
}
|
|
234
|
+
catch {
|
|
235
|
+
continue;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return out;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* Apply `isWorkDirReapable` to every candidate, RETIRE that run's sessions, and
|
|
243
|
+
* remove the ones that pass. Returns the directories actually removed, so a
|
|
244
|
+
* caller can log a count.
|
|
245
|
+
*
|
|
246
|
+
* ── SESSION LIFETIME = CWD LIFETIME (the teardown gate) ──
|
|
247
|
+
*
|
|
248
|
+
* Removing the directory is only half the gate. A session record for the same
|
|
249
|
+
* `(workflow, run, step)` outlives the directory in `sessions.jsonl`, and the
|
|
250
|
+
* next firing of that step RECREATES the directory at the same path
|
|
251
|
+
* (`ensureWorkDir` is idempotent by design), which defeats the worker's
|
|
252
|
+
* `dirExists(prev.cwd)` and `prev.cwd === recordCwd` guards on its own. So every
|
|
253
|
+
* session of the run is marked `dead` here — `src/agent/loop.ts` refuses to
|
|
254
|
+
* resume a `dead` record, which is what makes resume impossible past this point
|
|
255
|
+
* BY CONSTRUCTION rather than by a liveness check that can be raced.
|
|
256
|
+
*
|
|
257
|
+
* ORDER IS FAIL-SAFE, RETIRE FIRST: if the retire write fails, the directory is
|
|
258
|
+
* LEFT IN PLACE and the entry is skipped for this sweep, so the invariant "a
|
|
259
|
+
* removed work directory has no live session record" cannot be broken by a
|
|
260
|
+
* crash between the two writes. The opposite order (remove, then retire) has a
|
|
261
|
+
* window in which the invariant is already false. A retire that succeeds and a
|
|
262
|
+
* removal that then fails costs only a cold replay next firing — the safe
|
|
263
|
+
* direction to be wrong.
|
|
264
|
+
*
|
|
265
|
+
* KNOWN LIMITATION, stated rather than hidden: `lastSeenAt` is the run
|
|
266
|
+
* directory's own mtime, which a write deep inside a subdirectory does not
|
|
267
|
+
* update. It is therefore a weak "last touched" signal, and it is deliberately
|
|
268
|
+
* only the THIRD condition — a run with an open order or a live child is already
|
|
269
|
+
* protected by the first two regardless of how stale its mtime looks.
|
|
270
|
+
*/
|
|
271
|
+
export function sweepWorkDirs(o) {
|
|
272
|
+
const list = o.list ?? listWorkDirs;
|
|
273
|
+
const remove = o.remove ?? reapWorkDir;
|
|
274
|
+
const retire = o.retire ?? markRunSessionsDead;
|
|
275
|
+
const removed = [];
|
|
276
|
+
let entries;
|
|
277
|
+
try {
|
|
278
|
+
entries = list(o.workRoot, o.workflows);
|
|
279
|
+
}
|
|
280
|
+
catch (e) {
|
|
281
|
+
o.err?.(`owenloop work: could not scan work directories under ${o.workRoot}: ${String(e)} (ignored)`);
|
|
282
|
+
return removed;
|
|
283
|
+
}
|
|
284
|
+
for (const e of entries) {
|
|
285
|
+
const reapable = isWorkDirReapable({
|
|
286
|
+
runId: e.runId,
|
|
287
|
+
openRunIds: o.openRunIds,
|
|
288
|
+
liveRunIds: o.liveRunIds,
|
|
289
|
+
lastSeenAt: e.lastSeenAt,
|
|
290
|
+
now: o.now,
|
|
291
|
+
ttlMs: o.ttlMs,
|
|
292
|
+
});
|
|
293
|
+
if (!reapable)
|
|
294
|
+
continue;
|
|
295
|
+
if (o.sessionsFile !== undefined && o.sessionsFile !== '') {
|
|
296
|
+
try {
|
|
297
|
+
const steps = retire(o.sessionsFile, e.workflow, e.runId, o.now, {
|
|
298
|
+
...(o.err !== undefined ? { warn: o.err } : {}),
|
|
299
|
+
});
|
|
300
|
+
if (steps.length > 0) {
|
|
301
|
+
o.err?.(`owenloop work: retired ${String(steps.length)} session record${steps.length === 1 ? '' : 's'} for ${e.workflow}/${e.runId} (${steps.join(', ')}) — its work directory is being removed`);
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
catch (err) {
|
|
305
|
+
o.err?.(`owenloop work: could not retire the sessions for ${e.workflow}/${e.runId}: ${String(err)} — leaving ${e.dir} in place this sweep`);
|
|
306
|
+
continue; // fail-safe: never remove a directory whose sessions still read live
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
const result = remove({
|
|
310
|
+
dir: e.dir,
|
|
311
|
+
workRoot: o.workRoot,
|
|
312
|
+
...(o.workRepo !== undefined ? { workRepo: o.workRepo } : {}),
|
|
313
|
+
...(o.err !== undefined ? { err: o.err } : {}),
|
|
314
|
+
});
|
|
315
|
+
if (result === 'removed')
|
|
316
|
+
removed.push(e.dir);
|
|
317
|
+
}
|
|
318
|
+
return removed;
|
|
319
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import type { CachedBundle, FetchedDef, NormalizedStepSpec } from './types.ts';
|
|
2
|
+
/** Resolve the cache root from env → settings → XDG → HOME. */
|
|
3
|
+
export declare function resolveCacheDir(env: Record<string, string | undefined>, settingsCacheDir?: string): string;
|
|
4
|
+
/** `<cacheDir>/bundles/<name>` — the dir holding every hash for one workflow. */
|
|
5
|
+
export declare function workflowDir(cacheDir: string, name: string): string;
|
|
6
|
+
/** `<cacheDir>/bundles/<name>/<hash>` — one specific cached def revision. */
|
|
7
|
+
export declare function hashDir(cacheDir: string, name: string, hash: string): string;
|
|
8
|
+
/**
|
|
9
|
+
* Write a cached bundle + its normalized step specs under the hash dir. Returns
|
|
10
|
+
* the hash dir path. Overwrites are fine — atomic per file. Each spec lands at
|
|
11
|
+
* `steps/<spec.step>.json`.
|
|
12
|
+
*/
|
|
13
|
+
export declare function writeBundle(cacheDir: string, bundle: CachedBundle, specs: NormalizedStepSpec[]): string;
|
|
14
|
+
/**
|
|
15
|
+
* Read a cached bundle for `(name, hash)`, or `null` when absent or corrupt.
|
|
16
|
+
* A corrupt `bundle.json` is treated as absent (refetch), not an error — a
|
|
17
|
+
* cache read must never harden into a failure the user cannot clear by
|
|
18
|
+
* re-fetching.
|
|
19
|
+
*/
|
|
20
|
+
export declare function readBundle(cacheDir: string, name: string, hash: string): CachedBundle | null;
|
|
21
|
+
/**
|
|
22
|
+
* Read the most-recently-fetched cached bundle for `name`, or `null` when none
|
|
23
|
+
* is cached. After a prepare only one hash dir survives (the others are pruned),
|
|
24
|
+
* but if several exist the newest by `fetchedAt` wins. Corrupt `bundle.json`
|
|
25
|
+
* files are skipped, not fatal.
|
|
26
|
+
*/
|
|
27
|
+
export declare function readLatestBundle(cacheDir: string, name: string): CachedBundle | null;
|
|
28
|
+
/**
|
|
29
|
+
* Read the normalized step spec for `(name, hash, step)`, or `null` when it is
|
|
30
|
+
* absent, unreadable, or not valid JSON. Layout mirrors `writeBundle`:
|
|
31
|
+
* `<cacheDir>/bundles/<name>/<hash>/steps/<step>.json`.
|
|
32
|
+
*
|
|
33
|
+
* Never throws — a missing spec is a normal case the caller reports and moves
|
|
34
|
+
* past (a command step has no spec by design, and a hash dir prepared before
|
|
35
|
+
* Phase 5 has none at all). There is deliberately NO fallback to the legacy
|
|
36
|
+
* `templates/<step>.md`: silently running a stale compiled template would be
|
|
37
|
+
* worse than an honest "re-run `owenloop work prepare`".
|
|
38
|
+
*/
|
|
39
|
+
export declare function readStepSpec(cacheDir: string, name: string, hash: string, step: string): NormalizedStepSpec | null;
|
|
40
|
+
/**
|
|
41
|
+
* Every distinct hash of workflow `name` that some still-cached bundle (any
|
|
42
|
+
* name, including a parent, a sibling child, or `name` itself) currently pins.
|
|
43
|
+
* The protected set for pruning and the pin-index for dispatch resolution.
|
|
44
|
+
* Fail-open via `scanCachedPins`.
|
|
45
|
+
*/
|
|
46
|
+
export declare function collectPinnedHashes(cacheDir: string, name: string): Set<string>;
|
|
47
|
+
/**
|
|
48
|
+
* Delete hash dirs under `<name>` except the protected set (DD-3): `keepHash`
|
|
49
|
+
* plus every hash of `name` pinned by any still-cached bundle (pinned-is-immortal
|
|
50
|
+
* — the consumer mirror of the hub's INV-96). Signature unchanged from D2, so
|
|
51
|
+
* every existing call site inherits the rule. Fail-open: a prune error is
|
|
52
|
+
* swallowed (the fresh bundle is already written; a leftover stale dir is
|
|
53
|
+
* harmless), and a corrupt bundle.json in the pin scan is skipped rather than
|
|
54
|
+
* fatal.
|
|
55
|
+
*/
|
|
56
|
+
export declare function pruneSupersededHashes(cacheDir: string, name: string, keepHash: string): string[];
|
|
57
|
+
/**
|
|
58
|
+
* The dispatch-time bundle selection for `name` (DD-4), used by the shift sweep
|
|
59
|
+
* in place of a bare `readLatestBundle`. `whats_next` serves only the def NAME
|
|
60
|
+
* (no hash, no parent linkage), so per-instance pin disambiguation must come
|
|
61
|
+
* from the local cache's pin index:
|
|
62
|
+
* - 0 pinned hashes for `name` → `readLatestBundle` (today's behavior, byte
|
|
63
|
+
* for byte for the common, unpinned case).
|
|
64
|
+
* - exactly 1 pinned hash h → the bundle AT that hash (single-resolution
|
|
65
|
+
* honored, even when a NEWER unpinned hash of `name` is cached). If that
|
|
66
|
+
* bundle is missing/corrupt we do NOT fall back to latest (that would
|
|
67
|
+
* silently run the wrong version): return `{ bundle: null, warning }` naming
|
|
68
|
+
* `owenloop work prepare <parent>` as the fix — orders lapse via the pickup window.
|
|
69
|
+
* - >1 distinct pinned hashes (two cached parents pin DIFFERENT versions of
|
|
70
|
+
* one child name — legal across parents; the hub only forbids it inside one
|
|
71
|
+
* parent's tree) → ambiguous per-instance, so refuse: `{ bundle: null,
|
|
72
|
+
* warning }`, leave orders for the pickup window. Deliberate fail-safe —
|
|
73
|
+
* never guess a version. Reversible once the hub enriches `whats_next` with a
|
|
74
|
+
* def hash (owenloop-service follow-up, out of scope here).
|
|
75
|
+
*/
|
|
76
|
+
export declare function readDispatchBundle(cacheDir: string, name: string): {
|
|
77
|
+
bundle: CachedBundle | null;
|
|
78
|
+
warning?: string;
|
|
79
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* Resolve the pinned child target for a parent's `calls:` step (pure). Matches
|
|
82
|
+
* `def.pins[].call` against `callStep`, returning `{name, hash}` for the frozen
|
|
83
|
+
* child that step must dispatch, or `null` when the def has no matching pin. The
|
|
84
|
+
* parent-pin → child-bundle resolvable path (item 3 of the brief); D-work builds
|
|
85
|
+
* child-run spawning on top of it.
|
|
86
|
+
*/
|
|
87
|
+
export declare function resolvePinnedChild(def: FetchedDef, callStep: string): {
|
|
88
|
+
name: string;
|
|
89
|
+
hash: string;
|
|
90
|
+
} | null;
|