CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

Changed

• Thread lifecycle changes now serialize with active execution. Archive and soft-delete reject threads with queued or running turns, and archived threads reject new turns, retries, and pre-existing turn starts until explicitly unarchived. Full-history forks reject active sources instead of copying nonterminal turns, and startup failures terminalize any turn created before execution ownership is established. Rename remains available during execution because it does not alter run ownership.

Added

• Capability-validated durable reasoning effort. Runtime thread starts, turn starts/resumes, and retries now reject explicit reasoning effort when the selected catalog model is unknown, does not advertise reasoning, or does not advertise that exact effort. Supported explicit choices are stored in thread settings and turn input, inherited by later turns, and recovered by retries instead of becoming renderer-only state.
• Durable live turn steering. The app server now binds the exact public turn/steer request and response, requires thread and expected-active-turn correlation, and queues text instructions for the next safe model-request boundary. A durable steer item moves from queued to completed only after the next provider stream starts; interruption or terminal completion first marks it failed, and only completed instructions replay into later turns. Stable client message ids make active-turn response retries idempotent and reject conflicting text.
• Response-loss-safe full-history thread forks. The generated thread/fork extension accepts a source thread and bounded idempotency key, rejects queued or running source work, and transactionally copies durable turns and items with regenerated identities. Repeating the same request, including after daemon restart, returns the original child without emitting another thread/started notification. Forked timelines retain public file-change evidence but never inherit private exact-restoration snapshots.
• Restart-safe exact file-change reversal. Runtime file-change items now advertise whether Gollem persisted a private recovery snapshot. The item/fileChange/revert extension accepts only thread/item identity and an idempotency key, reuses the existing file-mutation approval flow, verifies exact workspace, path, content digest, mode, and terminal-turn ownership, and emits a durable receipt. Reversal is limited to regular files up to 1 MiB with exactly one observed hard link; directories, paths traversing symlinks, multiply linked files, unknown link counts, stale files, mismatched workspaces, active workspace turns, and incomplete evidence fail closed. Runtime mutations capture before/after evidence under the filesystem mutation lock only after approval, and reverts reserve the workspace without blocking unrelated thread reads. Pending operations reconcile after restart from deterministic transaction directories only inside the approved revert operation when the target and quarantined regular file are provably in a safe state. File metadata and affected directories are synchronized before a durable receipt can commit, and startup reconciles a private snapshot whose public item completion was interrupted. A daemon-wide coordinator makes rollback, thread deletion, and turn or thread starts serialize with that reservation across every client connection, while denied operations release their key only after proving no mutation occurred.
• Restart-safe app-server retry and daemon ownership. File-backed app-server daemons now hold one process-lifetime store lock and reconcile queued or running turns to an inspectable interrupted state after owner loss. The generated turn/retry extension requires an idempotency key, atomically creates or reuses one retry turn, preserves the recorded source prompt and model selection, and bounds model-visible replay after the latest compaction. Recovery never recreates pending approval authority or silently treats prior tool side effects as resumed.
• Typed app-server catalog and run-lifecycle bindings. Generated clients can now infer provider/model discovery, thread and turn start, turn interruption, thread/turn lifecycle notifications, and live text/reasoning deltas without raw JSON. Runtime-specific types preserve the current Gollem wire while exact standalone Codex contracts remain distinct.
• Adaptive thinking for Anthropic providers. New ModelSettings.AdaptiveThinking *bool emits {thinking: {type: "adaptive"}} from both the anthropic and vertexai_anthropic providers — the model decides when and how much to think. Gated per model (Claude 4.6 generation and newer; clear build-time error on older models), mutually exclusive with the legacy ThinkingBudget manual mode, and temperature is omitted on the wire as the API requires. Response and stream paths already parsed thinking blocks; this closes the request side.
• Opus 4.8 and Fable model gating. claude-opus-4-8 and claude-fable-5 (new ClaudeOpus48 / ClaudeFable5 constants) are recognized as post-4.7 flagships: adaptive-only thinking (manual budgets rejected with a pointer to AdaptiveThinking), and the full effort range including xhigh and max now passes per-model effort gating.
• core.WithAdaptiveThinking agent option, and the CLI's default reasoning setup now selects adaptive thinking for Claude 4.6+ models instead of a manual budget (which is rejected on 4.7+ — the budget default made the new models unusable from the CLI). An explicit -thinking-budget still wins.
• Request guards matching API removals (both Anthropic providers): temperature/top_p are stripped on Opus 4.7+ (the API 400s on them regardless of thinking config, and Fable thinks unconditionally server-side), and forced tool choice (required/specific tool) combined with any thinking mode now fails fast with a clear error instead of an API 400.
• Reasoning sandwich works with adaptive thinking. The codetool middleware only varied a manual ThinkingBudget, so on Claude 4.6+ agents (which now default to adaptive thinking, no budget) it was silently inert. With AdaptiveThinking on it now varies ReasoningEffort per phase — effort is adaptive thinking's depth control — keeping the plan-high/implement-lower/verify-high shape on Anthropic. First direct tests for the middleware included.

