feat(adk): background-task manager with subagent/filesystem/deep wiring (#1107)

* feat(adk): background-task manager with subagent/filesystem/deep wiring

Introduce a shared, domain-agnostic background-task engine and wire it into the
subagent and filesystem middlewares and the deep prebuilt agent.

adk/backgroundtask (engine):
- Manager tracks foreground/background/auto-background runs under one task-ID
  space; Run blocks with an optional foreground budget, then either completes,
  auto-backgrounds (Config.ShouldAutoBackground), or times out.
- RunStream + StreamWorkFunc forward a run's output to the caller in real time
  during the foreground phase, then on auto-background inject a generic notice
  and drain the rest into the task result.
- Cancellation records a reason on Task.Error and the foreground caller reports
  StatusCanceled (not a StatusFailed ctx error).
- Task ids are TaskType_base62(int64), where the int64 packs a ms timestamp, a
  per-ms sequence (spinning to the next ms on overflow), and random low bits —
  unique within a process and self-describing by type.
- Optional OutputStore persists completed results (filesystem.Backend satisfies
  it directly); WaitForTask/WaitAllDone for lifecycle waits.

adk/middlewares/backgroundtask (control tools):
- Injects task_output/task_stop once, bound to a Config{Manager}. task_output
  supports CC-aligned block/timeout inputs.

adk/middlewares/subagent + filesystem:
- subagent agent tool and filesystem execute tool route through a shared Manager
  when configured, gaining run_in_background; the streaming execute tool streams
  its foreground output via RunStream. filesystem.Shell now documents the
  ctx-cancellation contract.

adk/prebuilt/deep:
- deep.New accepts a Manager, wiring it into the top-level subagent + filesystem
  middlewares and injecting the control tools once; sub-agents stay
  foreground-only. Replaces the old task_tool with the subagent middleware.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

* feat: adjust background.Manager

* refactor(adk): clarify background task events

* feat: simplify done check

* feat: reduce one goroutine for direct run_in_background

* refactor: enchance background task with direct run_in_background

* refactor(adk): make background task output file worker-owned

The background-task Manager previously declared an output file globally and
wrote it once at completion, which broke its "interim output" promise and made
the file redundant with Task.Result. Move output-file ownership to the launching
adapters (execute / agent tools): the Manager only records RunInput.OutputFile,
while the worker writes — shell runs tee interim output as it streams, sub-agent
runs append their final result.

- backgroundtask: drop Config.OutputStore/OutputDir and persistOutput; add
  RunInput.OutputFile (path only, Manager never writes)
- filesystem: add Appender optional interface + AppendRequest (InMemoryBackend
  implements it); output files require an Appender, no rewrite fallback
- bundle Manager + output config into a nested BackgroundConfig across the
  filesystem, subagent, and deep configs
- name output files after the launching tool-call id (matching Task.ToolUseID),
  with a uuid fallback when absent
- task_output's formatTask points at the file when present instead of inlining
  the result

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

* feat: support mark output file

* fix: golangci-lint

* refactor(adk): hand WorkFunc a TaskInfo and key output-file failures by id

The launcher needs the Manager-assigned task id at write time to report an
output-file write failure, but the id is generated inside createTask, after the
work closure is already built. Pass a TaskInfo (read-only snapshot of
creation-time identity) as an explicit WorkFunc/StreamWorkFunc parameter so the
work receives the id directly; MarkOutputFileUnreliable then keys by id (O(1)
map lookup) instead of scanning all tasks by output-file path.

Also make the failed-write reporting honest: when a write fails, neither the
partial file nor the in-memory Result is the authoritative complete output
(Result may be empty while the task runs, or a partial projection of the file
for sub-agent runs). formatTask and the OutputFileErr doc no longer claim Result
is always the full copy.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4 <noreply@anthropic.com>

Author: 2 people

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
+}

adk/backgroundtask/id_test.go

