@possumtech/rummy 0.2.7 → 0.3.0

package/.env.example

@@ -18,7 +18,9 @@ RUMMY_MMAP_MB=0
 # Agent Loop Limits
 RUMMY_MAX_TURNS=99
 RUMMY_MAX_UNKNOWN_WARNINGS=3
+RUMMY_MAX_STALLS=3
 RUMMY_MAX_REPETITIONS=3
+RUMMY_MAX_UPDATE_REPEATS=3
 
 # Hygiene
 # Days to keep completed/aborted runs before purging
@@ -26,7 +28,15 @@ RUMMY_RETENTION_DAYS=31
 
 # Timeouts (ms)
 RUMMY_RPC_TIMEOUT=30000
-RUMMY_FETCH_TIMEOUT=120000
+RUMMY_FETCH_TIMEOUT=300000
+
+# Debug
+# RUMMY_DEBUG=true
+
+# Token Estimation
+# Characters per token. Lower = more conservative (fewer tokens per character).
+# Default 2. Set to 1 for worst-case (1 token per character).
+RUMMY_TOKEN_DIVISOR=2
 
 # Model Behavior
 # LLM temperature (0 = deterministic, 0.7 = creative). Client can override per-request.
@@ -57,7 +67,6 @@ RUMMY_X_TITLE=RUMMY
 # Web Search
 # RUMMY_SEARXNG_URL="http://127.0.0.1:8888"
 
-# required for web fetch and search
+# External plugins: npm i -g <package>, then uncomment
 # RUMMY_PLUGIN_WEB="@possumtech/rummy.web"
-# required for git repo and repomap/symbol functionality
 # RUMMY_PLUGIN_REPO="@possumtech/rummy.repo"

package/EXCEPTIONS.md

@@ -0,0 +1,46 @@
+# EXCEPTIONS.md — Documented Backbone Responsibilities
+
+Operations that bypass the plugin protocol. Each must justify WHY it
+can't go through the standard tool handler path. If the justification
+is weak, the exception should be eliminated.
+
+## Resolved
+
+### File.setConstraint / File.dropConstraint
+
+**What:** Direct DB writes to `file_constraints` table.
+**Justification:** File constraints are project-level config — they
+define which files a project cares about. This is backbone, not tool
+dispatch. Entry promotion/demotion that follows constraints now goes
+through the standard tool handler chain via `dispatchTool`.
+**Boundary documented:** SPEC.md §2.3.
+
+## Currently Identified
+
+### 1. TurnExecutor#record — tool-specific handling
+
+**What:** `known`, `unknown`, `summarize`, `update` have special-case
+code in `#record` (dedup, slug paths, lifecycle classification).
+**Bypasses:** These tools don't go through the same dispatch path as
+`get`, `set`, `rm` etc.
+**Justification:** Lifecycle signals (`summarize`, `update`) are state
+declarations, not tool operations — they always dispatch and cannot be
+409'd. `known` and `unknown` generate their own paths from body content
+(slug paths). The classification is a fundamental architectural split
+(lifecycle vs action), not a protocol violation.
+
+### 2. Token math — multiple measurement points
+
+**What:** `known_entries.tokens`, `turn_context.tokens`,
+`turns.context_tokens`, `countTokens()` estimates.
+**Bypasses:** No single function call, but a strict rule.
+**Justification:** Each serves a different purpose. `known_entries.tokens`
+is display-only (model sees entry sizes in `<knowns>`). `turn_context.tokens`
+is per-turn snapshot. `turns.context_tokens` is assembled ground truth for
+budget. The rule: budget decisions use ONLY assembled message tokens.
+DB tokens are NEVER used for budget. Documented in PLUGINS.md §7.5.
+
+---
+
+*This file should shrink over time. Every entry is a debt to be paid
+or a boundary to be justified.*