From 7f61db81fbf6618761002fce5af167de4d95ca71 Mon Sep 17 00:00:00 2001
From: Dmitrii Balabanov <dimonb@gmail.com>
Date: Tue, 31 Mar 2026 21:54:39 +0300
Subject: [PATCH] docs: document agentResponse, OnDelivered, sendWithRetry
 return values

- agentResponse: add struct-level doc explaining the OnDelivered lifecycle
- OutboundMessage.OnDelivered: field comment describing when it fires and
  what msgIDs contains
- sendWithRetry: document ([]string, bool) return values
- processOptions.SkipInitialSteeringPoll: update stale reference to Continue
---
 pkg/agent/loop.go       | 8 +++++++-
 pkg/bus/types.go        | 6 +++++-
 pkg/channels/manager.go | 3 +++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index ad6a5575a..ecabf0ee5 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -102,7 +102,7 @@ type processOptions struct {
 	SendResponse            bool                     // Whether to send response via bus
 	SuppressToolFeedback    bool                     // Whether to suppress inline tool feedback messages
 	NoHistory               bool                     // If true, don't load session history (for heartbeat)
-	SkipInitialSteeringPoll bool                     // If true, skip the steering poll at loop start (used by Continue)
+	SkipInitialSteeringPoll bool                     // If true, skip the steering poll at loop start (used by continueResponse)
 	Sender                  *providers.MessageSender // Author identity (nil for system/automated messages)
 }
 
@@ -112,6 +112,12 @@ type continuationTarget struct {
 	ChatID     string
 }
 
+// agentResponse carries the result of a single agent turn together with the
+// channel/chat routing needed to publish it and the delivery callback.
+// OnDelivered is called by the channel manager after all message chunks have
+// been successfully sent; it receives the platform message IDs of the
+// delivered chunks and is responsible for persisting the assistant message to
+// session history. It may be nil (e.g. NoHistory turns, heartbeats).
 type agentResponse struct {
 	Content     string
 	Channel     string
diff --git a/pkg/bus/types.go b/pkg/bus/types.go
index e5eda6d77..2c78ed6c7 100644
--- a/pkg/bus/types.go
+++ b/pkg/bus/types.go
@@ -39,7 +39,11 @@ type OutboundMessage struct {
 	Content          string            `json:"content"`
 	ReplyToMessageID string            `json:"reply_to_message_id,omitempty"`
 	Metadata         map[string]string `json:"metadata,omitempty"`
-	OnDelivered      func(msgIDs []string) `json:"-"`
+	// OnDelivered is called by the channel manager after all chunks of this
+	// message have been successfully delivered. msgIDs contains the platform
+	// message IDs of each sent chunk; it may be empty if the channel does not
+	// return IDs. The callback fires at most once per OutboundMessage.
+	OnDelivered func(msgIDs []string) `json:"-"`
 }
 
 // MediaPart describes a single media attachment to send.
diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go
index ac9dae10a..91dd0234a 100644
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@@ -752,6 +752,9 @@ func splitByLength(content string, maxLen int) []string {
 //   - ErrNotRunning / ErrSendFailed: permanent, no retry
 //   - ErrRateLimit: fixed delay retry
 //   - ErrTemporary / unknown: exponential backoff retry
+//
+// Returns the platform message IDs returned by the channel and true on
+// success, or nil/false if delivery ultimately failed.
 func (m *Manager) sendWithRetry(
 	ctx context.Context,
 	name string,