Removed

• Hosted coverage uploads, patch thresholds, badge, and service configuration.

Phase 14: Ten Innovations from Pydantic-AI, LangChain 1.0, OpenAI Agents SDK, AutoGen & CrewAI

Innovation 1: Typed Dependency Access

• GetDeps[D] extracts typed dependencies from RunContext without manual type assertions
• TryGetDeps[D] safe variant returning (D, bool)
• WithDeps agent option for setting dependencies at agent level
• Agent-level deps merge with run-level WithRunDeps (run-level takes precedence)

Innovation 2: Model Capability Profiles

• ModelProfile struct describes model capabilities (tool calls, vision, streaming, context window)
• Profiled optional interface for models to self-declare capabilities
• GetProfile returns profile or default (full capabilities) for non-Profiled models
• NewCapabilityRouter selects first model matching required capabilities

Innovation 3: Usage Quotas with Auto-Termination

• UsageQuota with hard limits on requests, total/input/output tokens
• QuotaExceededError returned when quota is breached
• WithUsageQuota agent option; checked before each model request
• Zero values mean unlimited (opt-in enforcement)

Innovation 4: Message Interceptor

• MessageInterceptor intercepts outgoing model requests (allow/drop/modify)
• ResponseInterceptor intercepts incoming model responses
• RedactPII built-in interceptor for regex-based PII redaction
• AuditLog built-in interceptor for message logging
• WithMessageInterceptor / WithResponseInterceptor agent options

Innovation 5: Tool Choice Control

• ToolChoice with modes: auto, required, none, force (specific tool)
• ToolChoiceAuto, ToolChoiceRequired, ToolChoiceNone, ToolChoiceForce constructors
• WithToolChoice agent option; WithToolChoiceAutoReset prevents infinite loops
• ToolChoice field added to ModelSettings for provider pass-through

Innovation 6: Cost Tracker

• CostTracker with per-model ModelPricing (input/output/cached token costs)
• Record accumulates costs; TotalCost and CostBreakdown for reporting
• RunCost on RunResult for per-run cost visibility
• WithCostTracker agent option; thread-safe for concurrent recording

Innovation 7: Composable Pipeline

• Pipeline chains PipelineStep functions sequentially
• AgentStep wraps Agent[string] as a pipeline step
• TransformStep for pure string transformations
• ParallelSteps runs steps concurrently and joins results
• ConditionalStep branches based on a predicate
• Then appends steps immutably (returns new pipeline)

Innovation 8: Auto Context Window Management

• AutoContextConfig with token threshold, keep-last-N, optional summary model
• WithAutoContext agent option for transparent overflow handling
• Simple word-based token estimation (no external deps)
• Summarizes old messages via model call when threshold exceeded

Innovation 9: Streaming Text Options

