@residualhq/dsh 0.0.0-stage → 0.0.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/README.md +4 -2
- package/cordis.patch.yml +51 -0
- package/dist/companion.d.ts +28 -0
- package/dist/companion.js +45 -0
- package/dist/engine.d.ts +45 -0
- package/dist/engine.js +200 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/tool-gate-host.d.ts +52 -0
- package/dist/tool-gate-host.js +84 -0
- package/package.json +57 -4
- package/residual-settings.example.yaml +15 -0
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @residualhq/dsh
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
DeepSeek Harness plugin for Residual: layered compaction policy, a local dollar savings ledger, and an optional append-only tool gate.
|
|
4
|
+
|
|
5
|
+
This is not another coding-assistant shell. Prompts stay on the customer's machine. The package is not published yet; install from the monorepo checkout. See the repository root README for install, web vs headless enablement, settings, and the ledger.
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Residual bundle for DeepSeek Harness.
|
|
2
|
+
#
|
|
3
|
+
# Residual subclasses official BasicCompactionEngine. Region selection,
|
|
4
|
+
# tool-pairing balance, summary framing, and the durable compaction
|
|
5
|
+
# transaction stay official. This layer only adds Residual's policy,
|
|
6
|
+
# local savings ledger, and an optional append-only tool gate.
|
|
7
|
+
#
|
|
8
|
+
# ctx.compaction is a single-slot seam: enabling residual-engine means
|
|
9
|
+
# the stock compaction-basic row must be disabled in the same profile.
|
|
10
|
+
# This bundle does not do that for you, and ships residual-engine disabled.
|
|
11
|
+
# Superseding the stock engine is a deployment decision — a bundle that
|
|
12
|
+
# turned itself on without also disabling compaction-basic would run two
|
|
13
|
+
# engines; disabling the stock engine without a replacement would leave
|
|
14
|
+
# none. Enable both changes in the same patch:
|
|
15
|
+
#
|
|
16
|
+
# - id: compaction-basic
|
|
17
|
+
# disabled: true
|
|
18
|
+
#
|
|
19
|
+
# - id: residual-engine
|
|
20
|
+
# disabled: false
|
|
21
|
+
# config:
|
|
22
|
+
# default:
|
|
23
|
+
# threshold: 0.8
|
|
24
|
+
# retain: 0.16
|
|
25
|
+
# providers:
|
|
26
|
+
# deepseek:
|
|
27
|
+
# threshold: 0.5
|
|
28
|
+
# models:
|
|
29
|
+
# - provider: deepseek
|
|
30
|
+
# model: deepseek-chat
|
|
31
|
+
# threshold: 0.9
|
|
32
|
+
#
|
|
33
|
+
# Policy can also live in $DSH_HOME/residual-settings.yaml (partial
|
|
34
|
+
# document; omitted layers keep this mount config). That file is polled
|
|
35
|
+
# so edits apply without a restart.
|
|
36
|
+
#
|
|
37
|
+
# The companion row is a separate, enabled, host-plane row. It does not
|
|
38
|
+
# claim ctx.compaction. name is the bare package, which resolves to the
|
|
39
|
+
# companion entry — never the engine.
|
|
40
|
+
- insert:
|
|
41
|
+
- id: residual-engine
|
|
42
|
+
name: '@residualhq/dsh/engine'
|
|
43
|
+
disabled: true
|
|
44
|
+
|
|
45
|
+
- insert:
|
|
46
|
+
- id: residual-settings
|
|
47
|
+
name: '@residualhq/dsh'
|
|
48
|
+
config:
|
|
49
|
+
default:
|
|
50
|
+
threshold: 0.8
|
|
51
|
+
retain: 0.16
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host-plane settings companion for Residual.
|
|
3
|
+
*
|
|
4
|
+
* Always-enabled. Publishes no `ctx.compaction` service — the engine entry
|
|
5
|
+
* (`@residualhq/dsh/engine`) is the only row that may claim that seam.
|
|
6
|
+
* The browser/host scan discovers enabled loader entries; the engine row
|
|
7
|
+
* ships disabled and is normally mounted inside an agent preset, so this
|
|
8
|
+
* companion exists as a visible, inert host-plane row.
|
|
9
|
+
*
|
|
10
|
+
* Entry id: residual-settings.
|
|
11
|
+
*/
|
|
12
|
+
import { type PolicyDocument } from "@residualhq/core";
|
|
13
|
+
export type ResidualSettingsConfig = PolicyDocument & {
|
|
14
|
+
toolGate?: {
|
|
15
|
+
enabled?: boolean;
|
|
16
|
+
};
|
|
17
|
+
};
|
|
18
|
+
export declare class ResidualSettings {
|
|
19
|
+
/** Own schema so the loader does not inherit any engine Config. */
|
|
20
|
+
static Config: unknown;
|
|
21
|
+
readonly document: PolicyDocument;
|
|
22
|
+
constructor(ctx: {
|
|
23
|
+
logger?: {
|
|
24
|
+
info?(message: string): void;
|
|
25
|
+
};
|
|
26
|
+
}, config?: ResidualSettingsConfig);
|
|
27
|
+
}
|
|
28
|
+
export default ResidualSettings;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host-plane settings companion for Residual.
|
|
3
|
+
*
|
|
4
|
+
* Always-enabled. Publishes no `ctx.compaction` service — the engine entry
|
|
5
|
+
* (`@residualhq/dsh/engine`) is the only row that may claim that seam.
|
|
6
|
+
* The browser/host scan discovers enabled loader entries; the engine row
|
|
7
|
+
* ships disabled and is normally mounted inside an agent preset, so this
|
|
8
|
+
* companion exists as a visible, inert host-plane row.
|
|
9
|
+
*
|
|
10
|
+
* Entry id: residual-settings.
|
|
11
|
+
*/
|
|
12
|
+
import z from "@deepseek-ai/schemastery";
|
|
13
|
+
import { parsePolicyDocument } from "@residualhq/core";
|
|
14
|
+
const ratio = z.number();
|
|
15
|
+
const tokenBudget = z.number();
|
|
16
|
+
const layer = z.object({
|
|
17
|
+
threshold: ratio,
|
|
18
|
+
retain: ratio,
|
|
19
|
+
thresholdTokens: tokenBudget,
|
|
20
|
+
retainTokens: tokenBudget,
|
|
21
|
+
});
|
|
22
|
+
const modelLayer = z.object({
|
|
23
|
+
provider: z.string(),
|
|
24
|
+
model: z.string(),
|
|
25
|
+
threshold: ratio,
|
|
26
|
+
retain: ratio,
|
|
27
|
+
thresholdTokens: tokenBudget,
|
|
28
|
+
retainTokens: tokenBudget,
|
|
29
|
+
});
|
|
30
|
+
export class ResidualSettings {
|
|
31
|
+
/** Own schema so the loader does not inherit any engine Config. */
|
|
32
|
+
static Config = z.object({
|
|
33
|
+
default: layer,
|
|
34
|
+
providers: z.dict(layer),
|
|
35
|
+
models: z.array(modelLayer),
|
|
36
|
+
toolGate: z.object({ enabled: z.boolean() }),
|
|
37
|
+
});
|
|
38
|
+
document;
|
|
39
|
+
constructor(ctx, config = {}) {
|
|
40
|
+
const { toolGate: _toolGate, ...document } = config;
|
|
41
|
+
this.document = parsePolicyDocument(document);
|
|
42
|
+
ctx.logger?.info?.("[residual] settings companion mounted (does not claim ctx.compaction)");
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
export default ResidualSettings;
|
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Residual compaction engine for DeepSeek Harness.
|
|
3
|
+
*
|
|
4
|
+
* Subclasses the official BasicCompactionEngine so region selection, tool
|
|
5
|
+
* pairing, summary framing, and the durable transaction stay official.
|
|
6
|
+
* Residual only decides the layered policy, records a local savings ledger,
|
|
7
|
+
* and (optionally) attaches an append-only tool gate.
|
|
8
|
+
*
|
|
9
|
+
* Entry id: residual-engine. Do not reuse compaction-control ids.
|
|
10
|
+
*/
|
|
11
|
+
import { BasicCompactionEngine } from "@deepseek-ai/dsh-compaction-basic";
|
|
12
|
+
import { SavingsLedger, type PolicyDocument, type Route } from "@residualhq/core";
|
|
13
|
+
import { ResidualToolGateHost } from "./tool-gate-host.ts";
|
|
14
|
+
export type ResidualEngineConfig = PolicyDocument & {
|
|
15
|
+
auto?: boolean;
|
|
16
|
+
toolGate?: {
|
|
17
|
+
enabled?: boolean;
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
export declare class ResidualEngine extends BasicCompactionEngine {
|
|
21
|
+
/**
|
|
22
|
+
* Own schema: inherited statics would otherwise validate Residual's
|
|
23
|
+
* layered document against the parent's official fields.
|
|
24
|
+
*/
|
|
25
|
+
static inject: string[];
|
|
26
|
+
static Config: unknown;
|
|
27
|
+
readonly ledger: SavingsLedger;
|
|
28
|
+
readonly toolGateHost: ResidualToolGateHost;
|
|
29
|
+
private readonly baseDocument;
|
|
30
|
+
private readonly parentDefaults;
|
|
31
|
+
private readonly toolGateEnabled;
|
|
32
|
+
private liveDocument;
|
|
33
|
+
private settingsWatcher;
|
|
34
|
+
constructor(ctx: BasicCompactionEngine["ctx"], config?: ResidualEngineConfig);
|
|
35
|
+
/**
|
|
36
|
+
* Rebuild the official parent config for the current route. Absolute
|
|
37
|
+
* budgets require a declared window; Residual will not guess one.
|
|
38
|
+
*/
|
|
39
|
+
applyPolicy(target: Route, contextWindow?: number): void;
|
|
40
|
+
compactIfNeeded(agent: unknown, trigger: string, signal: AbortSignal): Promise<Awaited<ReturnType<BasicCompactionEngine["compactIfNeeded"]>>>;
|
|
41
|
+
private contextWindowOf;
|
|
42
|
+
private measure;
|
|
43
|
+
private attachToolGate;
|
|
44
|
+
}
|
|
45
|
+
export default ResidualEngine;
|
package/dist/engine.js
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Residual compaction engine for DeepSeek Harness.
|
|
3
|
+
*
|
|
4
|
+
* Subclasses the official BasicCompactionEngine so region selection, tool
|
|
5
|
+
* pairing, summary framing, and the durable transaction stay official.
|
|
6
|
+
* Residual only decides the layered policy, records a local savings ledger,
|
|
7
|
+
* and (optionally) attaches an append-only tool gate.
|
|
8
|
+
*
|
|
9
|
+
* Entry id: residual-engine. Do not reuse compaction-control ids.
|
|
10
|
+
*/
|
|
11
|
+
import { BasicCompactionEngine } from "@deepseek-ai/dsh-compaction-basic";
|
|
12
|
+
import z from "@deepseek-ai/schemastery";
|
|
13
|
+
import { MissingContextWindowError, SavingsLedger, SettingsWatcher, parsePolicyDocument, requireResolvedPolicy, resolvePolicy, residualLedgerPath, residualSavingsPath, residualSettingsPath, toBootOfficialConfig, toOfficialBasicConfig, } from "@residualhq/core";
|
|
14
|
+
import { ResidualToolGateHost } from "./tool-gate-host.js";
|
|
15
|
+
const ratio = z.number();
|
|
16
|
+
const tokenBudget = z.number();
|
|
17
|
+
const layer = z.object({
|
|
18
|
+
threshold: ratio,
|
|
19
|
+
retain: ratio,
|
|
20
|
+
thresholdTokens: tokenBudget,
|
|
21
|
+
retainTokens: tokenBudget,
|
|
22
|
+
});
|
|
23
|
+
const modelLayer = z.object({
|
|
24
|
+
provider: z.string(),
|
|
25
|
+
model: z.string(),
|
|
26
|
+
threshold: ratio,
|
|
27
|
+
retain: ratio,
|
|
28
|
+
thresholdTokens: tokenBudget,
|
|
29
|
+
retainTokens: tokenBudget,
|
|
30
|
+
});
|
|
31
|
+
function documentOf(config) {
|
|
32
|
+
const { auto: _auto, toolGate: _toolGate, ...document } = config ?? {};
|
|
33
|
+
return parsePolicyDocument(document);
|
|
34
|
+
}
|
|
35
|
+
function routeOf(agent) {
|
|
36
|
+
const header = agent?.session?.requestHeader?.();
|
|
37
|
+
const config = header?.config ?? agent?.options;
|
|
38
|
+
if (!config?.provider || !config.model)
|
|
39
|
+
return undefined;
|
|
40
|
+
return { provider: config.provider, model: config.model };
|
|
41
|
+
}
|
|
42
|
+
export class ResidualEngine extends BasicCompactionEngine {
|
|
43
|
+
/**
|
|
44
|
+
* Own schema: inherited statics would otherwise validate Residual's
|
|
45
|
+
* layered document against the parent's official fields.
|
|
46
|
+
*/
|
|
47
|
+
static inject = BasicCompactionEngine.inject;
|
|
48
|
+
static Config = z.object({
|
|
49
|
+
default: layer,
|
|
50
|
+
providers: z.dict(layer),
|
|
51
|
+
models: z.array(modelLayer),
|
|
52
|
+
auto: z.boolean(),
|
|
53
|
+
toolGate: z.object({ enabled: z.boolean() }),
|
|
54
|
+
});
|
|
55
|
+
ledger;
|
|
56
|
+
toolGateHost;
|
|
57
|
+
baseDocument;
|
|
58
|
+
parentDefaults;
|
|
59
|
+
toolGateEnabled;
|
|
60
|
+
liveDocument;
|
|
61
|
+
settingsWatcher;
|
|
62
|
+
constructor(ctx, config = {}) {
|
|
63
|
+
const baseDocument = documentOf(config);
|
|
64
|
+
// Construction has no route window yet. Do not require absolute fields
|
|
65
|
+
// to convert here — that would keep the plugin from activating.
|
|
66
|
+
const baseline = resolvePolicy(baseDocument, { provider: "", model: "" });
|
|
67
|
+
super(ctx, { ...toBootOfficialConfig(baseline), auto: config.auto ?? true });
|
|
68
|
+
this.parentDefaults = { ...this.config };
|
|
69
|
+
this.baseDocument = baseDocument;
|
|
70
|
+
this.toolGateEnabled = config.toolGate?.enabled === true;
|
|
71
|
+
this.toolGateHost = new ResidualToolGateHost();
|
|
72
|
+
this.ledger = new SavingsLedger({
|
|
73
|
+
file: residualLedgerPath(),
|
|
74
|
+
summaryFile: residualSavingsPath(),
|
|
75
|
+
host: "dsh",
|
|
76
|
+
});
|
|
77
|
+
this.settingsWatcher = new SettingsWatcher({
|
|
78
|
+
base: this.baseDocument,
|
|
79
|
+
file: residualSettingsPath(),
|
|
80
|
+
onChange: (live) => {
|
|
81
|
+
this.liveDocument = live.document;
|
|
82
|
+
},
|
|
83
|
+
onError: (error) => {
|
|
84
|
+
this.ctx.logger?.warn?.(`[residual] residual-settings.yaml unreadable (${error.message}); keeping the last good policy`);
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
this.liveDocument = this.settingsWatcher.current().document;
|
|
88
|
+
const stop = this.settingsWatcher.start();
|
|
89
|
+
this.ctx.effect?.(() => stop);
|
|
90
|
+
if (this.toolGateEnabled)
|
|
91
|
+
this.attachToolGate();
|
|
92
|
+
const threshold = baseline.thresholdTokens ?? baseline.thresholdRatio;
|
|
93
|
+
this.ctx.logger?.info?.(`[residual] engine up: threshold=${String(threshold)} auto=${config.auto ?? true} toolGate=${this.toolGateEnabled}`);
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Rebuild the official parent config for the current route. Absolute
|
|
97
|
+
* budgets require a declared window; Residual will not guess one.
|
|
98
|
+
*/
|
|
99
|
+
applyPolicy(target, contextWindow) {
|
|
100
|
+
const policy = resolvePolicy(this.liveDocument, target, contextWindow);
|
|
101
|
+
for (const warning of policy.warnings)
|
|
102
|
+
this.ctx.logger?.warn?.(`[residual] ${warning.message}`);
|
|
103
|
+
requireResolvedPolicy(policy);
|
|
104
|
+
const official = toOfficialBasicConfig(policy);
|
|
105
|
+
const next = {
|
|
106
|
+
...this.parentDefaults,
|
|
107
|
+
...official,
|
|
108
|
+
};
|
|
109
|
+
if (official.retainTokens !== undefined)
|
|
110
|
+
delete next.retainRatio;
|
|
111
|
+
else
|
|
112
|
+
delete next.retainTokens;
|
|
113
|
+
this.config = next;
|
|
114
|
+
}
|
|
115
|
+
async compactIfNeeded(agent, trigger, signal) {
|
|
116
|
+
const typed = agent;
|
|
117
|
+
const target = routeOf(agent);
|
|
118
|
+
const window = target === undefined ? undefined : await this.contextWindowOf(target, signal);
|
|
119
|
+
if (target !== undefined) {
|
|
120
|
+
try {
|
|
121
|
+
this.applyPolicy(target, window);
|
|
122
|
+
}
|
|
123
|
+
catch (error) {
|
|
124
|
+
if (error instanceof MissingContextWindowError)
|
|
125
|
+
throw error;
|
|
126
|
+
throw error;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
const before = this.measure(typed);
|
|
130
|
+
let result = null;
|
|
131
|
+
let thrown;
|
|
132
|
+
try {
|
|
133
|
+
result = await super.compactIfNeeded(agent, trigger, signal);
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
thrown = error;
|
|
137
|
+
}
|
|
138
|
+
const measuredAfter = this.measure(typed);
|
|
139
|
+
// Official compaction may shrink the surface and still throw (for example,
|
|
140
|
+
// "still above threshold after N attempts"). Record any real shrink so the
|
|
141
|
+
// savings ledger is not lost on that path.
|
|
142
|
+
const tokensAfter = measuredAfter ??
|
|
143
|
+
(result !== null && before !== undefined
|
|
144
|
+
? Math.max(0, before - (result.shadowedTokenCount ?? 0))
|
|
145
|
+
: undefined);
|
|
146
|
+
if (before !== undefined && tokensAfter !== undefined && tokensAfter < before) {
|
|
147
|
+
const row = this.ledger.record({
|
|
148
|
+
tokensBefore: before,
|
|
149
|
+
tokensAfter,
|
|
150
|
+
sessionId: typed.session?.id,
|
|
151
|
+
provider: target?.provider,
|
|
152
|
+
model: target?.model,
|
|
153
|
+
});
|
|
154
|
+
const saved = this.ledger.tokensSaved(typed.session?.id === undefined ? {} : { sessionId: typed.session.id });
|
|
155
|
+
const line = this.ledger.formatRecordLine(row, saved);
|
|
156
|
+
this.ctx.logger?.info?.(line);
|
|
157
|
+
process.stderr.write(`${line}\n`);
|
|
158
|
+
}
|
|
159
|
+
if (thrown !== undefined)
|
|
160
|
+
throw thrown;
|
|
161
|
+
return result;
|
|
162
|
+
}
|
|
163
|
+
async contextWindowOf(target, signal) {
|
|
164
|
+
const info = await this.ctx.llm?.resolveModelInfo?.(target.provider, target.model, signal);
|
|
165
|
+
const window = info?.context?.contextWindow;
|
|
166
|
+
return typeof window === "number" && Number.isFinite(window) && window > 0 ? window : undefined;
|
|
167
|
+
}
|
|
168
|
+
measure(agent) {
|
|
169
|
+
try {
|
|
170
|
+
const total = this.ctx.tokenMeter?.measure?.(agent.session)?.totalTokens;
|
|
171
|
+
return typeof total === "number" && Number.isFinite(total) ? total : undefined;
|
|
172
|
+
}
|
|
173
|
+
catch {
|
|
174
|
+
return undefined;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
attachToolGate() {
|
|
178
|
+
const tools = this.ctx.tools;
|
|
179
|
+
if (!tools || typeof tools.schemas !== "function") {
|
|
180
|
+
this.ctx.logger?.warn?.("[residual] toolGate is enabled but ctx.tools.schemas is unavailable; catalog not attached");
|
|
181
|
+
return;
|
|
182
|
+
}
|
|
183
|
+
this.toolGateHost.snapshotCatalog(tools);
|
|
184
|
+
this.ctx.on?.("agent/pre-step", (event, next) => {
|
|
185
|
+
const session = event.agent?.session;
|
|
186
|
+
const agentTools = event.agent?.ctx?.tools;
|
|
187
|
+
if (session && agentTools) {
|
|
188
|
+
try {
|
|
189
|
+
this.toolGateHost.hideUnloadedMcpTools(session, agentTools);
|
|
190
|
+
}
|
|
191
|
+
catch (error) {
|
|
192
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
193
|
+
this.ctx.logger?.warn?.(`[residual] tool gate hide skipped: ${message}`);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
return next();
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
export default ResidualEngine;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Default package entry for @residualhq/dsh.
|
|
3
|
+
*
|
|
4
|
+
* The DSH loader mounts `exports.default` and has no entry option, so the
|
|
5
|
+
* bare package name must resolve to the settings companion — never the
|
|
6
|
+
* engine. The engine lives at `@residualhq/dsh/engine`.
|
|
7
|
+
*/
|
|
8
|
+
export { ResidualSettings, ResidualSettings as default } from "./companion.ts";
|
|
9
|
+
export type { ResidualSettingsConfig } from "./companion.ts";
|
|
10
|
+
export { ResidualToolGateHost } from "./tool-gate-host.ts";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Default package entry for @residualhq/dsh.
|
|
3
|
+
*
|
|
4
|
+
* The DSH loader mounts `exports.default` and has no entry option, so the
|
|
5
|
+
* bare package name must resolve to the settings companion — never the
|
|
6
|
+
* engine. The engine lives at `@residualhq/dsh/engine`.
|
|
7
|
+
*/
|
|
8
|
+
export { ResidualSettings, ResidualSettings as default } from "./companion.js";
|
|
9
|
+
export { ResidualToolGateHost } from "./tool-gate-host.js";
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host adapter that applies Residual's append-only ToolGate to a DSH
|
|
3
|
+
* `ctx.tools` / `agent.ctx.tools` surface.
|
|
4
|
+
*
|
|
5
|
+
* Official KV-cache guidance is append-only: newly visible tools may follow
|
|
6
|
+
* a reusable prefix, but hiding a tool mid-session can invalidate the cache.
|
|
7
|
+
* This adapter snapshots definitions, may hide unused `mcp__*` tools once
|
|
8
|
+
* before the first model call, and then only registers newly loaded tools
|
|
9
|
+
* in the agent scope. It never unloads, never rebuilds a deny list, and
|
|
10
|
+
* never reorders.
|
|
11
|
+
*/
|
|
12
|
+
import { ToolGate, type ToolCatalogEntry } from "@residualhq/core";
|
|
13
|
+
export type ToolSchemaView = {
|
|
14
|
+
name: string;
|
|
15
|
+
description?: string;
|
|
16
|
+
parameters?: unknown;
|
|
17
|
+
};
|
|
18
|
+
export type ToolsHost = {
|
|
19
|
+
schemas?: (scope?: unknown) => ToolSchemaView[];
|
|
20
|
+
get?: (name: string, scope?: unknown) => unknown;
|
|
21
|
+
register?: (definition: unknown, options?: unknown) => unknown;
|
|
22
|
+
restrict?: (filter: {
|
|
23
|
+
deny?: string[];
|
|
24
|
+
allow?: string[];
|
|
25
|
+
}) => unknown;
|
|
26
|
+
};
|
|
27
|
+
export type HideOptions = {
|
|
28
|
+
/** Tool ids that stay visible even if they have not been load()ed yet. */
|
|
29
|
+
eager?: string[];
|
|
30
|
+
};
|
|
31
|
+
export declare class ResidualToolGateHost {
|
|
32
|
+
readonly gate: ToolGate;
|
|
33
|
+
private readonly definitions;
|
|
34
|
+
private readonly sessionsHidden;
|
|
35
|
+
constructor(gate?: ToolGate);
|
|
36
|
+
/** Capture the current global (or provided) registry as a catalog. */
|
|
37
|
+
snapshotCatalog(tools: ToolsHost): ToolCatalogEntry[];
|
|
38
|
+
/**
|
|
39
|
+
* Once per session object, hide unused MCP tools. Safe only before the
|
|
40
|
+
* first model-facing tool list is sent. Subsequent calls are no-ops.
|
|
41
|
+
*/
|
|
42
|
+
hideUnloadedMcpTools(session: object, agentTools: ToolsHost, options?: HideOptions): string[];
|
|
43
|
+
/**
|
|
44
|
+
* Append a tool to the session list and, when the host allows it, register
|
|
45
|
+
* the original definition on the agent-scoped registry. Never touches deny.
|
|
46
|
+
*/
|
|
47
|
+
load(agentTools: ToolsHost, toolId: string): {
|
|
48
|
+
appended: boolean;
|
|
49
|
+
index: number;
|
|
50
|
+
};
|
|
51
|
+
search(query: string): ToolCatalogEntry[];
|
|
52
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host adapter that applies Residual's append-only ToolGate to a DSH
|
|
3
|
+
* `ctx.tools` / `agent.ctx.tools` surface.
|
|
4
|
+
*
|
|
5
|
+
* Official KV-cache guidance is append-only: newly visible tools may follow
|
|
6
|
+
* a reusable prefix, but hiding a tool mid-session can invalidate the cache.
|
|
7
|
+
* This adapter snapshots definitions, may hide unused `mcp__*` tools once
|
|
8
|
+
* before the first model call, and then only registers newly loaded tools
|
|
9
|
+
* in the agent scope. It never unloads, never rebuilds a deny list, and
|
|
10
|
+
* never reorders.
|
|
11
|
+
*/
|
|
12
|
+
import { ToolGate } from "@residualhq/core";
|
|
13
|
+
function oneLine(text) {
|
|
14
|
+
const line = text.replace(/\s+/g, " ").trim();
|
|
15
|
+
return line;
|
|
16
|
+
}
|
|
17
|
+
export class ResidualToolGateHost {
|
|
18
|
+
gate;
|
|
19
|
+
definitions = new Map();
|
|
20
|
+
sessionsHidden = new WeakSet();
|
|
21
|
+
constructor(gate = new ToolGate()) {
|
|
22
|
+
this.gate = gate;
|
|
23
|
+
}
|
|
24
|
+
/** Capture the current global (or provided) registry as a catalog. */
|
|
25
|
+
snapshotCatalog(tools) {
|
|
26
|
+
const schemas = tools.schemas?.() ?? [];
|
|
27
|
+
for (const schema of schemas) {
|
|
28
|
+
const definition = tools.get?.(schema.name);
|
|
29
|
+
if (definition !== undefined)
|
|
30
|
+
this.definitions.set(schema.name, definition);
|
|
31
|
+
const knownSchema = definition ?? schema.parameters ?? schema;
|
|
32
|
+
this.gate.addToCatalog({
|
|
33
|
+
id: schema.name,
|
|
34
|
+
name: schema.name,
|
|
35
|
+
summary: oneLine(schema.description ?? schema.name),
|
|
36
|
+
schema: knownSchema,
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
return this.gate.catalog();
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Once per session object, hide unused MCP tools. Safe only before the
|
|
43
|
+
* first model-facing tool list is sent. Subsequent calls are no-ops.
|
|
44
|
+
*/
|
|
45
|
+
hideUnloadedMcpTools(session, agentTools, options = {}) {
|
|
46
|
+
if (this.sessionsHidden.has(session))
|
|
47
|
+
return [];
|
|
48
|
+
if (typeof agentTools.restrict !== "function") {
|
|
49
|
+
throw new Error("Residual tool gate: host tools.restrict is unavailable; cannot hide unused MCP tools");
|
|
50
|
+
}
|
|
51
|
+
const eager = new Set([
|
|
52
|
+
...this.gate.listLoaded().map((tool) => tool.id),
|
|
53
|
+
...(options.eager ?? []),
|
|
54
|
+
]);
|
|
55
|
+
const deny = this.gate
|
|
56
|
+
.catalog()
|
|
57
|
+
.map((entry) => entry.id)
|
|
58
|
+
.filter((id) => id.startsWith("mcp__") && !eager.has(id));
|
|
59
|
+
if (deny.length > 0)
|
|
60
|
+
agentTools.restrict({ deny });
|
|
61
|
+
this.sessionsHidden.add(session);
|
|
62
|
+
return deny;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Append a tool to the session list and, when the host allows it, register
|
|
66
|
+
* the original definition on the agent-scoped registry. Never touches deny.
|
|
67
|
+
*/
|
|
68
|
+
load(agentTools, toolId) {
|
|
69
|
+
const definition = this.definitions.get(toolId);
|
|
70
|
+
const result = this.gate.load(toolId);
|
|
71
|
+
if (result.appended && definition !== undefined && typeof agentTools.register === "function") {
|
|
72
|
+
agentTools.register(definition);
|
|
73
|
+
}
|
|
74
|
+
return result;
|
|
75
|
+
}
|
|
76
|
+
search(query) {
|
|
77
|
+
const needle = query.trim().toLowerCase();
|
|
78
|
+
if (needle.length === 0)
|
|
79
|
+
return this.gate.catalog();
|
|
80
|
+
return this.gate.catalog().filter((entry) => {
|
|
81
|
+
return entry.id.toLowerCase().includes(needle) || entry.summary.toLowerCase().includes(needle);
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@residualhq/dsh",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"description": "Residual DeepSeek Harness plugin: layered compaction policy, local savings ledger, append-only tool gate.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./dist/index.js",
|
|
11
|
+
"./engine": "./dist/engine.js",
|
|
12
|
+
"./package.json": "./package.json"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"cordis.patch.yml",
|
|
17
|
+
"residual-settings.example.yaml",
|
|
18
|
+
"README.md"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "tsc -p tsconfig.json",
|
|
22
|
+
"test": "node --test --experimental-strip-types test/*.test.ts"
|
|
23
|
+
},
|
|
24
|
+
"keywords": [
|
|
25
|
+
"dsh",
|
|
26
|
+
"dsh-plugin",
|
|
27
|
+
"deepseek-harness",
|
|
28
|
+
"compaction",
|
|
29
|
+
"token-savings"
|
|
30
|
+
],
|
|
31
|
+
"dependencies": {
|
|
32
|
+
"@residualhq/core": "0.0.1"
|
|
33
|
+
},
|
|
34
|
+
"peerDependencies": {
|
|
35
|
+
"@deepseek-ai/dsh-compaction-basic": ">=0.2.2-0 <0.3.0-0",
|
|
36
|
+
"@deepseek-ai/schemastery": ">=3.18.0"
|
|
37
|
+
},
|
|
38
|
+
"peerDependenciesMeta": {
|
|
39
|
+
"@deepseek-ai/dsh-compaction-basic": {
|
|
40
|
+
"optional": true
|
|
41
|
+
},
|
|
42
|
+
"@deepseek-ai/schemastery": {
|
|
43
|
+
"optional": true
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"dsh": {
|
|
47
|
+
"manifestVersion": 1,
|
|
48
|
+
"bundle": {
|
|
49
|
+
"patch": "./cordis.patch.yml"
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
"engines": {
|
|
53
|
+
"node": ">=20",
|
|
54
|
+
"dsh": ">=0.2.2-0 <0.3.0-0"
|
|
55
|
+
},
|
|
56
|
+
"publishConfig": {
|
|
57
|
+
"access": "public"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Copy to $DSH_HOME/residual-settings.yaml (usually ~/.dsh/residual-settings.yaml).
|
|
2
|
+
# This is a partial document: keys you omit keep the mount-row / composition values,
|
|
3
|
+
# so a small edit cannot wipe model-specific policies.
|
|
4
|
+
residual:
|
|
5
|
+
default:
|
|
6
|
+
threshold: 0.8
|
|
7
|
+
retain: 0.16
|
|
8
|
+
# providers:
|
|
9
|
+
# deepseek:
|
|
10
|
+
# threshold: 0.5
|
|
11
|
+
# models:
|
|
12
|
+
# - provider: deepseek
|
|
13
|
+
# model: deepseek-chat
|
|
14
|
+
# thresholdTokens: 80000
|
|
15
|
+
# retainTokens: 16000
|