@dsh-cc/input-budget 0.0.0-stage → 0.9.5
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 +201 -0
- package/README.i18n.yaml +6 -0
- package/README.md +98 -2
- package/README.zh.md +99 -0
- package/lib/classes.d.ts +56 -0
- package/lib/classes.d.ts.map +1 -0
- package/lib/classes.js +115 -0
- package/lib/classes.js.map +1 -0
- package/lib/core.d.ts +136 -0
- package/lib/core.d.ts.map +1 -0
- package/lib/core.js +307 -0
- package/lib/core.js.map +1 -0
- package/lib/index.d.ts +32 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +32 -0
- package/lib/index.js.map +1 -0
- package/lib/ledger.d.ts +74 -0
- package/lib/ledger.d.ts.map +1 -0
- package/lib/ledger.js +140 -0
- package/lib/ledger.js.map +1 -0
- package/lib/listener.d.ts +138 -0
- package/lib/listener.d.ts.map +1 -0
- package/lib/listener.js +266 -0
- package/lib/listener.js.map +1 -0
- package/lib/pipeline.d.ts +50 -0
- package/lib/pipeline.d.ts.map +1 -0
- package/lib/pipeline.js +48 -0
- package/lib/pipeline.js.map +1 -0
- package/lib/plugin.d.ts +22 -0
- package/lib/plugin.d.ts.map +1 -0
- package/lib/plugin.js +24 -0
- package/lib/plugin.js.map +1 -0
- package/lib/row.d.ts +51 -0
- package/lib/row.d.ts.map +1 -0
- package/lib/row.js +55 -0
- package/lib/row.js.map +1 -0
- package/lib/settings.d.ts +80 -0
- package/lib/settings.d.ts.map +1 -0
- package/lib/settings.js +172 -0
- package/lib/settings.js.map +1 -0
- package/package.json +42 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.i18n.yaml
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
|
2
|
+
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
|
3
|
+
# after editing either side, bring the other along and re-record with:
|
|
4
|
+
# pnpm check:readme --write
|
|
5
|
+
README.md: 242b846b54f4dd87b1e96ca9849ada1f3a6ceb74
|
|
6
|
+
README.zh.md: af391756484c17a895cda412d995c78ffc37f53c
|
package/README.md
CHANGED
|
@@ -1,3 +1,99 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @dsh-cc/input-budget
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
English | [中文](README.zh.md)
|
|
4
|
+
|
|
5
|
+
Per-step input budget governor for the context-engineering input-governance program: one outermost gate over the final `agent/pre-step` enter batch, arbitrating producer content by class and byte budget 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L53-L59〕. Three layers ship together: the pure core (`govern()` — a function of its arguments, so the whole algorithm is testable without a runtime), the `agent/pre-step` listener the preset's `input-budget` row mounts, and the row emission that persists one `GovernorRow` per gate invocation through `@dsh-cc/input-ledger` 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕. It ships observe-first: in observe mode the batch is returned untouched and only the decisions are recorded.
|
|
6
|
+
|
|
7
|
+
## Classes — explicit membership only
|
|
8
|
+
|
|
9
|
+
Membership is closed and explicit 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L61-L73〕. Anything unlisted — an unknown kind, a late plugin, an absent or empty `source.kind` — is `passthrough` **by construction**, so unenumerated producers are never trimmed and never deferred.
|
|
10
|
+
|
|
11
|
+
| class | kinds | policy |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `governance` | `turn-rules`, `edit-recovery-hint`, `completion-gate`, `permission-rules`, `agent-instructions`, `hooks-claude-code`, `compact-checkpoint`, `moa-escalation` | never trim, never defer; counted |
|
|
14
|
+
| `task` | `user`, `progress-rebuild`, `moa`, `subagent-settled`, `cc-subagent-children`, `vwa-evidence`, `cc-workflow-completion` | never trim, never defer; counted |
|
|
15
|
+
| `memory` | `memory` | trim/defer FIFO under `memory-budget-bytes` |
|
|
16
|
+
| `advisory` | `advisor`, `retry-attendant`, `compaction-micro`, `compaction-cost-gate` | trim/defer FIFO under `advisory-budget-bytes` |
|
|
17
|
+
| `passthrough` | `cc-shell-glue` (v1 hard rule), `command-preset`, `side-query`, `tool-web-fetch`, `tool-registry`, named harness kinds, everything else | never trim, never defer; counted |
|
|
18
|
+
|
|
19
|
+
`cc-shell-glue` sits in `passthrough` in v1 as an **algorithmic rule**, not an annotation: `mcpReadyNotice` commits its once-per-session latch *before* returning the notice, so any enforced trim, defer or oversize drop of a glue notice would be a silent one-shot miss 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L71-L71〕. `memory` and `advisory` are the only budgeted classes; a 12 KiB memory entry is judged against `memory-budget-bytes`, never against the advisory limit 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L67-L67〕〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L92-L92〕.
|
|
20
|
+
|
|
21
|
+
## Budget model (per enter batch)
|
|
22
|
+
|
|
23
|
+
1. Classify each message; compute per-class UTF-8 bytes (text blocks only — the same measurement `@dsh-cc/input-ledger` records, so the two row families agree byte for byte) 〔src:ws:docs/plans/2026-11-12-per-step-input-ledger.md#L82-L82〕.
|
|
24
|
+
2. `governance` / `task` / `passthrough`: never modified, never charged.
|
|
25
|
+
3. `memory`: while memory bytes exceed `memory-budget-bytes`, trim the oldest memory message (whole message, FIFO).
|
|
26
|
+
4. `advisory`: while advisory bytes exceed `advisory-budget-bytes`, trim the oldest advisory message.
|
|
27
|
+
5. Enter budget: if the batch total exceeds `enter-budget-bytes`, trim advisory (then memory) further. If the budget cannot be met within the trimmable classes, nothing further is trimmed, protected classes are untouched, and `hardOver` records the overflow 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L77-L83〕.
|
|
28
|
+
|
|
29
|
+
A trimmed message whose own bytes alone exceed its class budget is dropped `drop-oversize` immediately and never enqueued — defer-then-drop would record a deferral that could never succeed.
|
|
30
|
+
|
|
31
|
+
## Defer queue
|
|
32
|
+
|
|
33
|
+
Per-session backlog of `{ message, enqueuedAtSeq, lastOfferedSeq }`, all values in `gateSeq` units. `gateSeq` is a **monotonic per-session invocation counter** incremented on every gate call; `agent/pre-step`'s `step` is turn-local and is never used 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L75-L75〕. `govern()` receives the counter and returns the next one; the listener owns it per session.
|
|
34
|
+
|
|
35
|
+
Each invocation, in order 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L87-L95〕:
|
|
36
|
+
|
|
37
|
+
1. **Age** — entries with `gateSeq - enqueuedAtSeq > defer-ttl-steps` drop `drop-expired`.
|
|
38
|
+
2. **Backlog admission** — walk the backlog FIFO and admit the head while the entry's **own** class budget has room (memory entries against `memory-budget-bytes`, advisory against `advisory-budget-bytes`, with this invocation's already-admitted bytes as `used`). Admitted entries lead this step's batch.
|
|
39
|
+
3. **Fresh trim** — the budget model above; surviving-fresh trims append to the backlog tail.
|
|
40
|
+
|
|
41
|
+
`lastOfferedSeq` starts at `enqueuedAtSeq` and advances to the current `gateSeq` at the end of every invocation that evaluated the entry — admission, rejection and re-defer alike. TTL is bounded by invocation count, not admission count.
|
|
42
|
+
|
|
43
|
+
## Observe mode
|
|
44
|
+
|
|
45
|
+
`mode: 'observe'` runs the identical fresh-batch computation and records the same rows under `mode: 'observe'`, but returns the incoming batch untouched, keeps no defer queue, simulates no backlog and emits no `drop-expired` rows. `drop-oversize` *is* possible in observe, because it is a fresh-batch computation 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L97-L103〕. Because an observe invocation returns an empty backlog, an `observe → enforce` flip starts with an empty queue by construction — no cross-mode carryover.
|
|
46
|
+
|
|
47
|
+
## Wiring — listener, preset row, ledger emission
|
|
48
|
+
|
|
49
|
+
`registerGovernorListener(ctx)` registers one `agent/pre-step` listener with `{ prepend: true }`, so it runs **outermost** among the preset's pre-step rewriters and sees the final decision on the way back out; it is delegate-first (it awaits `next()` and then spreads the returned decision, replacing only the message batch) and it never throws into the waterfall 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L53-L59〕. The preset row `input-budget` in the shared preset body mounts it through `apply()`, ordered after `tool-task` so the subagent strip-instructions/settled-notice pair stays inside the gate; the composition pin and the two live-fold ordering tests keep that boundary a tested property rather than an accident 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L57-L59〕.
|
|
50
|
+
|
|
51
|
+
Rows leave through `createGovernorLedgerSink()`: one content-free `GovernorRow` per gate invocation, appended to `$DSH_HOME/input-ledger/<projectKey>/<sessionId>.jsonl`, the same sink and path convention the ledger's own observers use (the project bucket is the first 16 hex chars of `sha256(realpath(cwd))`, replicated locally because `@dsh-cc/input-ledger` keeps it private) 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕. The dependency is soft by design: with no dsh-home, no session cwd, or `cc-input-ledger.enabled: false` the governor still runs and rows are simply not persisted; an append failure is swallowed, debug-logged and counted in `getGovernorLedgerHealth().droppedRows` — never thrown into the waterfall and never awaited on the hot path 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L122-L131〕. A governor exception returns the unmodified decision with an `{ error: true }` row, so a failing gate can never half-apply a batch 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L122-L124〕.
|
|
52
|
+
|
|
53
|
+
## Arithmetic (pinned to the verified model)
|
|
54
|
+
|
|
55
|
+
`available(budget, used) = budget - used` (saturating), `fits(budget, used, bytes) = bytes <= available(...)`, `oversize(budget, bytes) = budget < bytes` — identical to `Formal.fits` / `Formal.oversize` in `specs/lean/input-admission-arithmetic/Model.lean`. Protected classes are never charged; that is the arithmetic face of "never touched".
|
|
56
|
+
|
|
57
|
+
## Row fields
|
|
58
|
+
|
|
59
|
+
`@dsh-cc/input-ledger` owns the row schema; this package supplies only `mode`, `bytesByClass`, `trimmed`, `offeredBacklog` and `hardOver` 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕. `trimmed` entries are `{ kind, bytes, action }` with `action` in `defer | drop-expired | drop-oversize`.
|
|
60
|
+
|
|
61
|
+
Conventions this package pins, because the design leaves them to the implementation: `bytesByClass` always carries all five class keys, in table order, measured over the **decision** batch (so observe and enforce agree); `offeredBacklog` is the backlog present when the invocation started (always 0 in observe mode); the decision batch is the admitted backlog entries first (they are older), then the surviving fresh messages in arrival order — no other reordering; and an entry whose bytes exceed its class budget is dropped `drop-oversize` during the backlog walk too, which is reachable only when the hot-read budgets shrank after enqueue.
|
|
62
|
+
|
|
63
|
+
## Settings — `cc-input-budget`
|
|
64
|
+
|
|
65
|
+
Kebab-key, user-layer settings, re-read per gate invocation so a toggle applies on the next step without a restart 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L109-L120〕.
|
|
66
|
+
|
|
67
|
+
| key | type | default | bounds |
|
|
68
|
+
|---|---|---|---|
|
|
69
|
+
| `enabled` | bool | `true` | — |
|
|
70
|
+
| `mode` | `'observe' \| 'enforce'` | `'observe'` | — (a flip to enforce resets the defer queue) |
|
|
71
|
+
| `enter-budget-bytes` | int | `24576` | 4096..262144 |
|
|
72
|
+
| `advisory-budget-bytes` | int | `8192` | 512..65536 |
|
|
73
|
+
| `memory-budget-bytes` | int | `16384` | 1024..131072 |
|
|
74
|
+
| `defer-ttl-steps` | int | `3` | 1..16 |
|
|
75
|
+
|
|
76
|
+
Defaults are carried on four surfaces that must agree: the schema `.default()`s, the `DEFAULT_INPUT_BUDGET_SETTINGS` constants, the fail-soft raw reader (absent or malformed file, out-of-bounds integers → defaults or bounds, unknown mode → `observe`) and the wiring fallback. No settings file means the defaults, which means **observe mode runs**.
|
|
77
|
+
|
|
78
|
+
## Usage
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { govern, messageBytes, createGovernorListener } from '@dsh-cc/input-budget'
|
|
82
|
+
|
|
83
|
+
// The pure core: the whole algorithm as a function of its arguments.
|
|
84
|
+
const result = govern({ messages, settings, backlog, gateSeq })
|
|
85
|
+
// result.messages — the decision batch (the input batch untouched in observe mode)
|
|
86
|
+
// result.decision — { mode, bytesByClass, trimmed, offeredBacklog, hardOver }
|
|
87
|
+
// result.backlog — the defer queue to carry into the next invocation
|
|
88
|
+
// result.gateSeq — the next gateSeq to carry into the next invocation
|
|
89
|
+
|
|
90
|
+
// The wiring: a preset row mounts it, a test host can mount it directly.
|
|
91
|
+
const release = registerGovernorListener(ctx) // prepended agent/pre-step listener
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Caveats
|
|
95
|
+
|
|
96
|
+
- Observe mode is the ship default and the only mode exercised in production today; enforcement budgets are meant to be set from ledger data before flipping 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L137-L137〕.
|
|
97
|
+
- Deferred messages re-enter only through the governor's own return value, never through `agent.inject`, so no extra claimed batches form.
|
|
98
|
+
- The two ordering defenses (live-fold producer-chain tests, the late-prepended-listener boundary) and the repo-wide kind enumeration scan are pinned in `tests/live-fold.spec.ts` and `tests/kinds-enumeration.spec.ts`; the enumeration hard-fails when the pinned harness checkout is missing 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L57-L59〕〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L73-L73〕.
|
|
99
|
+
- Advisory starvation under sustained overload is bounded, not eliminated; per-kind caps are the sibling doc's job.
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# @dsh-cc/input-budget
|
|
2
|
+
|
|
3
|
+
[English](README.md) | 中文
|
|
4
|
+
|
|
5
|
+
上下文工程输入治理 program 的逐步输入预算 governor:对最终的 `agent/pre-step` enter 批次施加唯一的最外层闸门,按类别与字节预算仲裁各生产者写入的内容 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L53-L59〕。三层一并交付:纯核(`govern()`——只是其参数的函数,因此整个算法无需运行时即可单测)、预设 `input-budget` 行所挂载的 `agent/pre-step` 监听器,以及每次闸门调用写入一条 `GovernorRow` 的账本写入 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕。出厂 observe 优先:observe 模式下批次原样返回,只记录决策。
|
|
6
|
+
|
|
7
|
+
## 类别——仅显式成员
|
|
8
|
+
|
|
9
|
+
成员集合封闭且显式 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L61-L73〕。未列出的任何值——未知类别、后注册插件、缺失或空的 `source.kind`——由构造即归为 `passthrough`,因此未枚举的生产者永不被裁剪、永不被延迟。
|
|
10
|
+
|
|
11
|
+
| 类别 | 类别名(kind) | 策略 |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `governance` | `turn-rules`、`edit-recovery-hint`、`completion-gate`、`permission-rules`、`agent-instructions`、`hooks-claude-code`、`compact-checkpoint`、`moa-escalation` | 永不裁剪、永不延迟;照常计量 |
|
|
14
|
+
| `task` | `user`、`progress-rebuild`、`moa`、`subagent-settled`、`cc-subagent-children`、`vwa-evidence`、`cc-workflow-completion` | 永不裁剪、永不延迟;照常计量 |
|
|
15
|
+
| `memory` | `memory` | 在 `memory-budget-bytes` 下 FIFO 裁剪/延迟 |
|
|
16
|
+
| `advisory` | `advisor`、`retry-attendant`、`compaction-micro`、`compaction-cost-gate` | 在 `advisory-budget-bytes` 下 FIFO 裁剪/延迟 |
|
|
17
|
+
| `passthrough` | `cc-shell-glue`(v1 硬规则)、`command-preset`、`side-query`、`tool-web-fetch`、`tool-registry`、已列名 harness kind、其余全部 | 永不裁剪、永不延迟;照常计量 |
|
|
18
|
+
|
|
19
|
+
`cc-shell-glue` 在 v1 落入 `passthrough` 是一条**算法规则**,不是注解:`mcpReadyNotice` 在返回通告**之前**就已提交其每会话一次闩锁,因此对 glue 通告的任何强制裁剪、延迟或超限丢弃都会变成静默的一次性丢失 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L71-L71〕。`memory` 与 `advisory` 是唯二带预算的类别;一条 12 KiB 的 memory 记录按 `memory-budget-bytes` 判定,绝不以 advisory 限额判定 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L67-L67〕〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L92-L92〕。
|
|
20
|
+
|
|
21
|
+
## 预算模型(每个 enter 批次)
|
|
22
|
+
|
|
23
|
+
1. 逐条分类;计算各类 UTF-8 字节(仅文本块——与 `@dsh-cc/input-ledger` 记录的口径相同,因此两族行逐字节一致) 〔src:ws:docs/plans/2026-11-12-per-step-input-ledger.md#L82-L82〕。
|
|
24
|
+
2. `governance` / `task` / `passthrough`:永不改动、永不计量入预算。
|
|
25
|
+
3. `memory`:只要 memory 字节超过 `memory-budget-bytes`,就裁剪最旧的 memory 消息(整条消息,FIFO)。
|
|
26
|
+
4. `advisory`:只要 advisory 字节超过 `advisory-budget-bytes`,就裁剪最旧的 advisory 消息。
|
|
27
|
+
5. Enter 预算:若批次总量超过 `enter-budget-bytes`,继续裁剪 advisory(其后 memory)。若在可裁剪类别内仍无法满足预算,则不再进一步裁剪、绝不触碰受保护类别,并由 `hardOver` 记录溢出 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L77-L83〕。
|
|
28
|
+
|
|
29
|
+
被裁剪消息若其自身字节单独就超过其类别预算,立即以 `drop-oversize` 丢弃且绝不入队——先延迟后丢弃会记录一次永远不可能成功的延迟。
|
|
30
|
+
|
|
31
|
+
## 延迟队列
|
|
32
|
+
|
|
33
|
+
每会话的 `{ message, enqueuedAtSeq, lastOfferedSeq }` backlog,全部取值以 `gateSeq` 为单位。`gateSeq` 是**单调的每会话调用计数**,每次闸门调用递增;`agent/pre-step` 的 `step` 是回合内局部量,永不使用 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L75-L75〕。`govern()` 接收该计数并返回下一个;监听器按会话持有它。
|
|
34
|
+
|
|
35
|
+
每次调用按序执行 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L87-L95〕:
|
|
36
|
+
|
|
37
|
+
1. **老化**——`gateSeq - enqueuedAtSeq > defer-ttl-steps` 的条目以 `drop-expired` 丢弃。
|
|
38
|
+
2. **backlog 准入**——按 FIFO 走查,只要**队头自身**类别预算尚有余量就准入(memory 条目按 `memory-budget-bytes`,advisory 按 `advisory-budget-bytes`,`used` 取本次调用已准入的字节)。被准入的条目排在这一步批次之首。
|
|
39
|
+
3. **新批裁剪**——即上面的预算模型;存活批次中被裁剪的消息追加到 backlog 尾部。
|
|
40
|
+
|
|
41
|
+
`lastOfferedSeq` 初值等于 `enqueuedAtSeq`,并在每次评估过该条目的调用结束时推进到当前 `gateSeq`——准入、拒绝与再次延迟一视同仁。TTL 由调用次数而非准入次数界定。
|
|
42
|
+
|
|
43
|
+
## Observe 模式
|
|
44
|
+
|
|
45
|
+
`mode: 'observe'` 执行完全相同的新批计算并以 `mode: 'observe'` 记录相同的行,但原样返回输入批次、不保留延迟队列、不模拟 backlog、不产生 `drop-expired` 行。observe 下**仍可能**出现 `drop-oversize`,因为它属于新批计算 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L97-L103〕。由于 observe 调用返回空 backlog,`observe → enforce` 翻转由构造即从空队列开始——不存在跨模式遗留。
|
|
46
|
+
|
|
47
|
+
## 装配——监听器、预设行、账本写入
|
|
48
|
+
|
|
49
|
+
`registerGovernorListener(ctx)` 以一个 `{ prepend: true }` 的 `agent/pre-step` 监听器注册,因此它在预设的 pre-step 重写者中最外层运行,并在返回途中看到最终决策;它 delegate-first(先 await `next()`,再展开返回的决策、只替换消息批次),且绝不向瀑布抛错 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L53-L59〕。共享预设体中的预设行 `input-budget` 经 `apply()` 挂载它,排序在 `tool-task` 之后,使 subagent 的 strip-instructions/settled-notice 组合留在闸门之内;组合 pin 与两项 live-fold 顺序测试让该边界是被测试的性质而非偶然 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L57-L59〕。
|
|
50
|
+
|
|
51
|
+
行经 `createGovernorLedgerSink()` 落地:每次闸门调用一条无内容 `GovernorRow`,追加到 `$DSH_HOME/input-ledger/<projectKey>/<sessionId>.jsonl`,与账本自身观察者使用同一 sink 与路径约定(project 桶为 `sha256(realpath(cwd))` 的前 16 个十六进制字符;因 `@dsh-cc/input-ledger` 不导出该函数,此处保有一份一致的本地副本) 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕。该依赖按设计是软依赖:没有 dsh-home、没有会话 cwd,或 `cc-input-ledger.enabled: false` 时 governor 照常运行,行只是不落盘;追加失败被吞掉、记入调试日志并计入 `getGovernorLedgerHealth().droppedRows`——绝不抛入瀑布,也绝不在热路径上等待 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L122-L131〕。governor 自身抛错时返回未改动的决策并记录 `{ error: true }` 行,因此失败的闸门绝不会半应用一个批次 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L122-L124〕。
|
|
52
|
+
|
|
53
|
+
## 算术(钉住已验证模型)
|
|
54
|
+
|
|
55
|
+
`available(budget, used) = budget - used`(饱和减法)、`fits(budget, used, bytes) = bytes <= available(...)`、`oversize(budget, bytes) = budget < bytes`——与 `specs/lean/input-admission-arithmetic/Model.lean` 中的 `Formal.fits` / `Formal.oversize` 完全一致。受保护类别永不计量,这就是"永不触碰"的算术面。
|
|
56
|
+
|
|
57
|
+
## 行字段
|
|
58
|
+
|
|
59
|
+
行 schema 归 `@dsh-cc/input-ledger` 所有;本包只提供 `mode`、`bytesByClass`、`trimmed`、`offeredBacklog` 与 `hardOver` 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L105-L107〕。`trimmed` 元素为 `{ kind, bytes, action }`,`action` 取 `defer | drop-expired | drop-oversize`。
|
|
60
|
+
|
|
61
|
+
以下约定由本包钉住,因为设计把细节留给实现:`bytesByClass` 恒含全部五个类别键、按表格顺序、以**决策**批次计量(因此 observe 与 enforce 一致);`offeredBacklog` 是调用开始时的 backlog 长度(observe 模式恒为 0);决策批次中被准入的 backlog 条目在前(它们更旧),随后是存活的新批消息按到达顺序——除此之外不重排;自身字节超过类别预算的条目在 backlog 走查中同样以 `drop-oversize` 丢弃,这一分支只有在热读预算于入队后收窄时才可达。
|
|
62
|
+
|
|
63
|
+
## 设置——`cc-input-budget`
|
|
64
|
+
|
|
65
|
+
kebab 键、用户层设置,每次闸门调用重读,因此热开关在下一步即生效、无需重启 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L109-L120〕。
|
|
66
|
+
|
|
67
|
+
| 键 | 类型 | 默认 | 取值范围 |
|
|
68
|
+
|---|---|---|---|
|
|
69
|
+
| `enabled` | bool | `true` | — |
|
|
70
|
+
| `mode` | `'observe' \| 'enforce'` | `'observe'` | —(翻转到 enforce 会重置延迟队列) |
|
|
71
|
+
| `enter-budget-bytes` | int | `24576` | 4096..262144 |
|
|
72
|
+
| `advisory-budget-bytes` | int | `8192` | 512..65536 |
|
|
73
|
+
| `memory-budget-bytes` | int | `16384` | 1024..131072 |
|
|
74
|
+
| `defer-ttl-steps` | int | `3` | 1..16 |
|
|
75
|
+
|
|
76
|
+
默认值分散在四个必须一致的面:schema 的 `.default()`、`DEFAULT_INPUT_BUDGET_SETTINGS` 常量、fail-soft 原始读取器(文件缺失或损坏、越界整数 → 默认值或边界值、未知 mode → `observe`)以及装配层的兜底。没有设置文件即默认值,即 **observe 模式照常运行**。
|
|
77
|
+
|
|
78
|
+
## 用法
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { govern, messageBytes, createGovernorListener, registerGovernorListener } from '@dsh-cc/input-budget'
|
|
82
|
+
|
|
83
|
+
// 纯核:整个算法就是其参数的函数。
|
|
84
|
+
const result = govern({ messages, settings, backlog, gateSeq })
|
|
85
|
+
// result.messages —— 决策批次(observe 模式下即原输入批次,原样返回)
|
|
86
|
+
// result.decision —— { mode, bytesByClass, trimmed, offeredBacklog, hardOver }
|
|
87
|
+
// result.backlog —— 传递给下一次调用的延迟队列
|
|
88
|
+
// result.gateSeq —— 传递给下一次调用的 gateSeq
|
|
89
|
+
|
|
90
|
+
// 装配:预设行负责挂载,测试宿主也可直接挂载。
|
|
91
|
+
const release = registerGovernorListener(ctx) // prepend 的 agent/pre-step 监听器
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## 注意事项
|
|
95
|
+
|
|
96
|
+
- observe 模式是出厂默认,也是当前生产唯一启用的模式;enforce 预算应在翻转前依据账本数据设定 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L137-L137〕。
|
|
97
|
+
- 被延迟的消息只通过 governor 自身的返回值回流,从不经 `agent.inject`,因此不会额外形成 claimed 批次。
|
|
98
|
+
- 两项顺序防御(生产者链 live-fold 测试、后注册 prepend 监听器边界)与全仓类别枚举扫描分别钉在 `tests/live-fold.spec.ts` 与 `tests/kinds-enumeration.spec.ts`;缺少 pinned harness 检出时枚举硬失败 〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L57-L59〕〔src:ws:docs/plans/2026-11-12-per-step-input-budget-governor.md#L73-L73〕。
|
|
99
|
+
- 持续过载下 advisory 的饥饿被限定而非消除;按类上限是姊妹文档的职责。
|
package/lib/classes.d.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The explicit class map of the per-step input budget governor — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"Classes (explicit
|
|
4
|
+
* membership only)".
|
|
5
|
+
*
|
|
6
|
+
* Membership is explicit and closed. A kind that is not listed below is
|
|
7
|
+
* `passthrough`, which is never trimmed and never deferred. That inversion is
|
|
8
|
+
* the safety story of the whole gate: an unenumerated producer — a late
|
|
9
|
+
* plugin, a future package, a harness-only kind — keeps flowing untouched
|
|
10
|
+
* instead of being silently classed as deferrable. The r1 blind-review fold
|
|
11
|
+
* turned the original "unknown → advisory" inversion around for exactly this
|
|
12
|
+
* reason: it would have trimmed `agent-instructions` workspace rules and hook
|
|
13
|
+
* `additionalContext` as they currently flow.
|
|
14
|
+
*
|
|
15
|
+
* `cc-shell-glue` sits in `passthrough` in v1 as an **algorithmic rule**, not
|
|
16
|
+
* an annotation: `mcpReadyNotice` commits its once-per-session latch BEFORE
|
|
17
|
+
* returning the notice, so an enforced trim, defer or oversize drop of a glue
|
|
18
|
+
* notice would be a silent one-shot miss.
|
|
19
|
+
*
|
|
20
|
+
* @module @dsh-cc/input-budget/classes
|
|
21
|
+
*/
|
|
22
|
+
/** The five classes of the per-step input gate. */
|
|
23
|
+
export type InputClass = 'governance' | 'task' | 'memory' | 'advisory' | 'passthrough';
|
|
24
|
+
/** Every class, in the design table's order (also the row key order). */
|
|
25
|
+
export declare const INPUT_CLASSES: readonly InputClass[];
|
|
26
|
+
/** The classes carrying a byte budget; every other class is counted only. */
|
|
27
|
+
export declare const BUDGETED_CLASSES: readonly InputClass[];
|
|
28
|
+
/** Never trimmed, never deferred: policy and instruction content the model must see. */
|
|
29
|
+
export declare const GOVERNANCE_KINDS: readonly string[];
|
|
30
|
+
/**
|
|
31
|
+
* Never trimmed, never deferred: user turns, lifecycle wakes and delivery
|
|
32
|
+
* wakes. Losing one of these loses work product or a settlement.
|
|
33
|
+
*/
|
|
34
|
+
export declare const TASK_KINDS: readonly string[];
|
|
35
|
+
/** Trimmed/deferred FIFO under its own `memory-budget-bytes` (recall bodies). */
|
|
36
|
+
export declare const MEMORY_KINDS: readonly string[];
|
|
37
|
+
/** Trimmed/deferred FIFO under `advisory-budget-bytes`. */
|
|
38
|
+
export declare const ADVISORY_KINDS: readonly string[];
|
|
39
|
+
/**
|
|
40
|
+
* Never trimmed, never deferred. `cc-shell-glue` first (the v1 hard rule),
|
|
41
|
+
* then named host kinds, then every unknown kind by construction.
|
|
42
|
+
*/
|
|
43
|
+
export declare const PASSTHROUGH_KINDS: readonly string[];
|
|
44
|
+
/** One lookup table keyed by the exact `source.kind` string. */
|
|
45
|
+
export declare const KIND_CLASSES: Readonly<Record<string, InputClass>>;
|
|
46
|
+
/**
|
|
47
|
+
* Class of one source-kind string. Anything not explicitly listed — including
|
|
48
|
+
* an absent or empty kind — is `passthrough`, so unknown producers are never
|
|
49
|
+
* trimmed and never deferred.
|
|
50
|
+
*
|
|
51
|
+
* @param kind - the message's `source.kind`, or undefined when unlabelled.
|
|
52
|
+
*/
|
|
53
|
+
export declare function classifyKind(kind: string | undefined): InputClass;
|
|
54
|
+
/** Whether a class carries a byte budget (only `memory` and `advisory` do). */
|
|
55
|
+
export declare function isBudgeted(cls: InputClass): boolean;
|
|
56
|
+
//# sourceMappingURL=classes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../src/classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAA;AAEtF,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAMpC,CAAA;AAEX,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAAmD,CAAA;AAErG,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EASnC,CAAA;AAEX;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAQ7B,CAAA;AAEX,iFAAiF;AACjF,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAuC,CAAA;AAEjF,2DAA2D;AAC3D,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAKjC,CAAA;AAEX;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAYpC,CAAA;AAaX,gEAAgE;AAChE,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAM5D,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAGjE;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEnD"}
|
package/lib/classes.js
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The explicit class map of the per-step input budget governor — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"Classes (explicit
|
|
4
|
+
* membership only)".
|
|
5
|
+
*
|
|
6
|
+
* Membership is explicit and closed. A kind that is not listed below is
|
|
7
|
+
* `passthrough`, which is never trimmed and never deferred. That inversion is
|
|
8
|
+
* the safety story of the whole gate: an unenumerated producer — a late
|
|
9
|
+
* plugin, a future package, a harness-only kind — keeps flowing untouched
|
|
10
|
+
* instead of being silently classed as deferrable. The r1 blind-review fold
|
|
11
|
+
* turned the original "unknown → advisory" inversion around for exactly this
|
|
12
|
+
* reason: it would have trimmed `agent-instructions` workspace rules and hook
|
|
13
|
+
* `additionalContext` as they currently flow.
|
|
14
|
+
*
|
|
15
|
+
* `cc-shell-glue` sits in `passthrough` in v1 as an **algorithmic rule**, not
|
|
16
|
+
* an annotation: `mcpReadyNotice` commits its once-per-session latch BEFORE
|
|
17
|
+
* returning the notice, so an enforced trim, defer or oversize drop of a glue
|
|
18
|
+
* notice would be a silent one-shot miss.
|
|
19
|
+
*
|
|
20
|
+
* @module @dsh-cc/input-budget/classes
|
|
21
|
+
*/
|
|
22
|
+
/** Every class, in the design table's order (also the row key order). */
|
|
23
|
+
export const INPUT_CLASSES = Object.freeze([
|
|
24
|
+
'governance',
|
|
25
|
+
'task',
|
|
26
|
+
'memory',
|
|
27
|
+
'advisory',
|
|
28
|
+
'passthrough',
|
|
29
|
+
]);
|
|
30
|
+
/** The classes carrying a byte budget; every other class is counted only. */
|
|
31
|
+
export const BUDGETED_CLASSES = Object.freeze(['memory', 'advisory']);
|
|
32
|
+
/** Never trimmed, never deferred: policy and instruction content the model must see. */
|
|
33
|
+
export const GOVERNANCE_KINDS = Object.freeze([
|
|
34
|
+
'turn-rules',
|
|
35
|
+
'edit-recovery-hint',
|
|
36
|
+
'completion-gate',
|
|
37
|
+
'permission-rules',
|
|
38
|
+
'agent-instructions',
|
|
39
|
+
'hooks-claude-code',
|
|
40
|
+
'compact-checkpoint',
|
|
41
|
+
'moa-escalation',
|
|
42
|
+
]);
|
|
43
|
+
/**
|
|
44
|
+
* Never trimmed, never deferred: user turns, lifecycle wakes and delivery
|
|
45
|
+
* wakes. Losing one of these loses work product or a settlement.
|
|
46
|
+
*/
|
|
47
|
+
export const TASK_KINDS = Object.freeze([
|
|
48
|
+
'user',
|
|
49
|
+
'progress-rebuild',
|
|
50
|
+
'moa',
|
|
51
|
+
'subagent-settled',
|
|
52
|
+
'cc-subagent-children',
|
|
53
|
+
'vwa-evidence',
|
|
54
|
+
'cc-workflow-completion',
|
|
55
|
+
]);
|
|
56
|
+
/** Trimmed/deferred FIFO under its own `memory-budget-bytes` (recall bodies). */
|
|
57
|
+
export const MEMORY_KINDS = Object.freeze(['memory']);
|
|
58
|
+
/** Trimmed/deferred FIFO under `advisory-budget-bytes`. */
|
|
59
|
+
export const ADVISORY_KINDS = Object.freeze([
|
|
60
|
+
'advisor',
|
|
61
|
+
'retry-attendant',
|
|
62
|
+
'compaction-micro',
|
|
63
|
+
'compaction-cost-gate',
|
|
64
|
+
]);
|
|
65
|
+
/**
|
|
66
|
+
* Never trimmed, never deferred. `cc-shell-glue` first (the v1 hard rule),
|
|
67
|
+
* then named host kinds, then every unknown kind by construction.
|
|
68
|
+
*/
|
|
69
|
+
export const PASSTHROUGH_KINDS = Object.freeze([
|
|
70
|
+
'cc-shell-glue',
|
|
71
|
+
'command-preset',
|
|
72
|
+
'side-query',
|
|
73
|
+
'tool-web-fetch',
|
|
74
|
+
'tool-registry',
|
|
75
|
+
'developer',
|
|
76
|
+
'plan-mode',
|
|
77
|
+
'runtime-context',
|
|
78
|
+
'skill-invocation',
|
|
79
|
+
'subagent-instructions',
|
|
80
|
+
'system-prompt',
|
|
81
|
+
]);
|
|
82
|
+
/** Merge the per-class kind lists into one lookup table. */
|
|
83
|
+
function buildTable(lists) {
|
|
84
|
+
const table = {};
|
|
85
|
+
for (const cls of INPUT_CLASSES) {
|
|
86
|
+
for (const kind of lists[cls])
|
|
87
|
+
table[kind] = cls;
|
|
88
|
+
}
|
|
89
|
+
return Object.freeze(table);
|
|
90
|
+
}
|
|
91
|
+
/** One lookup table keyed by the exact `source.kind` string. */
|
|
92
|
+
export const KIND_CLASSES = buildTable({
|
|
93
|
+
governance: GOVERNANCE_KINDS,
|
|
94
|
+
task: TASK_KINDS,
|
|
95
|
+
memory: MEMORY_KINDS,
|
|
96
|
+
advisory: ADVISORY_KINDS,
|
|
97
|
+
passthrough: PASSTHROUGH_KINDS,
|
|
98
|
+
});
|
|
99
|
+
/**
|
|
100
|
+
* Class of one source-kind string. Anything not explicitly listed — including
|
|
101
|
+
* an absent or empty kind — is `passthrough`, so unknown producers are never
|
|
102
|
+
* trimmed and never deferred.
|
|
103
|
+
*
|
|
104
|
+
* @param kind - the message's `source.kind`, or undefined when unlabelled.
|
|
105
|
+
*/
|
|
106
|
+
export function classifyKind(kind) {
|
|
107
|
+
if (typeof kind !== 'string' || kind.length === 0)
|
|
108
|
+
return 'passthrough';
|
|
109
|
+
return KIND_CLASSES[kind] ?? 'passthrough';
|
|
110
|
+
}
|
|
111
|
+
/** Whether a class carries a byte budget (only `memory` and `advisory` do). */
|
|
112
|
+
export function isBudgeted(cls) {
|
|
113
|
+
return cls === 'memory' || cls === 'advisory';
|
|
114
|
+
}
|
|
115
|
+
//# sourceMappingURL=classes.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"classes.js","sourceRoot":"","sources":["../src/classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAA0B,MAAM,CAAC,MAAM,CAAC;IAChE,YAAY;IACZ,MAAM;IACN,QAAQ;IACR,UAAU;IACV,aAAa;CACL,CAAC,CAAA;AAEX,6EAA6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAA0B,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAU,CAAC,CAAA;AAErG,wFAAwF;AACxF,MAAM,CAAC,MAAM,gBAAgB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC/D,YAAY;IACZ,oBAAoB;IACpB,iBAAiB;IACjB,kBAAkB;IAClB,oBAAoB;IACpB,mBAAmB;IACnB,oBAAoB;IACpB,gBAAgB;CACR,CAAC,CAAA;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzD,MAAM;IACN,kBAAkB;IAClB,KAAK;IACL,kBAAkB;IAClB,sBAAsB;IACtB,cAAc;IACd,wBAAwB;CAChB,CAAC,CAAA;AAEX,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAU,CAAC,CAAA;AAEjF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC7D,SAAS;IACT,iBAAiB;IACjB,kBAAkB;IAClB,sBAAsB;CACd,CAAC,CAAA;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAChE,eAAe;IACf,gBAAgB;IAChB,YAAY;IACZ,gBAAgB;IAChB,eAAe;IACf,WAAW;IACX,WAAW;IACX,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;IACvB,eAAe;CACP,CAAC,CAAA;AAEX,4DAA4D;AAC5D,SAAS,UAAU,CACjB,KAAsD;IAEtD,MAAM,KAAK,GAA+B,EAAE,CAAA;IAC5C,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAA;IAClD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC;AAED,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAyC,UAAU,CAAC;IAC3E,UAAU,EAAE,gBAAgB;IAC5B,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,YAAY;IACpB,QAAQ,EAAE,cAAc;IACxB,WAAW,EAAE,iBAAiB;CAC/B,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,aAAa,CAAA;IACvE,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,aAAa,CAAA;AAC5C,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,UAAU,CAAA;AAC/C,CAAC"}
|