Compare commits

..

1 Commits

Author SHA1 Message Date
Dizhan Xue
de8503b272 fix(rpc): treat a null section as absent when settings.set writes a key
The loader reads a null skillForge or skill_forge section as an absent
one, and skill block and unblock now agree. The settings writer did not:
_write_raw_key walked the dotted path with setdefault, which hands back
the stored null, and raised "blocked by non-object", so the settings
page could not change the skill blocklist of such a config.

A null section on the way to the key is now written as an empty object
under the spelling the file already uses. A section that is neither an
object nor null is still refused, and left as it is.
2026-10-12 11:40:33 +00:00
807 changed files with 5179 additions and 128389 deletions

View File

@ -27,8 +27,7 @@ irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.
```
The installer puts uv, Node.js 22, Raven and its plugins in place, downloads the
browser runtime and the word dictionary and PDF models the knowledge reader uses
(about 110 MB), installs or offers LibreOffice, and then finishes by opening
browser runtime, installs or offers LibreOffice, and then finishes by opening
Raven in your browser. First-run setup happens on that page. The installer holds
the terminal while the page is up; press Ctrl-C to stop it, then start Raven
again with:
@ -38,22 +37,15 @@ raven web
```
That keeps Raven running in the background and opens the page; `raven web --stop`
stops it. Bare `raven` does the same, and opens the TUI only where no browser
can be opened. Prefer the terminal? `raven tui` runs the same first-run setup and
opens the TUI, and `raven onboard` stays the explicit way to reconfigure later.
Set `RAVEN_MINIMAL=1` to skip the browser, model and LibreOffice downloads, or
`RAVEN_NO_LAUNCH=1` to have the installer return without opening the page. The
Windows installer does not download the dictionary and models; there, and after
`RAVEN_MINIMAL=1`, `raven resources` fetches them.
stops it. Prefer the terminal? `raven` runs the same first-run setup and opens
the TUI, and `raven onboard` stays the explicit way to reconfigure later. Set
`RAVEN_MINIMAL=1` to skip the browser and LibreOffice downloads, or
`RAVEN_NO_LAUNCH=1` to have the installer return without opening the page.
## Upgrade
Already running Raven? Upgrade in place -- configuration, sessions, and memory
are preserved. On a `raven web` install whose page is served by 0.2.3 or later,
the update row at the bottom of the sidebar does this for you, and the page
reloads itself, still signed in, once the new version is up. A page served by
0.2.2 or earlier refuses it; from the command line, stop the page first, then
upgrade:
are preserved. Stop the page first, then upgrade:
```bash
raven web --stop
@ -83,10 +75,9 @@ one-line installer also upgrades, and ends on the running page.
- Version: `__VERSION__`
- Tag: `__TAG__`
- Stability: <!-- TODO: e.g. public preview patch / public preview minor -->
- Assets: the `raven` wheel and source distribution, four plugin wheels
(`everos_memory`, `everos_cloud_memory`, `design_engine`, `ppt_engine`), the
locked constraints file `raven-constraints.txt`, and the plugin list
`raven-plugins.txt`, which installs every plugin wheel but `everos_cloud_memory`
- Assets: the `raven` wheel and source distribution, the three plugin wheels
(`everos_memory`, `design_engine`, `ppt_engine`), the locked constraints file
`raven-constraints.txt`, and the plugin list `raven-plugins.txt`
## Notes

View File

@ -380,68 +380,6 @@ jobs:
# buy nothing -- the plugin only has to exist.
run: uvx --python 3.12 --from "pytest>=8,<10" --with pytest-asyncio --with pytest-xdist pytest --noconftest tests/integration/test_cli_upgrade_real_uv.py -q
windows-acp:
name: Windows ACP stdio
runs-on: windows-latest
timeout-minutes: 15
env:
PYTHONUTF8: "1"
steps:
- uses: actions/checkout@v7
- name: Install uv
uses: astral-sh/setup-uv@v8.2.0
- name: Install the test environment
run: uv sync --frozen --python 3.13 --extra dev
- name: Test that the suite keeps out of the runner's own home
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_conftest_home.py -q -n 0 --tb=short
- name: Test ACP handshakes and bundled launchers
run: uv run --frozen --python 3.13 --no-sync pytest tests/integration/test_acp_stdio_smoke.py -m integration -q -n 0 --tb=short
- name: Test the registered launcher command
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_cli_agents_commands.py::test_register_pins_the_resolved_row_into_the_host_roster -q -n 0 --tb=short
- name: Test a connect's checks against a live process tree
run: uv run --frozen --python 3.13 --no-sync pytest tests/integration/test_subagent_connect_windows_real_process.py -m integration -q -n 0 --tb=short
- name: Test Windows ACP teardown
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_subagent_acp.py -k close_without_killpg -q -n 0 --tb=short
- name: Test conditional DAG paths
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_subagent_dag_core.py -k at_nodes -q -n 0 --tb=short
- name: Test DAG finish-text paths
run: |
$env:PATH = (Join-Path $env:ProgramFiles 'Git\usr\bin') + ';' + $env:PATH
uv run --frozen --python 3.13 --no-sync pytest tests/test_subagent_dag_runner.py -k 'test_the_finish_text or test_branch_e2e_one_tool_call' -q -n 0 --tb=short
# A launch rewrites the agents' prompt files. Keeping a private file's
# DACL and recovering from a read-only one are Windows facts the Linux
# shards skip.
- name: Test regenerated prompt files
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_config_product_render.py tests/test_atomic_io.py::test_a_failed_replace_takes_its_tmp_with_it tests/test_atomic_io.py::test_a_read_only_tmp_a_dead_writer_left_does_not_block_the_replace -q -n 0 --tb=short
# On Windows the Mirasim desktop host is reached over the loopback port
# and its token file, never a unix socket, and the unit shards run on
# Linux only -- so the adapter's own road is exercised natively here.
- name: Test the Mirasim adapter over the loopback port
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_acp_mirasim_host.py tests/test_acp_mirasim_server.py tests/test_subagent_mirasim.py tests/test_acp_client_teardown.py -q -n 0 --tb=short
- name: Test Raven-Code file diagnostics and worker limits on Windows
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py -q -n 0 --tb=short
- name: Test Raven-Code exec diagnostics with the native Windows executor
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_flow_exec.py -k test_exec_ -q -n 0 --tb=short
- name: Test Windows MCP lending and endpoint lifetimes
run: uv run --frozen --python 3.13 --no-sync pytest tests/test_mcp_transport.py tests/test_mcp_bridge.py tests/test_mcp_endpoint.py tests/test_cli_mcp_commands.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_node_client.py -q -n 0 --tb=short
- name: Test Windows MCP bridge against a real server
run: uv run --frozen --python 3.13 --no-sync pytest tests/integration/test_mcp_bridge_e2e.py -m integration -q -n 0 --tb=short
core-wheel:
name: kernel wheel smoke
runs-on: ubuntu-latest

View File

@ -83,7 +83,6 @@ jobs:
# The everos memory plugin ships as its own wheel from the same
# release; gh release create uploads everything under dist/.
uv build --wheel plugins-dist/everos-memory -o dist
uv build --wheel plugins-dist/everos-cloud-memory -o dist
# The product engines ship the same way. install.sh resolves them
# from the release assets by name, and the roster leaves
# Raven-Design and Raven-PPT disabled when they are not installed.

1
.gitignore vendored
View File

@ -133,7 +133,6 @@ demos/skill_retrieval/agent_memory/
# Playwright MCP session artifacts (console logs, page snapshots, screenshots)
.playwright-mcp/
.playwright-cli/
demos/oncall_heat2d/.raven-demo-home/
# Generated benchmark reports (written by the real_llm integration tests).

View File

@ -6,86 +6,6 @@ All notable changes to Raven are documented here.
### Added
- The Agent Hub has a **Machines** tab: the registered machines with the state
of each one's link and Raven node, a form that registers one (it reaches the
machine first, like `raven ops connection add`, and explains a refusal by
its kind), **Install node** / **Update node** run in the background with the
card reporting the end, and **Remove machine**. A preset's sheet picks where
it runs (*Runs on*) among the machines with this Raven's node, with the
working directory there. `raven ops connection remove <id>` is the command
behind the removal, and `install-node` now records the node it put on the
machine (`node_install` on the row), which is how the tab says a machine has
the node before any link is up. The form, and `raven ops connection add
--non-interactive --auth password --password-stdin`, register a machine by
password as well: the password (at least six characters, or the scrubber
would pass it as ordinary text) is kept on this computer for Raven's own
logins (`~/.raven/keys/<id>.password`, readable by the owner alone), handed
to ssh on every connection through its askpass hook, and never on a command
line, in a log or in an answer; such a machine gets no ssh alias and no jump
host, its password answers the registered account's own password prompt and
no other, Oncall campaigns run on it as Raven's own connections do and at
the registered address alone, and the mode is not offered on Windows. A failed
or cancelled registration preserves the password written by another pending
registration of the same machine, including when both passwords are identical.
New RPC group `machines.{list,add,install_node,doctor,remove}`.
- The Machines tab says what to do next. A card names the agent entries
connected on the machine (*No agent connected here yet* until one is; the
state line now reads *Link up, no agent running*), and a machine whose node
is up has **Connect an agent on this machine** in its sheet: pick the agent
and its working directory there, and **Connect** adds `<preset>@<machine id>`
with one proof prompt run on the machine. The list has every preset a node
can start, including one already connected on this computer. `subagents.add`
now refuses a preset the machine already has when no name is given, naming
the entry there, so the page and a chat cannot add the same agent on one
machine twice between them; a named add is still a second entry. A preset
that is not installed on this computer can be connected onto a machine from
its own sheet (*Runs on*); a row that already exists, switched off, connects
by its own button as before. While an add is still running on a machine, a
form opened again on that machine greys the preset rather than adding it
twice. The register form fills the private-key path with the key ssh would
try first (`id_rsa` before `id_ed25519`) instead of a placeholder. New read-only RPCs
`subagents.presets` and `machines.local_keys`; `machines.list` rows carry
`agents_here`.
- A machine's switched-off agent entries are shown, not counted nowhere. A
card that listed only connected entries read *No agent connected here yet*
beside a connect form that greyed the preset as *already connected on this
machine*, because the entry still holds the machine for the add. The card,
the sheet and the form now show such an entry marked *switched off* (the
card line reads *N on this machine*, not *connected here*); in the
form each such entry is a choice of its own, by name, with **Reconnect**,
which switches that entry back on (with the same proof prompt) instead of
adding a second one. `machines.list` rows carry `agents_off_here`; `subagents.presets`
lists `on_machines` (connected) apart from `off_on_machines` (switched off,
with the entry's name).
- The bug report review remembers your redaction decisions. Every keep or
replace answer is stored in `redaction_history.json` under the Raven home
(hashes and masked samples only), and the next `report-bug` or browser
*Report a bug* replays it: values you already decided are listed instead of
asked, and a run without a TTY no longer needs `--keep-findings` /
`--redact-findings` for them. `--review-all` asks again, `raven trajectory
redaction-history list|forget|clear` inspects and edits what is remembered,
and `RAVEN_BUGREPORT_REDACTION_HISTORY=off` turns it off.
- Bug Report Packages can be sent to a Bug Report Receiver. `raven trajectory
receiver --save-dir DIR` runs the receiver: it checks each package in a
stream without extracting it, stores the original bytes by UTC day next to
a receipt sidecar, and answers the same package with the same receipt. It
takes only uploads that answer its Upload Challenge -- a shallow gate that
keeps out HTTP clients that are not Raven, built on a constant published
with the source, not a credential -- and bounds abuse with per-address rate
limits, daily budgets, a free-disk reserve and timeouts. `report-bug` and
the browser's *Report a bug* upload the package as soon as it lands when
`RAVEN_BUGREPORT_URL` names a receiver, and `raven trajectory
upload-bug-report` sends a filed report again. Before a report starts,
`report-bug`, the browser and the WebUI's *Report a problem* ask the
receiver's `/v1/hello` and say so when it does not answer: an interactive
run asks whether to go on (the WebUI offers *Continue anyway*), and
`report-bug --yes` goes on and keeps the package if the upload fails. A
proxy in front of the receiver must forward all of `/v1/`.
- Memory runs on native Windows. EverOS 1.4.0 runs there without WSL, so
the memory plugin's pin moves to `everos[multimodal]==1.4.1` and the
platform gate that made memory unavailable on Windows is gone, together
@ -132,34 +52,8 @@ All notable changes to Raven are documented here.
style outright: it takes one when the request asks for dark, black, night or
a technology register.
- A DAG graph can decide where it goes next in one run. A node that declares
`routes` is a decision node: the verdict call then also picks, from the
node's answer and the conditions the graph's author wrote, the route it
selects -- for `select: many`, any number of routes, none included. A
downstream node carries `when`, a guard over `<node>.<route>` and
`<node>.done` atoms with `not`, `and`, `or` and parentheses, evaluated once
its dependencies settle. A node a branch left out ends `not_executed` with
its reason and is never dispatched; a node of the same graph that reads one
gets a fixed sentence in place of the missing output and a note naming the
inputs that may be missing, and a file reference to such a node's files,
however its path is spelled, is refused. A decision node whose route cannot be determined fails rather than
guessing. Playbooks carry the same three fields, and the TUI's DAG panel and
the web tasks list show what each node's branch did.
### Changed
- Memory runs on EverOS 1.4.2, which fixes what a memory server that stays up
for days ran into: a LanceDB index reader leaked file descriptors until
searches took seconds, an interactive search queued behind the cascade's
background embedding (vector search p50 46 s under three concurrent
writers, 0.60 s now), and a cascade pass sent one embedding request per
entry instead of one per file. The derived index also repairs itself on the
first start after the upgrade: EverOS re-reconciles every indexed markdown
file against the index once, re-embedding only the rows that are missing,
and a healthy index pays one read pass and no embedding. Markdown is the
source either way and was never affected. A server left running from the
older version is restarted, as it has been since the pin moved to 1.4.1.
- Research reports are written for a reader rather than for a grader. The
report opens with the answer as a blockquote, with no label or bold lead-in
before it, stated first and then why it
@ -208,10 +102,11 @@ All notable changes to Raven are documented here.
terminal shows as raw tags. The shape gate, the clarify exemption and
`scripts/research_report_audit.py` read the new layout, and the old
three-heading layout stays the class default (`finalShape.reportLayout`).
An install that has already run Raven-Research moves to the new layout at
its next launch, since the contract in its workspace
(`agent_memory/profile/agent.md`) is now regenerated on every launch (see
Fixed); the gate still accepts three-heading replies.
An install that has already run Raven-Research keeps the contract it seeded
into its workspace (`agent_memory/profile/agent.md`), because seeding is
once-only so that an operator's edits survive; it moves to the new layout
when that file is deleted, and until then the gate still accepts its
three-heading replies.
The identity no longer carries the measured-guidance block, whose short-run
and one-answer numbers came from a short-answer benchmark
(`measuredGuidance` off). The product label moves to
@ -261,17 +156,6 @@ All notable changes to Raven are documented here.
file name is unchanged so the new picture arrives without the page being
edited.
- Node judgement is always on. `subagentDag.verdictEnabled` no longer exists,
and a load-time migration removes it from the config file and says so once;
set again later, by an older build sharing the config, it is dropped on every
load. A config that turned judgement off now has every finished node judged:
one more model call per node, and a node judged not to have accomplished its
task can suspend as `exception` and report, as it does wherever judgement was
on. `raven playbook run` judges its nodes too, on the same `subagentDag`
settings; with nobody there to answer, a node judged not to have accomplished
its task fails on the judge's reason. A host with no model to judge with
refuses a graph that declares routes.
### Removed
- The built-in `deep_research` tool is gone, along with the stand-in that
@ -347,70 +231,6 @@ All notable changes to Raven are documented here.
### Fixed
- What an agent on a registered machine writes on stderr reaches Raven even
when no link held the agent at the time. The node kept those lines but, when
a link attached, replayed only the agent's output: a run picked up after a
restart was reported as `exited 3` without the reason after it, a CLI that
names its session only on stderr (hermes) could not be bound to it by the
pick-up, so its next turn opened a new session, and what was written while a
link was down was lost the same way. The node now numbers stderr lines as it
numbers output lines and replays the ones the link has not seen. An ACP
agent is one task across every prompt its process is sent, so its pick-up
asks the replay from the line its record kept as the prompt went out, not
from the agent's first line; a CLI pick-up, whose task is the command's
own, reads from the first line.
- The research, code, oncall and ppt agents follow an upgrade or a config
change into the prompt files they keep in their workspace (`soul.md`,
`agent.md`, `TOOLS.md`). Those files were written only when absent, so the
model kept reading the text of the first launch while the gates enforced
the current release: a research contract seeded before the reader layout
still asked for the three-heading report. They are now rewritten on every
launch. Your own lines go in the sibling `*.local.md` file
(`agent_memory/profile/agent.local.md`, for example) and are appended after
the product text; a `*.local.md` must be UTF-8, and one that is not stops
the launch with the file named. A file edited in place, or left by an older
release, is saved as `<name>.bak-<time>-<pid>` before it is replaced, never
readable by more accounts than the file was, and the launcher log names the
backup. The ppt engine, whose plugin can be granted a host's or another
product's home, replaces only a file it can show it wrote: in Raven-PPT's
own home a seat edited before this release stays until it is deleted.
- A file Raven saves by replacing it -- `config.json`, an agent's prompt
files, state files -- keeps its own access rights from the first byte of the
new text. On Windows the replacement took its folder's inherited ACL, so a
file kept private in a folder other accounts may read came back readable by
them; on POSIX the new text sat in a umask-default temp file until the
target's mode was copied over. On Windows a save refused by a read-only
target also left a read-only temp file that failed every later save, even
after the target was made writable again.
- A task on a registered machine ends the way it ended, whatever happened on
either side. A Raven node killed outright (`kill -9`) used to leave its
agents running with nobody reading them and the host reading a bare
`exit -1`; the next daemon now ends what was left, records why, and the host
hands that sentence on (on Linux the agent also goes with the daemon). A
failed remote run whose announce the draining scheduler refused used to
vanish; its record now stays, like a reply's, for the next start to report.
A cli run picked up after a restart now binds its instance to the session
id in its output, so the next turn resumes it; a stateless run binds
nothing, and a binding a dispatch made while the pick-up waited is kept,
for a minted id as for one read off the output, without the pick-up
waiting for that turn, and the reply picked up finishes that dispatch's
own record, not a newer turn's to the same instance. A cancel while the machine's
link is down no longer waits out the settle budget. An openai row's tunnel
gives a local port that was taken in between up for another instead of
sending the request to whoever took it. A run record that is not JSON, or not
UTF-8, is set aside once instead of being warned about at every start, and
never stops the other records from being read.
- A backslash typed into a bug report's description or steps (a literal
`\n` standing in for a line break, or a regular expression such as `\d+`)
no longer stops `raven trajectory report-bug` and the browser's
`Report a bug` with "absolute path leaked into the export". The export
gate now checks the metadata values rather than their JSON-escaped text;
a real absolute path is still refused.
- The research trail no longer says a cited link "appears nowhere in this
run" when a search returned it with a click-tracking parameter
(`srsltid`, `utm_*`, `gclid`, `fbclid`, `msclkid`) that the citation left

View File

@ -5,7 +5,7 @@
- [Raven Runtime](./CONTEXT.md) — the Python agent runtime: channels, spine, agent loop, engines, providers
- [TUI](./ui-tui/CONTEXT.md) — the terminal frontend (`ui-tui/`, React/Ink); talks to the Runtime only via the RPC protocol
- [Web UI](./ui-web/CONTEXT.md) — the served page (`ui-web/`, React); talks to the Runtime only via the RPC protocol
- [Agents over ACP](./agents/README.md) -- the agent-serving vocabulary: rendered config, state root, ACP home, tool-face pin, regenerated prompts; `agents/BUILDING.md` is the from-zero guide
- [Agents over ACP](./agents/README.md) -- the agent-serving vocabulary: rendered config, state root, ACP home, tool-face pin, seed-once; `agents/BUILDING.md` is the from-zero guide
## Relationships

View File

@ -277,14 +277,6 @@ A background agent task spawned by `SubagentManager`. Runs with its own tool set
re-enters the session as a `SUBAGENT`-origin `TurnRequest` via Spine submit. Bounded by
`max_concurrent` (default 8) and a per-session hourly rate limit, both shared with the
nodes of a DAG run — every sub-agent dispatch draws on the one allowance.
Content received from another agent keeps that agent's redaction policy: Raven does not
replace token-shaped text or values matching its own configured credentials in replies,
questions, permission requests, errors, transcripts, or run records. `Tool.agent_output`
marks tools that return agent content; the admitted tool spec and `ToolOutput` carry that
fact through `tool_call`, context assembly, live ACP updates and stored-session replay.
Untrusted-content fencing and output limits
still apply. The ACP journal protects Raven's outgoing credentials without rewriting
incoming frames or stderr.
_Avoid_: conflating with a Turn — a Subagent lives outside the main turn and re-enters via Spine.
**Sub-agent role** (`RAVEN_SUBAGENT` → `agent/subagent/role.py`):
@ -293,8 +285,7 @@ launches, beside the `RAVEN_HOME` it already sends, and a process that reads it
registers none of the tools that hand work to a further agent (`spawn`, `run_subagent_dag`,
the three graph controls) and builds no playbook funnel, so `load_playbook` and
`create_playbook` unregister themselves. The `## Delegation` block and the DAG orchestration
guide follow the tools out on their own, both being conditional on a live dispatch path; the
**Host role** section is withheld on the role itself as well as on the tools.
guide follow the tools out on their own, both being conditional on a live dispatch path.
`WITHHELD_FROM_SUBAGENT` is the specification; the gates enforce it by not building, and the
tests hold the two in agreement. A config `env` entry outranks the host's, which is how one
agent is handed back a full registry.
@ -325,17 +316,10 @@ filesystem, then `builtin` package seeds, then config. `builtin` rows are packag
(`agent/subagent/builtin_agents.py`): they exist whether or not config mentions them, and a
config row of the same name is a field-level override -- of every field but `enabled`,
which the merge discards, so a seed row cannot be taken off the roster at all. An unnamed
`spawn` and a DAG node with no `subagent` both dispatch to the generic seed,
`Raven-General` -- named apart from the host, so a prompt or an approval can no longer mistake
one for the other. A name a seed used to answer to resolves to it (`LEGACY_AGENT_ALIASES`;
`raven` and `Raven` -> `Raven-General`), so stored instance rows, instance logs, direct-chat
records and dag nodes written before a rename still find their agent -- exact match first,
and the roster never offers an alias back. Instance records, handle locks and live indexes
use the current name, including when a request carries an alias. Existing message state
and instance logs are read from the most recently written store across those names; a
chat directory without saved messages cannot hide one with resumable state. Equal
timestamps prefer the current name, then the most recent former name. No files are moved.
Read under the
`spawn` and a DAG node with no `subagent` both dispatch to the generic seed, `Raven`. A name
a seed used to answer to resolves to it (`LEGACY_AGENT_ALIASES`; `raven` -> `Raven`), so
stored instance rows, direct-chat records and dag nodes written before a rename still find
their agent -- exact match first, and the roster never offers an alias back. Read under the
older key `thirdParty` too; the write path emits `agents`.
_Avoid_: "third-party registry" — the table holds raven's own agents as well, which is the
point of it: `spawn` and a DAG node pick from one roster, so an agent reachable from one
@ -374,12 +358,8 @@ call can write is presentation or policy, and a row that is off is left to the s
Every kind but `builtin` is pinged, that one being this process, with no backend to
reach.
Not deletable through config — removing one means removing its folder, or setting
`"enabled": false` in its own `subagent.json`. Switched off it stays one: the row
`subagents.toggle` writes carries only the switch, so it is neither a definition nor a
config entry to delete. An edit stores the folder's entry with the change as an
override, a switched-off one staying off, and removing an override that is off leaves
the switch behind. On the RPC wire the row source is still spelled `vendored`;
renaming that is a schema change.
`"enabled": false` in its own `subagent.json`. On the RPC wire the row source is still
spelled `vendored`; renaming that is a schema change.
_Avoid_: "product" / "product agent" — the retired category word (the ruling keeps
*agent* for the thing, *harness* for the mechanism it rides, *subagent* for the
protocol seat); code-level `product_*` spellings stay as API surface, prose does not
@ -401,78 +381,8 @@ keeping the registry and handing it over: a launcher points the agent's
`RAVEN_CONNECTIONS` at the owner's store rather than copying rows into the
agent's own home, and a sub-agent inherits `RAVEN_HOME` so it resolves the
same file. Which machine a job lands on, and whether it can run at all, is
settled inside the agent that runs it, with one exception: an agent entry that
names a `machine`, of any kind. An `acp` or `cli` entry is started there by the
machine's **Raven node**, reached over the one ssh link the host keeps to the machine
(`raven/node/client.py`) -- a link that may go and come back while the agent runs on;
an `openai` entry's endpoint is reached from that machine through an ssh tunnel the
host opens for the turn and closes after it (`remote.tunnel`); a `builtin` entry cannot
name one -- Raven's own loop runs here -- and is loaded with a warning and runs here.
The row's key opens that link or tunnel and goes nowhere else, and the ssh line built
from the row stays in memory; the row's user, address and port open it too and also name
every path on the machine that a model, a reply, a record or an RPC result carries, written
the way scp writes one -- `user@host:/abs`, or `scp://user@host:port//abs` off port 22
(`remote.shown`, `raven/acp_client/remote.py`) -- and never by the machine's id.
Its dispatch reads the registry once (`remote.machine`), and the run fails before
anything starts when the id is not registered, is listed twice, cannot be used, or
is this computer; the `spawn` itself has already answered that it started. No other
dispatch reads the registry, so no graph and no spawn is ever refused over the state
of it. The entry names only the machine's id, and the entry's `env` reaches the
agent on the link, never on a command line. Such an entry is added the way any
preset is, with `machine` (and
`remote_cwd`, for an `acp` or `cli` one) on `subagents.add` — from a chat through
`raven_config`, which lists the usable registered machines, or from the Agent
Hub, whose preset sheet picks the machine (*Runs on*) among those with this
Raven's node — refused before anything is spent when
the id is not usable or the preset is a built-in agent, and proved by the same
readiness ping as a local add, run on that machine.
Registered-machine dispatch, file access and recovery are available without an
environment switch. An entry without `machine` still runs here. Registration,
SSH authentication, file permissions and concurrency limits govern remote work;
listing entries and boot capability backfills do not open machine connections.
The registry itself is kept from the Agent Hub's **Machines** tab as well -- the
hub's third module beside Agents and Channels (`state/hub.ts`), drawn by the agents
island on the page the two share
(`machines.*`, `raven/rpc/methods/machines.py`): list, register (the same probe
as the command; or, with `auth: password`, a password this computer keeps for the machine
under `~/.raven/keys/<id>.password`, the owner's alone, and hands to ssh on every connection
through OpenSSH's askpass hook -- in no row, log, command line or answer,
`connection_add.store_password`, `transport.ssh_env`; the row carries `auth: password` and no
key, gets no ssh alias, no jump host and no shared connection, and is refused on Windows,
whose OpenSSH cannot run Raven's POSIX askpass helper; a password under six characters is
refused, since the scrubber would pass it as ordinary text, one with a line break too, since
ssh would take only its first line, and the id rule is the one owner `connections.password_path`;
the askpass helper answers the registered account's own password prompt (`user@host`, named by
`transport.ASKPASS_FOR_ENV`) and no other, another account's, a second factor's and a one-time
password's included; Oncall's ssh and rsync log in to such a row the same way, at the registry's
address alone, `oncall_flow.transport.password_row`), install the node in the background, doctor,
and remove (`raven ops connection remove`, refused while a connected agent entry names the
machine; a password file kept under the id goes with the row whatever its login,
`connection_add.forget_password`, and a refused registration forgets only its own file write
while no row of the id is listed, `connection_add.forget_unowned_password`;
`connection_add.store_registration_password` atomically replaces the password file and records
its identity under the same file lock used by cleanup, so an overlapping registration's file
survives even while its probe is pending and its password is identical; a registration probe
uses its own temporary 0600 password file under `keys/` (included in held-secret scrubbing),
and `connection_add.write` publishes its password and row under the cleanup lock after
checking duplicates again, so either completion order keeps the successful login usable);
none of it hands the page an address, an account or a key path, and
`node_install` on a row is the node the last install or contact found there,
which is how a listing says a machine has this Raven's node without reaching it.
A row also names the connected agent entries that run on the machine (`agents_here`) and the
switched-off ones apart (`agents_off_here`: they still hold the machine for the add, so the card
says so and the connect form offers them back as *Reconnect*, the agents page's own switch on the
existing entry; both empty when the agents section, or the config file itself, cannot be read --
that is the agents page's to say),
and a machine whose node is up offers the next step from its sheet: connect an agent
on it, chosen from `subagents.presets` -- every preset a node can start, one already
connected on this computer included, since an entry is one preset on one machine --
under the add's default `<preset>@<machine id>`, through the same proved `subagents.add`,
which refuses a preset the machine already has under that default name (the refusal
names the entry there; a named add is a second entry on purpose), so the page and the
chat cannot make one agent on one machine twice between them. The
register form proposes the private keys this computer has (`machines.local_keys`,
`~/.ssh` identities in ssh's order) instead of a placeholder path.
settled inside the agent that runs it. Nothing on the dispatch path reads the
registry, so no graph and no spawn is ever refused over the state of it.
_Avoid_: "host" / "server" / "node" (too broad, no link to the
`ops connection` registry that supplies the rows); "GPU box" (only some are
GPU hosts, and the term covers any registered compute destination);
@ -480,96 +390,12 @@ GPU hosts, and the term covers any registered compute destination);
here the rows name compute destinations with that binding as an
implementation detail).
**Raven node** (`raven/node/`):
The Raven process on a registered **Machine** that owns the agents the host runs there:
a daemon (`python -I -m raven.node --serve --dir <node_dir>`) that the host's relay
starts over ssh when none is up (`--attach`: the relay bridges the ssh session to the
daemon's socket -- under `node_dir/run/`, or in a directory of the user's own under the temp
directory when that path is too long for a socket; either way the relay forwards only to a
socket of the user's -- and leaves with the ssh; the daemon leaves on its
own once idle). It does three things there and nothing else: answers file calls with
Raven's own file tools (`read_file`, `list_dir`, `find`, `grep`, `write_file`, `edit_file`)
fenced to the directories each call names, so a read of 50 lines of a large file moves
those 50 lines, and fetches one file whole (`fs/pull`); starts the `acp` and `cli` agents
whose entries name the machine, each under a task id of the host's, in its own process
group in the machine user's login environment, forwards what they write (an ACP agent's
frames, a CLI agent's output lines) on numbered channels of the connection that holds them
-- a CLI agent's prompt reaches its stdin the other way (`agent/stdin`), which also closes
it -- and keeps those lines and the agent's stderr, each line numbered, in the task's record
(`node_dir/tasks/<task>/`, owner-only like the host's journal), so a connection that goes
leaves the agent running and the next
one takes it over from the frame and the stderr line the host last read (`agent/attach`; a
cli pick-up, which read none of it, gets the stderr from its first line -- a session id or a
failure a CLI agent says only there is not lost with a link -- and an acp pick-up from the
line its run record kept as the prompt went out, so the earlier prompts' lines are not read
again); and answers probes of
the machine and of an agent's command. It holds no conversation, calls no model and opens
no network port. It runs exactly the host's code, checked by protocol and digest at every
connection (`raven/node/bundle.py`); `raven ops connection install-node` puts it on a
machine, under the row's `node_dir` (`~/.raven-node` when it names none), in a directory
named by the code's version and digest -- its install name, `bundle.install_name()`. The
host keeps at most one live link per machine and watches it with a heartbeat
(`raven/node/client.py`): a link silent for 15 s is lost, the agents on it wait, and the
link is tried again on a backoff for as long as any waits; a link that comes back attaches
each agent again by its task id. A turn running on a machine when this computer stops is
left with the daemon (`remote.leave_agents_running()`), remembered while in flight in
`<raven home>/machines/runs/` (`raven/acp_client/remote_runs.py`), and picked up by the
next start (`raven/agent/subagent/resume_remote.py`): attached from the frame its prompt
went out after, so the turn is read again whole (a cli entry's command from its first line,
its whole output being the reply), its reply read off the machine and announced into the
conversation that asked -- the task quoted as the model wrote it, the record removed only
once the announce was taken. A turn that returned here, or whose prompt went out and failed,
keeps its record the same way until the manager's announce of the reply or the failure was
taken (`remote_runs.forget_dispatch`), so a host that stops between the two reads the outcome
again; a record that is not JSON, or not UTF-8, is set aside once under a name that says so,
and never stops the other records from being read. A daemon killed
outright ends what it leaves behind at its next start (`Daemon.recover`; on Linux the agent
also goes with the daemon, `PR_SET_PDEATHSIG`) and says so on the task's exit (`reason`),
which the host hands on in place of a bare exit code. An MCP server the
host lends an agent there is carried on the same link: the agent runs the install's bridge
(`python -I -m raven.node --mcp`) as a stdio server, the daemon relays its frames as a stream
(`mcp/open`, `mcp/frame`, `mcp/close`; which task a bridge is, the daemon tells by the process
that connected, whose parent chain reaches the agent it started, so no task can claim another's),
and the host pumps them into the endpoint it opened on its own side (`raven/node/bridge.py`,
`NodePool.lend`). The host binds each dispatch's endpoints to the acquired agent's task
and checks that binding against the daemon-authenticated task before connecting, and again
after the connection opens. A bridge's dispatch/server names alone grant no access.
The server's definition and keys stay here. Host endpoints use Unix sockets where
available; otherwise they bind an ephemeral port on `127.0.0.1` and authenticate
with a random per-endpoint token before opening the upstream. Local ACP bridges
and the host's Raven node client use the same transport, including on Windows.
The loopback token stays on the host for a remote dispatch. Only
`--stdio` (tests, a fallback) ties the agents to the connection.
_Avoid_: "node" alone (a DAG node is a `run_subagent_dag` step, and the Machine
entry already rules the bare word out for a computer); "node id" for the install
name (a **Node id** is a delegated task's address); "agent" or "server" (it
answers only the Raven that reaches it, only over ssh).
**By address** (`remote.files_note`, `raven/ops/remote_path.py`):
How a file crosses machines: it does not. A file that comes with a task is named to the
agent on the **Machine** by its address on the computer that sent it, and the agent uses
it where the machine can read it (the same path on a disk both mount, a copy already
there) or says it could not be found and goes on; what a session makes stays on the
machine, named in the reply by address (the scp form), where the file tools read it by
that address and `deliver_files` fetches one file by it on request. Nothing is copied
ahead of a prompt, nothing is brought back unasked, and no two machines are ever told to
share a disk: whether they do shows in whether a path reads there.
_Avoid_: "transfer", "sync", "collect" (nothing moves on its own); "shared disk" as a
registry fact (it is not recorded: a path either reads on a machine or does not).
**Roster** (`format_agent_listing`):
The agent table rendered as the text that closes `spawn`'s tool description — `name [stateful,
local-files, live-progress] (description)`. Rendered once per tool array: the registry lists
`run_subagent_dag` and then `spawn` after every other tool (`ToolRegistry.list_last`), and the
graph tool points at the end of `spawn`'s description instead of repeating it -- it renders the
roster itself only when `spawn` is not on offer, and always lists a turn's worker labels, which
the roster does not carry. The model's only
The agent table rendered as the text spliced into `spawn`'s and `run_subagent_dag`'s tool
descriptions — `name [stateful, local-files, live-progress] (description)`. The model's only
account of which agents exist, so an agent absent from it cannot be chosen; the `enum` on
the `subagent` parameter constrains the same set. All three capabilities render positive *or*
negative, because "no tag" and "the roster does not say" are indistinguishable otherwise. A
row of any kind that names a **Machine** renders a fourth tag after them, `on machine <id>`:
the one conditional tag, since a local row has nothing to say in that position, and the id
only, never the address.
negative, because "no tag" and "the roster does not say" are indistinguishable otherwise.
Also spliced into the skill gate's prompt under push discovery, where it is the account of
what can be delegated and so decides which candidate skills are dropped as already covered;
that copy omits the generic `builtin` row, which claims no capability bias and would read as
@ -614,7 +440,7 @@ in for it: from the folder's manifest for a vendored agent, from the package see
built-in override, so a config written before the field existed still gets one. `""` is the
user declaring the agent owns nothing and is never refilled.
Two things never carry ownership. The generic row (`Raven-General`) claims none whatever a config
Two things never carry ownership. The generic row (`raven`) claims none whatever a config
says, because it carries no capability bias and a line about it would prohibit the agent
reading it from doing its own work. And the section is withheld entirely on a turn holding
no dispatch tool — `spawn` and `run_subagent_dag` can both be withheld by
@ -623,23 +449,6 @@ leaves a request with no compliant action at all. Only the paths the turn does h
_Avoid_: putting it in `description` — that copy is spliced into the tool descriptions, where
the model reads it only once it is already choosing an agent.
**Host role** (`## Your role`, `_host_role` in `context_engine/segments/render.py`):
What the host is for, rendered at the top of its identity: the user's agent manager. It sorts
a request into tasks and dispatches each, keeps every task until the user accepts its result,
sends each later message about a task's work -- a question included -- to that task's
instance, and gathers the reports into one answer. Producing anything goes to the agent whose
ownership or description fits it, to `Raven-General` only when none does; the host answers
itself only what needs no tools and belongs to no task. On a turn that dispatches through a
**Worker Table** the same rule names the table's workers instead: the worker whose brief
covers the work, by its label. Work no worker covers is put to the user -- a worker added for
it, or another Harness -- rather than done by the host or sent to an agent outside the enum,
which offers labels alone. A table a call binds mid-turn (`load_playbook`) arrives after the
identity was assembled, so that call's result carries the same rule, after its untrusted
fence. Rendered only in a process that is
not a **Sub-agent role** and on a turn holding a dispatch path -- elsewhere the identity
stays "a helpful AI assistant", byte for byte. **Ownership** names each agent's territory;
this says what the host itself does and does not do.
**Subagent working directory** (`workspace=` on every backend's `run`):
Where a sub-agent's commands and file tools act: the *session's* working directory, the same
one the dispatching turn's own tools get. Every dispatch supplies it — `spawn` captures
@ -647,14 +456,7 @@ one the dispatching turn's own tools get. Every dispatch supplies it — `spawn`
read), a DAG node takes the same, and a Direct Chat resolves `session_workdir` because its
branch returns before `workdir.bind` wraps the turn body. Distinct from **Agent home**
(`SubagentManager.workspace`, `~/.raven/workspace`), which holds raven's memory and skills
and is only the fallback for a dispatch that supplied nothing. An `acp` or `cli` entry that
names a **Machine** is the exception: its session works on that machine, in
`<remoteCwd>/<instance or task id>` (`remoteCwd` defaults to `~/raven-work`), made and
resolved there by the machine's **Raven node** for each dispatch before the session
opens (`session/dir`); this computer's working directory never reaches the machine.
The files that come with the turn are named to the agent by address (`remote.files_note`);
nothing is copied to the machine, and nothing comes back unasked: what the session made
stays there, named in the reply by address.
and is only the fallback for a dispatch that supplied nothing.
_Avoid_: treating the fallback as the default — a sub-agent working in Agent home inspects
raven's own memory instead of the user's checkout, and says nothing about having done so.
@ -880,8 +682,6 @@ ran (a queued turn drained by a stop, an inject merged into a turn that did not
A `TurnFailed` is `reported` when the runner worded `error` itself (an `AnswerlessTurnError`)
rather than it being whatever a crash carried — in-process only, so a consumer deciding what to
show a stranger can quote a report and refuse to quote a crash.
A `TurnFailed` may also carry `full_detail`, the failure's long account, which the runner builds and
the lane copies off the exception (see **AnswerlessTurnError**).
Per-conversation **Lanes** are the unit of both ordering and cancellation. Deliberately
not a broadcast bus.
_Avoid_: "the bus" — there is no Bus; "queue" for Lane — Lane is a serial+cancel domain.
@ -915,13 +715,6 @@ it), and the `turn_ended` marker that says so is filed before the failure leaves
is worded twice, for its two readers: `turn_ended.reason` keeps the provider's account for whoever is
diagnosing the failure, while the entry text the model reads back names the failure's category and
endpoint only — a vendor body is not history the model should spend context on or try to answer.
Beside that bounded report a failed turn may carry `full_detail`, the same account at length --
credentials scrubbed, capped at the call record's body ceiling. The runner builds it
(`agent/loop/failure_text.py`), since the kernel imports nothing to scrub with, and sets it on the
exception it lets out; the lane copies it onto `TurnFailed.full_detail`, and it is filed on the
marker as `turn_ended.full_detail`, only when the bounded text left something out.
Both use the base exception's instance storage so a foreign property cannot substitute a value
or disrupt failure reporting. The turn path and runner reuse the same scrubbed account.
_Avoid_: conflating AnswerlessTurnError with `TurnFailed`, the lifecycle event the Spine worker
emits for any exception a runner lets out, this one included.
@ -1332,45 +1125,15 @@ and injects into the main agent's system prompt so evicted facts stay present.
**EverOS** (`plugins-dist/everos-memory/raven_everos/`):
Raven's default memory-backend plugin (`everos-memory`; ships enabled, works out of
the box). Its own distribution rather than part of the raven wheel, found through the
`raven.plugins` entry-point group. (`plugins-dist/ppt-engine/`,
`plugins-dist/design-engine/` and `plugins-dist/everos-cloud-memory/` ship the same way --
the group's other distributed members: a deck-building toolchain, a visual-design
engine, and the hosted memory backend below.) Provides dual-track semantic recall — the user track (episodes/profiles,
`raven.plugins` entry-point group. (`plugins-dist/ppt-engine/` and
`plugins-dist/design-engine/` ship the same way -- the group's other two
distributed members, contributing a deck-building toolchain and a visual-design
engine rather than memory.) Provides dual-track semantic recall — the user track (episodes/profiles,
injected into the `# Memory` segment) and the agent track (skills/cases, one of
SkillForge's three sources at RRF weight 0.9). The name refers to the external package
[EverMind-AI/EverOS](https://github.com/EverMind-AI/EverOS); the in-tree code is only an
adapter. The same plugin also contributes the `understand_media` multimodal-parsing tool.
**EverOS Cloud** (`plugins-dist/everos-cloud-memory/raven_everos_cloud/`):
The hosted EverOS at `https://api.evermind.ai`, reached with a Bearer key from
`https://everos.evermind.ai`, and the second memory-backend plugin (distribution
`everos-cloud-memory`, backend name `everos-cloud`). Speaks the same
`/api/v2/memory/{add,flush,get,search}` as the local server; the plugin depends on
`raven` and `httpx` only and never imports the `everos` package. Flushes only on an
**explicit end** and at `stop()`; every add is `mode: "agent"`.
**cloud slice**:
`plugins.config["everos-cloud-memory"]`: `api_key` and an optional `base_url`. Holds no
identity -- the **owner id** is the host's.
**owner id**:
`memory.userId` / `memory.agentId` from the host's `memory` block, handed to every
backend through `ServiceLocator`. On the wire it is the `user_id` or `agent_id` of a
search and the `sender_id` of a stored user message. The same two values on two
machines sharing one cloud key name one memory.
_Avoid_: owner identity (the older wording in `raven/contracts/plugin_surface.py`).
**memory backend chooser** (`cli/onboard_commands.py:_choose_memory_backend`):
The `raven onboard` question asked only when more than one memory plugin is
installed: which backend's screen to run. Off writes `memory.backend = null`; a
dismissed question exits the wizard and writes nothing.
**explicit end**:
A `store` call whose caller says the conversation is over: `metadata["flush"]` (the
sub-agent **Memory record** handoff; a convention of the `MemoryBackend` contract) or
`metadata["is_final"]` (the importer's last batch). The only two store-time reasons the
cloud backend calls `/flush`.
**EverOS role**:
One of the four models EverOS talks to: `llm` (reads each conversation and extracts
what matters), `embedding` (what recall matches meaning with), `rerank` (sharpens
@ -1726,8 +1489,7 @@ pass-through. Failures name the owner and the key at the door, not deep inside a
**Config-with-cargo** (`channels/contract.py:ChannelSpec.config_schema`, `raven-plugin.toml [plugin.config_schema]`):
A cargo declares the config keys only it consumes -- types, defaults, secrecy,
requiredness, choices, nested `fields`, and `settable = true` on the few fields
the settings page may write over RPC (a key, never an endpoint) -- next to the code that consumes them. The
requiredness, choices, nested `fields` -- next to the code that consumes them. The
declaration is the only truth: the door
dispenses from it, the writer (`config/update_channels.py`) validates through the same
door, and the declaration guard (`tests/test_channels_config_declaration.py`) pins the
@ -1775,8 +1537,7 @@ The module is the roster -- every key this lane serves has a named reader there
spellings), and machinery on this lane asks the reader, never the file by key: `disabled_tool_names`,
`disabled_playbook_names`, `exec_extra_deny_patterns`, `web_search_key`,
`media_tool_config`, `mcp_server_configs` (feeding the turn-boundary reconcile),
`routing_profile`, `default_model`, `cron_default_timezone` (captured by each new
cron-expression job, local time when unset; existing jobs retain their stored zone). The boundary is the module docstring's rule: anything
`routing_profile`, `default_model`. The boundary is the module docstring's rule: anything
whose change implies WORK rather than a different answer (constructing a provider,
an MCP handshake, moving a workspace) keeps its apply path -- a door, the pool's
fingerprint cache, or the generation swap. Timing is asymmetric by design: a revocation
@ -1892,9 +1653,9 @@ turns through its schedulers and sentinel but is an engine the loop and the asse
consume, not a transport), and `core` (the L2 assembly root). `templates` is packaged data
and takes no seat. Surfaces: `cli`, `rpc`, `acp` (an entrance: Raven serving as an
agent for another host) and `a2a` (the same entrance for a peer agent, over
Agent2Agent rather than ACP). `browser`, `importer` and `node` (the **Raven node**)
are seated inner (feature libraries consumed by surfaces, importing none themselves --
the edge is watched by the contract now, not by a ruling note). `evolver` is not a seat at all: it left the
Agent2Agent rather than ACP). `browser` and `importer` are seated inner (feature
libraries consumed by surfaces, importing none themselves -- the edge is watched
by the contract now, not by a ruling note). `evolver` is not a seat at all: it left the
package for the repo-level `evolver/` tool (outside the wheel) that drives raven as a library,
and a fifth import-linter contract keeps the runtime from importing it back. `agents/` is the
same kind of non-seat: repo-level agent definitions (the A/B pilots whose A side is the
@ -2192,25 +1953,6 @@ attribute, which read paths keep resolving; new spans never carry it
(`attempt.id` is a reserved attribute key stripped by `raven/tracing/spans.py`).
_Avoid_: "run id" / "task id" — neither is bound to span records.
**Main-line Turn** (`raven/trajectory/selection.py`):
A `session.turn` root recorded under a session's key that no other trace dispatched
(it carries no `trace.dispatched_in_trace_id`). It is the unit the web page's
export and bug report select by; selecting one brings along every trace it
dispatched -- sub-agents, their own sub-agents, follow-up turns reporting back --
resolved through those links. A main-line turn counts as in progress only when it
is the session's latest, its record is still only a checkpoint, and the session is
answering right now; a checkpoint left behind by a process that died is selectable.
_Avoid_: selecting a dispatched trace as a turn of its own.
**Turn Trace Mark** (`raven/agent/loop/turn_path.py`):
The `trace_id` stored on a turn's opening user message while tracing is on, naming
the trace of that turn's `session.turn` span. Cutting a session record down to
selected turns uses it to find each turn's messages; messages written before the
mark existed are matched by the turn's input text inside the turn's time window,
only where the record's order leaves one possible turn, and a turn that cannot be
matched with certainty keeps its trajectory only. The mark never reaches
a model request (history is read through field whitelists).
**Attempt Definition** (`raven/trajectory/store.py`):
The mutable sidecar record in `attempts.json` (trace state dir) mapping a minted
`att-*` id to its member trace ids plus the historical ids it absorbed (`aliases`),
@ -2249,39 +1991,6 @@ manifest's `missing_messages`. Bundling declares the trajectory corpus, so the i
auto-pinned.
_Avoid_: "archive" — that names the tracing store's rotated-log directory.
**Trajectory Export** (`raven/trajectory/export.py`):
The `tar.gz` the web page's "Export" downloads for chosen Main-line Turns of one
session: `<export-id>/export.json` (`schema: "raven_trajectory_export"` plus a
`format_version`, the selected turns and dispatched traces, counts, and what is
missing) + `spans.jsonl` + the session record cut to those turns + `artifacts/` at
their store-relative paths + the Message Blobs their v2 shells reference. It is the
input contract `web-traj-import` reads, so its layout and manifest change only with
the version. Unlike a Trajectory Bundle it is selected by turn rather than by
Attempt, keeps v2 shells as shells, carries only the selected turns' messages and
pins nothing; unlike a Bug Report Package its content is neither redacted nor
trimmed, and it travels only from the local gateway to the browser, fetched by a
one-hour token (`raven/trajectory/export_jobs.py`).
_Avoid_: calling it a bundle or a report.
**Imported Conversation** (`raven/trajectory/imported.py`, `raven/trajectory/imported_package.py`):
A Trajectory Export, Bug Report Package or Trajectory Report read back in and kept
as a read-only conversation, addressed as `imported:<id>` (32 lowercase hex). Each
lives in its own `<raven home>/imports/<id>/`: `meta.json` (`schema:
"raven_imported_conversation"`, the kind, the source file name and sha256, the
title, where it came from), `package/` (the package as unpacked, a report's inner
bundle expanded in place), `state/` (a trace store the trajectory index and detail
layer read unchanged: the span log copied, every artifact pointer rewritten
relative to `state/` or set to null when the package does not carry the file, and a
bundle's v1 model inputs split back into v2 shells so a long conversation reads
whole) and `session.jsonl` when the package carried a session record. Every layer
of the archive is walked once under one shared byte and member budget
(`package_check.walk_archive`); an import is built in `imports/.staging/` and
renamed into place whole. It never enters the SessionManager or
`<workspace>/sessions/`, so no session picker, sweep or delivery target can see it.
_Avoid_: "import" alone — that is the cold-start import of another tool's memory
(`raven/importer/`, `import.*`); "archive" — session archiving and the tracing
store's rotated logs.
**Message Blob** (`raven/tracing/artifact_v2.py`):
One model-input message stored once, at
`<state_dir>/logs/audit-artifacts/_messages/<sha1[:2]>/<sha1>.json`, addressed by the
@ -2340,10 +2049,7 @@ path-sanitized problem metadata, merged redaction summary with
`risk_accepted`, environment, content manifest) plus an embedded Trajectory
Report. Its entire content is frozen under the report's `snapshot/export/`
before the user confirms, so a packaging retry reuses the approved bytes and
never re-collects. A report the web page files for chosen turns carries a
synthetic attempt, `sel-<12 hex>` of the selected trace ids, whose
`member_traces` are those turns and every trace they dispatched; the receiver
reads it like any other.
never re-collects.
_Avoid_: confusing it with the Trajectory Report it embeds — the Package wraps
one and adds the problem metadata envelope.
@ -2367,92 +2073,6 @@ acknowledged. `apply_review_decisions` guarantees the array matches the
delivered bytes: replaced values are verified gone in every spelling variant
and kept values verified untouched before the export freezes.
**Redaction History** (`raven/trajectory/redaction_history.py`):
The machine-local record of the user's Review Item decisions (`kept` or
`redacted`), kept in `<raven home>/redaction_history.json` (mode 0600) and
keyed by the sha256 of the token value: only the hash and a masked sample are
stored, never the plaintext. `resolve` decides a suspected item -- or a whole
linked group -- from it only when every member has a recorded, agreeing
decision; confirmed-sensitive items are never decided from history. Each human
decision gets a fresh revision, and a replay is counted only against the
revision it read, so a stale replay never overrides a newer human answer or
revives a forgotten record. An unreadable file reads as empty and is backed
up, never overwritten in place, before the next save. The bug report review
(`report-bug` and the browser's "Report a bug") replays it before asking and
records the human decisions once the decision set is valid; decisions made by
the blanket `--keep-findings` / `--redact-findings` flags are neither replayed
over nor recorded, `--review-all` asks again, and
`RAVEN_BUGREPORT_REDACTION_HISTORY=off` disables it. The web page's bug report
records every value it showed with the final decision, source `web` -- the
default "keep" and the bulk buttons included -- because the page puts each
value in front of the reader; that differs from the CLI's blanket flags on
purpose.
_Avoid_: "memory" (the agent memory engine), "cache" (it is an authoritative
record, never evicted automatically).
**Report Session** (`raven/trajectory/report_session.py`):
One web bug report in progress, held in the gateway's memory between the page's
requests: the preparation, the Review Items with their plain values, what the
Redaction History decided, and the phase (`collecting`, `deciding`, `finishing`,
`ready`, `uploading`, `uploaded`, `upload_failed`, `failed`, `cancelled`). It lives
from `bugreport.start` until the report fails, is uploaded, is cancelled, sits
idle for thirty minutes, or the gateway stops. At most two are held at once, each
until its worker thread has cleaned up and exited; a failed or uploaded one then
drops its plain values and leaves only its last status, readable for ten minutes.
The worker checks for a cancel after every step and starts nothing further, so a
report cancelled while it was packaging is never sent. Cancelling or failing
before the report landed removes its staging, after it landed the Bug Report
Record stays for `raven trajectory upload-bug-report`. While it waits on the
decisions, its status carries each remaining value in full beside its masked
sample, since the value is what the reader decides on (a private key, replaced
whatever the reader says, is carried only as its replacement); the contexts a
decision needs come one item at a time. No other phase carries a value.
_Avoid_: calling it the record -- the Bug Report Record is the file that lands on
disk.
**Bug Report Receiver** (`raven/trajectory/receiver.py`):
The standalone HTTP service that takes Bug Report Packages in: it validates each
upload with `package_check.inspect_package` (streaming, never extracting), lands
the original bytes under `<save_dir>/<UTC date>/<report-id>.tar.gz` beside an
Upload Receipt sidecar, and answers idempotently by report id — the same bytes
again return the stored receipt, different bytes are refused. It takes only
uploads that answer its Upload Challenge, a shallow gate against HTTP clients
that are not Raven that identifies nobody; it serves no listing or download,
and who can reach it is still the network's job. `GET /v1/hello` names the
service and its protocol so a client can check, before a report starts, that
its URL leads to a receiver. The sidecar is written before the package is
moved into place, so a package in a date directory is always a committed one.
_Avoid_: "upload server" or "uploader backend" — it is not an `Uploader`
implementation for Trajectory Reports; it is the far end a Bug Report Package
is sent to.
**Upload Receipt** (`raven/trajectory/receiver.py`):
The Receiver's confirmation that one Bug Report Package was received:
`receipt_id`, `report_id`, `sha256`, `size_bytes`, `received_at`, plus
`duplicate` in the HTTP response. The server keeps it — with the remote address
and a triage digest of `bugreport.json` — as the `<report-id>.json` sidecar
next to the package, and the client records `receipt_id` in
`record.json.upload.receipt`. A sidecar that is missing or fails its contract
is rebuilt from the package: the package is the source of truth, the receipt
is derived from it.
_Avoid_: "receipt" for the sidecar file — the sidecar carries the receipt plus
server-side context; the receipt is what the client gets back.
**Upload Challenge** (`raven/trajectory/receiver_auth.py`):
The string a Bug Report Receiver hands out on `POST /v1/challenge` before an
upload, together with the client's answer to it. The receiver seals each
challenge with a key held only in its process memory, so it stores none and a
restart retires them all; a challenge carries the second it was issued, lives
`challenge_ttl` seconds (300 by default) and is not consumed. The client
answers with an HMAC, under a constant built into Raven, of the challenge with
the package's report id, sha256 and size, and sends both back as
`X-Raven-Challenge` / `X-Raven-Response`; the receiver checks them from the
headers alone and refuses with 401 before reading the body. The constant is
published with the source: the gate keeps out clients that do not know the
exchange, not anyone who has read the code.
_Avoid_: "token", "credential" or "authentication" — it identifies nobody and
nothing about it needs to be kept secret.
**Trajectory Replay** (`raven/trajectory/replay.py`):
Mock re-run of the harness against a Trajectory Bundle (`raven trajectory replay`):
recorded model replies (`llm.output`) and tool results (`tool.output`) are fed back
@ -2705,8 +2325,7 @@ below does, does not need wrapping: the path is raven-minted, only the file's co
A DAG node is told where its upstream records are: every node whose sub-agent can open
local paths gets an `## Upstream memory records` block appended to its rendered prompt,
listing each transitive upstream's node id and the absolute path of its record. Paths only --
nothing injects a record's text. A node that was not executed gets no line: it never ran, so
it has no record to point at. Suppressed entirely for a sub-agent the roster tags
nothing injects a record's text. Suppressed entirely for a sub-agent the roster tags
[no-local-files], gated the same as a `_path` placeholder (Prompt template, below). The
listed files usually do not exist yet when the node starts, because the record is written by a
fire-and-forget poller after the upstream finished while the runner starts the next wave
@ -2723,9 +2342,9 @@ same two ways, and `ref:<path>` / `ref_path:<path>` do it for an arbitrary file
form always injects content, the `_path` form always injects a location. `output` and
`output_path` name a node by the id it ran under, and both surfaces resolve them against the
same flat node root, so a spawn may name a graph's node and a graph may name a spawn's. The
id must already be readable: a node that failed, was skipped, was cancelled, was not
executed or is still running is refused with which of those it was, rather than handed the
leftover file a bare path would resolve to. A `{{ ... }}` body
id must already be readable: a node that failed, was skipped, was cancelled or is still
running is refused with which of those it was, rather than handed the leftover file a bare
path would resolve to. A `{{ ... }}` body
matching none of the six is not a mistyped placeholder -- it is ordinary text, carried
through untouched, so template syntax from another system (Jinja, Vue, Handlebars) can sit
in a prompt with no escape form needed. A body that does match a shape still fails
@ -2770,10 +2389,7 @@ node-shaped `inputs.<k>` entry, both `run_subagent_dag` only -- is wrapped with
a run fetched or a checkout brought in, and a node's output is sub-agent-authored by
construction. A literal `inputs.<k>` string is not fenced, because the author typed it into
the call, and neither is any `_path` form or the `## Upstream memory records` block -- those
carry a raven-minted path rather than content. Neither is the sentence that stands in for a
node that was not executed: that is the runner's own words, so it is written unfenced too,
and an upstream that writes the same sentence into its own output has it land inside a
nonce-tagged fence, where it reads as data.
carry a raven-minted path rather than content.
This rule replaces one that keyed on location: a read whose resolved path landed under
Subagent history was fenced, and every other read was not. That left the contents of a file
in the working directory reaching a prompt bare, which is the wrong way round -- a checkout
@ -2839,11 +2455,7 @@ unpinned `npx -y` would silently change which shim build a user runs. The **agen
never fetched; its preset names the bare executable (`opencode acp`, `hermes acp`), so the
build that answers is the one the user installed, at the version they chose, holding the login
they already granted. `SHIM_LAUNCHED_PRESETS` declares that split per preset and a test holds
every acp command to it. A **bundled shim** (`BUNDLED_SHIM_PRESETS`) is one Raven ships rather
than fetches: `raven.acp.mirasim` serves an agent Mirasim runs, as one more client of the
Mirasim host running on the machine (its WebSocket protocol), launched on Raven's own
interpreter (`{PYTHON}`, expanded when the preset is read), so there is no pin; the executable
its probe asks after is `mirasim` (`SHIM_REQUIRED_EXECUTABLES`).
every acp command to it.
_Avoid_: inferring it from the command shape. An agent whose own CLI happens to ship on npm
(`opencode-ai`) is not a shim, and fetching it would run a second copy beside the user's
install and report the agent as present on a machine that does not have it - `_probe_acp`
@ -3012,52 +2624,6 @@ and every tool result.
_Avoid_: calling it a transcript - a reader drawing a delegated run wants the Instance Log
or `transcript.jsonl`, not this.
**Leftover agent** (`raven/acp_client/leftovers.py`):
An ACP agent process group whose launching host is no longer running. An ACP agent runs in a
session of its own, so it gets none of the signals sent to its host's process group or
terminal, and while the host lives only `AcpClient.close` ends it; a host that dies before its
teardown can leave its agents' groups running with nobody on the other end of their pipes. On
Linux and macOS the agent starts through an exec wrapper (`_WRAPPERS`) that ties it to its host.
On Linux it arms `PR_SET_PDEATHSIG`, so where the signal is armed and survives the exec (a
set-id or file-capability binary clears it) its direct process ends when the thread that
launched it does, which for an agent launched from the host's event loop is when the host dies.
On macOS, which has no such signal, it leaves a watcher in the agent's group, adopted by
launchd and holding none of the agent's descriptors, that waits on the host process's exit with
kqueue and then ends the whole group - while the agent leads that group, as every launch has it
do. Every Linux and macOS host records the ACP agent groups it
launched in a file of its own under `acp-launches/` in the config file's directory
(`<raven home>` unless `--config` moves it), and the first launch in any process ends the
groups recorded by hosts that have since died, in the same boot and PID namespace, and only
where a surviving member still carries the dead host's mark and, while the leader still runs,
its start time matches the record - the group number alone can have been handed out again. Not
covered by the Linux and macOS sweep: other platforms, a group whose record was never written
(its host died first, the
write failed, or its leader had already exited when the record was taken), and agents started
by a Raven older than the records.
On Windows, each locally launched ACP connection owns an unnamed, non-inheritable Job Object with
`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. A launcher waits for one byte on stdin before starting
the agent; the host sends it only after assigning the launcher to the job. Host death before
assignment closes stdin, so no agent starts. After assignment, host death or closing the
connection closes the job's only handle, ending its processes and descendants even if the
original launcher has already exited.
_Avoid_: "orphaned" - in POSIX terms every agent group is an orphaned process group from the
moment it starts, since its session does not hold the host; and the DAG vocabulary rules the
word out for a released run.
**Launch mark** (`raven/acp_client/leftovers.py`):
`RAVEN_ACP_HOST` in a launched agent's environment, naming the host that launched it as
`<host pid>-<host start time>` (clock ticks since boot on Linux, microseconds since the epoch on
macOS), the stem of that host's launch record. Every process the
agent starts inherits it unless it is started with a fresh environment, so after the host dies
a sweep can tell a group made of that host's agents and what they started from an unrelated
group that happens to hold the same number. A process whose environment this user cannot read
(on macOS that includes every platform binary, such as `/bin/sh`) counts as carrying none (any other read error keeps the record for a later sweep), and a group
none of whose surviving processes carries the mark is left running - which is what remains
when the agent exits after starting its children without it.
_Avoid_: a security token - it is an identifier, not a secret; its parts are world-readable in
`/proc/<pid>/stat` and, on macOS, through `sysctl`.
**Instance Log** (`raven/agent/subagent/instance_log.py`):
One sub-agent instance's own conversation, for the whole conversation that owns it, at
`<session_dir>/subagents/instances/<agent>/<handle>.jsonl`. A call record answers "what was
@ -3328,9 +2894,9 @@ refused, so an id names one task and one output. Compared case-folded, because a
artifacts are files named after it and `Plan` and `plan` are one file on macOS and Windows.
An id is claimed at dispatch and kept whatever the outcome, but referencing it needs both a
`completed` status and an output file actually written — a task can finish having written
nothing, which the status alone does not say. A failed, skipped, cancelled, not-executed or
still-running one — or, as a replan validating its replacement sees it, one still pending
or awaiting a decision — keeps its id and is refused with which of those it is. A run stopped
nothing, which the status alone does not say. A failed, skipped, cancelled or still-running
one — or, as a replan validating its replacement sees it, one still pending or awaiting a
decision — keeps its id and is refused with which of those it is. A run stopped
by `/stop` or a shutdown records its still-running nodes as `cancelled` and its pending
ones as `skipped` on the way out, so "still-running" means what it says rather than
outliving the run that claimed it. Distinct from an
@ -3363,71 +2929,6 @@ _Avoid_: it is not a synonym for a Python exception. A raised exception is only
of the two routes into this status, and `status[node.id] = "exception"` sits next to
`except Exception as exc` in `_run_node` for that reason.
**Decision node** (`routes` on `DagNodeSpec`, `raven/agent/subagent/dag_graph.py`):
A node that decides where the graph goes next. `routes` maps a route name to the condition,
in the graph author's own words, under which the node's answer selects it; the conditions
are shown to the judge and never to the node.
Nothing the node writes selects a route: the same constrained verdict call that judges it
also picks the route, as a tool argument, and a selection is valid only if the judge reports
one of the declared names, so a node that writes "route: bug" into its own answer has said
nothing about the branch. `select` says how many an answer may take: `"one"` — exactly one,
and what unset means once `routes` is set — or `"many"`, any number including none. A node
may be a decision and guarded at once, which is a nested branch. Its selection is recorded
per run (`selected_routes`, plus the judge's `route_evidence`) and read by clients beside
the status. Where an ordinary node's judge failure or timeout reads as accomplished, a
decision node whose route cannot be established fails ("The route could not be determined:
..."), its output withdrawn and its dependents skipped, with no fallback route and no
adjudication. For the same reason a graph declaring routes is refused on a host with no
provider to judge with.
**Route (DAG branch)** (a key of `routes`; `raven/agent/subagent/dag_graph.py`):
One branch a decision node chooses between, named by the graph's author. A guard names it
exactly as declared; the judge's report is matched to the declared names without regard to
case and recorded under the declared spelling, which is why two names of one node may not
differ only in case. The charset is the node id's, `^[A-Za-z0-9_-]+$`, since a route name is
written into a guard beside a node id; `done` is reserved in any letter case because an atom
ending in it means something else entirely; a condition cannot be blank; and the count is
checked — at least two routes for `select: "one"`, at least one for `"many"`.
_Avoid_: the routing-table rows of a **Routing entry** (`routes` on an agent table row,
which pick the backend a task runs on), and the runner's unrelated `_route_available`
(`raven/agent/subagent/dag_runner.py`), which asks whether the main agent has any way to
call `resolve_dag_node` — neither is a branch of a graph.
**Guard** (`when` on `DagNodeSpec`; `raven/agent/subagent/dag_guard.py`):
The condition under which a node runs, as a three-valued expression over atoms
`<node>.<route>` and `<node>.done`, combined with `not`, `and`, `or` and parentheses
(`not` binds tightest, then `and`, then `or`; the keywords are lowercase). Parsed and
evaluated by a hand-written parser, never `eval`. An atom may name only a decision node of
this graph that is in the node's `depends_on`, and only a route that node declares or
`done`; every decision node of the graph in `depends_on` must appear in the guard, since a
node cannot depend on a decision and stay silent about it. Two guards that can never hold
are refused at submission: two un-negated routes of one `select: "one"` node in one `and`
chain, and `not <node>.done`. These checks preserve surrounding negation and disjunction:
an impossible arm does not reject an `or` whose other arm can hold. The runner reads a guard
once every dependency has settled,
and a dependency that failed or was skipped skips the node first, whatever the guard says.
Unknown is a value and not false: a route of a decision node that was never executed is
unknown, so `not` over it does not hold. A blank or unset `when` is no guard.
_Avoid_: the agent loop's guards (`NoProgressGuard`, the failure streak), which stop a call
that keeps repeating; a Guard is a DAG node's run condition, read against what the decision
nodes chose.
**Not executed** (`not_executed`, `raven/agent/subagent/dag_runner.py`):
A terminal node status for a node a branch left out: it was never dispatched, never took a
concurrency slot, and wrote no output — no prompt file, no output file, no memory record.
Distinct from `skipped`, which says something went wrong and poisons its dependents; a
`not_executed` dependency poisons nothing, so a merge node with one input left out is not
stopped by it and reads the fixed sentence in its place. Three reasons, recorded beside the
status and read back as `reason`: `when_false` (the guard is false — the branch was not
selected), `when_unknown` (the guard is unknown — a decision it names was never made), and
`upstream_not_executed` (every dependency this node has in the graph was left out, which is
decided before the guard and is why `<node>.done`, true whatever the decision did, cannot
revive a node with no input left on that path). Terminal in every reader: it is never
rewritten to `interrupted`, a replan and a stop leave it as it is, and a later run naming
one is refused with "its branch was not selected, so it wrote no output" — the id stays
claimed. The run's tally counts it only when there is one, so a run without branches tallies
exactly as before.
**replan** (adjudication decision; `raven/agent/subagent/dag_adjudication.py`) -- the answer
to an exception report that replaces the plan instead of the node: the agent hands
`resolve_dag_node` a new node list, the answered run stops where it is and finalizes, and a

View File

@ -47,14 +47,11 @@ history.
the artwork is unaltered in design or colour; only the embedded PNG is
resampled to 96x96, which `cmp` will therefore not match for this file alone.
Regenerate it with scripts/refresh_dmxapi_mark.py.
- `MIT-lobe-icons.txt` - fifteen of the eighteen sub-agent brand marks under
`ui-web/src/assets/agents/`, and `providers/vllm.svg`. Those fifteen keep
- `MIT-lobe-icons.txt` - twelve of the fourteen sub-agent brand marks under
`ui-web/src/assets/agents/`, and `providers/vllm.svg`. Those twelve keep
upstream's filenames, so each is byte-identical to the one
`@lobehub/icons-static-svg@1.95.0` ships under that name and the attribution is checkable
with `cmp` rather than by trust. The other three on the same nominative basis as the
vendor marks above: `raven.svg` is this project's own mark, drawn here and not upstream's;
`miromind.svg` is MiroMind's own favicon; `mirasim.svg` is the mark mirasim.ai serves for
itself at `/icon.svg`, copied byte for byte from the drawing its `marks.tsx` shares. No
`cmp` applies to those three. The rest of `providers/` moved to the vendors'
with `cmp` rather than by trust. `raven.svg` is this project's own mark, drawn here and
not upstream's, so no `cmp` applies to it. The rest of `providers/` moved to the vendors'
own colour marks; see the Cherry Studio entry above.
- `MIT-nanobot.txt` - Nanobot license notice.

View File

@ -10,7 +10,7 @@ COVERAGE_DIFF_THRESHOLD ?= 90
# Allowed line or branch regression in percentage points to absorb rounding noise.
COVERAGE_RATCHET_TOLERANCE ?= 0.05
DOCKER_IMAGE ?= raven:local
COVERAGE_REPORT_ARGS = --cov=raven --cov=raven_everos --cov=raven_everos_cloud --cov-branch --cov-report=term-missing:skip-covered --cov-report=xml --cov-report=json --cov-report=html
COVERAGE_REPORT_ARGS = --cov=raven --cov=raven_everos --cov-branch --cov-report=term-missing:skip-covered --cov-report=xml --cov-report=json --cov-report=html
# One slice of the suite, K/N; the shard writes its .coverage data and no report.
COVERAGE_SHARD ?= 1/1
# Without an explicit encoding= Python opens text files in the locale encoding.
@ -21,7 +21,7 @@ COVERAGE_SHARD ?= 1/1
export PYTHONUTF8 := 1
# Extra pytest flags for a shard; CI passes --idle-ceiling-strict, a local run stays warning-only.
PYTEST_ARGS ?=
COVERAGE_DATA_ARGS = --cov=raven --cov=raven_everos --cov=raven_everos_cloud --cov-branch --cov-report=
COVERAGE_DATA_ARGS = --cov=raven --cov=raven_everos --cov-branch --cov-report=
# Where the shards' .coverage.* files are gathered before they are combined.
COVERAGE_DATA_DIR ?= coverage-data

View File

@ -5,7 +5,7 @@
<p align="center">
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
<a href="https://arxiv.org/abs/2609.33439"><img src="https://img.shields.io/badge/arXiv-2609.33439-B31B1B?labelColor=gray&style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv"></a>
<a href="https://huggingface.co/papers/2609.33439"><img src="https://img.shields.io/badge/HuggingFace-%231%20Paper%20of%20the%20Day-F5C842?labelColor=gray&style=for-the-badge&logo=huggingface&logoColor=white" alt="Hugging Face #1 Paper of the Day"></a>
<a href="https://huggingface.co/papers/2609.33439"><img src="https://img.shields.io/badge/HuggingFace-Paper-F5C842?labelColor=gray&style=for-the-badge&logo=huggingface&logoColor=white" alt="Hugging Face"></a>
<a href="https://discord.gg/gYep5nQRZJ"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_presence_count&suffix=%20online&label=Discord&color=404EED&labelColor=gray&style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
<a href="https://github.com/EverMind-AI/EverOS/discussions/67"><img src="https://img.shields.io/badge/WeCom-EverMind_Community-07C160?labelColor=gray&style=for-the-badge&logo=wechat&logoColor=white" alt="WeCom"></a>
</p>
@ -203,10 +203,6 @@ Raven can connect to and orchestrate agents via ACP, CLI, or OpenAI-compatible A
<img src="https://github.com/user-attachments/assets/3370c883-00ac-4471-97ef-f4312df77202" width="80%" alt="Third-party agents: Claude Code, Codex, OpenCode, Hermes Agent, OpenClaw, MiroThinker, GitHub Copilot, Qwen Code, CodeBuddy, Qoder, Grok Build, Kimi Code, and Pi">
</p>
## ❯❯ News
- 📣 **2026-09-30** — Raven's technical report is [**#1 Paper of the day**](https://huggingface.co/papers/2609.33439) on Hugging Face.
## ❯❯ Quick Start
### 🤖 Install with Your Agent

View File

@ -5,7 +5,7 @@
<p align="center">
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
<a href="https://arxiv.org/abs/2609.33439"><img src="https://img.shields.io/badge/arXiv-2609.33439-B31B1B?labelColor=gray&style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv"></a>
<a href="https://huggingface.co/papers/2609.33439"><img src="https://img.shields.io/badge/HuggingFace-%231%20Paper%20of%20the%20Day-F5C842?labelColor=gray&style=for-the-badge&logo=huggingface&logoColor=white" alt="Hugging Face #1 Paper of the Day"></a>
<a href="https://huggingface.co/papers/2609.33439"><img src="https://img.shields.io/badge/HuggingFace-Paper-F5C842?labelColor=gray&style=for-the-badge&logo=huggingface&logoColor=white" alt="Hugging Face"></a>
<a href="https://discord.gg/gYep5nQRZJ"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_presence_count&suffix=%20online&label=Discord&color=404EED&labelColor=gray&style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
<a href="https://github.com/EverMind-AI/EverOS/discussions/67"><img src="https://img.shields.io/badge/WeCom-EverMind_Community-07C160?labelColor=gray&style=for-the-badge&logo=wechat&logoColor=white" alt="WeCom"></a>
</p>
@ -205,10 +205,6 @@ Raven 可以通过 ACP、CLI 或兼容 OpenAI 的 API 接入并编排 Agent,
<img src="https://github.com/user-attachments/assets/3370c883-00ac-4471-97ef-f4312df77202" width="80%" alt="Third-party agents: Claude Code, Codex, OpenCode, Hermes Agent, OpenClaw, MiroThinker, GitHub Copilot, Qwen Code, CodeBuddy, Qoder, Grok Build, Kimi Code, and Pi">
</p>
## ❯❯ 新闻
- 📣 **2026-09-30** — Raven 技术报告获评 Hugging Face [**#1 Paper of the day**](https://huggingface.co/papers/2609.33439)。
## ❯❯ 快速开始
### 🤖 让 Agent 帮你安装

View File

@ -34,12 +34,9 @@ Highlights before publishing. Structure:
install.sh one-liner for Linux / macOS / WSL2
install.ps1 one-liner for native Windows (plus the PowerShell 5.1 direct URL)
then: the installer ends on `raven web` (first-run setup is on that page);
bare `raven` opens the page too, `raven tui` for the TUI, `raven onboard` to
reconfigure, `raven resources` for the knowledge models the Windows installer
does not download
`raven` for the TUI, `raven onboard` to reconfigure
## Upgrade
the sidebar's update row (a page served by 0.2.3 or later), or
raven web --stop, raven upgrade, then raven web once the upgrade has finished,
with its limits (latest stable unless on the beta channel, plugin wheels
included, editable checkouts untouched, foreground on POSIX, external helper
@ -49,7 +46,7 @@ Highlights before publishing. Structure:
- Version: `X.Y.Z`
- Tag: `vX.Y.Z`
- Stability: <public preview patch | public preview minor | ...> # fill by hand per release type
- Assets: wheel, source distribution, the four plugin wheels, locked
- Assets: wheel, source distribution, the three plugin wheels, locked
constraints (`raven-constraints.txt`) and the plugin list (`raven-plugins.txt`)
## Notes
@ -63,11 +60,10 @@ Highlights before publishing. Structure:
1. Bump `version` in `pyproject.toml`, run `uv lock`, then open a PR; merge to `main`.
2. `git tag vX.Y.Z && git push origin vX.Y.Z`.
3. CI (`release.yml`) builds the wheel + sdist and the plugin wheels, writes the
plugin list, exports the locked constraints from `uv.lock`
(`uv export --locked`, which fails the release if the lock is stale vs
pyproject), and creates a **draft** GitHub Release with all of them attached,
titled and prefilled from the template.
3. CI (`release.yml`) builds the wheel + sdist, exports the locked constraints
from `uv.lock` (`uv export --locked`, which fails the release if the lock is
stale vs pyproject), and creates a **draft** GitHub Release with all three
attached, titled and prefilled from the template.
4. Fill the summary + Highlights in the draft, then click **Publish**.
Publishing makes it `/releases/latest`, which `install.sh` serves.

View File

@ -14,7 +14,7 @@ Raven is a harness of harnesses, two layers deep:
permission gate, the built-in tools, memory, and the roster of agents it
can dispatch to.
- **Your agent** is a second harness riding that loop: a folder with a
launcher that renders a config and serves the installed raven's own
launcher that renders a config and execs the installed raven's own
`raven acp`. Your identity, your tools, and your hooks enter through the
plugin seam; the core never imports your code and never learns your name.
@ -73,7 +73,7 @@ Each file, its one job, and the mistake most often made in it:
| File | Job | Common mistake |
|---|---|---|
| `subagent.json` | The roster row: the only file written for someone else (the dispatching model). `name` is the dispatch identity; `description` and `owns` are prompts -- the model decides from them alone when to pick you; `everos` ids are the machine identity (never change them after first use); `command` keeps `{PYTHON}` / `{SUBAGENT_DIR}` verbatim -- discovery resolves them in memory | Leaving the TODO prompts in place: the agent then never gets picked, and nothing errors |
| `run.py` | The launcher: renders the config (secret slots, host LLM inheritance, state root, plugin roots) and serves `python -m raven acp`; POSIX replaces the launcher, while Windows keeps it alive until the server exits | Writing state into the agent folder; everything the agent persists belongs under the state root |
| `run.py` | The launcher: renders the config (secret slots, host LLM inheritance, state root, plugin roots) and execs `python -m raven acp` -- it is not in the room during the session | Writing state into the agent folder; everything the agent persists belongs under the state root |
| `config.json` | The birth certificate: the diff between your agent and stock raven, in the host's own config schema. Ships as the minimal plugin slice | Adding `plugins.dirs` here -- the launcher injects it absolute at render time, and overwrites whatever this file says |
| `install.py` | The optional pinning ceremony: registers the row through `raven.config.update_subagents`. Needed only for a folder outside the discovery tree, an edited row, or a deliberately pinned one | Running it and expecting a live raven to notice -- the roster is read at startup; restart the gateway |
| `.env.example` | The secret slots, documented: the API key (own-key mode), the state root override, the ACP home override. Copy to `.env`, which stays in the folder and out of every wheel | Setting the key but no `providers` block in `config.json`: own-key mode renders a key with no provider/model to route on -- handshake green, first real turn dead |
@ -96,10 +96,6 @@ doctor just compiled.
optional knobs: `timeout_seconds`, `blocking_interaction`, `channels`).
The factory signature is `Callable[[PluginContext], Tool | None]` --
return `None` to decline registration for this run.
`agent_output = True` is a permission for results that carry another agent's
content (whose redaction policy is that agent's), and each such result still
has to claim it -- `ToolResult(..., agent_output=True)` -- so a tool's own
refusals and status lines around them stay Raven's text and stay scrubbed.
2. **Declare it** in `raven-plugin.toml`:
```toml
@ -161,15 +157,7 @@ Every phase returns a `HookDecision`. Its vocabulary, by field:
never in the folder.
- **Your plugin's slice** is `plugins.config["<id>"]` inside that file --
yours alone, delivered verbatim as `ctx.config` to every factory. This is
where your tools' and hooks' own knobs live; the host never interprets it,
with one exception below.
- **Long-term memory is not yours to point.** `memory.backend` and the memory
distribution's address arrive from the host at render time, because the host
reads a sub-agent's memories back through its own backend -- a product
writing anywhere else leaves that record empty with nothing reporting it. Do
not name a server in your config; name only your identity (`memory.userId` /
`agentId`, and `user_id` / `agent_id` in the slice), which is what keeps your
memories apart from every other product's inside one store.
where your tools' and hooks' own knobs live; the host never interprets it.
Secrets never sit in `config.json` (it is publishable): they ride `.env` or
the environment, merged in at render time. With no key of your own, the

View File

@ -26,15 +26,13 @@ it has. The agent then reads that home instead of the host's.
What one agent directory carries:
- `run.py` -- a stdlib-only launcher: render the agent's config (secret
slots, host LLM inheritance, mode catalogue), then serve
`python -m raven acp --config <rendered>` on the installed raven. POSIX replaces
the launcher; Windows keeps it alive until the server exits, so the host and
configuration cleanup still see the owning process.
slots, host LLM inheritance, mode catalogue), then exec
`python -m raven acp --config <rendered>` on the installed raven.
- `config.json` -- the baseline profile.
- `modes/*.json` -- optional per-session overlays, surfaced as `acp.modes`
for a client's mode picker (`research`, `raven-oncall`, and `code` ship one today).
An agent that ships no `modes/` renders no `acp` block, and the raven it
serves then falls back to its own three built-in tiers -- so
execs then falls back to its own three built-in tiers -- so
`session/set_mode` answers with those rather than method-not-found. An
overlay's `agents.defaults.reasoningEffort` is lifted onto the mode entry as
the trunk's `reasoningEffort` knob; the rest of an overlay is the agent's
@ -119,12 +117,12 @@ What one agent directory carries:
slice is absent (what the scaffold's engine templates do), or by the
operator's `plugins.disabled` list.
Prompt assets ride with the plugin whose conduct they teach, under
`plugins/<id>/prompts/`: the workspace guide `run.py` regenerates on every
launch (oncall's TOOLS.md section, code's whole-file TOOLS.md) lives there.
`plugins/<id>/prompts/`: the workspace guide `run.py` seeds once
(oncall's TOOLS.md section, code's whole-file TOOLS.md) lives there.
`raven-code` also seeds its identity as `soul.md` (beside `run.py`, the
raven-research shape) and a coding conduct as `agent.md` (one variant per
model family, the fork's split; every launch writes the variant its model
reads, and an operator's edit is backed up before it is replaced),
model family, the fork's split; a partition still carrying the other
variant or older managed seed is refreshed, an operator's edit never is),
and its code-flow hook
contributes the working directory's own instruction files (`AGENTS.md` /
`CLAUDE.md` / `CONTEXT.md`, the slice's `projectFiles`) to each turn's
@ -150,7 +148,7 @@ What one agent directory carries:
channel to ask on -- with the default it refused every write and the model
reported the task incomplete.
- `soul.md` + the contract the plugin renders into `agent.md` -- optional:
the agent's own identity, regenerated into the workspace on every launch, for an agent
the agent's own identity, seeded into the workspace once, for an agent
that replaces the host identity (research does; its `context.dropSegments`
keeps the host's own identity segment out of the prompt). An agent whose
vendored twin served the host-generic identity carries no `soul.md` and
@ -170,7 +168,7 @@ What one agent directory carries:
Agent vocabulary:
- **Rendered config** -- what `run.py` writes and serves from: the baseline
- **Rendered config** -- what `run.py` writes and execs against: the baseline
`config.json` after secret slots, host LLM inheritance and the mode
catalogue are applied. Rendered files live under the state root, never in
the agent directory.
@ -187,39 +185,9 @@ Agent vocabulary:
- **Tool-face pin** -- each launcher test pins the exact tool face the
rendered config exposes (`VENDORED_TOOL_FACE` in
`tests/test_agents_<agent>_launcher.py`) to its vendored twin's face.
- **Regenerated prompts** -- the prompt files a product owns (identity,
contract, tool guide) are rewritten on every launch from the release and the
rendered config (`write_generated()` in `raven/config/product_render.py`),
so the text the model reads matches the gates of the same release. An
operator's own lines go in the file's `*.local.md` sibling (`agent.local.md`
beside `agent_memory/profile/agent.md`, `soul.local.md` beside `soul.md`,
`TOOLS.local.md` beside `TOOLS.md`), appended after the product text at the
next launch; keep only the lines still needed there, saved as UTF-8 -- one
in another encoding stops the launch, and the error names it. A file that
does not hold the text the product last wrote -- edited in place, or left
by an older release before receipts existed -- is saved as
`<name>.bak-<time>-<pid>` before it is replaced, and the launcher's log
names the backup. A backup is never readable by more accounts than the file
was: an owner-only copy on POSIX, and on Windows a hard link to the file
itself, which keeps its ACL; a Windows volume that cannot hard-link stops
the launch and names the file rather than copy it. The regenerated file
keeps the file's own mode, and on Windows its DACL. Backups are never
deleted for you: remove one once what you need from it is in the
`*.local.md` file. The ppt engine writes into
whatever home its plugin is granted, which can be a host's own or another
product's, so it replaces only a seat its own receipt or a shipped prompt's
digest shows it wrote, and leaves any other file as it is. In Raven-PPT's
own home that includes a seat edited before prompts were regenerated: it
keeps the edit and its `*.local.md` is not applied until the seat is
deleted, and the next turn writes it fresh. The engine logs such a seat at
DEBUG only, since in a host's home it is the host's own, and retries a
failed write on the next turn instead of stopping. Each receipt
line names the product that wrote the file, so one product's receipt is
never another's proof. Two processes of one product share these
files, so a launch can change what an older process still running reads
next turn. Rolling back the code does not roll back the files: stop the
product's processes, delete each file whose `.<name>.generated.sha256`
receipt still matches it, and relaunch on the older code.
- **Seed-once** -- workspace assets (guides, identity) are written only when
absent (`seed_once()` in `raven/config/product_render.py`), so a user's
later edits survive relaunches.
Agent notes:

View File

@ -72,7 +72,9 @@
"config": {
"everos-memory": {
"user_id": "raven-code",
"agent_id": "raven-code"
"agent_id": "raven-code",
"mode": "http",
"base_url": "http://localhost:18791"
},
"code-flow": {
"enabled": true,

View File

@ -1,88 +0,0 @@
# Raven-Code Python diagnostics
When the replacement tool face is enabled, Python writes and edits return
syntax and name-binding diagnostics alongside the normal result. The name
checks cover undefined names (`F821`), undefined exports (`F822`), and local
variables used before assignment (`F823`). A direct edit compares with the
previous content to suppress existing name findings. A syntax error still
present after an edit remains visible, including after a rewrite that left
the file unchanged. A baseline that cannot be parsed, decoded or analyzed is
unknown, so findings are not claimed to be newly introduced. Diagnostics never undo an
edit, automatically fix code, or change the command's exit status.
These checks run only through the enabled code-flow replacement tools. Loading
the plugin or installing Pyflakes does not modify the host's built-in tools;
other agents keep their existing behavior unless explicitly configured to use
this tool face. Pyflakes is imported when the diagnostics module loads, so no
single check pays for a cold import inside its wait.
The switches live under `plugins.config["code-flow"].tools`:
| Switch | Default | Effect |
| --- | --- | --- |
| `pythonSyntaxNote` | `true` | Master switch for Python diagnostics. |
| `pythonLint` | `true` | Add name-binding checks to syntax diagnostics. |
| `pythonUnusedImports` | `false` | Add advisory `F401` notices. Imports can export names or have side effects; the notice does not recommend unconditional removal. |
| `execPythonDiagnostics` | `true` | Check changed Python files after completed local foreground commands when a checkpoint supplies visibility rules. |
The checks parse source without importing or executing it. They honor inline
`# noqa` / `# noqa: F821` and file-level `# ruff: noqa` / `# flake8: noqa`
comments for name/import checks, read as Ruff reads them: a file-level
directive counts only on a line of its own, and one trailing code suppresses
nothing; a marker counts only when a colon and codes follow it or, with no
colon, whitespace, another comment or the end of the comment does, so a URL
fragment such as `#noqa-section` or a colon with no codes is text. Unlike
Ruff, which takes the first directive in a comment, every directive in it
counts. They use
the host's Python parser and builtins, not the project's complete Ruff/Flake8
configuration or target interpreter;
dynamic bindings and version differences can need human or agent judgment.
Syntax feedback names the parser version. Passing diagnostics do not prove
that the patch is correct or replace project tests.
Name checks skip source over 256 KiB, the syntax check source over 2 MiB, and
a check skipped for size says so in one line. A file is checked as the bytes
on disk, decoded as Python decodes a source file, by its coding declaration or
as UTF-8; written or edited text, which the file tool stores as UTF-8, is
checked as those bytes, so a declaration in it applies. Bytes that do not
decode are reported as the syntax error Python raises for them, at the line
where decoding stops. A changed file that cannot be read reports diagnostics
unavailable. Each file reports at most eight findings.
Post-command checks consider at most eight visible changed Python files inside the
command's working directory, with a 6,000-character diagnostic budget plus
omission notices. The changed files come from the host's own write record for
the command, which lists regular files and skips symlinks; a command whose
directory the host could not list has no record and gets no post-command
checks. Post-command checks require a checkpoint covering the working
directory. With no checkpoint or no visibility verdict, they do not read
changed source files. Direct `write_file` / `edit_file` diagnostics remain
available. Noninteractive runs using the default
`runtime.checkpoint.policy = "interactive"` need an explicit `"always"` policy
to enable checkpoints and post-command checks. Visibility rules apply before the
eight-file limit and withhold ignored files. Visibility queries use batches of
up to 256 files and stop once eight eligible files are found. The host's
visibility callback resolves each queried path synchronously; yielding between
batches bounds that work, but one blocked host callback cannot be preempted by
an asyncio timeout.
Up to four file checks run concurrently, with feedback kept in input order.
Each check analyzes one file; it does not resolve imports across the project.
Python's GIL means concurrency does not promise a CPU speedup. Each file check
has a one-second wait limit, and post-command diagnostics have a three-second
total wait limit, separate from the command timeout.
All diagnostic reads and checks share a private four-worker limit per
process, independent of the host's default executor. There is no background
work queue: when all workers are occupied, new diagnostic work is skipped or
reported unavailable. A timeout or cancellation releases the caller but cannot
interrupt an operating system read or Python check already running. Such work
retains its worker slot until it finishes, preventing an accumulation of
abandoned workers; daemon workers do not delay process shutdown. A file check
that fails, including on source nested too deeply for the parser or checker,
reports diagnostics unavailable; post-command diagnostics that fail or overrun
their wait as a whole are dropped. Either way the operation's result is kept.
For existing files changed by a command, the original source is not
available: feedback explicitly says findings may predate the command.
Background, remote, sandboxed commands, symlinks, and writes outside the watched
directory are not covered. Concurrent writers can also appear in the host's write
record; the check does not establish which process made a change.

View File

@ -41,34 +41,24 @@ class ExecFaceConfig(_Base):
class ToolsConfig(_Base):
"""Raven-Code's file checks and shell interface.
"""The product's own tool face, and the two conduct knobs it carries.
``enabled`` defaults False the D6 way, like the flow itself: an absent
section hands the tools back to the host, and the model is served the
built-ins unchanged.
``require_read_before_edit`` is the fork's "editing unread content is
rejected" rule; ``python_syntax_note`` appends post-write Python
diagnostics to a ``.py`` write or edit; ``restrict_to_workspace`` mirrors the
rejected" rule; ``python_syntax_note`` appends the post-write syntax
verdict to a ``.py`` write or edit; ``restrict_to_workspace`` mirrors the
host's own ``tools.restrictToWorkspace`` -- a plugin factory cannot read
that field (``ServiceLocator`` grants five things and this is not one), so
the launcher renders the product's answer in here. Without it a product
that asked for the fence got replacements with no fence at all.
``python_syntax_note`` is the master diagnostic switch. ``python_lint``
adds name-binding checks; ``python_unused_imports`` opts into advisory
import notices. ``exec_python_diagnostics`` covers changed Python files
under a completed local command's working directory, read from the host's
write record where a checkpoint supplies visibility rules.
Background and remote commands have no local completion snapshot.
"""
enabled: bool = False
require_read_before_edit: bool = True
python_syntax_note: bool = True
python_lint: bool = True
python_unused_imports: bool = False
exec_python_diagnostics: bool = True
restrict_to_workspace: bool = False
exec: ExecFaceConfig = Field(default_factory=ExecFaceConfig)

View File

@ -1,55 +0,0 @@
"""Bounded Raven-Code diagnostic work, isolated from the host's default executor."""
from __future__ import annotations
import asyncio
import contextvars
import threading
from concurrent.futures import Future
from typing import Callable, TypeVar
T = TypeVar("T")
MAX_WORKERS = 4
class WorkersBusyError(RuntimeError):
"""All diagnostic workers are still occupied; new work is not queued."""
class DiagnosticWorkers:
"""Keep capacity until real work finishes, even after its caller times out."""
def __init__(self, limit: int = MAX_WORKERS) -> None:
self._slots = threading.BoundedSemaphore(limit)
async def run(self, call: Callable[[], T], *, timeout: float) -> T:
if not self._slots.acquire(blocking=False):
raise WorkersBusyError("Raven-Code diagnostic capacity is occupied")
future: Future[T] = Future()
context = contextvars.copy_context()
def work() -> None:
if not future.set_running_or_notify_cancel():
self._slots.release()
return
try:
result = context.run(call)
except BaseException as exc:
self._slots.release()
future.set_exception(exc)
else:
self._slots.release()
future.set_result(result)
# A stalled filesystem read cannot be killed in a Python thread. It
# keeps its slot, but must not hold process shutdown or the host pool.
try:
worker = threading.Thread(target=work, name="raven-code-diagnostics", daemon=True)
worker.start()
except BaseException:
self._slots.release()
raise
return await asyncio.wait_for(asyncio.wrap_future(future), timeout)
WORKERS = DiagnosticWorkers()

View File

@ -1,311 +0,0 @@
"""Bounded Python diagnostics attached to the edit that made them observable."""
from __future__ import annotations
import ast
import importlib.util
import io
import re
import sys
import tokenize
from collections import Counter
from dataclasses import dataclass
from pathlib import Path
from code_flow.tools.diagnostic_workers import WORKERS
# The name checks' one import, paid at plugin load rather than by whichever
# check first needs it: a cold import inside a check's wait was measured at
# 30-70 ms here and can outlast the wait on a cold Windows runner. Absent,
# the import below fails as it did before, and a check reports it.
try:
import pyflakes.checker # noqa: F401
except ImportError:
pass
MAX_SOURCE_BYTES = 256 * 1024
# The syntax check runs past the name checks' bound up to this one. Python's
# syntax tree of 2 MiB of source took about 0.3 s and 190 MiB to build, and of
# 16 MiB 7 s and 1.4 GiB, on a worker nothing can interrupt once it starts.
MAX_SYNTAX_BYTES = 2 * 1024 * 1024
MAX_FINDINGS = 8
CHECK_WAIT_SECONDS = 1.0
UNKNOWN = object()
# A marker counts the way Ruff reads one: an optional lowercase ``ruff:`` or
# ``flake8:`` prefix for the file-level form, ``noqa`` in any case, then either
# a colon and codes or, with no colon, whitespace, another comment or the
# comment's end. Anything else (a URL fragment, a quoted mention, a colon
# without codes) is text. Unlike Ruff, which takes the first directive in a
# comment, every directive in it counts.
_NOQA = re.compile(
r"#\s*(?:(ruff|flake8)\s*:\s*)?(?i:noqa)"
r"(?:\s*:\s*([A-Z]+[0-9]+(?:[\s,]+[A-Z]+[0-9]+)*)|(?!\s*:)(?=[\s#]|$))"
)
@dataclass(frozen=True)
class Finding:
code: str
line: int
column: int
message: str
source: str
@property
def key(self) -> tuple[str, str, str]:
return self.code, self.message, self.source.strip()
def read_source(path: Path) -> bytes:
"""A changed file's bytes for a check, at most one past the syntax bound.
A failed read raises: a baseline that cannot be read is unknown, but the
content being checked has no verdict without its bytes.
"""
if not path.is_file():
raise FileNotFoundError(f"no regular file at {path}")
with path.open("rb") as handle:
return handle.read(MAX_SYNTAX_BYTES + 1)
def _stored(content: str | bytes, limit: int) -> str | bytes:
"""``content`` as the bytes the file tool stores it as: text in UTF-8.
Text longer than ``limit`` in characters is longer in bytes too, so it is
left unencoded, still over the limit by length.
"""
return content.encode("utf-8") if isinstance(content, str) and len(content) <= limit else content
def _refused(raw: bytes, exc: SyntaxError | UnicodeDecodeError) -> Finding:
"""Source Python refuses to decode, placed at the first byte it cannot.
Python's parser places a declared encoding's failure at line 0, and 3.12's
passes undecodable bytes inside a comment, so the place is found here: the
first byte that does not decode, or else the line of the first two that
``tokenize.detect_encoding`` rejects.
"""
if isinstance(exc, UnicodeDecodeError):
# The codec's own buffer: a BOM's codec decodes only what follows the mark.
raw, at, encoding, message = exc.object, exc.start, exc.encoding, str(exc)
else:
first = raw.split(b"\n", 1)[0]
try:
tokenize.detect_encoding(io.BytesIO(first).readline)
except SyntaxError:
at = 0
else:
at = len(first) + 1
encoding, message = "utf-8", exc.msg
start = raw.rfind(b"\n", 0, at) + 1
end = raw.find(b"\n", at)
line = raw[start : end if end >= 0 else len(raw)].decode(encoding, "replace")
return Finding("syntax", raw.count(b"\n", 0, at) + 1, at - start + 1, message, line)
def read_python(path: Path) -> bytes | None | object:
"""Read bounded source bytes; distinguish an absent file from an unavailable baseline.
Bytes, decoded by ``findings`` the way Python decodes a source file: text
decoded here would pick an encoding of its own and hide the file's coding
declaration from the comparison.
"""
try:
if not path.exists():
return None
if not path.is_file() or path.stat().st_size > MAX_SOURCE_BYTES:
return UNKNOWN
with path.open("rb") as handle:
raw = handle.read(MAX_SOURCE_BYTES + 1)
return raw if len(raw) <= MAX_SOURCE_BYTES else UNKNOWN
except OSError:
return UNKNOWN
async def read_before(path: Path) -> bytes | None | object:
try:
return await WORKERS.run(lambda: read_python(path), timeout=CHECK_WAIT_SECONDS)
except Exception: # noqa: BLE001 - an unavailable baseline must not block a write
return UNKNOWN
def _ignores(text: str) -> dict[int, set[str] | None]:
ignored: dict[int, set[str] | None] = {}
for token in tokenize.generate_tokens(io.StringIO(text).readline):
if token.type != tokenize.COMMENT:
continue
# Ruff honors a file-level directive only on a line of its own and
# ignores one that trails code, which suppresses nothing.
own_line = not token.line[: token.start[1]].strip()
for match in _NOQA.finditer(token.string):
if match[1] and not own_line:
continue
row = 0 if match[1] else token.start[0]
codes = set(re.findall(r"[A-Z]+\d+", match[2].upper())) if match[2] else None
if row not in ignored:
ignored[row] = codes
elif ignored[row] is not None:
ignored[row] = None if codes is None else ignored[row] | codes
return ignored
class PythonDiagnostics:
"""Report actionable name errors; optional import notices never rewrite code."""
def __init__(self, *, lint: bool = True, unused_imports: bool = False) -> None:
self.lint = lint
self.unused_imports = unused_imports
def findings(self, path: Path, content: str | bytes, *, syntax_only: bool = False) -> list[Finding]:
"""Syntax findings, then the name findings unless ``syntax_only``.
Bytes are decoded as Python reads a source file, by its coding
declaration or else as UTF-8; bytes that do not decode are the syntax
error Python reports for them.
"""
if isinstance(content, str):
text = content
else:
try:
text = importlib.util.decode_source(content)
except (SyntaxError, UnicodeDecodeError) as exc:
return [_refused(content, exc)]
lines = text.splitlines()
try:
tree = ast.parse(text, filename=str(path))
except SyntaxError as exc:
row = exc.lineno or 1
source = lines[row - 1] if 0 < row <= len(lines) else ""
return [Finding("syntax", row, exc.offset or 1, exc.msg, source)]
except ValueError:
return []
if syntax_only or not self.lint:
return []
from pyflakes.checker import Checker
codes = {"UndefinedName": "F821", "UndefinedExport": "F822", "UndefinedLocal": "F823"}
if self.unused_imports:
codes["UnusedImport"] = "F401"
ignored = _ignores(text)
findings = []
for message in Checker(tree, filename=str(path)).messages:
code = codes.get(type(message).__name__)
if code is None:
continue
row = message.lineno
if any(key in ignored and (ignored[key] is None or code in ignored[key]) for key in (0, row)):
continue
source = lines[row - 1] if 0 < row <= len(lines) else ""
findings.append(Finding(code, row, message.col + 1, message.message % message.message_args, source))
return sorted(findings, key=lambda item: (item.line, item.column, item.code))
def note(self, path: Path, content: str | bytes, *, before: str | bytes | None | object = UNKNOWN) -> str:
try:
if path.suffix != ".py":
return ""
# Text is what the file tool writes, UTF-8, so it is checked as those
# bytes: Python reads the stored file, not the string in hand, and a
# coding declaration in the text applies to it. The content replaced
# is compared the same way, or one line would read two ways.
stored = _stored(content, MAX_SYNTAX_BYTES)
if len(stored) > MAX_SYNTAX_BYTES:
return (
f"\nPython diagnostics skipped for {path}: the source is over "
f"{MAX_SYNTAX_BYTES // 1024 // 1024} MiB. Run targeted project checks."
)
syntax_only = len(stored) > MAX_SOURCE_BYTES
findings = self.findings(path, stored, syntax_only=syntax_only)
replaced = _stored(before, MAX_SOURCE_BYTES) if isinstance(before, (str, bytes)) else before
if replaced is None:
baseline = Counter()
elif isinstance(replaced, bytes) and len(replaced) <= MAX_SOURCE_BYTES:
# Source nested too deeply for the parser or checker raises
# rather than parsing to nothing: unavailable for the content
# written, an unknown baseline for the content replaced.
try:
earlier = self.findings(path, replaced)
except Exception: # noqa: BLE001 - an unanalyzable baseline is unknown, not clean
earlier = None
baseline = (
None
if earlier is None or any(item.code == "syntax" for item in earlier)
else Counter(item.key for item in earlier)
)
else:
baseline = None
except Exception as exc: # noqa: BLE001 - diagnostics must not change an already completed write's verdict
return (
f"\nPython diagnostics unavailable ({type(exc).__name__}) for {path}; the file was kept. "
"Run targeted project checks."
)
if baseline is not None:
fresh = []
for finding in findings:
if baseline[finding.key]:
baseline[finding.key] -= 1
else:
fresh.append(finding)
findings = fresh
if not findings:
if syntax_only and self.lint:
return (
f"\nPython name checks skipped for {path}: the source is over "
f"{MAX_SOURCE_BYTES // 1024} KiB, so only its syntax was checked."
)
return ""
scope = (
"new findings compared with the content before this call"
if baseline is not None
else "current findings; the baseline is unknown or could not be parsed, so these may predate this call"
)
rows = [f"\nPython diagnostics for {path} ({scope}; the file was kept):"]
for finding in findings[:MAX_FINDINGS]:
label = "Python syntax error" if finding.code == "syntax" else finding.code
severity = "NOTICE" if finding.code == "F401" else "WARNING"
rows.append(f"{severity}: line {finding.line}, column {finding.column}: {label}: {finding.message[:240]}")
if finding.source:
rows.append(f" {finding.source.strip()[:160]}")
if len(findings) > MAX_FINDINGS:
rows.append(f"{len(findings) - MAX_FINDINGS} more findings omitted; inspect this file directly.")
if any(item.code == "syntax" for item in findings):
rows.append(
f"Parsed with Python {sys.version_info.major}.{sys.version_info.minor}; "
"check the project's Python version before changing newer syntax. "
"Fix confirmed syntax/indentation errors before relying on execution results."
)
if any(item.code in {"F821", "F822", "F823"} for item in findings):
rows.append(
"Check the named symbol's spelling, scope, import, or assignment order. "
"Confirm the intended binding; do not add dummy values just to silence this warning."
)
if any(item.code == "F401" for item in findings):
rows.append(
"An unused import can be a public re-export or have side effects; inspect its role before removing it."
)
return "\n".join(rows)
async def check(self, path: Path, *, text: str | None = None, before: str | None | object = UNKNOWN) -> str:
if path.suffix != ".py":
return ""
def inspect() -> str:
return self.note(path, read_source(path) if text is None else text, before=before)
try:
return await WORKERS.run(inspect, timeout=CHECK_WAIT_SECONDS)
except Exception as exc: # noqa: BLE001 - keep the completed operation's result on checker failure
return (
f"\nPython diagnostics unavailable ({type(exc).__name__}) for {path}; the file was kept. "
"Run targeted project checks."
)
__all__ = [
"MAX_SOURCE_BYTES",
"MAX_SYNTAX_BYTES",
"UNKNOWN",
"PythonDiagnostics",
"read_before",
"read_python",
"read_source",
]

View File

@ -56,8 +56,6 @@ from typing import Any
from loguru import logger
from code_flow.tools.diagnostic_workers import MAX_WORKERS
from code_flow.tools.diagnostics import UNKNOWN, PythonDiagnostics
from raven.agent.tools.shell import ExecTool
from raven.contracts.tool import ToolOutput, ToolResult
from raven.sandbox.direct_executor import DirectExecutor
@ -80,10 +78,6 @@ _SPILL_COUNTER = itertools.count(1)
#: Variables the probe's own shell adds on top of the baseline; not part of it.
_SHELL_ADDED = frozenset({"PWD", "OLDPWD", "SHLVL", "_"})
_PROBE_TIMEOUT = 15
_DIAGNOSTIC_WAIT_SECONDS = 3.0
_DIAGNOSTIC_FILES = 8
_DIAGNOSTIC_CHARS = 6000
_VISIBILITY_BATCH = 256
def spill_output(text: str, spill_dir: Path | None) -> str | None:
@ -255,13 +249,11 @@ class CodeExecutor(DirectExecutor):
)
def _prefixed(note: str, out: str | ToolResult, *, append: bool = False) -> str | ToolResult:
def _prefixed(note: str, out: str | ToolResult) -> str | ToolResult:
"""``note`` in front of a tool's answer, whatever shape the answer took."""
text = out.model_text if isinstance(out, ToolResult) else str(out)
text = text + note if append else note + text
if isinstance(out, ToolOutput):
return ToolOutput(
text,
note + str(out),
out.display_text,
retryable=out.retryable,
blocks_call=out.blocks_call,
@ -270,12 +262,10 @@ def _prefixed(note: str, out: str | ToolResult, *, append: bool = False) -> str
blocks=out.blocks,
diff=out.diff,
file_change=out.file_change,
removed=out.removed,
written=out.written,
)
if isinstance(out, ToolResult):
return ToolResult(
model_text=text,
model_text=note + out.model_text,
display_text=out.display_text,
retryable=out.retryable,
blocks_call=out.blocks_call,
@ -284,10 +274,8 @@ def _prefixed(note: str, out: str | ToolResult, *, append: bool = False) -> str
blocks=out.blocks,
diff=out.diff,
file_change=out.file_change,
removed=out.removed,
written=out.written,
)
return text
return note + str(out)
class CodeExecTool(ExecTool):
@ -295,80 +283,14 @@ class CodeExecTool(ExecTool):
_MAX_OUTPUT = MAX_OUTPUT
def __init__(
self,
*args: Any,
max_timeout: int = DEFAULT_MAX_TIMEOUT,
python_diagnostics: bool = True,
python_lint: bool = True,
python_unused_imports: bool = False,
**kwargs: Any,
) -> None:
def __init__(self, *args: Any, max_timeout: int = DEFAULT_MAX_TIMEOUT, **kwargs: Any) -> None:
super().__init__(*args, **kwargs)
self._python_diagnostics = python_diagnostics
self._diagnostics = PythonDiagnostics(lint=python_lint, unused_imports=python_unused_imports)
# The base ``execute`` clamps against ``self._MAX_TIMEOUT``; the
# instance value replaces the class constant of 600.
self._MAX_TIMEOUT = max_timeout
# The loop's backstop above the executor's own timeout, as trunk sets it.
self.timeout_seconds = float(max_timeout + 60)
async def _diagnose_writes(self, root: Path, out: str | ToolResult) -> str:
if self._shadow is None or (shadow := self._shadow(root)) is None:
return ""
# The host's write record lists regular files under the command's
# directory and already skips symlinks; only its Python files matter.
changed = [
(item.path, None if item.created else UNKNOWN)
for item in getattr(out, "written", ())
if Path(item.path).suffix == ".py"
]
if not changed:
return ""
unchecked_visibility = 0
candidates = []
for start in range(0, len(changed), _VISIBILITY_BATCH):
# The host resolves a batch's paths on the loop, so batches bound
# each stretch and the sleep gives the outer deadline a point to
# cancel between them. Far wider than the file limit: each query
# is a git process, and batches of eight spent the wait on ignored
# files.
await asyncio.sleep(0)
batch = changed[start : start + _VISIBILITY_BATCH]
shown = await shadow.trackable([path for path, _ in batch])
candidates.extend((Path(path), old) for path, old in batch if path in shown)
if len(candidates) >= _DIAGNOSTIC_FILES:
unchecked_visibility = len(changed) - start - len(batch)
break
selected = candidates[:_DIAGNOSTIC_FILES]
limit = asyncio.Semaphore(MAX_WORKERS)
async def check(path: Path, old: Any) -> str:
async with limit:
return await self._diagnostics.check(path, before=old)
results = await asyncio.gather(*(check(path, old) for path, old in selected))
notes = []
size = 0
for note in results:
if note:
if size + len(note) > _DIAGNOSTIC_CHARS:
notes.append("\nFurther Python diagnostics omitted to keep this tool result bounded.")
break
notes.append(note)
size += len(note)
if len(candidates) > _DIAGNOSTIC_FILES:
notes.append(
f"\nPython diagnostics limited to {_DIAGNOSTIC_FILES} changed files; "
f"{len(candidates) - _DIAGNOSTIC_FILES} more were skipped."
)
if unchecked_visibility:
notes.append(
f"\n{unchecked_visibility} additional changed files were not checked after the "
f"{_DIAGNOSTIC_FILES}-file diagnostic limit; their visibility was not evaluated."
)
return "\n".join(notes)
@property
def parameters(self) -> dict[str, Any]:
schema = super().parameters
@ -393,9 +315,6 @@ class CodeExecTool(ExecTool):
**kwargs: Any,
) -> str | ToolResult:
note = ""
inspect_writes = (
self._python_diagnostics and not machine and not run_in_background and not self._executor.is_sandboxed
)
if timeout is not None and not machine and not run_in_background and timeout > self._MAX_TIMEOUT:
note = (
f"[note: timeout {timeout}s clamped to the {self._MAX_TIMEOUT}s ceiling; for longer "
@ -410,15 +329,6 @@ class CodeExecTool(ExecTool):
run_in_background=run_in_background,
**kwargs,
)
if inspect_writes and isinstance(out, (ToolOutput, ToolResult)) and not out.blocks_call:
root = Path(self._cwd_for(working_dir))
try:
diagnostics = await asyncio.wait_for(self._diagnose_writes(root, out), timeout=_DIAGNOSTIC_WAIT_SECONDS)
except Exception as exc: # noqa: BLE001 - never replace a completed command's output with a checker error
logger.debug("code-flow: post-exec diagnostics unavailable: {}", exc)
else:
if diagnostics:
out = _prefixed(diagnostics, out, append=True)
return _prefixed(note, out) if note else out

View File

@ -6,7 +6,7 @@ descriptions), the accepted spellings (``cast_params`` maps the host's
``path`` / ``old_text`` / ``new_text`` onto the fork's names, so a call in
either convention runs), and two pieces of conduct the fork measured its way
to -- a read ledger that refuses to edit content unseen by the current session, and
post-write Python diagnostics in the same tool result.
a post-write Python syntax verdict in the same tool result.
Everything else (path resolution against the bound working directory, the
unified diff the UI renders, ``FileChange`` on the result, image reads) is
@ -15,15 +15,37 @@ trunk's, inherited unchanged.
from __future__ import annotations
import ast
from pathlib import Path
from typing import Any
from code_flow.tools.diagnostics import UNKNOWN, PythonDiagnostics, read_before
from code_flow.tools.read_state import Owner, ReadLedger, current_ledger
from raven.agent.tools import filesystem as trunk
from raven.contracts.tool import FileChange, ToolResult
def python_syntax_note(fp: Path, text: str) -> str:
"""Post-write syntax verdict for ``.py`` files, appended to the result.
Deterministic and in-band: a write or edit that leaves the file
unparseable is told so in the same tool result, costing zero extra
rounds. Syntax only -- a line that crashes at runtime still needs tests.
"""
if fp.suffix != ".py":
return ""
try:
ast.parse(text)
except SyntaxError as exc:
location = f"line {exc.lineno}" if exc.lineno else "unknown line"
return (
f"\nWARNING: {fp.name} now has a Python syntax error at {location}: "
f"{exc.msg}. The file cannot even be parsed; fix it before moving on."
)
except Exception: # noqa: BLE001 - a verdict the parser cannot give is no verdict
return ""
return ""
def _append_note(result: str | ToolResult, note: str) -> str | ToolResult:
if not note:
return result
@ -68,9 +90,11 @@ class ReadFileTool(_Aliased, trunk.ReadFileTool):
ALIASES = {"path": "file_path"}
#: One line may spend this many characters before it is cut, the fork's
#: budget. Cut on trunk's own hook, before the page's budget counts the
#: line, so a page of minified lines holds its lines rather than one
#: line's head; the mark makes the description's promise true.
#: budget. Trunk numbers a line whole, so a minified bundle or a base64
#: blob on one line overruns the whole-result budget by itself: the result
#: comes back with NO body and a note telling the model to continue from
#: the same offset, which it can do forever. Cutting the line keeps the
#: read useful and makes the description's promise true.
_MAX_LINE_CHARS = 2_000
@property
@ -104,32 +128,62 @@ class ReadFileTool(_Aliased, trunk.ReadFileTool):
try:
fp = self._resolve(file_path)
except Exception: # noqa: BLE001 - the read itself reported the path problem
fp = None
if fp is not None and (ledger := self._ledger) is not None:
ledger.note(fp)
if trunk._machine_of(file_path) is not None:
# Answered by a registered machine's node, which runs trunk's tool
# without this fork's hook: cut after the read. Decided by where
# the read ran, never by a line's text -- a line whose own text
# ends like the mark was taken for a cut one and came back whole.
return _cut_long_lines(result, self._MAX_LINE_CHARS)
# Read here: every line was cut on the hook before the page's budget counted it.
return result
if (ledger := self._ledger) is not None:
ledger.note(fp)
if _bodyless(result):
# One line longer than the whole-result budget leaves trunk's read
# with nothing to show and a note pointing at the same offset, so
# the cut has to happen before that budget is spent, not after.
taken = self._read_cut(fp, offset, limit)
if taken is not None:
return taken
return _cut_long_lines(result, self._MAX_LINE_CHARS)
def _cut_line(self, line: str) -> str:
"""Trunk's hook: the line cut to the fork's budget before it is numbered and the page's budget counts it."""
return _cut(line, self._MAX_LINE_CHARS)
def _read_cut(self, fp: Path, offset: int, limit: int | None) -> str | None:
"""Trunk's own numbering, with every line cut to the line budget first.
Returns ``None`` when the file cannot be read as text -- the caller
then keeps whatever trunk answered rather than inventing something.
"""
try:
all_lines = fp.read_text(encoding="utf-8", errors="replace").splitlines()
except OSError:
return None
total = len(all_lines)
if total == 0:
return None
start = max(offset, 1) - 1
if start >= total:
return None
end = min(start + (limit or self._DEFAULT_LIMIT), total)
numbered = []
for index, line in enumerate(all_lines[start:end]):
if len(line) > self._MAX_LINE_CHARS:
line = line[: self._MAX_LINE_CHARS] + f"... (line truncated to {self._MAX_LINE_CHARS} chars)"
numbered.append(f"{start + index + 1}| {line}")
body, chars, kept = [], 0, 0
for line in numbered:
chars += len(line) + 1
if chars > self._MAX_CHARS and kept:
break
body.append(line)
kept += 1
shown_end = start + kept
text = "\n".join(body)
if shown_end < total:
text += f"\n\n(Showing lines {start + 1}-{shown_end} of {total}. Use offset={shown_end + 1} to continue.)"
else:
text += f"\n\n(End of file — {total} lines total)"
return text
class WriteFileTool(_Aliased, trunk.WriteFileTool):
ALIASES = {"path": "file_path"}
def __init__(
self, *args: Any, syntax_note: bool = True, lint: bool = True, unused_imports: bool = False, **kwargs: Any
) -> None:
def __init__(self, *args: Any, syntax_note: bool = True, **kwargs: Any) -> None:
super().__init__(*args, **kwargs)
self._syntax_note = syntax_note
self._diagnostics = PythonDiagnostics(lint=lint, unused_imports=unused_imports)
@property
def description(self) -> str:
@ -161,7 +215,6 @@ class WriteFileTool(_Aliased, trunk.WriteFileTool):
except (OSError, ValueError) as exc:
return f"Error: {exc}"
ledger = self._ledger
previous = await read_before(fp) if self._syntax_note and fp.suffix == ".py" and mode == "append" else UNKNOWN
known = ledger is not None and ledger.status(fp) == ReadLedger.OK
authored = mode == "overwrite" or not fp.exists()
result = await super().execute(path=file_path, content=content, mode=mode, **kwargs)
@ -180,14 +233,11 @@ class WriteFileTool(_Aliased, trunk.WriteFileTool):
ledger.forget(fp)
if not self._syntax_note:
return result
if isinstance(result, ToolResult) and result.file_change is not None:
previous = result.file_change.before
elif mode != "append" and isinstance(result, ToolResult) and result.model_text.startswith("File unchanged:"):
# Nothing was written, so the content is its own baseline: name
# findings are not repeated, a syntax error still present is.
previous = content
note = await self._diagnostics.check(fp, text=None if mode == "append" else content, before=previous)
return _append_note(result, note)
try:
text = fp.read_text(encoding="utf-8", errors="replace") if mode == "append" else content
except Exception: # noqa: BLE001 - no verdict beats a wrong one
return result
return _append_note(result, python_syntax_note(fp, text))
def _respell(result: str | ToolResult) -> str | ToolResult:
@ -214,20 +264,18 @@ def _respell(result: str | ToolResult) -> str | ToolResult:
return respelled(str(result))
def _cut(line: str, budget: int) -> str:
"""``line`` cut to ``budget`` characters and marked, or as it is when it fits."""
if len(line) <= budget:
return line
return line[:budget] + f"... (line truncated to {budget} chars)"
def _cut_long_lines(result: str | ToolResult, budget: int) -> str | ToolResult:
"""Cut any line of a result past ``budget`` characters, marking the cut: a page cut nowhere else."""
"""Cut any numbered line past ``budget`` characters, marking the cut."""
def cut(text: str) -> str:
if not any(len(line) > budget for line in text.split("\n")):
return text
return "\n".join(_cut(line, budget) for line in text.split("\n"))
out = []
for line in text.split("\n"):
if len(line) > budget:
line = line[:budget] + f"... (line truncated to {budget} chars)"
out.append(line)
return "\n".join(out)
if isinstance(result, ToolResult):
result.model_text = cut(result.model_text)
@ -235,6 +283,12 @@ def _cut_long_lines(result: str | ToolResult, budget: int) -> str | ToolResult:
return cut(str(result))
def _bodyless(result: str | ToolResult) -> bool:
"""A read that answered with a note and no numbered line at all."""
text = result.model_text if isinstance(result, ToolResult) else str(result)
return "| " not in text and "(Showing lines" in text
def _failed(result: str | ToolResult) -> bool:
text = result.model_text if isinstance(result, ToolResult) else str(result)
return text.lstrip().startswith("Error")
@ -247,14 +301,11 @@ class EditFileTool(_Aliased, trunk.EditFileTool):
self,
*args: Any,
syntax_note: bool = True,
lint: bool = True,
unused_imports: bool = False,
require_read: bool = True,
**kwargs: Any,
) -> None:
super().__init__(*args, **kwargs)
self._syntax_note = syntax_note
self._diagnostics = PythonDiagnostics(lint=lint, unused_imports=unused_imports)
self._require_read = require_read
@property
@ -356,8 +407,11 @@ class EditFileTool(_Aliased, trunk.EditFileTool):
ledger.note(fp)
if not self._syntax_note:
return result
note = await self._diagnostics.check(fp, text=result.file_change.after, before=result.file_change.before)
return _append_note(result, note)
try:
after = fp.read_text(encoding="utf-8", errors="replace")
except Exception: # noqa: BLE001
return result
return _append_note(result, python_syntax_note(fp, after))
@staticmethod
def _edit_occurrence(fp: Path, shown: str, old: str, new: str, occurrence: int) -> str | ToolResult:
@ -418,4 +472,5 @@ __all__ = [
"ReadFileTool",
"ReadLedger",
"WriteFileTool",
"python_syntax_note",
]

View File

@ -63,8 +63,6 @@ def make_write_file(ctx: "PluginContext") -> WriteFileTool | None:
workspace=ctx.services.workspace,
allowed_dirs=_fence(ctx, cfg),
syntax_note=cfg.python_syntax_note,
lint=cfg.python_lint,
unused_imports=cfg.python_unused_imports,
read_owner=owner_for(ctx),
)
@ -77,8 +75,6 @@ def make_edit_file(ctx: "PluginContext") -> EditFileTool | None:
workspace=ctx.services.workspace,
allowed_dirs=_fence(ctx, cfg),
syntax_note=cfg.python_syntax_note,
lint=cfg.python_lint,
unused_imports=cfg.python_unused_imports,
read_owner=owner_for(ctx),
require_read=cfg.require_read_before_edit,
)
@ -123,9 +119,6 @@ def make_exec(ctx: "PluginContext") -> CodeExecTool | None:
executor=executor,
extra_allowed_dirs=(home,),
max_timeout=cfg.exec.max_timeout,
python_diagnostics=cfg.python_syntax_note and cfg.exec_python_diagnostics,
python_lint=cfg.python_lint,
python_unused_imports=cfg.python_unused_imports,
)

View File

@ -85,10 +85,8 @@ the host exec instead; follow that tool's stated limits and failure behavior.
to change only the nth non-overlapping exact
match, counted from 1 in file order. `occurrence` normalizes CRLF to LF but
does not use fuzzy whitespace matching; do not combine it with `replace_all`
- If a write or edit reports a Python syntax error, check the project's Python
version before changing newer syntax, and fix confirmed errors before relying
on execution results. An absent diagnostics note is not a successful test;
run the relevant checks
- If a write or edit reports a Python syntax error, fix it before moving on.
An absent syntax note is not a successful test; run the relevant checks
## grep / glob — search, truncation, spill

View File

@ -6,10 +6,10 @@ checkout; this product carries its assets only, and as of the exec-target
swap the process it starts is installed raven itself. Two hostings, the
fork launcher's own pair:
- ``--acp`` (what the roster row spawns): render the config, then serve
``python -m raven acp`` on this interpreter with inherited stdio. POSIX
replaces the launcher; Windows keeps it alive until the server exits.
Every turn uses build_runtime, like the host's TUI and gateway.
- ``--acp`` (what the roster row spawns): render the config, then exec
``python -m raven acp`` on this interpreter, so the server inherits this
pid, process group and stdio, and every turn runs through the same
assembly door (build_runtime) as the host's TUI and gateway.
- ``--task`` / ``--prompt-file``: the one-turn CLI adjudication hosting.
One call is one turn; the same ``--session <id>`` across calls is a
multi-turn conversation. The launcher renders, runs ``raven agent -m``
@ -190,7 +190,7 @@ def log(message: str) -> None:
# Pristine guide and conduct seeds from before per-file seed receipts existed.
# Digests recognize exact product text, so an untouched copy is not backed up.
# Digests recognize exact product text without overwriting an operator's edit.
_LEGACY_GUIDE_DIGESTS = frozenset(
{
"7d0dc36934316639000b486d2775e2581b1378472b29841bdc67231570576657",
@ -210,44 +210,35 @@ _LEGACY_CONDUCT_DIGESTS = frozenset(
)
def _seed_prompt(target: Path, wanted: str | None, pristine: set[str] | frozenset[str] = frozenset()) -> None:
"""Regenerate a product-owned prompt file, or remove it when ``wanted`` is None.
def _seed_prompt(target: Path, wanted: str | None, pristine: set[str] | frozenset[str]) -> None:
"""Refresh an untouched product seed; keep edited files byte-for-byte.
``write_generated`` decides what an edit in place is and backs it up
before writing. The receipt this launcher kept before that function
existed still names the last text it wrote, so it counts as one more
pristine digest and is dropped once the shared receipt replaces it.
A raven older than ``write_generated`` -- a home tree copied out by a
newer wheel serves an older checkout too -- seeds the file once instead,
and says that it will not be refreshed or removed.
A small sibling receipt remembers the last text this launcher wrote, so
later product updates do not need an ever-growing list of old templates.
"""
generate = getattr(render, "write_generated", None)
if generate is None:
if wanted is not None:
render.seed_once(target, lambda: wanted)
log(f"[run] {target.name}: this raven predates regenerated prompts; seeded once, never refreshed or removed")
receipt = target.with_name(f".{target.name}.code-flow.sha256")
if target.exists():
current = target.read_text(encoding="utf-8")
digest = hashlib.sha256(current.encode()).hexdigest()
previous = receipt.read_text(encoding="ascii").strip() if receipt.exists() else ""
if current != wanted and digest not in pristine and digest != previous:
log(f"[run] {target.name}: edited in place; kept unchanged")
return
if wanted is None:
target.unlink(missing_ok=True)
receipt.unlink(missing_ok=True)
return
old_receipt = target.with_name(f".{target.name}.code-flow.sha256")
try:
previous = {old_receipt.read_text(encoding="ascii").strip()}
except (OSError, UnicodeDecodeError):
previous = set()
try:
generate(
target,
wanted,
owner=PRODUCT,
legacy_digests=pristine | previous,
notify=lambda message: log(f"[run] {message}"),
)
old_receipt.unlink(missing_ok=True)
except (OSError, UnicodeDecodeError) as exc:
raise SystemExit(f"error: cannot regenerate {target}: {exc}") from exc
target.parent.mkdir(parents=True, exist_ok=True)
if not target.exists() or target.read_text(encoding="utf-8") != wanted:
# newline="" so the seed is the carried asset byte for byte. The default
# translates each line ending to os.linesep, which on Windows writes a
# CRLF copy of an LF source; the guide is asserted equal to its asset.
target.write_text(wanted, encoding="utf-8", newline="")
receipt.write_text(hashlib.sha256(wanted.encode()).hexdigest() + "\n", encoding="ascii")
def seed_guide(partition: Path) -> None:
"""Regenerate the tool guide; an operator's own lines go in ``TOOLS.local.md``."""
"""Seed or refresh the tool guide while preserving in-place edits."""
_seed_prompt(partition / "TOOLS.md", GUIDE.read_text(encoding="utf-8"), _LEGACY_GUIDE_DIGESTS)
@ -294,22 +285,21 @@ def conduct_settings() -> dict:
def seed_soul(partition: Path) -> None:
"""Write the product identity as the partition's ``soul.md``.
"""Seed the product identity as the partition's ``soul.md``, once.
The workspace sync only creates what is missing, so a file written before
the engine starts is the one bootstrap reads on both hostings. Regenerated
on every launch; an operator's own lines go in ``soul.local.md``.
The workspace sync only creates what is missing, so a file seeded before
the engine starts is the one bootstrap reads on both hostings. Once is the
contract (``seed_once``): an operator's edit is never overwritten.
"""
_seed_prompt(partition / SOUL_RELATIVE, SOUL.read_text(encoding="utf-8"))
render.seed_once(partition / SOUL_RELATIVE, lambda: SOUL.read_text(encoding="utf-8"))
def seed_conduct(partition: Path, model: str | None) -> None:
"""Write the configured conduct, regenerated on every launch.
"""Seed the configured conduct, replacing only untouched product text.
Bootstrap reads agent.md after the product identity. Model-family,
discipline and product updates all reach it. Turning conduct off removes
the copy this product wrote instead of leaving it resident; an edited
copy is the operator's, and stays.
discipline and product updates refresh managed seeds; edited text stays.
Turning conduct off removes a managed seed instead of leaving it resident.
"""
settings = conduct_settings()
wanted = (
@ -547,20 +537,17 @@ def render_acp_config(source: Path, mode: str | None = None) -> Path:
def serve(args: argparse.Namespace) -> int:
"""Serve installed raven's ``raven acp`` on this process's stdio.
After rendering, the launcher serves ``python -m raven acp``
on this interpreter with inherited stdio. POSIX exec preserves the pid;
Windows waits for the child so the rendered config's owner stays alive.
No finally-unlink around it: the fork's own sweep
After rendering, this process execs ``python -m raven acp`` on its own
interpreter (the roster row's ``{PYTHON}`` resolves at install time to
one that imports raven), so the server inherits this pid, process group
and stdio untouched. No finally-unlink around it: the fork's own sweep
docstring concedes that promise is one a SIGKILLed process group never
keeps, and the pid-liveness sweep in render_config is the cleaner that
actually runs.
"""
rendered = render_acp_config(Path(args.config).resolve(), mode=getattr(args, "mode", None))
log(f"[run] serve {sys.executable} -m raven acp (config {rendered})")
argv = [sys.executable, "-m", "raven", "acp", "--config", str(rendered)]
if sys.platform == "win32":
raise SystemExit(subprocess.call(argv))
os.execv(sys.executable, argv)
log(f"[run] exec {sys.executable} -m raven acp (config {rendered})")
os.execv(sys.executable, [sys.executable, "-m", "raven", "acp", "--config", str(rendered)])
raise AssertionError("unreachable: execv does not return")

View File

@ -64,6 +64,9 @@
},
"plugins": {
"config": {
"everos-memory": {
"base_url": "http://localhost:18791"
},
"design-engine": {
"enabled": true,
"visualDomainSelector": {

View File

@ -12,7 +12,6 @@ import importlib.util
import json
import os
import shlex
import subprocess
import sys
from copy import deepcopy
from pathlib import Path
@ -125,6 +124,23 @@ def configure_image_generation(config: dict, host: dict) -> None:
render.inherit_media_image(config, host)
def inherit_everos_address(config: dict, host: dict) -> str | None:
"""Point this product's memory at the host's EverOS server, when the host names one.
The product config carries the stock port; a host that runs its own EverOS on
another port (every second instance on one machine does) would otherwise send
this lane's turns to whatever answers on the stock one.
"""
host_slice = ((host.get("plugins") or {}).get("config") or {}).get("everos-memory") or {}
base_url = host_slice.get("base_url") if isinstance(host_slice, dict) else None
if not isinstance(base_url, str) or not base_url.strip():
return None
own = config.setdefault("plugins", {}).setdefault("config", {}).setdefault("everos-memory", {})
if isinstance(own, dict):
own["base_url"] = base_url.strip()
return base_url.strip()
def render_config(source: Path) -> Path:
"""Write a copy of ``source`` with the secrets merged in, under the state root.
@ -142,6 +158,7 @@ def render_config(source: Path) -> Path:
web.setdefault("search", {})["images"] = True
config.setdefault("tools", {})["web"] = web
configure_image_generation(config, host)
inherit_everos_address(config, host)
defaults = config.setdefault("agents", {}).setdefault("defaults", {})
for key in ("model", "provider", "reasoningEffort"):
@ -253,13 +270,13 @@ def serve(args: argparse.Namespace) -> int:
The engine precheck comes before the render, the fork launcher's order: a
missing engine is the answer whoever installed this needs first, and no
file holding merged secrets should exist for a run that cannot start.
The launcher serves ``python -m raven acp`` on this
interpreter with inherited stdio: POSIX exec preserves the pid, while
Windows waits for the child to keep the config's owner alive.
No chdir: the fork engine resolved its corpus
After rendering, this process execs ``python -m raven acp`` on its own
interpreter (the roster row's ``{PYTHON}`` resolves at install time to
one that imports raven), so the server inherits this pid, process group
and stdio untouched. No chdir: the fork engine resolved its corpus
relative to its checkout, the wheel resolves it relative to its own
package. The pid-liveness sweep in render_config removes configurations
from exited launchers.
package. Nothing runs after the exec, so the pid-liveness sweep in
render_config is the only cleanup this hosting has.
"""
if importlib.util.find_spec(ENGINE_PACKAGE) is None:
raise SystemExit(
@ -269,11 +286,8 @@ def serve(args: argparse.Namespace) -> int:
)
rendered = render_config(Path(args.config).resolve())
log(f"[run] serve {sys.executable} -m raven acp (config {rendered})")
argv = [sys.executable, "-m", "raven", "acp", "--config", str(rendered)]
if sys.platform == "win32":
raise SystemExit(subprocess.call(argv))
os.execv(sys.executable, argv)
log(f"[run] exec {sys.executable} -m raven acp (config {rendered})")
os.execv(sys.executable, [sys.executable, "-m", "raven", "acp", "--config", str(rendered)])
raise AssertionError("unreachable: execv does not return")

View File

@ -71,6 +71,8 @@
"plugins": {
"config": {
"everos-memory": {
"mode": "http",
"base_url": "http://localhost:18791",
"user_id": "raven-oncall",
"agent_id": "raven-oncall",
"timeout_s": 360

View File

@ -106,48 +106,24 @@ def prepare_from_meta(meta: dict[str, Any], *, app_dir: str) -> None:
return
from oncall_flow.docker_backend import make_ssh_runner
from oncall_flow.runner import make_ssh_sync, prepare_remote
from oncall_flow.transport import logs_in_by_password, password_env, password_row, runner_from
# Same seam as backend_from_meta: a campaign that names a connection has no
# address of its own, and reading meta["host"] here raised KeyError on the
# first campaign an agent created for itself (2026-08-18).
meta = _resolve(meta)
key_path = os.path.expanduser(meta.get("key", "~/.ssh/id_rsa"))
host, port = meta["host"], int(meta.get("port", 22))
remote_dir = meta.get("remote_dir", "/root/raven-ops")
if logs_in_by_password(meta):
run = runner_from(meta)
row = password_row(meta)
sync = make_ssh_sync(row["host"], row["port"], "", user=row["user"], password=True, env=password_env(row))
else:
key_path = os.path.expanduser(meta.get("key", "~/.ssh/id_rsa"))
host, port = meta["host"], int(meta.get("port", 22))
run, sync = make_ssh_runner(host, port, key_path), make_ssh_sync(host, port, key_path)
prepare_remote(
run,
sync,
make_ssh_runner(host, port, key_path),
make_ssh_sync(host, port, key_path),
image=meta.get("image", "python:3.12-slim"),
app_local=os.path.abspath(app_dir) + "/",
app_remote=f"{remote_dir}/app",
)
def _runs_here_on_windows(meta: dict[str, Any]) -> bool:
# Locality is the transport seam's call, not this module's: a meta that
# names a connection the registry no longer has carries neither host nor
# transport, and must reach runner_from's refusal rather than run here.
if os.name != "nt":
return False
from oncall_flow.transport import LOCAL, transport_of
return transport_of(meta) == LOCAL
def _process_from_meta(meta: dict[str, Any]) -> JobBackend:
# The process launcher is a /bin/sh script; on a Windows machine raven runs
# on there is no sh to run it, and the job would sit in RUNNING forever. The
# agent declares 'process' because that is what a command on the owner's
# machine is -- the native launcher is how that runs here.
if _runs_here_on_windows(meta):
return _windows_from_meta(meta)
from oncall_flow.process_backend import process_from_meta
return process_from_meta(meta)
@ -159,27 +135,17 @@ def _openfoam_from_meta(meta: dict[str, Any]) -> JobBackend:
return openfoam_from_meta(meta)
def _windows_from_meta(meta: dict[str, Any]) -> JobBackend:
from oncall_flow.windows_backend import windows_from_meta
return windows_from_meta(meta)
def _docker_from_meta(meta: dict[str, Any]) -> JobBackend:
# Imported inside the factory so the module-level name stays patchable by
# tests that swap the SSH runner.
from oncall_flow.docker_backend import DockerExecutor, make_ssh_runner
from oncall_flow.transport import logs_in_by_password, runner_from
if logs_in_by_password(meta):
run = runner_from(meta)
else:
run = make_ssh_runner(
meta["host"],
int(meta.get("port", 22)),
os.path.expanduser(meta.get("key", "~/.ssh/id_rsa")),
user=str(meta.get("user") or "root"),
)
run = make_ssh_runner(
meta["host"],
int(meta.get("port", 22)),
os.path.expanduser(meta.get("key", "~/.ssh/id_rsa")),
user=str(meta.get("user") or "root"),
)
return DockerExecutor(
run,
image=meta.get("image", "python:3.12-slim"),
@ -190,4 +156,3 @@ def _docker_from_meta(meta: dict[str, Any]) -> JobBackend:
register_backend(DEFAULT_BACKEND, _docker_from_meta)
register_backend("process", _process_from_meta)
register_backend("openfoam", _openfoam_from_meta)
register_backend("windows", _windows_from_meta)

View File

@ -21,13 +21,10 @@ is. Three things follow:
budget is counted in, and how many jobs it will run at once, were being
restated in every campaign's meta and in the task statement itself.
A credential in a campaign is never the secret itself. A key is a path to one
the owner already has; a password is the one this computer keeps for the
connection (trunk's registry says ``auth: password``), found by the
connection's id. So a campaign's meta carries ``auth`` beside the address and
never the password, and every ssh this plugin starts for such a machine, its
rsync's included, logs in with trunk's options and trunk's askpass hook
(:mod:`oncall_flow.transport`).
Credentials stay a reference -- a path to a key the owner already has. Passwords
wait until there is a platform that needs them (2026-08-17, deliberate): storing
one means a keychain or a master password, and neither is worth building before
something asks for it.
Trunk's :mod:`raven.ops.connections` is the reader and
:mod:`raven.ops.connection_add` the writer; both are imported here rather than
@ -76,10 +73,8 @@ _SHOWN = SHOWN
# this one changes nothing about which machine the work calls for, and a field
# the agent can see is a field it can reason about wrongly -- here, by deciding
# it may skip naming the machine at all, which loses the record of where a
# command ran. ``auth`` goes with the address because a machine that takes a
# password has no key: a meta without it is logged in to with a key the machine
# was never given, and refused at its first ssh.
_TRANSPORT = ("host", "port", "user", "key", "transport", "auth")
# command ran.
_TRANSPORT = ("host", "port", "user", "key", "transport")
def get(conn_id: str) -> dict[str, Any] | None:

View File

@ -238,9 +238,7 @@ def make_ssh_runner(
"""Run a command over ssh, the way a job reaches its machine: whatever the
owner's ssh would use gets to work, an agent included. The probe that has
to prove WHICH key opened a session is trunk's
(``raven.ops.transport.make_ssh_runner(identities_only=True)``), and so is
the login to a machine that takes a password, which never comes here
(``oncall_flow.transport.runner_from``)."""
(``raven.ops.transport.make_ssh_runner(identities_only=True)``)."""
import subprocess
def run(cmd: str) -> tuple[int, str]:

View File

@ -10,12 +10,9 @@ everything about escalation that is a fact on disk rather than a tool face:
fixed setup, quiet hours and ask budget included); the counts come from
``interruptions.json`` (what has happened so far).
- **the question trail.** Which question the owner has not come back on is
read from the events and notes -- the same records a grader and a later
turn read anyway, so there is no second place to keep in sync. A question
carries an ``ask_id``; it is closed by the owner speaking (an answer to it,
or anything typed after it), by the loop settling it on the default it
named, or by the campaign withdrawing it. A note the loop writes about its
own work does not close it.
read from the events and closed by a later note -- the same records a
grader and a later turn read anyway, so there is no second place to keep
in sync.
Per the seam-one final ruling the fork's owner-window store machinery is not
rebuilt; the contract is enforced plugin-side, in front of whatever delivery
@ -73,7 +70,7 @@ def save_guard(cdir: Path, guard: ContractGuard) -> None:
tmp.replace(cdir / GUARD_FILE)
def append_note(campaign_dir: Path, note: str, *, source: str = "agent", ask_id: str = "") -> None:
def append_note(campaign_dir: Path, note: str, *, source: str = "agent") -> None:
"""Append one instruction to the campaign's notes.
``source`` says who it came from. A note the owner typed and a note the loop
@ -94,8 +91,6 @@ def append_note(campaign_dir: Path, note: str, *, source: str = "agent", ask_id:
pass
campaign_dir.mkdir(parents=True, exist_ok=True)
row = {"ts": datetime.now().isoformat(timespec="seconds"), "note": note, "source": source}
if ask_id:
row["ask_id"] = ask_id
if rnd is not None:
row["trials_at_the_time"] = rnd
with open(campaign_dir / NOTES_FILE, "a", encoding="utf-8") as f:
@ -108,64 +103,6 @@ def append_owner_answer(cdir: Path, answer: str) -> None:
append_note(cdir, answer[:2000], source="owner")
# The events that end a question, each naming the ask it ends.
_CLOSING_EVENTS = frozenset({"owner_answered", "ask_settled", "ask_withdrawn"})
def _rows(path: Path) -> list[dict[str, Any]]:
if not path.exists():
return []
rows = []
for line in path.read_text(encoding="utf-8").splitlines():
try:
row = json.loads(line)
except ValueError:
continue
if isinstance(row, dict):
rows.append(row)
return rows
def open_question(cdir: Path) -> dict[str, Any] | None:
"""The latest allowed question, while nobody has closed it; else None.
``{"ask_id", "question", "blocks_progress", "ts"}``. Only the latest ask
counts: a new question supersedes the one before it.
An ask with an id is closed by an event naming that id, or by the owner
speaking after it -- a note of theirs that answers no other question.
The loop's own notes do not close it: a progress note is not the owner's
answer, and taking it for one let the loop end its own question without
saying so. An ask recorded before ids existed keeps
the old reading, where any later note closes it.
"""
ask: dict[str, Any] | None = None
events = _rows(cdir / "events.jsonl")
for e in events:
if e.get("kind") == "ask_owner" and e.get("allowed") is not False:
ask = e
if ask is None:
return None
asked_at = str(ask.get("ts") or "")
ask_id = str(ask.get("ask_id") or "")
for e in events:
if ask_id and e.get("kind") in _CLOSING_EVENTS and e.get("ask_id") == ask_id:
return None
for n in _rows(cdir / NOTES_FILE):
if str(n.get("ts") or "") < asked_at:
continue
if not ask_id:
return None
if n.get("source") == "owner" and n.get("ask_id") in (None, "", ask_id):
return None
return {
"ask_id": ask_id,
"question": str(ask.get("question") or "a question"),
"blocks_progress": bool(ask.get("blocks_progress")),
"ts": asked_at,
}
def blocking_question_open(cdir: Path) -> str:
"""An unanswered question the loop itself marked as blocking, or "".
@ -173,36 +110,70 @@ def blocking_question_open(cdir: Path) -> str:
reading, not on ours -- it said nothing worth doing was left, so spending
compute contradicts it.
"""
q = open_question(cdir)
return q["question"] if q and q["blocks_progress"] else ""
path = cdir / "events.jsonl"
if not path.exists():
return ""
asked_at, question = "", ""
for line in path.read_text(encoding="utf-8").splitlines():
try:
e = json.loads(line)
except ValueError:
continue
if e.get("kind") == "ask_owner" and e.get("allowed") is not False:
if e.get("blocks_progress"):
asked_at, question = str(e.get("ts") or ""), str(e.get("question") or "a question")
else:
asked_at, question = "", ""
if not question:
return ""
notes = cdir / NOTES_FILE
if notes.exists():
for line in notes.read_text(encoding="utf-8").splitlines():
try:
n = json.loads(line)
except ValueError:
continue
if str(n.get("ts") or "") >= asked_at:
return ""
return question
def unanswered_question(cdir: Path) -> str:
"""The question the owner has not come back on, or "" (see ``open_question``)."""
q = open_question(cdir)
return q["question"] if q else ""
"""The question the owner has not come back on, or "".
def decided_without_owner(cdir: Path) -> list[dict[str, str]]:
"""Questions the loop settled on its default, with the owner never answering.
``[{"question", "reason"}]``, oldest first. A report reads these out, so a
decision the owner was asked for and never made is on the page rather than
only in the trail.
Read from the events, which is what a grader and a later turn read anyway; a
second place to keep this in sync is a second place for it to be wrong. An
owner's note closes it, and so does one the loop writes to say the question
no longer matters -- both are a statement on the record that the answer is no
longer being waited for.
"""
events = _rows(cdir / "events.jsonl")
asked = {
str(e.get("ask_id")): str(e.get("question") or "")
for e in events
if e.get("kind") == "ask_owner" and e.get("ask_id")
}
answered = {str(e.get("ask_id")) for e in events if e.get("kind") == "owner_answered" and e.get("ask_id")}
out = []
for e in events:
ask_id = str(e.get("ask_id") or "")
if e.get("kind") == "ask_settled" and ask_id in asked and ask_id not in answered:
out.append({"question": asked[ask_id], "reason": str(e.get("reason") or "")})
return out
path = cdir / "events.jsonl"
if not path.exists():
return ""
asked_at, question = "", ""
for line in path.read_text(encoding="utf-8").splitlines():
try:
e = json.loads(line)
except ValueError:
continue
if e.get("kind") == "ask_owner" and e.get("allowed") is not False:
asked_at, question = str(e.get("ts") or ""), str(e.get("question") or "a question")
if not question:
return ""
# Any note written after the question closes it: the owner's answer arrives
# as one (captured from the chat), and so does the loop saying the answer no
# longer matters. Timestamps rather than a flag, because notes.jsonl is where
# both already land.
notes = cdir / NOTES_FILE
if notes.exists():
for line in notes.read_text(encoding="utf-8").splitlines():
try:
n = json.loads(line)
except ValueError:
continue
if str(n.get("ts") or "") >= asked_at:
return ""
return question
def anything_running(cdir: Path) -> bool:
@ -222,9 +193,7 @@ __all__ = [
"append_note",
"append_owner_answer",
"blocking_question_open",
"decided_without_owner",
"load_guard",
"open_question",
"save_guard",
"unanswered_question",
]

View File

@ -52,7 +52,7 @@ from typing import TYPE_CHECKING, Any
from loguru import logger
from oncall_flow import wakes, watched
from oncall_flow.escalation import append_note, open_question
from oncall_flow.escalation import append_note, unanswered_question
from oncall_flow.instrument import is_concluded, log_event
from oncall_flow.tools import base as tools_base
from oncall_flow.window import campaign_for_window, task_fingerprint
@ -181,14 +181,14 @@ def _capture_owner_instruction(session_key: str, content: str, origin: str) -> d
cdir = home / campaign
if (cdir / "concluded.json").exists():
return {}
# Read BEFORE the note is written: the owner speaking after the ask
# closes the question (escalation.open_question), and the capture's own
# note is exactly that -- writing first would answer the question with
# itself and the wake would never be pulled forward.
question = open_question(cdir)
# Read BEFORE the note is written: any note at or after the ask closes
# the question (escalation.unanswered_question), and the capture's own
# note is exactly such a note -- writing first would answer the
# question with itself and the wake would never be pulled forward.
question_open = bool(unanswered_question(cdir))
append_note(cdir, text[:2000], source="owner")
out: dict[str, Any] = {"owner_note": campaign}
if question is not None:
if question_open:
# The owner is right here; the wake the loop scheduled while it
# waited is pulled to now, so the answer is read within seconds
# rather than after the rest of a twenty-minute timer (fork
@ -197,7 +197,7 @@ def _capture_owner_instruction(session_key: str, content: str, origin: str) -> d
scheduler = tools_base.granted_scheduler()
if scheduler is not None:
woke = wakes.pending_look(scheduler, campaign) is not None
log_event(cdir, "owner_answered", ask_id=question["ask_id"], via="chat", woke=woke)
log_event(cdir, "owner_answered", woke=woke)
if woke:
wakes.advance_look(scheduler, campaign)
out["owner_woke"] = woke

View File

@ -160,10 +160,7 @@ class Ledger:
os.replace(tmp, self._path)
# The rename itself needs flushing too, or a host crash can leave the
# directory entry unwritten and the previous ledger in place -- silently
# losing the last mutation instead of corrupting it. Windows cannot open
# a directory as a file (EACCES), and NTFS journals the rename itself.
if os.name == "nt":
return
# losing the last mutation instead of corrupting it.
dir_fd = os.open(self._path.parent, os.O_RDONLY)
try:
os.fsync(dir_fd)

View File

@ -44,42 +44,16 @@ def prepare_remote(
ensure_image(run, image)
def make_ssh_sync(
host: str,
port: int,
key: str,
*,
user: str = "root",
connect_timeout: int = 15,
password: bool = False,
env: dict[str, str] | None = None,
) -> SyncRunner:
"""rsync to ``user@host`` over ssh, logged in with ``key``.
With ``password`` it logs in with the password kept for the machine instead:
no key is offered and ``BatchMode``, which forbids asking at all, is off, so
ssh asks the askpass helper that ``env`` names
(``oncall_flow.transport.password_env``); ``key`` is then unread. rsync
starts ssh itself, so ``env`` is rsync's, and rsync is started the way
trunk starts a password connection's ssh, in a session of its own: an
OpenSSH older than 8.4 reads no ``SSH_ASKPASS_REQUIRE`` and asks the helper
only when there is no terminal to ask instead.
"""
def make_ssh_sync(host: str, port: int, key: str, *, user: str = "root", connect_timeout: int = 15) -> SyncRunner:
import subprocess
from raven.ops.transport import PASSWORD_AUTH
def sync(local: str, remote: str) -> tuple[int, str]:
if password:
ssh = f"ssh -p {port} -o ConnectTimeout={connect_timeout} -o StrictHostKeyChecking=accept-new "
ssh += " ".join(PASSWORD_AUTH)
else:
ssh = (
f"ssh -i {key} -p {port} -o BatchMode=yes "
f"-o ConnectTimeout={connect_timeout} -o StrictHostKeyChecking=accept-new"
)
ssh = (
f"ssh -i {key} -p {port} -o BatchMode=yes "
f"-o ConnectTimeout={connect_timeout} -o StrictHostKeyChecking=accept-new"
)
argv = ["rsync", "-az", "-e", ssh, local, f"{user}@{host}:{remote}"]
proc = subprocess.run(argv, capture_output=True, text=True, env=env, start_new_session=password)
proc = subprocess.run(argv, capture_output=True, text=True)
tail = f"\n{proc.stderr}" if proc.stderr and proc.returncode != 0 else ""
return proc.returncode, proc.stdout + tail

View File

@ -2034,8 +2034,7 @@ class OpsSubmitTool(_OpsScheduler):
"heard back -- so spending compute now contradicts it. Reading logs, reading "
"the case and writing down what you find cost nothing and are still open to "
"you. If you have since found something that makes the answer unnecessary, "
"record it with ops_note and settles_question=true, and submit again. Nothing "
"was submitted."
"record it with ops_note and submit again. Nothing was submitted."
)
if round >= 1:
@ -2837,45 +2836,17 @@ class OpsNoteTool(Tool):
"campaign": {"type": "string", "description": "Campaign name (as used in ops_submit)."},
"note": {"type": "string", "description": "The user's instruction, verbatim or faithfully summarized."},
"ledger": {"type": "string", "description": "Ledger path if known (locates the campaign dir)."},
"settles_question": {
"type": "boolean",
"description": "True when this note says you are going ahead without the owner's answer "
"to the open ops_ask_owner question -- on what you said you would do if unanswered, or "
"because the answer no longer changes anything. The question then stops holding back "
"ops_submit and ops_finish, and the report lists it as decided without the owner.",
},
},
"required": ["campaign", "note"],
}
async def execute(
self,
campaign: str,
note: str,
ledger: str | None = None,
settles_question: bool = False,
**kwargs: Any,
) -> str:
async def execute(self, campaign: str, note: str, ledger: str | None = None, **kwargs: Any) -> str:
cdir = _resolve_campaign_dir(campaign, ledger, getattr(self, "_session_key", ""), getattr(self, "_task", ""))
_append_note(cdir, note)
from oncall_flow.escalation import open_question
from oncall_flow.instrument import log_event
log_event(cdir, "note", note=note)
settled = ""
if settles_question:
question = open_question(cdir)
if question is None:
settled = "\nNo question to the owner is open, so there was nothing to settle."
elif not question["ask_id"]:
settled = "\nThe open question predates question ids; this note closes it as any note does."
else:
log_event(cdir, "ask_settled", ask_id=question["ask_id"], reason=note[:400])
settled = (
f"\nSettled without the owner: {question['question'][:200]}\n"
"Their answer, if it still comes, is written to the notes like any other."
)
return f"Noted for campaign '{campaign}': {note}\nThe next wake turn will see it via ops_tune_status.{settled}"
return f"Noted for campaign '{campaign}': {note}\nThe next wake turn will see it via ops_tune_status."
class OpsKillTool(Tool):

View File

@ -26,12 +26,9 @@ and there would be no enforcement at all.
Delivery is the one part the port reshapes (D4, and D3 for the conclusion):
the fork reached the owner by taking the host's message tool off the registry
and sending itself; the trunk hands a plugin no registry. An ALLOWED ask goes
out through the host's question grant (``direct_ask``) as a question of its
own -- over ACP an ``elicitation/create`` the host puts in front of the owner
-- and the tool returns without waiting for the answer. Where no grant is lent
it comes back as the exact text to send with the message tool, as does a filed
report. What the guard
and sending itself; the trunk hands a plugin no registry, so an ALLOWED ask --
and a filed report -- come back to the model as the exact text to send with
the message tool, which the product deliberately keeps enabled. What the guard
guarantees is unchanged and is the half that matters: a REFUSED ask never
reaches anyone, because the refusal happens in the tool. The guard mechanics
themselves (load/save, the question trail) live in ``oncall_flow.escalation``
@ -40,31 +37,18 @@ since part 2a; this file is the two faces over them.
from __future__ import annotations
import asyncio
import json
from datetime import datetime
from pathlib import Path
from typing import Any
from uuid import uuid4
from loguru import logger
from oncall_flow import wakes
from oncall_flow.escalation import (
anything_running as _anything_running,
)
from oncall_flow.escalation import (
append_note as _append_note,
)
from oncall_flow.escalation import (
decided_without_owner as _decided_without_owner,
)
from oncall_flow.escalation import (
load_guard as _load_guard,
)
from oncall_flow.escalation import (
open_question as _open_question,
)
from oncall_flow.escalation import (
save_guard as _save_guard,
)
@ -164,51 +148,16 @@ def _expected_baseline(cdir: Path) -> dict[str, Any]:
# private spellings so every call site below reads unchanged.
# The question each campaign has in front of its owner right now, by campaign
# directory: its ask id and the task awaiting the answer. One per campaign,
# because only the latest question is open (escalation.open_question).
_ASKING: dict[str, tuple[str, "asyncio.Task[None]"]] = {}
def withdraw_question(cdir: Path, reason: str) -> bool:
"""Take a question still in front of the owner back down; False when none is.
Recorded before the cancel, so the trail says why the form went away even
though the cancelled wait itself only sees that nobody answered.
"""
from oncall_flow.instrument import log_event
entry = _ASKING.pop(str(cdir), None)
if entry is None:
return False
ask_id, task = entry
if task.done():
return False
log_event(cdir, "ask_withdrawn", ask_id=ask_id, reason=reason)
task.cancel()
return True
def _owner_prompt(campaign: str, question: str, if_unanswered: str) -> str:
text = f"[ops campaign '{campaign}'] {question.strip()}"
if if_unanswered.strip():
text += f"\nIf there is no answer: {if_unanswered.strip()}"
return text
class OpsAskOwnerTool(_OpsScheduler):
"""Contact the job's owner, through the campaign's interruption contract.
An ALLOWED ask is put to the owner by the tool itself, through the host's
``direct_ask`` grant, on a task of its own: the call returns at once and the
loop carries on, which is the point of asking without stopping. Over ACP
the question reaches the host as ``elicitation/create`` -- not as a message
inside the turn, which the host gathers into the run's transcript where
nobody is reading. The answer, when one comes, is written to the notes as
the owner's and pulls the campaign's wake to now. A host that lends no
grant gets the model-mediated delivery (D4): the exact text to send with
the message tool. Either way the guard sits in front of the only door -- a
REFUSED ask returns nothing sendable and says nobody has seen it.
Delivery is model-mediated (D4): the trunk hands a plugin no tool registry,
so an ALLOWED ask comes back as the exact text to send with the message
tool -- the guard still sits in front of the only door, because a REFUSED
ask returns nothing sendable and says nobody has seen it. What the fork's
in-tool delivery additionally guaranteed -- that an allowed ask cannot be
silently dropped by the model -- is the optional messenger grant the
verdict lists (section two), not something this face can promise today.
The safety wake (a question outstanding, nothing running -> come back in
ten minutes) rides the scheduling base: the fork armed it through the cron
@ -219,14 +168,6 @@ class OpsAskOwnerTool(_OpsScheduler):
face left, and the broker's inline wait went with the registry grant.
"""
def __init__(self) -> None:
super().__init__()
self._direct_ask: Any = None
def bind_runtime(self, handles: Any) -> None:
super().bind_runtime(handles)
self._direct_ask = getattr(handles, "direct_ask", None)
@property
def name(self) -> str:
return "ops_ask_owner"
@ -249,12 +190,7 @@ class OpsAskOwnerTool(_OpsScheduler):
"one the answer could make wrong, which is usually anything that spends compute you "
"may not be authorised to spend. Blocking does NOT mean sitting still: reading logs, "
"reading the case and writing down what you found cost nothing and stay open to you. "
"What it stops is submitting more trials.\n"
"Ask about goals and standards, not about how to do the work. Write the question so "
"someone who does not know the method can answer it, in the owner's language: give "
"the choices in options, each saying what it costs, and say which you recommend. "
"if_unanswered says what you will do if nobody answers -- you carry on that way "
"rather than stop."
"What it stops is submitting more trials."
)
@property
@ -273,19 +209,9 @@ class OpsAskOwnerTool(_OpsScheduler):
"description": "True when nothing useful is left to do until this is answered; "
"false when another branch is worth doing under either answer.",
},
"options": {
"type": "array",
"items": {"type": "string"},
"description": "The choices the owner picks from, two or more, each with its cost. "
"The owner can always type an answer of their own instead.",
},
"if_unanswered": {
"type": "string",
"description": "What you will do if nobody answers.",
},
"ledger": {"type": "string", "description": "Ledger path if known (locates the campaign dir)."},
},
"required": ["campaign", "question", "expected_loss_minutes", "blocks_progress", "if_unanswered"],
"required": ["campaign", "question", "expected_loss_minutes", "blocks_progress"],
}
async def execute(
@ -295,8 +221,6 @@ class OpsAskOwnerTool(_OpsScheduler):
expected_loss_minutes: int,
blocks_progress: bool = False,
ledger: str | None = None,
options: list[str] | None = None,
if_unanswered: str = "",
**kwargs: Any,
) -> str:
from oncall_flow.instrument import log_event
@ -315,19 +239,14 @@ class OpsAskOwnerTool(_OpsScheduler):
decision = guard.check(at_ms=at_ms, expected_loss_ms=estimate)
_save_guard(cdir, guard)
ask_id = uuid4().hex[:8]
choices = [str(o).strip() for o in (options or []) if str(o).strip()]
log_event(
cdir,
"ask_owner",
ask_id=ask_id,
allowed=decision.allowed,
estimated=decision.estimated,
expected_loss_minutes=expected_loss_minutes,
reason=decision.reason,
question=question[:400],
options=choices,
if_unanswered=if_unanswered[:400],
blocks_progress=bool(blocks_progress),
)
# The returns say what happened to the message and what now follows from
@ -374,14 +293,17 @@ class OpsAskOwnerTool(_OpsScheduler):
f" ops_finish -- the work is done, or the answer can no longer change "
f"the result. Say in the report which decision was never made. "
f"If ops_finish refuses over the unanswered question, record with "
f"ops_note and settles_question=true why the answer no longer matters, "
f"then finish.\n"
f"ops_note why the answer no longer matters, then finish.\n"
f"(An answer left by some other route -- another window, ops_note from "
f"the CLI -- would show in ops_tune_status. Worth one look, not a wait.)"
),
eta_seconds=_ASK_WAKE_MINUTES * 60,
)
prompt = _owner_prompt(campaign, question, if_unanswered)
# Model-mediated delivery: the allowed text goes back to the model
# with the sending named as its next act. The trail records that the
# contract allowed the ask; whether it was then sent is the message
# tool's record, not this one's to invent.
log_event(cdir, "ask_owner_delivery", sent=False, detail="model-mediated (D4)")
note = "" if decision.estimated else " (recorded as an interruption you could not price)"
follows = (
"You called this blocking, so no more trials go out until it is answered. Looking "
@ -390,82 +312,16 @@ class OpsAskOwnerTool(_OpsScheduler):
else "You called this non-blocking, so carry on with whatever does not depend on the "
"answer -- that was the reading that made it non-blocking."
)
settle = (
"If you later carry on with what you said you would do without an answer, record that "
"with ops_note and settles_question=true."
)
if self._direct_ask is not None and self._session_key:
withdraw_question(cdir, "superseded by a new question")
task = asyncio.create_task(
self._await_answer(cdir, campaign, ask_id, prompt, choices, self._session_key),
name=f"oncall-ask:{campaign}:{ask_id}",
)
_ASKING[str(cdir)] = (ask_id, task)
log_event(cdir, "ask_owner_delivery", ask_id=ask_id, sent=True, detail="question")
return (
(woke + "\n" if woke else "")
+ f"ALLOWED by the campaign's contract{note}, and put to the owner as a question "
f"(ask {ask_id}). Do not send it again with the message tool. Their answer, if "
"one comes, is written to the campaign's notes and wakes you to read it. They may "
"take a long time to reply, or never reply.\n"
f"{follows} {settle} Do not close the campaign over silence -- that is the one "
"step that cannot be undone."
)
# Model-mediated delivery: the allowed text goes back to the model
# with the sending named as its next act. The trail records that the
# contract allowed the ask; whether it was then sent is the message
# tool's record, not this one's to invent.
log_event(cdir, "ask_owner_delivery", ask_id=ask_id, sent=False, detail="model-mediated (D4)")
return (
(woke + "\n" if woke else "")
+ f"ALLOWED by the campaign's contract{note}. Send exactly this to the owner with "
f"the message tool now, and nothing else:\n"
f" {prompt}\n"
f" [ops campaign '{campaign}'] {question}\n"
"They may take a long time to reply, or never reply.\n"
f"{follows} {settle} Do not close the campaign over silence -- that is the one "
"step that cannot be undone."
f"{follows} Do not close the campaign over silence -- that is the one step that "
"cannot be undone."
)
async def _await_answer(
self, cdir: Path, campaign: str, ask_id: str, prompt: str, choices: list[str], conversation_id: str
) -> None:
"""Wait out one question on its own task, and file what came back.
The host shows the question for its own while and then closes it; an
empty answer is that closing (or the owner dismissing it), and leaves
the question open -- the wake the ask armed is what follows up on it.
"""
from oncall_flow.instrument import log_event
try:
answer = await self._direct_ask(prompt, choices or None, conversation_id, None)
except Exception: # noqa: BLE001 -- a failed ask is recorded, never raised into a turn that has moved on
logger.warning("oncall-flow: asking the owner failed for {}", campaign, exc_info=True)
log_event(cdir, "ask_owner_unanswered", ask_id=ask_id, reason="the question could not be put")
return
finally:
current = _ASKING.get(str(cdir))
if current is not None and current[0] == ask_id:
_ASKING.pop(str(cdir), None)
task = asyncio.current_task()
if task is not None and task.cancelling():
return
if answer is None:
log_event(cdir, "ask_owner_unanswered", ask_id=ask_id, reason="no channel to the owner")
return
if not answer.strip():
log_event(cdir, "ask_owner_unanswered", ask_id=ask_id, reason="closed without an answer")
return
still_open = (_open_question(cdir) or {}).get("ask_id") == ask_id
_append_note(cdir, answer.strip()[:2000], source="owner", ask_id=ask_id)
if not still_open:
log_event(cdir, "owner_answered_late", ask_id=ask_id)
return
woke = wakes.pending_look(self._scheduler, campaign) is not None
log_event(cdir, "owner_answered", ask_id=ask_id, via="question", woke=woke)
if woke:
wakes.advance_look(self._scheduler, campaign)
def _finish_summary(
campaign: str, subject: str, outcome: str, observed: dict, baseline: dict | None, narrative: str, watch: str = ""
@ -770,9 +626,8 @@ class OpsFinishTool(_OpsScheduler):
"cleared, and what is left of the budget goes with them. Waiting costs nothing "
"by comparison: the campaign stays open and one sentence from the owner starts "
"it again.\n"
"If the answer no longer changes anything, say so with ops_note and "
"settles_question=true, then finish again. Otherwise keep going on whatever "
"does not depend on it, or wait."
"If the answer no longer changes anything, say so with ops_note and finish "
"again. Otherwise keep going on whatever does not depend on it, or wait."
)
seen = self._seen_keys(cdir)
@ -848,7 +703,6 @@ class OpsFinishTool(_OpsScheduler):
# is one cancel. The watcher's concluded sweep is the backstop for a
# host that lent no scheduler here.
removed = 1 if wakes.cancel_look(self._scheduler, campaign) else 0
withdraw_question(cdir, "campaign closed")
# Counted before the report is written, so the figure in the report and
# the figure in the trail are the same reading.
watch = _watch_kept(cdir)
@ -860,15 +714,8 @@ class OpsFinishTool(_OpsScheduler):
# no unverified content. Handed back AFTER the close, as the text to
# send with the message tool: the close never waits on a
# channel, which is the failure the fork's two-call shape kept hitting.
# Read out with the report, not left in the trail: the owner was asked
# these and never answered, so what was done instead is theirs to see.
undecided = "\n".join(
f"decided without the owner: {d['question'][:300]} -- {d['reason'][:300]}"
for d in _decided_without_owner(cdir)
)
shown = "\n".join(part for part in (watch, undecided) if part)
md = _write_report_md(cdir, campaign, subject, outcome, observed, baseline, narrative, shown)
summary = _finish_summary(campaign, subject, outcome, observed, baseline, narrative, shown)
md = _write_report_md(cdir, campaign, subject, outcome, observed, baseline, narrative, watch)
summary = _finish_summary(campaign, subject, outcome, observed, baseline, narrative, watch)
if md is not None:
summary += f"\n\nWritten to {md}"
log_event(cdir, "report_delivery", sent=False, detail="model-mediated (D3/D4)", dedupe_key=dedupe_key)

View File

@ -20,8 +20,6 @@ from typing import Any
from oncall_flow.backend import JobBackendError
from oncall_flow.docker_backend import CommandRunner
from raven.ops import transport as trunk
from raven.ops.connections import AUTH_PASSWORD, password_auth
LOCAL = "local"
SSH = "ssh"
@ -36,68 +34,6 @@ def transport_of(meta: dict[str, Any]) -> str:
return LOCAL if str(meta.get("transport") or SSH).strip().lower() == LOCAL else SSH
def logs_in_by_password(meta: dict[str, Any]) -> bool:
"""Whether this meta reaches its machine over ssh with the password kept for it (``auth: password``)."""
return transport_of(meta) == SSH and password_auth(meta)
def password_row(meta: dict[str, Any], *, what: str = "campaign") -> dict[str, Any]:
"""The registry row trunk logs in with, for a meta that logs in by password.
Its id is the meta's connection, because that is what the password is kept
under: a meta that names none has nothing to log in with, and is refused
saying so rather than sent to a machine that would refuse it. The address
and account are the registry's, never the meta's: a kept password goes
only to the machine it was registered for, and a meta -- which the model's
own tool calls write -- that carries another host, port or user for such a
connection is refused before any ssh is started. A key machine's meta may
still override those, since a key never leaves this computer.
"""
from oncall_flow.connections import get
named = str(meta.get("connection") or "").strip()
if not named:
raise JobBackendError(
f"this {what} logs in with a password and names no connection: a password is kept for a "
"registered machine, under its id, so the machine has to be named by its connection"
)
registered = get(named)
if registered is None:
raise JobBackendError(
f"this {what} names connection {named!r}, which is not in the connection registry; the password kept "
"for a machine goes only to the machine it was registered for"
)
host = str(registered.get("host") or "").strip()
port = int(registered.get("port") or 22)
user = str(registered.get("user") or "root")
for field, given, theirs in (
("host", str(meta.get("host") or "").strip().lower(), host.lower()),
("port", int(meta.get("port") or port), port),
("user", str(meta.get("user") or user), user),
):
if given and given != theirs:
raise JobBackendError(
f"this {what} names connection {named!r}, a machine logged in to with the password kept for it, but "
f"carries a {field} of its own that differs from the registered one: a kept password goes only to "
"the machine it was registered for -- leave host, port and user to the registry, or register that "
"other machine"
)
return {"id": named, "transport": SSH, "host": host, "port": port, "user": user, "auth": AUTH_PASSWORD}
def password_env(row: dict[str, Any]) -> dict[str, str]:
"""This process's environment plus what ssh needs to log in as ``row``, for a caller that starts ssh itself.
rsync is that caller: it runs ssh with the environment it was given. Trunk's
refusals -- no password kept here, a Windows computer -- arrive as a
:class:`JobBackendError` in trunk's words.
"""
try:
return {**os.environ, **trunk.ssh_env(row)}
except trunk.TransportError as exc:
raise JobBackendError(str(exc)) from None
# What ``timeout`` returns when it kills something, reused so a caller reads one
# code whichever way the cap was applied.
TIMED_OUT_RC = 124
@ -138,14 +74,6 @@ def runner_from(meta: dict[str, Any], *, what: str = "campaign", cap_seconds: fl
Measured 2026-08-17, and again 2026-08-18 when the failure reached the owner
as "your machine refused the connection" while that machine was answering in
under 200ms.
A machine that takes a password is logged in to by trunk's runner
(:func:`raven.ops.transport.runner_from`) rather than by a copy of its login
here: the options that make each password connection log in on its own, and
the askpass hook that hands ssh the password kept for the machine, are
trunk's, and a copy drifts the first time either changes. Trunk's refusals
-- no password kept here, a Windows computer -- arrive as a
:class:`JobBackendError` in trunk's words, before anything is started.
"""
if transport_of(meta) == LOCAL:
# The caller's cap, not this module's default. Looking at a machine is
@ -167,11 +95,6 @@ def runner_from(meta: dict[str, Any], *, what: str = "campaign", cap_seconds: fl
raise JobBackendError(
f"this {what} has no address to run on: connection {named!r} is not in the connection registry"
)
if logs_in_by_password(meta):
try:
return trunk.runner_from(password_row(meta, what=what), cap_seconds=cap_seconds)
except trunk.TransportError as exc:
raise JobBackendError(str(exc)) from None
return make_ssh_runner(
host,
int(meta.get("port") or 22),

View File

@ -2,7 +2,7 @@
"""Host-side launcher for the Raven-Oncall ACP server -- the B side.
The retired vendored Raven-Oncall carried a whole fork checkout; this
product carries none. It renders its config and serves the
product carries none. It renders its config and execs the
installed raven's own ``raven acp``, so every turn runs through the same
assembly door (build_runtime) as the host's TUI and gateway. The machinery
of rendering lives in the launcher library
@ -23,9 +23,9 @@ plugin's contributions, and the one-turn CLI adjudication path retires with
its only callers (the wake shell and the fork benchmarks). This launcher
serves ACP, nothing else.
After rendering, the launcher serves ``python -m raven acp`` on this
interpreter with inherited stdio. POSIX replaces the launcher; Windows
keeps it alive until the child exits, preserving the rendered config's owner.
After rendering, this process execs ``python -m raven acp`` on its own
interpreter (the row's ``{PYTHON}`` resolves at install time to one that
imports raven), so the server inherits this pid, process group and stdio.
stdout belongs to the protocol; every diagnostic goes to stderr.
"""
@ -34,7 +34,6 @@ from __future__ import annotations
import argparse
import json
import os
import subprocess
import sys
from pathlib import Path
@ -134,31 +133,18 @@ def connections_registry() -> Path:
def seed_guide(workspace: Path) -> None:
"""Write the workspace TOOLS.md with the on-call section already in place.
"""Seed the workspace TOOLS.md with the on-call section already in place.
The vendored twin appended TOOLS_ONCALL.md to the workspace TOOLS.md on
every sync while its gate was on; here the composed file is written before
the engine starts, so trunk's own template sync finds it existing and
leaves it alone. Regenerated on every launch (``write_generated``): the
template half changes with the installed raven, and an operator's own
lines go in ``TOOLS.local.md``. The composition mirrors the twin's append
-- template body, blank line, section -- so the model-visible text is
every sync while its gate was on; here the composed file is seeded once,
before first launch, so trunk's own template sync finds it existing and
leaves it alone. Once is the contract: the workspace copy is the live one
afterwards, and a product update must not silently overwrite what an
operator tuned in place. The composition mirrors the twin's append --
template body, blank line, section -- so the model-visible text is
byte-equal to what the fork produced on a fresh workspace.
A raven older than ``write_generated`` -- a home tree copied out by a newer
wheel serves an older checkout too -- seeds the guide once instead, and
says that it will not be refreshed.
"""
target = workspace / "TOOLS.md"
generate = getattr(render, "write_generated", None)
if generate is None:
render.seed_once(target, _guide_text)
log(f"[run] {target.name}: this raven predates regenerated prompts; seeded once, never refreshed")
return
try:
generate(target, _guide_text(), owner=PRODUCT, notify=lambda message: log(f"[run] {message}"))
except (OSError, UnicodeDecodeError) as exc:
raise SystemExit(f"error: cannot regenerate {target}: {exc}") from exc
render.seed_once(workspace / "TOOLS.md", _guide_text)
def _guide_text() -> str:
@ -257,11 +243,8 @@ def main() -> int:
rendered = render_config(Path(args.config).resolve())
os.environ.setdefault(CONNECTIONS_ENV, str(connections_registry()))
log(f"[run] serve {sys.executable} -m raven acp (config {rendered})")
argv = [sys.executable, "-m", "raven", "acp", "--config", str(rendered)]
if sys.platform == "win32":
raise SystemExit(subprocess.call(argv))
os.execv(sys.executable, argv)
log(f"[run] exec {sys.executable} -m raven acp (config {rendered})")
os.execv(sys.executable, [sys.executable, "-m", "raven", "acp", "--config", str(rendered)])
raise AssertionError("unreachable: execv does not return")

View File

@ -118,6 +118,9 @@
},
"plugins": {
"config": {
"everos-memory": {
"base_url": "http://localhost:18791"
},
"ppt-engine": {
"enabled": true,
"profile": "script_author",

View File

@ -30,7 +30,6 @@ import argparse
import importlib.util
import json
import os
import subprocess
import sys
from collections.abc import Collection
from pathlib import Path
@ -676,13 +675,13 @@ def serve(args: argparse.Namespace) -> int:
The engine precheck comes before the render, the fork launcher's order: a
missing engine is the answer whoever installed this needs first, and no
file holding merged secrets should exist for a run that cannot start.
The launcher serves ``python -m raven acp`` on this
interpreter with inherited stdio: POSIX exec preserves the pid, while
Windows waits for the child to keep the config's owner alive.
No chdir: the fork engine resolved its templates and
After rendering, this process execs ``python -m raven acp`` on its own
interpreter (the roster row's ``{PYTHON}`` resolves at install time to
one that imports raven), so the server inherits this pid, process group
and stdio untouched. No chdir: the fork engine resolved its templates and
skills relative to its checkout, the wheel resolves them relative to its
own package. The pid-liveness sweep in render_config removes configurations
from exited launchers.
own package. Nothing runs after the exec, so the pid-liveness sweep in
render_config is the only cleanup this hosting has.
"""
if importlib.util.find_spec(ENGINE_PACKAGE) is None:
raise SystemExit(
@ -692,11 +691,8 @@ def serve(args: argparse.Namespace) -> int:
)
rendered = render_config(Path(args.config).resolve())
log(f"[run] serve {sys.executable} -m raven acp (config {rendered})")
argv = [sys.executable, "-m", "raven", "acp", "--config", str(rendered)]
if sys.platform == "win32":
raise SystemExit(subprocess.call(argv))
os.execv(sys.executable, argv)
log(f"[run] exec {sys.executable} -m raven acp (config {rendered})")
os.execv(sys.executable, [sys.executable, "-m", "raven", "acp", "--config", str(rendered)])
raise AssertionError("unreachable: execv does not return")

View File

@ -24,6 +24,8 @@
"plugins": {
"config": {
"everos-memory": {
"mode": "http",
"base_url": "http://localhost:18791",
"user_id": "raven-research-ng",
"agent_id": "raven-research-ng",
"timeout_s": 360

View File

@ -29,7 +29,7 @@ from __future__ import annotations
from contextvars import ContextVar
from typing import Any
from raven.agent.tools.ask_user import AskUserTool, option_text
from raven.agent.tools.ask_user import AskUserTool
from raven.contracts.tool import ToolResult
# Returned when the model's call reaches execution, which happens whenever the
@ -71,7 +71,7 @@ def _schema_shaped(entry: Any) -> dict[str, Any]:
if (header := entry.get("header")) is not None:
shaped["header"] = str(header)
if isinstance(options := entry.get("options"), list):
shaped["options"] = [option_text(option) for option in options]
shaped["options"] = [str(option) for option in options]
if isinstance(pick := entry.get("recommended"), int) and not isinstance(pick, bool):
shaped["recommended"] = pick
return shaped

View File

@ -2,7 +2,7 @@
"""Host-side launcher for the Raven-Research ACP server -- the B side.
The retired vendored Raven-Research carried a whole fork checkout; this
product carries none. It renders its config and serves the
product carries none. It renders its config and execs the
installed raven's own ``raven acp``, so every turn runs through the same
assembly door (build_runtime) as the host's TUI and gateway. The machinery
of rendering lives in the launcher library
@ -23,14 +23,14 @@ architecture doing the job the fork used to:
* the home is answered by the path paper (``raven.home``), never re-derived;
* identity is a workspace asset -- raven reads
``agent_memory/profile/soul.md``, so ``soul.md`` beside this file is
rendered there on every launch -- not a config override;
copied there on first launch -- not a config override;
* modes are overlays: ``modes/*.json`` diffs become ``acp.modes`` entries a
client's picker shows, applied per session over the baseline flow config
instead of being compiled into the loop the way the fork did.
After rendering, the launcher serves ``python -m raven acp`` on this
interpreter with inherited stdio. POSIX replaces the launcher; Windows
keeps it alive until the child exits, preserving the rendered config's owner.
After rendering, this process execs ``python -m raven acp`` on its own
interpreter (the row's ``{PYTHON}`` resolves at install time to one that
imports raven), so the server inherits this pid, process group and stdio.
stdout belongs to the protocol; every diagnostic goes to stderr.
"""
@ -39,10 +39,9 @@ from __future__ import annotations
import argparse
import json
import os
import subprocess
import sys
from pathlib import Path
from typing import Callable, get_args
from typing import get_args
from raven.config import product_render as render
from raven.config.schema import WEB_VENDOR_ENV_VARS, WebFetchProvider, WebSearchProvider
@ -227,33 +226,19 @@ def require_search(config: dict) -> None:
)
def write_generated(target: Path, text: Callable[[], str]) -> None:
"""Regenerate one product-owned workspace file, or refuse to launch.
A raven older than ``write_generated`` -- a home tree copied out by a newer
wheel serves an older checkout too -- seeds the file once instead, and says
that it will not be refreshed.
"""
generate = getattr(render, "write_generated", None)
if generate is None:
render.seed_once(target, text)
log(f"[run] {target.name}: this raven predates regenerated prompts; seeded once, never refreshed")
return
try:
generate(target, text(), owner=PRODUCT, notify=lambda message: log(f"[run] {message}"))
except (OSError, UnicodeDecodeError) as exc:
raise SystemExit(f"error: cannot regenerate {target}: {exc}") from exc
def seed_identity(workspace: Path, flow_slice: dict) -> None:
"""Write the product identity into the workspace raven reads it from.
"""Seed the product identity into the workspace raven reads it from.
Rendered, not copied: the flow inserts its measured guidance into the
identity text the way the vendored twin did at prompt-build time, so the
workspace copy is the model-visible text. Regenerated on every launch
(``write_generated``): an operator's own lines go in ``soul.local.md``.
workspace copy is the model-visible text. Once (``seed_once``'s
contract): the workspace copy is the live one afterwards, and a product
update must not silently overwrite what an operator tuned in place.
"""
write_generated(workspace / "agent_memory" / "profile" / "soul.md", lambda: rendered_identity(flow_slice))
render.seed_once(
workspace / "agent_memory" / "profile" / "soul.md",
lambda: rendered_identity(flow_slice),
)
def _flow_prompts(flow_slice: dict):
@ -304,14 +289,16 @@ def rendered_identity(flow_slice: dict) -> str:
def seed_contract(workspace: Path, flow_slice: dict) -> None:
"""Write the contract beside the identity as ``agent.md``.
"""Write the contract beside the identity, once, as ``agent.md``.
Bootstrap renders both files in order: the identity from ``soul.md``, the
contract from ``agent.md`` -- the two halves of the segment the fork built
in code. Regenerated like the identity, so the contract the model reads
is the one this release's gates enforce.
in code. Same once-only rule as the identity.
"""
write_generated(workspace / "agent_memory" / "profile" / "agent.md", lambda: _flow_prompts(flow_slice)[1])
render.seed_once(
workspace / "agent_memory" / "profile" / "agent.md",
lambda: _flow_prompts(flow_slice)[1],
)
def iteration_cap(base_flow: dict, base_cap, overlay: dict):
@ -468,11 +455,8 @@ def main() -> int:
args = parser.parse_args()
rendered = render_config(Path(args.config).resolve())
log(f"[run] serve {sys.executable} -m raven acp (config {rendered})")
argv = [sys.executable, "-m", "raven", "acp", "--config", str(rendered)]
if sys.platform == "win32":
raise SystemExit(subprocess.call(argv))
os.execv(sys.executable, argv)
log(f"[run] exec {sys.executable} -m raven acp (config {rendered})")
os.execv(sys.executable, [sys.executable, "-m", "raven", "acp", "--config", str(rendered)])
raise AssertionError("unreachable: execv does not return")

View File

@ -132,10 +132,6 @@ start_nginx() {
log "the engine did not publish its browser session cookie"
return 1
fi
# The name has to be the one the engine reads, and it derives that from the
# request's Host port -- which nginx forwards without one, so the engine keeps
# its own PAGE_PORT. Spelled here as that same port; test_docker_runtime.py
# holds the two sides together.
RAVEN_AUTO_LOGIN_COOKIE="raven_session_${PAGE_PORT}=${cookie}; Path=/; Max-Age=2592000; HttpOnly; SameSite=Strict"
fi
export RAVEN_AUTO_LOGIN_COOKIE

View File

@ -15,12 +15,10 @@ server {
include /etc/nginx/proxy.conf;
# The engine accepts an Origin that names its own loopback port, or one that
# equals the request's Host on a loopback name (`_origin_ok` in
# raven/rpc/transports/ws.py). A browser reaching this container through a
# published port or a hostname sends neither -- behind nginx its Host is the
# hostname it published, and Origin names that host with the published port
# -- so rewriting Origin here is what makes the proxy work at all.
# The engine answers only to an Origin naming its own loopback port
# (`_origin_ok` in raven/rpc/transports/ws.py), which no browser reaching
# this container through a published port or a hostname can send. Rewriting
# it here is what makes the proxy work at all.
#
# What that gives up is a defence-in-depth layer, not the gate: the session
# cookie is SameSite=Strict, so a page on another site gets no cookie
@ -58,17 +56,6 @@ server {
proxy_pass http://127.0.0.1:${RAVEN_PAGE_PORT};
}
# The knowledge document reader: a page of the file as a picture
# (/knowledge/page), the region a chunk was cut from (/knowledge/crop),
# and the file itself (/knowledge/file). All three are engine-served and
# none of them is a file under the dist root, so without this block they
# fall through to `location /` and answer index.html -- a 200 of text/html
# where the page put an <img>, which a browser draws as a broken image
# rather than as an error anybody can read.
location /knowledge/ {
proxy_pass http://127.0.0.1:${RAVEN_PAGE_PORT};
}
location = /oauth/callback {
proxy_pass http://127.0.0.1:${RAVEN_PAGE_PORT};
}

View File

@ -7,42 +7,6 @@ tasks and stateful agent instances; they are different things.
Set up agents first with [Agent Integrations](agent-integrations.md). This page
covers using them, not installing their transports.
## What the host does and what it hands over
Raven itself works as your agent manager. It sorts a request into tasks, hands
each to the sub-agent that fits it, keeps track of every task until you accept
the result, and gathers what the agents report into one answer. A later message
about a task's work -- a correction, more work, or a question about why it was
done that way -- goes back to the instance that did the work, which still has
its context. Raven answers conversation, what it already knows and where your
tasks stand itself; anything to produce, however small, goes to the agent that
fits it, and to the built-in `Raven-General` agent only when none does. In a
conversation running on a Harness with workers, such as a Persona, Raven hands work
only to those workers; work none of them covers, it tells you about and asks how to
go on instead of doing it itself. On a turn where both dispatch tools are disabled,
Raven does the work itself.
## Work on a registered machine
An agent entry that names a `machine` runs on that registered machine, works
there and leaves its files there; entries without one run locally as before.
[Working on Registered Machines](machines.md) walks through registering the
machine, installing its node, configuring the entry, and what to expect when
the connection drops.
Remote ACP agents can use the MCP servers granted to their entry through the
Raven node. Server definitions and credentials stay on the host, as do tool
restrictions and sandbox rules. The node tells which task a bridge belongs to by
the process that opened it, and the host checks that task against the grant;
another task cannot select a grant by name.
The host serves each granted server from a Unix socket where the system supports
one. Otherwise, as on Windows, it listens on a port on `127.0.0.1` and opens the
server only for a connection that presents that endpoint's random token; the
token stays on the host. CLI agents on machines continue without lent MCP. A
host restart recovers the task result but does not restore its previous MCP
connections.
## Choose a collaboration shape
| Need | Use | Completion evidence |
@ -150,16 +114,6 @@ Parallel instances do not imply independent working copies. For concurrent
edits, give each agent explicit file ownership or separate worktrees. Raven-Code
reports shared-workspace conditions, but that is not a filesystem lock.
For coding work the host arranges this itself, following its built-in
`multi-agent-coding` skill. When coding tasks run side by side in one git
project, the host asks each coding agent to create a git worktree of its own, on
a branch named for its task, and to report the worktree's path and branch. The
changes stay on those branches until you ask for them to be merged, and the
worktrees stay until you ask for them to be removed. The same skill keeps one
instance per task, sends a follow-up on an unfinished task to that task's
instance, and moves a task to another coding agent when the first reports that
its quota is used up.
## Troubleshooting
| Symptom | Check |

View File

@ -5,32 +5,6 @@ Raven 同时提供委派任务与有状态 Agent 实例,两者不是一回事
先按[Agent 集成](agent-integrations.md)完成配置。本页介绍如何协作,不介绍传输安装。
## 宿主做什么、交出去什么 { #what-the-host-does-and-what-it-hands-over }
Raven 本身是你的 Agent 管家:把请求拆成任务、交给合适的子 Agent,跟踪每个任务
直到你认可结果,再把各 Agent 的汇报汇总成一个回答。针对某个任务工作的后续消息,
无论是修改、追加的工作,还是问为什么这样做,都会交回做这件事的实例,它仍保有
上下文。闲聊、Raven 已经知道的内容和任务进展,由 Raven 直接回答;任何需要产出的
工作,再小也交给最合适的 Agent,没有合适的 Agent 时才交给内置的 `Raven-General`。
如果对话运行在带 worker 的 Harness(例如 Persona)上,Raven 只把工作交给这些 worker;
没有 worker 负责的工作,它会告诉你并询问如何继续,而不是自己去做。
如果这一轮两个派发工具都被禁用,Raven 会自己完成工作。
## 在登记机器上工作 { #work-on-a-registered-machine }
配置了 `machine` 的 Agent 会在那台登记机器上运行,在那里工作,文件也留在那里;
没有配置的 Agent 仍像以前一样在本机运行。登记机器、安装节点、配置条目,以及断线时会
发生什么,见[在登记机器上工作](machines.md)。
远端 ACP Agent 可通过 Raven 节点使用配置授权给它的 MCP 服务器。服务器定义、
凭据、工具限制和沙箱规则仍在本机;节点按发起连接的进程判定每条流属于哪个任务,
本机再核对该任务与授权的对应关系,别的任务不能凭授权名称冒用。
系统支持 Unix socket 时,本机通过 Unix socket 提供每个授权的服务器;否则(例如
Windows)监听 `127.0.0.1` 上的端口,只为出示该端点随机令牌的连接打开服务器,
令牌只留在本机。机器上的 CLI Agent 暂不借用 MCP;本机重启后可以接回任务结果,
但不会恢复之前的 MCP 连接。
## 选择协作形式 { #choose-a-collaboration-shape }
| 需求 | 方式 | 完成证据 |
@ -116,12 +90,6 @@ tier,清除后恢复继承;清除模型覆盖则回到 Agent 自己的选择
并行实例不等于独立工作副本。并发修改时,应明确文件分工或提供独立 worktree。
Raven-Code 会报告共享工作目录情况,但这不是文件锁。
编程任务由宿主按内置的 `multi-agent-coding` skill 自行安排:同一个 git 项目里有多个编程任务并行时,
宿主让每个编程 Agent 自己创建独立的 worktree 和以任务命名的分支,并汇报 worktree 的路径和分支。
改动留在这些分支上,直到你要求合并;worktree 也会一直保留,直到你要求删除。
同一个 skill 还让每个任务对应一个实例:未完成任务的后续要求交给该任务的实例继续,
某个编程 Agent 报告额度用尽时,任务转交给另一个编程 Agent。
## 排障 { #troubleshooting }
| 现象 | 检查 |

View File

@ -180,71 +180,12 @@ your local installation has passed a live task.
| `hermes` | `hermes acp --accept-hooks` | Native authentication; the flag accepts previously unseen shell hooks |
| `openclaw` | `openclaw acp` | Its gateway and authentication; startup has a longer handshake allowance |
| `mirothinker` | OpenAI-compatible HTTP | Endpoint/model/key; preset opts out of stateful replay |
| `mirasim_<agent>` | Raven's own ACP adapter over the Mirasim host's protocol | Mirasim running on this machine, the agent installed inside it, and the `mirasim` CLI on the login shell's PATH (the check that offers the rows); session MCP withheld via `sessionMcp: false` |
GitHub Copilot, Qwen Code, CodeBuddy, Qoder, Grok Build, Kimi Code, and Pi also
have preset entries. Adapter versions and exact commands are maintained in
`raven/agent/subagent/presets.py` and `raven/agent/subagent/acp_registry_presets.py`.
Prefer the installed version's preset instead of reconstructing its flags.
The `mirasim_*` presets reach the agents Mirasim runs, one
row each: Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok Build, DSH,
Pi and ZCode CLI, named `Claude Code-Mirasim` and so on. Such a row is the agent on
the accounts and model routes set in Mirasim, which is why it can sit beside the
same agent's own preset. The adapter ships with Raven (`raven/acp/mirasim/`), so
nothing is downloaded; the `{PYTHON}` in its command becomes Raven's interpreter
when the row is written to config; if that interpreter is later gone, as after an
install moves, the row is pointed at the one serving Raven the next time the config
is read. Its model list is Mirasim's for that agent,
grouped under the agent's own name, `Mirasim` (the platform's quota) and `Own key`
(keys you added to Mirasim). Mirasim's platform also runs the own models of Claude
Code, Codex, Kimi Code and ZCode CLI, so for those four each such model is listed in
both of the first two groups: under the agent's name it runs on your own account,
under `Mirasim` on the platform's quota. Every turn names the route its model
runs on, so choosing the other one moves an existing conversation to that route
from its next turn. A session with no model chosen runs on Mirasim's default for
the agent, route included.
The adapter is one more client of the Mirasim host already running on the
machine -- the desktop app's, or the one Mirasim keeps on a machine it reaches
over SSH -- so it starts nothing of its own, and Raven's turns show in the Mirasim
app as they run. A turn streams: its thinking, text, tool calls, plan and the
files it delivers reach Raven as they happen, and the context it used is reported
when it ends. A cancel stops the turn. Text sent to a running turn is taken into
it for Claude Code, Codex, DSH, Pi and ZCode CLI. Images reach Claude Code
inline; another agent gets an image linked as a local file as that file's path,
and refuses one sent inline. Sessions can be listed -- this agent's
conversations in the given directory, including ones begun in Mirasim itself --
resumed, loaded with their whole history, closed and deleted. Deleting one
also deletes its Mirasim conversation; the agent's own transcript files stay
where it keeps them. A turn Mirasim starts on its own in a session Raven holds,
such as a background job's report, is forwarded to Raven too, and what it stops
to ask is left to the Mirasim app.
The adapter looks for the host in this order: the socket of the host Mirasim
keeps on a machine it reaches over SSH (`~/.mirasim-remote/run/server.sock`,
Linux and macOS only), then the desktop app on `127.0.0.1:4970` with the token
it writes to `run/local-4970.token` under Mirasim's state directory
(`MIRASIM_HOME`, else `~/.mirasim`). When the host listens anywhere else,
`RAVEN_MIRASIM_HOST` names it: `unix:<path>` for a socket (not on Windows, where
the desktop app's port is the way in), or a loopback port as `<port>`,
`127.0.0.1:<port>`, `localhost:<port>` or `[::1]:<port>`. On Linux and macOS
the adapter runs with the login shell's environment plus the row's own `env`,
not Raven's, so set the variable in your shell profile, or in the `env` of the
Mirasim rows that should use it; exported only in the shell that starts Raven,
it does not reach them. On Windows the adapter inherits Raven's own
environment, so setting it where Raven starts is enough.
What a turn Raven started stops to ask is put to Raven while the turn
waits: a tool approval as a permission request, and a
question -- Claude Code's `AskUserQuestion` when Mirasim's `askTool` setting is
on, or an MCP server's form -- as an elicitation, answered by you or by Raven's
question autofill. A client without forms has the question skipped and named in
the reply.
Question text, choices, replies and error details retain the sending agent's
content. Raven leaves redaction decisions to that agent, including when a
returned value matches a credential Raven itself holds.
Distinguish three claims when assessing compatibility:
- **Preset declared:** Raven has a configuration template.
@ -324,30 +265,6 @@ Keep credentials out of prompts and shared manifests. A2A credentials are
matched by origin, not by agent display name; its peer list is not an egress
firewall. Follow the [A2A guide](agent-protocols.md#call-a-remote-a2a-peer).
The prompt files a native agent keeps in its ACP home -- `soul.md` and
`agent.md` under `agent_memory/profile/`, and `TOOLS.md` -- are regenerated
from the release and its config on every launch, so editing them in place
does not last. Put your own lines in the sibling `*.local.md` file
(`agent_memory/profile/agent.local.md`, for example); the next launch appends
it after the product text. Copy in only what you still need: text from an
older release can contradict the current one. Save it as UTF-8; a file in
another encoding (an editor's legacy code page, GBK for example) stops the
launch, and the error names it. A file that was edited in place,
or that an older release left behind, is saved as `<name>.bak-<time>-<pid>`
before it is replaced, and the launcher log names the backup. The regenerated
file keeps the access rights the old one had. On Windows the backup is a hard
link to the file, so it keeps them too; on a volume that cannot hard-link, the
launch stops and names the file instead.
Backups are not deleted for you.
Raven-PPT differs in one respect: its deck engine can share a home with the
host, so it replaces only a file it can show it wrote. A `soul.md`, `agent.md`
or `TOOLS.md` edited before this release is left as it is, without a backup,
and its `*.local.md` is not applied. Move the lines you still need into the
`*.local.md` file and delete the edited one; the next turn writes it fresh. A
write the engine cannot make is logged and retried on the next turn instead
of stopping it.
## Security and troubleshooting
Outbound ACP automatically prefers an offered allow option. The parent's

View File

@ -156,53 +156,11 @@ Raven-Code 的 `code-flow` 提供的不只是身份 prompt。每个任务都应
| `hermes` | `hermes acp --accept-hooks` | 原生认证;该标志接受之前未见的 Shell hook |
| `openclaw` | `openclaw acp` | 自身网关、认证;启动使用较长握手等待 |
| `mirothinker` | OpenAI-compatible HTTP | 端点、模型、key;预设关闭有状态重放 |
| `mirasim_<agent>` | Raven 自带的 ACP 适配器,经 Mirasim host 的协议调用 | 本机正在运行 Mirasim,该 Agent 已在 Mirasim 中安装,且登录 shell 的 PATH 上有 `mirasim` CLI(列出这些行时据此判断);以 `sessionMcp: false` 阻止每会话 MCP 下发 |
GitHub Copilot、Qwen Code、CodeBuddy、Qoder、Grok Build、Kimi Code 和 Pi 也有预设。
适配器版本与精确命令维护在 `raven/agent/subagent/presets.py` 和
`raven/agent/subagent/acp_registry_presets.py`,优先使用已安装版本的预设,不要自行猜 flags。
`mirasim_*` 预设接入 Mirasim 运行的 Agent,每个 Agent 一行:
Claude Code、Codex、Kimi Code、Antigravity、Qwen Code、Grok Build、DSH、Pi 和 ZCode CLI,
名称形如 `Claude Code-Mirasim`。这样一行代表在 Mirasim 所设账号与模型路由上运行的该
Agent,因此可以与同一 Agent 自己的预设并存。适配器随 Raven 发布(`raven/acp/mirasim/`),
无需下载;命令中的 `{PYTHON}` 在写入配置时替换为 Raven 自己的解释器;若该解释器之后不复存在
(例如安装位置发生变化),下次读取配置时该行会改指当前运行 Raven 的解释器。可选模型取自
Mirasim 为该 Agent 提供的列表,分为三组:Agent 自己名下的模型、`Mirasim`(平台额度)
和 `Own key`(你在 Mirasim 中添加的 key)。Mirasim 平台也能运行 Claude Code、Codex、
Kimi Code 和 ZCode CLI 的自有模型,因此这四个 Agent 的这些模型在前两组各列一次:
选 Agent 名下的走你自己的账号,选 `Mirasim` 下的走平台额度。每一轮都会带上所选模型对应的
路由,因此已有对话的会话改选另一组后,从下一轮起即切到那条路由。未选模型的会话使用 Mirasim
为该 Agent 设定的默认模型和默认路由。
适配器是本机已在运行的 Mirasim host 的又一个客户端——桌面端的 host,或 Mirasim 经 SSH
接入的机器上的 host——自身不启动任何服务,Raven 发起的轮次在 Mirasim 应用中实时可见。
每轮以流式返回:思考、正文、工具调用、计划和交付的文件随发生随送达 Raven,结束时报告
所用上下文。取消会停止该轮。对 Claude Code、Codex、DSH、Pi 和 ZCode CLI,运行中追加的
文字会并入当前轮。图片以内联方式送达 Claude Code;其他 Agent 收到以本地文件链接给出的
图片时得到该文件的路径,内联图片则会被拒绝。会话可以列出(指定目录下该 Agent 的对话,
包括在 Mirasim 中开启的)、续接、连同全部历史载入、关闭和删除;删除时 Mirasim 中的对话
一并删除,Agent 自己保存的转录文件不会删除。Raven 持有的会话里由 Mirasim 自行发起的轮次
(例如后台任务的报告)也会转给 Raven,这类轮次中的提问留给 Mirasim 应用处理。
适配器按以下顺序查找 host:Mirasim 经 SSH 接入的机器上的 host socket
(`~/.mirasim-remote/run/server.sock`,仅限 Linux 和 macOS),然后是桌面端在
`127.0.0.1:4970` 上的 host,其 token 写在 Mirasim 状态目录(`MIRASIM_HOME`,否则为
`~/.mirasim`)下的 `run/local-4970.token`。若 host 监听在其他位置,用
`RAVEN_MIRASIM_HOST` 指明:socket 写作 `unix:<path>`(Windows 不支持,那里经桌面端的
端口接入),本机回环端口写作 `<port>`、`127.0.0.1:<port>`、`localhost:<port>` 或
`[::1]:<port>`。在 Linux 和 macOS 上,适配器使用的是登录 shell 的环境加上该行自己的
`env`,而不是 Raven 进程的环境,所以请把这个变量写进 shell 配置文件,或写进要使用它的
Mirasim 行的 `env`;只在启动 Raven 的 shell 里 export 是传不到适配器的。在 Windows 上,
适配器继承 Raven 自己的环境,在启动 Raven 的地方设置即可。
Raven 发起的轮次停下来等待的事项会在等待期间转交 Raven:工具审批以权限请求发出;提问——Mirasim
开启 `askTool` 设置时 Claude Code 的 `AskUserQuestion`,或 MCP 服务器的表单——以
elicitation 发出,由你或 Raven 的提问自动作答回答。不支持表单的客户端会跳过该提问,
并在回复中写明所问内容。
提问、选项、回复和错误详情保留发送方 Agent 的内容。脱敏由该 Agent 自行决定;
即使回传值与 Raven 自身持有的凭据相同,Raven 也不替换。
判断兼容性时区分三个结论:
- **已声明预设:** Raven 有配置模板。
@ -270,20 +228,6 @@ HTTP 后端没有本地文件访问,应传有界内容而不是宿主路径。
凭据不要放进 prompt 和共享 manifest。A2A 凭据按 origin 而不是显示名匹配;peer
列表不是出站防火墙,详见[A2A 指南](agent-protocols.md#call-a-remote-a2a-peer)。
原生 Agent 放在 ACP home 里的提示词文件(`agent_memory/profile/` 下的 `soul.md`、
`agent.md`,以及 `TOOLS.md`)每次启动都会按当前版本和配置重新生成,直接修改不会保留。
自己的内容请写进同目录的 `*.local.md`(例如 `agent_memory/profile/agent.local.md`),
下次启动时会接在产品文本之后。只放仍然需要的内容:旧版本的文本可能与当前规则冲突。
`*.local.md` 请保存为 UTF-8;其他编码(例如编辑器按 GBK 保存)会导致启动停止,报错会写明是哪个文件。
被直接修改过的文件、或旧版本留下的文件,会在覆盖前保存为 `<name>.bak-<时间>-<pid>`,launcher
日志会写明备份位置。重新生成的文件保留原文件的访问权限。在 Windows 上,备份是指向原文件的硬链接,
因此同样保留这些权限;如果所在的卷不支持硬链接,启动会停止并给出文件名。备份不会被自动删除。
Raven-PPT 有一点不同:它的 deck engine 可能和 host 共用同一个 home,所以只替换能证明是自己写的文件。
本版本之前被修改过的 `soul.md`、`agent.md` 或 `TOOLS.md` 会保持原样,不做备份,对应的 `*.local.md`
也不会生效。请把仍需要的内容移到 `*.local.md`,再删除修改过的文件,下一轮会重新写入。engine 写入失败时
会记录日志并在下一轮重试,不会让本轮停止。
## 安全与排障 { #security-and-troubleshooting }
出站 ACP 自动优先选择对方提供的 allow 选项。父级 permission mode 不为每个外部

View File

@ -8,6 +8,7 @@ lists its subcommands and options.
| `raven` or `raven tui` | Launch the terminal UI |
| `raven web` | Open the WebUI and keep Raven running in the background |
| `raven web --stop` | Stop the background WebUI service |
| `raven web --dev` | Open the WebUI with the developer-only trajectory view enabled (also `raven --dev`) |
| `raven agent -m "..."` | Run a single task from the command line |
| `raven onboard` | Set up model providers, sandboxing, messaging channels, memory, web tool credentials, subagents, and data import |
| `raven status` | Show configuration and runtime status |
@ -22,9 +23,9 @@ lists its subcommands and options.
| `raven playbook` | Create, validate, manage, and run reusable agent workflows |
| `raven provider` | Configure providers and endpoints, authenticate, test connectivity, and select the active model |
| `raven channels` | List, configure, authenticate, enable, or disable messaging channels |
| `raven gateway` | Start the gateway and its configured services |
| `raven gateway` | Start the gateway and its configured services; `--dev` enables the trajectory view in the page it hosts |
| `raven gateway status` / `raven gateway reload` / `raven gateway stop` | Inspect, reload configuration, or gracefully stop a running gateway |
| `raven serve` | Start the WebSocket RPC service and serve the WebUI when its build is available |
| `raven serve` | Start the WebSocket RPC service and serve the WebUI when its build is available; `--dev` enables the trajectory view |
| `raven skill` | Browse SkillForge skills, inspect their contents, block or unblock skills, and remove installed bundles |
| `raven plugins` | List installed plugins and the active memory backend |
| `raven plugin auth <server>` | Authenticate or refresh OAuth access for an MCP server |
@ -36,7 +37,7 @@ lists its subcommands and options.
| `raven sandbox` | List sandbox VMs, run commands, or open a shell; requires `tools.sandbox.debug.enabled=true` |
| `raven tracing` | Open the local trace dashboard |
| `raven tracing compact` | Consolidate duplicate trace artifacts to free disk space |
| `raven trajectory` | Save, replay, redact, label, and preserve execution trajectories for debugging, and run the bug report receiver |
| `raven trajectory` | Save, replay, redact, label, and preserve execution trajectories for debugging |
Run `raven --help` for the command list, or `raven <command> --help` for details
on a specific command. From a source checkout, prefix commands with `uv run`.

View File

@ -7,6 +7,7 @@
| `raven` 或 `raven tui` | 启动终端界面 |
| `raven web` | 打开 WebUI,并让 Raven 在后台运行 |
| `raven web --stop` | 停止 WebUI 后台服务 |
| `raven web --dev` | 打开 WebUI 并启用仅供开发者使用的轨迹视图(也可用 `raven --dev`) |
| `raven agent -m "..."` | 从命令行执行单次任务 |
| `raven onboard` | 配置模型服务商、沙箱、消息渠道、记忆、网络工具凭据、子 Agent 和数据导入 |
| `raven status` | 查看配置与运行状态 |
@ -21,9 +22,9 @@
| `raven playbook` | 创建、校验、管理和运行可复用的 Agent 工作流 |
| `raven provider` | 配置模型服务商与端点、完成认证、测试连通性并选择当前模型 |
| `raven channels` | 列出、配置、认证、启用或禁用消息渠道 |
| `raven gateway` | 启动网关及已配置的服务 |
| `raven gateway` | 启动网关及已配置的服务;`--dev` 在其托管的页面中启用轨迹视图 |
| `raven gateway status` / `raven gateway reload` / `raven gateway stop` | 查看网关状态、重新加载配置,或有序停止网关 |
| `raven serve` | 启动 WebSocket RPC 服务,并在 WebUI 构建产物可用时提供页面 |
| `raven serve` | 启动 WebSocket RPC 服务,并在 WebUI 构建产物可用时提供页面;`--dev` 启用轨迹视图 |
| `raven skill` | 浏览 SkillForge 技能、查看内容、屏蔽或解除屏蔽技能,以及移除已安装的技能包 |
| `raven plugins` | 列出已安装的插件和当前记忆后端 |
| `raven plugin auth <server>` | 为 MCP 服务完成认证或刷新 OAuth 授权 |
@ -35,7 +36,7 @@
| `raven sandbox` | 列出沙箱虚拟机、执行命令或打开 Shell;需要设置 `tools.sandbox.debug.enabled=true` |
| `raven tracing` | 打开本地追踪面板 |
| `raven tracing compact` | 合并重复的追踪产物,回收磁盘空间 |
| `raven trajectory` | 保存、回放、脱敏、标注和保留执行轨迹,用于调试;也运行问题报告接收器 |
| `raven trajectory` | 保存、回放、脱敏、标注和保留执行轨迹,用于调试 |
运行 `raven --help` 查看命令列表,或运行 `raven <command> --help` 查看指定命令的详细说明。
从源码检出运行时,在命令前加 `uv run`。

View File

@ -1,530 +0,0 @@
# Working on registered machines
Run a sub-agent on another computer -- a GPU box, a lab workstation, a
server in the office -- from the Raven on your own. You register the machine
once, put Raven's node on it, and name that machine in an agent entry. From
then on the agent is dispatched there, works in its own directory there, and
its files stay there; your conversation reads them by address and fetches one
when you ask. If the connection drops, or you stop Raven, the agent keeps
working and the result is picked up when you are back.
This page is the full walk-through. [Working with Sub-agents](agent-collaboration.md)
covers delegating in general; [Agent Integrations](agent-integrations.md) covers
installing the agents themselves.
## What you need
- A machine reached over ssh, as the user the agent will run as: with a key,
or with a password that Raven keeps on this computer and hands to ssh on
every connection (see the registration section below).
- Linux or macOS on that machine, with a POSIX shell for that user. The node
uses unix sockets and process groups, so a Windows machine cannot be a
destination. (Raven itself may run on Windows; see
[Limits and defaults](#limits-and-defaults).)
- `uv` on the machine (on the PATH, or where its installer puts it), **or**
`curl` or `wget` so the installer can fetch one. The installer builds the
node with `uv` and stops without it, whatever Python the machine has. A
Python 3.12 or newer there is welcome but not required: with one, the node's
virtualenv is made from it; without one, `uv` brings a Python 3.12 of its
own, which takes more space.
- The agent you want to run installed and signed in on that machine, for that
user: an ACP agent such as Claude Code, Codex or Qwen Code; a CLI agent; or an
OpenAI-compatible endpoint that answers on that machine's network.
## 1. Register the machine
```bash
raven ops connection add
```
The command asks one thing at a time: what you call the machine, whether it is
reached over ssh or is this computer, a short id for it, then the address,
port, username and private-key path. It connects before writing anything;
a machine that does not answer is not recorded. What the machine can say about
itself -- cores, memory, GPUs -- is read off it, not typed. The last questions
are for on-call jobs: what is installed on it (any short answer), the budget
unit and jobs at once (Enter takes the defaults), and the directories that hold
your work, which may be left blank. Directories you do list are also where a
file can be read without a question later (see [section 6](#6-read-edit-and-fetch-by-address)).
For a script, pass every answer as a flag:
```bash
raven ops connection add --id gpu1 --name "GPU box 1" \
--host <address> --port 22 --user alice --key ~/.ssh/id_ed25519 \
--non-interactive
```
What gets recorded, and where:
- The row lands in `connections.json`: the file `RAVEN_CONNECTIONS` points at,
else the one beside your config, else the one in the Raven home (`~/.raven`).
[Oncall](oncall.md#prepare-the-agent-and-machine) describes the registry in
more detail.
- The **path** of the private key is stored, never the key itself.
- A machine you can only reach with a password is registered from the Agent
Hub with **Login: Password**, or with `raven ops connection add
--non-interactive --auth password --password-stdin --id <id> --name <name>
--host <address> --port 22 --user <user>` (the password on the first line of
stdin, never on the command line; `--password-stdin` is read before the first
question, so it works with or without `--non-interactive`). The password must
be at least six characters and is kept on this computer, under
`~/.raven/keys/<id>.password`, readable by your account alone (mode 0600),
and handed to ssh on every connection through OpenSSH's askpass hook: it is
in no registry row, log or answer, and never on a command line. Each of
those connections logs in on its own (connection sharing from your ssh
config, `ControlMaster`, is turned off for them), so a registration proves
the password it keeps and a password changed on the machine is noticed at
the next connection. It is started with no controlling terminal, so an
OpenSSH older than 8.4 -- which only uses askpass when it cannot open a
terminal -- still reaches the helper instead of prompting. A jump host does
not: `ProxyJump` and `ProxyCommand` are off for password connections, since
the jump's own ssh would be handed this machine's password; a machine
reached only through one has to be registered with a key. The helper
answers one prompt: ssh's own, for the password of the registered account
at the registered address (`user@host`). Another account's prompt, a
second factor's (a verification code, a passcode) and a one-time
password's get no answer, so a machine whose login also asks for one is
registered with a key as well. The row carries `auth: password` and no key
path. `raven ops connection doctor` counts the row usable, and Oncall
campaigns run on it too, logging in the same way at the registered address
alone: a campaign cannot point such a connection at another host, port or
user. The machine's sshd has to accept
password logins (`PasswordAuthentication yes`); one that does not refuses
every connection, and the refusal says so. A password the machine refuses at
registration is not kept. A failed or cancelled registration preserves the
password kept by another registration of the same machine, even if that
registration is still connecting and uses the same password.
When the machine's password changes, remove the
machine and register it again (a registration under an id in use is
refused). Not available when this computer is Windows, whose OpenSSH cannot
run the POSIX script that hands ssh the password. Such a machine gets no
`Host <id>` alias in `~/.ssh/config`: `scp` and `rsync` from a terminal ask
for the password, and an agent reads and writes its files through Raven's
own file tools. Removing the machine deletes the password kept here
([section 8](#8-remove-a-machine)).
- The machine's host key is accepted on the first connection and kept in
`~/.ssh/known_hosts`. A machine that later presents a different key is
refused until you check it yourself. With a password that first connection
carries the password, so on a network you do not trust, connect once from a
terminal first (`ssh user@host` shows the fingerprint to confirm) and
register after, or register with a key.
- For a machine registered with a key, a managed `Host <id>` block is written
to `~/.ssh/config`, so `scp` and `rsync` on this computer can address the
machine by its id.
`raven ops connection list` shows the machines. `raven ops connection doctor`
lists what is wrong with each entry, blocking or advisory, and exits non-zero
only when no entry is usable: a broken entry beside a usable one still exits
zero, so read its output rather than its exit code.
### From the Agent Hub
The same registration without a terminal: the Agent Hub's **Machines** tab,
beside **Agents** and **Channels** at the top of the hub,
lists the registered machines, and **Register a machine** opens a form for
the name, id, address, port, user name and private-key path, plus the work
directories. The page reaches the machine once before writing anything, the
way the command does, and a machine that does not answer is not recorded;
the refusal says what kind it was (unreachable, login refused, changed host
key, no answer in time) and what to do about it. What the page shows
afterwards is what the machine is -- its name, id, link and node -- never its
address, user or key path: those travel once, in the form, and are not read
back. The private-key field starts filled with a key this computer has: ssh's
own identities first (`~/.ssh/id_rsa` before `id_ed25519`, the order ssh tries them), then any pair you
named, with the others to pick from; when none is found the form says so, and
*Password* is the other way in.
## 2. Install the node
```bash
raven ops connection install-node gpu1
```
The node is Raven's own code in a small virtualenv on the machine. It is what
starts agents there and answers file calls. The command looks at the machine
once, prints what it would do, and asks before doing it (`--yes` skips the
question). A successful run ends with two lines:
```text
Installed the Raven node <version>-<digest> in /home/alice/.raven-node (62 MB).
The node answers: Python 3.12.3, code <digest>.
```
What lands on the machine:
| Item | Where |
| --- | --- |
| The node | `<node_dir>/<version>-<digest>/`, with `node_dir` from the registry row, `~/.raven-node` by default |
| Its runtime state | `run/` (the socket), `tasks/<task>/` (each agent's record, owner-only) and `log/` under `node_dir` |
| `uv`, when the machine had none, or when its own is older than 0.4.23 while pip there is configured with an index (such a `uv` ignores the index) | `<node_dir>/.uv`, version 0.13.0, fetched with the machine's `curl` or `wget`; the next install uses it |
| A Python 3.12, when the machine had none | beside the node, kept by `uv` |
Nothing else changes: no system package, no shell rc file, no environment
variable, no service, no open port. The node's packages come from the index
pip is configured with on the machine, else from PyPI. Space needed, as the
installer checks it:
| Part | About |
| --- | --- |
| The node | 60 MB |
| A Python 3.12 brought by `uv` | 80 MB more |
| `uv` itself, when fetched | 25 MB more |
`--dir <path>` keeps the nodes somewhere other than `~/.raven-node`; the path
is recorded in the registry row, so later commands find it. A machine that
already has this Raven's node is left as it is. The node's name is recorded
on the row as well (`node_install`), which is how the Agent Hub says a machine
has the node before any link to it is up.
### Installing from the Agent Hub
**Install node** on a machine's card, or in its sheet, runs the same install
in the background: the card says *Installing the node* until it ends, and the
sheet keeps how it ended. The sheet's *Install into* field is the command's
`--dir`. A machine whose node is another Raven's shows *needs updating* and
offers **Update node**.
Once the node is up, the card lists the agent entries on the machine,
connected or switched off (*No agent connected here yet* until there is one;
the state line, *Link up, no agent running*, is about this moment), and the sheet says the next
step and offers **Connect an agent on this machine**: pick the agent, give
its working directory there, and **Connect** adds `<preset>@<machine id>`
(`codex@gpu1`) the way section 4's `subagents.add` does, one real prompt run
on the machine first, and refused the same way when the machine already has
that preset. The list has every preset a machine's node can start, including
one already connected on this computer -- that is a second entry, on the
machine, not a conflict. An entry on the machine that is switched off is shown
too, marked *switched off*, on the card and in the form: it still holds the
machine, so the form lists each such entry as a choice of its own, by name,
and the button reads **Reconnect**, which switches that entry back on (with
the same proof prompt) rather than adding another. An agent's own sheet connects it onto a
machine too (*Runs on*), which lists the registered machines, lets only those
with this Raven's node be picked (the others say why), and takes the working
directory there; an agent that is not installed on this computer offers it
as well, since what matters is that it is installed and signed in on the
machine. Only a preset not yet on the roster offers it: a row that already
exists, switched off, connects by its own button, which takes no machine.
While an add on a machine is still running -- its proof prompt takes up to a
minute -- the machine's connect form, opened again, greys that preset rather
than adding it a second time.
**Upgrading.** The node runs exactly the code of the Raven that installed it,
checked by a digest on every connection. After you update Raven on this
computer, run `install-node` again: the new node lands beside the old one, and
`--prune` removes the nodes of other versions from the directory (the cached
`uv` and Python stay). Until you do, a dispatch to that machine fails with
*runs different code from this Raven; update it with `raven ops connection
install-node gpu1`*.
**The daemon.** Nothing is started by the install. The first time Raven uses
the machine, its ssh session starts the node's daemon, which outlives the
session; the daemon leaves on its own after 10 minutes with no connection and
no agent running. After the machine reboots, the next use starts it again.
## 3. Name the machine in an agent entry
Take the entry you already have for the agent under `subagents.agents` in
your config -- the one the sub-agent page or `raven_config` added -- and add
`machine` to it. The value is the registry id. `remoteCwd` is where the agent works on that machine; it
defaults to `~/raven-work`, with `~` being the registered user's home there.
Each instance or task works in its own directory under it,
`<remoteCwd>/<instance or task id>`.
### ACP agents
```json
{
"name": "Claude Code on gpu1",
"preset": "claude_code",
"kind": "acp",
"enabled": true,
"command": "<the agent's ACP command, as in a local entry>",
"machine": "gpu1",
"remoteCwd": "/data/alice/projects"
}
```
The node starts the entry's `command` on the machine, in the registered user's
login environment (the profile and rc chain of a `bash` or `zsh` login; a user
of another shell gets the environment ssh started the node with). The entry's
`env` is laid over it and reaches the agent over the link, never on a command
line. `cwd` names a directory on this computer and is not read for an entry on
a machine.
### CLI agents
```json
{
"name": "my-cli on gpu1",
"kind": "cli",
"enabled": true,
"command": "my-agent --prompt-file {prompt_file}",
"machine": "gpu1"
}
```
The same command runs on the machine, split by that machine's POSIX shell
rules. The prompt reaches it the three ways it does locally: `{prompt}` as one
argument, `{prompt_file}` as a file written into the run's directory there,
or on stdin, which the node closes after the prompt. Output lines come back as
they are written, blank lines included. A cancel or a timeout ends the whole
process tree on the machine, background commands included.
### OpenAI-compatible endpoints
```json
{
"name": "vLLM on gpu1",
"kind": "openai",
"enabled": true,
"baseUrl": "http://127.0.0.1:8000/v1",
"model": "my-model",
"machine": "gpu1"
}
```
For an endpoint that answers only on the machine, or only on its network. Each
turn opens an ssh tunnel to the machine, sends the request through it to
`baseUrl` as the machine resolves it, and closes the tunnel. `baseUrl` has to
be `http`: the tunnel ends on this computer's loopback, which an `https`
certificate would not name. There is no `remoteCwd` for this kind -- an
endpoint has no working directory -- and one written here is dropped with a
warning.
### Built-in agents
A built-in agent is Raven's own loop in this process, where its model keys and
tools are. It has no process to start elsewhere: a `machine` on a built-in row
is dropped with a warning at load, and the row runs here.
## 4. Or add one from a conversation
Ask Raven in a chat, for example *"add the Codex preset on machine gpu1"*. The
main agent lists the usable registered machines and calls `subagents.add`
with the preset, the machine and, for an ACP or CLI preset, an optional
`remote_cwd`:
```json
{"preset": "codex", "machine": "gpu1", "remote_cwd": "/data/alice/projects"}
```
The entry is named `<preset>@<machine>` unless you give a name, so one preset
can be added once per machine: a preset the machine already has is refused
under the default name, and the refusal names the entry it has (connected or
switched off). A second entry of one agent on one machine -- two working
directories, say -- is added by giving it a name of its own. Before anything
is stored, the add is proved
the way a local add is: one real test prompt, run on that machine, through
that agent -- so the agent has to be installed and signed in there already.
The add is refused up front when the preset is a built-in agent, when an
OpenAI preset is given a `remote_cwd`, or when the machine's entry cannot be
used.
On the page, the same add is the machine sheet's **Connect an agent on this
machine**, or *Runs on* in the agent's own sheet.
## 5. What happens when you dispatch
Dispatch as usual: ask the host to delegate, or chat with the agent's instance.
Three things differ from a local agent.
**Attachments are named, not copied.** A file that comes with the task is
named to the agent by its address on this computer, with a note that nothing
was copied. The agent uses it where the machine can read it -- the same path
on a disk both mount, a copy already there -- or says in its reply that it
could not be found on the machine, and goes on.
**MCP servers are not lent.** The host's MCP servers are reached through a
socket on this computer, which an agent elsewhere cannot open. A granted
server is noted in the reply as not lent. Lending them across the link is
coming, in pull request #947.
**Its files stay on the machine.** Nothing is brought back when the turn
ends. The reply closes with a line that says where it worked:
```text
[raven] Ran on machine 'GPU box 1' (gpu1), in alice@203.0.113.7:/data/alice/projects/task-3f9a;
the files it wrote are there, not on this computer -- read_file, list_dir, find,
grep, write_file and edit_file take that path as it is, and deliver_files fetches one by it.
```
The record of the dispatch names the directory the same way: *Working
directory: on machine 'gpu1', /data/alice/projects/task-3f9a (made there when
the run started)*.
### How a path on a machine is written
A path on a machine is written the way `scp` writes one, with the user,
address and port from the registry. That is the one spelling a reply, a
record or a tool result uses, and the one the tools read back:
| Form | Example | When |
| --- | --- | --- |
| `user@host:/abs/path` | `alice@203.0.113.7:/data/alice/projects/task-3f9a/report.md` | port 22 |
| `scp://user@host:port//abs/path` | `scp://alice@203.0.113.7:2222//data/alice/projects/task-3f9a/report.md` | any other port; note the double slash before an absolute path |
| `<id>:/abs/path` | `gpu1:/data/alice/projects/task-3f9a/report.md` | what you may type yourself: the registry id works in place of the address |
A path after the colon that does not start with `/` is relative to the user's
home on the machine. A file on this computer whose name holds a colon is
written as `./a:b` or as an absolute path. A spelling that names no registered
machine is refused with a sentence that says so, before any ssh.
## 6. Read, edit and fetch by address
`read_file`, `list_dir`, `find`, `grep`, `write_file` and `edit_file` take a
path on a machine as readily as a local one. The call runs on the machine,
through its node, and only the answer travels: a read of 50 lines moves those
50 lines. Line numbers, limits and footers are the same as for a local file.
- **Reads ask no question** under the directories Raven's agents work in on
that machine: `~/raven-work`, the `remoteCwd` of every entry on that
machine, and the absolute `paths` listed on its registry row. A read
elsewhere asks, as a read outside the workspace does here.
- **Writes always ask**, as they do here, and a grant is for the one file.
A whole-file write checks that the file is still what this conversation last
read; a file changed in between is left alone, with *changed after it was
read; nothing was written. Read it again before writing.*
- The node confines every call to the directory the check allowed, resolving
the machine's own symlinks.
`deliver_files` fetches one file by its address, so you can download it from
the page. The file lands under the conversation's workspace at
`pulled/<machine>/<key>/<name>`, the key being a digest of its path there, so
two paths never land on each other. Only a file under the directories the
agents work in is fetched, and only one of 20 MiB or less; a bigger file, or
one elsewhere, is read on the machine instead. `pulled/` is not cleaned up;
clear it when you no longer need what is in it.
In `exec`, an `ssh` typed to a registered machine's address is refused with a
pointer to the registered route; `scp` and `rsync` to it are fine, and can
address it by id thanks to the alias written at registration.
## 7. Disconnects and restarts
Raven keeps one ssh link per machine and watches it with a heartbeat: a ping
every 5 seconds, and 15 seconds without an answer means the link is gone. The
agents are not: they run under the machine's daemon, which keeps every frame
they write and every line of their stderr. Raven tries the link again on a
backoff of 2, 4, 8, then 16 seconds for as long as any agent is waiting, and a
link that comes back attaches each agent by its task id, from the frame and
the stderr line Raven last read. The turn goes on as if nothing had happened;
a cancel sent while the link was down is delivered when it is back.
Stopping Raven does the same on purpose. An agent running on a machine is left
to the daemon; what Raven keeps is a record under
`<raven home>/machines/runs/`. The next start reads those records, attaches
each run from where it was, reads what it wrote on stderr during that turn
too (a command's whole stderr: the reason it failed, or the session id a CLI
names only there), and announces the
result into the conversation that asked, as a finished turn. Keep the
machine's registration and the agent entry in place for that. `/restart` and a
Raven that was killed are covered the same way.
What is not recoverable: a machine that rebooted, or a daemon that was ended
by hand, no longer knows the task. The turn is then announced as an error
(*no longer runs 'agent' (task …)*), and nothing is left running there.
A link that has carried no call and run no agent for 10 minutes is closed
the next time Raven uses another machine; there is no timer, so the last link
in use stays open until then. The daemon does keep a timer: it leaves after
10 minutes with no connection and no agent. Neither is an error; the next use
starts them again.
## 8. Remove a machine
```bash
raven ops connection remove gpu1
```
Takes the machine out of the registry after asking (`--yes` skips the
question) and removes its managed `Host gpu1` block from `~/.ssh/config`. A
block with one of its two marker lines missing (edited by hand) is left as it
is and named in a warning: take it out yourself. Nothing else in that file is
touched.
Refused while a connected agent entry names the machine: such an entry fails
at its next dispatch, after the spawn has answered that it started, so
disconnect those entries first (the Agent Hub, or the `subagents.agents`
section of the config), or pass `--force` to remove the machine anyway and be
told which entries are left pointing at nothing. A disconnected entry does not
stand in the way; it is named, and connecting it again is refused until a
machine is registered under that id again. The node under its `node_dir` stays on the machine,
and removing it is a matter of deleting that directory there by hand. The
password kept here for a machine registered with one is deleted with the row.
The Agent Hub's **Remove machine**, in a machine's sheet, does the same after
a confirmation, and also refuses while agents are running on the machine over
the link from this computer; wait for them, or stop them, first. A run left on
the machine by an earlier Raven process ([section 7](#7-disconnects-and-restarts))
is not picked up once the machine is gone from the registry.
## Limits and defaults
| What | Value |
| --- | --- |
| Agents running at once on one machine | 8; a ninth launch is refused with *already runs 8 agents; wait for one to finish* |
| A finished task's record on the machine | kept 7 days |
| Heartbeat / link lost after | 5 s / 15 s |
| Reconnect backoff | 2, 4, 8, 16 s |
| Idle link closed | after 10 min without a call or an agent, at the next use of another machine; no timer |
| Daemon leaves | after 10 min with no connection and no agent; a timer |
| ssh connect timeout | 15 s |
| A file call's answer | within 120 s, or the call fails |
| A file fetched by `deliver_files` | 20 MiB at most |
| Default working directory on the machine | `~/raven-work` |
| Default node directory | `~/.raven-node` |
| Ways to send the prompt to a CLI agent there | `{prompt}`, `{prompt_file}`, stdin |
The registry row's `concurrency` and `budget_unit` govern on-call jobs, not
these agents.
**Windows.** The machine has to be Linux or macOS. Raven itself may run on
Windows: there, a drive-relative path such as `C:file` is read as a local path
and never as a machine named `C`, and a fetched file whose name holds a
character Windows reserves lands with that character written as a percent
code.
## Troubleshooting
Every failure is one sentence that names the machine by its id and display
name, never by its address. ssh's own messages, which do name the address, go
to an owner-only log under the Raven home (`logs/ssh/`).
| The sentence says | It means | Do this |
| --- | --- | --- |
| *is not registered; add it with `raven ops connection add`* | No row has that id | Check the id in the entry against `raven ops connection list` |
| *is registered, but its entry cannot be used; run `raven ops connection doctor`* | The row is incomplete or its id is listed twice | Run `doctor` and fix what it names |
| *is this computer; remove `machine` from the agent's entry* | The row is a `local` transport | Drop `machine`; the agent runs here |
| *refused the login; check the key it is registered with* | ssh's key login failed | Try `ssh -i <key> user@host` by hand; re-add if the key changed |
| *presented a host key that differs from the one on record* | The machine's host key changed | Check the machine, then clear its `known_hosts` line |
| *could not be reached* / *did not answer within the connection timeout* | Network or address | Check address, port and whether sshd is up |
| *is not installed on machine …; install it with `raven ops connection install-node …`* | No node there | Run the install |
| *runs different code from this Raven; update it with …* | The node is from another Raven version | Run `install-node` again |
| *has no uv, and no curl or wget to fetch one with* | The installer needs `uv`, and the machine has neither it nor a way to fetch it; a Python there does not change this | Install `uv` on the machine (the sentence names its installer), or `curl` or `wget`, then retry |
| *has uv 0.4.22, and only uv 0.4.23 or later installs from the package index pip is configured with there; with no curl or wget to fetch uv 0.13.0, upgrade uv there* | pip on the machine is configured with an index, its `uv` is too old to read one (or does not say its version), and the installer has no way to fetch a newer one | Upgrade `uv` on the machine, or install `curl` or `wget` so the installer fetches one under `node_dir`, then retry |
| *the agent's command was not found on machine …* | The agent is not installed there for that user | Install and sign in on the machine |
| *already runs 8 agents; wait for one to finish* | The machine is at its limit | Wait, or use another machine |
| *did not answer a heartbeat within 15s* | The link dropped | Nothing; Raven reconnects. The agent keeps running |
| *no longer runs 'agent' (task …)* | The daemon lost the task (reboot, killed) | Dispatch again |
| *changed after it was read; nothing was written* | Someone changed the file since this conversation read it | Read it again, then write |
| *is over the 20.0 MB limit for a file brought back* | Too large for `deliver_files` | Read it on the machine, or copy it with `scp` |
| *an endpoint reached through the machine has to be http* | `baseUrl` is `https` | Use the `http` address the machine reaches it at |
| *this command reaches … over raw ssh* | A typed `ssh` to a registered address in `exec` | Use `exec(machine=…)`, or the file tools |
## Security
- The private key stays on this computer; the registry holds its path. The
ssh command line built from the row is held in memory and written to no
config, log or model-visible text.
- The user, address and port do reach a model, because they name every file on
the machine (the `scp` spelling above). The key and the ssh line never do.
- The node opens no network port. It listens on a socket under its own
directory, owned by the registered user, and only that user's ssh session
reaches it. Each task's record there is readable by that user alone.
- The node runs file calls with Raven's own tools, fenced to the directory the
permission check allowed. It holds no conversation and calls no model;
nothing of your model keys goes to the machine.
- An agent on a machine is that machine's install, signed in there. Raven
lends it no key of its own: `lendKeys` on an entry that names a machine
lends nothing. The entry's `env` is the one thing of yours it receives, over
the link.

View File

@ -1,406 +0,0 @@
# 在登记机器上工作
把子 Agent 放到另一台电脑上跑:GPU 机器、实验室工作站、办公室的服务器,
而对话仍在你自己的 Raven 里。登记一次机器,把 Raven 的节点装上去,再在 Agent
条目里写上这台机器,之后 Agent 就派到那里执行,在那里的目录里工作,文件也留在那里;
对话按地址读取,你要的时候再取回一个。连接断了,或者你把 Raven 停了,Agent 照样工作,
回来时接回结果。
本页是完整的操作指南。委派本身见[与子 Agent 协作](agent-collaboration.md),
Agent 的安装见[Agent 集成](agent-integrations.md)。
## 准备条件 { #what-you-need }
- 一台能 ssh 登录的机器,登录用户就是 Agent 将要运行的用户:用密钥,或者用一个由 Raven
保存在本机、每次连接时交给 ssh 的密码(见下面的登记一节)。
- 机器上是 Linux 或 macOS,该用户有 POSIX shell。节点依赖 unix 套接字和进程组,
所以 Windows 机器不能作为目标。(Raven 本机可以是 Windows,见[限制与默认值](#limits-and-defaults)。)
- 机器上有 `uv`(在 PATH 上,或在它的安装程序放置的位置),**或者**有 `curl` 或 `wget`
让安装程序去取一个。安装程序用 `uv` 构建节点,没有 `uv` 就停下,不管机器上有什么
Python。机器上有 Python 3.12 或更新版本更好,但不是必需:有的话,节点的虚拟环境从它
建出来;没有的话,`uv` 自带一个 Python 3.12,占用空间更多。
- 要运行的 Agent 已经装在那台机器上,并且以那个用户登录过:Claude Code、Codex、
Qwen Code 这类 ACP Agent,命令行 Agent,或者一个只在那台机器网络里能访问的
OpenAI 兼容端点。
## 1. 登记机器 { #1-register-the-machine }
```bash
raven ops connection add
```
命令一次问一件事:你怎么称呼这台机器、它是 ssh 连的还是这台电脑本身、给它一个短 id,
然后是地址、端口、用户名和私钥路径。写入之前会先连一次;连不上的机器不会被记录。
机器能自己说清楚的信息(核数、内存、GPU)从机器上读,不用手敲。最后几个问题是给
on-call 任务用的:装了什么软件(随便写一句即可)、预算单位和同时跑几个任务(回车取默认值)、
存放你工作的目录(可留空)。你列出的目录以后读文件也不用再问(见[第 6 节](#6-read-edit-and-fetch-by-address))。
写脚本时,把每个回答都用参数给出:
```bash
raven ops connection add --id gpu1 --name "GPU box 1" \
--host <地址> --port 22 --user alice --key ~/.ssh/id_ed25519 \
--non-interactive
```
记录了什么、记在哪里:
- 这一行写进 `connections.json`:`RAVEN_CONNECTIONS` 指向的文件;没有就是 config
旁边那份;再没有就是 Raven 主目录(`~/.raven`)里那份。注册表的细节见
[Oncall](oncall.md#prepare-the-agent-and-machine)。
- 记录的是私钥的**路径**,从不记录私钥本身。
- 只能用密码登录的机器,在 Agent Hub 里把**登录方式**选成**密码**来登记,或者用
`raven ops connection add --non-interactive --auth password --password-stdin --id <id>
--name <name> --host <地址> --port 22 --user <用户>`(密码从标准输入的第一行读,不走
命令行;`--password-stdin` 在第一个问题之前就读,带不带 `--non-interactive` 都行)。
密码至少 6 个字符,保存在本机的 `~/.raven/keys/<id>.password`,只有你的账号能读
(权限 0600);每次连接时经 OpenSSH 的 askpass 钩子交给 ssh,不进登记表、不进日志、
不回显、不上命令行。这些连接每一条都自己登录(你 ssh 配置里的连接共享 `ControlMaster`
对它们不生效),所以登记时证明的就是保存下来的这个密码,机器改了密码也会在下一次连接时
发现。它们启动时没有控制终端,所以 OpenSSH 8.4 以前的版本(只在开不了终端时才用
askpass)也会走助手而不是在终端上要密码。跳板机不行:密码连接关掉了 `ProxyJump` 和
`ProxyCommand`,因为跳板自己的 ssh 会拿到这台机器的密码;只能经跳板到达的机器请用
密钥登记。助手只回答一种提示:ssh 自己向登记的账号、登记的地址(`user@host`)索要密码的
那一句。别的账号的提示、第二重验证的提示(验证码、passcode)、一次性密码的提示都拿不到
回答,所以登录时还要第二重验证的机器也请用密钥登记。登记表里这一行记 `auth: password`,
没有密钥路径。`raven ops connection doctor` 把它算作可用,Oncall 的 campaign 也能在上面跑,
登录方式相同,而且只登录到登记的地址:campaign 不能把这样一条连接指到别的主机、端口或
用户名上。机器的 sshd 必须允许
密码登录(`PasswordAuthentication yes`),不允许的机器每次连接都会拒绝,拒绝语里会说明。
登记时被机器拒绝的密码不会保存。登记失败或取消时,会保留另一条并发登记保存的密码,
即使另一条登记仍在连接中、使用的密码也完全相同。机器改了密码,先移除这台机器再重新登记(id 已在用的登记
会被拒)。本机是 Windows 时不提供:
Windows 的 OpenSSH 跑不了把密码交给 ssh 的 POSIX 脚本。这样登记的机器不写
`~/.ssh/config` 里的 `Host <id>` 别名:终端里对它用 `scp`、`rsync` 要自己输密码,
Agent 读写它上面的文件走 Raven 自己的文件工具。移除机器时会删掉本机保存的密码
([第 8 节](#8-remove-a-machine))。
- 机器的主机密钥在第一次连接时接受并写进 `~/.ssh/known_hosts`。之后机器换了密钥,
会被拒绝,直到你自己核实过。用密码登记时,这第一次连接带着密码:在不信任的网络上,
先在终端里连一次(`ssh user@host` 会显示指纹让你确认)再登记,或者改用密钥登记。
- 用密钥登记的机器,`~/.ssh/config` 里会写入一段受管理的 `Host <id>`,这样本机的 `scp`
和 `rsync` 可以按 id 找到这台机器。
`raven ops connection list` 列出机器。`raven ops connection doctor` 逐条列出条目的问题,
阻塞的和提示性的都列,但只有一台可用的机器都没有时退出码才非零:一条坏的条目旁边有一条
可用的,退出码仍是零,所以要看它的输出,不要只看退出码。
### 在 Agent Hub 里 { #from-the-agent-hub }
不开终端也能登记:Agent Hub 顶部与**智能体**、**渠道**并列的**机器**标签列出已登记的机器,
**登记机器**打开一个表单,
填名称、id、地址、端口、用户名和私钥路径,以及工作目录。页面和命令一样,写入之前先连一次,
连不上的机器不会被记录;拒绝时会说明是哪一类(连不上、拒绝登录、主机密钥变了、没有按时应答)
以及该怎么办。之后页面上显示的只是这台机器是什么——名称、id、链路、节点——从不显示地址、
用户名或私钥路径:这些只在表单里传一次,不会再读回来。私钥路径一栏会预填这台电脑上
已有的密钥:先是 ssh 自己的那几把(`~/.ssh/id_rsa` 排在 `id_ed25519` 前面,和 ssh 自己尝试的顺序一致),再是你自己
起名的密钥对,其余的可以下拉换;一把都没找到时表单会说明,这时可以改用*密码*登记。
## 2. 安装节点 { #2-install-the-node }
```bash
raven ops connection install-node gpu1
```
节点是 Raven 自己的代码,装在机器上的一个小虚拟环境里,负责在那里启动 Agent、回答文件调用。
命令先看一眼机器,打印它准备做什么,确认后才动手(`--yes` 跳过确认)。成功时最后两行是:
```text
Installed the Raven node <版本>-<摘要> in /home/alice/.raven-node (62 MB).
The node answers: Python 3.12.3, code <摘要>.
```
机器上会多出什么:
| 内容 | 位置 |
| --- | --- |
| 节点 | `<node_dir>/<版本>-<摘要>/`,`node_dir` 取注册表那一行的值,默认 `~/.raven-node` |
| 运行状态 | `node_dir` 下的 `run/`(套接字)、`tasks/<任务>/`(每个 Agent 的记录,仅属主可读)和 `log/` |
| `uv`(机器上原本没有时,或者机器自己的 `uv` 早于 0.4.23 而 pip 又配了索引时——那样的 `uv` 会无视索引) | `<node_dir>/.uv`,版本 0.13.0,用机器自己的 `curl` 或 `wget` 取回;之后的安装直接用它 |
| Python 3.12(机器上原本没有时) | 节点旁边,由 `uv` 管理 |
别的都不变:不装系统包,不改 shell 的 rc 文件,不改环境变量,不注册服务,不开端口。
节点的依赖包从机器上 pip 配置的索引安装,没有配置就从 PyPI 安装。安装程序按下面的
数字检查空间:
| 部分 | 大约 |
| --- | --- |
| 节点 | 60 MB |
| `uv` 带来的 Python 3.12 | 再加 80 MB |
| `uv` 本身(需要取回时) | 再加 25 MB |
`--dir <路径>` 把节点放在 `~/.raven-node` 以外的地方;路径会记进注册表那一行,
以后的命令都能找到。机器上已经有这个 Raven 的节点时,什么都不动。节点的名字也会记在
那一行(`node_install`),Agent Hub 就是靠它在链路还没建立时说明机器上有节点。
### 在 Agent Hub 里安装 { #installing-from-the-agent-hub }
机器卡片或抽屉里的**安装节点**在后台做同样的安装:卡片上显示*正在安装节点*直到结束,
抽屉里保留结束时的结果。抽屉里的*安装到*就是命令的 `--dir`。节点是另一个版本的 Raven 装的,
会显示*需要更新*并提供**更新节点**。
节点装好之后,卡片会列出这台机器上的 Agent 条目,接着的和已断开的都在(一条都没有时写*还没有 Agent 接到这里*;
状态行*链路在,没有 Agent 在跑*说的是此刻),抽屉里会给出下一步并提供**在这台机器上接入
Agent**:选 Agent、填它在机器上的工作目录,**接入**会像第 4 节的 `subagents.add` 一样写入
`<预设>@<机器 id>`(如 `codex@gpu1`),写入前先在机器上真跑一句;机器上已经有这个预设时同样
会被拒绝。可选的是机器节点能启动的全部预设,本机
已经接入的也在其中——那是机器上的第二个条目,不冲突。机器上已断开的条目也会显示出来,
卡片和表单里都带「已断开」:它仍然占着这台机器,所以表单里每条这样的条目各是一个选项(按条目名),
按钮变成**重新接入**,点下去是把那条条目重新启用(同样先真跑一句),不是再加一条。也可以在 Agent 自己的抽屉里选
*运行在*:列出的是全部已登记机器,只有装了本 Raven 节点的能选(其余会说明原因),还要填
机器上的工作目录;本机没装的 Agent 同样可以这样接到机器上,要紧的是它在那台机器上装好
并登录了。只有还没进花名册的预设才有这个选项:已经存在、只是关着的条目用它自己的按钮接入,
那个按钮不带机器。某台机器上的接入还在进行时(试跑一句最长要一分钟),再打开这台机器的接入
表单,那个预设会置灰,不会接第二次。
**升级。** 节点跑的正是装它的那个 Raven 的代码,每次连接都按摘要核对。在本机更新
Raven 之后,再跑一次 `install-node`:新节点装在旧节点旁边;`--prune` 删掉目录里其他
版本的节点(缓存的 `uv` 和 Python 保留)。没升级之前,派到那台机器会失败,提示
*runs different code from this Raven; update it with `raven ops connection install-node gpu1`*。
**守护进程。** 安装不会启动任何东西。Raven 第一次使用这台机器时,它的 ssh 会话会把
节点的守护进程拉起来,守护进程不随会话结束;没有连接也没有 Agent 在跑满 10 分钟后,
它自己退出。机器重启后,下一次使用会再把它拉起来。
## 3. 在 Agent 条目里写上机器 { #3-name-the-machine-in-an-agent-entry }
拿配置里 `subagents.agents` 下已有的那条 Agent 条目(子 Agent 页面或 `raven_config`
添加的那条),加上 `machine`,值是注册表里的 id。`remoteCwd` 是 Agent 在那台机器上的
工作目录,默认 `~/raven-work`,`~` 是登记用户在那台机器上的家目录。每个实例或任务在
它下面各有自己的目录:`<remoteCwd>/<实例或任务 id>`。
### ACP Agent { #acp-agents }
```json
{
"name": "Claude Code on gpu1",
"preset": "claude_code",
"kind": "acp",
"enabled": true,
"command": "<该 Agent 的 ACP 命令,同本机条目>",
"machine": "gpu1",
"remoteCwd": "/data/alice/projects"
}
```
节点在机器上启动条目的 `command`,用的是登记用户的登录环境(`bash` 或 `zsh` 登录时
读的 profile 和 rc 那一串;其他 shell 的用户得到的是 ssh 启动节点时的环境)。条目的
`env` 叠在上面,经链路送到 Agent,不走命令行。`cwd` 指的是本机目录,机器上的条目不读它。
### 命令行 Agent { #cli-agents }
```json
{
"name": "my-cli on gpu1",
"kind": "cli",
"enabled": true,
"command": "my-agent --prompt-file {prompt_file}",
"machine": "gpu1"
}
```
同一条命令在机器上执行,按那台机器 POSIX shell 的规则切分。提示词送达的方式和本机一样有
三种:`{prompt}` 作为一个参数、`{prompt_file}` 写成那次运行目录下的文件、或者走标准输入
(节点送完提示词就关闭它)。输出按行原样回传,空行也在内。取消或超时会结束机器上的整棵
进程树,放到后台的命令也一起结束。
### OpenAI 兼容端点 { #openai-compatible-endpoints }
```json
{
"name": "vLLM on gpu1",
"kind": "openai",
"enabled": true,
"baseUrl": "http://127.0.0.1:8000/v1",
"model": "my-model",
"machine": "gpu1"
}
```
用于只在那台机器上、或只在它的网络里能访问的端点。每一轮都开一条到机器的 ssh 隧道,
请求经隧道送到机器所理解的 `baseUrl`,这一轮结束隧道就关。`baseUrl` 必须是 `http`:
隧道的终点是本机回环地址,`https` 证书对不上它。这种类型没有 `remoteCwd`(端点没有
工作目录),写了会在加载时丢弃并给出警告。
### 内置 Agent { #built-in-agents }
内置 Agent 是 Raven 自己的循环,跑在这个进程里,模型密钥和工具都在这里,没有可以放到
别处启动的进程。内置条目上的 `machine` 在加载时丢弃并给出警告,条目仍在本机运行。
## 4. 或者在对话里添加 { #4-or-add-one-from-a-conversation }
在对话里直接说,比如“把 Codex 预设添加到机器 gpu1 上”。主 Agent 会列出可用的登记机器,
然后带着预设、机器,以及(ACP 或命令行预设可选的)`remote_cwd` 调用 `subagents.add`:
```json
{"preset": "codex", "machine": "gpu1", "remote_cwd": "/data/alice/projects"}
```
不指定名字时条目叫 `<预设>@<机器>`,所以一个预设可以在每台机器上各添加一次:机器上已经有
这个预设时,不带名字的添加会被拒绝,拒绝语里写明已有的那个条目(接着的或已断开的);要在
一台机器上给同一个 Agent 加第二个条目(比如两个工作目录),就给它起一个自己的名字。存入之前,
添加会像本机添加一样先验证:用那个 Agent 在那台机器上真的跑一条测试提示,所以 Agent
必须已经在那里装好并登录。预设是内置 Agent、OpenAI 预设带了 `remote_cwd`、或者机器的
条目不可用时,添加会在花费任何东西之前被拒绝。
页面上同样的添加,就是机器抽屉里的**在这台机器上接入 Agent**,或 Agent 自己抽屉里的*运行在*。
## 5. 派发时会发生什么 { #5-what-happens-when-you-dispatch }
照常派发:让宿主委派,或者和这个 Agent 的实例直聊。和本机 Agent 相比有三处不同。
**附件只给地址,不复制。** 随任务来的文件按它在本机上的地址告诉 Agent,并注明没有复制。
Agent 在机器能读到的地方使用它(两边都挂载的盘上的同一路径、已经在那里的副本),
读不到就在回复里说明找不到,然后继续。
**MCP 服务器不出借。** 宿主的 MCP 服务器通过本机上的一个套接字访问,别的机器上的
Agent 打不开它。授权了的服务器会在回复里注明没有出借。跨链路出借即将提供(拉取请求 #947)。
**它写的文件留在机器上。** 这一轮结束时什么都不会自动拿回来。回复末尾有一行说明它在哪里工作:
```text
[raven] Ran on machine 'GPU box 1' (gpu1), in alice@203.0.113.7:/data/alice/projects/task-3f9a;
the files it wrote are there, not on this computer -- read_file, list_dir, find,
grep, write_file and edit_file take that path as it is, and deliver_files fetches one by it.
```
派发记录里也用同样的方式写目录:*Working directory: on machine 'gpu1',
/data/alice/projects/task-3f9a (made there when the run started)*。
### 机器上的路径怎么写 { #how-a-path-on-a-machine-is-written }
机器上的路径按 `scp` 的写法写,带注册表里的用户、地址和端口。回复、记录、工具结果里都
只用这一种写法,工具也按这种写法读回去:
| 形式 | 例子 | 何时 |
| --- | --- | --- |
| `user@host:/abs/path` | `alice@203.0.113.7:/data/alice/projects/task-3f9a/report.md` | 端口是 22 |
| `scp://user@host:port//abs/path` | `scp://alice@203.0.113.7:2222//data/alice/projects/task-3f9a/report.md` | 其他端口;注意绝对路径前是两个斜杠 |
| `<id>:/abs/path` | `gpu1:/data/alice/projects/task-3f9a/report.md` | 你自己输入时可以这样写:注册表 id 可以代替地址 |
冒号后面不以 `/` 开头的路径,相对于那台机器上用户的家目录。本机上名字里带冒号的文件,
写成 `./a:b` 或绝对路径。对不上任何登记机器的写法会在任何 ssh 之前被拒绝,并说明原因。
## 6. 按地址读、改、取 { #6-read-edit-and-fetch-by-address }
`read_file`、`list_dir`、`find`、`grep`、`write_file` 和 `edit_file` 接受机器上的路径,
和本机路径一样用。调用通过节点在机器上执行,只有结果回传:读 50 行就只传这 50 行。
行号、上限和页脚和读本机文件完全一样。
- **读不用问**的范围是 Raven 的 Agent 在那台机器上的工作目录:`~/raven-work`、那台机器上
每个条目的 `remoteCwd`,以及注册表那一行里列出的绝对路径 `paths`。读别处会询问,
就像在本机读工作区以外的文件一样。
- **写一律询问**,和本机一样,授权只对那一个文件有效。整文件写入会核对文件是否还是这个
对话上次读到的样子;中途被改过的文件不动,并提示 *changed after it was read;
nothing was written. Read it again before writing.*
- 节点把每次调用限制在审批允许的目录内,并按机器自己的符号链接解析。
`deliver_files` 按地址取回一个文件,这样你就能在页面上下载它。文件落在对话工作区下的
`pulled/<机器>/<键>/<文件名>`,键是它在机器上路径的摘要,所以两个路径永远不会互相覆盖。
只取 Agent 工作目录之内的文件,而且不超过 20 MiB;更大的文件或别处的文件,在机器上读。
`pulled/` 不会自动清理,不需要时自己清掉。
在 `exec` 里直接输入指向登记机器地址的 `ssh` 会被拒绝,并提示应走的登记路线;
`scp` 和 `rsync` 到它没有限制,而且因为登记时写了别名,可以按 id 找到它。
## 7. 断线与重启 { #7-disconnects-and-restarts }
Raven 对每台机器保持一条 ssh 链路,用心跳看着它:每 5 秒 ping 一次,15 秒没有回应就算
链路断了。Agent 没有断:它们在机器的守护进程下继续运行,写出的每一帧和 stderr 的每一行都被守护进程保存。
只要还有 Agent 在等,Raven 就按 2、4、8、16 秒的退避不断重试;链路回来后按任务 id
把每个 Agent 接回,从 Raven 上次读到的那一帧和那一行 stderr 继续,这一轮像什么都没发生一样进行下去;
链路断开期间发出的取消,链路回来时送达。
停止 Raven 的效果是一样的,而且是有意为之。机器上的 Agent 留给守护进程,Raven 这边
留下的是 `<Raven 主目录>/machines/runs/` 下的一条记录。下次启动时读这些记录,把每次
运行从原来的位置接回,连同这一轮写在 stderr 里的内容一起读到(命令的整个 stderr:失败的原因,或只在 stderr
里报会话 id 的 CLI 给出的 id),再把结果通告到发起它的那个对话,就像一轮正常结束一样。为此要保留
机器的登记和 Agent 条目。`/restart` 和被强制结束的 Raven 也按同样方式处理。
接不回来的情况:机器重启过,或者守护进程被手动结束,任务就不再被机器认识。这一轮会以错误
通告(*no longer runs 'agent' (task …)*),机器上也不会留下任何在跑的东西。
一条 10 分钟内没有调用、也没有 Agent 的链路,会在 Raven 下一次使用别的机器时被关闭;
没有定时器,所以最后那条在用的链路会一直开着,直到那时。守护进程有定时器:没有连接也没有
Agent 满 10 分钟就退出。两者都不是错误,下次使用会重新建立。
## 8. 移除机器 { #8-remove-a-machine }
```bash
raven ops connection remove gpu1
```
确认后把机器从注册表里去掉(`--yes` 跳过确认),并删掉 `~/.ssh/config` 里受管理的
`Host gpu1` 段。那一段若少了两行标记中的一行(被手改过),就原样不动、在警告里点名,由你自己删;
文件里别的内容一律不碰。还有**已接入**的 Agent 条目写着这台机器时会拒绝:这样的条目在下一次派发时会失败,
而且是在 spawn 已经回答"已启动"之后,所以要先断开这些条目(Agent Hub,或配置里的
`subagents.agents` 段),或者加 `--force` 照样移除,命令会说出哪些条目还指着一台不存在的机器。
已断开的条目不拦着移除,只会被点名:再接入它会被拒,直到用同一个 id 重新登记机器。
`node_dir` 下的节点留在机器上,要删就到机器上手动删掉那个目录。用密码登记的机器,本机为它
保存的密码会随这一行一起删掉。
Agent Hub 机器抽屉里的**移除机器**做同样的事,先弹确认;本机链路上还有 Agent 在这台机器上
跑时也会拒绝,等它们跑完或先停掉。之前的 Raven 进程留在机器上的运行
([第 7 节](#7-disconnects-and-restarts))在机器移出注册表之后不会再被接回。
## 限制与默认值 { #limits-and-defaults }
| 项目 | 值 |
| --- | --- |
| 一台机器同时运行的 Agent 数 | 8 个;第 9 个启动会被拒绝,提示 *already runs 8 agents; wait for one to finish* |
| 已结束任务的记录在机器上保留 | 7 天 |
| 心跳间隔 / 判定断链 | 5 秒 / 15 秒 |
| 重连退避 | 2、4、8、16 秒 |
| 空闲链路关闭 | 10 分钟没有调用也没有 Agent 之后,在下一次使用别的机器时关闭;没有定时器 |
| 守护进程退出 | 没有连接也没有 Agent 满 10 分钟;有定时器 |
| ssh 连接超时 | 15 秒 |
| 一次文件调用的回应 | 120 秒内,否则调用失败 |
| `deliver_files` 取回的文件 | 最大 20 MiB |
| 机器上的默认工作目录 | `~/raven-work` |
| 默认节点目录 | `~/.raven-node` |
| 给命令行 Agent 送提示词的方式 | `{prompt}`、`{prompt_file}`、标准输入 |
注册表里的 `concurrency` 和 `budget_unit` 管的是 on-call 任务,不管这里的 Agent。
**Windows。** 机器必须是 Linux 或 macOS。Raven 本机可以是 Windows:在 Windows 上,
`C:file` 这种盘符相对路径按本机路径读,不会被当成叫 `C` 的机器;取回的文件名里如果有
Windows 保留的字符,落地时该字符写成百分号编码。
## 排错 { #troubleshooting }
每个失败都是一句话,用机器的 id 和显示名称指代它,从不出现地址。ssh 自己的信息会带地址,
写在 Raven 主目录下仅属主可读的日志里(`logs/ssh/`)。
| 提示里写着 | 意思 | 怎么办 |
| --- | --- | --- |
| *is not registered; add it with `raven ops connection add`* | 没有这个 id 的条目 | 对照 `raven ops connection list` 检查条目里的 id |
| *is registered, but its entry cannot be used; run `raven ops connection doctor`* | 条目不完整,或 id 重复 | 跑 `doctor`,按它指出的修 |
| *is this computer; remove `machine` from the agent's entry* | 这一行的 transport 是 `local` | 去掉 `machine`,Agent 在本机跑 |
| *refused the login; check the key it is registered with* | ssh 密钥登录失败 | 手动试 `ssh -i <密钥> user@host`;密钥换了就重新登记 |
| *presented a host key that differs from the one on record* | 机器的主机密钥变了 | 核实机器,再清掉 `known_hosts` 里它那一行 |
| *could not be reached* / *did not answer within the connection timeout* | 网络或地址问题 | 检查地址、端口,以及 sshd 是否在运行 |
| *is not installed on machine …; install it with `raven ops connection install-node …`* | 那里没有节点 | 安装节点 |
| *runs different code from this Raven; update it with …* | 节点来自另一个 Raven 版本 | 再跑一次 `install-node` |
| *has no uv, and no curl or wget to fetch one with* | 安装程序需要 `uv`,机器上既没有它也没有取它的办法;有 Python 也不改变这一点 | 在机器上装 `uv`(提示里给了它的安装程序),或者装 `curl` 或 `wget`,再试 |
| *has uv 0.4.22, and only uv 0.4.23 or later installs from the package index pip is configured with there; with no curl or wget to fetch uv 0.13.0, upgrade uv there* | 机器上的 pip 配了索引,它的 `uv` 太旧、读不了索引(或者说不出自己的版本),安装程序又没办法取一个新的 | 在机器上升级 `uv`,或者装 `curl` 或 `wget` 让安装程序把 `uv` 取到 `node_dir` 下,再试 |
| *the agent's command was not found on machine …* | 那个用户在机器上没装这个 Agent | 在机器上安装并登录 |
| *already runs 8 agents; wait for one to finish* | 机器已到上限 | 等一等,或换一台机器 |
| *did not answer a heartbeat within 15s* | 链路断了 | 不用做什么,Raven 会重连;Agent 还在跑 |
| *no longer runs 'agent' (task …)* | 守护进程丢了这个任务(重启、被结束) | 重新派发 |
| *changed after it was read; nothing was written* | 这个对话读过之后文件被别人改了 | 重新读一遍再写 |
| *is over the 20.0 MB limit for a file brought back* | 超过 `deliver_files` 的上限 | 在机器上读,或用 `scp` 拷贝 |
| *an endpoint reached through the machine has to be http* | `baseUrl` 是 `https` | 用机器访问它的 `http` 地址 |
| *this command reaches … over raw ssh* | 在 `exec` 里直接 `ssh` 到登记的地址 | 改用 `exec(machine=…)` 或文件工具 |
## 安全 { #security }
- 私钥留在本机,注册表只记它的路径。由那一行拼出来的 ssh 命令行只在内存里,不写进任何
配置、日志或模型可见的文字。
- 用户、地址和端口会出现在模型面前,因为机器上的每个文件都靠它们命名(上面的 `scp` 写法)。
密钥和 ssh 命令行永远不会。
- 节点不开网络端口。它监听自己目录下的一个套接字,属主是登记用户,只有这个用户的 ssh
会话能接到它。那里每个任务的记录也只有这个用户能读。
- 节点用 Raven 自己的文件工具执行文件调用,限制在审批允许的目录内。它不保存对话、
不调用模型;你的模型密钥不会去到机器上。
- 机器上的 Agent 是那台机器自己装的、在那里登录过的。Raven 不借给它自己的密钥:
写了 `machine` 的条目上,`lendKeys` 什么都不出借。它从你这里收到的只有条目的
`env`,经链路送达。

View File

@ -58,15 +58,7 @@ one, else the home. A first registration lands in the home. Sub-agents run on a
rendered config in a state directory of their own and inherit the home, so
they read the owner's registry rather than a copy of it. SSH registration can
also write a managed alias in `~/.ssh/config`; the key path is recorded, not
the private key bytes. A machine registered with a password
([Working on registered machines](machines.md#1-register-the-machine)) runs
campaigns too: their ssh and their rsync log in with the password Raven keeps
for it, through the same options and askpass hook as every other connection,
and a campaign carries the connection id and `auth`, never the password. The
address and account are the registry's: a campaign meta that gives such a
connection another host, port or user is refused before any ssh starts, since
the kept password goes only to the machine it was registered for. Do not put
keys or passwords in a task message.
the private key bytes. Do not put keys or passwords in a task message.
An agent can register a machine too. The `ops_connection_add` tool (on in
raven-oncall and raven-code through `tools.connectionAdd`; off elsewhere) takes
@ -74,9 +66,7 @@ what the owner said in conversation -- this computer or another, what they
call it, an address if another -- fills a port, user or key they left out from
their own ssh config, reaches the machine, and only then writes the row. When
the registry lists no machine that fits, the agent asks the owner rather than
looking for a way in with a raw ssh command. It never asks for a password: a
machine that takes one is the owner's to register, from the Agent Hub's
**Machines** tab or with `raven ops connection add --auth password`.
looking for a way in with a raw ssh command.
`doctor` validates registry usability; it is not a fresh execution test of
every remote environment. `--skip-probe` on `add` skips contacting the machine

View File

@ -46,18 +46,13 @@ raven ops connection add --id local-lab --name "Local lab" \
先读 config 旁边的 `connections.json`,没有再读家目录。第一次注册写在家目录。
子代理各自用渲染出的 config 跑在自己的状态目录里、继承家目录,所以读到的是
主人的注册表,不是一份副本。SSH 注册还可能在 `~/.ssh/config` 写入受管理的别名;
只记录私钥路径,不记录私钥内容。用密码登记的机器(见[在登记机器上工作](machines.md#1-register-the-machine))
同样能跑 campaign:它们的 ssh 和 rsync 用 Raven 为这台机器保存的密码登录,用的选项和 askpass
钩子与其他每条连接相同;campaign 里记的是连接 id 和 `auth`,从不记密码。地址和账号以登记表为准:
campaign 的 meta 若给这样一条连接写了别的主机、端口或用户名,在任何 ssh 启动之前就会被拒绝,
因为保存的密码只送往登记它的那台机器。不要把密钥或密码放进任务消息。
只记录私钥路径,不记录私钥内容。不要把密钥或密码放进任务消息。
agent 也能登记机器。`ops_connection_add` 工具(raven-oncall 与 raven-code 通过
`tools.connectionAdd` 开启,其他产品关闭)接主人在对话里说的话——是这台电脑还是
另一台、叫什么、另一台的话地址是什么——用主人自己的 ssh 配置补上没说的端口、
用户名或密钥路径,先连上机器,连上了才写入。注册表里没有合适的机器时,agent
会问主人,而不是拿一条原始 ssh 命令自己找路进去。它从不索要密码:用密码登录的机器由主人
自己登记,在 Agent Hub 的**机器**标签里,或者用 `raven ops connection add --auth password`。
会问主人,而不是拿一条原始 ssh 命令自己找路进去。
`doctor` 校验注册表可用性,不会重新执行每台远程环境的连通测试。
`add --skip-probe` 不联系机器,并明确保留“未验证连接”状态。

View File

@ -96,7 +96,7 @@ following **tool arguments**, not a shell command or standalone config file:
},
{
"id": "readiness_summary",
"subagent": "Raven-General",
"subagent": "Raven",
"node_summary": "Synthesize readiness findings",
"depends_on": ["api_audit", "test_audit"],
"prompt_template": "Combine these findings into a prioritized review. Do not edit files. API: {{ api_audit.output }} Tests: {{ test_audit.output }}"
@ -126,9 +126,6 @@ parallel nodes do not imply separate worktrees or exclusive file locks.
| `skills` | Omitted: the agent's menu; `[]`: no skills; list: narrowed menu where supported |
| `mcps` | Omitted: the row's defaults; `[]`: no attached MCPs; list: replace the selection |
| `instance` | Reuse a sub-agent session, not a node output address |
| `routes` | Route name to condition. Makes this node a decision: the verdict call picks the route from its answer |
| `select` | `"one"` (default) or `"many"`: how many routes one answer may select |
| `when` | Guard. The node runs only if the condition holds once its dependencies settle |
The graph requires `task_summary` and `nodes`. `background` belongs to the
tool call; `confirm` is a graph-wide gate, defaulting to false. The model-facing
@ -143,85 +140,23 @@ a remote service. Prefer content forms when the backend has no local-file access
References to another node in the same graph must declare their dependency.
Earlier completed nodes in the same conversation can be referenced without
re-running them; the saved output must exist. Earlier failed, skipped,
canceled, interrupted, not-executed, or still-running nodes are not valid
inputs. Ids are case-folded for uniqueness and remain claimed after failure.
re-running them; the saved output must exist. Failed, skipped, canceled,
interrupted, or still-running nodes are not valid inputs. Ids are case-folded
for uniqueness and remain claimed after failure.
File references are confined to the working directory and the current
conversation's sub-agent history. They do not expose the whole Agent home,
memory store, skill tree, or another conversation. `@nodes/` names the current
conversation's flat node-artifact directory.
## Conditional branches
A graph can decide where it goes next. A node that declares **`routes`** is a
**decision node**: each route name maps to the condition, in plain words, under
which the node's answer selects that route. **`select`** says how many routes one
answer may select: `"one"`, the default where routes are given, or `"many"`, any
number including none. Any node, a decision node included, may carry **`when`**,
a guard over what the decision nodes before it chose.
The verdict call that checks a decision node's answer also picks its route. The
conditions are the graph author's criteria: they go to the judge and are not added
to the node's prompt, and the node's own text never selects a route.
| Field | Meaning |
| --- | --- |
| `routes` | Route name to condition. At least two routes for `select: "one"`, at least one for `"many"`; names use the node-id charset (letters, digits, `_`, `-`), no two may differ only in case, and `done` is reserved in any letter case |
| `select` | `"one"`: exactly one route, so give the decision a catch-all route for everything else. `"many"`: any number, none included. Only on a node with `routes` |
| `when` | Guard, read once every dependency has settled |
A guard's atoms are `<node>.<route>`, true when that decision node selected that
route, and `<node>.done`, true once it settled, whatever it chose. An atom names a
decision node of this graph that appears in the guarded node's own `depends_on`.
Atoms combine with `not`, `and`, `or`, and parentheses; `not` binds tightest, then
`and`, then `or`. Every decision node in a node's `depends_on` must appear in its
`when`; write `<node>.done` where the route does not matter. A node whose
dependencies in the graph were all left out is left out with them, so a branch
node needs no guard beyond naming any decision node it depends on. A node of
the branch that also depends on something outside it, the decision node included,
needs the branch's route in its own `when`, as `<node>.<route>` rather than
`<node>.done`, which holds whichever route is selected. A merge node that should
run on every route keeps `<node>.done`.
A node ends `not_executed` when its guard is false (`when_false`), when the guard
is unknown because a decision it names was never made (`when_unknown`), or when
every dependency it has in the graph was itself not executed
(`upstream_not_executed`). It is never dispatched and writes no output, and unlike
a skipped node it does not skip its dependents. A node of the same graph that
reads one receives this sentence where the output would have been:
```text
<This task is not executed and the output is missing, please go on without this output.>
```
The stand-in is for the same graph only: a later graph that names a node an
earlier run did not execute is refused, as it is for a failed node (see
[Node contract and data flow](#node-contract-and-data-flow)).
A node may not run when it has a `when` of its own, `<node>.done` included, or
when it depends on nodes of the graph that all may not run. When a template reads
such a node, the rendered prompt also carries a note naming those inputs. Raven
adds no titles of its own, so give each output that may be missing its own titled
block in the template. Read such a node with `{{ <id>.output }}`: a `ref:@nodes/`
path or `{"file": ...}` input aimed at its artifacts is refused at submission,
because a node that is not executed writes no file.
The check matches node ids without regard to case on every host, as the session's
node namespace does, so changing a filename's case cannot evade it.
A decision node whose route cannot be established fails, with the reason recorded
on the node; it does not fall back to a default route, and its dependents are
skipped. A host with no model available to judge refuses a graph that declares
routes before anything is dispatched.
## Scheduling and shared limits
Before dispatch, Raven checks required fields, ids, dependencies, cycles,
input contracts, routes and guards, path confinement, and backend
capabilities. Independent ready nodes run concurrently, sharing the host's
semaphore with `spawn` and other DAGs. `agents.defaults.maxConcurrentSubagents`
defaults to 8; `agents.defaults.maxSubagentSpawnsPerHour` defaults to 30 per
session and also bounds repeated DAG submissions.
input contracts, path confinement, and backend capabilities. Independent ready
nodes run concurrently, sharing the host's semaphore with `spawn` and other
DAGs. `agents.defaults.maxConcurrentSubagents` defaults to 8;
`agents.defaults.maxSubagentSpawnsPerHour` defaults to 30 per session and also
bounds repeated DAG submissions.
Nodes sharing an `instance` are serialized. Add dependencies when their order
matters; a shared instance alone is not a deterministic ordering rule. Backends
@ -261,17 +196,14 @@ running a graph with external effects.
| `exception` | Unsuccessful work awaiting a continue, abandon, or replan decision |
| `failed` | Failure is final for this node |
| `skipped` | A prerequisite failed or execution stopped before dispatch |
| `not_executed` | A branch left the node out: its guard was false or unknown, or none of its dependencies in the graph was executed. Never dispatched, no output |
| `cancelled` | The active node was canceled |
| `interrupted` | A history reader found unfinished recorded work without a live run |
A model-based **verdict** checks whether the returned output actually
accomplished the node's prompt, using output, transcript tail, and available
transport stop reason. A normal process return alone is not enough. However,
verdicts are a quality check, not a safety gate: for an ordinary node, a judge
failure/timeout falls back to accepting a normal backend return. A decision node
has no route to fall back to, so it fails instead (see
[Conditional branches](#conditional-branches)).
By default, a model-based **verdict** checks whether the returned output
actually accomplished the node's prompt, using output, transcript tail, and
available transport stop reason. A normal process return alone is not enough.
However, verdicts are a quality check, not a safety gate: disabling the judge,
or a judge failure/timeout, falls back to accepting a normal backend return.
For an exception, `resolve_dag_node` can continue with corrective instructions,
abandon the node, or replan. Replanning finalizes the old run and starts a new
@ -279,11 +211,11 @@ one; reuse completed outputs by reference and assign fresh ids to replacement
nodes. Failed prerequisites eventually skip their dependents; independent
branches need not be discarded.
The `subagentDag` settings default to a 180-second judge timeout, a 600-second
background adjudication window, and two continuations per node. These bound
additional model calls and waiting; they do not prove an external action is safe
to retry. Check for already-created files, messages, or remote jobs before
continuing a node with side effects.
The `subagentDag` settings default to enabled verdicts, a 180-second judge
timeout, a 600-second background adjudication window, and two continuations
per node. These bound additional model calls and waiting; they do not prove an
external action is safe to retry. Check for already-created files, messages,
or remote jobs before continuing a node with side effects.
## Inspect and recover

View File

@ -82,7 +82,7 @@ Charter 不是操作系统沙箱,也不是 fail-closed 安全边界;应独
},
{
"id": "readiness_summary",
"subagent": "Raven-General",
"subagent": "Raven",
"node_summary": "Synthesize readiness findings",
"depends_on": ["api_audit", "test_audit"],
"prompt_template": "Combine these findings into a prioritized review. Do not edit files. API: {{ api_audit.output }} Tests: {{ test_audit.output }}"
@ -111,9 +111,6 @@ Charter 不是操作系统沙箱,也不是 fail-closed 安全边界;应独
| `skills` | 省略:Agent 自身菜单;`[]`:无技能;列表:在支持时收窄菜单 |
| `mcps` | 省略:配置行默认值;`[]`:不附加 MCP;列表:替换选择 |
| `instance` | 复用子 Agent 会话,不是节点输出地址 |
| `routes` | 路由名到条件的映射。使该节点成为决策节点:路由由裁决调用根据其答案选出 |
| `select` | `"one"`(默认)或 `"many"`:一次答案可选多少条路由 |
| `when` | 执行条件。依赖全部有结果后条件成立,该节点才运行 |
图要求 `task_summary` 和 `nodes`。`background` 是工具调用参数;`confirm` 是整图
确认开关,默认 false。面向模型的 schema 使用 snake_case,保存的 playbook 也接受
@ -125,66 +122,16 @@ camelCase 节点字段。未知节点字段会被拒绝,不会静默成为指
能力时,优先使用内容形式。
引用同一张图中的节点时必须声明依赖。可以直接引用同一对话中早先完成的节点,无需
重跑,但其保存输出必须存在。早先任务中失败、跳过、取消、中断、未执行或仍在运行的
节点不是有效输入。Id 的唯一性比较忽略大小写,失败后也不会释放 id。
重跑,但其保存输出必须存在。失败、跳过、取消、中断或仍在运行的节点不是有效输入。
Id 的唯一性比较忽略大小写,失败后也不会释放 id。
文件引用只允许落在工作目录和当前对话的子 Agent 历史内,不暴露整个 Agent home、
记忆、技能或其他对话。`@nodes/` 表示当前对话的扁平节点产物目录。
## 条件分支 { #conditional-branches }
图可以自行决定下一步走向。声明 **`routes`** 的节点是**决策节点**:每个路由名对应一个
条件,用直白的话写出该节点的答案在什么情况下选中这条路由。**`select`** 指定一次答案
可以选中多少条路由:`"one"`(给出 `routes` 时的默认值),或 `"many"`(任意条数,也可以
一条都不选)。任何节点(包括决策节点)都可以带 **`when`**,即依据它之前的决策节点所选
结果设定的执行条件。
检查决策节点答案的裁决调用,同时为它选出路由。条件由图的作者编写,只交给 judge,
不会写进该节点的 prompt;节点自己输出的内容不会选中任何路由。
| 字段 | 含义 |
| --- | --- |
| `routes` | 路由名到条件。`select: "one"` 至少两条路由,`"many"` 至少一条;路由名沿用节点 id 字符集(字母、数字、`_`、`-`),同一节点的两个路由名不能只差大小写,`done` 不论大小写均为保留名 |
| `select` | `"one"`:恰好一条,因此要为其余情况留一条兜底路由。`"many"`:任意条数,可以一条都没有。只用于声明了 `routes` 的节点 |
| `when` | 执行条件,在所有依赖都有了结果之后判断 |
执行条件的原子有两种:`<node>.<route>`,该决策节点选中了这条路由时为真;`<node>.done`,
该决策节点已有结果时为真,不论它选了哪条路由。原子只能指向本图中、且出现在该节点
`depends_on` 里的决策节点,用 `not`、`and`、`or` 和括号组合;`not` 结合最紧,其次是
`and`,再次是 `or`。节点 `depends_on` 中的每个决策节点都必须出现在它的 `when` 里;
不关心选了哪条路由时写 `<node>.done`。一个节点在图内的依赖若全部未执行,
它也随之不执行,因此分支内的节点除了写明它依赖的决策节点之外,无需再写别的执行条件。
若它还依赖分支外的节点(包括决策节点本身),就要在自己的 `when` 里写明该分支的路由
`<node>.<route>`,而不是 `<node>.done`:后者不论选中哪条路由都成立。
汇合各分支、需要在每条路由上都运行的节点,则保留 `<node>.done`。
以下三种情况下,节点以 `not_executed`(未执行)结束:执行条件为假(`when_false`);
执行条件取值未知,因为它引用的决策从未做出(`when_unknown`);或它在图内的每个依赖
都未执行(`upstream_not_executed`)。未执行的节点不会被调度,也不产生输出;与
`skipped` 不同,它不会连带跳过自己的下游。同一张图中读取它的节点,
会在原本放输出的位置读到这一句:
```text
<This task is not executed and the output is missing, please go on without this output.>
```
这一替代句只用于同一张图:之后的图引用早先运行中未执行的节点会被拒绝,
与引用失败的节点相同(见[节点契约与数据流](#node-contract-and-data-flow))。
节点自身带有 `when`(包括 `<node>.done`),或它依赖的图内节点全都可能不执行时,它就
可能不执行。模板引用了这类节点时,渲染后的 prompt 还会附上一段说明,列出这些可能缺失
的输入。Raven 不会自行添加标题,请在模板中为每个可能缺失的输出各写一个带标题的块。
读取这类节点请用 `{{ <id>.output }}`:指向其产物的 `ref:@nodes/` 路径或 `{"file": ...}`
输入会在提交时被拒绝,因为未执行的节点不会写出文件。
此检查在所有系统上都按节点命名空间的不区分大小写规则匹配 ID,因此改变文件名大小写也会被识别。
无法确定路由的决策节点直接失败,原因记录在该节点上;它不会退回某条默认路由,其下游会被
跳过。宿主没有可用于判断的模型时,声明了 `routes` 的图会在调度任何节点之前被拒绝。
## 调度与共享限制 { #scheduling-and-shared-limits }
调度前 Raven 检查必填字段、id、依赖、循环、输入契约、路由与执行条件、路径边界和
后端能力。已就绪的独立节点可并发,并与 `spawn` 和其他 DAG 共享宿主信号量。
调度前 Raven 检查必填字段、id、依赖、循环、输入契约、路径边界和后端能力。已就绪的
独立节点可并发,并与 `spawn` 和其他 DAG 共享宿主信号量。
`agents.defaults.maxConcurrentSubagents` 默认 8;
`agents.defaults.maxSubagentSpawnsPerHour` 默认每会话 30,也限制重复提交 DAG。
@ -217,20 +164,19 @@ camelCase 节点字段。未知节点字段会被拒绝,不会静默成为指
| `exception` | 工作未成功,等待继续、放弃或重新规划 |
| `failed` | 该节点最终失败 |
| `skipped` | 前置失败,或调度前执行已停止 |
| `not_executed` | 分支没有走到该节点:条件为假或未知,或它在图内的依赖全部没有执行。不会被调度,也没有输出 |
| `cancelled` | 活动节点被取消 |
| `interrupted` | 历史读取发现未完成记录,但已无活动运行 |
模型 **verdict(裁决)** 根据输出、transcript 尾部及可用的传输 stop reason 判断节点
是否真正完成 prompt 的任务;进程正常返回本身不足以证明成功。但 verdict 是质量检查,
不是安全门:普通节点在 judge 失败/超时时,会退回接受正常后端返回的行为。决策节点没有
可退回的路由,此时直接失败(见[条件分支](#conditional-branches))。
默认情况下,模型 **verdict(裁决)** 根据输出、transcript 尾部及可用的传输 stop
reason 判断节点是否真正完成 prompt 的任务;进程正常返回本身不足以证明成功。但
verdict 是质量检查,不是安全门:关闭 judge,或 judge 失败/超时时,会退回接受正常
后端返回的行为。
进入 exception 后,`resolve_dag_node` 可以提供修正指令继续、放弃节点,或重新规划。
重新规划会结束旧运行并启动新运行;按引用复用已完成输出,为替代节点分配新 id。
前置节点最终失败会使依赖节点跳过,不必丢弃独立分支。
`subagentDag` 默认 judge 超时为 180 秒,后台裁决窗口 600 秒,每节点
`subagentDag` 默认启用 verdict,judge 超时为 180 秒,后台裁决窗口 600 秒,每节点
最多两次继续。这些设置限制额外模型调用和等待,不证明外部动作可安全重试。继续有
副作用的节点前,应检查是否已创建文件、发送消息或启动远程任务。

View File

@ -161,13 +161,9 @@ scopes. Prompt-injection labels mark tool results and sub-agent output as
untrusted data; they do not make model judgement infallible. Check credentials
and network reach separately from prompt instructions.
ACP redacts recognized secrets in outgoing arguments and permission
descriptions, and in the errors Raven itself composes. Content that comes back
from another agent -- a sub-agent's answer, a Mirasim turn, an A2A peer's reply
-- is kept as that agent sent it, on the policy that the agent producing it
decides what may be redacted; a credential such a reply echoes is therefore
left in place. A2A turn failures expose a fixed message and retain the detailed
exception in local logs. Neither mechanism guarantees every log or
ACP redacts recognized secrets in outgoing arguments, previews, errors, and
permission descriptions. A2A turn failures expose a fixed message and retain
the detailed exception in local logs. Neither mechanism guarantees every log or
transcript is safe to publish. Keep secrets out of task prompts where possible,
and review/redact diagnostic exports before sharing.

View File

@ -128,10 +128,8 @@ Raven 的权限门管理自身注册表调用,不是外部 Agent 进程内每
Prompt injection 标签把工具结果和子 Agent 输出标为不可信数据,但不能使模型判断
永不出错。凭据与网络可达范围应独立于 prompt 指令检查。
ACP 会脱敏出站参数、权限描述,以及 Raven 自己拼出的错误中可识别的秘密。由其他
Agent 返回的内容——子 Agent 的答复、Mirasim 的一轮回复、A2A 对端的回复——按发送方
Agent 的原文保留,脱敏与否由产生该内容的 Agent 决定;因此这类回复里回显的凭据会
原样保留。A2A 轮次失败只暴露固定消息,详细异常留在本地日志。两者都不保证每份日志和 transcript 可安全公开。尽量
ACP 会脱敏出站参数、预览、错误和权限描述中可识别的秘密。A2A 轮次失败只暴露固定
消息,详细异常留在本地日志。两者都不保证每份日志和 transcript 可安全公开。尽量
不要把秘密放进任务 prompt,分享诊断导出前应审阅并脱敏。
## 排查拒绝或停滞的动作 { #diagnose-a-refused-or-stalled-action }

View File

@ -78,13 +78,13 @@ params:
description: The brief to inspect
nodes:
- id: inspect
subagent: Raven-General
subagent: raven
nodeSummary: Identify gaps
skills: []
mcps: []
promptTemplate: "Find gaps in this brief: {{ params.brief }}. Do not edit files or contact external services."
- id: summarize
subagent: Raven-General
subagent: raven
nodeSummary: Prioritize feedback
dependsOn: [inspect]
skills: []
@ -93,7 +93,7 @@ nodes:
```
````
`Raven-General` is the generic built-in agent. To use Raven-Code or another specialized
`raven` is the generic built-in agent. To use Raven-Code or another specialized
agent, substitute a registered name and verify its setup through
[Agent Integrations](agent-integrations.md). A stored Playbook uses the
underlying agent registry, not temporary worker labels advertised for an

View File

@ -72,13 +72,13 @@ params:
description: The brief to inspect
nodes:
- id: inspect
subagent: Raven-General
subagent: raven
nodeSummary: Identify gaps
skills: []
mcps: []
promptTemplate: "Find gaps in this brief: {{ params.brief }}. Do not edit files or contact external services."
- id: summarize
subagent: Raven-General
subagent: raven
nodeSummary: Prioritize feedback
dependsOn: [inspect]
skills: []
@ -87,7 +87,7 @@ nodes:
```
````
`Raven-General` 是通用内置 Agent。如需 Raven-Code 等专用 Agent,替换为已注册的名称,
`raven` 是通用内置 Agent。如需 Raven-Code 等专用 Agent,替换为已注册的名称,
并按[Agent 集成](agent-integrations.md)检查配置。保存的 Playbook 使用底层
Agent registry,而不是临时组图时向模型展示的 worker label。

View File

@ -8,7 +8,7 @@ Key directories:
```text
raven/ # Shared runtime, feature engines, and CLI/RPC/ACP surfaces
agents/ # Specialized agents assembled from installed Raven and plugins
plugins-dist/ # everos-memory, everos-cloud-memory, design-engine, and ppt-engine distributions
plugins-dist/ # everos-memory, design-engine, and ppt-engine distributions
ui-web/ # Browser UI, also used by the desktop window
ui-tui/ # React/Ink terminal UI
rpc-schema/ # Shared OpenRPC contract for interactive clients
@ -52,7 +52,6 @@ repository's commit conventions.
| `market` | PlugHub catalog, trust checks, installation, and contribution ledgers |
| `mcp` | MCP server connections and tool integration |
| `memory_engine` | Memory recall and consolidation, local skills, and SkillForge retrieval |
| `node` | The Raven node: Raven's own file tools and the agents it dispatches, run on a registered machine over one ssh link |
| `observability` | Span semantics, attribute extraction, and usage attribution |
| `ops` | Local and remote machine registry and execution transports |
| `permissions` | Tool-call decisions: allow, request approval, or deny |

View File

@ -7,7 +7,7 @@
```text
raven/ # 共享运行时、功能引擎,以及 CLI/RPC/ACP 接口层
agents/ # 由已安装的 Raven 与插件组装而成的专用 Agent
plugins-dist/ # everos-memory、everos-cloud-memory、design-engine 和 ppt-engine 发行包
plugins-dist/ # everos-memory、design-engine 和 ppt-engine 发行包
ui-web/ # 浏览器界面,桌面窗口也使用同一页面
ui-tui/ # React/Ink 终端界面
rpc-schema/ # 交互式客户端共用的 OpenRPC 契约

View File

@ -52,191 +52,10 @@ raven trajectory report-bug ATTEMPT_ID \
--actual "The next request has no tool result"
```
This creates a local record/package. It does not open a GitHub issue, and it
uploads the package only when `RAVEN_BUGREPORT_URL` names a Bug Report Receiver
(see [Send and receive bug reports](#send-and-receive-bug-reports)); the
receipt is then written into the record. Review flagged items and the package
before sharing. `--yes` is not sensitive-data risk consent. Do not routinely
bypass findings with `--accept-risk` or declare every token harmless.
The WebUI's **Report a problem** runs the same pipeline on the turns you pick
in a conversation, with the decisions made on a page instead of a prompt; see
[Export and report a problem](webui.md#export-and-report-a-problem).
### Remembered redaction decisions
Every keep or replace answer you give in the review is remembered on this
machine, in `redaction_history.json` under the Raven home (`~/.raven`, or
`RAVEN_HOME` when set). The next report replays it: a value you already decided
is listed as decided from your redaction history instead of being asked again,
and a run without a TTY no longer needs `--keep-findings` or `--redact-findings`
for those values (`--accept-risk` is still required). Only a hash of each value
and a masked sample are stored. Private-key items are always asked, and
decisions made by the blanket `--keep-findings` / `--redact-findings` flags are
never remembered.
```bash
raven trajectory report-bug ATTEMPT_ID -d "..." --review-all # decide every item again
raven trajectory redaction-history list # what is remembered
raven trajectory redaction-history forget 3f9a1c2b7d4e # drop one decision by id
raven trajectory redaction-history clear --yes # drop all of them
```
A report made in the WebUI follows a different rule on purpose: every
decision on its decisions page is remembered, including the default "keep all"
and the bulk buttons, with `web` as its source, because the page shows every
value it asks about.
Set `RAVEN_BUGREPORT_REDACTION_HISTORY=off` to neither replay nor record
decisions. A history file that cannot be read is backed up next to it before
the next save; until then every item is asked.
## Send and receive bug reports
### The receiver
A Bug Report Receiver is a small HTTP service that takes Bug Report Packages
in, checks them, stores them by day, and answers with a receipt. It takes only
uploads that answer its challenge (see [The upload challenge](#the-upload-challenge)),
and it serves no listing or download. Who can reach it is still decided by the
network it listens on.
```bash
raven trajectory receiver --save-dir /srv/raven-bugreports
```
| Option | Default | Meaning |
| --- | --- | --- |
| `--save-dir` | required | Directory that receives packages; created with mode 0700 |
| `--host` / `--port` | `127.0.0.1` / `18795` | Bind address; `--port 0` picks a free port and prints it |
| `--trusted-proxy CIDR` | none | A proxy whose `X-Forwarded-For` is believed (repeatable) |
| `--max-package-mib` / `--max-unpacked-mib` | 64 / 256 | Largest package, and largest decompressed volume inspected |
| `--max-daily-mib` / `--max-daily-count` | 2048 / 500 | What one UTC day may accept, in bytes and in packages |
| `--min-free-mib` | 1024 | Free disk space the receiver keeps |
| `--rate-burst` / `--rate-per-10min` | 10 / 30 | Uploads one address may make at once, and regains per ten minutes; `--rate-burst 0` disables rate limiting |
| `--concurrency` | 4 | Uploads handled at the same time; others get 503 |
| `--idle-timeout` / `--total-timeout` | 30 / 600 | Seconds without body data, and seconds for one upload in total |
Packages land as `<save-dir>/<YYYY-MM-DD>/<report-id>.tar.gz`, the original
bytes untouched, next to a `<report-id>.json` sidecar that holds the receipt,
the sender's address, and a triage digest of `bugreport.json` (reporter,
description, severity, completeness, redaction classification) so a reader can
sort packages without unpacking them. The digest keeps the first 1000
characters of each field and at most 16 path notices, and a sidecar counts
against the daily byte budget together with its package. The day is the UTC day the upload was
admitted on: a package that finishes after midnight stays in the day it
started, and its sidecar's `received_at` records when it actually landed. The
same package sent twice returns the receipt already stored; a different
package under the same report id is refused. Retention is the operator's job
-- the per-day directories make `find -mtime` cleanup trivial.
### The upload challenge
The receiver answers four requests:
| Request | Answer |
| --- | --- |
| `GET /v1/hello` | `{"service": "raven-bug-report-receiver", "protocol": 1}`; clients ask it before a report starts |
| `POST /v1/challenge` | `{"challenge": "...", "expires_in": 300}`: a fresh challenge for one upload |
| `POST /v1/bugreports` | the upload, carrying `X-Raven-Challenge` and `X-Raven-Response` next to the report id and sha256 |
| `GET /healthz` | `{"status": "ok"}` for an operator's liveness check |
A challenge is sealed with a key the receiver holds only in memory, so it keeps
no table of them and a restart retires them all; it is valid for 300 seconds
and is not used up. A Raven client answers it with an HMAC, under a constant
built into Raven, of the challenge together with the package's report id,
sha256 and size. The receiver checks both headers before it reads the body: a
missing, forged, expired or mismatched answer gets `401` with
`WWW-Authenticate: Raven-Challenge` and the error `unauthorized` (or
`challenge_expired`), nothing is written, and the attempt still counts against
the sender's rate limit.
This is a shallow gate, not authentication. The constant is published with the
source and is not configurable; it identifies nobody.
| Who tries | What happens |
| --- | --- |
| `curl`, a script or a scanner posting a file | `401`, nothing stored |
| A captured upload replayed with another package | `401`: the answer is bound to the report id, digest and size |
| A captured upload replayed as it was | at most the receipt already stored for that package |
| Someone who has read Raven's source (it is public) | not stopped, by design |
| Raven itself sending junk | bounded by the package checks, rate limits and daily budgets |
Upgrade the receiver and its clients together. An older receiver has no
`/v1/hello` or `/v1/challenge`: a newer client says it does not answer as a
Raven receiver before a report starts, and an upload fails with "the receiver
does not issue challenges"; the package is kept either way.
### Deployment
The receiver speaks plain HTTP and binds loopback by default. Anything beyond
this machine belongs behind a TLS-terminating proxy; never expose the port
itself to the public internet. An nginx location that works -- it covers all of
`/v1/`, since clients ask `/v1/hello` and `/v1/challenge` as well as uploading:
```nginx
location /v1/ {
proxy_pass http://127.0.0.1:18795;
proxy_request_buffering off;
client_max_body_size 64m; # at least --max-package-mib
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```
Add `--trusted-proxy 127.0.0.0/8` (or the proxy's network) so rate limiting
and the sidecar's `client` address follow the real sender instead of the proxy;
without it every upload through the proxy shares one bucket. `GET /healthz`
answers `{"status": "ok"}` for liveness checks; clients probe `/v1/hello`
instead, under their base URL. Run the receiver as an unprivileged
user and treat `--save-dir` as holding sensitive material: packages are
redacted for credentials, not anonymized.
### Telling clients where to send
`report-bug`, the browser's *Report a bug*, and `raven trajectory
upload-bug-report` all read one setting:
| `RAVEN_BUGREPORT_URL` | Effect |
| --- | --- |
| not set | the build's default (empty in this repository: packages stay local) |
| set to an empty value | uploading off, even in a build that ships a default |
| `https://ops.example.com/raven-bugreports` | upload there; a path prefix is fine, the client adds `/v1/bugreports`; a query, a fragment or credentials in the URL are refused |
| `http://127.0.0.1:18795` | plain HTTP is accepted on this machine only |
| `http://10.1.2.3:18795` | refused unless `RAVEN_BUGREPORT_ALLOW_HTTP=1` says plaintext on the network is acceptable |
A misconfigured URL stops `report-bug` before anything is collected. With a
URL in place the confirmation screen says `Will upload to ...`, the package is
sent as soon as it lands, and the receipt is written into the record. When
the upload fails the package is kept and the record says so; send it again
with:
```bash
raven trajectory upload-bug-report REPORT_ID
```
With a URL in place, `report-bug` and the browser's *Report a bug* first ask
the receiver's `/v1/hello`, before anything is collected. When it does not
answer, the reason is printed, and then:
- on a TTY without `--yes`, you are asked whether to continue (default no;
declining collects and pins nothing);
- with `--yes`, on a TTY or not, the command says it is continuing and goes
on; if the upload then fails, the package is kept for `upload-bug-report`;
- without a TTY and without `--yes`, the existing rule stops the command
first (`--yes is required without a TTY`): nothing is probed or packaged.
The browser's *Report a bug* runs on a TTY and asks the same question; Esc
counts as no. The WebUI's *Report a problem* checks when its wizard opens; see
[Export and report a problem](webui.md#export-and-report-a-problem).
`upload-bug-report` does not probe: the upload itself names what went wrong.
### What the receiver checks
Before a package is stored its size, gzip and tar framing, member names and
types, the manifest's hashes, and the `needs_review`/`risk_accepted`
invariant are all verified in a stream, without extracting anything. The
receiver does not scan content for secrets: redaction remains the sender's
responsibility, and what it reports on the confirmation screen is what ships.
This creates a local record/package; it does not open a GitHub issue or upload
the report. Review flagged items and the package before sharing.
`--yes` is not sensitive-data risk consent. Do not routinely bypass findings
with `--accept-risk` or declare every token harmless.
## Replay the harness without repeating actions
@ -348,5 +167,4 @@ delete exported copies or redact existing bundles. Treat evidence retention,
sharing, and deletion as separate decisions.
Implementation: `raven/trajectory/replay.py`, `regression.py`, `cassette.py`,
`redact.py`, `package_check.py`, `receiver.py`, `upload.py`, and
`raven/cli/trajectory_commands.py`.
`redact.py`, and `raven/cli/trajectory_commands.py`.

View File

@ -45,163 +45,10 @@ raven trajectory report-bug ATTEMPT_ID \
--actual "The next request has no tool result"
```
它创建本地记录/包,不会创建 GitHub issue;只有当 `RAVEN_BUGREPORT_URL` 指向一个
Bug Report Receiver 时才上传(见[发送与接收问题报告](#send-and-receive-bug-reports)),
回执随后写入记录。分享前检查 findings 和包内容。
它创建本地记录/包,不会创建 GitHub issue 或上传报告。分享前检查 findings 和包内容。
`--yes` 不代表敏感数据风险授权,不应习惯性使用 `--accept-risk` 绕过,
或宣称所有 token 都无害。
WebUI 中的**问题报告**对会话里选中的轮次运行同一条流程,只是决定在页面上做,而不是在终端提示里;
见[导出与问题报告](webui.md#export-and-report-a-problem)。
### 记住的脱敏裁决 { #remembered-redaction-decisions }
你在审核中给出的每个"保留"或"替换"回答都会记在本机 Raven home(`~/.raven`,
设置了 `RAVEN_HOME` 时为该目录)下的 `redaction_history.json`。下一次报告会回放
这些记录:已经裁决过的值会列为"由脱敏裁决历史决定",不再重复询问;没有 TTY 的
运行也不再需要为这些值传 `--keep-findings` 或 `--redact-findings`(仍需
`--accept-risk`)。文件里只保存每个值的哈希和掩码样本。私钥条目每次都会询问,
通过 `--keep-findings` / `--redact-findings` 整批做出的决定不会被记住。
```bash
raven trajectory report-bug ATTEMPT_ID -d "..." --review-all # decide every item again
raven trajectory redaction-history list # what is remembered
raven trajectory redaction-history forget 3f9a1c2b7d4e # drop one decision by id
raven trajectory redaction-history clear --yes # drop all of them
```
WebUI 中的报告有意采用不同的规则:决策页上的每个决定都会被记住,包括默认的"全部保持"和批量按钮,
来源记为 `web`,因为页面把它询问的每个值都展示给了用户。
设置 `RAVEN_BUGREPORT_REDACTION_HISTORY=off` 可既不回放也不记录。读不了的历史
文件会在下一次保存前备份到同目录;在那之前每个条目都会询问。
## 发送与接收问题报告 { #send-and-receive-bug-reports }
### 接收器 { #the-receiver }
Bug Report Receiver 是一个小型 HTTP 服务:接收 Bug Report Package、校验、按日
落盘、返回回执。它只接收答对其挑战的上传(见[上传挑战](#the-upload-challenge)),
不提供列表或下载。谁能连上它,仍由它监听的网络决定。
```bash
raven trajectory receiver --save-dir /srv/raven-bugreports
```
| 选项 | 默认 | 含义 |
| --- | --- | --- |
| `--save-dir` | 必填 | 接收包的目录;以 0700 创建 |
| `--host` / `--port` | `127.0.0.1` / `18795` | 绑定地址;`--port 0` 自动选端口并打印 |
| `--trusted-proxy CIDR` | 无 | 可信反代网段,其 `X-Forwarded-For` 才被采信(可重复) |
| `--max-package-mib` / `--max-unpacked-mib` | 64 / 256 | 最大包体,以及校验时解压的最大体积 |
| `--max-daily-mib` / `--max-daily-count` | 2048 / 500 | 一个 UTC 日可接收的字节数与包数 |
| `--min-free-mib` | 1024 | 保留的磁盘剩余空间 |
| `--rate-burst` / `--rate-per-10min` | 10 / 30 | 一个地址可连续上传的次数,以及每十分钟恢复的次数;`--rate-burst 0` 关闭限速 |
| `--concurrency` | 4 | 同时处理的上传数;超出返回 503 |
| `--idle-timeout` / `--total-timeout` | 30 / 600 | 无 body 数据的秒数上限,以及单次上传的总秒数上限 |
包以原始字节落在 `<save-dir>/<YYYY-MM-DD>/<report-id>.tar.gz`,旁边的
`<report-id>.json` sidecar 保存回执、发送方地址和 `bugreport.json` 的分诊摘要
(reporter、描述、严重程度、完整度、脱敏分类),读者不解包即可分拣。摘要只保留
每个字段的前 1000 个字符和至多 16 条路径提示;sidecar 与它的包一起计入每日字节
预算。日期是上传
被准入的 UTC 日:跨午夜才完成的包留在开始的那一天,sidecar 的 `received_at` 记
录真实落地时刻。同一个包再发一次返回已存的回执;同一 report id 的不同内容会被
拒绝。保留与清理由运维负责——按日的目录让 `find -mtime` 式清理很简单。
### 上传挑战 { #the-upload-challenge }
接收器响应四种请求:
| 请求 | 应答 |
| --- | --- |
| `GET /v1/hello` | `{"service": "raven-bug-report-receiver", "protocol": 1}`;客户端在报告开始前用它探测 |
| `POST /v1/challenge` | `{"challenge": "...", "expires_in": 300}`:为一次上传签发的新挑战 |
| `POST /v1/bugreports` | 上传,在 report id 与 sha256 之外带上 `X-Raven-Challenge` 和 `X-Raven-Response` |
| `GET /healthz` | `{"status": "ok"}`,供运维探活 |
挑战由接收器只保存在内存里的密钥签名,所以接收器不需要记录发出过哪些挑战,重启后
旧挑战全部失效;挑战在 300 秒内有效,可以重复使用。Raven 客户端用内置在 Raven 中
的常量,对"挑战 + 包的 report id、sha256 与大小"计算 HMAC 作为应答。接收器在读取
body 之前就校验这两个头:缺失、伪造、过期或与包不符的应答一律返回 `401`,带
`WWW-Authenticate: Raven-Challenge`,错误码为 `unauthorized`(或
`challenge_expired`);不写入任何文件,但这次尝试仍计入该地址的限速。
这是一道浅层门槛,不是身份鉴权:那个常量随源码公开、不可配置,也不标识任何人。
| 谁在尝试 | 结果 |
| --- | --- |
| 用 `curl`、脚本或扫描器直接发文件 | `401`,不落盘 |
| 抓到一次上传,换一个包重放 | `401`:应答绑定了 report id、摘要和大小 |
| 抓到一次上传,原样重放 | 至多拿到该包已存的回执 |
| 读过 Raven 源码的人(仓库是公开的) | 挡不住,这是预期的 |
| 用 Raven 本身发送垃圾 | 由包校验、限速和每日预算约束 |
接收器和客户端要一起升级。较旧的接收器没有 `/v1/hello` 与 `/v1/challenge`:新客户端
会在报告开始前提示对方不是 Raven 接收器,上传时报"the receiver does not issue
challenges";两种情况下包都会保留。
### 部署 { #deployment }
接收器只说明文 HTTP,默认只绑 loopback。要让本机以外访问,必须放在终止 TLS 的
反代之后;绝不要把端口直接暴露到公网。可用的 nginx location——它覆盖整个
`/v1/`,因为客户端除了上传,还会请求 `/v1/hello` 和 `/v1/challenge`:
```nginx
location /v1/ {
proxy_pass http://127.0.0.1:18795;
proxy_request_buffering off;
client_max_body_size 64m; # 不小于 --max-package-mib
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```
加上 `--trusted-proxy 127.0.0.0/8`(或反代所在网段),限速和 sidecar 的 `client`
地址才按真实发送方计,否则经反代的所有上传共用一个桶。`GET /healthz` 返回
`{"status": "ok"}` 供运维探活;客户端探测的是其 base URL 下的 `/v1/hello`。用非特权账号运行,并把 `--save-dir` 当作敏感材料的
目录:包只做了凭据脱敏,没有匿名化。
### 告诉客户端往哪发 { #telling-clients-where-to-send }
`report-bug`、浏览器里的 *Report a bug* 和 `raven trajectory upload-bug-report`
读同一个设置:
| `RAVEN_BUGREPORT_URL` | 效果 |
| --- | --- |
| 未设置 | 用构建内置的默认值(本仓库为空:包留在本机) |
| 设为空值 | 关闭上传,即使构建内置了默认地址 |
| `https://ops.example.com/raven-bugreports` | 上传到那里;可以带路径前缀,客户端自己拼 `/v1/bugreports`;URL 里带查询串、片段或凭据会被拒绝 |
| `http://127.0.0.1:18795` | 明文 HTTP 只在本机被接受 |
| `http://10.1.2.3:18795` | 除非 `RAVEN_BUGREPORT_ALLOW_HTTP=1` 声明网络上的明文可接受,否则拒绝 |
URL 配置错误会让 `report-bug` 在采集任何东西之前停下。配置就绪后,确认页会显示
`Will upload to ...`,包一落地就发送,回执写入记录。上传失败时包保留、记录写明
原因,用下面的命令重传:
```bash
raven trajectory upload-bug-report REPORT_ID
```
配置了 URL 时,`report-bug` 与浏览器里的 *Report a bug* 会在采集任何东西之前先请求
接收器的 `/v1/hello`。没有应答时先打印原因,然后:
- 有 TTY 且未给 `--yes`:询问是否继续(默认否;选否则什么都不采集、不 pin);
- 给了 `--yes`(有没有 TTY 都一样):说明正在继续并照常进行;之后若上传失败,包会
保留,可用 `upload-bug-report` 重传;
- 没有 TTY 且未给 `--yes`:按既有规则先以 `--yes is required without a TTY` 停下,
不探测也不打包。
浏览器里的 *Report a bug* 运行在 TTY 上,同样询问;按 Esc 等同于否。WebUI 的
*Report a problem* 在向导打开时检查,见
[导出与问题报告](webui.md#export-and-report-a-problem)。`upload-bug-report` 不探测:
上传本身就会说明出了什么问题。
### 接收器校验什么 { #what-the-receiver-checks }
存入之前,包的大小、gzip 与 tar 结构、成员名与类型、清单哈希,以及
`needs_review`/`risk_accepted` 不变量都以流式方式校验,不解包任何内容。接收器
不扫描内容里的秘密:脱敏仍是发送方的责任,确认页上展示的就是外发的。
## 回放 Harness,而不重复动作 { #replay-the-harness-without-repeating-actions }
```bash
@ -299,5 +146,4 @@ System prompt 装配应使用针对性单元测试;provider 行为、浏览器
也不会给既有 bundle 脱敏。证据保留、分享和删除是不同决策。
实现位于 `raven/trajectory/replay.py`、`regression.py`、`cassette.py`、
`redact.py`、`package_check.py`、`receiver.py`、`upload.py` 和
`raven/cli/trajectory_commands.py`。
`redact.py` 和 `raven/cli/trajectory_commands.py`。

View File

@ -12,92 +12,20 @@ This command opens the WebUI in your browser and starts Raven in the
background. Raven keeps running after you close the browser. To stop the
service, run `raven web --stop`.
## Trajectory view
## Developer launch
Once a conversation has content, a trajectory toggle appears in the chat
header, to the left of the workspace panel button. The trajectory view lists
```bash
raven web --dev
```
`raven --dev` and `raven web --dev` start the same service with the
trajectory view enabled: a toggle appears in the chat header, to the left
of the workspace panel button, once a conversation has content. It lists
every recorded step of that conversation (inputs, model calls, tool calls,
replies) with its timing, opens the details of any step, and draws a
duration bar above the list.
## Export and report a problem
The three-dot menu in the top-right corner of the chat header (the desk
launcher sits just left of it) acts on the open conversation. It is disabled on
a new task that has no content yet.
**Export** packs the turns you pick into a `.tar.gz` that the browser
downloads. A turn brings the sub-agents it started with it; a turn that is
still running cannot be picked. You can rename the file before exporting.
!!! warning
The export is the raw trajectory and is not redacted. It can contain
keys, tokens and other secrets: keep it private.
**Report a problem** appears only when Raven has a Bug Report Receiver to send
to (`RAVEN_BUGREPORT_URL`, or the built-in default address). It is the web
version of `raven trajectory report-bug`: pick the turns, describe the problem,
decide the values the redaction scan was unsure about (this page is skipped
when the redaction history already decided them all), then upload and get a
receipt. Every decision on that page, including "keep all" and the bulk
buttons, is remembered in the redaction history with `web` as its source.
When the wizard opens it checks that the receiver answers. If it does not, the
wizard says why, and the report starts only when you choose **Continue
anyway**; **Check again** asks once more, for instance after the receiver is
back. Going on without it is safe: if the upload then fails, the report is kept
on this machine as described below.
Closing the wizard before the upload starts discards the report being
prepared. Once an upload has started the report is saved on this machine: if
the upload fails, a failure marked as retryable offers a retry, and either way
the saved report can be sent later with
`raven trajectory upload-bug-report <id>`, using the report id the page shows.
See
[Trajectory debugging](trajectory-debugging.md#produce-a-reviewed-report) for
the pipeline behind it.
## Import a conversation
**Import conversation**, in the left menu below New task and Connectors, opens
a package from another machine (or another Raven home) for reading. Pick the
file in the browser and it is uploaded to Raven, so this works whether you open
the WebUI locally or remotely. A file can be up to 100 MiB, and one import runs
at a time: starting another while one is in progress asks you to try again when
it finishes.
Three kinds of package can be imported: an export from the three-dot menu, a
bug report package (from **Report a problem** or
`raven trajectory report-bug`), and a trajectory report from
`raven trajectory report`. Any other file is refused with a message saying so.
A damaged or unsafe package (a path that leaves the package, a link, more data
unpacked than the limit allows) is refused and leaves nothing behind, and so is
one whose conversation record is too large to open (over 32 MiB or 50,000
entries). A package made by a newer Raven asks you to update first.
Imported packages are kept under `imports/` in the Raven home and stay there
across restarts. They are never added to the workspace's sessions. Importing
the same package again says it was already imported under its current title,
and offers **Open existing** or **Import anyway**.
Imported conversations are listed under **Imported**, below Recent; the group
is hidden while there are none. An export is titled after its original
conversation (or its first user input when that had no title), a bug report
package after the first line of its description (or its report id), and a
trajectory report after its original conversation (or its own id). Hovering a
row shows the file it came from. Hovering or right-clicking a row offers only
**Rename** and **Delete**; deleting also removes the copy kept on this machine.
An imported conversation is read-only. It reads like any other conversation,
and the trajectory view works as usual, including the full model input of a
long conversation. What differs: there is no input box, the title cannot be
edited in the chat header (rename it from the rail), replies have no Branch,
and the three-dot menu and the working-directory tag are not shown. Things a
package does not carry (a sub-agent's own transcript, attachments and delivered
files, task-graph runs, generated images) are shown as unavailable rather than
as errors. The `[REDACTED:...]` placeholders of a bug report package are shown
as they are.
An export is not redacted, so importing someone else's export gives you its raw
contents: keep it as private as they should have.
duration bar above the list. A normal `raven web` shows no toggle. If a
normal service is already running, `--dev` reports that it has no trajectory
view and leaves it running; stop it with `raven web --stop` first.
For installation and provider setup, see [Quick Start](quick-start.md).
For Docker or source deployments, see [Self-Hosting](self-hosting.md).

View File

@ -10,53 +10,17 @@ raven web
该命令会在浏览器中打开 WebUI,并在后台启动 Raven。关闭浏览器后,Raven 仍会继续运行。
如需停止服务,请运行 `raven web --stop`。
## 轨迹视图 { #trajectory-view }
## 开发者启动 { #developer-launch }
当会话有内容后,聊天页头部工作区面板按钮的左侧会出现轨迹切换按钮。轨迹视图按时间列出该会话的每一步
```bash
raven web --dev
```
`raven --dev` 与 `raven web --dev` 启动同一个服务,但会启用轨迹视图:当会话有内容后,
聊天页头部工作区面板按钮的左侧会出现一个切换按钮。轨迹视图按时间列出该会话的每一步
(输入、模型调用、工具调用、回复)及其耗时,可打开任意一步的详情,并在列表上方绘制耗时构成条。
## 导出与问题报告 { #export-and-report-a-problem }
聊天页头部右上角的三点菜单(desk 启动器在它左侧)作用于当前打开的会话。还没有任何内容的新任务上,菜单不可用。
**导出**:把你选中的轮次打成一个 `.tar.gz`,由浏览器下载。一轮会连同它派发的子代理一起导出;仍在进行的轮次不能选。导出前可以修改文件名。
!!! warning
导出的是原始轨迹,没有脱敏,可能含密钥、令牌等敏感信息,请妥善保管。
**问题报告**:只有 Raven 有可发送的问题报告服务器时才出现(`RAVEN_BUGREPORT_URL`,或内置的默认地址)。它是
`raven trajectory report-bug` 的网页版本:选轮次、填写问题、对脱敏扫描不确定的值逐一决定(脱敏历史已全部决定时跳过这一页),
然后上传并拿到回执号。这一页上的所有决定,包括"全部保持"和批量按钮,都会以 `web` 为来源记入脱敏历史。
向导打开时会检查问题报告服务是否应答;不应答时向导会说明原因,只有你点击**仍然继续**才会开始报告,
**重新检查**可以再查一次(例如服务恢复之后)。不依赖服务继续是安全的:之后上传失败时,报告会按下文所述保存在本机。
在开始上传之前关闭向导,会丢弃正在准备的报告。一旦开始上传,报告就会保存到本机:上传失败时,被标为可重试的失败会提供"重试";
无论哪种情况,都可以用页面上显示的报告编号,稍后通过 `raven trajectory upload-bug-report <id>` 发送已保存的报告。背后的流程见
[轨迹调试](trajectory-debugging.md#produce-a-reviewed-report)。
## 导入会话 { #import-a-conversation }
左侧菜单"新任务""连接"之下的**导入会话**,用来打开从另一台机器(或另一个 Raven home)带来的包并查看。
在浏览器里选择文件后,文件会上传给 Raven,所以本机和远程打开 WebUI 都能用。单个文件上限 100 MiB;
同一时刻只进行一个导入,导入进行中再发起会提示稍后再试。
可以导入三种包:三点菜单"导出"得到的包;问题报告包(来自**问题报告**或 `raven trajectory report-bug`);
`raven trajectory report` 生成的轨迹报告。其他文件会被拒绝并给出提示。损坏或不安全的包(路径跑出包外、链接、
解压后超过上限等)会被拒绝,不留下任何文件;会话记录过大、无法打开的包(超过 32 MiB 或 5 万条)同样会被拒绝。
由更新版本的 Raven 生成的包会提示先升级。
导入的包保存在 Raven home 下的 `imports/` 目录,重启后仍在,不会进入工作区的会话目录。再次导入同一个包时,
会提示它已导入为当前的标题,并提供**打开已有**和**仍然导入一份**两个选项。
导入的会话列在"最近"之下的**导入**分组中,没有导入时不显示这一组。导出包以原会话的标题命名(原会话没有标题时用第一条用户输入),
问题报告包以问题描述的第一行命名(没有时用报告编号),轨迹报告以原会话的标题命名(没有时用报告自身的编号)。
悬停在条目上会显示它来自哪个文件。悬停或右键只有**重命名**和**删除**两项;删除会同时删掉本机保存的那一份。
导入的会话是只读的:阅读方式与普通会话相同,轨迹视图照常可用,长对话的模型输入也能完整查看。不同之处在于:
没有输入区;不能在聊天页头部修改标题(请在侧栏重命名);回复没有"分叉";不显示三点菜单和工作目录标签。
包里没有的内容(子代理自己的会话记录、附件与交付文件、任务编排记录、生成的图片)显示为不可用,而不是报错。
问题报告包中的 `[REDACTED:...]` 占位按原样显示。
导出包没有脱敏,导入别人的导出包就等于拿到了它的原始内容,请同样妥善保管。
普通的 `raven web` 不显示该按钮。如果已有普通服务在运行,`--dev` 会提示它没有轨迹视图并
保持其运行;请先执行 `raven web --stop` 再启动。
安装及模型服务商配置请参阅[快速开始](quick-start.md);Docker 和源码部署请参阅
[自托管](self-hosting.md)。

View File

@ -74,7 +74,6 @@ plugins:
Quick Start: 快速开始
Using Raven: 使用 Raven
Working with Sub-agents: 与子 Agent 协作
Working on Registered Machines: 在登记机器上工作
Browser and Human Collaboration: 浏览器与人工协作
Knowledge Bases: 知识库与文档检索
Long-running Work (Oncall): 长任务托管(Oncall)
@ -120,7 +119,6 @@ nav:
- Launch WebUI: webui.md
- Sandbox: sandbox.md
- Working with Sub-agents: agent-collaboration.md
- Working on Registered Machines: machines.md
- Browser and Human Collaboration: browser-collaboration.md
- Knowledge Bases: knowledge.md
- Playbooks: playbooks.md

View File

@ -315,7 +315,7 @@ imported.
## 7. EverOS version pinning & upgrade SOP
### 7.1 Exact pin is mandatory **[DONE: `everos[multimodal]==1.4.2`]**
### 7.1 Exact pin is mandatory **[DONE: `everos[multimodal]==1.4.1`]**
The adapter is written against EverOS **internal** APIs, not a stable
public surface:
@ -343,7 +343,7 @@ Single pin: EverOS is pinned in **one** place, the plugin's own
(`~/.everos/.index/` sqlite + lancedb) changed.
1. **Bump the pin (uv only — never hand-edit pyproject/lock)**:
```bash
uv add --package everos-memory 'everos[multimodal]==1.4.2' && uv sync
uv add --package everos-memory 'everos[multimodal]==1.4.1' && uv sync
```
Always keep the `[multimodal]` extra. Skip `1.2.0`: it shipped a
path-traversal regression fixed in `1.2.1`.
@ -370,13 +370,9 @@ Single pin: EverOS is pinned in **one** place, the plugin's own
notes for any bump whose migration behaves this way. An upgrade whose
only record is a pull-request description is known to whoever read
that description.
5. **Finalize**: set the plugin's own `version` to the EverOS version it
pins — the two are read together, and a plugin `1.4.0` that ships EverOS
`1.4.1` only invites the question which of them a given install has.
Three files carry it: `pyproject.toml`, `raven_everos/raven-plugin.toml`,
`raven_everos/__init__.py`. Two tests assert it as a literal and must be
updated with it —
`test_everos_plugin_discovery.py::TestPackageSurface::test_imports_clean`
5. **Finalize**: bump the manifest `version`. Two tests assert it as a
literal and must be updated with it —
`test_everos_plugin_discovery.py::test_bundled_shadows_lower_priority_source`
and `test_cli_plugin_commands.py::TestActiveBackend::test_lists_everos_memory`.
Then commit
`pyproject.toml` + `uv.lock` + adapter changes. Rollback =
@ -554,46 +550,6 @@ the memory backend: a knowledge base sizes itself to whatever width the
model returns, so an install with memory off or on another backend keeps
any width. The wizard's own check reads the same constant and probe.
### 7.5 Record: `1.4.1` -> `1.4.2`
One package moved: `everos` `1.4.1` -> `1.4.2`. EverOS declares the same 36
requirements in both releases, so nothing else in the lock follows it. The
plugin's own version goes `1.4.0` -> `1.4.2` rather than `1.4.1`: step 5 now
holds it equal to the EverOS it pins, and the number this upgrade skips is the
gap that rule closes.
**No adapter change.** Every internal symbol the adapter reaches is present
in `1.4.2` with the same signature, the package layout churn underneath
included: `everos.infra.persistence.lancedb.tables` became
`everos.infra.persistence.records` and `everos.infra.persistence.backends`
became `.lancedb.LanceIndexBackend`, but the adapter imports
`episode_repo` / `agent_skill_repo` from the `lancedb` package, which
re-exports both the way it did before.
**The derived index repairs itself, once, on the first start.** `1.4.2`
makes a table's primary key `(app_id, project_id, id)` rather than `id`
alone, and the first full cascade pass after the upgrade re-reconciles every
indexed markdown file against the index, re-embedding only rows that are
missing or stale and recording that it ran in
`.index/.index_reconcile_version`. A healthy root pays one read pass and no
embedding. Markdown was never affected by the bug this fixes, so the
markdown a root keeps is the source either way. The two roots EverOS says
need `everos cascade rebuild` by hand are a Milvus derived index and a root
where reflection already ran across projects; raven writes one project into
a LanceDB root and reaches neither, but a user who pointed raven at a root
of their own might.
**Three faults fixed that a long-lived server hits.** A LanceDB index reader
leaked file descriptors for the life of the process (capped now by
`[lancedb] metadata_cache_size_bytes`, default 1 MB), an interactive search
queued behind the cascade's background embedding (queries draw on
`[embedding] query_max_concurrent`, default 4), and a cascade pass embedded
one request per entry instead of one per file. The settings are EverOS's
own; raven writes only `[api]` into `everos.toml` and copies the shipped
template for a root that has none, so an existing root keeps `max_concurrent`
as its own file spells it and picks up `query_max_concurrent` from the class
default behind the file.
---
## 8. Validation (this change)
@ -623,29 +579,3 @@ independent of this refactor.
| Discovery | manifest-only (TOML) | import-on-scan (Hermes-style) | missing deps can't break discovery; no startup cost for unselected backends |
| EverOS pin | exact `==X.Y.Z` | range `>=,<` | adapter binds internal (non-public) APIs; upgrades must be deliberate |
| Conflict priority | `bundled > user > project > entry_points` | user-overrides-bundled | builtin can't be silently shadowed |
---
## 10. EverOS Cloud as a second backend
`plugins-dist/everos-cloud-memory/` (package `raven_everos_cloud`, backend name
`everos-cloud`) keeps a Raven's memory on the hosted EverOS at
`https://api.evermind.ai` instead of a local server. It speaks the same four
routes as the local plugin (`/api/v2/memory/{search,add,flush,get}`) with a
Bearer key, depends on `raven` and `httpx` only, and never imports the
`everos` package. Design record: `docs/specs/2026-10-08-everos-cloud-memory-design.md`.
| Topic | How it works |
|---|---|
| Key | `plugins.config["everos-cloud-memory"].api_key` first, `EVEROS_CLOUD_API_KEY` second; a key that came from the environment is never written to the file. The wizard's screen and the settings page's card both write the slice through `set_plugin_config_fields`. |
| Identity | `memory.userId` / `memory.agentId`, through `ServiceLocator`, as for every backend. Two machines on one key with the default ids share one memory; the wizard says so. |
| Extraction | every add carries `mode: "agent"` (the local server runs both pipelines on every add; the cloud defaults to `chat`). `/flush` is sent only when the caller says the conversation is over -- `metadata["flush"]` (the sub-agent handoff) and `metadata["is_final"]` (the importer's last batch) -- and once per touched session at `stop()`, within a 5 s budget. Ordinary turns rely on the cloud's own extraction. |
| Limits | adds are split at 500 messages / 250 KB; a single message over the ceiling is not stored and is named in the log. |
| Health | `POST /memory/get` with `page_size: 1`; 401, 403, 429, unreachable and "no key" each have their own sentence for `raven doctor`, the wizard and the card. |
| Host surfaces | the wizard asks "Which memory backend?" when more than one memory plugin is installed; the memory page reads whichever backend `memory.backend` names (with the Bearer header, without the OSS `/health` probe); `settings.everos` answers `reason: "other_backend"` for any backend that is not EverOS, which hides the llm / rerank / multimodal slots (embedding stays: knowledge bases embed with that pin); `settings.everosCloud` feeds the card; `settings.set` admits `plugins.config.<id>.<field>` only for a field the plugin's manifest marks `settable = true` (the cloud key; never an endpoint, which decides where that key is sent); a provider save no longer restarts a local EverOS unless EverOS is the backend. |
| Not shipped by default | the release builds the wheel but `raven-plugins.txt` keeps three distributions until the plugin has run against the live service (`tests/integration/test_everos_cloud_real_cloud.py`, key-gated). |
| Not done | `delete` answers `False` (the cloud deletes by scope, not by id); no `understand_media` tool (cloud multimodal needs a presigned upload); `app_id` / `project_id` stay at the cloud's defaults. |
Tests: `tests/test_everos_cloud_*.py` over `tests/_everos_cloud_fake.py`, a fake
cloud that honours or refuses every field the backend sends and records every
request; `tests/test_plugin_boundary.py` scans both plugin packages.

View File

@ -1,516 +0,0 @@
# EverOS Cloud memory plugin -- implementation plan
Status: plan; G3 passed 2026-10-08
> For the executor: run this under `dev-workflow` stage 4; tick steps with
> `- [ ]`; when something this plan does not cover comes up, read Global
> Constraints first, then the three tiers of `unattended-run` section 7 -- do
> not guess. Each task is self-contained: read only the task you are on, plus
> this header.
**Goal**: a person on `main` can install `everos-cloud-memory`, pick it in
`raven onboard`, and have recall, storage, the sub-agent handoff, the importer,
`raven doctor`, the memory page and the settings page all run against EverOS
Cloud, while a person on the local plugin sees nothing change.
**Design document**: `docs/specs/2026-10-08-everos-cloud-memory-design.md`
(A1-A39, C1-C18, H1-H16).
**Acceptance cases**: `docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`
(T1.1-T39.2; stage 4 runs them).
**Approach**: a thin plugin distribution over the cloud's REST API, copied from
`raven_everos.backend` and stripped of the local service state machine; fifteen
small host edits and one ui-web card for parity; a fake cloud fixture that both
the unit tests and the real-host acceptance runs use.
**Stack**: Python 3.12, `httpx`, `uv` workspace member; `typer` / `questionary`
for the wizard; pydantic models mirrored in `rpc-schema/openrpc.json`;
React + vitest in `ui-web`; `i18n/messages.json` for every GUI string.
**Change map**: the spec's Overview diagram; the host-edit table (H1-H16) names
the files, and the task numbers below map onto it: Task 1 = H16, Task 2 = the
plugin + H11, Task 3 = H9 + H10 + H12, Task 4 = H1, Task 5 = H2-H5, Task 6 =
H6-H8 + H15 (+ the RPC contract files), Task 7 = H13, Task 8 = H14, Task 9 =
the live tests of C14-C18, Task 10 = the acceptance run.
Working tree: `/Users/admin/Raven-b`, branch `feat/everos_cloud_memory_plugin`
(base `3632e6040`). Every `git` command names the tree: `git -C /Users/admin/Raven-b ...`.
Every Python command runs through `uv run --frozen ...` from that directory.
Baselines measured there on 2026-10-08, before any code change:
```
tests/test_plugin_boundary.py 4 tests collected
tests/test_release_plugin_list.py 6 tests collected
tests/test_everos_backend_contract.py 11 tests collected
tests/test_rpc_memory.py 17 tests collected
tests/test_rpc_settings.py 107 tests collected
tests/test_cli_onboard_commands.py 348 tests collected
grep -c "uv build --wheel plugins-dist/" .github/workflows/release.yml -> 3
```
`tests/test_cli_onboard_commands.py::test_onboard_cli_writes_the_keys_passed_as_flags`
is red when the file runs in the same xdist batch as `test_rpc_settings.py` and
green alone (deviations.md D1, recorded before any change); judge that file by
a solo rerun of a failing test.
## Global Constraints
Verbatim from the spec's Constraints table. Every task's requirements include
these.
| # | Kind | Constraint | How it is checked |
|---|---|---|---|
| C1 | architecture | The plugin imports the host only through `raven.contracts.memory`, `raven.plugins` and `raven.config.update` (to write its own slice); never `raven.cli`, `raven.config.loader`, `raven.config.raven`. | `tests/test_plugin_boundary.py::test_plugin_does_not_import_host_private_modules`, with `PLUGIN_DIR` widened to every `plugins-dist/*/raven_*` package. |
| C2 | architecture | The host imports `raven_everos_cloud` from `raven/rpc/methods/memory.py` and `raven/rpc/methods/console.py` only -- the two files already allow-listed as EverOS wire-protocol surfaces. | `test_plugin_boundary.py::test_host_does_not_import_plugin_internals`, regex widened to `raven_everos(_cloud)?\b`; `HOST_WIRE_PROTOCOL_SURFACES` unchanged. |
| C3 | architecture | The plugin's dependency table is `raven` and `httpx`; it never imports `everos` or `raven_everos`. | `plugins-dist/everos-cloud-memory/pyproject.toml`; a test imports every module of the package with `everos` and `raven_everos` blocked in `sys.modules`. |
| C4 | design | Owner ids come from `ServiceLocator` only. The cloud slice declares no `user_id` / `agent_id`; a stale one is warned about and ignored. | manifest `config_schema` has no identity key; unit test with a slice carrying `user_id` asserts the wire uses the locator's. |
| C5 | design | Every `/memory/add` carries `mode: "agent"`. | fake-transport test asserts the body of every add. |
| C6 | design | `/memory/flush` is sent only on an explicit end and in `stop()`. Twenty ordinary turns produce zero flushes. | fake-transport test counts flush calls across N plain `store` calls (0), one `flush` metadata store (1), one `is_final` store (1), one `stop()` after unflushed writes (1 per session). |
| C7 | design | Key resolution is config first, `EVEROS_CLOUD_API_KEY` second; a key that came from the environment is never written to `config.json`. | unit tests on the resolver; onboard test asserts the slice after an env-sourced run has no `api_key`. |
| C8 | design | No contract method raises. `recall` answers within 4.0 s on both tracks (the per-turn user-track caller abandons at 5.0 s, `raven/context_engine/segments/memory.py:27`; the skill router has no budget of its own, `raven/memory_engine/skill_forge/backend_source.py:95`, so this bound is the only one it gets). `recall_session` answers within 10.0 s (its caller allows 30.0 s, `raven/agent/subagent_memory.py:42`, and a read-back right after extraction is the slow case). `store` returns `False` on any failure. `health` answers within 5.0 s. | `tests/test_everos_cloud_backend_contract.py` inherits `MemoryBackendContractTests` and `LifecycleContractTests`; fault-injection tests per failure row with a hanging fake and a clock. |
| C9 | design | With `memory.backend` equal to `"everos"` or `None`, every host surface behaves exactly as before. A backend name that is neither (`"everos-cloud"` today, any future plugin, a stale name) is the one case the host edits change: role slots hidden, settings role writes refused, no EverOS restart. | existing suites unchanged and green: `test_cli_onboard_commands.py`, `test_rpc_settings.py`, `test_rpc_memory.py`, `test_everos_*`; one explicit regression test per surface for the `everos` and `None` branches. |
| C10 | design | Request bodies respect Cloud limits: at most 500 messages and under 300 KB per add. | unit test: a 600-message `store` issues two adds; a 400 KB slice splits by message. |
| C11 | design | Source language is English, including the plugin, tests and the `i18n/messages.json` `en` column; `zh` entries only where the catalogue already carries them. | `make check-source-language`. |
| C12 | design | GUI text goes through `t(key)` with entries in `i18n/messages.json`; no CJK literal enters a `.tsx`. | `ui-web/scripts/gates/first-frame-literals.test.mjs`; `npm run gen:check` in `ui-web` and `lint:rpc` in `ui-tui` for the regenerated RPC types. |
| C13 | design | The release plugin list stays at three distributions. | `tests/test_release_plugin_list.py` unchanged and green; `release.yml` keeps `-eq 3`. |
| C14 | assumption | Cloud `/api/v2/memory/{add,flush,get,search}` accept the request bodies the local plugin sends (`SearchRequest`, `MemorizeAddRequest`, get-by-type), differing only in `mode` being per request. | Read from docs.evermind.ai (`llms-full.txt`) on 2026-10-08. **Unverified against the live service**: `tests/integration/test_everos_cloud_real_cloud.py::test_add_flush_search_roundtrip` and `::test_get_by_session` run only with `EVEROS_CLOUD_API_KEY` set and are the first thing to run when a key exists. |
| C15 | assumption | `/memory/flush` exists on Cloud and answers `no_extraction` harmlessly when nothing is pending. | docs.evermind.ai 2026-10-08; EverOS's own `everos demo --live` client calls it against `api.evermind.ai`. Live: `test_everos_cloud_real_cloud.py::test_flush_with_nothing_pending_is_no_extraction`. |
| C16 | assumption | HTTP 401 means "invalid or missing token"; 403 means "account not authorized for v2". | docs.evermind.ai error table, 2026-10-08. Live: `test_everos_cloud_real_cloud.py::test_wrong_key_is_401` (a deliberately wrong key). The 403 half cannot be exercised without an un-entitled account; it stays documentation-backed and the spec words it as a hint, not a certainty ("may mean ..."). |
| C17 | assumption | Cloud extracts on its own after `add` ("you rarely need flush"), so a session that never sees an explicit end is still extracted eventually. | docs.evermind.ai 2026-10-08. Live: `test_everos_cloud_real_cloud.py::test_add_without_flush_is_searchable_within_two_minutes` (polls `/search`; skipped by default, run by hand -- it costs two minutes). The `stop()` sweep is the hedge. |
| C18 | assumption | `POST /memory/get` with `page_size: 1` is accepted with a key and refused without one, so it can stand as the health probe. | Live: `test_everos_cloud_real_cloud.py::test_get_page_one_with_and_without_key`. |
Repository rules that bind every task (AGENTS.md): source and docs in English
(section 1.3); `uv` only, never `pip`, never a hand edit of a dependency table
(section 4); tests through `uv run pytest`, CLI tests in the existing
`tests/test_cli_<module>_commands.py` (section 5); canonical terms from
`CONTEXT.md`, new ones defined there in the same change (section 6); no SVG,
HTML or files over 1 MiB (section 7).
### Authorization (this run)
Baseline: `unattended-run` section 1, narrowed by AGENTS.md section 3.4 / 3.6,
which wins in this repository: **no commit and no push without the owner's
word in chat**; "commit per task" below is a checkpoint the executor asks for,
not a pre-authorization. Pre-authorized: rebasing onto `github/main`; building
and running the fake cloud and isolated Raven instances on free ports under
`$SCRATCH`; creating temporary directories and processes (torn down and listed
in `deviations.md`); editing every file this plan names; adding workspace
members with `uv add`. Never pre-authorized: editing `AGENTS.md`, `CLAUDE.md`
or `CONTEXT-MAP.md`; touching the owner's `~/.raven`, the owner's running
gateway or EverOS, or any process not started by this run. Pushing goes to
GitHub over SSH (`git@github.com:EverMind-AI/Raven.git`), never to the GitLab
`origin`; a PR is offered after the push, and when the owner says "send", the
PR is created without a description preview (project memory).
### Caps and goal
Rounds 40, time 48 h (defaults). Goal text, to be pasted into `status.md` and
`/goal` when the owner starts one:
> Every `real` case in `docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`
> passes with evidence under `.work_context/everos_cloud_memory/acceptance/evidence/`
> and its commands rerun as written; the PR is open against `main`; every CI
> job's final state is green on the current head; every blocker from the G4
> self-review is handled; every external review comment that has arrived is
> handled or answered in the PR with the reason it is not changed; **and the
> owner confirms acceptance in chat**. Or `deviations.md` gains a stop-tier
> entry. Or 40 rounds. Or 48 hours.
---
### Task 1: the fake cloud (H16)
**Delivers**: the fixture every later task tests against; the acceptance
document's section 1.2. No A of its own; A10-A18, A33, A34 and every `real`
case depend on it.
**Files**:
- new: `tests/_everos_cloud_fake.py`
- new: `tests/test_everos_cloud_fake.py`
**Interfaces**:
- produces `class FakeCloud` with `__init__(self, *, mode: str = "ok", hang_on: set[str] = frozenset(), ledger: list[dict] | None = None)`,
`transport(self) -> httpx.MockTransport`, `set_mode(self, mode: str, hang_on: set[str] | None = None) -> None`,
`ledger: list[dict]` (entries `{ts, method, path, headers, body, status}`),
`serve(self, port: int, ledger_path: Path | None, with_health: bool) -> None` (blocking; `python -m tests._everos_cloud_fake --port N --mode M --ledger F [--with-health] [--hang-on PATH]...`),
and the HTTP control route `POST /_fake/mode {"mode": str, "hang_on": [str]}`.
- sentinels: `EPISODE_SUBJECT = "ECM-EP-5c1d"`, `TOTALS = {"episode": 7, "profile": 1, "agent_case": 2, "agent_skill": 3}`, `REFUSED_MESSAGE = "ECM-REFUSED-401"`.
- the field table of the acceptance document section 1.2 is the behaviour contract: unknown field -> 400 naming it; `user_id` XOR `agent_id` else 422; `memory_type` must match the owner's track else 422; add body over 500 messages or 300 KB -> 413; every message needs `sender_id`, `role`, integer `timestamp`, `content`.
- [ ] **Step 1: write the tests first** (there is no real dependency to smoke; the fake *is* the stand-in, and the docs copy at `.work_context/everos_cloud_memory/everos-cloud-api-llms-full-20261008.txt` is its source)
```python
# tests/test_everos_cloud_fake.py
"""The fake cloud honours or refuses every field the backend can send."""
import httpx, pytest
from tests._everos_cloud_fake import FakeCloud, EPISODE_SUBJECT
async def _post(fake, path, body, key="k"):
async with httpx.AsyncClient(transport=fake.transport(), base_url="http://fake") as c:
return await c.post(path, json=body, headers={"Authorization": f"Bearer {key}"})
async def test_search_requires_exactly_one_owner():
fake = FakeCloud()
r = await _post(fake, "/api/v2/memory/search", {"query": "q", "top_k": 5})
assert r.status_code == 422 and "user_id" in r.text and "agent_id" in r.text
r = await _post(fake, "/api/v2/memory/search", {"query": "q", "top_k": 5, "user_id": "u", "agent_id": "a"})
assert r.status_code == 422
async def test_agent_rows_only_for_an_agent_owner():
fake = FakeCloud()
r = await _post(fake, "/api/v2/memory/search", {"query": "q", "top_k": 5, "user_id": "u"})
assert r.json()["data"]["agent_skills"] == [] and r.json()["data"]["episodes"][0]["subject"] == EPISODE_SUBJECT
r = await _post(fake, "/api/v2/memory/search", {"query": "q", "top_k": 5, "agent_id": "a"})
assert r.json()["data"]["episodes"] == [] and r.json()["data"]["agent_skills"]
async def test_unknown_field_is_refused_by_name():
r = await _post(FakeCloud(), "/api/v2/memory/search", {"query": "q", "top_k": 5, "user_id": "u", "bogus": 1})
assert r.status_code == 400 and "bogus" in r.text
async def test_add_limits_and_message_shape():
fake = FakeCloud()
msg = {"sender_id": "u", "role": "user", "timestamp": 1_700_000_000_000, "content": "x"}
r = await _post(fake, "/api/v2/memory/add", {"session_id": "s", "mode": "agent", "messages": [msg] * 501})
assert r.status_code == 413
r = await _post(fake, "/api/v2/memory/add", {"session_id": "s", "mode": "agent", "messages": [{**msg, "timestamp": "2026"}]})
assert r.status_code == 400 and "timestamp" in r.text
async def test_ledger_records_unknown_routes_too():
fake = FakeCloud()
await _post(fake, "/health", {})
assert fake.ledger[-1]["path"] == "/health" and fake.ledger[-1]["status"] == 404
async def test_mode_switch_changes_the_answer():
fake = FakeCloud()
fake.set_mode("401")
r = await _post(fake, "/api/v2/memory/get", {"user_id": "u", "memory_type": "episode", "page_size": 1})
assert r.status_code == 401 and r.json()["error"]["message"] == "ECM-REFUSED-401"
```
- [ ] **Step 2: implement** `tests/_everos_cloud_fake.py` -- a pure-Python request handler `handle(method, path, headers, body) -> (status, json)` used by both faces (the `MockTransport` wraps it; the HTTP server wraps it with `http.server` and a `--ledger` JSONL writer); modes as a dict of answer builders; `hang` sleeps forever on the named routes (in the transport, `await asyncio.sleep(3600)`).
- [ ] **Step 3: run, then prove it can fail**
Run: `cd /Users/admin/Raven-b && uv run --frozen pytest tests/test_everos_cloud_fake.py -q -p no:cacheprovider`
Expected: `6 passed` (copy the actual line).
Mutation: delete the XOR check in `handle` -> `test_search_requires_exactly_one_owner` fails on its first assertion; restore; `git -C /Users/admin/Raven-b diff --stat -- tests/_everos_cloud_fake.py` prints nothing.
- [ ] **Step 4: smoke the HTTP face once**
Run (through the host's background runner, with the section 8 watchdog from the acceptance document 1.2): `python -m tests._everos_cloud_fake --port $FAKE_PORT --mode ok --ledger $SCRATCH/ecm-fake/requests.jsonl`, then
`curl -s -X POST http://127.0.0.1:$FAKE_PORT/api/v2/memory/get -H 'Authorization: Bearer k' -H 'Content-Type: application/json' -d '{"user_id":"u","memory_type":"episode","page_size":1}' | python3 -m json.tool | head -5`
Expected: `"total_count": 7` among the lines; `tail -1 $SCRATCH/ecm-fake/requests.jsonl` shows the request with its header. Kill the server by the pid from `lsof -tiTCP:$FAKE_PORT -sTCP:LISTEN`.
- [ ] **Step 5: record** -- nothing to record unless the docs copy and the fake disagree somewhere; a disagreement goes to `deviations.md` as assumption-mismatch against C14.
---
### Task 2: the plugin distribution (H11)
**Delivers**: A2, A4, A5, A6, A7, A28 (the screen), A10, A11, A12, A13, A14, A15,
A16, A17, A18, A27 (the health table), A33, A34 at the contract level; the
real-host halves land in Task 10.
**Files**:
- new: `plugins-dist/everos-cloud-memory/pyproject.toml`
- new: `plugins-dist/everos-cloud-memory/raven_everos_cloud/__init__.py`
- new: `plugins-dist/everos-cloud-memory/raven_everos_cloud/raven-plugin.toml`
- new: `plugins-dist/everos-cloud-memory/raven_everos_cloud/backend.py`
- new: `plugins-dist/everos-cloud-memory/raven_everos_cloud/onboard.py`
- modify: `pyproject.toml:385` (`[tool.ruff]` `src` list -- not a dependency table, a hand edit is allowed) and, through `uv add --dev everos-cloud-memory`, the dev-dependency list and `[tool.uv.sources]` (`:151-153`, `:222-224`), plus `uv.lock`
- new tests: `tests/test_everos_cloud_backend.py`, `tests/test_everos_cloud_backend_contract.py`, `tests/test_everos_cloud_onboard.py`, `tests/test_everos_cloud_discover.py`
**Interfaces**:
- consumes `FakeCloud` (Task 1); `raven.contracts.memory.{Memory, BackendHealth, HealthCheck}`; `raven.plugins.{PluginContext, OnboardUI, StepOutcome}`; `raven.config.update.set_plugin_config_fields(plugin_id, fields)`.
- produces, in `raven_everos_cloud.backend`: `DEFAULT_BASE_URL = "https://api.evermind.ai"`, `ENV_KEY = "EVEROS_CLOUD_API_KEY"`, `KEYS_URL = "https://everos.evermind.ai"`, `resolve_api_key(config: Mapping[str, Any]) -> tuple[str, str | None]`, `class EverosCloudBackend(ctx, *, client=None)` implementing the `MemoryBackend` Protocol, `make_backend(ctx) -> EverosCloudBackend`; constants `RECALL_TIMEOUT_S = 4.0`, `SESSION_TIMEOUT_S = 10.0`, `ADD_TIMEOUT_S = 30.0`, `FLUSH_TIMEOUT_S = float(os.environ.get("RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S", "360"))`, `HEALTH_TIMEOUT_S = 5.0`, `SHUTDOWN_FLUSH_BUDGET_S = 5.0`, `ADD_MAX_MESSAGES = 500`, `ADD_MAX_BYTES = 250_000`; log lines `"recall timed out after %.1f s; returning empty"` and `"flushed %d session(s) at stop"`.
- produces, in `raven_everos_cloud.onboard`: `class CloudKeyScreen(ctx, *, client_factory=None)` with `run(ui, *, step_no, non_interactive, main_model, warnings, skip_test) -> StepOutcome` and `configured() -> bool`; `make_onboard_step(ctx) -> CloudKeyScreen`. Screen strings exactly as the spec's onboard.py sketch, including the sharing hint naming `memory.userId`.
- manifest: id `everos-cloud-memory`, `memory_backends` name `everos-cloud`, `onboard` name `everos-cloud`, `config_schema` with `api_key` and `base_url` (strings) only.
- [ ] **Step 1: scaffold and register the member**
```bash
cd /Users/admin/Raven-b
mkdir -p plugins-dist/everos-cloud-memory/raven_everos_cloud
# write pyproject.toml (copy plugins-dist/everos-memory/pyproject.toml, name everos-cloud-memory, version 0.1.0,
# dependencies = ["raven", "httpx>=0.28.0,<1.0.0"], entry point everos-cloud-memory = "raven_everos_cloud",
# hatch include raven_everos_cloud/**/*.py and raven_everos_cloud/raven-plugin.toml)
# write raven-plugin.toml exactly as the spec's "The plugin's manifest" block
cat > plugins-dist/everos-cloud-memory/raven_everos_cloud/__init__.py <<'INIT'
"""EverOS Cloud memory backend for Raven.
Implements the host's :class:`raven.memory_engine.MemoryBackend` Protocol over
HTTPS against EverOS Cloud (``https://api.evermind.ai``); ``backend.make_backend``
is the factory the registry calls. Kept import-cheap: discovery resolves
``raven-plugin.toml`` through this module, so it imports neither ``httpx`` nor
``backend``.
"""
__version__ = "0.1.0"
INIT
uv add --dev everos-cloud-memory # adds the dev dep and the workspace source
uv sync --frozen 2>/dev/null || uv sync # a fresh lock is expected here
uv run --frozen python -c "import raven_everos_cloud, importlib.metadata as m; print(m.version('everos-cloud-memory'))"
```
Expected: `0.1.0`. Then add `"plugins-dist/everos-cloud-memory"` to the `src` list at `pyproject.toml:385`.
- [ ] **Step 2: write the tests first**
`tests/test_everos_cloud_backend.py` -- one test per row, each over `FakeCloud().transport()` injected as `client=httpx.AsyncClient(transport=...)` and a `PluginContext(config=..., services=ServiceLocator(workspace=tmp_path, user_id="ecm-user", agent_id="ecm-agent"), logger=...)`:
`test_key_resolution_prefers_the_file` (C7), `test_recall_sends_bearer_and_include_profile_and_sorts` (A10), `test_profile_is_capped_with_marker` (A10), `test_store_sends_mode_agent_and_owner_ids_and_no_flush` (A11, 20 turns -> 0 flush), `test_recall_hang_returns_empty_within_bound` (A12, patch `RECALL_TIMEOUT_S` to 0.3 and assert `[]` within 0.6 s; same for `recall_session` with `SESSION_TIMEOUT_S`), `test_recall_500_and_429_return_empty_and_store_false` (A12), `test_agent_track_maps_skills_and_cases` (A13), `test_both_or_neither_owner_is_empty_without_a_request` (A13), `test_flush_metadata_flushes_once_with_per_call_owners` (A14, snake), `test_camel_case_owner_override_also_fires` (A14), `test_recall_session_filters_by_session_and_track` (A15), `test_is_final_flushes_once_after_the_last_batch` (A16), `test_six_hundred_messages_split_into_two_adds` (A17), `test_oversize_message_fails_its_own_add_and_logs_index` (A17), `test_stop_flushes_only_unflushed_sessions_and_closes` (A18), `test_stop_hang_returns_within_budget_and_warns` (A18, `SHUTDOWN_FLUSH_BUDGET_S` patched to 0.5), `test_hung_flush_keeps_the_session_for_the_sweep` (A34, `RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S=0.3` via `monkeypatch.setenv` before import of the constant -- read it at call time, not import time, so the env hook works in a running process too), `test_health_classifies_every_answer` (A27: the seven rows of the health table, parametrised), `test_stale_identity_in_slice_is_ignored_with_a_warning` (C4), `test_no_key_means_no_request` (recall `[]`, store `False`, health `missing`).
`tests/test_everos_cloud_backend_contract.py` -- mirrors `tests/test_everos_backend_contract.py:1-30`: subclasses of `MemoryBackendContractTests` and `LifecycleContractTests` whose `make_backend` builds `EverosCloudBackend` over `FakeCloud`.
`tests/test_everos_cloud_onboard.py` -- a scripted `OnboardUI` (copy the shape `tests/test_cli_onboard_commands.py:50-70` builds): `test_typed_key_is_probed_and_recorded` (A2), `test_env_key_is_used_and_not_written` (A4), `test_401_and_403_get_their_own_sentences_and_offer_reenter` (A5), `test_unreachable_names_the_url` (A6), `test_back_returns_back` (A7), `test_hint_names_memory_user_id_and_the_locator_id` (A28), `test_configured_reads_file_then_env` (A29's `configured()`).
`tests/test_everos_cloud_discover.py` -- `test_manifest_is_discovered_through_the_entry_point` (mirrors `tests/test_everos_plugin_discovery.py`), `test_package_imports_with_everos_and_raven_everos_blocked` (C3: iterate `pkgutil.walk_packages(raven_everos_cloud.__path__)` with `sys.modules["everos"] = None`, `sys.modules["raven_everos"] = None`), `test_init_is_import_cheap` (`httpx` not in `sys.modules` after a fresh `import raven_everos_cloud` in a subprocess).
- [ ] **Step 3: implement** `backend.py` (copy `convert_messages`, `as_ms_epoch`, `_owner_override`, `_search_data_to_memories`, `_flatten_profile`, `_cap_profile_text`, `_flatten_profile_list`, `_PATH_SAFE_ID_RE` warning from `plugins-dist/everos-memory/raven_everos/backend.py`; write `EverosCloudBackend` per the spec sketch; `_search_data_to_memories` takes parsed JSON dicts, so adapt its `getattr` reads to `.get`) and `onboard.py` (the spec sketch verbatim, `_probe` building a backend on the candidate key with the test's `client_factory` when given).
- [ ] **Step 4: run and prove red**
Run: `uv run --frozen pytest tests/test_everos_cloud_backend.py tests/test_everos_cloud_backend_contract.py tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py -q -p no:cacheprovider`
Expected: all pass; the contract file collects `11 tests` (`uv run --frozen pytest --collect-only -q tests/test_everos_cloud_backend_contract.py | tail -1` -> `11 tests collected`, the same as the local plugin's).
Mutations (each: change, run the named test, see it fail on the named assertion, restore, `git diff` clean):
- drop `"mode": "agent"` from the add body -> `test_store_sends_mode_agent_...` fails on the body assertion;
- flush after every add -> `test_store_sends_mode_agent_and_owner_ids_and_no_flush` fails on the flush count;
- read only `user_id` in `_owner_override` -> `test_camel_case_owner_override_also_fires` fails;
- write the env key into the slice in `onboard.py` -> `test_env_key_is_used_and_not_written` fails;
- `import raven_everos` at the top of `backend.py` -> `test_package_imports_with_everos_and_raven_everos_blocked` fails.
- [ ] **Step 5: record** -- `# ponytail:` on the oversize-message ceiling (`ADD_MAX_BYTES`: a single message over it is not stored; upgrade: chunk one message) goes into `deviations.md` as a fallback-tier row at G4.
---
### Task 3: gates that must see the new plugin (H9, H10, H12)
**Delivers**: A30, A31.
**Files**:
- modify: `tests/test_plugin_boundary.py:20-22` (`PLUGIN_DIR`, `_PLUGIN_IMPORT`), `:50` (`_plugin_files`), `:55` (`test_scan_roots_exist`)
- modify: `scripts/coverage_gate.py:26`; `Makefile:13` and `:18` (`--cov=raven_everos` -> add `--cov=raven_everos_cloud`)
- modify: `.github/workflows/release.yml:85-90` (one `uv build --wheel plugins-dist/everos-cloud-memory -o dist` line after `:85`)
**Interfaces**: none produced; consumes the package name `raven_everos_cloud`.
- [ ] **Step 1: boundary test** -- `PLUGIN_DIRS = sorted((REPO_ROOT / "plugins-dist").glob("*/raven_*"))`; `_plugin_files` walks all of them; `_PLUGIN_IMPORT = re.compile(r"^\s*(from|import)\s+raven_everos(_cloud)?\b", re.M)`; `test_scan_roots_exist` asserts each dir yields files.
Run: `uv run --frozen pytest tests/test_plugin_boundary.py -q -p no:cacheprovider`
Expected: `4 passed` (same count as the baseline; the widened scan must still pass -- `raven_ppt` and `raven_design` do not import the host's private modules).
Mutation: add `import raven_everos_cloud` to `raven/core/plugin_stack.py` -> `test_host_does_not_import_plugin_internals` fails naming that file; restore.
- [ ] **Step 2: coverage and release**
```bash
cd /Users/admin/Raven-b
# scripts/coverage_gate.py: add ":(glob)plugins-dist/everos-cloud-memory/**/*.py" after line 26
# Makefile:13 and :18: --cov=raven_everos --cov=raven_everos_cloud
# release.yml: after line 85 add
# uv build --wheel plugins-dist/everos-cloud-memory -o dist
grep -c "uv build --wheel plugins-dist/" .github/workflows/release.yml # 4
grep -c -- "-eq 3" .github/workflows/release.yml # 1
uv run --frozen pytest tests/test_release_plugin_list.py -q -p no:cacheprovider # 6 passed
uv build --wheel plugins-dist/everos-cloud-memory -o $SCRATCH/dist && ls $SCRATCH/dist # everos_cloud_memory-0.1.0-py3-none-any.whl
```
- [ ] **Step 3: record** -- nothing expected.
---
### Task 4: the memory backend chooser (H1)
**Delivers**: A1, A3, A8, A9, A29, A38 (contract level; A1/A3/A8/A9/A29/A38 real-host halves in Task 10).
**Files**:
- modify: `raven/cli/onboard_commands.py:2010-2026` (`_step4_memory`'s loop) and a new `_choose_memory_backend(steps) -> str | None` beside `_memory_steps` (`:1929`)
- modify: `tests/test_cli_onboard_commands.py` (append; AGENTS 5.4: no new file)
**Interfaces**:
- consumes `_memory_steps()`, `_selected_backend()`, `_require_questionary()`, `RAVEN_STYLE`, `_QMARK`, `t`, `set_memory_backend`.
- produces `_choose_memory_backend(steps: list[tuple[str, OnboardStep]]) -> str | None`: `questionary.select(t("Which memory backend?"), choices=[Choice(name, value=name) for name in names] + [Choice(t("Off"), value=_MEMORY_OFF)], default=current if current in names else None, style=RAVEN_STYLE, qmark=_QMARK).ask()`; `None` from `.ask()` (Esc / Ctrl-C) -> `raise typer.Exit(1)`; `_MEMORY_OFF` -> return `None`; else the name. `_MEMORY_OFF = object()` module constant.
- [ ] **Step 1: tests first** (append to `tests/test_cli_onboard_commands.py`; the file already stubs `questionary.select` at `:306-319` -- copy that pattern):
`test_two_memory_screens_ask_which_backend_and_run_only_the_chosen_one` (A1: fake steps `[("everos", s1), ("everos-cloud", s2)]`, select returns `"everos-cloud"`, only `s2.run` called, `set_memory_backend("everos-cloud")`), `test_choosing_off_writes_null_and_runs_no_screen` (A3), `test_one_memory_screen_runs_without_a_question` (A8: `questionary.select` patched to raise if called), `test_a_cancelled_choice_exits_one_and_writes_nothing` (A38: select returns `None` -> `typer.Exit` with code 1, `set_memory_backend` not called), `test_non_interactive_with_two_screens_never_asks` (A29).
- [ ] **Step 2: implement** per the spec's "Host: the chooser (H1), before and after" block.
- [ ] **Step 3: run and prove red**
Run: `uv run --frozen pytest tests/test_cli_onboard_commands.py -q -p no:cacheprovider`
Expected: `353 passed` (348 + 5; if `test_onboard_cli_writes_the_keys_passed_as_flags` is red, rerun it alone per D1 and record both outputs).
Mutation: make `_choose_memory_backend` return `None` on `.ask() is None` instead of raising -> `test_a_cancelled_choice_exits_one_and_writes_nothing` fails; restore.
Edit check for A9: `git -C /Users/admin/Raven-b diff 3632e6040 -- tests/test_cli_onboard_commands.py` changes only `test_step4_memory_first_configured_wins`, `test_step4_memory_all_disabled_clears_backend` and `test_step4_memory_back_returns_sentinel_without_writing` (they pinned the retired run-every-screen behaviour with two fake plugins; deviations.md D2) and adds tests; no other existing test body changes.
- [ ] **Step 4: record** -- nothing expected.
---
### Task 5: the memory page reads the configured backend (H2-H5)
**Delivers**: A19, A20, A21, A36, A37 (contract level; real-host halves in Task 10).
**Files**:
- modify: `raven/rpc/methods/memory.py:39` (`_EVEROS_BACKEND` -> `_WIRE_BACKENDS`, `_CLOUD_BACKEND`), `:55-69` (`_cfg`), `:72-78` (`_post`), `:81-102` (`_search_tuning`), `:171-195` (`_unavailable_note`), plus a new `_auth_headers()`
- modify: `tests/test_rpc_memory.py` (append only)
**Interfaces**:
- consumes `raven_everos_cloud.backend.{DEFAULT_BASE_URL, resolve_api_key}` (Task 2); `raven.config.raven.load_raven_config`.
- produces `_cfg() -> tuple[str, str, str]` (shape unchanged; slice by backend), `_auth_headers() -> dict[str, str]`, `_post(base_url, path, body)` (signature unchanged; passes `headers=_auth_headers()`), `_search_tuning(base_url, kind)` (returns `{}` + `include_profile` for the cloud backend without probing), `_unavailable_note()` (per-backend `find_spec`; names the missing distribution).
- [ ] **Step 1: tests first** (append; the existing `fake_cfg` fixture at `:19-23` monkeypatches `_cfg` with a 3-tuple and must keep working):
`test_cloud_backend_adds_bearer_header_and_skips_health` (monkeypatch `load_raven_config` to a cloud config with a key; capture the headers `httpx.AsyncClient.post` receives via a `MockTransport`; assert `Authorization: Bearer ...` and no `/health` request), `test_everos_backend_sends_no_header` (A21), `test_stats_say_ok_false_on_401_and_list_carries_the_server_message` (A37), `test_missing_cloud_distribution_note_names_it` (A36: `find_spec` patched to `None` for `raven_everos_cloud`), `test_empty_store_is_ok_true_with_zeros` (A20).
- [ ] **Step 2: implement** per the spec's refined H2 block (`_cfg` keeps three values; `_auth_headers` is new).
- [ ] **Step 3: run and prove red**
Run: `uv run --frozen pytest tests/test_rpc_memory.py -q -p no:cacheprovider`
Expected: `22 passed` (17 + 5).
Zero-edit check for A21: `git -C /Users/admin/Raven-b diff 3632e6040 -- tests/test_rpc_memory.py | grep '^-' | grep -v '^---'` prints nothing (no line removed or changed).
Mutation: have `_auth_headers` return `{}` for the cloud backend -> `test_cloud_backend_adds_bearer_header_and_skips_health` fails; restore.
- [ ] **Step 4: record** -- nothing expected.
---
### Task 6: settings RPC -- the reason flag, the slice route, the cloud status, the restart guard (H6, H7, H8, H15)
**Delivers**: A23, A25, A35, A39 (contract level), the RPC half of A22 and A24.
**Files**:
- modify: `raven/rpc/methods/console.py:1243-1264` (`settings_everos`), `:630-725` (`settings_set`, new arm before the final raise), `:1362-1398` (`everos_follows_provider`), `:1426-` (`settings_everos_set`), new `settings_everos_cloud`, registration beside `:2438`
- modify: `rpc-schema/openrpc.json` (method `settings.everos` result gains `reason`; new method `settings.everosCloud`)
- modify: `raven/rpc/models.py:3761` (`SettingsEverosResult.reason`), new `SettingsEverosCloudParams` / `SettingsEverosCloudResult`, `METHOD_MODELS` at `:5444`
- modify: `tests/test_rpc_settings.py` (append only)
**Interfaces**:
- produces RPC `settings.everosCloud` (params `{}`) -> `{"available": bool, "selected": bool, "api_key_set": bool, "key_source": "file" | "env" | null, "base_url": str, "status": "ok" | "degraded" | "missing" | null, "hint": str | null}`; `settings.everos` result gains `reason: "other_backend" | null`.
- produces `settings.set` arm for `plugins.config.<plugin_id>.<field>`: `_plugin_config_declaration(plugin_id) -> dict | None` reads `registry.manifest_for(plugin_id).config_schema` from `build_plugin_registry(load_raven_config())`; `_TYPE_FOR = {"string": str, "boolean": bool, "integer": int, "object": dict}`; write through `set_plugin_config_fields`; returns `{"applied": True, "previous": None}`.
- `everos_follows_provider` and `settings_everos_set` read `load_raven_config().memory.backend` first (spec H15).
- [ ] **Step 1: contract files first** -- add the `reason` property and the new method to `rpc-schema/openrpc.json` (copy the `settings.everos` entry at `:4851` as the shape), mirror in `models.py`, register in `METHOD_MODELS`.
Run: `uv run --frozen pytest tests/test_rpc_schema_match.py tests/test_rpc_registration.py -q -p no:cacheprovider`
Expected: `test_rpc_registration` red until the handler is registered in Step 3 (that red is the point: the contract names a method nobody serves yet); `test_rpc_schema_match` green.
- [ ] **Step 2: tests first** (append to `tests/test_rpc_settings.py`, reusing its `everos_cfg` fixture):
`test_everos_roles_answer_other_backend_for_the_cloud` (A23: `available False`, `reason "other_backend"`, note names `everos-cloud`), `test_everos_roles_unchanged_for_everos_and_none` (A23/C9: compare with the dict the base worktree produced -- Task 10 records it; here assert `available True` and `reason` absent/None), `test_stale_backend_name_also_hides_roles` (A39), `test_settings_set_writes_a_declared_plugin_field` (A24's write), `test_settings_set_refuses_undeclared_wrong_type_and_unknown_plugin` (A25), `test_everos_cloud_status_reports_key_source_and_health` (A22/A24's RPC: fake cloud `ok` -> `status ok`, `401` -> `missing` with the 401 hint, no key -> `api_key_set False`), `test_provider_save_does_not_restart_everos_for_the_cloud_backend` (A35: patch `_everos_applied` to record calls; `everos_follows_provider("openrouter", factory)` with backend `everos-cloud` -> not called; with `everos` -> called when a pin names it), `test_role_write_is_refused_for_the_cloud_backend` (A35).
- [ ] **Step 3: implement** -- H6 (reason), H7 (arm), H8 (`settings_everos_cloud`: build `PluginContext` from the slice and `ServiceLocator(workspace, user_id, agent_id)`, `make_backend`, `await health()`, `await stop()`), H15 (guards), registration `dispatcher.register("settings.everosCloud", bind(settings_everos_cloud))`.
- [ ] **Step 4: run and prove red**
Run: `uv run --frozen pytest tests/test_rpc_settings.py tests/test_rpc_schema_match.py tests/test_rpc_registration.py -q -p no:cacheprovider`
Expected: `test_rpc_settings.py` `115 passed` (107 + 8); the other two green.
Zero-edit check for A26/A35: `git -C /Users/admin/Raven-b diff 3632e6040 -- tests/test_rpc_settings.py | grep '^-' | grep -v '^---'` prints nothing.
Mutations: remove the backend check from `everos_follows_provider` -> `test_provider_save_does_not_restart_everos_for_the_cloud_backend` fails; let the `settings.set` arm skip the declaration lookup -> `test_settings_set_refuses_undeclared_wrong_type_and_unknown_plugin` fails; restore both.
- [ ] **Step 5: record** -- nothing expected.
---
### Task 7: the settings page (H13)
**Delivers**: A22, A24, A26 (page level; real-host halves in Task 10).
**Files**:
- regenerate: `ui-web/src/rpc/generated.ts` (`cd ui-web && npm run gen`), `ui-tui/src/rpc/generated.ts` (`cd ui-tui && npm run gen:rpc`), `ui-tui/src/i18n/messages.generated.ts` (`cd ui-tui && npm run gen:i18n`)
- modify: `i18n/messages.json` (`ui` section: `gui.settings.cloud.title`, `.status`, `.key`, `.endpoint`, `.restart_hint`, `.chip_connected`, `.chip_needs_key`, `.chip_rate_limited`, `.chip_probing` -- `en` and `zh` both, the catalogue requires both)
- modify: `ui-web/src/features/settings/types.ts:143` (`everosCloud: EverosCloudInfo | null` on `SettingsSnapshot`; `EverosCloudInfo = ResultOf<'settings.everosCloud'>`), `store.ts:146-149` (`everosCloud: null` in `emptySnap`), `source.ts:79-83` (`loadEverosCloud` beside `loadEveros`, both awaited where `loadEveros` is; snapshot field `everosCloud`), `providers/Roles.tsx:514-526` (filter) and the new `EverosCloudCard` (export) rendered by `Roles()` under the card
- modify: `ui-web/src/rpc/fixtures/settings.ts:211-215` (a `settings.everosCloud` fixture), `ui-web/src/test/settingsHarness.ts:87` (`everosCloud` seed)
- modify tests: `ui-web/src/features/settings/providers/Roles.test.tsx`, `ui-web/src/features/settings/source.test.ts` (append only)
**Interfaces**:
- consumes `settings.everosCloud` and the `reason` field (Task 6); `KeyRow` from `pages/Tools.tsx:53` (import it; it writes through `store.write(keyName, value)` which calls `settings.set`); `Card`, `Row`, `Rov`, `Chip`, `Spin` from `Fields.tsx`.
- produces `EverosCloudCard(): JSX.Element | null` as in the spec's ui-web block; `Roles()` maps `ROLES.filter((r) => !(r.everos && r.everos !== 'embedding' && s.snap.everos?.reason === 'other_backend'))` (spec H13; the embedding row stays for knowledge bases) -- keyed on the roles RPC's `reason`, not on the cloud card's `selected`, so a future third backend hides the rows too; one comment line says so.
- [ ] **Step 1: regenerate and seed**
```bash
cd /Users/admin/Raven-b/ui-web && npm run gen && npm run gen:check # exit 0 after the regen
cd /Users/admin/Raven-b/ui-tui && npm run gen:rpc && npm run lint:rpc # exit 0
grep -c "everosCloud" /Users/admin/Raven-b/ui-web/src/rpc/generated.ts # >= 2 (params and result)
```
- [ ] **Step 2: tests first** (append):
`Roles.test.tsx`: `hides the four EverOS rows when the roles RPC says other_backend` (A22), `keeps the four rows and the not-installed pill when available is false without a reason` (A26 regression), `draws the cloud card only when everosCloud.selected` (A22), `the card's key row writes plugins.config.everos-cloud-memory.api_key` (A24: the harness records `set` calls).
`source.test.ts`: `loads settings.everosCloud beside settings.everos and seeds null on failure`.
- [ ] **Step 3: implement**, then strings:
```bash
cd /Users/admin/Raven-b && python3 - <<'EOF'
import json, pathlib
p = pathlib.Path("i18n/messages.json"); d = json.loads(p.read_text())
d["ui"].update({
"gui.settings.cloud.title": {"en": "Long-term memory: EverOS Cloud", "zh": "长期记忆:EverOS Cloud"},
"gui.settings.cloud.status": {"en": "Status", "zh": "状态"},
"gui.settings.cloud.key": {"en": "API key", "zh": "API 密钥"},
"gui.settings.cloud.endpoint": {"en": "Endpoint", "zh": "服务地址"},
"gui.settings.cloud.restart_hint": {"en": "A changed key is used by the running gateway after its next start.", "zh": "更换密钥后,运行中的网关下次启动才会使用新密钥。"},
"gui.settings.cloud.chip_connected": {"en": "Connected", "zh": "已连接"},
"gui.settings.cloud.chip_needs_key": {"en": "Needs a key", "zh": "需要密钥"},
"gui.settings.cloud.chip_rate_limited": {"en": "Rate limited", "zh": "被限流"},
"gui.settings.cloud.chip_probing": {"en": "Checking", "zh": "检查中"},
})
p.write_text(json.dumps(d, indent=2, ensure_ascii=False) + "\n")
EOF
cd ui-tui && npm run gen:i18n && npm run lint:i18n
```
(`i18n/messages.json` already carries CJK, so the source-language gate's carrier pass admits the `zh` column -- AGENTS 1.3.)
- [ ] **Step 4: run and prove red**
```bash
cd /Users/admin/Raven-b/ui-web && npm test -- Roles source 2>&1 | tail -5 # all pass; record the counts
npm run lint && npm run gen:check && npx vitest run scripts/gates/first-frame-literals.test.mjs # 5 passed on the base
cd /Users/admin/Raven-b && make build-ui 2>&1 | tail -3 # the served page must carry the card
```
Mutation: remove the `.filter(...)` in `Roles()` -> `hides the four EverOS rows ...` fails; restore.
- [ ] **Step 5: record** -- nothing expected.
---
### Task 8: documentation and terms (H14)
**Delivers**: AGENTS section 6 for the new terms; the layout page; the plugin architecture record.
**Files**:
- modify: `docs/memory-plugin-architecture.md` (a section "EverOS Cloud as a second backend": the slice, the key order, the flush policy, the two host flags `reason` and the restart guard, the not-in-default-install decision)
- modify: `docs-site/docs/repo-layout.md:11` and `docs-site/docs/repo-layout.zh.md` (the `plugins-dist/` line names four distributions)
- modify: `CONTEXT.md` Memory section (the six terms of the spec's Terms table, verbatim definitions)
- [ ] **Step 1: write**; **Step 2**: `make check-source-language && make check-large-files` -> both exit 0 (the zh layout page is a `.md`, self-governing).
---
### Task 9: the live tests (C14-C18)
**Delivers**: A32.
**Files**:
- new: `tests/integration/test_everos_cloud_real_cloud.py`
**Interfaces**: six tests named exactly as C14-C18 name them; module-level `pytestmark = pytest.mark.skipif(not os.environ.get("EVEROS_CLOUD_API_KEY"), reason="EVEROS_CLOUD_API_KEY is not set; the live EverOS Cloud tests need a key")`; `test_add_without_flush_is_searchable_within_two_minutes` additionally `@pytest.mark.skipif(not os.environ.get("EVEROS_CLOUD_SLOW"), reason="costs two minutes; set EVEROS_CLOUD_SLOW=1 to run it by hand")`. Each test uses a fresh `session_id` / `user_id` pair (`ecm-live-<uuid12>`) so runs never read each other's memory, and prints the service's raw replies.
- [ ] **Step 1: write**; **Step 2**: `uv run --frozen pytest tests/integration/test_everos_cloud_real_cloud.py -rs -q -p no:cacheprovider` -> `6 skipped`, five reasons naming `EVEROS_CLOUD_API_KEY`, one naming `EVEROS_CLOUD_SLOW`; `grep -c "^def test_\|^async def test_" tests/integration/test_everos_cloud_real_cloud.py` -> `6`. **Step 3**: when the owner provides a key (`zsh -ic`), run with it and keep the raw output under the acceptance evidence as T32.2.
---
### Task 10: the acceptance run (stage 4 proper)
**Delivers**: every `real` case of the acceptance document, the ★ journeys with
screenshots, the G4 package.
- [ ] **Step 1**: before anything, `git -C /Users/admin/Raven-b branch --show-current` -> `feat/everos_cloud_memory_plugin`; run the acceptance document's section 1.1 sweep and build the isolated home (1.3); record the baselines (1.3 last bullet) on the detached base worktree.
- [ ] **Step 2**: run sections 2.1-2.5 in order; each case leaves its evidence directory; a red case is a finding, not a reason to touch the case (prove-it-works section 1).
- [ ] **Step 3**: the five ★ journeys once more with a screenshot per screen (`playwright-cli -s=ecm screenshot`, `tmux capture-pane -p`), filed under `acceptance/`.
- [ ] **Step 4**: gates the CI runs, locally, in the order the project memory lists: `make lint lint-types check-source-language check-large-files`, `cd ui-web && npx eslint .`, `make build-ui`, `make check-commits` on each new sha; then the G4 five-dimension review and the acceptance report page (`dev-workflow` section 5).
- [ ] **Step 5**: teardown per the acceptance document 1.5; `deviations.md` gains the fallback-tier rows for every `# ponytail:` comment (`/ponytail-debt`) and the assumption-mismatch rows for temporary resources.
---
## Self-review (done before dispatching the G3 reviewer)
1. Coverage: A1-A39 each appear in a task's Delivers (A1 A3 A8 A9 A29 A38 -> 4; A2 A4 A5 A6 A7 A27 A28 -> 2 + 10; A10-A18 A33 A34 -> 2 + 10; A19 A20 A21 A36 A37 -> 5 + 10; A22 A24 A26 -> 7 + 10; A23 A25 A35 A39 -> 6 + 10; A30 A31 -> 3; A32 -> 9). C1-C3 -> Task 3 and Task 2's discover tests; C4-C8, C10 -> Task 2; C9 -> Tasks 4-7 zero-edit checks; C11-C12 -> Tasks 7, 8; C13 -> Task 3; C14-C18 -> Task 9.
2. Placeholders: none of the patterns the plan template forbids; expected outputs that can be measured today are the measured numbers above; the rest are counts the step defines (N added tests) and are to be replaced by the actual line in `run.md`.
3. Names: `resolve_api_key`, `DEFAULT_BASE_URL`, `make_backend`, `_auth_headers`, `_choose_memory_backend`, `_MEMORY_OFF`, `settings_everos_cloud`, `settings.everosCloud`, `reason`, `EverosCloudCard`, `everosCloud` are spelled the same in every task that uses them.
4. Ponytail ladder per task: Task 1 exists because every later test needs a counterparty and no real one is reachable; Task 2 copies rather than re-derives; Task 3 is three one-line edits; Task 4 is the smallest change that keeps one plugin's path identical; Task 5 keeps `_cfg`'s shape to leave 17 tests untouched; Task 6 adds one generic arm instead of a per-plugin setter; Task 7 reuses `KeyRow`, `Card`, `Chip`; Task 8 and 9 are the minimum the spec promises.
5. Authorization and caps are in the header.
6. `deviations.md` exists with D1.

File diff suppressed because it is too large Load Diff

View File

@ -33,7 +33,7 @@ them wrong reads a stopped run as still running:
|---|---|---|---|
| run dir | `<session_dir>/subagents/mas_dag/<run_id>/graph.json`, `manifest.json` | `DagRunStore.init`, `_finalize -> write_manifest` | the graph (edges, templates, `skills`, `mcps`, `inputs`, `instance`, `confirm`, top-level `replan`); per-node terminal state once finalized |
| session node registry | `<session_dir>/subagents/nodes.json` (`dag_store.REGISTRY_FILENAME`) | `record_nodes`, `ensure_node_claimed`, `record_outcome` | `nodes{<id>: {kind: dag\|spawn, run_id?, status, started_at_ms, ended_at_ms?, has_output?}}`; the only place a hard-stopped run's `cancelled` / `skipped` land |
| instance registry | `~/.raven/subagent_instances.json` (`raven.agent.subagent.instances.get_registry`) | `upsert_dag_node`, `upsert_spawn` | rows `kind in {cli, acp, dag-node}` with `runId`, `nodeId`, `status`, `createdAtMs`, `updatedAtMs`; a `dag-node` row a branch decided also carries `reason` / `selectedRoutes` / `routeEvidence` |
| instance registry | `~/.raven/subagent_instances.json` (`raven.agent.subagent.instances.get_registry`) | `upsert_dag_node`, `upsert_spawn` | rows `kind in {cli, acp, dag-node}` with `runId`, `nodeId`, `status`, `createdAtMs`, `updatedAtMs` |
Node files sit in the flat namespace `<session_dir>/subagents/nodes/<node_id>.{prompt,out,
error}.md`, `.meta.json`, `.transcript.jsonl` (older records: `mas_dag/<run>/<node>.*`; the
@ -70,7 +70,7 @@ field), `status` (`running` | `completed` | `failed` | `interrupted` | `cancelle
`started_at` / `ended_at` (epoch ms), `agent` (spawn only),
`handle` (spawn only; what `subagent.cancel_instance` takes), `counts` (`total`,
`pending`, `running`, `completed`, `failed`, `skipped`, `cancelled`, `interrupted`,
`exception`, `not_executed`), `nodes[]`.
`exception`), `nodes[]`.
`TaskNode`: `node_id`, `node_summary`, `agent`, `instance`, `status`
(`DagSnapshotNodeStatus`), `depends_on` (may name a node outside this task: the id space
@ -79,14 +79,7 @@ stores it uncapped; a spawn's is the head of `.error.md`, or of `.out.md` when `
`tokens_in` / `tokens_out` (null = the lane cannot report; never zero), `tool_call_count`
(null = zero or unreported, an acknowledged ambiguity of `as_meta`), `tool_failure_count`,
`has_output`, `prompt_template`, `inputs`, `skills`, `mcps`, `files[]`
(`{path, op: write|edit, add, del, size}`). A dag node of a branching graph also carries the
six optional branch fields, each present on a node that has one: `reason` (`when_false` |
`when_unknown` | `upstream_not_executed`, on a node the branch left out), `selected_routes`
(a decision node's selection, always a list, possibly empty -- empty is a `select: "many"`
choice, not an absent one), `route_evidence` (the judge's quote for it), and the request it
was written with -- `routes`, `select`, `when` -- of which `select` is the effective value
and `routes` the declared names alone. The three outcomes are the manifest's, and until it is
written the node's `dag-node` row supplies them. While a node runs, the usage, the tool counts and
(`{path, op: write|edit, add, del, size}`). While a node runs, the usage, the tool counts and
the files are read off the activity being collected for it in this process (the same
in-memory account `subagent.context` and `dag.node` serve a transcript from), since the record
on disk carries them only once the run finishes; what the lane has not reported yet stays null,
@ -117,9 +110,6 @@ Task status, first rule that matches: (0) `graph.json` carries `replan`: `starte
`running` / `exception` -> `running`; (4) any `cancelled` or `skipped` -> `cancelled`;
(5) `completed`. Rule 4 says *any*: `_mark_stopped` leaves completed nodes alone, so a
run stopped after its first node finishes ends as `{completed, cancelled, skipped}`.
`not_executed` is on no rung: a branch that was not taken did not stop the run, so a graph
whose only other states are `completed` reads as `completed`. Like `skipped`, a
`not_executed` node has its `started_at` / `ended_at` cleared, since it never ran.
### 3. Stop: reused

View File

@ -1,341 +0,0 @@
# EverOS Cloud memory plugin -- acceptance cases
Status: cases; G2 passed 2026-10-08
Date: 2026-10-08
Spec: `docs/specs/2026-10-08-everos-cloud-memory-design.md` (A1-A39, C1-C18, H1-H16)
Every case below names the acceptance item it proves (`T<A>.<n> <- A<A>`), where
it is observed, why that observation cannot be faked by the code under test,
what would turn it red, the evidence that the things its verdict names exist,
and which rings of evidence it leaves behind. "Real host" means the process and
entry a person uses: `raven onboard` in a terminal, `raven serve` with the web
page in a browser, `raven doctor`, `raven agent`, `raven import run`.
What this document proves, and what it does not: every case but A32's runs
real Raven against a fake EverOS Cloud (section 1.2) written from the service's
documentation. Passing all of them proves the host wiring and the plugin's own
logic; it proves nothing about EverOS Cloud itself. The live tests of A32 are
the delivery gate for that half, and until a key exists the delivery states
that no request has reached the real service (spec C14-C18).
## 1. Environment
### 1.1 Shared-resource sweep (before the first case and after any interruption)
Several Claude sessions and the owner's own Raven share this machine. The
sweep looks for what this document's processes actually put on their command
lines -- the ledger path and the ports -- because `RAVEN_HOME` is an
environment variable and never appears in `ps`:
```bash
echo "EVEROS_CLOUD_API_KEY=${EVEROS_CLOUD_API_KEY:-unset}" # must print unset outside T4.1
for p in $FAKE_PORT $SERVE_PORT $RPC_PORT; do lsof -nP -iTCP:$p -sTCP:LISTEN; done # all empty, or pids in run.md
ps -axo pid,ppid,etime,args | grep -E "[_]everos_cloud_fake .*--ledger $SCRATCH/ecm-fake|raven serve --port $SERVE_PORT"
tmux -L ecm list-sessions 2>/dev/null # none, or only ours
playwright-cli -s=ecm list 2>/dev/null | grep -c 'status: open' # 0 or 1
ls -d $SCRATCH/ecm-* 2>/dev/null
```
A non-empty line is a signal to reconcile against `run.md`, not a normal
state. Anything not listed there is somebody else's: leave it and pick other
ports. Cleanup is always by pid recorded in `run.md`, never by pattern.
### 1.2 The fake cloud (spec H16)
`tests/_everos_cloud_fake.py`: one module, two faces. `FakeCloud` is an
`httpx.MockTransport` for the contract cases; `python -m tests._everos_cloud_fake`
serves the same logic over HTTP for the real-host cases. It speaks the four
wire-table routes and, with `--with-health`, the OSS `GET /health` the local
plugin probes (used only by the baseline cases T21.2, T26.2, T26.3).
Every request -- known route or not, 404s included -- is appended by a
catch-all, before routing, to the ledger `requests.jsonl` as
`{ts, method, path, headers, body, status}`. The ledger is the counterparty's
own record: a header or body asserted from it was sent by the host process.
Modes: `ok`, `empty`, `401`, `403`, `429`, `500`, `418`, `hang` (per route,
`--hang-on /api/v2/memory/flush`), switched at run time with
`POST /_fake/mode {"mode": ..., "hang_on": [...], "auth": true|false}` so one server serves a
journey. The control route never hangs, whatever the mode. `auth: false` is the
OSS face for the local-backend cases (T21.2, T26.2, T26.3, T35.1): the local plugin
sends no key and the local server asks for none, so a request without
`Authorization` is admitted; every other case keeps the cloud's 401. In `ok` mode the data carries sentinels nothing in Raven's config
contains: episode subject `ECM-EP-5c1d`, totals 7/1/2/3, error message
`ECM-REFUSED-401` in `401` mode.
Every field the backend sends is either honoured or refused; nothing is read
and ignored (`prove-it-works` section 3):
| Field | Route | Fake's treatment |
|---|---|---|
| `user_id` / `agent_id` | search, get | exactly one required else 422 (`user_id, agent_id` named); selects the user-track rows (episodes, profiles) or the agent-track rows (agent_cases, agent_skills); the other arrays come back empty |
| `query` | search | required; recorded; does not change the scripted rows |
| `top_k` | search | truncates each returned array |
| `include_profile` | search | profiles returned only when true and the owner is a user |
| `method`, `min_score`, `radius`, `enable_llm_rerank`, `with_readable_episode`, `filters` | search | accepted and recorded; `filters.session_id` narrows `get` and `search` rows to that session |
| `memory_type`, `page`, `page_size` | get | `memory_type` must match the owner's track else 422; `page_size` truncates; `total_count` is the scripted total |
| `session_id`, `messages[]` | add | required; each message must carry `sender_id`, `role`, `timestamp` (integer), `content`, else 400 naming the field; body over 300 KB or over 500 messages -> 413 |
| `mode` | add | recorded; `agent` or `chat` only |
| `async_mode`, `app_id`, `project_id` | add | accepted and recorded |
| `session_id` | flush | required; answers `extracted` when the session has unflushed adds, else `no_extraction` |
| any other field | any | 400 naming the field |
Started through the host's background runner with the `prove-it-works`
section 8 template (trap on `EXIT INT TERM`, a flag file, a 7,200 s lifetime
cap), never with a trailing `&` in a foreground command:
```bash
sh -c 'F=$(mktemp); ( cd $SCRATCH && exec python -m tests._everos_cloud_fake --port $FAKE_PORT --mode ok --ledger $SCRATCH/ecm-fake/requests.jsonl ) > $SCRATCH/ecm-fake/server.log 2>&1 < /dev/null & C=$!;
trap "rm -f $F; kill $C 2>/dev/null" EXIT INT TERM;
( sleep 7200; [ -e "$F" ] && kill -9 $C 2>/dev/null ) & wait $C'
```
The pid is read back from `lsof -tiTCP:$FAKE_PORT -sTCP:LISTEN` and written to
`run.md`; `raven serve` is started the same way.
### 1.3 The isolated Raven
- Tree: `/Users/admin/Raven-b`, branch `feat/everos_cloud_memory_plugin`;
`git -C /Users/admin/Raven-b branch --show-current` is checked and written to
`run.md` before every run. Binary: `/Users/admin/Raven-b/.venv/bin/raven`.
Both memory plugins are installed there as workspace members; a case that
needs "only one installed" disables the other through `plugins.disabled`
(`raven/config/raven.py:1112`), which keeps a plugin out of
`build_onboard_steps` because activation skips it.
- Config home: `RAVEN_HOME=$SCRATCH/ecm-home` (`raven/home.py:48`), which
moves `config.json`, `serve.json`, `everos-server.pid` and `logs/`. The
`raven agent --home` option is **not** used: it sets
`agents.defaults.workspace`, not the config home (`raven/core/config_stack.py:27-28`).
`raven doctor` and `raven import run` take no home option at all; the
variable is the only lever. `HOME=$SCRATCH/ecm-home-user` for the import
scanner, which reads `Path.home()/.claude/projects`
(`raven/importer/scanners/claude_code.py:194-196`).
- Every command runs under `env -u EVEROS_CLOUD_API_KEY` except T4.1, which
exports it in its own subshell; the sweep prints the variable first.
- `config.json` is copied from the owner's and edited: `memory.userId` ->
`ecm-user`, `memory.agentId` -> `ecm-agent`, `memory.backend` per case,
`plugins.config["everos-cloud-memory"]` -> `{"base_url": "http://127.0.0.1:$FAKE_PORT"}`
(no key unless the case says so), `plugins.config["everos-memory"]` ->
`{"owned": false, "base_url": "http://127.0.0.1:$FAKE_PORT", "port": <a free port>, "root": "$SCRATCH/ecm-everos"}`
(`owned: false` keeps the *backend* from spawning; the local plugin's onboard
screen still spawns on its default answer, so every case that reaches that
screen answers `I run my own EverOS -- connect to it`, the port is moved off
the owner's, and the root is a copy of the owner's `everos.toml` + `ome.toml`
under `$SCRATCH` so nothing writes into the owner's root), `gateway.port` -> `$RPC_PORT`, `gateway.heartbeat.enabled` ->
false, `agents.defaults.workspace` -> `$SCRATCH/ecm-ws` (the one workspace;
session files and sub-agent records land under it), `skillForge.enabled` ->
false unless the case says otherwise. The owner's provider credentials stay,
because the chat cases need a real model; **every config snapshot archived
as evidence is passed through `jq 'walk(if type == "object" then with_entries(if (.key | test("api_?[Kk]ey")) and (.value | type) == "string" and .value != "" then .value = "<redacted>" else . end) else . end)'`
first**, so no live key lands in `.work_context`.
- Per-case isolation (`make-it-fail` section 6): each case starts by restoring
`config.json` from `config.before.json`, setting the fake's mode, and
recording `LEDGER_START=$(wc -l < requests.jsonl)`; "the ledger" in a case
means the lines after `LEDGER_START`. Each case ends by killing what it
started (pids in its `run.md`) and restoring the config.
- Web: `raven serve --port $SERVE_PORT` started from `$SCRATCH/ecm-ws`
(never from the repo tree); login by `POST /auth/nonce` with
`X-Raven-Token` from `$RAVEN_HOME/serve.json`, then `goto /auth#<nonce>`;
driver `playwright-cli -s=ecm`; `make build-ui` beforehand and the startup
log checked for the absence of `built page is older than`.
- Terminal: `tmux -L ecm new -d -s wiz`; `send-keys` types, `capture-pane -p`
reads; typing and Enter are sent separately with a pause. A command that
must finish (T29.x) runs through the host's background runner with the
section 8 watchdog; `timeout` is not assumed to exist.
- Baseline tree for T9.2 and T35.1's "before": `git -C /Users/admin/Raven-b archive 3632e6040 raven plugins-dist | tar -x -C $SCRATCH/base-src`,
then `PYTHONPATH=$SCRATCH/base-src:$SCRATCH/base-src/plugins-dist/everos-memory`
in front of the slot venv. Before a baseline half runs, the same environment
must print the base paths for both packages:
`python -c "import raven.cli.onboard_commands as m, raven_everos as e; print(m.__file__, e.__file__)"`
-> both under `$SCRATCH/base-src/`; the output goes into `run.md`. The
check and every baseline command run from `$SCRATCH`, never from the repo
root: `python -c` puts the working directory ahead of `PYTHONPATH`, and
from the root that is the branch's `raven/`. A
baseline half whose import check prints the venv paths is not a baseline and
the case is not run.
- "Plugin not installed" for T36.1: `PYTHONPATH=$SCRATCH/ecm-block` with a
`sitecustomize.py` that prepends a meta-path finder answering `None` for
`raven_everos_cloud`, which is what `importlib.util.find_spec` answers for an
absent distribution -- the host's own test for "installed"
(`raven/core/plugin_stack.py:76-88`).
- Recorded baselines (T9.1, T21.1, T23.1, T26.1, T35.2): produced once on a
detached worktree of the base commit
(`git -C /Users/admin/Raven-b worktree add $SCRATCH/base-wt 3632e6040 --detach`,
`uv sync` there), by the commands each case names; the raw output is kept in
the case's evidence directory as `baseline.txt` with the command and time.
### 1.4 Evidence
`.work_context/everos_cloud_memory/acceptance/evidence/T<id>/` holds, per
case: `run.md` (branch, commands, times, pids, exit codes, `LEDGER_START`),
`ledger.jsonl` (the case's slice), `pane.txt` or `snapshot.txt` / `shot.png`,
redacted `config.before.json` / `config.after.json` where the case writes
config, `pytest.txt` for suite cases, `baseline.txt` where a baseline is
compared. The rings follow `prove-it-works` section 10: trigger, process,
effect, visible, rerunnable.
### 1.5 Teardown (end of a run, and after any interruption)
```bash
for pid in $(grep -h '^pid ' $EVIDENCE/*/run.md | awk '{print $2}' | sort -u); do
ps -o pid,args -p $pid | grep -E "ecm-fake|--port $SERVE_PORT|--page-port $RPC_PORT" && kill $pid
done
for p in $FAKE_PORT $SERVE_PORT $RPC_PORT; do # a stopped process still holds its port while it drains
n=0; while lsof -nP -iTCP:$p -sTCP:LISTEN >/dev/null && [ $n -lt 100 ]; do sleep 0.2; n=$((n+1)); done
pid=$(lsof -tiTCP:$p -sTCP:LISTEN); [ -n "$pid" ] && grep -q "^pid $pid" $EVIDENCE/*/run.md && kill -9 $pid
done
tmux -L ecm kill-server 2>/dev/null
playwright-cli -s=ecm close-all 2>/dev/null
command rm -rf $SCRATCH/ecm-home $SCRATCH/ecm-home-user $SCRATCH/ecm-ws $SCRATCH/ecm-fake $SCRATCH/ecm-block # the homes hold provider keys
ps -Ao pcpu,pid,ppid,etime,args -r | awk '$3==1 && $1>50' # no escaped orphan
```
## 2. Cases
Columns: **Host** -- `real` (the entry a person uses, against the fake cloud),
`pytest` (the requirement is a suite's verdict, and the suite's own output is
the fact), `contract` (fake transport, or a JSON-RPC frame sent straight to the
gateway; supports a real case, never replaces it), `live` (the real service;
needs `EVEROS_CLOUD_API_KEY`). **Exists** -- for each thing the verdict names:
`today:` a command run on `3632e6040` that shows it; `new:` the spec section
that introduces it and the command the run uses to confirm it on the built
code.
### 2.1 Wizard (A1-A9, A28, A29, A38)
| T <- A | Host | Observation, and why it cannot lie | Red when | Exists | Evidence |
|---|---|---|---|---|---|
| T1.1 <- A1 | real (tmux) | Step 4 pane shows `Which memory backend?` with entries `everos`, `everos-cloud`, `Off`, `Back`, cursor on `everos` (config has `memory.backend: "everos"`). (`Back` joined the chooser after the recorded run, in the self-review round; its path is pinned by `test_step4_memory_back_on_the_chooser_returns_to_the_previous_step`, and T7.1 already shows the wizard honouring `_BACK` out of step 4.) The entries are the registry's contribution names (`PluginRegistry.onboard_names`): the wizard cannot print a name no activated plugin contributes. | no question before a plugin screen; a missing or extra entry; cursor not on the current backend | today: `grep -n "def onboard_names" raven/plugins/registry.py` -> 425; new: spec H1, confirmed by `grep -n "Which memory backend" raven/cli/onboard_commands.py` | trigger (command, time), visible (`pane.txt`), rerunnable |
| T2.1 <- A2 | real (tmux) | Continue T1.1: pick `everos-cloud`, type `ecm-key-7f3a`, Enter. Pane shows `EverOS Cloud connected.`; `config.after.json` has `memory.backend == "everos-cloud"` and `plugins.config["everos-cloud-memory"].api_key == "ecm-key-7f3a"`; the ledger holds one `POST /api/v2/memory/get` with `Authorization: Bearer ecm-key-7f3a` and `page_size: 1`. The file is the fact; the ledger proves the key typed is the key probed. | either field missing or elsewhere; probe absent or under another key | today: `set_plugin_config_fields` merge (`raven/config/update.py:365`), `set_memory_backend` writes `section["backend"]` (`:455`); new: spec onboard.py sketch, probe = health table | trigger, process (ledger), effect (`config.after.json`), visible, rerunnable |
| T3.1 <- A3 | real (tmux) | Pick `Off`. `config.after.json`: `memory.backend == null`; `jq 'del(.memory.backend, .a2a)'` of before and after are byte-identical (`.a2a` is excluded because the wizard provisions `a2a.server.token` on every run, `_initialize_a2a_face`, before and after this change alike). | any other key changes; backend keeps a name | new: spec H1 (`Off` -> `None` -> `set_memory_backend(None)`); today: `set_memory_backend(None)` writes `null` (`update.py:455`) | trigger, effect, rerunnable |
| T4.1 <- A4 | real (tmux) | In a subshell with `EVEROS_CLOUD_API_KEY=ecm-env-key` exported, start the wizard. Pane shows `Using the API key from EVEROS_CLOUD_API_KEY` and no key prompt; `config.after.json` slice has no `api_key`; ledger probe carries `Bearer ecm-env-key`. The ledger is the only place the env key is visible; the file not having it is read from the file. | a prompt appears; `api_key` lands in the file; probe uses another key | new: spec C7, onboard.py `source == "env"` branch; confirmed by `grep -n 'EVEROS_CLOUD_API_KEY' plugins-dist/everos-cloud-memory/raven_everos_cloud/*.py` | trigger, process, effect, visible, rerunnable |
| T5.1 <- A5 | real (tmux) | Fake in `401` mode. After typing a key of at least 8 characters (`ecm-bad-key-401`; the host's key prompt refuses shorter ones before the plugin sees them) the pane shows the 401 sentence (`API key rejected (401)`) and the choices `Re-enter` / `Skip long-term memory`. | the sentence is the generic "cannot reach"; no Re-enter | today: `failure_choice=_failure_choice` lent by `_onboard_ui` (`onboard_commands.py:1912-1926`); new: health table row "key rejected" | trigger, visible, rerunnable |
| T5.2 <- A5 | real (tmux) | Fake in `403` mode: pane shows `refused (403); this may mean the account is not authorized for the v2 memory API`, same two choices. Pick Skip: `config.after.json` `memory.backend == null`. | 403 gets the 401 sentence; Skip leaves a backend name | new: health table row "not authorized"; H1's `set_memory_backend(chosen if outcome is CONFIGURED else None)` writes `null` for `DISABLED` | trigger, effect, visible, rerunnable |
| T6.1 <- A6 | real (tmux) | Slice `base_url` set to `http://127.0.0.1:$DEAD_PORT` where `lsof -nP -iTCP:$DEAD_PORT -sTCP:LISTEN` is empty. Pane shows `cannot reach http://127.0.0.1:$DEAD_PORT` and the two choices. | URL absent from the sentence | new: health table row "unreachable" | trigger, visible, rerunnable |
| T7.1 <- A7 | real (tmux) | At the key prompt, send the back gesture the prompt's placeholder names (read from `pane.txt`; it is `_back_placeholder`'s text). Pane shows the step 3 header again. | Back ignored; wizard exits | today: `back_placeholder=_back_placeholder`, `prompt_api_key=_prompt_api_key` in `_onboard_ui` (`onboard_commands.py:1912-1926`); `StepOutcome.BACK -> return _BACK` (`:2020-2021`) | trigger, visible, rerunnable |
| T8.1 <- A8 | real (tmux) | `plugins.disabled: ["everos-memory"]`. Step 4 pane shows the header `Long-term memory: EverOS Cloud` directly, no `Which memory backend?`. | a chooser with one entry | today: `plugins.disabled` (`raven/config/raven.py:1112`) honoured by activation; new: spec H1 `len(steps) > 1` | trigger, visible, rerunnable |
| T9.1 <- A9 | pytest | `git -C /Users/admin/Raven-b diff 3632e6040 -- tests/test_cli_onboard_commands.py` touches only `test_step4_memory_first_configured_wins`, `test_step4_memory_all_disabled_clears_backend` and `test_step4_memory_back_returns_sentinel_without_writing` (which pinned the retired run-every-screen behaviour with two fake plugins; deviations.md D2) and adds tests; no other existing test body changes; `uv run pytest tests/test_cli_onboard_commands.py -q` passes with the base count plus the added tests. | a hunk in any other existing test; a failure | today: file exists (`ls tests/test_cli_onboard_commands.py`) | process (`pytest.txt`, `baseline.txt`), rerunnable |
| T9.2 <- A9 | real (tmux) | `plugins.disabled: ["everos-cloud-memory"]`, `memory.backend: "everos"`, `--skip-test`. Run step 4 twice from the same `config.before.json`: on the branch, and under the baseline `PYTHONPATH` after the import check of 1.3 printed the base paths. `diff <(normalise pane.branch.txt) <(normalise pane.base.txt)` is empty. Step 4 itself prints no timing under `--skip-test`; `normalise` strips the one varying thing earlier steps can leave in the same scrollback, step 1's probe duration (`f"{elapsed:.1f}s"`, `onboard_commands.py:1044`), with `sed -E 's/[0-9]+\.[0-9]s/<t>s/'`, and nothing else -- a diff that needed more stripping than that is a real difference. **Positive control, run once per session**: with one word of the step-4 header changed in a scratch copy of the branch's `onboard_commands.py`, the same diff is non-empty. The base tree is the fact about "before"; the import check proves it is the tree being run. | any differing line; the import check printed venv paths; the positive control stayed empty | today: `git archive` of `3632e6040`; `test -n "$(ls $SCRATCH/base-src/raven)"`; the import check in 1.3 | trigger, visible (both panes), process (import check output, positive control), rerunnable |
| T28.1 <- A28 | real (tmux) | In T2.1's pane the hint line contains `memory.userId` and `ecm-user`. `ecm-user` is the isolated config's owner id; a hint printing `default` would be reading something other than the locator. | hint absent; prints another id | new: spec onboard.py sketch | visible, rerunnable |
| T29.1 <- A29 | real | Both plugins, `memory.backend: null`: `raven onboard --non-interactive --yes --provider <p> --api-key <p's key> --model <the current default> --skip-test --skip-sandbox --skip-channel --skip-web --skip-subagents --skip-import` (`--yes` because the home already holds a config and `--api-key` because non-interactive step 1 demands it, each missing one exits 2 before step 4; `--model` pins the current default so step 1 writes nothing; `--skip-test` keeps step 1 from billing a test message) under the section 8 watchdog (60 s cap) prints `Long-term memory stays off`, exits 0 before the cap; no `Which memory backend?` in stdout; `config.after.json` `memory.backend == null`. | the watchdog fires (a prompt blocked); chooser text in stdout | today: sentence at `onboard_commands.py:2004`; early return `if not steps or skip or non_interactive` (`:1981`); `--non-interactive` (`:2873`) | trigger, effect, visible, rerunnable |
| T29.2 <- A29 | real | Same command with `memory.backend: "everos-cloud"` and a key in the slice: same sentence; `config.after.json` identical to `config.before.json` (sha256). | the configured backend is cleared | today: `_memory_enabled()` guard (`:2000-2001`); new: `CloudKeyScreen.configured()` returns true on a key | trigger, effect, rerunnable |
| T38.1 <- A38 | real (tmux) | At `Which memory backend?` send `C-c`. Pane shows the shell prompt; `echo $?` prints `1`; `config.after.json` identical to before (sha256). The exit code alone proves little -- Click exits 1 on any `KeyboardInterrupt` (`onboard_commands.py:668` leaves it to propagate); the load-bearing assertion is the unchanged config, which only H1's "nothing written on cancel" produces. | `memory.backend` becomes `null` or any key changes; a screen runs | new: spec H1 (`typer.Exit(1)` on a cancelled select, nothing written) | trigger, effect (config sha), visible, rerunnable |
### 2.2 Recall, store and the two explicit ends (A10-A18, A33, A34)
| T <- A | Host | Observation, and why it cannot lie | Red when | Exists | Evidence |
|---|---|---|---|---|---|
| T10.1 <- A10 | contract | `FakeCloud` serves two episodes (scores 0.3, 0.9) and one profile of 1,500 chars. `recall("q", user_id="ecm-user", top_k=5)` returns three `Memory`, scores descending, the profile text ending in `[profile truncated, N chars omitted]`; the ledger request has `Authorization: Bearer <key>`, `include_profile: true`, `user_id: "ecm-user"`. | order wrong; no marker; header or flag missing | new: spec backend.py `recall`; `_flatten_profile` cap copied from `raven_everos/backend.py:1785,1832-1840` | process (ledger), effect (returned list), rerunnable |
| T10.2 <- A10 | real | `raven agent -m "What do you remember about me?"` with the owner's real model. Ledger: a `POST /search` with `Bearer`, `include_profile: true`, `user_id: "ecm-user"`, no `agent_id`. The fake is the counterparty: a request in its ledger was sent by the host process a person runs. | no search; wrong owner; header missing | today: `raven agent -m` (`agent_commands.py:222`); user-track recall path `raven/context_engine/segments/memory.py:27` | trigger, process (ledger), rerunnable |
| T11.1 <- A11 | contract | 20 plain `store` calls on one session: 20 `/add`, each `mode: "agent"`, user message `sender_id == "ecm-user"`, assistant `sender_id == "ecm-agent"`, `timestamp` integer > 10^12; zero `/flush` (C6). | `mode` missing or `chat`; a slice-sourced id; any flush | new: spec C5, C6; copied `convert_messages` (`raven_everos/backend.py` `def convert_messages`) | process, rerunnable |
| T11.2 <- A11 | real | The T10.2 run's ledger slice: exactly one `/add` after the `/search`, `mode: "agent"`, sender ids `ecm-user` / `ecm-agent`; no `/flush` between the add and the process's last request (the one flush at exit belongs to T18.2). | a flush right after the add; `mode` absent | as T11.1 | process, rerunnable |
| T12.1 <- A12 | contract | `FakeCloud` in `hang` mode: `recall` returns `[]` after 4.0-4.5 s (measured with `time.monotonic`), `recall_session` after 10.0-10.5 s; in `500` and `429` modes both return at once and `store` returns `False`; no exception in any mode. | an exception; a bound missed | new: spec C8 constants `RECALL_TIMEOUT_S = 4.0`, `SESSION_TIMEOUT_S = 10.0` | process, rerunnable |
| T12.2 <- A12 | real | Fake `hang` on `/search` only. `raven agent -m "hello" --logs` exits 0 and answers; the log carries the plugin's recall-timeout warning, `recall timed out after 4.0 s; returning empty` (spec backend sketch); the ledger shows the `/search` and then the turn's `/add`. The log line is written by the plugin inside the real process; the exit code and the following add show the turn was not held hostage. | the run hangs past the model's own time plus 10 s (watchdog); no warning; no add after the hung search | today: `raven agent --logs` (`agent_commands.py:268`); new: spec C8, the warning text in backend `recall` | trigger, process (log, ledger), rerunnable |
| T13.1 <- A13 | contract | `recall("q", agent_id="ecm-agent", top_k=5)` sends `agent_id` only and maps `agent_skills` -> `type: skill`, `agent_cases` -> `type: case` from the fake's agent-track rows (the fake serves agent rows only to an `agent_id` owner, so a request that sent `user_id` would get none); `recall("q", top_k=5)` and `recall("q", user_id="u", agent_id="a", top_k=5)` return `[]` with no request in the ledger and a warning in caplog. | both ids on the wire; a request on the invalid calls; agent rows answered to a user-track request | new: spec backend.py `recall` (XOR copied from `raven_everos/backend.py` `recall`); fake field table | process, rerunnable |
| T13.2 <- A13 | real | `skillForge.enabled: true`; `raven agent -m "hello"`. Ledger holds a `/search` with `agent_id: "ecm-agent"` and no `user_id` (the skill router's recall), beside the user-track `/search` of T10.2. | no agent-track search; both ids on one request | today: `BackendSkillSource.recall(agent_id=...)` (`raven/memory_engine/skill_forge/backend_source.py:95-99`); new: spec backend `recall` | trigger, process (ledger), rerunnable |
| T14.1 <- A14 | contract | `store(sid, msgs, metadata={"flush": True, "user_id": "u2", "agent_id": "a2"})`: ledger shows one `/add` with sender ids `u2` / `a2`, then exactly one `/flush {"session_id": sid}`. | no flush; two; host ids | new: spec "explicit end"; `_owner_override` copied from `raven_everos/backend.py:501-513` | process, rerunnable |
| T14.2 <- A14 | contract | Same call spelled `{"flush": True, "userId": "u2", "agentId": "a2"}` produces the same two requests with the same ids. | the camelCase call falls back to `ecm-user` / `ecm-agent` | today: `raven/agent/subagent_memory.py:69-76` reads both spellings; `_owner_override` as above | process, rerunnable |
| T14.3 <- A14, A15 | real | A sub-agent configured with a `memory` block (`SubagentMemoryConfig`, `raven/config/schema.py:1379`: `userId: "sub-u"`, `agentId: "sub-a"`, `source: "trace"` -- the source is what makes the host write and read back the trace, `manager.py:712`; the default `agent` source joins on an instance id a stateless sub-agent never has; the agent itself is an `openai`-kind sub-agent on an endpoint whose key has quota); `raven agent -m "Use the spawn tool to have a sub-agent reply with the single word pineapple"`. **Precondition asserted first**: a node directory appeared under `$SCRATCH/ecm-ws/sessions/*/subagents/` (the model did call spawn); a run without one is recorded as "precondition not met" and repeated, not as a failure of the plugin. Fake `ok` serves, for `/get` with `filters.session_id` of that spawn, one episode `ECM-EP-5c1d`. Ledger: `/add` with sender ids `sub-u` / `sub-a` for that session (its body size recorded in `run.md`, as the measured headroom under 250 KB), immediately followed by `/flush` for it, then `/get {user_id: "sub-u", memory_type: "episode", filters: {session_id: ...}}`. `<node>.memory.json` holds `status: "settled"` and, under `memories`, the fake's episode text (`Prefers short answers; names files.`, the row whose subject is `ECM-EP-5c1d`; the host maps the row's text, not its subject) and a case item carrying `ECM-CASE-5c1d`. Both strings exist only in the fake; the record file is written by the host from what `/get` returned. | the add carries the host's ids; no flush before the read-back; the record is `pending` / `unavailable`; the text is absent | today: handoff `metadata={"flush": True, **scope.block}` (`subagent_memory.py:199`), record dir `_HISTORY_DIRNAME = "subagents"` (`raven/agent/subagent/history.py:44`), workspace from `agents.defaults.workspace`; new: spec backend `recall_session` | trigger, process, effect (`*.memory.json`), rerunnable |
| T15.1 <- A15 | contract | `recall_session(sid, user_id="u2")`: ledger `/get` body has `user_id: "u2"`, `memory_type: "episode"`, `filters: {"session_id": sid}`, `page_size: 100`; rows map to `Memory`. `recall_session(sid, agent_id="a2")` asks `memory_type: "agent_case"`. | filter missing; wrong type for the track | new: spec wire table `/get` row | process, rerunnable |
| T16.1 <- A16 | contract | Importer-shaped calls: three `store` with `{"bulk": True, "is_final": False}` then one with `is_final: True`: four `/add`, one `/flush` after the fourth add, none earlier. | a flush after a non-final batch; none after the final | today: `raven/importer/orchestrator.py:253` metadata shape; new: spec "explicit end" | process, rerunnable |
| T16.2 <- A16 | real | `$HOME/.claude/projects/ecm-proj/one.jsonl` (a 30-message Claude Code transcript fixture); `raven import run --platform claude_code --tier full --yes` (`full`: the `memory_files` tier keeps only memory files, `raven/importer/types.py:85-89`, and this fixture is a conversation). Ledger for that session id: three `/add` (10 messages each, `_BATCH_MSG_LIMIT = 10`), then exactly one `/flush`, as the last request for the session; the command exits 0. | zero or several flushes; a flush before the last add | today: `import run` subcommand with `--platform/--tier/--yes` (`raven/cli/import_commands.py:512-516`; the group is `import`, `raven/cli/commands.py:218`), scanner root (`claude_code.py:194-196`), `_BATCH_MSG_LIMIT = 10` (`orchestrator.py:30`) | trigger, process, rerunnable |
| T17.1 <- A17 | contract | A 600-message `store`: two `/add` (500 + 100), both `mode: "agent"`. A slice whose JSON is 400 KB of 40 messages: adds split at a message boundary, each body < 250 KB. | one request; a split inside a message | new: spec C10, `ADD_MAX_MESSAGES`, `ADD_MAX_BYTES` | process, rerunnable |
| T17.2 <- A17 | contract | A slice with one 300 KB message and four small ones: the four go out in one `/add`; `store` returns `True` (the dropped message cannot be retried into fitting, and a `False` would have both callers re-store the four); caplog has a warning naming the session id and the message index. | the big message is sent; the small ones are dropped; `True` | new: spec failure row "request body" | process, rerunnable |
| T17.3 <- A17 | real | `raven agent --message-file $SCRATCH/big.txt` where the file holds 300 KB of text. Ledger: the turn's `/add` carries the assistant message and not the 300 KB user message (no body in the slice exceeds 250 KB); the log has the warning naming the session and message index; the run exits 0. The ledger is the counterparty's: a 300 KB body would be in it. | a body over 250 KB in the ledger; no warning; the assistant message also missing | today: `--message-file` (`agent_commands.py:223`); new: spec failure row "request body" | trigger, process (ledger, log), rerunnable |
| T18.1 <- A18 | contract | Plain stores on `s1`, `s2`, `s3`; explicit-end store on `s2`; `stop()`: ledger gains exactly `/flush s1` and `/flush s3` (any order), then the client is closed (`client.is_closed`). With the fake hanging on `/flush`, `stop()` returns within 5.5 s and caplog names the sessions left. | `s2` flushed again; a session missing; `stop()` past 5.5 s | new: spec backend `stop`, `SHUTDOWN_FLUSH_BUDGET_S = 5.0` (copied from `_SHUTDOWN_FLUSH_BUDGET_S`, `raven_everos/backend.py:159`) | process, rerunnable |
| T18.2 <- A18 | real | The T14.3 run has two sessions in one process: the main turn (plain adds, never flushed) and the sub-agent's (explicit end, flushed). At exit the ledger gains exactly one more `/flush`, for the main session, and none for the sub-agent's; the plugin's stop-sweep line, `flushed 1 session(s) at stop` (spec backend sketch), is INFO on a standard-library logger, which `raven agent --logs` does not bridge (only WARNING and above reach the terminal); it is read in T34.2's `import.log`, where the importer installs the bridge. Two sessions with different histories give the sweep a way to be wrong; the sweep line is the plugin's own account of what it did. | the sub-agent session flushed twice; the main session not flushed; a sweep line naming two | today: `backend.stop()` at one-shot exit (`raven/cli/agent_commands.py:512`); new: spec backend `stop` and its log line | trigger, process (ledger, log), rerunnable |
| T33.1 <- A33 | pytest | `uv run pytest tests/test_everos_cloud_backend_contract.py -q` passes; `--collect-only -q` lists every test `MemoryBackendContractTests` and `LifecycleContractTests` define (same count as `tests/test_everos_backend_contract.py` collects for the local plugin, which inherits the same two classes and defines no test of its own). | a test skipped or overridden; counts differ | today: `raven/memory_engine/contract_test.py:34,169`; `tests/test_everos_backend_contract.py:10` imports both | process (`pytest.txt`), rerunnable |
| T34.1 <- A34 | contract | Fake `ok` for `/add`, `hang` for `/flush`; `RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S=1`: explicit-end `store` returns `False` after 1.0-1.5 s; the session is still in `_unflushed`; a following `stop()` (fake back to `ok`) issues `/flush` for it. | `True`; the session dropped | new: spec backend `store` / `_unflushed`, `RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S` (Decisions) | process, rerunnable |
| T34.2 <- A34 | real | `RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S=2`, fake `ok` with `--hang-on /api/v2/memory/flush`; `raven import run --platform claude_code --tier full --yes` on the T16.2 fixture. The importer's final batch fails its flush and retries by calling `store` again each time (`_STORE_RETRY_BACKOFF_S = (30, 60, 120)`: four attempts, about four minutes in all); every attempt is a whole `store`, so the ledger shows for the final batch four `/add` of the same ten messages (the duplicate-add exposure of spec Open question 3, visible here) each followed by a hung `/flush`, then one more `/flush` at exit (the stop sweep, which the hang also defeats); the command exits non-zero reporting the batch not accepted; the log's sweep warning names the session. The attempt count and the exit are the importer's, the extra flush is the sweep's -- neither can be produced by a session that left the set. | fewer `/add` than attempts (a store that skipped its add), a `/flush` count equal to the attempts (no sweep), exit 0, or no warning | today: importer retry loop (`raven/importer/orchestrator.py:254-270`); new: spec backend `store`, `stop`, the env hook | trigger, process (ledger, log), effect (exit code), rerunnable |
### 2.3 Memory page (A19-A21, A36, A37)
| T <- A | Host | Observation, and why it cannot lie | Red when | Exists | Evidence |
|---|---|---|---|---|---|
| T19.1 <- A19 | real (web) | `memory.backend: "everos-cloud"`, key in slice, fake `ok`. Open the memory page: `snapshot` shows the four `.memstats` values `7`, `1`, `2`, `3`; the Episodes list shows a row with `ECM-EP-5c1d`. Ledger slice: every request carries `Authorization: Bearer`, and no line has `"path": "/health"` -- the fake's catch-all records unknown routes, so a probe would be there as a 404. The numbers and the subject exist only in the fake. | the `TwoPaneNone` "off" pane renders; a request without the header; a `/health` line; a count not from the fake | today: `.memstats` (`ui-web/src/features/memory/MemoryPage.tsx:110`), `if (s.note) return <TwoPane><TwoPaneNone` (`:65`); new: spec H2-H5, H16 catch-all | trigger, process (ledger), visible (`snapshot.txt`, `shot.png`), rerunnable |
| T20.1 <- A20 | real (web) | Fake `empty` mode: `.memstats` values all `0`; no `TwoPaneNone` in the snapshot; the Episodes tab shows the "0 total" note; the ledger slice since page load holds a `POST /api/v2/memory/get` with `page_size: 1` and `Bearer` for each of the four kinds (the page asks for the stats more than once per open, so the count is per kind, not a total). The page half alone is what an idle page also shows; the requests are what make it a measurement. | a kind never asked; a note; a retry control | today: `memory_stats` asks one `/get` per kind (`raven/rpc/methods/memory.py:220-233`) | trigger, process (ledger), visible, rerunnable |
| T20.2 <- A20 | contract | `memory.stats` over the gateway's WebSocket (JSON-RPC, cookie `raven_session_$SERVE_PORT`, `Origin` header) with the fake `empty`: `ok: true`, `note: null`, four zeros. | `ok: false`; a note | today: `memory.stats` shape (`memory.py:198-240`) | effect (RPC reply), rerunnable |
| T21.1 <- A21 | pytest | `git diff --stat 3632e6040 -- tests/test_rpc_memory.py` empty; `uv run pytest tests/test_rpc_memory.py -q` passes with the count in `baseline.txt`. | a hunk; a failure | today: file exists | process, rerunnable |
| T21.2 <- A21 | real (web) | `memory.backend: "everos"`, fake `--with-health`. Open the memory page: the ledger slice has no `Authorization` header on any request and includes `GET /health`. | a header appears; `/health` absent | today: `_cfg` everos arm (`memory.py:55-69`), `_search_tuning` probes (`:81-102`), `owned: false` means no spawn (`CONTEXT.md` EverOS; `raven-plugin.toml` `owned`) | trigger, process, visible, rerunnable |
| T36.1 <- A36 | real | `memory.backend: "everos-cloud"`, `PYTHONPATH=$SCRATCH/ecm-block` (1.3). **Preflight**: `raven doctor --json` under the same environment parses as JSON (the command itself runs). Then `raven doctor; echo $?` prints a memory line containing `did not build` and exits `2`; `raven serve` under the same `PYTHONPATH`: the memory page's `TwoPaneNone` text contains `everos-cloud-memory`. | exit 0; the note names nothing; the preflight fails (a usage error also exits 2) | today: doctor "did not build" branch (`raven/cli/doctor_commands.py:688-697`), exit on `faults` (`:255`), `--json` (`:1077`), no `--home` option (`:1075-1089`); new: spec H5 note naming the distribution | trigger, effect, visible, rerunnable |
| T37.1 <- A37 | real (web) | Fake `401` mode: the Episodes tab's error text contains `everos refused the request:` followed by the fake's `error.message` (`ECM-REFUSED-401`). | the list error says "unreachable" | today: `_everos_error` (`memory.py:105-122`) | trigger, visible, rerunnable |
| T37.2 <- A37 | contract | `memory.stats` over the gateway WebSocket with the fake in `401`: `ok: false`, four zeros, `note: null`. | `ok: true` | today: `memory_stats` degrades per kind (`memory.py:227-233`) | effect, rerunnable |
### 2.4 Settings page and the restart guard (A22-A27, A35, A39)
| T <- A | Host | Observation, and why it cannot lie | Red when | Exists | Evidence |
|---|---|---|---|---|---|
| T22.1 <- A22, A23 | real (web) | `memory.backend: "everos-cloud"`. Model page snapshot: none of the three EverOS-only role labels (`Memory extraction`, rerank, multimodal) is present in any form -- in particular not the dim `The EverOS memory plugin isn't installed` pill that today's `available: false` draws; the embedding row is present (knowledge bases embed with that pin); a card titled by `gui.settings.cloud.title` with a status chip, a key row and the endpoint `http://127.0.0.1:$FAKE_PORT`. | one of the three rows visible in any form; the not-installed sentence; the embedding row missing; card absent | today: `Roles` maps every `ROLES` entry (`Roles.tsx:514-526`), the not-installed pill (`:265-272`, string `gui.settings.roles.everos_missing`), label `gui.settings.roles.memllm` = "Memory extraction" (`i18n/messages.json`); new: spec H6 `reason`, H13 filter, H8, cloud strings | trigger, visible, rerunnable |
| T23.1 <- A23 | contract (pytest) | `settings_everos({})` with `memory.backend = "everos-cloud"` -> `reason: "other_backend"`, note contains `everos-cloud`, `set(sections) == {"embedding"}`, `required` holds nothing but `embedding`; with `"everos"` and with `None` -> the dict in `baseline.txt` for that config. | sections reported for the cloud; `reason` missing; a change for `everos` / `None` | today: `settings_everos` (`console.py:1243-1264`); new: spec H6 | process, rerunnable |
| T24.1 <- A24 | real (web) | Type `ecm-key-rot8` in the card's key row, Save: `config.after.json` slice `api_key == "ecm-key-rot8"`; chip reads connected; ledger shows a `/get page_size: 1` with `Bearer ecm-key-rot8`. Switch the fake to `401`, save `ecm-key-bad`: chip text contains `rejected (401)`. The file and the ledger carry the typed value. | key written elsewhere; chip unchanged; probe under the old key | today: `KeyRow` writes `store.write(keyName, v)` (`ui-web/src/features/settings/pages/Tools.tsx:53-70`); new: spec H7 route, H8 RPC | trigger, process, effect, visible, rerunnable |
| T25.1 <- A25 | contract (pytest) | `settings_set({"key": "plugins.config.everos-cloud-memory.nope", "value": "x"})`, `(... ".api_key", 42)`, `("plugins.config.not-a-plugin.api_key", "x")` and `("plugins.config.everos-cloud-memory.base_url", "http://attacker.test")` (declared but not `settable`: the endpoint decides where the stored key is sent) each raise `ConfigValidationError` whose message contains the key; `config.json` unchanged after all four. (`null` on a settable key is admitted as "unset", admission's rule for an optional key.) | a write lands; a message without the key | today: `settings_set` final `raise` (`console.py:725`); new: spec H7 | process, rerunnable |
| T25.2 <- A25 | contract | The same three frames sent to the running gateway over its WebSocket: each answer is a JSON-RPC error containing the key; `config.after.json` identical to before. | an `applied` result; a config change | today: `/rpc` WebSocket with cookie and `Origin` check; new: spec H7 | effect (reply, config sha), rerunnable |
| T26.1 <- A26 | pytest | `git diff --stat 3632e6040 -- tests/test_rpc_settings.py ui-web/src/features/settings/providers/Roles.test.tsx ui-web/src/features/settings/source.test.ts` empty; `uv run pytest tests/test_rpc_settings.py -q` and `cd ui-web && npm test -- Roles source` pass with the counts in `baseline.txt`. | a hunk; a failure | today: the three files exist | process, rerunnable |
| T26.2 <- A26 | real (web) | `memory.backend: "everos"` (fake `--with-health`): Model page shows the four EverOS role rows and no cloud card. | a card; a hidden row | today: Roles.tsx role rows (`:43-56`, `:514-526`) | trigger, visible, rerunnable |
| T26.3 <- A26, A23 | real (web) | `memory.backend: null`: Model page shows the four EverOS role rows (the `None` arm answers as today) and no cloud card. | a card; a hidden row | today: `settings_everos` answers for any backend when the plugin is installed (`console.py:1243-1264`) | trigger, visible, rerunnable |
| T27.1 <- A27 | real | **Preflight**: `raven doctor --json` parses as JSON. Then `raven doctor; echo $?` under seven conditions -- fake `ok`, `401`, `403`, `429`, `hang`, `418`, and no key with the fake up -- prints the health table's sentence for each (the seven literal fragments: the base URL after `ok`, `rejected (401)`, `refused (403)`, `rate limited by`, `cannot reach`, `answered 418`, `no API key`) and exits `2` for the five `missing` answers, `0` for `ok` and `429`. `--json` shows the same seven under `memory`. | two conditions share a sentence; 429 exits 2; `ok` exits non-zero; the preflight fails | today: rendering `_render_memory_capabilities` (`doctor_commands.py:725-745`), exit on `faults` only (`:124`, `:255`), `--json` (`:1077`), options list without `--home` (`:1075-1089`); new: health table | trigger, effect (stdout, exit codes), rerunnable |
| T35.1 <- A35 | real (web) | `memory.backend: "everos-cloud"`, both plugins active, `plugins.config["everos-memory"].owned: false` (as 1.3; nothing can spawn here). Record before: the set `P0` of pids whose args match `everos server start --root $RAVEN_HOME/everos` (empty), the line count `L0` of `$RAVEN_HOME/logs/*.log` (asserted to exist and be non-empty first), absence of `$RAVEN_HOME/everos-server.pid`. On the Model providers page save a key for the main model's provider, then change the main model. After each: the pid set is still empty, the pidfile still absent, and `grep "everos restart .* begin" $RAVEN_HOME/logs/*.log` finds no line after `L0`; the page snapshot has no banner mentioning a memory restart. **Before (baseline `PYTHONPATH`, import check passed)**: the same two actions make `everos restart <id> begin` appear after `L0` -- with `owned: false` the local plugin logs the restart and stops short of spawning (`server.py:1273,1283`), so the log line is the whole symptom and nothing needs killing. The log lines are written by the local plugin inside the gateway; the pid set is the operating system's; the before/after difference is the guard. | a restart line after `L0` in the after-run; a pid or pidfile appears; no line in the before-run (the before-run did not exercise the path) | today: `everos_follows_provider` (`console.py:1362-1398`) called from `model.py:578`; `everos_follows_main_model` from `config.py:665`; pidfile `everos-server.pid` (`raven_everos/server.py:304`), argv `everos server start --root` (`:1017`), log `everos restart {} begin` (`:1273`), `owned: false` path (`:1283`); new: spec H15 | trigger, process (log before/after), effect (pid set, pidfile), visible, rerunnable |
| T35.2 <- A35 | contract (pytest) | `settings_everos_set({"section": "llm", "model": "m", "provider": "p"})` with `memory.backend = "everos-cloud"` raises `ConfigValidationError` containing `everos-cloud`; nothing written; the same call for `section: "embedding"` is accepted (knowledge bases keep their pin). With `"everos"` the call behaves as `baseline.txt` records. | the write succeeds; `everos` changes | today: `settings_everos_set` (`console.py:1426-`); new: spec H15 | process, rerunnable |
| T35.3 <- A35 | pytest | `uv run pytest tests/test_rpc_settings.py -q -k "restart or queued"` collects the base tree's set (the seven `TestTheSaveRestartsTheService` tests, among them `test_a_session_that_queued_a_restart_hears_how_it_went` and `test_a_cancelled_restart_still_reports`) plus this change's `test_provider_save_does_not_restart_everos_for_the_cloud_backend`, and passes, with no existing line of the file edited (T26.1's check). | a base test missing from the collection; a failure | today: `tests/test_rpc_settings.py:339,422`; `-k "follows"` deliberately not used (it also matches `:1047`, an unrelated test) | process, rerunnable |
| T39.1 <- A39 | contract (pytest) | `settings_everos({})` with `memory.backend = "mem0"` -> `reason: "other_backend"`, sections holding only `embedding`, note contains `mem0`. | sections reported; `reason` missing | new: spec H6 (any non-`everos`, non-`None` name) | process, rerunnable |
| T39.2 <- A39 | real (web) | `memory.backend: "mem0"`: Model page snapshot has none of the memllm / rerank / multimodal rows (the embedding row stays) and no cloud card; the memory page shows the "runs on 'mem0'" note. | a role row | today: memory page note branch (`memory.py:188-195`); new: spec H6, H13 | trigger, visible, rerunnable |
### 2.5 Structure, release and the live service (A30-A32)
| T <- A | Host | Observation, and why it cannot lie | Red when | Exists | Evidence |
|---|---|---|---|---|---|
| T30.1 <- A30 | pytest | `uv run pytest tests/test_plugin_boundary.py -q` passes, and `test_scan_roots_exist` now asserts both plugin roots are non-empty (so an empty scan cannot pass vacuously). A deliberate `import raven_everos_cloud` added to `raven/core/plugin_stack.py` turns `test_host_does_not_import_plugin_internals` red (then reverted; `git diff` clean). | the mutation stays green | today: `tests/test_plugin_boundary.py:20-22,50`; new: spec H9 | process (`pytest.txt` with the mutation run), rerunnable |
| T30.2 <- A30 | pytest | A test imports every module under `raven_everos_cloud` with `sys.modules["everos"] = None` and `sys.modules["raven_everos"] = None`; passes. Adding `import raven_everos` to `backend.py` turns it red (then reverted). | the mutation stays green | new: spec C3 | process, rerunnable |
| T31.1 <- A31 | pytest | `git diff --stat 3632e6040 -- tests/test_release_plugin_list.py` empty; `uv run pytest tests/test_release_plugin_list.py -q` passes; `grep -c "uv build --wheel plugins-dist/" .github/workflows/release.yml` prints `4` (3 on the base); `grep -c -- "-eq 3" .github/workflows/release.yml` prints `1`. | the list grows; the wheel is not built | today: `release.yml:85-90,187` (3 and 1 on the base) | process, rerunnable |
| T32.1 <- A32 | pytest | `N=$(grep -c "^def test_" tests/integration/test_everos_cloud_real_cloud.py)` equals 6, the number of tests C14-C18 name; without the variable, `uv run pytest tests/integration/test_everos_cloud_real_cloud.py -rs -q` reports 6 skipped: five with a reason containing `EVEROS_CLOUD_API_KEY`, and `test_add_without_flush_is_searchable_within_two_minutes` with its own reason (run by hand; spec C17). | N is not 6; a test runs or passes without a key; a reason missing | new: spec C14-C18 test names | process, rerunnable |
| T32.2 <- A32 | live | With `EVEROS_CLOUD_API_KEY` set (`zsh -ic` to load it): the five key-gated tests pass; the C17 test is run by hand once and its output kept. **Deferred until a key exists; the delivery says so.** | any failure; a skip hidden as a pass | spec C14-C18 | trigger, process, effect (the service's own replies), rerunnable |
## 3. Human walk-through (★)
Five journeys, at most one screen each, for the owner to take by hand after
the agent has run them. Each names what the person looks at, not what to
assert.
| ★ | Journey | Cases | Look at |
|---|---|---|---|
| ★1 | Configure the cloud backend in the wizard, once with a good key and once with a rejected one | T1.1, T2.1, T5.1 | the chooser's three entries and preselection; the connected line; the 401 sentence with Re-enter; `config.json` afterwards |
| ★2 | Open the memory page on the cloud backend | T19.1 | four counts that match the fake's 7/1/2/3; an episode row reading `ECM-EP-5c1d`; nothing saying the memories are elsewhere |
| ★3 | Change the key on the settings card | T22.1, T24.1 | no memllm / rerank / multimodal rows at all (not even the "plugin isn't installed" line), the embedding row still there; the card's chip turning connected, then showing the 401 wording after a bad key |
| ★4 | Run `raven doctor` against the seven conditions | T27.1 | seven different sentences; exit code 2 only for the five faults |
| ★5 | Save a provider key with the cloud backend active | T35.1 | no restart line in the gateway log, no EverOS process, no pidfile, no banner -- and the same action on the base tree writing the restart line |
## 4. Coverage
Counts from the machine check in section 5: 39 A items, 64 T cases; 35 `real`,
9 `pytest`, 19 `contract`, 1 `live`. Every A has at least one case; every A
has a `real` case except these, each with the reason it cannot have one:
| A | Why no real-host case | What stands instead |
|---|---|---|
| A25 (undeclared settings key refused) | no page control sends an undeclared key or a wrong type; the refusal guards against a client the page is not, so the only entry that reaches it is a JSON-RPC frame | T25.1 in process, T25.2 against the running gateway (both `contract`) |
| A30, A31, A33 | the requirement is a suite's verdict; the suite's output is the fact | the `pytest` cases, with a mutation run for A30 |
| A32 | the real service; deferred until a key exists, and the delivery says so | T32.1 proves the skip reasons and the count; T32.2 runs live later |
No A is marked "not built", "unit only" or "fixture only".
## 5. Machine check
```bash
python3 - <<'EOF'
import re, pathlib
doc = pathlib.Path("docs/specs/2026-10-08-everos-cloud-memory-acceptance.md").read_text()
spec = pathlib.Path("docs/specs/2026-10-08-everos-cloud-memory-design.md").read_text()
a_in_spec = set(re.findall(r"^\| (A\d+)", spec, re.M))
rows = [l for l in doc.splitlines() if re.match(r"^\| T\d+\.\d+ <- A", l)]
covered, hosts, real_as = set(), {}, set()
for r in rows:
cells = [c.strip() for c in r.strip("|").split("|")]
aa = re.findall(r"A\d+", cells[0]); covered.update(aa)
h = cells[1].split()[0]; hosts[h] = hosts.get(h, 0) + 1
if h == "real": real_as.update(aa)
print("A in spec:", len(a_in_spec), "covered:", len(covered), "missing:", sorted(a_in_spec - covered, key=lambda x: int(x[1:])))
print("T rows:", len(rows), hosts)
print("A without a real-host case:", sorted(a_in_spec - real_as, key=lambda x: int(x[1:])))
assert a_in_spec == covered
EOF
```

File diff suppressed because it is too large Load Diff

View File

@ -1,122 +0,0 @@
# Episodic log writer: acceptance cases
Companion to `2026-10-12-episodic-log-writer-design.md`. One row per case,
each pointing back at an acceptance item (A1-A16) there. "Real host" means
the agent drives the gateway the way a person does; a row marked "unit" is a
quick check during the work and does not count as acceptance on its own.
Test names are filled in after the code lands; "pending" means the file or
function does not exist yet. Line numbers are against `main` at `829eb28e1`.
## 0. Shared resources and the reset to run first
Every real-host case runs in its own `RAVEN_HOME` under the session
scratchpad, never in `~/.raven`. Before any case, and after any interruption:
```bash
# nothing of ours listening; ports are per home (see table)
for p in 18820 18821 18822 18823 18824 18825 18826 18827 18830 18835 18836; do lsof -nP -iTCP:$p -sTCP:LISTEN && echo "port $p busy"; done
# the control plane falls back to 8765 regardless of --port
lsof -nP -iTCP:8765 -sTCP:LISTEN
# no gateway of ours still alive: kill by pid only, after reading its args
ps -ww -o pid=,lstart=,args= -p "$(cat "$SCRATCH"/elw_*/gateway.pid 2>/dev/null | tr '\n' ' ')" 2>/dev/null
```
| Home | Purpose | `memory.backend` | Ports (rpc / page) | Extra config |
|---|---|---|---|---|
| `elw_native` | T1-T11, T12, T15 | `null`, `plugins.disabled: ["everos-memory"]` | 18820 / 18821 | `memory.annotate_every_turns: 3`; `gateway.heartbeat.enabled: false`; `skillForge.enabled: false`; `sentinel.enabled: false` |
| `elw_heartbeat` | T15 (live variant) | `null` | 18822 / 18823 | as above plus `gateway.heartbeat.enabled: true` with the shortest interval the schema allows |
| `elw_backend` | T13, T14 | `"everos"`, EverOS `owned: true` on 18830, `plugins.config.everos-memory.base_url` pointed at the EverOS-side logging proxy on 18836 | 18824 / 18825 | as `elw_native` for the rest; EverOS root under the home |
| `elw_baseline` | T12's reference capture | `null`, as `elw_native` | 18826 / 18827 | same config as `elw_native`; the gateway binary is `main` at `829eb28e1`, run from a checkout of that commit (`git worktree` or `PYTHONPATH`, the way #440's before/after was driven), confirmed at runtime by printing `render.__file__` |
All three route the agent's provider through a local logging proxy
(`providers.custom.apiBase = http://127.0.0.1:18835/v1`) that writes every
request body to `$SCRATCH/elw_proxy/<ts>.json` and forwards it unchanged to
the real provider, `Authorization` header included. The proxy is the layer
that owns two facts no other surface exposes: the exact system prompt that
went out (T12, T13) and the moment the annotator's request left (T7). The
`custom` provider is the generic OpenAI-compatible gateway
(`raven/providers/per_model_provider.py:26`), so the proxy needs no
protocol translation. The proxy is started with `run_in_background`, holds
a `trap ... EXIT`, and is killed by pid in the teardown of the last case.
The proxy has one control: a file `$SCRATCH/elw_proxy/mode` it re-reads on
every request. `pass` (default) forwards everything. The other modes apply
only to a request whose `tools[0].function.name` is `annotate_conversation`
and leave the agent's own requests untouched: `hold:10` sleeps ten seconds
before forwarding (T7, T8); `fail:500:once` answers one request with HTTP 500
and then resets itself to `pass` (T9); `empty:once` answers one request with
a well-formed `annotate_conversation` tool call whose `episode_summary` is
`[]`, then resets (T10). The case writes the mode before its sends and
asserts the file reads `pass` at its end. The proxy is not committed: it is a
few dozen lines of aiohttp that an operator rebuilds from the contract above,
and nothing in the design depends on it. A second instance of it on 18836
fronts EverOS for `elw_backend`, in `pass` mode only, so T14 can read what
`/add` received.
Driving a turn without a browser: `raven gateway --port <rpc> --page-port
<page>` from inside the home's workspace, then over WebSocket at
`http://127.0.0.1:<page>/rpc` with `Origin: http://127.0.0.1:<page>` and the
cookie `raven_session_<page>` (value: `cookie` in `<home>/serve.json`):
`session.create` -> `session_id`; `turn.subscribe {"session_key"}`;
`turn.send {"session_key", "content"}`. `message.complete` marks the reply.
Observation points used below, and where each fact lives:
| Fact | Owner | Read it with |
|---|---|---|
| lines written | the file | `cat <workspace>/user_memory/episodic/episodes.md` |
| the cursor | the session file | `grep '"_type": "metadata"' <workspace>/sessions/<slug>/<chat_id>.jsonl \| tail -1` (`raven/session/manager.py:754-760` writes that record; the last one wins on load, `:551`) |
| the reply moment | the event stream | `message.complete` timestamp from `turn.subscribe` |
| the annotator's request | the proxy | the capture file whose `tools[0].function.name == "annotate_conversation"` (`consolidator.py:1035` names it) |
| the system prompt | the proxy | the first `messages[0].content` of the turn's request |
| a declined or failed annotation | the gateway log | `<home>/gateway.log` (`raven/cli/gateway_commands.py:453-455`), the `episodic annotate` lines the change adds (pending) |
| the profile refresh ran | the offsets file | `<workspace>/user_memory/episodic/.consolidation_offsets.json` (`consolidator.py:1183-1187`) |
| `last_consolidated` untouched | the session file | the same metadata record's sibling field, or `session.status` |
## 1. Cases
| T <- A | Real host | Observation point, and why it cannot lie | Goes red when | Named things exist (command run) | Evidence to collect | ★ |
|---|---|---|---|---|---|---|
| T1 <- A1 | yes (`elw_native`) | Seed a session file by copying one with 12 messages from `~/.raven/workspace/sessions/` into the home's `sessions/<slug>/`, send one turn, read the last metadata record: `annotated_through` must be 12 (the length before that turn, not 14) and `episodes.md` must be empty. The number 12 is in no config and no prompt; only a seed read from the real message count produces it | no seed: the file gains lines from the copied history; or the seed lands at 14 and the turn just sent can never count | `sessions/<group>/<chat_id>.jsonl` layout: `grep -n 'chat_id}.jsonl' raven/session/manager.py` -> `:377`; `"_type": "metadata"` record: `sed -n 754,760p raven/session/manager.py`; `annotated_through`: pending | command, the copied file's line count, the metadata record, `wc -c episodes.md` (0), branch sha, home path | |
| T2 <- A2 | yes (`elw_native`) | With N=3: send three user turns whose content is unrelated to anything in the fixture (three distinct nouns chosen at run time). After the third `message.complete`, poll up to 60 s: `episodes.md` gains at least one line matching `^\[\d{4}-\d{2}-\d{2} \d{1,2}:\d{2}\]` (`consolidator.py:243`), the cursor equals the session's message count, and the proxy holds exactly one `annotate_conversation` request whose `messages` start at a `user` message and end with the third reply. The run-time nouns cannot be guessed by a stale file or a cached response | the step never fires, fires on the wrong boundary, or the cursor is not patched | regex: `sed -n 243p consolidator.py`; `annotate_conversation`: `grep -n annotate_conversation consolidator.py` -> `:1035`; `message.complete`: memory recipe 2026-10-10 | the three sends with timestamps, the captured request body, `episodes.md` before/after, the metadata record, offsets file | ★ |
| T3 <- A3 | yes (`elw_native`) | Fresh session, N=3, send two turns, wait 60 s: no `annotate_conversation` request in the proxy, file unchanged, cursor unchanged | the count is of messages (two turns are four messages) | as T2 | proxy listing (zero matches), file size, metadata record | |
| T4 <- A4 | yes (`elw_native`, `annotate_every_turns: 0`) | Send six turns, wait 60 s: no `annotate_conversation` request, file unchanged, and no `annotated_through` key in any metadata record (the knob short-circuits before the seed) | the seed runs before the knob check, or the knob is not read | `annotate_every_turns`: pending (new field at `raven/config/raven.py:1161` region) | proxy listing, `grep -c annotated_through <jsonl>` (0), config excerpt | |
| T5 <- A5 | yes (`elw_native`) | After T2's state (cursor = m), call `session.undo` with `n: 2` (TUI `/undo`, `ui-tui/src/app/slash/commands/core.ts:902`): the metadata record the undo writes already shows `annotated_through` pulled back to the cut. Then send three turns: the next `annotate_conversation` request's first message is the first user message after the undo cut, not an earlier one; `last_consolidated` in the metadata record is 0 before and after | the cursor is left past the end (the undo's record still shows m, and the three turns after it send nothing), or the step moved `last_consolidated` | `session.undo`: `grep -n 'register("session.undo"' raven/rpc/methods/session.py` -> `:1494`; `undo_last_turn` floor: `sed -n 282,300p raven/session/manager.py` | undo response (`removed`), the two metadata records, the captured request's first message | |
| T6 <- A6 | yes (`elw_native`) | After T2: kill the gateway by pid, start it again on the same home, send one turn: the metadata record's `annotated_through` is still T2's value (not reseeded to the new length, not absent) | the patch was not appended, or a later `save` dropped the key | `append_metadata_patch`: `grep -n 'def append_metadata_patch' raven/session/manager.py` -> `:682`; gateway pid: `<home>/gateway.pid` written by our launcher (pending) | `ps` before kill, the two boot banners in `gateway.log`, the metadata record | ★ |
| T7 <- A7 | yes (`elw_native`) | Hold the proxy for 10 s on `annotate_conversation` requests only (the proxy sleeps before forwarding when the tool name matches). On the third turn, `message.complete` arrives before the proxy's forward timestamp for that request. Two clocks on one machine, both written by processes the step does not control | the step is awaited inline | proxy hold flag: pending (proxy script); `message.complete`: as T2 | the event timestamp, the proxy's receive/forward timestamps | |
| T8 <- A8 | yes (`elw_native`) | With the proxy holding 10 s, send turns 3 and 4 within that window: the proxy records exactly one `annotate_conversation` request, and after release the cursor equals the message count at the time the first task sliced (turn 3's end), then the next qualifying turn picks up from there | no lock (two requests), or the tail is sliced outside the lock (the second request includes turn 3 again) | `get_lock`: `grep -n 'def get_lock' consolidator.py` -> `:1663` | proxy listing (one match), both metadata records | |
| T9 <- A9 | yes (`elw_native`) | Make the proxy answer `annotate_conversation` with HTTP 500 once: the file is unchanged, the cursor is unchanged, `gateway.log` gains the warning line, and the next qualifying turn sends the same tail again (same first message) | the cursor advances on False | warning text: pending (until the text lands, the log clause is checked by the unit twin asserting `logger.warning`'s arguments; the live case then matches the exact line); `chat_with_retry` path: `grep -n chat_with_retry consolidator.py` -> `:1104` | proxy 500 record, log line, two captured requests' first messages | |
| T10 <- A10 | yes (`elw_native`) | Make the proxy answer with a well-formed tool call whose `episode_summary` is `[]`: the file is unchanged, the cursor advances to the message count, and the log carries a debug line with `0` written | the step inspects the file and refuses to move | `n_written` path: `sed -n 1120,1176p consolidator.py` (returns True on zero) | proxy response record, metadata record, log line | |
| T11 <- A11 | unit only, by decision | Monkeypatch `append_metadata_patch` to raise; the task logs a traceback and the next turn in the same test completes. A11 has no real-host case: the only live fault that reaches this `except` is a write failure on the session file, and making that file unwritable also breaks the turn's own `save`, so the live observation would not isolate the branch. This narrows A11 to a unit check and needs the maintainer's word at G2 | the exception reaches the turn | pending test; `logger.exception` site: pending | pytest output | |
| T12 <- A12 | yes (`elw_native`) | The system prompt captured by the proxy for any turn contains both `user_memory/profile/user.md` and the `Episodic log:` line with `(grep-searchable)`, and, after replacing the home's absolute path with `<HOME>` in both captures (the render embeds `home_path`, `render.py:396`, `:423-424`, `:457-458`, so two homes never match literally), byte-for-byte equal to the same block captured from `elw_baseline` | the no-backend branch was touched; also red if the normalisation is skipped, which is the reverse check that the diff is live | current text: `sed -n 420,426p raven/context_engine/segments/render.py`; path embedding: `grep -n 'home_path = ' render.py` -> `:396` | both captures, the normalised pair, `diff` of the identity block (empty) | |
| T13 <- A13 | yes (`elw_backend`) | The system prompt captured for a turn names `episodes.md` exactly once, on a line containing `read-only`, and still contains `never report it to the user as done or as failed`; it does not contain `profile/user.md` | the line is missing, the #894 sentence was dropped, or the profile path crept back | #894 sentence: `sed -n 413,419p render.py`; read-only line: pending | the capture, `grep -c` for each of the three strings | ★ |
| T14 <- A14 | yes (`elw_backend`) | For one turn, the EverOS-side proxy captures exactly one `POST /api/v2/memory/add`, and its body's `messages` (`backend.py:389`) are, message for message, the entries that turn appended to the session file (the jsonl lines after the previous `"_type": "metadata"` record). Same run, two owners of the same fact, so model nondeterminism cannot split them; `_dispatch_backend_store` is unchanged, so the only way they diverge is ordering damage from the new block | the new block disturbs the slice (a missing or extra message, or a second `/add`) | endpoint and body: `grep -n 'memory/add' -B 6 plugins-dist/everos-memory/raven_everos/backend.py` -> `:389` `"messages": payload_messages`; plugin endpoint key: `base_url` in `raven_everos/config.py` | the captured `/add` body, the jsonl slice, the field-by-field comparison | |
| T15 <- A15 | yes (`elw_heartbeat`) + unit | Live: with heartbeat on and N=1, let three heartbeat turns run (count them in `gateway.log`), send no user turn: no `annotate_conversation` request, no `annotated_through` key. Unit: call the helper with each of `SENTINEL`, `CRON`, `HEARTBEAT`, `SUBAGENT` and assert no consolidator call; drive a whole turn with `_req(text, origin=...)` (`tests/test_agent_loop_run_emit.py:156`) and `_stub_edges(loop)` (`:165`), which already take the origin | the origin check admits more than `USER` | `Origin` members: `sed -n 9,16p raven/spine/turn.py`; heartbeat switch: `grep -n heartbeat raven/config/raven.py \| head -3`; heartbeat turns in the log: pending (until the text lands, count them by the `turn.subscribe` events on the heartbeat session instead) | log excerpt with the heartbeat turns, proxy listing, metadata records | |
| T16 <- A16 | yes (`elw_native`) | After T2 on session S (m messages), call `session.branch` (TUI `/branch`, alias `/fork`, `ui-tui/src/app/slash/commands/session.ts:356-358`) to get S2, send one turn on S2: S2's first metadata record with the key reads `annotated_through = m` (the fork length), and after three more turns on S2 the captured request's first message is S2's first own user message | the child inherits no cursor and no seed runs, so the parent's history is in the request | `session.branch`: `grep -n 'register("session.branch"' raven/rpc/methods/session.py` -> `:1497`; fork drops metadata: `sed -n 866,890p raven/session/manager.py` | branch response (child key), S2's metadata records, the captured request | |
Every case starts by asserting its home has no gateway listening on its
ports and no `annotate_conversation` capture newer than the case start, and
ends by killing the gateway it started (by pid from `gateway.pid`) and
removing its capture files. T13 and T14 additionally stop the owned EverOS and the EverOS-side proxy by
pid; T12 stops the `elw_baseline` gateway by pid.
## 2. Unit checks during the work (not acceptance)
| Check | What it pins | File |
|---|---|---|
| each T1-T10 as a pytest with a fake consolidator recording its arguments | the helper's arithmetic and the lock, without a provider | pending (`tests/test_agent_loop_episodic_annotate.py`, to be created) |
| T11 | exception containment | same file |
| T12, T13 as render tests | the two prompt branches | `tests/test_segments.py` (exists; `test_identity_with_a_backend_names_no_memory_file` at `:1`-region asserts `"user_memory" not in seg.text` and must change) |
| reverse check for A4 | delete the `every <= 0` clause: T4's unit twin goes red | same file |
Each unit twin is made red once before it is trusted: remove the guard it
claims to cover, run, confirm red on the asserted symptom, restore, `git
diff` clean.
## 3. Hand-run (★)
| T | Why a person | What they do |
|---|---|---|
| T2 | the main journey; the lines' wording is the product | read the lines the annotator wrote for three turns they typed themselves and say whether each line is a fair one-line summary with sensible tags |
| T6 | irreversible if wrong (a lost cursor replays history) | kill and restart the gateway themselves, send one message, open the session file and find `annotated_through` |
| T13 | wording that an agent might read as permission | read the captured system prompt once and say whether the read-only line could be read as "you may edit" |

View File

@ -1,442 +0,0 @@
# Episodic log writer: a periodic annotator after the turn
Change proposal. Reader: whoever reviews or implements the restoration of the
`episodes.md` writer tracked in #122. After reading, you can say which files
move, by how much, what could silently break, and how each acceptance item is
checked on a live gateway. Line numbers are against `main` at `829eb28e1`.
## Goal
`user_memory/episodic/episodes.md` has no writer on any surface people use.
The only writer, the annotator (`MemoryStore.annotate`,
`raven/memory_engine/consolidate/consolidator.py:985`), runs inside the
token-pressure compaction loop (`maybe_consolidate_by_tokens`, `:1746`), and
all three calls into that loop are gated on `owns_compaction`
(`raven/agent/loop/turn_path.py:2191`, `:2707`,
`raven/rpc/methods/session.py:1077`), which the only shipped context engine
hardcodes to `True` (`raven/context_engine/assembler.py:111`). The annotator
survives as live code with one caller, `/new` typed as message text in a chat
channel (`turn_path.py:2164` -> `consolidate_unconsolidated`,
`consolidator.py:1729`); the web and TUI "new session" buttons go through
`session.create` and never reach it. Six readers read the empty file: the
prompt line (no-backend branch only since #894), two attention producers
(`currently_focused`, `project_rhythm`) and three predictor modules
(`daily_analysis`, `task_discoverer`, `context_assembler`).
This change gives the log a writer that does not depend on compaction: after
a user turn, once enough user turns have accumulated since the last
annotation, the unannotated tail is handed to the annotator. The host's own
memory and the plugin backend run side by side; the plugin is untouched. The
prompt's backend branch names the log again, read-only.
Shapes rejected in discussion: pointing the readers at EverOS (its episodes
carry no `#tag` and no one-line summary, so `project_rhythm` and
`daily_analysis` cannot consume them without reinventing the annotator);
flipping `owns_compaction` (puts the old consolidator back in charge of the
Curator's pointer); deleting the log and its readers (the proactive layer is
parked, not retired); making native and plugin memory mutually exclusive
(withdrawn by the maintainer on 2026-10-12).
## Non-goals
- No memory-writing tool for the agent. A validated `remember` tool is a
separate change.
- No change to `owns_compaction`, the Curator, `Session.last_consolidated`,
or the `/new` path.
- No change to the Sentinel readers or to how `# Memory` reads `user.md`
(its lexical section pick never matches a Chinese message and falls back to
the whole file; that is a separate defect).
- No change to the EverOS plugin or the `MemoryBackend` contract.
- No annotation of history that predates the writer: an existing session is
annotated from the first turn after upgrade onward, never back-filled.
- No annotation of machine-initiated turns (`Origin.SENTINEL`, `CRON`,
`HEARTBEAT`, `SUBAGENT`); only `Origin.USER` turns count and are written.
- No lock on `episodes.md` itself. `append_history` stays a bare append; see
F5 for why that is acceptable.
- No entry in the self-configuration surface (`raven/config/self_surface.py`,
`raven/config/live.py`): the knob is read at boot, so changing it needs a
gateway reload.
- `/compress` copy and the `memory.backend = None` docstring are separate
branches.
## Constraints
| # | Kind | Constraint | How it is checked |
|---|---|---|---|
| C1 | design | The annotate step never moves `Session.last_consolidated`; its own cursor is `session.metadata["annotated_through"]`, written through `SessionManager.append_metadata_patch`; truncation moves the cursor where it happens (`Session.undo_last_turn` pulls it back to the cut, `Session.clear` drops it), the way the same two methods already treat `last_consolidated` | A5, plus a grep in review: no assignment to `last_consolidated` and no `sessions.save` in the new code |
| C2 | design | The step never splits a turn: the tail it annotates starts and ends on a turn boundary | A2 |
| C3 | design | The step never blocks the reply: it is a tracked background task, the shape of Step 4 at `turn_path.py:2710-2724` | A7 |
| C4 | design | Per session, annotation runs under the consolidator's session lock (`MemoryConsolidator.get_lock`), the same lock `/new` holds; the tail is computed inside the lock, so a task that waited re-reads the cursor and finds nothing to do | A8 |
| C5 | architecture | No new import edge: `raven/agent/loop/_shared.py:68` already imports `raven.memory_engine` | `uv run --frozen --all-extras lint-imports` stays at 10 contracts kept |
| C6 | assumption | `MemoryConsolidator.consolidate_messages` then `maybe_refresh_hot_tags`, under `get_lock(session.key)`, is the write path `/new` runs today (`consolidator.py:1729-1743`) | verified 2026-10-12 against a live gateway, not by reading: reading missed that the annotator's `tool_choice="required"` (`consolidator.py:1111`) is refused by the default model, which made the whole path inert. See the provider repair below |
| C11 | assumption | A forced tool choice reaches the model. It does not on every vendor: DeepSeek's thinking mode answers `HTTP 400: Thinking mode does not support this tool_choice`, and eleven call sites across the repo force a choice | measured 2026-10-12 against the live vendor, three ways (`required` -> 400, `auto` -> tool called, omitted -> tool called); the adapter now relaxes and retries once, which `tests/test_providers_forced_tool_choice.py` pins |
| C7 | assumption | A metadata patch survives a restart: `append_metadata_patch` appends one record and the last record wins on load (`raven/session/manager.py:682-703`, `_scan_file` at `:546`) | verified 2026-10-12 by reading; A6 restarts the gateway and checks the cursor |
| C8 | assumption | The consolidator's provider and model follow a `/model` switch (`raven/agent/loop/wiring.py:1119` calls `set_provider`) | verified 2026-10-12 by reading; not re-tested here |
| C9 | design | `annotate_every_turns = 0` short-circuits the step; the only other conditions are the turn's origin and the count | A4 |
| C10 | design | A cursor that is absent is seeded at `prev_len`, the message count before the turn that just ended, and counting continues in the same pass; so neither an upgraded install nor a forked session hands its history to one provider call, while a new session counts from its first turn | A1 (seed), A16 (fork) |
## Perspective checklist
| # | Perspective | Applies? |
|---|---|---|
| V1 context | Applies, see Participants. The new participant is "a session that existed before the writer": its history is never annotated; only turns from the first one seen onward are. A trajectory replay (`raven/trajectory/replay.py:1155`) calls the turn without an origin and is never annotated. |
| V2 scenarios | Applies, see Paths. |
| V3 structure | Applies, see Placement: one new block and one helper in the after-turn pipeline, no new module. |
| V4 data | Applies, see Data: `episodes.md` gains a writer; the cursor is a new persisted field. |
| V5 state | Applies, see Cursor states. The empty state is "never seen". |
| V6 interaction | Not applicable for new Raven-internal messages: there are none. The step adds one outbound provider call per `annotate_every_turns` user turns (`provider.chat_with_retry`, `consolidator.py:1104`), a path no shipped install has run before; its timeout and failure are F1. |
| V7 deployment | Applies, one row: the step runs inside the gateway process, in the turn's event loop, as a detached task. No new process. |
| V8 failure | Applies, see FMEA. "Another writer changed this data" is a row: `/new` and the eval adapter append to the same file. |
| V9 decisions | Applies, see Decisions. |
| V10 traceability | Applies, see Acceptance. |
## Participants
| Participant | Person or system | Wants | Crosses the boundary via |
|---|---|---|---|
| A reader on web or TUI | person | their conversations summarised into the log without typing `/new` | nothing new; the step fires after their turn |
| The agent | system | to grep the log when it helps | the prompt's read-only line |
| Two attention producers | system | non-empty episodes to count by `#tag` | `MemoryStore.history_file`, unchanged |
| Three predictor modules | system | episodes windowed by day, and a recent tail | `MemoryStore.history_file`, unchanged |
| EverOS plugin | system | the same turn slice it gets today | `_dispatch_backend_store`, unchanged |
| A session that existed before the writer | system | not to have its history replayed into one call | the seed rule (C10) |
| Sentinel, cron and heartbeat | system | their own turns kept out of the log they read | the origin check |
| An ACP host driving this Raven | system | its prompts answered; whether they belong in this instance's log is a deployment question | `turn.send`, which stamps `Origin.USER` -- a parent agent's prompt is indistinguishable from a person's here |
## Paths
| # | Given | When | Then | Acceptance |
|---|---|---|---|---|
| P1 | cursor absent, session has 12 messages from before this turn | a user turn ends | cursor is seeded at 12 (`prev_len`); the turn itself is counted from there and, alone, is below N, so nothing is annotated | A1 |
| P2 | cursor at i, `annotate_every_turns = 5` | the 5th user turn since i ends | the tail `messages[i:]` is annotated; the file gains lines; cursor = `len(messages)` | A2 |
| P3 | cursor at i, 3 user turns since | a user turn ends | nothing is called | A3 |
| P4 | knob = 0 | any turn ends | nothing is called, cursor untouched | A4 |
| P5 | cursor at i | the reader undoes two turns past i, then user turns end | `undo_last_turn` pulled the cursor back to the cut, so the first turn after the undo counts; no re-annotation of removed messages; `last_consolidated` unchanged | A5 |
| P6 | cursor at i | the gateway restarts | cursor is still i on the next turn | A6 |
| P7 | the annotator's provider call takes 10 s | a user turn ends | the reply is delivered before the call resolves | A7 |
| P8 | an annotate task for session S holds the lock | the next user turn on S ends and would qualify | the new task waits, re-reads the cursor the first task wrote, finds fewer than N new turns, and returns without a provider call | A8 |
| P9 | the provider call fails (`consolidate_messages` returns False) | a user turn ends | the cursor does not advance; a warning is logged; the next qualifying turn retries the same tail | A9 |
| P10 | the annotator answers but writes zero lines (`annotate` returns True with nothing kept) | a user turn ends | the cursor advances past the tail; a debug line records zero lines | A10 |
| P11 | `append_metadata_patch` or `maybe_refresh_hot_tags` raises inside the task | a user turn ends | the exception is logged with a traceback and the task ends; nothing is re-raised into the turn | A11 |
| P12 | a backend is wired | the identity prompt is rendered | the backend branch names the log, read-only; the no-backend branch is unchanged | A12, A13 |
| P13 | a backend is wired | a user turn ends | `_dispatch_backend_store` still runs with the same slice | A14 |
| P14 | a turn with `Origin.SENTINEL` (or `CRON`, `HEARTBEAT`, `SUBAGENT`) ends | - | nothing is called; machine-initiated turns neither count nor get written | A15 |
| P15 | session S is forked to S2 | the 5th user turn on S2 ends | S2's cursor was seeded at fork length on first sight; only S2's own turns are annotated | A16 |
## Data
**`episodes.md`** (exists; gains a writer)
| Question | Answer |
|---|---|
| Lives longer than | the session; it is per workspace |
| Who writes it | the annotator through `append_history` (`consolidator.py:719`), from this step, from `/new`, from the eval adapter (default off). `append_history` is a bare `open(..., "a")` + one `write` per entry; `MemoryStore.locked()` (`:647`) locks `user.md.lock` (`:622`) and does not cover this file |
| Reader's relation | the agent greps it; Sentinel parses it line by line with `parse_episode_line` (`:247`); a line that does not match is skipped silently by every reader |
**`session.metadata["annotated_through"]`** (new)
| Field | Type | Produced by | When |
|---|---|---|---|
| `annotated_through` | int, index into `session.messages` | the annotate step, via `append_metadata_patch` | on seed (first sight) and after each annotation that returned True |
| Entity | Created | Updated | Read | Deleted |
|---|---|---|---|---|
| cursor | first time the step sees the session: seeded at `prev_len` | after each `consolidate_messages` that returns True; pulled back to the cut by `Session.undo_last_turn`; read as `min(stored, len(messages))` as a last guard against a hand-edited file | the annotate step | dropped by `Session.clear` (`/new`, `session.clear`), so a cleared session is seen afresh and counts from its first new turn. `Session.fork` (`manager.py:866`) copies messages but not metadata; the child is seeded on first sight |
## Cursor states
| State | Entered when | Observable | Actions | Left when |
|---|---|---|---|---|
| never seen | session created or forked; key absent | file has no line for this session | seed at `len(messages)` | the first user turn after the writer exists |
| annotated through i | seed, or annotation returned True | `metadata.annotated_through == i` | count user turns in `messages[i:]` | annotation returns True again, or undo brings `len(messages) < i` |
| pulled back | undo removed messages past i | `annotated_through == cut_index` in the record the undo's save writes | count from the cut | the next annotation |
| locked | a task for this session holds `get_lock(key)` | a second task on the same key is waiting | the waiter recomputes from the cursor after acquiring | the holder releases |
## Placement
One block in `raven/agent/loop/turn_path.py`, directly after Step 4 (lines
2710-2724). It takes only the origin half of Step 4's guard: Step 4 is `if
self.personalization_enabled and origin is not Origin.SUBAGENT:` (`:2713`);
this step does not follow the personalization switch and admits only
`Origin.USER` (`raven/spine/turn.py:9-16`), which also keeps out the
Sentinel, cron and heartbeat turns the comment at `:2199-2203` says reach
this flow. It runs on the main-turn site only; the `deliver_text` site at
`turn_path.py:3129` does not run it.
Before (the end of Step 4, verbatim, `:2721-2724`):
```python
_t4 = asyncio.create_task(_post_learn())
self._consolidation_tasks.add(_t4)
_t4.add_done_callback(self._consolidation_tasks.discard)
# ── End Step 4 ──────────────────────────────────────────────────────
```
After (indicative; names are placeholders until written):
```python
# ── End Step 4 ──────────────────────────────────────────────────────
if origin is Origin.USER:
self._maybe_annotate_tail(session, prev_len)
```
with, in the same file:
```python
def _maybe_annotate_tail(self, session: Session, prev_len: int) -> None:
every = self._annotate_every_turns # MemoryConfig.annotate_every_turns
if every <= 0:
return
async def _run() -> None:
try:
async with self.memory_consolidator.get_lock(session.key):
stored = session.metadata.get("annotated_through")
if stored is None:
stored = prev_len
self._set_annotated_through(session, prev_len)
start = min(int(stored), len(session.messages))
tail = session.messages[start:]
if sum(1 for m in tail if m.get("role") == "user") < every:
return
if not await self.memory_consolidator.consolidate_messages(tail):
logger.warning("episodic annotate for {} declined; cursor kept", session.key)
return
self._set_annotated_through(session, start + len(tail))
await self.memory_consolidator.maybe_refresh_hot_tags()
except Exception:
logger.exception("episodic annotate for {} failed", session.key)
task = asyncio.create_task(_run())
self._consolidation_tasks.add(task)
task.add_done_callback(self._consolidation_tasks.discard)
def _set_annotated_through(self, session: Session, n: int) -> None:
session.metadata["annotated_through"] = n
self.sessions.append_metadata_patch(session.key, {"annotated_through": n})
```
`append_metadata_patch` (`manager.py:682`) rather than `sessions.save`: the
task runs detached and can land mid-way through the next turn, and a whole
`save` of this task's copy of the metadata would drop keys the turn wrote in
between (the method's docstring says exactly this). `_consolidation_tasks` is
created at `main.py:650`.
`raven/config/raven.py`, `MemoryConfig` (`:1129`), one field after
`memory_top_k` (`:1161`):
```python
annotate_every_turns: int = 0
"""How many user turns accumulate before the unannotated tail is handed
to the annotator and written to ``episodes.md``. ``0``, the default,
turns the step off: it costs one provider call per cadence, and an
install that never reads the log should not pay for it. The tail always
starts and ends on a turn boundary because the step runs after a turn,
so this is a cadence, not a cut point. Read at boot; a change needs a
gateway reload."""
```
`raven/context_engine/segments/render.py:413-419`, the backend branch.
Before (verbatim):
```python
if has_memory_backend:
home_memory = (
" — your own skills, not a place for user artifacts.\n"
" - Memory is not yours to write: what is relevant is recalled into the `# Memory`\n"
" section each turn, and the host persists the conversation after it ends. You\n"
" cannot observe that write, so never report it to the user as done or as failed."
)
```
After (indicative):
```python
if has_memory_backend:
home_memory = (
" — your own skills, not a place for user artifacts.\n"
" - Memory is not yours to write: what is relevant is recalled into the `# Memory`\n"
" section each turn, and the host persists the conversation after it ends. You\n"
" cannot observe that write, so never report it to the user as done or as failed.\n"
f" - Episodic log, read-only: {home_path}/user_memory/episodic/episodes.md "
"(grep-searchable; the host appends to it, you do not)."
)
```
The no-backend branch (`:420-426`) is unchanged.
Also touched: `raven/providers/openai_responses_provider.py` gains the
repair its Anthropic sibling already has (`anthropic_messages_provider.py:505`):
a 400 that names `tool_choice` while the body forces one relaxes it to `auto`
and retries once. Without it the annotator never writes on the default model.
Eleven call sites force a choice today (two in the consolidator, one in the
behaviours extractor, four in the proactive layer, four in the playbook
compiler), so the repair is placed where all of them pass rather than at the
two this change depends on. Adapters for the other protocols (`litellm`,
`azure`, `codex`) do not carry it; the default model routes to `responses`.
Also touched: `Session.clear` drops the cursor and `Session.undo_last_turn`
pulls it back to the cut (`raven/session/manager.py:276-306`), beside the
same methods' handling of `last_consolidated`; their three callers
(`turn_path.py:2178`, `rpc/methods/session.py:987`, `:1020`) all save
afterwards and need no change.
Not touched: `owns_compaction`, the three guards, `consolidate_unconsolidated`,
`last_consolidated`, `_dispatch_backend_store`, every reader, `Session.fork`.
## Sizing
| Item | Size (estimate) | Depth | Why that depth |
|---|---|---|---|
| after-turn block + two helpers | `turn_path.py`, ~45 lines | deep | runs an LLM call on every install; a wrong cursor re-annotates or skips silently; a blocking await would stall every reply; a missing seed replays a session's whole history in one call |
| config field | `raven.py`, ~7 lines | shallow | additive, default-off, boot-time read |
| prompt line | `render.py`, ~2 lines | deep | shared text every backend-wired install renders; #440 was a wording accident on this exact block |
| tests | 3 files: `tests/test_agent_loop_episodic_annotate.py` (new, ~150 lines), `tests/test_segments.py` (~15 lines changed), `tests/integration/test_episodic_writer_real_llm.py` (new, ~60 lines) | - | see Acceptance |
Dependencies: none. Minimal set: the block, the helpers and the field are the
fix; the prompt line can ship separately, but without it an agent under a
backend never learns the log exists.
Perspective rows this change touches: V2 P1-P15 (new), V4 cursor (new
entity), V5 all four states (new), V8 rows F1-F8 (new), V9 D1-D8. No existing
state table changes: `last_consolidated` keeps its meaning and its one reader
(`undo_last_turn`, `raven/session/manager.py:282`).
## FMEA
| # | Part | Failure | Effect | Detected by | Recovery | Severity |
|---|---|---|---|---|---|---|
| F1 | annotator provider call | times out or errors (`consolidate_messages` returns False) | tail not written | warning log; A9 | cursor kept, next qualifying turn retries | low |
| F2 | annotator | returns lines that do not match `parse_episode_line` | readers skip them silently | none at write time (pre-existing property of the readers); no A | none; out of scope, noted for the `remember` change | low |
| F3 | cursor | undo leaves it past the end | would slice to empty and never fire | A5 | clamp before counting | medium |
| F4 | cursor | gateway dies between `append_history` and the metadata patch | file has the lines, cursor not advanced; next run re-annotates the same tail, duplicating lines | not tested; accepted in D5 | duplicates are harmless to grep and over-count a tag by one batch at most | low |
| F5 | another writer | `/new` or the eval adapter appends while this task appends | entries from two writers interleave in the file | none needed: each `append_history` is one `write` of one blank-line-terminated entry under `O_APPEND`, so entries do not tear; same-session `/new` is serialised by `get_lock` (C4) anyway; no A | none | low |
| F6 | task set | `_consolidation_tasks` is never awaited on shutdown (`main.py:650` is its only non-add/discard reference) | a task in flight at shutdown is cancelled; same as Step 4 today | not detected; no A | pre-existing; the cursor is patched only after a successful write, so a cancelled task loses the call, not the data | low |
| F7 | prompt line | the agent reads "read-only" as a hint and edits the file anyway | a hand-written line that may not parse | A13 is a render check only; behaviour is covered by the ask-mode gate on `edit_file` as in #440; no A | the `remember` change is the real fix | low |
| F8 | task body | `append_metadata_patch` or `maybe_refresh_hot_tags` raises | file may hold the lines with the cursor not advanced (same outcome as F4), or the profile refresh is skipped this round | `logger.exception`; A11 | next qualifying turn retries; nothing is re-raised into a turn | low |
| F9 | first sight | an upgraded install's long session, or a forked child carrying its parent's history | without a seed, one provider call would receive the whole history | A1, A16 | the seed (C10) | medium |
## Acceptance
Derived from Paths (P1-P15), Cursor states (4) and FMEA (F1, F3, F8, F9):
15 paths + 4 states + 4 failures = 23 rows; several collapse onto one item.
Test names marked "to be created" do not exist yet.
| # | Item | Source | Fails when | Test |
|---|---|---|---|---|
| A1 | On first sight of a session that already has messages, the cursor is set to `prev_len` and the annotator is not called for the history | P1, state "never seen", F9, C10 | the seed is missing and the whole history is annotated, or the seed lands at the current length and the first turn of every new session is skipped | `tests/test_agent_loop_episodic_annotate.py::test_first_sight_seeds_the_cursor_and_writes_nothing` (to be created) |
| A2 | After 5 user turns past the cursor, the annotator receives a tail whose first message is `user` and whose last message is the final message of the last turn; the file gains at least one line starting with `[YYYY-MM-DD HH:MM]`; the cursor equals `len(messages)` | P2, state "annotated through i", C2 | the slice starts at the wrong index, or the cursor is not patched | `::test_the_fifth_turn_hands_the_tail_to_the_annotator` (to be created), asserting on the fake consolidator's recorded argument; live: `tests/integration/test_episodic_writer_real_llm.py` (to be created) |
| A3 | With 3 user turns since the cursor, nothing is called | P3 | the count is of messages, not user turns | `::test_three_turns_since_the_cursor_call_nothing` (to be created) |
| A4 | With `annotate_every_turns = 0`, nothing is called after 20 user turns and the cursor is not even seeded | P4, C9 | the knob is not read, or the seed runs before the knob check | `::test_zero_turns_the_step_off` (to be created); reverse check: delete the `every <= 0` clause and this goes red |
| A5 | After undoing past the cursor, the next qualifying turns annotate from the cut; `last_consolidated` is unchanged throughout | P5, state "pulled back", F3, C1 | the cursor stays past the end and swallows the turns written after the undo until the count climbs back, or the wrong pointer is moved | `::test_undo_past_the_cursor_is_clamped` (to be created) |
| A6 | After a gateway restart the cursor is the value patched before | P6, C7 | the patch is not written, or `save` overwrote it | live only, part of the integration file above |
| A7 | The turn's reply is delivered before the annotator's provider call resolves | P7, C3 | the step is awaited inline | `::test_the_reply_does_not_wait_for_the_annotator` (to be created), consolidator stub with a held future |
| A8 | With a task holding the session lock, a second qualifying turn's task waits and then makes no provider call because the cursor moved | P8, state "locked", C4 | the tail is computed outside the lock, or no lock is taken | `::test_a_waiting_task_recomputes_and_does_nothing` (to be created) |
| A9 | When `consolidate_messages` returns False, the cursor does not move and a warning is logged, except for a turn larger than the whole budget, which the cursor moves past | P9, F1 | the cursor is advanced unconditionally, or the exemption covers an ordinary decline | `::test_a_declined_annotation_keeps_the_cursor`, `::test_a_refused_oversized_turn_moves_the_cursor_past_it`, `::test_an_ordinary_decline_still_keeps_the_cursor` |
| A10 | When `consolidate_messages` returns True having written zero lines, the cursor advances past the tail | P10 | the step inspects the file and refuses to move | `::test_zero_lines_still_advance_the_cursor` (to be created) |
| A11 | When `append_metadata_patch` raises inside the task, a traceback is logged and the turn that follows is unaffected | P11, F8 | the exception escapes the task or the next turn fails | `::test_a_failing_patch_is_logged_not_raised` (to be created) |
| A12 | The no-backend identity render still names `user.md` and the `Episodic log:` line exactly as on `main` | P12 | the no-backend branch was touched | `tests/test_segments.py::test_identity_without_a_backend_still_names_both_memory_files` (exists; it asserts both paths and the `Episodic log:` wording) |
| A13 | The backend identity render names `episodes.md` once, with "read-only", and still contains "never report it to the user as done or as failed" | P12 | the line is missing, or the #894 sentence was dropped | `tests/test_segments.py::test_identity_with_a_backend_names_the_log_read_only` (to be created); `test_identity_with_a_backend_names_no_memory_file` (exists) must change: it asserts `"user_memory" not in seg.text`, which this line breaks on purpose, so it becomes "names no profile file" |
| A14 | With a backend wired, `_dispatch_backend_store` receives the same slice it does on `main` after a turn | P13 | the new block disturbs the slice or ordering | `tests/test_agent_loop_backend_dispatch.py` existing dispatch tests stay green (exist) |
| A15 | A turn whose origin is `SENTINEL`, `CRON`, `HEARTBEAT` or `SUBAGENT` neither seeds nor counts nor annotates | P14 | the origin check admits more than `USER` | `::test_machine_turns_are_ignored` (to be created), parametrised over the four origins |
| A16 | A forked session whose parent had 12 messages is seeded at 12 on first sight and annotates only its own turns afterwards | P15, F9, C10 | the child inherits no cursor and no seed runs | `::test_a_forked_session_is_seeded_at_its_length` (to be created) |
Candidates for the hand-run guide: A2 and A6 on the live gateway. Everything
else is an agent-judged assertion. F2, F5, F6 and F7 carry no acceptance
item: F2, F6 and F7 are pre-existing properties this change does not alter,
and F5's safety follows from how `append_history` writes, not from new code.
## Cost
| Who pays | What |
|---|---|
| an install that sets the knob | one annotator LLM call per `annotate_every_turns` user turns, plus a profile refresh call whenever a tag crosses the hot threshold; an install with EverOS wired then runs two extractors over the same conversation |
| every other install | nothing: the default is `0`, which short-circuits before the seed |
| reversibility | back to `annotate_every_turns = 0` stops the step after a gateway reload; the file and cursor are left as they are |
| minimal set | the after-turn block, the helpers and the config field; the prompt line is a separate, smaller commit |
## Decisions
- **The knob ships at `0`, off.** The log has had no writer for the life of
the project, so no install is waiting on one; turning it on everywhere would
bill every user for a side provider call per cadence to fill a file they may
never read. The owner chose cost over reach. Rejected: shipping at 5.
- **The cursor is a new metadata key, not `last_consolidated`.** The gate on
`owns_compaction` exists to keep a second writer off the Curator's pointer;
reusing that pointer would reintroduce the conflict the gate prevents, and
`undo_last_turn` reads it as a floor. Rejected: reuse `last_consolidated`.
- **The cursor is patched, not saved.** A detached task that calls
`sessions.save` with its own copy of the metadata can drop keys the next
turn wrote; `append_metadata_patch` exists for exactly this writer.
Rejected: `sessions.save` from the task.
- **The cadence unit is user turns, not messages or tokens.** The original
design cut only at `role == "user"` boundaries (`pick_consolidation_boundary`,
`consolidator.py:1690`); counting turns keeps that unit, and the step's
placement after a turn makes the boundary free. Rejected: 20 messages (a
tool-heavy turn is 30 messages, a chat turn is 2); a token budget (a light
user never reaches it).
- **A session is seeded at the length before its first seen turn; history is
not back-filled.** The original loop fed the annotator chunks bounded by a
token budget; this step has no chunking, so an unseeded long session would go
to the provider in one call. Seeding at `prev_len` rather than the current
length lets a brand-new session count its first turn. `Session.fork`
seeds the child the same way, at its inherited length: the after-turn step
would have covered a fork on its own, but `/new` reads the cursor directly
and an unseeded fork hands its parent's annotated history over again.
Rejected: chunked back-fill (a second cut rule, for a one-time event);
seeding at the current length (the first turn of every session would never
be annotated).
- **Truncation moves the cursor where it happens, not lazily.** Clamping to
`len(messages)` at the next turn keeps the stale index on disk, and every
turn written after an undo or a clear is swallowed until the count climbs
past it; the first draft of this document said exactly that and the unit
twin of A5 refused it. `Session.undo_last_turn` and `Session.clear` already
own `last_consolidated` the same way. Rejected: the lazy clamp.
- **A crash between the file write and the metadata patch duplicates one tail
(F4) and is accepted.** Making it atomic means writing the cursor into the
same file under the same lock; duplicates cost nothing to grep and over-count
a tag by one batch at most. Rejected: a two-phase write.
- **A refused turn larger than the whole bound advances the cursor anyway.**
That turn is sent whole, because sending nothing would stall the cursor on
it forever, and nothing records that it was sent. Keeping the cursor on the
refusal therefore does not retry the call later; it rebuilds the same tail
and sends the same oversized prompt on every qualifying turn after it, which
is the self-reinforcing retry the bound was added to stop. An ordinary
decline still keeps the cursor: that one may have been the provider rather
than the size. Rejected: one rule for both, in either direction.
- **`True` with zero lines advances the cursor.** The annotator returning
True with nothing kept means it read the tail and found nothing worth an
episode (or dropped every candidate as process-only); that is a verdict, not
a failure, and retrying the same tail would ask the same question again.
Rejected: inspecting the file for growth before moving the cursor.
- **Only `Origin.USER` turns are annotated.** Sentinel, cron and heartbeat
turns are machine-initiated, and two of the file's readers are Sentinel
producers; writing those turns into the log would feed Sentinel its own
output. Rejected: excluding only `SUBAGENT`, as Step 4 does.
- **No gate other than the knob, the origin and the count.** Native and
plugin memory run side by side by the maintainer's decision; a `backend is
None or sentinel.enabled` gate was proposed to avoid double extraction and
withdrawn. Rejected: that gate.
- **The backend branch names the log, read-only.** Native memory was never
designed for the model to write: the only policy text about it is the #894
sentence, every writer is host-side, and `_PROTECTED_SUBTREES`
(`raven/agent/workdir.py:23`) treats agent writes there as damage. Naming
the log for reading restores the original intent; #440 came from "your own
memory" plus a profile path, which this line does not repeat. Rejected:
leaving the backend branch silent (the log would be written and invisible).
## Open
- Whether `maybe_refresh_hot_tags` should run on every successful annotation
or only every k-th. It is cheap when no tag is hot; left as every time until
cost shows.
- The read-only wording. Any phrasing that an agent reads as permission to
edit reopens #440; the one above is a draft for the G1 read.
- Whether the ACP entrance deserves an origin of its own. Today it reaches
`turn.send` as `Origin.USER`, so an ACP Raven sharing `~/.raven` mixes its
parent's prompts into the reader's log, where two Sentinel producers read
them as the reader's own activity. Not new -- `_dispatch_backend_store` is
unconditional on origin the same way -- and the alternative, a deployment
rule giving each ACP instance its own `RAVEN_HOME`, is already the correct
setup for a separate agent.

View File

@ -1,368 +0,0 @@
# Turn Continuation: resuming a failed turn from its recorded model request
Date: 2026-10-15. Status: design approved; Delivery item 1 (the full failure text) implemented, item 2 (Turn Continuation) pending.
## Problem
A turn that fails on a model call leaves the reader with two dead ends.
1. **The error cannot be read in full.** The web client draws a failed turn as one row,
`label + firstErrLine(detail, 140)` (`NoteView`, `ui-web/src/features/transcript/TranscriptPage.tsx:1152`),
with the rest only in a hover title. That title is itself cut: the runtime bounds
every failure text at 200 characters before it leaves the process
(`TURN_FAILURE_TEXT_MAX`, `raven/spine/events.py:91`; `LLM_ERROR_DETAIL_MAX`,
`raven/providers/base.py:83`), and the session marker's `turn_ended.reason` is
bounded the same way. For an OpenRouter 429 this drops exactly the fields that say
what happened (`provider_name`, `limit_source`, `remedy_hint`). The trace keeps the
whole text (the failed `llm.call` span's `status.message`), but nothing in the web client
reads it.
2. **Retry restarts the turn.** The row's retry action is `send(rt.lastAsk)`
(`ui-web/src/state/session/stages.ts:260`): the question is sent again as a new
turn, so the transcript carries it twice, the context is assembled from scratch, and
the iteration count starts over. It exists only while the web client that saw the failure
stays open; a failed turn replayed from the session has no retry at all.
## Goals
- **G1** A failed-turn row expands to the full failure text, scrubbed and bounded,
both live and when the session is replayed.
- **G2** Retry resumes the failed turn at the model call that failed: the first
request of the resumed run carries that call's message list unchanged, no user
message is added, and the completed tool work is kept.
- **G3** A failure that was resumed stays visible where it happened, as a quiet note
with the original error, and never reaches the model again.
- **G4** When the recording cannot seed a resume, retry sends a plain go-on message in
the configured language ("Go on" / "继续", from `config.language`).
## Non-goals
- The terminal TUI (`ui-tui/`). It has no retry today and keeps none.
- Cancelled turns. A person stopped them; they are not resumable.
- The 200-character failure texts. Chat-channel replies, cron job records and logs keep
them as they are.
- Resuming anything but the session's last turn.
- ACP replay (`raven/acp/replay.py`). A resumed marker keeps replaying as the failure
text it is today.
## Terms
**Turn Continuation** (added to `CONTEXT.md` with this change). A turn with no inbound
message that resumes the session's last failed turn from that turn's last recorded
model request: the `llm.input` artifact of the turn's trace. It is a turn of its own
(its own `turn_id` and lifecycle events) that the transcript draws as the rest of the
failed one.
_Avoid_: "retry" unqualified (`CONTEXT.md` already reserves it for the Model-Error
Ladder and Empty-Response Recovery); "continuation" unqualified (the DAG runner's node
continuations, `max_continuations`).
**Continuation seed.** The message list read from that artifact, resolved to full
messages.
The web client's button keeps its existing label, `gui.retry`.
## Why the trace, not the session
The session file records the conversation; the trace records each request as the
provider received it. In an inspected failed turn,
the failed `llm.call` span's `llm.input` artifact (`audit.artifact.v2`) held the system
prompt as assembled for that call, all 24 messages exactly as sent (a pasted screenshot
inline as a data URI, reasoning content, a mid-turn user message, three tool results),
the 34 tool definitions and the generation parameters. Re-sending those messages is the
failed call, with no context assembly, memory recall or skill selection run again.
Tracing is on by default (`TracingConfig.enabled = True`; `raven/tracing/config.py`
reads a missing key as on) and off only through `RAVEN_TRACING` or
`tracing.enabled = false`. Its writes are best effort: a write error is swallowed
(`raven/tracing/store.py`), and the trace directory may be cleaned by hand. A
continuation therefore checks the recording before it uses it and falls back when the
check fails (G4).
## Design
### 1. `turn.continue` RPC
Params: `{session_key}`. Result: `{status, turn_id?, reason?}`.
| status | meaning | client action |
|---|---|---|
| `continued` | a continuation turn was submitted; `turn_id` names it | none; the stream arrives |
| `fallback` | the recording cannot seed one; `reason` is `no_trace_id`, `no_model_call`, `trace_unreadable` or `tail_mismatch` | send the go-on text as an ordinary message |
| `refused` | nothing may run; `reason` is `busy`, `not_failed` or `already_continued` | show a toast; send nothing |
`not_failed` covers every session whose last entry is not a failed-turn marker,
including one where a newer message followed the failure, so a retry clicked on an old
row can never send a go-on message into a later conversation.
Eligibility is decided twice. The handler decides it to answer the client. The lane
decides it again before the run, and that answer is the authoritative one: a lane runs
one turn of a session at a time, so a second click that passed the handler's check
finds the marker already resumed, and its turn ends without output and writes nothing.
The method sits beside `turn.send` and `turn.cancel` in `raven/rpc/methods/turn.py`,
refuses a busy session through the existing `is_session_busy`, and is declared in
`rpc-schema/openrpc.json` with its mirrors (see "Contract surface"). It opens the turn
on the wire the way `turn.send` does, since the spine leaves `message.start` to the
submitting handler: it binds the lane's turn slot, so `turn.cancel` stops a
continuation like any sent turn, and emits `message.start` with `continued: true`
(section 6).
### 2. Loading and checking the seed
A new module beside the turn path (working name `raven/agent/loop/continuation.py`)
turns a session into either a seed or a reason, in this order:
1. **The failure.** The session's last entry is an assistant marker with
`turn_ended.status == "failed"` and no `turn_ended.resumed`. Otherwise `refused`
(`not_failed` / `already_continued`).
2. **The trace.** Walk back to the failed turn's opening user entry (the nearest
`role == "user"` that is not a mid-turn message) and read its `trace_id` (the Turn
Trace Mark). None: `fallback` / `no_trace_id`.
3. **The last model request.** Read that trace's spans from the span logs, newest file
first (`raven/trajectory/store.py:span_log_paths` lists the active log and its
archives), and take the last `llm.call` span. None: `fallback` / `no_model_call`.
4. **The artifact.** Its `llm.input.artifact_path` must resolve inside
`<tracing state dir>/logs/audit-artifacts/` (a path that escapes is refused, as
`raven/trajectory/replay.py:_artifact_path` refuses one for bundles), parse as JSON,
and resolve through `raven/tracing/artifact_v2.py:resolve_payload` with no missing
message blob. Otherwise `fallback` / `trace_unreadable`.
5. **The tail.** The seed's messages after its opening user message are compared with
the session's entries of the failed turn between its opening user entry and the
marker, after dropping what `_save_broken_turn` synthesizes on the way out (the
`[interrupted]` tool results and the `partial` assistant text, section 4). The two
must have the same sequence of roles and tool-call ids. Contents are not compared:
the session may hold a capped copy of a long tool result. A difference means the
turn failed after its last model call (a tool died with it) and the recording is
stale: `fallback` / `tail_mismatch`.
### 3. Running a continuation
`TurnRequest` (`raven/spine/turn.py`) gains a continuation flag; such a request carries
no text, has origin `USER`, and is submitted only onto an idle lane. The turn path
handles it inside the existing turn machinery rather than in a parallel copy of it.
What runs, in order:
1. The in-lane eligibility check (section 1), then the seed load (section 2). A marker
already resumed means another click won: the turn ends without output and writes
nothing, and the winning turn's stream reaches every window. A seed that stopped
loading in between (the trace was removed) fails the turn before anything is
written, so the marker stays unresumed and the next retry falls back.
2. The marker gets `turn_ended.resumed = true` and the session is saved, before the
first model call.
3. Turn setup that does not depend on an inbound message: tool context, the message
tool's `start_turn`, the `ask_user` context, the turn tier and attachment scopes,
`TurnSpend`.
4. The model binding of an ordinary turn: the session's model, else the router over the
failed turn's question text, else the default. The provider, key and routing are
the current ones, so a key or model changed after the failure is in force; the
artifact's recorded `generation` block is not replayed.
5. The attempt machinery with the seed as its list: `persist_from` is the seed's
length, `turn_start_idx` is the seed's opening user message. Tools are offered per
iteration as for any turn, not taken from the artifact.
6. The counters continue from the failed turn. The iteration count and the episode
index start at the number of model calls the failed turn completed (its assistant
entries in the seed), so the budget is the turn's, not renewed by each retry, and
live step rows do not reuse the failed turn's indexes, which the client keys fold
state by. `_run_agent_loop` gains a starting offset for this.
7. Everything after the attempt is the ordinary path: the answerless-turn exits and
their rescue (`_save_broken_turn`, which writes a new marker that can be continued
in turn), the `after_send` chain, `_save_turn`, feedback dispatch.
What does not run: the `before_user_inbound` hooks, slash commands, token-triggered
consolidation (the next ordinary turn runs it), the personalization flow, the playbook
turn message, skill selection, context assembly, `planning.prepare`, and filing a
question.
### 4. Session records and the model's history
- `_save_broken_turn` (`raven/agent/loop/turn_path.py:2828`) tags the assistant text it
saves from the stream with `partial: true`.
- A resumed marker keeps its place; the continuation's messages are appended after it.
- One helper decides what the model may see, used by both `Session.get_history`
(`raven/session/manager.py:281`) and the Memory role's `candidate_messages`
(`raven/agent/harness/memory.py:89`): a marker with `turn_ended.resumed`, and the
`partial` entries directly before it, are left out. An unresumed marker is kept, as
today: the model reads that a turn failed.
- `session.history` (`raven/rpc/methods/session.py`) already forwards `turn_ended`
whole, so the new keys reach the web client with no change there.
### 5. The full failure text
- The 200-character texts stay. Alongside them, a failed turn carries `full_detail`:
the unbounded failure text, scrubbed twice -- with the scrubber
`raven/providers/call_record.py` already applies to response bodies (made public as
`scrub_credentials`), then with `raven.security.redact.redact`, which knows the
shapes a crash message carries (a key in a URL, userinfo, `password=`, vendor
tokens) -- and capped at `call_record.MAX_BODY_CHARS` (8,000) rather than a new number.
The scrubbers read a window of at most 32,000 characters for a crash. A private key
without closing armour is scrubbed through the end of that window, since a prior
replacement can move a cut fragment inside the output cap. Call records use both
scrubbers before their own body cap. Authorization whitespace is consumed without
backtracking, and JWT matching starts only at token boundaries -- matching `eyJ`
anywhere cost 21 seconds of CPU on a 256,000-character body of it, and a token
glued to a word (`/verify-eyJ...`) is what that trade gives up. Known truncation
is passed into the scrubber so incomplete JWTs, vendor tokens, URL passwords and
labelled credential tails are removed even without their normal minimum length
or closing delimiter. Each tail pattern's search starts behind the run of its
own value's characters that ends the text, the label's gap and scheme word, and
room for the label's name, rather than at the start: the value runs to the end
of the input, so retrying the pattern at every position makes label-shaped text
cost its length squared -- 64,000 characters of `pwd=` ending in a comma take
10.8 seconds, and a regex search for the run's start costs the same on a long
gap, 32 seconds for 31,000 spaces inside a failing turn. That start is found by
matching the reversed text step by step, which reads a gap of any width once,
so the search finds exactly what a whole-text search finds. Ordinary
unlabelled diagnostic text is preserved.
The long text is the scrubbed one; the 200-character texts keep the wording they had,
unscrubbed, so a credential inside a short crash message makes the opened text differ
from the row only by its redaction.
- **The runner builds it, the lane carries it.** `raven/spine` is the frozen kernel:
it imports no other raven package and holds a line budget
(`tests/test_kernel_budget.py`), so it can neither scrub nor reach `call_record`.
A new agent-layer module, `raven/agent/loop/failure_text.py`, builds the text, and
the runner sets it as a `full_detail` attribute on the exception it lets out:
`AgentLoop.run_turn`'s failure arm, which every agent turn passes, and before that
`_process_message`'s arms, which also write the marker. The lane copies a string
`full_detail` from the exception onto `TurnFailed.full_detail`. An exception that
arrives without one (a runner other than the agent loop) carries none, and its row
shows the bounded text, as today.
- **A model call the loop gave up on.** `AnswerlessTurnError` (kernel) gains an
optional `full_detail` keyword. When the Model-Error Ladder gives up
(`turn_path.py`, the branch that sets `error_detail`), the loop fills
`LoopOutcome.error_full` from the failed response: its content unbounded, then the
body its call record kept (`call_record.from_exception` already holds the provider's
response body, scrubbed and capped). `_process_message` raises
`AnswerlessTurnError(outcome.error, full_detail=outcome.error_full)`. A provider
exception that escapes the loop (the stream ladder re-raises it) is covered by the
generic rule above: its message, then the body its client library kept
(`call_record.exception_body` -- the response text, else an HTTP error's parsed
`exc.body`; litellm reduces an OpenAI-style error body to one line in `str(exc)` and
keeps the rest there). `call_record.from_exception` reads the same body, so a
non-streamed error response's call record keeps it too.
The turn path and outer runner share the computed account, including an absent
one, so a failure is not scanned twice. Attachment and lane reads use the base
exception's instance storage; a foreign read-only property or throwing getter
is never consulted.
- It travels three ways: `TurnFailed.full_detail` (`raven/spine/events.py`), the
`error` event (`raven/rpc/spine.py` passes it to `emit_error`, a new optional
`ErrorEventPayload.full_detail`), and the marker (`turn_ended.full_detail`, written
by `_save_broken_turn`). All three carry it only when it says more than the bounded
text: a failure the 200 characters already hold whole gets no second copy and no
toggle.
- Who sees it: the RPC clients of this runtime (the web client, the TUI). A chat channel's
reply keeps quoting the bounded text, as `TurnFailed.reported` already decides.
### 6. The web client (`ui-web`)
- **Expand.** `NoteView` gains an expand toggle when the full text is longer than what
the row shows or spans several lines: a focusable button with `aria-expanded`,
revealing the full text in a wrapped, selectable monospace block. The state is local
to the row and never persisted. `note()` / `noteRow()` take the full text as an
option; the live `error` handler passes `p.full_detail`, the replay passes
`m.turn_ended.full_detail`. A marker written before this change has none; its row
opens to the bounded `reason` it kept, when that is longer than the row's line.
Quiet runtime notices use the neutral "Show details" label for the same expansion.
- **Retry.** A failed-turn row is no longer removed when its action is clicked; the
handler calls `turn.continue`. `continued`: nothing more here (the next point turns
the row). `fallback`, or an error from the call (an older Raven gateway without
the method): the row loses its action and the web client `send()`s the go-on text,
`t('gui.turn.go_on')`, which follows `config.language` because the web client's
language is the Raven gateway's. `refused`: the row loses its action and a toast says
`t('gui.turn.continue_refused')`. The row stays in both cases because the replay
will show it there: an unresumed marker followed by whatever came next.
- **Replay.** An unresumed failed marker that is the session's last entry gets the same
retry action. A resumed marker draws as a quiet note, `gui.transcript.resumed`, with
its `full_detail` expandable and no retry.
- **The continuation's start.** `message.start` gains `continued: true` for a
continuation turn. Every window that receives it turns the trailing failed-turn row
into the resumed note (so the window that clicked, any other window on the session
and a later reload all show the same row), then enters the streaming state without
drawing a question and without `advanceTurn()`: like a delegated result re-entering
the conversation, this turn has no user entry, and counting it would put the live
`wsCurrentTurn()` ahead of the one a reload computes.
- **Strings** (`i18n/messages.json`, read by the web client directly and regenerated into
the TUI's copy). The web client's key gate (`ui-web/scripts/gates/i18n-keys.test.mjs`) wants a
key drawn under `features/transcript/` in the `transcript` namespace; the two
`gui.turn.*` keys are said only by `state/session/`, a domain of its own to that
gate. The unused `gui.err.detail` pair cannot be reused for the same
reason.
| key | en | zh |
|---|---|---|
| `gui.transcript.error_expand` | Show full error | 展开完整错误 |
| `gui.transcript.notice_expand` | Show details | 展开详情 |
| `gui.transcript.error_collapse` | Hide | 收起 |
| `gui.transcript.resumed` | Interrupted here, then continued | 此处曾中断,已重试 |
| `gui.turn.go_on` | Go on | 继续 |
| `gui.turn.continue_refused` | This turn can no longer be continued | 这一轮已无法续跑 |
### Contract surface
`rpc-schema/openrpc.json` is the source; each addition below is mirrored in
`raven/rpc/models.py` and both generated clients (`ui-web/src/rpc/generated.ts` via
`scripts/gen-rpc-client.mjs`, `ui-tui/src/rpc/generated.ts` via
`scripts/gen-rpc-types.mjs`). The hand-written `ui-tui/src/gatewayTypes.ts` needs no
entry: it declares only `message` for the error event, and its drift test
(`gatewayTypesDrift.test.ts`) covers the model-picker payloads alone.
- method `turn.continue` with its params and result;
- `ErrorEventPayload.full_detail` (optional);
- `MessageStartPayload.continued` (optional, default false);
- `TranscriptTurnEnded.full_detail` and `TranscriptTurnEnded.resumed` (optional).
Every addition is optional, so a client that does not know a field behaves as today.
## Testing
Backend, `uv run --all-extras pytest`:
- **Seed.** A recorded v2 `llm.input` with `$msg` references as a fixture: the first
request of the continuation carries the recorded messages unchanged. Each fallback
reason from its own fixture: no `trace_id`, no `llm.call` span, a missing blob, an
artifact path outside the artifacts directory, and a session tail one tool call
longer than the seed.
- **Eligibility.** Each refusal reason; two concurrent submissions of which exactly one
runs.
- **Records.** The marker is marked resumed before the first model call; new messages
follow it; the iteration and episode counters continue from the failed turn; a
continuation that fails writes a new marker that is itself continuable.
- **History.** A resumed marker and the `partial` text before it are absent from both
history views; an unresumed marker is present.
- **Full text.** The bounded `error` is unchanged; `full_detail` is scrubbed, capped,
and present for a raised model error, a crash and an answerless turn.
Web client, `ui-web` vitest: the expand toggle appears only when there is more to show and
keeps `aria-expanded` right; each `turn.continue` outcome; the two replay renderings;
`message.start` with `continued` draws no question and does not advance the turn.
End to end: a real `raven web` under an isolated `RAVEN_HOME`, against a local
OpenAI-compatible stub that fails the Nth call with a 429, answers afterwards and
records every request body. Retry in the browser, then check that the continuation's
first request body equals the failed one, that no user message was added, and that
after a reload the note is the resumed one and the marker is absent from the next
request. One ordinary conversation on the live default model confirms the unchanged
paths.
Gates: `make lint check-source-language`, the RPC contract checks (`ui rpc contract`,
the TUI checks for `gatewayTypes.ts`), the `ui-web` build and type check.
## Delivery
Two pull requests, in this order, because the repository lands one feature per squash
commit:
1. **The full failure text (G1).** Section 5, the expand half of section 6, the
`full_detail` fields of the contract surface, and their tests. Useful on its own:
every failure row becomes readable.
2. **Turn Continuation (G2 to G4).** Sections 1 to 4, the rest of section 6, the
remaining contract fields, the `CONTEXT.md` term, and the end-to-end check. It
builds on the first: a resumed note expands to the `full_detail` its marker keeps.
## Compatibility and risks
- Sessions written before this change: markers without `full_detail` or `resumed`
render as today. Such a failure can still be continued when its trace exists.
- A failure that is deterministic (a request the provider will always refuse) fails
again on continue and leaves a new row; nothing retries on its own.
- The seed is read from local files Raven wrote, through the same confinement replay
uses for bundles; it is as large as the failed request, inline images included.

View File

@ -122,14 +122,11 @@ A playbook with no variable inputs (e.g. "pull an issue triage once a week") omi
| `mcps` | list[string] | Optional | The mcps this step wants to attach. **Playbook-only, and not in effect today**: subagent has no mcp channel; dispatch explicitly reports them ignored and does not write them into the prompt (writing them in would be a fake instruction the agent has no tools to execute) |
| `instance` | string | Optional | The session handle; nodes with the same handle share one agent session |
| `inputs` | map | Optional | Each key is a literal string, `{file: path}` or `{node: id}` -- **only these three, no run qualifier** (to pin a specific run, use the file form `{{ ref:@runs/<run_id>/... }}`, see section 6). The value is **structure**, not a unique capability: a key referenced by `{{ inputs.k }}` must be declared first (default-deny; inline `{{ ref: }}` cannot be validated at this level), and reading the node definition tells you what it reads without going through the prompt |
| `routes` | map | Optional | Route name -> the condition under which this node's answer selects it. **Makes this node a decision**: after it finishes, the judge picks the route from its answer, and the conditions are shown to the judge, never to the step. Route names use the `id` charset, `done` is reserved in any letter case, and a `select: one` decision needs at least two of them |
| `select` | enum | Optional | `one` (default where `routes` are given): exactly one route. `many`: any number, none included. Only on a node with `routes` |
| `when` | string | Optional | Guard: run this step only if it holds once its dependencies settle. Atoms `<node>.<route>` and `<node>.done` -- a decision node of this graph that is in `dependsOn` -- joined by `not` / `and` / `or` and parentheses. Every decision node in `dependsOn` must appear in it. False, or unknown because a decision it names never ran, means the step does not run |
**This table is the dag tool's node schema, not a separate set defined by the playbook.** Per-node configuration is a dag capability itself;
once a playbook is loaded, its nodes are injected directly into the dag tool, so the model can write these fields when calling dag directly too.
"The same set" refers to the field set and the semantics; two shape differences do not count as a separate set: the model-facing JSON Schema uses snake_case (`prompt_template` / `depends_on`) while this table is the camelCase written in the file; and at dispatch the `id` gets a `<playbook name>-<random 6 chars>-` prefix, with `dependsOn`, `{{ id.output }}` and the node ids in `when` atoms rewritten in sync -- because ids on the dag side are **unique within a session**, and without the rewrite, running the same playbook a second time in one session would be rejected by the uniqueness rule. The prefix lives only at run time; it never enters the file.
"The same set" refers to the field set and the semantics; two shape differences do not count as a separate set: the model-facing JSON Schema uses snake_case (`prompt_template` / `depends_on`) while this table is the camelCase written in the file; and at dispatch the `id` gets a `<playbook name>-<random 6 chars>-` prefix, with `dependsOn` and `{{ id.output }}` rewritten in sync -- because ids on the dag side are **unique within a session**, and without the rewrite, running the same playbook a second time in one session would be rejected by the uniqueness rule. The prefix lives only at run time; it never enters the file.
`instance` manages exactly one thing: **whether to carry the context forward**. `promptTemplate` is that injected prompt;
no extra field exists, and a new prompt can still be injected when the context is carried forward.
@ -241,7 +238,6 @@ The `output` vs `output_path` choice: local agents receive the path (they read i
| `dependsOn: [a]` | Waits for a to finish |
| `dependsOn: [a, b]` | Waits for both a and b to finish, merging |
| Two nodes with the same upstream | No dependency between them; parallel, forking |
| `when: <guard>` | Runs only if the guard holds; a step left out is `not_executed`, and a dependent that still runs reads the fixed "not executed" sentence in its place |
```yaml
nodes:
@ -257,17 +253,13 @@ scan_market -+
scan_tech ---+
```
A graph can branch: a node with `routes` is a **decision**, its judge picks the route its answer
selects, and the steps behind each route carry a `when` guard over that choice (section 5). That is
the one run-time decision a playbook can express, and it is written into the file like any other field.
`dependsOn` is also reference authorization: the `x` in `{{ x.output }}` must be listed in this node's `dependsOn`, otherwise a compile-time error (default-deny).
Graphs assembled in `prompt` mode are bound by the same rules; it is not an escape hatch.
**Two things that cannot be expressed**: cycles (conditional fallback, e.g. "review fails, fall back to rewriting"), and per-playbook concurrency caps (governed by the runner's global config).
**Three things that cannot be expressed**: cycles (conditional fallback, e.g. "review fails, fall back to rewriting"), conditional skipping (no `when:`), per-playbook concurrency caps (governed by the runner's global config).
Note that `mode: prompt` **cannot** bypass these two. A branch is a value in the assembled graph, not a change to it; what no mode can do is change a running graph based on intermediate results -- the steps a branch left out are decided by the guard's own value, not by a new plan. So loops like "stop after two consecutive rounds without new findings" are beyond both modes; `prompts` can only spell "how to assemble this graph", not "how to judge once it runs".
Note that `mode: prompt` **cannot** bypass these three. It is a graph generator, not a run-time orchestrator -- a graph is fixed once assembled; mid-run it cannot be changed based on intermediate results. So loops like "stop after two consecutive rounds without new findings" are beyond both modes; `prompts` can only spell "how to assemble this graph", not "how to judge once it runs".
---
@ -416,7 +408,7 @@ prompts: |
```
````
`prompts` spells out **how to assemble this graph** -- how many layers, which agent pairs with which skills/mcps at each layer, who dependsOn whom, how data flows between nodes. A step that decides where the graph goes next is still something `prompts` writes: give it `routes`, and guard what follows with `when`. What `prompts` cannot do is change the graph once it runs -- a branch is decided by the values the guards read, not by a new plan assembled mid-run.
`prompts` spells out **how to assemble this graph** -- how many layers, which agent pairs with which skills/mcps at each layer, who dependsOn whom, how data flows between nodes. Do not write "how to judge once it runs": the graph is fixed once assembled; there are no decision points at run time.
---
@ -429,7 +421,7 @@ block top-level taskSummary | version | mode | confirm | triggers | params | nod
triggers keywords
params.<key> type | required | default | enum | description
nodes[] id | subagent | nodeSummary | promptTemplate | dependsOn |
skills | mcps | instance | inputs | routes | select | when
skills | mcps | instance | inputs
placeholders ${params.x}
{{ dep.output }} | {{ dep.output_path }}

View File

@ -79,7 +79,7 @@ def hire(
baseline,
root,
timeout=timeout,
children=lambda current: prepare_children(current, root, [GENERIC_AGENT, *housed]),
children=lambda current: prepare_children(current, root, ["Raven", *housed]),
withheld=withheld(scenario),
)
@ -107,7 +107,7 @@ def replicate(
shutil.copytree(employee.baseline.workdir, workdir, symlinks=True)
baseline = prepare(config, workdir=workdir, task=employee.baseline.task, home=workspace)
housed = house(baseline, model=subagent_model, deployment=root / "deployment")
children = prepare_children(baseline, root, [GENERIC_AGENT, *housed])
children = prepare_children(baseline, root, ["Raven", *housed])
if children.keys() != employee.children.keys():
raise ValueError(f"a replica has child harnesses {sorted(children)}, the employee {sorted(employee.children)}")
for name, child in children.items():

File diff suppressed because it is too large Load Diff

View File

@ -1,54 +0,0 @@
[project]
name = "everos-cloud-memory"
version = "0.1.0"
description = "EverOS Cloud memory backend for Raven: dual-track semantic recall over the hosted EverOS API"
requires-python = ">=3.12"
license = "Apache-2.0"
authors = [
{name = "EverMind"}
]
keywords = ["raven", "raven-plugin", "memory", "everos", "cloud"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Programming Language :: Python :: 3.12",
]
# raven and httpx, nothing else: this plugin talks to a hosted service and
# never imports the everos engine, so a cloud-only install does not carry it.
dependencies = [
"raven",
"httpx>=0.28.0,<1.0.0",
]
# The one line that makes this package findable: PluginDiscovery._scan_entry_points
# reads this group, takes the value as a bare package name, and loads
# raven-plugin.toml out of that package with importlib.resources.
[project.entry-points."raven.plugins"]
everos-cloud-memory = "raven_everos_cloud"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["raven_everos_cloud"]
# raven-plugin.toml is package data, not a stray file: discovery resolves it
# through importlib.resources inside the installed package, so a wheel that
# ships the modules without it installs a plugin nothing can find.
[tool.hatch.build]
include = [
"raven_everos_cloud/**/*.py",
"raven_everos_cloud/raven-plugin.toml",
]
[tool.hatch.build.targets.sdist]
include = [
"raven_everos_cloud/",
"pyproject.toml",
]
[tool.uv.sources]
raven = { workspace = true }

View File

@ -1,14 +0,0 @@
"""EverOS Cloud memory backend for Raven.
Implements the host's :class:`raven.memory_engine.MemoryBackend` Protocol over
HTTPS against EverOS Cloud (``https://api.evermind.ai``): the same
``/api/v2/memory/{search,add,flush,get}`` routes the local ``everos-memory``
plugin speaks, with a Bearer key instead of a local server to start and no
model roles to configure. ``backend.make_backend`` is the factory the registry
calls; ``onboard.make_onboard_step`` builds the one ``raven onboard`` screen.
Kept import-cheap on purpose: PluginDiscovery resolves ``raven-plugin.toml``
through this module, so it imports neither ``httpx`` nor ``backend``.
"""
__version__ = "0.1.0"

View File

@ -1,693 +0,0 @@
"""EverosCloudBackend -- the host's :class:`MemoryBackend` over EverOS Cloud.
The same four routes the local plugin speaks (``POST /api/v2/memory/{search,add,flush,get}``),
with three differences that are the whole of this module's reason to exist:
- **A Bearer key instead of a server.** The key comes from the plugin's own
slice first and ``EVEROS_CLOUD_API_KEY`` second; without one nothing is sent
(``recall`` is ``[]``, ``store`` is ``False``, ``health`` says what to set).
There is no process to probe, spawn or stop, so there is no service state
machine either: every call stands on its own.
- **Every add is ``mode: "agent"``.** The local server runs both extraction
pipelines on every add; the cloud makes that a per-request field that
defaults to ``chat``, and ``chat`` would silently stop agent-track memories.
- **Flush only when the caller says the conversation is over, and at stop.**
``metadata["flush"]`` (the sub-agent handoff) and ``metadata["is_final"]``
(the importer's last batch) flush right after their adds; ordinary turns
never do, because the cloud extracts on its own. ``stop()`` flushes whatever
this process added to and never flushed, within a small budget.
Identity is the host's: ``ctx.services.user_id`` / ``agent_id`` name the owner
on every request, and a per-call override arrives in ``store``'s metadata in
either spelling (``user_id`` or ``userId``). The translation layer --
message conversion, result flattening, the profile cap -- is copied from
``raven_everos.backend`` so the two plugins file and read memories the same
way.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import math
import os
import time
from collections.abc import Mapping
from datetime import datetime
from typing import Any, Literal
import httpx
from raven.contracts.memory import BackendHealth, HealthCheck, Memory
from raven.plugins import PluginContext
logger = logging.getLogger("raven_everos_cloud")
DEFAULT_BASE_URL = "https://api.evermind.ai"
ENV_KEY = "EVEROS_CLOUD_API_KEY"
KEYS_URL = "https://everos.evermind.ai"
PLUGIN_ID = "everos-cloud-memory"
BACKEND_NAME = "everos-cloud"
# The host abandons a per-turn recall at 5.0 s (raven/context_engine/segments/memory.py);
# the skill router has no budget of its own, so this bound is the only one it gets.
RECALL_TIMEOUT_S = 4.0
# The sub-agent read-back allows 30 s (raven/agent/subagent_memory.py); a
# read right after extraction is the slow case.
SESSION_TIMEOUT_S = 10.0
# The cloud queues an add and answers 202 at once.
ADD_TIMEOUT_S = 30.0
# Extraction runs inside a flush. The variable exists so an acceptance run can
# make a hung flush give up in seconds; it is a test hook, not a feature.
FLUSH_TIMEOUT_ENV = "RAVEN_EVEROS_CLOUD_FLUSH_TIMEOUT_S"
DEFAULT_FLUSH_TIMEOUT_S = 360.0
HEALTH_TIMEOUT_S = 5.0
# One budget for the whole sweep at stop, as the local plugin's.
SHUTDOWN_FLUSH_BUDGET_S = 5.0
# Documented cloud limits are 500 messages and 300 KB; the byte ceiling keeps
# headroom for the envelope.
ADD_MAX_MESSAGES = 500
ADD_MAX_BYTES = 250_000
_SESSION_PAGE_SIZE = 100
_OwnerType = Literal["user", "agent"]
_STALE_IDENTITY_KEYS = ("user_id", "agent_id", "userId", "agentId")
def flush_timeout_s() -> float:
"""Read at call time so the environment hook works in a running process.
A malformed value falls back to the default: ``store`` must never raise
(C8), and this is the one place a typo in the environment could make it.
"""
raw = os.environ.get(FLUSH_TIMEOUT_ENV, "")
try:
return float(raw) if raw else DEFAULT_FLUSH_TIMEOUT_S
except ValueError:
return DEFAULT_FLUSH_TIMEOUT_S
def resolve_api_key(config: Mapping[str, Any]) -> tuple[str, str | None]:
"""``(key, source)``: the slice first, then the environment; ``("", None)`` when neither.
File before environment is the order the web tool vendor keys use, and the
one the settings page edits; a key that came from the environment is never
written back, so the file records only what a person typed.
"""
for raw, source in ((config.get("api_key"), "file"), (os.environ.get(ENV_KEY), "env")):
key = str(raw or "").strip()
if key:
# A control character cannot travel in a header: the HTTP layer refuses
# it by quoting the whole Authorization value in its error, and every
# hint and log line that prints that error would show the key.
return (key, source) if key.isprintable() else ("", None)
return "", None
# ---------------------------------------------------------------------------
# Translation layer, copied from raven_everos.backend
# ---------------------------------------------------------------------------
def as_ms_epoch(value: Any) -> int | None:
"""A message's timestamp as the service wants it (unix ms), or ``None``.
Accepts a ms-epoch int, a seconds-epoch int and an ISO 8601 string. The
seconds/ms split is by magnitude: a seconds value stays below the threshold
until the year 5138.
"""
if isinstance(value, bool) or value is None:
return None
if isinstance(value, (int, float)):
number = float(value)
if not math.isfinite(number) or number <= 0:
return None
return int(number * 1000) if number < 100_000_000_000 else int(number)
if isinstance(value, str):
try:
ms = int(datetime.fromisoformat(value).timestamp() * 1000)
except ValueError:
return None
return ms if ms > 0 else None
return None
def convert_messages(
messages: list[dict[str, Any]],
*,
agent_id: str,
user_id: str = "default",
) -> list[dict[str, Any]]:
"""AgentLoop ``{"role", "content", ...}`` rows as the service's message items.
``assistant`` / ``tool`` messages get ``sender_id = agent_id`` so the agent
track accrues under the stable agent identity; ``user`` messages keep their
own ``sender_id`` or get ``user_id``. ``system`` is dropped; multimodal
parts collapse to their text; a missing timestamp becomes now.
"""
now_ms = int(time.time() * 1000)
out: list[dict[str, Any]] = []
for m in messages:
role = m.get("role")
if role not in ("user", "assistant", "tool"):
continue
content = m.get("content", "")
if isinstance(content, list):
content = " ".join(
str(part.get("text", "")).strip()
for part in content
if isinstance(part, dict) and part.get("type") == "text"
).strip()
if content is None:
content = "" # a tool-call-only turn; "None" would be read by the extraction model as a reply
elif not isinstance(content, str):
content = str(content)
# A lone surrogate (a Claude Code transcript can carry one) cannot be encoded;
# it becomes U+FFFD here so the slice is sendable and ``store`` never raises.
content = content.encode("utf-8", errors="replace").decode("utf-8")
tool_calls = m.get("tool_calls") if role == "assistant" else None
if not content and not tool_calls:
continue
entry: dict[str, Any] = {
"sender_id": agent_id if role in ("assistant", "tool") else (m.get("sender_id") or user_id),
"role": role,
"timestamp": as_ms_epoch(m.get("timestamp")) or now_ms,
"content": content,
}
if tool_calls:
entry["tool_calls"] = tool_calls
if role == "tool" and m.get("tool_call_id"):
entry["tool_call_id"] = m["tool_call_id"]
out.append(entry)
return out
def _owner_override(metadata: dict[str, Any] | None, key: str) -> str:
"""One per-call owner id from ``store``'s metadata, in either spelling.
The block reaches here as an agent wrote it in raven's config, which spells
its keys in camelCase; the contract documents them in snake_case. Reading
only one of the two made the override silently never fire for a real
config, filing a sub-agent's memories under the host's own identity.
"""
if not metadata:
return ""
return str(metadata.get(key) or metadata.get(key.replace("_id", "Id")) or "")
# The profile grows for the life of an install with no server-side cap; this
# keeps it from outweighing every episode in the recalled block.
_PROFILE_MAX_CHARS = 1200
def _cap_profile_text(text: str) -> str:
if len(text) <= _PROFILE_MAX_CHARS:
return text
head, _, _ = text[:_PROFILE_MAX_CHARS].rpartition("\n")
kept = head or text[:_PROFILE_MAX_CHARS]
omitted = len(text) - len(kept)
return f"{kept}\n[profile truncated, {omitted} chars omitted]"
def _flatten_profile_list(items: list[Any]) -> list[str]:
lines: list[str] = []
for item in items:
if not isinstance(item, dict):
lines.append(f"- {item}")
continue
label = item.get("category") or item.get("trait")
body = item.get("description")
if label and body:
lines.append(f"- {label}: {body}")
elif label or body:
lines.append(f"- {label or body}")
return lines
def _flatten_profile(profile_data: Any) -> str:
"""Profile dict as prompt lines; the ``*_ms`` bookkeeping keys are skipped."""
if not isinstance(profile_data, dict):
return _cap_profile_text(str(profile_data))
lines: list[str] = []
for key, value in profile_data.items():
if key.endswith("_ms"):
continue
if isinstance(value, list):
lines.extend(_flatten_profile_list(value))
else:
lines.append(f"{key}: {value}")
return _cap_profile_text("\n".join(lines))
def _score(row: dict[str, Any], default: float = 0.0) -> float:
try:
value = row.get("score")
return float(value) if value is not None else default
except (TypeError, ValueError):
return default
def _digest(body: dict[str, Any], index: int) -> str:
"""Identity of one add for the retry memo: the content and its place, not the clock.
A row without a timestamp is stamped with "now" on every conversion, so a
retry of the same slice would never match if the stamp took part; the batch
index keeps two identical batches in one slice apart (a retry re-splits the
slice the same way, so the index is stable too).
"""
stable = {
"session_id": body.get("session_id"),
"index": index,
"messages": [{k: v for k, v in m.items() if k != "timestamp"} for m in body.get("messages", [])],
}
return hashlib.sha256(
json.dumps(stable, ensure_ascii=False, sort_keys=True).encode("utf-8", errors="replace")
).hexdigest()
def _joined(*parts: Any) -> str:
return " - ".join(str(part).strip() for part in parts if part)
def session_data_to_memories(data: Any, owner_type: _OwnerType) -> list[Memory]:
"""One session's rows as the lines a reader gets back (``recall_session``).
Episodes are rendered as ``subject - episode``: ``summary`` is a hard
200-character prefix of ``episode`` (as the local plugin's ``_session_text``
records), so it is the fallback, never the choice -- taking it would hand
the sub-agent memory record a sentence cut mid-word. Search hits keep the
summary, as the local plugin's do.
"""
if owner_type != "user":
return search_data_to_memories(data, owner_type)
if not isinstance(data, dict):
return []
# Rendered row by row, in the service's order (a session's episodes come
# back chronologically), so each text stays with its own id: the search
# mapping sorts by score, and matching its output to the rows by position
# swapped texts as soon as two scores reordered them.
out: list[Memory] = []
for ep in data.get("episodes") or []:
if not isinstance(ep, dict):
continue
out.append(
Memory(
text=_joined(ep.get("subject"), ep.get("episode") or ep.get("summary")),
score=_score(ep),
metadata={
"id": ep.get("id"),
"session_id": ep.get("session_id"),
"type": "episode",
"owner_type": "user",
},
)
)
return out
def search_data_to_memories(data: Any, owner_type: _OwnerType) -> list[Memory]:
"""Flatten the service's ``data`` envelope into ``list[Memory]``, sorted by score."""
out: list[Memory] = []
if not isinstance(data, dict):
return out
if owner_type == "user":
for ep in data.get("episodes") or []:
if not isinstance(ep, dict):
continue
text = ep.get("summary") or ep.get("episode") or ""
out.append(
Memory(
text=str(text),
score=_score(ep),
metadata={
"id": ep.get("id"),
"session_id": ep.get("session_id"),
"type": "episode",
"owner_type": "user",
},
)
)
for prof in data.get("profiles") or []:
if not isinstance(prof, dict):
continue
out.append(
Memory(
text=_flatten_profile(prof.get("profile_data")),
score=_score(prof, 1.0) if prof.get("score") is not None else 1.0,
metadata={"id": prof.get("id"), "type": "profile", "owner_type": "user"},
)
)
else:
for skill in data.get("agent_skills") or []:
if not isinstance(skill, dict):
continue
out.append(
Memory(
text=str(skill.get("content") or ""),
score=_score(skill),
metadata={
"id": skill.get("id"),
"name": skill.get("name", ""),
"type": "skill",
"owner_type": "agent",
"confidence": skill.get("confidence"),
},
)
)
for case in data.get("agent_cases") or []:
if not isinstance(case, dict):
continue
text = "\n\n".join(
part
for field in ("task_intent", "approach", "key_insight")
if (part := str(case.get(field) or "").strip())
)
out.append(
Memory(
text=text,
score=_score(case),
metadata={"id": case.get("id"), "type": "case", "owner_type": "agent"},
)
)
out.sort(key=lambda m: m.score, reverse=True)
return out
# ---------------------------------------------------------------------------
# The backend
# ---------------------------------------------------------------------------
class EverosCloudBackend:
"""raven_everos_cloud's :class:`MemoryBackend` implementation."""
def __init__(self, ctx: PluginContext, *, client: httpx.AsyncClient | None = None) -> None:
self._config: dict[str, Any] = dict(ctx.config or {})
self._logger = ctx.logger
self._user_id: str = ctx.services.user_id
self._agent_id: str = ctx.services.agent_id
self._warn_stale_identity_keys()
self._api_key, self._key_source = resolve_api_key(self._config)
self._base_url: str = str(self._config.get("base_url") or DEFAULT_BASE_URL).rstrip("/")
self._client: httpx.AsyncClient | None = client
self._owns_client = client is None
self._unflushed: set[str] = set()
self._landed: dict[str, set[str]] = {}
self._stopping = False
self._no_key_logged = False
# ── identity ────────────────────────────────────────────────────
def _warn_stale_identity_keys(self) -> None:
for key in _STALE_IDENTITY_KEYS:
stale = self._config.get(key)
if stale is None:
continue
current = self._user_id if key in ("user_id", "userId") else self._agent_id
if stale != current:
self._logger.warning(
"plugins.config['%s'].%s=%r is ignored; identity comes from memory.%s=%r. Remove the key.",
PLUGIN_ID,
key,
stale,
"userId" if key in ("user_id", "userId") else "agentId",
current,
)
# ── transport ───────────────────────────────────────────────────
def _client_or_open(self) -> httpx.AsyncClient:
if self._client is None:
self._client = httpx.AsyncClient(timeout=httpx.Timeout(ADD_TIMEOUT_S))
return self._client
def _headers(self) -> dict[str, str]:
return {"Authorization": f"Bearer {self._api_key}"}
def _has_key(self, what: str) -> bool:
if self._api_key:
return True
if not self._no_key_logged:
self._no_key_logged = True
self._logger.warning("EverOS Cloud %s skipped: no API key; set %s or run raven onboard", what, ENV_KEY)
return False
async def _post(self, path: str, body: dict[str, Any], timeout: float) -> httpx.Response:
client = self._client_or_open()
return await asyncio.wait_for(
client.post(f"{self._base_url}{path}", json=body, headers=self._headers()),
timeout=timeout,
)
# ── lifecycle ───────────────────────────────────────────────────
async def start(self) -> None:
self._client_or_open()
async def stop(self) -> None:
self._stopping = True
try:
await self._sweep_unflushed()
finally:
if self._owns_client and self._client is not None:
await self._client.aclose()
self._client = None
async def _sweep_unflushed(self) -> None:
"""One flush per session this process added to and never flushed.
Only an explicit end flushes during a run, so the sweep is the only
flush most sessions ever get from Raven; the cloud's own extraction is
the fallback for whatever the budget leaves behind.
"""
pending = sorted(self._unflushed)
if not pending or not self._api_key:
return
deadline = time.monotonic() + SHUTDOWN_FLUSH_BUDGET_S
flushed = 0
for session_id in list(pending):
remaining = deadline - time.monotonic()
if remaining <= 0:
break
try:
r = await self._post("/api/v2/memory/flush", {"session_id": session_id}, timeout=remaining)
r.raise_for_status()
except (httpx.TimeoutException, asyncio.TimeoutError):
# The budget is spent waiting on this one; the rest get no turn.
self._logger.warning(
"EverOS Cloud stop: flush of session %s timed out; the budget is spent", session_id
)
break
except Exception as exc: # noqa: BLE001 - a sweep must not fail the shutdown
# A refusal costs no time: the next session still gets its flush,
# as the local plugin's sweep does.
self._logger.warning("EverOS Cloud stop: flush of session %s failed (%s)", session_id, exc)
continue
self._unflushed.discard(session_id)
flushed += 1
self._logger.info("flushed %d session(s) at stop", flushed)
if self._unflushed:
self._logger.warning(
"EverOS Cloud stop: %d session(s) left unflushed (budget %ss): %s",
len(self._unflushed),
SHUTDOWN_FLUSH_BUDGET_S,
sorted(self._unflushed),
)
# ── MemoryBackend ───────────────────────────────────────────────
async def recall(
self,
query: str,
*,
user_id: str | None = None,
agent_id: str | None = None,
top_k: int,
) -> list[Memory]:
if (user_id is None) == (agent_id is None):
self._logger.warning(
"EverosCloudBackend.recall: expected exactly one of user_id / agent_id (got user_id=%r, agent_id=%r); returning empty",
user_id,
agent_id,
)
return []
if not self._has_key("recall"):
return []
owner_type: _OwnerType = "user" if user_id is not None else "agent"
body: dict[str, Any] = {"query": query, "top_k": top_k}
if user_id is not None:
body["user_id"] = user_id
body["include_profile"] = True
else:
body["agent_id"] = agent_id
try:
r = await self._post("/api/v2/memory/search", body, timeout=RECALL_TIMEOUT_S)
r.raise_for_status()
payload = r.json() or {}
except asyncio.TimeoutError:
self._logger.warning("recall timed out after %.1f s; returning empty", RECALL_TIMEOUT_S)
return []
except Exception as exc: # noqa: BLE001 - a recall must never cost the turn
self._logger.warning("EverosCloudBackend.recall failed (%s); returning empty", exc)
return []
return search_data_to_memories(payload.get("data"), owner_type)[:top_k]
async def store(
self,
session_id: str,
messages: list[dict[str, Any]],
*,
metadata: dict[str, Any] | None = None,
) -> bool:
if not messages:
return True
payload = convert_messages(
messages,
agent_id=_owner_override(metadata, "agent_id") or self._agent_id,
user_id=_owner_override(metadata, "user_id") or self._user_id,
)
if not payload:
return True
if not self._has_key("store"):
return False
batches, _dropped = self._batches(session_id, payload)
explicit_end = bool(metadata and (metadata.get("flush") or metadata.get("is_final")))
self._unflushed.add(session_id)
for index, batch in enumerate(batches):
body = {"session_id": session_id, "mode": "agent", "messages": batch}
# Both callers re-send a slice that answered False (contracts/memory.py);
# a batch the service accepted on the failed attempt is not sent twice.
# The memo lives only until the slice lands, so a later store of the
# same content is a new write, not a retry.
digest = _digest(body, index)
if digest in self._landed.get(session_id, ()):
continue
if not await self._send("add", "/api/v2/memory/add", body, ADD_TIMEOUT_S):
return False
self._landed.setdefault(session_id, set()).add(digest)
if explicit_end:
if not await self._send("flush", "/api/v2/memory/flush", {"session_id": session_id}, flush_timeout_s()):
return False
self._unflushed.discard(session_id)
self._landed.pop(session_id, None)
# A dropped oversize message is logged by _batches and is not a reason to
# answer False: no retry can make it fit, and a False here would only make
# both callers store the rest of the slice again on every attempt.
return True
def _batches(self, session_id: str, payload: list[dict[str, Any]]) -> tuple[list[list[dict[str, Any]]], bool]:
"""Split a slice at the service's limits; a single oversize message is dropped and named.
A message over the byte ceiling cannot be made to fit without storing
words the user never said, so it is left out and the rest goes on; the
slice still reports landed (see ``store``).
"""
batches: list[list[dict[str, Any]]] = []
current: list[dict[str, Any]] = []
size = 0
dropped = False
for index, message in enumerate(payload):
item_size = len(json.dumps(message, ensure_ascii=False).encode("utf-8", errors="replace"))
if item_size > ADD_MAX_BYTES:
# ponytail: a single message over the ceiling is dropped whole; chunk one
# message across adds if real turns ever hit this.
dropped = True
self._logger.warning(
"EverosCloudBackend.store: message %d of session %s is %d bytes, over the %d-byte ceiling; not stored",
index,
session_id,
item_size,
ADD_MAX_BYTES,
)
continue
if current and (len(current) >= ADD_MAX_MESSAGES or size + item_size > ADD_MAX_BYTES):
batches.append(current)
current, size = [], 0
current.append(message)
size += item_size
if current:
batches.append(current)
return batches, dropped
async def _send(self, what: str, path: str, body: dict[str, Any], timeout: float) -> bool:
try:
r = await self._post(path, body, timeout=timeout)
r.raise_for_status()
except asyncio.TimeoutError:
self._logger.warning(
"EverosCloudBackend.store: %s timed out after %ss; this slice was not indexed", what, timeout
)
return False
except Exception as exc: # noqa: BLE001 - a write failure is reported, never raised
level = self._logger.info if self._stopping else self._logger.warning
level("EverosCloudBackend.store: %s failed (%s); this slice was not indexed", what, exc)
return False
return True
async def recall_session(
self,
session_id: str,
*,
user_id: str | None = None,
agent_id: str | None = None,
) -> list[Memory]:
if (user_id is None) == (agent_id is None) or not self._has_key("recall_session"):
return []
owner_type: _OwnerType = "user" if user_id is not None else "agent"
body: dict[str, Any] = {
"memory_type": "episode" if owner_type == "user" else "agent_case",
"filters": {"session_id": session_id},
"page_size": _SESSION_PAGE_SIZE,
}
body["user_id" if owner_type == "user" else "agent_id"] = user_id if owner_type == "user" else agent_id
try:
r = await self._post("/api/v2/memory/get", body, timeout=SESSION_TIMEOUT_S)
r.raise_for_status()
payload = r.json() or {}
except Exception as exc: # noqa: BLE001 - a read-back must not fail the caller
self._logger.warning("EverosCloudBackend.recall_session failed (%s); returning empty", exc)
return []
return session_data_to_memories(payload.get("data"), owner_type)
async def delete(self, memory_id: str, *, kind: str | None = None) -> bool:
# The cloud deletes by scope, not by memory id, and no caller remains.
return False
async def feedback(self, signals: dict[str, Any]) -> None:
return None
async def health(self) -> BackendHealth:
if not self._api_key:
return self._missing(f"no API key; set {ENV_KEY} or run raven onboard")
body = {"memory_type": "episode", "user_id": self._user_id, "page_size": 1}
try:
r = await self._post("/api/v2/memory/get", body, timeout=HEALTH_TIMEOUT_S)
except asyncio.TimeoutError:
return self._missing(f"cannot reach {self._base_url}: no answer within {HEALTH_TIMEOUT_S:g}s")
except Exception as exc: # noqa: BLE001 - a probe reads as "not reachable"
return self._missing(f"cannot reach {self._base_url}: {exc}")
status = r.status_code
if 200 <= status < 300:
return BackendHealth(ready=True, checks=[HealthCheck(BACKEND_NAME, "ok", self._base_url)])
if status == 401:
return self._missing(f"API key rejected (401); check the key in plugins.config.{PLUGIN_ID} or {ENV_KEY}")
if status == 403:
return self._missing(
"refused (403); this may mean the account is not authorized for the v2 memory API; see " + KEYS_URL
)
if status == 429:
return BackendHealth(
ready=True, checks=[HealthCheck(BACKEND_NAME, "degraded", f"rate limited by {self._base_url}")]
)
return self._missing(f"{self._base_url} answered {status}")
def _missing(self, hint: str) -> BackendHealth:
return BackendHealth(ready=False, checks=[HealthCheck(BACKEND_NAME, "missing", hint)])
def make_backend(ctx: PluginContext) -> EverosCloudBackend:
"""Sync and read-only: ``raven doctor`` constructs without starting."""
return EverosCloudBackend(ctx)

View File

@ -1,110 +0,0 @@
"""The ``raven onboard`` screen for EverOS Cloud: one key, one probe.
The screen asks for the key unless the file or the environment already holds
one, proves it with the backend's own ``health()``, and records a typed key
under this plugin's slice through ``set_plugin_config_fields`` -- a merge, so
it never touches another plugin's slice. A key that came from the environment
is not copied into the file: the file records only what a person typed here.
The one sentence beyond the key: memories are shared by every Raven that uses
this key under the same ``memory.userId``, which is the host's field, not this
plugin's -- so the hint names it and offers no control for it.
"""
from __future__ import annotations
import asyncio
from collections.abc import Callable
from typing import Any
import httpx
from raven.config import update as config_update
from raven.plugins import OnboardUI, PluginContext, StepOutcome
from raven_everos_cloud.backend import ENV_KEY, KEYS_URL, PLUGIN_ID, EverosCloudBackend, resolve_api_key
class CloudKeyScreen:
"""The ``onboard`` contribution: step 4 when `everos-cloud` is the chosen backend."""
def __init__(self, ctx: PluginContext, *, client_factory: Callable[[], httpx.AsyncClient] | None = None) -> None:
self._ctx = ctx
self._client_factory = client_factory
def run(
self,
ui: OnboardUI,
*,
step_no: int,
non_interactive: bool,
main_model: str | None,
warnings: list[str],
skip_test: bool,
) -> StepOutcome:
ui.step_header(step_no, ui.t("Long-term memory: EverOS Cloud"))
key, source = resolve_api_key(self._ctx.config)
while True:
if source == "env":
ui.console.print(ui.t(" [dim]Using the API key from {var}.[/dim]", var=ENV_KEY))
elif source == "file":
ui.console.print(ui.t(" [dim]Using the API key on file.[/dim]"))
else:
ui.console.print(ui.t(" [dim]Keys: {url}[/dim]", url=KEYS_URL))
typed = ui.prompt_api_key("EverOS Cloud", allow_back=True)
if typed is ui.back:
return StepOutcome.BACK
key, source = str(typed), "typed"
ui.console.print(
ui.t(
" [dim]Memories are shared by every Raven that uses this key under user id {uid}; "
"change memory.userId in config.json to keep devices apart.[/dim]",
uid=self._ctx.services.user_id,
)
)
if not skip_test:
health = self._probe(key)
if health is None or not health.ready:
hint = health.checks[0].hint if health and health.checks else ""
ui.console.print(
ui.t(" [yellow]✗ Couldn't verify EverOS Cloud: {detail}[/yellow]", detail=hint or "")
)
options = [(ui.t("Skip long-term memory"), "skip")]
if source != "env":
options.insert(0, (ui.t("Re-enter"), "rekey"))
if ui.failure_choice(options, non_interactive=non_interactive) == "rekey":
key, source = "", None
continue
return StepOutcome.DISABLED
ui.console.print(ui.t(" [green]✓ EverOS Cloud connected.[/green]"))
if source == "typed":
config_update.set_plugin_config_fields(PLUGIN_ID, {"api_key": key})
return StepOutcome.CONFIGURED
def configured(self) -> bool:
return bool(resolve_api_key(self._ctx.config)[0])
def _probe(self, api_key: str) -> Any:
# A backend built on this key alone, so the probe answers for what is
# about to be recorded rather than for whatever the slice held before.
ctx = PluginContext(
config={**self._ctx.config, "api_key": api_key},
services=self._ctx.services,
logger=self._ctx.logger,
)
client = self._client_factory() if self._client_factory else None
backend = EverosCloudBackend(ctx, client=client)
try:
return asyncio.run(self._health_then_stop(backend))
except Exception: # noqa: BLE001 - a probe that cannot run reads as "not verified"
return None
@staticmethod
async def _health_then_stop(backend: EverosCloudBackend) -> Any:
try:
return await backend.health()
finally:
await backend.stop()
def make_onboard_step(ctx: PluginContext) -> CloudKeyScreen:
return CloudKeyScreen(ctx)

View File

@ -1,28 +0,0 @@
[plugin]
id = "everos-cloud-memory"
version = "0.1.0"
display_name = "EverOS Cloud memory"
raven = ">=0.1"
bundled = false
[[plugin.contributes.memory_backends]]
name = "everos-cloud"
factory = "raven_everos_cloud.backend:make_backend"
# Step 4 of ``raven onboard``: one screen that asks for the key (unless the
# file or the environment already holds one), probes it, and records it under
# this plugin's slice. Named after the backend it configures, which is what
# lets the host resolve this plugin's config slice for it.
[[plugin.contributes.onboard]]
name = "everos-cloud"
factory = "raven_everos_cloud.onboard:make_onboard_step"
# The backend reads plugins.config["everos-cloud-memory"]. api_key is read
# first; EVEROS_CLOUD_API_KEY in the environment is the fallback. Identity is
# not declared here: user_id / agent_id come from the host through
# ServiceLocator, never from a plugin's own slice. Only api_key is settable
# from the settings page (settings.set): base_url decides where that key is
# sent, so it is changed in the config file, never over RPC.
[plugin.config_schema]
api_key = { type = "string", settable = true }
base_url = { type = "string" }

View File

@ -1,6 +1,6 @@
[project]
name = "everos-memory"
version = "1.4.2"
version = "1.4.0"
description = "EverOS memory backend for Raven: dual-track semantic recall and the understand_media tool"
requires-python = ">=3.12"
license = "Apache-2.0"
@ -20,7 +20,7 @@ dependencies = [
# The substrate this adapter binds. Exact pin, not a range: the adapter
# reaches internal (non-public) everos APIs, so an upgrade is a deliberate
# act. Same pin the host carried while the plugin lived inside it.
"everos[multimodal]==1.4.2",
"everos[multimodal]==1.4.1",
"httpx>=0.28.0,<1.0.0",
"loguru>=0.7.3,<1.0.0",
"tomli-w>=1.2.0",

View File

@ -32,4 +32,4 @@ What the host may reach, declared rather than assumed:
Anything else in the package is the plugin's own.
"""
__version__ = "1.4.2"
__version__ = "1.4.0"

View File

@ -1,6 +1,6 @@
[plugin]
id = "everos-memory"
version = "1.4.2"
version = "1.4.0"
display_name = "EverOS memory"
raven = ">=0.1"
bundled = false

View File

@ -34,10 +34,10 @@ one loop whose bootstrap seats live in the AGENT HOME workspace
these), so seeding ``workdir.current()`` would feed a directory nothing
reads. The first ``before_user_inbound`` therefore seeds the HOME the
locator granted this plugin (``ServiceLocator.workspace``): the three
carried prompts from this wheel's package data first, regenerated so an
engine upgrade reaches them, then the host's own ``sync_workspace_templates``
for the rest of the template set, write-if-missing -- exactly the fork's
per-session order collapsed to once per process.
carried prompts from this wheel's package data first, write-if-missing, then
the host's own ``sync_workspace_templates`` for the rest of the template
set, exactly the fork's per-session order collapsed to once per home -- a
later turn, or an operator's in-place edit, is never overwritten.
"""
from __future__ import annotations
@ -159,83 +159,29 @@ IDENTITY_SEATS = (
("TOOLS.md", Path("TOOLS.md")),
)
# Every text this wheel has shipped in prompts/, so a seat an older engine
# wrote before receipts existed is recognised as the engine's own.
_SHIPPED_PROMPT_DIGESTS = frozenset(
{
"8dcc0ed76a30fe3f6aab91d47c8bc8994b4152d5902a879d231f03a25c605e9a",
"57d56e5374f5c105abf270e5e9d4f15f314bd8cdcd15ca818f3b263501447eba",
"fe51bc017ecc69ac6109eb3601fba9fece80c6b7632868438958c23ce25689ce",
"57197a8de9ee4637508d8c7c7cb66d51262fda8c6e3284fc6d3672ae74a7d343",
}
)
def seed_identity(home: Path) -> list[str]:
"""Write the deck identity into ``home`` and report what changed.
"""Seed the deck identity into ``home``, write-if-missing, and report what landed.
The three drifted prompts first -- so the host's template sync below finds
them present and leaves them alone -- then the host's own sync for the
rest of the template set (USER/HEARTBEAT and the L4 stubs), which is the
fork's per-session ``sync_workspace_templates(session.root)`` collapsed to
once per home. The prompts are this wheel's and are regenerated
(``write_generated``), so an engine upgrade reaches the model; an
operator's own lines go in the seat's ``*.local.md``. The home is whatever
the locator granted, which need not be this product's -- a host that
enables the engine grants its own -- so a seat nothing shows this engine
wrote is left alone rather than replaced. The rest of the set is the
user's and stays write-if-missing.
A raven older than ``write_generated`` seeds the prompts write-if-missing
instead, and the log says they will not be refreshed. A seat that cannot
be written does not stop the other seats; ``OSError`` then names each one,
and the sync waits for the retry.
once per home. Write-if-missing on every file: an operator's in-place edit
outlives every later launch, the fork's own contract.
"""
from raven.config import product_render
seeded: list[str] = []
failed: list[str] = []
prompts = pkg_files("raven_ppt") / "prompts"
generate = getattr(product_render, "write_generated", None)
if generate is None:
logger.warning("ppt-engine: this raven predates regenerated prompts; the deck identity is never refreshed")
for name, seat in IDENTITY_SEATS:
target = home / seat
text = (prompts / name).read_text(encoding="utf-8")
if generate is not None:
said: list[str] = []
try:
action = generate(
target,
text,
owner="ppt-engine",
legacy_digests=_SHIPPED_PROMPT_DIGESTS,
adopt=False,
notify=said.append,
)
except (OSError, UnicodeDecodeError) as exc:
failed.append(f"{target}: {exc}")
continue
# A seat left alone is the host's own in a home the host granted,
# every process, with nothing for anyone to do.
level = logging.DEBUG if action == "kept" else logging.WARNING
for message in said:
logger.log(level, "ppt-engine: %s", message)
if action == "written":
seeded.append(str(seat))
continue
if target.exists():
continue
target.parent.mkdir(parents=True, exist_ok=True)
# newline="" for the reason raven-code seeds its guide that way: the
# default would write a CRLF copy of an LF prompt on Windows, and each
# seat is asserted equal to the packaged source byte for byte.
target.write_text(text, encoding="utf-8", newline="")
target.write_text((prompts / name).read_text(encoding="utf-8"), encoding="utf-8", newline="")
seeded.append(str(seat))
if failed:
# Not synced yet: the host's templates would fill a failed seat, and a
# seat this engine did not write is never replaced (adopt=False).
raise OSError("cannot regenerate " + "; ".join(failed))
seeded.extend(sync_workspace_templates(home, silent=True))
return seeded
@ -297,17 +243,16 @@ class _DeckEngine:
# First touch, not construction: the factory runs while the host is
# still assembling, and a seat this engine never serves a turn on is a
# home it has no business writing into.
self._seeded = True
if self.home is not None:
try:
if seeded := seed_identity(Path(self.home)):
logger.info("ppt-engine: wrote the deck identity into %s: %s", self.home, seeded)
except (OSError, UnicodeDecodeError) as exc:
# The turn must run either way, but on whatever identity the
# home still holds, which may be an older engine's: loud on
# every turn, and retried on every turn until it lands.
logger.warning("ppt-engine: writing the deck identity failed; retrying next turn: %s", exc)
return
self._seeded = True
logger.info("ppt-engine: seeded the deck identity into %s: %s", self.home, seeded)
except OSError as exc:
# The turn must run either way; a home that cannot be written
# is loud in the log, and the next process retries because
# nothing was marked done on disk.
logger.warning("ppt-engine: seeding the deck identity failed: %s", exc)
def bookkeeping(self, root: Path) -> tuple[list[tuple[str, Path]], set[str]]:
key = str(root)

View File

@ -17,13 +17,10 @@ import hashlib
import json
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING
from raven_ppt.contracts import DeckBrief, Project, brief_path, load_brief
from raven_ppt.services.ingest import CATALOGUE_FILE, MATERIALS_FILE, READ_FILE
if TYPE_CHECKING:
from raven_ppt.services.template import BoundTemplate
from raven_ppt.services.template import PREPARED_FILE, BoundTemplate, bound
# How much of the materials the intake pass is shown, and in how many pieces.
# Enough to tell what these documents are about; not so much that its question
@ -195,10 +192,6 @@ def read(project: Project) -> DeckState:
read_record = _json(project.ingest_dir / READ_FILE)
materials = _text(project.ingest_dir / MATERIALS_FILE)
script = project.build_dir / "build.py"
# Imported here: the template service loads python-pptx, which every gateway
# would otherwise hold from the moment the plugin loads, deck or no deck.
from raven_ppt.services.template import bound
deck = project.build_dir / "deck.pptx"
return DeckState(
project=project,
@ -254,8 +247,6 @@ def _loose_templates(project: Project) -> tuple[str, ...]:
workspace with a checkout in it would make `rglob` the expensive part of an
otherwise free call. Two levels is where a user drops a file.
"""
from raven_ppt.services.template import PREPARED_FILE
workspace = project.workspace
skip = {"deck", "out"}
found: list[str] = []

View File

@ -1,6 +1,6 @@
[project]
name = "raven"
version = "0.2.5"
version = "0.2.4"
description = "Raven — AI-native command line agent with memory, proactivity, context control, and skill evolution"
requires-python = ">=3.12"
license = "Apache-2.0"
@ -116,7 +116,6 @@ dependencies = [
# tells them apart -- and a reader can do something about a password and
# nothing about a corrupt file.
"pdfminer-six>=20250416",
"pyflakes>=3.2,<4",
]
[project.optional-dependencies]
@ -275,7 +274,6 @@ include = [
everos-memory = { workspace = true }
ppt-engine = { workspace = true }
design-engine = { workspace = true }
everos-cloud-memory = { workspace = true }
[tool.uv]
constraint-dependencies = [
@ -359,8 +357,8 @@ ignore = ["DEP002", "DEP004"]
# The list is per-module, not per-file, so a later unguarded import of any other
# package is still caught by both rules.
[tool.deptry.per_rule_ignores]
DEP001 = ["raven_everos", "raven_everos_cloud", "requests", "cryptography", "pymupdf", "fitz"]
DEP003 = ["raven_everos", "raven_everos_cloud", "requests", "cryptography", "pymupdf", "fitz"]
DEP001 = ["raven_everos", "requests", "cryptography", "pymupdf", "fitz"]
DEP003 = ["raven_everos", "requests", "cryptography", "pymupdf", "fitz"]
[tool.ty]
# A call-correctness gate, not a typing-strictness project. Of ty's 133 rules,
@ -439,7 +437,7 @@ target-version = "py312"
# The distributables beside the host wheel are first-party to this repo's
# lint: without their root here, ruff reads `raven_everos` as a third-party
# package and wants its imports in another block than `raven`'s.
src = [".", "plugins-dist/everos-memory", "plugins-dist/everos-cloud-memory", "plugins-dist/ppt-engine", "plugins-dist/design-engine"]
src = [".", "plugins-dist/everos-memory", "plugins-dist/ppt-engine", "plugins-dist/design-engine"]
extend-exclude = [
# Byte snapshots of the retired vendored fork: the records the parity
# guards compare against. Reformatting a record destroys its fidelity.
@ -593,7 +591,6 @@ addopts = [
]
asyncio_mode = "auto"
markers = [
"everos_cloud: the test wants the everos-cloud-memory plugin visible to plugin discovery (tests/conftest.py hides it by default)",
"integration: needs a real external resource (LLM / RPC subprocess / VM / network); deselected by default, run with '-m integration' or by pointing at tests/integration",
"e2e: spawns real subprocesses / drives the full stack (slow); deselected by default, run with '-m e2e' (e.g. tests/tui/autotest)",
"real_llm: hits a real everos runtime (LLM + embedding); skipped unless EVEROS_LLM__API_KEY / EVEROS_EMBEDDING__MODEL are configured",
@ -634,7 +631,6 @@ output = "coverage.json"
[dependency-groups]
dev = [
"deptry>=0.25.1",
"everos-cloud-memory",
"grimp>=3.16",
"hatchling>=1.32.0",
"import-linter>=2.14",
@ -702,9 +698,6 @@ source_modules = [
# `raven.playbook`, by the CLI and RPC surfaces that read a stint's record,
# and by the dispatch path that carries its ref; it imports no surface itself.
"raven.stint",
# The Raven node: this Raven's own file tools run on a registered machine;
# consumed by the CLI, it imports no surface itself.
"raven.node",
]
forbidden_modules = ["raven.cli", "raven.rpc", "raven.acp", "raven.a2a"]
# Debt allowlist: none. The last allowlisted edge (market reaching the skill

View File

@ -14,24 +14,11 @@ from loguru import logger
from raven.a2a_client.client import send_message
from raven.config.schema import A2aConfig
from raven.contracts.tool import Tool, ToolOutput
from raven.contracts.tool import Tool
class A2aTool(Tool):
"""Declared ``agent_output`` because the peer's reply is that peer's words.
The declaration is the permission; each return still says whether THIS one
carries them. The reply does, and is returned as a claiming result. Every
other line here is this process's own -- a missing argument, or the
transport's error interpolated into "the A2A call failed" -- and is returned
as a bare string, which claims nothing and is scrubbed like any local
result. Measured live: a peer credential with a trailing newline made httpx
report ``Illegal header value b'Bearer ...\\n'``, and the whole sentence
skipped the scrub while the tool's declaration stood for the result.
"""
timeout_seconds = 600.0
agent_output = True
def __init__(self, config: A2aConfig) -> None:
self._config = config
@ -71,8 +58,7 @@ class A2aTool(Tool):
if not card_url or not message:
return "Error: both card_url and message are required."
try:
reply = await send_message(self._config, card_url, message)
return await send_message(self._config, card_url, message)
except Exception as exc:
logger.opt(exception=True).warning("a2a_send failed for {}", card_url)
return f"Error: the A2A call failed: {exc}"
return ToolOutput(reply, agent_output=True)

View File

@ -34,24 +34,8 @@ The layers, outermost first:
The opposite direction -- raven spawning somebody else's ACP agent -- already
exists under :mod:`raven.acp_client` and is not this. The two share only the wire
layer in :mod:`raven.acp_client.protocol`, which is imported rather than copied.
:mod:`raven.acp.mirasim` is a second agent served over the same channel: not
raven, but an agent Mirasim runs, answered over the Mirasim host's own protocol.
It reuses :mod:`raven.acp.stdio` and :mod:`raven.acp.protocol` and none of the
layers above them.
"""
from typing import Any
from raven.acp.stdio import MAX_FRAME_BYTES, claim_stdout, read_frames, write_frame
__all__ = ["MAX_FRAME_BYTES", "claim_stdout", "read_frames", "write_frame"]
def __getattr__(name: str) -> Any:
# Resolved on first use rather than at import: :mod:`raven.acp.stdio` reaches
# the ACP client and Raven's config schema, which a module of this package
# that only needs the protocol constants should not pay for.
if name in __all__:
from raven.acp import stdio
return getattr(stdio, name)
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

View File

@ -334,14 +334,7 @@ class AcpMethods:
# Offered at creation so a client can put a model picker in the session
# menu without a second round trip. Absent rather than empty when there
# is nothing to offer -- an empty list is a menu that opens onto nothing.
try:
options = await self._config_options(session.session_key)
except asyncio.CancelledError:
if not self._translator.closing:
raise
# The session exists; optional metadata must not suppress its EOF reply.
logger.debug("acp: returning {} without model options during shutdown", session.session_id)
options = []
options = await self._config_options(session.session_key)
if options:
result["configOptions"] = options
return self._with_modes(result, session.session_id)

View File

@ -1,25 +0,0 @@
"""An ACP agent for each agent Mirasim runs, served by Raven over the Mirasim host's own protocol.
Mirasim (https://mirasim.ai) runs third-party coding agents -- Claude Code,
Codex, Kimi Code and others -- behind one workbench, with a model menu that adds
its own platform's models and the user's own keys to each agent's own. It has no
ACP surface, so Raven brings one: ``python -m raven.acp.mirasim --agent <id>``
serves one Mirasim agent on stdio, and the ``mirasim_*`` presets in
:mod:`raven.agent.subagent.mirasim_presets` launch it. It drives the Mirasim host
the user is already running, the way Mirasim's own apps do, so a turn streams
and shows in those apps as it runs.
The layers, outermost first:
* :mod:`raven.acp.mirasim.server` -- the frame loop and the ACP methods.
* :mod:`raven.acp.mirasim.stream` -- a session's snapshot, rebuilt from the
host's patches, and the ACP updates each change makes.
* :mod:`raven.acp.mirasim.interactions` -- what a running turn stops to ask, as
the request that puts it to the client, and the client's reply as an answer.
* :mod:`raven.acp.mirasim.store` -- which Mirasim conversation an ACP session
continues, kept across adapter processes.
* :mod:`raven.acp.mirasim.catalog` -- the agent's models and effort rungs, as
the menus Raven reads off any ACP agent.
* :mod:`raven.acp.mirasim.host` -- where the host listens, and the one
WebSocket to it.
"""

View File

@ -1,5 +0,0 @@
"""``python -m raven.acp.mirasim --agent <id>``: serve one Mirasim agent over ACP on stdio."""
from raven.acp.mirasim.server import main
raise SystemExit(main())

View File

@ -1,327 +0,0 @@
"""What one Mirasim agent offers, read from the host's ``listClis`` and ``getCatalog`` frames.
Read once when the adapter starts and again when the copy is old, never per
turn. ``listClis`` says whether the agent's CLI is installed and what Mirasim
calls it; ``getCatalog`` names its models and effort rungs. The menus are
advertised in the shapes Raven already reads off any ACP agent -- the model as
the ``session/new`` config option whose ``category`` is ``model``, and the effort
rungs as session modes -- so the model picker, a per-instance model and the
session tier reach a Mirasim agent unchanged.
Three kinds of model share one catalog, told apart by ``routeByModel``: a row
routed ``relay`` runs on the Mirasim platform's quota, one routed ``direct`` on
a key the user added to Mirasim (its id is ``profile:<uuid>``), and an unrouted
row is the agent's own, served by its own sign-in. The menu groups them under
those three headings, because the same model can sit in two of them -- a
platform ``deepseek-flash`` and an own-key profile that also reaches DeepSeek --
and the label alone cannot say which one bills where.
Which of the two a session bills, the platform's quota or the user's own
account, is the session's route, not a property of the model: a ``prompt``
frame's ``route`` puts the session on one (``cloud`` or ``local``, ``null`` for
Mirasim's default), on its first turn and on any later one, and the id it runs
stays the same. The platform runs the own models of the
agents in :data:`PLATFORM_ROUTE_AGENTS` too, so for those each own model is
offered once per route, the route prefixed to its id -- ``own:`` under the
agent's heading, ``platform:`` under the platform's. The bare id is still taken,
as the model on whichever route Mirasim picks: it is what a session reports with
nothing chosen, and so what Raven sends back to undo a choice.
"""
from __future__ import annotations
from dataclasses import dataclass, field, replace
from typing import Any
MODEL_OPTION = "model"
PLATFORM_GROUP = ("platform", "Mirasim")
OWN_KEY_GROUP = ("own-key", "Own key")
OWN_ROUTE = "own"
PLATFORM_ROUTE = "platform"
DEFAULT_ROUTE = "default"
"""A session's routes as this adapter names them; ``default`` leaves the session to Mirasim's own setting."""
WIRE_ROUTES: dict[str, str | None] = {OWN_ROUTE: "local", PLATFORM_ROUTE: "cloud", DEFAULT_ROUTE: None}
"""Each route as a ``prompt`` frame's ``route`` spells it; ``None`` goes out as ``null``, clearing a choice."""
STEER_AGENTS = frozenset({"claude", "codex", "dsh", "pi", "zcode"})
"""The agents whose running turn takes a ``steer``, as ``mirasim ui-cli agents`` reported each one's
``capabilities.steer`` (measured 2026-10-12 on 0.0.465). The host's ``listClis`` rows do not say."""
IMAGE_AGENTS = frozenset({"claude"})
"""The agents measured seeing an image sent as a ``prompt`` frame's ``attachments``.
Measured 2026-10-17: Claude Code on ``glm-5.3-flash`` named the colour of an
attached image. An agent outside this set declares no image support: an image
linked as a local file reaches it as that file's path, which its own tools can
open, and an image sent inline is refused."""
PLATFORM_ROUTE_AGENTS = frozenset({"claude", "codex", "kimi", "zcode"})
"""The agents whose own models the Mirasim platform runs as well.
Named rather than read off the catalog, which does not say: ``routeByModel``
marks only the rows that take one route -- the platform's own models and the
user's keys -- and leaves every model of the agent's own unmarked, whether the
platform runs it or not.
"""
@dataclass(frozen=True)
class ModelEntry:
id: str
"""The value the menu offers, and a client sends back."""
label: str
route: str = ""
"""``relay``, ``direct``, or empty for the agent's own model."""
rungs: tuple[str, ...] = ()
model: str = ""
"""The id Mirasim runs, where it is not ``id``: the model behind a route prefix."""
session_route: str = ""
"""The route a session is put on to run this value, ``own`` or ``platform``; empty leaves that to Mirasim."""
context_window: int | None = None
"""The model's context window in tokens, as the catalog says; the size a usage update reports against."""
@dataclass(frozen=True)
class AgentCatalog:
"""One agent's facts and menus, as Mirasim reported them."""
agent: str
label: str
installed: bool
default_model: str | None = None
default_effort: str | None = None
models: tuple[ModelEntry, ...] = ()
"""The menu, in the order it is offered."""
efforts: tuple[tuple[str, str], ...] = ()
"""The agent-level rungs as ``(id, label)``, which every model's list is drawn from."""
menus_unread: bool = False
"""This catalog is empty because the read failed, not because the agent offers nothing.
The two are one shape here -- ``models`` and ``efforts`` both empty -- and
only one of them is a fact about the agent. A reader that cannot tell them
apart records the failure as a measurement, and nothing invalidates a
measurement, so a menu that was never read outlives every restart. Set by
:func:`read_catalog` from the shape of its second document.
"""
_by_id: dict[str, ModelEntry] = field(default_factory=dict, compare=False, repr=False)
"""Every value taken: the menu, and the bare ids of models it offers only behind a route."""
def model(self, model_id: str | None) -> ModelEntry | None:
return self._by_id.get(model_id or "")
def mirasim_model(self, choice: str | None) -> str | None:
"""The id Mirasim runs for ``choice``: the model behind its route prefix, else ``choice`` itself."""
entry = self.model(choice)
return (entry.model or entry.id) if entry is not None else choice
def route_for(self, choice: str | None) -> str | None:
"""The route a turn on ``choice`` runs on -- ``own``, ``platform``, or ``default`` for Mirasim's.
``None`` for an agent outside :data:`PLATFORM_ROUTE_AGENTS`: with no
second route to choose, its sessions are never put on one, and stay on
whatever Mirasim routes each model to. No choice at all is Mirasim's
default, its route included.
"""
if self.agent not in PLATFORM_ROUTE_AGENTS:
return None
entry = self.model(choice)
return (entry.session_route if entry is not None else "") or DEFAULT_ROUTE
def offers_model(self, model_id: str) -> bool:
return model_id in self._by_id
def context_window(self, mirasim_model: str | None) -> int | None:
"""The context window of the model Mirasim names ``mirasim_model`` -- the id a snapshot reports."""
for entry in self._by_id.values():
if mirasim_model in (entry.id, entry.model) and entry.context_window:
return entry.context_window
return None
def offers_effort(self, effort: str) -> bool:
return any(rung == effort for rung, _ in self.efforts)
def rungs_for(self, model_id: str | None) -> tuple[str, ...]:
"""The effort rungs ``model_id`` takes -- the default model's when none is chosen.
A model the catalog lists without rungs takes none. One missing from the
catalog altogether gets the agent-level list: nothing narrower is known.
"""
entry = self.model(model_id or self.default_model)
if entry is not None:
return entry.rungs
return tuple(rung for rung, _ in self.efforts)
def model_option(self, current: str | None) -> dict[str, Any] | None:
"""The ``model`` config option with ``current`` selected, or ``None`` when there is no menu."""
if not self.models:
return None
groups: dict[tuple[str, str], list[dict[str, Any]]] = {}
for entry in self.models:
groups.setdefault(self._group_of(entry), []).append({"value": entry.id, "name": entry.label})
value = current or self.default_model or self.models[0].id
return {
"id": MODEL_OPTION,
"name": "Model",
"category": "model",
"type": "select",
"currentValue": value,
"options": [{"group": group, "name": name, "options": opts} for (group, name), opts in groups.items()],
}
def config_options(self, current: str | None) -> list[dict[str, Any]]:
option = self.model_option(current)
return [option] if option is not None else []
def modes(self, current: str | None) -> dict[str, Any] | None:
"""The session's mode state, or ``None`` where no effort can be said to be current.
That is an agent with no rungs, and one whose catalog names no default
(ZCode CLI): a turn there runs on an effort Mirasim does not report, so
any rung offered as current would be a guess -- and the menu itself is
what Raven fits its session tier onto.
"""
ids = [rung for rung, _ in self.efforts]
if not ids or self.default_effort not in ids:
return None
return {
"currentModeId": current if current in ids else self.default_effort,
"availableModes": [
{"id": rung, "name": name, "description": f"Reasoning effort: {name}"} for rung, name in self.efforts
],
}
def _group_of(self, entry: ModelEntry) -> tuple[str, str]:
if entry.route == "relay" or entry.session_route == PLATFORM_ROUTE:
return PLATFORM_GROUP
if entry.route == "direct":
return OWN_KEY_GROUP
return ("agent", self.label)
def _text(value: Any) -> str:
return value.strip() if isinstance(value, str) else ""
def _rungs(items: Any) -> tuple[tuple[str, str], ...]:
if not isinstance(items, list):
return ()
out: list[tuple[str, str]] = []
for item in items:
rung = _text(item.get("id")) if isinstance(item, dict) else ""
if rung:
out.append((rung, _text(item.get("label")) or rung))
return tuple(out)
def agent_entry(rows: Any, agent: str) -> dict[str, Any] | None:
"""The ``listClis`` row naming ``agent``, or ``None``."""
for row in rows if isinstance(rows, list) else ():
if isinstance(row, dict) and row.get("id") == agent:
return row
return None
def installed_ids(rows: Any) -> list[str]:
"""The ids of the ``listClis`` rows Mirasim reports installed, in its order."""
return [
row["id"]
for row in (rows if isinstance(rows, list) else ())
if isinstance(row, dict) and isinstance(row.get("id"), str) and row.get("installed") is True
]
def read_catalog(agent: str, row: Any, catalog_doc: Any) -> AgentCatalog:
"""Build an :class:`AgentCatalog` from the agent's ``listClis`` row and its catalog, tolerating a missing catalog.
Anything not in the expected shape is dropped rather than guessed at: a
guessed model would be offered to a reader and then refused by Mirasim.
"""
row = row if isinstance(row, dict) else {}
label = _text(row.get("label")) or agent
installed = bool(row.get("installed"))
doc = catalog_doc if isinstance(catalog_doc, dict) else {}
routes = doc.get("routeByModel") if isinstance(doc.get("routeByModel"), dict) else {}
efforts_by_model = doc.get("effortByModel") if isinstance(doc.get("effortByModel"), dict) else {}
listed: list[ModelEntry] = []
seen: set[str] = set()
for item in doc.get("models") if isinstance(doc.get("models"), list) else ():
model_id = _text(item.get("id")) if isinstance(item, dict) else ""
if not model_id or model_id in seen:
continue
seen.add(model_id)
route = routes.get(model_id)
window = item.get("contextWindow")
listed.append(
ModelEntry(
id=model_id,
label=_text(item.get("label")) or model_id,
route=route if route in ("relay", "direct") else "",
rungs=tuple(rung for rung, _ in _rungs(efforts_by_model.get(model_id))),
context_window=window
if isinstance(window, int) and not isinstance(window, bool) and window > 0
else None,
)
)
models, unlisted = _menu(agent, listed)
return AgentCatalog(
agent=agent,
label=label,
installed=installed,
# Mirasim's own word even when its menu does not list it: this is what
# a turn with no --model runs on, and a session restored to it has to
# land there rather than on whatever the menu happens to list first.
default_model=_text(doc.get("defaultModel")) or (listed[0].id if listed else None),
default_effort=_text(doc.get("defaultEffort")) or None,
models=tuple(models),
efforts=_rungs(doc.get("effort")),
# Not ``not models``: an agent that answered with a well-formed catalog
# naming no model has offered nothing, and that IS a fact about it. Only
# a document that never arrived is a read to take again.
menus_unread=not isinstance(catalog_doc, dict),
_by_id={entry.id: entry for entry in (*unlisted, *models)},
)
def _menu(agent: str, listed: list[ModelEntry]) -> tuple[list[ModelEntry], list[ModelEntry]]:
"""``agent``'s menu, and the entries it takes without offering them.
For an agent the platform also runs, each own model is offered once per
route, under the agent's heading and then ahead of the platform's own
models, the order Mirasim lists the two kinds in; its bare id is taken
unlisted. Any other agent's menu is the catalog as it stands.
"""
if agent not in PLATFORM_ROUTE_AGENTS:
return listed, []
own = [entry for entry in listed if not entry.route]
taken = {entry.id for entry in listed}
def on(route: str) -> list[ModelEntry]:
return [
replace(entry, id=f"{route}:{entry.id}", model=entry.id, session_route=route)
for entry in own
if f"{route}:{entry.id}" not in taken
]
return [*on(OWN_ROUTE), *on(PLATFORM_ROUTE), *(entry for entry in listed if entry.route)], own
__all__ = [
"DEFAULT_ROUTE",
"IMAGE_AGENTS",
"MODEL_OPTION",
"OWN_KEY_GROUP",
"OWN_ROUTE",
"PLATFORM_GROUP",
"PLATFORM_ROUTE",
"PLATFORM_ROUTE_AGENTS",
"STEER_AGENTS",
"WIRE_ROUTES",
"AgentCatalog",
"ModelEntry",
"agent_entry",
"installed_ids",
"read_catalog",
]

View File

@ -1,377 +0,0 @@
"""The adapter's one connection to the Mirasim host already running on this machine.
Mirasim's desktop and phone apps are clients of a *host*: one long-running
server that runs the agents, keeps the sessions and speaks JSON frames over a
WebSocket at ``/ws``. This adapter is one more client of it -- it never starts a
host of its own, because two hosts over one ``~/.mirasim`` contend for the same
sessions and the same machine identity. Where the host listens, in the order
:func:`locate_host` looks:
- ``RAVEN_MIRASIM_HOST``: ``unix:<path>`` for a socket, ``<port>`` or
``127.0.0.1:<port>`` for a loopback port, when the host is somewhere else;
- ``~/.mirasim-remote/run/server.sock``: the host Mirasim runs on a machine it
reaches over SSH (POSIX only). The same user is trusted there, no token;
- ``127.0.0.1:4970``: the installed desktop app's server, whose access token is
``local-4970.token`` under Mirasim's state directory (``MIRASIM_HOME``,
else ``~/.mirasim``) -- the file ``mirasim ui-cli --port`` reads.
Two frames are never sent, because the answers carry secrets: ``ready`` makes
the host push its whole settings tree, IM bot tokens included, and
``getConfig`` answers with the configuration. No frame is logged whole --
only the reason a refusal gives, which names what failed -- and the token
travels in a header, never in a URL.
One connection serves every session of the adapter. A frame comes back to its
request by what the host echoes, which differs per frame: ``clientRef`` on
``accepted`` / ``error`` / ``sessionDeleteResult``, ``reqId`` on ``sessions`` and
``history``, only ``agent`` on ``catalog`` and ``commands``, nothing on
``clis`` -- so :meth:`HostConnection.request` takes a predicate rather than a
key. Every frame, answered or not, also goes to ``on_frame``. A connection that
drops is made again in the background while ``wanted`` says something depends
on it; a turn the host is running goes on regardless, and the sessions are
subscribed to again once it is back (``on_connect``).
"""
from __future__ import annotations
import asyncio
import contextlib
import json
import os
import time
from collections.abc import Awaitable, Callable, Iterator, Mapping
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
import aiohttp
from loguru import logger
HOST_ENV = "RAVEN_MIRASIM_HOST"
DESKTOP_PORT = 4970
UNIX_SOCKETS = os.name != "nt"
"""Whether asyncio can open a unix socket here: on Windows neither of its event loops can."""
CONNECT_TIMEOUT_S = 10.0
HEALTH_TIMEOUT_S = 5.0
STREAM_CADENCE_MS = 150
"""How long the host may merge a session's patches before sending them.
Measured on 0.0.465: a 98-second Claude Code turn sent 4,015 frames uncoalesced,
text two to four characters at a time; at 150 ms text arrives six to twenty-four
characters at a time and a short turn takes a dozen frames."""
MAX_FRAME_BYTES = 64 * 1024 * 1024
RECONNECT_PAUSES_S = (0.2, 0.5, 1.0, 2.0, 5.0)
NO_HOST = (
"No Mirasim host is running on this machine: start the Mirasim app (or let it reach this machine), "
f"or name where the host listens in {HOST_ENV}."
)
class HostUnavailableError(Exception):
"""The host could not be reached, or the connection to it dropped."""
@dataclass(frozen=True)
class HostAddress:
"""Where a host listens: a unix socket, or a port on the loopback with the token it asks for."""
socket: str | None = None
port: int | None = None
token: str | None = field(default=None, repr=False)
host: str = "127.0.0.1"
"""The loopback name the port is reached on, as the address named it: ``localhost`` and ``[::1]`` stay so."""
@property
def base_url(self) -> str:
# Over a unix socket the host part is never resolved; it names the request.
return "http://localhost" if self.socket else f"http://{self.host}:{self.port}"
def describe(self) -> str:
return f"unix socket {self.socket}" if self.socket else f"{self.host}:{self.port}"
def mirasim_home(env: Mapping[str, str] | None = None) -> Path:
"""Mirasim's state directory: ``MIRASIM_HOME``, else ``~/.mirasim``."""
named = (env if env is not None else os.environ).get("MIRASIM_HOME", "").strip()
return Path(named).expanduser() if named else Path.home() / ".mirasim"
def remote_socket() -> Path:
"""Where the host Mirasim runs on a machine it reaches over SSH listens; fixed under the home."""
return Path.home() / ".mirasim-remote" / "run" / "server.sock"
def port_token(port: int, env: Mapping[str, str] | None = None) -> str | None:
"""The access token the host on ``port`` wrote for its local clients, or ``None``."""
try:
token = (mirasim_home(env) / "run" / f"local-{port}.token").read_text(encoding="utf-8").strip()
except OSError:
return None
return token or None
def parse_address(value: str, env: Mapping[str, str] | None = None) -> HostAddress:
"""``unix:<path>``, ``<port>`` or ``<loopback host>:<port>``; a :exc:`ValueError` for anything else."""
value = value.strip()
if value.startswith("unix:"):
path = value.removeprefix("unix:")
if not path:
raise ValueError(f"{HOST_ENV}={value!r} names no socket")
return HostAddress(socket=path)
host, _, port_text = value.rpartition(":")
if host not in ("", "127.0.0.1", "localhost", "[::1]"):
raise ValueError(f"{HOST_ENV}={value!r}: the host must listen on this machine's loopback")
if not port_text.isdigit() or not 0 < int(port_text) < 65536:
raise ValueError(f"{HOST_ENV}={value!r} names no port")
port = int(port_text)
return HostAddress(port=port, token=port_token(port, env), host=host or "127.0.0.1")
def locate_host(env: Mapping[str, str] | None = None) -> HostAddress | None:
"""Where the running host listens, or ``None`` when there is none to find (see the module docstring)."""
env = env if env is not None else os.environ
if named := env.get(HOST_ENV, "").strip():
return parse_address(named, env)
socket = remote_socket()
if UNIX_SOCKETS:
with contextlib.suppress(OSError):
if socket.is_socket():
return HostAddress(socket=str(socket))
token = port_token(DESKTOP_PORT, env)
return HostAddress(port=DESKTOP_PORT, token=token) if token is not None else None
Predicate = Callable[[dict[str, Any]], bool]
class HostConnection:
"""One WebSocket to the host, shared by every session of the adapter."""
def __init__(
self,
*,
on_frame: Callable[[dict[str, Any]], None],
locate: Callable[[], HostAddress | None] = locate_host,
on_connect: Callable[[], Awaitable[None]] | None = None,
on_lost: Callable[[], None] | None = None,
wanted: Callable[[], bool] = lambda: False,
) -> None:
self._locate = locate
self._on_frame = on_frame
self._on_connect = on_connect
self._on_lost = on_lost
self._wanted = wanted
self._session: aiohttp.ClientSession | None = None
self._ws: aiohttp.ClientWebSocketResponse | None = None
self._reader: asyncio.Task[None] | None = None
self._reconnect: asyncio.Task[None] | None = None
self._closing: set[asyncio.Future[None]] = set()
self._connect_lock = asyncio.Lock()
self._send_lock = asyncio.Lock()
self._listeners: list[tuple[Predicate, asyncio.Queue[dict[str, Any] | BaseException]]] = []
self._closed = False
self.address: HostAddress | None = None
self.version: str | None = None
"""The host's version, as its ``/api/health`` said on the last connect."""
self.lost_at: float | None = None
"""``time.monotonic()`` when the connection last dropped; ``None`` while it is up or was never made."""
self.epoch = 0
"""How many connections have been made: a frame sent under an older one may have been lost with it."""
@property
def connected(self) -> bool:
return self._ws is not None and not self._ws.closed
async def connect(self) -> None:
"""Connect unless connected; :exc:`HostUnavailableError` when there is no host to reach."""
if self.connected:
return
async with self._connect_lock:
if self.connected:
return
if self._closed:
raise HostUnavailableError("the connection to the Mirasim host was closed")
try:
address = self._locate()
except ValueError as exc:
raise HostUnavailableError(str(exc)) from exc
if address is None:
raise HostUnavailableError(NO_HOST)
if address.socket and not UNIX_SOCKETS:
raise HostUnavailableError(
f"cannot reach the Mirasim host at {address.describe()}: asyncio opens no unix socket on this "
f"platform, so name the Mirasim app's port in {HOST_ENV} instead"
)
connector: aiohttp.BaseConnector = (
aiohttp.UnixConnector(path=address.socket) if address.socket else aiohttp.TCPConnector()
)
session = aiohttp.ClientSession(
connector=connector, timeout=aiohttp.ClientTimeout(total=None, connect=CONNECT_TIMEOUT_S)
)
headers = {"x-mirasim-token": address.token} if address.token else {}
try:
version = await _health(session, address, headers)
# The session's timeout bounds the connection, not the upgrade's answer: a host that
# takes the request and never upgrades would hold this lock, and every send, forever.
async with asyncio.timeout(CONNECT_TIMEOUT_S):
ws = await session.ws_connect(
f"{address.base_url}/ws",
headers=headers,
max_msg_size=MAX_FRAME_BYTES,
)
except BaseException as exc:
await session.close()
if not isinstance(exc, (aiohttp.ClientError, OSError, TimeoutError)):
raise
said = str(exc) or (
"it did not answer in time" if isinstance(exc, TimeoutError) else type(exc).__name__
)
raise HostUnavailableError(f"cannot reach the Mirasim host at {address.describe()}: {said}") from exc
self._session, self._ws, self.address, self.version = session, ws, address, version
self.lost_at = None
self.epoch += 1
self._reader = asyncio.create_task(self._read(ws, session))
await self._send(
{"type": "setStreamCadence", "coalesceMs": STREAM_CADENCE_MS, "statusMs": STREAM_CADENCE_MS}
)
logger.info("Mirasim adapter: connected to the Mirasim host {} at {}", version or "?", address.describe())
if self._on_connect is not None:
await self._on_connect()
async def send(self, frame: dict[str, Any]) -> None:
"""Send one frame, connecting first if need be."""
await self.connect()
await self._send(frame)
async def request(self, frame: dict[str, Any], reply: Predicate, *, timeout: float) -> dict[str, Any]:
"""Send ``frame`` and answer the first frame ``reply`` accepts; :exc:`TimeoutError` past ``timeout``."""
with self.listen(reply) as queue:
await self.send(frame)
got = await asyncio.wait_for(queue.get(), timeout)
if isinstance(got, BaseException):
raise got
return got
@contextlib.contextmanager
def listen(self, accept: Predicate) -> Iterator[asyncio.Queue[dict[str, Any] | BaseException]]:
"""The frames ``accept`` takes, queued while the block runs; a dropped connection queues the error."""
queue: asyncio.Queue[dict[str, Any] | BaseException] = asyncio.Queue()
entry = (accept, queue)
self._listeners.append(entry)
try:
yield queue
finally:
self._listeners.remove(entry)
async def close(self) -> None:
self._closed = True
if self._reconnect is not None:
self._reconnect.cancel()
ws, session, reader = self._ws, self._session, self._reader
self._ws = None
if ws is not None:
with contextlib.suppress(Exception):
await ws.close()
if reader is not None:
reader.cancel()
await asyncio.gather(reader, return_exceptions=True)
if session is not None:
await session.close()
await asyncio.gather(*self._closing, return_exceptions=True)
async def _send(self, frame: dict[str, Any]) -> None:
ws = self._ws
if ws is None or ws.closed:
raise HostUnavailableError("the connection to the Mirasim host is closed")
try:
async with self._send_lock:
await ws.send_str(json.dumps(frame, ensure_ascii=False))
except (aiohttp.ClientError, ConnectionError, RuntimeError) as exc:
raise HostUnavailableError(f"the Mirasim host could not be sent a frame: {exc}") from exc
async def _read(self, ws: aiohttp.ClientWebSocketResponse, session: aiohttp.ClientSession) -> None:
try:
async for message in ws:
if message.type != aiohttp.WSMsgType.TEXT:
continue
try:
frame = json.loads(message.data)
except ValueError:
continue
if isinstance(frame, dict):
self._deliver(frame)
finally:
if self._ws is ws:
self._lost(session)
def _deliver(self, frame: dict[str, Any]) -> None:
for accept, queue in list(self._listeners):
try:
taken = accept(frame)
except Exception: # noqa: BLE001 - one bad predicate must not stop the others
taken = False
if taken:
queue.put_nowait(frame)
try:
self._on_frame(frame)
except Exception: # noqa: BLE001 - a frame that breaks its handler must not end the connection
logger.opt(exception=True).warning("Mirasim adapter: handling a {!r} frame failed", frame.get("type"))
def _lost(self, session: aiohttp.ClientSession) -> None:
self._ws = None
self.lost_at = time.monotonic()
lost = HostUnavailableError("the connection to the Mirasim host dropped")
for _, queue in list(self._listeners):
queue.put_nowait(lost)
closing = asyncio.ensure_future(session.close())
self._closing.add(closing)
closing.add_done_callback(self._closing.discard)
if self._closed:
return
logger.warning("Mirasim adapter: the connection to the Mirasim host dropped")
if self._on_lost is not None:
self._on_lost()
if self._reconnect is None or self._reconnect.done():
self._reconnect = asyncio.create_task(self._come_back())
async def _come_back(self) -> None:
"""Connect again, pausing longer each time, while anything still depends on the connection."""
pauses = iter(RECONNECT_PAUSES_S)
while not self._closed and not self.connected and self._wanted():
await asyncio.sleep(next(pauses, RECONNECT_PAUSES_S[-1]))
try:
await self.connect()
except HostUnavailableError as exc:
logger.debug("Mirasim adapter: the Mirasim host is still unreachable: {}", exc)
async def _health(session: aiohttp.ClientSession, address: HostAddress, headers: dict[str, str]) -> str | None:
"""The host's version from ``/api/health``, or ``None``: a host that cannot say is still one to talk to."""
try:
async with session.get(
f"{address.base_url}/api/health", headers=headers, timeout=aiohttp.ClientTimeout(total=HEALTH_TIMEOUT_S)
) as response:
body = await response.json(content_type=None) if response.status == 200 else None
except (aiohttp.ClientConnectionError, OSError, TimeoutError):
raise
except (aiohttp.ClientError, ValueError):
return None
version = body.get("version") if isinstance(body, dict) else None
return version.strip() if isinstance(version, str) and version.strip() else None
__all__ = [
"DESKTOP_PORT",
"HOST_ENV",
"NO_HOST",
"HostAddress",
"HostConnection",
"HostUnavailableError",
"locate_host",
"mirasim_home",
"parse_address",
"port_token",
"remote_socket",
]

View File

@ -1,250 +0,0 @@
"""What a Mirasim turn stops to ask, put to an ACP client, and the reply read back as an answer.
A turn that needs a person -- a question the agent asks, or a tool it wants
approved -- shows up in the turn's snapshot as an *interaction* and waits there
until an ``interact`` frame resolves it. This module is the pure half of relaying
one: reading the interaction, building the request that puts it in front of
the client, and reading the client's reply back into an answer. The shapes
were read from Mirasim 0.0.465's and 0.0.537's host code and seen live:
- an interaction is ``{promptId, kind, title, hint, questions, currentIndex,
step}``; ``kind`` is ``"permission"`` for a tool approval and
``"user-input"`` for everything else, an MCP server's approval included;
- a question is ``{id, header, text, type, choices, multiSelect,
allowFreeform, allowEmpty}``, ``type`` being ``"select"`` or ``"text"`` and
each choice ``{label, description}`` -- plus, for an approval an ACP agent
asked, ``value`` (the agent's option id) and ``intent`` (``allow_once``,
``allow_always``, ``reject_once`` or ``reject_always``);
- an ask of several questions is put one question at a time, each under a
prompt id of its own, and ``currentIndex`` names the question an answer goes
to;
- the answer is ``interact {promptId, action, value}``, its value one string
whatever the action, so several choices travel joined -- the way Claude
Code's ``AskUserQuestion`` joins them itself. The host answers the question
``currentIndex`` names with ``[value]``, ``skip`` with nothing chosen, and
``cancel`` by dismissing it.
A tool approval goes out as ``session/request_permission``, the request every
ACP client answers; anything else goes out as ``elicitation/create``, which a
client answers only if it declared form support.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from uuid import uuid4
PERMISSION = "permission"
ANSWER_FIELD = "answer"
CUSTOM_FIELD = f"{ANSWER_FIELD}_custom"
CUSTOM_FOR_META = "customAnswerFor"
"""The key under a property's ``_meta.raven`` naming the question it is the free-text box for.
The marker raven's own ACP server writes beside an ``ask_user`` with choices,
and the one raven's client folds into the question, so a person who types an
answer of their own is asked once rather than twice."""
_REFUSING = {"deny", "decline", "reject", "no", "cancel"}
_INTENTS = frozenset({"allow_once", "allow_always", "reject_once", "reject_always"})
@dataclass(frozen=True)
class Reply:
"""One ``interact`` frame: its ``action`` and, for an answer, its ``value``."""
action: str
value: str | None = None
def pending(snapshot: dict[str, Any]) -> list[dict[str, Any]]:
"""The interactions a turn's snapshot holds that can be answered, in order."""
items = snapshot.get("interactions")
if not isinstance(items, list):
return []
return [item for item in items if isinstance(item, dict) and _text(item.get("promptId"))]
def question(interaction: dict[str, Any]) -> dict[str, Any]:
"""The question an answer goes to: the current one, else the first; empty when there is none."""
questions = interaction.get("questions")
if not isinstance(questions, list) or not questions:
return {}
index = interaction.get("currentIndex")
if isinstance(index, int) and not isinstance(index, bool) and 0 <= index < len(questions):
picked = questions[index]
else:
picked = questions[0]
return picked if isinstance(picked, dict) else {}
def elicitation_request(session_id: str, interaction: dict[str, Any]) -> dict[str, Any]:
"""The ``elicitation/create`` params that put ``interaction`` to the client as a one-question form."""
asked = question(interaction)
labels = _labels(asked)
selects = asked.get("type") == "select" and bool(labels)
title = _text(asked.get("text")) or _text(asked.get("header")) or _text(interaction.get("title")) or "Your answer"
field: dict[str, Any] = {"type": "string", "title": title}
if selects and asked.get("multiSelect"):
field = {"type": "array", "title": title, "items": {"type": "string", "enum": labels}}
elif selects:
field["enum"] = labels
properties: dict[str, Any] = {ANSWER_FIELD: field}
required: list[str] = [] if asked.get("allowEmpty") else [ANSWER_FIELD]
if selects and asked.get("allowFreeform"):
properties[CUSTOM_FIELD] = {
"type": "string",
"title": "Your own answer, when none of the options fits",
"_meta": {"raven": {CUSTOM_FOR_META: ANSWER_FIELD}},
}
# A required enum could never be satisfied by an answer off the list,
# and the person fills one property or the other.
required = []
return {
"sessionId": session_id,
"mode": "form",
"message": _message(interaction, asked),
"requestedSchema": {"type": "object", "properties": properties, "required": required},
}
def read_elicitation(interaction: dict[str, Any], result: Any) -> Reply:
"""The answer a client's ``elicitation/create`` reply stands for.
``decline`` is a person choosing not to answer, which Mirasim calls a skip,
and so is a form accepted with nothing in it. ``cancel`` -- and a reply in
no shape at all -- dismisses the question.
"""
if not isinstance(result, dict):
return Reply("cancel")
action = result.get("action")
if action == "decline":
return Reply("skip")
if action != "accept":
return Reply("cancel")
content = result.get("content")
if not isinstance(content, dict):
return Reply("skip")
asked = question(interaction)
chosen = _said(content.get(ANSWER_FIELD))
typed = _said(content.get(CUSTOM_FIELD))
if typed and not (chosen in _labels(asked) and not asked.get("multiSelect")):
chosen = typed
if not chosen:
return Reply("skip")
return Reply("select" if asked.get("type") == "select" else "text", chosen)
def permission_request(session_id: str, interaction: dict[str, Any]) -> tuple[dict[str, Any], dict[str, str]]:
"""The ``session/request_permission`` params for a tool approval, and the answer each option id stands for.
Option ids are minted per request, so an id from an earlier request, or one
a client made up, selects nothing. A choice that carries its ``intent`` is
offered as exactly that kind; one without -- Claude Code's ``Allow`` and
``Deny`` -- is read off its label. The answer is the choice's own ``value``
where it has one, the option id of the ACP agent behind it, else its label.
"""
asked = question(interaction)
offered: dict[str, str] = {}
options: list[dict[str, Any]] = []
choices = (
[choice for choice in asked.get("choices") or () if isinstance(choice, dict) and _text(choice.get("label"))]
if isinstance(asked.get("choices"), list)
else []
)
for index, choice in enumerate(choices or [{"label": "Allow"}, {"label": "Deny"}]):
label = _text(choice.get("label"))
option_id = f"choice-{index}-{uuid4().hex}"
offered[option_id] = _text(choice.get("value")) or label
intent = choice.get("intent")
kind = intent if intent in _INTENTS else "reject_once" if label.lower() in _REFUSING else "allow_once"
options.append({"optionId": option_id, "name": label, "kind": kind})
title = _text(asked.get("text")) or _text(interaction.get("title")) or "Approve tool use?"
params = {
"sessionId": session_id,
"toolCall": {
"toolCallId": f"mirasim-{_text(interaction.get('promptId'))}",
"title": title,
"kind": "other",
"status": "pending",
},
"options": options,
}
return params, offered
def read_permission(result: Any, offered: dict[str, str]) -> Reply:
"""The answer a client's ``session/request_permission`` reply stands for: the choice it selected, or a dismissal."""
outcome = result.get("outcome") if isinstance(result, dict) else None
if isinstance(outcome, dict) and outcome.get("outcome") == "selected":
label = offered.get(outcome.get("optionId"))
if label:
return Reply("select", label)
return Reply("cancel")
def describe(interaction: dict[str, Any]) -> str:
"""One interaction in words, for a reply that has to carry it instead of the client."""
asked = question(interaction)
said = _text(asked.get("text")) or _text(asked.get("header"))
title = _text(interaction.get("title"))
line = f"{title}: {said}" if title and said else title or said or "a question"
if labels := _labels(asked):
line += f" ({' / '.join(labels)})"
if hint := _text(interaction.get("hint")):
line += f"\n {hint}"
return line
def _message(interaction: dict[str, Any], asked: dict[str, Any]) -> str:
lines = [_text(interaction.get("title")) or "The agent asks"]
if hint := _text(interaction.get("hint")):
lines.append(hint)
step = interaction.get("step")
total = step.get("total") if isinstance(step, dict) else None
index = step.get("index") if isinstance(step, dict) else None
if isinstance(total, int) and isinstance(index, int) and total > 1:
lines.append(f"Question {index + 1} of {total}")
for choice in asked.get("choices") if isinstance(asked.get("choices"), list) else ():
if isinstance(choice, dict) and _text(choice.get("label")) and _text(choice.get("description")):
lines.append(f"- {_text(choice.get('label'))}: {_text(choice.get('description'))}")
return "\n".join(lines)
def _labels(asked: dict[str, Any]) -> list[str]:
choices = asked.get("choices")
if not isinstance(choices, list):
return []
return [label for choice in choices if isinstance(choice, dict) and (label := _text(choice.get("label")))]
def _said(value: Any) -> str:
"""A form value as the one string an ``interact`` frame takes; empty for no answer."""
if isinstance(value, bool) or value is None:
return ""
if isinstance(value, (int, float)):
return str(value)
if isinstance(value, list):
return ", ".join(item.strip() for item in value if isinstance(item, str) and item.strip())
return value.strip() if isinstance(value, str) else ""
def _text(value: Any) -> str:
return value.strip() if isinstance(value, str) else ""
__all__ = [
"ANSWER_FIELD",
"CUSTOM_FIELD",
"CUSTOM_FOR_META",
"PERMISSION",
"Reply",
"describe",
"elicitation_request",
"pending",
"permission_request",
"question",
"read_elicitation",
"read_permission",
]

Some files were not shown because too many files have changed in this diff Show More