@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.
- package/LICENSE +201 -0
- package/NOTICE +9 -0
- package/README.md +9 -0
- package/dist/alert-watchdog.d.ts +17 -1
- package/dist/alert-watchdog.js +91 -18
- package/dist/cli-markdown-lines.d.ts +20 -0
- package/dist/cli-markdown-lines.js +91 -0
- package/dist/cli-markdown.js +15 -13
- package/dist/flatten-union.d.ts +36 -0
- package/dist/flatten-union.js +65 -0
- package/dist/forged-footer.d.ts +51 -0
- package/dist/forged-footer.js +212 -0
- package/dist/identity.js +47 -21
- package/dist/incident-collector.js +25 -6
- package/dist/index.d.ts +261 -22
- package/dist/index.js +2327 -218
- package/dist/lineage-screen.d.ts +33 -0
- package/dist/lineage-screen.js +46 -0
- package/dist/observability.d.ts +11 -3
- package/dist/observability.js +46 -8
- package/dist/path-canonical.d.ts +74 -0
- package/dist/path-canonical.js +676 -0
- package/dist/pre-route.d.ts +5 -3
- package/dist/state-roots.d.ts +147 -0
- package/dist/state-roots.js +559 -0
- package/dist/tool-limit.d.ts +54 -0
- package/dist/tool-limit.js +66 -0
- package/package.json +52 -44
|
@@ -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
|
+
}
|
package/dist/observability.d.ts
CHANGED
|
@@ -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 (
|
|
277
|
-
*
|
|
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;
|
package/dist/observability.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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 (
|
|
714
|
-
*
|
|
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
|
|
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
|
-
|
|
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 {};
|