zeph-core

Core agent loop, configuration, context builder, metrics, vault, and sub-agent orchestration for Zeph.

Overview

Core orchestration crate for the Zeph agent. Manages the main agent loop, bootstraps the application from TOML configuration with environment variable overrides, and assembles the LLM context from conversation history, skills, and memory. Includes sub-agent orchestration with zero-trust permission grants, background execution, filtered tool/skill access, persistent memory scopes, lifecycle hooks, persistent JSONL transcript storage with resume-by-ID, A2A-based in-process communication channels, and /agent CLI commands for runtime management. All other workspace crates are coordinated through zeph-core.

Key modules

Re-exports: Agent, content_hash, DiffData

Configuration

Key AgentConfig fields (TOML section [agent]):

Key InstructionConfig fields (TOML section [agent.instructions]):

[!NOTE] zeph.md and .zeph/zeph.md are always loaded regardless of auto_detect. Use --instruction-file <path> at the CLI to supply extra files at startup without modifying the config file.

[!TIP] Instruction files support hot reload — edit any watched .md file while the agent is running and the updated content is applied within 500 ms on the next inference turn. The watcher starts automatically when at least one instruction path is resolved.

Key LspConfig fields (TOML section [agent.lsp], requires lsp-context feature):

[agent.lsp]
enabled = true
mcp_server_id = "mcpls"
token_budget = 2000

[agent.lsp.diagnostics]
enabled = true
max_per_file = 20
max_files = 5
min_severity = "error"

[agent.lsp.hover]
enabled = false
max_symbols = 10

[agent.lsp.references]
enabled = true
max_refs = 50

[!NOTE] LSP context injection requires the mcpls MCP server to be configured. If mcpls is unavailable, hooks degrade silently — the agent continues normally with no LSP context injected. Enable via --lsp-context CLI flag or zeph init wizard.

Key DocumentConfig fields (TOML section [memory.documents]):

Key MemoryConfig fields (TOML section [memory]):

Key CompressionConfig fields (TOML section [memory.compression]):

Key CompressionGuidelinesConfig fields (TOML section [memory.compression_guidelines]):

[!NOTE] archive_tool_outputs requires the compression-guidelines feature flag. categorized_guidelines is also gated behind compression-guidelines. Both are disabled by default and must be explicitly opted in.

[agent]
auto_update_check = true   # set to false to disable update notifications

Set ZEPH_AUTO_UPDATE_CHECK=false to disable update notifications without changing the config file.

Key DebugConfig fields (TOML section [debug]):

[!TIP] Use --debug-dump without a path to use output_dir from config. Use --debug-dump /tmp/mydir to override for one session. The /debug-dump [path] slash command enables it mid-session without restarting.

Key LoggingConfig fields (TOML section [logging]):

[logging]
# Omit to use the default user-data log path.
# file = "/absolute/path/to/zeph.log"
level = "info"
rotation = "daily"
max_files = 7

[!NOTE] Use --log-file <PATH> at the CLI to override the log file path for one session. The file-level filter is independent of RUST_LOG — stderr output and file output can use different levels simultaneously. The /log slash command shows the active config and tails recent entries.

Skill commands

[!TIP] /skill reject provides the strongest feedback signal. The rejection is persisted with a FailureKind discriminant to the outcome_detail column and immediately updates the Wilson score posterior for Bayesian re-ranking.

Self-learning configuration

Key AgentConfig.learning fields (TOML section [agent.learning]):

Key LlmConfig fields (TOML section [llm]):

# Example: use Claude Haiku for summarization, primary model for inference
[llm.summary_provider]
type = "claude"
model = "claude-haiku-4-5-20251001"

Sub-agent Commands

In-session commands for managing sub-agents:

Sub-agents run as independent tokio tasks with their own LLM provider and filtered tool executor. Each sub-agent receives only explicitly granted tools, skills, and secrets via PermissionGrants. Conversation history is persisted as JSONL transcripts with .meta.json sidecars, enabling session resumption via /agent resume <id> <prompt> — the resumed agent inherits the original definition, tools, and full message history.

Lifecycle hooks can be attached at two levels: config-level SubagentStart/SubagentStop hooks (in [agents.hooks]) fire on spawn and completion, while per-agent PreToolUse/PostToolUse hooks (defined in the agent YAML frontmatter) fire around each tool call, matched by pipe-separated tool-name patterns. All hooks run as shell commands in an env-cleared sandbox with configurable timeout and fail-open/closed policy.

Plan Commands

In-session commands for task orchestration (requires orchestration feature):

[!NOTE] When confirm_before_execute is enabled (default), /plan <goal> stores the plan in a pending state. Run /plan confirm to start execution or /plan cancel to discard.

[!NOTE] /plan resume applies when a graph is paused by the Ask failure strategy — the agent waits for user direction before continuing. /plan retry re-queues all Failed tasks in the graph for re-execution.

Key OrchestrationConfig fields (TOML section [orchestration]):

Experiment Commands

In-session commands for autonomous self-experimentation (requires experiments feature):

[!NOTE] Only one experiment session can run at a time. Starting a new session while one is active returns an error. Use /experiment stop to cancel the current session first.

Agents management CLI

zeph agents provides CRUD management of sub-agent definition files outside of a running session:

[!TIP] The same CRUD operations are available interactively in the TUI agents panel — press a in the TUI to open the panel, then c (create), e (edit), d (delete), Enter (detail view).

Features

Installation

cargo add zeph-core

Documentation

Full documentation: https://bug-ops.github.io/zeph/

License

MIT