diff --git a/reference/configuration/debugging.md b/reference/configuration/debugging.md index 0424fe46..072bd8c2 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 112327b2..45cdcd3e 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 e1f63819..d515349b 100644 --- a/release-notes/v5-lincoln/5.4.md +++ b/release-notes/v5-lincoln/5.4.md @@ -42,6 +42,14 @@ The built-in agent's read-only `config` filesystem scope used to be the director The built-in agent added every tool result to its conversation in full, so one large result, such as a log read whole, could fill the model's context window and leave the session unusable. A tool result is now cut to `agent.maxToolResultBytes` (default `65536`) before it is stored, and `read_file` pages through a file by line, with no size limit, returning a cursor (`nextLine`, `nextOffset`) to continue from. When a provider still rejects a request as too long for the model, the agent cuts the most recent tool results to 2 KiB and retries once, and prompting a session left unusable by an earlier version usually recovers it the same way. The agent also stops sending its system prompt twice per request. See [When a conversation outgrows the model's context window](/reference/v5/operations-api/operations#when-a-conversation-outgrows-the-models-context-window). +## 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