OKLMdocumentation v1.0.3
On this page

Harness

The agent harness behind oklm agent: the loop that runs a task, the tools the model calls, what decides whether a call runs, the settings and memory files, the terminal UI, sessions, and the ways to extend it. Each part has its own page; this one lists them and how the whole is tested. Day-to-day use is in user-guide.md.

Status: implemented: permissions, the audit log, the built-in tools, skills, plans, background jobs, sub-agents, the Linux sandbox and the agent loop.

Parts

  • agent-loop.md: the agent loop, the system prompt, loop details, backends and stream events, headless and library use, results on published models, the agent evals.
  • agent-tools.md: the built-in tools (the web, notebooks, questions), skills, deferred tools and ToolSearch, sub-agents, git.
  • agent-permissions.md: permission rules and modes, dangerous calls, the audit log, the sandbox.
  • agent-settings.md: settings files and every setting, usage, the debug log and telemetry, memory files.
  • agent-ui.md: slash commands and the terminal UI.
  • agent-sessions.md: context and compaction, sessions.
  • agent-extensions.md: hooks, plugins, MCP servers.
  • processes.md: background jobs, declared services, language servers, integrations.

Verification

tests/harness/test_permissions.c: the splitter on separators, quoting, escapes, comments, continuations, and the lines it must refuse (substitutions in and out of double quotes, backquotes, process substitution, subshells, unbalanced quotes); path normalization and globs; Bash rules against compound lines, quoted command names, background separators and substitutions; path rules against .., repeated slashes and symbolic links; precedence across sources; managed-only allow rules; every mode, bypass refused without the sandbox; domains against look-alike hosts and query strings; malformed rules; the standard settings files and the highest defaultMode; audit lines parsed back, secrets masked.

tests/harness/test_tools.c: Write, Read (offsets, limits, binary files, directories), Edit (unique, ambiguous, every occurrence, missing); Glob and Grep with a Read deny rule hiding a directory's files and contents, case-insensitive search, file filters; Bash output and exit codes, the project as working directory, the output limit, a timeout returning within seconds, a background process killed when the shell ends; a denied command not run, the user's refusals, "always" allowing the same commands later in any order, plan mode, the audit lines.

Skills (test_tools.c): headers with quoted values, a skill without a header named by its directory, the project's skill over the user's of the same name, the Skill tool in plan mode, an unknown name answered with the list. tests/harness/test_skills.c: precedence across the project's, .agent's, the user's and the built-in skills; each header error leaving a skill out with its file named, warnings for smaller faults, the validation function; YAML blocks, lists, quotes and comments; twenty skills with long descriptions within the prompt's budget, bodies never in the prompt, a small budget leaving skills to ToolSearch; the Skill tool's body, directory and arguments, a user-only skill refused, the built-in skill; additions, edits and removals noticed; allowed-tools running a command unasked during the request and asking again after it, a deny rule winning; deferred tools named but not defined in the prompt, loaded by ToolSearch, a skill found by words, an unknown name; a backend offered a tool once loaded; a definition's skills preloaded, a forked skill run as a sub-agent of its type; the skills loaded named after a compaction.

tests/harness/test_headless.c: stream-json lines parsed back (init, thinking and text, tool_use with its input, tool_result, the result with its usage and turns), the single JSON result, error_max_turns and its status, the text format, user messages read from JSON lines; a custom tool refused without a rule, run with one, its call without a required argument stopped before it runs, names taken refused; a PreToolUse hook as a function blocking Read with its reason; oklm_agent_cancel() from another thread.

tests/harness/test_probe.c: probes read and refused; a delay, a log line (and one printed before the wait), a command, all and any; a job ending first failing the wait at once with its last lines; a timeout; a port and an HTTP answer (a 503 refused, a 200 accepted, from a server in the test); the holder of a port named, this process's own; a job's port held by another process said before waiting; a job listening found by oklm_job_ports(); WaitFor on a job's line, a command probe refused without a rule and run with one, the last lines on a timeout.

