KogenAI/kogen-loop

Standalone Go agent-loop library and CLI, using only the standard library. It repeats model requests → tool calls/results until a terminal call (default finish) or a no-call answer. An ending is a model claim, never proof of completion: the host decides what counts as done. Kogen retains delivery policy; this component does not execute shaping, approval, verification, review, commits or checkpoints.
## Start here
Caller contract v1: library loop/v1, process protocol kogen-loop/v1, strict tasks, events, errors, usage and cancellation.
Public schema (api/) and engine (loop/): independently callable Go interfaces, optional host hooks and standalone sessions.
Conformance tests and recorded fixtures: offline library and built-process behavior.
Testing rules.
Apache-2.0 license and NOTICE.
Extraction and reconciliation record, full reference manifest, and original candidate README.
## Build and run
Use Go 1.27.2 (see go.mod). No Cobra, Viper or third-party module dependencies are selected.
sh
go build -o bin/kogen-loop ./cmd/kogen-loop
bin/kogen-loop capabilities --json
bin/kogen-loop run --task task.json
bin/kogen-loop run --task - .json) remain compatible; no credentials are migrated or bundled. The one exception is openai-compatible: its saved key now carries the origin it was logged in for (Client.LoginWithBaseURL) and is sent only there, so a key saved earlier must be saved again; see the contract.
The CLI supports private atomic transcript resume (sessionresume: "transcript"), not Kogen checkpoints. Subagents and compaction are unsupported. Over-budget requests are refused rather than clipped. Missing usage is null, not estimated. Tool text is bounded to 16384 UTF-8 bytes (first 4096 kept); intercepted host outputs remain host-owned. These limits are fixed, not options: the 524288-byte input window (a smaller model-family bound still applies), the documentation tool's 16384-byte result and 8388608-byte response prefix, the provider's own parallel tool-call behavior and three default cache breakpoints. Cancellation and deadlines terminate shell process groups, including one that is still starting, before returning, and every round ends the groups it started whether it succeeds or fails (background processes live between its calls).
Shell calls have no per-call time limit (the shell definition says Commands have no time limit.); the lower-level sys.Options.Timeout and its custody observation are independent sys options. See the caller contract. The standalone whole-round deadlineseconds is a context deadline. Native membership observation includes zombies on Darwin (numeric KERNPROCPGRP) and Linux. Linux first uses kill(-pgid, 0) as a monotone presence witness: success or EPERM means the group is present, with no readable /proc needed, and pgid <= 1 is rejected before any kill. ESRCH alone never proves absence: Linux then enumerates /proc (zombies, state Z, included) and reads the group after the final ) of each stat. Entries that vanish (ENOENT/ESRCH) are skipped; unreadable entries (EPERM/EACCES) and malformed stat are remembered, and a later membership witness wins over them. Without a witness, any remembered error or listing failure is an observation failure; only ESRCH plus a complete error-free scan with no member is absent. A hidepid=1/noaccess mount makes final confirmation fail rather than report absence; with hidepid=2 (invisible) a hidden live member still cannot become absent because kill is a presence witness. Status as of 27 October 2026 (history): research had reproduced the ESRCH defect on Linux; this correction was source-qualified on Darwin and cross-built, with Linux runtime proof pending at delivery. A cross-build does not prove lifecycle behavior. Commit c7e8331 fixed two Linux test flakes; both tests passed 50/50 on eu2. Other platforms return sys.ErrTimeoutObservation after timeout signalling/teardown. Failed observation returns an empty result and that stopping error even without a context, never tool feedback.