Skip to main content

kernel/
ops.rs

1//! The host requests runtime.py's clients (`packages/coding-agent/src/ultron/rlm/*.py`) send, one row per op: the
2//! module that serves it, the payload keys it takes and the reply keys the clients read. `tests/ops.rs` checks the
3//! Python clients against this table (every op they send is a row, every row is sent, no key outside its row),
4//! and handlers refuse other payload keys with [`fields`].
5
6use serde_json::{Map, Value};
7
8pub struct Op {
9    pub name: &'static str,
10    /// The module (or modules, comma-separated) whose handler serves the op.
11    pub owner: &'static str,
12    pub payload: &'static [&'static str],
13    pub reply: &'static [&'static str],
14}
15
16const fn op(
17    name: &'static str,
18    owner: &'static str,
19    payload: &'static [&'static str],
20    reply: &'static [&'static str],
21) -> Op {
22    Op {
23        name,
24        owner,
25        payload,
26        reply,
27    }
28}
29
30pub const OPS: &[Op] = &[
31    op(
32        "bash",
33        "host",
34        &["command", "timeout", "yield_after"],
35        &[
36            "cancelled",
37            "exit_code",
38            "full_output_path",
39            "job",
40            "output",
41            "partial_file",
42            "running",
43            "timed_out",
44            "truncated",
45        ],
46    ),
47    op("files.before_write", "host", &["writes"], &["results"]),
48    op("shell.cancel", "host", &["id"], &[]),
49    op("shell.get", "host", &["id"], &[]),
50    op("shell.list", "host", &[], &[]),
51    op("shell.read", "host", &["cursor", "id", "max_bytes"], &[]),
52    op("shell.result", "host", &["id", "wait"], &[]),
53    op("shell.run", "host", &["command", "timeout", "yield_after"], &[]),
54    op(
55        "rlm.view_image",
56        "host::view_image",
57        &["detail", "path"],
58        &["description", "note"],
59    ),
60    op("ctx.forget", "kernel_apis::context_control", &["ids", "reason"], &[]),
61    op("ctx.get", "kernel_apis::context_control", &["id"], &[]),
62    op("ctx.history", "kernel_apis::context_control", &["kinds", "limit"], &[]),
63    op("ctx.note", "kernel_apis::context_control", &["text"], &[]),
64    op("ctx.pin", "kernel_apis::context_control", &["id"], &[]),
65    op("ctx.summarize", "kernel_apis::context_control", &["ids", "text"], &[]),
66    op("ctx.unpin", "kernel_apis::context_control", &["id"], &[]),
67    op(
68        "diagram.mermaid",
69        "diagram",
70        &["path", "show", "text", "theme", "to_model"],
71        &[],
72    ),
73    op("agent_message.list", "kernel_apis::family", &[], &[]),
74    op("agent_message.receive", "kernel_apis::family", &["limit"], &[]),
75    op(
76        "agent_message.send",
77        "kernel_apis::family",
78        &[
79            "key",
80            "message",
81            "receiver_id",
82            "receiver_name",
83            "receiver_role",
84            "steer",
85            "ttl_ms",
86        ],
87        &[],
88    ),
89    op("goal.blocked", "kernel_apis::goal", &["reason", "revision"], &[]),
90    op("goal.check", "kernel_apis::goal", &[], &[]),
91    op(
92        "goal.complete",
93        "kernel_apis::goal",
94        &["evidence", "revision", "summary"],
95        &[],
96    ),
97    op("goal.get", "kernel_apis::goal", &[], &[]),
98    op(
99        "sessions.list",
100        "kernel_apis::sessions",
101        &["cwd", "days", "limit"],
102        &["sessions"],
103    ),
104    op(
105        "sessions.read",
106        "kernel_apis::sessions",
107        &[
108            "around",
109            "branch",
110            "from_entry",
111            "limit",
112            "session",
113            "span",
114            "to_entry",
115            "tool_chars",
116        ],
117        &[],
118    ),
119    op(
120        "sessions.search",
121        "kernel_apis::sessions",
122        &[
123            "branch",
124            "cwd",
125            "days",
126            "ignore_case",
127            "limit",
128            "pattern",
129            "per_session",
130            "roles",
131            "sessions",
132            "snippet",
133            "terms",
134        ],
135        &[],
136    ),
137    op("hints.mute", "kernel_apis::hints", &["tags"], &["muted"]),
138    op("hints.muted", "kernel_apis::hints", &[], &["muted"]),
139    op("hints.unmute", "kernel_apis::hints", &["tags"], &["muted"]),
140    op(
141        "images.generate",
142        "kernel_apis::images",
143        &["model", "n", "out", "prompt", "size"],
144        &[],
145    ),
146    op("images.models", "kernel_apis::images", &[], &[]),
147    op("instances.close", "kernel_apis::instances", &["id"], &[]),
148    op("instances.get", "kernel_apis::instances", &["id"], &[]),
149    op(
150        "instances.invoke",
151        "kernel_apis::instances",
152        &["id", "input", "key"],
153        &[],
154    ),
155    op("instances.list", "kernel_apis::instances", &[], &[]),
156    op("instances.retain", "kernel_apis::instances", &["task_id"], &[]),
157    op(
158        "memory.brief",
159        "kernel_apis::memory",
160        &["text", "scope", "topic", "project"],
161        &[],
162    ),
163    op(
164        "memory.correct",
165        "kernel_apis::memory",
166        &["id", "text", "evidence", "evidenceClass"],
167        &[],
168    ),
169    op(
170        "memory.dream",
171        "kernel_apis::memory",
172        &["days", "limit", "project"],
173        &[],
174    ),
175    op("memory.forget", "kernel_apis::memory", &["id"], &[]),
176    op("memory.get", "kernel_apis::memory", &["id"], &[]),
177    op("memory.invalidate", "kernel_apis::memory", &["id", "reason"], &[]),
178    op("memory.list", "kernel_apis::memory", &[], &[]),
179    op(
180        "memory.prepare",
181        "kernel_apis::memory",
182        &["query", "taskId", "scope", "refresh"],
183        &["results"],
184    ),
185    op(
186        "memory.propose",
187        "kernel_apis::memory",
188        &[
189            "text",
190            "evidence",
191            "scope",
192            "evidenceClass",
193            "type",
194            "key",
195            "situation",
196            "pathGlobs",
197        ],
198        &[],
199    ),
200    op("memory.reflect", "kernel_apis::memory", &["query", "scope"], &[]),
201    op(
202        "memory.topic",
203        "kernel_apis::memory",
204        &["topic", "scope", "project"],
205        &[],
206    ),
207    op("memory.why", "kernel_apis::memory", &["taskId"], &[]),
208    op("procedure.abort", "delegation::skill_runs", &["reason", "run"], &[]),
209    op("procedure.coverage", "delegation::skill_runs", &["name"], &[]),
210    op(
211        "procedure.propose",
212        "delegation::skill_runs",
213        &["content", "evidence", "name"],
214        &[],
215    ),
216    op(
217        "procedure.start",
218        "delegation::skill_runs",
219        &["input", "name", "version"],
220        &[],
221    ),
222    op(
223        "procedure.step",
224        "delegation::skill_runs",
225        &["run", "segment", "state"],
226        &[],
227    ),
228    op("progress.assess", "kernel_apis::progress", &["task_id"], &[]),
229    op("progress.history", "kernel_apis::progress", &["task_id"], &[]),
230    op(
231        "progress.reassess",
232        "kernel_apis::progress",
233        &["claim", "extend_budget", "task_id", "verifier", "verifier_input"],
234        &[],
235    ),
236    op(
237        "progress.report",
238        "kernel_apis::progress",
239        &["evidence", "metrics", "summary", "task_id"],
240        &[],
241    ),
242    op(
243        "schedule.at",
244        "kernel_apis::prompt_schedule",
245        &["when_ms", "when_in_ms", "prompt", "name"],
246        &["id"],
247    ),
248    op("schedule.cancel", "kernel_apis::prompt_schedule", &["id"], &[]),
249    op(
250        "schedule.every",
251        "kernel_apis::prompt_schedule",
252        &["interval", "prompt", "name", "until_ms", "until_in_ms", "max_runs"],
253        &["id"],
254    ),
255    op(
256        "schedule.loop",
257        "kernel_apis::prompt_schedule",
258        &["interval", "prompt", "name", "until_ms", "until_in_ms", "max_runs"],
259        &["id"],
260    ),
261    op(
262        "schedule.watch_pr",
263        "kernel_apis::prompt_schedule",
264        &[
265            "repo",
266            "pr",
267            "mode",
268            "interval",
269            "prompt",
270            "name",
271            "until_ms",
272            "until_in_ms",
273            "max_runs",
274        ],
275        &["id"],
276    ),
277    op("schedule.list", "kernel_apis::prompt_schedule", &[], &[]),
278    op("goals.attach", "kernel_apis::schedules", &["id", "task_id"], &[]),
279    op(
280        "goals.create",
281        "kernel_apis::schedules",
282        &["max_tasks", "required_checks", "title"],
283        &[],
284    ),
285    op("goals.get", "kernel_apis::schedules", &["id"], &[]),
286    op("goals.list", "kernel_apis::schedules", &[], &[]),
287    op("goals.pause", "kernel_apis::schedules", &["id"], &[]),
288    op("goals.resume", "kernel_apis::schedules", &["id"], &[]),
289    op("goals.verify", "kernel_apis::schedules", &["id", "input"], &[]),
290    op(
291        "schedules.create",
292        "kernel_apis::schedules",
293        &[
294            "definition",
295            "every_ms",
296            "goal_id",
297            "input",
298            "max_runs",
299            "model",
300            "start_at",
301        ],
302        &[],
303    ),
304    op("schedules.delete", "kernel_apis::schedules", &["id"], &[]),
305    op("schedules.list", "kernel_apis::schedules", &[], &[]),
306    op("schedules.pause", "kernel_apis::schedules", &["id"], &[]),
307    op("schedules.resume", "kernel_apis::schedules", &["id"], &[]),
308    op("schedules.tick", "kernel_apis::schedules", &[], &[]),
309    op("skills.code_history", "kernel_apis::skills", &["name"], &[]),
310    op("skills.code_list", "kernel_apis::skills", &["family", "kind"], &[]),
311    op(
312        "skills.invoke",
313        "kernel_apis::skills",
314        &["input", "name", "version"],
315        &[],
316    ),
317    op("skills.list", "kernel_apis::skills", &[], &[]),
318    op("skills.load", "kernel_apis::skills", &["name", "version"], &[]),
319    op(
320        "skills.propose_code",
321        "kernel_apis::skills",
322        &["evidence", "name", "source", "test_source"],
323        &[],
324    ),
325    op(
326        "skills.propose_policy",
327        "kernel_apis::skills",
328        &["evidence", "family", "name", "source", "test_source"],
329        &[],
330    ),
331    op("skills.refresh", "kernel_apis::skills", &[], &[]),
332    op("skills.rollback", "kernel_apis::skills", &["name", "version"], &[]),
333    op("skills.select", "kernel_apis::skills", &["limit", "query"], &[]),
334    op("skills.why", "kernel_apis::skills", &["decision_id"], &[]),
335    op(
336        "tools.call",
337        "kernel_apis::tool_calls",
338        &["detach", "name", "params", "yield_after"],
339        &[],
340    ),
341    op("tools.calls", "kernel_apis::tool_calls", &[], &[]),
342    op("tools.cancel", "kernel_apis::tool_calls", &["id"], &[]),
343    op("tools.describe", "kernel_apis::tool_calls", &["name"], &[]),
344    op("tools.get", "kernel_apis::tool_calls", &["id"], &[]),
345    op("tools.list", "kernel_apis::tool_calls", &[], &[]),
346    op("tools.result", "kernel_apis::tool_calls", &["id", "wait"], &[]),
347    op("agents.cancel", "delegation::agents", &["id"], &[]),
348    op("agents.inspect", "delegation::agents", &["id"], &[]),
349    op(
350        "agents.invoke",
351        "delegation::agents",
352        &["definition", "input", "key", "model", "timeout_ms"],
353        &["error", "status", "value"],
354    ),
355    op("agents.list", "delegation::agents", &[], &[]),
356    op("agents.register", "delegation::agents", &["definition"], &[]),
357    op("agents.result", "delegation::agents", &["id"], &[]),
358    op(
359        "agents.spawn",
360        "delegation::agents",
361        &["definition", "input", "key", "model"],
362        &["id"],
363    ),
364    op("agents.status", "delegation::agents", &[], &[]),
365    op("agents.tasks", "delegation::agents", &[], &[]),
366    op("background.inspect", "delegation::agents", &["id"], &[]),
367    op("background.list", "delegation::agents", &[], &[]),
368    op("background.result", "delegation::agents", &["id"], &[]),
369    op(
370        "background.start",
371        "delegation::agents",
372        &["key", "model", "prompt", "timeout_ms"],
373        &[],
374    ),
375    op("background.stop", "delegation::agents", &["id"], &[]),
376    op("workflows.run", "delegation::agents", &["key", "nodes"], &[]),
377    op("budget.estimate", "delegation::agents", &["plan", "workflow"], &[]),
378    op(
379        "rlm.collect",
380        "delegation::host, harness::chat::host_ops",
381        &["selectors", "timeout_ms"],
382        &["results"],
383    ),
384    op(
385        "rlm.delete_subagent",
386        "delegation::host, harness::chat::host_ops",
387        &["selector"],
388        &[],
389    ),
390    op(
391        "rlm.finish",
392        "delegation::host",
393        &["changed_files", "evidence", "left", "outputs", "status", "summary"],
394        &[],
395    ),
396    op(
397        "rlm.list_subagents",
398        "delegation::host, harness::chat::host_ops",
399        &[],
400        &["subagents"],
401    ),
402    op(
403        "rlm.merge",
404        "delegation::host",
405        &["include_failed", "on_conflict", "selectors"],
406        &[],
407    ),
408    op("rlm.progress", "delegation::host", &["selectors"], &["subagents"]),
409    op(
410        "rlm.results",
411        "delegation::host, harness::chat::host_ops",
412        &["selectors"],
413        &["results", "running"],
414    ),
415    op(
416        "rlm.spawn",
417        "delegation::host, harness::chat::host_ops",
418        &["kwargs", "prompt"],
419        &[],
420    ),
421    op("rlm.worktrees.cleanup", "delegation::host", &["branches"], &[]),
422    op("rlm.worktrees.list", "delegation::host", &["all"], &["worktrees"]),
423    op("board.add", "harness::chat::host_ops", &["detail", "title"], &[]),
424    op("board.claim", "harness::chat::host_ops", &["id"], &[]),
425    op("board.list", "harness::chat::host_ops", &["status"], &[]),
426    op(
427        "board.update",
428        "harness::chat::host_ops",
429        &["id", "note", "status"],
430        &[],
431    ),
432    op("notes.append", "harness::chat::host_ops", &["text"], &[]),
433    op("notes.read", "harness::chat::host_ops", &[], &[]),
434    op(
435        "notes.write",
436        "harness::chat::host_ops",
437        &["expect_version", "text"],
438        &[],
439    ),
440    op(
441        "rlm.ask",
442        "harness::chat::host_ops",
443        &["child", "question", "timeout_ms"],
444        &[],
445    ),
446    op("swarm.agents", "harness::chat::host_ops", &[], &[]),
447    op("swarm.inbox", "harness::chat::host_ops", &["all", "mark"], &[]),
448    op(
449        "swarm.register",
450        "harness::chat::host_ops",
451        &["files", "name", "summary", "topics", "work"],
452        &[],
453    ),
454    op("swarm.route", "harness::chat::host_ops", &["query"], &[]),
455    op("swarm.send", "harness::chat::host_ops", &["text", "to", "wake"], &[]),
456    op("rlm.frames", "inference", &["id", "limit"], &[]),
457    op(
458        "rlm.infer",
459        "inference",
460        &[
461            "budget",
462            "context",
463            "contract",
464            "max_repairs",
465            "model",
466            "task",
467            "thinking",
468            "timeout_ms",
469        ],
470        &[],
471    ),
472    op(
473        "rlm.load",
474        "inference",
475        &["chars", "digest", "label", "size", "source"],
476        &["label", "path", "stored"],
477    ),
478    op(
479        "rlm.map",
480        "inference::map",
481        &[
482            "budget",
483            "concurrency",
484            "contract",
485            "frames",
486            "max_repairs",
487            "model",
488            "prefix",
489            "thinking",
490            "timeout_ms",
491        ],
492        &["budget", "results", "usage"],
493    ),
494    op("rlm.models", "inference::map", &[], &[]),
495    op("rlm.cancel", "lanes, harness::chat::host_ops", &["cell"], &[]),
496    op("rlm.cell.cancel", "lanes", &["cell"], &[]),
497    op("rlm.cells", "lanes", &[], &["cells"]),
498    op("rlm.lane.close", "lanes", &["lane"], &[]),
499    op("rlm.lane.open", "lanes", &["lane"], &[]),
500    op("rlm.lanes", "lanes", &[], &["lanes"]),
501    op("rlm.recovery", "lanes", &[], &[]),
502    op(
503        "gates.compare",
504        "services::gates",
505        &["baseline", "candidate", "gate_id"],
506        &[],
507    ),
508    op(
509        "gates.define",
510        "services::gates",
511        &["checks", "fixture_hash", "id"],
512        &[],
513    ),
514    op("gates.history", "services::gates", &["gate_id"], &[]),
515    op("gates.list", "services::gates", &[], &[]),
516    op("refinements.activate", "services::local", &["id"], &[]),
517    op("refinements.list", "services::local", &[], &[]),
518    op(
519        "refinements.propose",
520        "services::local",
521        &["baseVersion", "content", "evidence", "kind", "scope", "target"],
522        &[],
523    ),
524    op("refinements.reject", "services::local", &["id"], &[]),
525    op("refinements.rollback", "services::local", &["id"], &[]),
526    op(
527        "ext.call",
528        "session_core::compose",
529        &["arguments", "extension", "function"],
530        &[],
531    ),
532    op("ext.list", "session_core::compose", &[], &[]),
533    op("judge.decide", "judge", &["expect", "kind", "questions", "state"], &[]),
534    op("knowledge.mirror", "graph", &[], &[]),
535    op(
536        "knowledge.relations",
537        "graph",
538        &["kinds", "paths"],
539        &[
540            "files",
541            "mirror",
542            "pending",
543            "pruned",
544            "read",
545            "relations",
546            "rev",
547            "truncated",
548        ],
549    ),
550    op("knowledge.settle", "graph", &["rev", "verdicts"], &["mirror"]),
551    op("rlm.find_models", "session_core::compose", &["limit", "query"], &[]),
552    op("rlm.race_models", "session_core::compose", &[], &[]),
553    op("cell.output", "session_core::turns", &["text"], &[]),
554];
555
556/// The TS host's refusal of a request kind it does not serve, which the model sees.
557pub fn not_wired(kind: &str) -> String {
558    format!("Ultron RLM host request is not wired: {kind}")
559}
560
561pub fn find(name: &str) -> Option<&'static Op> {
562    OPS.iter().find(|op| op.name == name)
563}
564
565/// Refuses a payload key that op `name` does not take: "Unknown payload field: <key>".
566///
567/// # Panics
568/// When `name` is no row of [`OPS`].
569pub fn fields(name: &str, payload: &Map<String, Value>) -> Result<(), String> {
570    let op = find(name).unwrap_or_else(|| panic!("{name} is not in kernel::ops::OPS"));
571    jsrt::payload::fields(payload, op.payload)
572}