dsh-boost 0.1.1 → 0.1.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.
Files changed (48) hide show
  1. package/README.en.md +97 -33
  2. package/README.md +85 -32
  3. package/dist/gate/decide.js +33 -2
  4. package/dist/gate/decide.js.map +1 -1
  5. package/dist/hooks/llm-stream.js +129 -54
  6. package/dist/hooks/llm-stream.js.map +1 -1
  7. package/dist/hooks/post-execute.js +104 -21
  8. package/dist/hooks/post-execute.js.map +1 -1
  9. package/dist/hooks/session-state.js +18 -8
  10. package/dist/hooks/session-state.js.map +1 -1
  11. package/dist/index.js +371 -67
  12. package/dist/index.js.map +1 -1
  13. package/dist/scope/doc.js.map +1 -1
  14. package/dist/scope/store.js +24 -9
  15. package/dist/scope/store.js.map +1 -1
  16. package/package.json +8 -4
  17. package/dist/admission/fixed-cost.d.ts +0 -23
  18. package/dist/admission/ledger.d.ts +0 -113
  19. package/dist/admission/retrieval.d.ts +0 -65
  20. package/dist/admission/usage.d.ts +0 -75
  21. package/dist/config.d.ts +0 -43
  22. package/dist/gate/binding.d.ts +0 -113
  23. package/dist/gate/decide.d.ts +0 -82
  24. package/dist/gate/guard.d.ts +0 -69
  25. package/dist/gate/invalidate.d.ts +0 -112
  26. package/dist/gate/plan.d.ts +0 -86
  27. package/dist/hooks/clock.d.ts +0 -68
  28. package/dist/hooks/execute.d.ts +0 -79
  29. package/dist/hooks/llm-stream.d.ts +0 -283
  30. package/dist/hooks/pending.d.ts +0 -89
  31. package/dist/hooks/post-execute.d.ts +0 -257
  32. package/dist/hooks/session-state.d.ts +0 -158
  33. package/dist/hooks/synthesize.d.ts +0 -74
  34. package/dist/host/loader.d.ts +0 -23
  35. package/dist/host/platform.d.ts +0 -18
  36. package/dist/host/root.d.ts +0 -25
  37. package/dist/projection/apply.d.ts +0 -174
  38. package/dist/projection/canonicalise.d.ts +0 -43
  39. package/dist/projection/counters.d.ts +0 -65
  40. package/dist/projection/truncate.d.ts +0 -47
  41. package/dist/prompt/protocol.d.ts +0 -45
  42. package/dist/receipts/store.d.ts +0 -198
  43. package/dist/scope/doc.d.ts +0 -117
  44. package/dist/scope/resolve.d.ts +0 -91
  45. package/dist/scope/store.d.ts +0 -135
  46. package/dist/selector/jev.d.ts +0 -93
  47. package/dist/tools/boost.d.ts +0 -380
  48. package/dist/tools/family.d.ts +0 -26
