odek

README

odek

Minimal Go autonomous agent runtime — tiny dep tree, small static binary, instant startup.

One binary. One loop. Zero frameworks. ReAct (Reasoning + Acting) — think, therefore act.

# Install (requires Go ≥ 1.25.12 — see "Build requirements" below)
go install github.com/BackendStack21/odek/cmd/odek@latest

# Use (set ODEK_API_KEY, DEEPSEEK_API_KEY, or OPENAI_API_KEY)
export ODEK_API_KEY=sk-...
odek run "How many lines in go.mod?"
# → 3 lines

Build requirements: Go 1.25.12 or newer. The go directive in go.mod pins this floor because earlier 1.25.x toolchains ship reachable standard-library CVEs; CI additionally runs govulncheck on every push/PR so new advisories fail the build.

---

Why odek

odek is not a framework. It's a runtime — the smallest possible surface area between an LLM and your tools.

	odek	Python agents (LangChain, CrewAI, etc.)
Dependencies	5. 3× stdlib, 2× 21no.de	200+ packages
Binary size	~11 MB static	50-200 MB with venv
Startup	Instant	2-10s (Python imports)
Sandbox	--sandbox flag	Requires manual Docker setup
Tool interface	One interface, one method	Class hierarchies + decorators

---

Strategic Features

🔒 Sandboxed Execution

Every session can run in an isolated Docker container: no network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. odek serve enables the sandbox by default; odek run keeps it opt-in but warns when running unsandboxed. --ctx files are auto-injected into the container at /workspace/. Full security model in docs/SANDBOXING.md.

🛡️ Prompt-Injection-Aware

External content the agent ingests (browser, read_file, shell, search_files, multi_grep, transcribe, vision, web_search, session_search, MCP tools) is wrapped in per-call nonce'd <untrusted_content> boundaries so the model can distinguish data from instructions. Redirect hops are re-classified (browser/http_batch), MCP tool descriptions are scanned for injection at registration, and the MCP error channel is wrapped too. The danger classifier resists 8 known shell-evasion tricks ($(), backticks, $IFS, command/exec, \rm, basenamed absolute paths). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Skill auto-save tracks provenance, declines to persist untrusted suggestions by default, and pins them for explicit odek skill promote --force. odek audit <session-id> surfaces every ingest + per-turn divergence heuristic. Full threat model in docs/SECURITY.md.

🧩 Sub-Agent Delegation

Parallel OS-process sub-agents via delegate_tasks. True isolation — each sub-agent is a fresh odek subagent process with its own config, tools, and termination timeout. Up to 8 concurrent workers. docs/SUBAGENTS.md

🧠 Skill System (on by default)

Skill-matched SKILL.md files load on-demand. Auto-learns from patterns every session — detects multi-step procedures, error recoveries, repeated actions, and user corrections. LLM-enhanced: each detected pattern is enriched with an LLM-generated name, description, trigger keywords, and structured body with overview, steps, pitfalls, and verification sections. Use --no-learn to disable. Import skills from any URI with automatic LLM risk assessment. docs/CLI.md#skills

💾 Persistent Memory

Three tiers: facts (agent-managed durable entries), session buffer (auto-appended turn summaries), episodes (LLM-extracted knowledge from past sessions). Merge-on-write via go-vector RandomProjections — cosine >0.7 auto-merges, <0.3 auto-adds. Saves ~80% LLM calls. Every lifecycle moment (fact add/merge/consolidate, episode store/dedup/evict/promote) emits an observable event surfaced in the terminal (verbose), Web UI, Telegram, or a programmatic MemoryEventHandler. docs/MEMORY.md

🔧 Multi-Turn Sessions

Save, resume, list, trim, and clean up conversations. Sessions persist as JSON in ~/.odek/sessions/. Continue any session with odek continue. docs/SESSIONS.md

🏗️ Layerable Config

Five-layer priority chain: ~/.odek/secrets.env → global (~/.odek/config.json) → project (./odek.json) → ODEK_* env vars → CLI flags. ${VAR} substitution in config files. Project configs are untrusted — operator-only fields set there are ignored. docs/CONFIG.md

⏱️ Execution Budgets & Runtime Events

