dsh-boost 0.1.3 → 0.1.4
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.en.md +113 -62
- package/README.md +84 -45
- package/dist/admission/usage.js +12 -2
- package/dist/admission/usage.js.map +1 -1
- package/dist/hooks/llm-stream.js +18 -1
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +27 -13
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/projection/apply.js +11 -2
- package/dist/projection/apply.js.map +1 -1
- package/dist/projection/truncate.js +27 -10
- package/dist/projection/truncate.js.map +1 -1
- package/package.json +3 -2
package/dist/projection/apply.js
CHANGED
|
@@ -10,7 +10,16 @@ function omissionNote(omittedBytes) {
|
|
|
10
10
|
* locator text is not known before that write, this is a lower bound.
|
|
11
11
|
*/
|
|
12
12
|
function projectedText(truncation) {
|
|
13
|
-
return `${renderHeadLine(truncation)}\n${truncation.head}\n${omissionNote(truncation.omittedBytes)}\n${truncation.tail}`;
|
|
13
|
+
return `${renderHeadLine(truncation)}\n${truncation.head}\n${omissionNote(truncation.omittedBytes)}\n${truncation.tail}${signalSuffix(truncation)}`;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* The marker lines `truncate` rescued from the cut-away middle, appended after
|
|
17
|
+
* the tail so the model still sees an exit code or error flag that would
|
|
18
|
+
* otherwise be lost (design §5.4-4). Empty for the overwhelming majority.
|
|
19
|
+
*/
|
|
20
|
+
function signalSuffix(truncation) {
|
|
21
|
+
const signals = truncation.signals ?? [];
|
|
22
|
+
return signals.length === 0 ? '' : `\n${signals.join('\n')}`;
|
|
14
23
|
}
|
|
15
24
|
/** Price the original and the replacement together, so the pair always agrees. */
|
|
16
25
|
function measure(original, replacement, estimate) {
|
|
@@ -110,7 +119,7 @@ export async function projectApply(input) {
|
|
|
110
119
|
});
|
|
111
120
|
phase = 'footer';
|
|
112
121
|
const footer = formatFooter({ kind: 'exact', count: truncation.omittedBytes }, ref);
|
|
113
|
-
const assembled = `${renderHeadLine(truncation)}\n${truncation.head}\n${footer}\n${truncation.tail}`;
|
|
122
|
+
const assembled = `${renderHeadLine(truncation)}\n${truncation.head}\n${footer}\n${truncation.tail}${signalSuffix(truncation)}`;
|
|
114
123
|
// The footer is only known after the write, so this check can only run now.
|
|
115
124
|
// The backend exposes no delete: a spill that reaches this point stays in
|
|
116
125
|
// the store, unreferenced, while the model gets the original content back.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/projection/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projection execution: the shadow accounting and the real replacement.\n *\n * `projectShadow` is the half of projection that never changes what the model\n * sees: it decides whether a receipt *would* be cut, composes the replacement\n * string `projectApply` would produce, and prices both sides in tokens through\n * the caller's `estimate`. It writes nothing and reads no host service, so the\n * caller alone decides which mode to invoke (design §5.4).\n *\n * `projectApply` is the half that replaces, and it only replaces what is still\n * recoverable: the canonical receipt is persisted through the injected spill\n * backend first, then head line, head, spill footer and tail are composed. All\n * guards run before the write, a failed write or footer is a skip rather than\n * an exception, and a footer that would grow the receipt sends the original\n * back unchanged — a projection that grows a receipt defeats the plugin's\n * premise.\n *\n * The projected size is composed here, not read off `Truncation.after`:\n * `after` is the head line plus the two windows *without* the omission note, so\n * it is only a lower bound on the final replacement. Shadow mode prices\n * `renderHeadLine + head + omission note + tail`; the note's locator part is\n * unknown before the spill write, so only the standardized omission clause is\n * included.\n *\n * Skip reasons are stable codes, never prose: `error-receipt` (an error receipt\n * is evidence and is never projected), `family-not-configured` (the family has\n * no window), `not-worth-it` (`truncate`'s guard said no, or the footer left no\n * net gain), `empty` (shadow's empty receipt), and on the apply half\n * `no-spill`, `no-owner`, `projection-skipped:no-footer`, `spill-failed`, and\n * `footer-failed`.\n *\n * @module dsh-boost/projection/apply\n */\nimport type { BoostConfig, ProjectionParams, ToolFamily } from '../types.js'\nimport { renderHeadLine, truncate } from './truncate.js'\nimport type { Truncation } from './truncate.js'\n\n/** Which projection behaviour the caller is running. */\nexport type ProjectionMode = 'off' | 'shadow' | 'on'\n\n/** What projection did, or would have done, to one receipt. */\nexport interface ProjectionOutcome {\n kind: 'skipped' | 'shadow' | 'applied'\n /** Stable skip code; present only when `kind === 'skipped'`. */\n reason?: string\n /**\n * Tokens in the original receipt.\n *\n * Present only when `kind === 'shadow'` and the estimator priced both\n * sides; absent (with `estimate: 'unknown'` on the receipt) when it did not.\n */\n before?: number\n /** Tokens in the replacement shadow mode would have produced. */\n after?: number\n /** `before - after`. */\n saved?: number\n /**\n * UTF-8 bytes the replacement omits; present only when `kind === 'applied'`.\n *\n * Apply mode has no token estimator: the caller (T23b) prices both texts\n * itself, and these two fields are the projection's own accounting.\n */\n omittedBytes?: number\n /** Unicode code points the replacement omits; applied outcomes only. */\n omittedCodePoints?: number\n /**\n * The persisted artifact's locator; applied outcomes only.\n *\n * It is the path the footer tells the model to read, and the retrieval ledger\n * matches later `read`/`grep` arguments against it (Task 25).\n */\n locator?: string\n}\n\n/** A persisted spill artifact's model-facing handle. */\nexport interface SpillHandle {\n /** Opaque locator the model can `read` or `grep`; never parsed here. */\n locator: string\n /** How to retrieve the artifact, as guidance for the model. */\n retrievalHint: string\n}\n\n/**\n * The host spill store, narrowed to the one method projection needs.\n *\n * `callId` and `label` are required because the host's `SaveTextSpill` requires\n * them; `projectApply` fills them in before calling. `saveText` rejects on a\n * real storage failure, and that rejection is handled as a skip.\n */\nexport interface SpillBackend {\n saveText(input: {\n owner: { sessionId: string }\n source: { kind: 'tool'; toolName: string; callId: string; label: string }\n suggestedName: string\n content: string\n }): Promise<SpillHandle>\n}\n\n/**\n * Render the footer that names what was omitted and where the original lives.\n *\n * Injected by the caller, which dynamically imports the host's\n * `formatSpillNotice`; this module must never statically import\n * `@deepseek-ai/dsh-spill-policy` — it is not declared as a dependency, and a static import\n * would make the degradation path unreachable (design §5.4).\n */\nexport type FormatFooter = (omitted: { kind: 'exact'; count: number }, ref: SpillHandle) => string\n\n/** Everything one apply decision reads; every host service arrives pre-bound. */\nexport interface ProjectApplyInput {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Owning session; without one the spill has no owner and projection stops. */\n sessionId: string | undefined\n /** Tool name, recorded on the spill source and used for its file name. */\n toolName: string\n /** Model-issued call id; defaults to `toolName`. */\n callId?: string\n /** Human label for the artifact; defaults to `family`. */\n label?: string\n /** Spill backend, absent when the host has none (projection then stops). */\n spill: SpillBackend | undefined\n /** Footer renderer, absent when the host spill policy package is not installed. */\n formatFooter: FormatFooter | undefined\n}\n\n/** The omission clause of the spill footer; the locator is unknown here. */\nfunction omissionNote(omittedBytes: number): string {\n return `(Omitted ${omittedBytes} bytes.)`\n}\n\n/**\n * The replacement shadow mode prices: head line, head, omission note, tail.\n *\n * `projectApply` replaces the note with the persisted spill footer; because the\n * locator text is not known before that write, this is a lower bound.\n */\nfunction projectedText(truncation: Truncation): string {\n return `${renderHeadLine(truncation)}\\n${truncation.head}\\n${omissionNote(truncation.omittedBytes)}\\n${truncation.tail}`\n}\n\n/** Price the original and the replacement together, so the pair always agrees. */\nfunction measure(\n original: string,\n replacement: string,\n estimate: (s: string) => number,\n): Pick<ProjectionOutcome, 'before' | 'after' | 'saved'> | undefined {\n const before = estimate(original)\n const after = estimate(replacement)\n // A non-finite estimate is an unknown, never a number to serialise: JSON\n // would turn NaN into `null`, which looks like a measured zero in the\n // shadow account. The caller writes `estimate: 'unknown'` instead.\n if (!Number.isFinite(before) || !Number.isFinite(after)) return undefined\n return { before, after, saved: before - after }\n}\n\n/**\n * Report what projection would save, without touching the receipt.\n *\n * Guards run in a fixed order: an error receipt is skipped before anything\n * else, so even an empty or oversized error keeps its evidence (design §5.4\n * contract 4); then empty text; then a family with no configured window; then\n * `truncate`'s own decision (trigger, 256 KiB cap, net-gain guard).\n */\nexport async function projectShadow(input: {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Token estimator injected by the caller (never imported from the host). */\n estimate: (s: string) => number\n}): Promise<ProjectionOutcome> {\n const { text, isError, family, cfg, estimate } = input\n\n if (isError) return { kind: 'skipped', reason: 'error-receipt' }\n if (text === '') return { kind: 'skipped', reason: 'empty' }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { kind: 'skipped', reason: 'family-not-configured' }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { kind: 'skipped', reason: 'not-worth-it' }\n\n const measured = measure(text, projectedText(truncation), estimate)\n return measured === undefined ? { kind: 'shadow' } : { kind: 'shadow', ...measured }\n}\n\n/** The prechecks that passed, with the host pieces narrowed to their present values. */\ninterface Ready {\n truncation: Truncation\n owner: { sessionId: string }\n spill: SpillBackend\n formatFooter: FormatFooter\n}\n\n/**\n * Decide whether the receipt may be replaced, in the plan's fixed order.\n *\n * Every guard returns the intact receipt and a stable code: an error receipt\n * first (it is evidence, design §5.4 contract 4); then a family with no window;\n * then `truncate`'s decision — calling it once is the same decision\n * `shouldTruncate` exposes, without cutting twice; then the host pieces that\n * would make the footer a lie: no backend, no owner, no footer renderer. None\n * of these writes anything.\n */\nfunction precheck(input: ProjectApplyInput): { skip: ProjectionOutcome } | Ready {\n const { text, isError, family, cfg, sessionId, spill, formatFooter } = input\n\n if (isError) return { skip: { kind: 'skipped', reason: 'error-receipt' } }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { skip: { kind: 'skipped', reason: 'family-not-configured' } }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { skip: { kind: 'skipped', reason: 'not-worth-it' } }\n\n if (!spill) return { skip: { kind: 'skipped', reason: 'no-spill' } }\n if (!sessionId) return { skip: { kind: 'skipped', reason: 'no-owner' } }\n if (!formatFooter) return { skip: { kind: 'skipped', reason: 'projection-skipped:no-footer' } }\n\n return { truncation, owner: { sessionId }, spill, formatFooter }\n}\n\n/**\n * Replace an oversized receipt with its head, tail, and a way back to the rest.\n *\n * The canonical original is spilled *before* anything is replaced — never the\n * projection, which would make the footer point at an artifact that does not\n * contain what it promises. The footer sits on its own line between the two\n * windows, and the composed replacement is re-checked against the original:\n * at the trigger boundary a long locator can make the \"projection\" longer than\n * the receipt it replaces, and a projection that grows a receipt is worse than\n * none.\n *\n * A spill or footer failure is swallowed and reported as `spill-failed` /\n * `footer-failed`; the caller's `post-execute` hook must never see an exception\n * from here. The footer must be guarded too: the host turns a throwing\n * `post-execute` listener into an `isError` result, which would lose the very\n * output this module exists to preserve.\n */\nexport async function projectApply(\n input: ProjectApplyInput,\n): Promise<{ content: string; outcome: ProjectionOutcome }> {\n const ready = precheck(input)\n if ('skip' in ready) return { content: input.text, outcome: ready.skip }\n\n const { text, family, toolName, callId, label } = input\n const { truncation, owner, spill, formatFooter } = ready\n\n // One guard covers both host calls: `saveText` and the footer renderer. The\n // marker tells the two failures apart, because status counts distinguish\n // them — and neither may reach the caller as an exception.\n let phase: 'spill' | 'footer' = 'spill'\n try {\n const ref = await spill.saveText({\n owner,\n source: { kind: 'tool', toolName, callId: callId ?? toolName, label: label ?? family },\n suggestedName: `${toolName}.txt`,\n content: text,\n })\n phase = 'footer'\n\n const footer = formatFooter({ kind: 'exact', count: truncation.omittedBytes }, ref)\n const assembled = `${renderHeadLine(truncation)}\\n${truncation.head}\\n${footer}\\n${truncation.tail}`\n\n // The footer is only known after the write, so this check can only run now.\n // The backend exposes no delete: a spill that reaches this point stays in\n // the store, unreferenced, while the model gets the original content back.\n if (assembled.length >= text.length) {\n return { content: text, outcome: { kind: 'skipped', reason: 'not-worth-it' } }\n }\n\n return {\n content: assembled,\n outcome: {\n kind: 'applied',\n omittedBytes: truncation.omittedBytes,\n omittedCodePoints: truncation.omittedCodePoints,\n locator: ref.locator,\n },\n }\n } catch {\n return {\n content: text,\n outcome: { kind: 'skipped', reason: phase === 'spill' ? 'spill-failed' : 'footer-failed' },\n }\n }\n}\n"]}
|
|
1
|
+
{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/projection/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projection execution: the shadow accounting and the real replacement.\n *\n * `projectShadow` is the half of projection that never changes what the model\n * sees: it decides whether a receipt *would* be cut, composes the replacement\n * string `projectApply` would produce, and prices both sides in tokens through\n * the caller's `estimate`. It writes nothing and reads no host service, so the\n * caller alone decides which mode to invoke (design §5.4).\n *\n * `projectApply` is the half that replaces, and it only replaces what is still\n * recoverable: the canonical receipt is persisted through the injected spill\n * backend first, then head line, head, spill footer and tail are composed. All\n * guards run before the write, a failed write or footer is a skip rather than\n * an exception, and a footer that would grow the receipt sends the original\n * back unchanged — a projection that grows a receipt defeats the plugin's\n * premise.\n *\n * The projected size is composed here, not read off `Truncation.after`:\n * `after` is the head line plus the two windows *without* the omission note, so\n * it is only a lower bound on the final replacement. Shadow mode prices\n * `renderHeadLine + head + omission note + tail`; the note's locator part is\n * unknown before the spill write, so only the standardized omission clause is\n * included.\n *\n * Skip reasons are stable codes, never prose: `error-receipt` (an error receipt\n * is evidence and is never projected), `family-not-configured` (the family has\n * no window), `not-worth-it` (`truncate`'s guard said no, or the footer left no\n * net gain), `empty` (shadow's empty receipt), and on the apply half\n * `no-spill`, `no-owner`, `projection-skipped:no-footer`, `spill-failed`, and\n * `footer-failed`.\n *\n * @module dsh-boost/projection/apply\n */\nimport type { BoostConfig, ProjectionParams, ToolFamily } from '../types.js'\nimport { renderHeadLine, truncate } from './truncate.js'\nimport type { Truncation } from './truncate.js'\n\n/** Which projection behaviour the caller is running. */\nexport type ProjectionMode = 'off' | 'shadow' | 'on'\n\n/** What projection did, or would have done, to one receipt. */\nexport interface ProjectionOutcome {\n kind: 'skipped' | 'shadow' | 'applied'\n /** Stable skip code; present only when `kind === 'skipped'`. */\n reason?: string\n /**\n * Tokens in the original receipt.\n *\n * Present only when `kind === 'shadow'` and the estimator priced both\n * sides; absent (with `estimate: 'unknown'` on the receipt) when it did not.\n */\n before?: number\n /** Tokens in the replacement shadow mode would have produced. */\n after?: number\n /** `before - after`. */\n saved?: number\n /**\n * UTF-8 bytes the replacement omits; present only when `kind === 'applied'`.\n *\n * Apply mode has no token estimator: the caller (T23b) prices both texts\n * itself, and these two fields are the projection's own accounting.\n */\n omittedBytes?: number\n /** Unicode code points the replacement omits; applied outcomes only. */\n omittedCodePoints?: number\n /**\n * The persisted artifact's locator; applied outcomes only.\n *\n * It is the path the footer tells the model to read, and the retrieval ledger\n * matches later `read`/`grep` arguments against it (Task 25).\n */\n locator?: string\n}\n\n/** A persisted spill artifact's model-facing handle. */\nexport interface SpillHandle {\n /** Opaque locator the model can `read` or `grep`; never parsed here. */\n locator: string\n /** How to retrieve the artifact, as guidance for the model. */\n retrievalHint: string\n}\n\n/**\n * The host spill store, narrowed to the one method projection needs.\n *\n * `callId` and `label` are required because the host's `SaveTextSpill` requires\n * them; `projectApply` fills them in before calling. `saveText` rejects on a\n * real storage failure, and that rejection is handled as a skip.\n */\nexport interface SpillBackend {\n saveText(input: {\n owner: { sessionId: string }\n source: { kind: 'tool'; toolName: string; callId: string; label: string }\n suggestedName: string\n content: string\n }): Promise<SpillHandle>\n}\n\n/**\n * Render the footer that names what was omitted and where the original lives.\n *\n * Injected by the caller, which dynamically imports the host's\n * `formatSpillNotice`; this module must never statically import\n * `@deepseek-ai/dsh-spill-policy` — it is not declared as a dependency, and a static import\n * would make the degradation path unreachable (design §5.4).\n */\nexport type FormatFooter = (omitted: { kind: 'exact'; count: number }, ref: SpillHandle) => string\n\n/** Everything one apply decision reads; every host service arrives pre-bound. */\nexport interface ProjectApplyInput {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Owning session; without one the spill has no owner and projection stops. */\n sessionId: string | undefined\n /** Tool name, recorded on the spill source and used for its file name. */\n toolName: string\n /** Model-issued call id; defaults to `toolName`. */\n callId?: string\n /** Human label for the artifact; defaults to `family`. */\n label?: string\n /** Spill backend, absent when the host has none (projection then stops). */\n spill: SpillBackend | undefined\n /** Footer renderer, absent when the host spill policy package is not installed. */\n formatFooter: FormatFooter | undefined\n}\n\n/** The omission clause of the spill footer; the locator is unknown here. */\nfunction omissionNote(omittedBytes: number): string {\n return `(Omitted ${omittedBytes} bytes.)`\n}\n\n/**\n * The replacement shadow mode prices: head line, head, omission note, tail.\n *\n * `projectApply` replaces the note with the persisted spill footer; because the\n * locator text is not known before that write, this is a lower bound.\n */\nfunction projectedText(truncation: Truncation): string {\n return `${renderHeadLine(truncation)}\\n${truncation.head}\\n${omissionNote(truncation.omittedBytes)}\\n${truncation.tail}${signalSuffix(truncation)}`\n}\n\n/**\n * The marker lines `truncate` rescued from the cut-away middle, appended after\n * the tail so the model still sees an exit code or error flag that would\n * otherwise be lost (design §5.4-4). Empty for the overwhelming majority.\n */\nfunction signalSuffix(truncation: Truncation): string {\n const signals = truncation.signals ?? []\n return signals.length === 0 ? '' : `\\n${signals.join('\\n')}`\n}\n\n/** Price the original and the replacement together, so the pair always agrees. */\nfunction measure(\n original: string,\n replacement: string,\n estimate: (s: string) => number,\n): Pick<ProjectionOutcome, 'before' | 'after' | 'saved'> | undefined {\n const before = estimate(original)\n const after = estimate(replacement)\n // A non-finite estimate is an unknown, never a number to serialise: JSON\n // would turn NaN into `null`, which looks like a measured zero in the\n // shadow account. The caller writes `estimate: 'unknown'` instead.\n if (!Number.isFinite(before) || !Number.isFinite(after)) return undefined\n return { before, after, saved: before - after }\n}\n\n/**\n * Report what projection would save, without touching the receipt.\n *\n * Guards run in a fixed order: an error receipt is skipped before anything\n * else, so even an empty or oversized error keeps its evidence (design §5.4\n * contract 4); then empty text; then a family with no configured window; then\n * `truncate`'s own decision (trigger, 256 KiB cap, net-gain guard).\n */\nexport async function projectShadow(input: {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Token estimator injected by the caller (never imported from the host). */\n estimate: (s: string) => number\n}): Promise<ProjectionOutcome> {\n const { text, isError, family, cfg, estimate } = input\n\n if (isError) return { kind: 'skipped', reason: 'error-receipt' }\n if (text === '') return { kind: 'skipped', reason: 'empty' }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { kind: 'skipped', reason: 'family-not-configured' }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { kind: 'skipped', reason: 'not-worth-it' }\n\n const measured = measure(text, projectedText(truncation), estimate)\n return measured === undefined ? { kind: 'shadow' } : { kind: 'shadow', ...measured }\n}\n\n/** The prechecks that passed, with the host pieces narrowed to their present values. */\ninterface Ready {\n truncation: Truncation\n owner: { sessionId: string }\n spill: SpillBackend\n formatFooter: FormatFooter\n}\n\n/**\n * Decide whether the receipt may be replaced, in the plan's fixed order.\n *\n * Every guard returns the intact receipt and a stable code: an error receipt\n * first (it is evidence, design §5.4 contract 4); then a family with no window;\n * then `truncate`'s decision — calling it once is the same decision\n * `shouldTruncate` exposes, without cutting twice; then the host pieces that\n * would make the footer a lie: no backend, no owner, no footer renderer. None\n * of these writes anything.\n */\nfunction precheck(input: ProjectApplyInput): { skip: ProjectionOutcome } | Ready {\n const { text, isError, family, cfg, sessionId, spill, formatFooter } = input\n\n if (isError) return { skip: { kind: 'skipped', reason: 'error-receipt' } }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { skip: { kind: 'skipped', reason: 'family-not-configured' } }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { skip: { kind: 'skipped', reason: 'not-worth-it' } }\n\n if (!spill) return { skip: { kind: 'skipped', reason: 'no-spill' } }\n if (!sessionId) return { skip: { kind: 'skipped', reason: 'no-owner' } }\n if (!formatFooter) return { skip: { kind: 'skipped', reason: 'projection-skipped:no-footer' } }\n\n return { truncation, owner: { sessionId }, spill, formatFooter }\n}\n\n/**\n * Replace an oversized receipt with its head, tail, and a way back to the rest.\n *\n * The canonical original is spilled *before* anything is replaced — never the\n * projection, which would make the footer point at an artifact that does not\n * contain what it promises. The footer sits on its own line between the two\n * windows, and the composed replacement is re-checked against the original:\n * at the trigger boundary a long locator can make the \"projection\" longer than\n * the receipt it replaces, and a projection that grows a receipt is worse than\n * none.\n *\n * A spill or footer failure is swallowed and reported as `spill-failed` /\n * `footer-failed`; the caller's `post-execute` hook must never see an exception\n * from here. The footer must be guarded too: the host turns a throwing\n * `post-execute` listener into an `isError` result, which would lose the very\n * output this module exists to preserve.\n */\nexport async function projectApply(\n input: ProjectApplyInput,\n): Promise<{ content: string; outcome: ProjectionOutcome }> {\n const ready = precheck(input)\n if ('skip' in ready) return { content: input.text, outcome: ready.skip }\n\n const { text, family, toolName, callId, label } = input\n const { truncation, owner, spill, formatFooter } = ready\n\n // One guard covers both host calls: `saveText` and the footer renderer. The\n // marker tells the two failures apart, because status counts distinguish\n // them — and neither may reach the caller as an exception.\n let phase: 'spill' | 'footer' = 'spill'\n try {\n const ref = await spill.saveText({\n owner,\n source: { kind: 'tool', toolName, callId: callId ?? toolName, label: label ?? family },\n suggestedName: `${toolName}.txt`,\n content: text,\n })\n phase = 'footer'\n\n const footer = formatFooter({ kind: 'exact', count: truncation.omittedBytes }, ref)\n const assembled = `${renderHeadLine(truncation)}\\n${truncation.head}\\n${footer}\\n${truncation.tail}${signalSuffix(truncation)}`\n\n // The footer is only known after the write, so this check can only run now.\n // The backend exposes no delete: a spill that reaches this point stays in\n // the store, unreferenced, while the model gets the original content back.\n if (assembled.length >= text.length) {\n return { content: text, outcome: { kind: 'skipped', reason: 'not-worth-it' } }\n }\n\n return {\n content: assembled,\n outcome: {\n kind: 'applied',\n omittedBytes: truncation.omittedBytes,\n omittedCodePoints: truncation.omittedCodePoints,\n locator: ref.locator,\n },\n }\n } catch {\n return {\n content: text,\n outcome: { kind: 'skipped', reason: phase === 'spill' ? 'spill-failed' : 'footer-failed' },\n }\n }\n}\n"]}
|
|
@@ -8,16 +8,27 @@ export function renderHeadLine(truncation) {
|
|
|
8
8
|
function headLine(outputChars, firstChars, lastChars) {
|
|
9
9
|
return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`;
|
|
10
10
|
}
|
|
11
|
+
/** The marker lines the design's §5.4-4 says must survive any projection. */
|
|
12
|
+
const PRESERVED_SIGNAL = /^(?:\[exit code: -?\d+\]|exit_code\s*[:=]\s*-?\d+|is_error\s*[:=]\s*(?:true|false))$/i;
|
|
11
13
|
/**
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* Delegates instead of re-deriving the decision, so the two entry points can
|
|
15
|
-
* never disagree at the edges (the exact cut, the net-gain guard, the byte
|
|
16
|
-
* cap). The cheap pre-filters inside `truncate` keep the common "not worth
|
|
17
|
-
* cutting" path free of code-point allocation.
|
|
14
|
+
* Marker lines from the omitted middle, capped so a pathological receipt cannot
|
|
15
|
+
* make the projection longer than what it replaced.
|
|
18
16
|
*/
|
|
19
|
-
|
|
20
|
-
|
|
17
|
+
function preservedSignals(middle) {
|
|
18
|
+
if (middle.length === 0)
|
|
19
|
+
return [];
|
|
20
|
+
const out = [];
|
|
21
|
+
for (const line of middle.join('').split('\n')) {
|
|
22
|
+
const trimmed = line.trim();
|
|
23
|
+
if (trimmed === '' || !PRESERVED_SIGNAL.test(trimmed))
|
|
24
|
+
continue;
|
|
25
|
+
if (out.includes(trimmed))
|
|
26
|
+
continue;
|
|
27
|
+
out.push(trimmed);
|
|
28
|
+
if (out.length === 8)
|
|
29
|
+
break;
|
|
30
|
+
}
|
|
31
|
+
return out;
|
|
21
32
|
}
|
|
22
33
|
/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */
|
|
23
34
|
export function truncate(text, params) {
|
|
@@ -42,16 +53,22 @@ export function truncate(text, params) {
|
|
|
42
53
|
const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('');
|
|
43
54
|
const omittedCodePoints = codePoints.length - params.headChars - params.tailChars;
|
|
44
55
|
const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8');
|
|
56
|
+
// Signals a reader must never lose, even when they sit in the middle that the
|
|
57
|
+
// two windows cut away: an error flag, an exit code, the `[exit code: N]`
|
|
58
|
+
// suffix the tool executor appends (design §5.4-4). They are re-emitted after
|
|
59
|
+
// the tail so the projection stays append-only from the reader's view.
|
|
60
|
+
const preserved = preservedSignals(codePoints.slice(params.headChars, codePoints.length - params.tailChars));
|
|
45
61
|
// The replacement this layer can render: the head line plus the two windows.
|
|
46
62
|
// The apply stage inserts the spill footer between the windows; that footer is
|
|
47
63
|
// not known here, so this is a lower bound on the final projected length.
|
|
48
64
|
const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length);
|
|
49
|
-
const
|
|
65
|
+
const signals = preserved.length === 0 ? '' : `\n${preserved.join('\n')}`;
|
|
66
|
+
const after = `${header}\n${head}\n${tail}${signals}`;
|
|
50
67
|
// A cut that would not shrink the receipt (misconfigured windows, or windows
|
|
51
68
|
// that together swallow the whole text) is not worth taking; fall back to the
|
|
52
69
|
// original rather than throwing on unvalidated config.
|
|
53
70
|
if (after.length >= text.length)
|
|
54
71
|
return null;
|
|
55
|
-
return { before: text, after, head, tail, omittedBytes, omittedCodePoints };
|
|
72
|
+
return { before: text, after, head, tail, omittedBytes, omittedCodePoints, signals: preserved };
|
|
56
73
|
}
|
|
57
74
|
//# sourceMappingURL=truncate.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/projection/truncate.ts"],"names":[],"mappings":"AAoBA,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG,GAAG,GAAG,IAAI,CAAA;
|
|
1
|
+
{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/projection/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Receipt truncation: whether to cut, the two windows, and the head line.\n *\n * Lengths are counted in Unicode code points, never UTF-16 code units (design\n * §5.4): a CJK or emoji receipt must be cut at the same visual length as an\n * ASCII one, and slicing the code-point array is the only way never to split a\n * surrogate pair. `text.length` appears only as a cheap pre-filter — it is an\n * upper bound on the code-point count, so `text.length <= triggerChars` proves\n * that no cut is due.\n *\n * `truncate` returns `null` when a cut is not worth it: when the receipt does\n * not exceed the trigger, when its UTF-8 size exceeds the projection cap, or\n * when the rendered replacement would not be shorter than the original. Every\n * non-null result therefore satisfies `after.length < before.length`, which\n * the shadow-mode accounting relies on.\n *\n * @module dsh-boost/projection/truncate\n */\nimport type { ProjectionParams } from '../types.js'\n\n/** Receipts above this many UTF-8 bytes are never projected (design §5.4). */\nconst MAX_PROJECTED_BYTES = 256 * 1024\n\n/** The two windows plus the facts later stages report and account for. */\nexport interface Truncation {\n /** The original receipt text, byte for byte. */\n before: string\n /** The rendered replacement: head line, then head, then tail. */\n after: string\n /** First `headChars` code points of `before`. */\n head: string\n /** Last `tailChars` code points of `before`. */\n tail: string\n /** UTF-8 bytes of `before` that neither window carries. */\n omittedBytes: number\n /** `before` code points minus the two window sizes. */\n omittedCodePoints: number\n /**\n * Marker lines from the cut-away middle that must survive (design §5.4-4):\n * an exit code or error flag the reader would otherwise lose. Empty for the\n * overwhelming majority of receipts.\n */\n signals: string[]\n}\n\n/** Render the head line of a truncation, with `en-US` thousands separators. */\nexport function renderHeadLine(truncation: Truncation): string {\n return headLine(\n Array.from(truncation.before).length,\n Array.from(truncation.head).length,\n Array.from(truncation.tail).length,\n )\n}\n\n/** The one place the head line's literal format lives. */\nfunction headLine(outputChars: number, firstChars: number, lastChars: number): string {\n return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`\n}\n\n/** The marker lines the design's §5.4-4 says must survive any projection. */\nconst PRESERVED_SIGNAL = /^(?:\\[exit code: -?\\d+\\]|exit_code\\s*[:=]\\s*-?\\d+|is_error\\s*[:=]\\s*(?:true|false))$/i\n\n/**\n * Marker lines from the omitted middle, capped so a pathological receipt cannot\n * make the projection longer than what it replaced.\n */\nfunction preservedSignals(middle: readonly string[]): string[] {\n if (middle.length === 0) return []\n const out: string[] = []\n for (const line of middle.join('').split('\\n')) {\n const trimmed = line.trim()\n if (trimmed === '' || !PRESERVED_SIGNAL.test(trimmed)) continue\n if (out.includes(trimmed)) continue\n out.push(trimmed)\n if (out.length === 8) break\n }\n return out\n}\n\n/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */\nexport function truncate(text: string, params: ProjectionParams): Truncation | null {\n // UTF-16 length upper-bounds the code-point count: when it does not exceed\n // the trigger, neither can the real count.\n if (text.length <= params.triggerChars) return null\n\n // Large receipts are not projected at all. The design's 256 KiB is a byte\n // budget, so measure UTF-8 bytes rather than UTF-16 units — otherwise CJK\n // and emoji receipts would overflow the budget by 2–4×.\n const beforeBytes = Buffer.byteLength(text, 'utf8')\n if (beforeBytes > MAX_PROJECTED_BYTES) return null\n\n const codePoints = Array.from(text)\n if (codePoints.length <= params.triggerChars) return null\n\n // Slicing the code-point array cannot split a surrogate pair; string\n // indexing could.\n const head = codePoints.slice(0, params.headChars).join('')\n // `slice(-0)` is `slice(0)`, i.e. the whole text: a configured zero tail must\n // be no tail, not a duplicate of the receipt (review row 69).\n const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('')\n const omittedCodePoints = codePoints.length - params.headChars - params.tailChars\n const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8')\n\n // Signals a reader must never lose, even when they sit in the middle that the\n // two windows cut away: an error flag, an exit code, the `[exit code: N]`\n // suffix the tool executor appends (design §5.4-4). They are re-emitted after\n // the tail so the projection stays append-only from the reader's view.\n const preserved = preservedSignals(codePoints.slice(params.headChars, codePoints.length - params.tailChars))\n\n // The replacement this layer can render: the head line plus the two windows.\n // The apply stage inserts the spill footer between the windows; that footer is\n // not known here, so this is a lower bound on the final projected length.\n const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length)\n const signals = preserved.length === 0 ? '' : `\\n${preserved.join('\\n')}`\n const after = `${header}\\n${head}\\n${tail}${signals}`\n // A cut that would not shrink the receipt (misconfigured windows, or windows\n // that together swallow the whole text) is not worth taking; fall back to the\n // original rather than throwing on unvalidated config.\n if (after.length >= text.length) return null\n\n return { before: text, after, head, tail, omittedBytes, omittedCodePoints, signals: preserved }\n}\n"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-boost",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "Cut DSH token usage by projecting tool receipts and substituting deterministic read-only calls.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -40,7 +40,8 @@
|
|
|
40
40
|
"stats": "node scripts/session-stats.mjs",
|
|
41
41
|
"ci": "npm run typecheck && npm test && npm run build",
|
|
42
42
|
"verify:package": "node scripts/verify-package.mjs",
|
|
43
|
-
"prepublishOnly": "npm run ci && npm run verify:package -- --prebuilt"
|
|
43
|
+
"prepublishOnly": "npm run ci && npm run verify:package -- --prebuilt",
|
|
44
|
+
"prepare": "node scripts/prepare-build.mjs"
|
|
44
45
|
},
|
|
45
46
|
"devDependencies": {
|
|
46
47
|
"@deepseek-ai/dsh-llm": "0.2.2-rc.4",
|