dsh-boost 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +476 -0
- package/README.md +408 -2
- package/cordis.patch.yml +40 -0
- package/dist/admission/fixed-cost.d.ts +23 -0
- package/dist/admission/fixed-cost.js +61 -0
- package/dist/admission/fixed-cost.js.map +1 -0
- package/dist/admission/ledger.d.ts +113 -0
- package/dist/admission/ledger.js +176 -0
- package/dist/admission/ledger.js.map +1 -0
- package/dist/admission/retrieval.d.ts +65 -0
- package/dist/admission/retrieval.js +162 -0
- package/dist/admission/retrieval.js.map +1 -0
- package/dist/admission/usage.d.ts +75 -0
- package/dist/admission/usage.js +124 -0
- package/dist/admission/usage.js.map +1 -0
- package/dist/config.d.ts +43 -0
- package/dist/config.js +103 -0
- package/dist/config.js.map +1 -0
- package/dist/gate/binding.d.ts +113 -0
- package/dist/gate/binding.js +297 -0
- package/dist/gate/binding.js.map +1 -0
- package/dist/gate/decide.d.ts +82 -0
- package/dist/gate/decide.js +163 -0
- package/dist/gate/decide.js.map +1 -0
- package/dist/gate/guard.d.ts +69 -0
- package/dist/gate/guard.js +195 -0
- package/dist/gate/guard.js.map +1 -0
- package/dist/gate/invalidate.d.ts +112 -0
- package/dist/gate/invalidate.js +111 -0
- package/dist/gate/invalidate.js.map +1 -0
- package/dist/gate/plan.d.ts +86 -0
- package/dist/gate/plan.js +222 -0
- package/dist/gate/plan.js.map +1 -0
- package/dist/hooks/clock.d.ts +68 -0
- package/dist/hooks/clock.js +82 -0
- package/dist/hooks/clock.js.map +1 -0
- package/dist/hooks/execute.d.ts +79 -0
- package/dist/hooks/execute.js +128 -0
- package/dist/hooks/execute.js.map +1 -0
- package/dist/hooks/llm-stream.d.ts +276 -0
- package/dist/hooks/llm-stream.js +1008 -0
- package/dist/hooks/llm-stream.js.map +1 -0
- package/dist/hooks/pending.d.ts +89 -0
- package/dist/hooks/pending.js +115 -0
- package/dist/hooks/pending.js.map +1 -0
- package/dist/hooks/post-execute.d.ts +247 -0
- package/dist/hooks/post-execute.js +1776 -0
- package/dist/hooks/post-execute.js.map +1 -0
- package/dist/hooks/session-state.d.ts +158 -0
- package/dist/hooks/session-state.js +168 -0
- package/dist/hooks/session-state.js.map +1 -0
- package/dist/hooks/synthesize.d.ts +74 -0
- package/dist/hooks/synthesize.js +100 -0
- package/dist/hooks/synthesize.js.map +1 -0
- package/dist/host/loader.d.ts +23 -0
- package/dist/host/loader.js +31 -0
- package/dist/host/loader.js.map +1 -0
- package/dist/host/platform.d.ts +18 -0
- package/dist/host/platform.js +19 -0
- package/dist/host/platform.js.map +1 -0
- package/dist/host/root.d.ts +18 -0
- package/dist/host/root.js +43 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +866 -0
- package/dist/index.js.map +1 -0
- package/dist/projection/apply.d.ts +174 -0
- package/dist/projection/apply.js +137 -0
- package/dist/projection/apply.js.map +1 -0
- package/dist/projection/canonicalise.d.ts +43 -0
- package/dist/projection/canonicalise.js +43 -0
- package/dist/projection/canonicalise.js.map +1 -0
- package/dist/projection/counters.d.ts +65 -0
- package/dist/projection/counters.js +88 -0
- package/dist/projection/counters.js.map +1 -0
- package/dist/projection/truncate.d.ts +47 -0
- package/dist/projection/truncate.js +57 -0
- package/dist/projection/truncate.js.map +1 -0
- package/dist/prompt/protocol.d.ts +45 -0
- package/dist/prompt/protocol.js +56 -0
- package/dist/prompt/protocol.js.map +1 -0
- package/dist/receipts/store.d.ts +198 -0
- package/dist/receipts/store.js +734 -0
- package/dist/receipts/store.js.map +1 -0
- package/dist/scope/doc.d.ts +117 -0
- package/dist/scope/doc.js +158 -0
- package/dist/scope/doc.js.map +1 -0
- package/dist/scope/resolve.d.ts +91 -0
- package/dist/scope/resolve.js +146 -0
- package/dist/scope/resolve.js.map +1 -0
- package/dist/scope/store.d.ts +135 -0
- package/dist/scope/store.js +573 -0
- package/dist/scope/store.js.map +1 -0
- package/dist/selector/jev.d.ts +93 -0
- package/dist/selector/jev.js +171 -0
- package/dist/selector/jev.js.map +1 -0
- package/dist/tools/boost.d.ts +367 -0
- package/dist/tools/boost.js +768 -0
- package/dist/tools/boost.js.map +1 -0
- package/dist/tools/family.d.ts +26 -0
- package/dist/tools/family.js +26 -0
- package/dist/tools/family.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.js +21 -0
- package/dist/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +75 -4
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Projection skip observability.
|
|
3
|
+
*
|
|
4
|
+
* A tool with no configured family returns its receipt unchanged, which is the
|
|
5
|
+
* correct policy for `web_fetch`/`edit` and a silent mapping failure for a
|
|
6
|
+
* decorated tool such as a new `mcp__ssh__*`. Both used to look identical from
|
|
7
|
+
* `boost status` ("nothing projected"), so the operator could not tell "not
|
|
8
|
+
* worth it" from "your tool is invisible to the mapper".
|
|
9
|
+
*
|
|
10
|
+
* The counter is deliberately cheap and bounded: two integers plus at most
|
|
11
|
+
* {@link MAX_TRACKED_TOOLS} names. It counts calls that reached the projection
|
|
12
|
+
* stage with a text receipt and no family; it is not a per-tool ledger. The
|
|
13
|
+
* prompt-suppression count is the same shape, for the same reason: assembly
|
|
14
|
+
* runs on every request, so only a number may be kept.
|
|
15
|
+
*
|
|
16
|
+
* @module dsh-boost/projection/counters
|
|
17
|
+
*/
|
|
18
|
+
/** Process-wide projection counters, owned by `apply` and read by `status`. */
|
|
19
|
+
export declare class ProjectionCounters {
|
|
20
|
+
private unknownFamilyCount;
|
|
21
|
+
private readonly unknownTools;
|
|
22
|
+
private suppressedAssemblies;
|
|
23
|
+
private missingProtocols;
|
|
24
|
+
/**
|
|
25
|
+
* Count one **decorated** call (`mcp__*`) whose family is not configured.
|
|
26
|
+
*
|
|
27
|
+
* Only decorated names are counted. An undecorated non-family tool (`edit`,
|
|
28
|
+
* `web_fetch`, `todo_write`, or this plugin's own `boost`) is a by-design
|
|
29
|
+
* pass, not a mapper gap, and counting it would bury the gap that matters in
|
|
30
|
+
* noise the operator cannot separate out.
|
|
31
|
+
*
|
|
32
|
+
* `name` is optional because `exec.name` can be absent; the count still
|
|
33
|
+
* increments, and only a present name is retained for the tool list.
|
|
34
|
+
*/
|
|
35
|
+
unknownFamily(name: string | undefined): void;
|
|
36
|
+
/** Calls skipped because no projection family matched. */
|
|
37
|
+
unknownFamilies(): number;
|
|
38
|
+
/** The retained unmapped tool names and their call counts (a copy). */
|
|
39
|
+
unknownToolCounts(): Record<string, number>;
|
|
40
|
+
/**
|
|
41
|
+
* Count one prompt assembly whose protocol section was suppressed.
|
|
42
|
+
*
|
|
43
|
+
* `systemPrompt` assembly runs on every request, so design §5.5:378 requires
|
|
44
|
+
* a count and forbids a per-assembly receipt. Without the count, `status`
|
|
45
|
+
* cannot distinguish the shipped `selected + []` (correctly inert) from an
|
|
46
|
+
* assembly whose section failed to inject — the exact "inert looks identical
|
|
47
|
+
* to broken" failure the operator has no other signal for.
|
|
48
|
+
*/
|
|
49
|
+
protocolSuppressed(): void;
|
|
50
|
+
/** Prompt assemblies suppressed since load; read live by `boost status`. */
|
|
51
|
+
protocolSuppressions(): number;
|
|
52
|
+
/**
|
|
53
|
+
* Count one model request whose final system prompt lost the protocol
|
|
54
|
+
* section to a `complete: true` section.
|
|
55
|
+
*
|
|
56
|
+
* Distinct from {@link protocolSuppressed}: that counter includes correctly
|
|
57
|
+
* invisible workspaces, while this one means the plugin judged the workspace
|
|
58
|
+
* visible and still could not teach the model the plan grammar. It is the
|
|
59
|
+
* operator's only signal that the prompt belongs to another plugin (review
|
|
60
|
+
* row 12), and it drives the stable `ERR_HOST_COMPLETE_SECTION` code.
|
|
61
|
+
*/
|
|
62
|
+
protocolMissing(): void;
|
|
63
|
+
/** Model requests that lost the protocol section since load. */
|
|
64
|
+
protocolMissings(): number;
|
|
65
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Projection skip observability.
|
|
3
|
+
*
|
|
4
|
+
* A tool with no configured family returns its receipt unchanged, which is the
|
|
5
|
+
* correct policy for `web_fetch`/`edit` and a silent mapping failure for a
|
|
6
|
+
* decorated tool such as a new `mcp__ssh__*`. Both used to look identical from
|
|
7
|
+
* `boost status` ("nothing projected"), so the operator could not tell "not
|
|
8
|
+
* worth it" from "your tool is invisible to the mapper".
|
|
9
|
+
*
|
|
10
|
+
* The counter is deliberately cheap and bounded: two integers plus at most
|
|
11
|
+
* {@link MAX_TRACKED_TOOLS} names. It counts calls that reached the projection
|
|
12
|
+
* stage with a text receipt and no family; it is not a per-tool ledger. The
|
|
13
|
+
* prompt-suppression count is the same shape, for the same reason: assembly
|
|
14
|
+
* runs on every request, so only a number may be kept.
|
|
15
|
+
*
|
|
16
|
+
* @module dsh-boost/projection/counters
|
|
17
|
+
*/
|
|
18
|
+
/** Bound on distinct unmapped tool names retained for status. */
|
|
19
|
+
const MAX_TRACKED_TOOLS = 32;
|
|
20
|
+
/** Process-wide projection counters, owned by `apply` and read by `status`. */
|
|
21
|
+
export class ProjectionCounters {
|
|
22
|
+
unknownFamilyCount = 0;
|
|
23
|
+
unknownTools = new Map();
|
|
24
|
+
suppressedAssemblies = 0;
|
|
25
|
+
missingProtocols = 0;
|
|
26
|
+
/**
|
|
27
|
+
* Count one **decorated** call (`mcp__*`) whose family is not configured.
|
|
28
|
+
*
|
|
29
|
+
* Only decorated names are counted. An undecorated non-family tool (`edit`,
|
|
30
|
+
* `web_fetch`, `todo_write`, or this plugin's own `boost`) is a by-design
|
|
31
|
+
* pass, not a mapper gap, and counting it would bury the gap that matters in
|
|
32
|
+
* noise the operator cannot separate out.
|
|
33
|
+
*
|
|
34
|
+
* `name` is optional because `exec.name` can be absent; the count still
|
|
35
|
+
* increments, and only a present name is retained for the tool list.
|
|
36
|
+
*/
|
|
37
|
+
unknownFamily(name) {
|
|
38
|
+
this.unknownFamilyCount += 1;
|
|
39
|
+
if (typeof name !== 'string' || name === '')
|
|
40
|
+
return;
|
|
41
|
+
const seen = this.unknownTools.get(name) ?? 0;
|
|
42
|
+
if (seen === 0 && this.unknownTools.size >= MAX_TRACKED_TOOLS)
|
|
43
|
+
return;
|
|
44
|
+
this.unknownTools.set(name, seen + 1);
|
|
45
|
+
}
|
|
46
|
+
/** Calls skipped because no projection family matched. */
|
|
47
|
+
unknownFamilies() {
|
|
48
|
+
return this.unknownFamilyCount;
|
|
49
|
+
}
|
|
50
|
+
/** The retained unmapped tool names and their call counts (a copy). */
|
|
51
|
+
unknownToolCounts() {
|
|
52
|
+
return Object.fromEntries(this.unknownTools);
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Count one prompt assembly whose protocol section was suppressed.
|
|
56
|
+
*
|
|
57
|
+
* `systemPrompt` assembly runs on every request, so design §5.5:378 requires
|
|
58
|
+
* a count and forbids a per-assembly receipt. Without the count, `status`
|
|
59
|
+
* cannot distinguish the shipped `selected + []` (correctly inert) from an
|
|
60
|
+
* assembly whose section failed to inject — the exact "inert looks identical
|
|
61
|
+
* to broken" failure the operator has no other signal for.
|
|
62
|
+
*/
|
|
63
|
+
protocolSuppressed() {
|
|
64
|
+
this.suppressedAssemblies += 1;
|
|
65
|
+
}
|
|
66
|
+
/** Prompt assemblies suppressed since load; read live by `boost status`. */
|
|
67
|
+
protocolSuppressions() {
|
|
68
|
+
return this.suppressedAssemblies;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Count one model request whose final system prompt lost the protocol
|
|
72
|
+
* section to a `complete: true` section.
|
|
73
|
+
*
|
|
74
|
+
* Distinct from {@link protocolSuppressed}: that counter includes correctly
|
|
75
|
+
* invisible workspaces, while this one means the plugin judged the workspace
|
|
76
|
+
* visible and still could not teach the model the plan grammar. It is the
|
|
77
|
+
* operator's only signal that the prompt belongs to another plugin (review
|
|
78
|
+
* row 12), and it drives the stable `ERR_HOST_COMPLETE_SECTION` code.
|
|
79
|
+
*/
|
|
80
|
+
protocolMissing() {
|
|
81
|
+
this.missingProtocols += 1;
|
|
82
|
+
}
|
|
83
|
+
/** Model requests that lost the protocol section since load. */
|
|
84
|
+
protocolMissings() {
|
|
85
|
+
return this.missingProtocols;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
//# sourceMappingURL=counters.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"counters.js","sourceRoot":"","sources":["../../src/projection/counters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iEAAiE;AACjE,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAE5B,+EAA+E;AAC/E,MAAM,OAAO,kBAAkB;IACrB,kBAAkB,GAAG,CAAC,CAAA;IACb,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAA;IACjD,oBAAoB,GAAG,CAAC,CAAA;IACxB,gBAAgB,GAAG,CAAC,CAAA;IAE5B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,IAAwB;QACpC,IAAI,CAAC,kBAAkB,IAAI,CAAC,CAAA;QAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;YAAE,OAAM;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7C,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,IAAI,iBAAiB;YAAE,OAAM;QACrE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,0DAA0D;IAC1D,eAAe;QACb,OAAO,IAAI,CAAC,kBAAkB,CAAA;IAChC,CAAC;IAED,uEAAuE;IACvE,iBAAiB;QACf,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;;;;OAQG;IACH,kBAAkB;QAChB,IAAI,CAAC,oBAAoB,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,4EAA4E;IAC5E,oBAAoB;QAClB,OAAO,IAAI,CAAC,oBAAoB,CAAA;IAClC,CAAC;IAED;;;;;;;;;OASG;IACH,eAAe;QACb,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED,gEAAgE;IAChE,gBAAgB;QACd,OAAO,IAAI,CAAC,gBAAgB,CAAA;IAC9B,CAAC;CACF","sourcesContent":["/**\n * Projection skip observability.\n *\n * A tool with no configured family returns its receipt unchanged, which is the\n * correct policy for `web_fetch`/`edit` and a silent mapping failure for a\n * decorated tool such as a new `mcp__ssh__*`. Both used to look identical from\n * `boost status` (\"nothing projected\"), so the operator could not tell \"not\n * worth it\" from \"your tool is invisible to the mapper\".\n *\n * The counter is deliberately cheap and bounded: two integers plus at most\n * {@link MAX_TRACKED_TOOLS} names. It counts calls that reached the projection\n * stage with a text receipt and no family; it is not a per-tool ledger. The\n * prompt-suppression count is the same shape, for the same reason: assembly\n * runs on every request, so only a number may be kept.\n *\n * @module dsh-boost/projection/counters\n */\n\n/** Bound on distinct unmapped tool names retained for status. */\nconst MAX_TRACKED_TOOLS = 32\n\n/** Process-wide projection counters, owned by `apply` and read by `status`. */\nexport class ProjectionCounters {\n private unknownFamilyCount = 0\n private readonly unknownTools = new Map<string, number>()\n private suppressedAssemblies = 0\n private missingProtocols = 0\n\n /**\n * Count one **decorated** call (`mcp__*`) whose family is not configured.\n *\n * Only decorated names are counted. An undecorated non-family tool (`edit`,\n * `web_fetch`, `todo_write`, or this plugin's own `boost`) is a by-design\n * pass, not a mapper gap, and counting it would bury the gap that matters in\n * noise the operator cannot separate out.\n *\n * `name` is optional because `exec.name` can be absent; the count still\n * increments, and only a present name is retained for the tool list.\n */\n unknownFamily(name: string | undefined): void {\n this.unknownFamilyCount += 1\n if (typeof name !== 'string' || name === '') return\n const seen = this.unknownTools.get(name) ?? 0\n if (seen === 0 && this.unknownTools.size >= MAX_TRACKED_TOOLS) return\n this.unknownTools.set(name, seen + 1)\n }\n\n /** Calls skipped because no projection family matched. */\n unknownFamilies(): number {\n return this.unknownFamilyCount\n }\n\n /** The retained unmapped tool names and their call counts (a copy). */\n unknownToolCounts(): Record<string, number> {\n return Object.fromEntries(this.unknownTools)\n }\n\n /**\n * Count one prompt assembly whose protocol section was suppressed.\n *\n * `systemPrompt` assembly runs on every request, so design §5.5:378 requires\n * a count and forbids a per-assembly receipt. Without the count, `status`\n * cannot distinguish the shipped `selected + []` (correctly inert) from an\n * assembly whose section failed to inject — the exact \"inert looks identical\n * to broken\" failure the operator has no other signal for.\n */\n protocolSuppressed(): void {\n this.suppressedAssemblies += 1\n }\n\n /** Prompt assemblies suppressed since load; read live by `boost status`. */\n protocolSuppressions(): number {\n return this.suppressedAssemblies\n }\n\n /**\n * Count one model request whose final system prompt lost the protocol\n * section to a `complete: true` section.\n *\n * Distinct from {@link protocolSuppressed}: that counter includes correctly\n * invisible workspaces, while this one means the plugin judged the workspace\n * visible and still could not teach the model the plan grammar. It is the\n * operator's only signal that the prompt belongs to another plugin (review\n * row 12), and it drives the stable `ERR_HOST_COMPLETE_SECTION` code.\n */\n protocolMissing(): void {\n this.missingProtocols += 1\n }\n\n /** Model requests that lost the protocol section since load. */\n protocolMissings(): number {\n return this.missingProtocols\n }\n}\n"]}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Receipt truncation: whether to cut, the two windows, and the head line.
|
|
3
|
+
*
|
|
4
|
+
* Lengths are counted in Unicode code points, never UTF-16 code units (design
|
|
5
|
+
* §5.4): a CJK or emoji receipt must be cut at the same visual length as an
|
|
6
|
+
* ASCII one, and slicing the code-point array is the only way never to split a
|
|
7
|
+
* surrogate pair. `text.length` appears only as a cheap pre-filter — it is an
|
|
8
|
+
* upper bound on the code-point count, so `text.length <= triggerChars` proves
|
|
9
|
+
* that no cut is due.
|
|
10
|
+
*
|
|
11
|
+
* `truncate` returns `null` when a cut is not worth it: when the receipt does
|
|
12
|
+
* not exceed the trigger, when its UTF-8 size exceeds the projection cap, or
|
|
13
|
+
* when the rendered replacement would not be shorter than the original. Every
|
|
14
|
+
* non-null result therefore satisfies `after.length < before.length`, which
|
|
15
|
+
* the shadow-mode accounting relies on.
|
|
16
|
+
*
|
|
17
|
+
* @module dsh-boost/projection/truncate
|
|
18
|
+
*/
|
|
19
|
+
import type { ProjectionParams } from '../types.js';
|
|
20
|
+
/** The two windows plus the facts later stages report and account for. */
|
|
21
|
+
export interface Truncation {
|
|
22
|
+
/** The original receipt text, byte for byte. */
|
|
23
|
+
before: string;
|
|
24
|
+
/** The rendered replacement: head line, then head, then tail. */
|
|
25
|
+
after: string;
|
|
26
|
+
/** First `headChars` code points of `before`. */
|
|
27
|
+
head: string;
|
|
28
|
+
/** Last `tailChars` code points of `before`. */
|
|
29
|
+
tail: string;
|
|
30
|
+
/** UTF-8 bytes of `before` that neither window carries. */
|
|
31
|
+
omittedBytes: number;
|
|
32
|
+
/** `before` code points minus the two window sizes. */
|
|
33
|
+
omittedCodePoints: number;
|
|
34
|
+
}
|
|
35
|
+
/** Render the head line of a truncation, with `en-US` thousands separators. */
|
|
36
|
+
export declare function renderHeadLine(truncation: Truncation): string;
|
|
37
|
+
/**
|
|
38
|
+
* Whether `truncate` would cut `text`.
|
|
39
|
+
*
|
|
40
|
+
* Delegates instead of re-deriving the decision, so the two entry points can
|
|
41
|
+
* never disagree at the edges (the exact cut, the net-gain guard, the byte
|
|
42
|
+
* cap). The cheap pre-filters inside `truncate` keep the common "not worth
|
|
43
|
+
* cutting" path free of code-point allocation.
|
|
44
|
+
*/
|
|
45
|
+
export declare function shouldTruncate(text: string, params: ProjectionParams): boolean;
|
|
46
|
+
/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */
|
|
47
|
+
export declare function truncate(text: string, params: ProjectionParams): Truncation | null;
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/** Receipts above this many UTF-8 bytes are never projected (design §5.4). */
|
|
2
|
+
const MAX_PROJECTED_BYTES = 256 * 1024;
|
|
3
|
+
/** Render the head line of a truncation, with `en-US` thousands separators. */
|
|
4
|
+
export function renderHeadLine(truncation) {
|
|
5
|
+
return headLine(Array.from(truncation.before).length, Array.from(truncation.head).length, Array.from(truncation.tail).length);
|
|
6
|
+
}
|
|
7
|
+
/** The one place the head line's literal format lives. */
|
|
8
|
+
function headLine(outputChars, firstChars, lastChars) {
|
|
9
|
+
return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Whether `truncate` would cut `text`.
|
|
13
|
+
*
|
|
14
|
+
* Delegates instead of re-deriving the decision, so the two entry points can
|
|
15
|
+
* never disagree at the edges (the exact cut, the net-gain guard, the byte
|
|
16
|
+
* cap). The cheap pre-filters inside `truncate` keep the common "not worth
|
|
17
|
+
* cutting" path free of code-point allocation.
|
|
18
|
+
*/
|
|
19
|
+
export function shouldTruncate(text, params) {
|
|
20
|
+
return truncate(text, params) !== null;
|
|
21
|
+
}
|
|
22
|
+
/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */
|
|
23
|
+
export function truncate(text, params) {
|
|
24
|
+
// UTF-16 length upper-bounds the code-point count: when it does not exceed
|
|
25
|
+
// the trigger, neither can the real count.
|
|
26
|
+
if (text.length <= params.triggerChars)
|
|
27
|
+
return null;
|
|
28
|
+
// Large receipts are not projected at all. The design's 256 KiB is a byte
|
|
29
|
+
// budget, so measure UTF-8 bytes rather than UTF-16 units — otherwise CJK
|
|
30
|
+
// and emoji receipts would overflow the budget by 2–4×.
|
|
31
|
+
const beforeBytes = Buffer.byteLength(text, 'utf8');
|
|
32
|
+
if (beforeBytes > MAX_PROJECTED_BYTES)
|
|
33
|
+
return null;
|
|
34
|
+
const codePoints = Array.from(text);
|
|
35
|
+
if (codePoints.length <= params.triggerChars)
|
|
36
|
+
return null;
|
|
37
|
+
// Slicing the code-point array cannot split a surrogate pair; string
|
|
38
|
+
// indexing could.
|
|
39
|
+
const head = codePoints.slice(0, params.headChars).join('');
|
|
40
|
+
// `slice(-0)` is `slice(0)`, i.e. the whole text: a configured zero tail must
|
|
41
|
+
// be no tail, not a duplicate of the receipt (review row 69).
|
|
42
|
+
const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('');
|
|
43
|
+
const omittedCodePoints = codePoints.length - params.headChars - params.tailChars;
|
|
44
|
+
const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8');
|
|
45
|
+
// The replacement this layer can render: the head line plus the two windows.
|
|
46
|
+
// The apply stage inserts the spill footer between the windows; that footer is
|
|
47
|
+
// not known here, so this is a lower bound on the final projected length.
|
|
48
|
+
const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length);
|
|
49
|
+
const after = `${header}\n${head}\n${tail}`;
|
|
50
|
+
// A cut that would not shrink the receipt (misconfigured windows, or windows
|
|
51
|
+
// that together swallow the whole text) is not worth taking; fall back to the
|
|
52
|
+
// original rather than throwing on unvalidated config.
|
|
53
|
+
if (after.length >= text.length)
|
|
54
|
+
return null;
|
|
55
|
+
return { before: text, after, head, tail, omittedBytes, omittedCodePoints };
|
|
56
|
+
}
|
|
57
|
+
//# sourceMappingURL=truncate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/projection/truncate.ts"],"names":[],"mappings":"AAoBA,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG,GAAG,GAAG,IAAI,CAAA;AAkBtC,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,UAAsB;IACnD,OAAO,QAAQ,CACb,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EACpC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,EAClC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CACnC,CAAA;AACH,CAAC;AAED,0DAA0D;AAC1D,SAAS,QAAQ,CAAC,WAAmB,EAAE,UAAkB,EAAE,SAAiB;IAC1E,OAAO,WAAW,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,yBAAyB,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,aAAa,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAA;AACnK,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAwB;IACnE,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,IAAI,CAAA;AACxC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,MAAwB;IAC7D,2EAA2E;IAC3E,2CAA2C;IAC3C,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IAEnD,0EAA0E;IAC1E,0EAA0E;IAC1E,wDAAwD;IACxD,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACnD,IAAI,WAAW,GAAG,mBAAmB;QAAE,OAAO,IAAI,CAAA;IAElD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,UAAU,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IAEzD,qEAAqE;IACrE,kBAAkB;IAClB,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC3D,8EAA8E;IAC9E,8DAA8D;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACvF,MAAM,iBAAiB,GAAG,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IACjF,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAEpG,6EAA6E;IAC7E,+EAA+E;IAC/E,0EAA0E;IAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAA;IAC5F,MAAM,KAAK,GAAG,GAAG,MAAM,KAAK,IAAI,KAAK,IAAI,EAAE,CAAA;IAC3C,6EAA6E;IAC7E,8EAA8E;IAC9E,uDAAuD;IACvD,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAE5C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAC7E,CAAC","sourcesContent":["/**\n * Receipt truncation: whether to cut, the two windows, and the head line.\n *\n * Lengths are counted in Unicode code points, never UTF-16 code units (design\n * §5.4): a CJK or emoji receipt must be cut at the same visual length as an\n * ASCII one, and slicing the code-point array is the only way never to split a\n * surrogate pair. `text.length` appears only as a cheap pre-filter — it is an\n * upper bound on the code-point count, so `text.length <= triggerChars` proves\n * that no cut is due.\n *\n * `truncate` returns `null` when a cut is not worth it: when the receipt does\n * not exceed the trigger, when its UTF-8 size exceeds the projection cap, or\n * when the rendered replacement would not be shorter than the original. Every\n * non-null result therefore satisfies `after.length < before.length`, which\n * the shadow-mode accounting relies on.\n *\n * @module dsh-boost/projection/truncate\n */\nimport type { ProjectionParams } from '../types.js'\n\n/** Receipts above this many UTF-8 bytes are never projected (design §5.4). */\nconst MAX_PROJECTED_BYTES = 256 * 1024\n\n/** The two windows plus the facts later stages report and account for. */\nexport interface Truncation {\n /** The original receipt text, byte for byte. */\n before: string\n /** The rendered replacement: head line, then head, then tail. */\n after: string\n /** First `headChars` code points of `before`. */\n head: string\n /** Last `tailChars` code points of `before`. */\n tail: string\n /** UTF-8 bytes of `before` that neither window carries. */\n omittedBytes: number\n /** `before` code points minus the two window sizes. */\n omittedCodePoints: number\n}\n\n/** Render the head line of a truncation, with `en-US` thousands separators. */\nexport function renderHeadLine(truncation: Truncation): string {\n return headLine(\n Array.from(truncation.before).length,\n Array.from(truncation.head).length,\n Array.from(truncation.tail).length,\n )\n}\n\n/** The one place the head line's literal format lives. */\nfunction headLine(outputChars: number, firstChars: number, lastChars: number): string {\n return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`\n}\n\n/**\n * Whether `truncate` would cut `text`.\n *\n * Delegates instead of re-deriving the decision, so the two entry points can\n * never disagree at the edges (the exact cut, the net-gain guard, the byte\n * cap). The cheap pre-filters inside `truncate` keep the common \"not worth\n * cutting\" path free of code-point allocation.\n */\nexport function shouldTruncate(text: string, params: ProjectionParams): boolean {\n return truncate(text, params) !== null\n}\n\n/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */\nexport function truncate(text: string, params: ProjectionParams): Truncation | null {\n // UTF-16 length upper-bounds the code-point count: when it does not exceed\n // the trigger, neither can the real count.\n if (text.length <= params.triggerChars) return null\n\n // Large receipts are not projected at all. The design's 256 KiB is a byte\n // budget, so measure UTF-8 bytes rather than UTF-16 units — otherwise CJK\n // and emoji receipts would overflow the budget by 2–4×.\n const beforeBytes = Buffer.byteLength(text, 'utf8')\n if (beforeBytes > MAX_PROJECTED_BYTES) return null\n\n const codePoints = Array.from(text)\n if (codePoints.length <= params.triggerChars) return null\n\n // Slicing the code-point array cannot split a surrogate pair; string\n // indexing could.\n const head = codePoints.slice(0, params.headChars).join('')\n // `slice(-0)` is `slice(0)`, i.e. the whole text: a configured zero tail must\n // be no tail, not a duplicate of the receipt (review row 69).\n const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('')\n const omittedCodePoints = codePoints.length - params.headChars - params.tailChars\n const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8')\n\n // The replacement this layer can render: the head line plus the two windows.\n // The apply stage inserts the spill footer between the windows; that footer is\n // not known here, so this is a lower bound on the final projected length.\n const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length)\n const after = `${header}\\n${head}\\n${tail}`\n // A cut that would not shrink the receipt (misconfigured windows, or windows\n // that together swallow the whole text) is not worth taking; fall back to the\n // original rather than throwing on unvalidated config.\n if (after.length >= text.length) return null\n\n return { before: text, after, head, tail, omittedBytes, omittedCodePoints }\n}\n"]}
|
|
@@ -0,0 +1,45 @@
|
|
|
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.";
|
|
@@ -0,0 +1,56 @@
|
|
|
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 const PROTOCOL_NAME = 'dsh-boost';
|
|
35
|
+
/** Section order: alongside the other tool-contract sections. */
|
|
36
|
+
export 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 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.
|
|
46
|
+
<CHISEL_PLAN>
|
|
47
|
+
{"goal":"g","steps":[{"id":"A","tool":"read","args":{"file_path":"/repo/b.ts"},"guards":[{"text_contains":"2 matches"}]}]}
|
|
48
|
+
</CHISEL_PLAN>
|
|
49
|
+
The guard reads the incoming receipt, which says "2 matches".
|
|
50
|
+
id:one capital A-Z, unique,max 26 steps.
|
|
51
|
+
args:object,not $public itself,depth<=64,no prototype keys,no $-key except $public.
|
|
52
|
+
guards:>=1 other than {"ok":true};each guard object has exactly one form key.
|
|
53
|
+
{"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.
|
|
54
|
+
Substituted:read, grep, glob;others run normally.
|
|
55
|
+
$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.`;
|
|
56
|
+
//# sourceMappingURL=protocol.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/prompt/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AAExC,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;qbAUwZ,CAAA","sourcesContent":["/**\n * The plan-protocol system prompt section.\n *\n * This module owns the literal text that teaches the model to write a\n * `<CHISEL_PLAN>` block: the block shape, the candidate-id rule, the `args`\n * restrictions, the `$public` template, the guard vocabulary and the tools\n * substitution covers. Nothing here parses or validates a plan —\n * `src/gate/plan.ts`, `src/gate/binding.ts`, `src/gate/guard.ts` and\n * `src/gate/decide.ts` are the authority, and the text agrees with them.\n *\n * The referent is the most load-bearing claim: `decide` evaluates every\n * candidate's guards against `receipts.get(stepId)` — the receipt that just\n * arrived — not against the candidate's own not-yet-existing result. With no\n * such receipt nothing is viable, and several candidates whose guards pass on\n * that one receipt are alternatives for the selector, not a queue. The text\n * states this before the example because a guard aimed at the candidate's own\n * output fails every time.\n *\n * `after:\"root\"` is taught because T23b keys the just-arrived receipt as\n * `root`; an earlier executed candidate's receipt is keyed by its id. `$scalar`\n * needs the whole receipt to be one token (a one-path glob); an identifier\n * needs un-numbered output (a line-start `X: \"value\"`), which read/grep do not\n * provide; a multi-line value must be typed literally. `$single` is accepted\n * by binding but has no producer among the read/grep/glob receipts, so it is\n * deliberately not taught.\n *\n * The section is registered with `interpolate: false`; the text is still kept\n * free of `{{` so a later relaxation of that flag cannot rewrite it. The budget\n * is 1500 characters; the test pins it because this text is a permanent cost.\n *\n * @module dsh-boost/prompt/protocol\n */\n\n/** Section name the protocol is registered under (design §5.3). */\nexport const PROTOCOL_NAME = 'dsh-boost'\n\n/** Section order: alongside the other tool-contract sections. */\nexport const PROTOCOL_ORDER = 100\n\n/**\n * The protocol section's body, injected verbatim.\n *\n * Order is what the model needs first: where the block goes and which one\n * counts, what the guards read, the example and the sentence that repeats its\n * operand, the literal `args` rules, the guard vocabulary, the substituted\n * tools, and finally `$public` with its two binding sources and its limits.\n */\nexport 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.`\n"]}
|
|
@@ -0,0 +1,198 @@
|
|
|
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 {};
|