Hard stop runaway tasks: --max-runtime, --max-tool-calls, --max-input-tokens, --max-output-tokens, --max-cost-usd (or the limits config section, with per-model pricing via limits.model_prices). On exhaustion the session is persisted for resume and the CLI exits with dedicated exit code 4. Follow any run from an external process with --events-jsonl (structured odek.event/v1 JSONL, secrets-redacted, args hashed) or the EventHandler Go API; GET /api/limits on odek serve exposes limits + effective prices for cost rendering. docs/EXTENSIONS.md

🔌 LLM-Agnostic

Any OpenAI-compatible endpoint: Deepseek, OpenAI, Anthropic, Z.ai (GLM), Ollama, vLLM, Groq, Together, Fireworks — anything that speaks /chat/completions. Per-model profiles for thinking depth and context windows. docs/PROVIDERS.md

🌐 Web UI

odek serve — browser-based agent with @ resource completion (@file.go, @sess:abc123), drag-and-drop file attachments, WebSocket streaming, and a full IDE-style console. docs/WEBUI.md

🤖 Telegram Bot

Run agent tasks directly from Telegram via long-polling. Supports slash commands (/plan, /sessions, /resume, /prune, /help, etc.), voice message transcription, photo analysis, conversation persistence across restarts, saved plan files, and daily token budgeting. No external Telegram libraries — built on stdlib net/http. docs/TELEGRAM.md

⏰ Scheduled Tasks (native cron)

Run agent tasks on a cron schedule and deliver results to Telegram, stdout, or a log — no external cron daemon. The scheduler runs in-process (inside odek telegram or a standalone odek schedule daemon), so a scheduled task sees the same resolved config (API key, model, bot token) an interactive run does. Stdlib-only cron parser with Vixie day-of-month/day-of-week semantics, per-job timezones, missed-run catchup, and a singleton lock so jobs never double-fire. odek schedule add --cron "0 9 * * 1-5" --deliver telegram "...". docs/SCHEDULES.md

📎 File Attachments

Attach files to any prompt with --ctx / -c (CLI), @filename inline references (CLI + REPL + Web UI), or drag-and-drop (Web UI). File content is injected as context blocks before the task — no tool calls needed. Comma-separate multiple files: --ctx main.go,lib.go. docs/CLI.md#file-attachments

🔗 MCP (Two-Way)

Server (odek mcp) — expose odek's native tools (shell, read/write/search files, patch, browser) to Claude Code, Cursor, and any MCP client. Client (mcp_servers config) — odek connects to external MCP servers (Playwright, Fetch, GitHub, SQLite, etc.) and makes their tools available to the agent as <server>__<tool>. Per-server limits (timeout_seconds, max_response_bytes, max_result_chars, artifact_roots) and validated file:// artifact references keep large tool outputs out of the model context — see the versioned odek-extension/v1 contract in docs/EXTENSIONS.md. Both directions in one binary. docs/MCP.md

🔍 Native Tools

Built-in read_file, write_file, search_files, patch, shell, and browser tools. All gated by a unified security layer (dangerous config) — classify operations as allow / deny / prompt per risk class. No third-party dependencies. docs/SECURITY.md

🌐 Local Web Search

web_search queries a self-hosted SearXNG metasearch instance — no cloud search API, no keys. Returns ranked results (title, url, snippet) the agent then fetches with browser / http_batch; results are wrapped as untrusted content and gated as network_egress. The Docker Compose setup runs a SearXNG sidecar and enables it out of the box; standalone installs point web_search.base_url at any SearXNG instance. docs/CHEATSHEET.md

---

Quick Start

# Single-shot task
odek run "List the files"

# With session persistence
odek run --session "Refactor auth module"
odek continue "Add rate limiting"

# Sandboxed (Docker isolation)
odek run --sandbox "npm audit"

# Different model
odek run --model gpt-4o --base-url https://api.openai.com/v1 "Explain this"

# With skill learning (on by default — use --no-learn to disable)
odek run "Set up a Go project with CI"

# Interactive REPL
odek repl

# Attach files for context
odek run --ctx data.csv "analyze this"
odek run --ctx main.go,lib.go "compare these files"
odek run "@README.md what does this project do?"

---

Cheatsheet

Commands

