feat(adk): merge agent teams into alpha/10

.gitignore

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

AGENTS.md

@@ -0,0 +1 @@
+@./AGENTS.local.md

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,41 @@ func newTypedUserMessages[M MessageType](text string) []M {
 	}
 }
 
+func stampAgentToolSessionEvent[M MessageType](event *TypedAgentEvent[M], childSessionID string) {
+	if event == nil || childSessionID == "" {
+		return
+	}
+	if event.SessionEventVariant == nil && event.Output != nil && event.Output.MessageOutput != nil {
+		ts := newEventTimestamp()
+		if event.Output.MessageOutput.IsStreaming {
+			event.SessionEventVariant = &SessionEventVariant[M]{
+				MessageStreamRef: &MessageStreamRef{
+					Timestamp: ts,
+					Kind:      SessionEventMessage,
+				},
+			}
+		} else if !isNilMessage(event.Output.MessageOutput.Message) {
+			event.SessionEventVariant = &SessionEventVariant[M]{
+				Event: &SessionEvent[M]{
+					Timestamp: ts,
+					Kind:      SessionEventMessage,
+					Message:   event.Output.MessageOutput.Message,
+				},
+			}
+		}
+	}
+	if event.SessionEventVariant != nil {
+		event.SessionEventVariant.SessionID = childSessionID
+	}
+}
+
+// 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 SessionEventVariant) 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,44 @@ 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.SessionEventVariant.Event)
+	assert.Equal(t, "agent_tool:child", event.SessionEventVariant.SessionID)
+	assert.Empty(t, event.SessionEventVariant.Event.EventID)
+	assert.False(t, event.SessionEventVariant.Event.Timestamp.IsZero())
+	assert.Equal(t, SessionEventMessage, event.SessionEventVariant.Event.Kind)
+}
+
+func TestStampAgentToolSessionEvent_Streaming(t *testing.T) {
+	event := &AgentEvent{
+		Output: &AgentOutput{
+			MessageOutput: &MessageVariant{
+				IsStreaming:   true,
+				MessageStream: schema.StreamReaderFromArray([]Message{schema.AssistantMessage("child", nil)}),
+				Role:          schema.Assistant,
+			},
+		},
+	}
+
+	stampAgentToolSessionEvent(event, "agent_tool:child")
+
+	ref := event.SessionEventVariant.MessageStreamRef
+	require.NotNil(t, ref)
+	assert.Equal(t, "agent_tool:child", event.SessionEventVariant.SessionID)
+	assert.Empty(t, ref.EventID)
+	assert.False(t, ref.Timestamp.IsZero())
+	assert.Equal(t, SessionEventMessage, ref.Kind)
+}
+
 func TestSequentialWorkflow_WithChatModelAgentTool_NestedRunPathAndSessions(t *testing.T) {
 	ctx := context.Background()
 

adk/backgroundtask/id.go

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2026 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package backgroundtask
+
+import (
+	"math/rand"
+	"time"
+)
+
+// Task-id layout: a positive int64 (63 usable bits) packed as
+//
+//	[ 41 bits ms timestamp ][ 12 bits sequence ][ 10 bits random ]
+//
+// Uniqueness within a process is guaranteed by (timestamp, sequence): the
+// sequence resets each millisecond and increments for every id minted within the
+// same millisecond, all under the Manager lock. If more than 2^12 ids are minted
+// in a single millisecond the generator spins to the next millisecond rather than
+// wrapping the sequence, so (timestamp, sequence) never repeats. The random low
+// bits only make ids look unordered/unpredictable; they are not relied upon for
+// uniqueness.
+//
+// 41 bits of milliseconds covers ~69 years; 12 bits allows 4096 ids per
+// millisecond before the generator advances to the next millisecond.
+const (
+	idSeqBits    = 12
+	idRandomBits = 10
+	idSeqLimit   = 1 << idSeqBits
+	idRandomMask = (1 << idRandomBits) - 1
+)
+
+// nextRawID packs the next task id integer. Must be called with m.mu held, as it
+// reads and advances m.seq / m.lastMs.
+func (m *Manager) nextRawID() int64 {
+	ms := time.Now().UnixMilli()
+	switch {
+	case ms > m.lastMs:
+		m.lastMs = ms
+		m.seq = 0
+	default:
+		// Same millisecond (or a backward clock step): keep the id monotonic by
+		// staying on lastMs and advancing the sequence. On sequence overflow, move
+		// to the next millisecond so (timestamp, sequence) stays unique.
+		ms = m.lastMs
+		m.seq++
+		if m.seq >= idSeqLimit {
+			ms = m.waitNextMs(m.lastMs)
+			m.lastMs = ms
+			m.seq = 0
+		}
+	}
+
+	//nolint:gosec // non-cryptographic: random bits only diffuse the id's look.
+	r := int64(rand.Intn(idRandomMask + 1))
+	return (ms << (idSeqBits + idRandomBits)) | (m.seq << idRandomBits) | r
+}
+
+// waitNextMs busy-waits until the wall clock advances past prevMs. Reached only
+// when more than 2^12 ids are minted within one millisecond.
+func (m *Manager) waitNextMs(prevMs int64) int64 {
+	ms := time.Now().UnixMilli()
+	for ms <= prevMs {
+		ms = time.Now().UnixMilli()
+	}
+	return ms
+}
+
+// base62 encodes a non-negative int64 using [0-9A-Za-z]. It is the compact,
+// URL-safe textual form of a task id's integer.
+func base62(n int64) string {
+	const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+	if n == 0 {
+		return "0"
+	}
+	var buf [11]byte // ceil(63 / log2(62)) = 11
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = alphabet[n%62]
+		n /= 62
+	}
+	return string(buf[i:])
+}
+
+// defaultTaskIDPrefix is used when a task has no Type tag.
+const defaultTaskIDPrefix = "task"
+
+// taskIDPrefix returns the id prefix for a task type, falling back to a generic
+// prefix when the type is empty. The type tag (e.g. "bash", "subagent") makes ids
+// self-describing: "bash_3Fa9...".
+func taskIDPrefix(taskType string) string {
+	if taskType == "" {
+		return defaultTaskIDPrefix
+	}
+	return taskType
+}