Colin4k1024/Aetheris

Aetheris is a Go-based platform for building, executing, and auditing durable AI agent workflows. It provides a runtime that manages agent lifecycles with deterministic replay, checkpointing, and idempotent tool execution to ensure reliability. The system includes comprehensive observability, forensic evidence tracking, and multi-tenant compliance controls for monitoring and verifying agent decisions.

A new mock LLM server has been added to the \cmd/llm-mock\ directory to support CI testing. This service implements a minimal OpenAI-compatible API, handling \POST /v1/chat/completions\ and \GET /v1/models\ requests by returning valid, static responses without invoking a real model. It also exposes a \GET /health\ endpoint for Docker health checks. By default, the server listens on port 11434, but this can be overridden via the \LLM\_MOCK\_ADDR\ environment variable. This allows performance gates to measure runtime throughput independently of external LLM providers like Ollama or OpenAI.

cmd/llm-mock · high confidence

Introduces a new agent execution layer in the internal runtime using the CloudWeGo Eino framework. This change adds a concrete implementation supporting React and DEER agent patterns, providing both synchronous (Invoke) and streaming (Stream) execution capabilities for users interacting with the agent system.

_internal/agent/runtime/executor/eino\agent · high confidence

The agent can now connect to external Model Context Protocol (MCP) servers using either stdio (subprocess) or SSE (HTTP Server-Sent Events) transports. This change introduces the \internal/agent/tools/mcp\ package, which includes a \Manager\ to handle multiple server connections, a \Client\ for protocol-level interactions (initialization, tool discovery, and tool calling), and transport implementations for both stdio and SSE. Users can configure server connections via \ServerConfig\ (specifying command/args for stdio or URL/headers for SSE) and the system will automatically discover and expose available tools from these servers.

internal/agent/tools/mcp · high confidence

The internal/model/vision package now provides a Client interface and an OpenAIVisionClient implementation that allows the system to describe images via the OpenAI Chat Completions API. Users can pass image URLs, base64-encoded data, or data URIs (limited to JPEG, PNG, GIF, and WebP, max 20 MB) to receive text descriptions. A StubClient is also included for testing purposes, and configuration is handled via a Config struct supporting provider selection (currently 'openai' and 'stub').

internal/model/vision · high confidence

The new verify package introduces a verification capability for job executions, allowing users to validate the integrity and consistency of job history. It computes an execution hash based on the plan and node results, generates an event chain root hash to ensure event immutability, and provides a ledger proof to confirm that every tool invocation has a matching finish or failure event. Additionally, it supports replay proofs to verify consistency between the event stream and a replay context, exposing these results via a structured API for CLI or external consumption.

internal/agent/verify · high confidence

The \artifacts/readme-scenario-proof\ directory now contains the configuration files, raw logs, and embedded data stores used to verify the README quickstart and \external\_http\ batch demo. This includes \api.demo.yaml\ and \worker.demo.yaml\ for local embedded mode, logs (\api.demo.log\, \crash\_recovery\_demo\_success.log\), and JSON evidence files (\jobs.json\, \job\_events.json\, \checkpoints.json\, \effects.json\, \tool\_invocations.json\, \agent\_state.json\) that capture the full execution trace of a batch job. A Python script (\render\_readme\_scenario\_gifs.py\) is also included to generate the GIF deliverables from these artifacts.

artifacts · high confidence

The internal/einoext package now supports configuring Redis as a vector storage backend. A new config.go file provides logic to construct Redis client options from VectorConfig, ensuring Protocol 2 and UnstableResp3 are enabled for Redis Stack vector search compatibility. The factory.go file introduces NewIndexer and NewRetriever functions that, when the vector type is set to 'redis', instantiate cloudwego/eino-ext Redis indexer and retriever components. Comprehensive unit tests in config\_test.go validate the configuration parsing, including default address fallback, DB selection, and protocol settings.

internal/einoext · high confidence

The system now includes a persistent signal inbox in the agent's signal package to ensure at-least-once delivery of job signals. This change introduces a \SignalInbox\ interface with \Append\ and \MarkAcked\ operations, implemented via an in-memory store (\inbox\_mem.go\) for single-process or testing scenarios and a PostgreSQL-backed store (\inbox\_pg.go\) for production use. The implementation guarantees that signals are persisted before being marked as acknowledged, preventing data loss during API crashes, and includes unit tests to verify the correctness of these operations.

internal/agent/signal · high confidence

The embedded storage package now includes \json\_file.go\, which provides \LoadJSON\ and \SaveJSON\ functions for reading and writing JSON data to the local filesystem. \LoadJSON\ treats missing or empty files as empty state, while \SaveJSON\ ensures atomic writes by using a temporary file and rename operation, automatically creating parent directories as needed. This change is accompanied by a new test file (\json\_file\_test.go\) that validates these behaviors, including handling of non-existent paths, empty files, valid data, and nested directory creation.

internal/storage/embedded · high confidence

The \aetheris init\ command now scaffolds a new project using a minimal agent template located in \cmd/cli/templates/agent-minimal\. This template includes a pre-configured \api.yaml\ (using in-memory storage and default ports), a \README.md\ with setup instructions, and a \main.go.example\ demonstrating how to initialize an OpenAI-based chat agent using the CloudWeGo Eino ADK library. This provides users with a ready-to-run starting point for building agents on the Aetheris platform.

cmd/cli/templates · high confidence

A new pre-commit hook has been added to automatically format staged Go files using gofmt before they are committed. This ensures consistent code style without requiring manual intervention from developers.

.githooks · high confidence

The \internal/agent/replay\ package now provides a complete framework for deterministically resuming agent jobs by replaying their event history. It introduces a \History\ iterator to consume job events, a \ReplayContext\ that reconstructs execution state (including completed nodes, tool invocation results, and recorded randomness/time/HTTP) from the event log, and a \ReplayContextBuilder\ that supports both full event replay and optimized snapshot-based restoration. To ensure safety, the package includes a verification system with pluggable \ExternalStateVerifier\ implementations (such as \ToolLedgerVerifier\ and \DatabaseStateVerifier\) that check external resource states before deciding whether to skip execution or fail. This allows the agent to resume from checkpoints without re-executing completed steps or violating external state consistency.