Command	What it does
odek run <task>	Single-shot task
odek run --session <task>	Save conversation as session
odek continue [--id <id>] <task>	Resume a saved session
odek repl	Interactive multi-turn REPL
odek session list	List recent sessions
odek session show [id]	View session transcript
odek session delete <id>	Delete a session
odek session trim <id> <n>	Keep last n messages
odek session cleanup <days>	Delete old sessions
odek skill list	List available skills
odek skill view <name>	View skill content
odek skill delete <name>	Delete a skill
odek skill promote <name> [--force]	Promote a tainted auto-saved skill after review
odek skill import <uri>	Import skill from URL
odek skill curate	Audit skill quality/overlap
odek audit <session-id>	Print the prompt-injection audit log for a session
odek audit --list	List sessions with ingest counts and divergence flags
odek serve [--addr :8080]	Start Web UI server (sandbox on by default; --no-sandbox to disable)
odek subagent --goal <string>	Run a focused sub-task
odek init [--global]	Create config file
odek mcp [--sandbox]	Start MCP server — expose tools to Claude Code
odek version	Print version

Key Flags

Flag	What it does
--model <name>	LLM model (e.g. deepseek-v4-flash, gpt-4o)
--base-url <url>	API endpoint URL
--sandbox	Run in Docker sandbox
--thinking <level>	Reasoning depth (enabled/disabled/low/medium/high)
--learn	Enable skill learning mode — on by default
--no-learn	Disable skill learning mode
--system <prompt>	Override system prompt
--max-iter <n>	Max think→act cycles (default 90)
--prompt-caching	Enable Anthropic/OpenAI/DeepSeek prompt caching markers
--no-color	Disable colored output
--ctx <files> / -c	Attach files as context blocks (comma-separated)
--no-agents	Skip AGENTS.md project file
--events-jsonl <path>	Stream structured runtime events (odek.event/v1) to a JSONL file
--external-ref <ref>	Attach an opaque external-state reference to the session (repeatable)
--max-runtime/--max-tool-calls/--max-input-tokens/--max-output-tokens/--max-cost-usd	Hard execution budgets — exhaustion exits with code 4

---

Docs

Doc	Covers
CLI Reference	All commands, subcommands, flags, error codes
Cheat Sheet	CLI quick reference, key flags, config snippets
Configuration	Config files, env vars, priority chain, all sections
Programmatic API	SDK Guide: import, Agent lifecycle, Tool interface, multi-turn sessions, memory system, model profiles, complete examples
Providers & Models	Supported providers, thinking config, context windows
Prompt Caching	Anthropic/OpenAI/DeepSeek caching support, config, metrics
Response Streaming	Live streaming of LLM responses, config, reliability semantics
Memory	Three-tier design, go-vector merge-on-write, memory tool
Sessions	Multi-turn conversations, save/resume/trim/cleanup
Telegram Bot	Telegram integration: bot client, slash commands, session management, plans, media downloads
Scheduled Tasks	Native in-process cron: odek schedule, Vixie cron syntax, delivery, missed-run catchup, daemon vs embedded
Sandboxing	Docker isolation model, config, security hardening
Security	Threat model, prompt injection defense, sandbox model
Sub-Agents	Task decomposition, delegation tool, subagent protocol
Web UI	odek serve, WebSocket protocol, @ resource resolution
Self-Learning	LLM-enhanced skill learning, pattern detection, auto-curation
Skills	Trigger-matched skills, learning, import, curation
MCP	Serve tools to Claude Code + connect to external MCP servers
Extensions	odek-extension/v1 contract: MCP limits, artifact refs, event stream, external refs, budgets
Development	Building, testing, contributing, project structure

---

Programmatic API

import "github.com/BackendStack21/odek"

agent, err := odek.New(odek.Config{
    Model:          "deepseek-v4-flash",
    APIKey:         os.Getenv("ODEK_API_KEY"),
    MaxIterations:  30,
    Tools:          []odek.Tool{&myCustomTool{}},
    SystemMessage:  "You are an expert at refactoring Go code.",
})
defer agent.Close()

result, err := agent.Run(context.Background(), "Refactor this module")

The full Config struct supports: BaseURL, Thinking, SandboxCleanup, Renderer, MemoryConfig, MemoryDir, Skills, SkillManager, NoProjectFile, plus the extension API — EventHandler (structured runtime events), ExternalRefs (opaque session references), and Limits (execution budgets).

---

Test

go test ./...                 # full suite, no setup required
go test -race ./...           # also clean under the race detector
go test -cover ./...          # per-package coverage report
ODEK_E2E=1 go test ./cmd/odek/   # opt-in Docker / subprocess E2E suite

Everything runs with go test — no Docker, no network, no external services required for the default unit suite. The opt-in ODEK_E2E=1 set exercises the sandbox, sub-agent subprocess pipeline, and Web UI handshake against real Docker / real processes.