• StreamText with StreamTextOptions (delta mode, debounce window)
• StreamTextDelta for raw incremental chunks
• StreamTextAccumulated for growing accumulated text
• StreamTextDebounced for grouped event delivery
• Returns iter.Seq2[string, error] consistent with existing streaming API

Innovation 10: Agent Middleware

• AgentMiddleware wraps model calls with cross-cutting concerns
• WithAgentMiddleware agent option; middleware compose in order (first = outermost)
• LoggingMiddleware logs request/response summaries
• MaxTokensMiddleware enforces token limits via ModelSettings
• TimingMiddleware records request durations
• Middleware can modify inputs, outputs, or skip the model call entirely

Phase 13: Ten Innovations from LangGraph, Pydantic-AI, OpenAI Agents SDK & AutoGen

Innovation 1: Rate Limiter Model Wrapper

• RateLimitedModel wraps any Model with token-bucket rate limiting
• NewRateLimitedModel with configurable requests-per-second and burst
• Requests exceeding rate are delayed, not rejected
• Context cancellation stops waiting requests

Innovation 2: Response Cache Model Wrapper

• CacheStore interface with MemoryCache implementation
• NewMemoryCacheWithTTL for TTL-based expiration
• CachedModel wraps Model to cache Request() responses by SHA-256 hash
• Streaming requests bypass cache

Innovation 3: Tool Timeout / Deadline

• WithToolTimeout per-tool execution deadline via context.WithTimeout
• WithDefaultToolTimeout agent-level default for tools without explicit timeout
• Per-tool timeout takes precedence over agent default

Innovation 4: Composable Run Conditions

• RunCondition predicate checked after each model response
• Or() and And() combinators for composing conditions
• Built-in conditions: MaxRunDuration, TextContains, ToolCallCount, ResponseContains
• WithRunCondition agent option
• RunConditionError error type when condition triggers

Innovation 5: Handoff Context Filters

• HandoffFilter transforms messages at agent handoff boundaries
• Built-in filters: StripSystemPrompts, KeepLastN, SummarizeHistory
• ChainFilters for composing multiple filters in sequence
• ChainRunWithFilter for filtered agent chaining
• Handoff.AddStepWithFilter for filtered handoff pipeline steps

Innovation 6: Trace Exporter Interface

• TraceExporter interface for pluggable trace export
• JSONFileExporter writes JSON trace files to a directory
• ConsoleExporter prints human-readable trace summaries
• MultiExporter fans out to multiple exporters
• WithTraceExporter agent option (implicitly enables tracing)

Innovation 7: Agent Test Override

• Override() creates independent agent with replaced model
• WithTestModel() convenience returns agent + TestModel pair
• Original agent is never modified

Innovation 8: Retry with Exponential Backoff

• RetryModel wraps Model with configurable retry for transient failures
• RetryConfig with MaxRetries, InitialBackoff, MaxBackoff, BackoffFactor, Jitter
• DefaultRetryConfig targets HTTP 429/500/502/503
• Both Request and RequestStream retry

Innovation 9: Conversation State Snapshot

• RunSnapshot captures full run state (messages, usage, step)
• MarshalSnapshot / UnmarshalSnapshot for JSON round-trip
• Branch() creates independent copies for alternate-path exploration
• WithSnapshot RunOption to resume from saved state
• Hook-friendly capture via Snapshot(rc)

Innovation 10: Typed Event Bus for Agent Coordination

• EventBus with typed Subscribe / Publish / PublishAsync using generics
• Type-safe: subscribers only receive matching event types
• Unsubscribe via returned function from Subscribe
• Built-in events: RunStartedEvent, RunCompletedEvent, ToolCalledEvent
• WithEventBus agent option; bus accessible via RunContext.EventBus
• Thread-safe under concurrent access

Phase 12: Ten Innovations from Pydantic-AI & LangChain/LangGraph

Innovation 1: Agent Lifecycle Hooks