@@ -0,0 +1,160 @@
+/*
+ * 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 (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBase62(t *testing.T) {
+	assert.Equal(t, "0", base62(0))
+	assert.Equal(t, "A", base62(10))
+	assert.Equal(t, "10", base62(62))
+	// Round-trippable shape: only alphabet chars, non-empty.
+	const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+	for _, n := range []int64{1, 61, 100, 1 << 40, (1 << 63) - 1} {
+		s := base62(n)
+		assert.NotEmpty(t, s)
+		for _, c := range s {
+			assert.True(t, strings.ContainsRune(alphabet, c), "char %q not in alphabet", c)
+		}
+	}
+}
+
+func TestTaskIDPrefix(t *testing.T) {
+	assert.Equal(t, "bash", taskIDPrefix("bash"))
+	assert.Equal(t, "subagent", taskIDPrefix("subagent"))
+	assert.Equal(t, defaultTaskIDPrefix, taskIDPrefix(""))
+}
+
+// IDs minted in a tight loop within one process must never collide, and must
+// carry the task-type prefix.
+func TestCreateTask_IDsUniqueAndPrefixed(t *testing.T) {
+	m := New(context.Background(), &Config{})
+	defer closeWithTimeout(m)
+
+	const n = 20000
+	seen := make(map[string]struct{}, n)
+	for i := 0; i < n; i++ {
+		id, err := m.createTask(context.Background(), &RunInput{Type: "bash", Description: "x"})
+		if err != nil {
+			t.Fatalf("createTask: %v", err)
+		}
+		assert.True(t, strings.HasPrefix(id, "bash_"), "id %q missing type prefix", id)
+		if _, dup := seen[id]; dup {
+			t.Fatalf("duplicate id generated: %q", id)
+		}
+		seen[id] = struct{}{}
+	}
+	assert.Len(t, seen, n)
+}
+
+// An empty task type falls back to the generic prefix.
+func TestCreateTask_EmptyTypePrefix(t *testing.T) {
+	m := New(context.Background(), &Config{})
+	defer closeWithTimeout(m)
+
+	id, err := m.createTask(context.Background(), &RunInput{Description: "x"})
+	assert.NoError(t, err)
+	assert.True(t, strings.HasPrefix(id, defaultTaskIDPrefix+"_"), "id %q", id)
+}
+
+type taskIDContextKey struct{}
+
+func TestManager_IDGenOverridesDefaultID(t *testing.T) {
+	const wantID = "short_000001"
+	ctx := context.WithValue(context.Background(), taskIDContextKey{}, "trace-1")
+	called := false
+	m := New(context.Background(), &Config{
+		IDGen: func(ctx context.Context, input *RunInput) (string, error) {
+			called = true
+			assert.Equal(t, "bash", input.Type)
+			assert.Equal(t, "call_1", input.ToolUseID)
+			assert.Equal(t, "trace-1", ctx.Value(taskIDContextKey{}))
+			return wantID, nil
+		},
+	})
+	defer closeWithTimeout(m)
+
+	result, err := m.Run(ctx, &RunInput{
+		Description: "x",
+		Type:        "bash",
+		ToolUseID:   "call_1",
+	}, workReturning("ok", nil))
+	require.NoError(t, err)
+	assert.True(t, called)
+	assert.Equal(t, wantID, result.ID)
+
+	task, ok := m.Get(wantID)
+	require.True(t, ok)
+	assert.Equal(t, wantID, task.ID)
+	assert.Equal(t, "bash", task.Type)
+}
+
+func TestCreateTask_IDGenEmptyIDFails(t *testing.T) {
+	m := New(context.Background(), &Config{
+		IDGen: func(context.Context, *RunInput) (string, error) {
+			return "", nil
+		},
+	})
+	defer closeWithTimeout(m)
+
+	_, err := m.createTask(context.Background(), &RunInput{Description: "x"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "empty id")
+	assert.Empty(t, m.List())
+}
+
+func TestCreateTask_IDGenDuplicateIDFails(t *testing.T) {
+	m := New(context.Background(), &Config{
+		IDGen: func(context.Context, *RunInput) (string, error) {
+			return "fixed", nil
+		},
+	})
+	defer closeWithTimeout(m)
+
+	id, err := m.createTask(context.Background(), &RunInput{Description: "first"})
+	require.NoError(t, err)
+	assert.Equal(t, "fixed", id)
+
+	_, err = m.createTask(context.Background(), &RunInput{Description: "second"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `task id "fixed" already exists`)
+	assert.Len(t, m.List(), 1)
+}
+
+func TestManager_IDGenErrorFailsRun(t *testing.T) {
+	wantErr := errors.New("allocate id")
+	m := New(context.Background(), &Config{
+		IDGen: func(context.Context, *RunInput) (string, error) {
+			return "", wantErr
+		},
+	})
+	defer closeWithTimeout(m)
+
+	_, err := m.Run(context.Background(), &RunInput{Description: "x"}, workReturning("ok", nil))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, wantErr)
+	assert.Contains(t, err.Error(), "task id generator")
+	assert.Empty(t, m.List())
+}