---

License

MIT

Documentation

Overview

Package odek is a minimal Go agent loop runtime.

odek implements the ReAct (Reasoning + Acting) pattern — the "think, therefore act" loop that powers autonomous AI agents. It is not a framework or an SDK. It is a runtime: one loop, one binary, minimal deps.

Design

• Minimal external dependencies. stdlib + a few focused packages.
• Session isolation via Docker containers (--sandbox).
• LLM-agnostic. Any OpenAI-compatible endpoint works.
• Tool-first. Tools are the only extension point.

Security

When running with --sandbox, each session executes in a fresh Docker container. The container has no network access, no host mounts beyond the working directory, and is destroyed on exit. The agent can never access files outside its working directory.

Index

• Constants
• Variables
• func BuildRuntimeContext(platform string) string
• func LoadProjectFile() string
• func ProfileLabel(model string) string
• type Agent
  • func New(cfg Config) (*Agent, error)
  • func (a *Agent) Close() error
  • func (a *Agent) EmitEvent(ev events.Event)
  • func (a *Agent) Memory() *memory.MemoryManager
  • func (a *Agent) Run(ctx context.Context, task string) (string, error)
  • func (a *Agent) RunID() string
  • func (a *Agent) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)
  • func (a *Agent) SetEventSessionID(id string)
  • func (a *Agent) SetMessagesPersistCallback(cb loop.MessagesPersistCallback)
  • func (a *Agent) SkillManager() *skills.SkillManager
  • func (a *Agent) SwitchModel(model string)
  • func (a *Agent) SwitchThinking(thinking string)
  • func (a *Agent) TotalCacheCreationTokens() int
  • func (a *Agent) TotalCacheReadTokens() int
  • func (a *Agent) TotalCachedTokens() int
  • func (a *Agent) TotalInputTokens() int
  • func (a *Agent) TotalOutputTokens() int
• type Config
• type ModelProfile
  • func LookupProfile(model string) *ModelProfile
• type Tool
• type ToolFilterConfig

Constants

const ProjectFileName = "AGENTS.md"

ProjectFileName is the name of the project-level instructions file that odek automatically loads from the working directory.

Variables

var KnownProfiles = []struct {
	Prefix  string
	Profile ModelProfile
}{
	{

		Prefix: "glm-5.3",
		Profile: ModelProfile{
			Label:      "GLM 5.3 (Z.ai)",
			Timeout:    300,
			MaxContext: 1_000_000,
		},
	},
	{

		Prefix: "glm-5.2",
		Profile: ModelProfile{
			Label:      "GLM 5.2 (Z.ai)",
			Timeout:    300,
			MaxContext: 1_000_000,
		},
	},
	{

		Prefix: "glm-5-turbo",
		Profile: ModelProfile{
			Label:      "GLM 5 Turbo (Z.ai)",
			Timeout:    180,
			MaxContext: 200_000,
		},
	},
	{
		Prefix: "glm-",
		Profile: ModelProfile{
			Label:      "GLM (Z.ai)",
			Timeout:    180,
			MaxContext: 131_072,
		},
	},
	{
		Prefix: "kimi-",
		Profile: ModelProfile{
			Label:      "Kimi",
			Timeout:    300,
			MaxContext: 262_144,
		},
	},
	{

		Prefix: "k3-256k",
		Profile: ModelProfile{
			Label:      "Kimi",
			Timeout:    300,
			MaxContext: 262_144,
		},
	},
	{
		Prefix: "k3",
		Profile: ModelProfile{
			Label:      "Kimi",
			Timeout:    300,
			MaxContext: 1_000_000,
		},
	},
	{
		Prefix: "deepseek-v4-pro",
		Profile: ModelProfile{
			Label:           "DeepSeek v4 Pro",
			DefaultThinking: "enabled",
			Timeout:         180,
			MaxContext:      1_000_000,
		},
	},
	{
		Prefix: "deepseek-v4-flash",
		Profile: ModelProfile{
			Label:           "DeepSeek v4 Flash",
			DefaultThinking: "",
			Timeout:         90,
			MaxContext:      131_072,
		},
	},
	{
		Prefix: "deepseek-",
		Profile: ModelProfile{
			Label:      "DeepSeek (generic)",
			MaxContext: 131_072,
		},
	},
}

KnownProfiles lists all built-in model profiles. Each entry is matched by longest prefix — "deepseek-v4-flash" matches before "deepseek-" would. Add new profiles here; the rest of odek consumes them automatically.