internal/agent/replay · high confidence

The configuration model has been significantly expanded to support new operational capabilities. Users can now configure runtime profiles (dev/prod) with strict validation gates, garbage collection with optional archival retention, and granular rate limiting for both LLM providers and tools. Security settings now include mTLS, API signing, evidence signing, and IP allowlisting. Storage backends for jobs, effects, and checkpoints are explicitly configurable (memory, postgres, or embedded), and the schema supports agent definitions, MCP transport, and Hermes integration settings.

pkg/config · high confidence

The Hermes runtime now includes an ACP client (acp\_client.go) that enables bidirectional communication with the Hermes ACP Server, allowing users to dispatch jobs, send tool results and checkpoints to Aetheris, and query job status. This is supported by new data structures in job\_dispatch.go defining job dispatch messages and event types (such as tool calls, session start/end, and checkpoints) required for the integration.

internal/runtime/hermes · high confidence

This change introduces the generated Go protocol buffer code for the internal gRPC API, establishing the foundational service contracts for the application. Specifically, it adds the DocumentService (supporting list, get, delete, and upload operations), the JobService (handling submission, status retrieval, cancellation, heartbeats, and listing), and the QueryService (providing single and batch query capabilities). These files define the request and response message structures and client/server interfaces required for the gRPC communication layer.

internal/api/grpc/pb · high confidence

This change introduces the foundational in-memory storage implementations for both object storage and vector search capabilities within the internal storage layer. For object storage, it adds a \MemoryStore\ supporting Put, Get, Delete, List, and Exists operations, along with a \File\ metadata struct and a factory function (\NewStore\) that defaults to the memory backend when no specific type is configured. For vector storage, it provides a \MemoryStore\ capable of creating indexes, adding vectors, performing similarity searches with optional thresholds and metadata filters, and managing index lifecycle (Create, Delete, List). Comprehensive unit tests are included for both modules to verify core functionality and error handling, such as dimension mismatches and missing resources.

internal/storage/vector · high confidence

This change introduces the foundational data layer for the Human-in-the-Loop (HITL) approval engine. It defines the core domain types for approval requests and responses, including support for various approver types (anyone, specific user, or role) and decision states (pending, approved, rejected, expired). Additionally, it provides an in-memory store implementation (\MemStore\) that handles the creation, retrieval, and completion of approval requests, serving as a lightweight backend suitable for testing or single-instance deployments.

internal/agent/approval · high confidence

The repository is now structured for public open-source distribution with the addition of essential governance and onboarding files. This includes an Apache 2.0 LICENSE, contributor guidelines (CONTRIBUTING.md), a Code of Conduct, and a community growth plan. Developer experience is enhanced with a comprehensive Makefile for building and running services, a golangci-lint configuration, and detailed project documentation (AGENTS.md, CLAUDE.md) that outlines the Aetheris architecture, build commands, and code style. A CHANGELOG.md is also introduced to track version history starting from v2.5.3.

(repo-wide) · high confidence

This release adds new capabilities for auditing AI-driven decisions. In the \pkg/ai\_forensics\ package, the system now detects anomalies in job execution steps, flagging issues such as missing evidence, inconsistent results, timing deviations, low confidence, suspicious retry loops, and tampered reasoning, while also identifying broader suspicious patterns like approval bypasses and repeated failures across multiple jobs. In the \pkg/monitoring\ package, a new quality scorer evaluates individual decisions based on evidence completeness, evidence quality, confidence, and human oversight, translating these metrics into SRE-facing alert levels (healthy, degraded, critical, or noisy) to help operators quickly identify and respond to declining decision quality.

_pkg/ai\forensics, pkg/monitoring · high confidence

The \cmd/cli\ package now provides the \aetheris\ command-line interface, enabling users to manage agent jobs (list, trace, cancel, pause, resume, signal), monitor system observability, and verify forensic evidence. The CLI supports multi-tenancy via the \--tenant\ flag or \AETHERIS\_TENANT\_ID\ environment variable, automatically injecting the \X-Tenant-ID\ header into API requests. New capabilities include verifying job execution integrity through \verify\ (checking execution hashes, event chains, and ledger proofs) and validating signed evidence zips with public keys. The tool also offers debugging features like replay comparison and job export, connecting to the backend API (defaulting to \localhost:8080\) using the Resty HTTP client.

cmd/cli · high confidence

The \pkg/agent/sdk\ package now provides a high-level Agent facade and a strict Step programming model to ensure deterministic, replayable agent execution. Users can submit tasks via \Run\ or \RunWithSession\ and configure a wait timeout using \WithWaitTimeout\. The SDK enforces that Step functions avoid direct side effects (like \time.Now\ or \http.Get\) by requiring them to use the injected \RuntimeContext\ for time, UUIDs, HTTP calls, and job/step identification. It also defines \AgentRuntime\ and \DurableAgentRuntime\ interfaces for job submission and lifecycle management, along with a \ToolRegistrar\ interface for registering tools that are executed and recorded by the runtime.

pkg/agent/sdk · high confidence

The internal runtime now uses the CloudWeGo Eino framework (specifically the ADK package) to build and manage Agents, replacing the previous custom Plan→Execute loop. This change adds an AgentFactory that constructs ADK Runners from configuration, tool registries, and LLM models, supporting features like streaming, checkpointing, and tool filtering. It also introduces a memory-backed RuntimeRunStore for tracking run lifecycles (create, pause, resume, human-in-the-loop decisions) and events, as well as a HermesRunner for dispatching jobs to external agents via ACP protocol. Workflow execution is supported through a Node/Graph abstraction that wraps pipeline stages, with comprehensive unit and integration tests added for the factory, run store, components, and workflow engine.

internal/runtime/eino · high confidence

The \pkg/evidence\ package now includes a new \Builder\ component that constructs a causal dependency graph from \reasoning\_snapshot\ events. This feature allows users to visualize and trace the flow of data between job steps by parsing input and output keys to create directed edges. The implementation supports detailed evidence nodes, including RAG document references, tool invocations, and LLM decision metadata (model, provider, temperature, token count), and ensures the resulting graph structure is serializable for export.

