diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index fe690eb7f..843de8632 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,6 +34,12 @@ See `docs/architecture/organisation.md` for the target structure and | `internal/events/` | In-process event bus: publish/subscribe for observability | | `internal/infrastructure/` | Config loading, eventbus transport, model catalog | | `internal/webui/` | SSE dashboard: live event stream, task status | +| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch | +| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract | +| `internal/memory/` (7k LOC) | Pluggable memory provider architecture | +| `internal/secret/` | Secret reference resolution across named engines (env, vault, etc.) | +| `internal/plugin/` | Core plugin interface: Yaegi-interpreted `.go` plugins loaded from `~/.config/archie/plugins/` and registered with the daemon's extension registry | +| `internal/skill/` | Parses and discovers agentskills.io `SKILL.md` files | | `ai-sdk/runtime` | External: provider-agnostic LLM runtime | | `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails | | `ai-sdk/core` | External: tool definitions, generate options | diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index 2ea3ab071..082a6b25b 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -18,12 +18,15 @@ tests, persistence, and runtime wiring. ```text internal/domain/ - identity/ - agent/ + identity/ (approved, not yet materialised as a package) + agent/ (approved, not yet materialised as a package) workflow/ - messaging/ + messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2) workintake/ - plugin/ + plugin/ (approved, not yet materialised as a package) + curator/ + mapping/ + scheduling/ ``` - `identity` owns persistent actors, lifecycle, ownership, attribution, and @@ -43,6 +46,30 @@ internal/domain/ - `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle mechanics. It remains metadata-only; capability semantics and typed registration belong to the owning domain. +- `curator` owns the curator engine family: long-running agent loops that + reason over memory and perform maintenance tasks on a declared shape + (check-in interval, tool set, attached memory engine). See epic + archie-core-yp9. +- `mapping` owns the payload field-mapping vocabulary: binding named fields to + JSON paths inside a captured webhook payload, and detecting drift. See + `docs/prds/payload-field-mapping.md`. +- `scheduling` owns the ticker engine: deciding when a scheduled job runs and + with what concurrency. It declares `JobSource`/`Runner` contracts and owns + no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20. + +**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed +in the tree without being added to this list when their epics landed. They are +confirmed as legitimate, narrowly-scoped domains under the same rules as the +original six — each owns one capability family, declares typed contracts, and +has no cross-domain reach. This list was out of date, not the tree. + +Conversely, `identity`, `agent`, `messaging`, and `plugin` are approved target +domains that do not yet exist as packages. Their behaviour currently lives in +pre-migration packages (see "Complete package destination map" below for the +full inventory). Do **not** create empty stub packages for them ahead of an +actual migration PR — an unused stub is dead code and gives no test coverage. +Each materialises when its corresponding migration decision below is resolved +and implemented in the same change. Memory's final package placement remains undecided pending focused review of the existing implementation. @@ -105,6 +132,30 @@ implementation evidence: - normal scoped-memory behaviour regardless of the originating Conversation; - Messaging and Work Intake ownership. +**Decision (2026-08-31), resolving the open questions above:** + +`internal/gateway/` is the "parallel gateway session implementation" this +section names. It is retained as-is for now — a big-bang rewrite of live +session/compression/approval/branch logic across Telegram, web UI, email, and +webhook channels in one change is exactly the "convoluted to satisfy edge +cases" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would +risk silent behavioural regressions in the one path every user-facing message +travels through. + +Instead, `internal/domain/messaging/` is materialised now with the pieces +that are already decided and don't require touching gateway: the canonical +`Message` and `Conversation` types (composite Conversation identity, immutable +`MessageID`, typed tool-call/tool-result message variants, branch lineage via +`ParentConversationID`/`ForkMessageID`). These are pure domain types with no +gateway dependency — a new package, not a rewrite of an existing one. + +Migrating `internal/gateway/`'s session, compression, approval, and branch +logic onto these types is real, cross-channel-risk work and is **not** done in +this pass. It is tracked as separate, appropriately-scoped bd issues (see +`bd list --label messaging-migration`), sequenced channel-by-channel so each +lands with its own behavioural verification instead of one large diff no one +can safely review. + ### 3. Identity data migration The migration must define: diff --git a/internal/domain/messaging/message.go b/internal/domain/messaging/message.go new file mode 100644 index 000000000..e6f2111ee --- /dev/null +++ b/internal/domain/messaging/message.go @@ -0,0 +1,100 @@ +// Package messaging owns canonical Messages, Conversations, branches, +// channel and source correlation, and typed tool-call/tool-result message +// variants. +// +// This package intentionally contains only the vocabulary already settled +// in docs/architecture/migration-decisions.md section 2: the composite +// Conversation identity, immutable MessageIDs, typed tool-call and +// tool-result messages, and branch lineage through ParentConversationID and +// ForkMessageID. Migrating internal/gateway/'s session, compression, +// approval, and branch logic onto these types is deliberately out of scope +// here — see that section for why, and bd for the tracked follow-up work. +package messaging + +import "time" + +// ConversationID is the composite identity of a Conversation: a channel and +// the channel-native thread within it. Two conversations with the same +// ChannelID but different ThreadID are distinct. +type ConversationID struct { + ChannelID string + ThreadID string +} + +// MessageID is the canonical, immutable identifier for a Message. Once +// assigned it never changes, including across branch and fork operations — +// a forked transcript references the original MessageID it branched from +// rather than minting a new one for shared history. +type MessageID string + +// Role identifies who or what produced a Message. +type Role string + +const ( + RoleUser Role = "user" + RoleAssistant Role = "assistant" + RoleTool Role = "tool" + RoleSystem Role = "system" +) + +// Conversation is a single thread of Messages within a channel, optionally +// forked from another Conversation. +// +// Parent and child transcript isolation is exact: a fork sees the parent's +// history up to ForkMessageID, and appends to its own independent +// continuation. Nothing appended to the child is visible to the parent, and +// nothing appended to the parent after the fork point is visible to the +// child. +type Conversation struct { + ID ConversationID + + // ParentConversationID is the Conversation this one branched from, and + // the zero value when this Conversation is not a branch. + ParentConversationID ConversationID + // ForkMessageID is the last MessageID visible to this Conversation from + // its parent's history. Empty when ParentConversationID is empty. + ForkMessageID MessageID + + CreatedAt time.Time +} + +// IsBranch reports whether this Conversation was forked from another. +func (c Conversation) IsBranch() bool { + return c.ParentConversationID != ConversationID{} +} + +// Message is one immutable, persisted turn in a Conversation. +type Message struct { + ID MessageID + ConversationID ConversationID + + // SourceID is the channel-native identifier (e.g. a Telegram + // message_id) this Message correlates to. Empty for messages with no + // upstream identity. + SourceID string + + Role Role + Text string + + // ToolCall and ToolResult are populated instead of Text for their + // respective Roles; a Message carries exactly one of Text, ToolCall, or + // ToolResult content. + ToolCall *ToolCall + ToolResult *ToolResult + + At time.Time +} + +// ToolCall is a typed request from the assistant to invoke a tool. +type ToolCall struct { + CallID string + ToolName string + Arguments string // JSON-encoded arguments, opaque to this package +} + +// ToolResult is a typed response to a prior ToolCall, correlated by CallID. +type ToolResult struct { + CallID string + Output string + Err string // non-empty when the tool call failed +} diff --git a/internal/domain/messaging/message_test.go b/internal/domain/messaging/message_test.go new file mode 100644 index 000000000..9f42157cd --- /dev/null +++ b/internal/domain/messaging/message_test.go @@ -0,0 +1,42 @@ +package messaging + +import "testing" + +func TestConversationIsBranch(t *testing.T) { + tests := []struct { + name string + conv Conversation + want bool + }{ + { + name: "root conversation", + conv: Conversation{ID: ConversationID{ChannelID: "chan-1"}}, + want: false, + }, + { + name: "forked conversation", + conv: Conversation{ + ID: ConversationID{ChannelID: "chan-1", ThreadID: "fork-1"}, + ParentConversationID: ConversationID{ChannelID: "chan-1"}, + ForkMessageID: "msg-42", + }, + want: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := tt.conv.IsBranch(); got != tt.want { + t.Fatalf("IsBranch() = %t, want %t", got, tt.want) + } + }) + } +} + +func TestConversationIDDistinguishesThreads(t *testing.T) { + a := ConversationID{ChannelID: "chan-1", ThreadID: "t1"} + b := ConversationID{ChannelID: "chan-1", ThreadID: "t2"} + if a == b { + t.Fatal("distinct ThreadIDs must produce distinct ConversationIDs") + } +}