## Summary On a Windows host the on-call flow could not run a job: the process backend's launcher is a `/bin/sh` script (`setsid`, `trap`, `kill -0`, `stat -c`), so every job stayed RUNNING forever and the spend scan billed nothing, quietly. - New `windows` job backend (`oncall_flow/windows_backend.py`): the same submit / poll / fetch_result / cancel / fetch_progress contract, written in Python. Liveness uses `raven.utils.pid.pid_alive` (`os.kill(pid, 0)` terminates a process on Windows). Cancel is a tree kill with `taskkill /T`. The job is started through a short-lived relay, so it is nobody's child: stopping the host with `taskkill /T` (which walks parent pids, whatever the creation flags) no longer kills a running job. Measured: a 20-minute job survived the page being stopped and wrote its result. - `backends.py`: registers `windows`, and routes a local `process` campaign to it on Windows, since that is what the agent declares for a command on the owner's machine. - A POSIX `remote_dir` (the `/root/raven-ops` submit default, which never reaches `meta.json`) maps to `~/raven-ops`, so the submit path and the status path look in the same directory. - `ledger.py`: skip the directory fsync on Windows (opening a directory raises EACCES; NTFS journals the rename). - `tui_commands.py` / `_tui_relay.py`: do not forward SIGINT to the child on Windows. The console already delivers Ctrl+C to it, and `Popen.send_signal(SIGINT)` raises ValueError, which took the TUI down. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification On Windows 11, Python 3.13, `uv sync --extra dev`, `PYTHONUTF8=1`: - `uv run pytest tests/ -k "oncall_flow or tui or acp_commands or ledger"` - this branch: 14 failed, 1091 passed, 15 skipped, 18 errors - `origin/main`: 126 failed, 976 passed, 15 skipped, 18 errors - no test fails on this branch that passes on `origin/main`; the remaining failures and the 18 collection errors are identical on both (POSIX shell tests, missing optional modules). - `uv run pytest tests/test_agents_oncall_flow_windows_backend.py`: 3 passed, including a job that survives `taskkill /T` of the process that submitted it. - `uv run ruff check` and `uv run ruff format --check` on the changed files: clean. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed No user-facing docs describe on-call backends per platform, so none were changed. ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes Behaviour changes only on Windows (`os.name == "nt"` / `sys.platform == "win32"` guards); POSIX hosts take the same code paths as before. A job started on Windows now outlives the host by design; `cancel` still stops it. Rollback: revert this commit. ## Related Issues N/A --------- Co-authored-by: silverLXT <xiaotian.luo@evermind.ai> Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
agents/
Agent definitions built on installed raven, serving over raven acp.
Five shipped agents today: raven-code, raven-design, raven-oncall,
raven-ppt, raven-research. A new agent starts as raven agents new <name>
-- the scaffold command that instantiates this whole shape into a fresh
folder; BUILDING.md in this directory is the from-zero guide.
Agents that have no model key of their own inherit the host's model
binding, provider configuration, routing and reasoning effort.
Inheritance uses the same credential check as the host runtime,
including stored OAuth sign-ins such as OpenAI Codex. The child reads
OAuth credentials from the host's home, which it shares because the
host passes its RAVEN_HOME when one is set and both otherwise
normally resolve ~/.raven; tokens stay in that credential store
rather than the rendered agent config. An agent is spawned with the
login shell's environment -- raven's own environment only when that
shell cannot be captured -- so a token-location override
(CHATGPT_TOKEN_DIR, CHATGPT_AUTH_FILE) reaches it when the login
profile exports it, when the agent's stored row carries it in env (a
stored row replaces the discovered one whole), or in that fallback. A
RAVEN_HOME reaches the agent the same ways: from the login profile
while the host has none set, and from the agent's stored row even when
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 servepython -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. -
config.json-- the baseline profile. -
modes/*.json-- optional per-session overlays, surfaced asacp.modesfor a client's mode picker (research,raven-oncall, andcodeship one today). An agent that ships nomodes/renders noacpblock, and the raven it serves then falls back to its own three built-in tiers -- sosession/set_modeanswers with those rather than method-not-found. An overlay'sagents.defaults.reasoningEffortis lifted onto the mode entry as the trunk'sreasoningEffortknob; the rest of an overlay is the agent's own hooks' to read. -
subagent.json-- the roster row templateinstall.pyregisters throughraven.config.update_subagents(the same pinned surface the retired vendored installers used). The inverse is the uninstall story -- delete the roster row with the interpreter that serves raven:# Unquoted on purpose: the shebang may be an `env` line, which is two words. $(sed -n '1s/^#!//p' "$(command -v raven)") -c \ 'from raven.config.update_subagents import remove_third_party_subagent as rm; print(rm("raven-code"))'The folder itself can stay -- an unregistered folder is inert. A live raven holds the roster it read at startup; restart it afterwards. Two manifest fields shape how the row is reached rather than what it runs:
"hidden": truekeeps the row off the roster the dispatching model reads (and off the WebUI's sub-agent page) while a task routed to it still runs there;"routes": [{"to": "<name>"}, ...]makes this row's backend a routing entry (agent/subagent/backends/routing.py): every caller --spawn, a DAG node, a direct chat -- runs the row, and the entry picks the implementation onrun, reading the task as the model wrote it (authored_task), never the rendering with file contents inlined. A reused instance handle stays where its transport bound it; otherwise the host's own model picks between the targets' roster lines and this row. A fronting row is only as ready as its targets: a route to a folder that is missing, unready or switched off disables the row with the reason on it, so a half-installed agent does not run the missing half's work on the wrong implementation. A route entry may also carry"owes"and"note": what the work still owes when the entry keeps it on this row instead of sending it, and what to tell this row's own implementation when that happens, appended to the task under a[host]marker. Both are the row's words, because the gate that closes a route serves every row that declares one; a route that declares neither hands the task over exactly as it arrived. Prose past a sentence goes in"noteFile": "<name>.md"beside the manifest instead -- discovery reads that file intonote, so a requirement long enough to be worth writing stays reviewable as a diff; declaring both is refused. What puts a route under that gate at all is its own declaration, and the three parts are independent:"needs": ["image_generation", "image_search"]names what the target's own pipeline cannot work without,"needsFile": ".pptx"a file the user attached that the dispatch hands over (a direct chat's media, or an attachment of the turn that the spawn task names -- a path in the text alone is not one) for the route to open, and"minTier": "max"the lowest tier the route may open at. A route naming none is dispatched exactly as routes were before the gate existed -- never probed, never asked for a file, never tiered -- becauseroutesis a general facility and a row routing for reasons of its own must not inherit conditions it never asked for. The names inneedscome from a closed vocabulary (ROUTE_REQUIREMENTS), since the host is what answers them; one outside it is warned about and treated as met, so a manifest written for a later raven keeps its route on an older one. And the probe answers for the target's lane, reading the product folder's own.envfirst (PPT_SERPER_API_KEY,PPT_IMAGE_API_KEY) and falling back to the host sections the launcher would inherit -- the host's own credentials answer for the host loop, and a lane is free to be equipped differently. It follows the launcher one branch further than the explicit keys: with no image key anywhere and an OpenRouter endpoint, the key paying for the lane's words pays for its pictures, so a folder holding onlyPPT_API_KEYstill counts as able to draw -- and towards any other gateway it does not. All four fields are manifest facts: a stored row takes them from the folder on every merge.raven-pptships hidden behindraven-design's routes, so the model sees one design agent and decks still build on the deck engine, its own model and key; the two halves share one everos identity (raven-design), so what the user says over a deck is remembered for the next design turn. ItsPPT_API_KEYis configured throughraven subagents setupor the folder's.env, since the page no longer lists it. -
plugins/<id>/-- the agent's own harness as raven plugins: hooks on the loop's six phases, replacement tools under the built-in names, its own config slice underplugins.config["<id>"].run.pynames the directory throughplugins.dirs; nothing inraven/knows the plugin exists. An agent's harness may instead ship as a standalone distribution:raven-pptandraven-designcarry noplugins/directory -- their engines are theplugins-dist/ppt-engineandplugins-dist/design-enginewheels, found through theraven.pluginsentry-point group. Each engine underplugins-dist/belongs to its agent -- but an entry-point plugin withenabled_by_default = trueACTIVATES in every raven process in the environment; staying out of the host's and the sibling agents' turns is the engine's own duty, done by factories that decline when their config slice is absent (what the scaffold's engine templates do), or by the operator'splugins.disabledlist. Prompt assets ride with the plugin whose conduct they teach, underplugins/<id>/prompts/: the workspace guiderun.pyregenerates on every launch (oncall's TOOLS.md section, code's whole-file TOOLS.md) lives there.raven-codealso seeds its identity assoul.md(besiderun.py, the raven-research shape) and a coding conduct asagent.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), and its code-flow hook contributes the working directory's own instruction files (AGENTS.md/CLAUDE.md/CONTEXT.md, the slice'sprojectFiles) to each turn's system message through the context assembler, without rewriting the query. The same plugin carries one more surface:code-flow/code_flow/tools/-- the product's own tool face, contributed by the same plugin: the fork's spelling (file_path/old_string, with the host's names accepted as aliases),glob,todo. Four of them ride the built-in names, which is how a product serves its own file tools without touchingraven/agent/tools/or the four other products that share it: plugin tools register last and a same-name registration replaces the built-in instance, so the model is only ever shown this one. Disabling the built-in name instead is not the same thing -- withholding is by name and would take the replacement with it. The face is a section of the flow slice (tools), with its own switch and arestrictToWorkspacethe launcher renders from the product'stoolsblock: a plugin factory cannot read that field, and a replacement built without it is fenceless whatever the product asked for. The ask tier is decided per hosting, not product-wide: the ACP hosting keeps trunk'sask(raven dispatching a sub-agent answers those prompts itself, and a person in an editor should still be asked), and the one-turn CLI hosting renderspermissions.mode: fullbecause that hosting has no 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 intoagent.md-- optional: the agent's own identity, regenerated into the workspace on every launch, for an agent that replaces the host identity (research does; itscontext.dropSegmentskeeps the host's own identity segment out of the prompt). An agent whose vendored twin served the host-generic identity carries nosoul.mdand keeps the host identity segment -- oncall and design: each of those forks' SOUL.md is byte-identical to trunk's own template, its ACP path never seeded it into a workspace, so an added identity file would change the very prompt face the parity tests pin.raven-codeis the exception with a reason: its one-turn CLI hosting runsraven agent, whose workspace sync writes trunk's templatesoul.md-- a personal assistant with a personality -- in front of the coding conduct, while its ACP hosting (no sync) read none; seeding its ownsoul.mdfirst gives both hostings one identity and keeps the host identity segment.raven-pptalso carries nosoul.md, for a different reason: its fork's SOUL.md is its own, and it rides byte-for-byte at the engine wheel's prompts home (raven_ppt/prompts/), seeded into the pinned home by the engine plugin's hook at first turn.
Agent vocabulary:
- Rendered config -- what
run.pywrites and serves from: the baselineconfig.jsonafter secret slots, host LLM inheritance and the mode catalogue are applied. Rendered files live under the state root, never in the agent directory. - State root -- where the agent keeps its work (repos, instance
buckets, flow stores, rendered configs):
product_state_root()inraven/config/product_render.py, default<raven home>/workspace/subagent_sessions/<agent>, overridden by the agent's*_STATE_ROOTvariable. - ACP home -- the engine's own Agent home,
product_acp_home(): under the raven data directory, never inside the host's Agent home (the host hands its home out as a session working directory, and a raven engine refuses a working directory that contains its own home). The agent's*_ACP_HOMEvariable overrides it outright. - Tool-face pin -- each launcher test pins the exact tool face the
rendered config exposes (
VENDORED_TOOL_FACEintests/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()inraven/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.mdsibling (agent.local.mdbesideagent_memory/profile/agent.md,soul.local.mdbesidesoul.md,TOOLS.local.mdbesideTOOLS.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.mdfile. 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.mdis 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.sha256receipt still matches it, and relaunch on the older code.
Agent notes:
raven-designgives each session its own working directory under<workdir>/designs/<session-slug>-<hash>/, following the deck agent's per-session directory mechanism. The hash uses the full session key so channel names, normalized characters and truncated names remain distinct. Task State is still stored under the configuredtaskState.stateRoot, keyed by this session directory; relative file and render paths use the same directory. The reply ends with that directory's absolute path and the note that its paths resolve against it: a caller dispatched the run into the directory above, which is what its dispatch receipt names, so it would otherwise resolve the reply's relative paths one level too high and deliver nothing. A symlink used asdesigns/or as the session directory stops the turn before model or tool execution, preserving the original working directory's access boundary. The caller's working directory may itself be a symlink; its resolved location is the root. Resuming a session with the same working directory returns to its files and Task State. Setplugins.config["design-engine"].workdirPerSessiontofalseto keep the caller's directory directly. Existing files and Task State from the shared directory are left there: their owning session cannot be inferred safely.raven-ppt(the deck agent) needs the ten bundled templates theppt-engineplugin offers, and gets them from the clone: they are tracked underplugins-dist/ppt-engine/raven_ppt/assets/templates/, which the editable install serves and the ppt-engine wheel bundles. Nothing to fetch and no token to hold -- the registry they used to be fetched from is private, and requiring it left an outside install with an empty catalogue and a wheel carrying zero templates.plugins-dist/ppt-engine/templates.manifest.jsonstill pins every file by sha256;make verify-templateschecks the tracked copies against those pins,make fetch-templateslands a fresh cut over them (maintainers,GITLAB_TOKEN), and release.yml refuses a wheel that does not carry all ten.
Ground rules:
- The A side of the comparison is the retired vendored tree: byte snapshots
of its record live under
tests/fixtures/vendored_fork/, and the full trees remain in git history (the commit that removedsubagents/is the anchor). Nothing here may re-grow a dependency on that tree. - The runtime never imports this directory -- enforced by the import-linter contract "the runtime does not import the agents pilots".
- In the wheel as data, never as code:
hatch_build.pymaps the tracked files toraven/agentsfor the roster's file-level discovery, and the import-linter contract still keeps the runtime from importing any of it. - Acceptance for a shipped agent is transport-face equivalence against its vendored twin: transcript shape, timeout semantics, everos records field by field.