Skip to content

Local headless agent runs requirements

These requirements track the live implementation of the local headless agent runs specification.

ID Requirement Implementation Verification Documentation Evidence
HLR-001 Package users can open and close a supported local runtime with documented config, dotenv, runtime-layout, session, snapshot, notification, and resource-ownership behavior. Implemented Automated Documented test_local_agent_runtime.py; user guide
HLR-002 The local runtime lists configured agent IDs deterministically without making a provider request. Implemented Automated Documented Python runtime and CLI agent-list tests; user guide
HLR-003 Python and CLI callers can inspect safe configured-agent display metadata, provider route/plugin identity, effective model/reasoning defaults, and flattened config schema without exposing credentials or making a provider request. Implemented Automated Documented Runtime and agents --details tests; agent discovery
HLR-004 Python list_models(agent_id) and CLI models --agent ID expose the existing generic provider, extension, and feature model discovery using the agent's effective configuration and shared cache; complete JSON descriptors and readable text preserve order without creating a session or sending an inference request. Implemented Automated Documented Core public discovery/cache tests, runtime catalog tests, and CLI subprocess tests passed; clean macOS source-install smoke passed on 2026-10-06. The shared archive/Bash/PowerShell smoke helper includes both discovery checks; other native targets were not rerun for this addition. Model discovery
HLR-010 One natural Python run(...) call starts a persisted session selected by agent_id or continues one selected by session_id. Implemented Automated Documented test_open_runtime_runs_and_follows_up_with_bounded_progress; Python first run
HLR-011 Synchronous request admission and message append are atomic through the shared coordinator, and rejected same-session admission does not append. Implemented Automated Documented test_synchronous_message_run_is_atomic_and_returns_success; test_same_session_rejection_does_not_append_losing_prompt; request execution
HLR-012 Python callers can receive ordered bounded progress without polling events or receiving full tool/native/binary payloads by default. Implemented Automated Documented Runtime progress and deterministic long-tool tests; progress guide
HLR-013 Every completed Python run returns a compact structured success, failure, cancellation, or interruption result with session, request, agent, output, final-message, and safe error information but no complete serialized session. Implemented Automated Documented Structured success/failure/cancel/interrupted tests; results
HLR-014 A completed run's session ID supports a subsequent follow-up that uses the persisted prior conversation and the same configured agent. Implemented Automated Documented Python and subprocess follow-up tests; follow-up guide
HLR-015 Python overrides and repeated CLI --set KEY=VALUE assignments apply generic request-scoped provider/plugin settings without mutating source config or stored session settings. Implemented Automated Documented Runtime and headless CLI tests; request-scoped settings
HLR-016 Python persistence="ephemeral" and CLI --ephemeral run the ordinary coordinated tool loop with progress, timeout, cancellation, and structured results while writing no canonical session; ephemeral identities cannot be continued by session ID. Implemented Automated Documented Runtime and subprocess no-session-file tests; non-retained runs
HLR-020 Ordinary Python futures and shell jobs can execute distinct sessions concurrently while existing same-session process-local single-flight remains authoritative. Implemented Automated Documented Python-futures and concurrent-CLI subprocess tests; parallel Python; parallel shell
HLR-021 Timeout and user interruption cancel through the application request ID, preserve the last valid checkpoint, and produce documented result or exit behavior. Implemented Automated Documented Synchronous timeout, runtime cancellation, CLI timeout, and POSIX SIGINT tests; cancellation and exit codes
HLR-030 Python callers can retrieve a named deterministic compact history projection with canonical indices, range-before-role semantics, newest-row retention, per-message and total content budgets, and explicit omission/truncation state. Implemented Automated Documented test_history_projection.py; runtime and CLI history tests; compact history
HLR-031 Compact tool rows prefer safe concise display metadata, exclude unrestricted native/binary/heavy fields, and provide deterministic bounded fallbacks. Implemented Automated Documented Long-tool projection, metadata-exclusion, and non-text-content tests; compact history
HLR-032 A caller can explicitly retrieve one canonical message in full by Python-style index, and neither full lookup nor projection mutates or duplicates persisted history. Implemented Automated Documented Canonical full-message and immutability tests; Python/CLI full lookup tests; command-line history
HLR-040 crystal-lattice agents exposes configured agent IDs in stable text and JSON forms. Implemented Automated Documented test_agents_and_json_run_follow_up_and_history; prerequisites
HLR-041 crystal-lattice run supports exactly one new/existing-session selector and one prompt argument/file/stdin source, emits bounded progress on stderr, and emits only final text or one structured JSON result on stdout. Implemented Automated Documented test_headless_cli.py prompt-source, JSON, text, long-tool, and argument tests; command-line runs
HLR-042 crystal-lattice history exposes compact ranged history and explicit full-message retrieval in stable text and JSON forms. Implemented Automated Documented Headless CLI history tests; command-line history
HLR-043 One-shot commands use stable success, usage, failure/interruption, timeout, and interrupt exit behavior and remain usable through ordinary distinct-session shell parallelism. Implemented Automated Documented Headless CLI failure, timeout, SIGINT, usage, and parallel subprocess tests; exit codes
HLR-050 Existing synchronous/background coordination, events, terminal behavior, session persistence, configuration, and application cleanup remain compatible; HTTP and frontend contracts are unchanged. Implemented Automated Documented Core default suite: 541 passed, 1 xfailed; application default suite: 481 passed, 1 skipped; request execution
HLR-051 Current package-user documentation provides verified first-success, progress, result, follow-up, history, concurrency, cancellation, configuration, persistence, and troubleshooting guidance for Python and CLI users. Implemented Automated Documented Local headless agent runs; docs preparation and MkDocs build
HLR-052 Deterministic automated coverage exercises public Python and real subprocess boundaries, including streaming, tools, long output, failures, cancellation, timeout, follow-ups, concurrency, clean JSON, and canonical-history preservation. Implemented Automated Documented test_local_agent_runtime.py; test_headless_cli.py; test_history_projection.py; test_session_request_coordinator.py
HLR-060 An independently enabled system-message section obtains explicit runtime/configuration values and accurately tells agents in externally launched projects how to invoke the installed CLI, import the supported Python API, use the applicable interpreter, and find installed documentation across supported source and bundled layouts. Implemented Automated Documented test_crystal_lattice_access_system_message.py; test_runtime_layout.py; test_python_runtime_package_builder.py; external-project guidance
HLR-061 An explicitly gated real Ollama API test using glm-5.3-flash:cloud gives an outer configured agent a sparse request to use a subagent and proves that the guidance causes an actual Crystal Lattice CLI invocation against the same config/session root and a separately persisted completed worker session. Implemented Automated Documented test_crystal_lattice_access_ollama_api.py; post-change gated real API run passed in 94.45 seconds with a separately persisted subagent-worker session
HLR-062 The config-owned parent delegation section clearly separates parent instructions, the selected child's configured system/developer message, and the self-contained child user prompt constructed by the parent; it covers setting selection, progress, result checks, persistence, and follow-ups. Implemented Automated Documented All-agent compiled-message tests; external-project delegation
HLR-063 An explicitly gated real Ollama behavior test gives the parent a sparse, safe project-review request and verifies that it constructs and runs a self-contained ephemeral child assignment, returns the finding, and leaves no child session in the shared store. Implemented Not run Documented test_glm_ollama_constructs_ephemeral_self_contained_review; requires explicit cloud-model gate
HLR-064 An explicitly gated real OpenAI behavior test uses gpt-5.6-luna as the parent and requests a gpt-6-luna ephemeral child through the same config, verifying the actual child model, separate configured instructions, self-contained read-only assignment, correct review result, and no child saves or snapshots. Implemented Automated Documented test_luna_parent_delegates_ephemeral_self_contained_review; macOS real ChatGPT run passed on 2026-10-06 in 144.94 seconds with bounded provider/session-store observations and unchanged fixture assertions
HLR-065 Full and CLI-only access guidance advertise one generic model-list command, full guidance includes the SDK call, and a gated real parent-agent run with a sparse model-discovery prompt proves use of the production model-list surface and returns the discovered Luna IDs. Implemented Automated Documented Compiled access-guidance tests passed; test_luna_parent_discovers_models_from_access_guidance passed on macOS on 2026-10-06 in 112.41 seconds. The real gpt-5.6-luna parent used the advertised CLI command, discovered 11 model descriptors, and reported gpt-5.6-luna and gpt-6-luna. Model discovery
HLR-070 Local headless runs remain distinct from durable model-facing subagents and do not claim parent-child sessions, mid-run input, detached lifetime, result recovery, or vendor-compatible subagent tools. Implemented Not applicable Documented Specification non-goals and public guide; no subagent, HTTP, or frontend contract changes
HLR-080 Default system-message configuration contains explicit full CLI+SDK and CLI-only access text with mutually exclusive predicates; helper code owns only validation, gating, and UI contribution. Implemented Automated Documented Default-config inspection and all-agent compilation tests; system-message configuration
HLR-081 The access UI identifies full or CLI-only mode and remains visible but disabled with a concrete reason when no valid CLI capability exists; a persisted true override cannot compile invalid guidance. Implemented Automated Documented Helper predicate/UI, terminal rejection, and mobile/desktop component tests; external-project guidance
HLR-082 Source, direct archive/manual, Bash-installed, and PowerShell-installed runtimes execute deterministic tasks through both their real CLI and Python SDK entry points and verify every required access value on applicable native targets. Implemented Automated Documented Clean macOS ARM64 source smoke plus all native archives/installers passed in run 34999315316; cross-reference CLI distribution requirements
HLR-083 A release-gated OpenRouter model uses production tools and config-owned guidance to create separately persisted child sessions through both CLI and SDK routes on all six native release targets without exposing its credential to tool or child environments. Implemented Automated Documented anthropic/claude-haiku-4.5 passed both routes on all six native targets in run 35062591328; tool-call, child-session, marker, runtime-identity, and credential-isolation assertions enforced
HLR-084 Permanent component coverage plus one-off Detox evidence verifies full, CLI-only, and unavailable native UI presentation and disabled behavior. Implemented Automated + one-off native Documented Mobile/desktop component tests; one-off iOS Detox run passed on iPhone 17 Pro and temporary harness/test changes were removed

