vrr/opencode
2
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-05-09 03:00:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 19

Apply PR #24174: feat(core): add background subagent support

Browse source
This commit is contained in:
opencode-agent[bot] 2026-04-27 20:02:21 +00:00
commit e27ce92ace
12 changed files with 809 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

4
packages/opencode/src/cli/cmd/tui/routes/session/index.tsx
View file

@ -2001,7 +2001,9 @@ function Task(props: ToolProps<typeof TaskTool>) {
const content = createMemo(() => {
if (!props.input.description) return ""
let content = [`${Locale.titlecase(props.input.subagent_type ?? "General")} Task — ${props.input.description}`]
const description =
props.metadata.background === true ? `${props.input.description} (background)` : props.input.description
let content = [`${Locale.titlecase(props.input.subagent_type ?? "General")} Task — ${description}`]
if (isRunning() && tools().length > 0) {
// content[0] += ` · ${tools().length} toolcalls`

4
packages/opencode/src/session/prompt.ts
View file

@ -118,6 +118,10 @@ export const layer = Layer.effect(
cancel: (sessionID: SessionID) => run.fork(cancel(sessionID)),
resolvePromptParts: (template: string) => resolvePromptParts(template),
prompt: (input: PromptInput) => prompt(input),
loop: (input: LoopInput) => loop(input),
fork: (effect: Effect.Effect<void, never, never>) => {
run.fork(effect)
},
} satisfies TaskPromptOps
})

7
packages/opencode/src/tool/registry.ts
View file

@ -7,6 +7,7 @@ import { GlobTool } from "./glob"
import { GrepTool } from "./grep"
import { ReadTool } from "./read"
import { TaskTool } from "./task"
import { TaskStatusTool } from "./task_status"
import { TodoWriteTool } from "./todo"
import { WebFetchTool } from "./webfetch"
import { WriteTool } from "./write"
@ -50,6 +51,7 @@ import { Agent } from "../agent/agent"
import { Git } from "@/git"
import { Skill } from "../skill"
import { Permission } from "@/permission"
import { SessionStatus } from "@/session/status"
const log = Log.create({ service: "tool.registry" })
@ -82,6 +84,7 @@ export const layer: Layer.Layer<
| Agent.Service
| Skill.Service
| Session.Service
| SessionStatus.Service
| Provider.Service
| Git.Service
| LSP.Service
@ -121,6 +124,7 @@ export const layer: Layer.Layer<
const greptool = yield* GrepTool
const patchtool = yield* ApplyPatchTool
const skilltool = yield* SkillTool
const taskstatus = yield* TaskStatusTool
const agent = yield* Agent.Service
const state = yield* InstanceState.make<State>(
@ -201,6 +205,7 @@ export const layer: Layer.Layer<
edit: Tool.init(edit),
write: Tool.init(writetool),
task: Tool.init(task),
taskstatus: Tool.init(taskstatus),
fetch: Tool.init(webfetch),
todo: Tool.init(todo),
search: Tool.init(websearch),
@ -226,6 +231,7 @@ export const layer: Layer.Layer<
tool.edit,
tool.write,
tool.task,
tool.taskstatus,
tool.fetch,
tool.todo,
tool.search,
@ -345,6 +351,7 @@ export const defaultLayer = Layer.suspend(() =>
Layer.provide(Skill.defaultLayer),
Layer.provide(Agent.defaultLayer),
Layer.provide(Session.defaultLayer),
Layer.provide(SessionStatus.defaultLayer),
Layer.provide(Provider.defaultLayer),
Layer.provide(Git.defaultLayer),
Layer.provide(LSP.defaultLayer),

194
packages/opencode/src/tool/task.ts
View file

@ -2,17 +2,22 @@ import * as Tool from "./tool"
import DESCRIPTION from "./task.txt"
import { Session } from "@/session/session"
import { ShellToolID } from "./shell/id"
import { Bus } from "../bus"
import { SessionID, MessageID } from "../session/schema"
import { MessageV2 } from "../session/message-v2"
import { Agent } from "../agent/agent"
import type { SessionPrompt } from "../session/prompt"
import { Config } from "@/config/config"
import { Effect, Schema } from "effect"
import { SessionStatus } from "@/session/status"
import { TuiEvent } from "@/cli/cmd/tui/event"
import { Cause, Effect, Option, Schema } from "effect"
export interface TaskPromptOps {
cancel(sessionID: SessionID): void
resolvePromptParts(template: string): Effect.Effect<SessionPrompt.PromptInput["parts"]>
prompt(input: SessionPrompt.PromptInput): Effect.Effect<MessageV2.WithParts>
loop(input: SessionPrompt.LoopInput): Effect.Effect<MessageV2.WithParts>
fork(effect: Effect.Effect<void, never, never>): void
}
const id = "task"
@ -21,24 +26,65 @@ export const Parameters = Schema.Struct({
description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
task_id: Schema.optional(Schema.String).annotate({
task_id: Schema.optional(SessionID).annotate({
description:
"This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
}),
command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
background: Schema.optional(Schema.Boolean).annotate({
description: "When true, launch the subagent in the background and return immediately",
}),
})
function output(sessionID: SessionID, text: string) {
return [
`task_id: ${sessionID} (for resuming to continue this task if needed)`,
"",
"<task_result>",
text,
"</task_result>",
].join("\n")
}
function backgroundOutput(sessionID: SessionID) {
return [
`task_id: ${sessionID} (for polling this task with task_status)`,
"state: running",
"",
"<task_result>",
"Background task started. Continue your current work and call task_status when you need the result.",
"</task_result>",
].join("\n")
}
function backgroundMessage(input: { sessionID: SessionID; description: string; state: "completed" | "error"; text: string }) {
const tag = input.state === "completed" ? "task_result" : "task_error"
const title =
input.state === "completed"
? `Background task completed: ${input.description}`
: `Background task failed: ${input.description}`
return [title, `task_id: ${input.sessionID}`, `state: ${input.state}`, `<${tag}>`, input.text, `</${tag}>`].join(
"\n",
)
}
function errorText(error: unknown) {
if (error instanceof Error) return error.message
return String(error)
}
export const TaskTool = Tool.define(
id,
Effect.gen(function* () {
const agent = yield* Agent.Service
const bus = yield* Bus.Service
const config = yield* Config.Service
const sessions = yield* Session.Service
const status = yield* SessionStatus.Service
const run = Effect.fn("TaskTool.execute")(function* (
params: Schema.Schema.Type<typeof Parameters>,
ctx: Tool.Context,
) {
const run = Effect.fn(
"TaskTool.execute",
)(function* (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) {
const cfg = yield* config.get()
const primaryTools = (cfg.experimental?.primary_tools ?? []).map(ShellToolID.normalize)
@ -64,7 +110,7 @@ export const TaskTool = Tool.define(
const taskID = params.task_id
const session = taskID
? yield* sessions.get(SessionID.make(taskID)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
? yield* sessions.get(taskID).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
: undefined
const nextSession =
session ??
@ -105,19 +151,107 @@ export const TaskTool = Tool.define(
modelID: msg.info.modelID,
providerID: msg.info.providerID,
}
const parentModel = {
modelID: msg.info.modelID,
providerID: msg.info.providerID,
}
const background = params.background === true
const metadata = {
sessionId: nextSession.id,
model,
...(background ? { background: true } : {}),
}
yield* ctx.metadata({
title: params.description,
metadata: {
sessionId: nextSession.id,
model,
},
metadata,
})
const ops = ctx.extra?.promptOps as TaskPromptOps
if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
const messageID = MessageID.ascending()
const runTask = Effect.fn("TaskTool.runTask")(function* () {
const parts = yield* ops.resolvePromptParts(params.prompt)
const result = yield* ops.prompt({
messageID: MessageID.ascending(),
sessionID: nextSession.id,
model: {
modelID: model.modelID,
providerID: model.providerID,
},
agent: next.name,
tools: {
...(canTodo ? {} : { todowrite: false }),
...(canTask ? {} : { task: false }),
...Object.fromEntries(primaryTools.map((item) => [item, false])),
},
parts,
})
return result.parts.findLast((item) => item.type === "text")?.text ?? ""
})
const continueIfIdle = Effect.fn("TaskTool.continueIfIdle")(function* (input: {
userID: MessageID
state: "completed" | "error"
}) {
if ((yield* status.get(ctx.sessionID)).type !== "idle") return
const latest = yield* sessions.findMessage(ctx.sessionID, (item) => item.info.role === "user")
if (Option.isNone(latest)) return
if (latest.value.info.id !== input.userID) return
yield* bus.publish(TuiEvent.ToastShow, {
title: input.state === "completed" ? "Background task complete" : "Background task failed",
message:
input.state === "completed"
? `Background task \"${params.description}\" finished. Resuming the main thread.`
: `Background task \"${params.description}\" failed. Resuming the main thread.`,
variant: input.state === "completed" ? "success" : "error",
duration: 5000,
})
yield* ops.loop({ sessionID: ctx.sessionID }).pipe(Effect.ignore)
})
if (background) {
const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (state: "completed" | "error", text: string) {
const message = yield* ops.prompt({
sessionID: ctx.sessionID,
noReply: true,
model: parentModel,
agent: ctx.agent,
parts: [
{
type: "text",
synthetic: true,
text: backgroundMessage({
sessionID: nextSession.id,
description: params.description,
state,
text,
}),
},
],
})
yield* continueIfIdle({ userID: message.info.id, state })
})
ops.fork(
runTask().pipe(
Effect.matchCauseEffect({
onSuccess: (text) => inject("completed", text),
onFailure: (cause) =>
inject("error", errorText(Cause.squash(cause))).pipe(Effect.catchCause(() => Effect.void)),
}),
Effect.catchCause(() => Effect.void),
Effect.asVoid,
),
)
return {
title: params.description,
metadata,
output: backgroundOutput(nextSession.id),
}
}
function cancel() {
ops.cancel(nextSession.id)
@ -129,36 +263,11 @@ export const TaskTool = Tool.define(
}),
() =>
Effect.gen(function* () {
const parts = yield* ops.resolvePromptParts(params.prompt)
const result = yield* ops.prompt({
messageID,
sessionID: nextSession.id,
model: {
modelID: model.modelID,
providerID: model.providerID,
},
agent: next.name,
tools: {
...(canTodo ? {} : { todowrite: false }),
...(canTask ? {} : { task: false }),
...Object.fromEntries(primaryTools.map((item) => [item, false])),
},
parts,
})
const text = yield* runTask()
return {
title: params.description,
metadata: {
sessionId: nextSession.id,
model,
},
output: [
`task_id: ${nextSession.id} (for resuming to continue this task if needed)`,
"",
"<task_result>",
result.parts.findLast((item) => item.type === "text")?.text ?? "",
"</task_result>",
].join("\n"),
metadata,
output: output(nextSession.id, text),
}
}),
() =>
@ -166,13 +275,12 @@ export const TaskTool = Tool.define(
ctx.abort.removeEventListener("abort", cancel)
}),
)
})
}, Effect.orDie)
return {
description: DESCRIPTION,
parameters: Parameters,
execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
run(params, ctx).pipe(Effect.orDie),
execute: run,
}
}),
)

12
packages/opencode/src/tool/task.txt
View file

@ -14,11 +14,13 @@ When NOT to use the Task tool:
Usage notes:
1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session.
3. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
4. The agent's outputs should generally be trusted
5. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
2. By default, task waits for completion and returns the result immediately, along with a task_id you can reuse later to continue the same subagent session.
3. Set background=true to launch asynchronously. In background mode, continue your current work without waiting.
4. For background runs, use task_status(task_id=..., wait=false) to poll, or wait=true to block until done (optionally with timeout_ms).
5. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
6. The agent's outputs should generally be trusted
7. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
8. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
Example usage (NOTE: The agents below are fictional examples for illustration only - use the actual agents listed above):

152
packages/opencode/src/tool/task_status.ts Normal file
View file

@ -0,0 +1,152 @@
import * as Tool from "./tool"
import DESCRIPTION from "./task_status.txt"
import { Session } from "@/session/session"
import { SessionID } from "../session/schema"
import { MessageV2 } from "../session/message-v2"
import { SessionStatus } from "../session/status"
import { PositiveInt } from "@/util/schema"
import { Effect, Option, Schema } from "effect"
const DEFAULT_TIMEOUT = 60_000
const POLL_MS = 300
const Parameters = Schema.Struct({
task_id: SessionID.annotate({ description: "The task_id returned by the task tool" }),
wait: Schema.optional(Schema.Boolean).annotate({ description: "When true, wait until the task reaches a terminal state or timeout" }),
timeout_ms: Schema.optional(PositiveInt).annotate({
description: "Maximum milliseconds to wait when wait=true (default: 60000)",
}),
})
type State = "running" | "completed" | "error"
type InspectResult = { state: State; text: string }
function format(input: { taskID: SessionID; state: State; text: string }) {
return [`task_id: ${input.taskID}`, `state: ${input.state}`, "", "<task_result>", input.text, "</task_result>"].join(
"\n",
)
}
function errorText(error: NonNullable<MessageV2.Assistant["error"]>) {
const data = Reflect.get(error, "data")
const message = data && typeof data === "object" ? Reflect.get(data, "message") : undefined
if (typeof message === "string" && message) return message
return error.name
}
export const TaskStatusTool = Tool.define(
"task_status",
Effect.gen(function* () {
const sessions = yield* Session.Service
const status = yield* SessionStatus.Service
const inspect: (taskID: SessionID) => Effect.Effect<InspectResult> = Effect.fn("TaskStatusTool.inspect")(function* (
taskID: SessionID,
) {
const current = yield* status.get(taskID)
if (current.type === "busy" || current.type === "retry") {
return {
state: "running" as const,
text: current.type === "retry" ? `Task is retrying: ${current.message}` : "Task is still running.",
}
}
const latestAssistant = yield* sessions.findMessage(taskID, (item) => item.info.role === "assistant")
if (Option.isNone(latestAssistant)) {
return {
state: "running" as const,
text: "Task has started but has not produced output yet.",
}
}
if (latestAssistant.value.info.role !== "assistant") {
return {
state: "running" as const,
text: "Task has started but has not produced output yet.",
}
}
const latestUser = yield* sessions.findMessage(taskID, (item) => item.info.role === "user")
if (
Option.isSome(latestUser) &&
latestUser.value.info.role === "user" &&
latestUser.value.info.id > latestAssistant.value.info.id
) {
return {
state: "running" as const,
text: "Task is starting.",
}
}
const text = latestAssistant.value.parts.findLast((part) => part.type === "text")?.text ?? ""
if (latestAssistant.value.info.error) {
return {
state: "error" as const,
text: text || errorText(latestAssistant.value.info.error),
}
}
const done =
!!latestAssistant.value.info.finish && !["tool-calls", "unknown"].includes(latestAssistant.value.info.finish)
if (done) {
return {
state: "completed" as const,
text,
}
}
return {
state: "running" as const,
text: text || "Task is still running.",
}
})
const waitForTerminal: (
taskID: SessionID,
timeout: number,
) => Effect.Effect<{ result: InspectResult; timedOut: boolean }> = Effect.fn(
"TaskStatusTool.waitForTerminal",
)(function* (taskID: SessionID, timeout: number) {
const result = yield* inspect(taskID)
if (result.state !== "running") return { result, timedOut: false }
if (timeout <= 0) return { result, timedOut: true }
const sleep = Math.min(POLL_MS, timeout)
yield* Effect.sleep(sleep)
return yield* waitForTerminal(taskID, timeout - sleep)
})
const run = Effect.fn(
"TaskStatusTool.execute",
)(function* (params: Schema.Schema.Type<typeof Parameters>, _ctx: Tool.Context) {
yield* sessions.get(params.task_id)
const waited =
params.wait === true
? yield* waitForTerminal(params.task_id, params.timeout_ms ?? DEFAULT_TIMEOUT)
: { result: yield* inspect(params.task_id), timedOut: false }
const outputText = waited.timedOut
? `Timed out after ${params.timeout_ms ?? DEFAULT_TIMEOUT}ms while waiting for task completion.`
: waited.result.text
return {
title: "Task status",
metadata: {
task_id: params.task_id,
state: waited.result.state,
timed_out: waited.timedOut,
},
output: format({
taskID: params.task_id,
state: waited.result.state,
text: outputText,
}),
}
}, Effect.orDie)
return {
description: DESCRIPTION,
parameters: Parameters,
execute: run,
}
}),
)

13
packages/opencode/src/tool/task_status.txt Normal file
View file

@ -0,0 +1,13 @@
Poll the status of a subagent task launched with the task tool.
Use this to check background tasks started with `task(background=true)`.
Parameters:
- `task_id` (required): the task session id returned by the task tool
- `wait` (optional): when true, wait for completion
- `timeout_ms` (optional): max wait duration in milliseconds when `wait=true`
Returns compact, parseable output:
- `task_id`
- `state` (`running`, `completed`, or `error`)
- `<task_result>...</task_result>` containing final output, error summary, or current progress text

5
packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
View file

@ -338,6 +338,10 @@ exports[`tool parameters JSON Schema (wire shape) task 1`] = `
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"background": {
"description": "When true, launch the subagent in the background and return immediately",
"type": "boolean",
},
"command": {
"description": "The command that triggered this task",
"type": "string",
@ -356,6 +360,7 @@ exports[`tool parameters JSON Schema (wire shape) task 1`] = `
},
"task_id": {
"description": "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
"pattern": "^ses.*",
"type": "string",
},
},

14
packages/opencode/test/tool/parameters.test.ts
View file

@ -26,6 +26,7 @@ import { Parameters as Todo } from "../../src/tool/todo"
import { Parameters as WebFetch } from "../../src/tool/webfetch"
import { Parameters as WebSearch } from "../../src/tool/websearch"
import { Parameters as Write } from "../../src/tool/write"
import { SessionID } from "../../src/session/schema"
const parse = <S extends Schema.Decoder<unknown>>(schema: S, input: unknown): S["Type"] =>
Schema.decodeUnknownSync(schema)(input)
@ -220,6 +221,19 @@ describe("tool parameters", () => {
const parsed = parse(Task, { description: "d", prompt: "p", subagent_type: "general" })
expect(parsed.subagent_type).toBe("general")
})
test("accepts optional task_id + command + background", () => {
const parsed = parse(Task, {
description: "d",
prompt: "p",
subagent_type: "general",
task_id: SessionID.make("ses_test"),
command: "/cmd",
background: true,
})
expect(parsed.task_id).toBe(SessionID.make("ses_test"))
expect(parsed.command).toBe("/cmd")
expect(parsed.background).toBe(true)
})
test("rejects missing prompt", () => {
expect(accepts(Task, { description: "d", subagent_type: "general" })).toBe(false)
})

179
packages/opencode/test/tool/task.test.ts
View file

@ -1,13 +1,15 @@
import { afterEach, describe, expect } from "bun:test"
import { Effect, Layer } from "effect"
import { Agent } from "../../src/agent/agent"
import { Bus } from "../../src/bus"
import { Config } from "@/config/config"
import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
import { Instance } from "../../src/project/instance"
import { Session } from "@/session/session"
import { MessageV2 } from "../../src/session/message-v2"
import type { SessionPrompt } from "../../src/session/prompt"
import { MessageID, PartID } from "../../src/session/schema"
import { MessageID, PartID, SessionID } from "../../src/session/schema"
import { SessionStatus } from "../../src/session/status"
import { ModelID, ProviderID } from "../../src/provider/schema"
import { TaskTool, type TaskPromptOps } from "../../src/tool/task"
import { Truncate } from "@/tool/truncate"
@ -27,9 +29,11 @@ const ref = {
const it = testEffect(
Layer.mergeAll(
Agent.defaultLayer,
Bus.defaultLayer,
Config.defaultLayer,
CrossSpawnSpawner.defaultLayer,
Session.defaultLayer,
SessionStatus.defaultLayer,
Truncate.defaultLayer,
ToolRegistry.defaultLayer,
),
@ -64,15 +68,59 @@ const seed = Effect.fn("TaskToolTest.seed")(function* (title = "Pinned") {
return { chat, assistant }
})
function stubOps(opts?: { onPrompt?: (input: SessionPrompt.PromptInput) => void; text?: string }): TaskPromptOps {
function stubOps(session: Session.Interface, opts?: { onPrompt?: (input: SessionPrompt.PromptInput) => void; text?: string }): TaskPromptOps {
return {
cancel() {},
resolvePromptParts: (template) => Effect.succeed([{ type: "text" as const, text: template }]),
prompt: (input) =>
Effect.sync(() => {
Effect.gen(function* () {
opts?.onPrompt?.(input)
return reply(input, opts?.text ?? "done")
const userID = input.messageID ?? MessageID.ascending()
const user: MessageV2.User = {
id: userID,
role: "user",
sessionID: input.sessionID,
agent: input.agent ?? "build",
model: input.model ?? ref,
tools: input.tools,
time: { created: Date.now() },
}
yield* session.updateMessage(user)
const parts = input.parts.map((part) => ({
...part,
id: part.id ?? PartID.ascending(),
messageID: user.id,
sessionID: input.sessionID,
}))
yield* Effect.forEach(parts, (part) => session.updatePart(part), { discard: true })
if (input.noReply) {
return {
info: user,
parts,
}
}
const result = reply({ ...input, messageID: user.id }, opts?.text ?? "done")
yield* session.updateMessage(result.info)
yield* Effect.forEach(result.parts, (part) => session.updatePart(part), { discard: true })
return result
}),
loop: (input) =>
Effect.sync(() =>
reply(
{
sessionID: input.sessionID,
messageID: MessageID.ascending(),
agent: "build",
model: ref,
parts: [],
},
opts?.text ?? "done",
),
),
fork() {},
}
}
@ -195,7 +243,7 @@ describe("tool.task", () => {
const tool = yield* TaskTool
const def = yield* tool.init()
let seen: SessionPrompt.PromptInput | undefined
const promptOps = stubOps({ text: "resumed", onPrompt: (input) => (seen = input) })
const promptOps = stubOps(sessions, { text: "resumed", onPrompt: (input) => (seen = input) })
const result = yield* def.execute(
{
@ -229,11 +277,12 @@ describe("tool.task", () => {
it.live("execute asks by default and skips checks when bypassed", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const { chat, assistant } = yield* seed()
const tool = yield* TaskTool
const def = yield* tool.init()
const calls: unknown[] = []
const promptOps = stubOps()
const promptOps = stubOps(sessions)
const exec = (extra?: Record<string, any>) =>
def.execute(
@ -282,14 +331,14 @@ describe("tool.task", () => {
const tool = yield* TaskTool
const def = yield* tool.init()
let seen: SessionPrompt.PromptInput | undefined
const promptOps = stubOps({ text: "created", onPrompt: (input) => (seen = input) })
const promptOps = stubOps(sessions, { text: "created", onPrompt: (input) => (seen = input) })
const result = yield* def.execute(
{
description: "inspect bug",
prompt: "look into the cache key path",
subagent_type: "general",
task_id: "ses_missing",
task_id: SessionID.make("ses_missing"),
},
{
sessionID: chat.id,
@ -322,7 +371,7 @@ describe("tool.task", () => {
const tool = yield* TaskTool
const def = yield* tool.init()
let seen: SessionPrompt.PromptInput | undefined
const promptOps = stubOps({ onPrompt: (input) => (seen = input) })
const promptOps = stubOps(sessions, { onPrompt: (input) => (seen = input) })
const result = yield* def.execute(
{
@ -384,4 +433,116 @@ describe("tool.task", () => {
},
),
)
it.live("execute launches background tasks without waiting for completion", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const { chat, assistant } = yield* seed()
const tool = yield* TaskTool
const def = yield* tool.init()
const forks: Effect.Effect<void, never, never>[] = []
const result = yield* def.execute(
{
description: "inspect bug",
prompt: "look into the cache key path",
subagent_type: "general",
background: true,
},
{
sessionID: chat.id,
messageID: assistant.id,
agent: "build",
abort: new AbortController().signal,
extra: {
promptOps: {
...stubOps(sessions),
fork(effect) {
forks.push(effect)
},
} satisfies TaskPromptOps,
},
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.metadata.sessionId).toBeDefined()
expect(result.metadata.background).toBe(true)
expect(result.output).toContain(`task_id: ${result.metadata.sessionId}`)
expect(result.output).toContain("state: running")
expect(forks).toHaveLength(1)
}),
),
)
it.live("background tasks inject completion into the parent session and resume when idle", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const { chat, assistant } = yield* seed()
const tool = yield* TaskTool
const def = yield* tool.init()
const forks: Effect.Effect<void, never, never>[] = []
const loops: string[] = []
const result = yield* def.execute(
{
description: "inspect bug",
prompt: "look into the cache key path",
subagent_type: "general",
background: true,
},
{
sessionID: chat.id,
messageID: assistant.id,
agent: "build",
abort: new AbortController().signal,
extra: {
promptOps: {
...stubOps(sessions, { text: "background done" }),
loop(input) {
loops.push(input.sessionID)
return Effect.sync(() =>
reply(
{
sessionID: input.sessionID,
messageID: MessageID.ascending(),
agent: "build",
model: ref,
parts: [],
},
"looped",
),
)
},
fork(effect) {
forks.push(effect)
},
} satisfies TaskPromptOps,
},
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
yield* forks[0]!
const parent = yield* sessions.findMessage(chat.id, (msg) => msg.info.role === "user")
expect(parent._tag).toBe("Some")
if (parent._tag !== "Some") return
expect(parent.value.parts.find((part) => part.type === "text")?.text).toContain("Background task completed")
expect(parent.value.parts.find((part) => part.type === "text")?.text).toContain("background done")
expect(loops).toEqual([chat.id])
const child = yield* sessions.findMessage(result.metadata.sessionId, (msg) => msg.info.role === "assistant")
expect(child._tag).toBe("Some")
if (child._tag !== "Some") return
expect(child.value.parts.find((part) => part.type === "text")?.text).toBe("background done")
}),
),
)
})

278
packages/opencode/test/tool/task_status.test.ts Normal file
View file

@ -0,0 +1,278 @@
import { afterEach, describe, expect } from "bun:test"
import { Effect, Layer, Scope } from "effect"
import { Agent } from "../../src/agent/agent"
import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
import { Instance } from "../../src/project/instance"
import { Session } from "@/session/session"
import { MessageV2 } from "../../src/session/message-v2"
import { MessageID, PartID } from "../../src/session/schema"
import { SessionStatus } from "../../src/session/status"
import { TaskStatusTool } from "../../src/tool/task_status"
import { Truncate } from "@/tool/truncate"
import { ModelID, ProviderID } from "../../src/provider/schema"
import { provideTmpdirInstance } from "../fixture/fixture"
import { testEffect } from "../lib/effect"
afterEach(async () => {
await Instance.disposeAll()
})
const ref = {
providerID: ProviderID.make("test"),
modelID: ModelID.make("test-model"),
}
const it = testEffect(
Layer.mergeAll(
Agent.defaultLayer,
CrossSpawnSpawner.defaultLayer,
Session.defaultLayer,
SessionStatus.defaultLayer,
Truncate.defaultLayer,
),
)
const seedUser = Effect.fn("TaskStatusToolTest.seedUser")(function* (sessionID: Session.Info["id"]) {
const session = yield* Session.Service
return yield* session.updateMessage({
id: MessageID.ascending(),
role: "user",
sessionID,
agent: "build",
model: ref,
time: { created: Date.now() },
})
})
const seedAssistant = Effect.fn("TaskStatusToolTest.seedAssistant")(function* (input: {
sessionID: Session.Info["id"]
text: string
error?: string
}) {
const session = yield* Session.Service
const user = yield* seedUser(input.sessionID)
const message = yield* session.updateMessage({
id: MessageID.ascending(),
role: "assistant",
parentID: user.id,
sessionID: input.sessionID,
mode: "build",
agent: "build",
cost: 0,
path: { cwd: "/tmp", root: "/tmp" },
tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
modelID: ref.modelID,
providerID: ref.providerID,
time: { created: Date.now(), completed: Date.now() },
finish: "stop",
...(input.error
? {
error: new MessageV2.APIError({
message: input.error,
isRetryable: false,
}).toObject(),
}
: {}),
})
yield* session.updatePart({
id: PartID.ascending(),
messageID: message.id,
sessionID: input.sessionID,
type: "text",
text: input.text,
})
})
describe("tool.task_status", () => {
it.live("returns running while session status is busy", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const status = yield* SessionStatus.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
yield* status.set(chat.id, { type: "busy" })
const result = yield* def.execute(
{ task_id: chat.id },
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("state: running")
}),
),
)
it.live("returns completed with final task output", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
yield* seedAssistant({ sessionID: chat.id, text: "all done" })
const result = yield* def.execute(
{ task_id: chat.id },
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("state: completed")
expect(result.output).toContain("all done")
}),
),
)
it.live("wait=true blocks until terminal status", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const status = yield* SessionStatus.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
const scope = yield* Scope.Scope
yield* status.set(chat.id, { type: "busy" })
yield* Effect.gen(function* () {
yield* Effect.sleep("150 millis")
yield* status.set(chat.id, { type: "idle" })
yield* seedAssistant({ sessionID: chat.id, text: "finished later" })
}).pipe(Effect.forkIn(scope))
const result = yield* def.execute(
{
task_id: chat.id,
wait: true,
timeout_ms: 4_000,
},
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("state: completed")
expect(result.output).toContain("finished later")
}),
),
)
it.live("returns error when child run fails", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
yield* seedAssistant({ sessionID: chat.id, text: "", error: "child failed" })
const result = yield* def.execute(
{ task_id: chat.id },
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("state: error")
expect(result.output).toContain("child failed")
expect(result.metadata.state).toBe("error")
}),
),
)
it.live("wait=true times out with timed_out metadata", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const status = yield* SessionStatus.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
yield* status.set(chat.id, { type: "busy" })
const result = yield* def.execute(
{
task_id: chat.id,
wait: true,
timeout_ms: 80,
},
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("Timed out after 80ms")
expect(result.metadata.timed_out).toBe(true)
expect(result.metadata.state).toBe("running")
}),
),
)
it.live("returns running for resumed task with a newer user turn", () =>
provideTmpdirInstance(() =>
Effect.gen(function* () {
const sessions = yield* Session.Service
const tool = yield* TaskStatusTool
const def = yield* tool.init()
const chat = yield* sessions.create({})
yield* seedAssistant({ sessionID: chat.id, text: "old done" })
yield* seedUser(chat.id)
const result = yield* def.execute(
{ task_id: chat.id },
{
sessionID: chat.id,
messageID: MessageID.ascending(),
agent: "build",
abort: new AbortController().signal,
messages: [],
metadata: () => Effect.void,
ask: () => Effect.void,
},
)
expect(result.output).toContain("state: running")
expect(result.output).toContain("Task is starting.")
}),
),
)
})

8
packages/ui/src/components/message-part.tsx
View file

@ -1756,9 +1756,11 @@ ToolRegistry.register({
const title = createMemo(() => agent().name ?? i18n.t("ui.tool.agent.default"))
const tone = createMemo(() => agent().color)
const subtitle = createMemo(() => {
const value = props.input.description
if (typeof value === "string" && value) return value
return childSessionId()
const value =
typeof props.input.description === "string" && props.input.description ? props.input.description : childSessionId()
if (!value) return value
if (props.metadata.background === true) return `${value} (background)`
return value
})
const running = createMemo(() => props.status === "pending" || props.status === "running")