diff --git a/internal/gateway/approval.go b/internal/gateway/approval.go index 9c7fa9c6d..00a70be65 100644 --- a/internal/gateway/approval.go +++ b/internal/gateway/approval.go @@ -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" diff --git a/internal/gateway/chat_contract_aliases.go b/internal/gateway/chat_contract_aliases.go index 33eb58179..e4b9f550a 100644 --- a/internal/gateway/chat_contract_aliases.go +++ b/internal/gateway/chat_contract_aliases.go @@ -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" diff --git a/internal/gateway/chat_local.go b/internal/gateway/chat_local.go index 27ad73b87..e10d0b3a4 100644 --- a/internal/gateway/chat_local.go +++ b/internal/gateway/chat_local.go @@ -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}} diff --git a/internal/gateway/compression.go b/internal/gateway/compression.go index 3471d6898..3ba74a6f0 100644 --- a/internal/gateway/compression.go +++ b/internal/gateway/compression.go @@ -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{ diff --git a/internal/gateway/dashboard_tools.go b/internal/gateway/dashboard_tools.go index 3c8708e53..6a4b39869 100644 --- a/internal/gateway/dashboard_tools.go +++ b/internal/gateway/dashboard_tools.go @@ -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."}, diff --git a/internal/gateway/gateway.go b/internal/gateway/gateway.go index 19a83f390..1f191a399 100644 --- a/internal/gateway/gateway.go +++ b/internal/gateway/gateway.go @@ -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 { diff --git a/internal/gateway/health.go b/internal/gateway/health.go index 945b48987..ff7e206f9 100644 --- a/internal/gateway/health.go +++ b/internal/gateway/health.go @@ -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) diff --git a/internal/gateway/interactive.go b/internal/gateway/interactive.go index 951e934f5..41c0b3413 100644 --- a/internal/gateway/interactive.go +++ b/internal/gateway/interactive.go @@ -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" diff --git a/internal/gateway/interactive_tools.go b/internal/gateway/interactive_tools.go index ff8c002ca..cb7fd8848 100644 --- a/internal/gateway/interactive_tools.go +++ b/internal/gateway/interactive_tools.go @@ -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 { diff --git a/internal/gateway/message_dedup.go b/internal/gateway/message_dedup.go index 3b5ed5882..c2aba1ee9 100644 --- a/internal/gateway/message_dedup.go +++ b/internal/gateway/message_dedup.go @@ -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 diff --git a/internal/gateway/messaging_convert.go b/internal/gateway/messaging_convert.go index 525099adb..fa0ed3c2c 100644 --- a/internal/gateway/messaging_convert.go +++ b/internal/gateway/messaging_convert.go @@ -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. diff --git a/internal/gateway/prompt.go b/internal/gateway/prompt.go index aabcd1033..3f8f01126 100644 --- a/internal/gateway/prompt.go +++ b/internal/gateway/prompt.go @@ -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 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 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 - // 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 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 block body; empty omits the block. Memory string } diff --git a/internal/gateway/session_commands.go b/internal/gateway/session_commands.go index e6c66a7ff..5a85510b4 100644 --- a/internal/gateway/session_commands.go +++ b/internal/gateway/session_commands.go @@ -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 diff --git a/internal/gateway/session_delete.go b/internal/gateway/session_delete.go index d205b1ccd..67747d10e 100644 --- a/internal/gateway/session_delete.go +++ b/internal/gateway/session_delete.go @@ -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 == "" { diff --git a/internal/gateway/session_store_memory.go b/internal/gateway/session_store_memory.go index 0c51d939a..abd1f4f4b 100644 --- a/internal/gateway/session_store_memory.go +++ b/internal/gateway/session_store_memory.go @@ -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 diff --git a/internal/gateway/session_store_postgres.go b/internal/gateway/session_store_postgres.go index d0ce12458..fd3693b3d 100644 --- a/internal/gateway/session_store_postgres.go +++ b/internal/gateway/session_store_postgres.go @@ -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 == "" { diff --git a/internal/gateway/session_titles.go b/internal/gateway/session_titles.go index 9402c25f7..85b721bd2 100644 --- a/internal/gateway/session_titles.go +++ b/internal/gateway/session_titles.go @@ -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) diff --git a/internal/gateway/session_tools.go b/internal/gateway/session_tools.go index 7ca9b88c2..a5ae4d8ff 100644 --- a/internal/gateway/session_tools.go +++ b/internal/gateway/session_tools.go @@ -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) } diff --git a/internal/gateway/slash_access.go b/internal/gateway/slash_access.go index a897d6b58..81304b65a 100644 --- a/internal/gateway/slash_access.go +++ b/internal/gateway/slash_access.go @@ -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 diff --git a/internal/gateway/task_tools.go b/internal/gateway/task_tools.go index 5fdd1b965..fbc08cef2 100644 --- a/internal/gateway/task_tools.go +++ b/internal/gateway/task_tools.go @@ -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) } diff --git a/internal/gateway/tasks.go b/internal/gateway/tasks.go index dd1c41174..4c1750933 100644 --- a/internal/gateway/tasks.go +++ b/internal/gateway/tasks.go @@ -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 diff --git a/internal/gateway/text_batch.go b/internal/gateway/text_batch.go index 215d17939..9b0cb8bb1 100644 --- a/internal/gateway/text_batch.go +++ b/internal/gateway/text_batch.go @@ -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 diff --git a/internal/gateway/turn.go b/internal/gateway/turn.go index d618a53b6..0e02c11c2 100644 --- a/internal/gateway/turn.go +++ b/internal/gateway/turn.go @@ -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 { diff --git a/internal/gateway/turn_memory.go b/internal/gateway/turn_memory.go index 31ddb1a67..57d26902f 100644 --- a/internal/gateway/turn_memory.go +++ b/internal/gateway/turn_memory.go @@ -15,11 +15,8 @@ import ( // records before the byte cap below trims further. const memoryRecordsPerScope = 20 -// memoryBlockByteCap bounds the rendered 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 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 ("&" -> "&") 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 { diff --git a/internal/gateway/turn_memory_tool.go b/internal/gateway/turn_memory_tool.go index e92e92f93..66afcfdfa 100644 --- a/internal/gateway/turn_memory_tool.go +++ b/internal/gateway/turn_memory_tool.go @@ -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