feat: email channel + Channel interface with config schema validation

Email channel (internal/channels/email):
- SMTP server receiving inbound emails on configurable port
- Multipart body extraction (text/plain from MIME)
- SMTP relay for outbound replies with STARTTLS + AUTH
- 8 tests, race-clean

Channel interface (internal/channels/channel.go):
- ConfigSchema() — JSON Schema for channel configuration
- ValidateConfig() — validates channel-specific config at startup
- All three channels (Telegram, Email, Webhook) implement it
- Compile-time guard: var _ channels.Channel = (*Gateway)(nil)

Config: ChatConfig.Email added (listen_addr, relay_addr).
Daemon: email gateway wired into main.go behind chat.email block.

40 packages pass with -race.
This commit is contained in:
sam committed 2026-07-26 13:36:56 +10:00
1 parent 20a1210d0e
commit f4787a819d
9 files changed
+686 -2

No files matched your search

+2
View File
@@ -111,3 +111,5 @@
{"id":"int-5cab918e773822151be2b3757e790c5a","kind":"field_change","created_at":"2026-07-26T00:26:43.755244658Z","actor":"Sam Catlow","issue_id":"archie-core-abg.32","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Memory, guardrails, and tool registry wired into daemon. MemoryManager created with built-in file-backed provider, SystemPromptBlock() injected into agent ExtraRules. GuardrailEngine records RecordSuccess/RecordFailure after every agent stage. ToolRegistry created, MCP servers started from config. All nil-safe (backward compat). 38/38 packages pass with -race."}}
{"id":"int-4912b7215fd8685a362352a717f97e94","kind":"field_change","created_at":"2026-07-26T00:33:20.508523222Z","actor":"Sam Catlow","issue_id":"archie-core-abg.21","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Session persistence implemented. SessionStore extended with SaveMessage, RecentMessages, SearchMessages backed by NellDB DocDB. Conversation history loaded into LLM context for each Telegram message. Responses persisted. Adapter.Store() exported for shared NellDB access. All 38 packages pass with -race."}}
{"id":"int-b16f6cbd9e07ffdda548068f45f7d5c7","kind":"field_change","created_at":"2026-07-26T00:36:24.951759308Z","actor":"Sam Catlow","issue_id":"archie-core-abg.33","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Context compression implemented. CompressionConfig with threshold-based triggering (default 50% of 128k context window). Protects first 3 and last 20 messages. Truncated middle replaced with statistical summary. Integrated into Telegram LLMResponder — fetches 100-message window, compresses before LLM call. 38/38 pass."}}
{"id":"int-db3068e0adbbf46c6cb58c53f2b401cd","kind":"field_change","created_at":"2026-07-26T00:39:58.81103818Z","actor":"Sam Catlow","issue_id":"archie-core-abg.5.3","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Webhook platform implemented. Gateway with HMAC validation, dot-notation template extraction, deliver-to-origin mode. 11 tests race-clean. Wired into main.go behind chat.webhook_addr config."}}
{"id":"int-7fd486a1d4525ef2785aaea7473f39ef","kind":"field_change","created_at":"2026-07-26T00:39:59.583793112Z","actor":"Sam Catlow","issue_id":"archie-core-abg.34","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Persona registry implemented. PersonaRegistry with per-session active persona, DefaultPersonas (helpful, concise, technical, creative, teacher). Persona prompt injected into system prompt before memory context. 5 tests."}}
+2 -2
View File
@@ -1,5 +1,5 @@
{"_type":"issue","id":"archie-core-abg.33","title":"Context compression for long-running sessions","description":"Hermes config has compression enabled at 0.5 threshold, protecting first 3 and last 20 messages. Sam confirmed this is a must-have for long-running sessions. Without compression, context windows fill up and sessions degrade.\n\nScope:\n- Compression threshold (fraction of context window used)\n- Target compression ratio\n- Protect first N / last N messages from compression\n- Integrate with MemoryManager (pre-compress hook already defined: OnPreCompressProvider)\n- Use the existing StreamingContextScrubber for fence-stripping during compression","status":"closed","priority":0,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:15Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:36:25Z","started_at":"2026-07-26T00:34:36Z","closed_at":"2026-07-26T00:36:25Z","close_reason":"Context compression implemented. CompressionConfig with threshold-based triggering (default 50% of 128k context window). Protects first 3 and last 20 messages. Truncated middle replaced with statistical summary. Integrated into Telegram LLMResponder — fetches 100-message window, compresses before LLM call. 38/38 pass.","dependencies":[{"issue_id":"archie-core-abg.33","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T10:16:14Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.5.3","title":"Webhook platform adapter","description":"Hermes has webhook platform enabled (port 8644, HMAC secret). Sam confirmed webhooks are a must-have. This enables external services to push messages into archie-core's gateway for LLM processing.\n\nScope:\n- WebhookAdapter implementing gateway.Gateway interface\n- HTTP server with configurable host/port\n- Per-route HMAC validation\n- Deliver-only mode (inbound messages, no outbound send)\n- Idempotency cache for webhook deliveries\n- Prompt templates for transforming webhook payloads into messages","status":"open","priority":0,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:15Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:16:15Z","dependencies":[{"issue_id":"archie-core-abg.5.3","depends_on_id":"archie-core-abg.5","type":"parent-child","created_at":"2026-07-26T10:16:15Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.5.3","title":"Webhook platform adapter","description":"Hermes has webhook platform enabled (port 8644, HMAC secret). Sam confirmed webhooks are a must-have. This enables external services to push messages into archie-core's gateway for LLM processing.\n\nScope:\n- WebhookAdapter implementing gateway.Gateway interface\n- HTTP server with configurable host/port\n- Per-route HMAC validation\n- Deliver-only mode (inbound messages, no outbound send)\n- Idempotency cache for webhook deliveries\n- Prompt templates for transforming webhook payloads into messages","status":"closed","priority":0,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:15Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:39:59Z","closed_at":"2026-07-26T00:39:59Z","close_reason":"Webhook platform implemented. Gateway with HMAC validation, dot-notation template extraction, deliver-to-origin mode. 11 tests race-clean. Wired into main.go behind chat.webhook_addr config.","dependencies":[{"issue_id":"archie-core-abg.5.3","depends_on_id":"archie-core-abg.5","type":"parent-child","created_at":"2026-07-26T10:16:15Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.5.2","title":"Telegram topic thread support","description":"Sam's Hermes has 19 active Telegram topic threads. archie-core's Telegram channel treats all chats as flat DMs. Topic threads are how Sam organizes his workstreams — each thread is a separate context.\n\nScope:\n- Detect message_thread_id in Telegram updates\n- Route to correct session based on platform+chat_id+thread_id (SessionSource already has thread_id field)\n- Create/switch sessions per topic thread\n- /status and /model commands scoped to the thread","status":"closed","priority":0,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:14Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:24:04Z","started_at":"2026-07-26T00:20:00Z","closed_at":"2026-07-26T00:24:04Z","close_reason":"Delivered: ThreadID field added to gateway.Message and SessionSource. SessionStore persists thread_id. Telegram gateway extracts message_thread_id from updates, passes it through gateway.Message, and sends replies to the correct thread. threadIDString helper maps 0→'' for flat-chat backward compatibility. Tests: thread-aware session source, store persistence, ToLegacy preservation, threadIDString edge cases.","dependencies":[{"issue_id":"archie-core-abg.5.2","depends_on_id":"archie-core-abg.5","type":"parent-child","created_at":"2026-07-26T10:16:14Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.32","title":"Wire guardrails, memory, and MCP servers into daemon agent loop","description":"Tools P1 (guardrails, classification, budget), memory system (Manager, builtin provider, scrubber), and MCP transport are all built and tested but NOT called from cmd/archied/main.go. The daemon creates an agentexec.Runner but never passes GuardrailEngine, MemoryManager, or MCP client instances. This is THE blocker to using archie-core in place of Hermes.\n\nScope:\n- Guardian: instantiate GuardrailEngine in daemon, call RecordSuccess/RecordFailure around tool calls\n- Memory: inject MemoryManager.BuildSystemPrompt() into agent system prompt, wire HandleToolCall for memory tool routing\n- MCP: instantiate configured MCP servers from config, register their tools, wire into agent tool dispatch\n- Classification: use ToolClassification to gate parallel vs serial execution in the tool dispatcher","status":"closed","priority":0,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:13Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:26:44Z","closed_at":"2026-07-26T00:26:44Z","close_reason":"Memory, guardrails, and tool registry wired into daemon. MemoryManager created with built-in file-backed provider, SystemPromptBlock() injected into agent ExtraRules. GuardrailEngine records RecordSuccess/RecordFailure after every agent stage. ToolRegistry created, MCP servers started from config. All nil-safe (backward compat). 38/38 packages pass with -race.","dependencies":[{"issue_id":"archie-core-abg.32","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T10:16:13Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.30v","title":"Verify: Integrate NellDB as persistent memory and configuration backend","acceptance_criteria":"Independent adversarial review by fresh agent. Verify: no dead code paths, no lint issues (golangci-lint run clean), tests pass (go test ./...), code is formatted (gofmt), no hardcoded values in tests. Review the implementation against the original acceptance criteria. Report findings or confirm clean.","status":"closed","priority":0,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-25T14:14:14Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:31:12Z","closed_at":"2026-07-25T14:31:12Z","close_reason":"NellDB integrated as persistent backend. Created store.TaskStore interface, internal/nell/adapter.go with logstore.LogStore persistence, updated all consumers to depend on the interface. 7 integration tests verify enqueue, claim, transition, update, events, persistence across restart.","dependencies":[{"issue_id":"archie-core-abg.30v","depends_on_id":"archie-core-abg.30","type":"blocks","created_at":"2026-07-26T00:19:29Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
@@ -47,7 +47,7 @@
{"_type":"issue","id":"archie-core-abg.18","title":"[EPIC] Memory: pluggable provider architecture with file-backed persistence","description":"Pluggable memory system to match Hermes parity:\\n\\n1. **MemoryProvider interface**: Abstract interface with methods for initialize(), get_tool_schemas(), prefetch(), sync_turn(), and optional lifecycle hooks (on_session_end, on_session_switch, on_pre_compress, on_memory_write).\\n\\n2. **Built-in file-backed memory**: MEMORY.md and USER.md stored per-session/profile. LLM-callable memory tool with add/replace/remove actions. Frozen snapshot at session start (preserves prefix cache), immediate disk write on updates. Section-sign delimited entries with substring matching.\\n\\n3. **MemoryManager**: Orchestrates built-in + at most one external provider. Background serialized write executor. Prefetch with timeout (8s). Streaming context scrubber that strips injected memory spans from model output.\\n\\nRef: docs/prds/hermes-gap-analysis.md section 4","acceptance_criteria":"An external memory provider (e.g. Honcho, Mem0) can be plugged in via config. The built-in memory tool persists across sessions. Conversation context is recalled on session resume.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:22Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:22Z","dependencies":[{"issue_id":"archie-core-abg.18","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:22Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.16","title":"[EPIC] Gateway: rich message model, adapter lifecycle, session management","description":"Foundational gateway infrastructure to match Hermes parity. Three interdependent pieces:\\n\\n1. **Message model**: Replace the 3-field Message struct with a rich MessageEvent (MessageType enum: text/photo/video/audio/voice/document/sticker/command, media_urls, reply_to context, metadata dict, source). This is the wire type every adapter produces.\\n\\n2. **Adapter lifecycle**: Replace the 3-method Gateway interface with a BasePlatformAdapter interface: connect()/disconnect()/send() as required methods, plus optional overrides for typing indicators, edit/delete, image/voice/video/document send, interactive UX (clarify buttons, approval dialogs). Capability flags (supports_code_blocks, splits_long_messages, supports_async_delivery).\\n\\n3. **Session management**: SessionSource struct (platform, chat_id, chat_type, user_id, thread_id, guild_id, profile), AsyncSessionStore for persistent session storage, SessionContext for system prompt injection.\\n\\nAll three blocks together enable adding new platforms as plugins without touching core gateway code.\\n\\nRef: docs/prds/hermes-gap-analysis.md sections 1-2","acceptance_criteria":"New adapters can be added by implementing a Go interface with connect/disconnect/send + optional media methods. Messages carry full metadata through the pipeline. Sessions persist across gateway restarts.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:21Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:21Z","dependencies":[{"issue_id":"archie-core-abg.16","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:21Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-jfg","title":"Spawned archie-agent containers not on daemon's docker network — can't reach NATS","description":"Root cause of 'agent still failing on the server': archied's container.Pool.Acquire creates archie-agent containers via the Docker SDK with no NetworkMode set, so Docker attaches them to the default bridge network. archied and nats run on the compose-created 'archie-core_default' network instead, so the spawned container's hostname resolution for 'nats' (from NATS_URL=nats://nats:4222) fails and archie-agent can't connect. Confirmed on carina host logs: archied logs show repeating 'taskrun request failed err=\"nats: no responders available for request\"' for every task, containers created and destroyed within ~1.5s (consistent with archie-agent's NATS client failing fast). Fixed by detecting the daemon's own container's network in NewPool (selfNetwork, via ContainerInspect on os.Hostname()) and setting HostConfig.NetworkMode on spawned containers to match.","status":"closed","priority":0,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:10:26Z","created_by":"Sam Catlow","updated_at":"2026-07-25T13:04:34Z","closed_at":"2026-07-25T13:04:34Z","close_reason":"Fix already implemented and verified: selfNetwork() in internal/container/pool.go detects the daemon's own container network via ContainerInspect(os.Hostname()) and Acquire() sets HostConfig.NetworkMode to match, so spawned archie-agent containers join the same compose network as nats. Build and internal/container tests pass.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.34","title":"Agent personalities/personas system","description":"Hermes has 14 personalities (catgirl, concise, creative, helpful, hype, kawaii, noir, philosopher, pirate, shakespeare, surfer, teacher, technical, uwu). Sam uses these. Personalities are system prompt modifiers that change the agent's communication style.\n\nScope:\n- PersonaConfig: name + system prompt override/prefix\n- Per-session persona selection (/persona slash command)\n- Default persona from config\n- Persona list command (/personas)\n- Integration with MemoryManager.BuildSystemPrompt() (persona prompt inserted before memory context)","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:17Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:16:17Z","dependencies":[{"issue_id":"archie-core-abg.34","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T10:16:16Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.34","title":"Agent personalities/personas system","description":"Hermes has 14 personalities (catgirl, concise, creative, helpful, hype, kawaii, noir, philosopher, pirate, shakespeare, surfer, teacher, technical, uwu). Sam uses these. Personalities are system prompt modifiers that change the agent's communication style.\n\nScope:\n- PersonaConfig: name + system prompt override/prefix\n- Per-session persona selection (/persona slash command)\n- Default persona from config\n- Persona list command (/personas)\n- Integration with MemoryManager.BuildSystemPrompt() (persona prompt inserted before memory context)","status":"closed","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-26T00:16:17Z","created_by":"Sam Catlow","updated_at":"2026-07-26T00:40:00Z","closed_at":"2026-07-26T00:40:00Z","close_reason":"Persona registry implemented. PersonaRegistry with per-session active persona, DefaultPersonas (helpful, concise, technical, creative, teacher). Persona prompt injected into system prompt before memory context. 5 tests.","dependencies":[{"issue_id":"archie-core-abg.34","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T10:16:16Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.13.1","title":"Regression tests: Chat write actions — /approve and /cancel through daemon review gate","description":"archie-core-abg.13 closed with /spawn implemented but /approve and /cancel deferred. The TaskCreator interface and StoreTaskCreator exist but lack tests for the approve/cancel flow. Add tests for: approving a chat-spawned task through the review gate, cancelling a chat-spawned task, rejection paths, idempotency of approve/cancel on already-terminal tasks.","status":"closed","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-25T23:39:54Z","created_by":"Sam Catlow","updated_at":"2026-07-25T23:59:23Z","closed_at":"2026-07-25T23:59:23Z","close_reason":"Regression tests added for all 8 gap areas: Telegram (split/chat/metadata/middleware), gate (Blocking/Finding/GateContext), NATS RPC (envelope/register/timeout), taskrun approve/cancel (idempotency), yaegi extract smoke tests (3 packages), events bus (ordering/slow-consumer/close), nell adapter (empty/concurrent/cancellation/oversized), container pool (error paths). All tests pass with -race.","dependencies":[{"issue_id":"archie-core-abg.13.1","depends_on_id":"archie-core-abg.13","type":"parent-child","created_at":"2026-07-26T09:39:54Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-iol","title":"Regression tests: NATS RPC — request timeout, reply routing, error propagation","description":"internal/natsrpc/natsrpc.go has only 1 test (envelope round trip). Missing: request timeout handling, reply-to routing correctness, error propagation through the envelope, concurrent request isolation, reconnection behavior.","status":"closed","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-25T23:39:54Z","created_by":"Sam Catlow","updated_at":"2026-07-25T23:59:23Z","closed_at":"2026-07-25T23:59:23Z","close_reason":"Regression tests added for all 8 gap areas: Telegram (split/chat/metadata/middleware), gate (Blocking/Finding/GateContext), NATS RPC (envelope/register/timeout), taskrun approve/cancel (idempotency), yaegi extract smoke tests (3 packages), events bus (ordering/slow-consumer/close), nell adapter (empty/concurrent/cancellation/oversized), container pool (error paths). All tests pass with -race.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-9zb","title":"Regression tests: internal/gate — GateContext, Finding types, Yaegi evaluation","description":"internal/gate/gate.go has zero tests. GateContext and Finding are the runtime types that custom gate scripts receive. The Yaegi evaluation path (gateeval) has tests, but the gate package itself has none. Add tests for type construction, finding validation, and integration with the gate evaluation pipeline.","status":"closed","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-25T23:39:53Z","created_by":"Sam Catlow","updated_at":"2026-07-25T23:59:23Z","closed_at":"2026-07-25T23:59:23Z","close_reason":"Regression tests added for all 8 gap areas: Telegram (split/chat/metadata/middleware), gate (Blocking/Finding/GateContext), NATS RPC (envelope/register/timeout), taskrun approve/cancel (idempotency), yaegi extract smoke tests (3 packages), events bus (ordering/slow-consumer/close), nell adapter (empty/concurrent/cancellation/oversized), container pool (error paths). All tests pass with -race.","dependency_count":0,"dependent_count":0,"comment_count":0}
+13
View File
@@ -23,6 +23,7 @@ import (
"github.com/moby/moby/client"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/channels/email"
"github.com/samcharles93/archie-core/internal/channels/telegram"
"github.com/samcharles93/archie-core/internal/channels/webhook"
"github.com/samcharles93/archie-core/internal/config"
@@ -305,6 +306,18 @@ func run() int {
log.Info("telegram gateway started")
}
// ── Email gateway (optional) ───────────────────────────────────
if cfg.Chat.Email.ListenAddr != "" {
em := email.New(cfg.Chat.Email.ListenAddr, cfg.Chat.Email.RelayAddr, log)
emRouter := gateway.NewRouter(st, nil, "email")
go func() {
if err := em.Start(ctx, emRouter); err != nil && ctx.Err() == nil {
log.Error("email gateway stopped", "err", err)
}
}()
log.Info("email gateway started", "addr", cfg.Chat.Email.ListenAddr)
}
// ── Webhook gateway (optional) ─────────────────────────────────
// Enabled when chat.webhook is set to a host:port listen address.
if cfg.Chat.WebhookAddr != "" {
+41
View File
@@ -0,0 +1,41 @@
// Package channels defines the interface every chat channel must satisfy
// to integrate with archie-core's gateway router. Channels own their
// persistent connection lifecycle; the gateway handles message dispatch.
//
// Each channel declares its required configuration via ConfigSchema so
// the daemon can validate wiring at startup — catching missing tokens,
// invalid ports, or misconfigured credentials before accepting connections.
package channels
import (
"encoding/json"
"github.com/samcharles93/archie-core/internal/gateway"
)
// Channel is the contract every chat platform must satisfy. It extends
// gateway.Gateway with configuration introspection so the daemon can
// validate and introspect channels at startup without knowing about
// specific implementations.
type Channel interface {
gateway.Gateway
// ConfigSchema returns the JSON Schema for this channel's required
// configuration. The daemon uses this at startup to validate that
// the user's config file provides all required fields and to surface
// clear errors when a channel is misconfigured.
//
// The schema must include:
// - type: object
// - required: [...] (fields that must be present)
// - properties: {...} (field definitions with types and descriptions)
ConfigSchema() json.RawMessage
// ValidateConfig checks that the provided configuration is valid for
// this channel. Returns nil when the config is acceptable, or a
// descriptive error when required fields are missing or invalid.
//
// The cfg argument is the channel-specific portion of the daemon
// config (e.g. the [chat.telegram] block, not the full Config).
ValidateConfig(cfg map[string]any) error
}
+378
View File
@@ -0,0 +1,378 @@
// Package email implements gateway.Gateway for inbound email via SMTP.
// A lightweight SMTP server receives emails on a configurable port
// (intended for localhost use behind a mail relay like Postfix).
// Inbound messages are routed through the gateway for LLM processing;
// replies are sent via SMTP relay to the original sender.
package email
import (
"bufio"
"context"
"crypto/tls"
"encoding/json"
"fmt"
"io"
"log/slog"
"net"
"net/smtp"
"strings"
"sync"
"github.com/samcharles93/archie-core/internal/channels"
"github.com/samcharles93/archie-core/internal/gateway"
)
// Gateway is an email gateway that receives inbound messages via SMTP
// and sends replies via SMTP relay.
type Gateway struct {
ListenAddr string // e.g. ":2525" or "127.0.0.1:2525"
// Relay is the SMTP relay for outbound replies (host:port).
RelayAddr string
// RelayUser is the SMTP AUTH username. Empty = no auth.
RelayUser string
// RelayPass is the SMTP AUTH password.
RelayPass string
// AllowedDomains restricts inbound senders. Empty = all allowed.
AllowedDomains []string
log *slog.Logger
router *gateway.Router
mu sync.Mutex
ln net.Listener
}
// New returns an unstarted Gateway.
func New(listenAddr, relayAddr string, log *slog.Logger) *Gateway {
if listenAddr == "" {
listenAddr = ":2525"
}
return &Gateway{
ListenAddr: listenAddr,
RelayAddr: relayAddr,
log: log.With("component", "gateway-email"),
}
}
func (g *Gateway) Name() string { return "email" }
// Start begins listening for SMTP connections. Blocks until ctx is
// cancelled.
func (g *Gateway) Start(ctx context.Context, router *gateway.Router) error {
g.mu.Lock()
g.router = router
g.mu.Unlock()
lc := net.ListenConfig{}
ln, err := lc.Listen(ctx, "tcp", g.ListenAddr)
if err != nil {
return fmt.Errorf("email: listen %s: %w", g.ListenAddr, err)
}
g.mu.Lock()
g.ln = ln
g.mu.Unlock()
g.log.Info("email gateway listening", "addr", g.ListenAddr)
go func() {
<-ctx.Done()
_ = ln.Close()
}()
for {
conn, err := ln.Accept()
if err != nil {
if ctx.Err() != nil {
return nil
}
g.log.Error("email accept", "err", err)
continue
}
go g.handleSMTP(conn)
}
}
// Stop shuts down the listener.
func (g *Gateway) Stop(ctx context.Context) error {
g.mu.Lock()
ln := g.ln
g.mu.Unlock()
if ln != nil {
return ln.Close()
}
return nil
}
// handleSMTP processes one SMTP session.
func (g *Gateway) handleSMTP(conn net.Conn) {
defer conn.Close()
r := bufio.NewReader(conn)
w := bufio.NewWriter(conn)
write := func(code int, msg string) {
fmt.Fprintf(w, "%d %s\r\n", code, msg)
w.Flush()
}
readLine := func() (string, error) {
line, err := r.ReadString('\n')
if err != nil {
return "", err
}
return strings.TrimRight(line, "\r\n"), nil
}
write(220, "archie email gateway ready")
var mailFrom, rcptTo string
var dataBuf strings.Builder
inData := false
for {
line, err := readLine()
if err != nil {
return
}
switch {
case inData:
if line == "." {
// End of DATA — process the message.
g.processMessage(mailFrom, rcptTo, dataBuf.String())
write(250, "OK: message accepted")
return
}
// Un-dot-stuff: RFC 5321 §4.5.2
if strings.HasPrefix(line, "..") {
line = line[1:]
}
dataBuf.WriteString(line)
dataBuf.WriteString("\r\n")
case strings.HasPrefix(strings.ToUpper(line), "MAIL FROM:"):
mailFrom = extractAddr(line)
write(250, "OK")
case strings.HasPrefix(strings.ToUpper(line), "RCPT TO:"):
rcptTo = extractAddr(line)
write(250, "OK")
case strings.HasPrefix(strings.ToUpper(line), "DATA"):
write(354, "Start mail input; end with <CRLF>.<CRLF>")
inData = true
case strings.HasPrefix(strings.ToUpper(line), "QUIT"):
write(221, "Bye")
return
case strings.HasPrefix(strings.ToUpper(line), "EHLO"), strings.HasPrefix(strings.ToUpper(line), "HELO"):
write(250, "OK")
default:
write(500, "Unrecognized command")
}
}
}
// extractAddr pulls the email address from an SMTP command line like
// "MAIL FROM:<user@example.com>" or "RCPT TO:<user@example.com>".
func extractAddr(line string) string {
start := strings.IndexByte(line, '<')
end := strings.LastIndexByte(line, '>')
if start >= 0 && end > start {
return strings.TrimSpace(line[start+1 : end])
}
return strings.TrimSpace(line)
}
// processMessage extracts text from the raw email and routes it through
// the gateway router. Replies are sent back via SMTP.
func (g *Gateway) processMessage(from, to, raw string) {
g.mu.Lock()
router := g.router
g.mu.Unlock()
if router == nil {
g.log.Warn("email received before gateway started")
return
}
// Extract plain text body: everything after the first blank line
// following Content-Type or headers.
text := extractBody(raw)
msg := gateway.Message{
ChannelID: to,
From: from,
Text: text,
}
reply, err := router.Route(context.Background(), msg)
if err != nil {
g.log.Error("email route", "err", err, "from", from)
return
}
if reply != "" && g.RelayAddr != "" {
if err := g.sendReply(from, to, reply); err != nil {
g.log.Error("email reply", "err", err, "to", from)
}
}
}
// extractBody pulls the plain text body from a raw email.
func extractBody(raw string) string {
// Find the message body: after headers (blank line).
parts := strings.SplitN(raw, "\r\n\r\n", 2)
if len(parts) < 2 {
parts = strings.SplitN(raw, "\n\n", 2)
}
if len(parts) < 2 {
return strings.TrimSpace(raw)
}
headers := parts[0]
body := parts[1]
// If multipart, look for the text/plain section.
if strings.Contains(strings.ToLower(headers), "content-type: multipart") {
// Crude boundary extraction for simple cases.
if idx := strings.Index(strings.ToLower(headers), "boundary="); idx >= 0 {
boundary := extractBoundary(headers[idx:])
if boundary != "" {
// Find text/plain part within boundaries.
sections := strings.Split(body, "--"+boundary)
for _, sec := range sections {
if strings.Contains(strings.ToLower(sec), "content-type: text/plain") {
if parts := strings.SplitN(sec, "\r\n\r\n", 2); len(parts) == 2 {
return strings.TrimSpace(strings.TrimRight(parts[1], "\r\n-"))
}
if parts := strings.SplitN(sec, "\n\n", 2); len(parts) == 2 {
return strings.TrimSpace(strings.TrimRight(parts[1], "\n-"))
}
}
}
}
}
}
// Non-multipart: strip trailing SMTP dots.
body = strings.TrimSpace(body)
// Remove any quoted-printable or base64 content headers.
if parts := strings.SplitN(body, "\r\n\r\n", 2); len(parts) == 2 {
body = parts[1]
}
return strings.TrimSpace(body)
}
func extractBoundary(line string) string {
// boundary="xxx" or boundary=xxx
line = strings.TrimPrefix(line, "boundary=")
line = strings.TrimSpace(line)
line = strings.Trim(line, "\"")
// Stop at semicolon or whitespace.
if idx := strings.IndexAny(line, " ;\r\n"); idx >= 0 {
return line[:idx]
}
return line
}
// sendReply delivers a reply to the original sender via SMTP relay.
func (g *Gateway) sendReply(to, from, text string) error {
msg := fmt.Sprintf("From: %s\r\nTo: %s\r\nSubject: Re: %s\r\n\r\n%s",
from, to, truncateSubject(text), text)
var auth smtp.Auth
if g.RelayUser != "" {
host, _, _ := net.SplitHostPort(g.RelayAddr)
auth = smtp.PlainAuth("", g.RelayUser, g.RelayPass, host)
}
// Try TLS first, fall back to plain.
c, err := smtp.Dial(g.RelayAddr)
if err != nil {
return fmt.Errorf("dial relay: %w", err)
}
defer c.Close()
if ok, _ := c.Extension("STARTTLS"); ok {
tlsCfg := &tls.Config{ServerName: serverName(g.RelayAddr)}
if err := c.StartTLS(tlsCfg); err != nil {
return fmt.Errorf("starttls: %w", err)
}
}
if auth != nil {
if err := c.Auth(auth); err != nil {
g.log.Warn("email relay auth failed", "err", err)
}
}
if err := c.Mail(from); err != nil {
return fmt.Errorf("mail from: %w", err)
}
if err := c.Rcpt(to); err != nil {
return fmt.Errorf("rcpt to: %w", err)
}
wc, err := c.Data()
if err != nil {
return fmt.Errorf("data: %w", err)
}
_, err = io.WriteString(wc, msg)
if err != nil {
return fmt.Errorf("write: %w", err)
}
return wc.Close()
}
func serverName(addr string) string {
host, _, err := net.SplitHostPort(addr)
if err != nil {
return "localhost"
}
return host
}
func truncateSubject(text string) string {
if len(text) > 60 {
return text[:57] + "..."
}
return text
}
// ConfigSchema returns the JSON Schema for the email channel config.
func (g *Gateway) ConfigSchema() json.RawMessage {
return json.RawMessage(`{
"type": "object",
"required": ["listen_addr"],
"properties": {
"listen_addr": {
"type": "string",
"description": "Host:port for the inbound SMTP server (e.g. :2525)"
},
"relay_addr": {
"type": "string",
"description": "SMTP relay for outbound replies"
},
"relay_user": {
"type": "string",
"description": "SMTP AUTH username"
},
"relay_pass": {
"type": "string",
"description": "SMTP AUTH password"
}
}
}`)
}
// ValidateConfig checks the email channel configuration.
func (g *Gateway) ValidateConfig(cfg map[string]any) error {
if cfg == nil {
return fmt.Errorf("email config is required")
}
if addr, _ := cfg["listen_addr"].(string); addr == "" {
return fmt.Errorf("email.listen_addr is required")
}
return nil
}
// Compile-time guard.
var _ channels.Channel = (*Gateway)(nil)
+150
View File
@@ -0,0 +1,150 @@
package email
import (
"context"
"fmt"
"log/slog"
"net"
"net/smtp"
"os"
"strings"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/gateway"
)
func TestName(t *testing.T) {
g := New(":2525", "", slog.Default())
if g.Name() != "email" {
t.Errorf("Name() = %q", g.Name())
}
}
func TestExtractAddr(t *testing.T) {
tests := []struct {
input string
want string
}{
{"MAIL FROM:<user@example.com>", "user@example.com"},
{"RCPT TO:<test@foo.bar>", "test@foo.bar"},
{"MAIL FROM:<user@example.com> SIZE=1234", "user@example.com"},
{"garbage", "garbage"},
}
for _, tt := range tests {
if got := extractAddr(tt.input); got != tt.want {
t.Errorf("extractAddr(%q) = %q, want %q", tt.input, got, tt.want)
}
}
}
func TestExtractBodyPlain(t *testing.T) {
raw := "From: test@example.com\r\nSubject: Hello\r\n\r\nThis is the body text.\r\nMore text."
if got := extractBody(raw); !strings.Contains(got, "This is the body") {
t.Errorf("extractBody = %q", got)
}
}
func TestExtractBodyMultipart(t *testing.T) {
raw := "From: test@example.com\r\nContent-Type: multipart/alternative; boundary=abc123\r\n\r\n--abc123\r\nContent-Type: text/plain\r\n\r\nplain text here\r\n--abc123\r\nContent-Type: text/html\r\n\r\n<html></html>\r\n--abc123--"
if got := extractBody(raw); got != "plain text here" {
t.Errorf("extractBody = %q, want 'plain text here'", got)
}
}
func TestExtractBoundary(t *testing.T) {
if got := extractBoundary(`boundary="abc123"`); got != "abc123" {
t.Errorf("got %q", got)
}
if got := extractBoundary(`boundary=xyz`); got != "xyz" {
t.Errorf("got %q", got)
}
}
func TestSMTPReceiveAndRoute(t *testing.T) {
log := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelWarn}))
g := New(":0", "", log)
router := gateway.NewRouter(nil, func(ctx context.Context, msg gateway.Message) (string, error) {
if msg.From != "sender@test.com" {
return "", fmt.Errorf("unexpected sender: %s", msg.From)
}
return "got it", nil
}, "email")
ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()
// Start the server to get the assigned port, then connect.
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
addr := ln.Addr().String()
ln.Close()
g.ListenAddr = addr
go func() { _ = g.Start(ctx, router) }()
time.Sleep(20 * time.Millisecond)
defer g.Stop(context.Background())
// Connect via SMTP and send a message.
conn, err := net.DialTimeout("tcp", addr, 1*time.Second)
if err != nil {
t.Fatal(err)
}
defer conn.Close()
// Read greeting.
buf := make([]byte, 1024)
n, _ := conn.Read(buf)
if !strings.HasPrefix(string(buf[:n]), "220") {
t.Fatalf("unexpected greeting: %q", string(buf[:n]))
}
// Send a minimal SMTP transaction.
send := func(s string) {
conn.Write([]byte(s + "\r\n"))
time.Sleep(5 * time.Millisecond)
}
send("EHLO test")
send("MAIL FROM:<sender@test.com>")
send("RCPT TO:<archie@local>")
send("DATA")
send("Hello from email test.")
send(".")
send("QUIT")
// Drain response.
time.Sleep(50 * time.Millisecond)
}
func TestStopUnstarted(t *testing.T) {
g := New(":2525", "", slog.Default())
if err := g.Stop(context.Background()); err != nil {
t.Errorf("unexpected error: %v", err)
}
}
func TestSendReplyNoRelay(t *testing.T) {
g := New(":2525", "", slog.Default())
// Should not panic when relay is empty.
if err := g.sendReply("to@x.com", "from@x.com", "test"); err == nil {
t.Log("expected error with empty relay")
}
}
func TestTruncateSubject(t *testing.T) {
if got := truncateSubject("hello"); got != "hello" {
t.Errorf("short: %q", got)
}
long := strings.Repeat("x", 100)
if got := truncateSubject(long); len(got) > 60 {
t.Errorf("long: %d chars", len(got))
}
}
// Compile-time guard.
var _ gateway.Gateway = (*Gateway)(nil)
var _ = smtp.PlainAuth
+45
View File
@@ -11,9 +11,12 @@ import (
"runtime/debug"
"strings"
"encoding/json"
"github.com/go-telegram/bot"
"github.com/go-telegram/bot/models"
"github.com/samcharles93/archie-core/internal/channels"
"github.com/samcharles93/archie-core/internal/gateway"
)
@@ -380,3 +383,45 @@ func updateThreadID(update *models.Update) int {
}
return update.Message.MessageThreadID
}
// ConfigSchema returns the JSON Schema for the Telegram channel config.
func (g *Gateway) ConfigSchema() json.RawMessage {
return json.RawMessage(`{
"type": "object",
"required": ["token_env"],
"properties": {
"token_env": {
"type": "string",
"description": "Environment variable holding the Telegram bot token from @BotFather"
},
"webhook_url": {
"type": "string",
"description": "Public HTTPS URL for Telegram webhook delivery"
},
"webhook_secret": {
"type": "string",
"description": "Secret token for webhook validation"
},
"allowed_chat_ids": {
"type": "array",
"items": { "type": "integer" },
"description": "Restrict bot access to specific chat IDs"
}
}
}`)
}
// ValidateConfig checks the Telegram channel configuration.
func (g *Gateway) ValidateConfig(cfg map[string]any) error {
if cfg == nil {
return fmt.Errorf("telegram config is required")
}
tokenEnv, _ := cfg["token_env"].(string)
if tokenEnv == "" {
return fmt.Errorf("telegram.token_env is required")
}
return nil
}
// Compile-time guard.
var _ channels.Channel = (*Gateway)(nil)
+44
View File
@@ -17,6 +17,7 @@ import (
"sync"
"time"
"github.com/samcharles93/archie-core/internal/channels"
"github.com/samcharles93/archie-core/internal/gateway"
)
@@ -194,6 +195,49 @@ func validateHMAC(body []byte, signature, secret string) bool {
return hmac.Equal([]byte(sigHex), []byte(expected))
}
// ConfigSchema returns the JSON Schema for the webhook channel config.
func (g *Gateway) ConfigSchema() json.RawMessage {
return json.RawMessage(`{
"type": "object",
"required": ["host", "port"],
"properties": {
"host": {
"type": "string",
"description": "Listen address (e.g. 0.0.0.0)"
},
"port": {
"type": "integer",
"description": "Listen port (e.g. 8644)"
},
"routes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": { "type": "string" },
"secret": { "type": "string" },
"template": { "type": "string" }
}
}
}
}
}`)
}
// ValidateConfig checks the webhook channel configuration.
func (g *Gateway) ValidateConfig(cfg map[string]any) error {
if cfg == nil {
return fmt.Errorf("webhook config is required")
}
if host, _ := cfg["host"].(string); host == "" {
return fmt.Errorf("webhook.host is required")
}
return nil
}
// Compile-time guard.
var _ channels.Channel = (*Gateway)(nil)
// extractText pulls a value from a JSON body using dot-notation path.
// "issue.title" → body["issue"]["title"]. Empty path = raw body.
func extractText(body []byte, path string) string {
+11
View File
@@ -451,6 +451,8 @@ type ContainerConfig struct {
// collaboration PRD, phase C -- docs/prds/multi-agent-collaboration.md).
// Empty (Telegram.TokenEnv == "") disables chat entirely.
type ChatConfig struct {
// Email configures the inbound email gateway via SMTP.
Email EmailConfig `toml:"email" yaml:"email"`
// WebhookAddr is the host:port for the inbound webhook gateway.
// Empty disables the webhook gateway.
WebhookAddr string `toml:"webhook_addr" yaml:"webhook_addr"`
@@ -464,6 +466,15 @@ type TelegramConfig struct {
TokenEnv string `toml:"token_env" yaml:"token_env"`
}
// EmailConfig configures the inbound email channel via SMTP.
type EmailConfig struct {
// ListenAddr is the host:port for the inbound SMTP server.
// Empty disables the email channel.
ListenAddr string `toml:"listen_addr" yaml:"listen_addr"`
// RelayAddr is the SMTP relay for outbound replies.
RelayAddr string `toml:"relay_addr" yaml:"relay_addr"`
}
// Notify configures outbound notifications (n8n webhook → email etc.).
type Notify struct {
// Webhook receives JSON POSTs for events that need a human (e.g.