Functions

func BuildRuntimeContext

func BuildRuntimeContext(platform string) string

BuildRuntimeContext returns a system prompt header with OS, hostname, working directory, current date/time, and platform-specific formatting rules for the given transport (platform). platform can be "telegram", "terminal", "web", or empty for generic.

This context eliminates the need for the agent to run shell commands to discover its own environment — the most common waste of tokens in CLI agent usage.

func LoadProjectFile

func LoadProjectFile() string

LoadProjectFile reads ProjectFileName from the current working directory. Returns the file content (trimmed) if it exists and is readable. Returns empty string if the file doesn't exist or can't be read. Checks for symlinks to prevent following attacker-controlled paths. The content is intended to be appended to the system message with a clear header — use it for project conventions, architecture notes, etc.

func ProfileLabel

func ProfileLabel(model string) string

ProfileLabel returns the human-readable label for a model, or the model name itself if no profile matches. Used in CLI headers and status output.

Types

type Agent

type Agent struct {
	// contains filtered or unexported fields
}

Agent is the agent loop runtime.

func New

func New(cfg Config) (*Agent, error)

New creates a new Agent with the given configuration.

If Config.SandboxCleanup is set, the cleanup function is called when Close() is invoked. The caller is responsible for creating the sandbox container and wiring up tool executables to use it before calling New().

func (*Agent) Close

func (a *Agent) Close() error

Close cleans up resources. If a sandbox container was created, it is destroyed. Always call Close() when done with the agent.

Close first drains background memory work with a bounded wait: session-end episode extraction and consolidation run on tracked goroutines (see MemoryManager.RunBackground) and would otherwise be silently killed when the CLI process exits right after a run. This is the single choke point every CLI path reaches via `defer agent.Close()` (run, continue, REPL, serve, telegram), so the drain lives here rather than at each call site.

func (*Agent) EmitEvent

func (a *Agent) EmitEvent(ev events.Event)

EmitEvent emits a caller-originated runtime event (e.g. session_saved from the session persistence layer, budget_exceeded from budget enforcement) through the same non-blocking, run-scoped pipeline as engine events. No-op when no EventHandler is configured.

func (*Agent) Memory

func (a *Agent) Memory() *memory.MemoryManager

Memory returns the agent's memory manager. Used by the CLI layer to append buffer entries after each turn and signal session end. Returns nil if memory is disabled.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, task string) (string, error)

Run executes the agent loop for the given task and returns the final answer.

func (*Agent) RunID

func (a *Agent) RunID() string

RunID returns the random identifier stamped on every runtime event of this agent's run, or "" when no EventHandler is configured.

func (*Agent) RunWithMessages

func (a *Agent) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)

RunWithMessages executes the agent loop starting from a pre-built message history. Use this for multi-turn conversations where the full conversation context (system prompt, prior turns) has been loaded from a session file and the new user message appended.

Returns the final answer plus the complete updated message history. The caller should persist the history (e.g. to a session file) so the conversation can be continued in a future call.

func (*Agent) SetEventSessionID

func (a *Agent) SetEventSessionID(id string)

SetEventSessionID stamps the session identifier on subsequent runtime events. Call it as soon as the session ID is known (events emitted earlier simply carry no session_id). No-op when no EventHandler is configured.

func (*Agent) SetMessagesPersistCallback

func (a *Agent) SetMessagesPersistCallback(cb loop.MessagesPersistCallback)

SetMessagesPersistCallback registers a callback the loop fires after each completed step — once a tool batch's result messages are appended, and again after the final assistant message — with a copy of the current message history. Callers use it to persist per-turn progress so an interrupted run (Ctrl-C, SIGTERM, crash) can be resumed from the last completed step. Safe to call between RunWithMessages calls.

func (*Agent) SkillManager

func (a *Agent) SkillManager() *skills.SkillManager

SkillManager returns the agent's skill manager. Used by the CLI, WebUI, and Telegram layers to run learning heuristics after agent completion. Returns nil if skills are disabled.

func (*Agent) SwitchModel

func (a *Agent) SwitchModel(model string)

SwitchModel updates the LLM model used by this agent at runtime. The model string must be a valid OpenAI-compatible model identifier. This is safe to call between RunWithMessages calls to switch models mid-session. Empty strings are silently ignored.

func (*Agent) SwitchThinking

func (a *Agent) SwitchThinking(thinking string)