pkg/evidence · high confidence

The planner package now provides a structured approach to agent decision-making, introducing an \LLMPlanner\ that generates executable plans via LLM calls and a \RulePlanner\ for deterministic, rule-based task graphs. These planners implement a common interface to produce \TaskGraph\ structures, which define nodes for tools, workflows, LLM calls, and wait/approval states. The new \TaskGraphExecutor\ runs these graphs sequentially, dispatching each node to the appropriate runner (Tool, Workflow, or LLM) and handling errors or missing configurations gracefully. This change shifts the agent's core logic from ad-hoc execution to a defined planning and execution pipeline, supporting complex multi-step interactions and session-based context.

internal/agent/planner · high confidence

Added the internal/tool/mcp package to provide a Model Context Protocol (MCP) server implementation and a plugin loading system. The server exposes registered tools, resources, and prompts via JSON-RPC, enforcing security through the existing gatekeeper. Additionally, a plugin loader enables dynamic discovery and execution of external tools defined by JSON or YAML manifests, supporting both inline handlers and command-based tools.

internal/tool/mcp · high confidence

The routing package now includes a new RoutingAdvisor contract that enables evidence-first capability routing, allowing the system to select among tools, agents, adapters, models, or workflows based on scored candidates and runtime constraints. This change adds the core data structures for routing decisions, a deterministic NoOpAdvisor for local fallback, and SHA-256 hashing to ensure decision integrity and tamper detection during replay. Configuration is handled via NewAdvisorFromConfig, which supports noop and remote modes (with remote currently returning an error) and validates fallback policies. The package also introduces a FailoverHandler for model-level failover with retry and hot-switch logic, along with Prometheus metrics for tracking selections, latency, fallbacks, costs, errors, retries, and active requests. Comprehensive fixture-driven tests and a 9-step recovery validation suite verify that routing decisions are deterministic, replay-safe, and structurally valid.

pkg/routing · high confidence

Added the internal agent instance layer, defining the \AgentInstance\ data model (including \CurrentJobID\ and \BehaviorID\ fields) and a persistence interface (\AgentInstanceStore\). This includes an in-memory implementation (\StoreMem\) for development and a PostgreSQL implementation (\StorePg\) for production, enabling the system to create, update, and track the lifecycle status of agent instances within a tenant.

internal/agent/instance · high confidence

The internal/agent/messaging package now provides a structured messaging system for inter-agent communication, featuring an \AgentMessagingBus\ interface for sending immediate and delayed messages, and an \InboxReader\ interface for consuming messages. The implementation includes an in-memory store (\StoreMem\) for development and a PostgreSQL-backed store (\StorePg\) for production, both supporting message kinds (user, signal, timer, webhook, agent), causation IDs for tracing, and idempotency keys. Tests verify message creation, inbox peeking/consuming, and consumption tracking.

internal/agent/messaging · high confidence

The internal agent runtime now provides the core infrastructure for managing agent lifecycles, including state management, checkpointing, and scheduling. Agents can now be created, retrieved, and deleted via a Manager, with atomic Take/Release semantics to handle concurrency. Checkpointing is supported via an in-memory store, a file-backed embedded store, and a PostgreSQL implementation, allowing agents to save and restore their state (including task graph and memory) for resilience and replay. A Scheduler handles waking, suspending, and resuming agents, with a distributed variant using Redis locks for multi-instance deployments. Additionally, deterministic replay is enabled through context-injected clocks and RNGs, and async events can be emitted for tracing.

internal/agent/runtime · high confidence

This change adds a suite of new built-in tools to the \internal/tool/builtin\ package, including \http.request\ for making HTTP calls, \llm.generate\ for text generation, \knowledge.search\ and \knowledge.add\_document\ for RAG-based retrieval and ingestion, and \workflow.run\ for executing registered workflows. It also introduces an Effects Isolation Layer (\EffectsToolAdapter\ and \EffectsToolRegistry\) that wraps these tools to enable deterministic replay and idempotency, ensuring consistent behavior during agent execution.

internal/tool/builtin · high confidence

This change adds the foundational types and interfaces for the internal tool system, enabling the definition, validation, and execution of tools. It introduces the \Tool\ interface with methods for name, description, schema generation, and execution, alongside \ToolDescriptor\ and \ParameterConstraint\ structs that allow tools to define their input parameters with strict validation (e.g., type checking, min/max constraints). The update also includes \ToolResult\ for execution outcomes and a set of error types (\HTTPError\, \ValidationError\, \NetworkError\, etc.) in the \types\ package to handle failures consistently. This provides the structural basis for integrating tools into the agent runner.

internal/tool · high confidence

The \pkg/effects\ package now provides an isolation layer that wraps non-deterministic operations (LLM, HTTP, tools, random, sleep) to enable deterministic replay. By routing these calls through a central \EffectSystem\, the library records inputs and outputs, allowing subsequent executions in replay mode to return cached results instead of performing real external calls. This ensures idempotency via computed keys and supports event recording for observability, while \crypto/rand\ is used for secure random generation.

pkg/effects · high confidence

Added a new distributed verification subsystem in pkg/distributed that enables cross-organization event ledger synchronization and consensus checking. The package defines a SyncProtocol interface and request/response types (LedgerSyncRequest, LedgerSyncResponse) for pushing and pulling events between organizations. A DistributedVerifier component aggregates root hashes from multiple orgs to detect divergences and report consensus status, with configurable event sources (protocol-backed or custom). Additionally, a readiness assessment mechanism (AssessPromotionReadiness) enforces operational evidence requirements—such as single-node saturation, lease/recovery failure modes, and root hash drills—before the distributed verifier can be promoted beyond prototype. Comprehensive unit and integration tests cover consensus, divergence detection, empty inputs, and mock source scenarios.

pkg/distributed · high confidence

