@crewhaus/runtime-core 0.7.0 → 0.8.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.
@@ -0,0 +1,33 @@
1
+ /**
2
+ * 0.8.0 (design/0.8.0-provability-release.md §6.1, §10; AGENTS.md Pillar 3)
3
+ * — the sink-side screen for a HEAD a provability gate sends OUTSIDE a
4
+ * running loop: the research shape's report gate, which grades the report
5
+ * after every branch's loop has closed, so no loop's screen is there to ask.
6
+ *
7
+ * The URL is one the report names — a destination the model chose, so an
8
+ * `external-dynamic` sink — and it is classified against the lineage of
9
+ * every run context the caller lists (each branch's), folded to the
10
+ * strictest verdict: content a boundary tagged from a non-user origin — a
11
+ * secret a tool read — refuses the request, and the gate sends nothing.
12
+ *
13
+ * There is no "handed verbatim" exemption here: a URL that merely appears
14
+ * in a tool result may be one the model wrote into a tool that echoed it.
15
+ * The one URL let through unclassified is one the caller says was already
16
+ * requested in this run (`sent`) — the research crawler's own GET, which
17
+ * its origin allow-list admitted: a HEAD to it carries nothing new.
18
+ */
19
+ import { type EgressMatcher } from "@crewhaus/egress-classifier";
20
+ import type { RunContext } from "@crewhaus/run-context";
21
+ import type { GateEgressScreen } from "./index";
22
+ /** The sink id a gate HEAD is classified and recorded under (evaluation-service's `RESOLVE_SINK_ID`). */
23
+ export declare const GATE_RESOLVE_SINK_ID = "provability.resolve";
24
+ export type LineageScreenOptions = {
25
+ /** The run contexts whose lineage a URL is screened against, read at each screen. */
26
+ readonly contexts: () => Iterable<RunContext>;
27
+ /** A URL already requested in this run (by a fetch the run's own guard admitted). */
28
+ readonly sent?: (url: string) => boolean;
29
+ /** The run's egress matcher (default: egress-classifier's substring matcher). */
30
+ readonly matcher?: EgressMatcher;
31
+ };
32
+ /** The screen (see the module doc): `(url) => verdict`, never a throw for a clean URL. */
33
+ export declare function lineageEgressScreen(opts: LineageScreenOptions): (url: string) => Promise<GateEgressScreen>;
@@ -0,0 +1,46 @@
1
+ /**
2
+ * 0.8.0 (design/0.8.0-provability-release.md §6.1, §10; AGENTS.md Pillar 3)
3
+ * — the sink-side screen for a HEAD a provability gate sends OUTSIDE a
4
+ * running loop: the research shape's report gate, which grades the report
5
+ * after every branch's loop has closed, so no loop's screen is there to ask.
6
+ *
7
+ * The URL is one the report names — a destination the model chose, so an
8
+ * `external-dynamic` sink — and it is classified against the lineage of
9
+ * every run context the caller lists (each branch's), folded to the
10
+ * strictest verdict: content a boundary tagged from a non-user origin — a
11
+ * secret a tool read — refuses the request, and the gate sends nothing.
12
+ *
13
+ * There is no "handed verbatim" exemption here: a URL that merely appears
14
+ * in a tool result may be one the model wrote into a tool that echoed it.
15
+ * The one URL let through unclassified is one the caller says was already
16
+ * requested in this run (`sent`) — the research crawler's own GET, which
17
+ * its origin allow-list admitted: a HEAD to it carries nothing new.
18
+ */
19
+ import { classifyEgress } from "@crewhaus/egress-classifier";
20
+ /** The sink id a gate HEAD is classified and recorded under (evaluation-service's `RESOLVE_SINK_ID`). */
21
+ export const GATE_RESOLVE_SINK_ID = "provability.resolve";
22
+ const RANK = { pass: 0, warn: 1, block: 2 };
23
+ /** The screen (see the module doc): `(url) => verdict`, never a throw for a clean URL. */
24
+ export function lineageEgressScreen(opts) {
25
+ return async (url) => {
26
+ if (opts.sent?.(url) === true) {
27
+ return { verdict: "pass", sinkScope: "external-dynamic", originsFound: [], matchCount: 0 };
28
+ }
29
+ let verdict = "pass";
30
+ const origins = new Set();
31
+ let matchCount = 0;
32
+ for (const ctx of opts.contexts()) {
33
+ const screened = await classifyEgress(url, ctx, {
34
+ sinkId: GATE_RESOLVE_SINK_ID,
35
+ sinkScope: "external-dynamic",
36
+ ...(opts.matcher !== undefined ? { matcher: opts.matcher } : {}),
37
+ });
38
+ if (RANK[screened.verdict] > RANK[verdict])
39
+ verdict = screened.verdict;
40
+ for (const origin of screened.originsFound)
41
+ origins.add(origin);
42
+ matchCount += screened.matchCount;
43
+ }
44
+ return { verdict, sinkScope: "external-dynamic", originsFound: [...origins], matchCount };
45
+ };
46
+ }
@@ -273,7 +273,15 @@ export type AttachedWatchmeCapture = {
273
273
  *
274
274
  * Gated on CREWHAUS_WATCHME=1|true (stamped by `crewhaus run` /
275
275
  * the compiled-bundle preambles); returns undefined otherwise. Appends are
276
- * synchronous (`appendFileSync`, mode 0600, one line < PIPE_BUF ⇒ atomic) and
277
- * every failure is swallowed — capture can never crash a run.
276
+ * synchronous (mode 0600, one line < PIPE_BUF ⇒ atomic) and every failure is
277
+ * swallowed — capture can never crash a run.
278
+ *
279
+ * 0.7.1: the append goes through @crewhaus/tool-safety's `appendContained`,
280
+ * rooted at the session directory as the event log's is, so a symlink, FIFO
281
+ * or directory at `<sessionId>.events.jsonl` is refused instead of followed.
282
+ * A model that planted a link there (GitApplyPatch creates one from a patch)
283
+ * had every trace event of the next watched run appended to a file of its
284
+ * choosing. A refusal stops the capture for this run and is reported once on
285
+ * `onRefused` (default: one stderr line naming the file and the reason).
278
286
  */
279
- export declare function attachWatchmeCapture(bus: TraceEventBus, sessionsDir: string, sessionId: string, env?: NodeJS.ProcessEnv): AttachedWatchmeCapture | undefined;
287
+ export declare function attachWatchmeCapture(bus: TraceEventBus, sessionsDir: string, sessionId: string, env?: NodeJS.ProcessEnv, onRefused?: (message: string) => void): AttachedWatchmeCapture | undefined;
@@ -1,9 +1,9 @@
1
- import { appendFileSync } from "node:fs";
2
1
  import { join } from "node:path";
3
2
  import { createCostTracker, formatUsdMicros } from "@crewhaus/cost-tracker";
4
3
  import { attachIfEnvSet as attachMetricsIfEnvSet, } from "@crewhaus/metrics-collector";
5
4
  import { attachIfEnvSet as attachOtelIfEnvSet, } from "@crewhaus/otel-exporter";
6
5
  import { attachIfEnvSet as attachPrinterIfEnvSet, formatJsonLine, } from "@crewhaus/structured-event-printer";
6
+ import { appendContained } from "@crewhaus/tool-safety/fs";
7
7
  import { SessionMetricsAccumulator, appendMetricsSnapshot, deriveThresholds, detectBreaches, readMetricsHistory, } from "./alert-watchdog";
8
8
  import { attachSloMonitor, } from "./slo-monitor";
9
9
  /**
@@ -293,12 +293,29 @@ export function attachAlertWatchdog(bus, runContext, env, options = {}) {
293
293
  return;
294
294
  finalized = true;
295
295
  const snapshot = acc.snapshot(runContext.sessionId);
296
+ // 0.7.1 — a history file the store refuses (a link, FIFO or directory
297
+ // planted at it or at `metrics/`) is reported after the breach check
298
+ // rather than aborting it: the session is graded against the bootstrap
299
+ // defaults, as a first session is, and nothing is read or written through
300
+ // the plant.
301
+ const persistence = [];
296
302
  // Derive thresholds from PRIOR history (before this session's snapshot is
297
303
  // appended) so a session is never graded against itself.
298
- const history = readMetricsHistory(options.metricsDir);
304
+ let history = [];
305
+ try {
306
+ history = readMetricsHistory(options.metricsDir);
307
+ }
308
+ catch (err) {
309
+ persistence.push(err instanceof Error ? err.message : String(err));
310
+ }
299
311
  const thresholds = deriveThresholds(history);
300
312
  // Persist AFTER reading history so the next session benefits from this one.
301
- appendMetricsSnapshot(snapshot, options.metricsDir);
313
+ try {
314
+ appendMetricsSnapshot(snapshot, options.metricsDir);
315
+ }
316
+ catch (err) {
317
+ persistence.push(err instanceof Error ? err.message : String(err));
318
+ }
302
319
  const breaches = detectBreaches(snapshot, thresholds);
303
320
  const sink = options.alertSink;
304
321
  for (const breach of breaches) {
@@ -334,6 +351,8 @@ export function attachAlertWatchdog(bus, runContext, env, options = {}) {
334
351
  .catch((err) => logFlushError(runContext, "alert-hook", err));
335
352
  }
336
353
  }
354
+ if (persistence.length > 0)
355
+ throw new Error(persistence.join("; "));
337
356
  };
338
357
  return { finalize, unsubscribe };
339
358
  }
@@ -696,6 +715,10 @@ const WATCHME_MIRRORED_KIND_RECORD = {
696
715
  goal_update: true,
697
716
  action_proof: true,
698
717
  dream_run: true,
718
+ // 0.8.0 (design/0.8.0-provability-release.md §5.3) — the provability gate's
719
+ // verdict summary and ProofCheck's checker runs, both mirrored durably.
720
+ provability_graded: true,
721
+ proof_checked: true,
699
722
  };
700
723
  export const WATCHME_MIRRORED_KINDS = new Set(Object.keys(WATCHME_MIRRORED_KIND_RECORD));
701
724
  /**
@@ -710,21 +733,36 @@ export const WATCHME_MIRRORED_KINDS = new Set(Object.keys(WATCHME_MIRRORED_KIND_
710
733
  *
711
734
  * Gated on CREWHAUS_WATCHME=1|true (stamped by `crewhaus run` /
712
735
  * the compiled-bundle preambles); returns undefined otherwise. Appends are
713
- * synchronous (`appendFileSync`, mode 0600, one line < PIPE_BUF ⇒ atomic) and
714
- * every failure is swallowed — capture can never crash a run.
736
+ * synchronous (mode 0600, one line < PIPE_BUF ⇒ atomic) and every failure is
737
+ * swallowed — capture can never crash a run.
738
+ *
739
+ * 0.7.1: the append goes through @crewhaus/tool-safety's `appendContained`,
740
+ * rooted at the session directory as the event log's is, so a symlink, FIFO
741
+ * or directory at `<sessionId>.events.jsonl` is refused instead of followed.
742
+ * A model that planted a link there (GitApplyPatch creates one from a patch)
743
+ * had every trace event of the next watched run appended to a file of its
744
+ * choosing. A refusal stops the capture for this run and is reported once on
745
+ * `onRefused` (default: one stderr line naming the file and the reason).
715
746
  */
716
- export function attachWatchmeCapture(bus, sessionsDir, sessionId, env = process.env) {
747
+ export function attachWatchmeCapture(bus, sessionsDir, sessionId, env = process.env, onRefused = (message) => process.stderr.write(`${message}\n`)) {
717
748
  const gate = env["CREWHAUS_WATCHME"];
718
749
  if (gate !== "1" && gate !== "true")
719
750
  return undefined;
720
- const path = join(sessionsDir, `${sessionId}.events.jsonl`);
751
+ const name = `${sessionId}.events.jsonl`;
752
+ let refused = false;
721
753
  const unsubscribe = bus.subscribe((event) => {
754
+ if (refused)
755
+ return;
722
756
  if (WATCHME_EPHEMERAL_KINDS.has(event.kind))
723
757
  return;
724
758
  if (WATCHME_MIRRORED_KINDS.has(event.kind))
725
759
  return;
726
760
  try {
727
- appendFileSync(path, formatJsonLine(event), { mode: 0o600 });
761
+ const appended = appendContained(sessionsDir, name, formatJsonLine(event), { mode: 0o600 });
762
+ if (!appended.ok && appended.code !== "not-found") {
763
+ refused = true;
764
+ onRefused(`[watchme] capture stopped: refusing to append to ${join(sessionsDir, name)}: ${appended.reason} (code ${appended.code})`);
765
+ }
728
766
  }
729
767
  catch {
730
768
  // Swallowed by design — a capture hiccup must never abort a turn.
@@ -0,0 +1,74 @@
1
+ import type { ApprovalPlace } from "@crewhaus/session-store";
2
+ import type { PathCanonicalizer, ProgramPathReader } from "@crewhaus/tool-executor";
3
+ type OperativeValue = ReturnType<PathCanonicalizer>[number];
4
+ /**
5
+ * The longest path this resolves, in UTF-16 code units; a longer one is
6
+ * refused before it is walked. Nothing that long can be opened or created:
7
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
8
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
9
+ * UTF-16 one. The limit is twice that because the part of a path that exists
10
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
11
+ * own: no spelling of the place reaches it, not even one through a symlink
12
+ * that shortens the part that exists.
13
+ */
14
+ export declare const MAX_PATH_CHARS: number;
15
+ /** Where the workspace root's other spellings come from; tests pass their own. */
16
+ export type RootSpellingSources = {
17
+ /** The shell's logical working directory. Default `process.env.PWD`. */
18
+ readonly pwd?: string | undefined;
19
+ /** Top-level symlinks and their resolved targets. Default: read from `/`. */
20
+ readonly topLevelLinks?: ReadonlyArray<readonly [string, string]>;
21
+ };
22
+ /**
23
+ * The value(s) `raw` names inside the workspace at `root`. Parent
24
+ * directories are followed through symlinks — `build/link/app.ts` with
25
+ * `build/link → ../src` IS `src/app.ts` for every tool. The last component is
26
+ * not followed, because a tool that replaces or deletes it acts on the link
27
+ * itself; but it is written the way its directory stores it when it exists
28
+ * (`.ENV` is `.env` on macOS), and when it is a symlink, a tool that opens it
29
+ * acts on the target instead, so the target is a second value. An allow then
30
+ * has to cover both, and a deny fires on either. The name as written stays a
31
+ * spelling a deny also fires on.
32
+ */
33
+ export declare function canonicalWorkspacePath(raw: string, root: string, rootSpellings?: RootSpellingSources): OperativeValue[];
34
+ /**
35
+ * How a place reads when even the tools' own walk cannot follow the path: a
36
+ * loop of links, or a directory that cannot be searched. A tool cannot open
37
+ * such a path either.
38
+ */
39
+ export declare const UNRESOLVED_PLACE = "unresolved:";
40
+ /**
41
+ * The gate's canonicaliser, keeping a record of every path it read and where
42
+ * each one lands — absolute, every symlink followed, one place per value it
43
+ * gave a rule (the entry itself and, when that is a symlink, its target),
44
+ * inside or outside the workspace alike. That record is what a headless
45
+ * approval is bound to (`landsWhereApproved` in this package). Paths a call names through a directory field (a
46
+ * command's `cwd`, a PATH entry it sets) are read through it too, and so is
47
+ * each command word that names a file — the program run by its path, the
48
+ * script an interpreter is handed — through `readProgramPath`, so the record
49
+ * is everything on the filesystem the gate's decision rested on.
50
+ */
51
+ export declare function placeRecordingCanonicalizer(root?: string): {
52
+ readonly canonicalizePath: PathCanonicalizer;
53
+ /** Where a command word that names a file lands, recorded like a path. */
54
+ readonly readProgramPath: ProgramPathReader;
55
+ /**
56
+ * Every path read so far, ordered by path, each with where it lands; then
57
+ * every command word, ordered the same way, keyed by the word joined to
58
+ * the directory it runs in.
59
+ */
60
+ readonly places: () => ApprovalPlace[];
61
+ /**
62
+ * True when every path and command word read lands exactly where it reads
63
+ * on its face — one place, the root joined to the path with `..` collapsed
64
+ * and no symlink followed. Vacuously true when nothing was read.
65
+ */
66
+ readonly allAsWritten: () => boolean;
67
+ };
68
+ /**
69
+ * The canonicaliser the permission gate hands `preparePermissionSubject`:
70
+ * paths resolved against `root` — by default the current working directory,
71
+ * which is the root every workspace tool resolves against at call time.
72
+ */
73
+ export declare function workspacePathCanonicalizer(root?: string): PathCanonicalizer;
74
+ export {};