API Reference lemon_core v#0.1.0

Runtime hot-reload helpers built on BEAM code loading primitives.

LemonCore provides shared primitives for the Lemon umbrella.

Direct request/reply channel from a run's tool execution to the ACP client handler that owns the client connection for that run.

Application supervisor for the LemonCore OTP application.

Struct representing a binding between a transport chat/topic and a project configuration.

Canonical binding resolver shared by gateway and channels.

Runtime build and release metadata for support surfaces.

Process-safe PubSub for cross-app event communication.

Transport-specific chat identification.

Persistent sticky execution state for a chat scope.

Typed wrapper for chat-state persistence.

Shared checkpoint store and filesystem rollback operations.

Time utilities for Lemon.

Canonical Lemon configuration loader.

Agent behavior configuration.

Feature flag configuration for Lemon.

Gateway configuration for Telegram, SMS, and engine management.

Helper functions for configuration resolution.

Logging configuration for file output and log levels.

Modular configuration interface for Lemon.

LLM provider configuration for API keys and base URLs.

TUI (Terminal User Interface) configuration for themes and debug mode.

Minimal TOML patch helpers for targeted table key updates.

Tools configuration for web search, fetch, and WASM tools.

Exception raised when configuration validation fails.

Validation utilities for Lemon configuration.

ETS-backed cache for merged Lemon configuration.

Raised when a LemonCore.ConfigCache ETS table name is already taken by another process — mirrors LemonCore.Store.ReadCache.CollisionError.

Exception raised when the ConfigCache is not available or encounters an error.

Central orchestrator for runtime config reload.

Change detection via source fingerprinting for the config reloader.

File-system watcher for config reload triggers.

Shared default working-directory resolver for gateway and channels runtimes.

Simple TTL-based deduplication backed by ETS.

Semantic router-to-channels delivery contract.

Semantic delivery route from router to channels.

Runs the Lemon doctor check suite and builds the aggregate diagnostic report used by CLI and support tooling.

CLI entrypoint for generating Lemon doctor support bundles and reporting failed diagnostics to stderr.

Redacted Telegram and Discord configuration diagnostics for support bundles.

Redacted launch-gate readiness for promoted Telegram and Discord channels.

A single diagnostic check result.

Redacted diagnostics for the preview checkpoint store.

Checks ACP preview proof readiness from redacted stdio proof artifacts.

Checks browser preview proof readiness from redacted local smoke artifacts.

Checks Telegram and Discord channel readiness from redacted diagnostics.

Validates Lemon configuration files.

Checks cron preview proof readiness from redacted smoke artifacts.

Checks extension/plugin supportability proof state.

Checks LSP preview proof readiness from redacted language-server smoke artifacts.

Checks MCP preview proof readiness from redacted smoke artifacts.

Checks media provider and channel-delivery readiness from redacted proofs.

Checks that required system binaries are available on PATH.

Checks OpenAI-compatible API preview proof readiness.

Checks that at least one AI provider is configured.

Checks Lemon runtime health: port availability and running apps.

Checks encrypted secrets readiness.

Checks skill store integrity and directory layout.

Checks terminal backend live-proof readiness from redacted proof artifacts.

Checks usage aggregate and quota visibility.

Redacted diagnostics for cron jobs and scheduled-run history.

Redacted extension/plugin directory diagnostics for support bundles.

Redacted diagnostics for local live-proof artifacts.

Shared launch-gate summaries derived from redacted proof diagnostics.

Redacted provider setup diagnostics for support bundles.

Compact redacted launch-readiness summary for operator surfaces.

Aggregates diagnostic check results and renders them as text or JSON.

Config-injected module references for diagnostics owned by other apps.

Builds sanitized support bundle archives from doctor reports, runtime diagnostics, proof metadata, and selected configuration files.

Minimal .env loader for Lemon runtime processes.

Shared engine identifier catalog for validation and normalization.

Optional bridge to the engine runtime, without compile-time coupling.

Behaviour for execution runtimes used by router run processes.

Typed, declarative environment-variable registry for Lemon.

