Raven-1/tests/test_subagent_memory.py
zhanghui e70a868e9c
refactor(*): seal the memory backend seam so a memory plugin needs no host edits (#414)
## Summary

Make `MemoryBackend` the only seam between the host and the memory
subsystem, so a second memory plugin can be installed without editing
host code.

The abstraction is the goal; no second backend is being added.

What the branch does:

- `health()` joins the Protocol. `raven doctor` and `raven import` read
a `BackendHealth(ready, checks)` the backend fills in with its own
vocabulary, instead of reaching into EverOS internals. Doctor prints the
checks verbatim and never interprets a label.
- A new `[[plugin.contributes.onboard]]` kind, with
`raven/contracts/onboard.py` as its paper. The host lends the wizard
shell as one `OnboardUI` and records the result; the screen returns a
`StepOutcome`. The plugin never writes `memory.backend` -- that key
stays the host's. EverOS's step-4 screen and its `everos.toml`
management move into the plugin.
- The skill source and the after-turn feedback prefix are named from
`memory.backend` rather than the literal `everos`.
- `enabled_by_default` is gone from the manifest: an installed plugin
the user has not disabled is active.
- `tests/test_plugin_boundary.py` pins the dependency direction in both
directions, with an equality assertion so the remaining exceptions
cannot grow.

That guard's allowlist started at five host files still speaking
EverOS's wire protocol. The follow-ups below close three of them.

Two things this branch itself introduced were found in manual acceptance
on an install without the plugin and fixed here: a turn printed which
backends were installed -- empty on exactly the install that needs the
sentence -- and `settings.everos` / `settings.everosSet` let
`ModuleNotFoundError` reach the dispatcher as an internal error carrying
a traceback. Both now carry the note doctor and the wizard already use,
naming the distribution to install.

Review on this PR found four blockers, all fixed and covered. A fifth
defect came out of manual acceptance rather than review, and four more
out of the rounds that followed it -- every one of those in the
embedding endpoint's own plumbing, each found by the round after the fix
that introduced it. They are listed under Risk; the blockers are:

1. `onboard` is an optional contribution, but the wizard equated "no
matching screen" with "not configured", so one `raven onboard
--skip-memory` wrote `memory.backend` back to null for a third-party
backend configured by hand. A backend with no screen now answers on the
strength of having been selected; only one whose own screen says it is
unconfigured is cleared, which is the case that rule exists for.
2. The record a sub-agent call leaves behind ran through a backend
nobody had started. The shipped adapter begins in an unknown state, so
the first flushing write only scheduled a readiness probe and answered
false -- the record said "unavailable" while the service was up the
whole time, and each per-record HTTP client was left open. One context
manager now owns start and stop around a record, in both the manager and
the DAG runner.
3. That record's write and the recall after it addressed different
owners: a real config spells its keys in camelCase and the block reaches
the backend as written, while the adapter read only the contract's
snake_case, so a sub-agent's memories were filed under the host
identity. The adapter reads both spellings.
4. Legacy embedding discovery had narrowed to the recorded plugin root,
so an install predating root recording lost its knowledge-base endpoint
with a valid file still on disk.

**The five follow-ups the seam left behind are in this PR too**, rather
than in three stacked ones, because they are one goal and the branch
protection dismisses an approval on every push:

- The embedding endpoint is raven's. A knowledge base indexes inside the
gateway process and never speaks to the memory service, yet it read its
endpoint out of everos.toml, so selecting another backend left it with
no vectors and no message naming the cause. Raven holds the block now
and hands it to the backend at start -- as a shared default, not an
override: a plugin that was given an endpoint of its own keeps it, and
only one that has none takes raven's. Discovery of an existing
everos.toml still checks all three places the plugin itself looks, read
with plain tomllib so it works where the plugin is not installed. No
data migrates: a base is keyed on its model and measured width, not on
the base url.
- `delete()` joins the Protocol. The browser used to delete a row out of
EverOS's index, in the host process, through the plugin's repository
layer -- while the markdown EverOS treats as the source of truth kept
the text, so the memory came back on the next rebuild, after the user
was told it was gone. The adapter now uses only operations EverOS
already performs, for the kinds it performs them for.
- Sub-agent memory goes through the contract. The read half is a new
optional `recall_session`; the write half needed no new surface, only
two metadata conventions written down. `agents.<name>.config.everos`
becomes `config.memory`, opaque to the host except the two keys the host
reads; the old spelling still loads.
- The memory and settings pages say why they are empty -- no plugin, or
a backend this page does not read -- instead of four zeros and a retry
button that cannot help.
- The `everos` package leaves the host's dependencies for the plugin's
own, at the same exact pin; the host reaches the tree through the
plugin. This is the package layer only: the installers already deliver
`everos-memory` as a sibling wheel from the same release, so an ordinary
install still has long-term memory.

The boundary guard's allowlist falls from five entries to two, both GUI
surfaces still shaped around EverOS's own store. Generalising their wire
is a frontend change and is deliberately not in scope.

This branch was reviewed on GitLab as merge request 639 over three
rounds, including a post-rebase range-diff check. It is being moved here
because GitHub is now the source of truth.

## Type

- [x] Refactor

## Verification

- `uv run pytest` on this branch, rebased onto `main`: 22146 passed, 4
failed, 45 skipped. Three of the four (`test_agents_oncall_launcher`,
`test_agent_loop_token_budget`, `test_agents_code_launcher`) were re-run
on a detached checkout of that same `main` commit in this environment
and fail there identically. The fourth (`test_ppt_engine_image_search`)
could not run in that checkout, whose environment lacks the deck
engine's extras; this branch's only change anywhere under
`plugins-dist/ppt-engine` is the removal of the `enabled_by_default`
manifest key, which that test does not reach. So this branch adds no
regression.
- `npx vitest run` in ui-web: 1680 passed across 103 files. `npm run
type-check` and `npm run gen:check` clean, so the generated client
matches the contract.
- Every fix in the follow-up commits was mutated away and its test
confirmed red, then restored and confirmed green. For the record path
that is three separate mutations: dropping `start()`, dropping `stop()`,
and narrowing the owner lookup back to one spelling.
- `uv run ruff check .` and `uv run ruff format --check` on the changed
files: clean.
- `uv lock --check`: consistent.
- `scripts/check_commit_messages.py`, `scripts/check_large_files.py`,
`scripts/check_source_language.py` over the branch range: clean.
- Manual acceptance against a real isolated install (temporary
RAVEN_HOME, isolated EverOS root and port), 34 cases: `raven plugins`,
`raven doctor` across four backend states, `raven onboard` interactive
and non-interactive including all three step-4 lanes, `raven import`
refusing and importing, an end-to-end write and recall, the web UI's
memory and settings pages driven through a real browser, a sub-agent
trace record, and an install with no memory plugin at all. 31 passed; 1
failed and was fixed; 1 partial; 1 carried over from the earlier round.
- The failure is the one worth reading. On a fresh managed install the
wizard reported embedding configured and the service it started the next
moment ran keyword-only: the spawned process carried no
`EVEROS_EMBEDDING__` values, and EverOS logged that the embedding key
was not configured. The rule deciding whether everos.toml already held
an operator's own endpoint asked whether its model name was a `"<...>"`
placeholder; the shipped template seeds every section with a real model
name and an empty key, so every fresh install read as a deliberate
choice and the host's endpoint was never bound. It now asks the
criterion the module already had -- model and key. The unit tests missed
it because each built its "operator's own" section with a key in it; the
regression copies the shipped template itself.
- The partial: the memory page's search returned relevant results
without error, but every memory in the test corpus was on one subject,
so narrowing could not be observed. The carried-over case is the
skill-source prefix, whose path this branch does not touch.
- Findings recorded and not fixed here, none introduced by this branch:
a progress spinner is still drawn after `import` reports it imported
nothing; an unsupported delete surfaces as a generic internal error; the
TUI log and `doctor` word "no memory plugin" differently; a turn that
did reach disk still prints that it was not written.
- The partial case: an induced agent skill is discovered through
`find_skill` with the backend's prefix, but `read_skill` / `use_skill`
on that id fail. Nothing writes the on-disk layer those tools look in,
on this branch or on `main`, and no test covers it. Pre-existing; filed
as a follow-up.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

User-visible changes:

1. User-track recall is now strictly bounded by `top_k`. A profile row
used to ride outside that bound.
2. `raven doctor` builds the plugin factory, so a managed EverOS setup
writes its env var and config templates during a doctor run. It used to
be read-only. The `--json` memory section is reshaped around
`health.checks`.
3. A third-party drop-in plugin without `enabled_by_default = true` used
to be skipped and now loads.
4. The loader no longer back-fills the EverOS config slice's `root` /
`owned`, nor strips a legacy `mode` key; a leftover `mode` now draws an
unknown-key warning.
5. The wizard's recap shows the contribution name `everos` rather than
`EverOS`.
6. `use_skill` with an unknown prefix reports "not found" after a disk
lookup instead of "unknown source".

From the follow-ups:

7. Config gains an optional top-level `embedding` block. Absent, the
knowledge base reads the EverOS file as before and says so once. An
operator who moves the values across changes nothing else; one who names
a *different* model there gets the existing `StaleBaseError` telling
them to rebuild that base. The block is a default for the memory plugin
rather than an override, so an install that had configured the plugin
separately keeps what it had. Note that a config carrying this block
does not load on an older Raven, which rejects unknown top-level keys.
8. `agents.<name>.everos` is written back as `agents.<name>.memory`. The
old spelling still loads; a per-agent `baseUrl` is ignored with a
warning, having never had a user.
9. Deleting a memory now changes what EverOS treats as the source of
truth, so it stays deleted. Profiles and cases report that they cannot
be deleted rather than appearing to succeed.
10. `pip install raven` no longer pulls the memory engine in.
`install.sh` and `install.ps1` are unaffected: both already resolve
`everos_memory-*.whl` from the release they install and pass it as
`--with everos-memory`, and the source path installs it editable, so
those installs keep long-term memory. An install that reaches neither --
a release predating the sibling wheel, or a bare `pip install` -- now
boots without memory and says which distribution to install rather than
failing on an import.

Found after the acceptance run, in review, all fixed here. They share
one cause worth stating once: the endpoint acquired a second home, and
each fix taught one more reader about it while leaving the next one
behind.

11. The endpoint the wizard saved never reached the EverOS process it
then started. The rule for "does everos.toml already hold an operator's
own endpoint" asked whether its model name was a `"<...>"` placeholder;
the shipped template seeds every section with a real model name and an
empty key, so every fresh managed install read as a deliberate choice
and the host's endpoint was never bound. The service came out of the
wizard running keyword-only while the wizard said embedding was
configured. The rule now asks the criterion the module already had:
model and key.
12. The exported `EVEROS_EMBEDDING__*` variables are a third home,
documented by EverOS and ranked above its file. They were being
overwritten. A complete triple is now an operator's choice; an
incomplete one is not an endpoint and is replaced whole rather than
topped up from the host.
13. Raven writes those same variables itself at startup, so a reader
that asked only whether all three were set called raven's own binding an
operator's export -- a blank settings card and a save refused by naming
variables nobody had set. The module now records which of them it set.
14. That record lived in a module-level set, and `raven gateway
--restart` re-launches through `os.execv`: the values survive, module
state does not. The record now travels in a variable beside them, and is
stripped from the environment handed to EverOS.
15. A settings save the environment would outrank is refused with the
variable names, rather than written and silently ignored.

Four of the five arrived one per review round, each in the fix for the
one before it. The tests that missed them all shared a shape: each built
its "an operator configured this" fixture with a key in it, or cleared
the environment before the case, so the states the product actually
produces -- a template with no key, a live process that has just bound
its own endpoint -- were never the input. The regressions now copy the
shipped template, and run the startup sequence and a second interpreter
rather than a prepared state.

Rollback is a revert of the branch: the seam is additive, and
`memory.backend` keeps its shipped default.

- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-09-16 22:19:50 +08:00

674 lines
22 KiB
Python

"""The Memory record: what a sub-agent left in long-term memory for one call.
The module speaks the MemoryBackend contract and nothing else, so the double
here is a backend, not a transport. What a row looks like on the wire, and how
it renders, belongs to whichever backend is installed and is tested with it.
"""
from __future__ import annotations
import asyncio
import json
import time
from collections.abc import Callable
import pytest
from raven.agent import subagent_memory as subagent_memory_mod
from raven.agent.subagent_memory import (
MemoryScope,
collect_memories,
prime_from_turn,
record_memories,
scope_from_config,
trace_session_id,
)
from raven.config.schema import SubagentMemoryConfig
from raven.contracts.memory import Memory
class _FakeBackend:
"""A memory backend that records what it was asked and answers canned rows.
Rows are keyed by track, which is the only distinction the contract makes:
the host names a track and reads ``Memory.text``, and everything about how
a backend stores or renders a memory stays behind that.
"""
def __init__(self) -> None:
self.reads: list[tuple[str, str | None, str | None]] = []
self.writes: list[tuple[str, list[dict], dict | None]] = []
self.rows: dict[str, list[Memory]] = {"user_id": [], "agent_id": []}
self.raises: Exception | None = None
self.store_answer: bool = True
async def recall_session(self, session_id, *, user_id=None, agent_id=None):
self.reads.append((session_id, user_id, agent_id))
if self.raises is not None:
raise self.raises
return list(self.rows["user_id" if user_id else "agent_id"])
async def store(self, session_id, messages, *, metadata=None):
self.writes.append((session_id, list(messages), metadata))
if self.raises is not None:
raise self.raises
return self.store_answer
def _memory(text: str, kind: str = "episode") -> Memory:
return Memory(text=text, metadata={"type": kind})
def _scope(**kw) -> MemoryScope:
block = {
"user_id": kw.get("user_id", "raven-code"),
"agent_id": kw.get("agent_id", "raven-code"),
}
return MemoryScope(
block={k: v for k, v in block.items() if v},
source=kw.get("source", "agent"),
session_prefix="cli:",
)
def _sink() -> tuple[list[str], Callable]:
written: list[str] = []
async def write(text: str) -> None:
written.append(text)
return written, write
async def _key() -> str:
return "cli:abc"
# --------------------------------------------------------------------------- scope
def test_no_config_means_no_scope() -> None:
assert scope_from_config(None) is None
def test_the_block_reaches_the_backend_unread() -> None:
"""Which keys identify a memory is the backend's vocabulary. The host reads
two: which path to run, and how the fork prefixes its session id."""
scope = scope_from_config(
SubagentMemoryConfig.model_validate(
{"userId": "u", "agentId": "a", "source": "trace", "sessionPrefix": "x:", "mem0Space": "s"}
)
)
assert scope is not None
assert scope.source == "trace" and scope.session_prefix == "x:"
assert scope.block == {"userId": "u", "agentId": "a", "mem0Space": "s"}
assert (scope.user_id, scope.agent_id) == ("u", "a")
def test_source_defaults_to_agent() -> None:
scope = scope_from_config(SubagentMemoryConfig.model_validate({"userId": "u"}))
assert scope is not None and scope.source == "agent"
def test_a_declared_base_url_is_dropped_with_a_warning() -> None:
"""No config, fixture or document ever set one, and honouring it would mean
every backend growing a per-call way to address a different server."""
scope = scope_from_config(SubagentMemoryConfig.model_validate({"userId": "u", "baseUrl": "http://elsewhere"}))
assert scope is not None
assert "baseUrl" not in scope.block and "base_url" not in scope.block
# --------------------------------------------------------------------------- reading back
@pytest.mark.asyncio
async def test_both_tracks_are_asked_for_separately() -> None:
"""The contract takes one track per call, so each declared owner is its own
question."""
backend = _FakeBackend()
backend.rows["user_id"] = [_memory("Ran the audit.")]
backend.rows["agent_id"] = [_memory("Fixed the tokenizer.", "agent_case")]
items = await collect_memories(backend, _scope(), "cli:abc")
assert backend.reads == [("cli:abc", "raven-code", None), ("cli:abc", None, "raven-code")]
assert [i.text for i in items] == ["Ran the audit.", "Fixed the tokenizer."]
@pytest.mark.asyncio
async def test_only_the_declared_owner_is_asked() -> None:
backend = _FakeBackend()
backend.rows["agent_id"] = [_memory("Fixed the tokenizer.", "agent_case")]
await collect_memories(backend, _scope(user_id=None), "cli:abc")
assert backend.reads == [("cli:abc", None, "raven-code")]
@pytest.mark.asyncio
async def test_a_memory_with_no_usable_text_is_dropped() -> None:
backend = _FakeBackend()
backend.rows["user_id"] = [_memory(" "), _memory("Ran the audit.")]
items = await collect_memories(backend, _scope(agent_id=None), "cli:abc")
assert [i.text for i in items] == ["Ran the audit."]
@pytest.mark.asyncio
async def test_a_backend_failure_propagates_to_the_caller() -> None:
"""The caller decides what an unreachable memory service means for the
record; this function does not get to swallow it."""
backend = _FakeBackend()
backend.raises = RuntimeError("service down")
with pytest.raises(RuntimeError):
await collect_memories(backend, _scope(), "cli:abc")
# --------------------------------------------------------------------------- the record
@pytest.mark.asyncio
async def test_a_found_memory_is_recorded_as_settled() -> None:
backend = _FakeBackend()
backend.rows["user_id"] = [_memory("Ran the audit.")]
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=backend,
scope=_scope(agent_id=None),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
assert json.loads(written[0]) == {
"agent": "Raven-Code",
"source": "agent",
"status": "settled",
"memories": [{"type": "episode", "text": "Ran the audit."}],
}
@pytest.mark.asyncio
async def test_nothing_found_within_the_budget_is_pending() -> None:
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(agent_id=None),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
assert json.loads(written[0])["status"] == "pending"
@pytest.mark.asyncio
async def test_an_unreachable_backend_is_unavailable_not_a_raise() -> None:
backend = _FakeBackend()
backend.raises = RuntimeError("service down")
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=backend,
scope=_scope(),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
assert json.loads(written[0])["status"] == "unavailable"
@pytest.mark.asyncio
async def test_no_join_key_writes_no_file_at_all() -> None:
"""There is nothing truthful to say about a call with no session id."""
written, write = _sink()
async def _none() -> None:
return None
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(),
resolve_session_id=_none,
write=write,
budget_s=0.0,
)
assert written == []
@pytest.mark.asyncio
async def test_polling_stops_once_the_result_stops_growing(monkeypatch) -> None:
monkeypatch.setattr("raven.agent.subagent_memory._BACKOFF_S", (0.01, 0.02, 0.04))
backend = _FakeBackend()
backend.rows["user_id"] = [_memory("First.")]
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=backend,
scope=_scope(agent_id=None),
resolve_session_id=lambda: _key(),
write=write,
budget_s=5.0,
)
# One look finds it, a second confirms it stopped growing. No third.
assert len(backend.reads) == 2
assert json.loads(written[0])["status"] == "settled"
@pytest.mark.asyncio
async def test_a_failing_write_never_raises_at_the_caller() -> None:
"""An audit trail written after the call already answered must not disturb
anything by failing."""
async def write(_: str) -> None:
raise OSError("read-only file system")
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
@pytest.mark.asyncio
async def test_a_failing_resolver_never_raises_at_the_caller() -> None:
written, write = _sink()
async def _boom() -> str:
raise RuntimeError("registry gone")
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(),
resolve_session_id=_boom,
write=write,
budget_s=0.0,
)
assert written == []
@pytest.mark.asyncio
async def test_a_transient_failure_after_growth_keeps_what_was_found(monkeypatch) -> None:
monkeypatch.setattr("raven.agent.subagent_memory._BACKOFF_S", (0.01,))
backend = _FakeBackend()
backend.rows["user_id"] = [_memory("First.")]
written, write = _sink()
real = backend.recall_session
calls = {"n": 0}
async def flaky(session_id, **kw):
calls["n"] += 1
if calls["n"] > 1:
raise RuntimeError("dropped")
return await real(session_id, **kw)
backend.recall_session = flaky # type: ignore[method-assign]
await record_memories(
agent="Raven-Code",
backend=backend,
scope=_scope(agent_id=None),
resolve_session_id=lambda: _key(),
write=write,
budget_s=5.0,
)
payload = json.loads(written[0])
assert payload["status"] == "settled"
assert [m["text"] for m in payload["memories"]] == ["First."]
@pytest.mark.asyncio
async def test_a_stalled_look_is_cut_off_by_the_remaining_budget() -> None:
"""``budget_s`` bounds the whole poll, not just the sleeps between looks.
The first look always runs in full -- a budget of zero still means "look
once" -- but a later one that runs past its share of the remaining budget
must be cut off rather than left to its own, much longer, timeout, or a
stalled backend keeps a recorder alive for minutes past what the budget
says.
"""
backend = _FakeBackend()
calls = {"n": 0}
async def first_answers_then_stalls(session_id, **kw):
calls["n"] += 1
if calls["n"] == 1:
return [_memory("First.")]
await asyncio.sleep(2.0)
return []
backend.recall_session = first_answers_then_stalls # type: ignore[method-assign]
written, write = _sink()
started = time.monotonic()
await record_memories(
agent="Raven-Code",
backend=backend,
scope=_scope(agent_id=None),
resolve_session_id=lambda: _key(),
write=write,
budget_s=1.0,
)
elapsed = time.monotonic() - started
# 1s of slack over a 1s budget: the bound is on wall time, so the margin
# that matters is absolute, and scaling it down with the budget is what
# would turn a slow case into an intermittent one.
assert elapsed < 2.0, "a stalled look must not be allowed to run past the budget"
payload = json.loads(written[0])
assert payload["status"] == "settled"
assert payload["memories"] == [{"type": "episode", "text": "First."}]
@pytest.mark.asyncio
async def test_the_record_names_the_instance() -> None:
"""Unlike the identity and session id, this is something the reader can act
on: passing it back as ``spawn``'s ``instance`` continues the same
conversation."""
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
instance="inst-1",
)
assert json.loads(written[0])["instance"] == "inst-1"
@pytest.mark.asyncio
async def test_a_call_with_no_instance_omits_the_key() -> None:
"""A key that is always present but usually empty costs every reader a
check."""
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
assert "instance" not in json.loads(written[0])
@pytest.mark.asyncio
async def test_the_record_names_its_source() -> None:
"""A memory the agent wrote and one the host synthesised from its
transcript are not equally strong evidence."""
written, write = _sink()
await record_memories(
agent="Raven-Code",
backend=_FakeBackend(),
scope=_scope(source="trace"),
resolve_session_id=lambda: _key(),
write=write,
budget_s=0.0,
)
assert json.loads(written[0])["source"] == "trace"
# --------------------------------------------------------------------------- priming
class TestPrimeFromTurn:
"""The host hands its own backend a conversation nobody wrote memories for."""
@pytest.mark.asyncio
async def test_the_turn_is_stored_with_flush_and_its_owners(self) -> None:
"""``flush`` because the conversation has already ended -- waiting for
the backend's cadence would wait for a turn that never comes -- and the
owners because the content is the sub-agent's, not the host's."""
backend = _FakeBackend()
assert await prime_from_turn(
backend=backend,
scope=_scope(),
session_id="cli:abc",
turn=[{"role": "user", "content": "do it"}],
)
session_id, messages, metadata = backend.writes[0]
assert session_id == "cli:abc"
assert [m["content"] for m in messages] == ["do it"]
assert metadata["flush"] is True
assert metadata["user_id"] == "raven-code" and metadata["agent_id"] == "raven-code"
@pytest.mark.asyncio
async def test_an_empty_turn_writes_nothing(self) -> None:
backend = _FakeBackend()
assert await prime_from_turn(backend=backend, scope=_scope(), session_id="s", turn=[]) is False
assert backend.writes == []
@pytest.mark.asyncio
async def test_a_missing_owner_writes_nothing(self) -> None:
"""A missing owner must not fall back to a shared default: that would
write this sub-agent's memories into the host's own track."""
for scope in (_scope(user_id=None), _scope(agent_id=None)):
backend = _FakeBackend()
landed = await prime_from_turn(
backend=backend,
scope=scope,
session_id="s",
turn=[{"role": "user", "content": "x"}],
)
assert landed is False
assert backend.writes == []
@pytest.mark.asyncio
async def test_a_refused_write_is_false_not_an_exception(self) -> None:
backend = _FakeBackend()
backend.store_answer = False
assert (
await prime_from_turn(
backend=backend,
scope=_scope(),
session_id="s",
turn=[{"role": "user", "content": "x"}],
)
is False
)
@pytest.mark.asyncio
async def test_a_raising_backend_is_false_not_an_exception(self) -> None:
"""The caller's next move is to record ``unavailable``, not to fail a
run."""
backend = _FakeBackend()
backend.raises = RuntimeError("service down")
assert (
await prime_from_turn(
backend=backend,
scope=_scope(),
session_id="s",
turn=[{"role": "user", "content": "x"}],
)
is False
)
@pytest.mark.asyncio
async def test_the_prompt_is_never_timestamped_after_the_work(self) -> None:
"""``append_turn`` stamps the user row when the turn ends, so its clock
is later than the work it caused; a consumer sorting by timestamp would
read the prompt as the last thing that happened."""
backend = _FakeBackend()
await prime_from_turn(
backend=backend,
scope=_scope(),
session_id="s",
turn=[
{"role": "user", "content": "ask", "timestamp": "2026-09-15T10:00:09Z"},
{"role": "assistant", "content": "work", "timestamp": "2026-09-15T10:00:05Z"},
],
)
_, messages, _ = backend.writes[0]
# Only the first row moves, and only backwards: it is rewritten to an
# epoch just before the earliest of the rest.
assert subagent_memory_mod._as_ms_epoch(messages[0]["timestamp"]) < subagent_memory_mod._as_ms_epoch(
messages[1]["timestamp"]
)
class TestTraceSessionId:
def test_id_is_its_own_namespace(self) -> None:
assert trace_session_id("Raven-Code", "t1").startswith("trace:")
def test_id_is_unique_per_call(self) -> None:
assert trace_session_id("a", "t1") != trace_session_id("a", "t2")
class TestMonotonic:
def test_an_already_ordered_turn_passes_through_untouched(self) -> None:
turn = [
{"role": "user", "content": "a", "timestamp": "2026-09-15T10:00:00Z"},
{"role": "assistant", "content": "b", "timestamp": "2026-09-15T10:00:05Z"},
]
assert subagent_memory_mod._monotonic(turn) == turn
def test_a_single_row_turn_passes_through(self) -> None:
turn = [{"role": "user", "content": "a"}]
assert subagent_memory_mod._monotonic(turn) == turn
class TestStartedBackend:
"""The record path owns the backend's lifecycle, and survives it failing.
A record is an audit trail written after the call it describes has already
answered, so nothing here may reach the caller as an exception -- but a
backend that never started must also not be written to, and one that was
started must be stopped whatever the record did.
"""
async def test_no_backend_yields_nothing_to_write_to(self) -> None:
async with subagent_memory_mod.started_backend(None, label="test") as backend:
assert backend is None
async def test_a_backend_that_will_not_start_is_never_written_to(self) -> None:
events: list[str] = []
class _WontStart:
async def start(self) -> None:
events.append("start")
raise RuntimeError("no service")
async def stop(self) -> None:
events.append("stop")
async with subagent_memory_mod.started_backend(_WontStart(), label="test") as backend:
assert backend is None, "a failed start must not hand the caller a backend"
# Not stopped: nothing was opened, and a `stop` after a failed `start`
# is the one call an adapter is least likely to have made safe.
assert events == ["start"]
async def test_a_failing_stop_does_not_lose_the_record(self) -> None:
did_the_work = False
class _WontStop:
async def start(self) -> None:
return None
async def stop(self) -> None:
raise RuntimeError("socket already gone")
async with subagent_memory_mod.started_backend(_WontStop(), label="test") as backend:
assert backend is not None
did_the_work = True
assert did_the_work
class TestRecordFailureModes:
"""A prime or a poll that fails is a status in the record, never a raise."""
async def test_a_prime_that_raises_records_unavailable_without_polling(self) -> None:
backend = _FakeBackend()
backend.rows["user_id"] = [_memory("something extracted")]
written, write = _sink()
async def _prime(_session_id: str) -> bool:
raise RuntimeError("everos refused the handover")
await record_memories(
agent="Coder",
backend=backend,
scope=_scope(source="trace"),
resolve_session_id=_key,
write=write,
prime=_prime,
)
record = json.loads(written[0])
assert record["status"] == "unavailable"
assert record["memories"] == []
# Nothing landed, so nothing can have been extracted: spending the
# budget confirming an absence already known is the bug this guards.
assert backend.reads == []
async def test_a_poll_that_raises_records_unavailable(self) -> None:
backend = _FakeBackend()
backend.raises = RuntimeError("connection refused")
written, write = _sink()
await record_memories(
agent="Coder",
backend=backend,
scope=_scope(),
resolve_session_id=_key,
write=write,
budget_s=0.0,
)
record = json.loads(written[0])
assert record["status"] == "unavailable"
assert record["memories"] == []
class TestAsMsEpoch:
"""Timestamps arrive in whatever shape the turn log wrote them."""
def test_an_unparseable_string_is_no_timestamp_rather_than_a_raise(self) -> None:
assert subagent_memory_mod._as_ms_epoch("last tuesday") is None
def test_a_shape_with_no_clock_in_it_is_no_timestamp(self) -> None:
assert subagent_memory_mod._as_ms_epoch({"when": 1}) is None
assert subagent_memory_mod._as_ms_epoch(None) is None