@dsh-cc/input-budget 0.0.0-stage → 0.9.6-rc.1
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 +102 -2
- package/README.zh.md +103 -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/lib/ledger.js
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ledger emission wiring — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"GovernorRow":
|
|
4
|
+
* `@dsh-cc/input-ledger` owns the row schema and the append sink, this package
|
|
5
|
+
* owns the row fields, and this module is the one place the two meet.
|
|
6
|
+
*
|
|
7
|
+
* The dependency is SOFT by design ("when the ledger package is absent/disabled,
|
|
8
|
+
* the governor still runs; rows are simply not persisted"):
|
|
9
|
+
*
|
|
10
|
+
* - no dsh-home on the host (a bare test host) — nothing to write to;
|
|
11
|
+
* - no cwd on the session header — no project bucket, so no file path exists
|
|
12
|
+
* (the ledger's own observers skip the same rows by convention);
|
|
13
|
+
* - `cc-input-ledger.enabled: false` — the ledger's own kill switch, hot-read
|
|
14
|
+
* per row exactly like the ledger's observers read it.
|
|
15
|
+
*
|
|
16
|
+
* Every one of those is a silent skip; every actual failure (a thrown path
|
|
17
|
+
* build, a failed append reported through `onError`) counts into
|
|
18
|
+
* {@linkcode getGovernorLedgerHealth}'s `droppedRows` and is debug-logged.
|
|
19
|
+
* Nothing here is ever thrown into the `agent/pre-step` waterfall and nothing
|
|
20
|
+
* here is awaited on the hot path: the append is detached and serialized by the
|
|
21
|
+
* ledger's own per-file write chain.
|
|
22
|
+
*
|
|
23
|
+
* @module @dsh-cc/input-budget/ledger
|
|
24
|
+
*/
|
|
25
|
+
import { createHash } from 'node:crypto';
|
|
26
|
+
import { realpathSync } from 'node:fs';
|
|
27
|
+
import { DEFAULT_INPUT_LEDGER_SETTINGS, appendLedgerRow, readUserSettingsSync, sessionLedgerPath, } from '@dsh-cc/input-ledger';
|
|
28
|
+
/** Width of a project key: the `projectKeyOf` convention's 16 hex chars. */
|
|
29
|
+
const PROJECT_KEY_CHARS = 16;
|
|
30
|
+
/** Rows lost to a failed append since process start (fresh object per call). */
|
|
31
|
+
let droppedRows = 0;
|
|
32
|
+
/**
|
|
33
|
+
* In-process emission health: governor rows that never reached the ledger.
|
|
34
|
+
* A fresh object each call, so callers cannot mutate the counter. Mirrors the
|
|
35
|
+
* ledger's own `getLedgerHealth()`; the sink counts here even when the ledger's
|
|
36
|
+
* counter also saw the failure, because this is the governor's view.
|
|
37
|
+
*/
|
|
38
|
+
export function getGovernorLedgerHealth() {
|
|
39
|
+
return { droppedRows };
|
|
40
|
+
}
|
|
41
|
+
/** The object face of an untyped value, or `undefined`. */
|
|
42
|
+
function objectOf(value) {
|
|
43
|
+
return typeof value === 'object' && value !== null ? value : undefined;
|
|
44
|
+
}
|
|
45
|
+
/** Canonicalize a cwd: `realpathSync` when it resolves, the raw spelling otherwise. */
|
|
46
|
+
function canonicalize(path) {
|
|
47
|
+
try {
|
|
48
|
+
return realpathSync(path);
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
return path;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Project bucket of one cwd: the first 16 hex chars of `sha256(realpath(cwd))`
|
|
56
|
+
* — the `cwdProjectKey` convention (handoff-store `cwdProjectKey`, sidecar-io
|
|
57
|
+
* `projectKeyOf`). A local replica, byte-identical to the one in
|
|
58
|
+
* `@dsh-cc/input-ledger` `src/observe.ts` (`projectKeyOfAgent`): that package
|
|
59
|
+
* keeps it private, and importing `@dsh-cc/sidecar-io` here would add a
|
|
60
|
+
* runtime dependency this soft wiring must not have.
|
|
61
|
+
*/
|
|
62
|
+
export function projectKeyForCwd(cwd) {
|
|
63
|
+
return createHash('sha256').update(canonicalize(cwd), 'utf8').digest('hex').slice(0, PROJECT_KEY_CHARS);
|
|
64
|
+
}
|
|
65
|
+
/** Header-derived cwd of an agent face, or `undefined` when the header carries none. */
|
|
66
|
+
function cwdOf(agent) {
|
|
67
|
+
const header = objectOf(objectOf(objectOf(agent)?.session)?.header);
|
|
68
|
+
const cwd = header?.cwd;
|
|
69
|
+
return typeof cwd === 'string' && cwd.length > 0 ? cwd : undefined;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The project bucket of one `agent/pre-step` payload's agent, or `undefined`
|
|
73
|
+
* when the session header carries no cwd (the row is then skipped, as the
|
|
74
|
+
* ledger's observers skip theirs).
|
|
75
|
+
*
|
|
76
|
+
* @param agent - the payload's agent, of unknown shape.
|
|
77
|
+
*/
|
|
78
|
+
export function cwdProjectKeyOf(agent) {
|
|
79
|
+
const cwd = cwdOf(agent);
|
|
80
|
+
return cwd === undefined ? undefined : projectKeyForCwd(cwd);
|
|
81
|
+
}
|
|
82
|
+
/** Best-effort one-line description of a caught failure. */
|
|
83
|
+
function describe(error) {
|
|
84
|
+
return error instanceof Error ? error.message : String(error);
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Build the sink that persists governor rows through the input ledger.
|
|
88
|
+
*
|
|
89
|
+
* @param deps - dsh-home root, the ledger settings read and the debug sink.
|
|
90
|
+
* @returns a synchronous, never-throwing row sink.
|
|
91
|
+
*/
|
|
92
|
+
export function createGovernorLedgerSink(deps) {
|
|
93
|
+
const warn = (message) => {
|
|
94
|
+
try {
|
|
95
|
+
deps.debug(message);
|
|
96
|
+
}
|
|
97
|
+
catch {
|
|
98
|
+
// The debug sink is best-effort; a failure there must not escape either.
|
|
99
|
+
}
|
|
100
|
+
};
|
|
101
|
+
const readSettings = deps.readSettings
|
|
102
|
+
?? (() => (deps.home === undefined ? DEFAULT_INPUT_LEDGER_SETTINGS : readUserSettingsSync(deps.home)));
|
|
103
|
+
return (row, projectKey) => {
|
|
104
|
+
const home = deps.home;
|
|
105
|
+
// Silent skips (never counted as drops): nothing to write to, or no bucket.
|
|
106
|
+
if (home === undefined || projectKey === undefined)
|
|
107
|
+
return;
|
|
108
|
+
const settings = ledgerSettingsOf(readSettings, warn);
|
|
109
|
+
if (!settings.enabled)
|
|
110
|
+
return;
|
|
111
|
+
try {
|
|
112
|
+
const file = sessionLedgerPath(home, projectKey, row.sessionId);
|
|
113
|
+
void appendLedgerRow(file, row, (error) => {
|
|
114
|
+
droppedRows += 1;
|
|
115
|
+
warn(`input-budget: governor row dropped: ${describe(error)}`);
|
|
116
|
+
}, settings['max-rows-per-file']).catch(() => {
|
|
117
|
+
// `appendLedgerRow` resolves on every path by contract: belt-and-braces.
|
|
118
|
+
droppedRows += 1;
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
catch (error) {
|
|
122
|
+
droppedRows += 1;
|
|
123
|
+
warn(`input-budget: governor row dropped: ${describe(error)}`);
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* One hot settings read, fail-soft: a throwing reader must never suppress rows,
|
|
129
|
+
* so it degrades to the ship defaults (the ledger's own reader never throws).
|
|
130
|
+
*/
|
|
131
|
+
function ledgerSettingsOf(readSettings, warn) {
|
|
132
|
+
try {
|
|
133
|
+
return readSettings();
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
warn(`input-budget: ledger settings read failed: ${describe(error)}`);
|
|
137
|
+
return DEFAULT_INPUT_LEDGER_SETTINGS;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
//# sourceMappingURL=ledger.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `agent/pre-step` governor listener — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"Package & seam",
|
|
4
|
+
* §"Defer queue" and §"Failure semantics".
|
|
5
|
+
*
|
|
6
|
+
* One waterfall listener, registered `{ prepend: true }`, delegate-first: it
|
|
7
|
+
* awaits `next()` (so every inner listener produced its decision) and then
|
|
8
|
+
* rewrites the returned decision with `{ ...decision, messages: newBatch }`.
|
|
9
|
+
* The decision is always SPREAD, never reconstructed: harness
|
|
10
|
+
* `PreStepDecision.enter` carries `startsRequestSeries`, and tomorrow's payload
|
|
11
|
+
* may carry more — a rebuilt literal would silently drop them.
|
|
12
|
+
*
|
|
13
|
+
* Per-session state owned here (the reason this is wiring, not core): the
|
|
14
|
+
* monotonic `gateSeq` invocation counter and the defer backlog. The turn-local
|
|
15
|
+
* `step` resets per turn and is never used as a clock.
|
|
16
|
+
*
|
|
17
|
+
* Failure semantics: any exception — settings read, hook, governor — returns
|
|
18
|
+
* the unmodified decision and records `{ error: true }`. Nothing is ever thrown
|
|
19
|
+
* into the waterfall and no protected class is ever dropped.
|
|
20
|
+
*
|
|
21
|
+
* Backlog re-entry happens ONLY through this listener's return value: a
|
|
22
|
+
* deferred message is re-admitted by prepending it to the decision batch, never
|
|
23
|
+
* by `agent.inject`, so no new claimed batches form.
|
|
24
|
+
*
|
|
25
|
+
* Payload/decision faces are declared here as local structural subsets
|
|
26
|
+
* (turn-rules `PreStepPayload` idiom, `packages/interaction/turn-rules/src/wiring.ts:71`)
|
|
27
|
+
* rather than harness imports: the listener reads a session id and a message
|
|
28
|
+
* list, and the merge-extensible harness types stay out of this package.
|
|
29
|
+
*
|
|
30
|
+
* @module @dsh-cc/input-budget/listener
|
|
31
|
+
*/
|
|
32
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
33
|
+
import type { GovernorRow } from '@dsh-cc/input-ledger';
|
|
34
|
+
import type { DeferredEntry, GovernedMessage } from './core.ts';
|
|
35
|
+
import { type GovernorStageHook } from './pipeline.ts';
|
|
36
|
+
import { type InputBudgetMode, type InputBudgetSettings } from './settings.ts';
|
|
37
|
+
declare module '@deepseek-ai/cordis' {
|
|
38
|
+
interface Context {
|
|
39
|
+
/** Harness-home path resolver, provided by @deepseek-ai/dsh-app-boot at boot. Optional in tests. */
|
|
40
|
+
dshHomePath?: (...segments: string[]) => string;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/** Structural face of the `agent/pre-step` payload (turn-rules idiom). */
|
|
44
|
+
export interface PreStepPayloadLike {
|
|
45
|
+
readonly agent?: unknown;
|
|
46
|
+
readonly messages?: unknown;
|
|
47
|
+
readonly turn?: unknown;
|
|
48
|
+
readonly step?: unknown;
|
|
49
|
+
readonly signal?: unknown;
|
|
50
|
+
readonly modelSelection?: unknown;
|
|
51
|
+
}
|
|
52
|
+
/** Structural face of an `enter` decision; every field survives the rewrite. */
|
|
53
|
+
export interface EnterDecisionLike<T> {
|
|
54
|
+
readonly kind: 'enter';
|
|
55
|
+
readonly messages: T[];
|
|
56
|
+
readonly startsRequestSeries?: true;
|
|
57
|
+
}
|
|
58
|
+
/** Structural face of `PreStepDecision`: exactly the two shapes the harness emits. */
|
|
59
|
+
export type PreStepDecisionLike<T> = {
|
|
60
|
+
readonly kind: 'reject';
|
|
61
|
+
} | EnterDecisionLike<T>;
|
|
62
|
+
/** Per-session governor state: the monotonic clock and the defer backlog. */
|
|
63
|
+
export interface SessionGovernorState {
|
|
64
|
+
/** The last `gateSeq` this session consumed (0 before the first gate call). */
|
|
65
|
+
gateSeq: number;
|
|
66
|
+
/** The mode the stored backlog belongs to; a flip resets the backlog. */
|
|
67
|
+
mode: InputBudgetMode;
|
|
68
|
+
/** The defer backlog carried into the next invocation (empty in observe mode). */
|
|
69
|
+
backlog: DeferredEntry[];
|
|
70
|
+
}
|
|
71
|
+
/** Collaborators of the listener; the registration wires them to the runtime. */
|
|
72
|
+
export interface GovernorListenerDeps {
|
|
73
|
+
/** Hot settings read — called once per gate invocation. */
|
|
74
|
+
readSettings(): InputBudgetSettings;
|
|
75
|
+
/**
|
|
76
|
+
* Row sink seam: the input-ledger append (wired by the ledger slice). The
|
|
77
|
+
* project bucket rides alongside because the row schema carries none — the
|
|
78
|
+
* bucket is the file path's directory, exactly as the ledger's observers
|
|
79
|
+
* pass it.
|
|
80
|
+
*/
|
|
81
|
+
emit(row: GovernorRow, projectKey?: string | undefined): void;
|
|
82
|
+
/** Process boot id stamped into every row. */
|
|
83
|
+
gen: string;
|
|
84
|
+
/** Debug sink for swallowed failures (must not throw). */
|
|
85
|
+
debug(message: string): void;
|
|
86
|
+
/** Pre-trim pipeline stages (doc 7 dedupe → caps); empty in this slice. */
|
|
87
|
+
hooks?: readonly GovernorStageHook<GovernedMessage>[] | undefined;
|
|
88
|
+
}
|
|
89
|
+
/** The listener plus the introspection a test needs. */
|
|
90
|
+
export interface GovernorListener {
|
|
91
|
+
/** The waterfall listener itself. */
|
|
92
|
+
handler(payload: PreStepPayloadLike, next: () => Promise<PreStepDecisionLike<GovernedMessage>>): Promise<PreStepDecisionLike<GovernedMessage>>;
|
|
93
|
+
/** One session's live state, or undefined before its first gate call. */
|
|
94
|
+
stateOf(sessionId: string): SessionGovernorState | undefined;
|
|
95
|
+
/** Drop one session's state (session disposal; never affects other sessions). */
|
|
96
|
+
forget(session: unknown): void;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Durable session id of an agent face: `session.header.id` first (the harness
|
|
100
|
+
* shape every other dsh-cc listener reads), then the bare `session.id`.
|
|
101
|
+
* @param agent - the payload's agent, of unknown shape.
|
|
102
|
+
* @returns the session id, or undefined when the face carries none.
|
|
103
|
+
*/
|
|
104
|
+
export declare function sessionIdOf(agent: unknown): string | undefined;
|
|
105
|
+
/**
|
|
106
|
+
* Create the governor listener over one private per-session state map.
|
|
107
|
+
*
|
|
108
|
+
* The returned {@link GovernorListener.handler} is pure wiring around the pure
|
|
109
|
+
* pipeline: read settings, resolve state, run the pipeline, persist the new
|
|
110
|
+
* clock/backlog, emit the row, rewrite the decision.
|
|
111
|
+
*
|
|
112
|
+
* @param deps - settings reader, row sink, debug sink, boot id and stages.
|
|
113
|
+
*/
|
|
114
|
+
export declare function createGovernorListener(deps: GovernorListenerDeps): GovernorListener;
|
|
115
|
+
/** Test/consumer seams of {@link registerGovernorListener}. */
|
|
116
|
+
export interface GovernorListenerOverrides {
|
|
117
|
+
/** Replace the hot settings read (default: the raw user-layer file). */
|
|
118
|
+
readSettings?: () => InputBudgetSettings;
|
|
119
|
+
/** Replace the row sink (default: the input-ledger append sink). */
|
|
120
|
+
emit?: (row: GovernorRow, projectKey?: string | undefined) => void;
|
|
121
|
+
/** Replace the process boot id stamped into rows. */
|
|
122
|
+
gen?: string;
|
|
123
|
+
/** Pre-trim pipeline stages (doc 7); empty in this slice. */
|
|
124
|
+
hooks?: readonly GovernorStageHook<GovernedMessage>[];
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Register the governor on a context — what the preset's `input-budget` row
|
|
128
|
+
* mounts through {@linkcode apply}.
|
|
129
|
+
*
|
|
130
|
+
* The listener is prepended, so it runs outermost among the preset's
|
|
131
|
+
* `agent/pre-step` rewriters and sees the final batch on the way back out.
|
|
132
|
+
*
|
|
133
|
+
* @param ctx - the preset (or any) context mounting the governor.
|
|
134
|
+
* @param overrides - test seam; production callers pass nothing.
|
|
135
|
+
* @returns the release handle that unregisters the listeners.
|
|
136
|
+
*/
|
|
137
|
+
export declare function registerGovernorListener(ctx: Context, overrides?: GovernorListenerOverrides): () => void;
|
|
138
|
+
//# sourceMappingURL=listener.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE/D,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAE3E,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAA;AAEtB,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,oGAAoG;QACpG,WAAW,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;KAChD;CACF;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAA;IACtB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAA;CACpC;AAED,sFAAsF;AACtF,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAA;AAEvF,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,IAAI,EAAE,eAAe,CAAA;IACrB,kFAAkF;IAClF,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,YAAY,IAAI,mBAAmB,CAAA;IACnC;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IAC7D,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAA;IACX,0DAA0D;IAC1D,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,iBAAiB,CAAC,eAAe,CAAC,EAAE,GAAG,SAAS,CAAA;CAClE;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,OAAO,CACL,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC,GACxD,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC,CAAA;IAChD,yEAAyE;IACzE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAA;IAC5D,iFAAiF;IACjF,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAmBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG9D;AAOD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAmHnF;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,mBAAmB,CAAA;IACxC,oEAAoE;IACpE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;IAClE,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,KAAK,CAAC,EAAE,SAAS,iBAAiB,CAAC,eAAe,CAAC,EAAE,CAAA;CACtD;AA+BD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,SAAS,GAAE,yBAA8B,GACxC,MAAM,IAAI,CA6CZ"}
|
package/lib/listener.js
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `agent/pre-step` governor listener — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"Package & seam",
|
|
4
|
+
* §"Defer queue" and §"Failure semantics".
|
|
5
|
+
*
|
|
6
|
+
* One waterfall listener, registered `{ prepend: true }`, delegate-first: it
|
|
7
|
+
* awaits `next()` (so every inner listener produced its decision) and then
|
|
8
|
+
* rewrites the returned decision with `{ ...decision, messages: newBatch }`.
|
|
9
|
+
* The decision is always SPREAD, never reconstructed: harness
|
|
10
|
+
* `PreStepDecision.enter` carries `startsRequestSeries`, and tomorrow's payload
|
|
11
|
+
* may carry more — a rebuilt literal would silently drop them.
|
|
12
|
+
*
|
|
13
|
+
* Per-session state owned here (the reason this is wiring, not core): the
|
|
14
|
+
* monotonic `gateSeq` invocation counter and the defer backlog. The turn-local
|
|
15
|
+
* `step` resets per turn and is never used as a clock.
|
|
16
|
+
*
|
|
17
|
+
* Failure semantics: any exception — settings read, hook, governor — returns
|
|
18
|
+
* the unmodified decision and records `{ error: true }`. Nothing is ever thrown
|
|
19
|
+
* into the waterfall and no protected class is ever dropped.
|
|
20
|
+
*
|
|
21
|
+
* Backlog re-entry happens ONLY through this listener's return value: a
|
|
22
|
+
* deferred message is re-admitted by prepending it to the decision batch, never
|
|
23
|
+
* by `agent.inject`, so no new claimed batches form.
|
|
24
|
+
*
|
|
25
|
+
* Payload/decision faces are declared here as local structural subsets
|
|
26
|
+
* (turn-rules `PreStepPayload` idiom, `packages/interaction/turn-rules/src/wiring.ts:71`)
|
|
27
|
+
* rather than harness imports: the listener reads a session id and a message
|
|
28
|
+
* list, and the merge-extensible harness types stay out of this package.
|
|
29
|
+
*
|
|
30
|
+
* @module @dsh-cc/input-budget/listener
|
|
31
|
+
*/
|
|
32
|
+
import { randomUUID } from 'node:crypto';
|
|
33
|
+
import { createGovernorLedgerSink, cwdProjectKeyOf } from "./ledger.js";
|
|
34
|
+
import { runGovernorPipeline } from "./pipeline.js";
|
|
35
|
+
import { buildGovernorRow } from "./row.js";
|
|
36
|
+
import { DEFAULT_INPUT_BUDGET_SETTINGS, readUserSettingsSync, registerSettings, } from "./settings.js";
|
|
37
|
+
/** Read one untyped value as an object face, or undefined. */
|
|
38
|
+
function objectOf(value) {
|
|
39
|
+
return typeof value === 'object' && value !== null ? value : undefined;
|
|
40
|
+
}
|
|
41
|
+
/** Read one untyped value as a finite integer, or undefined. */
|
|
42
|
+
function intOf(value) {
|
|
43
|
+
return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : undefined;
|
|
44
|
+
}
|
|
45
|
+
/** Read one untyped identifier as a non-empty string, or undefined. */
|
|
46
|
+
function idOf(value) {
|
|
47
|
+
if (typeof value === 'string')
|
|
48
|
+
return value.length > 0 ? value : undefined;
|
|
49
|
+
if (typeof value === 'number' && Number.isFinite(value))
|
|
50
|
+
return String(value);
|
|
51
|
+
return undefined;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Durable session id of an agent face: `session.header.id` first (the harness
|
|
55
|
+
* shape every other dsh-cc listener reads), then the bare `session.id`.
|
|
56
|
+
* @param agent - the payload's agent, of unknown shape.
|
|
57
|
+
* @returns the session id, or undefined when the face carries none.
|
|
58
|
+
*/
|
|
59
|
+
export function sessionIdOf(agent) {
|
|
60
|
+
const session = objectOf(objectOf(agent)?.session);
|
|
61
|
+
return idOf(objectOf(session?.header)?.id) ?? idOf(session?.id);
|
|
62
|
+
}
|
|
63
|
+
/** Best-effort one-line description of a caught failure. */
|
|
64
|
+
function describe(error) {
|
|
65
|
+
return error instanceof Error ? error.message : String(error);
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Create the governor listener over one private per-session state map.
|
|
69
|
+
*
|
|
70
|
+
* The returned {@link GovernorListener.handler} is pure wiring around the pure
|
|
71
|
+
* pipeline: read settings, resolve state, run the pipeline, persist the new
|
|
72
|
+
* clock/backlog, emit the row, rewrite the decision.
|
|
73
|
+
*
|
|
74
|
+
* @param deps - settings reader, row sink, debug sink, boot id and stages.
|
|
75
|
+
*/
|
|
76
|
+
export function createGovernorListener(deps) {
|
|
77
|
+
const sessions = new Map();
|
|
78
|
+
/** This session's state, created on demand — no state is shared across sessions. */
|
|
79
|
+
const stateOfSession = (sessionId) => {
|
|
80
|
+
let state = sessions.get(sessionId);
|
|
81
|
+
if (state === undefined) {
|
|
82
|
+
state = { gateSeq: 0, mode: 'observe', backlog: [] };
|
|
83
|
+
sessions.set(sessionId, state);
|
|
84
|
+
}
|
|
85
|
+
return state;
|
|
86
|
+
};
|
|
87
|
+
/** Run one gate invocation and persist its outcome (throws only to the caller). */
|
|
88
|
+
const governBatch = (payload, decision, settings, sessionId, projectKey) => {
|
|
89
|
+
const state = stateOfSession(sessionId);
|
|
90
|
+
// Flip boundary (plan §"Observe mode"): an observe → enforce flip starts with
|
|
91
|
+
// an empty queue, and an enforce → observe flip clears it — no cross-mode
|
|
92
|
+
// carryover in either direction.
|
|
93
|
+
const flipped = state.mode !== settings.mode;
|
|
94
|
+
const result = runGovernorPipeline({
|
|
95
|
+
messages: decision.messages,
|
|
96
|
+
settings,
|
|
97
|
+
backlog: flipped ? [] : state.backlog,
|
|
98
|
+
gateSeq: state.gateSeq,
|
|
99
|
+
}, deps.hooks ?? []);
|
|
100
|
+
// The mode, the clock and the backlog advance only with a completed
|
|
101
|
+
// invocation, so a throwing invocation leaves the session where it was.
|
|
102
|
+
state.mode = settings.mode;
|
|
103
|
+
state.gateSeq = result.gateSeq;
|
|
104
|
+
state.backlog = result.backlog;
|
|
105
|
+
try {
|
|
106
|
+
deps.emit(buildGovernorRow({
|
|
107
|
+
sessionId,
|
|
108
|
+
gen: deps.gen,
|
|
109
|
+
turn: intOf(payload?.turn),
|
|
110
|
+
step: intOf(payload?.step),
|
|
111
|
+
decision: result.decision,
|
|
112
|
+
}), projectKey);
|
|
113
|
+
}
|
|
114
|
+
catch (error) {
|
|
115
|
+
// The sink is best-effort by contract (a missing ledger must never change
|
|
116
|
+
// admission). It throws only after the state advanced, so it must not be
|
|
117
|
+
// allowed to route this invocation into the failure path — that would
|
|
118
|
+
// return the untrimmed batch while the backlog already holds its trims.
|
|
119
|
+
deps.debug(`input-budget: row dropped: ${describe(error)}`);
|
|
120
|
+
}
|
|
121
|
+
// SPREAD the decision (never rebuild it): `startsRequestSeries` and any
|
|
122
|
+
// future field survive, only the batch is replaced.
|
|
123
|
+
return { ...decision, messages: result.messages };
|
|
124
|
+
};
|
|
125
|
+
return {
|
|
126
|
+
async handler(payload, next) {
|
|
127
|
+
// Delegate first, OUTSIDE the try: if the inner chain already threw, the
|
|
128
|
+
// waterfall is failing and calling `next()` again would run every inner
|
|
129
|
+
// listener a second time (progress-rebuild delivery.ts:151 rationale).
|
|
130
|
+
const decision = await next();
|
|
131
|
+
// Only an `enter` decision carries a batch. A `reject` is not a gate
|
|
132
|
+
// invocation: it must not advance the clock, age the backlog or emit a row
|
|
133
|
+
// for a batch that does not exist.
|
|
134
|
+
if (decision?.kind !== 'enter')
|
|
135
|
+
return decision;
|
|
136
|
+
let sessionId;
|
|
137
|
+
let projectKey;
|
|
138
|
+
let mode = 'observe';
|
|
139
|
+
try {
|
|
140
|
+
sessionId = sessionIdOf(payload?.agent);
|
|
141
|
+
// The ledger's file bucket (cwd-derived), resolved from the same agent
|
|
142
|
+
// face: rows carry none, and a cwd-less header simply yields no bucket.
|
|
143
|
+
projectKey = cwdProjectKeyOf(payload?.agent);
|
|
144
|
+
const settings = deps.readSettings();
|
|
145
|
+
mode = settings.mode;
|
|
146
|
+
// Disabled is a full no-op — no row, no clock tick, no queue change.
|
|
147
|
+
if (!settings.enabled)
|
|
148
|
+
return decision;
|
|
149
|
+
// An unattributable batch has no session clock to age against: never
|
|
150
|
+
// gate it blind, and never emit a row under a guessed session id.
|
|
151
|
+
if (sessionId === undefined)
|
|
152
|
+
return decision;
|
|
153
|
+
return governBatch(payload, decision, settings, sessionId, projectKey);
|
|
154
|
+
}
|
|
155
|
+
catch (error) {
|
|
156
|
+
deps.debug(`input-budget: degraded to passthrough: ${describe(error)}`);
|
|
157
|
+
if (sessionId !== undefined) {
|
|
158
|
+
try {
|
|
159
|
+
deps.emit(buildGovernorRow({
|
|
160
|
+
sessionId,
|
|
161
|
+
gen: deps.gen,
|
|
162
|
+
turn: intOf(payload?.turn),
|
|
163
|
+
step: intOf(payload?.step),
|
|
164
|
+
mode,
|
|
165
|
+
error: true,
|
|
166
|
+
}), projectKey);
|
|
167
|
+
}
|
|
168
|
+
catch (emitError) {
|
|
169
|
+
// The sink is best-effort; a failure there must not escape either.
|
|
170
|
+
deps.debug(`input-budget: error row dropped: ${describe(emitError)}`);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
return decision;
|
|
174
|
+
}
|
|
175
|
+
},
|
|
176
|
+
stateOf(sessionId) {
|
|
177
|
+
return sessions.get(sessionId);
|
|
178
|
+
},
|
|
179
|
+
forget(session) {
|
|
180
|
+
const scope = objectOf(session);
|
|
181
|
+
const sessionId = idOf(scope?.id) ?? idOf(objectOf(scope?.header)?.id);
|
|
182
|
+
if (sessionId !== undefined)
|
|
183
|
+
sessions.delete(sessionId);
|
|
184
|
+
},
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
/** Guarded dsh-home read: cordis throws on the property access itself when absent. */
|
|
188
|
+
function dshHomeOf(ctx) {
|
|
189
|
+
try {
|
|
190
|
+
const resolve = ctx.dshHomePath;
|
|
191
|
+
return resolve === undefined ? undefined : resolve();
|
|
192
|
+
}
|
|
193
|
+
catch {
|
|
194
|
+
return undefined;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Register one listener on the event chain through the untyped surface
|
|
199
|
+
* (input-ledger `mount.ts` idiom): the event name belongs to a harness
|
|
200
|
+
* augmentation this package deliberately does not import.
|
|
201
|
+
*/
|
|
202
|
+
function listen(ctx, event, listener, options) {
|
|
203
|
+
const on = ctx.on;
|
|
204
|
+
return on.call(ctx, event, listener, options);
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Register the governor on a context — what the preset's `input-budget` row
|
|
208
|
+
* mounts through {@linkcode apply}.
|
|
209
|
+
*
|
|
210
|
+
* The listener is prepended, so it runs outermost among the preset's
|
|
211
|
+
* `agent/pre-step` rewriters and sees the final batch on the way back out.
|
|
212
|
+
*
|
|
213
|
+
* @param ctx - the preset (or any) context mounting the governor.
|
|
214
|
+
* @param overrides - test seam; production callers pass nothing.
|
|
215
|
+
* @returns the release handle that unregisters the listeners.
|
|
216
|
+
*/
|
|
217
|
+
export function registerGovernorListener(ctx, overrides = {}) {
|
|
218
|
+
const home = dshHomeOf(ctx);
|
|
219
|
+
const debug = (message) => {
|
|
220
|
+
try {
|
|
221
|
+
ctx.logger.debug(message);
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
// Debug sink failures are swallowed by contract.
|
|
225
|
+
}
|
|
226
|
+
};
|
|
227
|
+
try {
|
|
228
|
+
registerSettings(ctx);
|
|
229
|
+
}
|
|
230
|
+
catch (error) {
|
|
231
|
+
debug(`input-budget: settings namespace registration failed: ${describe(error)}`);
|
|
232
|
+
}
|
|
233
|
+
const listener = createGovernorListener({
|
|
234
|
+
// Hot read per gate invocation: a settings edit applies on the next step.
|
|
235
|
+
// No home (a bare test host) means the ship defaults, i.e. observe mode.
|
|
236
|
+
readSettings: overrides.readSettings
|
|
237
|
+
?? (() => (home === undefined ? DEFAULT_INPUT_BUDGET_SETTINGS : readUserSettingsSync(home))),
|
|
238
|
+
// Row sink: the input-ledger append sink under `<dshHome>/input-ledger/`.
|
|
239
|
+
// A host with no dsh-home keeps the governor running with rows unpersisted
|
|
240
|
+
// (the soft dependency of plan §"GovernorRow"), and every sink failure is
|
|
241
|
+
// contained inside the sink — never into the waterfall.
|
|
242
|
+
emit: overrides.emit ?? createGovernorLedgerSink({ home, debug }),
|
|
243
|
+
gen: overrides.gen ?? randomUUID(),
|
|
244
|
+
debug,
|
|
245
|
+
hooks: overrides.hooks,
|
|
246
|
+
});
|
|
247
|
+
const disposers = [
|
|
248
|
+
// prepend: true — cordis unshifts prepended listeners, so this one runs
|
|
249
|
+
// OUTERMOST and rewrites the decision after every inner listener returned.
|
|
250
|
+
listen(ctx, 'agent/pre-step', listener.handler, { prepend: true }),
|
|
251
|
+
listen(ctx, 'session/disposed', ((session) => {
|
|
252
|
+
listener.forget(session);
|
|
253
|
+
}), undefined),
|
|
254
|
+
];
|
|
255
|
+
return () => {
|
|
256
|
+
for (const dispose of disposers) {
|
|
257
|
+
try {
|
|
258
|
+
dispose();
|
|
259
|
+
}
|
|
260
|
+
catch (error) {
|
|
261
|
+
debug(`input-budget: listener disposal failed: ${describe(error)}`);
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
};
|
|
265
|
+
}
|
|
266
|
+
//# sourceMappingURL=listener.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"listener.js","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The governor pipeline seam — plan doc
|
|
3
|
+
* `docs/plans/2026-11-12-per-step-input-budget-governor.md` §"Dependencies &
|
|
4
|
+
* interactions": the `govern()` order is **dedupe → caps → budget trim**, and
|
|
5
|
+
* doc 7 (injection dedupe / per-class caps) plugs its two stages into this same
|
|
6
|
+
* listener ahead of the trim.
|
|
7
|
+
*
|
|
8
|
+
* This module fixes the ORDER and nothing else: the trim stage IS `govern()`,
|
|
9
|
+
* the two earlier stages are typed hook slots that slice 5 leaves empty. No
|
|
10
|
+
* dedupe and no cap logic lives here — the stages exist so that slice cannot be
|
|
11
|
+
* added as a post-trim patch that would arbitrate against already-charged
|
|
12
|
+
* bytes.
|
|
13
|
+
*
|
|
14
|
+
* @module @dsh-cc/input-budget/pipeline
|
|
15
|
+
*/
|
|
16
|
+
import { type GovernedMessage, type GovernInput, type GovernorSettings, type GovernResult } from './core.ts';
|
|
17
|
+
/** The three ordered stages; `trim` is the budget governor itself. */
|
|
18
|
+
export type GovernorStage = 'dedupe' | 'caps' | 'trim';
|
|
19
|
+
/** The fixed stage order (dedupe → caps → budget trim), as a runtime value. */
|
|
20
|
+
export declare const GOVERNOR_STAGES: readonly GovernorStage[];
|
|
21
|
+
/**
|
|
22
|
+
* One pre-trim stage. A hook sees the batch the listener received — the claimed
|
|
23
|
+
* enter batch after every inner `agent/pre-step` listener ran — and returns the
|
|
24
|
+
* batch the following stage (and finally the trim) evaluates.
|
|
25
|
+
*/
|
|
26
|
+
export interface GovernorStageHook<T extends GovernedMessage = GovernedMessage> {
|
|
27
|
+
/** Which pre-trim stage this hook belongs to. */
|
|
28
|
+
readonly stage: 'dedupe' | 'caps';
|
|
29
|
+
/**
|
|
30
|
+
* Rewrite the fresh batch for this stage.
|
|
31
|
+
* @param messages - the batch produced by the preceding stage.
|
|
32
|
+
* @param settings - the hot-read governor settings of this invocation.
|
|
33
|
+
* @returns the batch the next stage evaluates.
|
|
34
|
+
*/
|
|
35
|
+
run(messages: readonly T[], settings: GovernorSettings): readonly T[];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Run one gate invocation through the pipeline: every registered hook in stage
|
|
39
|
+
* order over the fresh batch, then the budget trim over the result.
|
|
40
|
+
*
|
|
41
|
+
* Hook failures propagate to the caller: the listener contains them by
|
|
42
|
+
* returning the unmodified decision and recording `{ error: true }`, so a
|
|
43
|
+
* broken stage can never half-apply a batch.
|
|
44
|
+
*
|
|
45
|
+
* @param input - the gate invocation: batch, settings, backlog and `gateSeq`.
|
|
46
|
+
* @param hooks - pre-trim stages; empty until doc 7 lands.
|
|
47
|
+
* @returns the same shape {@link govern} returns.
|
|
48
|
+
*/
|
|
49
|
+
export declare function runGovernorPipeline<T extends GovernedMessage>(input: GovernInput<T>, hooks?: readonly GovernorStageHook<T>[]): GovernResult<T>;
|
|
50
|
+
//# sourceMappingURL=pipeline.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAA;AAElB,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;AAEtD,+EAA+E;AAC/E,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAIzC,CAAA;AAEX;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IAC5E,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAA;IACjC;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC,EAAE,CAAA;CACtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EACrB,KAAK,GAAE,SAAS,iBAAiB,CAAC,CAAC,CAAC,EAAO,GAC1C,YAAY,CAAC,CAAC,CAAC,CAUjB"}
|