refactor(gateway): cut comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 21:53:24 +10:00
1 parent 796ca4e2c4
commit 96a90d643b
25 files changed
+168 -779

No files matched your search

-8
View File
@@ -1,11 +1,3 @@
// Package gateway: approval.go — re-exports the tool-approval contract
// from internal/tools so existing gateway-internal and adapter code
// continues to compile against the names it already uses.
//
// The canonical definitions live in internal/tools/approval.go so that
// internal/agentexec (also used by the archie-agent sandbox binary) can
// import them without pulling in the chat-gateway domain stack.
package gateway
import "github.com/samcharles93/archie-core/internal/tools"
@@ -1,9 +1,3 @@
// Wire-contract aliases. The chat contract types moved to
// internal/domain/messaging so the webui and
// archie-ui processes can hold the contract without linking the gateway
// runtime (and, transitively, its SQLite session store). internal/gateway
// keeps these aliases so daemon-side callers and channel adapters are
// unaffected.
package gateway
import "github.com/samcharles93/archie-core/internal/domain/messaging"
+3 -18
View File
@@ -169,12 +169,8 @@ func (a *LocalChatAdapter) stream(ctx context.Context, in Inbound, id string, ev
a.runStreamedTurn(ctx, in, id, events)
}
// runStreamedTurn dispatches one turn whose payload the prelude produced and
// pumps its events to the caller. The turn runs on its session lane -- the
// lane key is the session, so /stop reaches the turn the sender is actually
// watching -- while the pump stays on the caller's goroutine, so a
// caller-cancelled stream stops the lane it is serving. The terminal event
// lands after every mid-turn event that was already queued.
// runStreamedTurn runs one prepared turn on its session lane and pumps its
// events to the caller. The terminal event comes after every queued event.
func (a *LocalChatAdapter) runStreamedTurn(ctx context.Context, in Inbound, id string, events chan ChatEvent) {
pending := make(chan ChatEvent, 32)
stream := localChatStream{done: ctx.Done(), events: pending, sessionID: id}
@@ -250,18 +246,7 @@ type streamPrelude struct {
}
// prelude runs the per-message gates and the text batcher for one streamed
// fragment, on this call's own goroutine and before the session lane, and
// returns what this caller's stream does next.
//
// The gates run here rather than inside the session lane: a redelivered
// fragment is a declined delivery to the gate it always reached and never
// joins the batch it repeats; the rate budget is charged per fragment the
// way it always was; and since the reply a gate returns renders today, the
// prose is the done event of this very stream rather than a turn output.
// Rapid-fire text fragments of one thought coalesce before the session lane
// exists for the same reason: waiting inside a lane would make every
// fragment queue behind the first fragment's batch window instead of
// joining it.
// fragment, before the session lane, and returns what this stream does next.
func (a *LocalChatAdapter) prelude(ctx context.Context, in Inbound, id string) streamPrelude {
if a.Router.duplicateDelivery(in) {
return streamPrelude{event: &ChatEvent{Kind: "done", Text: dedupReply, SessionID: id}}
+6 -17
View File
@@ -79,11 +79,8 @@ func CompressionConfigForModel(details ModelDetails, promptReserve int) (Compres
return cfg, nil
}
// tokenEstimate returns a rough estimate of the token count for a string.
// ASCII text keeps the common four-characters-per-token approximation. Every
// non-ASCII rune reserves one token because byte/rune averaging substantially
// undercounts CJK text and emoji, which providers commonly tokenize more
// densely than English text.
// tokenEstimate estimates a string's tokens: four ASCII characters per token,
// one token per non-ASCII rune.
func tokenEstimate(s string) int {
ascii, nonASCII := 0, 0
for _, r := range s {
@@ -117,11 +114,8 @@ type CompressedView struct {
// TokensAfter is the estimated token count after compression.
TokensAfter int
// ProtectedFirst and ProtectedLast index the input messages passed through
// untouched, and are only meaningful when WasCompressed is true. A caller
// persisting the result writes back the original records for those
// positions, keeping their MessageID, SourceID and timestamp for redelivery
// deduplication.
// ProtectedFirst and ProtectedLast index the input messages kept unchanged;
// meaningful only when WasCompressed is true.
ProtectedFirst int
ProtectedLast int
}
@@ -132,13 +126,8 @@ type CompressedMessage struct {
Content string
}
// CompressHistory applies context compression to a list of messages. When
// the estimated token count is below the threshold, messages are returned
// unchanged. When compression triggers, messages between ProtectFirst
// and ProtectLast are replaced with a summary marker.
//
// The caller supplies messages as role/content pairs (e.g. from
// session store history) and gets back a compressed view.
// CompressHistory replaces the messages between ProtectFirst and ProtectLast
// with a summary marker once the estimated token count reaches the threshold.
func CompressHistory(messages []CompressedMessage, cfg CompressionConfig) CompressedView {
if !cfg.Enabled || cfg.ContextWindow <= 0 {
return CompressedView{
+2 -5
View File
@@ -21,11 +21,8 @@ type DashboardPage struct {
Description string
}
// dashboardPages is the single source of truth for what the dashboard exposes.
// It is deliberately a package-level registry rather than a per-router field:
// the same pages are shown regardless of identity, and the prompt's current
// page line and the dashboard_navigate tool both draw from it, so the agent
// never points at a page it was not told about.
// dashboardPages lists the dashboard pages the prompt and the
// dashboard_navigate tool can name.
var dashboardPages = []DashboardPage{
{Path: "/", Label: "Dashboard", Description: "What Archie is working on, what needs you, and token spend."},
{Path: "/tasks", Label: "Tasks", Description: "Issues Archie has picked up, and where each one stands."},
+36 -133
View File
@@ -1,11 +1,5 @@
// Package gateway defines the persistent-connection layer between archie
// and its users. Each gateway implementation (Telegram, web UI, Discord,
// etc.) owns its connection lifecycle and delegates message dispatch to a
// shared CommandRouter.
//
// The router distinguishes gateway-local commands -- handled directly
// without the LLM (model changes, status queries, restart) -- from
// general messages that need LLM processing.
// Package gateway routes chat messages from channel adapters to local
// commands or the LLM.
package gateway
import (
@@ -50,16 +44,9 @@ type StatusReader interface {
// router did not handle directly.
type LLMResponder func(ctx context.Context, in Inbound) (string, error)
// LLMStreamResponder is the streaming counterpart of LLMResponder. It
// reports the turn's progress -- text fragments and completed tool calls
// -- to stream as it is generated, and returns the complete reply when the
// turn finishes.
//
// It is optional: a gateway that cannot render partial output, or a
// deployment whose provider does not stream, simply leaves it nil and the
// Router falls back to the blocking LLMResponder. stream is called from the
// generating goroutine and must not block for long -- adapters should
// throttle their own network writes rather than stall the stream.
// LLMStreamResponder is the streaming form of LLMResponder: it reports text
// fragments and tool calls to stream and returns the full reply. Optional;
// stream must not block for long.
type LLMStreamResponder func(ctx context.Context, in Inbound, stream TurnStream) (string, error)
// ModelManager provides access to available models and allows switching the
@@ -111,12 +98,7 @@ type UpdateService interface {
CanInstall() bool
}
// TaskController approves or cancels a chat-originated task. Both
// methods must enforce authorization (identity must own the task) and
// valid state transitions; see gateway.tasks.go's StoreTaskController
// for the reference implementation. When nil on a Router, /approve and
// /cancel return "not configured".
// AgentInfo is a lightweight agent summary for /agents.
// AgentInfo is an agent summary for /agents.
type AgentInfo struct {
ID int64
Title string
@@ -134,12 +116,8 @@ type TaskController interface {
// error (surfaced to the user, not the LLM) if the task doesn't
// exist, isn't owned by identity, or isn't in waiting_human.
Approve(ctx context.Context, taskID int64, identity string) error
// Cancel moves an active task to a terminal state through the one
// cancel path: the store
// records the cancellation first, and the runtime delivers it by
// cancelling the run's in-memory context where this process owns one.
// Returns an error if the task doesn't exist, isn't owned by identity,
// or is already terminal.
// Cancel cancels an active task owned by identity. It errors if the task is
// missing, not owned or already terminal.
Cancel(ctx context.Context, taskID int64, identity string) error
}
@@ -171,11 +149,8 @@ type Router struct {
// chat adapter (internal/gateway/chat_local.go) shows the reply as it
// generates; when nil, everything falls back to LLM.
LLMStream LLMStreamResponder
// Identity is the archie identity this router belongs to (empty in
// single-identity deployments). Propagated into SpawnRequest and
// used to scope /approve and /cancel authorization -- a task
// spawned under one identity cannot be controlled from another's
// chat session.
// Identity is this router's archie identity; it scopes spawned tasks and task
// control. Empty in single-identity deployments.
Identity string
// Version is shown by the shared /version command when supplied by the
// composition root. Empty means version information is unavailable.
@@ -200,31 +175,14 @@ type Router struct {
// path. Nil drops those diagnostics silently; nothing on this path is
// important enough to fail the turn over.
Log *slog.Logger
// Limiter enforces a per-(gateway, source) inbound budget when set.
// Nil disables rate limiting entirely. A message is charged against
// Inbound.BudgetKey when the channel set one (a webhook route, which
// has a stable source but no person), else against Message.SenderID.
// A message with neither is never limited: there is no key to charge
// it against.
// Limiter enforces a per-(gateway, source) inbound budget, keyed by
// inboundBudgetKey. Nil disables it.
Limiter *ratelimit.Limiter
// Dedup declines a redelivered platform message (same platform,
// conversation and channel-native ID, delivered again inside the TTL
// window from internal/gateway/message_dedup.go) before it re-enters
// the turn pipeline. NewRouter wires the package default, so a
// production router is always guarded; set a differently configured
// gate to tune it, or nil to disable dedup entirely (test setups).
// The window is deliberately not a config knob here: the durable
// prior-reply replay in turn.go is the backstop for duplicates that
// outlive it, and no composition choice between them needs exposing.
// Dedup declines a redelivered platform message inside its TTL. Nil disables
// it.
Dedup *MessageDeduplicator
// Batches coalesces rapid-fire plain-text fragments from one sender into
// a single turn (internal/gateway/text_batch.go), so a chat client that
// splits one thought across several messages costs one agent turn, not
// one per fragment. It sits after the per-message gates (dedup, rate
// limit) and before the responder: each fragment passes the gates as
// the message it is, and the batch's single turn is the only dispatch.
// NewRouter wires the package default, so a production router batches;
// nil disables coalescing (test setups).
// Batches coalesces rapid text fragments from one sender into one turn,
// after the per-message gates. Nil disables it.
Batches *TextBatchAggregator
// SlashAccess gates slash commands by sender role. Nil leaves every
// command available, which is the pre-policy behaviour; a composition
@@ -282,12 +240,7 @@ func (r *Router) checkRateLimit(in Inbound) (blocked bool) {
return !r.Limiter.Allow(r.gatewayName, key)
}
// inboundBudgetKey returns the key this message's inbound budget is charged
// against: the channel's own transport budget key when it set one, else the
// per-person SenderID. The two are deliberately distinct -- SenderID means
// "who sent this", and a channel whose SenderID is not a person (a webhook
// route path) must not put it there, because several consumers read that
// field as a user identity.
// inboundBudgetKey returns the channel's BudgetKey when set, else SenderID.
func inboundBudgetKey(in Inbound) string {
if in.BudgetKey != "" {
return in.BudgetKey
@@ -302,12 +255,7 @@ func (r *Router) Route(ctx context.Context, in Inbound) (string, error) {
return reply, err
}
// RouteResult is Route, plus whether the sender was blocked by its inbound
// rate limit. A caller with a human reading the reply (chat channels) can
// ignore the flag and treat the reply text as usual; a caller with no human
// there (a webhook) needs it to answer with a proper rejection instead of
// echoing the rate-limit prose as a successful delivery, or accepting an
// event that was actually dropped.
// RouteResult is Route plus whether the sender hit its inbound rate limit.
func (r *Router) RouteResult(ctx context.Context, in Inbound) (reply string, rateLimited bool, err error) {
if r.duplicateDelivery(in) {
return dedupReply, false, nil
@@ -330,22 +278,15 @@ func (r *Router) RouteResult(ctx context.Context, in Inbound) (reply string, rat
return reply, false, err
}
// duplicateDelivery reports whether in is a repeat delivery inside the
// dedup window, and records the delivery so later repeats see this one.
// The check runs before the rate limit: a repeated delivery is the
// channel's doing, not the sender's, so it must not spend the sender's
// inbound budget. A nil Dedup (disabled) never blocks.
// duplicateDelivery reports whether in repeats a delivery inside the dedup
// window and records it. It runs before the rate limit. Nil Dedup never
// blocks.
func (r *Router) duplicateDelivery(in Inbound) bool {
return r.Dedup != nil && !r.Dedup.Admit(in)
}
// CollectTurn hands a gated inbound to the text batcher and returns the
// payload this call is responsible for dispatching. Every gate has already
// run by the time it is called -- a gate reply like the dedup prose is
// computed for the message it is and never waits on a batch window, and
// then the batch's single turn dispatches without running the gates again
// (their answer is already recorded). A nil Batches passes through, as do
// messages that are no fragment (internal/gateway/text_batch.go).
// payload this call must dispatch. Nil Batches passes through.
func (r *Router) CollectTurn(ctx context.Context, in Inbound) (Inbound, bool, error) {
if r.Batches == nil {
return in, true, nil
@@ -519,14 +460,8 @@ func (r *Router) dispatchSessionCommand(ctx context.Context, msg messaging.Messa
return "", false, nil
}
// streamTurn dispatches one streamed turn for an inbound the streamed chat
// adapter has already prepared: the per-message gates (dedup, rate limit)
// ran per fragment in the adapter's prelude, and the text batcher has
// settled the turn's payload -- prelude's dispatcher carries the joined
// payload for its whole batch here, so the gates answer no second time for
// messages they already saw, and in particular the combined payload's
// first-fragment source ID, which the dedup gate already recorded, does
// not read back as a redelivery.
// streamTurn dispatches one streamed turn whose gates and batching already
// ran in the adapter's prelude.
func (r *Router) streamTurn(ctx context.Context, in Inbound, stream TurnStream) (string, error) {
if r.LLMStream == nil || stream == nil {
return r.route(ctx, in)
@@ -731,11 +666,7 @@ func (r *Router) handleTasks(ctx context.Context) (string, error) {
return formatTasks(tasks, time.Now()), nil
}
// reportLineBreak ends a line of a line-oriented report. A chat report is a
// list of facts, not prose, so every one of its newlines is a real break;
// plain "\n" is CommonMark's soft wrap, which a Markdown-rendering channel
// joins into one run-on paragraph (see the Telegram renderer's
// markdownBlockParser).
// reportLineBreak is a Markdown hard line break.
const reportLineBreak = " \n"
// parkReasonMaxRunes bounds the park reason shown per task. A reason carries
@@ -763,11 +694,8 @@ func summarizeParkReason(reason string) string {
return strings.TrimSpace(string(runes[:parkReasonMaxRunes])) + "..."
}
// formatTasks renders each task with enough identity and state to act on
// it: id, title, status, workflow/stage, and age since its last
// transition -- so a task that is running but stuck (old UpdatedAt) reads
// differently from one making progress (recent UpdatedAt), which a bare
// status count could never distinguish.
// formatTasks renders each task's id, title, status, workflow/stage and age
// since its last transition.
func formatTasks(tasks []ChatTaskSummary, now time.Time) string {
var b strings.Builder
b.WriteString("🗂 Archie tasks\n\n")
@@ -833,11 +761,8 @@ var statusOrder = []string{
taskstate.Dead,
}
// sortTasksByPriority orders tasks so the ones an operator would look for
// first -- running, then waiting on them, then parked -- lead the list,
// with terminal states (merged, rejected, dead, ...) trailing. It is
// stable, so within one status group the lister's own recency order
// survives.
// sortTasksByPriority stably orders running, then waiting, then parked
// tasks, with terminal tasks last.
func sortTasksByPriority(tasks []ChatTaskSummary) {
orderMap := make(map[string]int, len(statusOrder))
for i, s := range statusOrder {
@@ -939,14 +864,8 @@ func formatRuntimeSection(b *strings.Builder, provider, model string) {
fmt.Fprintf(b, "Provider: %s%sModel: %s", provider, reportLineBreak, model)
}
// formatStatus formats daemon health into a clean, mobile-friendly summary:
// the aggregate queue line, then the health section (broker, worker pool,
// channels, chat model, last poll) from whatever the process could truthfully
// report, then the runtime block.
//
// It deliberately does not itemize tasks -- that is /tasks' job -- so it
// reduces the task counts to one aggregate health signal (is work backing
// up) rather than duplicating /tasks' per-task list.
// formatStatus renders the queue summary, the health sections the process
// can report, and the runtime block.
func formatStatus(counts map[string]int, report HealthReport, models ModelManager, now time.Time) string {
var b strings.Builder
b.WriteString("📊 Archie status\n\n")
@@ -1057,21 +976,11 @@ func renderSessionList(sessions []SessionContext, active string, now time.Time)
return strings.TrimSpace(b.String())
}
// shortSessionIDLen is how much of a session ID the chat surfaces show. It
// is also the shorthand /resume and /delete are given back, so every
// listing must truncate to the same width.
// UUIDv7 stores its timestamp at the front, so no fixed shorter prefix is
// guaranteed to distinguish sessions. UUID session references therefore use
// all 36 characters. The limit only abbreviates longer legacy/non-UUID keys.
// shortSessionIDLen is how much of a session ID listings show. UUIDs are
// shown in full; only longer keys are abbreviated.
const shortSessionIDLen = 36
// shortSessionID renders the abbreviated form of a session ID used
// wherever a session is listed.
//
// Truncation is on a rune boundary: slicing bytes could split a
// multi-byte channel-ID-derived session key mid-rune and emit invalid
// UTF-8. UUID keys are ASCII, so this only differs for the exotic cases --
// where it must stay well-formed.
// shortSessionID abbreviates a session ID on a rune boundary.
func shortSessionID(id string) string {
if r := []rune(id); len(r) > shortSessionIDLen {
return string(r[:shortSessionIDLen])
@@ -1079,14 +988,8 @@ func shortSessionID(id string) string {
return id
}
// resolveSessionRef resolves an operator-supplied session reference
// against a session list, the way /resume and /delete both accept one.
//
// An exact ID wins outright -- a full ID names one session unambiguously
// even when it is also the prefix of a longer one -- otherwise the
// reference must be a prefix of exactly one session. It returns (nil,
// false) when nothing matches and (nil, true) when more than one session
// shares the prefix.
// resolveSessionRef finds the session an exact ID or unique prefix names. It
// returns (nil, false) for no match and (nil, true) for an ambiguous prefix.
func resolveSessionRef(sessions []SessionContext, ref string) (match *SessionContext, ambiguous bool) {
for i, s := range sessions {
if s.SessionID == ref {
+3 -19
View File
@@ -6,18 +6,8 @@ import (
"time"
)
// This file is /status' health contract: the facts the daemon reports about
// its own well-being, and the rules for rendering them. It is deliberately
// separate from the work surface (/tasks, and the identity/stage/age those
// summaries carry): /status answers "is archie well", /tasks answers "what is
// archie doing", and neither repeats the other.
//
// Every section below is optional, and a nil section means "this process has
// no truthful source for that fact". The renderer omits it. It must never
// print a zero, a dash or a probe result in its place: an operator cannot
// tell an invented "0 running" from a measured one, and a probe reports
// whether a fresh connection works rather than whether the daemon's own
// connections are alive.
// Health facts for /status. A nil section means the process has no source for
// it and is omitted, never shown as zero.
// BrokerHealth is the state of this process's own task-broker connection.
type BrokerHealth struct {
@@ -152,13 +142,7 @@ func formatChannels(channels []ChannelHealth) string {
return strings.Join(parts, " · ")
}
// channelDetail collapses an adapter's error detail onto one line, so a
// multi-line error cannot break the chat reply's layout, and bounds its
// length. A failed adapter is the case where an operator most needs the
// reason, so this trims rather than drops it.
// boundedDetail flattens and caps a detail so one line of /status stays one
// line. A provider error carries whatever the provider sent back, which for an
// HTML error page or a echoed request body is neither short nor single-line.
// boundedDetail flattens a detail to one line and caps its length.
func boundedDetail(detail string) string {
flattened := strings.Join(strings.Fields(detail), " ")
runes := []rune(flattened)
-11
View File
@@ -1,14 +1,3 @@
// Package gateway: interactive.go re-exports the adapter interactive-UX
// contract from internal/domain/messaging so gateway-internal code and
// channel tests can name it without qualifying the domain package.
//
// The contract is the interactive counterpart of the media/delete
// capabilities in adapter_capabilities.go: clarify and picker are optional
// interfaces an adapter type-asserts through ClarifierOf/PickerOf, and
// approval reuses the existing ApprovalRequester flow rather than a second
// decision model. TextFallback is the shared text degrade for an adapter
// with no native question or selection UI.
package gateway
import "github.com/samcharles93/archie-core/internal/domain/messaging"
+4 -10
View File
@@ -12,11 +12,8 @@ import (
// askUserToolName is the model-facing tool that asks the human a question.
const askUserToolName = "ask_user"
// InteractiveTools builds the model-facing tool that lets a turn ask its human
// a question, but only when the channel adapter for this turn can carry one.
// The carrier is read from ctx (WithInteractive), the way the approval gate
// reads WithApprovalRequester: a channel that cannot carry an interaction
// registers no tool rather than one that always fails.
// InteractiveTools returns the ask-the-user tool when the turn's channel can
// carry an interaction, and nothing otherwise.
func InteractiveTools(ctx context.Context) []tools.ToolEntry {
if !InteractiveFromContext(ctx).Carries() {
return nil
@@ -72,11 +69,8 @@ func askUserHandler(ctx context.Context, args map[string]any) (any, error) {
return map[string]any{"answer": answer}, nil
}
// askUserChoice carries a single-choice question. A channel with a Picker gets
// the native request; one with only Clarify still carries the choice, rendered
// as numbered text and matched from the typed reply through the same domain
// fallback the adapters use, so the degrade is one implementation rather than
// two.
// askUserChoice asks a single-choice question with the channel's Picker, or
// as numbered text through Clarify.
func askUserChoice(ctx context.Context, interactive Interactive, question string, options []string) (any, error) {
req := PickerRequest{Prompt: question, Options: interactiveChoices(options)}
if interactive.Picker != nil {
+8 -41
View File
@@ -6,52 +6,23 @@ import (
"time"
)
// The deduplicator's delivery window and memory bound. A redelivery
// (webhook retry, Telegram long-poll re-fetch after a slow ack, forge
// redelivery) reaches the gateway within seconds to a few minutes of the
// first delivery, so five minutes clears the fast-path gate without ever
// colliding with the durable prior-reply replay in turn.go, which remains
// the backstop for a duplicate answered long before or long after the
// window. Each entry is one key and a timestamp, so 1024 entries stay
// comfortably under a megabyte.
// Dedup window and capacity.
const (
defaultDedupTTL = 5 * time.Minute
defaultDedupCapacity = 1024
)
// dedupKey identifies one platform message delivery: the channel that
// carried it, the conversation it addressed, and its channel-native
// message ID -- the same tuple a repeat delivery is keyed on. Two
// components are not enough: Telegram message IDs are only unique per
// chat, and different platforms reuse the same numeric ID ranges.
// dedupKey identifies one delivery: platform, conversation and
// channel-native message ID.
type dedupKey struct {
Platform string
Conversation string
SourceID string
}
// MessageDeduplicator rejects a second delivery of the same platform
// message within a TTL window, so at-least-once hand-off (webhook
// retries, Telegram long-poll re-fetch, forge redelivery) does not
// process one message twice -- a duplicate still inside the window never
// reaches the turn pipeline at all.
//
// Memory is bounded by design, not by chance: at most capacity entries
// are held. An insert brings the cache back under the bound by evicting
// expired entries first (oldest recorded delivery first, exactly the
// entries a TTL sweep would drop), then the oldest still-live delivery
// once expired entries alone no longer make room. A rejected repeat
// never extends the window: expiry is judged from the first delivery.
//
// One Router may be reached from several channel goroutines at once, so
// every method holds a mutex; Admit's test-and-record is one atomic
// step, which is what makes a concurrent duplicate see the race and
// lose it.
//
// Admit runs before the turn, so a message whose first processing fails
// stays inside the window until it expires; redeliveries of failed work
// wait out the TTL, and turn.go's prior-reply path covers anything
// that was actually completed in the meantime.
// MessageDeduplicator rejects a repeat delivery of the same platform message
// within a TTL of the first. It holds at most capacity entries, evicting
// expired entries first and then the oldest. Safe for concurrent use.
type MessageDeduplicator struct {
mu sync.Mutex
// ttl is the delivery window; cap is the live-entry bound.
@@ -89,12 +60,8 @@ func NewMessageDeduplicator(ttl time.Duration, capacity int, now func() time.Tim
}
}
// Admit records this delivery and reports whether the message may be
// processed: true for the first delivery inside the window (or the first
// after an earlier one expired), false for a repeat that is already
// inside the window. A message with no channel-native ID (its SourceID
// is empty -- gateway-local commands, most dashboard turns) has no key to
// deduplicate against and is always admitted.
// Admit records the delivery and reports whether it may be processed. A
// message with no SourceID is always admitted.
func (d *MessageDeduplicator) Admit(in Inbound) bool {
if in.Message.SourceID == "" {
return true
-16
View File
@@ -1,17 +1 @@
package gateway
// This file holds the one piece of the old channel-facing Message that
// outlived it: the role derivation.
//
// messaging.Message is the canonical persisted record and is now also the
// currency at the channel-facing boundary. Channel adapters build it
// directly and set Role themselves (always messaging.RoleUser -- a channel
// carries only what a person said), and the gateway sets
// messaging.RoleAssistant on the reply it generates, so nothing converts
// between two shapes of a message in process any more.
//
// The wire is the exception. pb.Message carries no role, so both sides of
// the gRPC contract derive it from the owning session's bot identity
// instead of adding a field to the proto -- see
// internal/infrastructure/gatewayrpc. Because both derive from the same
// session, they agree.
+4 -16
View File
@@ -17,11 +17,7 @@ type ToolSummary struct {
Description string
}
// RepoEnv is the runtime-metadata summary of one repository under
// management, rendered into the chat prompt's <env> block so the agent knows
// which checkouts it is responsible for without probing the filesystem. It is
// built only from live configuration; it never names a repository the daemon
// cannot confirm.
// RepoEnv describes one managed repository for the chat prompt's <env> block.
type RepoEnv struct {
// FullName is the configured owner/name.
FullName string
@@ -43,11 +39,8 @@ type SystemPromptConfig struct {
Channel string
Model string
SessionID string
// Page is the dashboard route the operator is on right now (e.g.
// "/tasks"). It is supplied per message by the web channel; empty for
// non-web channels, which have no page context. Rendered in the <env>
// runtime-metadata block so the agent knows where the operator is
// looking and can point them somewhere relevant.
// Page is the dashboard route the operator is on; empty outside the web
// channel.
Page string
// Now stamps the prompt's date.
Now time.Time
@@ -64,12 +57,7 @@ type SystemPromptConfig struct {
// (chat.operator). Rendered so the agent knows the identity context it
// serves under; empty means unconfigured and must be said explicitly.
Operator string
// Memory is the pre-rendered <memory> block body: the durable records the
// read path recalled for this turn's resolved subject, already bounded by
// the per-scope record limit and the render byte cap. Empty when there is
// nothing to recall, or when the read degraded (engine failure, panic,
// unresolved identity beyond global/agent scope) -- the template omits
// the block entirely in that case, exactly like Tools.
// Memory is the rendered <memory> block body; empty omits the block.
Memory string
}
+22 -105
View File
@@ -69,11 +69,7 @@ func (t *sessionTracker) resolve(ctx context.Context, platform, botUser, channel
return "", fmt.Errorf("resolve session: %w", err)
}
// Find the most recent session matching this thread and bot.
//
// Pick by LastActiveAt rather than trusting storage order so a restart,
// which always re-resolves because the cache is in-memory, cannot drop the
// operator back into a session they had left with /new.
// Pick the most recently active session for this thread and bot.
var best *SessionContext
for i, s := range sessions {
if s.Source.BotUser != botUser || s.Source.ThreadID != threadID {
@@ -89,15 +85,7 @@ func (t *sessionTracker) resolve(ctx context.Context, platform, botUser, channel
return resolved, nil
}
// Create a new session with a deterministic key so it matches the
// sessionKey format used by the LLM responder.
//
// Claim the cache slot before writing to the store, not after. Saving
// first and asking the cache who won afterwards meant the loser of a race
// had already persisted a session that nothing pointed at -- unreachable,
// but still listed by /topic and /sessions as "(untitled)", and
// resurrectable by a later restart now that resolution goes by recency.
// Whoever holds the slot is the only one that writes.
// Claim the cache slot before saving, so only the winner of a race writes.
id = sessionKeyFromFields(channelID, threadID)
if winner, won := t.claimActive(key, id); !won {
return winner, nil
@@ -124,16 +112,7 @@ func (t *sessionTracker) resolve(ctx context.Context, platform, botUser, channel
return id, nil
}
// touch records that a session is in use now.
//
// Nothing called Touch before, so LastActiveAt only ever held the creation
// time and "resolve the most recently active session" really meant the most
// recently created one -- an operator who switched to an older session with
// /topic and worked there was dropped back into the newer, abandoned one on
// the next restart.
//
// Best-effort: a failed timestamp update must not fail the turn, and the
// worst case is the ordering this restores being stale again.
// touch records that a session is in use now. Best-effort.
func (t *sessionTracker) touch(ctx context.Context, sessionID string) {
if sessionID == "" {
return
@@ -141,11 +120,8 @@ func (t *sessionTracker) touch(ctx context.Context, sessionID string) {
_ = t.sessions.Touch(ctx, sessionID)
}
// claimActive reserves key for sessionID unless another caller already holds
// it. It returns the winning session ID and whether this caller won.
//
// This is the same double-check cacheActive performs, moved ahead of the
// store write so only the winner writes.
// claimActive reserves key for sessionID unless another caller holds it, and
// returns the winning session ID and whether this caller won.
func (t *sessionTracker) claimActive(key, sessionID string) (string, bool) {
t.mu.Lock()
defer t.mu.Unlock()
@@ -190,11 +166,7 @@ func sessionKeyFromFields(channelID, threadID string) string {
// setActive sets the current session for a channel+thread, overriding any
// previously resolved session (used by /new, /branch and /topic).
func (t *sessionTracker) setActive(channelID, threadID, sessionID string) {
// An empty session ID is never meaningful, and caching one is actively
// destructive: resolve treats map presence as authoritative, so a "" here
// makes every later message in this chat persist under session "" with no
// way to recover. Rejecting it at the setter means no caller can poison
// the map, whatever it computes.
// Never cache an empty session ID.
if sessionID == "" {
return
}
@@ -203,12 +175,8 @@ func (t *sessionTracker) setActive(channelID, threadID, sessionID string) {
t.active[sessionTrackerKey(channelID, threadID)] = sessionID
}
// flattenTopic points a channel's flat key at whatever session its thread is
// currently using, in one critical section.
//
// Doing this as setActive(get(...)) was two separate critical sections, so a
// /resume or /branch landing between them was silently clobbered by the value
// read before the switch.
// flattenTopic points a channel's flat key at its thread's current session,
// in one critical section.
func (t *sessionTracker) flattenTopic(channelID, threadID string) {
t.mu.Lock()
defer t.mu.Unlock()
@@ -221,17 +189,7 @@ func (t *sessionTracker) flattenTopic(channelID, threadID string) {
t.active[sessionTrackerKey(channelID, "")] = current
}
// forget drops every channel+thread whose active session is sessionID.
//
// It is the counterpart to deleting a session from the store. resolve
// treats a cached entry as authoritative and never checks that the session
// still exists, so a pointer left behind here would make every later
// message in that chat persist under an ID the store no longer knows --
// history written to a session nothing can list, resume or delete.
//
// One session can be active under more than one key (a flat chat and a
// thread that /resume'd the same session), so every entry is swept, not
// just the one the command was typed in.
// forget drops every cached key whose active session is sessionID.
func (t *sessionTracker) forget(sessionID string) {
// An empty ID is a prefix of nothing and a value of everything a
// poisoned map would hold; sweeping on it would clear unrelated chats.
@@ -266,12 +224,8 @@ func sessionTrackerKey(channelID, threadID string) string {
return channelID + ":" + threadID
}
// sessionPlatform is the platform a session for this inbound belongs to: the
// channel that carried the message when the frontend named itself, else the
// Gateway's own name. Naming it is what makes SessionSource.Platform truthful --
// one Router serves every channel, so its own name is "web" even for a Telegram
// turn, which made the platform a constant and left the per-user identity policy
// unreachable with a real channel name.
// sessionPlatform returns the channel that carried the message, else the
// gateway's own name.
func (r *Router) sessionPlatform(in Inbound) string {
if in.Platform != "" {
return in.Platform
@@ -432,12 +386,7 @@ func (r *Router) handleRetry(ctx context.Context, msg messaging.Message) (string
if r.LLM == nil {
return "LLM is not configured. The last response has been removed; send another message to continue.", nil
}
// Replay the stored record, but route it with the live message's
// addressing. Stored history is read back with the conversation
// address of the session that holds it, which for a replay must be
// the chat the /retry was typed in. A replay carries no page: the
// operator's route is transport context of the message they sent,
// and this message is not one they just sent.
// Replay the stored record with the live message's addressing and no page.
replay := msgs[0]
replay.ConversationID = msg.ConversationID
reply, err := r.LLM(ctx, Inbound{Message: replay})
@@ -531,11 +480,7 @@ func (r *Router) handleBranch(ctx context.Context, msg messaging.Message, platfo
threadID := msg.ConversationID.ThreadID
parentID := r.sessionTracker.getActive(channelID, threadID)
if parentID == "" {
// Nothing to branch from. Telegram never reaches this -- submitTurn
// resolves first -- but the email and webhook channels call Route
// directly, and slicing an empty parent ID for the default title
// panicked. The email path runs in a goroutine with no recover, so
// that took the daemon down over a single message.
// Channels that call Route directly can reach this with no session.
return "No active session to branch from. Send a message first.", nil
}
@@ -581,13 +526,7 @@ func (r *Router) handleBranch(ctx context.Context, msg messaging.Message, platfo
return "", fmt.Errorf("inherit history: %w", err)
}
if len(msgs) > 0 {
// Clear the canonical ID so the child derives its own. The store
// honours an incoming MessageID -- which is what lets a
// read-modify-write keep identities -- so copying the parent's
// messages verbatim made two sessions claim one identity, leaving
// branch-point correlation ambiguous. It also broke dedup in the
// child: an inherited message carried an ID derived from the
// parent's session, so redelivering it appended.
// Clear MessageID so the child's copies get their own IDs.
inherited := make([]messaging.Message, 0, len(msgs))
for _, m := range msgs {
m.ID = ""
@@ -697,21 +636,9 @@ func (r *Router) compressPreview(ctx context.Context, sessionID string) (string,
), nil
}
// compressedHistory builds the message list that replaces a session's
// history after compression.
//
// Protected messages are carried over as the ORIGINAL records, not rebuilt
// from the compressed view. A rebuilt message is a different message: it gets
// a fresh canonical MessageID, loses the upstream SourceID and has its
// timestamp reset, so every message surviving a compression stops being
// recognisable on redelivery and the session doubles the next time a channel
// replays its queue. Only the summary is a new record.
//
// The summary is attributed to the bot. CompressHistory emits it with role
// "system", which has no representation in the store -- the summary is
// recorded as an assistant message instead -- and attributing a description
// of the conversation to the user makes the model replay it as something
// the human said.
// compressedHistory builds a session's history after compression: protected
// messages are the original records, and the summary is a new assistant
// message.
func compressedHistory(original []messaging.Message, view CompressedView, identity string) []messaging.Message {
summaryAt := view.SummaryIndex()
if summaryAt < 0 {
@@ -723,13 +650,8 @@ func compressedHistory(original []messaging.Message, view CompressedView, identi
head := min(view.ProtectedFirst, len(original))
tail := min(view.ProtectedLast, len(original)-head)
// The summary stands in for the span it replaced, so it takes a
// timestamp inside that span. Ordering is by timestamp, not by the order
// the caller writes: the retained messages keep their original times --
// that is what preserves their identity -- so a summary stamped with now
// would sort after the tail it is supposed to precede, and the model
// would read the recent conversation before being told earlier context
// was summarised.
// Timestamp the summary inside the span it replaced so it sorts before the
// retained tail.
if summaryAt >= len(view.Messages) {
// A view whose summary index is outside its own messages cannot be
// reconstructed; leaving history untouched is the safe answer.
@@ -796,14 +718,9 @@ func (r *Router) applyCompress(ctx context.Context, sessionID string, cfg Compre
), nil
}
// compressSessionHistory loads a session's whole stored history, compresses it
// with cfg and, when that removes anything, persists the replacement. It is
// the one compression implementation: the /compress command and the automatic
// trigger on the inbound turn path both call it, so what an operator asks for
// and what a session does unattended cannot diverge.
//
// loaded is the number of stored messages read, which is what the caller's
// reply describes when nothing was compressed.
// compressSessionHistory compresses a session's stored history with cfg and
// persists the result when anything was removed. loaded is the number of
// messages read. Both /compress and the automatic trigger use it.
func (r *Router) compressSessionHistory(ctx context.Context, sessionID string, cfg CompressionConfig) (view CompressedView, loaded int, err error) {
// Read the whole history: the replacement below becomes the session's
// entire history, so summarising only a recent window would silently
+2 -12
View File
@@ -8,21 +8,11 @@ import (
"github.com/samcharles93/archie-core/internal/domain/messaging"
)
// minDeleteRefLen is the shortest prefix /delete will act on.
//
// /resume resolves a session on any unique prefix, because resuming the
// wrong conversation is undone by resuming the right one. Deleting one is
// not undoable, so a reference short enough to be a typo is refused even
// when it happens to match exactly one session today -- the same keystroke
// would hit a different session tomorrow. A full ID always works: the
// guard applies to prefix matching, not to naming a session outright.
// minDeleteRefLen is the shortest prefix /delete accepts. A full ID always
// works.
const minDeleteRefLen = 4
// handleDelete permanently removes a session and its history.
//
// It is the only way to retire a conversation from chat: /new starts a
// fresh one and leaves the old session listed by /sessions forever, so
// without this the list only ever grows.
func (r *Router) handleDelete(ctx context.Context, msg messaging.Message, rest string) (string, error) {
ref := strings.TrimSpace(rest)
if ref == "" {
+2 -6
View File
@@ -12,12 +12,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/messaging"
)
// memorySessionStore is the in-process SessionStore for tests and embedders
// that need no durability. It follows the PostgreSQL store's contract including
// the optional TurnLedger, TurnHistory and TurnReplayStore capabilities:
// millisecond timestamps, the strictly-increasing append clamp, redelivery
// dedup on canonical IDs, and a search that ANDs lowercase word terms over
// sender and text.
// memorySessionStore is an in-memory SessionStore with the same contract as
// the PostgreSQL store.
type memorySessionStore struct {
mu sync.Mutex
sessions map[string]SessionContext
+6 -36
View File
@@ -17,23 +17,9 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/postgresdb"
)
// ── PostgreSQL implementation ───────────────────────────────────────────────
//
// postgresSessionStore is the PostgreSQL-backed SessionStore. It shares the
// SQLite store's wire contract (messaging.SessionStore plus the optional
// TurnLedger, TurnHistory and TurnReplayStore capability interfaces) and its
// on-disk representation: timestamps remain bigint milliseconds so the
// monotonic clamp (MAX(ts) + 1) keeps the same unit, and full-text search
// moves from FTS5 to a tsvector + GIN generated column over (sender, text).
//
// Unlike the SQLite store it carries no in-process mutex. Two semantics make
// that safe:
// - The strictly-increasing message timestamp is assigned inside
// InsertMessageClamped, and appends to one session are serialised by a
// transaction-scoped advisory lock (LockSessionMessages), so two
// concurrent appends cannot both read the same MAX(ts).
// - ClaimTurn is insert-first: InsertTurn's ON CONFLICT DO NOTHING makes the
// claim winner/loser decision atomically in the database.
// postgresSessionStore is the PostgreSQL SessionStore. Appends to one session
// are serialised by an advisory lock, so message timestamps stay strictly
// increasing; ClaimTurn is decided by INSERT ... ON CONFLICT DO NOTHING.
type postgresSessionStore struct {
pool *pgxpool.Pool
}
@@ -416,11 +402,7 @@ func recentMessagesFromRows(rows []postgresdb.RecentMessagesRow) []messaging.Mes
return out
}
// stripMediaBytes returns the attachment list with in-process bytes
// removed -- the shared persist-boundary rule both stores apply. Data is a
// turn-scoped in-process value: a transcript that quietly retained
// megabytes of base64 would corrupt the context-budget model the message
// text assumes. Metadata survives; bytes do not.
// stripMediaBytes returns attachments without their in-memory bytes.
func stripMediaBytes(media []messaging.MediaAttachment) []messaging.MediaAttachment {
if len(media) == 0 {
return nil
@@ -471,20 +453,8 @@ func rowMessage(base messaging.Message, mediaRaw string) messaging.Message {
return base
}
// SearchMessages runs a tsvector search over the session's entire message
// history, matching message text and sender only. The generated search column
// indexes exactly (sender, text), so ts, source_id and the other metadata are
// not part of the indexed content -- a query like "2026" cannot match every
// message via its timestamp.
//
// plainto_tsquery is the tsvector analog of the SQLite store's ftsMatchQuery:
// it parses the query as plain text, never as query syntax, and ANDs the
// surviving terms. Punctuation in the input is therefore treated as text to
// tokenize, not as a Boolean operator or column filter, which is the
// quote-escaping behaviour ftsMatchQuery provided for FTS5.
//
// Like SQLite, the full result set is counted exactly, so MessagePage.Truncated
// is always false.
// SearchMessages full-text searches a session's message text and sender with
// plainto_tsquery. Truncated is always false.
func (s *postgresSessionStore) SearchMessages(ctx context.Context, sessionID string, q MessageQuery) (MessagePage, error) {
query := strings.TrimSpace(q.Query)
if query == "" {
+9 -35
View File
@@ -8,15 +8,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/messaging"
)
// TitleGenerator proposes a display title for an untitled session.
//
// The gateway invokes it asynchronously after a successful turn on a
// session that still has no title, and persists the result itself: the
// generator is a pure proposal and must not write to the session store.
// Returning an empty title declines; returning an error leaves the
// session untitled and is logged by the implementation. The gateway
// bounds the call with a timeout, so implementations need no deadline of
// their own, but must stop promptly when ctx is cancelled.
// TitleGenerator proposes a title for an untitled session. It must not write
// to the store. An empty title declines; errors leave the session untitled.
type TitleGenerator interface {
GenerateTitle(ctx context.Context, sessionID, firstMessage string) (string, error)
}
@@ -42,16 +35,8 @@ const maxTitleRunes = 60
// a stuck model call must not pin a goroutine forever.
const titleGenerationTimeout = 30 * time.Second
// maybeAutoTitle proposes a title for an untitled session after a
// successful turn, without delaying the reply. It runs in the
// background: the title is not worth blocking the turn on, and a failed
// or slow proposal must never fail the conversation.
//
// The triggering message becomes the title source -- the first user
// message the session successfully answered while it still had no
// title. For a fresh session that is its first message; for an older
// session that predates automatic titles, it is the first message
// observed after this code is deployed, i.e. the current topic.
// maybeAutoTitle proposes a title in the background after a successful turn
// on an untitled session, using the triggering message.
func (r *Router) maybeAutoTitle(ctx context.Context, msg messaging.Message) {
if r.Titles == nil || r.sessionTracker == nil {
return
@@ -103,12 +88,7 @@ func (r *Router) generateTitle(ctx context.Context, sessionID, firstMessage stri
if title == "" {
return
}
// Re-check before writing: a manual /title that lands while the
// proposal is in flight must win over the generated one. The re-read
// closes the multi-second generation window; the residual gap between
// this read and the Save below is a few microseconds and is left open
// deliberately -- closing it would need a store-level compare-and-set
// that a cosmetic path does not justify.
// Re-read so a manual /title made meanwhile wins.
sc, err = r.sessionTracker.sessions.Get(gctx, sessionID)
if err != nil {
r.debugTitle(sessionID, "session title skipped: re-read failed", err)
@@ -123,11 +103,8 @@ func (r *Router) generateTitle(ctx context.Context, sessionID, firstMessage stri
}
}
// debugTitle reports a best-effort background failure through the
// router's optional logger. Without a logger these are dropped, exactly
// like the session tracker's best-effort touch; with one they are debug
// noise rather than alerts, because a missing title is never a turn
// failure.
// debugTitle logs a background title failure at debug level, if a logger is
// set.
func (r *Router) debugTitle(sessionID, msg string, err error) {
if r.Log != nil {
r.Log.Debug(msg, "session", sessionID, "err", err)
@@ -159,11 +136,8 @@ func (r *Router) releaseTitleInFlight(sessionID string) {
delete(r.titling, sessionID)
}
// cleanGeneratedTitle normalises a model-proposed title for display. The
// model is told to reply with a bare title, but it may wrap it in
// quotes, trail a period, or include stray whitespace; this turns
// whatever came back into a single trimmed line, and drops anything
// unusable.
// cleanGeneratedTitle trims a generated title to one line without quotes or a
// trailing period, or returns "" if unusable.
func cleanGeneratedTitle(text string) string {
s := strings.Join(strings.Fields(text), " ")
s = strings.TrimSpace(s)
+4 -22
View File
@@ -69,22 +69,9 @@ type SessionDeleteResult struct {
Message string `json:"message"`
}
// SessionTools builds the chat tools that let Archie manage its own sessions.
// Until these existed, /resume, /title and /delete were slash commands only a
// human could type, so "switch back to that conversation" had no tool path at
// all.
//
// The tools are scoped to the current platform + channel: session_list returns
// only this channel's sessions (not every session the daemon knows), and
// session_resume/session_delete resolve references against that same scoped
// list. A model in chat A cannot list or manipulate chat B's history.
//
// msg is captured so the handlers act on the chat they were built for; the
// model never supplies a channel or thread.
//
// A nil store omits every tool rather than registering ones that always fail,
// so a daemon without session support advertises nothing. A nil tracker omits
// the two tools that need it (session_resume and session_delete).
// SessionTools builds the session management tools, scoped to msg's platform
// and channel. A nil store returns none; a nil tracker omits session_resume
// and session_delete.
func SessionTools(store SessionStore, tracker *sessionTracker, platform string, msg messaging.Message) []tools.ToolEntry {
if store == nil {
return nil
@@ -317,12 +304,7 @@ func sessionDeleteTool(store SessionStore, tracker *sessionTracker, platform, ch
}
}
// sessionListLimit resolves the requested limit, falling back to the default
// for anything absent or non-positive and clamping the rest, exactly like the
// task list limit.
//
// JSON numbers decode as float64, but a model that emits an integer through a
// different provider path can arrive as int, so both are accepted.
// sessionListLimit returns the requested limit, defaulted and clamped.
func sessionListLimit(input map[string]any) int {
return tools.ListLimit(input, defaultSessionListLimit, maxSessionListLimit)
}
+5 -20
View File
@@ -43,11 +43,7 @@ type SlashDenialRecorder interface {
RecordSlashDenial(ctx context.Context, denial SlashDenial) error
}
// slashAdminOnly names the commands that reconfigure the installation or the
// model it runs, and therefore require an admin. Every other command in
// messaging.LocalCommands is an ordinary user command; task control
// (/approve, /cancel) is deliberately ordinary here because it is scoped by
// task ownership at its own layer.
// slashAdminOnly names the commands that require an admin.
var slashAdminOnly = map[string]bool{
"/model": true,
"/personality": true,
@@ -56,21 +52,10 @@ var slashAdminOnly = map[string]bool{
"/restart": true,
}
// SlashAccessPolicy decides which slash commands a chat sender may run. It
// is deny-by-default: a sender named by neither list may run nothing, so the
// zero value refuses every command.
//
// AllowAdminFrom names the senders with full access. UserAllowedCommands
// names the non-admin senders and, for each, the admin commands delegated to
// it (the ordinary commands are always available to a named user).
//
// The Router consults the policy before dispatching any local command, so a
// refusal executes none of the handler and is visible to the sender and to the
// daemon log; a wired SlashDenials sink records it for audit. The policy is
// keyed on the channel-native sender, not on an org principal: a chat message
// carries no identity the access chain can evaluate, so this is the layer that
// can decide at the point the command is typed. A composition with no policy
// leaves every command available, which is the pre-policy behaviour.
// SlashAccessPolicy decides which slash commands a sender may run. Deny by
// default: AllowAdminFrom has full access, UserAllowedCommands names users and
// their delegated admin commands. Refusals are logged and recorded through
// SlashDenials. A nil policy allows everything.
type SlashAccessPolicy struct {
AllowAdminFrom []string
UserAllowedCommands map[string][]string
+11 -44
View File
@@ -73,12 +73,8 @@ type TaskSpawnResult struct {
// supplies an adapter over the store and runtime, so this package keeps its
// independence from the task store.
type ChatTaskActor interface {
// ApplyChatTaskAction executes action on taskID, scoped to identity's own
// tasks. A nil identity is an authenticated dashboard operator, who acts
// across identities -- the distinction internal/domain/taskactions draws,
// and not the same as an empty name, which is a real identity in a
// single-identity deployment. res is the review gate answer payload; this
// tool has no instruction or selection syntax, so it is the zero value.
// ApplyChatTaskAction runs action on taskID within identity's tasks. A nil
// identity is a dashboard operator acting across identities.
ApplyChatTaskAction(ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action, res taskactions.ActionPayload) (TaskActionResult, error)
}
@@ -127,17 +123,10 @@ type ChatTaskLogResult struct {
// Truncated reports that older matching entries exist beyond what this
// page examined (the on-disk scan hit its size cap before EOF).
Truncated bool `json:"truncated"`
// Cursor is the opaque byte offset to pass back as AfterID to read the
// next page. It is the file offset just past the last line this page
// returned, so a non-zero value after a full page means "resume here";
// when MoreAvailable is false the caller is done regardless of the
// value. Zero means the log was missing or empty, not "exhausted".
// Cursor is the offset to pass as AfterID for the next page. Zero means the
// log was missing or empty.
Cursor int64 `json:"cursor"`
// MoreAvailable is true when the scan saw more matching entries that
// did not fit in this page. Combine with Truncated: a result can be
// MoreAvailable=false while still Truncated=true when the scan ended
// at the size cap, or MoreAvailable=true while Truncated=false when
// more matches remain within the same scan window.
// MoreAvailable reports that matching entries did not fit in this page.
MoreAvailable bool `json:"more_available"`
}
@@ -151,16 +140,8 @@ type ChatTaskLogReader interface {
ReadChatTaskLogs(ctx context.Context, identity string, taskID int64, attempt int, q ChatTaskLogQuery) (ChatTaskLogResult, error)
}
// TaskTools builds the chat tools that let Archie see, add to, and manage its own work
// queue. Until these existed, /spawn and the task list were slash commands only
// a human could type, so "what are you working on?" had no tool path at all.
//
// All tools are bound to identity at construction. The model never supplies
// it: a model that could name an identity could read, mutate or file work
// belonging to another instance on the same host.
//
// A nil backend omits its tool rather than registering one that always fails,
// so a daemon without chat task support advertises nothing.
// TaskTools builds the task tools, bound to identity. A nil backend omits its
// tool.
func TaskTools(lister ChatTaskLister, creator TaskCreator, logs ChatTaskLogReader, actor ChatTaskActor, identity string) []tools.ToolEntry {
var entries []tools.ToolEntry
if lister != nil {
@@ -326,11 +307,7 @@ func taskActionTool(actor ChatTaskActor, identity string) tools.ToolEntry {
return nil, fmt.Errorf("task_action: action is required")
}
// The bound identity, never input["identity"]. Passed by
// address: chat is always scoped, never an operator. The
// actor is that same bound identity, because a bot acting on
// its own channel's task is exactly what happened -- and it is
// recorded as an agent's action, not a person's.
// Always the bound identity, recorded as the agent's action.
result, err := actor.ApplyChatTaskAction(ctx, &identity, taskactions.ActorFromScope(identity), taskID, taskstate.Action(actionStr), taskactions.ActionPayload{})
if err != nil {
return nil, fmt.Errorf("task_action: %w", err)
@@ -477,14 +454,8 @@ func asStringSlice(v any) []string {
return nil
}
// asRFC3339 parses an RFC3339 timestamp string, treating the zero value
// as "no bound" (returns time.Time{} without error). An obviously
// malformed value is rejected so a model that emits nonsense does not
// silently get every entry. The parser accepts RFC3339Nano (with
// fractional seconds) as well as bare RFC3339 -- the schema advertises
// "RFC3339 timestamp" and per Go's time package the two layouts both
// match when no fractional component is present, but RFC3339 alone
// rejects the fractional case. RFC3339Nano is a strict superset.
// asRFC3339 parses an RFC3339 timestamp, with optional fractional seconds.
// Empty returns the zero time.
func asRFC3339(v any) (time.Time, error) {
s, ok := v.(string)
if !ok || strings.TrimSpace(s) == "" {
@@ -513,11 +484,7 @@ func asInt64(v any) (int64, bool) {
}
}
// taskListLimit resolves the requested limit, falling back to the default for
// anything absent or non-positive and clamping the rest.
//
// JSON numbers decode as float64, but a model that emits an integer through a
// different provider path can arrive as int, so both are accepted.
// taskListLimit returns the requested limit, defaulted and clamped.
func taskListLimit(input map[string]any) int {
return tools.ListLimit(input, defaultTaskListLimit, maxTaskListLimit)
}
+7 -30
View File
@@ -8,11 +8,8 @@ import (
"github.com/samcharles93/archie-core/internal/taskstate"
)
// StoreTaskCreator implements TaskCreator backed by a store interface.
// Chat-spawned tasks use a timestamp-based synthetic issue number to
// avoid colliding with Gitea-issued tasks; the created row is native
// (Source "chat", no backing forge issue). The configured default repo
// is used when a spawn request doesn't specify one explicitly.
// StoreTaskCreator creates chat-spawned tasks with a synthetic issue number,
// using the default repo when none is given.
type StoreTaskCreator struct {
store chatTaskWriter
defaultOwner string
@@ -40,22 +37,13 @@ type taskProfile struct {
allowed map[string]bool
}
// chatTaskWriter is the write surface StoreTaskCreator needs. It
// returns the created task's real database ID, not a *workflow.Task --
// gateway deliberately has no dependency on the task store or
// internal/domain/workflow; the daemon supplies an adapter closure over
// the store.TaskStore method of the same name.
// chatTaskWriter creates a chat task and returns its database ID.
type chatTaskWriter interface {
EnqueueChatTask(ctx context.Context, owner, repo, title, body, workflow, identity string, inputs map[string]any) (taskID int64, err error)
}
// NewStoreTaskCreator returns a TaskCreator that enqueues chat-spawned
// tasks via the daemon's store. defaultOwner/defaultRepo are used when
// a spawn request doesn't specify repo=owner/name explicitly. repos
// lists every "owner/name" pair the identity is configured for (the
// default included); an explicit repo= selection outside this set is
// rejected. When defaultOwner/defaultRepo are empty, /spawn without an
// explicit repo= returns a configuration error.
// NewStoreTaskCreator returns a TaskCreator. repos lists the allowed
// "owner/name" pairs; without a default repo, a spawn must name one.
func NewStoreTaskCreator(sw chatTaskWriter, defaultOwner, defaultRepo string, repos []string) *StoreTaskCreator {
allowed := make(map[string]bool, len(repos))
for _, r := range repos {
@@ -116,12 +104,6 @@ func splitOwnerRepo(s string) (owner, repo string, ok bool) {
return "", "", false
}
// Task lifecycle statuses come from internal/taskstate, a leaf package with
// no dependencies, so gateway stays decoupled from the task store without
// keeping a hand-synced copy of the strings. The copy that used to live here
// is how the dashboard and chat ended up recording different states for the
// same operator decision.
// ChatTaskStatus is the minimal task state StoreTaskController needs to
// authorize and validate /approve and /cancel.
type ChatTaskStatus struct {
@@ -136,13 +118,8 @@ type chatTaskController interface {
// ChatTaskStatus returns the task's status and owning identity, and
// false if no task with that ID exists.
ChatTaskStatus(ctx context.Context, taskID int64) (ChatTaskStatus, bool, error)
// ApproveChatTask releases a waiting_human task through the daemon's one
// task-action service, so chat and the dashboard cannot record different
// decisions for one operator intent. The caller has already validated the
// current status is waiting_human; the actor is the chat-bound identity,
// never an operator acting across identities. There is no review-gate
// payload: the chat surface has no instruction or selection syntax, so an
// approve posts every offered finding.
// ApproveChatTask approves a waiting_human task through the task-action
// service, posting every offered finding.
ApproveChatTask(ctx context.Context, taskID int64, actor taskactions.Actor) error
// CancelChatTask transitions an active task to a rejected/terminal
// state. Callers must have already validated the current status is
+12 -62
View File
@@ -10,19 +10,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/messaging"
)
// The batcher's quiet window, its per-batch bounds, and its open-batch cap.
// Chat clients -- Telegram in particular -- split one thought across several
// messages sent within a second or two of each other, so a quiet window of
// 1.5s since the last fragment catches that habit; a lone message is delayed
// by exactly the window, which is the price a coalescer can never avoid
// (every inbound message is bounded away from dispatch by at most the
// window). A batch is also bounded up front: at most defaultBatchFragments
// fragments or defaultBatchMaxRunes of combined text close it before the
// window runs out, and at most defaultBatchOpenCap batches may be open at
// once -- the oldest is settled early, never dropped, when a later one
// opens. The cap bounds memory the way the deduplicator's cache does: one
// open batch is a handful of Inbound values, and settling is bounded by the
// same window.
// Batching window and bounds.
const (
defaultBatchWindow = 1500 * time.Millisecond
defaultBatchFragments = 8
@@ -30,36 +18,10 @@ const (
defaultBatchOpenCap = 256
)
// TextBatchAggregator coalesces rapid-fire text fragments from one sender
// into a single turn instead of running the agent loop once per fragment.
//
// Collect is the whole contract. A message that is not a fragment (media, a
// command, anything without a per-person SenderID, anything without text)
// passes through at once: those are not parts of one thought, and a /stop
// must never wait on a window. A fragment is registered under the batch key
// (platform, conversation, sender) and the call blocks until the batch
// closes -- on a quiet window since the last fragment (reset by every join),
// or on one of the size bounds. The first still-waiting fragment is the
// dispatcher: it receives the combined payload and runs the one turn, and
// every other fragment is released with mine=false, because the batch's
// single dispatch covers it. Fragments arrive in order and are joined in
// that order; the payload carries the first fragment's identity, so the
// session records one message with one channel-native source ID.
//
// The release -- not the dispatch -- happens inside Collect: a covered
// fragment's caller is free the moment its batch settles and renders
// nothing on its own behalf, while the dispatcher's caller carries the turn
// through the ordinary session machinery, which is where per-session
// ordering stays enforced. The gate order upstream is unchanged: dedup and
// the rate limit run per fragment before Collect, so a redelivered fragment
// is a declined delivery as always and never joins the batch whose original
// it repeats, and each fragment is charged its own budget.
//
// Cancellation is per call: a fragment whose context ends before the batch
// settles leaves with its own error and takes no dispatch duty; if it was
// the dispatcher, the first still-waiting fragment inherits the slot, so
// the batch never loses its one turn to a caller that gave up. A batch
// whose every caller left settles with no dispatcher at all.
// TextBatchAggregator coalesces rapid text fragments from one sender into
// one turn. A batch closes after a quiet window or a size bound; its first
// still-waiting caller dispatches the joined payload and the others return
// mine=false. A cancelled caller leaves the batch alone.
type TextBatchAggregator struct {
window time.Duration
maxFragments int
@@ -87,12 +49,8 @@ type batchKey struct {
SenderID string
}
// coalescableText reports whether in is a fragment a batch may hold. A
// fragment is plain text from a sender with a stable per-person ID: no
// media (a photo is a turn of its own), no command (an operator's /stop is
// never delayed into a window), and text to join. An empty sender means no
// per-person stream exists to fragment -- a webhook route is an automated
// source, not someone splitting a thought.
// coalescableText reports whether in is plain text from a sender with an ID,
// with no media and no command.
func coalescableText(in Inbound) bool {
text := strings.TrimSpace(in.Message.Text)
if text == "" || strings.HasPrefix(text, "/") {
@@ -104,11 +62,8 @@ func coalescableText(in Inbound) bool {
return in.Message.ToolCall == nil && in.Message.ToolResult == nil
}
// textBatch is one open batch: the fragments in arrival order, the quiet
// deadline the latest join set, and the release every waiting call reads
// once the batch settles. The payload and the chosen dispatcher are written
// under the aggregator's mutex before release closes, so a released caller
// reads them safely.
// textBatch is one open batch. payload and dispatcher are written before
// release closes.
type textBatch struct {
key batchKey
fragments []Inbound
@@ -153,14 +108,9 @@ func NewTextBatchAggregator(window time.Duration, maxFragments, maxRunes int, no
}
}
// Collect registers a plain-text fragment in the batch for its key and
// blocks until that batch settles. It reports the payload this call is
// responsible for and whether this call must dispatch it: true for the
// batch's dispatcher (whose payload equals its own message when no fragment
// ever joined, and carries the joined text when one did), false for a
// covered fragment that must render nothing of its own. A message that is
// no fragment returns at once with its own payload. A call's own context
// cancellation takes only itself out of the batch.
// Collect adds a fragment to its batch and blocks until the batch settles. It
// returns the payload and whether this call must dispatch it. Non-fragments
// return at once.
func (b *TextBatchAggregator) Collect(ctx context.Context, in Inbound) (Inbound, bool, error) {
if !coalescableText(in) {
return in, true, nil
+12 -60
View File
@@ -15,11 +15,7 @@ import (
"github.com/samcharles93/archie-core/internal/tools"
)
// TurnPrepareContext carries the per-turn inputs the model seam needs to build
// a generation plan: the active model, the per-turn extra (identity-bound)
// tools, the model's context window used for progressive tool disclosure, and
// whether the catalog marks the model reasoning-class, which the provider seam
// needs to choose the output-token parameter.
// TurnPrepareContext carries what the model seam needs to plan a turn.
type TurnPrepareContext struct {
Model string
Extra []tools.ToolEntry
@@ -93,14 +89,8 @@ type TurnRunnerConfig struct {
Models ModelManager
Personas PersonaPromptSource
Model TurnModel
// Transcriber turns an inbound speech attachment (messaging.MediaTypeVoice)
// into text before the turn's inbound message is recorded, so stored
// history reads what was said rather than the frontend's note. The
// composition root builds it from the process's own [models]/[providers],
// which only the model-owning side of the Messaging boundary reads; a
// channel frontend carries the attachment bytes across the inbound wire
// but never holds the provider credential. Nil keeps the note (the
// capability is optional and degrades).
// Transcriber replaces an inbound voice attachment's note with its
// transcript. Nil keeps the note.
Transcriber messaging.Transcriber
Ledger TurnLedger
OwnerID string
@@ -130,16 +120,8 @@ type TurnRunnerConfig struct {
// Nil omits those tools entirely (MemoryTools treats a nil store the
// same as a subject with no writable scope: no tools registered).
MemoryWriter MemoryWriteStore
// UserIdentity resolves the initiating user's identity for one inbound
// message, per platform. It reads the platform off the inbound rather than
// closing over one, because a single Router serves every channel: a resolver
// bound to a channel name received "web" for a Telegram turn, which left
// Subject.UserID always empty in production.
//
// False (or a nil UserIdentity) means the platform carries no per-person
// identity -- the dashboard's one bearer token, or a webhook route path,
// which must never be treated as a person -- and the turn's memory Subject
// gets no UserID, so its read is agent and global scope only
// UserIdentity resolves the sending user's identity for an inbound message.
// False or nil means no per-user memory scope.
UserIdentity func(in Inbound) (memory.IdentityID, bool)
}
@@ -183,26 +165,8 @@ func (r *TurnRunner) RespondStream(ctx context.Context, in Inbound, stream TurnS
return r.Run(ctx, in, stream)
}
// Run executes one turn, reporting progress to stream. A completed duplicate
// source message replays its durable response without invoking the model
// again; the replay reaches stream as the turn's recorded tool-call events,
// in the order they originally ran, followed by one whole-text fragment for
// the answer, since there is no generation left to watch. Replaying the tool
// events first is what keeps a redelivered or restart-recovered duplicate
// from disagreeing with the original about what ran.
//
// The prior-reply fallback below (matching an already-answered source
// message by conversation history rather than by turn ID) is deliberately
// text-only: it exists for the narrow race where a process crashed after
// saving the assistant message but before the turn record was marked
// completed, so the original turn's structured tool record -- saved in the
// same call as ResponseText -- never made it to durable storage either. It
// has nothing to replay, so it must not synthesize a tool block it cannot
// verify.
//
// stream may be nil, which means the caller renders only the returned reply.
// checkConfigured returns an error naming the first unconfigured
// dependency Run requires.
// checkConfigured returns an error naming the first unconfigured dependency
// Run requires.
func (r *TurnRunner) checkConfigured() error {
switch {
case r.Router == nil:
@@ -413,17 +377,9 @@ func (r *TurnRunner) prepareTurn(ctx context.Context, sessionID string, in Inbou
return preparedTurn{prepared: prepared, modelName: modelName, modelDetails: modelDetails, view: view, media: in.Media}, nil
}
// compressSessionAtBudget compresses the session's stored history when it has
// crossed the model-derived budget, through the same replacement path the
// /compress command uses. It returns the history this turn should build its
// request from: re-read from the store after a compression was written, and
// the caller's slice untouched otherwise.
//
// It refuses to guess a budget. Without a resolved context window there is
// nothing to compare the session against, and the compatibility window the
// compressor falls back to would either summarise a conversation that fits
// its model or leave a longer one to overflow -- so an unresolved model
// leaves the session alone.
// compressSessionAtBudget compresses stored history once it passes the
// model's budget and returns the history to use. With no known context
// window it does nothing.
func (r *TurnRunner) compressSessionAtBudget(
ctx context.Context,
sessionID string,
@@ -516,12 +472,8 @@ func (r *TurnRunner) Run(ctx context.Context, in Inbound, stream TurnStream) (st
return r.generateAndComplete(ctx, turn, sessionID, prep, stream)
}
// transcribeSpeech replaces an inbound speech attachment's placeholder note
// with the transcript before the turn's message is recorded, so the store --
// and every later turn reading its history -- keeps the words rather than a
// note whose audio is gone. It degrades: a nil Transcriber, a failed call, or
// an empty transcript leaves the frontend's note in place. A turn must never
// fail because transcription was unavailable.
// transcribeSpeech replaces a voice attachment's note with its transcript,
// keeping the note on any failure.
func (r *TurnRunner) transcribeSpeech(ctx context.Context, in Inbound) messaging.Message {
msg := in.Message
if r.Transcriber == nil {
+7 -32
View File
@@ -15,11 +15,8 @@ import (
// records before the byte cap below trims further.
const memoryRecordsPerScope = 20
// memoryBlockByteCap bounds the rendered <memory> block's size. This is a
// size guard, not a timeout: the read is local and synchronous, and nothing
// here waits on the network. A record that would push the block over the cap
// is dropped (not truncated mid-record) and the drop is logged, so the block
// stays valid content rather than silently corrupted output.
// memoryBlockByteCap bounds the <memory> block; a record that would exceed it
// is dropped and logged.
const memoryBlockByteCap = 8192
// MemoryStore is the read surface prepareTurn needs from a memory engine: a
@@ -47,12 +44,7 @@ func renderMemory(ctx context.Context, store MemoryStore, subject domainmemory.S
}
}()
// One Query per scope, each capped at memoryRecordsPerScope: BuiltinEngine.
// Query bounds q.Limit across the whole result, not per scope it is given,
// so a single call across all of subject.Scopes() would let an early scope
// (agent-user is queried first) exhaust the entire budget and starve the
// later, wider scopes. Scopes() is already ordered most-specific-first, so
// appending each scope's results in order preserves that ordering.
// Query each scope separately so each gets its own limit.
var records []domainmemory.Record
for _, scope := range subject.Scopes() {
heads, err := store.Query(ctx, domainmemory.Query{
@@ -70,19 +62,8 @@ func renderMemory(ctx context.Context, store MemoryStore, subject domainmemory.S
return renderMemoryRecords(records, log)
}
// renderMemoryRecords formats records as one line each, addressed by the
// record's own id -- the same id the write path (slice 4) will take a
// memory_edit call by, so the read and write directions share one source of
// truth for addressing. A record whose line would push the block past
// memoryBlockByteCap is dropped and logged rather than truncated mid-line,
// so a partial block is never mistaken for a complete or a corrupted one.
//
// The cap is measured against each line's *escaped* size -- what
// BuildSystemPrompt's `{{xml .Memory}}` will expand it to -- not its raw
// size, because escapeXML can grow a byte fivefold ("&" -> "&amp;") and an
// unescaped-size cap would let the rendered prompt exceed it by that factor.
// The block itself still accumulates the raw (unescaped) lines: the template
// escapes once on render, so escaping here too would double-escape it.
// renderMemoryRecords formats one line per record, dropping any that would
// push the escaped block past memoryBlockByteCap.
func renderMemoryRecords(records []domainmemory.Record, log *slog.Logger) string {
var b strings.Builder
escapedLen := 0
@@ -104,14 +85,8 @@ func renderMemoryRecords(records []domainmemory.Record, log *slog.Logger) string
return strings.TrimRight(b.String(), "\n")
}
// resolveSubject builds a turn's memory Subject from the runner's agent
// identity (BotUser, the closest thing to an Agent id the tree records today
// -- see sessioncurator.Adapter) and the session's UserIdentity resolver. A
// nil resolver, or one that returns false, yields UserID "" -- Subject.Scopes
// then names only agent and global, never a wider fallback
//
// It takes the whole inbound rather than its message because the resolver needs
// the platform the message arrived on.
// resolveSubject builds the turn's memory Subject from BotUser and the
// UserIdentity resolver.
func (r *TurnRunner) resolveSubject(in Inbound) domainmemory.Subject {
subject := domainmemory.Subject{AgentID: domainmemory.AgentID(r.BotUser)}
if r.UserIdentity == nil {
+3 -15
View File
@@ -45,21 +45,9 @@ func recordSummary(r domainmemory.Record) MemoryRecordSummary {
}
}
// MemoryTools builds the chat tools that let the model manage its own
// durable memory, scoped to one turn's resolved Subject
//
// Built per turn, not registered once at boot, because the writable scope
// set is a function of the turn's Subject: two different users talking to
// the same agent get two different sets of tools, each only able to
// address that user's own scopes.
//
// The model chooses the scope KIND (an enum built from
// subject.WritableScopes(), which never includes global); it never chooses
// the agent or user id a scope resolves to -- there is no schema field for
// either, so even a model that tries to emit another user's id has nowhere
// to write it. A nil store, or a subject with no writable scope at all
// (no resolvable agent and no resolvable user), omits every tool rather
// than registering ones that always fail.
// MemoryTools builds the memory tools for one turn's Subject. The model
// picks a writable scope kind, never an id. Returns none without a store or
// writable scope.
func MemoryTools(store MemoryWriteStore, subject domainmemory.Subject) []tools.ToolEntry {
if store == nil {
return nil