This change adds the \internal/model/embedding\ package, defining an \Embedder\ interface that standardizes text-to-vector conversion. It includes a production-ready \OpenAIEmbedder\ implementation that calls the OpenAI embeddings API (supporting custom base URLs via the \OPENAI\_BASE\_URL\ environment variable and requiring an API key), a legacy \OpenAIAdapter\ for backward compatibility, and a \mockEmbedder\ that generates deterministic, non-zero vectors for testing and demo purposes. Comprehensive unit tests are provided for both the mock and OpenAI implementations, covering default configurations, error handling, and vector consistency.

internal/model/embedding · high confidence

The agent now features a comprehensive memory architecture comprising short-term, working, episodic, and long-term memory layers. Short-term memory manages conversation history per session with configurable limits, while working memory tracks intermediate task results and session variables. Episodic memory stores detailed event records with support for both in-memory and PostgreSQL backends, and long-term memory provides persistent key-value storage across sessions, also available in memory or PostgreSQL variants. A composite memory interface allows combining these layers for unified recall and storage operations.

internal/agent/memory · high confidence

The auth package now supports multi-tenancy and role-based access control. It introduces context helpers to inject and retrieve tenant ID, user ID, and role, ensuring these identifiers are available throughout the request lifecycle. A new RBAC system defines roles (admin, operator, auditor, user) with specific permissions (e.g., job view, create, stop, export) and provides a checker to enforce them. Tenant isolation is enforced by scoping role assignments and checks to specific tenant IDs. The system includes a Postgres-backed role store for production use, which initializes an \rbac\_roles\ table, and an in-memory store for testing or single-instance deployments. Additionally, tenant models and quotas (for jobs, storage, exports, and agents) are defined to support tenant lifecycle and resource management.

pkg/auth · high confidence

The \pkg/agent\ package now provides a high-level \Agent\ facade that simplifies interacting with the underlying LLM planner and executor. Users can create an agent with optional LLM clients (defaulting to OpenAI gpt-3.5-turbo if \OPENAI\_API\_KEY\ is set) and configure execution parameters like maximum steps. The agent supports stateful conversations via \RunWithSession\, allowing multiple runs to share history under a specific session ID. It also exposes \Tool\ and \RegisterTool\ methods, enabling developers to register custom simple functions or full \tools.Tool\ implementations that become visible to the planner and executable by the runner. Context options allow per-call overrides for timeouts and step limits.

pkg/agent · high confidence

Added a new session management layer in the runtime to handle AI task lifecycles, conversation history, and persistent state. This includes a \SessionManager\ for creating and retrieving sessions, a \Session\ struct that tracks short-term conversation messages, long-term memory blocks, and working state, and a \Message\ type for handling LLM-aligned conversation turns. The implementation provides a \MemoryStore\ for in-memory persistence and includes comprehensive integration and unit tests to verify session isolation, concurrent access safety, and tenant separation.

internal/runtime/session · high confidence

The metrics package now exposes a comprehensive set of Prometheus metrics for the Aetheris runtime, all scoped by tenant. This includes histograms for LLM call and DAG node execution durations, counters for LLM tokens and retries, and gauges for worker and queue states. These metrics enable monitoring of multi-tenant job performance, SLOs, and resource usage directly from the metrics subsystem.

pkg/metrics · high confidence

The internal storage cache layer now provides a unified \Store\ interface that can be instantiated via \NewCache\ based on configuration. Users can choose between an in-memory store (default for empty or "memory" types) and a Redis-backed store (for "redis" type), which supports key prefixing, tenant isolation, and automatic connection-pool metrics collection. The change includes the core factory logic, the Redis implementation with JSON serialization and metrics instrumentation, and the memory implementation, along with corresponding unit tests for creation, get/set/delete, existence checks, and clear operations.

internal/storage/cache · high confidence

This change establishes the integration contract between the L1 agent and the L3 governance service (hermesx) by defining interfaces and data structures for policy evaluation, compliance constraints, and audit event reporting. It also introduces a new routing subsystem that includes a \RoutingAdvisor\ interface for selecting execution capabilities, deterministic hash computation for recording and verifying routing decisions, and a local fallback advisor to handle routing when the external service is unavailable.

internal/agent/governance, internal/agent/routing · high confidence

The agent's job management layer now supports durable, resumable execution. Jobs can be persisted to a local JSON store and recovered via checkpoints, allowing long-running tasks to survive restarts. Execution plans are modeled as directed acyclic graphs (DAGs) with topological sorting and dependency tracking, enabling parallel and ordered step execution. Tool invocations are tracked in an in-memory ledger that enforces idempotency via SHA-256 keys, preventing duplicate work on retries. The system also includes high-availability safeguards, such as orphaned job reclamation when workers crash, and supports multi-tenancy, queue-based prioritization, and capability-aware worker dispatching.

internal/agent/job · high confidence

The scheduler now supports reliable job execution through a new lease management system that allows workers to claim jobs and maintain ownership via heartbeats, enabling automatic reclamation of jobs if a worker becomes unresponsive. It includes a Redis-based leader election mechanism for coordinating distributed agents and a fair queue scheduler that uses weighted round-robin selection to prevent low-priority tasks from starving. These components work together to ensure jobs are correctly assigned, monitored, and migrated when necessary.

internal/agent/scheduler · high confidence

A new model registry has been added to the internal model package, enabling the registration and retrieval of LLM, Embedding, and Vision clients by name. This allows the application to dynamically switch between different model implementations at runtime. The registry includes thread-safe registration and lookup functions for each model type, along with corresponding unit tests that verify error handling for unregistered models.

internal/model · high confidence

A new main entry point for the API service has been added, establishing the application bootstrap process. This entry point introduces a command-line flag to enable development mode, which switches the configuration to use in-memory stores and disables authentication, while the default production mode loads configuration via a model-based loader. The service initializes the API application and starts listening on port 8080 (or a configured port), with graceful shutdown handling for interrupt signals.

cmd/api · high confidence

A new tool registry has been added to the internal package to manage the lifecycle of available tools. This component allows tools to be registered, retrieved by name, and listed, while specifically providing a method to serialize their schemas (name, description, and parameters) into JSON for consumption by the LLM planner. Unit tests have been included to verify registration, lookup, listing, and schema serialization behaviors.