Environment variables read by lemon_core — the platform primitives (store, secrets, logging, retries), the standard platform/release variables no single app owns, and — until their readers move out in plan 1.10 — the variables lemon_core's own Config.* modules resolve on other apps' behalf.

Contract for a module that declares environment variables.

A single resolved environment variable, as produced by LemonCore.Env.snapshot/0.

Canonical event envelope used on the Bus and in persisted streams.

Optional bridge for subscribing/unsubscribing external event fanout.

The registry of typed LemonCore.Bus payloads — the platform's wire format.

A single unit of engine activity — a tool call, command, file change, search, subagent or reasoning step. Carried inside LemonCore.Events.EngineAction.

A tool execution awaiting a human decision. Carried inside the approval events and stored verbatim in LemonCore.ExecApprovalStore.

A tool call is blocked awaiting approval. Published on exec_approvals, where two chat plugins, the ACP server and the requesting process itself are listening.

A pending approval was decided, denied or timed out. Published on exec_approvals.

The engine's terminal result for a run. Carried inside LemonCore.Events.RunCompleted.

A configuration reload raised. Published on system.

Configuration was reloaded successfully. Published on system.

A cron job was created, updated or deleted. Published on cron; the specific transition is the LemonCore.Event type (:cron_job_created, :cron_job_updated, :cron_job_deleted). Deletions carry no job record.

A durable cron lifecycle/audit action was recorded. Published on cron.

A cron job (or timer heartbeat) finished, successfully or not. Published on cron.

A cron job (or timer heartbeat) began executing. Published on cron.

The scheduler ticked. Published on cron once a minute.

A chunk of streamed answer text. Published on run:<run_id> and forwarded to session:<session_key>. The highest-volume payload on the bus.

An engine action started, progressed or finished. Published on run:<run_id> and forwarded to session:<session_key>; it is what drives tool-status surfaces in chat channels and the web UI.

A durable goal's lifecycle changed. Published on goals and session:<session_key> by LemonAgent.Workspace.GoalStore; the specific transition is the LemonCore.Event type (:goal_set, :goal_paused, :goal_resumed, :goal_completed, :goal_cleared, :goal_continuation_submitted, :goal_loop_verdict, :goal_loop_status).

A heartbeat returned a non-OK status. Published on cron.

A healthy heartbeat response was suppressed rather than delivered. Published on cron.

Shared scaffolding for typed LemonCore.Bus payloads.

A finalized run's outcome, keyed by task fingerprint, for router-owned model selection. Published on routing_feedback by lemon_memory and consumed by lemon_router.

A run reached a terminal state, successfully or not. Published on run:<run_id>.

The router's run process terminated abnormally without the engine reporting a completion. Published on run:<run_id>.

A run moved between lifecycle phases. Published on run:<run_id> by both the gateway run process and the router's phase publisher.

A run has begun executing on an engine. Published on run:<run_id>.

A stored secret was added, updated or removed. Published on system.

A session's talk mode changed. Published on system.

Typed wrapper for execution approval policy and pending-request tables.

Tool execution approvals (shared).

Queue-semantic-free execution command shared across router/runtime boundaries.

Extension package manifest discovery and validation.

Code-free extension registry validation and update audit.

Unified gateway configuration access.

Thin wrapper around Erlang's :httpc.

ID generation utilities for Lemon.

Idempotency service for deduplicating operations.

Typed wrapper for persisted idempotency entries.

Normalized inbound message type (shared).

Canonical introspection event API.

Typed wrapper for introspection event persistence.

Runtime logging setup for Lemon.

Helpers for accessing map keys that may be stored as either atoms or strings.

Filesystem layout used by lemon_core.

Typed wrapper for policy domain storage.

Typed wrapper for progress-message to run mapping.

Typed wrapper for project binding tables.

Enforces architecture boundaries for umbrella dependencies and module references.

Renders and validates the generated dependency-policy section in the architecture boundaries document.

Canonical source of truth for architecture dependency policy.

Enforces explicit architecture guardrails that are easier to express as stable source-pattern checks than dependency graph rules.