SwitchThinking updates the reasoning/thinking mode used by this agent at runtime. Accepts the same values as Config.Thinking: "enabled", "disabled", "low", "medium", "high", or "" (provider default / off). Safe to call between RunWithMessages calls to toggle thinking per-query.

func (*Agent) TotalCacheCreationTokens

func (a *Agent) TotalCacheCreationTokens() int

TotalCacheCreationTokens returns the cumulative Anthropic cache creation tokens across all iterations of the most recent run.

func (*Agent) TotalCacheReadTokens

func (a *Agent) TotalCacheReadTokens() int

TotalCacheReadTokens returns the cumulative Anthropic cache read tokens across all iterations of the most recent run.

func (*Agent) TotalCachedTokens

func (a *Agent) TotalCachedTokens() int

TotalCachedTokens returns the cumulative OpenAI cached prompt tokens across all iterations of the most recent run.

func (*Agent) TotalInputTokens

func (a *Agent) TotalInputTokens() int

TotalInputTokens returns the cumulative prompt tokens consumed across all iterations of the most recent RunWithMessages call.

func (*Agent) TotalOutputTokens

func (a *Agent) TotalOutputTokens() int

TotalOutputTokens returns the cumulative completion tokens generated across all iterations of the most recent RunWithMessages call.

type Config

