chore: make code more readable

.gitignore

@@ -64,3 +64,7 @@ CLAUDE.md
 
 # Internal dev setup (not for public repo)
 /scripts/dev_setup_internal.sh
+
+# External working trees
+/examples/
+/ext/

adk/agent_tool.go

@@ -19,10 +19,12 @@ package adk
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 
 	"github.com/bytedance/sonic"
+	"github.com/google/uuid"
 
 	"github.com/cloudwego/eino/components/tool"
 	"github.com/cloudwego/eino/compose"
@@ -151,6 +153,15 @@ func (at *typedAgentTool[M]) Info(ctx context.Context) (*schema.ToolInfo, error)
 	}, nil
 }
 
+// agentToolInterruptState is the JSON-encoded state captured when an AgentTool
+// invocation is interrupted. It wraps the bridge checkpoint bytes alongside
+// the synthetic child session ID so resume preserves SessionID-based event
+// filtering across interrupt/resume.
+type agentToolInterruptState struct {
+	ChildSessionID   string `json:"child_session_id"`
+	BridgeCheckpoint []byte `json:"bridge_checkpoint"`
+}
+
 func (at *typedAgentTool[M]) InvokableRun(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
 	if cancelCtx := getCancelContext(ctx); cancelCtx != nil {
 		cancelCtx.markAgentToolDescendant()
@@ -161,19 +172,42 @@ func (at *typedAgentTool[M]) InvokableRun(ctx context.Context, argumentsInJSON s
 	var iter *AsyncIterator[*TypedAgentEvent[M]]
 	var err error
 
-	wasInterrupted, hasState, state := tool.GetInterruptState[[]byte](ctx)
+	wasInterrupted, hasState, rawState := tool.GetInterruptState[[]byte](ctx)
+
+	var childSessionID string
+	var bridgeCheckpoint []byte
+
+	if !wasInterrupted {
+		// First invocation — generate a globally-unique child session ID.
+		// Synthetic UUID avoids collisions with model-assigned tool call IDs
+		// (which may be reused across turns) and with user-assigned session IDs.
+		childSessionID = "agent_tool:" + uuid.NewString()
+	} else if !hasState {
+		return "", fmt.Errorf("agent tool '%s' interrupt has happened, but cannot find interrupt state", at.agent.Name(ctx))
+	} else {
+		// Resume — try the JSON envelope (introduced when SessionID-based event
+		// filtering landed). If the envelope does not parse or carries no bridge
+		// checkpoint, the rawState is from a pre-envelope version: treat the
+		// raw bytes as the bridge checkpoint and synthesize a fresh
+		// childSessionID. Pre-envelope checkpoints predate session persistence,
+		// so the synthesized ID has no parent-session filter to coordinate with.
+		var wrapped agentToolInterruptState
+		if json.Unmarshal(rawState, &wrapped) == nil && len(wrapped.BridgeCheckpoint) > 0 {
+			childSessionID = wrapped.ChildSessionID
+			bridgeCheckpoint = wrapped.BridgeCheckpoint
+		} else {
+			childSessionID = "agent_tool:" + uuid.NewString()
+			bridgeCheckpoint = rawState
+		}
+	}
+
 	if !wasInterrupted {
 		ms = newBridgeStore()
 
 		var input []M
 		if at.fullChatHistoryAsInput {
 			var zero M
 			if _, ok := any(zero).(*schema.Message); !ok {
-				// fullChatHistoryAsInput is only supported for *schema.Message agents and will not
-				// be extended to *schema.AgenticMessage. The chat history format and role semantics
-				// differ fundamentally between Message and AgenticMessage, and the history rewriting
-				// logic (role attribution, system message filtering, transfer messages) is specific
-				// to the Message model.
 				return "", fmt.Errorf("fullChatHistoryAsInput is only supported for *schema.Message agents")
 			}
 			msgInput, histErr := getReactChatHistory(ctx, at.agent.Name(ctx))
@@ -197,11 +231,7 @@ func (at *typedAgentTool[M]) InvokableRun(ctx context.Context, argumentsInJSON s
 		iter = runner.Run(ctx, input,
 			append(extractAndDeriveAgentToolCancelCtx(ctx, at.agent.Name(ctx), opts), WithCheckPointID(bridgeCheckpointID), withSharedParentSession())...)
 	} else {
-		if !hasState {
-			return "", fmt.Errorf("agent tool '%s' interrupt has happened, but cannot find interrupt state", at.agent.Name(ctx))
-		}
-
-		ms = newResumeBridgeStore(bridgeCheckpointID, state)
+		ms = newResumeBridgeStore(bridgeCheckpointID, bridgeCheckpoint)
 
 		agentOpts := extractAndDeriveAgentToolCancelCtx(ctx, at.agent.Name(ctx), opts)
 		agentOpts = append(agentOpts, withSharedParentSession())
@@ -239,6 +269,10 @@ func (at *typedAgentTool[M]) InvokableRun(ctx context.Context, argumentsInJSON s
 					rp = append(rp, event.RunPath...)
 					event.RunPath = rp
 				}
+				// Tag forwarded events with the child session ID so live consumers
+				// can distinguish child timeline events and the parent's persistence
+				// loop can skip them.
+				stampAgentToolSessionEvent(event, childSessionID)
 				tmp := copyTypedAgentEvent(event)
 				gen.Send(event)
 				event = tmp
@@ -257,7 +291,17 @@ func (at *typedAgentTool[M]) InvokableRun(ctx context.Context, argumentsInJSON s
 			return "", fmt.Errorf("interrupt has happened, but cannot find interrupt info")
 		}
 
-		return "", tool.CompositeInterrupt(ctx, "agent tool interrupt", data,
+		// Wrap bridge checkpoint with childSessionID so resume can recover it.
+		wrapped := agentToolInterruptState{
+			ChildSessionID:   childSessionID,
+			BridgeCheckpoint: data,
+		}
+		wrappedBytes, mErr := json.Marshal(wrapped)
+		if mErr != nil {
+			return "", fmt.Errorf("agent_tool: failed to encode interrupt state: %w", mErr)
+		}
+
+		return "", tool.CompositeInterrupt(ctx, "agent tool interrupt", wrappedBytes,
 			lastEvent.Action.internalInterrupted)
 	}
 
@@ -408,6 +452,43 @@ func newTypedUserMessages[M MessageType](text string) []M {
 	}
 }
 
+func stampAgentToolSessionEvent[M MessageType](event *TypedAgentEvent[M], childSessionID string) {
+	if event == nil || childSessionID == "" {
+		return
+	}
+	if event.EventID == "" {
+		event.EventID = uuid.NewString()
+	}
+	if event.Timestamp.IsZero() {
+		event.Timestamp = newEventTimestamp()
+	}
+	if event.SessionEvent == nil {
+		event.SessionEvent = &SessionEvent[M]{
+			SessionID: childSessionID,
+			EventID:   event.EventID,
+			Timestamp: event.Timestamp,
+		}
+		if event.Output != nil && event.Output.MessageOutput != nil {
+			event.SessionEvent.Kind = SessionEventMessage
+		}
+		return
+	}
+	event.SessionEvent.SessionID = childSessionID
+	if event.SessionEvent.EventID == "" {
+		event.SessionEvent.EventID = event.EventID
+	}
+	if event.SessionEvent.Timestamp.IsZero() {
+		event.SessionEvent.Timestamp = event.Timestamp
+	}
+}
+
+// newTypedInvokableAgentToolRunner creates a runner for the inner agent without
+// SessionEventStore. The child's events are forwarded to the parent's live stream
+// (tagged with childSessionID on SessionEvent) and filtered out of the parent's persistence.
+// The child's durability relies solely on the bridge checkpoint stored inside
+// agentToolInterruptState — there is no independent child session log.
+// This may change in the future if AgentTool needs cross-turn context
+// continuation or audit-level event logging for the child session.
 func newTypedInvokableAgentToolRunner[M MessageType](agent TypedAgent[M], store compose.CheckPointStore, enableStreaming bool) *TypedRunner[M] {
 	return &TypedRunner[M]{
 		a:               agent,

adk/agent_tool_test.go

@@ -937,6 +937,23 @@ func TestAgentTool_InvokableRun_StreamingVariant(t *testing.T) {
 	}
 }
 
+func TestStampAgentToolSessionEvent(t *testing.T) {
+	msg := schema.AssistantMessage("child", nil)
+	event := &AgentEvent{
+		Output: &AgentOutput{
+			MessageOutput: &MessageVariant{Message: msg, Role: schema.Assistant},
+		},
+	}
+
+	stampAgentToolSessionEvent(event, "agent_tool:child")
+
+	require.NotNil(t, event.SessionEvent)
+	assert.Equal(t, "agent_tool:child", event.SessionEvent.SessionID)
+	assert.Equal(t, event.EventID, event.SessionEvent.EventID)
+	assert.Equal(t, event.Timestamp, event.SessionEvent.Timestamp)
+	assert.Equal(t, SessionEventMessage, event.SessionEvent.Kind)
+}
+
 func TestSequentialWorkflow_WithChatModelAgentTool_NestedRunPathAndSessions(t *testing.T) {
 	ctx := context.Background()
 

adk/call_option.go

@@ -19,12 +19,16 @@ package adk
 import "github.com/cloudwego/eino/callbacks"
 
 type options struct {
-	sharedParentSession  bool
-	sessionValues        map[string]any
-	checkPointID         *string
-	skipTransferMessages bool
-	handlers             []callbacks.Handler
-	cancelCtx            *cancelContext
+	sharedParentSession          bool
+	sessionValues                map[string]any
+	checkPointID                 *string
+	skipTransferMessages         bool
+	enableSessionEvents          bool
+	enableTimelineEvents         bool
+	enableInternalTimelineEvents bool
+	handlers                     []callbacks.Handler
+	cancelCtx                    *cancelContext
+	refreshToolInfos             bool
 }
 
 // AgentRunOption is the call option for adk Agent.
@@ -55,6 +59,28 @@ func WithSessionValues(v map[string]any) AgentRunOption {
 	})
 }
 
+func withEnableSessionEvents() AgentRunOption {
+	return WrapImplSpecificOptFn(func(o *options) {
+		o.enableSessionEvents = true
+	})
+}
+
+// WithTimelineEvents exposes the first-class SessionEvent timeline envelope on
+// live AgentEvents. Without this option, lifecycle/span/observation-only events
+// are still produced for managed-session persistence but are stripped from the
+// user-facing stream.
+func WithTimelineEvents() AgentRunOption {
+	return WrapImplSpecificOptFn(func(o *options) {
+		o.enableTimelineEvents = true
+	})
+}
+
+func withEnableInternalTimelineEvents() AgentRunOption {
+	return WrapImplSpecificOptFn(func(o *options) {
+		o.enableInternalTimelineEvents = true
+	})
+}
+
 // WithSkipTransferMessages disables forwarding transfer messages during execution.
 //
 // NOT RECOMMENDED: Agent transfer with full context sharing between agents has not proven
@@ -81,6 +107,19 @@ func WithCallbacks(handlers ...callbacks.Handler) AgentRunOption {
 	})
 }
 
+// WithRefreshToolInfos forces the agent to re-derive its tool list from the current
+// BaseTool set instead of using the persisted TurnEndState.ToolInfos from the previous turn.
+//
+// By default, when a SessionEventStore is configured, the Runner reuses the exact tool list
+// from the previous turn's end to preserve the model's prompt cache. Use this option when
+// you have added, removed, or updated tools between turns and need the model to see the
+// changes immediately (accepting a cache miss).
+func WithRefreshToolInfos() AgentRunOption {
+	return WrapImplSpecificOptFn(func(o *options) {
+		o.refreshToolInfos = true
+	})
+}
+
 // WrapImplSpecificOptFn is the option to wrap the implementation specific option function.
 func WrapImplSpecificOptFn[T any](optFn func(*T)) AgentRunOption {
 	return AgentRunOption{

adk/cancel_edge_test.go

@@ -1435,9 +1435,20 @@ func TestWithCancel_CancelImmediate_StreamableToolAborted(t *testing.T) {
 			// ErrStreamCanceled appears on the tool's MessageStream.Recv()
 			if e.Output != nil && e.Output.MessageOutput != nil && e.Output.MessageOutput.IsStreaming &&
 				e.Output.MessageOutput.Role == schema.Tool {
-				// Signal that the tool stream event has been received.
-				close(toolStreamReady)
 				stream := e.Output.MessageOutput.MessageStream
+				// Consume the first chunk so we are sure the stream is active,
+				// then signal readiness. This ensures cancel fires while we are
+				// blocked inside Recv(), preventing a race where cancel completes
+				// before we start consuming.
+				if _, firstErr := stream.Recv(); firstErr == nil {
+					close(toolStreamReady)
+				} else {
+					if errors.Is(firstErr, ErrStreamCanceled) {
+						r.foundStreamCanceled = true
+					}
+					close(toolStreamReady)
+					continue
+				}
 				for {
 					_, recvErr := stream.Recv()
 					if recvErr != nil {