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.13 — see "Build requirements" below)
go install github.com/BackendStack21/odek/cmd/odek@latest

# Use (provider env key — DEEPSEEK_API_KEY for the default provider)
export DEEPSEEK_API_KEY=sk-...
odek run "How many lines in go.mod?"
# → 3 lines

Build requirements: Go 1.25.13 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.

New here? The step-by-step install guide — including the GLM 5.3 Flash (z.ai) setup and the optional bodek TUI — lives in GETTING_STARTED.md.

---

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. 2× 21no.de, 3× golang.org/x	200+ packages
Binary size	~11 MB static	50-200 MB with venv
Startup	Instant	2-10s (Python imports)
Sandbox	Default-on Docker sandbox (--no-sandbox to opt out)	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. Sandboxing is on by default for odek run, odek repl, and odek serve; opt out with --no-sandbox / ODEK_NO_SANDBOX=1 (unsandboxed runs warn loudly, and ODEK_REQUIRE_SANDBOX=1 makes them fatal). --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 common shell-evasion tricks ($()/backtick substitution, $IFS, brace expansion, command/env wrappers, \rm, basenamed absolute paths, and more). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Imported and project skills track provenance — untrusted ones stay excluded from trigger matching until 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. Operator-defined capability profiles (top-level profiles config) override a sub-agent's permissions by name and fail closed on unknown names — a curated starter set of 21 task profiles ships in profiles.template.json. See docs/SUBAGENTS.md and docs/SECURITY.md.

Background commands: bg_start/bg_list/bg_status/bg_output/bg_stop run long-lived processes (dev servers, watchers, fuzz runs) that outlive the turn that started them — session-scoped, bounded in-memory output, spawn-time approval parity with shell, killed when the session or the process ends. Config: background in docs/CONFIG.md; REPL and Telegram expose /jobs.

🧠 Skill System

Skill-matched SKILL.md files load on-demand — skills are authored by you or imported, never auto-generated. 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

Multi-provider via go-llm-sdk: DeepSeek, OpenAI, Anthropic, Gemini, Z.ai (GLM), Kimi, plus any OpenAI-compatible gateway. Provider id + model — no auto-thinking or auto-timeout from the model name. 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"