internal/tool/registry · high confidence

The LLM client layer now supports Ollama and Qwen providers via the \NewClient\ factory, with OpenAI clients accepting a configurable base URL for compatibility with other endpoints. All provider clients (OpenAI, Claude, Gemini) have been refactored to use standard \json.Unmarshal\ for response parsing and their error messages have been translated to English. A new rate-limiting system has been introduced, featuring an \LLMRateLimiter\ that enforces per-provider limits on requests, tokens, and concurrency, wrapped by a \RateLimitedClient\ that also records token usage metrics. Additionally, an \EffectAdapter\ wraps LLM calls to enable deterministic replay and idempotency through the effects system.

internal/model/llm · high confidence

The \tools/mcp-marketplace\ directory has been renamed to \tools/mcp-gateway\ and now includes an \openapi.yaml\ specification for the gateway's HTTP+SSE/JSON-RPC interface. This location also introduces four new MCP tool templates—GitHub, Filesystem, Web Search, and Database—each with Go implementations, manifests, and configuration schemas, alongside a \registry.yaml\ for tool discovery and a \CONTRIBUTING.md\ guide for adding new tools.

tools · high confidence

The metadata storage layer now supports multi-tenancy by adding a TenantID field to the Document model and Filter struct, with the in-memory store updated to enforce tenant isolation during list and count operations. A new Repository wrapper is introduced to encapsulate store interactions, providing a consistent interface for document CRUD and listing operations, accompanied by comprehensive unit tests for both the memory store and the repository.

internal/storage/metadata · high confidence

Added a new handler file (internal/api/acp\_handler.go) that implements the POST /api/acp/events endpoint. This endpoint receives tool and session events (such as tool.call, tool.result, session.start, session.end) from the Hermes system, validates the request fields (job\_id, type), parses timestamps, and maps these events to internal job store event types (JobRunning, JobCompleted, JobFailed, etc.) for storage. It also defines the necessary data structures (ACPEventRequest, ACPCheckpointRequest, HermesACPToolCall) and interfaces (ACPSEventStore) to support this integration.

internal/api · high confidence

The templates directory now includes four ready-to-use workflow templates for the Aetheris/CoRag agent framework: a Customer Service Agent with intelligent triage and human approval workflows, a RAG Assistant combining vector search with LLM generation for cited answers, a Multi-Agent Debate system with structured rounds and moderation, and an Autonomous Researcher that performs deep, multi-source research with verification. Each template provides configuration files (agents.yaml) and workflow definitions (workflow.go) using the TaskGraph API, along with documentation and usage examples to help users quickly deploy these agent patterns.

templates · high confidence

This change introduces a complete Docker Compose deployment configuration for the CoRag API and Workers, including a multi-stage Go 1.26 Dockerfile, environment variable examples, and a README with startup and verification instructions. It adds a CI-specific compose override that injects a mock LLM service to enable automated testing without external dependencies, and an embedded runtime compose file for local-first operation without an external database. The stack also provisions Prometheus for metrics collection and Grafana with pre-configured dashboards for job throughput, scheduler performance, and worker load, alongside Jaeger for distributed tracing.

deployments/compose · high confidence

This change introduces a comprehensive integration layer for the CloudWeGo Eino framework within the API application. It adds adapters to bridge internal components (LLM clients, tool registries, memory providers) with Eino interfaces, enabling the use of Eino's retrievers, generators, and chat models. The update includes a new v1 Agent API implementation that supports DAG-based execution plans, configurable agents via YAML, and external agent intake (e.g., LangGraph, external HTTP). It also adds an ADK (Agent Development Kit) runner for chat-based agents with checkpointing, a new DAG compiler for task graphs, and an attempt validator for lease fencing during job execution. Tests cover the new adapters, agent creation, and external agent integration.

internal/app/api · high confidence

Added new files in the ingest package to integrate with the CloudWeGo Eino framework: \doc\_convert.go\ provides conversion functions between internal \common.Document\/\common.Chunk\ types and Eino \schema.Document\ types; \eino\_loader.go\ implements an Eino \document.Loader\ (\URIDocumentLoader\) that wraps the existing loader to support local file paths and \file://\ URIs; \eino\_transformer.go\ implements an Eino \document.Transformer\ (\SplitterTransformer\) that chains the existing parser and splitter; \eino\_indexer.go\ implements an Eino \indexer.Indexer\ (\MemoryIndexer\) backed by the internal vector store, handling batching and optional embedding; \parser\impl.go\ adds concrete Markdown and HTML parsers with raw-mode support; and \pdf.go\ adds PDF text extraction using \unidoc/unipdf/v3\. Corresponding test files (\\\_test.go\) were added to cover these new components.

internal/pipeline/ingest · high confidence

The \pkg/tracing\ package has been introduced to provide distributed tracing capabilities using OpenTelemetry. It includes initialization functions (\InitTracer\, \InitTracerWithPrometheus\) that support exporting traces to Jaeger, OTLP (gRPC/HTTP), Prometheus, or stdout. The package also exposes a legacy-compatible \Span\ API that bridges to the global OpenTelemetry tracer, ensuring backward compatibility while enabling modern observability features like job, node, tool, and DAG span tracking.

pkg/tracing · high confidence

The \pkg/redaction\ package introduces a new capability to detect and mask personally identifiable information (PII) in JSON event data. The \PIIDetector\ component uses regular expressions to identify common PII types such as emails, phone numbers, SSNs, credit cards, IP addresses, and more. The \Engine\ component applies configurable \RedactionPolicy\ rules to JSON payloads, supporting four masking modes: \Redact\ (replaces with a placeholder), \Hash\ (SHA256 with optional salt), \Encrypt\ (AES-256-GCM), and \Remove\ (deletes the field). Policies can be defined per event type or globally, and loaded from YAML configuration.

pkg/redaction · high confidence

The \internal/agent/runtime/executor/eino\_examples\ package now provides adapters that bridge the internal agent runtime with the \github.com/cloudwego/eino-examples\ library. This includes \ReactAgentAdapter\, \DEERAgentAdapter\, and \ManusAgentAdapter\ to execute agent workflows, as well as \OllamaChatModel\ and \OpenAIChatModel\ to wrap local LLM clients into the eino \ChatModel\ interface. The implementation supports both synchronous invocation and streaming responses, and includes unit and integration tests to verify correct behavior.