type Config struct {
	// Model is the LLM model identifier (e.g., "deepseek-v4-flash").
	Model string

	// BaseURL is the OpenAI-compatible API endpoint.
	// Default: "https://api.deepseek.com/v1"
	BaseURL string

	// APIKey authenticates with the LLM provider.
	// Falls back to DEEPSEEK_API_KEY, then OPENAI_API_KEY env vars.
	APIKey string

	// Thinking controls the model's reasoning depth. Provider-specific:
	//
	//   Deepseek: "enabled" or "disabled" → {"type": "enabled"}
	//   OpenAI o-series: "low", "medium", "high" → {"reasoning_effort": "low"}
	//
	// When empty, the model's profile default is used. If the profile also
	// has no default, the field is not sent (provider default behavior).
	Thinking string

	// Temperature controls LLM output randomness (0.0–2.0).
	// Negative = omit from request (use provider default).
	// 0.0 = deterministic, 1.0 = creative. Default: 0.0 for benchmark
	// stability; set to -1 to use provider defaults.
	Temperature float64

	// ThinkingBudget is the maximum thinking tokens for Anthropic extended thinking (default 5000).
	ThinkingBudget int

	// Tools available to the agent.
	Tools []Tool

	// ToolFilter controls which auto-registered tools are exposed to the LLM
	// (for example the memory tool when a MemoryManager is provided). It is
	// not applied to caller-supplied Tools; callers are responsible for
	// filtering their own tool slices. Enabled is a whitelist; Disabled is a
	// blacklist. Empty Enabled means "no whitelist".
	ToolFilter ToolFilterConfig

	// MaxIterations caps the number of think→act cycles (default: 90).
	MaxIterations int

	// SystemMessage is the system prompt injected at the start of every run.
	// Runtime context (OS, hostname, cwd, date, platform) is automatically
	// prepended to this message before it reaches the LLM.
	// If AGENTS.md exists in the working directory, its content is appended
	// automatically. Set NoProjectFile to true to skip this.
	SystemMessage string

	// RuntimeContext, when set, prepends environment awareness to the system
	// message: OS, hostname, working directory, current date/time, and
	// platform-specific formatting rules. Each entry point (CLI, Telegram,
	// WebUI) sets this automatically. When empty, BuildRuntimeContext("")
	// provides generic terminal context.
	RuntimeContext string

	// NoProjectFile disables automatic loading of AGENTS.md from the
	// working directory. By default, odek reads AGENTS.md and appends
	// its content to the system message with a "Project Instructions" header.
	NoProjectFile bool

	// SandboxCleanup, if set, is called by Agent.Close() to destroy the
	// Docker sandbox container. Set by the CLI when --sandbox is active.
	// Programmatic API users can set this to their own cleanup logic
	// (e.g., remove a container, delete a VM, tear down a network).
	// When nil, Close() is a no-op.
	SandboxCleanup func() error

	// Renderer, if set, produces colored terminal output for each phase
	// of the agent loop. When nil, the agent runs silently (programmatic API).
	Renderer *render.Renderer

	// ToolEventHandler, if set, is invoked for each tool call and result
	// during the agent loop. Fires "tool_call" before and "tool_result"
	// after each tool invocation. Used by the WebUI for live streaming.
	ToolEventHandler func(event string, name string, data string)

	// InteractionMode controls tool-call rendering: "engaging" (default), "enhance", "verbose", or "off".
	InteractionMode string

	// IterationCallback, if set, is invoked after each iteration of the
	// agent loop with progress info (turn number, tokens, tools called).
	// Used by the Telegram handler for periodic progress updates.
	IterationCallback loop.IterationCallback

	// Skills configures the skill system. When nil, skills are disabled.
	Skills *skills.SkillsConfig

	// SkillManager holds the loaded skill state. Passed by the CLI layer;
	// when nil, New() auto-loads from default directories.
	SkillManager *skills.SkillManager

	// MemoryDir sets the directory for persistent memory storage.
	// Default: ~/.odek/memory/
	MemoryDir string

	// MemoryConfig controls the memory system (facts, buffer, episodes).
	// Default: memory.DefaultMemoryConfig()
	MemoryConfig memory.MemoryConfig

	// Guard is the prompt-injection detector shared across subsystems.
	// When nil, subsystems fall back to local rule-based scanning on demand.
	Guard guard.Guard

	// GuardConfig is the resolved guard configuration used to decide which
	// surfaces are scanned. It mirrors the guard instance passed above.
	GuardConfig guard.Config

	// PromptCaching enables prompt caching markers for supported providers.
	// When enabled (default: false), the system prompt and first user message
	// are annotated with cache_control markers, and Anthropic-style system
	// blocks are used. Supported by:
	//   - Anthropic (explicit cache_control markers)
	//   - DeepSeek (automatic — prefix stability helps)
	//   - OpenAI (automatic — prefix stability helps)
	//
	// When disabled (default), no cache markers are sent and the system
	// prompt stays in the messages array for maximum provider compatibility.
	// Enable this when using Anthropic models to get ~90% cost reduction
	// on cached tokens and ~60-80% TTFT latency reduction.
	PromptCaching bool

	// Stream enables SSE streaming of LLM responses for the main think
	// step (default: false). Requires DeltaHandler to display anything
	// incrementally; without one the behavior matches the buffered path.
	// Auxiliary LLM calls (compaction, progress summaries, memory) always
	// stay buffered. See docs/STREAMING.md.
	Stream bool

	// DeltaHandler receives streamed output fragments when Stream is
	// enabled. It is invoked synchronously and must be non-blocking;
	// returning an error aborts generation for that call.
	DeltaHandler func(llm.Delta) error

	// MaxToolParallel controls how many tool calls run concurrently per
	// agent iteration. 0 = use default (4). Models that emit multiple
	// parallel tool calls benefit from concurrent execution of I/O-bound
	// tools like read_file, search_files, and web_search.
	MaxToolParallel int

	// SkillEventHandler, if set, is invoked when a skill lifecycle event
	// occurs (loaded, autoloaded, saved, deleted, etc.). Used by WebUI
	// (WebSocket streaming) and Telegram (inline messages).
	SkillEventHandler func(event skills.SkillEvent)

	// MemoryEventHandler, if set, is invoked when a memory lifecycle event
	// occurs (fact add/merge/consolidate, episode store/dedup/evict/promote).
	// Fans out alongside the terminal renderer so embedding programs, the WebUI
	// (WebSocket streaming), and Telegram can observe memory activity that was
	// previously silent.
	MemoryEventHandler func(event memory.MemoryEvent)

	// AgentSignalHandler, if set, is invoked on internal agent-loop signals
	// (context-window trim, tool-failure recovery) that the engine previously
	// handled silently. Used for observability across all surfaces.
	AgentSignalHandler func(event loop.SignalEvent)

	// EventHandler, if set, receives the structured runtime event stream
	// (schema odek.event/v1 — see docs/EXTENSIONS.md): run_started,
	// iteration_completed, tool_call_started/completed/failed,
	// session_saved, context_trimmed, budget_exceeded, run_completed,
	// run_failed.
	//
	// Dispatch is non-blocking (buffered channel, drop-on-full) and
	// panic-isolated: a slow or panicking handler can never stall or crash
	// the agent loop. Events never carry raw tool arguments by default
	// (SHA-256 digest + sizes + a structured argv0/target/class summary
	// only) and human-readable fields pass through secret redaction.
	EventHandler func(event events.Event)

	// EventsIncludeArgs opts the event stream into carrying the raw
	// (secret-redacted) tool-call arguments in tool_call_started events.
	// Default off: raw arguments can include sensitive task content, but
	// incident review on an opt-in basis beats a stream that cannot answer
	// "what actually ran?" once the session has been deleted.
	EventsIncludeArgs bool

	// ExternalRefs carries operator-supplied pointers to state that lives
	// outside odek (schema odek-extension/v1 — see docs/EXTENSIONS.md).
	// The caller attaches them to the session at creation time via
	// session.Session.AddExternalRefs; odek stores and returns these refs
	// verbatim and NEVER resolves or dereferences their URIs. New rejects
	// invalid refs with a descriptive error.
	ExternalRefs []session.ExternalRef

	// Limits configures hard execution budgets for a run
	// (odek-extension/v1 — see docs/EXTENSIONS.md): wall-clock runtime,
	// tool-call count, cumulative input/output tokens, and estimated cost.
	// The zero value disables enforcement. On exhaustion the loop emits a
	// budget_exceeded event, persists the latest safe session state via the
	// messages-persist callback, and returns a typed *budget.Error (match
	// with budget.As). Cost enforcement is active only when MaxCostUSD and
	// both per-million prices are configured — odek never hard-codes
	// provider prices.
	Limits budget.Limits

	// Approver gates dangerous tool operations. When set and the LLM returns
	// multiple tool calls in one iteration, a single batch approval prompt
	// is shown instead of N individual prompts. If denied, no tools run
	// for that iteration. If approved, individual tool-level PromptCommand
	// calls are bypassed via SetTrustAll.
	Approver danger.Approver

	// DangerousConfig holds the user's risk class configuration (Allow/Deny/
	// Prompt per risk class). Used by the batch gate to decide whether a
	// tool call needs approval before showing the prompt. When nil, the
	// batch gate plays safe and shows the prompt for any classified tool.
	DangerousConfig *danger.DangerousConfig

	// UntrustedWrapper, if set, is applied to skill and episode context before
	// injection into the model's system context. It should wrap externally-
	// sourced content with a nonce'd boundary (and record it for audit). When
	// nil, skill/episode content is injected directly (not recommended for
	// production surfaces).
	UntrustedWrapper func(source, content string) string

	// Compaction enables LLM-based rolling compaction. When enabled,
	// conversation turn groups dropped by context trimming are
	// summarized by the model into a rolling digest system message instead of
	// vanishing entirely, so long sessions retain a compressed memory of
	// earlier work. Each compaction costs one extra LLM call per trim.
	// The CLI resolves it to ON by default (an explicit compaction=false,
	// ODEK_COMPACTION=false, or --no-compaction disables it); library
	// users of New must opt in explicitly here.
	Compaction bool
}