# 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 skill after review
odek skill import <uri>	Import skill from URL
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 <addr>]	Start Web UI server (loopback by default; 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 memory list	List pending memory facts (aliases: ls, pending)
odek memory promote <session-id>	Promote a session's pending facts to durable facts
odek memory extended <subcommand>	Extended-memory atom management (forget, promote, pin, quarantine, compact, stats, consolidate, nudges, pending, confirm, reject)
odek telegram	Run the Telegram bot (also hosts the embedded scheduler)
odek schedule <add|list|...>	Native cron scheduler (see docs/SCHEDULES.md)
odek cleanup [--dry-run]	One-shot storage sweep of ~/.odek (see docs/MAINTENANCE.md)
odek upgrade [--check]	Self-upgrade from GitHub Releases (SHA-256 verified)
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 (disabled/low/medium/high; enabled/on → medium)
--system <prompt>	Override system prompt
--max-iter <n>	Max think→act cycles (default 90)
--prompt-caching	Enable prompt caching (default on; --no-prompt-caching to disable)
--announce-budget	Parent 50/75/90% budget hints (default on; --no-announce-budget to disable)
--stream	Stream reasoning/answer live (default on; --no-stream to disable)
--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, complete examples
Providers & Models	go-llm-sdk registry, --provider, last-resort context windows
Prompt Caching	Anthropic-format markers; prefix stability on OpenAI-format providers
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, capability profiles
Web UI	odek serve, WebSocket protocol, @ resource resolution
Skills	Trigger-matched skills, import
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
Maintenance	Storage janitor: retention, log rotation, odek cleanup
Extended Memory	Atomic long-term memory layer (opt-in)
Planning	Plan tool, protected plan message, security model
Tool Selection	Tool whitelist/blacklist guide and names reference
Daily Worker	Headless scheduled-worker patterns
Providers	go-llm-sdk registry, --provider, v2 knobs
Migration (v2)	v1 → v2 config, deleted profiles, embedder API
Development	Building, testing, contributing, project structure

---

Programmatic API

import "github.com/BackendStack21/odek"

agent, err := odek.New(odek.Config{
    Provider:       "deepseek",
    Model:          "deepseek-v4-flash",
    APIKey:         os.Getenv("DEEPSEEK_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: Provider, Providers, BaseURL (selected-provider override), Thinking, SandboxCleanup, Renderer, MemoryConfig, MemoryDir, Skills, SkillManager, NoProjectFile, plus the extension API — EventHandler (structured runtime events), ExternalRefs (opaque session references), and Limits (execution budgets). v2 depends on go-llm-sdk; see docs/MIGRATION.md.

---

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
• func BuildRuntimeContext(platform string) string
• func ComposeSecureSystem(identity string) string
• func DefaultUntrustedWrapper(source, content 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) LastPromptTokens() int
  • func (a *Agent) MaxContextTokens() int
  • func (a *Agent) Memory() *memory.MemoryManager
  • func (a *Agent) RequestFinalization()
  • func (a *Agent) Run(ctx context.Context, task string) (string, error)
  • func (a *Agent) RunID() string
  • func (a *Agent) RunWithMessages(ctx context.Context, messages []session.Message) (string, []session.Message, error)
  • func (a *Agent) SetBackgroundNoticeProvider(fn func() string)
  • func (a *Agent) SetEventSessionID(id string)
  • func (a *Agent) SetMessagesPersistCallback(cb loop.MessagesPersistCallback)
  • func (a *Agent) SetToolSessionID(id string)
  • func (a *Agent) SkillManager() *skills.SkillManager
  • func (a *Agent) SwitchModel(model string)
  • func (a *Agent) SwitchThinking(thinking string)
  • func (a *Agent) SystemPrompt() string
  • func (a *Agent) 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 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.

const SecurityPillar = `` /* 5198-byte string literal not displayed */

SecurityPillar is the invariant runtime policy. Config.SystemMessage is an identity/persona surface; New always composes this policy into the effective system prompt so library embedders cannot accidentally construct an agent without the same boundary enforced by the CLI.

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 ComposeSecureSystem

func ComposeSecureSystem(identity string) string

ComposeSecureSystem strips embedded copies and appends one authoritative pillar at the end. Appending, rather than accepting an identity containing the pillar unchanged, prevents scanner-clean trailing identity text from becoming the last instruction in the trusted block.

func DefaultUntrustedWrapper

func DefaultUntrustedWrapper(source, content string) string

DefaultUntrustedWrapper provides a safe boundary for embedders that do not install a surface-specific wrapper. CLI wrappers can still add guard scans and audit recording by supplying Config.UntrustedWrapper.

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 is the display name for a model. v2 has no static profile table — this is the model id. Serve may show ListModels display names.

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) LastPromptTokens

func (a *Agent) LastPromptTokens() int

LastPromptTokens returns the provider-normalized prompt size of the last parent-side LLM call — the parent conversation window (input + cache-read + cache-creation). Not a cumulative; sub-agent usage charged via ChargeExternalUsage never affects it.

func (*Agent) MaxContextTokens

func (a *Agent) MaxContextTokens() int

MaxContextTokens returns the resolved model context limit (0 = unknown).

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) RequestFinalization

func (a *Agent) RequestFinalization()

RequestFinalization asks the running agent to conclude at the next iteration boundary: no new tool batches start and the engine produces a partial-progress summary prefixed with the time-budget marker instead of running to the iteration cap. Non-blocking; intended for soft-deadline watchers that trade a hard kill for a bounded graceful conclusion.

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 []session.Message) (string, []session.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) SetBackgroundNoticeProvider

func (a *Agent) SetBackgroundNoticeProvider(fn func() string)

SetBackgroundNoticeProvider registers a provider drained at the top of every iteration; its return value is injected as an observe-phase message (used for background-command completion notices). An empty return injects nothing. Safe to call between RunWithMessages calls.

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) SetToolSessionID

