luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #2449 from code-yeongyu/fix/issue-2330-v2

Browse Source 
fix(background-agent): cap recursive subagent spawning
This commit is contained in:
YeonGyu-Kim
2026-03-11 21:00:34 +09:00
committed by GitHub
parent 7d06aea7c8 398c950085
commit 68f0446301
14 changed files with 736 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/features/background-agent/manager.test.ts
+171
View File
@@ -1746,6 +1746,32 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
}
}
function createMockClientWithSessionChain(
sessions: Record<string, { directory: string; parentID?: string }>,
options?: { sessionLookupError?: Error }
) {
return {
session: {
create: async (_args?: any) => ({ data: { id: `ses_${crypto.randomUUID()}` } }),
get: async ({ path }: { path: { id: string } }) => {
if (options?.sessionLookupError) {
throw options.sessionLookupError
}
return {
data: sessions[path.id] ?? { directory: "/test/dir" },
}
},
prompt: async () => ({}),
promptAsync: async () => ({}),
messages: async () => ({ data: [] }),
todo: async () => ({ data: [] }),
status: async () => ({ data: {} }),
abort: async () => ({}),
},
}
}
beforeEach(() => {
// given
mockClient = createMockClient()
@@ -1940,6 +1966,151 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
expect(updatedTask.startedAt.getTime()).toBeGreaterThanOrEqual(queuedAt.getTime())
}
})
test("should track rootSessionID and spawnDepth from the parent chain", async () => {
// given
manager.shutdown()
manager = new BackgroundManager(
{
client: createMockClientWithSessionChain({
"session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
"session-depth-1": { directory: "/test/dir", parentID: "session-root" },
"session-root": { directory: "/test/dir" },
}),
directory: tmpdir(),
} as unknown as PluginInput,
{ maxDepth: 3 },
)
const input = {
description: "Test task",
prompt: "Do something",
agent: "test-agent",
parentSessionID: "session-depth-2",
parentMessageID: "parent-message",
}
// when
const task = await manager.launch(input)
// then
expect(task.rootSessionID).toBe("session-root")
expect(task.spawnDepth).toBe(3)
})
test("should block launches that exceed maxDepth", async () => {
// given
manager.shutdown()
manager = new BackgroundManager(
{
client: createMockClientWithSessionChain({
"session-depth-3": { directory: "/test/dir", parentID: "session-depth-2" },
"session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
"session-depth-1": { directory: "/test/dir", parentID: "session-root" },
"session-root": { directory: "/test/dir" },
}),
directory: tmpdir(),
} as unknown as PluginInput,
{ maxDepth: 3 },
)
const input = {
description: "Test task",
prompt: "Do something",
agent: "test-agent",
parentSessionID: "session-depth-3",
parentMessageID: "parent-message",
}
// when
const result = manager.launch(input)
// then
await expect(result).rejects.toThrow("background_task.maxDepth=3")
})
test("should block launches when maxDescendants is reached", async () => {
// given
manager.shutdown()
manager = new BackgroundManager(
{
client: createMockClientWithSessionChain({
"session-root": { directory: "/test/dir" },
}),
directory: tmpdir(),
} as unknown as PluginInput,
{ maxDescendants: 1 },
)
const input = {
description: "Test task",
prompt: "Do something",
agent: "test-agent",
parentSessionID: "session-root",
parentMessageID: "parent-message",
}
await manager.launch(input)
// when
const result = manager.launch(input)
// then
await expect(result).rejects.toThrow("background_task.maxDescendants=1")
})
test("should consume descendant quota for reserved sync spawns", async () => {
// given
manager.shutdown()
manager = new BackgroundManager(
{
client: createMockClientWithSessionChain({
"session-root": { directory: "/test/dir" },
}),
directory: tmpdir(),
} as unknown as PluginInput,
{ maxDescendants: 1 },
)
await manager.reserveSubagentSpawn("session-root")
// when
const result = manager.assertCanSpawn("session-root")
// then
await expect(result).rejects.toThrow("background_task.maxDescendants=1")
})
test("should fail closed when session lineage lookup fails", async () => {
// given
manager.shutdown()
manager = new BackgroundManager(
{
client: createMockClientWithSessionChain(
{
"session-root": { directory: "/test/dir" },
},
{ sessionLookupError: new Error("session lookup failed") }
),
directory: tmpdir(),
} as unknown as PluginInput,
{ maxDescendants: 1 },
)
const input = {
description: "Test task",
prompt: "Do something",
agent: "test-agent",
parentSessionID: "session-root",
parentMessageID: "parent-message",
}
// when
const result = manager.launch(input)
// then
await expect(result).rejects.toThrow("background_task.maxDescendants cannot be enforced safely")
})
})
describe("pending task can be cancelled", () => {
src/features/background-agent/manager.ts
+148 -60
View File
@@ -51,6 +51,14 @@ import { join } from "node:path"
import { pruneStaleTasksAndNotifications } from "./task-poller"
import { checkAndInterruptStaleTasks } from "./task-poller"
import { removeTaskToastTracking } from "./remove-task-toast-tracking"
import {
createSubagentDepthLimitError,
createSubagentDescendantLimitError,
getMaxRootSessionSpawnBudget,
getMaxSubagentDepth,
resolveSubagentSpawnContext,
type SubagentSpawnContext,
} from "./subagent-spawn-limits"
type OpencodeClient = PluginInput["client"]
@@ -115,6 +123,7 @@ export class BackgroundManager {
private completionTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
private idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
private notificationQueueByParent: Map<string, Promise<void>> = new Map()
private rootDescendantCounts: Map<string, number>
private enableParentSessionNotifications: boolean
readonly taskHistory = new TaskHistory()
@@ -139,10 +148,77 @@ export class BackgroundManager {
this.tmuxEnabled = options?.tmuxConfig?.enabled ?? false
this.onSubagentSessionCreated = options?.onSubagentSessionCreated
this.onShutdown = options?.onShutdown
this.rootDescendantCounts = new Map()
this.enableParentSessionNotifications = options?.enableParentSessionNotifications ?? true
this.registerProcessCleanup()
}
async assertCanSpawn(parentSessionID: string): Promise<SubagentSpawnContext> {
const spawnContext = await resolveSubagentSpawnContext(this.client, parentSessionID)
const maxDepth = getMaxSubagentDepth(this.config)
if (spawnContext.childDepth > maxDepth) {
throw createSubagentDepthLimitError({
childDepth: spawnContext.childDepth,
maxDepth,
parentSessionID,
rootSessionID: spawnContext.rootSessionID,
})
}
const maxRootSessionSpawnBudget = getMaxRootSessionSpawnBudget(this.config)
const descendantCount = this.rootDescendantCounts.get(spawnContext.rootSessionID) ?? 0
if (descendantCount >= maxRootSessionSpawnBudget) {
throw createSubagentDescendantLimitError({
rootSessionID: spawnContext.rootSessionID,
descendantCount,
maxDescendants: maxRootSessionSpawnBudget,
})
}
return spawnContext
}
async reserveSubagentSpawn(parentSessionID: string): Promise<{
spawnContext: SubagentSpawnContext
descendantCount: number
commit: () => number
rollback: () => void
}> {
const spawnContext = await this.assertCanSpawn(parentSessionID)
const descendantCount = this.registerRootDescendant(spawnContext.rootSessionID)
let settled = false
return {
spawnContext,
descendantCount,
commit: () => {
settled = true
return descendantCount
},
rollback: () => {
if (settled) return
settled = true
this.unregisterRootDescendant(spawnContext.rootSessionID)
},
}
}
private registerRootDescendant(rootSessionID: string): number {
const nextCount = (this.rootDescendantCounts.get(rootSessionID) ?? 0) + 1
this.rootDescendantCounts.set(rootSessionID, nextCount)
return nextCount
}
private unregisterRootDescendant(rootSessionID: string): void {
const currentCount = this.rootDescendantCounts.get(rootSessionID) ?? 0
if (currentCount <= 1) {
this.rootDescendantCounts.delete(rootSessionID)
return
}
this.rootDescendantCounts.set(rootSessionID, currentCount - 1)
}
async launch(input: LaunchInput): Promise<BackgroundTask> {
log("[background-agent] launch() called with:", {
agent: input.agent,
@@ -155,61 +231,79 @@ export class BackgroundManager {
throw new Error("Agent parameter is required")
}
// Create task immediately with status="pending"
const task: BackgroundTask = {
id: `bg_${crypto.randomUUID().slice(0, 8)}`,
status: "pending",
queuedAt: new Date(),
// Do NOT set startedAt - will be set when running
// Do NOT set sessionID - will be set when running
description: input.description,
prompt: input.prompt,
agent: input.agent,
parentSessionID: input.parentSessionID,
parentMessageID: input.parentMessageID,
parentModel: input.parentModel,
parentAgent: input.parentAgent,
parentTools: input.parentTools,
model: input.model,
fallbackChain: input.fallbackChain,
attemptCount: 0,
category: input.category,
}
const spawnReservation = await this.reserveSubagentSpawn(input.parentSessionID)
this.tasks.set(task.id, task)
this.taskHistory.record(input.parentSessionID, { id: task.id, agent: input.agent, description: input.description, status: "pending", category: input.category })
// Track for batched notifications immediately (pending state)
if (input.parentSessionID) {
const pending = this.pendingByParent.get(input.parentSessionID) ?? new Set()
pending.add(task.id)
this.pendingByParent.set(input.parentSessionID, pending)
}
// Add to queue
const key = this.getConcurrencyKeyFromInput(input)
const queue = this.queuesByKey.get(key) ?? []
queue.push({ task, input })
this.queuesByKey.set(key, queue)
log("[background-agent] Task queued:", { taskId: task.id, key, queueLength: queue.length })
const toastManager = getTaskToastManager()
if (toastManager) {
toastManager.addTask({
id: task.id,
description: input.description,
agent: input.agent,
isBackground: true,
status: "queued",
skills: input.skills,
try {
log("[background-agent] spawn guard passed", {
parentSessionID: input.parentSessionID,
rootSessionID: spawnReservation.spawnContext.rootSessionID,
childDepth: spawnReservation.spawnContext.childDepth,
descendantCount: spawnReservation.descendantCount,
})
// Create task immediately with status="pending"
const task: BackgroundTask = {
id: `bg_${crypto.randomUUID().slice(0, 8)}`,
status: "pending",
queuedAt: new Date(),
rootSessionID: spawnReservation.spawnContext.rootSessionID,
// Do NOT set startedAt - will be set when running
// Do NOT set sessionID - will be set when running
description: input.description,
prompt: input.prompt,
agent: input.agent,
spawnDepth: spawnReservation.spawnContext.childDepth,
parentSessionID: input.parentSessionID,
parentMessageID: input.parentMessageID,
parentModel: input.parentModel,
parentAgent: input.parentAgent,
parentTools: input.parentTools,
model: input.model,
fallbackChain: input.fallbackChain,
attemptCount: 0,
category: input.category,
}
this.tasks.set(task.id, task)
this.taskHistory.record(input.parentSessionID, { id: task.id, agent: input.agent, description: input.description, status: "pending", category: input.category })
// Track for batched notifications immediately (pending state)
if (input.parentSessionID) {
const pending = this.pendingByParent.get(input.parentSessionID) ?? new Set()
pending.add(task.id)
this.pendingByParent.set(input.parentSessionID, pending)
}
// Add to queue
const key = this.getConcurrencyKeyFromInput(input)
const queue = this.queuesByKey.get(key) ?? []
queue.push({ task, input })
this.queuesByKey.set(key, queue)
log("[background-agent] Task queued:", { taskId: task.id, key, queueLength: queue.length })
const toastManager = getTaskToastManager()
if (toastManager) {
toastManager.addTask({
id: task.id,
description: input.description,
agent: input.agent,
isBackground: true,
status: "queued",
skills: input.skills,
})
}
spawnReservation.commit()
// Trigger processing (fire-and-forget)
this.processKey(key)
return { ...task }
} catch (error) {
spawnReservation.rollback()
throw error
}
// Trigger processing (fire-and-forget)
this.processKey(key)
return task
}
private async processKey(key: string): Promise<void> {
@@ -865,6 +959,7 @@ export class BackgroundManager {
}
}
this.rootDescendantCounts.delete(sessionID)
SessionCategoryRegistry.remove(sessionID)
}
@@ -1411,14 +1506,6 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
}
}
private formatDuration(start: Date, end?: Date): string {
return formatDuration(start, end)
}
private isAbortedSessionError(error: unknown): boolean {
return isAbortedSessionError(error)
}
private hasRunningTasks(): boolean {
for (const task of this.tasks.values()) {
if (task.status === "running") return true
@@ -1618,6 +1705,7 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
this.pendingNotifications.clear()
this.pendingByParent.clear()
this.notificationQueueByParent.clear()
this.rootDescendantCounts.clear()
this.queuesByKey.clear()
this.processingKeys.clear()
this.unregisterProcessCleanup()
src/features/background-agent/subagent-spawn-limits.ts
+87
View File
@@ -0,0 +1,87 @@
import type { BackgroundTaskConfig } from "../../config/schema"
import type { OpencodeClient } from "./constants"
export const DEFAULT_MAX_SUBAGENT_DEPTH = 3
export const DEFAULT_MAX_ROOT_SESSION_SPAWN_BUDGET = 50
export interface SubagentSpawnContext {
rootSessionID: string
parentDepth: number
childDepth: number
}
export function getMaxSubagentDepth(config?: BackgroundTaskConfig): number {
return config?.maxDepth ?? DEFAULT_MAX_SUBAGENT_DEPTH
}
export function getMaxRootSessionSpawnBudget(config?: BackgroundTaskConfig): number {
return config?.maxDescendants ?? DEFAULT_MAX_ROOT_SESSION_SPAWN_BUDGET
}
export async function resolveSubagentSpawnContext(
client: OpencodeClient,
parentSessionID: string
): Promise<SubagentSpawnContext> {
const visitedSessionIDs = new Set<string>()
let rootSessionID = parentSessionID
let currentSessionID = parentSessionID
let parentDepth = 0
while (true) {
if (visitedSessionIDs.has(currentSessionID)) {
throw new Error(`Detected a session parent cycle while resolving ${parentSessionID}`)
}
visitedSessionIDs.add(currentSessionID)
let nextParentSessionID: string | undefined
try {
const session = await client.session.get({
path: { id: currentSessionID },
})
nextParentSessionID = session.data?.parentID
} catch (error) {
const reason = error instanceof Error ? error.message : String(error)
throw new Error(
`Subagent spawn blocked: failed to resolve session lineage for ${parentSessionID}, so background_task.maxDescendants cannot be enforced safely. ${reason}`
)
}
if (!nextParentSessionID) {
rootSessionID = currentSessionID
break
}
currentSessionID = nextParentSessionID
parentDepth += 1
}
return {
rootSessionID,
parentDepth,
childDepth: parentDepth + 1,
}
}
export function createSubagentDepthLimitError(input: {
childDepth: number
maxDepth: number
parentSessionID: string
rootSessionID: string
}): Error {
const { childDepth, maxDepth, parentSessionID, rootSessionID } = input
return new Error(
`Subagent spawn blocked: child depth ${childDepth} exceeds background_task.maxDepth=${maxDepth}. Parent session: ${parentSessionID}. Root session: ${rootSessionID}. Continue in an existing subagent session instead of spawning another.`
)
}
export function createSubagentDescendantLimitError(input: {
rootSessionID: string
descendantCount: number
maxDescendants: number
}): Error {
const { rootSessionID, descendantCount, maxDescendants } = input
return new Error(
`Subagent spawn blocked: root session ${rootSessionID} already has ${descendantCount} descendants, which meets background_task.maxDescendants=${maxDescendants}. Reuse an existing session instead of spawning another.`
)
}
src/features/background-agent/types.ts
+2
View File
@@ -20,11 +20,13 @@ export interface TaskProgress {
export interface BackgroundTask {
id: string
sessionID?: string
rootSessionID?: string
parentSessionID: string
parentMessageID: string
description: string
prompt: string
agent: string
spawnDepth?: number
status: BackgroundTaskStatus
queuedAt?: Date
startedAt?: Date