@ponythewhite/base-context 1.0.11 → 1.0.12

package/docs/compaction.md

@@ -35,13 +35,36 @@ or loss from a summary alone.
 
 ### When It Triggers
 
-Auto-compaction triggers when:
+Auto-compaction uses an earlier, model-aware soft target by default:
 
 ```
-contextTokens > contextWindow - reserveTokens
+softTarget = max(4 * keepRecentTokens, min(96000, contextWindow / 2))
+threshold = min(contextWindow - reserveTokens, max(softTarget, fixedContextTokens + 4 * keepRecentTokens))
+contextTokens > threshold
 ```
 
-By default, `reserveTokens` is 16384 tokens (configurable in `~/.base-context/settings.json` or `<project-dir>/.base-context/settings.json`). This leaves room for the LLM's response.
+With default `keepRecentTokens` of 20000 and `reserveTokens` of 16384, before
+fixed-context headroom raises the target, the thresholds are 96000 for a
+272000-token model, 80000 for a 128000-token model, and 47616 for a 64000-token
+model. The model-window ceiling always applies.
+
+`fixedContextTokens` estimates current system instructions, tool schemas, the
+current TaskFrame and latest harness snapshot. It does not count all historical
+messages or obsolete snapshots as fixed. Reserving room above this context avoids
+repeated ineffective summaries when required instructions already exceed the
+soft target. These are local estimates, not exact provider token counts.
+
+Set `compaction.targetTokens` to a positive safe integer to replace the soft
+target; required-context headroom can still raise a numeric target. Set
+`"model-limit"` to use exactly `contextWindow - reserveTokens` instead.
+Configure these settings in `~/.base-context/settings.json` or
+`<project-dir>/.base-context/settings.json`.
+
+This is a compaction heuristic, not a strict request cap, a validated backend
+limit, or a promise of optimal token use. Earlier summaries trade shorter replay
+for summary calls and possible rereads. Required instructions and replay
+dependencies are not clipped to meet this target. Explicit SDK request-token
+budgets remain separate; see [context management](context-management.md#model-aware-budgets).
 
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary — for example `/compact focus on the auth refactor, remember the exact migration command`. The instructions are passed to the summarization prompt with high priority, persisted on the `CompactionEntry`, and shown on the `[compaction]` message in the TUI.
 
@@ -432,6 +455,7 @@ Configure compaction in `~/.base-context/settings.json` or `<project-dir>/.base-
 | `enabled` | `true` | Enable auto-compaction |
 | `reserveTokens` | `16384` | Headroom used by the compaction threshold |
 | `keepRecentTokens` | `20000` | Estimated recent-token target for the retained tail |
+| `targetTokens` | Model-aware soft target | Positive safe integer to override the soft target, or `"model-limit"` for the model-window threshold |
 
 Disable automatic compaction with `"compaction": { "enabled": false }`. Manual
 `/compact` remains available while `context.mode` is `"on"`. Setting `context.mode`

package/docs/context-management.md

@@ -82,7 +82,23 @@ Profiles identify the API, provider, endpoint, final model, context allowance, o
 
 In supported native Responses/Codex selection paths, historical assistant literals can become optional at accepted boundaries. Users, the latest assistant, TaskFrames, summaries, recovery, and required dependencies remain mandatory. If that set cannot fit, the request can refuse. Unsupported media, opaque layouts, or missing contracts also remain explicit limits.
 
-See [SDK request-token profiles](sdk.md#explicit-request-token-budget-profiles) for the exact scope and configuration. Ordinary [compaction](compaction.md) and its `reserveTokens`/`keepRecentTokens` settings are separate.
+See [SDK request-token profiles](sdk.md#explicit-request-token-budget-profiles) for the exact scope and configuration.
+
+Ordinary [compaction](compaction.md) uses a separate model-aware soft target:
+`max(4 * keepRecentTokens, min(96000, contextWindow / 2))`. The actual trigger also
+leaves `4 * keepRecentTokens` above estimated fixed context, then caps the result
+at `contextWindow - reserveTokens`. Fixed context includes current system
+instructions, tool schemas, the current TaskFrame and latest harness snapshot,
+not every historical message. This avoids repeated ineffective summaries of
+noncompactable instructions.
+
+With small fixed context, default settings trigger earlier at 96000 estimated
+tokens for a 272000-token model. Set `compaction.targetTokens` to a positive safe
+integer to replace the soft target (still subject to fixed-context headroom), or
+`"model-limit"` to use exactly the full-window threshold.
+This policy reduces repeated large-history requests without clipping required
+replay groups. It can add summary calls and rereads; it is not a strict request
+cap, an optimality guarantee, or evidence of a deployment's actual limit.
 
 ## Stable context epochs
 

package/docs/rlm.md

@@ -101,7 +101,7 @@ await agent_message.send(
 
 #### Child handles and lifecycle
 
-An admission handle contains `rlm_child_id`, `name`, `session_dir`, and `model`. Child usage is attributed to the parent session while remaining distinguishable in context-tree reporting.
+An admission handle contains `rlm_child_id`, `name`, `session_dir`, and `model`. Child usage is attributed to the parent session while remaining distinguishable in context-tree reporting. Native child usage reporting continues after passivation and rehydration. `/context` separately totals saved request receipts for the captured family; parent attribution records are not added to those totals. See [token usage and status](usage.md#token-usage-and-status) for missing-data, catalog-estimate, and goal-budget scope.
 
 The parent-scoped child registry survives compaction, kernel restart, and parent restoration:
 

package/docs/settings.md

@@ -94,6 +94,7 @@ Private download manifests require `version` and `package` (or `packageName`) se
 | `compaction.enabled` | boolean | `true` | Enable auto-compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
 | `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+| `compaction.targetTokens` | positive integer or `"model-limit"` | Model-aware soft target | Override the soft compaction target, still capped by the model window minus reserve |
 | `compaction.model` | object | Current main model and effort | Explicit summary model: `provider`, `modelId`, and `thinkingLevel` are all required |
 
 ```json
@@ -107,6 +108,17 @@ Private download manifests require `version` and `package` (or `packageName`) se
 ```
 
 
+Without `targetTokens`, the soft target is
+`max(4 * keepRecentTokens, min(96000, contextWindow / 2))`. The trigger also leaves
+`4 * keepRecentTokens` above an estimate of current fixed instructions, tool
+schemas, TaskFrame and latest harness snapshot. It is capped at
+`contextWindow - reserveTokens`. With small fixed context, default settings use
+96000 for a 272000-token model. A positive safe integer replaces the soft target,
+but required-context headroom can raise it; `"model-limit"` uses exactly the
+full-window threshold. This is a summary heuristic,
+not strict provider-request admission. See [compaction](compaction.md#when-it-triggers)
+and [model-aware budgets](context-management.md#model-aware-budgets).
+
 Set `compaction.model` to choose the model and effort for manual, automatic and
 model-requested compaction summaries. For example, when this exact model/route is
 configured and budgeted:

package/docs/usage.md

@@ -49,7 +49,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, and message counts |
-| `/usage`, `/context` | Show the parent and subagent context, token, and cost breakdown |
+| `/usage`, `/context` | Show captured-family request usage, context, and separate goal-budget scope |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
@@ -73,6 +73,29 @@ The value is saved as the global `rlmMaxSubagents` preference, so it survives re
 
 Lowering the limit never kills or passivates existing agents. They keep running or remain idle. Only new spawns/admissions are blocked until the live count is below the limit. This slash command is separate from `base-context agents`, which lists agents.
 
+## Token usage and status
+
+`/context` (also `/usage`) separates generation usage from the goal budget:
+
+- When saved provider-attempt receipts are available, it shows each captured agent's own usage by purpose: main work, child work, compaction, refinement, status, and other recorded generation calls. The captured-family total counts each source once. It does not add assistant or child-attribution projections on top of receipts.
+- Processed tokens equal total input (including cache) plus output. Cached input is not added again. Uncached input, cache read/write, and output are also shown separately.
+- Missing or partial usage, unsettled attempts, unavailable prices, and agents without receipts are explicit. Missing values are not zero. The captured family may not include every historical child or request.
+- Dollar amounts are catalog estimates from recorded rates, not provider invoices. Unavailable prices are not treated as free usage.
+- Older sessions or daemons without receipt data use a labeled legacy conversation projection. It can omit auxiliary calls and is not whole-family provider spend.
+- The goal budget remains **root successful main uncached input + output only**. Cached input, child work, and auxiliary calls do not consume that counter.
+
+Dashboard summaries do not request inference again when their bounded input is unchanged. Changed working input and retries are coalesced with a 60-second minimum interval and a short settle debounce. An observed working-to-idle transition can request a final summary without waiting for that interval. Local activity, queues, and terminal errors remain visible without a new summary call. The selected status model is unchanged.
+
+## Harness refinement
+
+`/refine` updates the editable continual harness. Manual and automatic refinement keep their existing scheduling and scope rules.
+
+Static harness instructions stay in the system prompt. Fresh compact entries and selected error-fix advice enter the next owned model request as a saved **Continual Harness Snapshot**, rather than rewriting the system prefix. Direct kernel harness edits use the same path. Unchanged snapshots are not appended again.
+
+The latest snapshot supersedes older snapshots, including deletions, rollbacks, and empty state. Entries remain advice below system instructions and the current task. Resume and native context epochs use the retained source records; if compaction removes the snapshot, the next request adds the current state again. Snapshot rows are hidden in the normal UI but remain model-visible.
+
+This preserves fresh advice while reducing prefix changes. It does not guarantee a provider cache hit or reduce refinement frequency.
+
 ## Message Queue
 
 You can submit messages while the agent is still working:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ponythewhite/base-context",
-	"version": "1.0.11",
+	"version": "1.0.12",
 	"description": "Synerise base-context: a coding and research agent with durable context and a persistent Python REPL",
 	"type": "module",
 	"bin": {
@@ -42,9 +42,9 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "^1.3.0",
-		"@ponythewhite/base-context-agent": "1.0.11",
-		"@ponythewhite/base-context-ai": "1.0.11",
-		"@ponythewhite/base-context-tui": "1.0.11",
+		"@ponythewhite/base-context-agent": "1.0.12",
+		"@ponythewhite/base-context-ai": "1.0.12",
+		"@ponythewhite/base-context-tui": "1.0.12",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",