_internal/agent/runtime/executor/eino\examples · high confidence

The \pkg/proof\ package now provides a complete system for exporting, signing, and verifying job execution evidence. Users can generate tamper-evident ZIP packages containing event streams, tool invocation ledgers, and metadata, secured by SHA-256 hash chains and optional Ed25519 digital signatures. The system includes built-in verification to detect tampering, validate chain integrity, and ensure ledger consistency, with support for optional data redaction during export.

pkg/proof · high confidence

The system now includes a new compliance engine in \pkg/compliance\ that provides automated checking and reporting for SOC 2, GDPR, HIPAA, ISO 27001, and SOX standards. This engine introduces a \Checker\ for tenant-specific compliance status, a \Reporter\ that generates audit-ready reports with weighted compliance rates and explicit handling of unsupported controls, and pre-configured templates with specific redaction rules. HIPAA compliance is enforced via a dedicated checker that validates PHI encryption, retention, and data minimization, and requires runtime probes to verify encryption at rest and in transit. Additionally, a \DataResidencyController\ manages per-tenant data residency policies, allowing administrators to define allowed/blocked regions and enforce retention rules, with support for IP-based region resolution.

pkg/compliance · high confidence

A new \cmd/devops\ entry point has been added to start a local debugging service (listening on 127.0.0.1:52538) that registers example Eino graphs, enabling the Eino Dev IDE plugin to connect and visualize/debug these workflows.

cmd/devops · high confidence

The \internal/agent/effects\ package introduces a new \EffectLog\ interface and \JobStoreEffectLog\ implementation to standardize how external-impacting operations (LLM responses, tool results, external calls) are recorded in the event stream. This ensures that during replay, these operations are read from the log rather than re-executed, supporting deterministic state recovery. The package defines specific effect kinds (e.g., \llm\_response\_recorded\, \tool\_result\_recorded\) and maps them to existing job store event types, while also providing utilities for constructing command payloads.

internal/agent/effects · high confidence

The examples directory now includes comprehensive demos for integrating external agents, building customer service bots, and demonstrating crash recovery. The agent-integration example provides runnable Python and LangChain agent implementations with Docker Compose support, showing how to connect existing HTTP-based agents to Aetheris using configuration files for external\_http, langchain, and langgraph types. The ai-customer-bot example demonstrates a Go-based customer service agent with multi-turn conversation, human-in-the-loop approval workflows, and conversation history persistence. The crash\_recovery example showcases Aetheris's checkpointing capability by simulating a process crash mid-execution and resuming from the last checkpoint. These examples serve as practical references for common integration patterns and reliability features.

examples · high confidence

The forensics package now includes a query engine that allows users to search forensic jobs by time range, status, tool usage, and event keywords, with support for pagination. It also provides batch export of evidence packages as ZIP files and a consistency check to verify the integrity of the evidence chain (hash chain and ledger). This change introduces the core query logic, data types, and test coverage for these capabilities within the forensics module.

pkg/forensics · high confidence

The HTTP API now exposes new endpoints for AI forensics, compliance reporting, and runtime run management. Users can query job evidence, export signed ZIP packages with hash-chain validation, and check consistency via the forensics endpoints (controlled by an experimental flag). A new compliance API allows listing templates, applying standards (GDPR, SOX, HIPAA), and generating reports with verified evidence binding. Additionally, a runs API provides lifecycle management for workflow executions, including creating, pausing, resuming, and injecting human decisions, along with event streaming.

internal/api/http · high confidence

This change introduces the protocol buffer definitions for the new gRPC API layer, establishing the contract for three core services: DocumentService (for listing, retrieving, deleting, and uploading documents), QueryService (for single and batch queries), and JobService (for submitting, tracking, and canceling background jobs, including worker heartbeats). These proto files define the request and response structures that will enable programmatic access to these capabilities via gRPC, aligning with the existing HTTP capabilities.

internal/api/grpc/proto · high confidence

A new gRPC service implementation has been added to the internal API layer, providing programmatic access to core platform capabilities. This service exposes Document operations (listing, retrieving, deleting, and uploading via the ingest pipeline), Query operations (single and batch queries against the engine), and Job management (submitting, retrieving, canceling, and heartbeating). The implementation registers these services with the gRPC server and integrates with the existing Engine and DocumentService abstractions, allowing clients to interact with the system via a structured protocol alongside or instead of HTTP.

internal/api/grpc · high confidence

The internal/app package introduces a new application layer that centralizes service initialization and provides a facade for document operations. The Bootstrap struct now handles unified initialization of logging, metadata storage, and vector storage (supporting memory and Redis backends). A new DocumentService interface and its implementation expose document listing, retrieval, and deletion capabilities to the API layer, decoupling it from direct storage dependencies. Additionally, model client factories are added to instantiate LLM and embedding clients based on configuration, ensuring proper provider and model key parsing.

internal/app · high confidence

This change introduces two new internal tooling components. The \gatekeeper\ package provides a security and validation layer for tool parameters, enforcing required fields, type checking, host whitelisting/blacklisting, path traversal prevention, and rate limiting. The \lint\ package adds a static analysis tool that scans Go source code to ensure \ToolDescriptor\ definitions and schema-returning functions include required fields (Name, Description) and that all schema properties have descriptions, failing the build if errors are found.

internal/tool/gatekeeper · high confidence

The \pkg/security\ area now includes three new capabilities: mutual TLS (mTLS) support for gRPC and HTTP services, allowing users to configure server and client certificates with TLS 1.2 enforcement; an API request signing package (\signer\) that generates and verifies HMAC-SHA256/HMAC-SHA512 signatures for HTTP requests to ensure integrity and authenticity; and Single Sign-On (SSO) integration via OIDC and SAML protocols, enabling user authentication flows with token exchange, ID token verification, and SAML assertion handling.

pkg/security · high confidence

