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.