Compare commits
1 Commits
main
...
fix/settin
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
de8503b272 |
27
.github/release-notes-template.md
vendored
27
.github/release-notes-template.md
vendored
@ -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
|
||||
|
||||
|
||||
62
.github/workflows/ci.yml
vendored
62
.github/workflows/ci.yml
vendored
@ -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
|
||||
|
||||
1
.github/workflows/release.yml
vendored
1
.github/workflows/release.yml
vendored
@ -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
1
.gitignore
vendored
@ -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).
|
||||
|
||||
190
CHANGELOG.md
190
CHANGELOG.md
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
565
CONTEXT.md
565
CONTEXT.md
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
4
Makefile
4
Makefile
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 帮你安装
|
||||
|
||||
16
RELEASING.md
16
RELEASING.md
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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.
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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()
|
||||
@ -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",
|
||||
]
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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",
|
||||
]
|
||||
|
||||
@ -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,
|
||||
)
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
|
||||
@ -64,6 +64,9 @@
|
||||
},
|
||||
"plugins": {
|
||||
"config": {
|
||||
"everos-memory": {
|
||||
"base_url": "http://localhost:18791"
|
||||
},
|
||||
"design-engine": {
|
||||
"enabled": true,
|
||||
"visualDomainSelector": {
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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]:
|
||||
|
||||
@ -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",
|
||||
]
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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):
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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),
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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")
|
||||
|
||||
|
||||
|
||||
@ -118,6 +118,9 @@
|
||||
},
|
||||
"plugins": {
|
||||
"config": {
|
||||
"everos-memory": {
|
||||
"base_url": "http://localhost:18791"
|
||||
},
|
||||
"ppt-engine": {
|
||||
"enabled": true,
|
||||
"profile": "script_author",
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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};
|
||||
}
|
||||
|
||||
@ -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 |
|
||||
|
||||
@ -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 }
|
||||
|
||||
| 现象 | 检查 |
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 不为每个外部
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -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`。
|
||||
|
||||
@ -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.
|
||||
@ -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`,经链路送达。
|
||||
@ -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
|
||||
|
||||
@ -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` 不联系机器,并明确保留“未验证连接”状态。
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 秒,每节点
|
||||
最多两次继续。这些设置限制额外模型调用和等待,不证明外部动作可安全重试。继续有
|
||||
副作用的节点前,应检查是否已创建文件、发送消息或启动远程任务。
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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 }
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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。
|
||||
|
||||
|
||||
@ -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 |
|
||||
|
||||
@ -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 契约
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -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`。
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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)。
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
@ -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
|
||||
|
||||
|
||||
@ -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
@ -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" |
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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 }}
|
||||
|
||||
@ -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():
|
||||
|
||||
1354
i18n/messages.json
1354
i18n/messages.json
File diff suppressed because it is too large
Load Diff
@ -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 }
|
||||
@ -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"
|
||||
@ -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)
|
||||
@ -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)
|
||||
@ -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" }
|
||||
@ -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",
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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] = []
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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}")
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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.
|
||||
"""
|
||||
@ -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())
|
||||
@ -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",
|
||||
]
|
||||
@ -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",
|
||||
]
|
||||
@ -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
Loading…
x
Reference in New Issue
Block a user