• Hook struct with 6 event callbacks: OnRunStart, OnRunEnd, OnModelRequest, OnModelResponse, OnToolStart, OnToolEnd
• WithHooks agent option for registering multiple hooks in order
• All hooks fire at correct points in the agent run loop

Innovation 2: Prompt Templates

• PromptTemplate with Go text/template syntax ({{.VarName}})
• NewPromptTemplate, MustTemplate, Format, Partial, Variables API
• WithSystemPromptTemplate agent option for template-based system prompts
• TemplateVars interface for custom deps types

Innovation 3: Input Guardrails

• InputGuardrailFunc validates/transforms prompts before the agent loop
• TurnGuardrailFunc validates messages before each model request
• GuardrailError distinct error type with guardrail name
• Built-in guardrails: MaxPromptLength, ContentFilter, MaxTurns

Innovation 4: Batch Execution

• RunBatch executes multiple prompts concurrently with ordered results
• WithBatchConcurrency controls parallel execution limit
• Context cancellation aborts all in-flight runs

Innovation 5: Model Router

• ModelRouter interface and RouterModel implementing Model
• ClassifierRouter for function-based routing
• ThresholdRouter for prompt-length-based model selection
• RoundRobinRouter for even distribution across models

Innovation 6: Conversation Memory Strategies

• SlidingWindowMemory keeps last N message pairs
• TokenBudgetMemory drops oldest messages to fit token budget
• SummaryMemory uses a model to summarize older messages
• All implement HistoryProcessor for use with WithHistoryProcessor

Innovation 7: Output Auto-Repair

• RepairFunc[T] intercepts parse failures before retry flow
• WithOutputRepair agent option for custom repair logic
• ModelRepair[T] helper uses a model to fix malformed JSON
• Repaired output still runs through validators

Innovation 8: Agent Composition

• Clone creates independent agent copies with additional options
• ChainRun pipes agents: first output transforms to second prompt
• ChainRunFull returns both intermediate and final results with combined usage

Innovation 9: Structured Run Traces

• RunTrace captures all execution steps with timestamps and durations
• TraceStep with kinds: model_request, model_response, tool_call, tool_result
• WithTracing agent option; trace available on RunResult.Trace
• JSON-serializable for debugging, replay, and compliance auditing

Innovation 10: Tool Result Validators

• ToolResultValidatorFunc validates tool results before passing to model
• Per-tool validators via WithToolResultValidator tool option
• Agent-wide validators via WithGlobalToolResultValidator
• Invalid results become RetryPromptPart with validation error

Phase 11: Ten Innovations

Innovation 1: KnowledgeBase Interface

• KnowledgeBase interface for pluggable RAG, graph databases, and memory services
• Agent transparently calls Retrieve() before each request and Store() after successful runs
• StaticKnowledgeBase for testing and simple use cases
• WithKnowledgeBase and WithKnowledgeBaseAutoStore agent options

Innovation 2: Message Serialization API

• MarshalMessages / UnmarshalMessages for JSON round-trip of conversations
• Envelope pattern with kind and type discriminators for all part types
• RunResult.AllMessagesJSON() and NewMessagesJSON() helpers

Innovation 3: Multimodal Message Parts

• ImagePart, AudioPart, DocumentPart types implementing ModelRequestPart
• BinaryContent() helper for base64 data: URI generation
• Full serialization support for multimodal parts

Innovation 4: Tool Prepare Functions

• Per-tool PrepareFunc for dynamic include/exclude/modify at each agent step
• Agent-wide WithToolsPrepare for bulk tool filtering
• Context-based tool availability (e.g., hide tools based on run state)

Innovation 5: Deferred Tool Calls

• CallDeferred error type for tools that pause the agent for external resolution
• RunResultDeferred / ErrDeferred for clean deferred signaling
• WithDeferredResults to resume runs with externally-resolved tool results
• Mixed deferred and normal tool calls in the same step

Innovation 6: Graph Fan-Out / Map-Reduce

