owenloop 0.5.1 → 0.5.3
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 +30 -0
- package/README.md +9 -2
- package/dist/packages/work/src/agent/brief.d.ts +21 -0
- package/dist/packages/work/src/agent/brief.js +42 -1
- package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
- package/dist/packages/work/src/agent/capability-model.js +148 -0
- package/dist/packages/work/src/agent/loop.d.ts +47 -4
- package/dist/packages/work/src/agent/loop.js +83 -53
- package/dist/packages/work/src/exec/loop.d.ts +17 -0
- package/dist/packages/work/src/exec/loop.js +195 -34
- package/dist/packages/work/src/exec/runner.js +15 -5
- package/dist/packages/work/src/harness/claude.js +69 -9
- package/dist/packages/work/src/harness/codex.js +56 -8
- package/dist/packages/work/src/harness/contract.d.ts +65 -1
- package/dist/packages/work/src/harness/contract.js +56 -0
- package/dist/packages/work/src/harness/session-store.d.ts +3 -1
- package/dist/packages/work/src/harness/session-store.js +46 -22
- package/dist/packages/work/src/hold/mcp.js +9 -2
- package/dist/packages/work/src/hub/client.d.ts +7 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +71 -3
- package/dist/packages/work/src/roles/agent-run.js +8 -9
- package/dist/packages/work/src/roles/hold.d.ts +2 -0
- package/dist/packages/work/src/roles/hold.js +39 -8
- package/dist/packages/work/src/roles/settings.js +18 -6
- package/dist/packages/work/src/roles/shift.js +13 -1
- package/dist/packages/work/src/settings/settings.d.ts +60 -7
- package/dist/packages/work/src/settings/settings.js +69 -22
- package/dist/packages/work/src/shift/logretention.d.ts +253 -0
- package/dist/packages/work/src/shift/logretention.js +407 -0
- package/dist/packages/work/src/shift/logsink.d.ts +14 -0
- package/dist/packages/work/src/shift/logsink.js +98 -0
- package/dist/packages/work/src/shift/loop.d.ts +18 -1
- package/dist/packages/work/src/shift/loop.js +250 -12
- package/dist/packages/work/src/shift/protocol.d.ts +124 -1
- package/dist/packages/work/src/shift/protocol.js +14 -0
- package/dist/packages/work/src/shift/runtime.d.ts +14 -0
- package/dist/packages/work/src/shift/runtime.js +229 -6
- package/dist/packages/work/src/shift/server.d.ts +13 -0
- package/dist/packages/work/src/shift/server.js +61 -36
- package/dist/packages/work/src/shift/spawn.d.ts +78 -5
- package/dist/packages/work/src/shift/spawn.js +158 -12
- package/dist/packages/work/src/shift/state.d.ts +25 -0
- package/dist/packages/work/src/shift/state.js +29 -5
- package/dist/packages/work/src/shift/truncate.d.ts +35 -0
- package/dist/packages/work/src/shift/truncate.js +73 -0
- package/dist/packages/work/src/submit-proof.d.ts +31 -6
- package/dist/packages/work/src/submit-proof.js +33 -7
- package/dist/packages/work/src/submit-value.d.ts +48 -0
- package/dist/packages/work/src/submit-value.js +118 -0
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +11 -0
- package/dist/src/bundle/runtime.d.ts +1 -1
- package/dist/src/bundle/runtime.js +9 -0
- package/dist/src/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.js +37 -11
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +11 -0
- package/dist/src/defs.js +192 -4
- package/dist/src/engine.d.ts +112 -3
- package/dist/src/engine.js +224 -28
- package/dist/src/hub.d.ts +27 -11
- package/dist/src/hub.js +24 -18
- package/dist/src/index.d.ts +3 -1
- package/dist/src/index.js +4 -1
- package/dist/src/mcp/serve.js +11 -4
- package/dist/src/model.d.ts +36 -0
- package/dist/src/model.js +46 -0
- package/dist/src/schemas/index.d.ts +17 -0
- package/dist/src/schemas/order.v1.schema.json +17 -3
- package/dist/src/store.d.ts +33 -1
- package/dist/src/store.js +57 -4
- package/dist/src/types.d.ts +102 -2
- package/docs/agent-runner.md +26 -1
- package/docs/authoring.md +7 -0
- package/docs/bundles.md +103 -3
- package/docs/cli.md +127 -9
- package/docs/crypto.md +23 -7
- package/docs/shift-logs.md +642 -0
- package/docs/wire-contracts.md +34 -19
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
- package/dist/packages/work/src/agent/model-policy.js +0 -138
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
/** The shift's own structured JSON Lines log, inside the log directory. */
|
|
2
|
+
export declare const SHIFT_LOG_NAME = "shift.log";
|
|
3
|
+
/**
|
|
4
|
+
* `<log-dir>/shift.log` — the shift process's own structured log. Pure path
|
|
5
|
+
* math; creates nothing.
|
|
6
|
+
*/
|
|
7
|
+
export declare function shiftLogFile(logDir: string): string;
|
|
8
|
+
/**
|
|
9
|
+
* `<log-dir>/<run>.log` — one worker's raw output. Pure path math; creates
|
|
10
|
+
* nothing. Uses the SAME `safeRun` sanitizer `state.ts` uses for `<run>.json`,
|
|
11
|
+
* which is what makes basename correlation hold.
|
|
12
|
+
*/
|
|
13
|
+
export declare function runLogFile(logDir: string, run: string): string;
|
|
14
|
+
/**
|
|
15
|
+
* Default retention for worker logs: 14 days.
|
|
16
|
+
*
|
|
17
|
+
* Long enough to read a postmortem the week after something went wrong, short
|
|
18
|
+
* enough to bound disk on a machine that runs shifts continuously. Worker logs
|
|
19
|
+
* are unbounded in SIZE by design — the tail you would have capped away is
|
|
20
|
+
* exactly the pathological run you needed to read — so volume is bounded here,
|
|
21
|
+
* by age, instead.
|
|
22
|
+
*/
|
|
23
|
+
export declare const DEFAULT_SHIFT_LOG_MAX_AGE_MS: number;
|
|
24
|
+
/**
|
|
25
|
+
* Resolve the log directory: `--log-dir` > `OWENLOOP_SHIFT_LOG_DIR` >
|
|
26
|
+
* `settings.shiftLogDir` > the already-resolved state dir. Same precedence shape
|
|
27
|
+
* as `resolveWorkRoot` and `resolveStateDirOverride`, so there is one rule to
|
|
28
|
+
* remember.
|
|
29
|
+
*
|
|
30
|
+
* DEFAULTING TO THE STATE DIR is what makes correlation free: `<run>.log` lands
|
|
31
|
+
* beside the existing `<run>.json`, same basename. The correlation key is the
|
|
32
|
+
* BASENAME, not the adjacency — an operator who points `--log-dir` elsewhere
|
|
33
|
+
* moves the logs away from the records and basename correlation still holds.
|
|
34
|
+
*
|
|
35
|
+
* ALWAYS ABSOLUTE, for the same reason `resolveStateDir` is: this directory is
|
|
36
|
+
* the RENDEZVOUS between shift processes that may have been started from
|
|
37
|
+
* different working directories, and `.owners` inside it is read by whichever
|
|
38
|
+
* of them sweeps. Two spellings of one directory would be two rendezvous
|
|
39
|
+
* points, and a sweeping shift would not see the claims written under the
|
|
40
|
+
* other spelling.
|
|
41
|
+
*/
|
|
42
|
+
export declare function resolveShiftLogDir(flag: string | undefined, env: Record<string, string | undefined>, settingsLogDir: string | undefined, stateDir: string): string;
|
|
43
|
+
/**
|
|
44
|
+
* Resolve worker-log retention in milliseconds: `--log-max-age` >
|
|
45
|
+
* `OWENLOOP_SHIFT_LOG_MAX_AGE_MS` > `settings.shiftLogMaxAgeMs` >
|
|
46
|
+
* `DEFAULT_SHIFT_LOG_MAX_AGE_MS`. The env value is accepted only as a
|
|
47
|
+
* NON-NEGATIVE INTEGER: unparseable, negative, and non-integer values
|
|
48
|
+
* (`86400000.5`) are all ignored rather than fatal, and resolution falls through
|
|
49
|
+
* to the next source — a typo in an environment variable must not stop a shift
|
|
50
|
+
* from serving.
|
|
51
|
+
*/
|
|
52
|
+
export declare function resolveShiftLogMaxAgeMs(flag: number | undefined, env: Record<string, string | undefined>, settingsMaxAgeMs: number | undefined): number;
|
|
53
|
+
export interface ShiftLogReapGateInput {
|
|
54
|
+
/** The log file's basename, e.g. `run_7b29d1845b2926eba5dbc574.log`. */
|
|
55
|
+
name: string;
|
|
56
|
+
/** The log file's own last-modification time, in ms. */
|
|
57
|
+
mtimeMs: number;
|
|
58
|
+
/**
|
|
59
|
+
* Does the matching `<run>.json` in-flight record still exist in ANY state
|
|
60
|
+
* directory that logs into this directory? See `LOG_OWNERS_DIR_NAME`.
|
|
61
|
+
*/
|
|
62
|
+
hasRunRecord: boolean;
|
|
63
|
+
now: number;
|
|
64
|
+
maxAgeMs: number;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* May this log file be removed?
|
|
68
|
+
*
|
|
69
|
+
* PURE — no filesystem, no clock. That is what lets the truth table below be a
|
|
70
|
+
* unit test instead of an integration test.
|
|
71
|
+
*
|
|
72
|
+
* | `<run>.json` exists | older than maxAge | reap? |
|
|
73
|
+
* |---|---|---|
|
|
74
|
+
* | yes | any | NO — the run is still in flight (see the orphaned-inode note above) |
|
|
75
|
+
* | no | no | NO — recent, still the postmortem you would want |
|
|
76
|
+
* | no | yes | YES |
|
|
77
|
+
*
|
|
78
|
+
* NEVER reapable regardless of age: `shift.log` (the shift's own structured log,
|
|
79
|
+
* which this change does not rotate), anything not ending `.log`, and anything
|
|
80
|
+
* whose basename is not a `run_…` id. The log directory defaults to the state
|
|
81
|
+
* directory, which also holds `shift.sock`, `.dispatch.lock`, gate files and
|
|
82
|
+
* atomic-write temporaries — a sweep that removed by age alone would eat them.
|
|
83
|
+
*
|
|
84
|
+
* Unlike `isWorkDirReapable`, whose `lastSeenAt` is a DIRECTORY mtime and
|
|
85
|
+
* therefore a weak signal (a write deep inside a subtree does not update it),
|
|
86
|
+
* this gate reads the log file's OWN mtime, which the worker's every write
|
|
87
|
+
* updates. The signal is strong here, so the gate needs no grace window beyond
|
|
88
|
+
* the retention age.
|
|
89
|
+
*/
|
|
90
|
+
export declare function isShiftLogReapable(g: ShiftLogReapGateInput): boolean;
|
|
91
|
+
/**
|
|
92
|
+
* Is this basename a worker log this sweep owns?
|
|
93
|
+
*
|
|
94
|
+
* `<run>.log` where `<run>` is a run id as `state.ts` writes it — the same
|
|
95
|
+
* `run_…` shape, sanitized the same way. Exported so the sweep and the gate
|
|
96
|
+
* cannot disagree about what they own.
|
|
97
|
+
*/
|
|
98
|
+
export declare function isWorkerLogName(name: string): boolean;
|
|
99
|
+
/**
|
|
100
|
+
* Sub-directory of the log directory in which each shift declares WHICH state
|
|
101
|
+
* directory holds its in-flight `<run>.json` records.
|
|
102
|
+
*
|
|
103
|
+
* ── WHY A REGISTRY EXISTS AT ALL ──
|
|
104
|
+
*
|
|
105
|
+
* The in-flight gate asks "does `<run>.json` still exist?", and a shift can only
|
|
106
|
+
* answer that for the state directory it owns. `--log-dir` /
|
|
107
|
+
* `OWENLOOP_SHIFT_LOG_DIR` is a single global setting, so centralizing several
|
|
108
|
+
* crews' logs into ONE directory while each crew keeps its own per-crew state
|
|
109
|
+
* directory is the obvious way to use it. In that layout a sweeping shift sees
|
|
110
|
+
* another shift's `<run>.log` with no `<run>.json` anywhere IT can see, decides
|
|
111
|
+
* the run is finished, and unlinks a log a LIVE worker still holds a descriptor
|
|
112
|
+
* on — the exact orphaned-inode data loss the gate exists to prevent. At the
|
|
113
|
+
* 14-day default that needs a worker quiet for 14 days; at a reduced
|
|
114
|
+
* `--log-max-age` it fires against every live worker of every other shift.
|
|
115
|
+
*
|
|
116
|
+
* So each shift writes one claim naming its state directory, and the sweep
|
|
117
|
+
* treats a run as in flight if ANY claimed state directory still holds its
|
|
118
|
+
* record. One file per shift, named by a hash of the state directory it names,
|
|
119
|
+
* so two shifts starting at once each write their OWN file and no
|
|
120
|
+
* read-modify-write can lose a claim.
|
|
121
|
+
*
|
|
122
|
+
* A stale claim (a retired crew) is harmless: its state directory either no
|
|
123
|
+
* longer exists or holds no records, so it contributes no `true` and merely
|
|
124
|
+
* costs one `stat`. Erring toward keeping a log costs disk; erring the other way
|
|
125
|
+
* costs an operator the evidence they went looking for.
|
|
126
|
+
*/
|
|
127
|
+
export declare const LOG_OWNERS_DIR_NAME = ".owners";
|
|
128
|
+
/** `<log-dir>/.owners` — pure path math; creates nothing. */
|
|
129
|
+
export declare function logOwnersDir(logDir: string): string;
|
|
130
|
+
/**
|
|
131
|
+
* Declare that `stateDir` holds the in-flight records for the workers logging
|
|
132
|
+
* into `logDir`. Idempotent — re-run at every shift startup, rewriting the same
|
|
133
|
+
* path with the same bytes.
|
|
134
|
+
*
|
|
135
|
+
* WRITES THE ABSOLUTE PATH, and does not trust its caller to have resolved one.
|
|
136
|
+
* The reader of this file is a DIFFERENT process with a DIFFERENT working
|
|
137
|
+
* directory, and it joins `<run>.json` onto whatever string it finds here. A
|
|
138
|
+
* relative claim resolved against the reader's cwd probes a directory that does
|
|
139
|
+
* not exist, every probe answers "no record", and the sweep unlinks live
|
|
140
|
+
* workers' logs — which is precisely the failure this registry exists to
|
|
141
|
+
* prevent. Absoluteness is therefore an invariant OF THE REGISTRY, enforced at
|
|
142
|
+
* both ends, not an assumption about who calls it.
|
|
143
|
+
*
|
|
144
|
+
* THROWS on failure, deliberately: the caller decides what a shift that cannot
|
|
145
|
+
* claim its logs should do (see `runtime.ts`, which reports once and keeps
|
|
146
|
+
* dispatching, because an observability defect must not become an outage).
|
|
147
|
+
*/
|
|
148
|
+
export declare function registerShiftLogOwner(logDir: string, stateDir: string): string;
|
|
149
|
+
/**
|
|
150
|
+
* Every state directory that has claimed `logDir`, plus `ownStateDir` — which is
|
|
151
|
+
* included unconditionally so a sweep is never LESS informed than it was before
|
|
152
|
+
* the registry existed, even if the claim write failed or the directory is
|
|
153
|
+
* unreadable. Every returned path is absolute (see `registerShiftLogOwner`), so
|
|
154
|
+
* a caller joining `<run>.json` onto one of them probes the directory the
|
|
155
|
+
* claimant meant regardless of either process's working directory.
|
|
156
|
+
*
|
|
157
|
+
* Never throws. An absent registry (the default single-shift layout, where no
|
|
158
|
+
* claim has been written yet) and one unparseable claim both degrade to "that
|
|
159
|
+
* claim tells me nothing", not to a failed sweep. The try/catch is deliberately
|
|
160
|
+
* INSIDE the loop: one shift that crashed mid-write must cost its own logs
|
|
161
|
+
* only, never the other claimants' — an outer guard would blind the sweep to
|
|
162
|
+
* every claim after the corrupt one.
|
|
163
|
+
*/
|
|
164
|
+
export declare function readShiftLogOwners(logDir: string, ownStateDir: string): string[];
|
|
165
|
+
export interface SweepShiftLogsOptions {
|
|
166
|
+
/** The resolved log directory. */
|
|
167
|
+
dir: string;
|
|
168
|
+
/** Where THIS shift's `<run>.json` in-flight records live. */
|
|
169
|
+
stateDir: string;
|
|
170
|
+
/**
|
|
171
|
+
* Every state directory whose records gate this sweep. Defaults to
|
|
172
|
+
* `readShiftLogOwners(dir, stateDir)` — this shift's own, plus every other
|
|
173
|
+
* shift that has claimed the log directory. Injected for tests.
|
|
174
|
+
*/
|
|
175
|
+
stateDirs?: string[];
|
|
176
|
+
now: number;
|
|
177
|
+
maxAgeMs: number;
|
|
178
|
+
/** Progress/warning sink. */
|
|
179
|
+
err?: (line: string) => void;
|
|
180
|
+
/** Injected for tests; defaults to `node:fs` `readdirSync`. */
|
|
181
|
+
list?: (dir: string) => string[];
|
|
182
|
+
/** Injected for tests; defaults to `node:fs` `statSync().mtimeMs`. */
|
|
183
|
+
mtime?: (path: string) => number;
|
|
184
|
+
/** Injected for tests; defaults to `node:fs` `existsSync`-style probe. */
|
|
185
|
+
hasRecord?: (stateDir: string, name: string) => boolean;
|
|
186
|
+
/** Injected for tests; defaults to `node:fs` `rmSync`. */
|
|
187
|
+
remove?: (path: string) => void;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Apply `isShiftLogReapable` to every file in the log directory and remove the
|
|
191
|
+
* ones that pass. Returns the paths actually removed, so a caller can log a
|
|
192
|
+
* count.
|
|
193
|
+
*
|
|
194
|
+
* BEST EFFORT, NEVER THROWS. It runs at shift startup, before any work is
|
|
195
|
+
* dispatched, and a shift that cannot tidy its logs must still serve. Every
|
|
196
|
+
* per-file step is individually guarded: a locked, unreadable, or
|
|
197
|
+
* concurrently-removed file costs that one entry, not the sweep.
|
|
198
|
+
*/
|
|
199
|
+
export declare function sweepShiftLogs(o: SweepShiftLogsOptions): string[];
|
|
200
|
+
export interface PrepareShiftLogDirOptions {
|
|
201
|
+
/** `--log-dir`, if the operator passed one. */
|
|
202
|
+
flagDir?: string | undefined;
|
|
203
|
+
/** `--log-max-age`, if the operator passed one. */
|
|
204
|
+
flagMaxAgeMs?: number | undefined;
|
|
205
|
+
env: Record<string, string | undefined>;
|
|
206
|
+
settingsLogDir?: string | undefined;
|
|
207
|
+
settingsMaxAgeMs?: number | undefined;
|
|
208
|
+
/** This shift's ALREADY-RESOLVED state directory (absolute — see `resolveStateDir`). */
|
|
209
|
+
stateDir: string;
|
|
210
|
+
now: number;
|
|
211
|
+
/** Operator-facing report sink. Every line is prefixed with `label`. */
|
|
212
|
+
err: (line: string) => void;
|
|
213
|
+
/** The command's own name for its messages, e.g. `owenloop shift`. */
|
|
214
|
+
label: string;
|
|
215
|
+
}
|
|
216
|
+
export interface PreparedShiftLogDir {
|
|
217
|
+
/** The resolved, absolute log directory — valid whether or not it exists. */
|
|
218
|
+
dir: string;
|
|
219
|
+
maxAgeMs: number;
|
|
220
|
+
/**
|
|
221
|
+
* Did the directory come up? `false` means the caller must build NO log sink
|
|
222
|
+
* and pass NO log directory to the spawner, so workers keep the pre-logging
|
|
223
|
+
* `stdio: ['ignore','ignore','ignore']` topology.
|
|
224
|
+
*/
|
|
225
|
+
ready: boolean;
|
|
226
|
+
/** Paths the startup sweep removed. Empty when `ready` is `false`. */
|
|
227
|
+
reaped: string[];
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Everything that must happen to a log directory BEFORE the first dispatch:
|
|
231
|
+
* resolve it, create it, claim it for this shift's state directory, and sweep
|
|
232
|
+
* the worker logs that aged out.
|
|
233
|
+
*
|
|
234
|
+
* ── WHY THIS IS A FUNCTION AND NOT A BLOCK INSIDE `runtime.ts` ──
|
|
235
|
+
*
|
|
236
|
+
* It has five distinct failure branches (uncreatable directory, unclaimable
|
|
237
|
+
* registry, unscannable directory, unremovable file, a sweep that throws
|
|
238
|
+
* despite its never-throws contract) and every one of them must degrade to
|
|
239
|
+
* "less logging", never to "no shift". Driving those from a real
|
|
240
|
+
* `owenloop shift start` would mean five daemon processes; as a function it is
|
|
241
|
+
* five cheap calls against a temp directory, and `runtime.ts` keeps one call
|
|
242
|
+
* site whose wiring an acceptance test then proves once.
|
|
243
|
+
*
|
|
244
|
+
* NEVER THROWS. A shift whose only defect is that it cannot write a log must
|
|
245
|
+
* still dispatch work: refusing to start would turn an observability feature
|
|
246
|
+
* into an outage.
|
|
247
|
+
*
|
|
248
|
+
* ORDER MATTERS. The claim is written BEFORE the sweep so that this shift's own
|
|
249
|
+
* records gate its own sweep even on its very first startup, and so that a
|
|
250
|
+
* concurrently-starting sibling can see this shift's state directory rather
|
|
251
|
+
* than reaping its live workers' logs.
|
|
252
|
+
*/
|
|
253
|
+
export declare function prepareShiftLogDir(o: PrepareShiftLogDirOptions): PreparedShiftLogDir;
|
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where shift logs live, and the gate that removes worker logs.
|
|
3
|
+
*
|
|
4
|
+
* ── WHY THE LOG LIFETIME IS NOT THE RUN RECORD'S LIFETIME ──
|
|
5
|
+
*
|
|
6
|
+
* `state.ts` removes a run's `<run>.json` the moment its child completes. A log
|
|
7
|
+
* that inherited that lifecycle would be readable only while the run is still in
|
|
8
|
+
* flight — useless for the postmortem it exists for. So worker logs are swept by
|
|
9
|
+
* AGE, independently, and the run record's disappearance is what makes a log
|
|
10
|
+
* eligible rather than what deletes it.
|
|
11
|
+
*
|
|
12
|
+
* ── THE IN-FLIGHT GATE IS NOT TIDINESS ──
|
|
13
|
+
*
|
|
14
|
+
* A live worker holds an open descriptor on its log. On POSIX, unlinking that
|
|
15
|
+
* file makes it invisible while the child keeps writing to the now-orphaned
|
|
16
|
+
* inode: the bytes are produced, accounted against the filesystem, and lost.
|
|
17
|
+
* Refusing to reap any log whose `<run>.json` still exists is what prevents
|
|
18
|
+
* that.
|
|
19
|
+
*
|
|
20
|
+
* "Still exists" means in ANY state directory that writes logs here, not just
|
|
21
|
+
* the sweeping shift's own — several shifts may share one log directory while
|
|
22
|
+
* keeping separate per-crew state directories. `LOG_OWNERS_DIR_NAME` below is
|
|
23
|
+
* how a sweeping shift learns where the other shifts' records live.
|
|
24
|
+
*
|
|
25
|
+
* Shape mirrors `agent/workdir.ts`: a PURE truth-table gate (`isShiftLogReapable`)
|
|
26
|
+
* a unit test can drive with no filesystem, plus a best-effort sweep
|
|
27
|
+
* (`sweepShiftLogs`) that never throws, because a sweep must not die over one
|
|
28
|
+
* file.
|
|
29
|
+
*/
|
|
30
|
+
import { createHash } from 'node:crypto';
|
|
31
|
+
import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
|
|
32
|
+
import { join, resolve } from 'node:path';
|
|
33
|
+
import { safeRun } from "./state.js";
|
|
34
|
+
/** The shift's own structured JSON Lines log, inside the log directory. */
|
|
35
|
+
export const SHIFT_LOG_NAME = 'shift.log';
|
|
36
|
+
/**
|
|
37
|
+
* `<log-dir>/shift.log` — the shift process's own structured log. Pure path
|
|
38
|
+
* math; creates nothing.
|
|
39
|
+
*/
|
|
40
|
+
export function shiftLogFile(logDir) {
|
|
41
|
+
return join(logDir, SHIFT_LOG_NAME);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* `<log-dir>/<run>.log` — one worker's raw output. Pure path math; creates
|
|
45
|
+
* nothing. Uses the SAME `safeRun` sanitizer `state.ts` uses for `<run>.json`,
|
|
46
|
+
* which is what makes basename correlation hold.
|
|
47
|
+
*/
|
|
48
|
+
export function runLogFile(logDir, run) {
|
|
49
|
+
return join(logDir, `${safeRun(run)}.log`);
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Default retention for worker logs: 14 days.
|
|
53
|
+
*
|
|
54
|
+
* Long enough to read a postmortem the week after something went wrong, short
|
|
55
|
+
* enough to bound disk on a machine that runs shifts continuously. Worker logs
|
|
56
|
+
* are unbounded in SIZE by design — the tail you would have capped away is
|
|
57
|
+
* exactly the pathological run you needed to read — so volume is bounded here,
|
|
58
|
+
* by age, instead.
|
|
59
|
+
*/
|
|
60
|
+
export const DEFAULT_SHIFT_LOG_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
|
|
61
|
+
/**
|
|
62
|
+
* Resolve the log directory: `--log-dir` > `OWENLOOP_SHIFT_LOG_DIR` >
|
|
63
|
+
* `settings.shiftLogDir` > the already-resolved state dir. Same precedence shape
|
|
64
|
+
* as `resolveWorkRoot` and `resolveStateDirOverride`, so there is one rule to
|
|
65
|
+
* remember.
|
|
66
|
+
*
|
|
67
|
+
* DEFAULTING TO THE STATE DIR is what makes correlation free: `<run>.log` lands
|
|
68
|
+
* beside the existing `<run>.json`, same basename. The correlation key is the
|
|
69
|
+
* BASENAME, not the adjacency — an operator who points `--log-dir` elsewhere
|
|
70
|
+
* moves the logs away from the records and basename correlation still holds.
|
|
71
|
+
*
|
|
72
|
+
* ALWAYS ABSOLUTE, for the same reason `resolveStateDir` is: this directory is
|
|
73
|
+
* the RENDEZVOUS between shift processes that may have been started from
|
|
74
|
+
* different working directories, and `.owners` inside it is read by whichever
|
|
75
|
+
* of them sweeps. Two spellings of one directory would be two rendezvous
|
|
76
|
+
* points, and a sweeping shift would not see the claims written under the
|
|
77
|
+
* other spelling.
|
|
78
|
+
*/
|
|
79
|
+
export function resolveShiftLogDir(flag, env, settingsLogDir, stateDir) {
|
|
80
|
+
if (flag !== undefined && flag.trim() !== '')
|
|
81
|
+
return resolve(flag);
|
|
82
|
+
const override = env['OWENLOOP_SHIFT_LOG_DIR'];
|
|
83
|
+
if (override !== undefined && override.trim() !== '')
|
|
84
|
+
return resolve(override);
|
|
85
|
+
if (settingsLogDir !== undefined && settingsLogDir.trim() !== '')
|
|
86
|
+
return resolve(settingsLogDir);
|
|
87
|
+
return resolve(stateDir);
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Resolve worker-log retention in milliseconds: `--log-max-age` >
|
|
91
|
+
* `OWENLOOP_SHIFT_LOG_MAX_AGE_MS` > `settings.shiftLogMaxAgeMs` >
|
|
92
|
+
* `DEFAULT_SHIFT_LOG_MAX_AGE_MS`. The env value is accepted only as a
|
|
93
|
+
* NON-NEGATIVE INTEGER: unparseable, negative, and non-integer values
|
|
94
|
+
* (`86400000.5`) are all ignored rather than fatal, and resolution falls through
|
|
95
|
+
* to the next source — a typo in an environment variable must not stop a shift
|
|
96
|
+
* from serving.
|
|
97
|
+
*/
|
|
98
|
+
export function resolveShiftLogMaxAgeMs(flag, env, settingsMaxAgeMs) {
|
|
99
|
+
if (flag !== undefined)
|
|
100
|
+
return flag;
|
|
101
|
+
const raw = env['OWENLOOP_SHIFT_LOG_MAX_AGE_MS'];
|
|
102
|
+
if (raw !== undefined && raw.trim() !== '') {
|
|
103
|
+
const parsed = Number(raw);
|
|
104
|
+
if (Number.isFinite(parsed) && Number.isInteger(parsed) && parsed >= 0)
|
|
105
|
+
return parsed;
|
|
106
|
+
}
|
|
107
|
+
if (settingsMaxAgeMs !== undefined)
|
|
108
|
+
return settingsMaxAgeMs;
|
|
109
|
+
return DEFAULT_SHIFT_LOG_MAX_AGE_MS;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* May this log file be removed?
|
|
113
|
+
*
|
|
114
|
+
* PURE — no filesystem, no clock. That is what lets the truth table below be a
|
|
115
|
+
* unit test instead of an integration test.
|
|
116
|
+
*
|
|
117
|
+
* | `<run>.json` exists | older than maxAge | reap? |
|
|
118
|
+
* |---|---|---|
|
|
119
|
+
* | yes | any | NO — the run is still in flight (see the orphaned-inode note above) |
|
|
120
|
+
* | no | no | NO — recent, still the postmortem you would want |
|
|
121
|
+
* | no | yes | YES |
|
|
122
|
+
*
|
|
123
|
+
* NEVER reapable regardless of age: `shift.log` (the shift's own structured log,
|
|
124
|
+
* which this change does not rotate), anything not ending `.log`, and anything
|
|
125
|
+
* whose basename is not a `run_…` id. The log directory defaults to the state
|
|
126
|
+
* directory, which also holds `shift.sock`, `.dispatch.lock`, gate files and
|
|
127
|
+
* atomic-write temporaries — a sweep that removed by age alone would eat them.
|
|
128
|
+
*
|
|
129
|
+
* Unlike `isWorkDirReapable`, whose `lastSeenAt` is a DIRECTORY mtime and
|
|
130
|
+
* therefore a weak signal (a write deep inside a subtree does not update it),
|
|
131
|
+
* this gate reads the log file's OWN mtime, which the worker's every write
|
|
132
|
+
* updates. The signal is strong here, so the gate needs no grace window beyond
|
|
133
|
+
* the retention age.
|
|
134
|
+
*/
|
|
135
|
+
export function isShiftLogReapable(g) {
|
|
136
|
+
if (!isWorkerLogName(g.name))
|
|
137
|
+
return false;
|
|
138
|
+
if (g.hasRunRecord)
|
|
139
|
+
return false;
|
|
140
|
+
return g.now - g.mtimeMs >= g.maxAgeMs;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Is this basename a worker log this sweep owns?
|
|
144
|
+
*
|
|
145
|
+
* `<run>.log` where `<run>` is a run id as `state.ts` writes it — the same
|
|
146
|
+
* `run_…` shape, sanitized the same way. Exported so the sweep and the gate
|
|
147
|
+
* cannot disagree about what they own.
|
|
148
|
+
*/
|
|
149
|
+
export function isWorkerLogName(name) {
|
|
150
|
+
if (name === SHIFT_LOG_NAME)
|
|
151
|
+
return false;
|
|
152
|
+
if (!name.endsWith('.log'))
|
|
153
|
+
return false;
|
|
154
|
+
return /^run_[A-Za-z0-9_.-]+$/u.test(name.slice(0, -'.log'.length));
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Sub-directory of the log directory in which each shift declares WHICH state
|
|
158
|
+
* directory holds its in-flight `<run>.json` records.
|
|
159
|
+
*
|
|
160
|
+
* ── WHY A REGISTRY EXISTS AT ALL ──
|
|
161
|
+
*
|
|
162
|
+
* The in-flight gate asks "does `<run>.json` still exist?", and a shift can only
|
|
163
|
+
* answer that for the state directory it owns. `--log-dir` /
|
|
164
|
+
* `OWENLOOP_SHIFT_LOG_DIR` is a single global setting, so centralizing several
|
|
165
|
+
* crews' logs into ONE directory while each crew keeps its own per-crew state
|
|
166
|
+
* directory is the obvious way to use it. In that layout a sweeping shift sees
|
|
167
|
+
* another shift's `<run>.log` with no `<run>.json` anywhere IT can see, decides
|
|
168
|
+
* the run is finished, and unlinks a log a LIVE worker still holds a descriptor
|
|
169
|
+
* on — the exact orphaned-inode data loss the gate exists to prevent. At the
|
|
170
|
+
* 14-day default that needs a worker quiet for 14 days; at a reduced
|
|
171
|
+
* `--log-max-age` it fires against every live worker of every other shift.
|
|
172
|
+
*
|
|
173
|
+
* So each shift writes one claim naming its state directory, and the sweep
|
|
174
|
+
* treats a run as in flight if ANY claimed state directory still holds its
|
|
175
|
+
* record. One file per shift, named by a hash of the state directory it names,
|
|
176
|
+
* so two shifts starting at once each write their OWN file and no
|
|
177
|
+
* read-modify-write can lose a claim.
|
|
178
|
+
*
|
|
179
|
+
* A stale claim (a retired crew) is harmless: its state directory either no
|
|
180
|
+
* longer exists or holds no records, so it contributes no `true` and merely
|
|
181
|
+
* costs one `stat`. Erring toward keeping a log costs disk; erring the other way
|
|
182
|
+
* costs an operator the evidence they went looking for.
|
|
183
|
+
*/
|
|
184
|
+
export const LOG_OWNERS_DIR_NAME = '.owners';
|
|
185
|
+
/** `<log-dir>/.owners` — pure path math; creates nothing. */
|
|
186
|
+
export function logOwnersDir(logDir) {
|
|
187
|
+
return join(logDir, LOG_OWNERS_DIR_NAME);
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* The claim filename for one state directory. A hash, not the path itself:
|
|
191
|
+
* a state directory path is not a safe filename, and the hash makes each shift's
|
|
192
|
+
* write land on its own name so concurrent claims cannot clobber each other.
|
|
193
|
+
*
|
|
194
|
+
* Hashes the ABSOLUTE path. Hashing whatever spelling the caller happened to
|
|
195
|
+
* hold would give `./state` and `/a/state` two different names for one
|
|
196
|
+
* directory, so one shift restarted from a different working directory would
|
|
197
|
+
* accumulate a second claim file and contradict "one file per shift".
|
|
198
|
+
*/
|
|
199
|
+
function ownerClaimName(stateDir) {
|
|
200
|
+
return `${createHash('sha256').update(resolve(stateDir)).digest('hex').slice(0, 16)}.json`;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Declare that `stateDir` holds the in-flight records for the workers logging
|
|
204
|
+
* into `logDir`. Idempotent — re-run at every shift startup, rewriting the same
|
|
205
|
+
* path with the same bytes.
|
|
206
|
+
*
|
|
207
|
+
* WRITES THE ABSOLUTE PATH, and does not trust its caller to have resolved one.
|
|
208
|
+
* The reader of this file is a DIFFERENT process with a DIFFERENT working
|
|
209
|
+
* directory, and it joins `<run>.json` onto whatever string it finds here. A
|
|
210
|
+
* relative claim resolved against the reader's cwd probes a directory that does
|
|
211
|
+
* not exist, every probe answers "no record", and the sweep unlinks live
|
|
212
|
+
* workers' logs — which is precisely the failure this registry exists to
|
|
213
|
+
* prevent. Absoluteness is therefore an invariant OF THE REGISTRY, enforced at
|
|
214
|
+
* both ends, not an assumption about who calls it.
|
|
215
|
+
*
|
|
216
|
+
* THROWS on failure, deliberately: the caller decides what a shift that cannot
|
|
217
|
+
* claim its logs should do (see `runtime.ts`, which reports once and keeps
|
|
218
|
+
* dispatching, because an observability defect must not become an outage).
|
|
219
|
+
*/
|
|
220
|
+
export function registerShiftLogOwner(logDir, stateDir) {
|
|
221
|
+
const dir = logOwnersDir(resolve(logDir));
|
|
222
|
+
// 0700 on the registry directory and 0600 on the claim. A claim names an
|
|
223
|
+
// absolute filesystem path on this host, which is a layout disclosure and not
|
|
224
|
+
// something every local account needs. Both modes apply at CREATION only, so
|
|
225
|
+
// an existing `.owners/` from an earlier build keeps its mode — `mkdirSync`
|
|
226
|
+
// never chmods a directory that is already there.
|
|
227
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
228
|
+
const path = join(dir, ownerClaimName(stateDir));
|
|
229
|
+
writeFileSync(path, `${JSON.stringify({ stateDir: resolve(stateDir) })}\n`, { mode: 0o600 });
|
|
230
|
+
return path;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Every state directory that has claimed `logDir`, plus `ownStateDir` — which is
|
|
234
|
+
* included unconditionally so a sweep is never LESS informed than it was before
|
|
235
|
+
* the registry existed, even if the claim write failed or the directory is
|
|
236
|
+
* unreadable. Every returned path is absolute (see `registerShiftLogOwner`), so
|
|
237
|
+
* a caller joining `<run>.json` onto one of them probes the directory the
|
|
238
|
+
* claimant meant regardless of either process's working directory.
|
|
239
|
+
*
|
|
240
|
+
* Never throws. An absent registry (the default single-shift layout, where no
|
|
241
|
+
* claim has been written yet) and one unparseable claim both degrade to "that
|
|
242
|
+
* claim tells me nothing", not to a failed sweep. The try/catch is deliberately
|
|
243
|
+
* INSIDE the loop: one shift that crashed mid-write must cost its own logs
|
|
244
|
+
* only, never the other claimants' — an outer guard would blind the sweep to
|
|
245
|
+
* every claim after the corrupt one.
|
|
246
|
+
*/
|
|
247
|
+
export function readShiftLogOwners(logDir, ownStateDir) {
|
|
248
|
+
const owners = new Set([resolve(ownStateDir)]);
|
|
249
|
+
const dir = logOwnersDir(resolve(logDir));
|
|
250
|
+
let names;
|
|
251
|
+
try {
|
|
252
|
+
names = readdirSync(dir);
|
|
253
|
+
}
|
|
254
|
+
catch {
|
|
255
|
+
return [...owners];
|
|
256
|
+
}
|
|
257
|
+
for (const name of names) {
|
|
258
|
+
if (!name.endsWith('.json'))
|
|
259
|
+
continue;
|
|
260
|
+
try {
|
|
261
|
+
const parsed = JSON.parse(readFileSync(join(dir, name), 'utf8'));
|
|
262
|
+
const claimed = parsed.stateDir;
|
|
263
|
+
if (typeof claimed === 'string' && claimed.trim() !== '')
|
|
264
|
+
owners.add(resolve(claimed));
|
|
265
|
+
}
|
|
266
|
+
catch {
|
|
267
|
+
// One corrupt claim must not blind the sweep to the others. It can only
|
|
268
|
+
// cost the claimant's own logs, and only if that shift never rewrites it.
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
return [...owners];
|
|
272
|
+
}
|
|
273
|
+
function defaultHasRecord(stateDir, logName) {
|
|
274
|
+
const record = join(stateDir, `${logName.slice(0, -'.log'.length)}.json`);
|
|
275
|
+
try {
|
|
276
|
+
statSync(record);
|
|
277
|
+
return true;
|
|
278
|
+
}
|
|
279
|
+
catch {
|
|
280
|
+
return false;
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Apply `isShiftLogReapable` to every file in the log directory and remove the
|
|
285
|
+
* ones that pass. Returns the paths actually removed, so a caller can log a
|
|
286
|
+
* count.
|
|
287
|
+
*
|
|
288
|
+
* BEST EFFORT, NEVER THROWS. It runs at shift startup, before any work is
|
|
289
|
+
* dispatched, and a shift that cannot tidy its logs must still serve. Every
|
|
290
|
+
* per-file step is individually guarded: a locked, unreadable, or
|
|
291
|
+
* concurrently-removed file costs that one entry, not the sweep.
|
|
292
|
+
*/
|
|
293
|
+
export function sweepShiftLogs(o) {
|
|
294
|
+
const list = o.list ?? ((dir) => readdirSync(dir));
|
|
295
|
+
const mtime = o.mtime ?? ((path) => statSync(path).mtimeMs);
|
|
296
|
+
const hasRecord = o.hasRecord ?? defaultHasRecord;
|
|
297
|
+
// A run is in flight if ANY shift that logs here still holds its record — not
|
|
298
|
+
// just this one. See `LOG_OWNERS_DIR_NAME` for why a single-state-dir probe
|
|
299
|
+
// silently reaps other shifts' live logs.
|
|
300
|
+
const stateDirs = o.stateDirs ?? readShiftLogOwners(o.dir, o.stateDir);
|
|
301
|
+
const remove = o.remove ?? ((path) => {
|
|
302
|
+
rmSync(path, { force: true });
|
|
303
|
+
});
|
|
304
|
+
const removed = [];
|
|
305
|
+
let names;
|
|
306
|
+
try {
|
|
307
|
+
names = list(o.dir);
|
|
308
|
+
}
|
|
309
|
+
catch (e) {
|
|
310
|
+
o.err?.(`owenloop shift: could not scan shift logs in ${o.dir}: ${errMsg(e)} (ignored)`);
|
|
311
|
+
return removed;
|
|
312
|
+
}
|
|
313
|
+
for (const name of names) {
|
|
314
|
+
const path = join(o.dir, name);
|
|
315
|
+
try {
|
|
316
|
+
if (!isWorkerLogName(name))
|
|
317
|
+
continue;
|
|
318
|
+
if (!isShiftLogReapable({
|
|
319
|
+
name,
|
|
320
|
+
mtimeMs: mtime(path),
|
|
321
|
+
hasRunRecord: stateDirs.some((stateDir) => hasRecord(stateDir, name)),
|
|
322
|
+
now: o.now,
|
|
323
|
+
maxAgeMs: o.maxAgeMs,
|
|
324
|
+
}))
|
|
325
|
+
continue;
|
|
326
|
+
remove(path);
|
|
327
|
+
removed.push(path);
|
|
328
|
+
}
|
|
329
|
+
catch (e) {
|
|
330
|
+
o.err?.(`owenloop shift: could not reap shift log ${path}: ${errMsg(e)} (ignored)`);
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
return removed;
|
|
334
|
+
}
|
|
335
|
+
function errMsg(err) {
|
|
336
|
+
return err instanceof Error ? err.message : String(err);
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Everything that must happen to a log directory BEFORE the first dispatch:
|
|
340
|
+
* resolve it, create it, claim it for this shift's state directory, and sweep
|
|
341
|
+
* the worker logs that aged out.
|
|
342
|
+
*
|
|
343
|
+
* ── WHY THIS IS A FUNCTION AND NOT A BLOCK INSIDE `runtime.ts` ──
|
|
344
|
+
*
|
|
345
|
+
* It has five distinct failure branches (uncreatable directory, unclaimable
|
|
346
|
+
* registry, unscannable directory, unremovable file, a sweep that throws
|
|
347
|
+
* despite its never-throws contract) and every one of them must degrade to
|
|
348
|
+
* "less logging", never to "no shift". Driving those from a real
|
|
349
|
+
* `owenloop shift start` would mean five daemon processes; as a function it is
|
|
350
|
+
* five cheap calls against a temp directory, and `runtime.ts` keeps one call
|
|
351
|
+
* site whose wiring an acceptance test then proves once.
|
|
352
|
+
*
|
|
353
|
+
* NEVER THROWS. A shift whose only defect is that it cannot write a log must
|
|
354
|
+
* still dispatch work: refusing to start would turn an observability feature
|
|
355
|
+
* into an outage.
|
|
356
|
+
*
|
|
357
|
+
* ORDER MATTERS. The claim is written BEFORE the sweep so that this shift's own
|
|
358
|
+
* records gate its own sweep even on its very first startup, and so that a
|
|
359
|
+
* concurrently-starting sibling can see this shift's state directory rather
|
|
360
|
+
* than reaping its live workers' logs.
|
|
361
|
+
*/
|
|
362
|
+
export function prepareShiftLogDir(o) {
|
|
363
|
+
const dir = resolveShiftLogDir(o.flagDir, o.env, o.settingsLogDir, o.stateDir);
|
|
364
|
+
const maxAgeMs = resolveShiftLogMaxAgeMs(o.flagMaxAgeMs, o.env, o.settingsMaxAgeMs);
|
|
365
|
+
try {
|
|
366
|
+
// 0700 WHEN THIS CALL CREATES THE DIRECTORY. The directory holds worker
|
|
367
|
+
// logs of authored workflow content, and the files inside are 0600, so a
|
|
368
|
+
// world-traversable parent would only advertise their names. `mkdirSync`
|
|
369
|
+
// does NOT chmod a directory that already exists, and that is the escape
|
|
370
|
+
// hatch for a site that wants a shared drop directory a separate uploader
|
|
371
|
+
// account can read: pre-create `--log-dir` with the group and mode that
|
|
372
|
+
// account needs, and this call leaves it exactly as found. The two log
|
|
373
|
+
// FILES stay 0600 either way — a shared directory is an operator's choice
|
|
374
|
+
// to make, and it does not make the bytes inside less sensitive.
|
|
375
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
376
|
+
}
|
|
377
|
+
catch (err) {
|
|
378
|
+
o.err(`${o.label}: cannot create shift log directory ${dir}: ${errMsg(err)} — ` +
|
|
379
|
+
'continuing with logging disabled');
|
|
380
|
+
return { dir, maxAgeMs, ready: false, reaped: [] };
|
|
381
|
+
}
|
|
382
|
+
// A failed claim costs retention SAFETY, not dispatch: another shift sharing
|
|
383
|
+
// this directory can no longer see our in-flight records and may reap our
|
|
384
|
+
// live workers' logs. Report it and keep going — that is a degraded log, and
|
|
385
|
+
// an outage is worse.
|
|
386
|
+
try {
|
|
387
|
+
registerShiftLogOwner(dir, o.stateDir);
|
|
388
|
+
}
|
|
389
|
+
catch (err) {
|
|
390
|
+
o.err(`${o.label}: cannot record this shift's claim on ${dir}: ${errMsg(err)} — ` +
|
|
391
|
+
"another shift sharing this log directory may reap this one's worker logs");
|
|
392
|
+
}
|
|
393
|
+
// `sweepShiftLogs` never throws by contract; this guard is belt-and-braces so
|
|
394
|
+
// a future change to it can never become a startup failure.
|
|
395
|
+
let reaped = [];
|
|
396
|
+
try {
|
|
397
|
+
reaped = sweepShiftLogs({ dir, stateDir: o.stateDir, now: o.now, maxAgeMs, err: o.err });
|
|
398
|
+
if (reaped.length > 0) {
|
|
399
|
+
o.err(`${o.label}: reaped ${String(reaped.length)} worker log(s) older than ` +
|
|
400
|
+
`${String(maxAgeMs)}ms from ${dir}`);
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
catch (err) {
|
|
404
|
+
o.err(`${o.label}: shift log sweep failed (continuing): ${errMsg(err)}`);
|
|
405
|
+
}
|
|
406
|
+
return { dir, maxAgeMs, ready: true, reaped };
|
|
407
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { type ShiftEvent } from './protocol.ts';
|
|
2
|
+
export interface ShiftLogSinkOptions {
|
|
3
|
+
/** Absolute path of the JSON Lines file to append to. */
|
|
4
|
+
path: string;
|
|
5
|
+
/** Where the one-time failure report goes. Never the sink itself. */
|
|
6
|
+
err: (line: string) => void;
|
|
7
|
+
/** Injected for tests; defaults to `node:fs` `appendFileSync`. */
|
|
8
|
+
append?: (path: string, line: string) => void;
|
|
9
|
+
}
|
|
10
|
+
export interface ShiftLogSink {
|
|
11
|
+
/** Append one event as a single JSON Lines record. Never throws. */
|
|
12
|
+
write(event: ShiftEvent): void;
|
|
13
|
+
}
|
|
14
|
+
export declare function createShiftLogSink(opts: ShiftLogSinkOptions): ShiftLogSink;
|