Skip to main content

Crate kernel_apis

Crate kernel_apis 

Source
Expand description

Host operations behind the thin Python kernel APIs, served as one kernel::HostHandler:

  • skills.*: the version-pinned skill catalog (refresh, list, select, load, why; invoke is validated but needs task spawning) and code skills (propose_code / propose_policy with test gating in a fresh kernel, rollback, code_list, code_history), ported from ultron/skills.ts and ultron/code-skills.ts;
  • memory.*: prepare / propose / correct / get / forget / why / list over a Hindsight-shaped backend, ported from ultron/memory.ts and the dispatch of ultron/worker-services.ts;
  • images.*: image generation through the OpenRouter images API, saved to files (images);
  • sessions.*: stored sessions listed, grepped and read as spans, read-only (sessions);
  • hints.*: per-lane hint mutes (ultron/rlm/hints.ts), and cell_hints, the situational hints a cell’s result ends with;
  • tools.*: extension tool calls from the REPL, detached after yield_after (ultron/rlm/extension-tools.ts);
  • schedules.*, goals.* and goal.* as durable work: the schedule tick, goal recovery over the task journal, and DurableWork, the entry point a composition root opens and closes.

Modules are ApiModules, matched by request-type prefix as TS host modules are; every other request goes to the inner handler. Modules start once, on the first request of any type. Requests carry the calling lane, the task that owns it (from the TaskHost) and the host’s task operations.

Re-exports§

pub use artifacts::FileKeyedDocuments;
pub use artifacts::KeyedDocuments;
pub use artifacts::MemoryKeyedDocuments;
pub use code_skills::CodeSkillKind;
pub use code_skills::CodeSkills;
pub use code_skills::CodeSkillsOptions;
pub use context_control::ContextBranches;
pub use context_control::ContextControl;
pub use durable_work::DurableWork;
pub use durable_work::DurableWorkOptions;
pub use durable_work::Recovered;
pub use family::FamilyModule;
pub use family::FamilyOptions;
pub use goal::GoalDriver;
pub use goal::GoalJobs;
pub use goal::JobState;
pub use goal::TaskGoalJobs;
pub use hints::HintsModule;
pub use images::ImagesConfig;
pub use images::ImagesModule;
pub use instances::InstancesModule;
pub use memory::MemoryApi;
pub use memory::MemoryBackend;
pub use memory::MemoryError;
pub use memory::MemoryService;
pub use memory::worker_gate;
pub use progress::ProgressModule;
pub use schedule_tick::ManualTickClock;
pub use schedule_tick::ScheduleTicker;
pub use schedule_tick::TickClock;
pub use schedules::SchedulesModule;
pub use sessions::SessionsModule;
pub use skills::PinnedSkill;
pub use skills::SkillLoader;
pub use skills::SkillSource;
pub use skills::SkillsModule;
pub use tasks::RootOnly;
pub use tasks::TaskHost;
pub use tool_calls::ToolCallEnd;
pub use tool_calls::ToolCalls;
pub use tool_calls::ToolInfo;
pub use tool_calls::ToolRunner;

Modules§

