## 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>
674 lines
22 KiB
Python
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
|