tests/harness/test_git.c (scratch repositories, the user's git configuration kept out): detection and the snapshot; the branch and HEAD from the files, packed refs too; a merge stopped by a conflict seen; a push to the default branch, to HEAD:main, to a protected branch, with -C; an amend and a rebase dangerous only once HEAD is pushed; a commit read with -am; a staged AWS key blocking the commit, also through the Bash tool (the commit count unchanged); a .env told after the commit; a 6 MB file outside LFS; the agent told of a branch switch; a commit on main asking, not on another branch, a push to release/2.0 (the default protected list), a switch with an uncommitted file asking, not a new branch nor a restore; a merge stopped by a conflict resolved by a scripted model through Bash, Read, Write and a merge commit; a bisect the model started and left reset when its request ended. test_permissions.c test_git_classes: reads, changes and interactive forms; deny rules through global options and assignments; allow rules only past harmless ones; config writes dangerous.

tests/harness/test_process.c: a command past its timeout moved to the background, its output so far shown and not read again, its end and exit code seen; sleep stopped; the setting keeping commands in the foreground; Ctrl+B from another thread moving a command at once; ProcessOutput with a filter, nothing new the second time, BashOutput; ProcessList with the last lines; ProcessStop on two jobs, KillShell; an agent starting python3 -m http.server in the background, WaitFor on its port (told the job listens there), the URL in its answer, the request's log line read once; a harness killed with SIGKILL leaving a job whose child ignores SIGTERM, the next session finding it (and not the finished nor the detached job), stopping it and writing reaped_by in the dead session's journal; the jobs running and kept alive counted.

tests/harness/test_events.c: a burst of fourteen lines, seven errors, coalesced into one event showing the last five; the monitor's end when its job is stopped; a stop line ending a monitor and its own job; the rate cap keeping two events of three; a job's end counted without words; bad patterns and jobs refused; the Monitor tool refusing without a command or a running job, attached to a job (only the new line), and the agent told a monitor's event at its next turn.

tests/harness/test_lsp.c (clangd, when installed): Read opening the files, the server a job of kind lsp; an Edit making twice("21") getting LSP: 1 new error at main.c:3; a later edit not repeating it; the diagnostics, a definition across files, references, hover, the document's symbols, a rename preview that changes nothing; an unknown operation and a file without a server refused; the server stopped at the end; a server not installed told once, no job started.

tests/harness/test_jobs.c: output and exit codes, reading from an offset, a job killed with the process it started in the background, owned jobs stopped at close, a detached job outliving the harness then re-attached and seen finishing, a job of a dead process recorded as interrupted, an owned job killed when its harness process is killed, old sessions removed; a job's kind, label, directory, owner, times and environment markers, read back from the journal; readers with their own places, escapes and carriage returns, filter, tail and cap; a log rotated past its cap; a failing job restarted twice with growing delays; the limit refusing a third job and listing the two; a stop command, a grace, a grandchild ignoring SIGTERM gone; close in reverse order, a job kept alive left running; Bash in the background, JobOutput (offsets), JobKill, and Detach refused by default then allowed by a rule.

tests/harness/test_sandbox.c (skipped without user namespaces), by escape attempts: writing next to the project and in the home directory fails, a file written in /tmp is gone afterwards, unshare -U fails, the network namespace holds only the loopback, while the project stays writable, the user's id is kept, NoNewPrivs is 1 and the seccomp filter is in force; the command is process 1, sees only its own processes and cannot signal the test's; a Read deny rule's file reads empty and its directory lists nothing and takes no file, an Edit deny rule's file stays readable but not writable, the rest of the project stays writable and the real files are untouched; the five limits are in force, confined and not, and a confined command cannot start more processes than allowed; a confined background job cannot write outside the project.

tests/harness/test_agent.c: a scripted model writing two tool calls in two turns then an answer: the calls run, their results (the file written, the command's output) are in the next prompt, the conversation carries over to the next message and resets; skills listed in the system prompt; a background job's end told before the next turn; a sub-agent's report (its reasoning stripped) as the Agent result, the sub-agent refused an agent of its own, Agent asking by default; a background sub-agent held until the agent has gone on to its next call, its report (reasoning stripped) in the agent's last prompt after the interim answer, its write outside the project refused since it cannot ask; a second background agent over the limit refused, and an endless one stopped when the agent is freed; two calls in one turn run in order, each with its result; a denied command is not run and its refusal reaches the model; a model that never answers stops at the turn limit. With a fixture replayed by the mock: reasoning, a Read call and the answer, the events in order (TOOL_CALL after the turn's STOP, a last STOP ending the message), usage, the second request carrying the call with its arguments as a string and its result under its id; a <think> block in the content reported as reasoning and kept out of the history; an interrupt after two words (the history keeps them, the next message runs), an interrupt after the first of two calls (the second answered "Interrupted by the user" without running); sleep 20 killed 0.3 s after an interrupt; the HTTP backend's chunks with two tool calls in fragments. tests/server/test_server.c: the agent over the HTTP backend against the server (pieces streamed, the server's usage and finish reason), and on the in-process model (the turn's token limit as its stop, the second message reusing the cached prompt, an interrupt stopping generation after two tokens).

Next

The Windows restricted token and low-integrity ACLs of ADR-0011, and the HTTPS API and GUI over the agent (M8).