• FanOutNode for parallel branch execution via goroutines
• Send[S] directives and ReduceFunc for state merging
• Error propagation from parallel branches
• Mermaid diagram support for fan-out nodes

Innovation 7: Checkpoint Replay, Fork, and Tool State

• GetHistory() for browsing checkpoint history
• ReplayFrom() to resume from any checkpoint step
• ForkFrom() to branch with modified state
• StatefulTool interface for tool state persistence across checkpoints
• ExportToolStates / RestoreToolStates for checkpoint-aware tools

Innovation 8: Persistent Memory Store

• Store interface with namespace-scoped CRUD and search
• MemoryStore (in-memory, thread-safe) implementation
• SQLiteStore (persistent, pure-Go via modernc.org/sqlite)
• StoreKnowledgeBase adapter bridging Store to KnowledgeBase interface
• MemoryTool for agent-accessible memory operations

Innovation 9: Step-by-Step Evaluation

• StepEvaluator interface for per-step scoring
• Built-in evaluators: MaxStepsEvaluator, NoRetryEvaluator
• Step scores in CaseResult and aggregated reports

Innovation 10: TUI Agent Debugger

• Terminal UI using bubbletea with color-coded message display
• Step mode (press 's') and auto mode (press 'a') for agent execution
• Tool call formatting, usage stats, and scroll navigation
• cmd/gollem CLI entry point for interactive debugging

Phase 10: Innovations

• Provider fallback chains — FallbackModel tries multiple models in order until one succeeds
• Rate limiting middleware — token bucket rate limiter with configurable rps and burst
• Retry middleware with exponential backoff — configurable max retries, delay caps, RetryIf predicates
• Request/response caching middleware — SHA-256 hash-based cache with TTL expiration and stats
• Reflection/self-correction pattern — RunWithReflection loops output through a validator with configurable iterations

Phase 9: Documentation, README & Examples

• Comprehensive README.md with quick start, architecture diagram, and feature documentation
• CONTRIBUTING.md with development setup, code style, and PR process
• CHANGELOG.md documenting all phases
• New examples: temporal, evaluation, multi-agent delegation, deep context management, graph workflows

Phase 8: Extended MCP & Observability

• SSE transport for MCP servers
• Multi-server Manager with namespaced tool aggregation
• ToolSource interface for unified client usage
• OpenTelemetry tracing and metrics middleware
• Streaming middleware support

Phase 7: Evaluation Framework

• Dataset and Case types for structured evaluation
• Built-in evaluators: ExactMatch, Contains, JSONMatch, Custom, LLMJudge
• Runner with multi-evaluator support
• Report aggregation with pass/fail scoring

Phase 6: Multi-Agent Framework

• Agent delegation via AgentTool
• Sequential handoff pipelines
• Typed graph engine with conditional branching and cycle detection
• Mermaid diagram generation

Phase 5: Temporal Durable Execution

• TemporalModel wrapping model requests as activities
• Tool call wrapping as activities
• TemporalAgent orchestrator
• Activity collection for worker registration

Phase 4: Deep Package -- Planning & Checkpointing

• Planning tool for multi-step task coherence
• Checkpoint save/load/resume system
• Custom JSON serialization for ModelMessage interfaces
• LongRunAgent wrapper combining all deep features

Phase 3: Deep Package -- Context Management

• Three-tier context compression (offload large results, offload inputs, LLM summarization)
• Token estimation utility
• Filesystem-backed context store
• ContextManager as HistoryProcessor

Phase 2: Core Framework Enhancements

• Dynamic system prompts (WithDynamicSystemPrompt)
• History processors (WithHistoryProcessor)
• Human-in-the-loop tool approval (WithToolApproval)
• Node-by-node agent iteration (Agent.Iter)
• Concurrency and tool call limits
• Toolsets for grouped tool management

Phase 1: Go Best Practices & Infrastructure

• Makefile with comprehensive targets
• golangci-lint v2 configuration
• GitHub Actions CI/CD workflows
• MIT License and .gitignore
• Testable examples