package gateway import ( "context" "errors" "fmt" "log/slog" "sync" "time" "github.com/samcharles93/archie-core/internal/domain/memory" "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/events" "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, and the model's context window used for progressive tool disclosure. type TurnPrepareContext struct { Model string Extra []tools.ToolEntry ContextWindow int } // TurnModel prepares provider-specific tools and executes one completed chat // generation. The gateway owns the conversation lifecycle; the composition // root implements this seam over the selected model runtime. type TurnModel interface { Prepare(ctx context.Context, req TurnPrepareContext) (PreparedTurnModel, error) } // PreparedTurnModel is a provider-specific generation plan. Preparation is // separate from generation because the gateway needs tool metadata before it // can calculate the conversation budget and render the system prompt. type PreparedTurnModel interface { ToolSummaries() []ToolSummary ToolSchemaTokens() int // Generate runs the turn, reporting progress to stream as it goes. // stream is nil when the caller cannot render partial output; an // implementation must then generate without reporting anything. Generate(ctx context.Context, request TurnModelRequest, stream TurnStream) (string, error) } // TurnModelRequest is the provider-neutral request assembled by the gateway. // Messages include the system prompt as their first entry. type TurnModelRequest struct { Messages []CompressedMessage MaxOutputTokens int } // PersonaPromptSource supplies the active persona prompt for a session. type PersonaPromptSource interface { GetActive(sessionID string) string } // TurnEventPublisher receives completed primary chat-turn events. type TurnEventPublisher interface { Publish(events.Event) } // TurnReplayStore provides a durable source-ID lookup for redeliveries that // have fallen outside the recent model-context window. It is optional for // compatibility with small test stores; production session stores implement // it so retries do not depend on retaining old context. type TurnReplayStore interface { FindPriorReply(ctx context.Context, sessionID, sourceID, identity string) (string, error) } var defaultTurnOwnerID = NewTurnID() const defaultTurnPersistenceTimeout = 5 * time.Second // TurnRunnerConfig contains the dependencies for one channel's chat turn // runner. The runner is channel-neutral apart from the channel name used in // prompts, session tools, and completion events. type TurnRunnerConfig struct { Router *Router Sessions SessionStore Models ModelManager Personas PersonaPromptSource Model TurnModel Ledger TurnLedger OwnerID string PersistenceTimeout time.Duration TaskLister ChatTaskLister Tasks TaskCreator TaskLogs ChatTaskLogReader TaskActor ChatTaskActor TaskIdentity string PRReviewer ChatPRReviewer Bus TurnEventPublisher BotUser string Channel string Operator string // Workspace is the directory the chat agent's file and shell tools are // rooted at (chat.workspace). Passed into the prompt's block. Workspace string // Repos lists the repositories under management with their forge host and // default branch, rendered into the prompt's block. Repos []RepoEnv Log *slog.Logger // MemoryEngine is the durable-memory read surface consulted once per turn // in prepareTurn. Nil disables the block entirely (renderMemory // treats a nil store the same as a failed read). MemoryEngine MemoryStore // MemoryWriter is the write surface the per-turn memory tool (slice 4) // uses to build memory_create/memory_update/memory_delete/memory_list. // 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 (archie-core-c1qx). // // 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 // (docs/prds/memory-engine-unification.md §3, §4). UserIdentity func(in Inbound) (memory.IdentityID, bool) } // TurnRunner owns one chat turn from session resolution through model // generation and message persistence. Channel adapters delegate to it through // Router.LLM and Router.LLMStream compatibility callbacks. type TurnRunner struct { TurnRunnerConfig recoveryMu sync.Mutex recovered bool } // NewTurnRunner constructs a chat turn runner. func NewTurnRunner(cfg TurnRunnerConfig) *TurnRunner { if cfg.Ledger == nil { cfg.Ledger, _ = cfg.Sessions.(TurnLedger) } if cfg.OwnerID == "" { cfg.OwnerID = defaultTurnOwnerID } if cfg.PersistenceTimeout <= 0 { cfg.PersistenceTimeout = defaultTurnPersistenceTimeout } return &TurnRunner{TurnRunnerConfig: cfg} } // Recover marks turns from a previous process as failed and retryable. It is // intended to run during composition before the channel starts accepting // messages; Run also calls the same guard for small embedders and tests. func (r *TurnRunner) Recover(ctx context.Context) error { return r.recoverTurns(ctx) } // Respond adapts the runner to Router.LLM. func (r *TurnRunner) Respond(ctx context.Context, in Inbound) (string, error) { return r.Run(ctx, in, nil) } // RespondStream adapts the runner to Router.LLMStream. func (r *TurnRunner) RespondStream(ctx context.Context, in Inbound, stream TurnStream) (string, error) { 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. func (r *TurnRunner) checkConfigured() error { switch { case r.Router == nil: return fmt.Errorf("chat turn router is not configured") case r.Sessions == nil: return fmt.Errorf("chat turn session store is not configured") case r.Ledger == nil: return fmt.Errorf("chat turn ledger is not configured") case r.Models == nil: return fmt.Errorf("chat turn model manager is not configured") case r.Model == nil: return fmt.Errorf("chat turn model is not configured") } return nil } // replayPriorReply returns the reply already recorded for a redelivered // message, if any. done is true when Run should return immediately with // (text, err); done is false when there is no prior reply to replay and // Run should continue generating one. func (r *TurnRunner) replayPriorReply( ctx context.Context, turn TurnRecord, sessionID string, msg messaging.Message, history []messaging.Message, stream TurnStream, ) (string, bool, error) { prior := PriorReply(history, sessionID, msg.SourceID) if prior == "" && msg.SourceID != "" { if replayStore, ok := r.Sessions.(TurnReplayStore); ok { var err error prior, err = replayStore.FindPriorReply(ctx, sessionID, msg.SourceID, r.BotUser) if err != nil { return "", true, r.failTurn(ctx, turn, fmt.Errorf("find prior chat reply: %w", err)) } } } if prior == "" { return "", false, nil } turn.Status = TurnStatusCompleted turn.ResponseText = prior turn.Error = "" turn.UpdatedAt = time.Now().UTC() if err := r.saveTurn(ctx, turn); err != nil { return "", true, r.failTurn(ctx, turn, fmt.Errorf("save replayed chat turn: %w", err)) } if r.Log != nil { r.Log.Info("replaying the reply to a redelivered message", "session", sessionID, "source_id", msg.SourceID) } if stream != nil { stream.Delta(prior) } return prior, true, nil } // claimTurn claims the turn record, replaying a completed duplicate's // stream events and rejecting a still-in-progress duplicate. done is true // when Run should return turn.ResponseText immediately without generating. func (r *TurnRunner) claimTurn( ctx context.Context, turnID, sessionID string, msg messaging.Message, stream TurnStream, ) (TurnRecord, bool, error) { turn, claim, err := r.Ledger.ClaimTurn(ctx, TurnRecord{ TurnID: turnID, SessionID: sessionID, SourceID: msg.SourceID, Status: TurnStatusAccepted, OwnerID: r.OwnerID, }) if err != nil { return TurnRecord{}, false, fmt.Errorf("claim chat turn: %w", err) } switch claim { case TurnClaimCompleted: if stream != nil { for _, event := range turn.ToolCalls { stream.ToolCall(event) } if turn.ResponseText != "" { stream.Delta(turn.ResponseText) } } return turn, true, nil case TurnClaimInProgress: return TurnRecord{}, false, fmt.Errorf("%w: %s", ErrTurnInProgress, turn.TurnID) } return turn, false, nil } // recordInboundMessage assigns msg its canonical ID, persists it as the // turn's input on first sight, and folds it into history if it is not // already present there. func (r *TurnRunner) recordInboundMessage( ctx context.Context, turn *TurnRecord, sessionID string, msg messaging.Message, history []messaging.Message, ) (messaging.Message, []messaging.Message, error) { msg.ID = messaging.MessageID(messageIDForTurn(sessionID, msg)) if turn.InputMessageID == "" { if err := r.Sessions.SaveMessage(ctx, sessionID, msg); err != nil { return msg, history, fmt.Errorf("save inbound chat message: %w", err) } turn.InputMessageID = string(msg.ID) turn.UpdatedAt = time.Now().UTC() if err := r.saveTurn(ctx, *turn); err != nil { return msg, history, fmt.Errorf("save chat turn input: %w", err) } } else { msg.ID = messaging.MessageID(turn.InputMessageID) } if !messageInHistory(history, msg.SourceID) { history = append(history, msg) } return msg, history, nil } // preparedTurn is the generation-ready state built from a turn's history: // the prepared model, its resolved details, and the compressed message // view (system prompt already prepended). type preparedTurn struct { prepared PreparedTurnModel modelName string modelDetails ModelDetails view CompressedView } // prepareTurn builds the tools, system prompt, and compressed history view // for one turn's generation call. Before the request is assembled it also // runs the session-level compression trigger, since that needs the same // model-derived budget the view is built against. func (r *TurnRunner) prepareTurn(ctx context.Context, sessionID string, in Inbound, history []messaging.Message) (preparedTurn, error) { subject := r.resolveSubject(in) extraTools := append( TaskTools(r.TaskLister, r.Tasks, r.TaskLogs, r.TaskActor, r.TaskIdentity), SessionTools(r.Sessions, r.Router.SessionTracker(), r.Router.sessionPlatform(in), in.Message)..., ) extraTools = append(extraTools, ReviewTools(r.PRReviewer, r.TaskIdentity)...) // The dashboard tools (page_index, dashboard_navigate) belong to the web // UI only: a non-web channel has no dashboard to point at. extraTools = append(extraTools, PageIndexTools(r.Channel)...) extraTools = append(extraTools, MemoryTools(r.MemoryWriter, subject)...) modelName := r.Models.ActiveModel() modelDetails := ModelDetails{} if detailed, ok := r.Models.(DetailedModelManager); ok { modelDetails, _ = detailed.ModelDetails(modelName) } prepared, err := r.Model.Prepare(ctx, TurnPrepareContext{ Model: modelName, Extra: extraTools, ContextWindow: modelDetails.ContextWindow, }) if err != nil { return preparedTurn{}, fmt.Errorf("build chat model: %w", err) } if prepared == nil { return preparedTurn{}, fmt.Errorf("build chat model: empty preparation") } persona := "" if r.Personas != nil { persona = r.Personas.GetActive(sessionID) } memoryBlock := renderMemory(ctx, r.MemoryEngine, subject, r.Log) systemPrompt := BuildSystemPrompt(SystemPromptConfig{ Persona: persona, Tools: prepared.ToolSummaries(), Channel: r.Channel, Model: modelName, SessionID: sessionID, Now: time.Now(), Page: in.Page, Workspace: r.Workspace, Repos: r.Repos, Operator: r.Operator, Memory: memoryBlock, }) compression, err := CompressionConfigForModel( modelDetails, EstimateTokens(systemPrompt)+prepared.ToolSchemaTokens(), ) if err != nil { return preparedTurn{}, fmt.Errorf("derive chat context budget: %w", err) } if r.Log != nil && modelDetails.ContextWindow <= 0 { r.Log.Warn("chat model has no context metadata; using compatibility compression budget", "model", modelName) } // The trigger runs before the request is assembled, so a session that has // crossed its budget is summarised and this turn generates from the // compressed history rather than overflowing it. history, err = r.compressSessionAtBudget(ctx, sessionID, modelDetails, compression, history) if err != nil { return preparedTurn{}, err } view := CompressHistory(compressTurnHistory(history), compression) if r.Log != nil { r.Log.Info("chat turn", "session", sessionID, "channel", in.Message.ConversationID.ChannelID, "thread", in.Message.ConversationID.ThreadID, "history_messages", len(history), "model", modelName, "context_window", modelDetails.ContextWindow, "prompt_budget", compression.MaxPromptTokens) } view.Messages = append( []CompressedMessage{{Role: "system", Content: systemPrompt}}, view.Messages..., ) return preparedTurn{prepared: prepared, modelName: modelName, modelDetails: modelDetails, view: view}, 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. func (r *TurnRunner) compressSessionAtBudget( ctx context.Context, sessionID string, details ModelDetails, cfg CompressionConfig, history []messaging.Message, ) ([]messaging.Message, error) { if details.ContextWindow <= 0 { return history, nil } compressed, err := r.Router.compressSessionIfOverBudget(ctx, sessionID, cfg) if err != nil { return history, fmt.Errorf("compress chat session: %w", err) } if !compressed { return history, nil } if r.Log != nil { r.Log.Info("compressed the chat session at its context budget", "session", sessionID, "channel", r.Channel, "messages_before", len(history), "context_window", details.ContextWindow, "prompt_budget", cfg.MaxPromptTokens) } // The store is the authority on what this session now holds, including // any message that arrived while the summary was computed. count, err := r.Sessions.MessageCount(ctx, sessionID) if err != nil { return history, fmt.Errorf("count compressed chat history: %w", err) } reloaded, err := r.Sessions.RecentMessages(ctx, sessionID, count) if err != nil { return history, fmt.Errorf("reload compressed chat history: %w", err) } return reloaded, nil } func (r *TurnRunner) Run(ctx context.Context, in Inbound, stream TurnStream) (string, error) { if err := r.checkConfigured(); err != nil { return "", err } if err := r.recoverTurns(ctx); err != nil { return "", fmt.Errorf("recover chat turns: %w", err) } sessionID, err := r.Router.ResolveSessionKey(ctx, in) if err != nil { return "", fmt.Errorf("resolve chat session: %w", err) } turnID, err := r.canonicalTurnID(ctx, sessionID, in.Message.SourceID) if err != nil { return "", fmt.Errorf("resolve canonical turn ID: %w", err) } if turnID == "" { turnID = NewTurnID() } turn, done, err := r.claimTurn(ctx, turnID, sessionID, in.Message, stream) if err != nil { return "", err } if done { return turn.ResponseText, nil } history, err := r.Sessions.RecentMessages(ctx, sessionID, 100) if err != nil { return "", r.failTurn(ctx, turn, fmt.Errorf("load chat history: %w", err)) } if replayed, done, err := r.replayPriorReply(ctx, turn, sessionID, in.Message, history, stream); done { return replayed, err } in.Message, history, err = r.recordInboundMessage(ctx, &turn, sessionID, in.Message, history) if err != nil { return "", r.failTurn(ctx, turn, err) } prep, err := r.prepareTurn(ctx, sessionID, in, history) if err != nil { return "", r.failTurn(ctx, turn, err) } return r.generateAndComplete(ctx, turn, sessionID, prep, stream) } // generateAndComplete runs the model, persists the assistant message and // completed turn, and publishes the turn-completed event. func (r *TurnRunner) generateAndComplete( ctx context.Context, turn TurnRecord, sessionID string, prep preparedTurn, stream TurnStream, ) (string, error) { recorder := &toolCallRecorder{next: stream} text, err := prep.prepared.Generate(ctx, TurnModelRequest{ Messages: prep.view.Messages, MaxOutputTokens: prep.modelDetails.MaxOutputTokens, }, recorder) if err != nil { return "", r.failTurn(ctx, turn, err) } assistant := messaging.Message{ ID: messaging.MessageID(assistantMessageIDForTurn(turn.TurnID)), Sender: r.BotUser, Role: messaging.RoleAssistant, Text: text, } if err := r.Sessions.SaveMessage(ctx, sessionID, assistant); err != nil { return "", r.failTurn(ctx, turn, fmt.Errorf("save outbound chat message: %w", err)) } turn.Status = TurnStatusCompleted turn.AssistantMessageID = string(assistant.ID) turn.ResponseText = text turn.ToolCalls = recorder.events turn.Error = "" turn.UpdatedAt = time.Now().UTC() if err := r.saveTurn(ctx, turn); err != nil { return "", r.failTurn(ctx, turn, fmt.Errorf("save completed chat turn: %w", err)) } if r.Bus != nil { r.Bus.Publish(events.Event{ Kind: events.KindTurnCompleted, Detail: sessionID, Data: map[string]any{"session": sessionID, "channel": r.Channel}, }) } return text, nil } // canonicalTurnID preserves a matching identifier written by the legacy // separator encoding. A legacy collision belonging to a different // session/source pair is ignored in favour of the injective identifier. func (r *TurnRunner) canonicalTurnID(ctx context.Context, sessionID, sourceID string) (string, error) { current := CanonicalTurnID(sessionID, sourceID) if current == "" { return "", nil } legacy := legacyCanonicalTurnID(sessionID, sourceID) if current == legacy { return current, nil } turn, ok, err := r.Ledger.GetTurn(ctx, legacy) if err != nil { return "", err } if ok && turn.SessionID == sessionID && turn.SourceID == sourceID { return legacy, nil } return current, nil } func (r *TurnRunner) failTurn(ctx context.Context, turn TurnRecord, cause error) error { if errors.Is(cause, context.Canceled) { turn.Status = TurnStatusCancelled } else { turn.Status = TurnStatusFailed } turn.Error = cause.Error() turn.UpdatedAt = time.Now().UTC() if err := r.saveTurn(ctx, turn); err != nil { return errors.Join(cause, fmt.Errorf("save failed chat turn: %w", err)) } return cause } func (r *TurnRunner) recoverTurns(ctx context.Context) error { r.recoveryMu.Lock() defer r.recoveryMu.Unlock() if r.recovered { return nil } if err := r.Ledger.RecoverTurns(ctx, r.OwnerID); err != nil { return err } r.recovered = true return nil } func (r *TurnRunner) saveTurn(ctx context.Context, turn TurnRecord) error { persistCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), r.PersistenceTimeout) defer cancel() return r.Ledger.SaveTurn(persistCtx, turn) } func messageIDForTurn(sessionID string, msg messaging.Message) string { if msg.ID != "" { return string(msg.ID) } if id := CanonicalMessageID(sessionID, msg.SourceID); id != "" { return id } return NewTurnID() } func messageInHistory(history []messaging.Message, sourceID string) bool { if sourceID == "" { return false } for _, stored := range history { if stored.SourceID == sourceID { return true } } return false } // compressTurnHistory renders stored history as role/content pairs. The // role comes from the record, which its producer sets when the message is // written -- RoleUser at the channel, RoleAssistant at generateAndComplete. func compressTurnHistory(history []messaging.Message) []CompressedMessage { compressed := make([]CompressedMessage, 0, len(history)) for _, message := range history { role := "user" if message.Role == messaging.RoleAssistant { role = "assistant" } compressed = append(compressed, CompressedMessage{Role: role, Content: message.Text}) } return compressed }