dsh-boost 0.1.2 → 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 +157 -80
- package/README.md +119 -65
- package/dist/admission/usage.js +52 -8
- package/dist/admission/usage.js.map +1 -1
- package/dist/hooks/llm-stream.js +121 -5
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +129 -31
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/index.js +230 -5
- package/dist/index.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/dist/tools/boost.js +82 -2
- package/dist/tools/boost.js.map +1 -1
- package/package.json +4 -3
|
@@ -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/dist/tools/boost.js
CHANGED
|
@@ -49,6 +49,39 @@ const ERR_HOST_NO_TOKENMETER = 'ERR_HOST_NO_TOKENMETER';
|
|
|
49
49
|
const ERR_HOST_NO_ESTIMATOR = 'ERR_HOST_NO_ESTIMATOR';
|
|
50
50
|
const ERR_HOST_PLATFORM_UNSUPPORTED = 'ERR_HOST_PLATFORM_UNSUPPORTED';
|
|
51
51
|
const ERR_HOST_NO_WORKSPACE_REGISTRY = 'ERR_HOST_NO_WORKSPACE_REGISTRY';
|
|
52
|
+
/**
|
|
53
|
+
* Stable degradation code: a workspace registry is present but cannot list.
|
|
54
|
+
*
|
|
55
|
+
* Presence alone made a throwing `list()` look healthy: the resolver swallowed
|
|
56
|
+
* the throw per call (the intentional fail-closed path for one invisible
|
|
57
|
+
* session), every session was judged invisible, and `status` reported a healthy
|
|
58
|
+
* plugin doing nothing (review row 6). The probe calls `list()` at status time,
|
|
59
|
+
* exactly as the token meter is probed, so a broken registry is named instead
|
|
60
|
+
* of being indistinguishable from an absent one.
|
|
61
|
+
*/
|
|
62
|
+
const ERR_HOST_WORKSPACE_REGISTRY_BROKEN = 'ERR_HOST_WORKSPACE_REGISTRY_BROKEN';
|
|
63
|
+
/**
|
|
64
|
+
* Stable degradation code: `spillStore` is present but exposes no `saveText`.
|
|
65
|
+
*
|
|
66
|
+
* `hasSpill` was presence-only, so a `{}` service reported a healthy spill path
|
|
67
|
+
* until the first projection failed (review row 50). The store is probed at
|
|
68
|
+
* status time for the one method the projection path calls; the notice module
|
|
69
|
+
* stays covered by `ERR_HOST_NO_SPILL_NOTICE` / `projection-skipped:no-footer`,
|
|
70
|
+
* because it is reached by `import()` and has no service to probe.
|
|
71
|
+
*/
|
|
72
|
+
const ERR_HOST_SPILL_UNUSABLE = 'ERR_HOST_SPILL_UNUSABLE';
|
|
73
|
+
/**
|
|
74
|
+
* Stable degradation code: multi-candidate plans will abstain.
|
|
75
|
+
*
|
|
76
|
+
* The selector is the only consumer of the host LLM. Its absence or a failing
|
|
77
|
+
* call is written as `selector-unavailable` / `selector-error`, but those are
|
|
78
|
+
* receipt counts: an operator reading `degraded` saw a healthy plugin while
|
|
79
|
+
* every multi-candidate plan abstained (review row 49). Single-candidate
|
|
80
|
+
* substitution still works, so this is a warning, not a failure. A
|
|
81
|
+
* `selector-abstain` is deliberately not mapped: the model declined an
|
|
82
|
+
* ambiguous plan, which is not a host capability absence.
|
|
83
|
+
*/
|
|
84
|
+
const ERR_HOST_SELECTOR_UNAVAILABLE = 'ERR_HOST_SELECTOR_UNAVAILABLE';
|
|
52
85
|
/**
|
|
53
86
|
* Stable degradation code: at least one receipt shard could not be read.
|
|
54
87
|
*
|
|
@@ -104,6 +137,12 @@ const ERR_HOST_COMPLETE_SECTION = 'ERR_HOST_COMPLETE_SECTION';
|
|
|
104
137
|
* failing sends them to the wrong place. `footer-failed` stays with
|
|
105
138
|
* `ERR_HOST_NO_SPILL_NOTICE` because both mean the same thing at the point of
|
|
106
139
|
* use — the footer cannot be produced.
|
|
140
|
+
*
|
|
141
|
+
* `selector-unavailable` and `selector-error` are the selector's only two host
|
|
142
|
+
* failures: no LLM/route, or a call that threw. Both mean "multi-candidate
|
|
143
|
+
* plans will abstain" while single-candidate substitution keeps working, so
|
|
144
|
+
* they share one warning code. `selector-abstain` is not a host fact and is not
|
|
145
|
+
* mapped (review row 49).
|
|
107
146
|
*/
|
|
108
147
|
const RECEIPT_DEGRADATION = [
|
|
109
148
|
{ code: 'projection-skipped:no-spill', degraded: ERR_HOST_NO_SPILL },
|
|
@@ -113,6 +152,10 @@ const RECEIPT_DEGRADATION = [
|
|
|
113
152
|
// The substitution refusal writes the stable code itself, so a status built
|
|
114
153
|
// without host facts still reports the reason the decision path recorded.
|
|
115
154
|
{ code: ERR_HOST_NO_TOKENMETER, degraded: ERR_HOST_NO_TOKENMETER },
|
|
155
|
+
// Only absence is a capability fact. `selector-error` is a call failure that
|
|
156
|
+
// may be transient and is summed over all history, so mapping it here would
|
|
157
|
+
// mark a healthy host degraded forever (review qr5#4).
|
|
158
|
+
{ code: 'selector-unavailable', degraded: ERR_HOST_SELECTOR_UNAVAILABLE },
|
|
116
159
|
];
|
|
117
160
|
/** The scope document's caller-writable fields. Everything else is store-owned. */
|
|
118
161
|
const PATCH_FIELDS = ['mode', 'workspaceIds', 'shadow', 'projection'];
|
|
@@ -158,6 +201,8 @@ function replayOf(receipt, fallback) {
|
|
|
158
201
|
async function aggregate(receipts, fallbackHorizon) {
|
|
159
202
|
const counts = Object.create(null);
|
|
160
203
|
let substitution = 0;
|
|
204
|
+
let substitutionAvoided = 0;
|
|
205
|
+
let avoidedSeen = false;
|
|
161
206
|
let projectionGross = 0;
|
|
162
207
|
let projectionGrossReplay = 0;
|
|
163
208
|
let retrievalContentReplay = 0;
|
|
@@ -184,6 +229,26 @@ async function aggregate(receipts, fallbackHorizon) {
|
|
|
184
229
|
if (typeof saved === 'number' && Number.isFinite(saved))
|
|
185
230
|
substitution += saved;
|
|
186
231
|
}
|
|
232
|
+
// The lower estimate is the skipped request's own total, summed over every
|
|
233
|
+
// receipt that carries it (the settled line is its producer). Presence is
|
|
234
|
+
// tracked separately from the value: a receipt carrying `0` is a
|
|
235
|
+
// measurement, while no receipt carrying the field means "not measured"
|
|
236
|
+
// and the key is omitted from `status` rather than reported as zero
|
|
237
|
+
// (review row 7).
|
|
238
|
+
// Pair the two sums on the same receipt: a rollover settlement writes a
|
|
239
|
+
// numeric lower bound with `saved_input_tokens: 'unknown'`, so summing the
|
|
240
|
+
// lower over a superset could report a floor above the ceiling
|
|
241
|
+
// (review qr5#2). A receipt that carries only one side contributes to
|
|
242
|
+
// neither.
|
|
243
|
+
const avoided = receipt.avoided_total_tokens;
|
|
244
|
+
const upper = receipt.saved_input_tokens;
|
|
245
|
+
if (typeof avoided === 'number' &&
|
|
246
|
+
Number.isFinite(avoided) &&
|
|
247
|
+
typeof upper === 'number' &&
|
|
248
|
+
Number.isFinite(upper)) {
|
|
249
|
+
substitutionAvoided += avoided;
|
|
250
|
+
avoidedSeen = true;
|
|
251
|
+
}
|
|
187
252
|
if (receipt.kind !== 'projection')
|
|
188
253
|
continue;
|
|
189
254
|
const replay = replayOf(receipt, fallbackHorizon);
|
|
@@ -249,6 +314,7 @@ async function aggregate(receipts, fallbackHorizon) {
|
|
|
249
314
|
return {
|
|
250
315
|
counts,
|
|
251
316
|
substitution,
|
|
317
|
+
...(avoidedSeen ? { substitutionAvoided } : {}),
|
|
252
318
|
projectionGross,
|
|
253
319
|
projectionGrossReplay,
|
|
254
320
|
retrievalContentReplay,
|
|
@@ -415,10 +481,20 @@ function degradationCodes(observed, read, host, fixedOverhead, missingMounts = [
|
|
|
415
481
|
codes.push(ERR_HOST_NO_ESTIMATOR);
|
|
416
482
|
// `spillStore` matters only in apply mode; shadow mode never touches it
|
|
417
483
|
// (design §5.4), so reporting it while projection is `shadow` would be noise.
|
|
418
|
-
|
|
419
|
-
|
|
484
|
+
// Presence and capability are separate: an absent store and a present store
|
|
485
|
+
// without `saveText` need different repairs, so they get different codes.
|
|
486
|
+
if (read.doc.projection === 'on') {
|
|
487
|
+
if (host?.hasSpill === false)
|
|
488
|
+
codes.push(ERR_HOST_NO_SPILL);
|
|
489
|
+
else if (host?.spillUsable === false)
|
|
490
|
+
codes.push(ERR_HOST_SPILL_UNUSABLE);
|
|
491
|
+
}
|
|
492
|
+
// A present registry that cannot list is not an absent one: the operator is
|
|
493
|
+
// told which of the two host states to repair (review row 6).
|
|
420
494
|
if (host?.hasWorkspaceRegistry === false)
|
|
421
495
|
codes.push(ERR_HOST_NO_WORKSPACE_REGISTRY);
|
|
496
|
+
else if (host?.workspaceRegistryBroken === true)
|
|
497
|
+
codes.push(ERR_HOST_WORKSPACE_REGISTRY_BROKEN);
|
|
422
498
|
// A missing mount is a wiring failure, not a capability absence: the plugin
|
|
423
499
|
// is loaded but at least one of its four integration points is not, so the
|
|
424
500
|
// ledgers cannot be trusted to describe what it is doing.
|
|
@@ -473,6 +549,9 @@ async function statusCommand(deps) {
|
|
|
473
549
|
totals.legacyRetrievalCost;
|
|
474
550
|
const saved = {
|
|
475
551
|
substitution: totals.substitution,
|
|
552
|
+
...(totals.substitutionAvoided === undefined
|
|
553
|
+
? {}
|
|
554
|
+
: { substitution_avoided: totals.substitutionAvoided }),
|
|
476
555
|
projectionGross: grossReplay,
|
|
477
556
|
projectionNet,
|
|
478
557
|
retrievals: totals.retrievals,
|
|
@@ -514,6 +593,7 @@ async function statusCommand(deps) {
|
|
|
514
593
|
...(deps.host?.hasWorkspaceRegistry === undefined
|
|
515
594
|
? {}
|
|
516
595
|
: { hasWorkspaceRegistry: deps.host.hasWorkspaceRegistry }),
|
|
596
|
+
...(deps.host?.hasSpill === undefined ? {} : { hasSpill: deps.host.hasSpill }),
|
|
517
597
|
};
|
|
518
598
|
return { ok: true, data };
|
|
519
599
|
}
|