Config configures an Agent instance.

type ModelProfile

type ModelProfile struct {
	// Label is a human-readable name for the model family.
	Label string

	// DefaultThinking is the thinking value applied when Config.Thinking
	// is empty. Empty string means don't send the field (provider default).
	DefaultThinking string

	// Timeout is the default request timeout in seconds.
	// Zero means use the global default (120s). Increased for
	// models that take longer to reason (e.g. deepseek-v4-pro).
	Timeout int

	// MaxContext is the model's maximum context window in tokens.
	// The loop engine automatically trims conversation history when
	// estimated tokens approach this limit. Zero means no limit
	// enforcement (unknown or effectively unlimited models).
	MaxContext int
}

ModelProfile holds per-model defaults applied when the user hasn't explicitly provided a value. Zero values leave the system default.

func LookupProfile

func LookupProfile(model string) *ModelProfile

LookupProfile returns the best-matching ModelProfile for a model name, or nil if no profile matches. Matching uses longest prefix — a model named "deepseek-v4-flash-custom" would match "deepseek-v4-flash".

type Tool

type Tool interface {
	Name() string
	Description() string
	Schema() any // JSON Schema for the tool's parameters
	Call(args string) (string, error)
}

Tool represents a single capability the agent can invoke.

type ToolFilterConfig

type ToolFilterConfig struct {
	// Enabled is a whitelist. When non-nil, only tools whose names appear
	// here are registered. An empty (but non-nil) slice means no tools.
	Enabled []string
	// Disabled is a blacklist. Tools whose names appear here are removed
	// after the whitelist is applied.
	Disabled []string
}

ToolFilterConfig controls which tools are exposed to the LLM.