@ssheleg/agent-stack 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-08-12
+
+### Added
+
+- **`references/context-engineering.md`** — what the loop gives up when the window
+  runs out, which the skill named a threshold for and never answered. The five-rung
+  compaction ladder, cheapest first, with a re-measure between rungs so a small
+  overage never buys a model call; the rung that exists only for the case where the
+  compaction request itself does not fit; the **tool-pair invariant** — one boundary
+  finder used by every rung, because a truncation that orphans a `tool_use` fails the
+  *next* request with a 400 in the middle of a task; **typed carryover blocks** copied
+  across the boundary rather than summarized, since a summarizer keeps the discussion
+  and drops the state, including the flag that said not to write; **tool-output
+  offload** to a file with the path left in context, because trimming history cannot
+  save a window one result already filled; token estimation and the direction it errs;
+  the compaction circuit breaker; sub-agent context isolation; the filesystem as
+  context; and how to pick constants for your own window.
+
+  Ladder structure and the attachment taxonomy are adapted from
+  [HKUDS/OpenHarness](https://github.com/HKUDS/OpenHarness) (MIT),
+  `services/compact/__init__.py` and `services/tool_outputs.py`. The constants are
+  deliberately ours — and deliberately absent, with anchors for choosing them, because
+  a threshold copied without its window is a number nobody can defend.
+
+### Changed
+
+- **§12 Context Engineering** in the body: five traps an agent cannot know to look up,
+  because it does not know they exist. **§7 gains Layer 0 — carryover state**, the one
+  memory layer whose survival is deterministic rather than a model's choice. §2 gains
+  the iteration refund. Body lands at 486 lines / ~4985 tokens against the 500 / 5000
+  budget — every insertion was cut twice to fit, and the depth is in the reference
+  where it belongs.
+
 ## [0.3.0] — 2026-08-12
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Production patterns for AI agent orchestrators — tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access. This package is the installer CLI.",
   "bin": {
     "agent-stack": "bin/agent-stack.js"

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Production patterns for AI agent orchestrators: tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-orchestrator/SKILL.md

@@ -137,6 +137,7 @@ else:
 - **In-loop trimming**: At ~80% capacity, collapse older assistant+tool pairs into one-liner summaries
 - **Token limit recovery**: On `LLMTokenLimitError`, compress to 60% and retry once. If still fails, return partial answer
 - **Max iterations guard**: Always have a hard limit. On exhaustion, compose best-effort answer from data gathered so far
+- **Iteration refund**: a recoverable provider error is not charged to that guard
 
 ---
 
@@ -323,6 +324,9 @@ context window, so allocation has to be decided per call rather than per layer:
 a session that trims chat history to fit a large set of learnings has quietly
 chosen old generalities over what the user said sixty seconds ago. Give layer 1
 a floor.
+
+**Layer 0 — carryover state.** Goal, artifacts, verified work and restrictive
+mode cross a compaction boundary as copied typed blocks, not prose (§12).
 ## 8. Self-Learning Feedback Loops
 
 ### Cycle 1: Automatic (Validation Loop)
@@ -436,6 +440,27 @@ async def handle_ask_user(tc, context, wf_id):
 
 ---
 
+## 12. Context Engineering
+
+**Compaction is a ladder, not a call.** Clear old tool results, collapse
+oversized blocks, condense messages, and only then pay a summarizer —
+re-measuring between rungs. Most pressure resolves before the first call.
+
+**Never orphan a `tool_use`.** Every truncation point lands *between* an
+assistant+tool pair, or the next request is a 400 in the middle of a task.
+
+**Carry state across the boundary as typed blocks, not prose** — goal,
+artifacts, verified work, restrictive mode. A summarizer keeps the discussion
+and drops the state, including the flag that said not to write anything.
+
+**Offload a large tool result to a file, keep the path.** Trimming history
+cannot save a window one tool output already filled.
+
+**A sub-agent's value is its own window**: it returns a typed summary, not a
+transcript.
+
+---
+
 ## Checklist — Building a New Orchestrator
 
 - [ ] Shared `AgentContext` dataclass with all sub-agents
@@ -459,6 +484,7 @@ async def handle_ask_user(tc, context, wf_id):
 - [ ] Multi-stage pipeline with checkpoints and resume
 - [ ] `ask_user` clarification mechanism
 - [ ] Graceful degradation (partial answers on context overflow or max iterations)
+- [ ] Compaction ladder, tool-pair-safe boundaries, typed carryover, output offload
 
 ---
 
@@ -470,4 +496,5 @@ are the territory.
 | File | Read it when |
 |---|---|
 | [`references/patterns.md`](references/patterns.md) | you need the **data models and algorithms**: message and result protocols, pipeline models, the SQL validation loop, context-window sizes and token estimation, learning-extraction heuristics, confidence lifecycle, fuzzy dedup, conflict resolution, cross-resource transfer, the no-LLM suggestion engine |
+| [`references/context-engineering.md`](references/context-engineering.md) | the loop is **running out of window**: the five-rung compaction ladder, the tool-pair boundary invariant, typed carryover attachments, tool-output offload, token estimation, the compaction circuit breaker, sub-agent isolation, and how to pick your own constants |
 | [`references/llm-proxy-billing.md`](references/llm-proxy-billing.md) | the product **resells LLM access**: tiered wallets and where markup applies, two-phase commit against a provider API with compensating transactions, advisory locking, optimistic concurrency for reclaims, spend-delta polling and its three cases, budget/loop/auto-pause guardrails, per-tenant key lifecycle and healing, the refund waterfall, model routing |

package/plugins/agent-stack/skills/agent-orchestrator/references/context-engineering.md

@@ -0,0 +1,201 @@
+# Context engineering — what survives the window, and how
+
+**Load this when** the loop is running out of window: choosing a compaction strategy,
+deciding what crosses the boundary, bounding a tool result that will not fit, or
+splitting message history without breaking the next request.
+
+`SKILL.md` §2 gives the loop and its two thresholds — trim at ~80% of the window,
+inject the wrap-up at ~70%. This file is what happens *at* those thresholds. The
+difference matters: §2 decides **when** to act, this decides **what to give up**.
+
+Ladder structure and the attachment taxonomy are adapted from
+[HKUDS/OpenHarness](https://github.com/HKUDS/OpenHarness) (MIT),
+`src/openharness/services/compact/__init__.py` and `services/tool_outputs.py`. The
+constants below are ours; theirs are tuned for a different window and a different tool
+mix, and a threshold copied without its context is a number nobody can defend.
+
+## Contents
+
+- The ladder — five rungs, cheapest first
+- Re-measure between rungs
+- The tool-pair invariant
+- Carryover attachments — what crosses the boundary
+- Tool-output offload
+- Estimating what you have left
+- The circuit breaker
+- Sub-agent context isolation
+- The filesystem as context
+- Choosing your own constants
+
+## The ladder — five rungs, cheapest first
+
+Compaction is not one call. It is an ordered set of strategies, and the expensive one
+is last. A loop that summarizes at the first sign of pressure pays a model call and a
+round-trip for what a string operation would have solved.
+
+| Rung | What it does | Cost | Loses |
+|---|---|---|---|
+| 1. Microcompact | Replace old tool results with a tombstone: `[tool result cleared]`. Keep the N most recent. | free | old observations, kept recent ones |
+| 2. Head/tail collapse | For an oversized text block, keep a head and a tail, elide the middle with a marker | free | the middle of long outputs |
+| 3. Session condensation | Collapse each older message to a one-line summary, capped in total | free | phrasing, keeps the thread of events |
+| 4. LLM compaction | One model call summarizes the transcript into a structured brief | a call + latency | anything the summarizer does not think to keep |
+| 5. Prompt-round truncation | Drop the oldest whole prompt rounds, boundary-aligned | free | the earliest history entirely |
+
+Rung 5 exists for one case: **the compaction request itself does not fit.** When rung 4
+fails because the transcript it must summarize is over the limit, summarizing harder is
+not available — you drop oldest rounds and retry, bounded by a small retry count.
+
+**Eligibility, not just age.** A tool result becomes a rung-1 candidate by size as well
+as position: anything past a few thousand characters, and every result from an external
+tool server, whose outputs are the usual window hog and the least likely to be re-read.
+
+## Re-measure between rungs
+
+After every rung, measure again and stop if you are under the threshold. Two failure
+modes hide here:
+
+- **Running the whole ladder every time** turns a 200-character overage into a model
+  call. Rung 1 usually settles it.
+- **Trusting a rung that did nothing.** Head/tail collapse on a transcript with no
+  oversized blocks changes nothing. If the estimate did not drop, reject the result and
+  escalate rather than recording a compaction that never happened.
+
+## The tool-pair invariant
+
+**A tool call and its result are one unit. Never split them.**
+
+Every provider rejects a request where an assistant message announces a tool call whose
+result is missing, or a tool result with no matching call. It is not a soft error — the
+next request fails, mid-task, with a 400 that names nothing useful.
+
+This makes every boundary computation in this file conditional: a truncation point, a
+collapse range, a dropped round must all land **between** pairs. Write the boundary
+finder once, use it from every rung, and give it a test that plants an orphan and
+requires rejection.
+
+The same invariant governs parallel dispatch: if one tool in a batch raises, its result
+block must still be emitted — as an error result. A sibling's crash is not a reason to
+send a malformed request.
+
+## Carryover attachments — what crosses the boundary
+
+A summarizer keeps prose and drops state. Ask one to compress a transcript and it will
+faithfully preserve the discussion while losing the fact that you are in a read-only
+mode, the path of the file you verified, and what the user actually asked for.
+
+So state does not go through the summarizer. It is accumulated during normal execution
+and re-attached after compaction as **typed blocks**:
+
+| Block | Carries | Why it is lost otherwise |
+|---|---|---|
+| `task_focus` | the goal, recent sub-goals, active artifacts, verified state, next step | the summarizer rewrites the goal into its own words and drifts |
+| `recent_files` | paths read or written, most recent first | the agent re-reads what it already has |
+| `verified_work` | what was checked and how it was checked | re-verification, or worse, a claim of verification that was never re-run |
+| `plan` | the active plan and any mode that restricts what may be done | **a safety mode forgotten across a boundary is how a read-only run starts writing** |
+| `invoked_skills` | which doctrine is already loaded | re-loading a large file that is already in effect |
+| `work_log` | one line per significant action | the agent repeats a step it already completed |
+
+Accumulate them in bounded buckets during the loop — a small cap per bucket, oldest
+evicted — so the attachment cost is known in advance and does not itself grow into a
+context problem. Cap the number of attached blocks too.
+
+The property that matters: this is **deterministic**. Structured state survives because
+it is copied, not because a model chose to keep it.
+
+## Tool-output offload
+
+One large tool result poisons a window before any history trimming is relevant. Trimming
+the conversation does not help when the problem is a single 200 KB response sitting in
+the current turn.
+
+The rule: **above an inline limit, write the full output to a file and put a preview
+plus the path into the context.** The model reads the preview, and when it needs the
+rest it reads the file with the tools it already has.
+
+- **Inline limit** — the size above which offload happens.
+- **Preview size** — enough to decide whether the rest is needed; head, or head and tail
+  when the tail carries the verdict (test runs, build logs).
+- **Path** — stable and unique per call, so two calls to the same tool do not collide.
+- **Location** — a scratch directory scoped to the run, not the project tree; artifacts
+  of a loop are not deliverables and must never arrive in a diff.
+
+Both limits belong in configuration. The right value depends on the window and the tool
+mix, and the only way to find it is to measure a real run.
+
+## Estimating what you have left
+
+Every threshold in this file depends on an estimate, and estimates are optimistic in the
+direction that hurts:
+
+- **Character-based estimation runs low.** A divisor calibrated on prose under-counts
+  code, JSON and non-Latin text. Apply a padding factor, and prefer being early over
+  being right.
+- **Non-text content costs more than its representation suggests.** An image is worth
+  hundreds to thousands of tokens depending on its dimensions; a reference to a file is
+  worth nothing until it is read.
+- **Reserve the output.** The threshold is not "the window" — it is the window minus the
+  space the answer needs, minus a buffer for the next tool result. Express the trigger
+  as a floor in absolute tokens, not only as a percentage: at a small window a
+  percentage silently reserves too little.
+
+## The circuit breaker
+
+Compaction can fail — the summarizer errors, the provider is down, the result does not
+shrink. **After a small number of consecutive failures, disable compaction for the run
+and degrade deliberately**: stop adding to the context, compose the best answer
+available, and say that compaction is unavailable.
+
+Without this, a failing compaction is retried at the top of every iteration, and the
+loop spends its remaining budget on the one operation that is not working.
+
+**Related: refund the iteration.** When an iteration ends in a recoverable provider
+error — a token limit that can be clamped and retried, a rate limit — do not charge it
+to the max-iteration guard. A misconfiguration should not consume the budget that exists
+to stop a runaway agent.
+
+## Sub-agent context isolation
+
+A sub-agent's value is not that it is a different prompt. **It is that it has its own
+window.**
+
+The contract: the sub-agent receives a task and the context it needs, works in a window
+the parent never sees, and returns a typed result — a summary, not a transcript. The
+parent's window grows by the size of the result, not by the size of the work.
+
+This makes delegation the strongest context tool available: a search across forty files
+costs the parent one paragraph. It also sets the design rule — if a sub-agent's return
+value is proportional to its input rather than its conclusion, it is a function call
+wearing a costume, and it will fill the parent's window anyway.
+
+## The filesystem as context
+
+Anything durable belongs in a file, not in the transcript:
+
+- **It survives the boundary.** Compaction cannot delete what was never in the window.
+- **It survives the process.** A crash loses the conversation and keeps the work.
+- **It is shared.** Two agents on one task coordinate through files; a transcript is
+  private to one loop.
+- **It is addressable.** A path is a few tokens; the content it names can be any size.
+
+The pattern is the same in each case: do the work, write the artifact, keep the path.
+Where the runtime offers no real filesystem, the same contract works over any keyed
+store — what matters is that the address is cheap and the content is retrievable, not
+that it is POSIX.
+
+## Choosing your own constants
+
+Every number in this file is deliberately absent, because the useful value depends on
+the window, the tool mix and the cost of a summarizer call in your stack. Pick them
+against these anchors:
+
+1. **Reserve output before you reserve anything else.** Start from window minus expected
+   answer minus one worst-case tool result.
+2. **Rung 1's keep-count** is the smallest number of recent tool results the loop
+   actually re-reads. Measure it; the intuition is always too high.
+3. **The inline limit for offload** should be crossed only by outputs that are genuinely
+   large — if half of all tool calls offload, the limit is too low and the model is
+   reading files instead of working.
+4. **The circuit-breaker count** is small. Three consecutive failures is a pattern, not
+   a coincidence.
+5. **Write them down where the loop reads them**, not inline at the call site. A
+   threshold nobody can find is a threshold nobody will tune.