@crewhaus/runtime-core 0.7.0 → 0.8.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.
@@ -0,0 +1,559 @@
1
+ /**
2
+ * 0.8.0 (design/0.8.0-provability-release.md §1 principle 1, §5.2, §5.3) —
3
+ * where the runtime keeps its own record of a run, and the files that
4
+ * control it. The run hands these roots to permission-engine's
5
+ * runtime-state floor (`EvaluateOptions.protectedRoots`), which no rule can
6
+ * lift: it denies a call that writes inside one. `Bash` and `RunCommand`
7
+ * remain outside what it can see.
8
+ *
9
+ * - The record the gates read as evidence: the session event logs (every
10
+ * `tool_use` input and `tool_result` output, verbatim — the evidence the
11
+ * provability gate grounds a claim on and `continuity.proof` resolves),
12
+ * the tool results the runtime spilled to a file (the whole output a long
13
+ * fetch grounds on, whose head alone the log holds) and the proof bundles
14
+ * (the audit artifact). Evidence is checked, never believed, only while
15
+ * the agent cannot write it: a `Write` that appends a hand-made fetch to
16
+ * the log would ground any text under any URL.
17
+ * - The files that control the run, which decide what the agent may do
18
+ * next: the harness's run directory (`.crewhaus/run`: the runfiles, logs
19
+ * and control files a daemon keeps there), its settings file
20
+ * (`.crewhaus/settings.json`: permission rules, runtime hooks and the
21
+ * manager's spawn hooks) and Hangar's directory (the Hangar root, where
22
+ * `crewhaus hangar` keeps its token and settings) and registry file.
23
+ * - The records a harness's gates and janitors keep: the deploy approvals and
24
+ * environments, the graders, the judge calibration, the evals, datasets,
25
+ * retention pins, audit trail, graph checkpoints and advice.
26
+ * - The operator's configuration in the working directory: the environment
27
+ * files Bun loads there, any file `manager.envFiles` declares, and the
28
+ * `bunfig.toml` and `.npmrc` there.
29
+ * - A managed run's whole tenants root, and the approvals file beside session
30
+ * logs that a session directory puts at the working directory.
31
+ * - In a harness's own directory, what its next start runs. Each test here is
32
+ * the weakest that matches what it protects ({@link Standing}): a directory
33
+ * that holds a spec keeps `dist`, `build` and `node_modules` as generated
34
+ * trees; a compiled non-interactive bundle running from there also keeps the
35
+ * spec and the root `package.json`, `tsconfig.json` and `jsconfig.json`; a
36
+ * bundle started from inside its own directory keeps its code files, its
37
+ * manifest and lockfile, its dependencies and the spec's names; a compiled
38
+ * non-interactive bundle in a directory below keeps that directory and what
39
+ * lies between it and the working directory. A plain project, a project under
40
+ * another harness and an interactive target keep editing their own files.
41
+ *
42
+ * CrewHaus's own code still writes all of them; the floor applies to tool
43
+ * calls only.
44
+ *
45
+ * Each root is given every way a path the canonicaliser produces can spell
46
+ * it: absolute as resolved, absolute with symlinks followed (macOS's
47
+ * `/var` → `/private/var`; a root that does not exist yet is followed as far
48
+ * as it does), and workspace-relative when it lies inside the working
49
+ * directory, as resolved and with links followed (what a tool that declares no
50
+ * operative arguments carries, and what the floor compares a directory the
51
+ * call acts beneath with).
52
+ */
53
+ import { AsyncLocalStorage } from "node:async_hooks";
54
+ import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
55
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
56
+ import { DEFAULT_ROOT_DIR } from "@crewhaus/event-log";
57
+ import { hangarStateRoots, registryStateFiles } from "@crewhaus/harness-registry";
58
+ import { DEFAULT_APPROVALS_FILENAME } from "@crewhaus/session-store";
59
+ import { DEFAULT_ROOT_DIR as TOOL_RESULTS_ROOT_DIR } from "@crewhaus/tool-result-store";
60
+ import { protectedRootHolding, rootsBesideStore } from "@crewhaus/tool-safety/fs";
61
+ /**
62
+ * The files that control a run, relative to its working directory: the run
63
+ * directory, all of it, and the settings file, exactly that file (its
64
+ * neighbours, such as `settings.json.bak` or `.crewhaus/notes.md`, are not
65
+ * protected).
66
+ */
67
+ const CONTROL_FILES = [
68
+ join(".crewhaus", "run"),
69
+ join(".crewhaus", "settings.json"),
70
+ ];
71
+ /** The records a harness's gates and janitors keep. */
72
+ const GATE_RECORDS = [
73
+ join(".crewhaus", "approvals"),
74
+ join(".crewhaus", "environments.json"),
75
+ join(".crewhaus", "graders"),
76
+ join(".crewhaus", "judge-calibration.json"),
77
+ join(".crewhaus", "evals"),
78
+ join(".crewhaus", "datasets"),
79
+ join(".crewhaus", "retention.json"),
80
+ join(".crewhaus", "audit"),
81
+ join(".crewhaus", "graphs"),
82
+ join(".crewhaus", "advice"),
83
+ ];
84
+ /** Every file Bun loads into a process started here, whichever NODE_ENV. */
85
+ const ENV_FILES = [
86
+ ".env",
87
+ ".env.local",
88
+ ".env.development",
89
+ ".env.development.local",
90
+ ".env.production",
91
+ ".env.production.local",
92
+ ".env.test",
93
+ ".env.test.local",
94
+ ];
95
+ /** What Bun and npm read from the working directory of any process. */
96
+ const START_CONFIG = ["bunfig.toml", ".npmrc"];
97
+ /** The names a spec goes by at a harness's root. */
98
+ const SPEC_NAMES = ["crewhaus.yaml", "crewhaus.yml"];
99
+ /** The trees `crewhaus compile` and a package manager generate at a harness's root. */
100
+ const INSTALLED_TREES = ["dist", "build", "node_modules"];
101
+ /** What a compiled non-interactive harness reads when it starts or compiles again. */
102
+ const COMPILED_INPUTS = [
103
+ ...SPEC_NAMES,
104
+ "tsconfig.json",
105
+ "jsconfig.json",
106
+ "package.json",
107
+ ];
108
+ /**
109
+ * The name `crewhaus compile` stamps in the manifest beside a bundle's entry.
110
+ * Mirrors `BUNDLE_MANIFEST_NAME` in `@crewhaus/harness-supervisor`, which this
111
+ * package does not depend on; a test holds the two equal.
112
+ */
113
+ export const COMPILED_BUNDLE_NAME = "crewhaus-compiled-bundle";
114
+ /** The spec's own `target:` line. */
115
+ const TARGET_LINE = /^target:\s*["']?([A-Za-z-]+)/m;
116
+ /** The spellings of a code file's name, which all stand for one module. */
117
+ const CODE_EXTENSIONS = [
118
+ ".ts",
119
+ ".tsx",
120
+ ".js",
121
+ ".jsx",
122
+ ".mjs",
123
+ ".cjs",
124
+ ".mts",
125
+ ".cts",
126
+ ];
127
+ /** A bundle's code, at the top of the directory it runs from. */
128
+ const BUNDLE_CODE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
129
+ /** A lockfile at the top of the directory a bundle runs from. */
130
+ const BUNDLE_LOCK = /\.lock$/;
131
+ /**
132
+ * What a bundle resolves its modules and installs its dependencies from, whether
133
+ * or not each exists yet. Other JSON at the top of its directory is an agent's
134
+ * own data: `crewhaus compile` emits no other JSON file there.
135
+ */
136
+ const BUNDLE_CONFIG = [
137
+ "node_modules",
138
+ "tsconfig.json",
139
+ "jsconfig.json",
140
+ "package.json",
141
+ ];
142
+ /** The lockfile a bundle's install reads, whether or not it exists yet. */
143
+ const BUNDLE_LOCKFILES = ["bun.lock", "bun.lockb"];
144
+ /** The header a target's emitter writes at the top of a bundle's entry. */
145
+ const ENTRY_TARGET = /^\/\/ Source spec: .*\(target: ([A-Za-z-]+),/m;
146
+ /**
147
+ * The gate records a tool keeps its own store in, through a format of its own:
148
+ * `DatasetPut` adds a version to `.crewhaus/datasets` and `EvalBaselinePin` a
149
+ * pin to `.crewhaus/evals` ({@link relocatingFieldLeftOut}). Written out, so a
150
+ * root added later is the floor's until someone puts it here on purpose.
151
+ */
152
+ const TOOL_STORES = [join(".crewhaus", "datasets"), join(".crewhaus", "evals")];
153
+ /** `path` with every symlink on its existing part followed, or `undefined` when nothing of it exists. */
154
+ function followed(path) {
155
+ const rest = [];
156
+ let head = path;
157
+ for (let depth = 0; depth < 256; depth += 1) {
158
+ try {
159
+ const real = realpathSync(head);
160
+ // Rebuilt one name at a time: the list is never spread into join.
161
+ return rest.reduceRight((built, name) => join(built, name), real);
162
+ }
163
+ catch {
164
+ const parent = dirname(head);
165
+ if (parent === head)
166
+ return undefined;
167
+ rest.push(basename(head));
168
+ head = parent;
169
+ }
170
+ }
171
+ return undefined;
172
+ }
173
+ /** Is `inner` `outer` itself, or inside it? */
174
+ function within(inner, outer) {
175
+ const rel = relative(outer, inner);
176
+ return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
177
+ }
178
+ /** `path` relative to `cwd` when it lies strictly inside it. */
179
+ function insideSpelling(cwd, path) {
180
+ const rel = relative(cwd, path);
181
+ return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
182
+ ? rel
183
+ : undefined;
184
+ }
185
+ /** The run's record, unspelled: its session logs, spilled tool results and proof bundles. */
186
+ function recordRootPaths(sessionRootDir, tenant, cwd) {
187
+ const sessions = resolve(cwd, sessionRootDir ?? DEFAULT_ROOT_DIR);
188
+ const toolResults = resolve(cwd, tenant?.toolResultRoot ?? TOOL_RESULTS_ROOT_DIR);
189
+ const proofs = tenant !== undefined
190
+ ? resolve(cwd, tenant.sessionRoot, "..", "proofs")
191
+ : resolve(cwd, ".crewhaus", "proofs");
192
+ return [sessions, toolResults, proofs];
193
+ }
194
+ /**
195
+ * The directory a managed run's tenants live under, when the session root has
196
+ * the shape `buildTenant` gives it (`<tenantsRoot>/<id>/sessions`). An override
197
+ * puts it somewhere else, and its parent is then no tenants root.
198
+ */
199
+ function tenantsRootPaths(tenant, cwd) {
200
+ if (tenant === undefined)
201
+ return [];
202
+ const sessions = resolve(cwd, tenant.sessionRoot);
203
+ return basename(sessions) === "sessions" && basename(dirname(sessions)) === tenant.id
204
+ ? [resolve(sessions, "..", "..")]
205
+ : [];
206
+ }
207
+ /**
208
+ * The files `manager.envFiles` declares in `<cwd>/.crewhaus/settings.json`,
209
+ * resolved against `cwd`. Tolerant as the supervisor's own reader is, and equal
210
+ * to it (a test holds the two together): a missing or malformed file, a key of
211
+ * the wrong type and a bad entry each read as nothing.
212
+ */
213
+ export function declaredEnvFiles(cwd) {
214
+ let settings;
215
+ try {
216
+ settings = JSON.parse(readFileSync(resolve(cwd, ".crewhaus", "settings.json"), "utf8"));
217
+ }
218
+ catch {
219
+ return [];
220
+ }
221
+ if (typeof settings !== "object" || settings === null)
222
+ return [];
223
+ const manager = settings["manager"];
224
+ if (typeof manager !== "object" || manager === null || Array.isArray(manager))
225
+ return [];
226
+ const declared = manager["envFiles"];
227
+ if (!Array.isArray(declared))
228
+ return [];
229
+ return declared
230
+ .filter((entry) => typeof entry === "string")
231
+ .map((entry) => entry.trim())
232
+ .filter((entry) => entry !== "")
233
+ .map((entry) => resolve(cwd, entry));
234
+ }
235
+ /**
236
+ * The answers so far, by working directory and entry. Answered once per
237
+ * process: a child loop computes its roots again, and a call that moves the
238
+ * spec does not change the answer for the rest of the process.
239
+ */
240
+ const STANDINGS = new Map();
241
+ /** `entry` relative to the working directory, when it really lies inside it and not under `node_modules`. */
242
+ function entryInside(cwd, entry) {
243
+ if (entry === undefined)
244
+ return undefined;
245
+ let real;
246
+ try {
247
+ // A compiled binary's virtual entry has no real path, and lies in no directory here.
248
+ real = realpathSync(entry);
249
+ }
250
+ catch {
251
+ return undefined;
252
+ }
253
+ const rel = insideSpelling(followed(cwd) ?? cwd, real);
254
+ return rel === undefined || rel.split(sep).includes("node_modules") ? undefined : rel;
255
+ }
256
+ /** The `target:` of the spec at `cwd`, in the order the supervisor finds a spec. */
257
+ function specTarget(cwd) {
258
+ for (const name of SPEC_NAMES) {
259
+ let source;
260
+ try {
261
+ source = readFileSync(join(cwd, name), "utf8");
262
+ }
263
+ catch {
264
+ continue;
265
+ }
266
+ return TARGET_LINE.exec(source)?.[1];
267
+ }
268
+ return undefined;
269
+ }
270
+ /** Does the manifest in `dir` carry the name `crewhaus compile` stamps? */
271
+ function holdsBundleManifest(dir) {
272
+ try {
273
+ const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
274
+ return (typeof manifest === "object" &&
275
+ manifest !== null &&
276
+ manifest["name"] === COMPILED_BUNDLE_NAME);
277
+ }
278
+ catch {
279
+ return false;
280
+ }
281
+ }
282
+ /**
283
+ * Is the entry a non-interactive target's? Its header names the target; an entry
284
+ * with no such header goes by the file name the daemon targets give it.
285
+ */
286
+ function entryNonInteractive(cwd, entryRel) {
287
+ let source;
288
+ try {
289
+ source = readFileSync(join(cwd, entryRel), "utf8");
290
+ }
291
+ catch {
292
+ return false;
293
+ }
294
+ const target = ENTRY_TARGET.exec(source)?.[1];
295
+ return target !== undefined
296
+ ? target !== "cli" && target !== "browser"
297
+ : basename(entryRel) === "daemon.ts";
298
+ }
299
+ /** {@link Standing.ownBundle} for a bundle in `dir`, a directory below the working directory. */
300
+ function bundleBelowNames(dir, nonInteractive) {
301
+ if (!nonInteractive)
302
+ return [dir];
303
+ const names = new Set([dir, ...SPEC_NAMES]);
304
+ let at = dir;
305
+ do {
306
+ at = dirname(at);
307
+ for (const name of BUNDLE_CONFIG)
308
+ names.add(join(at, name));
309
+ } while (at !== ".");
310
+ return [...names];
311
+ }
312
+ /** {@link Standing.ownBundle}, for an entry at `entryRel` in `cwd`. */
313
+ function ownBundleNames(cwd, entryRel, compiledDaemon) {
314
+ const dir = dirname(entryRel);
315
+ if (!holdsBundleManifest(join(cwd, dir)))
316
+ return [];
317
+ if (dir !== ".") {
318
+ return bundleBelowNames(dir, compiledDaemon || entryNonInteractive(cwd, entryRel));
319
+ }
320
+ const names = new Set([...BUNDLE_CONFIG, ...BUNDLE_LOCKFILES, ...SPEC_NAMES]);
321
+ try {
322
+ for (const file of readdirSync(cwd, { withFileTypes: true })) {
323
+ if (!file.isFile())
324
+ continue;
325
+ if (BUNDLE_LOCK.test(file.name))
326
+ names.add(file.name);
327
+ if (!BUNDLE_CODE.test(file.name))
328
+ continue;
329
+ names.add(file.name);
330
+ const stem = file.name.slice(0, file.name.lastIndexOf("."));
331
+ for (const extension of CODE_EXTENSIONS) {
332
+ names.add(`${stem}${extension}`);
333
+ names.add(`${stem}.js${extension}`);
334
+ }
335
+ names.add(`${stem}.js.json`);
336
+ }
337
+ }
338
+ catch {
339
+ // An unreadable directory lists no files; the names above still hold.
340
+ }
341
+ return [...names];
342
+ }
343
+ /** {@link Standing}, read from the disk the first time and remembered after. */
344
+ function standingOf(cwd, entry) {
345
+ const key = `${cwd}\0${entry ?? ""}`;
346
+ const known = STANDINGS.get(key);
347
+ if (known !== undefined)
348
+ return known;
349
+ const holdsSpec = SPEC_NAMES.some((name) => existsSync(join(cwd, name)));
350
+ const entryRel = entryInside(cwd, entry);
351
+ const target = entryRel !== undefined && holdsSpec ? specTarget(cwd) : undefined;
352
+ const compiledDaemon = target !== undefined && target !== "cli" && target !== "browser";
353
+ const standing = {
354
+ holdsSpec,
355
+ compiledDaemon,
356
+ ownBundle: entryRel !== undefined && (!holdsSpec || compiledDaemon)
357
+ ? ownBundleNames(cwd, entryRel, compiledDaemon)
358
+ : [],
359
+ };
360
+ STANDINGS.set(key, standing);
361
+ return standing;
362
+ }
363
+ /** Every way the canonicaliser can spell `root`, added to `into`. */
364
+ function addSpellings(into, root, cwd) {
365
+ into.add(root);
366
+ const real = followed(root);
367
+ if (real !== undefined)
368
+ into.add(real);
369
+ const rel = insideSpelling(cwd, root);
370
+ if (rel !== undefined)
371
+ into.add(rel);
372
+ // A root reached through a link has a workspace-relative name of its own.
373
+ const realRel = real !== undefined ? insideSpelling(followed(cwd) ?? cwd, real) : undefined;
374
+ if (realRel !== undefined)
375
+ into.add(realRel);
376
+ }
377
+ /**
378
+ * The runtime-state roots of a run, in these groups.
379
+ *
380
+ * - The run's record: its session-log root (`sessionRootDir` as
381
+ * `runChatLoop` resolved it — the tenant's, `CREWHAUS_SESSION_DIR`, or
382
+ * event-log's default), its tool-result spill root (the tenant's
383
+ * `toolResultRoot`, else `<cwd>/.crewhaus/tool-results`, where the runtime
384
+ * saves an output too long for the log — `@crewhaus/tool-result-store`) and
385
+ * its proofs root (the tenant's `proofs/`, else `<cwd>/.crewhaus/proofs`,
386
+ * where every spec's bundles and artifacts live). With them, a managed
387
+ * run's whole tenants root, when the tenant has `buildTenant`'s shape, so
388
+ * the files under it are the operator's and each tenant's own store's.
389
+ * - The files that control the run, against `cwd` whatever the tenant:
390
+ * `.crewhaus/run` and `.crewhaus/settings.json`, which are the files the
391
+ * run loads its settings layer and hooks from, and the supervisor keeps
392
+ * its run files in, both in the harness directory the run works in; the
393
+ * records a harness's gates and janitors keep; the environment files Bun
394
+ * loads from there; and its `bunfig.toml` and `.npmrc`. These hold at every
395
+ * working directory, with or without a spec. Exact files stay exact: a
396
+ * neighbour such as `.env.example` or `.crewhaus/graders.yaml` is not one.
397
+ * - The approvals file beside session logs a session directory puts at the
398
+ * working directory or above it. The record's group leaves such a root to
399
+ * the rules; this one file stays protected. A default run adds nothing.
400
+ * - The files `manager.envFiles` declares ({@link declaredEnvFiles}), read
401
+ * from the settings file once per call. One that holds the working
402
+ * directory (a declared `.` or `..`) is left to the rules.
403
+ * - Hangar's directory and registry file: every Hangar root `env` names
404
+ * (`CREWHAUS_HANGAR_ROOT`, `<registryRoot>/hangar`) and `~/.crewhaus/hangar`
405
+ * always (`hangarStateRoots` in `@crewhaus/harness-registry`, beside the
406
+ * `resolveHangarRoot` the CLI and the fleet tools use), and the
407
+ * `harnesses.json` of `<registryRoot>` and of `~/.crewhaus`
408
+ * (`registryStateFiles`), so a variable can add a protected root and never
409
+ * move one. `env` is read for those two variables alone; the default
410
+ * follows the home directory (`homedir()`), as the Hangar server's own
411
+ * fallback does.
412
+ * - What the harness's next start runs, by what the working directory is to
413
+ * this process ({@link Standing}): `dist`, `build` and `node_modules`; the
414
+ * compiled inputs; and the bundle the process started from. `entry` is the
415
+ * process's entry file, `Bun.main` unless a test names another, and the
416
+ * answer is kept for the life of the process.
417
+ *
418
+ * The floor reads calls that write. A read of the run's record, a spilled
419
+ * output's parts included, goes on as before.
420
+ */
421
+ export function runtimeStateRoots(sessionRootDir, tenant, cwd = process.cwd(), env = process.env, entry = globalThis.Bun?.main) {
422
+ const sessions = resolve(cwd, sessionRootDir ?? DEFAULT_ROOT_DIR);
423
+ const standing = standingOf(cwd, entry);
424
+ const atCwd = (names) => names.map((name) => resolve(cwd, name));
425
+ /**
426
+ * Each group of roots, and what becomes of a root that holds the working
427
+ * directory itself. A new kind of root is one more entry here.
428
+ */
429
+ const groups = [
430
+ // The run's record. A root that holds the working directory itself (a
431
+ // session dir pointed at the workspace) would refuse every write the
432
+ // agent makes: it is left to the permission rules rather than walled
433
+ // off whole.
434
+ // A tenants root that holds it is left to them the same way.
435
+ {
436
+ roots: [...recordRootPaths(sessionRootDir, tenant, cwd), ...tenantsRootPaths(tenant, cwd)],
437
+ holdingCwd: "skip",
438
+ },
439
+ // The files that control the run: the working directory's, whatever the
440
+ // tenant. They lie inside it, so they never hold it.
441
+ {
442
+ roots: [...CONTROL_FILES, ...GATE_RECORDS, ...ENV_FILES, ...START_CONFIG].map((file) => resolve(cwd, file)),
443
+ holdingCwd: "protect",
444
+ },
445
+ // The approvals file of a session root the record's group left out above.
446
+ {
447
+ roots: within(cwd, sessions) ? [join(sessions, DEFAULT_APPROVALS_FILENAME)] : [],
448
+ holdingCwd: "protect",
449
+ },
450
+ // A declared `.` or `..` must not wall off the working directory.
451
+ { roots: declaredEnvFiles(cwd), holdingCwd: "skip" },
452
+ // Hangar's directory, every root the environment names and the default, and
453
+ // its registry file. One that holds the working directory stays protected:
454
+ // the floor refuses a run inside Hangar's directory that writes there.
455
+ { roots: [...hangarStateRoots(env), ...registryStateFiles(env)], holdingCwd: "protect" },
456
+ // What the harness's next start runs. Each lies inside the working
457
+ // directory, so none holds it.
458
+ { roots: standing.holdsSpec ? atCwd(INSTALLED_TREES) : [], holdingCwd: "protect" },
459
+ { roots: standing.compiledDaemon ? atCwd(COMPILED_INPUTS) : [], holdingCwd: "protect" },
460
+ { roots: atCwd(standing.ownBundle), holdingCwd: "protect" },
461
+ ];
462
+ const roots = new Set();
463
+ for (const group of groups) {
464
+ for (const root of group.roots) {
465
+ if (group.holdingCwd === "skip" && within(cwd, root))
466
+ continue;
467
+ addSpellings(roots, root, cwd);
468
+ }
469
+ }
470
+ return [...roots];
471
+ }
472
+ /**
473
+ * The roots of the run's record alone, spelled as {@link runtimeStateRoots}
474
+ * spells them: where a tool's own store may lie with the floor reading its own
475
+ * format rather than the path ({@link relocatingFieldLeftOut}).
476
+ */
477
+ export function runtimeRecordRoots(sessionRootDir, tenant, cwd = process.cwd()) {
478
+ const roots = new Set();
479
+ for (const root of recordRootPaths(sessionRootDir, tenant, cwd)) {
480
+ if (!within(cwd, root))
481
+ addSpellings(roots, root, cwd);
482
+ }
483
+ return [...roots];
484
+ }
485
+ /**
486
+ * Does the floor leave out this field declared `relocates`? A store the tool
487
+ * reads whole (`beneath`) and a service it is moved off (`url`) are not where
488
+ * it writes, so they stay out. A path is the store the call writes, and it
489
+ * stays out only where that store is the field's own: a session log's field
490
+ * (the one whose default is the session directory, EmitTraceEvent's namespaced
491
+ * `custom.*` lines) in the run's record, or a field whose default is a gate
492
+ * record ({@link TOOL_STORES}: DatasetPut's versions, EvalBaselinePin's pins) in
493
+ * that record, and in no other root. The value is the one the call names, else
494
+ * the field's default, and anything else the floor reads as it reads any path.
495
+ * A link is followed, so a store is placed by where it leads too.
496
+ */
497
+ export function relocatingFieldLeftOut(arg, parsedInput, recordRoots, roots, cwd = process.cwd()) {
498
+ if (arg.kind !== "path" || arg.beneath !== undefined)
499
+ return true;
500
+ // A field read out of a nested value is not one this can place.
501
+ if (arg.field.includes("."))
502
+ return false;
503
+ const given = typeof parsedInput === "object" && parsedInput !== null
504
+ ? parsedInput[arg.field]
505
+ : undefined;
506
+ const store = given === undefined || given === null ? arg.default : given;
507
+ if (typeof store !== "string" || store === "")
508
+ return false;
509
+ const fieldDefault = arg.default;
510
+ if (fieldDefault === undefined)
511
+ return false;
512
+ if (TOOL_STORES.some((kept) => resolve(cwd, kept) === resolve(cwd, fieldDefault))) {
513
+ if (protectedRootHolding(store, [fieldDefault], cwd) === undefined)
514
+ return false;
515
+ return (protectedRootHolding(store, rootsBesideStore(fieldDefault, roots, cwd), cwd) === undefined);
516
+ }
517
+ // The session directory is the field's own wherever the run has moved it.
518
+ const keepsLogs = resolve(cwd, fieldDefault) === resolve(cwd, DEFAULT_ROOT_DIR) ||
519
+ protectedRootHolding(fieldDefault, recordRoots, cwd) !== undefined;
520
+ if (!keepsLogs || protectedRootHolding(store, recordRoots, cwd) === undefined)
521
+ return false;
522
+ const others = roots.filter((root) => !recordRoots.includes(root));
523
+ return protectedRootHolding(store, others, cwd) === undefined;
524
+ }
525
+ /**
526
+ * The files a run that answers people other than its operator keeps from its
527
+ * agent's tools, relative to its working directory. Exact names: the rest of
528
+ * `.crewhaus/run`, such as a daemon's status file, stays readable.
529
+ */
530
+ const CREDENTIAL_ROOTS = [
531
+ ".env", // a directory of that name; the file is caught by name too
532
+ join(".crewhaus", "secrets"),
533
+ join(".crewhaus", "identity.json"),
534
+ join(".crewhaus", "run", "control-token"),
535
+ join(".crewhaus", "run", "mcp-token"),
536
+ join(".crewhaus", "run", "gateway-jwt-secret"),
537
+ join(".crewhaus", "run", "logs"),
538
+ join(".crewhaus", "run", "control", "keys"),
539
+ ];
540
+ /**
541
+ * The roots behind permission-engine's `EvaluateOptions.credentialRoots`, spelled
542
+ * as {@link runtimeStateRoots} spells its own: resolved, with links followed, and
543
+ * workspace-relative. A file `manager.envFiles` declares joins them
544
+ * ({@link declaredEnvFiles}), and a declared `.` or `..`, which holds the working
545
+ * directory, is left to the rules. A file named as `isCredentialFileName` matches
546
+ * is found by its name, in any directory, so it needs no root here.
547
+ */
548
+ export function credentialFileRoots(cwd = process.cwd()) {
549
+ const roots = new Set();
550
+ for (const root of CREDENTIAL_ROOTS)
551
+ addSpellings(roots, resolve(cwd, root), cwd);
552
+ for (const root of declaredEnvFiles(cwd)) {
553
+ if (!within(cwd, root))
554
+ addSpellings(roots, root, cwd);
555
+ }
556
+ return [...roots];
557
+ }
558
+ /** Set for the whole of a run that answers people other than its operator, nested loops included. */
559
+ export const credentialFloorScope = new AsyncLocalStorage();
@@ -0,0 +1,54 @@
1
+ /**
2
+ * provider-limits#0 — the boot check of the run's tool list against the
3
+ * per-request limit of each model that can be sent it.
4
+ *
5
+ * The compiler checks the spec's builtin tools; this is the authoritative
6
+ * check, because only the running loop knows the full list: the builtins plus
7
+ * the loop's own tools (ListTools, continuity, memory, Task, Skill), MCP
8
+ * server tools, plugin tools and the hybrid pair — and a `crewhaus run
9
+ * --model` override the compiler never saw. It runs before the first model
10
+ * call, so an over-long list costs a clear error instead of a provider 400
11
+ * on every call (retried, then reported as "tombstone budget exhausted", or
12
+ * for a fallback as "breaker open").
13
+ *
14
+ * The verdict is pure: the caller says which models can serve, how many
15
+ * tools each is sent and the environment the adapters read their endpoints
16
+ * from; the limits come from `@crewhaus/cost-tracker`, the table the
17
+ * compiler reads. An `openai/` model is held to api.openai.com's limit only
18
+ * when OPENAI_BASE_URL is unset or names api.openai.com — the compiler cannot
19
+ * see where it points, and leaves that to this check. The one piece of state
20
+ * is which boot lines this process has already written.
21
+ */
22
+ import { type ToolLimitEnv } from "@crewhaus/cost-tracker";
23
+ /** One model that can be sent the run's tools, and how many it would be sent. */
24
+ export type ServingModel = {
25
+ readonly model: string;
26
+ readonly toolCount: number;
27
+ /**
28
+ * `serves` — the primary, a fallback, a tier or a pool candidate: a model
29
+ * the run's calls go to. `degrade` — the budget degrade rung, which serves
30
+ * only after spend, so it can never be the only way a run succeeds.
31
+ */
32
+ readonly role: "serves" | "degrade";
33
+ /** How the boot line names it: "model_fallbacks[0] openai/gpt-4o", … */
34
+ readonly label: string;
35
+ /** What the run does about it when another model can serve: "routing leaves it out", … */
36
+ readonly whenOver: string;
37
+ };
38
+ export type ToolLimitVerdict = {
39
+ /** Set when no model that serves can accept its tools: the run cannot make one call. */
40
+ readonly fatal?: string;
41
+ /** One boot line per model over its limit, when some other model can serve. */
42
+ readonly warnings: ReadonlyArray<string>;
43
+ };
44
+ /**
45
+ * Check every serving model's tool count against its provider's per-request
46
+ * limit. `env` is where the adapters read their endpoints from: an `openai/`
47
+ * model that `OPENAI_BASE_URL` sends to another server is not held to
48
+ * api.openai.com's limit.
49
+ */
50
+ export declare function checkServingToolLimits(serving: ReadonlyArray<ServingModel>, env?: ToolLimitEnv): ToolLimitVerdict;
51
+ /** The `lines` this process has not written yet, now marked as written. */
52
+ export declare function unreportedToolLimitLines(lines: ReadonlyArray<string>): string[];
53
+ /** Tests only: forget which boot lines were written. */
54
+ export declare function __resetToolLimitReportsForTests(): void;
@@ -0,0 +1,66 @@
1
+ /**
2
+ * provider-limits#0 — the boot check of the run's tool list against the
3
+ * per-request limit of each model that can be sent it.
4
+ *
5
+ * The compiler checks the spec's builtin tools; this is the authoritative
6
+ * check, because only the running loop knows the full list: the builtins plus
7
+ * the loop's own tools (ListTools, continuity, memory, Task, Skill), MCP
8
+ * server tools, plugin tools and the hybrid pair — and a `crewhaus run
9
+ * --model` override the compiler never saw. It runs before the first model
10
+ * call, so an over-long list costs a clear error instead of a provider 400
11
+ * on every call (retried, then reported as "tombstone budget exhausted", or
12
+ * for a fallback as "breaker open").
13
+ *
14
+ * The verdict is pure: the caller says which models can serve, how many
15
+ * tools each is sent and the environment the adapters read their endpoints
16
+ * from; the limits come from `@crewhaus/cost-tracker`, the table the
17
+ * compiler reads. An `openai/` model is held to api.openai.com's limit only
18
+ * when OPENAI_BASE_URL is unset or names api.openai.com — the compiler cannot
19
+ * see where it points, and leaves that to this check. The one piece of state
20
+ * is which boot lines this process has already written.
21
+ */
22
+ import { describeToolLimitOverrun, toolLimitOverrun, } from "@crewhaus/cost-tracker";
23
+ /**
24
+ * Check every serving model's tool count against its provider's per-request
25
+ * limit. `env` is where the adapters read their endpoints from: an `openai/`
26
+ * model that `OPENAI_BASE_URL` sends to another server is not held to
27
+ * api.openai.com's limit.
28
+ */
29
+ export function checkServingToolLimits(serving, env = {}) {
30
+ const overruns = new Map();
31
+ for (const s of serving) {
32
+ const o = toolLimitOverrun(s.model, s.toolCount, env);
33
+ if (o !== undefined)
34
+ overruns.set(s, o);
35
+ }
36
+ if (overruns.size === 0)
37
+ return { warnings: [] };
38
+ const servers = serving.filter((s) => s.role === "serves");
39
+ const fix = "Narrow the tools (smaller all-<category> roll-ups, -<tool> exclusions, fewer MCP servers), or pick a model whose provider accepts more.";
40
+ if (servers.length > 0 && servers.every((s) => overruns.has(s))) {
41
+ const why = servers
42
+ .map((s) => describeToolLimitOverrun(overruns.get(s), "the run's tools"))
43
+ .join("; ");
44
+ return { fatal: `${why}. ${fix}`, warnings: [] };
45
+ }
46
+ const warnings = [...overruns].map(([s, o]) => `${s.label}: ${describeToolLimitOverrun(o, "the run's tools")}; ${s.whenOver}. ${fix}`);
47
+ return { warnings };
48
+ }
49
+ /**
50
+ * Boot lines this process has already written. A channel daemon, `managed`
51
+ * and `serve --mcp` run one loop per message or request, and the same
52
+ * verdict would otherwise be repeated on every one of them for the daemon's
53
+ * whole life.
54
+ */
55
+ const reportedLines = new Set();
56
+ /** The `lines` this process has not written yet, now marked as written. */
57
+ export function unreportedToolLimitLines(lines) {
58
+ const fresh = lines.filter((line) => !reportedLines.has(line));
59
+ for (const line of fresh)
60
+ reportedLines.add(line);
61
+ return fresh;
62
+ }
63
+ /** Tests only: forget which boot lines were written. */
64
+ export function __resetToolLimitReportsForTests() {
65
+ reportedLines.clear();
66
+ }