The scripts directory now includes a comprehensive set of tooling for local development and release validation. Developers can use bootstrap.sh to verify Go, PostgreSQL, and Redis prerequisites and build binaries, while local-2.0-stack.sh manages the Docker Compose environment with CI-aware overrides. The release-2.0.sh script orchestrates a suite of automated gates—including P0 performance benchmarks, tenant regression checks, and specific drills for evidence signing, forensics, and compliance—ensuring quality before release. Additionally, install.sh provides a quick-install mechanism for the v2.3.0 CLI, and migrate.sh simplifies database schema application.

scripts · high confidence

The HTTP middleware layer has been expanded with several new components to enforce security and compliance: an audit middleware that asynchronously logs API access details (tenant, user, action, resource, duration, IP) to a pluggable store (with a Postgres implementation provided); an authorization middleware that enforces RBAC permissions and tenant isolation; an IP allowlist middleware that validates client IPs against configurable allow/block lists and respects trusted proxies via X-Forwarded-For; an OIDC/SSO middleware handling login, logout, and callback flows; and a request-signing middleware that verifies cryptographic signatures on specified paths. These changes are specific to the internal/api/http/middleware package and complement the existing migration to the Hertz framework.

internal/api/http/middleware · high confidence

The agent executor now supports session management, allowing tool execution to be aware of the current session context. This introduces a new \SessionRegistryExecutor\ that passes session data to tools, alongside a legacy \RegistryExecutor\ for backward compatibility. The system also includes utilities to normalize input types (e.g., converting JSON floats to integers) and format execution results for the planner, enabling more robust and stateful agent planning loops.

internal/agent/executor · high confidence

The agent's tool execution model has been updated to support session-awareness and external dispatch. A new \tools.Tool\ interface now requires an \Execute\ method that accepts a \session.Session\ and optional state, enabling tools to resume interrupted operations. Existing built-in tools (RAG, Ingest, Workflow, LLM Generate, HTTP) are automatically wrapped to remain compatible with this new signature. A new \HermesDispatchTool\ allows the agent to offload coding, terminal, and messaging tasks to the Hermes-Agent via an HTTP ACP endpoint, tagging requests with the current job ID for audit correlation. Additionally, an \MCPHost\ has been introduced to dynamically discover and register tools from external MCP servers, exposing them through the same session-aware interface.

internal/agent/tools · high confidence

The SDK now includes a standalone, framework-agnostic Durability library for both Go and Python, enabling crash recovery, automatic checkpointing, and idempotent execution for any agent workflow. The Go implementation (in \sdk/durability\) and Python implementation (in \sdk/durability-py\) provide a \Runner\ for durable job execution with step-level retries and a \Store\ interface with in-memory and PostgreSQL backends. The Python package also exposes an \IdempotentTool\ for at-most-once execution of side-effecting operations, ensuring that repeated calls with the same key return cached results without re-execution.

sdk · high confidence

A new \pkg/log\ package has been introduced, wrapping Go's standard \log/slog\ library to provide a configurable logger for the application. Users can now configure log levels (debug, info, warn, error), output formats (JSON or text), and dual-output destinations (stdout and a file) via a \Config\ struct. The package includes a \MultiHandler\ to write logs to multiple handlers simultaneously and comes with comprehensive unit tests covering default behavior, level filtering, format selection, and file output.

pkg/log · high confidence

The internal storage layer now includes a new memory pipeline that manages vectorized memories with automatic weight decay, similarity-based compression, and vector store integration. Users benefit from a system that automatically ages out less important memories, merges similar entries to save space, and maintains a searchable vector index for recall, all configurable via parameters like decay factors, similarity thresholds, and batch sizes.

internal/storage/vector/pipeline · high confidence

Added a new internal document ingestion queue backed by PostgreSQL, enabling asynchronous processing of documents with status tracking. The implementation provides an \IngestQueue\ interface with methods to enqueue tasks, atomically claim pending tasks for workers, and mark tasks as completed or failed. A concrete PostgreSQL implementation (\ingestQueuePg\) stores task payloads and statuses in an \ingest\_tasks\ table, allowing API consumers to submit documents and later check their processing status via \GetStatus\.

internal/ingestqueue · high confidence

The JobStore now supports archiving tool invocation records before garbage collection deletes them, preventing data loss when archive is enabled. A new \archive.go\ module provides a pluggable \ToolInvocationArchiveSink\ (defaulting to an in-database \tool\_invocations\_archive\ table) and enforces a verify-before-delete contract: source records are only removed after a persisted copy is confirmed. The GC process (\gc.go\) respects \ArchiveEnabled\ and \ArchiveTTLDays\ configuration, allowing users to retain archived copies permanently or set a separate retention period. Additionally, an embedded JSON-backed store (\embedded\_store.go\) is introduced for local durable state persistence.

internal/runtime/jobstore · high confidence

The worker now supports executing agent jobs via a new AgentJobRunner that claims jobs from a store, enforces concurrency limits (backpressure), and handles orphan reclamation. Adapter components bridge the worker to the agent runtime's planner and tool providers. Production deployments now require explicit Postgres configurations for the job, effect, and checkpoint stores, with validation rejecting default passwords and insecure SSL settings. Runtime garbage collection and event archival are configurable, and the worker integrates OpenTelemetry for observability.

internal/app/worker · high confidence

The executor now enforces deterministic replay by routing non-deterministic operations (time, UUID, HTTP) through a recorded effects system that replays recorded values instead of generating new ones. It also introduces an atomic commit protocol for tool invocations, using a ledger to detect and handle orphaned executions after crashes, ensuring at-most-once semantics. Additionally, an effect store with a catch-up mechanism prevents double execution of tools when a crash occurs between effect recording and event stream commitment.

internal/agent/runtime/executor · high confidence

The internal/agent package now includes agent.go, which defines the Agent struct and its Run/RunWithSession methods. This implementation provides a Plan→Execute loop that supports session management, allowing users to maintain conversation history across multiple steps. The code is marked as deprecated in favor of the new Eino ADK Agent, indicating this is legacy logic being maintained during a migration period.

internal/agent · high confidence

