diff --git a/reference/configuration/debugging.md b/reference/configuration/debugging.md index 0424fe46c..072bd8c2c 100644 --- a/reference/configuration/debugging.md +++ b/reference/configuration/debugging.md @@ -106,8 +106,27 @@ threads: Snapshots can be large (often a sizable fraction of the heap limit) and writing them blocks the thread briefly — leave disabled for normal operation and enable only when investigating an out-of-memory pattern. +## Source Maps in Stack Traces + + + +Stack traces from Harper's core point at its compiled JavaScript under `dist/`. To map them back to the TypeScript sources, enable source maps with the Node.js `--enable-source-maps` flag, set through `NODE_OPTIONS`: + +```bash +NODE_OPTIONS=--enable-source-maps harper +``` + +Harper passes the setting on to every worker thread (not under Bun). Source maps cost memory: Node.js keeps every loaded module's source map on every thread, several megabytes per thread. + +The setting applies to modules Node.js loads itself: Harper's core, application code loaded natively (for example with `applications.moduleLoader: native`), and the npm packages that Harper loads natively (under the default `applications.dependencyLoader: auto`, every package that does not depend on Harper; see [Dependency Loading](../components/module-loading.md#dependency-loading)). Harper's VM-based loaders (`vm-current-context`, the default, as well as `vm` and `compartment`) do not apply source maps either way. + +On Fabric clusters that Harper hosts, you do not set the process environment, so `NODE_OPTIONS` is not available there. Stack traces from application code on the default loader are the same either way; those from Harper's core and from natively loaded packages stay unmapped. + +Before v5.4.0, source maps were always enabled. + ## Related - [Configuration Options — `threads`](./options.md#threads) — full thread configuration reference - [Architecture Overview](../database/overview.md#architecture-overview) — how worker threads fit into Harper - [Node.js Inspector documentation](https://nodejs.org/en/learn/getting-started/debugging) — debugger protocol details +- [Node.js `--enable-source-maps`](https://nodejs.org/api/cli.html#--enable-source-maps) — how Node.js applies source maps to stack traces diff --git a/reference/configuration/overview.md b/reference/configuration/overview.md index 033c8006c..c82ba9a49 100644 --- a/reference/configuration/overview.md +++ b/reference/configuration/overview.md @@ -315,6 +315,6 @@ Built-in plugins (REST, HTTP, operations API, etc.) and the core database are un ## See Also - [Configuration Options](./options.md) — complete reference for every `harper-config.yaml` key -- [Worker Thread Debugging](./debugging.md) — attaching Node.js inspector to Harper's worker threads +- [Worker Thread Debugging](./debugging.md) — attaching Node.js inspector to Harper's worker threads, and enabling source maps in stack traces - [Storage Tuning](../database/storage-tuning.md) — production tuning of `storage.*` options - [Logging Configuration](../logging/configuration.md) — main and per-subsystem log settings diff --git a/release-notes/v5-lincoln/5.4.md b/release-notes/v5-lincoln/5.4.md index bf779e192..de5cf747b 100644 --- a/release-notes/v5-lincoln/5.4.md +++ b/release-notes/v5-lincoln/5.4.md @@ -76,6 +76,14 @@ The agent records the usage of each model call on its session, and `get_agent_se A `models.generative` entry can now declare `pricing: { inputPerMtok, outputPerMtok }`, what you pay in USD per million prompt and completion tokens. Harper ships no prices of its own. Each `generate()` call is priced at the rates of the entry that served it, a fallback included, and the result carries `costUsd` when that entry is priced and the provider reported both token counts. With `toolMode: 'auto'` it covers the final round, and streaming calls are not priced. This makes `maxCostUsd` work on `toolMode: 'auto'` calls; before, it had no prices behind it and never tripped. A `toolMode: 'auto'` round that leaves `maxCostUsd` or `maxToolTokens` unmeasurable, because the entry is unpriced or the provider reported no token counts, now stops the call with the budget error (429) instead of warning once and continuing, so set `pricing` on entries you cap by cost. See [Pricing](/reference/v5/models/overview#pricing). +## Memory + +### Smaller Per-Thread Baseline + +An idle Harper thread now uses roughly 40% less JavaScript heap (about 58 MB down to 35 MB in a default install, before any application code loads). Harper's compiled code is smaller in memory, and several dependencies used only by specific features (LMDB storage, certificate revocation checks, certificate generation, `system_information`) now load when that feature is first used. + +Source maps are no longer enabled by default, so stack traces from Harper's core point at its compiled JavaScript. If you control the process environment (not on Fabric clusters that Harper hosts), set `NODE_OPTIONS=--enable-source-maps` to map them back to the TypeScript sources. See [Source Maps in Stack Traces](/reference/v5/configuration/debugging#source-maps-in-stack-traces). + ## Component Deploys ### Certifying a Release in a Canary Worker