Scans and prunes stale agent-loop run artifacts.

Loads and validates docs catalog metadata used by quality checks.

Lints documentation metadata and link integrity.

Session identifier for resuming interrupted CLI sessions.

Shared retry backoff utilities extracted from duplicated implementations across lemon_channels and lemon_gateway.

Optional bridge to :lemon_router without compile-time coupling.

Dedicated store for run history, isolated from the main Store GenServer.

Outcome labels for finalized runs.

Canonical end-to-end lifecycle phases for a run across router and gateway.

Helper for canonical run phase change payloads emitted by router and gateway.

Legal canonical run phase transitions across router and gateway boundaries.

Canonical run submission contract shared by router-facing callers.

Typed wrapper for run lifecycle and history persistence.

Orchestrates the Lemon runtime boot sequence.

Environment resolution for Lemon runtime startup.

Health and readiness checks for the Lemon runtime.

Runtime profiles for Lemon.

Encrypted secrets storage backed by LemonCore.Store.

Cryptographic helpers for encrypted secret storage.

Behaviour for master key providers.

Master key provider backed by an environment variable.

Master key provider backed by a file on disk.

Master key provider backed by the macOS Keychain.

macOS Keychain integration for Lemon secrets.

Master key resolution and initialization for encrypted secrets.

Session key generation and parsing.

Persistent key-value store with pluggable backends.

Behaviour for pluggable storage backends.

In-memory ETS-based storage backend.

Registration and safe invocation of LemonCore.Store extension points.

Persistent JSONL-based storage backend with dynamic table support.

Public ETS read-through cache for high-traffic Store domains.

Raised when a LemonCore.Store.ReadCache ETS table already exists but is owned by a process that is not the store instance claiming it.

SQLite-backed storage backend with optional ephemeral tables.

Shared projection logic for mapping child-run progress into parent task surfaces.

Telemetry event helpers for Lemon.

Behaviour for terminal/process execution backends.

Runtime policy checks for terminal/process backends.

Registry for terminal execution backends.

Docker container shell backend.

Local host shell backend.

Local host PTY shell backend backed by util-linux script(1).

SSH remote shell backend backed by OpenSSH.

Test harness for constructing test environments with sensible defaults.

Shared deterministic synchronization primitives for async test suites.

Test case module that provides the testing harness.

Test harness struct containing all test resources.

Helper functions for tests.

Shared helpers for keeping non-integration tests isolated from ambient machine state.

Minimal RFC 9562 UUID generation.

Detects and migrates deprecated configuration sections.

CalVer version parsing and comparison for Lemon.

Redacted aggregate usage diagnostics for operator surfaces.

Typed wrapper for shared usage records, summaries, and quota counters.

Regenerate the dependency policy section of docs/architecture_boundaries.md.

Runs the benchmark suites in bench/ and prints their results.

Show redacted Telegram and Discord launch readiness.

Scans test files for duplicate defmodule names.

Scan cleanup candidates and optionally prune old run artifacts.

Validate and inspect Lemon configuration.

Runs structured diagnostics across Lemon's configuration, secrets, runtime, providers, system tools, and skills store.

Validates Lemon extension package manifests without loading extension code.

Print every mix lemon.* task grouped by purpose.

Query and display agent introspection events from the Lemon store.

Show redacted local proof artifact status.

Run quality checks that keep harness docs and architecture boundaries healthy.

Show a compact redacted launch-readiness summary.

Reports the resolution source for each known secret — whether it resolves from the encrypted store, from an env var, or is missing entirely.

Deletes a secret by name.

Scans known secret env var names and imports any that are set in the environment but not already present in the encrypted store.

Initializes the encrypted secrets master key.

Lists stored secrets (metadata only, no plaintext values).

Stores a secret value in the encrypted secrets store.

Shows master key status and secret count.

One-time migration tool from JSONL-backed Lemon store data to SQLite.

Stage-1 Lemon update: config migration and bundled-skill sync.

Show redacted usage, cost, token, and quota diagnostics.