func (a *Agent) SetToolSessionID(id string)

SetToolSessionID stamps id onto every registered tool implementing sessionToolBinder (currently delegate_tasks, for artifact filing). Call it whenever the active session id becomes known or changes — serve binds per prompt because one connection can session_switch mid-flight; the single- session surfaces (run/continue/repl/telegram) bind once at startup or per agent construction. No-op on a nil agent or when no tool qualifies.

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 Config.Thinking values: "disabled", "low", "medium", "high", aliases (enabled/on/off/mid/max), or "" (provider default). Unrecognized values are ignored (the current level stays). Safe to call between RunWithMessages calls to toggle thinking per-query.

func (*Agent) SystemPrompt

func (a *Agent) SystemPrompt() string

SystemPrompt returns the resolved system message after runtime context and project-file composition. Persisted session heads should stay empty; RunWithMessages restores this value at run time.

func (*Agent) Thinking

func (a *Agent) Thinking() string

Thinking returns the agent's current reasoning depth (canonical, or empty when using the provider default).

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 {
	// Provider is the go-llm-sdk registry id (deepseek, openai, anthropic,
	// gemini, zai, kimi, or a custom id from Providers). Empty defaults to
	// deepseek.
	Provider string

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

	// BaseURL overrides the selected provider's base URL (legacy v1 alias
	// and embedder override). Empty keeps the SDK default for Provider.
	BaseURL string

	// APIKey authenticates the selected provider. Empty falls back to the
	// provider's env key (DEEPSEEK_API_KEY for the default provider).
	APIKey string

	// Providers holds per-id API key / base URL / format overrides.
	Providers map[string]llmclient.ProviderOverride

	// RequestTimeout is the per-request wall-clock budget. 0 uses 300s.
	RequestTimeout time.Duration

	// ContextWindow is an operator override for the trim budget. 0 means
	// discover via ListModels, then the last-resort table for shipped ids.
	ContextWindow int

	// Thinking controls the model's reasoning depth. Public values:
	// "disabled", "low", "medium", "high". Empty omits the field (provider
	// default). Aliases (enabled/on → medium, off → disabled, mid → medium,
	// max → high) are accepted inbound. go-llm-sdk maps the canonical
	// values onto provider fields. v2 does not infer thinking from the
	// model name — set it explicitly.
	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

	// AnnounceBudget, when set, enables or disables budget-awareness
	// telemetry: the engine injects one-line hints at 50/75/90% of the
	// iteration, wall-clock, tool-call, token, or cost budget and emits
	// budget_warning signals. Nil defaults on after MaxIterations is
	// filled (90). Distinct from subagent.announce_budget, which still
	// controls children. Set false to opt out.
	AnnounceBudget *bool `json:"announce_budget,omitempty"`

	// 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 Anthropic-format cache_control markers on the
	// first system block and first user message. Markers are sent only when
	// the bound client's format is Anthropic (never URL-sniffed). OpenAI-
	// format providers are unaffected — they rely on prefix-stable separate
	// system messages. Library default: false (opt in). The CLI resolves
	// this to ON when unset; pass --no-prompt-caching to disable.
	PromptCaching bool

	// Stream enables SSE streaming of LLM responses for the main think
	// step. Requires DeltaHandler to display anything incrementally;
	// without one the behavior matches the buffered path. Auxiliary LLM
	// calls (compaction, progress summaries, memory) always stay buffered.
	// Library default: false (opt in). The CLI resolves this to ON when
	// unset; pass --no-stream to disable. 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(llmclient.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, plan_created,
	// plan_updated, plan_blocked, 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 rolling compaction. When enabled, conversation
	// turn groups dropped by context trimming are sketched extractively
	// into a digest system message immediately, then a thinking-off side
	// call replaces that sketch with a model digest on a later iteration
	// if it succeeds. Long sessions retain a compressed memory of earlier
	// work without stalling the next think step. Each compaction still
	// 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 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.