artifacts
Keyed durable documents (DurableDocumentStorage of ultron/local-services.ts), in memory or in one JSON file: the store of schedules, local services and prompt schedules. (TypeScript’s artifacts.* host requests over the same store are not ported.)
cell_hints
Situational hints (ultron/rlm/hints.ts CellHints, ultron/rlm/loop-detector.ts): the host watches how a lane uses the runtime and ends a cell’s result with at most one short tagged line, [hint:<tag>] ..., when something worth knowing happened in that cell: a command detached into a job, a long wait on a job whose completion would have arrived as an event, polling, truncated output, a large file read into a string, the same exception three cells in a row, the same cell run again and again, or a lane stuck in a loop of failing or alternating cells. Mutes and per-tag counts are HintsModule’s (hints.mute). Hints are off unless ULTRON_HINTS=on.
code_skills
Code skills: procedural memory as tested Python (port of ultron/code-skills.ts).
context_control
ctx.* (port of the request side of ultron/context-control.ts) and the context-edit semantics it relies on (applyContextEdits / contextEditsOf of packages/agent/src/harness/session/context.ts).
durable_work
Durable work: schedules, the session goal and shell jobs as durable tasks that survive worker restarts. This is the one entry point a composition root calls.
family
agent_message.* (port of ultron/family.ts): untrusted messages between a task and its direct parent or children. The host derives the sender from the calling lane and enforces scope: a task messages only its parent or a direct child, verifier tasks only talk to their direct parent and never accept steering, and a finished task receives nothing. A key makes a send idempotent per sender. Steering delivers through the receiver’s lane (recorded as delivered before it is handed over, so a crash cannot deliver twice); otherwise messages wait in the receiver’s bounded inbox until receive marks them delivered. Delivered and expired history is kept, bounded, in the module document {version: 1, messages}.
goal
The session goal (/goal, port of ultron/goal.ts GoalDriver): a person sets one objective and a background job (its own REPL, under the usage root goal:<id>) works on it until the goal ends.
hints
hints.mute / hints.unmute / hints.muted (the request side of ultron/rlm/hints.ts): per-lane hint mutes, persisted in the module document {version: 1, lanes: {<lane>: {muted, fired}}}.
images
images.generate / images.models (rlm.images of images_api.py): image generation through the ported OpenRouter images API (ai::images, TS api/openrouter-images.ts). The host makes the requests, saves every image to a file and answers with the paths, so no image bytes reach the cell or the model’s context.
instances
instances.* (port of ultron/instances.ts): a completed RLM task can be retained so later invocations run on the same lane, continuing its conversation and declared state, while each invocation gets its own task record. An open instance pins its lane’s kernel (holder instance:<id>); closing unpins it, and a restarted owner re-pins every open instance. Pinning is best effort: retain reports pinned: false when the pool has no capacity.
memory
memory.* (port of ultron/memory.ts NativeMemoryService and the memory dispatch of worker-services.ts).
memory_import
ultron memory import --from claude-code|codex: the notes other harnesses keep on disk become typed memory records (crate::memory_records), stored through memory.propose with the user’s evidence, so the same secret check refuses what holds a secret. Which files are read follows Mirror (memory/import/*.rs):
memory_pointers
File-linked memory as pointers: when a cell writes a file (a checked write()/edit() or any other change the after-cell snapshot finds) that matches a typed record’s pathGlobs, the lane’s next cell result ends with one line per record, [memory] <id> <type>: <situation>, never the record’s content: the model reads it with memory.get(id) when it wants it. At most MAX_POINTERS lines per cell; each record is pointed at once per session. The setting memory.filePointers: false turns this off.
memory_records
Typed memory records (idea from Mirror’s memory_record.rs, fitted to Ultron’s journal + Hindsight memory).
progress
progress.* (port of ultron/progress.ts): evidence-based progress receipts and reassessment. Progress is inferred only from recorded evidence and task state; reassessment never raises a budget, and a completion claim is verified only by a verifier task the host ran that returned passed: true. The document is {version: 1, receipts, decisions}; a verifier still pending when the owner ended is settled as unverified on load.
prompt_schedule
schedule.* (schedule_api.py, Rust host only): prompts a session sends itself later, the proactive agent.
schedule_tick
The schedule tick: fires due schedules on its own, without anything else waking the session (the TS ScheduleModule interval timer, tickIntervalMs).
schedules
schedules.* and goals.* (port of ultron/schedules.ts): recurring task firings and goals with required checks. Firings are admitted through TaskHost::spawn with a slot-derived key (schedule:<id>:<slot>), and each slot is claimed durably (last_slot, pending_slot) before admission, so duplicate ticks and restarts never run a slot twice; a claimed slot that fails is recorded once and never retried. Missed slots coalesce into one run of the latest slot (skipped). A goal is achieved only when every required check succeeds with passed: true; max_tasks caps firings, verification and attachments. The document is {version: 1, schedules, goals}.
sessions
sessions.list / sessions.search / sessions.read (sessions of sessions_api.py): the stored sessions of this project, or of every project, listed, grepped and read read-only through session_journal::search. A finding cites its turns as a span, session://<id>#<from>..<to>, which sessions.read reads back.
skills
skills.* requests (port of ultron/skills.ts): the version-pinned, explainable skill catalog and the code-skill requests, journaled in the module document. Selection never grants capabilities: frontmatter keys that would grant tools, models, budgets or permissions are reported and ignored.
store
Durable module documents: the format version a stored document is read at.
tasks
The task operations host modules use (TS NativeHostApi of ultron/rlm/host-module.ts). Tasks and results are the TS JSON shapes (NativeTask, NativeResult of ultron/rlm/task-store.ts) so modules port unchanged. Identity comes from the calling lane, never from a payload.
tool_calls
tools.*: extension tool calls from the REPL (ultron/rlm/extension-tools.ts ExtensionToolCalls). The kernel calls a tool with await tools.call(name, params) / await tools.<name>(...) / await mcp.call(...) (the mcp gateway is a tool like any other); the host runs it on its own thread through a ToolRunner with a cancel signal. Every call is a record (name, label, status, elapsed time, input and result previews), journaled as the module document {version: 1, calls: [...]}.
util
The clock seam and small checks the modules share. The JavaScript semantics they use are in jsrt.

Structs§

KernelApis
Request
One host request as a module sees it (TS HostModuleRequest plus the NativeHostApi).

Traits§

ApiModule
A host module: owns every request type that starts with one of its prefixes.