Current-state note

Requirements HLR-080 through HLR-084 are implemented, verified, and documented.

Session-query refinement requirements

These implemented requirements refine the local Python and one-shot CLI surfaces through the session and message data query specification.

ID Requirement Implementation Verification Documentation Evidence
HLR-090 LocalAgentRuntime lists plugin-filtered session summaries and complete canonical message ranges with optional JSONPath include/exclude projection while preserving history(...) and get_message(...). Implemented Automated Documented Local-runtime tests; source and packaged SDK smokes; query guide
HLR-091 crystal-lattice sessions uses the active plugin filter schema and emits exact JSON plus composable text/TSV/CSV projections, including one undecorated session ID per line when selected alone. Implemented Automated Documented CLI subprocess and renderer tests; session CLI
HLR-092 crystal-lattice messages queries one session range, supports generic include/exclude projection and JSON/text/TSV/CSV output, and composes safely in a sessions shell loop. Implemented Automated Documented CLI subprocess chaining and invalid-input tests; message CLI
HLR-093 Existing agents, run, compact history, full-message lookup, stdout/stderr separation, exit behavior, and external-project access guidance remain compatible and document the new low-level commands only after verification. Implemented Automated Documented Existing headless suites; compiled access-guidance tests; source/archive/installer smokes; external-project guidance

Requirements HLR-090 through HLR-093 are implemented, verified, and documented.