@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,147 @@
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 type { Tenant } from "@crewhaus/tenancy";
55
+ /**
56
+ * The name `crewhaus compile` stamps in the manifest beside a bundle's entry.
57
+ * Mirrors `BUNDLE_MANIFEST_NAME` in `@crewhaus/harness-supervisor`, which this
58
+ * package does not depend on; a test holds the two equal.
59
+ */
60
+ export declare const COMPILED_BUNDLE_NAME = "crewhaus-compiled-bundle";
61
+ /**
62
+ * The files `manager.envFiles` declares in `<cwd>/.crewhaus/settings.json`,
63
+ * resolved against `cwd`. Tolerant as the supervisor's own reader is, and equal
64
+ * to it (a test holds the two together): a missing or malformed file, a key of
65
+ * the wrong type and a bad entry each read as nothing.
66
+ */
67
+ export declare function declaredEnvFiles(cwd: string): string[];
68
+ /**
69
+ * The runtime-state roots of a run, in these groups.
70
+ *
71
+ * - The run's record: its session-log root (`sessionRootDir` as
72
+ * `runChatLoop` resolved it — the tenant's, `CREWHAUS_SESSION_DIR`, or
73
+ * event-log's default), its tool-result spill root (the tenant's
74
+ * `toolResultRoot`, else `<cwd>/.crewhaus/tool-results`, where the runtime
75
+ * saves an output too long for the log — `@crewhaus/tool-result-store`) and
76
+ * its proofs root (the tenant's `proofs/`, else `<cwd>/.crewhaus/proofs`,
77
+ * where every spec's bundles and artifacts live). With them, a managed
78
+ * run's whole tenants root, when the tenant has `buildTenant`'s shape, so
79
+ * the files under it are the operator's and each tenant's own store's.
80
+ * - The files that control the run, against `cwd` whatever the tenant:
81
+ * `.crewhaus/run` and `.crewhaus/settings.json`, which are the files the
82
+ * run loads its settings layer and hooks from, and the supervisor keeps
83
+ * its run files in, both in the harness directory the run works in; the
84
+ * records a harness's gates and janitors keep; the environment files Bun
85
+ * loads from there; and its `bunfig.toml` and `.npmrc`. These hold at every
86
+ * working directory, with or without a spec. Exact files stay exact: a
87
+ * neighbour such as `.env.example` or `.crewhaus/graders.yaml` is not one.
88
+ * - The approvals file beside session logs a session directory puts at the
89
+ * working directory or above it. The record's group leaves such a root to
90
+ * the rules; this one file stays protected. A default run adds nothing.
91
+ * - The files `manager.envFiles` declares ({@link declaredEnvFiles}), read
92
+ * from the settings file once per call. One that holds the working
93
+ * directory (a declared `.` or `..`) is left to the rules.
94
+ * - Hangar's directory and registry file: every Hangar root `env` names
95
+ * (`CREWHAUS_HANGAR_ROOT`, `<registryRoot>/hangar`) and `~/.crewhaus/hangar`
96
+ * always (`hangarStateRoots` in `@crewhaus/harness-registry`, beside the
97
+ * `resolveHangarRoot` the CLI and the fleet tools use), and the
98
+ * `harnesses.json` of `<registryRoot>` and of `~/.crewhaus`
99
+ * (`registryStateFiles`), so a variable can add a protected root and never
100
+ * move one. `env` is read for those two variables alone; the default
101
+ * follows the home directory (`homedir()`), as the Hangar server's own
102
+ * fallback does.
103
+ * - What the harness's next start runs, by what the working directory is to
104
+ * this process ({@link Standing}): `dist`, `build` and `node_modules`; the
105
+ * compiled inputs; and the bundle the process started from. `entry` is the
106
+ * process's entry file, `Bun.main` unless a test names another, and the
107
+ * answer is kept for the life of the process.
108
+ *
109
+ * The floor reads calls that write. A read of the run's record, a spilled
110
+ * output's parts included, goes on as before.
111
+ */
112
+ export declare function runtimeStateRoots(sessionRootDir: string | undefined, tenant: Tenant | undefined, cwd?: string, env?: Readonly<Record<string, string | undefined>>, entry?: string | undefined): string[];
113
+ /**
114
+ * The roots of the run's record alone, spelled as {@link runtimeStateRoots}
115
+ * spells them: where a tool's own store may lie with the floor reading its own
116
+ * format rather than the path ({@link relocatingFieldLeftOut}).
117
+ */
118
+ export declare function runtimeRecordRoots(sessionRootDir: string | undefined, tenant: Tenant | undefined, cwd?: string): string[];
119
+ /**
120
+ * Does the floor leave out this field declared `relocates`? A store the tool
121
+ * reads whole (`beneath`) and a service it is moved off (`url`) are not where
122
+ * it writes, so they stay out. A path is the store the call writes, and it
123
+ * stays out only where that store is the field's own: a session log's field
124
+ * (the one whose default is the session directory, EmitTraceEvent's namespaced
125
+ * `custom.*` lines) in the run's record, or a field whose default is a gate
126
+ * record ({@link TOOL_STORES}: DatasetPut's versions, EvalBaselinePin's pins) in
127
+ * that record, and in no other root. The value is the one the call names, else
128
+ * the field's default, and anything else the floor reads as it reads any path.
129
+ * A link is followed, so a store is placed by where it leads too.
130
+ */
131
+ export declare function relocatingFieldLeftOut(arg: {
132
+ readonly field: string;
133
+ readonly kind: string;
134
+ readonly default?: string;
135
+ readonly beneath?: unknown;
136
+ }, parsedInput: unknown, recordRoots: readonly string[], roots: readonly string[], cwd?: string): boolean;
137
+ /**
138
+ * The roots behind permission-engine's `EvaluateOptions.credentialRoots`, spelled
139
+ * as {@link runtimeStateRoots} spells its own: resolved, with links followed, and
140
+ * workspace-relative. A file `manager.envFiles` declares joins them
141
+ * ({@link declaredEnvFiles}), and a declared `.` or `..`, which holds the working
142
+ * directory, is left to the rules. A file named as `isCredentialFileName` matches
143
+ * is found by its name, in any directory, so it needs no root here.
144
+ */
145
+ export declare function credentialFileRoots(cwd?: string): string[];
146
+ /** Set for the whole of a run that answers people other than its operator, nested loops included. */
147
+ export declare const credentialFloorScope: AsyncLocalStorage<true>;