@crewhaus/runtime-core 0.3.2 → 0.4.2

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.
@@ -133,6 +133,13 @@ export class SessionMetricsAccumulator {
133
133
  this.permissionDenials += 1;
134
134
  return;
135
135
  default:
136
+ // NEW-E-2 is PARTIAL by decision, not by omission: `eval_graded`,
137
+ // `judge_verdict` and `response_rated` fold into metrics-collector
138
+ // (crewhaus_eval_verdicts_total / _score / crewhaus_response_ratings_total)
139
+ // but deliberately NOT into this accumulator, so there is no
140
+ // "judge score dropped below baseline" breach yet. Adding one means
141
+ // new persisted snapshot fields + a `detectBreaches` rule; see the
142
+ // Wave 5 amendments in EVALS-CAMPAIGN-0.4.md before closing the gap.
136
143
  return;
137
144
  }
138
145
  }
@@ -0,0 +1,92 @@
1
+ /** Opt-out env for the exit rating prompt. */
2
+ export declare const NO_EXIT_RATING_ENV = "CREWHAUS_NO_EXIT_RATING";
3
+ export declare const EXIT_RATING_PROMPT = "rate this session? [g]ood / [b]ad / [enter] skip: ";
4
+ export declare const EXIT_RATING_TIMEOUT_MS = 10000;
5
+ /** The event-log EventKind a rating is persisted under (mirrors the CLI's
6
+ * `FEEDBACK_EVENT_KIND` and the channel target's reaction codegen). */
7
+ export declare const FEEDBACK_EVENT_KIND: "user_feedback";
8
+ /**
9
+ * The subset of the spec's `feedback:` block (IR `IrFeedback`) the runtime
10
+ * needs. Presence of the block is the opt-in; `enabled: false` disables the
11
+ * whole contract and `exitPrompt: false` disables just the prompt.
12
+ */
13
+ export type ExitRatingFeedback = {
14
+ readonly enabled?: boolean;
15
+ readonly exitPrompt?: boolean;
16
+ };
17
+ export type ExitRatingDecision = {
18
+ readonly prompt: boolean;
19
+ readonly reason: string;
20
+ };
21
+ /**
22
+ * The pure gate. Prompts only when ALL hold: the spec has a feedback block
23
+ * (presence opts in), it isn't disabled (`enabled: false`) or prompt-opted-out
24
+ * (`exitPrompt: false`), `CREWHAUS_NO_EXIT_RATING` is not set, the loop exited
25
+ * cleanly (an aborted or crashed run is not a session anyone wants to rate),
26
+ * stdin is a real TTY (NEVER in piped/CI mode), and the session produced at
27
+ * least one assistant answer.
28
+ */
29
+ export declare function shouldPromptExitRating(opts: {
30
+ readonly stdinIsTTY: boolean;
31
+ readonly env: Readonly<Record<string, string | undefined>>;
32
+ readonly feedback: ExitRatingFeedback | undefined;
33
+ readonly assistantTurns: number;
34
+ readonly cleanExit: boolean;
35
+ }): ExitRatingDecision;
36
+ export type ExitRatingChoice = "up" | "down" | "skip";
37
+ /** Map the raw keystroke to a rating: g/G → good (thumbs up), b/B → bad
38
+ * (thumbs down), anything else — enter, timeout (undefined), Ctrl-C/D —
39
+ * skips. One keystroke, no confirmation, zero-cost to ignore. */
40
+ export declare function parseExitRatingKey(key: string | undefined): ExitRatingChoice;
41
+ /**
42
+ * The `user_feedback` payload for an exit rating — byte-compatible with the
43
+ * record `crewhaus rate --thumbs` builds, so one distill reads both.
44
+ */
45
+ export declare function buildExitRatingRecord(input: {
46
+ readonly sessionId: string;
47
+ readonly turnNumber: number;
48
+ readonly thumbs: "up" | "down";
49
+ readonly id?: string;
50
+ readonly ts?: string;
51
+ }): {
52
+ schemaVersion: 1;
53
+ id: string;
54
+ sessionId: string;
55
+ turnNumber: number;
56
+ modality: "binary";
57
+ rating: {
58
+ thumbs: "up" | "down";
59
+ };
60
+ source: "cli";
61
+ ts: string;
62
+ };
63
+ export type ExitRatingRecord = ReturnType<typeof buildExitRatingRecord>;
64
+ /**
65
+ * The whole prompt, with every IO edge injected so the decision + append are
66
+ * unit-testable without a TTY. Returns the recorded choice, or `undefined`
67
+ * when the gate declined to prompt.
68
+ *
69
+ * Best-effort by contract: `readKey`/`append` failures are surfaced to the
70
+ * caller's `onError` (the runtime logs a warning) and never propagate — a
71
+ * rating prompt must not turn a clean session into a failed one.
72
+ */
73
+ export declare function runExitRating(opts: {
74
+ readonly feedback: ExitRatingFeedback | undefined;
75
+ readonly stdinIsTTY: boolean;
76
+ readonly env: Readonly<Record<string, string | undefined>>;
77
+ readonly assistantTurns: number;
78
+ readonly cleanExit: boolean;
79
+ readonly sessionId: string;
80
+ readonly turnNumber: number;
81
+ /** Reads one keystroke; defaults to the raw-mode {@link readExitRatingKey}. */
82
+ readonly readKey?: () => Promise<string | undefined>;
83
+ readonly append: (record: ExitRatingRecord) => Promise<void>;
84
+ readonly write: (line: string) => void;
85
+ readonly onError?: (err: unknown) => void;
86
+ }): Promise<ExitRatingChoice | undefined>;
87
+ /**
88
+ * One raw-mode keystroke with a timeout (undefined on timeout or when stdin
89
+ * is unusable). Thin IO by design — the gate and the key mapping above are
90
+ * the unit-tested pure functions.
91
+ */
92
+ export declare function readExitRatingKey(timeoutMs?: number): Promise<string | undefined>;
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Item 1 — the one-keystroke exit rating prompt, owned by the RUNTIME so both
3
+ * cli surfaces get it.
4
+ *
5
+ * The spec's `feedback:` block declares that a harness collects human ratings
6
+ * on responses. Until now only `crewhaus run` honoured it: the prompt lived in
7
+ * the CLI's own post-session teardown, and the cli emitter dropped the block
8
+ * entirely — a compiled bundle had no rating prompt, so the improvement
9
+ * contract the spec advertised silently vanished from the shipped artifact.
10
+ * The prompt belongs where the REPL is, and the REPL is `runChatLoop`, so it
11
+ * lives here and both surfaces reach it by threading `feedback` into the loop.
12
+ *
13
+ * On a CLEAN REPL exit (the loop returned — not aborted, not thrown) with at
14
+ * least one assistant answer, a TTY stdin, and no opt-out, the runtime asks
15
+ *
16
+ * rate this session? [g]ood / [b]ad / [enter] skip:
17
+ *
18
+ * and appends the answer as the SAME durable `user_feedback` event-log record
19
+ * `crewhaus rate` writes (`source: "cli"`, rating the last turn) — so
20
+ * `crewhaus rate`/`feedback`/`distill` and `optimize --ratings` read a
21
+ * compiled bundle's ratings exactly as they read an interpreted run's.
22
+ *
23
+ * Opt out with `CREWHAUS_NO_EXIT_RATING=1` or spec `feedback.exitPrompt:
24
+ * false`. NEVER prompts in non-TTY/piped mode, so scripts and CI are unaffected.
25
+ *
26
+ * Everything decidable is a pure function here (unit-tested); the raw-mode
27
+ * keystroke read is the one thin IO helper.
28
+ */
29
+ import { randomBytes } from "node:crypto";
30
+ /** Opt-out env for the exit rating prompt. */
31
+ export const NO_EXIT_RATING_ENV = "CREWHAUS_NO_EXIT_RATING";
32
+ export const EXIT_RATING_PROMPT = "rate this session? [g]ood / [b]ad / [enter] skip: ";
33
+ export const EXIT_RATING_TIMEOUT_MS = 10_000;
34
+ /** The event-log EventKind a rating is persisted under (mirrors the CLI's
35
+ * `FEEDBACK_EVENT_KIND` and the channel target's reaction codegen). */
36
+ export const FEEDBACK_EVENT_KIND = "user_feedback";
37
+ /**
38
+ * The pure gate. Prompts only when ALL hold: the spec has a feedback block
39
+ * (presence opts in), it isn't disabled (`enabled: false`) or prompt-opted-out
40
+ * (`exitPrompt: false`), `CREWHAUS_NO_EXIT_RATING` is not set, the loop exited
41
+ * cleanly (an aborted or crashed run is not a session anyone wants to rate),
42
+ * stdin is a real TTY (NEVER in piped/CI mode), and the session produced at
43
+ * least one assistant answer.
44
+ */
45
+ export function shouldPromptExitRating(opts) {
46
+ if (opts.feedback === undefined)
47
+ return { prompt: false, reason: "spec has no feedback block" };
48
+ if (opts.feedback.enabled === false) {
49
+ return { prompt: false, reason: "feedback block is disabled (enabled: false)" };
50
+ }
51
+ if (opts.feedback.exitPrompt === false) {
52
+ return { prompt: false, reason: "feedback.exitPrompt is false" };
53
+ }
54
+ const optOut = opts.env[NO_EXIT_RATING_ENV];
55
+ if (optOut !== undefined && optOut !== "" && optOut !== "0") {
56
+ return { prompt: false, reason: `${NO_EXIT_RATING_ENV} is set` };
57
+ }
58
+ if (!opts.cleanExit)
59
+ return { prompt: false, reason: "run did not exit cleanly" };
60
+ if (!opts.stdinIsTTY)
61
+ return { prompt: false, reason: "stdin is not a TTY" };
62
+ if (opts.assistantTurns < 1) {
63
+ return { prompt: false, reason: "session has no assistant turns to rate" };
64
+ }
65
+ return { prompt: true, reason: "feedback block present, TTY, rated-able session" };
66
+ }
67
+ /** Map the raw keystroke to a rating: g/G → good (thumbs up), b/B → bad
68
+ * (thumbs down), anything else — enter, timeout (undefined), Ctrl-C/D —
69
+ * skips. One keystroke, no confirmation, zero-cost to ignore. */
70
+ export function parseExitRatingKey(key) {
71
+ if (key === undefined || key.length === 0)
72
+ return "skip";
73
+ const first = key[0];
74
+ if (first === "g" || first === "G")
75
+ return "up";
76
+ if (first === "b" || first === "B")
77
+ return "down";
78
+ return "skip";
79
+ }
80
+ /**
81
+ * The `user_feedback` payload for an exit rating — byte-compatible with the
82
+ * record `crewhaus rate --thumbs` builds, so one distill reads both.
83
+ */
84
+ export function buildExitRatingRecord(input) {
85
+ return {
86
+ schemaVersion: 1,
87
+ id: input.id ?? `fb_${randomBytes(6).toString("hex")}`,
88
+ sessionId: input.sessionId,
89
+ turnNumber: input.turnNumber,
90
+ modality: "binary",
91
+ rating: { thumbs: input.thumbs },
92
+ source: "cli",
93
+ ts: input.ts ?? new Date().toISOString(),
94
+ };
95
+ }
96
+ /**
97
+ * The whole prompt, with every IO edge injected so the decision + append are
98
+ * unit-testable without a TTY. Returns the recorded choice, or `undefined`
99
+ * when the gate declined to prompt.
100
+ *
101
+ * Best-effort by contract: `readKey`/`append` failures are surfaced to the
102
+ * caller's `onError` (the runtime logs a warning) and never propagate — a
103
+ * rating prompt must not turn a clean session into a failed one.
104
+ */
105
+ export async function runExitRating(opts) {
106
+ const decision = shouldPromptExitRating({
107
+ stdinIsTTY: opts.stdinIsTTY,
108
+ env: opts.env,
109
+ feedback: opts.feedback,
110
+ assistantTurns: opts.assistantTurns,
111
+ cleanExit: opts.cleanExit,
112
+ });
113
+ if (!decision.prompt)
114
+ return undefined;
115
+ try {
116
+ const choice = parseExitRatingKey(await (opts.readKey ?? readExitRatingKey)());
117
+ if (choice === "skip")
118
+ return "skip";
119
+ await opts.append(buildExitRatingRecord({
120
+ sessionId: opts.sessionId,
121
+ turnNumber: opts.turnNumber,
122
+ thumbs: choice,
123
+ }));
124
+ opts.write(`[feedback] recorded ${choice === "up" ? "good" : "bad"} on ${opts.sessionId} turn ${opts.turnNumber}\n`);
125
+ return choice;
126
+ }
127
+ catch (err) {
128
+ opts.onError?.(err);
129
+ return undefined;
130
+ }
131
+ }
132
+ /**
133
+ * One raw-mode keystroke with a timeout (undefined on timeout or when stdin
134
+ * is unusable). Thin IO by design — the gate and the key mapping above are
135
+ * the unit-tested pure functions.
136
+ */
137
+ export async function readExitRatingKey(timeoutMs = EXIT_RATING_TIMEOUT_MS) {
138
+ const stdin = process.stdin;
139
+ if (stdin.isTTY !== true || stdin.destroyed)
140
+ return undefined;
141
+ process.stdout.write(EXIT_RATING_PROMPT);
142
+ return await new Promise((resolveKey) => {
143
+ let done = false;
144
+ const finish = (v) => {
145
+ if (done)
146
+ return;
147
+ done = true;
148
+ clearTimeout(timer);
149
+ stdin.off("data", onData);
150
+ if (typeof stdin.setRawMode === "function")
151
+ stdin.setRawMode(false);
152
+ stdin.pause();
153
+ process.stdout.write("\n");
154
+ resolveKey(v);
155
+ };
156
+ const timer = setTimeout(() => finish(undefined), timeoutMs);
157
+ const onData = (chunk) => finish(chunk.toString());
158
+ if (typeof stdin.setRawMode === "function")
159
+ stdin.setRawMode(true);
160
+ stdin.resume();
161
+ stdin.on("data", onData);
162
+ });
163
+ }
@@ -0,0 +1,29 @@
1
+ /** Default directory the identity file lives in (the project `.crewhaus` dir). */
2
+ export declare const DEFAULT_IDENTITY_DIR = ".crewhaus";
3
+ export declare const IDENTITY_FILENAME = "identity.json";
4
+ export declare const AGENT_IDENTITY_SCHEMA_VERSION: 1;
5
+ /**
6
+ * The persisted identity. `agentId` is the stable, verifiable fingerprint
7
+ * stamped onto trace envelopes; `publicKey`/`privateKey` are base64 DER
8
+ * (SPKI / PKCS8) so the keypair round-trips through `crypto.createPublicKey`
9
+ * for a future signing/verification layer.
10
+ */
11
+ export type AgentIdentityFile = {
12
+ readonly schemaVersion: 1;
13
+ /** SHA-256 hex digest of the SPKI-DER public key. */
14
+ readonly agentId: string;
15
+ readonly algorithm: "ed25519";
16
+ /** base64 SPKI DER. */
17
+ readonly publicKey: string;
18
+ /** base64 PKCS8 DER. */
19
+ readonly privateKey: string;
20
+ readonly createdAt: string;
21
+ };
22
+ /** The public-key fingerprint that becomes `agentId`. */
23
+ export declare function agentFingerprint(spkiDer: Buffer): string;
24
+ /**
25
+ * Load the agent identity from `<dir>/identity.json`, or mint + persist one on
26
+ * first boot. Idempotent and race-safe (create-exclusive write). `now` is
27
+ * injectable for deterministic tests.
28
+ */
29
+ export declare function loadOrCreateAgentIdentity(dir?: string, now?: () => Date): AgentIdentityFile;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Loop contract 0.4 (Batch C, item 4) — agent identity.
3
+ *
4
+ * An Ed25519 keypair auto-generated at first boot into `.crewhaus/identity.json`.
5
+ * Its `agentId` — the SHA-256 fingerprint of the public key — is stamped onto
6
+ * every `TraceEvent` envelope (via the bus's `agentId`) and appended to
7
+ * audit-log records, so a trace event and its audit trail attribute to one
8
+ * agent. The private key lives beside it (mode 0600) for later record signing;
9
+ * this module only generates and loads — signing is a downstream concern.
10
+ *
11
+ * `loadOrCreateAgentIdentity` is idempotent: the first call mints and persists
12
+ * the keypair; every later call re-reads the same file and returns the same
13
+ * `agentId`. Creation is create-exclusive so two concurrent first-boots can't
14
+ * clobber each other's keypair (first writer wins; the loser re-reads it).
15
+ */
16
+ import { createHash, generateKeyPairSync } from "node:crypto";
17
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
18
+ import { dirname, resolve } from "node:path";
19
+ /** Default directory the identity file lives in (the project `.crewhaus` dir). */
20
+ export const DEFAULT_IDENTITY_DIR = ".crewhaus";
21
+ export const IDENTITY_FILENAME = "identity.json";
22
+ export const AGENT_IDENTITY_SCHEMA_VERSION = 1;
23
+ /** The public-key fingerprint that becomes `agentId`. */
24
+ export function agentFingerprint(spkiDer) {
25
+ return createHash("sha256").update(spkiDer).digest("hex");
26
+ }
27
+ function mint(now) {
28
+ const { publicKey, privateKey } = generateKeyPairSync("ed25519");
29
+ const spki = publicKey.export({ type: "spki", format: "der" });
30
+ const pkcs8 = privateKey.export({ type: "pkcs8", format: "der" });
31
+ return {
32
+ schemaVersion: AGENT_IDENTITY_SCHEMA_VERSION,
33
+ agentId: agentFingerprint(spki),
34
+ algorithm: "ed25519",
35
+ publicKey: spki.toString("base64"),
36
+ privateKey: pkcs8.toString("base64"),
37
+ createdAt: now().toISOString(),
38
+ };
39
+ }
40
+ function safeParse(path) {
41
+ if (!existsSync(path))
42
+ return undefined;
43
+ try {
44
+ const parsed = JSON.parse(readFileSync(path, "utf8"));
45
+ if (typeof parsed.agentId === "string" &&
46
+ parsed.agentId.length > 0 &&
47
+ typeof parsed.publicKey === "string" &&
48
+ typeof parsed.privateKey === "string") {
49
+ return parsed;
50
+ }
51
+ }
52
+ catch {
53
+ // Corrupt/unreadable — the caller regenerates.
54
+ }
55
+ return undefined;
56
+ }
57
+ /**
58
+ * Load the agent identity from `<dir>/identity.json`, or mint + persist one on
59
+ * first boot. Idempotent and race-safe (create-exclusive write). `now` is
60
+ * injectable for deterministic tests.
61
+ */
62
+ export function loadOrCreateAgentIdentity(dir = DEFAULT_IDENTITY_DIR, now = () => new Date()) {
63
+ const path = resolve(dir, IDENTITY_FILENAME);
64
+ const existing = safeParse(path);
65
+ if (existing !== undefined)
66
+ return existing;
67
+ const identity = mint(now);
68
+ const body = `${JSON.stringify(identity, null, 2)}\n`;
69
+ mkdirSync(dirname(path), { recursive: true });
70
+ try {
71
+ // create-exclusive: the first concurrent first-boot wins the keypair.
72
+ writeFileSync(path, body, { flag: "wx", mode: 0o600 });
73
+ return identity;
74
+ }
75
+ catch (err) {
76
+ if (err.code !== "EEXIST")
77
+ throw err;
78
+ // Lost the create race, or a corrupt file squats the path.
79
+ const winner = safeParse(path);
80
+ if (winner !== undefined)
81
+ return winner;
82
+ writeFileSync(path, body, { mode: 0o600 });
83
+ return identity;
84
+ }
85
+ }