@@ -1,45 +0,0 @@
1
- /**
2
- * The plan-protocol system prompt section.
3
- *
4
- * This module owns the literal text that teaches the model to write a
5
- * `<CHISEL_PLAN>` block: the block shape, the candidate-id rule, the `args`
6
- * restrictions, the `$public` template, the guard vocabulary and the tools
7
- * substitution covers. Nothing here parses or validates a plan —
8
- * `src/gate/plan.ts`, `src/gate/binding.ts`, `src/gate/guard.ts` and
9
- * `src/gate/decide.ts` are the authority, and the text agrees with them.
10
- *
11
- * The referent is the most load-bearing claim: `decide` evaluates every
12
- * candidate's guards against `receipts.get(stepId)` — the receipt that just
13
- * arrived — not against the candidate's own not-yet-existing result. With no
14
- * such receipt nothing is viable, and several candidates whose guards pass on
15
- * that one receipt are alternatives for the selector, not a queue. The text
16
- * states this before the example because a guard aimed at the candidate's own
17
- * output fails every time.
18
- *
19
- * `after:"root"` is taught because T23b keys the just-arrived receipt as
20
- * `root`; an earlier executed candidate's receipt is keyed by its id. `$scalar`
21
- * needs the whole receipt to be one token (a one-path glob); an identifier
22
- * needs un-numbered output (a line-start `X: "value"`), which read/grep do not
23
- * provide; a multi-line value must be typed literally. `$single` is accepted
24
- * by binding but has no producer among the read/grep/glob receipts, so it is
25
- * deliberately not taught.
26
- *
27
- * The section is registered with `interpolate: false`; the text is still kept
28
- * free of `{{` so a later relaxation of that flag cannot rewrite it. The budget
29
- * is 1500 characters; the test pins it because this text is a permanent cost.
30
- *
31
- * @module dsh-boost/prompt/protocol
32
- */
33
- /** Section name the protocol is registered under (design §5.3). */
34
- export declare const PROTOCOL_NAME = "dsh-boost";
35
- /** Section order: alongside the other tool-contract sections. */
36
- export declare const PROTOCOL_ORDER = 100;
37
- /**
38
- * The protocol section's body, injected verbatim.
39
- *
40
- * Order is what the model needs first: where the block goes and which one
41
- * counts, what the guards read, the example and the sentence that repeats its
42
- * operand, the literal `args` rules, the guard vocabulary, the substituted
43
- * tools, and finally `$public` with its two binding sources and its limits.
44
- */
45
- export declare const PROTOCOL_TEXT = "Plan one <CHISEL_PLAN> block in visible text, not reasoning;only the first counts. It describes your next call, so guards test the receipt that just arrived, not that call's own result. No receipt, no substitution. Several steps passing on one receipt are alternatives;one is chosen. Omit when unsure;any failure runs the call normally.\n<CHISEL_PLAN>\n{\"goal\":\"g\",\"steps\":[{\"id\":\"A\",\"tool\":\"read\",\"args\":{\"file_path\":\"/repo/b.ts\"},\"guards\":[{\"text_contains\":\"2 matches\"}]}]}\n</CHISEL_PLAN>\nThe guard reads the incoming receipt, which says \"2 matches\".\nid:one capital A-Z, unique,max 26 steps.\nargs:object,not $public itself,depth<=64,no prototype keys,no $-key except $public.\nguards:>=1 other than {\"ok\":true};each guard object has exactly one form key.\n{\"ok\":true}:no error. {\"text_contains\":\"s\"}:s expected present. {\"text_not_contains\":\"s\"}:s expected absent, such as an error footer. Both case-sensitive,s non-empty,never guessed. {\"json_equals\":{\"pointer\":\"/a/b\",\"value\":\"v\"}}:the whole receipt must be JSON.\nSubstituted:read, grep, glob;others run normally.\n$public copies a value instead of retyping it:{\"$public\":{\"after\":\"root\",\"field\":\"$scalar\"}}. after:\"root\"=the incoming receipt,or a step that already ran. field:\"$scalar\"=the whole receipt is one token (a one-path glob);or X=exactly one line-start X:\"value\" or X=\"value\" (double-quoted, non-empty), which needs un-numbered output,so not read or grep. A multi-line value cannot be projected;type it literally. Else that step is skipped.";
@@ -1,198 +0,0 @@
1
- /** Why a receipt exists. `substitute-settled` is its own line because the store is append-only. */
2
- export type ReceiptKind = 'substitute' | 'substitute-settled' | 'shadow' | 'projection' | 'skip' | 'reset';
3
- /** Fields every receipt carries, before the store fills the derived ones. */
4
- type ReceiptCore = {
5
- ts: string;
6
- sessionId: string;
7
- turn: number;
8
- stepId?: string;
9
- kind: ReceiptKind;
10
- code: string;
11
- tool?: string;
12
- [k: string]: unknown;
13
- };
14
- /**
15
- * One line of the audit log.
16
- *
17
- * Invariant (plan line 581): a receipt with `kind === 'projection'` always
18
- * carries `unit: 'raw'` as a literal — T19/T26 filter on it, so a projection
19
- * receipt without it would be invisible to the counters. The plan keeps
20
- * `Receipt` an interface, which cannot pair `kind` with `unit`, so `buildReceipt`
21
- * enforces the invariant by construction: it overwrites `unit` with `'raw'` on
22
- * every projection receipt, ignoring any caller-supplied value, because the
23
- * literal is the invariant rather than a parameter. A projection receipt is
24
- * never rejected for shape; it must remain auditable.
25
- */
26
- export interface Receipt extends ReceiptCore {
27
- version: 1;
28
- receipt_hash: string;
29
- preview: string;
30
- }
31
- /** What callers hand to `append`; the store fills `version`, `receipt_hash` and `preview`. */
32
- type ReceiptInput = ReceiptCore & {
33
- version?: 1;
34
- preview?: string;
35
- };
36
- /** Tuning knobs; the defaults are the design's (§5.3). */
37
- interface ReceiptStoreOptions {
38
- fsyncEveryLines?: number;
39
- maxBytes?: number;
40
- maxLines?: number;
41
- }
42
- /**
43
- * `sha256(stable JSON)` of the fields that identify a call, first 16 hex chars.
44
- *
45
- * `args` is part of the payload on purpose: without it, two different calls of
46
- * the same tool in one turn would collide. A missing `args` hashes like `{}`,
47
- * and object keys are sorted recursively so insertion order cannot change the
48
- * hash. An own `__proto__` key is an ordinary key, not the prototype setter.
49
- *
50
- * Args deeper than {@link MAX_RECEIPT_ARGS_DEPTH} are cut with a marker before
51
- * hashing, exactly as they are before storing: otherwise the recursive walk or
52
- * `JSON.stringify` would throw and the receipt (the audit evidence) would be
53
- * lost. Two trees that differ only below the bound therefore hash alike; the
54
- * plan parser refuses such trees, and a call whose args are deeper did not come
55
- * from a plan.
56
- */
57
- export declare function receiptHash(r: {
58
- sessionId: string;
59
- turn: number;
60
- stepId?: string;
61
- tool?: string;
62
- args?: unknown;
63
- }): string;
64
- /**
65
- * Append-only, crash-safe, bounded store of receipts per session.
66
- *
67
- * See the module docs for the write and read paths. Concurrent method calls on
68
- * one instance are safe: writes are serialised through an internal promise
69
- * chain. The store is single-writer per root by design — rotation counters are
70
- * per instance, so two instances (or processes) writing one root can exceed the
71
- * shard caps and lose receipts. The plugin owns exactly one store per root.
72
- */
73
- export declare class ReceiptStore {
74
- private readonly root;
75
- private readonly fsyncEveryLines;
76
- private readonly maxBytes;
77
- private readonly maxLines;
78
- /** *Consecutive* write failures; reset by any successful append. */
79
- private failureCount;
80
- /**
81
- * Shard reads skipped by whole-store scans since the last scan that read
82
- * every shard (EACCES, EISDIR, …). A fully readable scan resets it to zero,
83
- * so a repaired shard drops `ERR_RECEIPTS_UNREADABLE` instead of pinning it
84
- * for the life of the process. Named scans neither count here nor reset it:
85
- * they do not cover the shard set status reports.
86
- */
87
- private readFailureCount;
88
- /** Whether the most recent whole-store scan hit {@link MAX_SCAN_SHARDS}. */
89
- private scanCapHit;
90
- private linesSinceSync;
91
- private readonly pending;
92
- private readonly states;
93
- private readonly dirty;
94
- private readonly disposed;
95
- private readonly disposedOrder;
96
- private dirReady;
97
- /** Writes run one at a time so rotation and buffer replay cannot interleave. */
98
- private chain;
99
- constructor(root: string, opts?: ReceiptStoreOptions);
100
- /**
101
- * Append one receipt. Never rejects: a serialisation or write failure is
102
- * counted and buffered. The session id is encoded only for the shard name;
103
- * the stored receipt keeps the original id.
104
- */
105
- append(receipt: ReceiptInput): Promise<void>;
106
- /** Force the buffered lines and the current shards to disk (called at turn end). */
107
- flush(): Promise<void>;
108
- /** Number of receipts readable for `sessionId` (`.1` plus current). */
109
- count(sessionId: string): Promise<number>;
110
- /**
111
- * Shard reads that the most recent whole-store scan skipped.
112
- *
113
- * A single unreadable shard (EACCES, a directory named `x.jsonl`, …) must
114
- * not abort the whole scan: `boost status` would turn that into
115
- * `ERR_BOOST_INTERNAL` for the entire ledger. Scans skip the shard and count
116
- * it here so status can report a stable degraded code.
117
- *
118
- * The count describes the skipped reads **since the last whole-store scan
119
- * that read every shard**, not the process lifetime: a fully readable scan
120
- * resets it, so repairing the shard and re-running `status` drops the code,
121
- * as the README instructs. A named `scan(sessionId)`/`count(sessionId)`
122
- * neither contributes to nor clears it, because it does not cover the shard
123
- * set the status total claims.
124
- */
125
- readErrors(): number;
126
- /**
127
- * Whether the most recent whole-store scan stopped at {@link MAX_SCAN_SHARDS}.
128
- *
129
- * `status` reports a total over the shards it read, so a capped scan is a
130
- * lower bound, not a total. The flag is per scan (false on the next full
131
- * scan that fits), which lets the operator see the condition clear; the
132
- * numeric totals stay unchanged and under-count, the safe direction.
133
- */
134
- scanTruncated(): boolean;
135
- /**
136
- * Yield readable receipts, oldest first: `.1` before the current shard.
137
- *
138
- * The optional `sessionId` is encoded to its shard name; the receipts keep
139
- * their original `sessionId`. With no argument, every shard under `receipts/`
140
- * is visited (encoded shard names sorted for determinism, capped at
141
- * {@link MAX_SCAN_SHARDS}), and each receipt supplies its own id from its
142
- * body. Unparseable middle lines are skipped; an unfinished trailing line is
143
- * ignored by the read and only the next write repairs it.
144
- *
145
- * A whole-store scan also maintains the two status readings: a shard it
146
- * cannot read increments {@link readErrors} (a fully readable scan resets
147
- * it), and more shards than the cap sets {@link scanTruncated}. Named scans
148
- * touch neither, because they are not the population `status` totals.
149
- */
150
- scan(sessionId?: string): AsyncIterable<Receipt>;
151
- /**
152
- * Forget one session's shard state and silence later receipts for it.
153
- *
154
- * Called from the plugin's `session/disposed` handler after `flush()`. It
155
- * evicts the cached counters, forgets any buffered lines for that session
156
- * **only when no write failure is outstanding**, and remembers the id
157
- * (bounded FIFO) so a hook that lands after disposal records nothing instead
158
- * of recreating state nothing will ever clear.
159
- *
160
- * The conditional drop is the "flush before eviction" promise: a successful
161
- * flush has already drained `pending`, so the loop is a no-op; a failed one
162
- * leaves the session's lines there, and they are the only copy of that
163
- * evidence. They stay queued for the next flush — the buffer is bounded by
164
- * {@link MAX_PENDING_LINES} and is emptied once {@link stopped} is reached,
165
- * so retaining them cannot grow without limit.
166
- */
167
- disposeSession(sessionId: string): void;
168
- /** Consecutive write failures; a successful append resets it to zero. */
169
- failures(): number;
170
- /** Fail-closed gate: true after {@link STOPPED_AFTER_FAILURES} consecutive write failures. */
171
- stopped(): boolean;
172
- private appendNow;
173
- /** The serialised body of {@link flush}; a failure is counted, never thrown. */
174
- private flushNow;
175
- /**
176
- * Count one write failure and enforce the buffer bound.
177
- *
178
- * Once the store is `stopped()` (three consecutive failures) it is
179
- * fail-closed: appends are still attempted so a recovered disk can reset the
180
- * count, but the replay buffer is dropped instead of growing for as long as
181
- * the outage lasts. Before that point `MAX_PENDING_LINES` is the hard cap.
182
- */
183
- private recordFailure;
184
- /** Replay buffered lines in order; the head stays queued until its write succeeds. */
185
- private drainPending;
186
- private writeLine;
187
- private ensureDir;
188
- /** Cached line/byte counters, loaded (and repaired) from disk on first use. */
189
- private stateFor;
190
- private rotateIfFull;
191
- private syncIfDue;
192
- private syncDirty;
193
- private syncSession;
194
- private shardPath;
195
- /** Encoded shard base names present under `receipts/`, sorted. */
196
- private listShardNames;
197
- }
198
- export {};
@@ -1,117 +0,0 @@
1
- /**
2
- * Scope document model: where the plugin is allowed to act.
3
- *
4
- * `scope.json` is the single source of truth for the exposure surface (design
5
- * §5.5). This module only parses an already-read value; it never touches the
6
- * filesystem. Task 9's store owns reading, locking and writing.
7
- *
8
- * The input is the JSON-decoded value `JSON.parse` produces for `scope.json`,
9
- * not an arbitrary host object: exotic in-memory shapes (throwing getters,
10
- * inherited fields) are outside the contract and are not defended against.
11
- *
12
- * Parsing is fail-closed in three ordered stages. **Type delimitation runs
13
- * before the version checks**: a non-object, `null` or an array is a parse
14
- * failure even when it carries a `version` property. Then a numeric `version`
15
- * greater than `2` is a **future version**: it is a valid document written by a
16
- * newer plugin, so reads degrade but writes must never rewrite it (the field
17
- * set may be newer than this parser knows). Finally anything whose `version` is
18
- * not exactly `2` — version 1, a missing or non-numeric version — is an
19
- * **unknown version**; a version 1 document is the one upgradeable case, and
20
- * the command decides when to upgrade it.
21
- *
22
- * A matching stage rejects immediately, and no failure returns a partial
23
- * document: every failure comes back as a fresh deep copy of `DEFAULT_SCOPE`,
24
- * the strictest exposure (`selected + []`), so a malformed or newer-versioned
25
- * file degrades to "nobody sees it" rather than crashing the agent.
26
- *
27
- * Individual fields are guarded on the strict side too: an unknown `mode` is
28
- * `'selected'`, a non-array `workspaceIds` is `[]`, non-string members are
29
- * dropped, a non-boolean `shadow` is `true`, an unknown `projection` is
30
- * `'shadow'`, and a non-finite `revision` is `0`. `updatedAt` is never
31
- * validated beyond being a string.
32
- *
33
- * @module dsh-boost/scope/doc
34
- */
35
- import type { ProjectionMode } from '../projection/apply.js';
36
- /** Stable rejection code: the file names a version this parser does not know. */
37
- export declare const ERR_SCOPE_UNKNOWN_VERSION = "ERR_SCOPE_UNKNOWN_VERSION";
38
- /**
39
- * Stable rejection code: the file's version is a number newer than this parser
40
- * (version 3+). Reads degrade like any other failure, but the document is
41
- * **read-only**: it may carry fields and workspace ids this parser would prune,
42
- * so writing it back would silently lose the user's configuration.
43
- */
44
- export declare const ERR_SCOPE_FUTURE_VERSION = "ERR_SCOPE_FUTURE_VERSION";
45
- /** Stable rejection code: the file is not a scope document at all. */
46
- export declare const ERR_SCOPE_PARSE_FAILED = "ERR_SCOPE_PARSE_FAILED";
47
- /** Stable rejection code: the file exists but could not be read. */
48
- export declare const ERR_SCOPE_READ_FAILED = "ERR_SCOPE_READ_FAILED";
49
- /** Stable rejection code: the write's base revision is stale. */
50
- export declare const ERR_SCOPE_REVISION_CONFLICT = "ERR_SCOPE_REVISION_CONFLICT";
51
- /** Stable rejection code: another writer holds the scope lock. */
52
- export declare const ERR_SCOPE_LOCKED = "ERR_SCOPE_LOCKED";
53
- /**
54
- * Stable rejection code: the write was cancelled through its `AbortSignal`.
55
- *
56
- * Checked at every await boundary of the write path. A cancellation is not a
57
- * storage failure — the file is left exactly as it was — so the caller can
58
- * report it without implying the scope is damaged.
59
- */
60
- export declare const ERR_SCOPE_ABORTED = "ERR_SCOPE_ABORTED";
61
- /** Every stable scope failure code (design §5.5 plus the future-version split). */
62
- export type ScopeCode = typeof ERR_SCOPE_UNKNOWN_VERSION | typeof ERR_SCOPE_FUTURE_VERSION | typeof ERR_SCOPE_PARSE_FAILED | typeof ERR_SCOPE_READ_FAILED | typeof ERR_SCOPE_REVISION_CONFLICT | typeof ERR_SCOPE_LOCKED | typeof ERR_SCOPE_ABORTED;
63
- /** A parsed `scope.json` document, version 2 (design §5.5). */
64
- export interface ScopeDoc {
65
- version: 2;
66
- /** Incremented by the store on every successful write. */
67
- revision: number;
68
- /** Last write time, when the store recorded one; never validated further. */
69
- updatedAt?: string;
70
- mode: 'selected' | 'global';
71
- workspaceIds: string[];
72
- /** Shadow accounting switch (`boost shadow on|off`). */
73
- shadow: boolean;
74
- /** Projection shape: off, accounting only, or real replacement. */
75
- projection: ProjectionMode;
76
- }
77
- /**
78
- * The strictest exposure and the fallback for every failure: nobody sees the
79
- * plugin until the user opts in.
80
- */
81
- export declare const DEFAULT_SCOPE: ScopeDoc;
82
- /**
83
- * Read one `scope.json` value, as produced by `JSON.parse`.
84
- *
85
- * A value whose type or version is wrong is rejected with a stable code and a
86
- * deep copy of `DEFAULT_SCOPE`; a version 2 object yields a complete document
87
- * built from its fields, with every malformed field degraded to its strict
88
- * value.
89
- */
90
- export declare function parseScope(raw: unknown): {
91
- doc: ScopeDoc;
92
- code?: 'ERR_SCOPE_UNKNOWN_VERSION' | 'ERR_SCOPE_FUTURE_VERSION' | 'ERR_SCOPE_PARSE_FAILED';
93
- };
94
- /**
95
- * The upgrade base for a version 1 document.
96
- *
97
- * Reading a v1 file still degrades to {@link DEFAULT_SCOPE} and reports
98
- * {@link ERR_SCOPE_UNKNOWN_VERSION} (design §5.5 rule 3: unknown versions are
99
- * read-only). Only the explicit `scope-set` upgrade may rewrite it, and this
100
- * function answers "what did the user's v1 file actually say" for that one
101
- * write: `version` becomes 2 and `revision` starts at the degraded read's 0,
102
- * while every recognised field keeps its value (strict side for malformed
103
- * ones). Never use this on the read path — a v1 document is not a valid v2
104
- * document and must keep presenting as invisible until upgraded.
105
- *
106
- * `undefined` for anything that is not a plain object with `version === 1`,
107
- * including v2, future versions, missing versions and non-objects.
108
- */
109
- export declare function parseVersionOneScope(raw: unknown): ScopeDoc | undefined;
110
- /**
111
- * Whether the plugin may act for an agent in `workspaceId`.
112
- *
113
- * An agent with no workspace has the global view, and the plugin never injects
114
- * into the global view (design §5.5), so `undefined` is always invisible.
115
- * `mode: 'global'` widens to any *defined* workspace id, not to `undefined`.
116
- */
117
- export declare function isVisible(doc: ScopeDoc, workspaceId: string | undefined): boolean;
@@ -1,91 +0,0 @@
1
- import type { ScopeStore } from './store.js';
2
- /**
3
- * The host's workspace registry.
4
- *
5
- * The host exposes only the synchronous `list()` and the asynchronous
6
- * `resolveByPath()`; there is no `byPath`. `workspaceIdOf` uses `list()`
7
- * exclusively so it can stay synchronous. `resolveByPath` is optional here
8
- * because a test double need not provide the pre-warm path.
9
- */
10
- export interface WorkspaceRegistry {
11
- list(): readonly {
12
- id: string;
13
- path: string;
14
- }[];
15
- resolveByPath?(path: string): Promise<{
16
- id: string;
17
- } | undefined>;
18
- }
19
- /**
20
- * The agent shape this module reads.
21
- *
22
- * Looser than `AgentLike`: the brief's tests pass agents without an `id` (and
23
- * `resolveVisible` passes `unknown`), so the header is optional here.
24
- */
25
- type AgentWithCwd = {
26
- session?: {
27
- header?: {
28
- cwd?: string;
29
- };
30
- };
31
- };
32
- /**
33
- * Resolve the host workspace UUID for an agent's cwd.
34
- *
35
- * The cwd is matched against `registry.list()` by exact `path` equality, so
36
- * `/w/a` does not match a workspace at `/w/ab` (or at `/w/a/`). This is the
37
- * **synchronous fallback** for a registry without `resolveByPath`; the async
38
- * {@link workspaceIdFor} is the production path because `Workspace.path` is a
39
- * canonical realpath while `Session.header.cwd` is only guaranteed absolute.
40
- * Any missing or malformed link in the chain — no agent, no session, a
41
- * non-string cwd, no registry, a `list()` that is not an array, throws, or
42
- * contains non-object entries — yields `undefined`, which `isVisible` treats as
43
- * invisible. This function never throws, even when called outside
44
- * `resolveVisible`.
45
- */
46
- export declare function workspaceIdOf(agent: AgentWithCwd | undefined, registry: WorkspaceRegistry | undefined): string | undefined;
47
- /**
48
- * Resolve the workspace UUID, preferring the host's canonical lookup.
49
- *
50
- * `Workspace.path` is the canonical realpath (`dsh-workspace/src/types.ts`),
51
- * while `Session.header.cwd` is only guaranteed absolute
52
- * (`dsh-session/src/index.ts`), so a symlinked cwd or one with a trailing
53
- * slash never matches byte-for-byte. `resolveByPath` is the registry's
54
- * canonical resolver and is used whenever it exists; its `undefined` answer is
55
- * authoritative (the workspace is not registered), while a registry without it
56
- * falls back to the synchronous exact match. A throwing resolver is a
57
- * resolution failure and fails closed (`undefined` -> invisible), never a
58
- * crash and never a silent exact-match second guess.
59
- *
60
- * Never throws.
61
- */
62
- export declare function workspaceIdFor(agent: AgentWithCwd | undefined, registry: WorkspaceRegistry | undefined): Promise<string | undefined>;
63
- /**
64
- * Visibility plus the workspace id the judgement was made against.
65
- *
66
- * `resolveVisible` is the boolean projection of this result. `apply` also needs
67
- * the id: the stream hook's `resolveSession` map must carry the same canonical
68
- * workspace id the judgement used, or a symlinked cwd would be judged visible
69
- * and then refused by the substitution path.
70
- */
71
- export declare function resolveWorkspace(store: ScopeStore, agent: unknown, registry: WorkspaceRegistry | undefined): Promise<{
72
- visible: boolean;
73
- workspaceId?: string;
74
- }>;
75
- /**
76
- * Whether the plugin may act for `agent`, caching the judgement for the
77
- * synchronous prompt provider.
78
- *
79
- * Never throws: a degraded read, a throwing registry, or a malformed `list()`
80
- * all resolve to `false`. When the agent has a session id the result (including
81
- * a failure's `false`) is written with `store.remember` before returning, so a
82
- * subsequent synchronous `judgement(key)` sees the same answer.
83
- *
84
- * A degraded store read (missing, unreadable, corrupt or newer-versioned
85
- * `scope.json`) is a *definitive* `false` for this resolution, not an unknown:
86
- * it is cached like any other judgement. It is not sticky — the next
87
- * `resolveVisible` call re-reads the store and overwrites the same key, so a
88
- * repaired scope document self-heals the cache on the following resolution.
89
- */
90
- export declare function resolveVisible(store: ScopeStore, agent: unknown, registry: WorkspaceRegistry | undefined): Promise<boolean>;
91
- export {};
@@ -1,135 +0,0 @@
1
- import type { ScopeCode, ScopeDoc } from './doc.js';
2
- /** Stable code logged when a live-pid lock is reclaimed on age alone. */
3
- export declare const ERR_SCOPE_LOCK_TAKEOVER = "ERR_SCOPE_LOCK_TAKEOVER";
4
- /** Test seam and operator hook for the lock's time-based takeover. */
5
- export interface ScopeStoreOptions {
6
- /** Age after which a live-pid lock is ignored (defaults to ten dead-pid timeouts). */
7
- lockTakeoverMs?: number;
8
- /** Age after which a dead-pid lock is reclaimable (defaults to 60 s). */
9
- lockStaleMs?: number;
10
- /** Clock, injectable so tests do not sleep. */
11
- now?: () => number;
12
- /** Sink for the takeover warning; defaults to a process warning. */
13
- warn?: (message: string) => void;
14
- }
15
- export declare class ScopeStore {
16
- private readonly dir;
17
- private readonly file;
18
- private readonly lockFile;
19
- private readonly lockStaleMs;
20
- private readonly lockTakeoverMs;
21
- private readonly now;
22
- private readonly warn;
23
- private cached?;
24
- private lockOwner?;
25
- private readonly judgements;
26
- constructor(dir: string, options?: ScopeStoreOptions);
27
- /**
28
- * Read the current document. Never throws and never writes: every stat,
29
- * read, JSON or shape failure comes back as a fresh `DEFAULT_SCOPE` plus
30
- * `degraded: 'scope-degraded'` and the stable code.
31
- */
32
- read(): Promise<{
33
- doc: ScopeDoc;
34
- degraded?: 'scope-degraded';
35
- code?: ScopeCode;
36
- }>;
37
- /**
38
- * Compare-and-swap write. Returns the new document (revision `baseRevision + 1`,
39
- * `updatedAt` now) and leaves it cached.
40
- *
41
- * A missing file is a first write: the base is `DEFAULT_SCOPE` at revision 0,
42
- * so it succeeds only when the caller passes 0. A corrupt or version 1 file
43
- * is also based on the strict default, which is how `boost scope set`
44
- * explicitly upgrades a version 1 document. A **future** version (a numeric
45
- * version greater than 2) is refused with `ERR_SCOPE_FUTURE_VERSION` before
46
- * the mutation: the newer field set cannot be represented here, so rewriting
47
- * it would silently drop configuration. An existing file that cannot be read
48
- * at all is `ERR_SCOPE_READ_FAILED` — never overwritten blindly.
49
- */
50
- write(mutate: (doc: ScopeDoc) => ScopeDoc, baseRevision: number, options?: {
51
- signal?: AbortSignal;
52
- }): Promise<ScopeDoc>;
53
- /** Cache one agent's visibility judgement; the only writer of this cache. */
54
- remember(key: string, visible: boolean): void;
55
- /**
56
- * Drop one session's cached judgement on session disposal.
57
- *
58
- * The judgement map is per session and otherwise lives as long as the plugin;
59
- * without this a process that served many sessions would retain one boolean
60
- * (and its string key) per session forever.
61
- */
62
- forget(key: string): void;
63
- /** Synchronous per-agent lookup: a miss is `fallback`, and fail-closed is `false`. */
64
- judgement(key: string, fallback?: boolean): boolean;
65
- /** Async read path: stat + read + decode, all failures degraded. */
66
- private readDisk;
67
- /**
68
- * Reuse the previous parse only when the exact bytes and mtime were already
69
- * parsed. Byte identity is a stronger key than mtime+revision: an external
70
- * edit that keeps both cannot be served from the old parse.
71
- */
72
- private decodeFromCache;
73
- /** Sync read path, used only inside the write lock (see the module comment). */
74
- private readDiskSync;
75
- /** The write path must be able to create `<root>/boost` on a fresh install. */
76
- private ensureDirectory;
77
- /**
78
- * Take the write lock, reclaiming a stale lock at most once.
79
- *
80
- * Two independent staleness rules:
81
- *
82
- * 1. dead-owner reclaim — older than `lockStaleMs` **and** the recorded pid is
83
- * dead (or unrecorded/unparseable/out of pid range);
84
- * 2. bounded takeover — the lock's `startedAt` (falling back to mtime) is
85
- * older than `lockTakeoverMs`, **even when its pid is alive**. A pid is
86
- * reused after a crash, so rule 1 alone can leave `scope.lock` held for the
87
- * whole process lifetime in a container. The hold window is one small
88
- * synchronous write, so a lock this old is a crashed writer.
89
- *
90
- * The takeover re-reads the lock immediately before unlinking and refuses if
91
- * its bytes or mtime changed, which narrows the cross-process race. Two
92
- * writers can still judge the same lock stale; `releaseLock` only removes a
93
- * lock whose content it wrote, and the CAS revision check still refuses to
94
- * merge divergent writes, so the residual race cannot corrupt the document.
95
- *
96
- * When that first read finds **no** lock there is nothing to compare against,
97
- * so the reclaim is refused with `ERR_SCOPE_LOCKED`. `createLock` already saw
98
- * the file exist; a lock created between that failure and the read is
99
- * indistinguishable from one a live writer still owns, and unlinking it
100
- * would lose that writer's update. Refusing is safe (the caller retries) and
101
- * the alternative is the one case the changed-lock guard cannot cover.
102
- */
103
- private acquireLock;
104
- /** `open(lock, 'wx')`; false means another writer holds it. */
105
- private createLock;
106
- /**
107
- * One read of the lock: bytes, mtime and the owner fields they record.
108
- *
109
- * `undefined` means absent (the `EEXIST` raced a release): the caller may
110
- * retry the create. An unreadable-but-present lock is returned with the mtime
111
- * and no owner fields, so it becomes reclaimable only after the dead-pid
112
- * timeout — never immediately, because an unreadable live lock must not be
113
- * evicted on a guess.
114
- */
115
- private readLock;
116
- /** Age from `startedAt` when it is usable, otherwise from the file's mtime. */
117
- private ageOf;
118
- /** Whether the lock is reclaimable, and whether that decision needs a warning. */
119
- private classifyLock;
120
- /**
121
- * Remove the lock only if it still contains exactly what this acquisition
122
- * wrote. An unconditional unlink would delete a replacement lock another
123
- * writer created after a stale-reclaim race. Every error is swallowed:
124
- * cleanup must never mask the causal error (rule 8), and a lock left behind
125
- * is reclaimable after 60 s while a masked conflict is not diagnosable.
126
- */
127
- private releaseLock;
128
- /**
129
- * Serialize `doc` into a temporary file, fsync it, and rename it over
130
- * `scope.json`. Returns the stored file's mtime and the exact text written
131
- * (for the cache). A failed write removes the temporary file; the caller's
132
- * `finally` removes the lock.
133
- */
134
- private writeAtomic;
135
- }