Error messages in the pipeline common package (errors.go) and associated comments have been translated from Chinese to English. This affects the user-facing error strings returned by PipelineError and ValidationError types, as well as the internal documentation comments for these types and their helper functions.

internal/pipeline/common · high confidence

The query pipeline components (retriever, generator, reranker, responder) have been refactored to support the Eino framework and improve code clarity. A new Eino-compatible MemoryRetriever has been added to enable vector search via the Eino retriever interface. Existing components now use the vector.Store interface instead of a concrete pointer, and the Retriever constructor now accepts an explicit index name. All internal error messages have been standardized to English (e.g., 'input validation failed', 'LLM call failed'). Additionally, the Generator now exposes a GenerateWithRetrieval method for direct RAG adapter calls, and the LLM client is handled via an interface rather than a pointer.

internal/pipeline/query · high confidence

The project homepage has been completely redesigned with a modern dark theme, featuring a new visual identity, updated navigation, and a restructured hero section. This change updates the static HTML and CSS served at the root of the HTTP server, providing a more contemporary look and feel for visitors accessing the site via GitHub Pages.

internal/api/http/static · high confidence

The internal/agent/determinism package now enforces deterministic replay by defining a set of forbidden operations (wall clock, random, unrecorded IO, goroutines, channels, and sleep) and providing a ReplayGuard that panics in strict mode when these are detected during replay. It also adds context helpers to mark and check replay mode, ensuring that steps executed in replay mode adhere to recorded effects and do not introduce non-deterministic behavior.

internal/agent/determinism · high confidence

The replay sandbox now uses a policy system to control how operations are handled during replay. For tool, LLM, and workflow nodes, the default policy marks them as side-effects, meaning their results are injected from the replay context rather than re-executed, ensuring deterministic and reproducible replay behavior. This change is implemented in the new policy.go file and validated by comprehensive unit tests in policy\_test.go.

internal/agent/replay/sandbox · high confidence

The worker entry point has been updated to load configuration via a new function that merges model settings from a local YAML file, requiring users to ensure the model configuration file exists at the project root when starting the service. Additionally, the graceful shutdown timeout is now explicitly defined using Go's time.Duration syntax for clarity, and the module path has been updated to reflect the v2 version of the Aetheris library.

cmd/worker · high confidence

Added benchmark infrastructure and baseline performance reports; Semantic splitter now supports real vector-based chunking via injectable embedder.

The main Go module has been upgraded to Go 1.26.1 and migrated from the Gin framework to Cloudwego Hertz (v0.10.4) for HTTP handling, bringing in associated JWT and OpenTelemetry tracing libraries. The dependency graph also includes updates to OpenTelemetry SDKs, Redis clients, and various indirect packages. Additionally, new dependency manifests were added for the Python durability SDK (using setuptools), the Go durability SDK (using pgx v5.10.0), the playground tool (using Gin v1.12.0), and the VSCode extension (using TypeScript and VSCode types).

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 56 → 58 (+2.2)
• Rubric changed (rubric-2026.08.18 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 70 → 78 (+7.5)
• Architecture 94 → 89 (-5.2)
• Maturity 86 → 86 (+0.1)
• Readiness 72 → 81 (+9.1)
• Security 42 → 48 (+5.2)
• Domain Modelling 100 → 71 (-28.7)
• Accessibility 59 → 58 (-1.1)

• Boundary-crossing change coupling: client.go ↔ router.go (cmd/cli/client.go)
• Change coupling: node_adapter.go ↔ memory_store.go (internal/agent/runtime/executor/node_adapter.go)
• Change coupling: runner.go ↔ store.go (internal/agent/runtime/executor/runner.go)
• Change coupling: task_graph.go ↔ router.go (internal/agent/planner/task_graph.go)
• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• CustomerServiceBot.RunInteractiveSession (cognitive 25) (examples/ai-customer-bot/bot.go)
• CustomerServiceBot.classifyIntent (cognitive 19) (examples/ai-customer-bot/bot.go)
• CustomerServiceBot.classifyIntent (cyclomatic 32) (examples/ai-customer-bot/bot.go)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/node_adapter.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/node_adapter.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/node_adapter.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/runner.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/session.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/state.go)
• Duplicated block (10 lines × 2) (internal/agent/tools/registry.go)
• Duplicated block (10 lines × 2) (internal/api/http/handler.go)
• …and 185 more

• Change coupling: replay.go ↔ types.go (internal/agent/replay/replay.go)
• ClassTooLong: Handler (internal/api/http/handler.go)
• ClassTooLong: Runner (internal/agent/runtime/executor/runner.go)
• ClassTooLong: nodeEventSinkImpl (internal/app/api/node_sink.go)
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (tools/playground/go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• DatabaseTool.describeTable (cognitive 20) (tools/mcp-gateway/tools/mcp-database/tool.go)
• DatabaseTool.query (cognitive 26) (tools/mcp-gateway/tools/mcp-database/tool.go)
• DatabaseTool.query (cyclomatic 17) (tools/mcp-gateway/tools/mcp-database/tool.go)
• DatabaseTool.validateSQL (cognitive 16) (tools/mcp-gateway/tools/mcp-database/tool.go)
• Deprecated module: go.opentelemetry.io/otel/exporters/jaeger
• Documentation: written for insiders (examples/mcp-gateway/README.md)
• Documentation: written for insiders (examples/simple_chat_agent/README.md)
• Duplicated block (10 lines × 2) (internal/agent/memory/episodic_mem.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/checkpoint_embedded.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/node_adapter.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/executor/node_adapter.go)
• Duplicated block (10 lines × 2) (internal/agent/runtime/session.go)
• …and 363 more

• 4 commits — 2 feature/other, 2 fixes

• internal/agent — 2 commits
• internal/runtime — 1 commit
• sdk/openclaw-adapter — 1 commit

• fix: fix(jobstore): implement tool invocation archive with verify-before-delete (#227)
• fix: fix: project audit cleanup (#225)
• change: Feat/standalone sdk (#224)
• change: feat: implement 24 unimplemented/partial features per issue #226 (P1-P3) (#228)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Colin4k1024/Aetheris was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.