Gap
analysis: the coding-agent specification against
oklm agent
Every section of agent_skill_chat_spec.md, then of process_spec.md, git_spec.md and commands_spec.md, against what the harness already does, of serving_spec.md against the server, and of rag_spec.md against what retrieval can build on, with evidence. The plan built on it is agent-design.md.
Status: audits of 2026-11-02: the agent specification's M0, then the process (P0), git (G0), commands (C0) and serving (S0) specifications' sections at the end, then the RAG specification's K0 (2026-11-08); each is updated at the start of its milestones.
Review of 2026-11-04: every row not marked ✅ was checked against the code again. 88 rows changed, most of them done by later milestones (hooks, compaction, templates, checkpoints, services, integrations, the git layer). What is still open (2026-11-08, the order to take it in is the roadmap's "Next": housekeeping, small leftovers, known speed gaps, larger work, what is optional, what is deferred, what is blocked, what stays out on purpose and why):
- Two defects found, both fixed since: with
--worktree, the project's settings were parsed and its WorktreeCreate hook ran before the trust question; processes started by a background sub-agent had no owner and could die with its thread (PR_SET_PDEATHSIGis per thread). - Missing by choice: LS,
mcp serve,/keybindings,/voice,/subtask,/fast,/advisor, iOS (the reasons in the roadmap, "Left out on purpose"); the job tests on Windows wait on a real Windows machine (roadmap, "Blocked"). The command classifier is done. - Partial: the rows marked 🟡, each saying what is left.
- Training on a large base: done on Qwen3-8B (two QLoRA rounds of the MCP fine-tune on the quantized base, the T rows below); the security fine-tune's next run is deferred (the roadmap's "Next", section 5); the hybrid layers' real-weight check is blocked (an 80B release only).
Legend: ✅ present, 🟡 partial, ❌ missing, ⚠️ conflicting with the
spec's conventions (on purpose where the row says so). Paths are
relative to the repository root. In apps/oklm.c, functions
are named instead of lines, which move often.
Answers to the spec's "fill in before starting"
| Question | Answer | Evidence |
|---|---|---|
| Interpreter / runtime | OKLM's own C inference engine, in the same process: the agent
tokenizes, keeps the KV cache of the common prefix, evaluates and
samples itself. The OpenAI-compatible server
(/v1/chat/completions with tools) exists, but
the agent does not use it. The only other source of text is the
generate callback, which the tests use as a mock. |
src/harness/agent.c:1447-1596 (model_turn);
include/oklm/harness/agent.h:203-221; src/server/server.c |
| Model(s) and context window | Any supported GGUF family (Llama, Qwen 2/3, Gemma 1-3, Phi 2/3,
Granite and its MoE, GPT-2, DeepSeek 1/2, Qwen MoE). The default model
is Qwen3-8B Q4_K_M, found in the models directories when nothing names
one (Qwen3-4B Q4_K_M for quick runs). oklm agent opens
32768 tokens by default, within the model's training length; a turn has
at most 8192 tokens and a message 32 turns. |
apps/oklm.c cmd_agent; agent.c:231-239; compatibility.md; agent-loop.md |
| Native tool calling | Yes. The tools go into the chat template's tools
variable, in five wire formats: Hermes (<tool_call>),
Llama 3 (<|python_tag|> or bare JSON), Mistral
([TOOL_CALLS]), GLM-4.5 (<tool_call>
with <arg_key> / <arg_value>
pairs) and GLM-4-0414 (the name, then JSON arguments, at the start of
the turn). The format is detected from the template or set with
--tool-format, Hermes otherwise. From the trigger on, the
call is constrained by a grammar built from the tools' schemas. |
include/oklm/model/tool_calls.h; agent.c:1225-1239, 1527-1576; adr/0009-tool-calls-and-grammars.md |
| Vision | The engine yes (oklm describe, SmolVLM). The agent no:
messages are text, and Read refuses images as binary. |
include/oklm/mm/vision.h; src/harness/tools.c:449-465 |
| Implementation language | C17 with POSIX threads; libc and nilorea (compiled from source) only. | adr/0001-language-and-dependencies.md, adr/0014-nilorea-as-source-tree.md |
| Platforms | Linux: everything, commands confined by namespaces, seccomp and limits. Windows (MinGW, tested under Wine): everything but the confinement, commands get Job Object limits only. macOS: not a target. | build.md; src/harness/sandbox.c; adr/0011-sandbox.md |
| Binary, config dir, memory file | ⚠️ on purpose (agent-design.md decisions 1 and 2):
oklm agent (a subcommand), .oklm/ in the
project and ~/.config/oklm/ for the user
($XDG_CONFIG_HOME, %APPDATA% on Windows),
managed /etc/oklm/managed-settings.json
($OKLM_MANAGED_SETTINGS), .agent/ read as a
fallback. Memory files: AGENTS.md (written by
/init), OKLM.md, AGENT.md,
CLAUDE.md (M5b). |
src/harness/permissions.c:618-631; skills.c:1121-1156; memory.c
default_names |
§0, §0A Principles and audit
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 0 | Swappable backend | ✅ (M1) | agent.h oklm_agent_backend; agent_http.c;
agent_mock.c |
The model in process, an OpenAI-compatible HTTP server, fixtures, or
the caller's callback (as row 49). test_agent.c test_mock,
test_http_chunks |
| 0 | Tools never crash the loop | ✅ | tools.c:3941-4016 | Failures become OKLM_TOOL_ERROR / DENIED
text. test_tools.c test_files, test_asking;
test_agent.c test_denied |
| 0 | Testable without a model | ✅ | test_agent.c (scripted generate) |
|
| 0A | Gap analysis and design note | ✅ | this file, agent-design.md |
§1 Directory layout
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 1 | Layout | ✅ | src/harness/ (about 40 modules), include/oklm/harness/, tests/harness/ | One module per concern with its own test (agent-design.md, principles of the mapping); new modules go to src/harness/. |
§2 Model adapter
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 2.1 | Adapter interface (context window, token count, stream events) | ✅ (M1) | agent.h oklm_agent_backend,
oklm_agent_event |
The in-process model, a backend (HTTP, mock, the caller's), stream events with usage and stop reasons. Token counting per part is §10. |
| 2.2 | Chat template with tools and tool results | ✅ | agent.c:1330-1375; src/model/chat_template.c; adr/0006-chat-templates.md | test_agent.c test_calls |
| 2.2 | Prefix cache reuse | ✅ | agent.c:1476-1498 | The system prompt changes with the skills list and plan notice (agent.c:804-867), so a mode change drops the cache. No direct test. |
| 2.2 | Cancel during generation | ✅ (M1) | oklm_agent_cancel(); apps/oklm.c
view_interrupt, view_keys |
Within a token; Esc and Ctrl-C on the terminal. test_server.c
test_agent_model, test_agent.c
test_cancel_text |
| 2.2 | Retry and backoff | ✅ | agent_http.c http_turn,
oklm_agent_http_set_retries,
oklm_agent_http_transient; settings
maxRetries |
No connection, a time-out, 408, 409, 429 and 5xx sent again after 1,
2, 4 s... (30 s at most, or Retry-After), 4 times by
default, never once part of the answer has arrived; a cancel stops the
wait; 4xx fail at once. test_server.c
test_agent_http_retry |
| 2.3 | Text tool-call protocol | ⚠️ | tool_calls.h; adr/0009-tool-calls-and-grammars.md | On purpose (ADR-0009): each family's native format instead of
{"name","input"}, Hermes the fallback. |
| 2.3 | Lenient parser | ✅ (M2) | src/model/tool_calls.c json_repair |
Code fences, single quotes, trailing commas, raw newlines, Python
literals, calls cut off; fuzzed (fuzz_toolcalls, 46 million inputs).
test_grammar.c test_tool_calls_lenient |
| 2.3 | Schema validation, error with the schema, N retries | ✅ (M2) | tools.c args_fit; agent.c watch_loop |
Every call checked against its schema, the error naming the fault
and showing the schema; three invalid calls in a row stop the turn.
test_tools.c test_search_options, test_agent.c
test_loops |
| 2.3 | Fake tool results detected | ✅ (M2) | tool_calls.c before_fake_results |
Text from <tool_response> /
[TOOL_RESULTS] on is dropped with any call after it. |
| 2.4 | <think> parsing |
✅ | src/harness/think.c; agent.c:1383-1387, 2725 | test_think.c |
| 2.4 | Folded display; kept out of later context | ✅ (M1) | apps/oklm.c view_split, view_toggle;
agent.c any_turn |
Folded with Ctrl-O; stripped from sub-agent reports and from what is
sent back to a backend; the in-process templates drop it. test_agent.c
test_think_in_content |
| 2.4 | "think hard" keywords, budget | 🟢 | agent.c model_turn, agent_send_inner;
settings maxReasoningTokens |
maxReasoningTokens
(OKLM_MAX_REASONING_TOKENS) caps a turn's
<think> tokens, closing the block so the answer
follows; a
think hard/think harder/think deeply/ultrathink
in the message lifts the cap for that turn. /effort still
turns a template's reasoning on or off. |
| 2.5 | Fast model, /model, model per sub-agent |
✅ | oklm.c c_model, cmd_agent (smallModel);
agent.c oklm_agent_set_aux_model,
sub_model |
/model switches the main model (a GGUF reloaded, or the
HTTP backend's). smallModel loads a small model beside the
main one for the asides (titles, compaction summaries): it answers in
its own context, the main model's cache untouched. A sub-agent
definition's model: small (or fast) runs the
sub-agent on it, in a context of its own. test_agent.c
test_aux_model. |
| 2.6 | Mock adapter with fixtures | ✅ (M1) | agent_mock.c; oklm agent --mock |
JSONL fixtures, requests recorded. test_agent.c
test_mock |
§3 Messages
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 3 | Roles | ✅ | agent_internal.h:28-44; agent.c:286-323 | OpenAI-style tool role. |
| 3 | Content blocks (text, image, thinking, tool use, tool result) | 🟡 | agent_internal.h agent_msg; agent.h
OKLM_AGENT_EV_REASONING |
Text, parsed calls, results by call id and metadata; reasoning is a stream event left out of the history; no image blocks (Read says the model cannot see images). |
| 3 | One result per call, "Interrupted" | ✅ (M2) | agent.c oklm_agent_send |
Interrupted calls get "Interrupted by the user", calls that cannot
run an error result. test_agent.c test_cancel_tools |
| 3 | Metadata (uuid, parent, time, usage, isMeta) | ✅ (M2) | oklm_agent_message() |
test_agent.c test_parallel_reads,
test_loops |
§4 Agent loop
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 4 | Generate, run tools, return results, repeat | ✅ | agent.c:4077-4411 | test_agent.c test_calls |
| 4 | Hooks | ✅ (M11) | hooks.c oklm_hooks_run |
As rows 227 to 231: nine events, exit codes, JSON decisions. test_hooks.c |
| 4 | System reminders | ✅ (M5) | agent.c remind, push_meta; tools.c
oklm_tool_ctx_changed_files |
Jobs, background reports, loops, the mode when it changes, files
changed on disk, the task list gone stale; merged into the user's
message for the template. test_agent.c test_reminders |
| 4 | Automatic compaction | ✅ (M7) | compact.c agent_context_check,
micro_compact, agent_compact_now |
As row 175: compaction at compactThreshold (0.85) and
micro-compaction of old tool results. test_compact.c
test_long_session, test_rolling |
| 4 | Read-only tools in parallel | ✅ (M2) | agent.c parallel_group |
Read, Glob, Grep, JobOutput in a row, unasked. test_agent.c
test_parallel_reads |
| 4 | Result truncation | ✅ | agent.c:2642-2663 | Head only, no spill file. |
| 4 | Turn limit | ✅ | agent.c:4143-4145, --max-turns |
test_agent.c test_turn_limit |
| 4 | Interrupts (Esc, Ctrl-C) | ✅ (M1) | oklm_agent_cancel(), view_interrupt,
view_keys |
Generation, a running command, the remaining calls; a second Ctrl-C
on an empty prompt exits. test_agent.c test_cancel_* |
| 4 | Steering while working | ✅ (M2) | oklm_agent_steer(); apps/oklm.c
view_key |
test_agent.c test_steering |
| 4 | Loop detection | ✅ (M2) | agent.c watch_loop |
test_agent.c test_loops |
| 4 | Token budget | ✅ | agent.h max_tokens, max_turns; oklm.c
--max-turns, --max-tokens |
A budget per turn and a ceiling of turns, as the spec asks.
test_agent.c test_turn_limit |
§5 Tools
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 5 | Common contract | ✅ | tools.c tools_read_only,
oklm_tool_ctx_read_only, custom-tool
read_only; mcp.c (readOnlyHint); agent.c
parallel_group |
Read-only calls run in parallel: the built-in read tools, and
program-added or MCP tools that declare it (an MCP tool's
readOnlyHint reaches the context, so its read calls
parallelize). test_mcp.c test_server. |
| 5 | Truncation with spill file | ✅ | agent.c clip, clip_spill; process.c
keeper |
Output capped at maxToolOutputChars (30000); when a
foreground result is longer it is spilled whole to
.oklm/tool-output/ and the cut tells the model the path to
Read for the rest (background jobs keep their output in their log).
test_agent.c test_spill. |
| 5.1 | Read | ✅ (M2) | tools.c t_read |
PDF page ranges, notebooks, images named (no vision), the read
registry. test_tools.c test_read_kinds |
| 5.2 | Write | ✅ (M3) | tools.c t_write, freshness |
Atomic, parents created; an existing file only once read and
unchanged (hash); CR LF and byte order mark kept. test_tools.c
test_write_edit |
| 5.3 | Edit | ✅ (M3) | tools.c t_edit, apply_edit,
edit_snippet |
Not-read and changed-since-read errors, Read's line numbers
stripped, CR LF matched, numbered snippet in the result. test_tools.c
test_write_edit |
| 5.4 | MultiEdit | ✅ (M3) | tools.c t_multi_edit |
In order, all or none. test_tools.c
test_write_edit |
| 5.5 | Glob | ✅ (M2) | tools.c t_glob, list_files |
.gitignore files, newest first, 1000 at most.
test_tools.c test_search_options |
| 5.6 | Grep | ✅ (M2) | tools.c t_grep |
OKLM's regex engine (no ripgrep); types, context, multiline, output
modes, head_limit and offset. test_tools.c
test_search_options |
| 5.7 | LS | ❌ | tools.c tools[] |
Optional; Glob and Bash list files. |
| 5.8 | Bash: persistent shell | ✅ (M3) | tools.c shell_wrap |
Directory and variables saved by an EXIT trap and restored (POSIX;
not on Windows); a directory outside the project reset. test_tools.c
test_shell |
| 5.8 | Timeouts, exit code, output | ✅ | tools.c:1971-2062 | test_tools.c test_bash |
| 5.8 | Background | ✅ | tools.c:1648-1775; jobs.c | Plus detach. test_jobs.c test_tools |
| 5.8 | Head and tail kept, ANSI stripped | ✅ (M3) | process.c keeper, strip_ansi |
test_tools.c test_shell |
| 5.8 | Interactive commands neutralized | ✅ (M3) | process.c (stdin from /dev/null, pager and editor variables) | test_tools.c test_shell |
| 5.9 | BashOutput / KillShell | ✅ | tools.c (BashOutput read as ProcessOutput,
KillShell as ProcessStop) |
The spec's names are aliases (agent-design.md decision 3); ProcessOutput gives the output since the model last read it. |
| 5.10 | WebFetch | ✅ (M16) | tools.c t_webfetch; client.c
oklm_client_fetch |
No small-model summary of the page (the text is given, capped by the output limit), no cache. test_web.c |
| 5.11 | WebSearch | ✅ (M16) | tools.c t_websearch |
Through a SearXNG instance (webSearch.url) only.
test_web.c |
| 5.12 | TodoWrite | ✅ (M5) | tools.c t_todo |
activeForm (todo_active), one task in
progress, shown whole on the terminal, recalled by reminders.
test_tools.c test_plan, test_agent.c
test_reminders |
| 5.13 | Task | ✅ (M12) | agent.c run_subagent |
Named Agent on purpose, Task read as an
alias (agent-design.md decision 3); as row 192. test_subagents.c |
| 5.14 | NotebookEdit | ✅ (M16) | tools.c t_notebook_edit |
test_web.c test_notebook |
| 5.15 | AskUserQuestion | ✅ (M16) | tools.c t_ask_question; oklm.c
agent_question |
test_web.c test_ask; tools/check_commands.sh |
| 5.16 | ExitPlanMode / EnterPlanMode | 🟡 | tools.c t_exit_plan; oklm.c c_plan |
ExitPlanMode only: the model cannot enter plan mode itself; the user
does with /plan, /mode plan or Shift+Tab.
test_tools.c test_plan |
| 5.17 | Skill | ✅ (M13) | skills.c skill_tool; agent.c
run_skill_fork |
{skill, args}; a forked skill as a sub-agent. §13.
test_skills.c |
| 5.18 | ToolSearch, deferred tools | ✅ (M13) | agent.c agent_tools, run_tool_search,
is_deferred |
deferredTools (by default ProcessList, PowerShell, LSP,
ScheduleWakeup, Service, NotebookEdit, WebSearch, AskUserQuestion,
EnterWorktree, ExitWorktree); the grammar accepts them all, so the
prompt never changes; a backend offered what was loaded. test_skills.c
test_tool_search, test_backend_tools |
| 5.19 | Registry, tools enabled per settings or agent | ✅ | agent.c tool_allowed, tool_offered,
agent_tools, is_deferred; permissions.c
oklm_perms_tool_denied |
Deferred tools and per-agent tool lists exist (rows 116, 194); a
tool a deny rule or --disallowedTools refuses whatever its
arguments is left out of the prompt, the deferred list, ToolSearch and
the grammar (the run-time refusal stays). |
§6 Permissions and sandbox
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 6.1 | Modes | ✅ | permissions.h:66-71; permissions.c:759-817 | test_permissions.c test_modes |
| 6.1 | Shift+Tab cycling | ✅ (M4) | line_edit.c (OKLM_LINE_MODE); permissions.c
oklm_perms_next_mode; tools.c
oklm_tool_ctx_cycle_mode |
At the prompt and while the agent works. test_line_edit.c,
test_permissions.c test_next_mode |
| 6.1 | Bypass mode | ⚠️ | permissions.c oklm_perms_set_mode; oklm.c
view_mode |
On purpose (agent-design.md decision 4, ADR-0010): the banner,
--dangerously-skip-permissions and the policy switch exist,
and bypass needs the sandbox. |
| 6.2 | Rule syntax, MCP prefixes | ✅ | permissions.c:261-326, 645-655 | test_permissions.c test_other_rules |
| 6.2 | Precedence | ✅ | permissions.c:1744-1751 | test_permissions.c test_precedence |
| 6.2 | Compound commands | ✅ | util.c:139; permissions.c:1638-1715 | test_permissions.c test_split,
test_bash |
| 6.2 | Paths, symbolic links | ✅ | util.c:296-376; permissions.c:1728-1733 | test_permissions.c test_paths,
test_path_rules |
| 6.2 | Added directories, /add-dir |
✅ (M4) | permissions.c oklm_perms_add_dir; tools.c
oklm_tool_ctx_add_dir; oklm.c /add-dir |
Settings, and /add-dir for the session (writable in the
sandbox too). |
| 6.3 | Question shows the call | ✅ (M4) | tools.h oklm_ask; tools.c edit_preview;
util.c text_diff |
The call in short, a unified diff for Write / Edit / MultiEdit.
test_tools.c test_question, test_permissions.c
test_diff |
| 6.3 | Yes / always / no with feedback | ✅ (M4) | tools.c always_rules, remember;
permissions.c oklm_perms_save_rule |
"Always" names its rule and saves it to
.oklm/settings.local.json; any other text refuses and
reaches the model. test_tools.c test_question,
test_permissions.c test_save_rule |
| 6.4 | Dangerous patterns | ✅ (M4) | permissions.c builtin_dangers,
danger_bash, danger_path,
oklm_perms_add_danger |
Allow turned into ask, in every mode; git's stateless entries and
the integrations' included, git's state-dependent ones left to G2.
test_permissions.c test_dangers |
| 6.4 | Command classifier | 🟢 | agent.c agent_classify_bash; tools.c
oklm_tool_run (ctx->classify); settings
commandClassifier |
With a smallModel set and
commandClassifier on, the small model rates each Bash
command for injection / exfiltration risk before it runs; a flag makes
the call ask even when a rule allows it. Fails open (no small model or
an unclear answer leaves the dangerous-pattern list, row 133, to
decide). test_tools.c test_command_classifier, test_agent.c
test_classify_bash. |
| 6.4 | Secrets masked | ✅ | telemetry.c oklm_mask_secrets /
oklm_scan_secrets; agent.c clip; audit.c
oklm_audit_scan; tools.c oklm_tool_run; git.c
oklm_git_precommit |
Credential shapes (sk-, ghp_, AKIA, AIza, Bearer, token=,
password=...) masked in a tool's output before the model, the transcript
and the spill file see it (agent.c clip), and in telemetry,
the debug log and /bug; refused at commit time. A tool's
output is also scanned (oklm_tool_run): found secrets are
registered with the audit log (masked in recorded arguments) and the
user is told. test_telemetry.c test_scan, test_tools.c
test_secret_scan. |
| 6.4 | Untrusted content policy | ✅ (M4) | agent.c (system prompt) | Tool results, files and pages are data, not instructions. |
| 6.5 | OS sandbox | ⚠️ | sandbox.c; proxy.c; adr/0011-sandbox.md | Own namespaces and seccomp rather than bubblewrap; the network all,
none, or by domain through a proxy (M18); Windows limits only.
test_sandbox.c test_network_filter;
tools/check_network.sh |
§7 Configuration
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 7.1 | Hierarchy | ✅ (M6) | settings.c oklm_settings_load, merge,
oklm_settings_file |
Managed, command line, environment, local, project, user; arrays
joined, objects merged, scalars from the highest; .agent/
files in place of missing OKLM ones. test_settings.c
test_precedence, test_fallback |
| 7.2 | Keys | ✅ (M6) | settings.c known; oklm.c
settings_apply |
All the spec's keys checked; model,
baseUrl, outputStyle,
bashTimeout, maxToolOutputChars,
env, sandbox, permissions,
memory used; the rest kept for their milestones. |
| 7.3 | Environment variables | ✅ (M6) | settings.c env_keys; oklm.c |
OKLM_MODEL, OKLM_BASE_URL,
OKLM_API_KEY / OPENAI_API_KEY, timeouts,
output limit, style; no telemetry exists.
MAX_THINKING_TOKENS is not read (the
maxReasoningTokens setting caps the reasoning). |
| 7.4 | /config, /permissions |
✅ (M6) | oklm.c config_command,
permissions_command; settings.c
oklm_settings_edit; permissions.c
oklm_perms_save_rule_to,
oklm_perms_remove_rule |
Line commands rather than full-screen editors (M9). test_settings.c
test_edit |
§8 Project memory
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 8.1 | Memory loading | ✅ (M5b) | memory.c oklm_memory_load |
test_memory.c |
| 8.2 | Scopes and order | ✅ (M5b) | memory.c load_all, read_dir |
AGENTS.md first, OKLM.md,
AGENT.md, CLAUDE.md read too (agent-design.md
decision 2); duplicates once. test_memory.c test_discovery,
test_ancestors |
| 8.3-8.8 | Imports, lazy loading, format, commands, tests | ✅ (M5b) | memory.c expand, oklm_memory_touch,
oklm_memory_render, oklm_memory_refresh,
oklm_memory_append; agent.c touch_memory,
oklm_agent_refresh_memory,
oklm_agent_ask_once; oklm.c /init,
#, /memory, /context,
--no-memory |
Imports outside the project are refused rather than asked (no trust
question yet); re-injection after compaction waits for compaction (M7).
test_memory.c, test_agent.c test_memory |
§9 System prompt
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 9.1 | Identity, core rules | ✅ (M5) | prompts/identity.md; prompt.c | test_prompt.c |
| 9.2 | Tool policy | ✅ (M5) | prompts/tools.md, agents.md | test_prompt.c |
| 9.3 | Tool definitions | ✅ | agent.c:468-489 | |
| 9.4 | Output style | ✅ (M5) | prompt.c oklm_prompt_style;
--output-style, /output-style |
default, explanatory, learning, custom files. test_prompt.c
test_styles |
| 9.5 | Environment | ✅ (M5) | prompts/environment.md; prompt.c put_environment |
Directory, git or not, platform, OS version, date, model. |
| 9.6, 9.7 | Git snapshot, memory | ✅ (M5b, G1) | git.c oklm_git_snapshot; memory.c
oklm_memory_load |
Both in the prompt (rows 152, 489). test_git.c, test_prompt.c
test_full |
| 9.8 | Replace or append the prompt | ✅ (M5) | --system / --system-prompt,
--append-system-prompt |
|
| 9 | Skills list, plan notice | ✅ | prompt.c (skills); agent.c remind (plan mode, as a
reminder) |
|
| 9 | Template files, snapshot test | ✅ (M5) | src/harness/prompts/*.md; prompt.c | Template files, checked by a snapshot test
(OKLM_UPDATE_SNAPSHOTS=1), as rows 160 to 164.
test_prompt.c test_full |
§10 Context
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 10 | Token accounting, /context |
✅ (M7) | compact.c count_text, msg_tokens,
agent_context_measured, oklm_agent_context;
oklm.c context_command |
Per message, system, memory, tools; scaled to the model's count of
the last prompt. test_compact.c test_accounting |
| 10 | Compaction, micro-compaction, warning | ✅ (M7) | compact.c agent_context_check,
micro_compact, agent_compact_now,
rolling_summary; prompts/compact.md; oklm.c
/compact, context_warning,
agent_event |
Summary by the agent's model (the small model comes with §2.5); the
PreCompact hook with §15; a warning line after the turn until the status
bar (M9). test_compact.c test_manual,
test_rolling, test_long_session |
| 10 | /clear |
✅ (M7) | oklm.c /clear, /reset |
§11 Sessions
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 11 | Transcripts | ✅ (M8) | session.c put_line, agent_session_sync,
load; agent.c (sync points) |
.oklm/sessions/<id>.jsonl (the project's, per the
decisions); flushed and synced per line, a line cut short skipped.
test_session.c test_round_trip,
test_torn_line, test_killed |
| 11 | Continue, resume, fork | ✅ (M8) | session.c oklm_session_restore, branch,
answer_dangling; oklm.c --resume,
--fork-session, pick_session |
Titles from the first request (the small model comes with §2.5);
-c stays the context's length. test_session.c
test_dangling_call, test_clear_fork |
| 11 | Checkpoints, rewind | ✅ (M8) | session.c oklm_session_checkpoint,
oklm_session_rewind; tools.c (Write,
edit_store); oklm.c /rewind, Esc Esc |
Commands' effects not tracked, said in the question. test_session.c
test_rewind |
| 11 | Cleanup | ✅ (M8) | session.c oklm_session_cleanup; jobs.c:50, 400-418 |
cleanupPeriodDays (0: no transcripts); the jobs keep
their own 30 days. test_session.c test_list_cleanup |
| 11 | Export | ✅ (M8) | session.c oklm_session_markdown; oklm.c
/export |
File, clipboard program, or conversation-<id>.md.
test_session.c test_markdown |
§12 Sub-agents
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 12 | Task tool | ✅ (M12) | agent.c agent_tool_json, run_subagent |
Agent (Task read as it):
description, prompt,
subagent_type, model (accepted, not acted on),
run_in_background. |
| 12 | Own context, final message only | ✅ | agent.c:2363-2470 | The foreground one shares the KV cache. test_agent.c
test_subagent |
| 12 | Own prompt, fewer tools | ✅ (M12) | agent.c agent_tools, tool_allowed,
subagent_params |
The type's instructions after the sub-agent prompt; its tools offered and enforced. test_subagents.c |
| 12 | Definitions, built-in types | ✅ (M12) | agents.c oklm_agent_defs_load; prompt.c (types
listed) |
general-purpose, Explore, Plan; .oklm/agents/, the
user's. test_subagents.c test_defs,
test_types |
| 12 | Background, parent told | ✅ | agent.c:1945-2095 | test_agent.c test_background,
test_background_limits |
| 12 | Parallel foreground calls, SendMessage, worktrees | ✅ / ❌ (M12) | agent.c agent_group, run_agents_parallel,
run_send_message, keep_agent |
Two to eight at once on their own contexts (or, through a backend,
on copies of it: oklm_agent_backend.clone, a connection
each with --url); SendMessage for the sixteen last;
worktrees with the git spec (G9). test_subagents.c
test_parallel_explore |
| 12 | Depth 1, no questions in background | ✅ (M12) | agent.c max_depth |
agents.maxDepth. test_subagents.c
test_depth |
| 12 | /agents, SubagentStop |
✅ (M12, M11) | oklm.c c_agents; agent.c stop_hooks |
Creation written by the model. |
| 12 | Read-only agents in plan mode | ✅ (M12) | agent.c def_reads_only,
subagent_decide |
Beyond the spec: Explore and Plan run in plan mode. test_subagents.c
test_plan_mode |
§13 Skills
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 13.1 | Skills exist | ✅ | skills.c; agent-tools.md | Same SKILL.md format; skills and commands one format (commands spec §1.7). |
| 13.2 | Front matter | ✅ (M13) | skills.c skill_parse; util.c fm_parse |
Every key of the spec, context/agent too;
YAML blocks, lists, quotes. test_skills.c test_yaml |
| 13.3 | Places, precedence | ✅ (M13) | skills.c skill_dirs |
.oklm/skills, .agent/skills, the user's,
built-in; plugins with §17. test_skills.c
test_discovery |
| 13.3 | Validation, warnings, reload | ✅ (M13) | skills.c skill_parse,
oklm_tool_ctx_skills_changed; oklm.c
repl_submit |
Errors leave a skill out, warnings told at start and in
/skills (and in /doctor, C9). test_skills.c
test_validation, test_reload |
| 13.4 | Three levels, a budget | ✅ (M13) | prompt.c oklm_prompt_skills_listed |
skills.listBudget (2000 tokens); past it, ToolSearch.
test_skills.c test_prompt_budget |
| 13.5 | Model and user invocation, allowed tools, compaction, sub-agents | ✅ (M13) | permissions.c OKLM_SRC_SKILL; agent.c
track_skill, preload_skills; compact.c |
Allowed until the request ends; the skills loaded named after a
summary; skills: preloaded. test_skills.c
test_allowed_scope, test_compaction_note,
test_subagent_skills |
| 13.6 | /skills, skill-creator,
skills validate |
✅ (M13) | oklm.c c_skills, agent_skills_cli;
skills.c builtin_skills |
The list is text (the commands spec's toggling panel waits for C9). |
| 13.7 | Trust, scripts through Bash | ✅ | oklm.c trust_question |
Asked before a folder's files are read; -p runs without
asking, as the other agents do. |
| 13.8, 13.9 | Tests, E2E | ✅ (M13) | test_skills.c; tools/check_skills_e2e.sh | Qwen3-4B loads the zorblax skill and runs its script; twenty skills under the budget. |
§14 Slash commands
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 14.1 | Built-ins | ✅ (M10, C1 to C10) | oklm.c repl_defs; commands.c |
One registry of about forty commands with aliases; see the Commands section. test_commands.c |
| 14.2 | Custom commands | ✅ (C3) | tools.c scan_commands; commands.c
oklm_cmds_expand |
.oklm/commands/*.md with front matter,
$ARGUMENTS, ! and @ (row 562); a
command's model and context: fork are read but
not acted on. test_commands.c test_expand,
test_precedence |
§15 Hooks
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 15 | Events | ✅ (M11) | tools.c oklm_tool_run; agent.c
oklm_agent_send, stop_hooks; compact.c; oklm.c
session_hooks, view_notify |
All nine. test_hooks.c |
| 15 | Settings, matchers | ✅ (M11) | hooks.c oklm_hooks_new,
oklm_hook_matches |
Glob patterns with *, | alternation, and
full regular expressions with the re: prefix
(oklm_regex). |
| 15 | Input, exit codes, JSON answers | ✅ (M11) | hooks.c run_one, fold_json |
suppressOutput read, nothing to suppress (no verbose
output of hooks yet). |
| 15 | At once, each once, timeouts | ✅ (M11) | hooks.c oklm_hooks_run |
|
| 15 | /hooks, change warning |
✅ (M11) | oklm.c c_hooks |
The session keeps its hooks until /hooks reload. |
§16 MCP
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 16.1 | JSON-RPC, MCP | ✅ (M15) | jsonrpc.c; mcp.c | Hand-written (no C SDK); protocol 2025-06-18. |
| 16.2 | Scopes, format, variables, CLI, trust | ✅ (M15) | oklm.c mcp_setup, mcp_accept,
agent_mcp_cli; mcp.c oklm_mcp_add_servers,
oklm_mcp_expand |
Local, project, user settings and .mcp.json,
--mcp-config, --strict-mcp-config; managed
allow and deny lists; reset-project-choices not done.
tools/check_mcp.sh |
| 16.3 | stdio, lifecycle, parallel start, reconnect, list_changed | ✅ (M15) | mcp.c server_spawn, server_handshake,
oklm_mcp_poll |
test_mcp.c test_server |
| 16.3 | Streamable HTTP | ✅ (M15) | mcp.c http_rpc; client.c
oklm_client_set_headers,
oklm_client_header |
JSON and event answers, session id, headers, timeouts; no GET
stream, no session re-opened on 404. test_mcp.c
test_http |
| 16.3 | Legacy SSE | ✅ (M15) | mcp.c sse_reader, sse_event,
sse_rpc; client.c oklm_client_stream_get |
The server's requests on the stream are not answered back.
test_mcp.c test_sse |
| 16.4 | Tools: names, pipeline, results, cap, deferral | ✅ (M15) | mcp.c list_tools, result_text,
oklm_mcp_sync_tools; permissions.c
tool_matches; agent.c in_list |
A stdio call interrupted sends notifications/cancelled;
HTTP calls wait for their limit. test_mcp.c, tools/check_mcp.sh |
| 16.5 | Resources | ✅ (M15) | mcp.c run_ref, oklm_mcp_read_resource;
oklm.c mention_files |
ListMcpResources, ReadMcpResource, @server:uri
mentions; no @ completion of them, no subscriptions.
tools/check_mcp.sh |
| 16.6 | Prompts as commands | ✅ (M15) | mcp.c list_prompts, oklm_mcp_prompt;
oklm.c mcp_prompt_line |
Arguments in order; not in the / menu. test_mcp.c,
tools/check_mcp.sh |
| 16.7 | OAuth | ✅ (M15) | oauth.c oklm_oauth_login,
oklm_oauth_token; mcp.c auth_lines,
srv_request, oklm_mcp_login; oklm.c
c_mcp, agent_mcp_cli |
Discovery (RFC 9728 resource metadata from the 401's header or the
well-known places, RFC 8414 / OpenID metadata, the older default
endpoints), dynamic registration or oauth.clientId, PKCE
S256 with a random state, the browser and a callback on 127.0.0.1, the
resource indicator, endpoints on https unless local; tokens
in mcp-credentials.json beside the user's settings (0600,
per server name and URL), refreshed when expired or after a 401 (the
request sent again once); a 401 without a token: the state "needs auth".
No system keychain (a dependency, to decide), no encryption of the file.
test_mcp.c test_oauth (a fake protected server and
authorization server, the browser simulated) |
| 16.8 | Roots, elicitation, sampling | 🟡 (M15) | mcp.c incoming |
Roots answered, elicitation declined, sampling not offered. |
| 16.9 | /mcp |
✅ (M15) | oklm.c c_mcp |
"needs auth", /mcp login NAME,
/mcp logout NAME (the clear-auth option); `oklm agent mcp
login |
| 16.10 | mcp serve |
❌ | Optional: no oklm agent mcp serve exposing the agent's
tools. |
|
| 16.12 | Fake server tests; official server E2E | ✅ (M15) | test_mcp.c (--serve); tools/check_mcp.sh;
tools/check_mcp_official.sh |
@modelcontextprotocol/server-filesystem 2.1.0 through
npx: listed and read under a fixture, and by Qwen3-4B on its own when
its tools are shown. Its 14 tools (about 3300 tokens) fit the default
mcp.deferAboveTokens, a quarter of the context window;
deferred, Qwen3-4B read the file with Read in 9 runs of 9 and never
searched for them. |
§17, §18 Plugins, output styles
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 17 | Plugins: manifest, commands, skills, agents, hooks, MCP servers,
scopes, enabledPlugins |
✅ (M19) | plugins.c; skills.c (NAME: namespace); agents.c
oklm_agent_defs_add_dir; hooks.c
oklm_hooks_add_json; oklm.c session_plugins,
mcp_setup |
.oklm-plugin/plugin.json or
.claude-plugin/plugin.json;
${OKLM_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT}
in hook commands. tools/check_plugins.sh |
| 17 | Install, remove, enable, disable, marketplaces,
/plugin |
✅ (M19) | oklm.c agent_plugin_cli, c_plugin |
From a directory, a git repository or NAME@MARKETPLACE;
no signature check, no update command; a change takes effect in the next
session. |
| 18 | Output styles | ✅ (M5) | prompt.c; oklm.c /output-style |
§19 Terminal UI
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 19 | Markdown while streaming | ✅ (M9) | term_md.c oklm_md_feed; oklm.c
view_split |
Tables aligned at their end, code colored by language, escape sequences dropped; a pipe gets the raw text. test_term.c |
| 19 | Compact tool calls | ✅ (M9) | term_ui.c oklm_term_tool; oklm.c
agent_tool, /verbose |
● Tool(subject) / ⎿ summary, diffs, task
list; Ctrl-R or /verbose whole. test_term.c
test_tools |
| 19 | Folded reasoning | ✅ | view_split, view_toggle |
Ctrl-O folds and unfolds in place. test_think.c; manual |
| 19 | Spinner | ✅ (M9) | term_ui.c oklm_term_spinner; oklm.c
view_spin_main |
Verb or the task in progress, time, tokens, how to interrupt;
reasoning's words. test_term.c test_spinner |
| 19 | Task list panel | ✅ (M9) | term_ui.c (TodoWrite); tui.c oklm_tui_todos,
draw_tasks, oklm_tui_tasks_toggle; oklm.c
tui_refresh_tasks, view_tasks |
Shown with ☐ ◼ ☒ at each change, its task in the spinner; in
/tui a strip kept on screen above the transcript (16 rows
or more, Ctrl-T hides or shows it), following each TodoWrite, the task
in progress by its activeForm, completed beyond three
folded, scrolled to keep the task in progress in sight; Ctrl-T prints it
in the line-mode UI. test_tui.c test_tasks_strip,
test_tasks_scroll, test_tasks_live;
check_commands.sh |
| 19 | Input editor | ✅ (M9) | line_edit.c; oklm.c view_draw_line,
view_complete, bang_command,
mention_files |
Several lines, Ctrl-R, bracketed pastes and placeholders,
@ completed and read, !, #; the
/ menu is M10's; no vim mode, no images pasted.
test_line_edit.c |
| 19 | Keys | ✅ (M9, P3) | oklm.c view_key, view_edit_line,
background_now |
Esc, Esc Esc, Shift+Tab, Ctrl-C, Ctrl-D, Ctrl-L, Ctrl-O, Ctrl-R,
Ctrl-T (the task list) and Ctrl-B (the running command to the
background); vim mode is left (roadmap Later). test_line_edit.c
test_keys_view |
| 19 | Status line, notifications, themes | ✅ (M9) | term_ui.c oklm_status_*, oklm_git_branch;
term_md.c themes; oklm.c status_line,
view_notify |
statusLine.command with the session JSON, else built
in; bell, OSC 9 or a desktop notification (a PowerShell toast on
Windows, untested there); dark, light, colorblind,
NO_COLOR. test_term.c, test_hooks.c
test_toast_command |
| 19 | Welcome, trust question | ✅ (M9) | oklm.c welcome, trust_question; term_ui.c
oklm_trust_* |
Asked on the first interactive run in a folder, kept in
trusted-folders.json. test_term.c
test_trust |
§20 Headless use
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 20 | -p |
✅ | cmd_agent |
|
| 20 | Output and input formats | ✅ (M14) | headless.c; oklm.c headless_main |
text, json, stream-json; stream-json input for several requests. test_headless.c |
| 20 | Flags | ✅ (M14) | cmd_agent |
The spec's names read as OKLM's (--model,
--allowedTools, --disallowedTools,
--permission-mode, --system-prompt,
--add-dir, --verbose);
--mcp-config and --strict-mcp-config with
M15. |
| 20 | Exit codes | ✅ (M14) | oklm_headless_result |
0, 1 for a request in error (the turn limit included), 2 for usage. |
| 20 | Standard input into -p |
✅ (M14) | oklm.c read_piped_stdin |
Piped text first, -p - alone; a silent pipe left open
does not hang. |
| 20 | Library API | ✅ (M14) | tools.h oklm_tool_ctx_add_tool; hooks.h
oklm_hooks_add_callback |
Custom tools, hooks as functions, the ask callback,
cancel, events; a callback API, not an iterator (C).
test_headless.c |
§21 to §23 Git, background work, diagnostics
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 21 | Git workflows | ✅ (G1 to G11) | git.c; prompts/git.md; skills.c commit,
pr, bisect, git-history |
See the Git section; what is left is there (rows 491 to 520). |
| 22 | Background commands and agents | ✅ | jobs.c; agent.c:1945-2095; adr/0012-jobs.md | test_jobs.c |
| 22 | Monitor, loops | ✅ (P2, P5, C8) | tools.c t_monitor, t_schedule_wakeup;
events.c; oklm.c c_loop, c_schedule |
Monitor, ScheduleWakeup, /loop, /schedule.
test_events.c |
| 23 | Tokens and time, /cost, /status |
✅ (C9) | oklm.c c_usage, c_status |
tools/check_commands.sh |
| 23 | Debug log | ✅ (M17) | telemetry.c oklm_telemetry_set_debug,
oklm_telemetry_event; oklm.c debug_log_on,
debug_command |
--debug, OKLM_DEBUG, /debug;
$XDG_STATE_HOME/oklm/logs. test_telemetry.c;
tools/check_diagnostics.sh |
| 23 | Price table, cost | ✅ (M17) | telemetry.c oklm_prices_lookup; headless.c
oklm_headless_set_prices; oklm.c c_usage |
/usage, total_cost_usd.
tools/check_diagnostics.sh |
| 23 | OpenTelemetry export | ✅ (M17) | telemetry.c oklm_telemetry_flush,
export_main |
OTLP/HTTP JSON logs and metrics, off unless asked; no gRPC, no
traces. test_telemetry.c test_export;
tools/check_diagnostics.sh |
| 23 | /bug, /feedback |
✅ (M17) | oklm.c bug_bundle |
A local bundle, secrets masked; no drafts queue (no feedback tool). tools/check_diagnostics.sh |
| 23 | Audit log and viewer | ✅ | audit.c; cmd_audit |
test_permissions.c test_audit |
| 23 | /doctor |
✅ (C9) | oklm.c c_doctor, doctor_check |
Fixes: keys of the wrong type, orphans. tools/check_commands.sh |
§24 Security checklist
| Item | Status | Evidence, notes |
|---|---|---|
| Untrusted content policy | ✅ (M4) | prompts/tools.md: tool results, files and web pages are data, not instructions (row 136). |
| Paths and symbolic links | ✅ | util.c:296-376; test_permissions.c test_path_rules |
| Compound commands, fuzzed | ✅ | Unit tests and fuzz/fuzz_shsplit.c (with fuzz_toolcalls.c). |
| Secrets masked | 🟢 | telemetry.c oklm_mask_secrets /
oklm_scan_secrets for the debug log, /bug and
telemetry, and a tool's output before the model and the transcript
(agent.c clip); a tool's output is scanned in
oklm_tool_run, found secrets registered with the audit log
(oklm_audit_scan, masked in recorded arguments) and the
user told. |
| Trust before project settings, hooks, MCP | ✅ (M9) | oklm.c trust_question before any of the folder's files
is read (its settings, the worktree --worktree makes with
its WorktreeCreate hook), and an approval per MCP server;
-p skips it by design (row 213). tools/check_commands.sh
(refused on a terminal: the hook does not run) |
| WebFetch per domain | ✅ | WebFetch domain rules (M16), shared with the sandbox's proxy (M18). |
| Managed lockdown | 🟡 | permissions.c disableBypassPermissionsMode,
allowManagedPermissionRulesOnly and the managed settings
scope; no managed-only switch for hooks, MCP servers or plugins (left
out on purpose, roadmap "Next"). |
§25 Tests
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 25 | Unit tests | ✅ | tests/harness/ | The tool-call parser fuzzed (fuzz_toolcalls) and the command splitter (fuzz_shsplit, 7.4 million inputs: parts non-empty, the same on a second split, an unparsable line kept whole). |
| 25 | Mock-model integration | ✅ (M1, M20) | agent_mock.c; oklm agent --mock |
Fixture-driven mock backend, and the evals of tests/evals.
test_agent.c test_mock |
| 25 | Snapshots, end to end, evaluation | ✅ (M20) | test_prompt.c (the system prompt's snapshot), test_term.c (frames);
tests/evals/; tools/eval_agent.sh, make eval |
Seventeen tasks in temporary directories and repositories (the git
evals 05, 11 to 15; the process evals 10, 16, 17), each with a checker;
the report gives the pass rate, turns, tokens and seconds a task (agent-loop.md). Qwen3-8B, the
default, passes 13 of 17 (2026-11-07; Qwen3-4B 7 of the first 12). CI
(.gitea/workflows/ci.yml) runs the unit and mock tests with gcc and
clang, under both sanitizers; the evals stay behind
make eval, since a run needs the model and a GPU. |
§26 Milestones against what exists
| M | State |
|---|---|
| M0 | Done: this file and agent-design.md. |
| M1 | ✅ Backends (in-process, HTTP, mock fixtures), stream events with usage and stop reasons, cancel from Esc / Ctrl-C (generation, commands, pending calls); reasoning kept out of the history sent back. |
| M2 | ✅ Lenient parser (fuzzed), schema validation, fake results dropped, message metadata, a result per call, reminders, parallel reads, loop detection, steering, Read / Glob / Grep in full; "where is X defined?" answered by Qwen3-4B. |
| M3 | ✅ Write / Edit with read-before-write checks, line ends kept, snippets; MultiEdit; a persistent shell, head and tail output, escape sequences stripped, pagers and editors neutralized; "create fizzbuzz, make test pass" done by Qwen3-4B. |
| M4 | ✅ Modes with Shift+Tab, rules, compound commands, plan mode, the
dangerous-pattern list, questions with diffs, rules saved, feedback,
/add-dir, the untrusted-content policy; later follow-ups
now done (roadmap "Done"): the command classifier, secrets found in
output, broader "always" prefix rules (OKLM_ANSWER_ALWAYS_PREFIX,
Bash(cmd:*)), read-only pipeline filters,
/add-dir --remember, memory imports outside the project
behind the trust question (mem_trust, oklm_trust_add), and
the bypass mode without the sandbox behind a flag and a louder banner
(--dangerously-skip-permissions,
oklm_perms_allow_unsafe_bypass, ADR-0010). |
| M5 | ✅ The prompt assembled from template files in a stable order
(snapshot test), environment, output styles, appended or replaced text;
TodoWrite with activeForm and one task in progress;
reminders for the mode, changed files and a stale task list. The git
snapshot waits for G1, the memory files for M5b. |
| M5b | ✅ The memory files by scope (managed, user, project from the
repository's root, local, sub-directories lazily), imports with caps and
warnings, the prompt's section, changes reloaded, /init,
#, /memory, /context, the
memory settings; "always use pnpm" followed by Qwen3-4B.
Left: the trust question for imports outside the project,
/doctor. Re-injection after compaction came with M7. |
| M6 | ✅ Settings merged by priority with their sources (merge-precedence
tests), the spec's keys checked, environment variables, edits that keep
a file's other content, /config and
/permissions. |
| M7 | ✅ Token accounting per part scaled to the model's count,
/context with a bar, old tool results cleared, summaries by
the model (after the conversation, or from a transcript in parts), the
user's messages verbatim, task list, edited files and instructions kept,
/compact [focus], /clear, the 70% warning,
autoCompact / compactThreshold /
contextWindow; a 440-turn synthetic session within a small
window without losing its task. |
| M8 | ✅ Transcripts as a tree of messages written as they go,
--resume / --fork-session, the files kept
before each change and /rewind (Esc Esc) of the
conversation, the files or both, /export,
cleanupPeriodDays; a process killed mid-turn resumed and
its task finished, files restored by rewind. |
| M9 | ✅ Markdown rendered as it streams, tool calls compactly with diffs,
the spinner, the status line (built in or a command), several-line input
with Ctrl-R, pastes, @ and !, notifications,
themes and NO_COLOR, the welcome box and the trust
question; frames tested, checked by hand on a pseudo-terminal and with
Qwen3-4B. |
| M10 | ✅ Slash commands, the commands spec's C1–C3: one registry
(built-ins, skills, command files), the parser (stacking, escapes,
namespaces, unknown names with suggestions), precedence with shadowed
names kept, queued or immediate while the agent works,
-p "/cmd", the / menu with argument
completion, a picker reused by four commands, prompt commands expanded
(!, @, placeholders) under their allowed
tools, skillOverrides, /skills,
/reload-skills. |
| M11 | ✅ Hooks: the nine events, matchers, the event on standard input,
exit codes and JSON answers (block, approve, new arguments, context,
stop), run at once and once each with timeouts, /hooks with
the change warning; a hook refusing edits of *.lock and a
formatter after writes. |
| M12 | ✅ Sub-agents: types (general-purpose, Explore, Plan, the project's
and the user's definitions), their tools and instructions, several at
once on their own contexts, SendMessage, a configurable depth,
/agents; two Explore agents return summaries while the
caller's context keeps only them. Worktrees with the git spec. |
| M13 | ✅ Skills in full: every header key in the YAML skills use, checked
(errors leave a skill out, warnings told), the project's,
.agent's, the user's and built-in skills (skill-creator), a
prompt budget with the rest found by ToolSearch,
{skill, args}, allowed tools until the request ends, forked
skills as sub-agents, preloaded skills, the loaded ones named after a
summary, changes on disk noticed, /skills NAME,
oklm agent skills validate; deferred tools loaded by
ToolSearch. Qwen3-4B loads the zorblax skill by itself and runs its
script. |
| M14 | ✅ Headless: `--output-format text |
| M15 | ✅ MCP: scopes, trust, stdio, Streamable HTTP and legacy SSE, tools,
resources, prompts, OAuth, /mcp,
oklm agent mcp, the official filesystem server end to
end. |
| M16 | ✅ WebFetch, WebSearch through SearXNG, NotebookEdit, AskUserQuestion. |
| M17 | ✅ The debug log, a price table and costs, the OpenTelemetry export,
/bug and /feedback. |
| M18 | ✅ Linux, 🟡 Windows. |
| M19 | ✅ Plugins: commands, skills, agents, hooks and MCP servers bundled, installed from a directory, a repository or a marketplace. |
| M20 | ✅ The eval harness (make eval, tests/evals/, its
report) and user-guide.md, extending.md. |
§27 Local models
| Item | Status | Notes |
|---|---|---|
| Small tool set | 🟡 | 27 built-in tools, ten deferred by default (ProcessList, PowerShell, LSP, ScheduleWakeup, Service, NotebookEdit, WebSearch, AskUserQuestion, EnterWorktree, ExitWorktree); more than the spec's seven stay loaded. |
| Worked examples in the prompt | ✅ (M2) | agent.c default system prompt: finding a definition with Grep |
| Instructional errors | ✅ | tools.c: schema errors with the schema, "No matches" with a hint, a missing file's directory listed, a headless refusal naming the parts no rule covers, a TodoWrite with several tasks in progress kept with the first. |
| Lower temperature for calls | ✅ | Greedy by default; grammar on calls. |
| Write fallback measured, lower compaction threshold | 🟡 | compactThreshold can be set but is not lowered for
small models; the evals do not measure Edit against a whole-file
Write. |
Tests already covering what is present
test_permissions.c (compound commands, paths, precedence, modes,
rules, settings, audit), test_tools.c (files, search, Bash, questions,
plan mode, skills), test_jobs.c (journal, restart, harness death,
retention, tools), test_sandbox.c, test_think.c, test_line_edit.c,
test_agent.c (calls, order, job notes, sub-agents, background, refusals,
turn limit). Not covered by a test: the prefix cache reuse,
-p, the terminal view, and the
oklm permissions / oklm audit commands.
Processes & Services
Audit of process_spec.md (its P0),
2026-11-02, the same legend. The job manager already does the
core of §2.2 and §2.5 (src/harness/jobs.c, adr/0012-jobs.md): jobs run in a process
group or a kill-on-close Job Object, write a log and a journal with
their start times, are stopped at close and die with the harness, and
are re-attached or marked interrupted when the same session is opened
again. What follows §2.5 (readiness, ports, events, Monitor, language
servers, MCP, hooks, services, integrations) is missing or partial.
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 0 | Nothing outlives the session by accident | ✅ (P4) | jobs.c oklm_jobs_close, find_orphans |
Detached and kept-alive jobs outlive it on purpose; what a crash leaves is reaped at the next start. |
| 0 | Event-driven waiting | ✅ (P2, P5) | probe.c; events.c | WaitFor, Monitor, events. |
| 0 | Logs on disk | ✅ | jobs.c:1457-1463, 1041-1046; tools.c:2212 | |
| 0 | Integrations as skills | ✅ | skills.c searchable_skills (docker, dev-server,
database, playwright, kubernetes, android, vms, cloud, tunnels,
git-history) |
Built-in integration skills, found by the skill search; no iOS skill (row 427). tools/check_integrations.sh |
| 2.1 | Ids, kinds, labels | ✅ (P1) | jobs.h oklm_job_spec, oklm_job_kind |
Integer ids shown as job 3 (decided in
process-design.md); six kinds; labels. test_jobs.c
test_spec |
| 2.1 | Command, directory, environment | ✅ (P1) | jobs.c spawn |
Its own directory; markers and neutralized pagers in the environment. |
| 2.1 | Process and group ids, Job Object | ✅ | jobs.c:77-114, 1121 | |
| 2.1 | Owner, status, times, exit and signal | ✅ (P1) | jobs.c note_end, oklm_jobs_info |
Owner, start and end times, signal in the info and the journal;
readiness is a wait (WaitFor), not a state. |
| 2.1 | Ports, readiness, restart, ring, readers | ✅ (P1, P2) | jobs.c oklm_jobs_read, note_end;
probe.c |
Readers kept by the manager; restart on failure with backoff; ports
found per job; no ring buffer (the log is read where the reader is).
test_jobs.c test_readers,
test_restart_policy |
| 2.1 | Resources | ✅ | sandbox.c (RLIMIT_CPU, AS, FSIZE, NOFILE, NPROC); process.c (Job
Object limits on Windows); jobs.c limiter_for,
oklm_jobs_limits_available; services.c
resources |
Shared limits, and per job a memory and CPU limit in a cgroup v2 of
its own on Linux (systemd's user manager; memLimit,
cpuLimit of a service); on Windows in the job's Job Object
(job memory, a hard CPU rate; job_cpu_rate,
job_memory_limit), cross-compiled, untested on Windows.
test_jobs.c test_limits,
test_job_object_limits, test_services.c
test_resources |
| 2.2 | Own group or session; Job Object; standard input closed | ✅ | jobs.c:1031-1198; process.c:306-361, 478-486 | Detached Windows jobs break away from the Job Object (jobs.c:1155). |
| 2.2 | Output merged with timestamps | ⚠️ | jobs.c spawn |
Merged; no timestamps on purpose: the log stays what the program wrote and offsets stay bytes (the journal has the times). |
| 2.2 | OKLM_SESSION_ID, OKLM_PROCESS_ID |
✅ (P1) | jobs.c spawn |
With the git specification's editor and pager variables; inherited
descriptors closed. test_jobs.c test_spec |
| 2.2 | Concurrency limit | ✅ (P1) | jobs.c oklm_jobs_start_spec,
oklm_jobs_running |
20 (processes.maxConcurrent); the error lists what
runs. |
| 2.3 | ANSI stripped, rotation | ✅ (P1) | jobs.c oklm_jobs_read, rotate |
Copy and truncate past 32 MiB; rotated journalled.
test_jobs.c test_rotation |
| 2.3 | Reading with reader, filter, tail, cap | ✅ (P1, P3) | jobs.c oklm_jobs_read; tools.c
t_process_output |
The model's reader, the user's in /tasks output. |
| 2.3 | Retention | ✅ (P1) | jobs.c retire_old |
processes.logRetentionDays. |
| 2.4 | Readiness probes | ✅ (P2) | probe.c | port, http, log, command, delay, all, any; timeout, fail fast, last 30 lines. test_probe.c |
| 2.5 | Stop: TERM, grace, KILL | ✅ (P1) | jobs.c oklm_jobs_stop |
5 s, a setting and per job, the group confirmed gone; on Windows
CTRL_BREAK to the group, the grace, then termination (verified on a real
Windows machine is "Blocked" in the roadmap). test_jobs.c
test_stopping |
| 2.5 | Stop hooks per integration | ✅ (P1) | jobs.c oklm_jobs_stop |
A stop command per job; the integrations give theirs (P9). |
| 2.5 | Session end | ✅ (P1, P4) | jobs.c oklm_jobs_close, oklm_jobs_keep,
keep_mark; sandbox.c sb_pass_term; oklm.c
leave_ok |
Reverse order, kept-alive jobs left running and said; the exit
question on the terminal with a "keep" answer; a kept job is marked so
the TERM of its harness's end (PR_SET_PDEATHSIG) does not
stop it (keep_alive, processes.keepOnExit and
--keep-services jobs too, which that TERM used to end).
test_jobs.c test_keep_at_exit |
| 2.5 | Registry with process start times | ✅ | jobs.c:222-327 | .oklm/jobs/<session>.jsonl. |
| 2.5 | Orphan reaper | ✅ (P4) | jobs.c find_orphans, group_lives,
oklm_jobs_reap |
Every other session's journal at open; groups checked on Linux
(leader dead or alive; a leader id held by a process of another start
time is a reused id, no orphan), the leader elsewhere; asked at start or
processes.autoReapOrphans; jobs kept at exit listed as
such. test_process.c test_orphans, test_jobs.c
test_reused_pid, test_keep_at_exit |
| 2.5 | Docker label | ✅ | oklm.c containers_cleanup; skills.c docker |
Containers labelled oklm.session=$OKLM_SESSION_ID (or
compose project oklm-ID) are stopped at the session's end,
volumes kept; the label is the skill's convention, not added to docker
commands by the harness. tools/check_integrations.sh |
| 2.6 | Ports: free check, detection, loopback | ✅ (P2) / 🟡 | probe.c oklm_port_holder, oklm_job_ports,
port_rows_holder |
The holder named on Linux; on Windows from
GetExtendedTcpTable (cross-compiled, untested on Windows)
and on macOS from libproc (never compiled); elsewhere only whether a
port answers. A held port named before waiting. A job's ports on Linux
only. test_probe.c test_ports,
test_port_rows |
| 2.7 | Re-attach on resume; died while away shown with its code | ✅ | oklm.c --resume; jobs.c alive |
A resumed session reopens its jobs: running ones re-attach, those
that died show their code. test_jobs.c test_restart |
| 3 | Bash background | ✅ (P3) | tools.c bash_job |
Id and log path at once; detach declared. |
| 3 | Backgrounding on timeout | ✅ (P3) | process.c proc_run_ex; jobs.c
oklm_jobs_adopt |
Decided; sleep stopped; POSIX (Windows stops it).
test_process.c test_auto_background |
| 3 | WaitFor | ✅ (P2) | tools.c t_wait_for |
Command probes only under an allow rule. test_probe.c
test_tool |
| 3 | Ctrl+B, PowerShell, ProcessList | ✅ (P3) | oklm.c view_key; tools.c t_powershell,
t_process_list |
PowerShell and ProcessList deferred. test_process.c |
| 3 | Monitor | ✅ (P5) | tools.c t_monitor; events.c |
Bash's rules for its command; its own job or attached (attaching
allowed under a bare Bash deny, refused with Monitor's, the
tool offered accordingly). test_events.c
test_monitor_denied |
| 3 | LSP | ✅ (P6) | tools.c t_lsp; lsp.c |
Deferred. test_lsp.c |
| 3 | Service | ✅ (P8) | tools.c t_service; services.c; oklm.c
c_services |
The Service tool, services.json with dependsOn and readiness,
processes.autostartServices, /services.
test_services.c test_load, test_run;
tools/check_services.sh |
| 3 | ProcessOutput, ProcessStop | ✅ (P3) | tools.c t_process_output,
t_process_stop |
BashOutput / KillShell read as them; JobOutput / JobKill kept, not offered. |
| 4.1 | Monitor | ✅ (P5) | events.c oklm_events_monitor |
filter, batch, rate, stop line, attach. |
| 4.2 | Events: job ended, background agent finished | ✅ | agent.c tell_jobs, tell_agents,
tell_events |
At each turn's start, to the user's agent. |
| 4.2 | Other sources, coalescing, idle wake, wake cap | ✅ (P5) / 🟡 | events.c; oklm.c wake_wanted, wake_agent,
headless_events |
Monitors and jobs; readiness, LSP and MCP events with their milestones. tools/check_events.sh |
| 4.3 | Scheduled wakeups | ✅ (C8) | events.c oklm_events_schedule; tools.c
t_schedule_wakeup |
Not counted against the hour's cap; dropped at session end (not
persisted). test_events.c test_wakeups,
tools/check_events.sh |
| 5 | Language servers | ✅ (P6) | lsp.c; jsonrpc.c; jobs.c piped jobs | Lazy start, sync, diagnostics after edits by version, the LSP tool; POSIX (piped jobs). test_lsp.c |
| 6 | MCP server processes | ✅ (M15) | mcp.c server_spawn |
Jobs of kind mcp (piped, outside the sandbox); a crash reconnects with a backoff; no ProcessExit hook yet (P7). |
| 7 | Background sub-agents listed as processes | 🟡 (P7) | agent.c oklm_agent_background_list; oklm.c
c_tasks |
/tasks lists them (kind agent, state, time); not in
ProcessList; no token use or last tool (reading a running sub-agent's
messages would race). test_agent.c test_background |
| 7 | Processes owned by a sub-agent | ✅ | agent.c start_background, end_owned_jobs;
jobs.c oklm_jobs_end_owner; process.c
proc_fork |
A background sub-agent owns its jobs (agent N, nested
agent N/agent M): stopped when it ends, Bash
keep_alive hands one to the session, its report lists both.
Every child is forked by one thread that lives as long as the harness,
so PR_SET_PDEATHSIG (per thread) follows the process.
test_jobs.c test_owner, test_thread_end;
test_agent.c test_background_jobs |
| 7 | Concurrency limit, stop at exit | ✅ | agent.c:209-229, 1946-1962 | test_agent.c test_background_limits |
| 8 | Hooks for processes | ✅ (P7) | hooks.h OKLM_HOOK_PROCESS_START,
OKLM_HOOK_PROCESS_EXIT,
OKLM_HOOK_MONITOR_EVENT,
OKLM_HOOK_SERVICE_READY; events.c
oklm_events_take_changes; services.c
oklm_services_take_ready,
oklm_services_ready_fields; oklm.c
process_hooks, monitor_hook_blocks; agent.c
tell_events |
ProcessStart, ProcessExit, MonitorEvent (which can block), and
ServiceReady (a declared service passed its readiness probe, once per
ready spell: name, job id, pid, ports, probe; matched on the name;
listed by /hooks). test_hooks.c
test_expansion, test_services.c test_ready;
tools/check_events.sh |
| 9 | services.json, dependsOn order, readiness, monitors,
/services, /init proposal, trust before
autostart |
✅ (P8) | services.c; tools.c t_service; oklm.c
c_services, c_init |
test_services.c; tools/check_services.sh (the spec's mock-model E2E) |
| 10.1, 10.6-10.8 | Docker / Podman, dev servers, databases, browsers (wave 1) | ✅ (P9) / 🟡 | skills.c docker, dev-server,
database, playwright; permissions.c
builtin_dangers; oklm.c containers_cleanup,
doctor_check; tools.c bash_job (reuse) |
Skills with the recipes, OKLM_SESSION_ID for labels,
the session's containers stopped at its end, image deletion and the
host's network asking, /doctor on a silent daemon, a
running command reused; a real-daemon check (tools/check_docker.sh,
skipped when no daemon answers) passing against Docker 28.5.2
(2026-11-08); not tried against a real database or real browsers
tonight; no SQL danger rules (the skill asks).
tools/check_integrations.sh (a fake docker), test_permissions.c,
test_jobs.c |
| 10.2, 10.3 | Kubernetes context safety, Android device safety, their skills | ✅ (P10) / 🟡 | devices.c oklm_cluster_danger,
oklm_device_danger; tools.c tool_run; skills.c
kubernetes, android |
test_devices.c; tools/check_integrations.sh (a fake kubectl);
tools/check_emulator.sh: the checklist on a real emulator (Android 36.1,
14 checks: detection, start, boot, Monitor on logcat with its lines
told, an activity, a screenshot, the UI tree, input, an APK built and
installed with -r, pm clear, uninstall, adb without -s
refused, emu kill). |
| 10.5, 10.9, 10.10 | VMs, cloud CLIs read-only by default, tunnels saying what they expose | ✅ (P11) / 🟡 | devices.c oklm_cloud_danger,
oklm_tunnel_danger; skills.c vms,
cloud, tunnels |
test_devices.c test_cloud_tunnels; no identity
reminder, no credential redaction, a tunnel's URL not parsed for the
user. |
| 10.4 | iOS Simulator | ❌ | Out of scope (macOS only). | |
| 11 | Resource guardrails, the target in the question,
cloud.readOnly, kubernetes.allowedContexts,
OKLM_DISABLE_BACKGROUND_TASKS, docs/processes.md |
✅ (P12) / 🟡 | tools.c resource_danger, t_bash;
devices.c; docs/processes.md |
A second VM or emulator and a container past
processes.maxContainers ask; per-job memory and CPU limits
in a cgroup (Linux); the evals report in agent-loop.md. test_jobs.c,
tools/check_integrations.sh |
| 11 | Rule syntax, background jobs confined | ✅ | permissions.c:261-326; jobs.c:970-1068 | test_sandbox.c test_jobs |
| 11 | Detach gated by a rule | ✅ | tools.c:1655-1700; permissions.c:98, 291, 1630-1633 | Beyond the spec. test_jobs.c test_tools |
| 11 | Dangerous patterns, target in the question, guardrails | 🟡 | permissions.c builtin_dangers; devices.c
oklm_cluster_danger, oklm_device_danger,
oklm_cloud_danger, oklm_tunnel_danger; tools.c
resource_danger |
The dangerous patterns and guardrails exist, and the question names the Kubernetes context, the adb serial and the tunnel's exposure; not the cloud account or the Docker host. tools/check_integrations.sh |
| 11 | Network exceptions | 🟡 (M18) | oklm.c (sandbox.allowedDomains,
oklm_proxy_start); proxy.c |
Sandboxed commands reach the allowed domains through a filtering proxy; no per-integration exceptions (listening ports, daemon sockets). tools/check_network.sh |
| 12 | Settings and environment variables | 🟡 | oklm.c (processes.maxConcurrent,
defaultGraceMs, logRetentionDays,
logRotateMB, autoBackgroundOnTimeout,
maxContainers, autostartServices,
autoReapOrphans; events.*;
kubernetes.allowedContexts, cloud.readOnly);
tools.c OKLM_DISABLE_BACKGROUND_TASKS |
Most settings reach the jobs; BASH_MAX_OUTPUT sets the
tool-output cap (as OKLM_MAX_TOOL_OUTPUT_CHARS);
processes.keepOnExit leaves the session's running jobs
alive at exit (jobs.c oklm_jobs_options.keep_on_exit,
test_jobs.c test_keep_on_exit).
monitor.defaultBatchMs is the Monitor tool's default batch
window when a call omits batch_ms (tools.c
t_monitor, tool-ctx monitor_batch_ms).
integrations.<name>.enabled is not read (modest
value). |
| 13 | /tasks panel |
✅ (P3) | oklm.c c_tasks, tui_jobs_panel; tui.c
oklm_tui_jobs_key, oklm_tui_jobs_run,
draw_jobs; jobs.c oklm_jobs_restart,
oklm_jobs_keep_one |
The list with agents, stop N, output N,
reap; in /tui an interactive panel kept up to
date (state, run time, kind, label, last line): arrows select, Enter
follows the output in a pager, s stops (ProcessStop),
r restarts a service or a job with a restart policy,
k keeps it running at exit, q closes.
test_tui.c test_jobs_layout, test_jobs_keys;
test_jobs.c test_restart_keep_one; check_commands.sh |
| 13 | Status line counts, Ctrl+B, notifications, exit prompt | ✅ (P3, P4) | oklm.c status_line, view_key,
leave_ok, view_notify,
show_notices; events.c oklm_events_notice,
notice_crash; services.c start_one; agent.c
bg_main |
Counts in the status line (running jobs, failed services, LSP and
MCP servers), Ctrl+B; the user told once (a dimmed line and a
notification, notification in stream-json) of a crashed job
(non-zero exit or signal, not stopped), a failed readiness probe and a
finished background agent, with the label and the reason, the model at
its next turn; the exit question's "keep" answer (jobs left running,
found by the next session with the orphans). test_events.c
test_notices, test_services.c test_ready,
test_agent.c test_background, test_jobs.c
test_keep_at_exit |
| 14 | Headless events, --keep-services, event callback |
🟡 (P5) | oklm.c headless_events, --keep-services;
jobs.c oklm_jobs_options.keep_services |
stream-json gets process_started, process_exited, monitor_event,
process_ready (a service reaching its readiness probe, with its pid,
ports and probe; oklm.c process_hooks,
tools/check_events.sh) and notification (the user's notices; oklm.c
show_notices). --keep-services leaves the
service, LSP and MCP jobs running at exit (test_jobs.c
test_keep_on_exit). Left: cleanup failures in the result,
an event callback in the library. |
| 15 | Tree kill, Linux and Windows | ✅ | jobs.c:1678-1703; process.c:392-413, 528 | A detached Windows job's descendants survive JobKill (jobs.c:1703). |
| 15 | Ports, shell, limits, messages | 🟡 | probe.c oklm_port_holder; tools.c PowerShell;
sandbox.c, process.c, jobs.c limits; hooks.c
oklm_notify_toast_command |
A port's holder named on Linux, Windows and macOS; PowerShell
exists; rlimits and Job Object limits, per-job cgroups v2 on Linux and
per-job Job Object memory and CPU-rate limits on Windows; a Windows
toast for the system notification channel. The Windows
parts are cross-compiled, untested on Windows; the macOS part was never
compiled. |
| 15 | Job tests on Windows | ❌ | test_jobs.c main |
Skipped on Windows. |
| 16 | Kill tree, harness death, re-attach, retention, events mid-turn | ✅ | test_jobs.c, test_tools.c test_bash, test_agent.c
test_job_note |
|
| 16 | Reused process id | ✅ | jobs.c alive (pid and start time),
group_lives |
Reused pids are told apart by their start time, in the session's own
journal and in the orphan finder (which took a group whose leader id was
reused by a later process before); a live process faked under a recorded
pid with another start time (earlier or later) is neither re-attached,
signalled nor an orphan, the real start time is (test_jobs.c
test_reused_pid); a pid that does not exist (test_jobs.c
test_restart, test_retention). |
| 16 | The rest | 🟡 | test_jobs.c; test_probe.c; test_events.c; test_lsp.c; tools/check_services.sh, check_integrations.sh | Most of the spec's tests exist; real Docker, kind and Playwright runs behind flags, the Android and iOS checklists are not run here. The real-model process evals (tests/evals 10, 16, 17) run on Qwen3-8B: 10 and 17 pass, 16 is the model's (agent-loop.md). |
| 18 | Deferred tools, worked example, "Running:" line | 🟡 (M13) | oklm.c deferredTools default; agent.c ToolSearch;
tools.c Bash description |
Deferred tools and ToolSearch exist; the worked example is a sentence of the Bash description, not of the system prompt; no "Running: ..." reminder line. |
| 18 | Short event notes | ✅ | events.c; agent.c tell_events, tell_jobs;
jobs.c oklm_jobs_last_line |
Short notes with the matched lines; a job's end note gives how it
ended and its last non-empty line (escapes removed, secrets masked,
clipped at a character; ProcessList uses the same). A job's output lines
become events only through a monitor; its end is an event without one.
test_agent.c test_job_note, test_jobs.c
test_last_line |
Processes conflicts (⚠️):
- Resolved (P1): the stop grace is 5 s.
- Resolved (P1): the journal has kind, directory and
rotated, the retention is a setting (ADR-0012 amended). - ADR-0012 and the spec make agents jobs; the code keeps them apart.
- Resolved (M8, P4):
--resumereopens a session (re-attaching its jobs), and other sessions' orphans are reaped at start. - Resolved (P3): a timeout moves a command to the background.
- Resolved (P3): a PowerShell tool next to Bash (which keeps
cmd.exe). - Resolved (P3): ProcessOutput / ProcessStop / ProcessList, readers
kept by the manager,
/tasks(integer ids kept, shown asjob 3). - In the default sandbox, jobs have their own network namespace: their ports cannot be reached or probed from the host.
- Resolved:
PR_SET_PDEATHSIGis per thread, so every child is forked by one thread of the harness's own (process.cproc_fork); a job a background sub-agent starts no longer dies with its thread. - On Windows, an owned job found alive on reopening is marked interrupted but not killed, and killing a detached job leaves its descendants.
Tests already covering it: test_jobs.c (test_basic,
test_restart, test_harness_death,
test_retention, test_tools; Unix only),
test_tools.c test_bash, test_sandbox.c
(test_jobs, limits, process namespace), test_agent.c
(test_job_note, test_background,
test_background_limits).
Git
Audit of git_spec.md (its G0),
2026-11-02, the same legend. The agent has no git code:
nothing in src/harness/, include/oklm/harness/
or apps/oklm.c runs or reads git, except the directory
walks skipping .git (tools.c:1011, 1034;
permissions.c:1817, 1839). No git library either, so git goes through
the command line as §0 wants. The "checkpoint" hits in the code are
oklm train's.
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 0 | Git through the command line, Bash, jobs | ✅ (G1 to G11) | git.c oklm_git_detect, oklm_git_snapshot,
oklm_git_state_danger, oklm_git_precommit,
oklm_git_worktree_*; permissions.c |
A git layer of its own: detection, the snapshot, a classifier, state checks, pre-commit checks, worktrees. test_git.c |
| 0 | History never rewritten unasked | ✅ | permissions.c builtin_dangers (push --force, reset
--hard, clean -f, filter-branch, update-ref); tools.c
oklm_git_state_danger |
History rewriting asks even under an allow rule or the bypass mode
(dangerous calls always ask). test_git.c
test_state_dangers, test_branch_dangers |
| 0 | Commits only when asked; conventions mirrored | ✅ | prompts/identity.md, prompts/git.md; git.c conventions in the snapshot | Commit and push only when asked; the repository's message style and branch names followed; safe staging, hook failures. |
| 0 | Works outside a repository | ✅ | Nothing depends on git. | |
| 1.1 | Detection, worktrees, submodules, LFS, default branch, hosts, conventions, hooks, signing | ✅ (G1) | git.c oklm_git_detect |
Sparse checkout not read; no /cd (the commands spec's).
test_git.c test_detect |
| 1.2 | Git snapshot in the prompt | ✅ (G1) | git.c oklm_git_snapshot; prompt.c;
cmd_agent |
Once per session, with the conventions and the commit rules. |
| 1.2 | Reminder on branch or HEAD change | ✅ (G1) | agent.c turn_reminders; git.c
oklm_git_head |
From the files, before each turn. test_git.c
test_reminder |
| 1.3 | Status line, operations in progress at start | ✅ (G1) | cmd_agent; term_ui.c oklm_git_branch,
oklm_status_default; git.c
oklm_git_read_marks |
The branch in the status line with its marks (↑N ahead
of the upstream, ↓N behind, * changed or
untracked files; also git.ahead / behind /
dirty for statusLine.command), read with one
git status after a submitted line or a ! command, never per
keystroke; the operation in progress told at start. test_git.c
test_marks, tools/check_commands.sh (on a terminal) |
| 2.1 | Read-only git allowed without asking | ✅ (G2) | permissions.c read_git, class_git,
class_gh |
Plan mode included. test_permissions.c
test_git_classes |
| 2.1 | Rules on subcommands | ✅ (G2) | permissions.c check_bash |
Rules also meet the command read apart; allow rules only past
-C and the pager options; a redirection makes a read a
change. |
| 2.1 | Compound commands | ✅ | util.c:139-251; permissions.c:1638-1715 | test_permissions.c test_split,
test_bash |
| 2.2 | Mutating commands ask; rules approve them | ✅ | permissions.c:783-788, 1638-1715 | acceptEdits with Bash has no test. |
| 2.3 | Always-ask list (force push, reset --hard,
clean -f, branch -D, amend of pushed,
--no-verify, config writes) |
✅ (M4, G2) | permissions.c builtin_dangers, class_git;
git.c oklm_git_state_danger |
The list (M4), config writes, a push to the default or a protected
branch, amends and rebases of pushed commits. test_git.c
test_state_dangers |
| 2.4 | Interactive commands refused | ✅ (G2) | permissions.c class_git |
With what to do instead. |
| 2.4 | GIT_EDITOR, GIT_SEQUENCE_EDITOR,
GIT_PAGER, PAGER,
GIT_TERMINAL_PROMPT set |
✅ (M3, P1) | process.c proc_run; jobs.c spawn |
|
| 2.5 | Secret scan, large files, unwanted files, staging only the agent's files | ✅ (G3) / 🟡 | git.c oklm_git_precommit; tools.c
tool_run |
Secrets block (gitleaks when installed); the others are told.
Staging by name is in the rules and /commit, not enforced
(an add -A asks like any change). test_git.c
test_precommit |
| 3 | Commit workflow, trailer, amend rules, edge cases | ✅ (G3) | prompts/git.md; skills.c commit;
cmd_agent |
git.coAuthorTrailer; amends of pushed commits ask;
/commit; git.autoCommit tells the model to
commit each change when done. |
| 4 | Branches: names, dirty switch, protected, sync, cleanup | ✅ (G4) | git.c oklm_git_state_danger; prompts/git.md |
A dirty switch and a commit to a protected branch ask; naming, sync
and cleanup in the rules. test_git.c
test_branch_dangers |
| 5.1 | /pr |
✅ (G7) | skills.c pr |
Template, Summary / Changes / Test plan, push without upstream
asked, gh or glab; /sandbox network on for the push.
tools/check_git_host.sh (a fake gh) |
| 5.2 | Existing PRs, comments, CI, /autofix-pr |
✅ (G10) | skills.c autofix-pr; permissions.c
class_gh |
A loop on ScheduleWakeup, ten rounds at most. tools/check_git_host.sh (a fake gh failing, then passing) |
| 5.3 | Issues | 🟡 | permissions.c class_gh |
Reads allowed, creation asked; no workflow of its own. |
| 6 | Conflicts, rebase, cherry-pick, bisect, interrupted operations | ✅ (G1, G5) | prompts/git.md; agent.c (bisect reset at the request's end) | test_git.c test_conflict_and_bisect |
| 7 | Archaeology, git-history skill |
✅ (G10) | skills.c git-history |
Loaded by the model when asked why, when or by whom. |
| 7 | Compact output | 🟡 | git.c oklm_git_snapshot; process.c |
The snapshot is compact (status lines capped, five subjects); git output through Bash gets the generic truncation. |
| 8 | /diff |
✅ (G6) | oklm.c c_diff |
The agent's files marked, stage / unstage / revert / open; no side-by-side view. tools/check_commands.sh |
| 8 | /code-review, /security-review,
/simplify, /ultrareview |
✅ (G8) | skills.c code-review, security-review,
simplify, ultrareview |
Prompt commands driving sub-agents by level; the last level not remembered. Measured with tools/eval_review.sh (six seeded bugs, medium): Qwen3-8B, the default, 6 of 6 then 5 of 6, above the 80% asked (Qwen3-4B 2, then 0). tools/check_git_host.sh |
| 9 | Worktrees, --worktree, sub-agent isolation,
/batch, /doctor |
✅ (G9) | git.c oklm_git_worktree_add, _changes,
_remove, oklm_git_worktrees; agent.c
wt_make, wt_settle; oklm.c
--worktree; skills.c batch |
test_git.c test_worktrees, test_isolation;
tools/check_git_host.sh |
| 9 | EnterWorktree / ExitWorktree tools, git.worktree.setup,
WorktreeCreate / WorktreeRemove hooks |
✅ (G9) | worktree.c oklm_worktree_make,
oklm_worktree_drop, tool_enter_worktree,
tool_exit_worktree, oklm_worktree_leave;
hooks.c; settings.c node_at |
Keep, remove (forced once agreed), merge (a protected branch asks; a
conflict undone); git.worktree.dir not offered (always
under .oklm/worktrees). test_git.c
test_worktree_tools, test_worktree_hooks;
tools/check_git_host.sh |
| 9 | Sandbox and worktrees | ✅ (G9) | cmd_agent; sandbox.c |
The agent's worktrees are under the project, so the writable set
holds them and the shared .git; a worktree made elsewhere
by hand is not covered. |
| 10 | Checkpoints independent of git | ✅ (M8) | session.c oklm_session_checkpoint,
oklm_session_rewind; oklm.c /rewind |
Checkpoints of the files the tools write, per turn, apart from git;
changes made by shell commands are not tracked. test_session.c
test_rewind |
| 11 | Git slash commands | ✅ (G3, G7 to G10) | skills.c commit, pr,
code-review, security-review,
simplify, ultrareview, bisect,
batch, autofix-pr,
git-history |
Every git command of the spec. tools/check_git_host.sh |
| 12 | git.* settings |
✅ (G3) | cmd_agent |
git.coAuthorTrailer,
git.protectedBranches, git.worktree.*, and (as
lines of the git snapshot the model follows)
git.branchPrefix, git.commitConvention,
git.prFooter, git.draftPRs,
git.autoCommit. host (gh/glab detected),
maxStatusLines (the snapshot's fixed cap) and
secretScan (gitleaks when installed) stay as they are. |
| 13 | -p, credentials from the environment, CI workflow |
🟡 (G10) | cmd_agent; skills.c
install-github-app |
JSON output since M14; /install-github-app writes the
workflow; network cut by the sandbox unless
/sandbox network on (sandbox.network in
CI). |
| 13 | Bypass only inside the sandbox | ✅ | permissions.c:369-380, 598-610 | test_permissions.c test_modes |
| 14 | Large repos, submodules, LFS, shallow clones | ✅ (G11) | git.c oklm_git_detect, oklm_git_snapshot,
oklm_git_owners; oklm.c owners_note |
Said in the snapshot with what to do; with LFS, whether git-lfs is
installed, the objects not pushed (git lfs status) and the
files not pulled (git lfs ls-files); CODEOWNERS
(.github/, the top, docs/; last match wins)
for the files the session edited, given to /commit and
/pr; timeouts on slow commands; pre-commit flags large
files outside LFS. test_git.c test_detect,
test_lfs (a stand-in git-lfs), test_owners,
test_precommit; tools/check_commands.sh
(/commit) |
| 13 | CI templates, pushes in CI | 🟡 (G10) | skills.c install-github-app |
/install-github-app writes the CI workflow; nothing
more on pushes in CI. |
| 14 | Large repositories | 🟡 | git.c command timeout, snapshot caps | As row 518: git commands time out and the snapshot is capped; nothing else for large repositories. |
| 15 | Fixture repositories, fake gh, git tests |
✅ | test_git.c (fixture repositories with a bare remote);
tools/check_git_host.sh (a fake gh) |
Fixture repositories, a fake gh, git tests
(test_detect, test_precommit,
test_conflict_and_bisect,
test_worktrees). |
Git conflicts (⚠️):
- Resolved (M4, G2): dangerous calls ask even when a rule allows them.
- Bypass allows everything but deny rules (permissions.c:772-774).
- Resolved (G2): read-only git runs in plan mode.
- Resolved (G2): the classifier reads the command apart first.
- The sandbox cuts the network by default (sandbox.c:399; ADR-0011 all
or nothing): fetch, push and host access need an answer (per call, or
--allow-network). - The sandbox's writable set excludes a linked worktree's git directory.
- Resolved (G3): the setting is
git.coAuthorTrailer.
Tests already touching it: test_permissions.c
(test_split, test_bash on git command lines,
test_modes, test_precedence,
test_settings), test_tools.c (test_bash,
test_skills), test_jobs.c, test_sandbox.c.
Commands
Audit of commands_spec.md (its C0),
2026-11-02. Before M10 (C1–C3 since; the rows below say what is done):
no command framework: two REPLs compared strings in
place, cmd_agent (/exit,
/thinking or Ctrl-O, /reset,
/jobs, /mode MODE) and cmd_chat
(/exit, /reset, /system TEXT,
/tool RESULT); the GUI has none; -p goes to
the model as it is.
Framework
| § | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| 1.1 | Command types | ✅ (C1) | commands.h oklm_cmd_type |
Actions, dialogs (picker or text), prompt commands; workflows and MCP prompts with their specs. |
| 1.2 | One registry | ✅ (C1) | commands.c oklm_cmds_add,
oklm_cmds_add_skills; oklm.c repl_defs |
oklm chat keeps its own four commands (Later). |
| 1.3 | At the start of a message only | ✅ (C1) | commands.c oklm_cmds_parse |
Case aside. test_commands.c test_parse |
| 1.3 | Stacking, case, namespaces, $ARGUMENTS, //
escape |
✅ (C1, C3) | commands.c oklm_cmds_parse,
oklm_cmds_expand |
test_commands.c test_parse,
test_expand |
| 1.3 | Usage errors | ✅ (C1) | oklm.c c_add_dir, c_skills; commands.c
(stacking) |
|
| 1.3 | Unknown command not sent to the model | ✅ (C1) | commands.c suggest |
Up to three close names. |
| 1.4 | Precedence, shadowing warnings | ✅ (C1) | commands.c oklm_cmds_add_skills; tools.c
add_skill (shadowed); oklm.c c_help |
/project:NAME, /user:NAME. test_commands.c
test_precedence |
| 1.5 | Running while busy | ✅ (C1) | commands.c oklm_cmds_submit,
oklm_cmds_take; oklm.c view_key,
repl_send |
Queue, immediate, immediate-set; no confirmation for
cache-invalidating changes (no /model yet). test_commands.c
test_submit, test_busy_applies |
| 1.6 | Menu on /, completion |
✅ (C2) | commands.c oklm_cmds_menu; oklm.c
view_draw_line, view_complete_arg |
Enum values and directories completed; sessions, servers, models
with their commands. test_commands.c test_menu |
| 1.7 | Skills folder format | ✅ | skills.c:1065-1076, 1227-1263; agent.c:834-837 | test_tools.c test_skills |
| 1.7 | .oklm/commands/, front matter superset, expansion
(!, @) |
✅ (C3) | tools.c add_skill, scan_commands;
commands.c oklm_cmds_expand |
model and context: fork read, not acted on
(Later). |
| 1.8 | Visibility overrides | ✅ (C3) | tools.c oklm_tool_ctx_skill_override; oklm.c
reload_skills, c_skills |
Managed locks with managed settings. |
| 1.9 | -p "/cmd" |
✅ (C1) | oklm.c repl_submit (headless) |
|
| 2 | Picker, settings panel, diff viewer | 🟡 (C2) | term_ui.c oklm_picker_*; oklm.c view_pick,
tui_config_panel; tui.c
oklm_tui_settings_* |
The picker (used by /rewind, /mode,
/theme, /output-style); the settings panel of
/config in the full-screen UI (edited in place, checked,
saved to a scope); the diff viewer is the git spec's. test_term.c
test_picker, test_tui.c
test_settings_panel |
| 2 | Confirmation with "don't ask again" | ✅ (M4) | oklm.c (an "always" answer); tools.c
oklm_perms_save_rule |
Saved as an allow rule in the settings. test_permissions.c
test_save_rule |
| 2 | Progress view, text fallback | ✅ | oklm.c status_line, c_tasks,
view_progress; tui.c oklm_tui_progress_set;
view.tty, view.keys |
Background work in the status line and /tasks as text;
in the full-screen UI a progress row above the status bar (writing with
tokens and speed, a tool running with its time, jobs, context).
test_tui.c test_progress |
| 4 | Bundled skills | ✅ (M13, G3, C7) | skills.c builtin_skills |
Every skill-type command of the spec is bundled (skill-creator,
commit, pr, the reviews, bisect, batch, autofix-pr, run, verify, debug,
deep-research, update-config, ...); /loop and
/doctor are built-in commands. |
| 5, 6 | Settings, hook events | ✅ (C3) | settings.c (known_members), skills.c, commands.c
review_args, oklm.c |
Every setting of the spec read: commands.maxStack,
skillOverrides, feedback.bundleDir,
commands.legacyDirs (the single-file command directories
skipped), review.defaultLevel (/code-review
without a level), goal.maxIterations
(goal.maxTurns its older name),
loop.defaultPrompt (after .oklm/loop.md),
schedule.backend (cron; systemd, launchd, taskscheduler
refused by /schedule as not written),
ui.viewMode (classic, full, fullscreen),
ui.promptColor; each member's type or value checked, a
wrong one left out with a warning. CommandRun (commands.c) and
DirectoryAdded (oklm.c c_add_dir) hook events fire.
test_settings.c test_members, test_skills.c
test_reload, test_commands.c
test_review_level, tools/check_commands.sh |
| 7 | Tests | ✅ (C1–C3) | test_commands.c; test_term.c test_picker;
test_line_edit.c |
Catalog
Present in part (🟡) or under another name (⚠️); every other command of §3 is ❌, and the Skip rows have nothing (their "not available" stubs are C10's).
| Command | OKLM | Evidence | Notes |
|---|---|---|---|
/clear [name] (/reset,
/new) |
✅ (C4) | oklm.c c_clear |
A name labels the conversation left (its session's title). |
/exit (/quit) |
✅ (C1, P4) | oklm.c c_exit, leave_ok |
Asks with jobs running. |
/btw, /copy, /todos,
/recap, /rename, /branch,
/resume (/continue),
/autocompact, /goal, /undo |
✅ (C4) | oklm.c c_btw, c_copy,
c_todos, c_recap, c_rename,
c_branch, c_resume,
c_autocompact, c_goal |
Asides through oklm_agent_ask_aside() (not in the
history); /recap not shown by itself after idle.
tools/check_commands.sh |
/fork, /background;
oklm agent agents, attach, send,
stop |
✅ (C8) | oklm.c c_background, c_fork,
bg_spawn, agent_bg_cli,
inbox_* |
Detached processes resuming the session (no daemon); peek replies
through an inbox file; Linux and macOS only. /subtask and
/stop not done. tools/check_background.sh |
/plan |
✅ | oklm.c c_plan |
test_tools.c test_plan |
/permissions |
✅ | oklm.c c_permissions,
permissions_command |
In the REPL: the mode, added directories, rules by scope, allow / ask / deny / remove per scope; text, no panel, no list of recent denials. |
/sandbox |
✅ (C5) | oklm.c c_sandbox |
|
/add-dir |
✅ (M4) | oklm.c c_add_dir |
Applies from the next tool call, also while the agent works. |
/cd, /import, /skill-doctor,
/statusline, /color |
✅ (C6) | oklm.c c_cd, c_import,
c_skill_doctor, c_statusline,
c_color |
/import copies commands, agents and skills (not MCP
servers, settings). tools/check_commands.sh |
/keybindings, /terminal-setup |
❌ | oklm.c stubs | Key bindings are fixed (no file to edit yet). |
/skills, /reload-skills |
✅ (C3) | oklm.c c_skills, c_reload_skills |
|
/tasks (/bashes) |
✅ (P3, C8) | oklm.c c_tasks; agent.c
oklm_agent_background_list |
/jobs and /bashes its aliases; background
agents, wakeups, loops and background sessions listed; text, and an
interactive panel in /tui (follow, stop, restart,
keep). |
/loop (/proactive), /schedule
(/routines) |
✅ (C8) | oklm.c c_loop, loop_round,
c_schedule |
Loops on an interval or paced by ScheduleWakeup;
/schedule through crontab only.
tools/check_commands.sh |
/help |
✅ (C1) | oklm.c c_help |
By source, aliases, shadowing. |
/status |
✅ (C9) | oklm.c c_status |
Text, not the settings panel. |
| Skipped commands (§3.8), the generated reference (C10) | ✅ (C10) | oklm.c skipped_command,
agent_commands_cli; docs/commands.md |
Typed, a skipped one says why. |
/debug, /deep-research (bundled skills,
§4) |
✅ (C10) | skills.c | /deep-research has no web search. |
/code-review (/review),
/ultrareview, /security-review,
/simplify, /batch, /autofix-pr,
/commit, /pr, /bisect,
/install-github-app, /run,
/verify, /run-skill-generator |
✅ (C7) | skills.c built-ins | Prompt commands; /review loads code-review (a project's
or user's review skill wins over it).
tools/check_git_host.sh |
/voice |
❌ | cmd_transcribe; audio.h:115-133 |
Speech to text exists; nothing records. |
/subtask |
❌ | oklm.c stub; agent.c; jobs.h | Background sub-agents (the Agent tool) and /fork (a
background session) exist, no /subtask forking the
conversation into a sub-agent. |
/context, /usage |
✅ (C9) | oklm.c c_usage (/cost,
/stats); /context with M5b |
tools/check_commands.sh |
/model, /effort |
✅ (C5) | oklm.c c_model, c_effort; agent.c
oklm_agent_set_model,
oklm_agent_set_template_var |
Checked switching Qwen2.5-0.5B to Qwen3-0.6B mid-session.
/effort changes enable_thinking alone, the
--template-vars ones (clear_thinking) kept
(test_agent test_template_var). |
/sandbox, /plan TEXT,
/config KEY=VALUE, /update-config,
/fewer-permission-prompts |
✅ (C5) | oklm.c c_sandbox, c_plan,
c_config; skills.c |
tools/check_commands.sh |
/fast, /advisor |
❌ | Local, optional: a second model. |
OKLM commands outside the spec: /mode MODE,
/thinking, and oklm chat's
/system TEXT, /tool RESULT.
Commands conflicts (⚠️): an unknown /foo and any
-p "/cmd" reach the model (§1.3, §1.9); /reset
and /jobs are the spec's /clear and
/tasks (aliases, per agent-design.md);
/mode and /thinking have no row (kept as local
built-ins, or folded into /plan, /permissions,
/config: C0 decides); oklm chat has its own
set (shared registry or not: C0); matching is exact and case-sensitive;
skill shadowing is silent.
Tests already touching it: test_tools.c (test_skills,
test_plan, test_asking), test_agent.c
(test_calls with reset, test_job_note,
test_background), test_permissions.c, test_jobs.c,
test_line_edit.c, test_sandbox.c.
Serving
Audit of serving_spec.md (its S0),
2026-11-02, the same legend; ⚠️ here also marks a row where the spec's
"What OKLM already does" table is wrong. Continuous batching
over a fixed set of sequences exists: one scheduler thread, one
oklm_eval_batch() a step, decode tokens first and prompt
pieces in the rest of n_batch, requests joining between
steps (sched.c:1371-1835). Memory is contiguous and reserved up front:
--parallel × -c cells per layer (model.c:1931,
2293-2340), resident from the start. No block, no allocator, no
preemption, no prefix shared between live requests. The design built on
this audit is serving-design.md, the
cache layout adr/0019-paged-kv-cache.md, the
measured baseline in serving-design.md.
S1 (prerequisites and baseline)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S1 | Packed (ragged) input: flat tokens, per-token positions, per-sequence offsets, no padding | ✅ | model.h:296-326; model.c:2924-3032 (run_items),
3173-3209; model_internal.h:249-256 (model_group) |
Items carry a sequence and its tokens; positions come from
seq_past, offsets are each group's r0. One
item per sequence per call (model.c:3182-3183). |
| S1 | Packed equals unbatched logits | ✅ | test_model.c:1138-1244 (check_sequences), 337
(test_batching) |
Mixed prompts, decodes, copies and truncation: 0.0 on the CPU, within 1e-5 on OpenCL (F32 cache). |
| S1 | Reference path | ✅ | model.h:249 (oklm_eval); adr/0015-test-references.md |
llama.cpp is the test-only oracle; its llama-server was
built for the baseline only. |
| S1 | Benchmark harness: throughput, TTFT, TPOT at 1, 4, 16, 64 | ✅ (S1) | tests/model/bench_batch.c; tools/bench_serve.py | The HTTP load generator (short and agent workloads, 503 retries, cached prompt tokens), its runs in serving-design.md. |
| S1 | Non-streamed requests cancelled on disconnect;
--workers over --parallel +
--queue |
✅ (S1) | server.c completion, oklm_server_new;
sched.c sched_req_wait_ms, take_queued,
sched_submit; nilorea
n_http_server_peer_gone |
Freed in 0.02 s against 1.7 s for the answer (test_server.c
test_disconnect); a burst within the free sequences is not
refused; the forward pass's view headers sized by the sequences
(test_model.c test_many_sequences, 1024 in one batch). |
S2 (paged KV cache)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S2 | KV pool of blocks | ✅ (S2) | model.c oklm_context_new (kv_blocks),
paged_attend; kv_pool.c |
One pool tensor per layer and kind of
kv_blocks * kv_block_size rows on the layer's device;
kv_blocks = 0 keeps the contiguous cache bit for bit. |
| S2 | Cache types | ✅ | model.h:138-140; model.c:1781-1797 (kv_type_ok),
2279-2291 (rotation) |
F32, F16, BF16, Q8_0, Q4_0, Q4_1, Q5_0, Q5_1, IQ4_NL; quantized ones
need head_dim % 32 == 0. A cell is one token's row,
quantization blocks run along head_dim (model.c:2307). |
| S2 | Block allocator, free list, refcounts | ✅ (S2) | kv_pool.c kv_pool_take, kv_pool_unref,
kv_pool_truncate; model.c paged_reserve,
oklm_seq_copy |
A batch takes its blocks all or none; copies share full blocks and
copy the partial one; a shared block is copied before a write.
test_model.c test_paged_blocks |
| S2 | Block size 16 | ✅ (S2) | model.h kv_block_size |
16 by default, 32 allowed (ADR-0019), not on the command line. |
| S2 | Memory profiled at start, the rest to the pool | ✅ (M14) | model.c oklm_kv_blocks_fit,
oklm_context_device_bytes; backend_cl.c
cl_free_memory; server.c oklm_server_new;
--kv-mem |
The pool takes what the device says is free (AMD's
CL_DEVICE_GLOBAL_FREE_MEMORY_AMD: other programs and models
counted) less a 3 % margin, the weights not yet there and the
activations (the context's buffers are all allocated up front, so they
are computed, not sampled), within the total-based estimate; a draft
model's weights, cache and activations come out of it. Four contexts'
worth on the CPU. |
| S2 | Slot mapping | ✅ (S2) | kv_pool.c kv_pool_slot; model.c
paged_attend |
New rows written block by block to
table[p / B] * B + p % B. |
| S2 | Paged attention, step A (gather) | ✅ (S2), replaced | git history (paged_attend before step B) |
Measured and left behind: identical logits, half the OpenCL throughput (serving-design.md). |
| S2 | Paged attention, step B (block-table kernel, decode and prefill) | ✅ (S2) | ops.h oklm_attention_paged; attention_cpu.c
kv_row; kernels.cl KVR in
attention and the tiled attention_tile*;
backend_cl.c arg_table; model.c paged_attend,
paged_upload_tables |
Keys and values read in place through the table on the CPU (every path, row by row) and OpenCL (decode and the tiled prompt kernels); the tables uploaded once per step. Identical logits; OpenCL within 4 % of the contiguous cache at 16 clients, equal at one. One launch per sequence and layer still (S6). |
| S2 | Memory follows the tokens used | ✅ (S2) | model.c paged_reserve, oklm_seq_truncate;
sched.c blocks_fit, reclaim_idle |
Blocks taken as tokens arrive and given back on truncation; idle
sequences give theirs first; a full cache ends the newest request
(length) until S3 preempts. 16 sequences of Qwen2.5-0.5B at
-c 4096: 1478 MiB against 2052 contiguous. test_server.c
test_kv_pressure |
| S2 | Greedy output equals the reference | ✅ (S2) | test_server.c test_parallel (both caches); test_model.c
test_paged_sequences |
Qwen2.5-0.5B, four concurrent chats: the paged and contiguous answers identical on the CPU and OpenCL. |
S3 (scheduler)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S3 | waiting queue |
✅ (S3) | sched.c take_queued, sched_submit |
FCFS by submission; --queue 256 by default with the
paged cache; preempted requests go back to its head. |
| S3 | running set |
✅ (S3) | sched.c sched_main |
The requests holding sequences, 64 on OpenCL and 16 on the CPU by default; the paged cache's blocks are the real bound. |
| S3 | swapped |
✅ (M14) | model.h oklm_seq_swap_out,
oklm_seq_swap_in; sched.c preempt,
assign, drop_swap;
--swap-mem |
A preempted request of 64 positions or more moves its rows to host
memory while the swapped ones hold under --swap-mem;
running again it attaches what the prefix cache still holds and brings
the rest back, its rows' keys recorded (its blocks cached again). Same
answers as unpressured (test_server.c test_preemption),
exact logits after a round trip (test_model.c check_swap).
Not for a quantized cache on a device nor several devices
(recompute). |
| S3 | Engine step: decode reservation, admission, forward, sample, finish | ✅ (S3) | sched.c sched_main |
Decode tokens first (oldest first, blocks reserved), then admission
while a sequence and the prompt's blocks are free, then prompt pieces
oldest first capped by --prefill-chunk, one forward,
sampling. |
| S3 | Preemption (recompute) | ✅ (S3) | sched.c preempt, newest_running,
feed_tokens |
The newest running request gives its blocks back and waits at the
head of the queue; it replays its prompt, generated tokens and the
pending one, its sampler kept. Answers identical to unpressured ones
(test_server.c test_preemption); counted in
/api/stats. |
| S3 | FCFS | ✅ | sched.c:921-1009 (take_queued) |
Head of the queue first, into the free slot holding its longest prefix. |
| S3 | No starvation or deadlock under memory pressure | ✅ (S3) | sched.c | Strict FCFS (the head waits for its blocks, the newest is preempted
first); prompts blocking each other release the newest; a request longer
than the cache ends with length. test_server.c
test_kv_pressure, test_preemption |
| S3 | Engine bounded by memory, not by a sequence count | ✅ (M14) | server.c oklm_server_new; model.c
paged_upload_tables |
By default as many sequences as a step has rows (512) or the pool has blocks, the fewer; a step uploads only its own sequences' tables, so idle sequences cost nothing per step. Qwen2.5-0.5B, 256 clients: 5203 to 7265 tokens/s, TTFT p50 4.57 to 0.22 s against 64 sequences. |
S4 (chunked prefill)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S4 | Chunk capped to the budget left after decodes | ✅ | sched.c:1568-1627 | |
| S4 | Partially prefilled sequences | ✅ | sched.c:73 (fed), 1749-1765 |
fed is the spec's
num_computed_tokens. |
| S4 | Decodes and chunks in one step | ✅ | sched.c:1439-1641 | |
| S4 | Fairness between prefills | ✅ (S3) | sched.c sched_main |
Oldest request first, each piece capped by
--prefill-chunk. |
| S4 | 30k-token prompt mid-generation, TPOT flat | ✅ ⚠️ (M14) | sched.c piece_cost, cost_fit,
PIECE_PROBE; kernels.cl ATH_KERNEL,
AT_KERNEL (GQA rows); tools/bench_stall.py |
Bounded, not flat (correction 8). Pieces sized by a fitted cost of their tokens and of their attention over the keys before them, so each at its depth; small probes until fitted. Prompt attention twice as fast (key tiles shared by a KV head's query heads, half tiles, accumulators in registers). Qwen3-4B, 32,872 tokens among four streams: the stall at its start gone (max gap 389 to 33 ms), its prefill 225 to 111 s, the streams' median 12.0 to 25.9 ms during it. |
S5 (prefix caching)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S5 | Prefix reuse | ✅ (S5) | sched.c assign, take_queued,
prefix_coming; model.h oklm_seq_attach_prefix,
oklm_kv_prefix_cached |
A request starts from the longer of its sequence's own prefix and the prefix cache's, any request's; a waiting request whose prefix another is computing waits for its blocks instead of computing them again. |
| S5 | oklm_seq_copy() sharing a prompt |
✅ (S2) | model.c oklm_seq_copy |
Paged: full blocks shared, the partial one copied on the device. The scheduler shares through the prefix cache instead. |
| S5 | Block hashes chained on the parent | ✅ (S5) | kv_pool.c block_hash, kv_pool_written |
FNV-1a over the parent's hash, the block size and the rows, when a block becomes full: a token, or a media row's marker, its media's content hash and its index (S8); a row given as an embedding without a hash keeps its block unhashed. |
| S5 | hash -> block map |
✅ (S5) | kv_pool.c map_lookup, map_insert |
Open addressing, rebuilt past a quarter of removed slots; a lookup compares the tokens, so a collision never attaches a wrong block. |
| S5 | Reuse across live requests (refcount) | ✅ (S5) | kv_pool.c kv_pool_attach, kv_pool_ref |
Two requests at once start from a system prompt a finished one
computed (test_server.c test_shared_prefix); 16 cold
clients of the agent workload find 1297 of 1319 tokens on average. |
| S5 | LRU of refcount-0 blocks | ✅ (S5) | kv_pool.c kv_pool_unref, kv_pool_take |
Released hashed blocks stay found until the pool takes them, least
recently released first; counted as free. test_model.c
test_prefix_cache |
| S5 | Copy-on-write rule | ✅ (S2, S5) | kv_pool.c kv_pool_must_copy; model.c
paged_reserve |
Shared or hashed blocks are copied before a write. |
| S5 | Cached tokens reported | ✅ | server.c:1208-1213; sched.c:608, 623 | usage.prompt_tokens_details.cached_tokens;
cached_tokens in /api/stats. |
S6 (model runner)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S6 | Launch overhead (the role of CUDA graphs) | ✅ (S6) | ops.h oklm_set_rows,
oklm_attention_paged_tokens; kernels.cl
set_rows, attention (per token); model.c
model_attend, paged_upload_tables |
Per step and layer: one write of every sequence's keys and one of its values (float caches; quantized ones keep a copy per block on a device), one attention launch for the decode tokens of every sequence, the step's metadata (positions, table offsets, slots, tables) uploaded once. OpenCL TPOT at 16 clients 21.0 to 14.6 ms, throughput 750 to 1078 tokens/s; the rest of the step (projections, norms, the prompt groups' launches) is unchanged. At one client a token is 2.55 ms of kernels in 3.2 ms, at four 3.4 ms in 3.6 to 3.9: decode steps are compute-bound, no graph equivalent needed. |
| S6 | Batched sampling | ✅ (S6) | sampling.c oklm_sampler_greedy,
oklm_sampler_top_needed,
oklm_sampler_sample_top; model.h argmax_only,
top_n; kernels.cl argmax_rows,
topk_rows |
Every row's best token (greedy) or best candidates (top_k plus the tokens a penalty may lower, up to 512) found on the device in one launch, only those read back; the host draws from the candidates, the same token as from the whole row (test_sample_top: 900 draws, penalties included). The whole row only for no top_k, grammars or penalties that raise logits. Temperature 0.8 at 64 clients: 2251 to 4917 tokens/s. |
| S6 | Logits transfer | ✅ (S6) | model.c run_items |
Greedy rows read back one id; the other items their own rows only. 64 clients on OpenCL: 3340 to 5126 tokens/s. |
| S6 | CPU and device overlap | ✅ (S6), measured unneeded | sched.c | The host works 0.22 ms between 11 ms steps at 64 clients (2 %); within a step the kernels run as they are queued. A pipelined engine would win at most that. |
S7 (serving layer)
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S7 | One loop owning scheduler and device | ✅ | sched.c:1371-1835, 1903 | One thread; HTTP threads only submit and wait. |
| S7 | Requests through a queue, outputs through per-request channels | ✅ | sched.c:256-267 (sched_req_wait), 2017-2037;
server_internal.h:32-96 |
Text and a condition variable per request; UTF-8 and stop-string holdback (sched.c:303-327). |
| S7 | Concurrent connections | ✅ (S1) | server.c oklm_server_new; server.h |
--workers, by default --parallel +
--queue + 8 (512 at most): 64 clients reach 64
sequences. |
| S7 | Cancellation within one step | ✅ (S1, S7) | server.c stream_answer, completion;
sched.c take_queued, finish |
A client that leaves frees its request at the next step, and with
the paged cache every finished request gives its blocks back at once
(the full ones stay as cached prefixes): kv_usage back to 0
after two clients hang up (test_server.c
test_disconnect). |
| S7 | OpenAI API, streaming, tools, JSON schemas | ✅ | server.c:2371-2462, 906-1101, 1393-1480; adr/0018-server-api.md | n = 1 only (server.c:2043-2050); text parts of messages
only (server.c:387-399). |
| S7 | Agent tooling unchanged | ✅ | test_server.c:3063 (test_agent_http), 3680
(test_agent_model) |
oklm agent --url, OpenAI's Python client (server.md). |
| S7 | Metrics: queue depth | ✅ | server.c:2295-2363; sched.c:2039-2048 | queued, active, tokens, rate. |
| S7 | Metrics: KV usage %, prefix hit rate, preemptions | ✅ (S7) | server.c stats; sched.c note_kv,
assign, preempt; dashboard.html |
kv_blocks, kv_blocks_free,
kv_usage, prefix_hit_rate (cached over all
prompt tokens), queue_wait_ms (mean wait for a sequence),
preemptions, in /api/stats and on the
dashboard. |
| S7 | Windows | ✅ | server.c:215; testing.md | test_server under make wine-test. |
S8 (extensions) and the models the paged cache must keep
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| S8.1 | Grammars per request | ✅ | sched.c:617-621, 706-755; sampling.c:372-375; adr/0009-tool-calls-and-grammars.md | Lazy (tool-call trigger) and eager; the mask applied only when the first choice is refused. Independent of the cache. |
| S8.2 | Speculative decoding, MTP | ✅ (S8) | sched.c ngram_drafts, draft_propose,
sched_main; model.h oklm_get_argmax_row,
oklm_context_device_bytes; --spec-ngram,
--draft; test_server.c test_spec_ngram,
test_draft_model |
In the server: drafts by prompt lookup (the tokens that followed a
request's last 3, 2 or 1 tokens earlier in its own text), or from a
draft model (--draft: a context of its own, paged, a
sequence per slot brought to the slot's tokens lazily, a batch a round
over every drafting request), verified in the same step, the cache
truncated past the accepted ones; greedy requests by the argmax of every
row, sampled ones by a draw a row from the same logits, so both keep
plain decoding's answers. Only while at most 4 requests decode and while
a request gains half a token a step; the draft model also only while its
measured speed beats plain decoding. Rewriting a function on
Qwen2.5-0.5B by prompt lookup: 253 to 569 tokens/s; Qwen3-4B with a 0.6B
draft: 11 to 13 % faster on the CPU, 2 to 4 % slower on OpenCL
(launch-bound small models). The MTP block stays out of the server
(oklm run --mtp). |
| S8.3 | Quantized and rotated KV | ✅ (S8) | model.c paged_attend, kv_type_ok;
test_infer_public.c test_paged_quant |
Whole rows per token: a block of any token count holds whole quantization blocks. Paged, a Q8_0 cache gives the logits of the contiguous one exactly on the CPU and OpenCL (SmolLM2, two sequences, 40 steps); Qwen2.5-0.5B's answers through the server identical. On a device a quantized cache keeps a copy per block for its new rows (set_rows takes float caches). |
| S8.4 | Several devices | ✅ ⚠️ | model.c:2166-2249, 2528-2586 (forward); opencl.md |
Layer ranges per device, each device holding its layers' cache; tensor parallelism decided against. |
| S8.5 | LoRA multiplexing | ✅ (S8.5) | adapter.c oklm_adapter_load, model_adapt;
kv_pool.c (salts); sched.c assign; server.c
(model) |
ADR-0021: adapters beside the weights, stacked per weight, one
gathered product per weight for a mixed batch; the prefix cache keeps
each adapter's blocks apart;
oklm serve --lora-module NAME=FILE, chosen by a request's
model. test_train.c lora_serve_check,
test_server.c test_adapters |
| model | Sliding window (Gemma 2, 3) | ✅ | arch_llama.c:87-89, 660; ops.h:404 | Full n_ctx cells kept, the window applied in attention:
unchanged by paging. |
| model | Latent attention (DeepSeek V2, V3) | ✅ | model.c:1939, 2777-2780; arch_llama.c:422-463 | One compressed row per token in the key cache, the value cache one unused cell. |
| model | Multimodal embeddings in a batch | ✅ (S8) | model.h oklm_seq_tokens.media; kv_pool.c
block_hash, same_rows; prompt.c
oklm_mm_build; server.c content_media,
mcache_keep; sched.c piece_rows; test_model.c
check_prefix_media, test_server.c test_media,
test_mm_public.c test_smolvlm_rows |
Images and sounds in chat messages (--mmproj, base64
image_url / input_audio parts), encoded as the
request arrives, their embeddings kept by content hash; their rows keyed
in the paged cache by the media's content hash and the row's index,
found again only with the same picture, exact against the contiguous
cache on the CPU and OpenCL. SmolVLM-256M: the same picture again 4.43
to 0.13 s on OpenCL (336 of 349 rows cached), the answer unchanged. |
| model | Weight streaming (--gpu-stream) |
✅ | model.c:2343-2372, 2497-2519 | Device mirrors of the CPU layers' caches, copied per sequence range. |
Testing strategy
| Part | Feature | Status | Evidence | Notes |
|---|---|---|---|---|
| T | Determinism, batched against the reference | ✅ | test_model.c check_sequences,
check_prefix_cache, check_prefix_media,
check_swap; test_server.c test_parallel,
test_preemption, test_spec_ngram |
Batch composition and chunking, preemption by recompute and swap, prefix and media cache hits, speculative drafts: the answers of plain decoding. |
| T | Stress test: random arrivals and cancellations, tiny pool | ✅ (M14) | test_server.c test_stress |
24 clients, random lengths and moments, shared prefixes, streamed and sampled requests, a quarter hung up on, 24 blocks for 8 sequences with swapping: preemptions and swaps each run, every block and swap given back, every request ended. |
| T | Allocator invariants | ✅ (M14) | kv_pool.c kv_pool_check; model.h
oklm_kv_check; sched.c (OKLM_KV_CHECK=1) |
No count below 0, counts equal to the tables holding each block, free and cached blocks on their lists once, the hash map holding exactly the hashed blocks, no block lost; checked after every step of the stress test and through the model tests. |
| T | ASan, TSan | ✅ | Makefile (asan-test, tsan-test) |
test_server runs under both. |
Serving conflicts and corrections (⚠️):
- The spec's table says no freed prefix is kept: each sequence keeps
its last request's tokens until another request takes it (sched.c:330,
520-626), so up to
--parallelprefixes survive. - It says
oklm_seq_copy()copies a shared prompt: only the library and bench_batch use it; the scheduler never does. - Decision 3 expects blocks of a multiple of 32 tokens for quantized
caches: a cell is one token's row, quantized along
head_dim(model.c:2307), so a block of any size holds whole quantization blocks. - Decision 1 expects the device's free memory: OpenCL gives the total
and the largest allocation only; AMD's
CL_DEVICE_GLOBAL_FREE_MEMORY_AMDis used when the driver has it (M14), the total-based estimate or a budget otherwise, as on the CPU. - Concurrency was capped at 32 by the HTTP workers and at
--queue+--parallelby 503 answers, below the spec's 64 clients. Done in S1:--workersfollows the two, and a burst the free sequences take is not refused. - Speculative decoding and multimodal prompts existed in the library
but not in the server: for the paged cache they were serving features to
add, not ones to keep. S8 added them: prompt-lookup drafts, a draft
model (
--draft), and images and sounds (--mmproj). - Attention costs one call per sequence and layer (model.c:2716-2790): the batch shares the weight reads, not the attention launches.
- S4's "TPOT flat" is not reached on this hardware: while a long
prompt is read beside decoding requests, each step carries a piece whose
attention reads every key before it (4.4 GB at 30k keys for Qwen3-4B's
36 layers), about a decode step's time even for a few tokens. What holds
instead: no stall (the largest gap 33 ms), the slowdown bounded by
--prefill-share, the prompt read twice as fast as before.
Tests already covering it: test_model.c (test_batching,
check_sequences on the CPU and OpenCL), test_server.c
(test_parallel, test_queue_and_halt,
test_completions cached prompt, test_client
cancel, test_agent_http, test_agent_model),
tests/model/bench_batch.c.
ROCm
The audit (R0) of rocm_spec.md, 2026-11-04: what exists for a ROCm/HIP training path and LoRA, with evidence. The decisions and recommendations are in rocm-design.md.
Environment
| Part | Status | Evidence | Notes |
|---|---|---|---|
| GPU | ✅ | rocminfo: AMD Radeon RX 7900 XT,
gfx1100 |
20 GB |
| HIP runtime | ✅ | hipcc --version: HIP 6.4;
/opt/rocm/lib/libamdhip64.so.7.2.70204 |
ROCm 7.2.4 |
| hipBLASLt | ✅ ⚠️ | /opt/rocm/lib/libhipblaslt.so, version 1.2.2 (hipblaslt-version.h:36-38) | Its header is C++ only (hipblaslt.h:54-56 include
<memory>, <regex>,
<vector>; gcc -std=c17 fails), against
the plan's constraint 7; its 24 functions are exported as C symbols
(nm -D), so a run-time loader with OKLM's own declarations
reaches them (conflict 1). |
| HIP runtime header in C | ✅ | hip/hip_runtime_api.h, hip/hip_runtime.h
compile with gcc -std=c17 -D__HIP_PLATFORM_AMD__ |
|
| rocBLAS in C | ✅ | rocblas/rocblas.h compiles as C;
/opt/rocm/lib/librocblas.so.5 |
Approved in hipBLASLt's place after R1 (hipBLASLt no faster than the OpenCL kernel, rocBLAS 1.7 to 3.5 times). |
| Run-time loader, product wrapper | ✅ (R1) | src/train/hip_loader.c; src/train/gemm_rocblas.c
(tr_rb_gemm); tests/train/test_rocblas.c;
tests/train/bench_rocblas.c |
Every layout of the trainer's products within 7e-6 of
tr_gemm. |
Abstractions and paths
| Part | Status | Evidence | Notes |
|---|---|---|---|
| Compute backend interface | ✅ | include/oklm/core/backend.h:51-84 (oklm_backend_iface),
src/core/backend.c |
Inference only; the trainer does not use it. |
| Trainer device seam | ✅ | src/train/train_internal.h:560-759 (tr_cl_*);
src/train/train.c:1191-1204 (k_matmul_forward,
k_matmul_backward), 658-661 (device chosen) |
A device launcher per CPU kernel, chosen through
tr->cl. |
| Device memory | ✅ | src/train/train_cl.c:95-112 (tr_cl_buf, fake
addresses), tr_cl_alloc, tr_cl_upload,
tr_cl_download |
Pointers never dereferenced on the host. |
| Device product | ✅ | src/train/train_cl.c:624-630, 903-989 (gemm_batch,
gemm), 1105 (pairs);
src/train/train_kernels.cl:167 (tr_gemm) |
Strides on both operands, batched; the attention's batches map query heads to KV heads. |
| CPU reference product | ✅ | src/train/gemm_train.c:233 (tr_gemm) |
Bit-identical across SIMD levels. |
| Run-time loading | ✅ | src/core/opencl/cl_loader.c:32-34 (LoadLibraryA,
dlopen), 68 (oklm_cl_load) |
The model for a HIP loader. |
| OpenCL types outside their modules | ✅ none | search for cl_mem, cl_kernel,
cl_int, clEnqueue, cl_context,
cl_command_queue outside src/core/opencl/ and
src/train/train_cl.c |
No leaks. |
| Memory shared between OpenCL and HIP | ✅ (R2) | src/train/train_cl.c (tr_cl_alloc,
shared_addr); src/core/opencl/cl_loader.c
(clSVMAlloc) |
With --backend rocm the trainer's buffers are shared
virtual memory wrapped in cl_mem; rocBLAS computes on the
same bytes. |
| The trainer's products through rocBLAS | ✅ (R2) | src/train/train_cl.c (gemm, after_rb);
tests/train/test_train_cl.c (the rocm pass) |
Large single products routed, hand-overs only on a switch; the device tests pass against the CPU; Nano 1.43 x, SmolLM2 1.26 x a step. |
| Build switches | ✅ none | Makefile:157-159 (-ldl), 239 (cl_loader.c), 535-539
(embedded kernels) |
Devices found at run time; no USE_*. |
Math and training
| Part | Status | Evidence | Notes |
|---|---|---|---|
| Training kernels, CPU and OpenCL | ✅ | src/train/layers_train.c, train_kernels.cl, declared side by side in train_internal.h | Norms, attention, GELU, SwiGLU, RoPE, dropout, cross-entropy, AdamW, gradient norm. |
| Layout | ✅ | include/oklm/core/tensor.h; train_internal.h:15-17 | Row-major; hipBLASLt is column-major (operands swapped). |
| Test harness | ✅ | tests/oklm_test.h; tests/tolerances.h:87
(TOL_TRAIN_DEVICE 1e-4); tests/train/test_train_cl.c |
Finite differences, device against CPU, llm.c oracle. |
| LoRA / adapters | ✅ (R3–R5, R7) | src/train/train.c (layout_lora,
lora_forward, lora_backward);
tests/train/test_train.c (test_lora);
tests/train/test_train_cl.c |
The paper's naming, Q/K/V and gate/up separately on the packed products; finite differences on five architectures; devices against the CPU. ADR-0020. |
| Frozen parameters | ✅ (LoRA) | src/train/train.c (G(), zero_grad, the
update over [lora_off, n_params)) |
With LoRA the model's weight gradients are never computed and AdamW covers the adapters only. |
| Activation recompute | ✅ | train.c alloc_acts, block_forward,
head_chunk, backward_rows |
recompute / oklm train --recompute: each
block's input kept, its activations computed again before its backward
pass (the same gradients to the bit); the head's logits held a chunk of
rows at a time (a frozen LoRA head's gradient taken in the forward
pass); activations 3 to 8 times smaller for 21 to 51 % more time a step
(training.md, Speed). test_train.c, test_train_cl.c
test_recompute, test_chunked_head |
| Quantized frozen base, transposed quantized product | ✅ | train.c load_packed, unpacked; train_cl.c
tr_cl_dequantize; kernels.cl dequant_rows |
quantized_base / --quantized-base: with
LoRA the blocks' matrices stay in the file's types, each unpacked into
one F32 scratch before its products (dX = dY W included), the same
results to the bit (Qwen3-4B Q4_K_M: 15.4 GB of weights to 3.8, 5 %
slower). The token embeddings and output head packed too (a token's row
unpacked as looked up, the head by tiles of rows), Qwen3-4B 2.6 GB for a
2.4 GB file. GPT-2's embeddings stay F32. test_train.c, test_train_cl.c
test_quantized_base, test_quantized_head,
test_dequantize |
| Adapter files | ✅ (R7) | src/train/checkpoint.c (write_adapter,
oklm_trainer_load_lora); src/io/lora.c
(oklm_lora_merge); apps/oklm.c (train --lora,
lora-merge, --lora) |
llama.cpp's format; llama.cpp's --lora perplexity
matches OKLM's merged model (27.3985 / 27.3989). |
Baseline
OKLM_CL_PROFILE=1 on the gfx1100, 2026-11-04: the Llama
Nano (16 x 256) spends 38.6 ms of a 47 ms step in 153 products a step
(69 %, about 3.6 TFLOP/s); the SmolLM2-135M fine-tune (4 x 4 x 128) 429
ms of a 528 ms step in 3135 products a step (69.5 %, about 3.8
TFLOP/s).
ROCm conflicts and corrections (⚠️):
- The plan's API constraint expects
hipblaslt/hipblaslt.hto be C-compatible; it is not (hipblaslt.h:54-56). The C symbols are reached through a run-time loader with OKLM's own declarations instead (decision 1). - The plan expects a HIP backend for training only; OKLM already trains on this GPU through OpenCL, so HIP brings hipBLASLt's products (69 % of a step) and nothing else: the design note proposes routing products from the trainer's OpenCL device rather than a new backend, if the two runtimes share memory.
- The plan reaches the 27B base within R7; the trainer's F32 path does not fit it in 20 GB (108 GB of weights alone), so it is split out.
MCP training
The MCP tool-use fine-tuning specification mcp_training_spec.md against what exists, for its T0 audit; the plan built on it is mcp-training-design.md. T0 is read-only: no training code. Legend as above.
| # | Item | State | Where | Note |
|---|---|---|---|---|
| T0.1 | The inference prompt and tool-call shape | ✅ | chat_template.c oklm_chat_template_render; tools.c
tools_json; agent.c:492-509; tool_calls.c
parse_hermes:378,
oklm_tool_format_detect:21 |
Qwen3's Hermes/ChatML template renders <tools> in
the system turn and the call as
<tool_call>{"name","arguments"}</tool_call>;
captured in the design note. OKLM_LOG_LEVEL=DEBUG logs each
raw turn (agent.c:2736). |
| T0.2 | Schema validation (constrain and check) | ✅ | grammar.h oklm_json_schema_to_grammar:160,
oklm_grammar_accept_text:100,
oklm_grammar_complete:107; agent.c
agent_grammar |
A tool's parameters schema becomes GBNF (ADR-0009);
generation is constrained to it, and a candidate call is checked by
accepting its text to completion. The data validator's function. |
| T0.3 | Training mechanism | ✅ (from R7) | oklm train --lora; io/lora.h
oklm_lora_merge; ADR-0020, ADR-0021;
--quantized-base |
LoRA on every backend, adapter files, a quantized base so the 8B fits 20 GB. Missing and this plan's to add: the data (T1), the hyperparameters and the validation loop (T2/T3). |
| T0.4 | Reference datasets (format only) | ✅ | tests/evals/03-mcp-tool; tests/harness/test_mcp.c | Hermes function-calling corpora share the shape; the faithful source
is capturing real oklm agent runs against the mock server.
None imported. |
| T0.5 | Evaluation harness | ✅ | tools/eval_agent.sh; tests/evals/; tests/harness/test_mcp.c:119-136 (mock MCP: echo, add, fail, big, slow) | Scripted tasks judged by what the run left; 03-mcp-tool
already calls a tool end to end; the mock server stands in for a real
one, held-out tools for T3. |
| T0.6 | Decisions | ✅ | mcp-training-design.md ## Decisions |
Data format (the in-process rendering), reasoning (a short
<think> kept, capped), base (Qwen3-8B), proceed now
(M15 and R7 done). |
| T1 | Data capture | ✅ | tools/mcp_zoo.py, mcp_data.py (tasks,
check, gate), mcp_run.sh,
make_mcp_data.sh |
The tool zoo's training tools, tasks of the five categories, each run judged (answer, the tools needed, only its tools, the answer after the results), the gate (every call parsed and fitting its schema, duplicates, a held-out tenth). 117 conversations from 200 tasks on Qwen3-8B. |
| T2 | Fine-tune (chat-data trainer) | ✅ | oklm train --chat-data --lora 16 --quantized-base --recompute;
tools/mcp_loop.sh |
Rank 16 on the Q4_K_M base, 6144-token sequences, 30 steps a round (46 min); held-out loss 0.085 to 0.061. ROCm cannot allocate the base's shared memory; OpenCL runs it. |
| T3 | Validation loop | ✅ | tools/mcp_loop.sh, mcp_data.py metrics;
oklm agent --no-tool-grammar |
Base and two rounds, the grammar off: trained tools 8 to 11 of 15 tasks, schema-valid calls 78 to 94 %; held-out tools 7 of 9 then 5; JSON always valid (mcp-training-design.md). |
T0 corrections (⚠️): none. The plan's assumptions hold — the tool-call shape, the schema path, the LoRA mechanism, the eval harness and the mock server all exist; T1 onward is data and training, not new engine code.
RAG
Audit of rag_spec.md (its K0),
2026-11-08, the same legend; ⚠️ marks a row where the spec's "What OKLM
already has" table was wrong or incomplete (corrected there). The design
built on this audit is rag-design.md, the
index file adr/0022-rag-index-format.md.
OKLM has no retrieval yet, but most of the pieces under it
exist: bidirectional attention, LayerNorm with bias, exact
GELU, rope and SwiGLU as ops (the vision and Whisper encoders already
run on them), the final hidden state of a decoder
(oklm_context_params.hidden), WordPiece and Unigram
tokenizers, products of F32 rows against F16 / Q8_0 matrices with a
top-k op (a search is one of them), an atomic GGUF writer and
memory-mapped reads, System One scoring, the agent's ToolSearch, memory
files, the debug log and the OpenTelemetry export. What is missing is
the text encoder itself, pooling, chunking, the index, BM25, the
cross-encoder and the glue.
Retrieval primitives
| Primitive | Status | Evidence | Verdict | Notes, change needed |
|---|---|---|---|---|
Encoder forward pass (bert, nomic-bert,
XLM-R) |
❌ | model.c:1166-1182 (the architectures accepted: no
bert); model_internal.h:28-32 (two families,
ARCH_LLAMA and ARCH_GPT2) |
NEW (K1) | ARCH_BERT and src/model/arch_bert.c:
post-norm blocks, token types, learned positions (bert) or
NEOX rope with SwiGLU (nomic-bert); XLM-R is written as
bert by llama.cpp's converter (rag-design.md). |
| Encoder building blocks | ✅ | ops.h:46 (LayerNorm with bias), 50 (GELU_ERF), 51
(SwiGLU), 52 (rope), 53 (GET_ROWS), 406
(bidirectional attention); vision.c:285-340 and audio.c:471
use them |
REUSE | ⚠️ the spec said "none": the vision and Whisper encoders are encoders already. On OpenCL, bidirectional attention runs on the CPU (backend_cl.c:2203): K1 adds it to the kernel or accepts the fallback, measured. No ALiBi (jina-bert-v2 left out). |
| Decoder-based embeddings (Qwen3-Embedding) | 🟡 | hf_config.c:40 (Qwen3ForCausalLM); model.h:153
(hidden), 293 (oklm_get_hidden); model.c:2069
(only ARCH_LLAMA) |
EXTEND (K1) | ⚠️ the spec said last-token pooling did not exist: the final normalized hidden state of every token is already kept on request; what is missing is taking the last row, L2-normalizing, appending `< |
| Pooling (CLS, mean, last), normalization | ❌ | none; llama.cpp's numbering (NONE 0, MEAN 1, CLS 2, LAST 3, RANK 4)
read from <arch>.pooling_type |
NEW (K1) | src/rag/embed.c; GGUF key first, else
sentence-transformers' 1_Pooling/config.json, else the
family's default. |
| Embedding tokenizer, WordPiece | 🟡 | tokenizer.h:51 (OKLM_TOK_WPM); tok_hf.c:545, 593, 623
(from tokenizer.json), 310-316
(BertProcessing: [CLS] and [SEP]
added); tok_gguf.c:111, 281-287; test_llama_vocabs.c:47, 166
(bert-bge parity with llama.cpp);
test_tokenizer_parity.c:214 |
REUSE, EXTEND (K1) | ⚠️ from a GGUF bert vocabulary OKLM adds
[CLS] but not [SEP]: add_eos
defaults to 0 and tokenizer.ggml.seperator_token_id is not
read, while llama.cpp always ends a WordPiece text with SEP
(llama-vocab.cpp:2768-2774, 3910-3936). K1 reads the separator and adds
it. |
| Embedding tokenizer, Unigram (XLM-R: bge-m3, bge-reranker-v2-m3) | ✅ | tokenizer.h:52 (OKLM_TOK_UGM, GGUF t5);
src/tok/ugm.c |
REUSE | XLM-R's GGUF uses the t5 model with
<s> … </s>; checked against llama.cpp in
K1. |
| Pair encoding (query, passage) for a cross-encoder | ❌ | none | NEW (K4) | [CLS] q [SEP] d [SEP] (WordPiece) or
<s> q </s></s> d </s> (XLM-R),
token type 1 on the passage where the model has two types. |
| Test files of the default model | ⚠️ | tests/public_models.txt:48-50 (tokenizer.json of
bge-small-en-v1.5); models/bge-small-en/config.json
(_name_or_path bge-small-en, v1) |
EXTEND (K1) | Only the tokenizer is there, not the weights; the
config.json beside it is the v1 model's. K1 adds the v1.5
weights (safetensors and GGUF) to the list with their sha256. |
| Document loaders | 🟡 | ingest.h:42-48 (text, JSON, HTML, DOCX, PDF), 61
(oklm_ingest_file), 116
(oklm_ingest_pdf_pages); ingest.c:97-110 (CRLF made LF);
oklm.c attach_doc (--doc: the whole text in
the prompt); tools.c:456 (Read of DOCX and PDF) |
REUSE, EXTEND (K2) | Offsets of chunks are offsets in the extracted text; for plain text
the line ends change, so the index keeps line numbers too. Pages are
known for PDF only (pdf_pages), kept as the chunk's
page. |
| Chunkers | ❌ | none (chunk in src/ is prefill pieces and stream pieces
only) |
NEW (K2) | Fixed, recursive (Markdown headings, paragraphs, sentences), semantic, code-aware (braces and indentation, or LSP symbols: lsp.c:770-773). |
| Vector store | ❌ | none; the parts: ops.c:233 (oklm_matmul: F32 rows
against weights of any computable type), 399 (oklm_topk);
gguf.h:394, 417 (tensors, streamed), 425; gguf_write.c:507-516
(temporary file, then oklm_file_replace); file.h:46
(oklm_file_map), 109, 245 |
NEW (K2) on REUSED parts | Vectors stored as a GGUF tensor [dim, n_chunks] in F32,
F16 or Q8_0: one query is a product and a top-k on the existing kernels
and threads (ADR-0022). |
| Model identity for the index header | ✅ | kv_file.c:180-210 (oklm_model_id: architecture, sizes,
tensor table, sampled weights) |
REUSE | The index records it with the pooling, normalization and prefixes, and refuses another model. |
| Keyword search | 🟡 | tools.c:1349 (t_grep: regular expressions,
unranked) |
NEW (K3) | BM25 (k1 1.2, b 0.75) over the chunks, postings in the index; the analyzer lowercases and splits on Unicode word boundaries (unicode.c), not the model's subwords. |
| Fusion | ❌ | none | NEW (K3) | RRF (k = 60) and weighted sums of normalized scores. |
| Reranker | ❌ | none | NEW (K4) | Cross-encoder = the K1 encoder plus cls /
cls.output (llama.cpp's names). |
| Relevance scoring by the generator | ✅ | decide.h:78 (oklm_decide_question); decide.c:237
(oklm_decide_eval: levels from one forward pass);
server.c:2444 (/v1/systemone, /v1/decide);
src/server/decide.c:208 (srv_decide) |
REUSE (K4 fallback, K5 evaluator) | A question "does this passage answer the query?" with levels relevant / partly / no gives K5's verdicts and their probabilities. |
| Evaluators (retrieval metrics) | ❌ | none: the agent evals measure pass rate, turns, tokens, time (Makefile:731, tools/eval_agent.sh, tests/evals/: 17 tasks) | NEW (K1) | oklm rag eval (recall@k, MRR, nDCG@10) and
make rag-eval (rag-design.md, "Evaluation"). |
| Tool registry | ✅ | tools.c:3300-3329 (built-in table), 3510
(oklm_tools_json); agent.c:641-694
(agent_tools: built-ins, the program's own tools, Agent /
SendMessage, ToolSearch); mcp.c:1834 (oklm_mcp_sync_tools);
tools.h:111 (searchable skills); plugins.c:124; agents.c:144 (sub-agent
definitions) |
REUSE | Every source K6 embeds is already enumerable in one place
(all_tools_json and the skills array). |
| Tool selection | 🟡 | agent.c:566 (ToolSearch's definition), 606
(is_deferred), 3671-3797 (run_tool_search);
tool_index.c:603-628 (oklm_tool_keyword_score: 3 a word in
the name, 1 in the description); prompt.c:194-275
(put_deferred: built-ins in a line, each MCP server in its
own), 356-376 (skills past the 2000-token budget left to ToolSearch);
oklm.c cmd_agent (the default deferred list and
deferredTools) |
EXTEND (K6) | ⚠️ the spec placed ToolSearch in tools.c: it is in agent.c and prompt.c. Keyword match only; K6 adds an embedding rank behind the same tool. |
| Prompt assembly, context injection | ✅ | prompt.c:277 (oklm_prompt_build); agent.c:331
(agent_push_meta: reminders); compact.c:348
(rolling_summary); oklm.c attach_doc |
REUSE | Retrieved chunks enter as a reminder (agent) or beside
--doc (run, chat), so the system prompt's bytes and the
prefix cache stay unchanged. |
| Memory | 🟡 | memory.c:701 (oklm_memory_load), 809
(oklm_memory_render); session.c:618, 1188
(oklm_session_turns), 1439
(oklm_session_list) |
EXTEND (K7) | Memory files are put in the prompt whole; transcripts are listed and replayed, never searched. |
| Caching | 🟡 | server.c:50, 79, 424-452 (media embeddings by content hash);
prefix_disk.c:167 (--prefix-dir); model.h:812
(oklm_kv_save) |
REUSE, EXTEND (K2) | Nothing caches text embeddings; the index is that cache (chunks keyed by their hash, re-embedded only when changed), and the server keeps an LRU of query embeddings. |
| Telemetry | 🟡 | telemetry.c:573 (oklm_telemetry_debug), 601
(oklm_telemetry_event), 10 (OTLP export); server.c:2295
(/api/stats); dashboard.c |
EXTEND (K5) | Retrieval decisions (queries, rewrites, hits and scores, verdicts,
fallback) as debug lines, agent events, OTLP spans and
/api/stats counters. |
| Rate limiting | 🟡 | server.c:264 (503 with Retry-After past
--queue), 330 (API keys); agent_http.c:53 (429
retried) |
REUSE | No per-key limits; embedding and rerank requests share the queue and its 503. WebSearch fallbacks capped per request (K5). |
| Web fallback | ✅ | tools.c:3195 (WebSearch through SearXNG), 2850 (WebFetch) | REUSE (K5) |
The taxonomy
| Group | Capability | Status | Evidence | Verdict | Notes, change needed |
|---|---|---|---|---|---|
| Foundational | Vector RAG | ❌ | the primitives above | NEW (K1, K2) | Encoder, chunker, index, exact search. |
| Hybrid RAG | ❌ | tools.c:1349 (Grep only) | NEW (K3) | BM25 and fusion in the same index. | |
| Graph RAG | ❌ | none | NEW (K8) | Entities and relations extracted by the generator (decide.c and grammars: grammar.h). | |
| Agentic, adaptive | Agentic RAG | ❌ | the tool table tools.c:3300 | NEW (K7) | A Retrieve tool over the project's index. |
| Adaptive RAG | ❌ | decide.c:237 | NEW (K7) on REUSE | A router question (none / one / several retrievals). | |
| Self-RAG | ❌ | decide.c:237 | NEW (K8) on REUSE | Support and usefulness scored by System One. | |
| Corrective RAG | ❌ | decide.c:237; tools.c:3195 | NEW (K5) on REUSE | Evaluator verdicts, rewrite, WebSearch, "no reliable source". | |
| Agent-centric | Hierarchical tool RAG | 🟡 | agent.c:3671 (keyword ToolSearch); prompt.c:194 (deferred tools grouped by MCP server) | EXTEND (K6) | Type to Service to Tool already shows in the prompt's grouping; the rank becomes semantic. |
| Multimodal RAG | 🟡 | vision.c:285 (SigLIP image embeddings into the language model, not a joint space); audio.c; video.c | EXTEND (K8) | Captions first, a joint encoder only if measured to be needed. | |
| Conversational, memory RAG | 🟡 | memory.c:701; session.c:1188 | EXTEND (K7) | Query rewriting from the conversation; transcripts and memory files indexed. | |
| Cross-cutting | Chunking | ❌ | none | NEW (K2) | |
| Reranking | ❌ | decide.c:237 as the only scorer | NEW (K4) | ||
| Query rewriting, expansion | ❌ | compact.c:348 (the summary turn is the nearest pattern) | NEW (K5, K7) | One generator call with a fixed prompt, logged. | |
| Evaluation harness | 🟡 | Makefile:731; tools/eval_agent.sh; oklm.c cmd_ppl |
EXTEND (K1) | make rag-eval beside make eval. |
|
| Caching, observability, budgets | 🟡 | the caching and telemetry rows above | EXTEND (K5, K9) | Token budget for injected chunks (--rag-tokens),
latency per stage. |
|
| Graceful degradation | ❌ | none | NEW (K5) | Never an invented citation; an index of another model refused, not misread. |
Capability matrix
DONE: usable as is. PARTIAL: exists, needs the change named. MISSING: new code.
| Capability | State | Change needed | Step |
|---|---|---|---|
| Encoder ops (LayerNorm, GELU, rope, SwiGLU, bidirectional attention) | DONE | the OpenCL bidirectional path (now the CPU) | K1 |
| BERT-family forward pass | MISSING | ARCH_BERT in model.c,
src/model/arch_bert.c, src/io/names_bert.c,
BertModel / XLMRobertaModel /
NomicBertModel in hf_config.c |
K1 |
| Decoder embeddings | PARTIAL | last row of oklm_get_hidden(), no output head, EOS
appended |
K1 |
Pooling, normalization, oklm_embed() |
MISSING | src/rag/embed.c,
include/oklm/rag/embed.h |
K1 |
| WordPiece from GGUF | PARTIAL | read tokenizer.ggml.seperator_token_id, add SEP |
K1 |
oklm embed, /v1/embeddings |
MISSING | cmd_embed in apps/oklm.c,
src/server/embed.c |
K1 |
| RAG evaluation | MISSING | src/rag/eval.c, oklm rag eval,
tools/rag_eval.sh, make rag-eval,
tests/rag/docs_questions.jsonl |
K1 |
| Loaders | DONE | chunk offsets, lines, PDF pages | K2 |
| Chunkers | MISSING | src/rag/chunk.c, src/rag/chunk_code.c |
K2 |
| Index, exact search | MISSING | src/rag/index.c (ADR-0022) on the GGUF writer,
oklm_matmul, oklm_topk |
K2 |
oklm rag index / search / info |
MISSING | cmd_rag in apps/oklm.c |
K2 |
| BM25, fusion | MISSING | src/rag/bm25.c, src/rag/fuse.c |
K3 |
Cross-encoder, /v1/rerank |
MISSING | cls head in arch_bert.c, oklm_rerank(),
the route |
K4 |
| Generator scoring fallback | DONE | a relevance question over decide.c | K4, K5 |
--rag in run, chat, serve |
MISSING | src/rag/pipeline.c; gen_opts beside --doc;
the server's per-request field |
K5 |
| Corrective loop, logging | MISSING | evaluator stage, rewrite, WebSearch fallback, trace in telemetry and
/api/stats |
K5 |
| Tool selection by retrieval | PARTIAL | src/harness/tool_index.c, run_tool_search
ranked by embeddings, toolSearch.mode setting |
K6 |
| Agentic, adaptive, conversational retrieval | MISSING | Retrieve tool, router, rewrite, session and memory
index |
K7 |
| Graph, self-critique, multimodal | MISSING | src/rag/graph.c, self-critique questions, captions |
K8 |
| Caching | PARTIAL | chunk-hash reuse in the index, query-embedding LRU in the server | K2, K5 |
| Telemetry | PARTIAL | retrieval events and counters | K5 |
| Rate limiting | DONE | the server's queue covers the new routes | K1, K4 |
K0 corrections (⚠️), made in the spec's table: encoders' ops exist
(the vision and Whisper encoders); decoder hidden states exist;
ToolSearch is in agent.c and prompt.c, not tools.c; a GGUF WordPiece
vocabulary gets no [SEP]; the bge files present are the
v1.5 tokenizer and a v1 config.json, no weights;
sentence-transformers needs PyTorch, which ADR-0015 rules out, so the
second reference is a numpy float64 encoder (rag-design.md, "Test
references"); the agent evals are 17 tasks.