harness-reflex 0.1.0 → 0.3.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.
- package/CHANGELOG.md +20 -0
- package/README.md +103 -23
- package/USER_GUIDE.md +121 -43
- package/dist/adapters/agy.js +1 -1
- package/dist/adapters/agy.js.map +1 -1
- package/dist/adapters/codex.d.ts +133 -4
- package/dist/adapters/codex.js +325 -2
- package/dist/adapters/codex.js.map +1 -1
- package/dist/backend/defaults.d.ts +31 -0
- package/dist/backend/defaults.js +32 -0
- package/dist/backend/defaults.js.map +1 -0
- package/dist/backend/jev.js +6 -5
- package/dist/backend/jev.js.map +1 -1
- package/dist/backend/mock.d.ts +12 -1
- package/dist/backend/mock.js +34 -0
- package/dist/backend/mock.js.map +1 -1
- package/dist/backend/simple-jev.js +5 -4
- package/dist/backend/simple-jev.js.map +1 -1
- package/dist/backend/types.d.ts +34 -0
- package/dist/backend/types.js.map +1 -1
- package/dist/cli/index.js +5 -3
- package/dist/cli/index.js.map +1 -1
- package/dist/core/closing.d.ts +90 -0
- package/dist/core/closing.js +111 -0
- package/dist/core/closing.js.map +1 -0
- package/dist/core/evidence.d.ts +119 -0
- package/dist/core/evidence.js +209 -0
- package/dist/core/evidence.js.map +1 -0
- package/dist/core/judge.d.ts +221 -0
- package/dist/core/judge.js +251 -0
- package/dist/core/judge.js.map +1 -0
- package/dist/core/orchestrate-closing.d.ts +237 -0
- package/dist/core/orchestrate-closing.js +250 -0
- package/dist/core/orchestrate-closing.js.map +1 -0
- package/dist/core/orchestrate-correction.d.ts +209 -0
- package/dist/core/orchestrate-correction.js +141 -0
- package/dist/core/orchestrate-correction.js.map +1 -0
- package/dist/core/orchestrate-host.d.ts +225 -0
- package/dist/core/orchestrate-host.js +80 -0
- package/dist/core/orchestrate-host.js.map +1 -0
- package/dist/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/core/orchestrate-stagnation.js +270 -0
- package/dist/core/orchestrate-stagnation.js.map +1 -0
- package/dist/core/orchestrate.d.ts +357 -0
- package/dist/core/orchestrate.js +418 -0
- package/dist/core/orchestrate.js.map +1 -0
- package/dist/core/policy.d.ts +122 -0
- package/dist/core/policy.js +102 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/prune-plan.d.ts +141 -0
- package/dist/core/prune-plan.js +390 -0
- package/dist/core/prune-plan.js.map +1 -0
- package/dist/core/score.d.ts +2 -2
- package/dist/core/score.js.map +1 -1
- package/dist/core/text.d.ts +36 -0
- package/dist/core/text.js +66 -0
- package/dist/core/text.js.map +1 -0
- package/dist/hook/cli.d.ts +9 -0
- package/dist/hook/cli.js +52 -0
- package/dist/hook/cli.js.map +1 -0
- package/dist/hook/contract.d.ts +125 -0
- package/dist/hook/contract.js +159 -0
- package/dist/hook/contract.js.map +1 -0
- package/dist/hook/decision.d.ts +97 -0
- package/dist/hook/decision.js +955 -0
- package/dist/hook/decision.js.map +1 -0
- package/dist/hook/memory-store.d.ts +81 -0
- package/dist/hook/memory-store.js +157 -0
- package/dist/hook/memory-store.js.map +1 -0
- package/dist/hook/payload.d.ts +55 -0
- package/dist/hook/payload.js +129 -0
- package/dist/hook/payload.js.map +1 -0
- package/dist/hook/run.d.ts +48 -0
- package/dist/hook/run.js +218 -0
- package/dist/hook/run.js.map +1 -0
- package/dist/hook/store-port.d.ts +72 -0
- package/dist/hook/store-port.js +2 -0
- package/dist/hook/store-port.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/ports/audit.d.ts +18 -0
- package/dist/ports/audit.js +11 -0
- package/dist/ports/audit.js.map +1 -0
- package/dist/ports/clock.d.ts +14 -0
- package/dist/ports/clock.js +11 -0
- package/dist/ports/clock.js.map +1 -0
- package/dist/ports/decision.d.ts +75 -0
- package/dist/ports/decision.js +2 -0
- package/dist/ports/decision.js.map +1 -0
- package/dist/ports/index.d.ts +14 -0
- package/dist/ports/index.js +2 -0
- package/dist/ports/index.js.map +1 -0
- package/dist/ports/log.d.ts +22 -0
- package/dist/ports/log.js +12 -0
- package/dist/ports/log.js.map +1 -0
- package/dist/ports/state.d.ts +46 -0
- package/dist/ports/state.js +13 -0
- package/dist/ports/state.js.map +1 -0
- package/dist/state/clock.d.ts +40 -0
- package/dist/state/clock.js +43 -0
- package/dist/state/clock.js.map +1 -0
- package/dist/state/file-store.d.ts +340 -0
- package/dist/state/file-store.js +849 -0
- package/dist/state/file-store.js.map +1 -0
- package/dist/state/paths.d.ts +41 -0
- package/dist/state/paths.js +73 -0
- package/dist/state/paths.js.map +1 -0
- package/docs/USER_GUIDE.en.md +79 -36
- package/docs/claude-code.md +281 -0
- package/docs/design/v0.2.0-harness-plugins.md +381 -0
- package/docs/design/v0.3.0-orchestration-unification.md +580 -0
- package/docs/dsh-plugin.md +54 -54
- package/docs/release-checklist-v0.1.0.md +32 -21
- package/docs/release-handbook-porting-notes.md +11 -11
- package/docs/release-handbook.md +55 -30
- package/docs/release-notes-v0.1.0.md +27 -14
- package/docs/release-notes-v0.3.0.md +152 -0
- package/docs/research/claude-code-harness.md +607 -0
- package/docs/research/pi-harness.md +621 -0
- package/package.json +16 -7
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Logger port.
|
|
3
|
+
*
|
|
4
|
+
* The decision core is deliberately quiet — it reports through the audit record
|
|
5
|
+
* rather than through free-form logging — but a composition root may still want
|
|
6
|
+
* its own diagnostics. This interface is the only logging surface the core could
|
|
7
|
+
* ever call, and it is optional.
|
|
8
|
+
*
|
|
9
|
+
* @module ports/log
|
|
10
|
+
*/
|
|
11
|
+
/** The severity vocabulary of the diagnostic sink. */
|
|
12
|
+
export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
|
|
13
|
+
/** A structured diagnostic sink. */
|
|
14
|
+
export interface LoggerPort {
|
|
15
|
+
/**
|
|
16
|
+
* Emit one diagnostic line.
|
|
17
|
+
* @param level - severity.
|
|
18
|
+
* @param message - human-readable text.
|
|
19
|
+
* @param fields - structured context, when the host can retain it.
|
|
20
|
+
*/
|
|
21
|
+
log(level: LogLevel, message: string, fields?: Readonly<Record<string, unknown>>): void;
|
|
22
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Logger port.
|
|
3
|
+
*
|
|
4
|
+
* The decision core is deliberately quiet — it reports through the audit record
|
|
5
|
+
* rather than through free-form logging — but a composition root may still want
|
|
6
|
+
* its own diagnostics. This interface is the only logging surface the core could
|
|
7
|
+
* ever call, and it is optional.
|
|
8
|
+
*
|
|
9
|
+
* @module ports/log
|
|
10
|
+
*/
|
|
11
|
+
export {};
|
|
12
|
+
//# sourceMappingURL=log.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/ports/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * Logger port.\n *\n * The decision core is deliberately quiet — it reports through the audit record\n * rather than through free-form logging — but a composition root may still want\n * its own diagnostics. This interface is the only logging surface the core could\n * ever call, and it is optional.\n *\n * @module ports/log\n */\n\n/** The severity vocabulary of the diagnostic sink. */\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\n\n/** A structured diagnostic sink. */\nexport interface LoggerPort {\n /**\n * Emit one diagnostic line.\n * @param level - severity.\n * @param message - human-readable text.\n * @param fields - structured context, when the host can retain it.\n */\n log(level: LogLevel, message: string, fields?: Readonly<Record<string, unknown>>): void;\n}\n"]}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* State-storage port.
|
|
3
|
+
*
|
|
4
|
+
* The core decisions are pure functions over an explicit state value; where that
|
|
5
|
+
* value is persisted between calls is the host's business. A host that runs each
|
|
6
|
+
* event in a fresh process writes through a file- or session-backed store; one
|
|
7
|
+
* that keeps its decision runtime mounted can use an in-memory map. The
|
|
8
|
+
* interface is the same so both see the same budget and dedupe semantics.
|
|
9
|
+
*
|
|
10
|
+
* @module ports/state
|
|
11
|
+
*/
|
|
12
|
+
/** The per-session counters a decision turn spends from. */
|
|
13
|
+
export interface BudgetSnapshot {
|
|
14
|
+
/** Interventions planned or applied in the current turn. */
|
|
15
|
+
interventions: number;
|
|
16
|
+
/** System 1 judgments spent in the current turn. */
|
|
17
|
+
judgmentsTurn: number;
|
|
18
|
+
/** System 1 judgments spent in the current session. */
|
|
19
|
+
judgmentsSession: number;
|
|
20
|
+
}
|
|
21
|
+
/** A keyed store of per-session state, including the turn/session budget. */
|
|
22
|
+
export interface StateStorePort<T> {
|
|
23
|
+
/**
|
|
24
|
+
* Read one key, without creating it.
|
|
25
|
+
* @param key - session-scoped identity.
|
|
26
|
+
* @returns the stored value, when one exists.
|
|
27
|
+
*/
|
|
28
|
+
read(key: string): T | undefined;
|
|
29
|
+
/**
|
|
30
|
+
* Write one key.
|
|
31
|
+
* @param key - session-scoped identity.
|
|
32
|
+
* @param value - the value to retain.
|
|
33
|
+
*/
|
|
34
|
+
write(key: string, value: T): void;
|
|
35
|
+
/**
|
|
36
|
+
* Drop one key.
|
|
37
|
+
* @param key - session-scoped identity.
|
|
38
|
+
* @returns whether a value was removed.
|
|
39
|
+
*/
|
|
40
|
+
delete(key: string): boolean;
|
|
41
|
+
/** Every key currently stored, for bounded-eviction housekeeping. */
|
|
42
|
+
keys(): Iterable<string>;
|
|
43
|
+
}
|
|
44
|
+
/** The budget half of a session store, narrowed to what the policy spends. */
|
|
45
|
+
export interface BudgetStorePort extends StateStorePort<BudgetSnapshot> {
|
|
46
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* State-storage port.
|
|
3
|
+
*
|
|
4
|
+
* The core decisions are pure functions over an explicit state value; where that
|
|
5
|
+
* value is persisted between calls is the host's business. A host that runs each
|
|
6
|
+
* event in a fresh process writes through a file- or session-backed store; one
|
|
7
|
+
* that keeps its decision runtime mounted can use an in-memory map. The
|
|
8
|
+
* interface is the same so both see the same budget and dedupe semantics.
|
|
9
|
+
*
|
|
10
|
+
* @module ports/state
|
|
11
|
+
*/
|
|
12
|
+
export {};
|
|
13
|
+
//# sourceMappingURL=state.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/ports/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG","sourcesContent":["/**\n * State-storage port.\n *\n * The core decisions are pure functions over an explicit state value; where that\n * value is persisted between calls is the host's business. A host that runs each\n * event in a fresh process writes through a file- or session-backed store; one\n * that keeps its decision runtime mounted can use an in-memory map. The\n * interface is the same so both see the same budget and dedupe semantics.\n *\n * @module ports/state\n */\n\n/** The per-session counters a decision turn spends from. */\nexport interface BudgetSnapshot {\n /** Interventions planned or applied in the current turn. */\n interventions: number;\n /** System 1 judgments spent in the current turn. */\n judgmentsTurn: number;\n /** System 1 judgments spent in the current session. */\n judgmentsSession: number;\n}\n\n/** A keyed store of per-session state, including the turn/session budget. */\nexport interface StateStorePort<T> {\n /**\n * Read one key, without creating it.\n * @param key - session-scoped identity.\n * @returns the stored value, when one exists.\n */\n read(key: string): T | undefined;\n /**\n * Write one key.\n * @param key - session-scoped identity.\n * @param value - the value to retain.\n */\n write(key: string, value: T): void;\n /**\n * Drop one key.\n * @param key - session-scoped identity.\n * @returns whether a value was removed.\n */\n delete(key: string): boolean;\n /** Every key currently stored, for bounded-eviction housekeeping. */\n keys(): Iterable<string>;\n}\n\n/** The budget half of a session store, narrowed to what the policy spends. */\nexport interface BudgetStorePort extends StateStorePort<BudgetSnapshot> {}\n"]}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The clock the state store and the hook read.
|
|
3
|
+
*
|
|
4
|
+
* Tests need a clock that can be pinned; the design exposes
|
|
5
|
+
* `HARNESS_REFLEX_CLOCK` for exactly that (design §3.4). Production reads the
|
|
6
|
+
* wall clock. Nothing in the decision core reads a clock directly.
|
|
7
|
+
*
|
|
8
|
+
* @module state/clock
|
|
9
|
+
*/
|
|
10
|
+
/** A clock with both a millisecond reading and an ISO rendering. */
|
|
11
|
+
export interface HookClock {
|
|
12
|
+
/** Current time in epoch milliseconds. */
|
|
13
|
+
now(): number;
|
|
14
|
+
/** Current time as an ISO-8601 string. */
|
|
15
|
+
iso(): string;
|
|
16
|
+
}
|
|
17
|
+
/** The wall clock. */
|
|
18
|
+
export declare class SystemClock implements HookClock {
|
|
19
|
+
now(): number;
|
|
20
|
+
iso(): string;
|
|
21
|
+
}
|
|
22
|
+
/** A clock pinned to one instant, for repeatable fixtures. */
|
|
23
|
+
export declare class FixedClock implements HookClock {
|
|
24
|
+
#private;
|
|
25
|
+
/**
|
|
26
|
+
* @param ms - the instant every reading reports.
|
|
27
|
+
*/
|
|
28
|
+
constructor(ms: number);
|
|
29
|
+
now(): number;
|
|
30
|
+
iso(): string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Resolve the clock from the environment.
|
|
34
|
+
*
|
|
35
|
+
* `HARNESS_REFLEX_CLOCK` is an ISO timestamp; an unparseable value is ignored
|
|
36
|
+
* rather than failing the hook (the wall clock is always a safe fallback).
|
|
37
|
+
* @param env - environment to read.
|
|
38
|
+
* @returns the pinned clock, or the wall clock.
|
|
39
|
+
*/
|
|
40
|
+
export declare function clockFromEnv(env?: NodeJS.ProcessEnv): HookClock;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/** The wall clock. */
|
|
2
|
+
export class SystemClock {
|
|
3
|
+
now() {
|
|
4
|
+
return Date.now();
|
|
5
|
+
}
|
|
6
|
+
iso() {
|
|
7
|
+
return new Date(this.now()).toISOString();
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
/** A clock pinned to one instant, for repeatable fixtures. */
|
|
11
|
+
export class FixedClock {
|
|
12
|
+
#ms;
|
|
13
|
+
/**
|
|
14
|
+
* @param ms - the instant every reading reports.
|
|
15
|
+
*/
|
|
16
|
+
constructor(ms) {
|
|
17
|
+
this.#ms = ms;
|
|
18
|
+
}
|
|
19
|
+
now() {
|
|
20
|
+
return this.#ms;
|
|
21
|
+
}
|
|
22
|
+
iso() {
|
|
23
|
+
return new Date(this.#ms).toISOString();
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Resolve the clock from the environment.
|
|
28
|
+
*
|
|
29
|
+
* `HARNESS_REFLEX_CLOCK` is an ISO timestamp; an unparseable value is ignored
|
|
30
|
+
* rather than failing the hook (the wall clock is always a safe fallback).
|
|
31
|
+
* @param env - environment to read.
|
|
32
|
+
* @returns the pinned clock, or the wall clock.
|
|
33
|
+
*/
|
|
34
|
+
export function clockFromEnv(env = process.env) {
|
|
35
|
+
const raw = env.HARNESS_REFLEX_CLOCK?.trim();
|
|
36
|
+
if (raw) {
|
|
37
|
+
const ms = Date.parse(raw);
|
|
38
|
+
if (Number.isFinite(ms))
|
|
39
|
+
return new FixedClock(ms);
|
|
40
|
+
}
|
|
41
|
+
return new SystemClock();
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=clock.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/state/clock.ts"],"names":[],"mappings":"AAiBA,sBAAsB;AACtB,MAAM,OAAO,WAAW;IACtB,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,GAAG;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,OAAO,UAAU;IACZ,GAAG,CAAS;IAErB;;OAEG;IACH,YAAY,EAAU;QACpB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;IAChB,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,GAAG;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["/**\n * The clock the state store and the hook read.\n *\n * Tests need a clock that can be pinned; the design exposes\n * `HARNESS_REFLEX_CLOCK` for exactly that (design §3.4). Production reads the\n * wall clock. Nothing in the decision core reads a clock directly.\n *\n * @module state/clock\n */\n/** A clock with both a millisecond reading and an ISO rendering. */\nexport interface HookClock {\n /** Current time in epoch milliseconds. */\n now(): number;\n /** Current time as an ISO-8601 string. */\n iso(): string;\n}\n\n/** The wall clock. */\nexport class SystemClock implements HookClock {\n now(): number {\n return Date.now();\n }\n\n iso(): string {\n return new Date(this.now()).toISOString();\n }\n}\n\n/** A clock pinned to one instant, for repeatable fixtures. */\nexport class FixedClock implements HookClock {\n readonly #ms: number;\n\n /**\n * @param ms - the instant every reading reports.\n */\n constructor(ms: number) {\n this.#ms = ms;\n }\n\n now(): number {\n return this.#ms;\n }\n\n iso(): string {\n return new Date(this.#ms).toISOString();\n }\n}\n\n/**\n * Resolve the clock from the environment.\n *\n * `HARNESS_REFLEX_CLOCK` is an ISO timestamp; an unparseable value is ignored\n * rather than failing the hook (the wall clock is always a safe fallback).\n * @param env - environment to read.\n * @returns the pinned clock, or the wall clock.\n */\nexport function clockFromEnv(env: NodeJS.ProcessEnv = process.env): HookClock {\n const raw = env.HARNESS_REFLEX_CLOCK?.trim();\n if (raw) {\n const ms = Date.parse(raw);\n if (Number.isFinite(ms)) return new FixedClock(ms);\n }\n return new SystemClock();\n}\n"]}
|
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
import type { HookClock } from './clock.js';
|
|
2
|
+
/** Longest JSONL line this store will append, in bytes (design §3.3). */
|
|
3
|
+
export declare const MAX_JSONL_LINE_BYTES: number;
|
|
4
|
+
/** Bad lines read from one file before the file is treated as unusable. */
|
|
5
|
+
export declare const MAX_BAD_LINES = 5;
|
|
6
|
+
/** Default lifetime of a session directory, seven days. */
|
|
7
|
+
export declare const SESSION_RETENTION_MS: number;
|
|
8
|
+
/** Default cap on one session's retained originals: 32 MiB. */
|
|
9
|
+
export declare const MAX_ORIGINAL_BYTES: number;
|
|
10
|
+
/** Default staleness of a `lock/` directory before it may be taken over. */
|
|
11
|
+
export declare const LOCK_STALE_MS: number;
|
|
12
|
+
/** Version recorded in `meta.json`; kept in step with package.json by hand. */
|
|
13
|
+
export declare const HARNESS_STATE_VERSION = "0.1.0-alpha.2";
|
|
14
|
+
/** Tail window for reads, so a large log is never loaded whole. */
|
|
15
|
+
export declare const READ_TAIL_BYTES: number;
|
|
16
|
+
/** One session's identity, as stored in `meta.json`. */
|
|
17
|
+
export interface SessionMeta {
|
|
18
|
+
harness: string;
|
|
19
|
+
/** Plaintext session id; the directory name only carries its hash. */
|
|
20
|
+
sessionId: string;
|
|
21
|
+
createdAt: string;
|
|
22
|
+
harnessVersion: string;
|
|
23
|
+
mode: string;
|
|
24
|
+
}
|
|
25
|
+
/** The per-turn counters a decision turn spends from. */
|
|
26
|
+
export interface SessionBudget {
|
|
27
|
+
interventions: number;
|
|
28
|
+
judgmentsTurn: number;
|
|
29
|
+
judgmentsSession: number;
|
|
30
|
+
}
|
|
31
|
+
/** The derived cache in `state.json`; never authoritative. */
|
|
32
|
+
export interface SessionState {
|
|
33
|
+
version: 1;
|
|
34
|
+
turnNo: number;
|
|
35
|
+
appliedSignatures: string[];
|
|
36
|
+
budgets: SessionBudget;
|
|
37
|
+
continues: Record<string, number>;
|
|
38
|
+
updatedAt: string;
|
|
39
|
+
}
|
|
40
|
+
/** One line of `events.jsonl`: a tool observation, append-only. */
|
|
41
|
+
export interface SessionEvent {
|
|
42
|
+
v: 1;
|
|
43
|
+
kind: 'pre' | 'post' | 'failure' | 'stop' | 'session';
|
|
44
|
+
at: number;
|
|
45
|
+
atIso: string;
|
|
46
|
+
turnNo: number;
|
|
47
|
+
tool?: string;
|
|
48
|
+
toolUseId?: string;
|
|
49
|
+
signature?: string;
|
|
50
|
+
failed?: boolean;
|
|
51
|
+
/** Bounded model-facing text of the result, for later evidence assembly. */
|
|
52
|
+
output?: string;
|
|
53
|
+
source?: string;
|
|
54
|
+
/** Present when the observation is also the idempotency commit of a decision. */
|
|
55
|
+
dedupeKey?: string;
|
|
56
|
+
}
|
|
57
|
+
/** The ledger vocabulary of the hook surface. */
|
|
58
|
+
export type HookLedgerType = 'stagnation' | 'prune' | 'gate' | 'closing' | 'noop' | 'error';
|
|
59
|
+
/** One line of `ledger.jsonl`: an auditable decision or skip. */
|
|
60
|
+
export interface HookLedgerRecord {
|
|
61
|
+
id: string;
|
|
62
|
+
timestamp: string;
|
|
63
|
+
type: HookLedgerType;
|
|
64
|
+
harness: string;
|
|
65
|
+
event: string;
|
|
66
|
+
backend: string;
|
|
67
|
+
latencyMs: number;
|
|
68
|
+
dedupeKey: string;
|
|
69
|
+
turnNo: number;
|
|
70
|
+
shadow?: boolean;
|
|
71
|
+
applied?: boolean;
|
|
72
|
+
judged?: boolean;
|
|
73
|
+
tokensSaved?: number;
|
|
74
|
+
originalTokens?: number;
|
|
75
|
+
prunedTokens?: number;
|
|
76
|
+
passed?: boolean;
|
|
77
|
+
isStuck?: boolean;
|
|
78
|
+
skipReason?: string;
|
|
79
|
+
retention?: 'retained' | 'evicted' | 'none';
|
|
80
|
+
details?: Record<string, unknown>;
|
|
81
|
+
}
|
|
82
|
+
/** The paths of one ensured session. */
|
|
83
|
+
export interface SessionPaths {
|
|
84
|
+
dir: string;
|
|
85
|
+
meta: string;
|
|
86
|
+
state: string;
|
|
87
|
+
events: string;
|
|
88
|
+
ledger: string;
|
|
89
|
+
originals: string;
|
|
90
|
+
decisions: string;
|
|
91
|
+
lock: string;
|
|
92
|
+
}
|
|
93
|
+
/** What one retention attempt produced. */
|
|
94
|
+
export interface RetentionResult {
|
|
95
|
+
retained: boolean;
|
|
96
|
+
/** Digest names of older originals evicted to make room. */
|
|
97
|
+
evicted: string[];
|
|
98
|
+
/** Why the new payload was not retained, when it was not. */
|
|
99
|
+
reason?: string;
|
|
100
|
+
}
|
|
101
|
+
/** Options of {@link FileStateStore}. */
|
|
102
|
+
export interface FileStateStoreOptions {
|
|
103
|
+
/** State root; defaults to {@link resolveStateRoot}. */
|
|
104
|
+
root?: string;
|
|
105
|
+
/** Harness tag; defaults to `cc`. */
|
|
106
|
+
harness?: string;
|
|
107
|
+
/** Clock used for timestamps and staleness. */
|
|
108
|
+
clock?: HookClock;
|
|
109
|
+
/** Lock takeover age, default five seconds. */
|
|
110
|
+
lockStaleMs?: number;
|
|
111
|
+
/** Session directory lifetime, default seven days. */
|
|
112
|
+
sessionRetentionMs?: number;
|
|
113
|
+
/** Retained-original cap, default 32 MiB. */
|
|
114
|
+
maxOriginalBytes?: number;
|
|
115
|
+
}
|
|
116
|
+
/** The value returned by a lock attempt. */
|
|
117
|
+
export interface LockAttempt<T> {
|
|
118
|
+
acquired: boolean;
|
|
119
|
+
value?: T;
|
|
120
|
+
reason?: string;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The file-backed implementation of the hook's external state.
|
|
124
|
+
*
|
|
125
|
+
* Every mutating operation is either an append (safe for concurrent writers) or
|
|
126
|
+
* guarded by the directory lock. Readers never throw on corrupt data: they
|
|
127
|
+
* isolate, rebuild, or return an empty view, because a hook that throws is a
|
|
128
|
+
* hook that might be misread as a decision.
|
|
129
|
+
*/
|
|
130
|
+
export declare class FileStateStore {
|
|
131
|
+
readonly root: string;
|
|
132
|
+
readonly harness: string;
|
|
133
|
+
readonly clock: HookClock;
|
|
134
|
+
readonly lockStaleMs: number;
|
|
135
|
+
readonly sessionRetentionMs: number;
|
|
136
|
+
readonly maxOriginalBytes: number;
|
|
137
|
+
/**
|
|
138
|
+
* @param options - root, harness, clock, and the retention/lock knobs.
|
|
139
|
+
*/
|
|
140
|
+
constructor(options?: FileStateStoreOptions);
|
|
141
|
+
/** The directory all session directories live in. */
|
|
142
|
+
sessionsRoot(): string;
|
|
143
|
+
/** The directory quarantined sessions are moved into. */
|
|
144
|
+
orphansRoot(): string;
|
|
145
|
+
/** The directory of one session (`<root>/sessions/cc-<sha16>`). */
|
|
146
|
+
sessionDir(sessionId: string): string;
|
|
147
|
+
/** The paths of one session without creating anything. */
|
|
148
|
+
sessionPaths(sessionId: string): SessionPaths;
|
|
149
|
+
/**
|
|
150
|
+
* Create the session directory and its metadata if they are missing.
|
|
151
|
+
*
|
|
152
|
+
* A directory whose `meta.json` does not hash back to its own name is
|
|
153
|
+
* quarantined under `orphans/` rather than trusted (design §3.2/§3.4).
|
|
154
|
+
* @param sessionId - the host's session id.
|
|
155
|
+
* @param mode - the effective three-state mode, for `meta.json`.
|
|
156
|
+
* @returns the ensured session paths.
|
|
157
|
+
*/
|
|
158
|
+
ensureSession(sessionId: string, mode: string): SessionPaths;
|
|
159
|
+
/**
|
|
160
|
+
* Append one observation to `events.jsonl`.
|
|
161
|
+
* @param sessionId - the session.
|
|
162
|
+
* @param record - the event line.
|
|
163
|
+
*/
|
|
164
|
+
appendEvent(sessionId: string, record: SessionEvent): void;
|
|
165
|
+
/**
|
|
166
|
+
* Append one decision or skip to `ledger.jsonl`.
|
|
167
|
+
*
|
|
168
|
+
* A record is bounded before it is written: an oversized details object is
|
|
169
|
+
* dropped rather than split, so a line is always one atomic write.
|
|
170
|
+
* @param sessionId - the session.
|
|
171
|
+
* @param record - the ledger line.
|
|
172
|
+
*/
|
|
173
|
+
appendLedger(sessionId: string, record: HookLedgerRecord): void;
|
|
174
|
+
/**
|
|
175
|
+
* Read the newest events of one session, oldest first.
|
|
176
|
+
* @param sessionId - the session.
|
|
177
|
+
* @param limit - maximum events to return.
|
|
178
|
+
* @returns parseable events, newest tail only.
|
|
179
|
+
*/
|
|
180
|
+
readEvents(sessionId: string, limit?: number): SessionEvent[];
|
|
181
|
+
/**
|
|
182
|
+
* Read the newest ledger lines of one session, oldest first.
|
|
183
|
+
* @param sessionId - the session.
|
|
184
|
+
* @param limit - maximum lines to return.
|
|
185
|
+
* @returns parseable ledger records.
|
|
186
|
+
*/
|
|
187
|
+
readLedger(sessionId: string, limit?: number): HookLedgerRecord[];
|
|
188
|
+
/**
|
|
189
|
+
* Read the cached state, rebuilding it from the logs when it is missing or
|
|
190
|
+
* corrupt. Never throws.
|
|
191
|
+
* @param sessionId - the session.
|
|
192
|
+
* @returns the derived state (a fresh one when nothing could be read).
|
|
193
|
+
*/
|
|
194
|
+
readState(sessionId: string): SessionState;
|
|
195
|
+
/**
|
|
196
|
+
* Run one read-modify-write of `state.json` under the directory lock.
|
|
197
|
+
*
|
|
198
|
+
* A caller that does not get the lock must skip its turn, not queue: a tool
|
|
199
|
+
* call is never worth blocking (design §3.3).
|
|
200
|
+
* @param sessionId - the session.
|
|
201
|
+
* @param mutate - pure update of the state in place.
|
|
202
|
+
* @returns whether the lock was acquired, plus the callback's value.
|
|
203
|
+
*/
|
|
204
|
+
updateState<T>(sessionId: string, mutate: (state: SessionState) => T): LockAttempt<T>;
|
|
205
|
+
/**
|
|
206
|
+
* Whether a dedupe key was already accounted for in the ledger.
|
|
207
|
+
*
|
|
208
|
+
* Only the tail is scanned: a hook is never asked about an ancient call, and
|
|
209
|
+
* an unbounded scan would turn a fast command into a slow one. Error records
|
|
210
|
+
* do not count — a duplicate delivery after a transient failure is allowed to
|
|
211
|
+
* decide again.
|
|
212
|
+
* @param sessionId - the session.
|
|
213
|
+
* @param key - the dedupe key.
|
|
214
|
+
* @param limit - how many trailing ledger lines to inspect.
|
|
215
|
+
* @returns whether a non-error record already carries this key.
|
|
216
|
+
*/
|
|
217
|
+
ledgerHasKey(sessionId: string, key: string, limit?: number): boolean;
|
|
218
|
+
/**
|
|
219
|
+
* Whether a dedupe key was already written to the event log.
|
|
220
|
+
*
|
|
221
|
+
* This is the crash window after the observation was appended and before the
|
|
222
|
+
* ledger line was: the retry must not append the observation twice.
|
|
223
|
+
* @param sessionId - the session.
|
|
224
|
+
* @param key - the dedupe key.
|
|
225
|
+
* @param limit - how many trailing events to inspect.
|
|
226
|
+
* @returns whether the event log already carries this key.
|
|
227
|
+
*/
|
|
228
|
+
eventsHaveKey(sessionId: string, key: string, limit?: number): boolean;
|
|
229
|
+
/**
|
|
230
|
+
* Read one cached decision output.
|
|
231
|
+
* @param sessionId - the session.
|
|
232
|
+
* @param key - the dedupe key.
|
|
233
|
+
* @returns the cached output, or `undefined` when absent/corrupt.
|
|
234
|
+
*/
|
|
235
|
+
readDecision(sessionId: string, key: string): Record<string, unknown> | undefined;
|
|
236
|
+
/**
|
|
237
|
+
* Commit one decision output atomically.
|
|
238
|
+
*
|
|
239
|
+
* The decision cache doubles as the idempotency marker: a duplicate delivery
|
|
240
|
+
* of the same dedupe key replays this object instead of deciding again.
|
|
241
|
+
* @param sessionId - the session.
|
|
242
|
+
* @param key - the dedupe key.
|
|
243
|
+
* @param output - the exact stdout object of the command.
|
|
244
|
+
*/
|
|
245
|
+
writeDecision(sessionId: string, key: string, output: Record<string, unknown>): void;
|
|
246
|
+
/**
|
|
247
|
+
* Claim the right to decide one dedupe key before the expensive path runs.
|
|
248
|
+
*
|
|
249
|
+
* The decision cache is the commit, but it can only be written after the
|
|
250
|
+
* judgment. Two processes delivering the same `tool_use_id` concurrently would
|
|
251
|
+
* both decide in that window; this exclusive-create claim makes the loser an
|
|
252
|
+
* explicit no-op (or a replay, when the winner has already committed). A claim
|
|
253
|
+
* older than `staleMs` is taken over, so a crashed process cannot wedge a key
|
|
254
|
+
* forever.
|
|
255
|
+
* @param sessionId - the session.
|
|
256
|
+
* @param key - the dedupe key.
|
|
257
|
+
* @param staleMs - age after which a claim is considered abandoned.
|
|
258
|
+
* @returns whether this process may decide the key.
|
|
259
|
+
*/
|
|
260
|
+
claimDecision(sessionId: string, key: string, staleMs?: number): {
|
|
261
|
+
acquired: boolean;
|
|
262
|
+
};
|
|
263
|
+
/** Release a claim; never throws. */
|
|
264
|
+
releaseDecisionClaim(sessionId: string, key: string): void;
|
|
265
|
+
/**
|
|
266
|
+
* Retain one pre-prune payload, evicting the oldest copies when the cap is
|
|
267
|
+
* exceeded.
|
|
268
|
+
*
|
|
269
|
+
* The cap applies to the whole `originals/` directory of one session. Evicted
|
|
270
|
+
* names are returned so the caller can record the downgrade; when the new
|
|
271
|
+
* payload itself cannot fit the result is `retained: false` and the caller must
|
|
272
|
+
* install the reduction without a locator and without counting a saving.
|
|
273
|
+
* @param sessionId - the session.
|
|
274
|
+
* @param digest - content digest (the file stem).
|
|
275
|
+
* @param text - the payload, verbatim.
|
|
276
|
+
* @returns what happened.
|
|
277
|
+
*/
|
|
278
|
+
retainOriginal(sessionId: string, digest: string, text: string): RetentionResult;
|
|
279
|
+
/**
|
|
280
|
+
* Read one retained payload back.
|
|
281
|
+
*
|
|
282
|
+
* The locator a pruned result carries names this record; reading it is what
|
|
283
|
+
* makes the reduction reversible, so a missing or unreadable file answers
|
|
284
|
+
* `undefined` instead of throwing into a decision path.
|
|
285
|
+
* @param sessionId - the session.
|
|
286
|
+
* @param digest - content digest (the file stem).
|
|
287
|
+
* @returns the verbatim payload, or `undefined`.
|
|
288
|
+
*/
|
|
289
|
+
readOriginal(sessionId: string, digest: string): string | undefined;
|
|
290
|
+
/** Enforce one session's original cap without retaining anything new. */
|
|
291
|
+
gcOriginals(sessionId: string): string[];
|
|
292
|
+
/**
|
|
293
|
+
* Remove session directories older than the retention window.
|
|
294
|
+
* @param nowMs - clock reading to compare against (defaults to the store clock).
|
|
295
|
+
* @param keepSessionId - a session that must survive even if its mtime looks
|
|
296
|
+
* old (a pinned test clock must never garbage-collect the turn being served).
|
|
297
|
+
* @returns the removed directory names.
|
|
298
|
+
*/
|
|
299
|
+
gcSessions(nowMs?: number, keepSessionId?: string): string[];
|
|
300
|
+
/** The quarantine log path for a session, created on demand. */
|
|
301
|
+
corruptLog(sessionId: string): string;
|
|
302
|
+
/** Create one directory with user-only permissions, best effort. */
|
|
303
|
+
private ensureDir;
|
|
304
|
+
/** Create an empty file with 0600 if it does not exist yet. */
|
|
305
|
+
private ensureFile;
|
|
306
|
+
/** Single-write append of one JSON line. */
|
|
307
|
+
private appendLine;
|
|
308
|
+
/** Read only the tail of a JSONL file, isolating unreadable lines. */
|
|
309
|
+
private readTail;
|
|
310
|
+
/** Append unreadable lines to `corrupt-<ts>.log`; never grow it unbounded. */
|
|
311
|
+
private isolateBadLines;
|
|
312
|
+
/** `corrupt-<ts>.log` in a session directory. */
|
|
313
|
+
private corruptLogFor;
|
|
314
|
+
/** Validate and normalize a parsed `state.json`. */
|
|
315
|
+
private normalizeState;
|
|
316
|
+
/** Rebuild the discardable state from the two authoritative logs. */
|
|
317
|
+
private rebuildState;
|
|
318
|
+
/** Write `state.json` via temp + fsync + rename. */
|
|
319
|
+
private writeState;
|
|
320
|
+
/** Atomic replacement of a small file. */
|
|
321
|
+
private writeAtomic;
|
|
322
|
+
/** Unlink without throwing. */
|
|
323
|
+
private safeUnlink;
|
|
324
|
+
/** Read and validate `meta.json`. */
|
|
325
|
+
private readMeta;
|
|
326
|
+
/** Move a directory whose meta does not match its name into `orphans/`. */
|
|
327
|
+
private quarantine;
|
|
328
|
+
/** Newest mtime under one directory, for the seven-day rule. */
|
|
329
|
+
private latestMtime;
|
|
330
|
+
/** The retained originals, oldest first. */
|
|
331
|
+
private originalEntries;
|
|
332
|
+
/** Take the directory lock, taking over one that is older than the stale rule. */
|
|
333
|
+
private acquireLock;
|
|
334
|
+
/** Release the lock directory. */
|
|
335
|
+
private releaseLock;
|
|
336
|
+
/** When the current lock owner started, from its metadata or its mtime. */
|
|
337
|
+
private lockStartedMs;
|
|
338
|
+
/** Bound one ledger record to the line budget before it can be appended. */
|
|
339
|
+
private bounded;
|
|
340
|
+
}
|