Skip to content

feat: support awaited extension continuity across compaction - #687

Open
phernandez wants to merge 3 commits into
huggingface:mainfrom
basicmachines-co:fix/compaction-lifecycle-memory
Open

feat: support awaited extension continuity across compaction#687
phernandez wants to merge 3 commits into
huggingface:mainfrom
basicmachines-co:fix/compaction-lifecycle-memory

Conversation

@phernandez

@phernandez phernandez commented Sep 6, 2026

Copy link
Copy Markdown

This is a Basic Machines contribution for Basic Memory, our local-first knowledge and memory system for AI agents. We are adding durable session continuity to Tau and contributing the required host APIs upstream.

The source branch lives in the Basic Machines Tau fork. This replaces #683. Follow-up commit d8216af removes redundant branch snapshot copying: the session makes the defensive deep copy once and the extension returns that snapshot directly. Regression tests verify snapshot reuse and nested mutation isolation.

Why

Refs #506. Memory extensions need to finish a checkpoint before context replacement, recover its receipt on the correct branch, and insert recall before the next prompt without triggering another agent response. Basic Memory is the concrete consumer: basicmachines-co/basic-memory#1489.

What Changed

  • A single CodingSession helper emits awaited extension start/end callbacks for manual, detailed manual, threshold, and overflow compaction. No-op threshold checks emit nothing; failure/cancellation emits an aborted end.
  • context.branch_entries: deep-copied persisted active-path entries, including custom receipts, for reload/resume reconciliation and branch lineage.
  • await context.summarize(messages, instructions=..., timeout=60): bounded tool-free synthesis using the active model/provider, without an agent turn or history mutation. Generation guards reject late results.
  • await tau.append_message(content, custom_type=...): persist reference context while idle before the next prompt. Queued follow-ups—even with trigger_turn=False—can generate another model response; this method does not queue a turn.
  • In-place tree branching emits shutdown/start(reason="branch") on the same runtime. Extensions must support closing and restarting resources.

Design and Boundaries

No persistence destinations, exposed credentials, installed-package patches, or detached summary tasks in core. Extensions select inputs, own cancellation, validate writes and retain receipts. Observation failures preserve the diagnostic-only contract; this is not a compaction veto API.

This addresses extension delivery from #506, not threshold/manual frontend async-iterator or TUI status work, and deliberately does not close that issue. entry_appended delivery is unchanged; persisted active-path inspection supports receipt reconstruction without it.

Verification

  • uv run pytest -q: 1882 passed, 2 Windows-only tests skipped on macOS.
  • uv run mypy: passed for 121 source files.
  • Ruff lint/format: passed.
  • Focused session/continuity tests prove a blocked start handler finishes before replacement, receipts persist through all four paths, no-op/cancellation semantics, summary isolation, zero-turn context insertion, and tree lifecycle notifications.
  • Downstream Basic Memory integration (previously verified against f4124253, not rerun for d8216af): 51 tests pass, including actual session compaction/reload/branch/resume, headless Textual /reload, and real Basic Memory transcript/checkpoint persistence in temporary projects. Model providers are deterministic fakes; no production user session or paid model was used.

Risks

Summary calls use the active provider's ordinary routing/billing. Extensions must choose bounded inputs and timeouts and must not treat a queued instruction or diagnostic-only callback as acknowledgement of an external write. References inserted with append_message are persisted custom messages and contribute to normal context size until compacted.

Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: phernandez <paul@basicmachines.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant