From b00b8238f427fad16c0deefc1554b842680d9ed8 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Sun, 14 Dec 2025 01:22:28 +0900
Subject: [PATCH] fix(background-task): gracefully handle agent not found
 errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When an invalid or unregistered agent is passed to background_task or
call_omo_agent, OpenCode crashes with "TypeError: undefined is not an
object (evaluating 'agent.name')". This fix:

- Validates agent parameter is not empty before launching
- Catches prompt errors and returns friendly error message
- Notifies parent session when background task fails
- Improves error message to guide user on resolution

Fixes #37

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
---
 src/features/background-agent/manager.ts | 15 ++++++++++--
 src/tools/background-task/tools.ts       |  8 +++++--
 src/tools/call-omo-agent/tools.ts        | 29 ++++++++++++++++--------
 3 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/src/features/background-agent/manager.ts b/src/features/background-agent/manager.ts
index bec6cd1..32563cf 100644
--- a/src/features/background-agent/manager.ts
+++ b/src/features/background-agent/manager.ts
@@ -39,6 +39,10 @@ export class BackgroundManager {
   }
 
   async launch(input: LaunchInput): Promise<BackgroundTask> {
+    if (!input.agent || input.agent.trim() === "") {
+      throw new Error("Agent parameter is required")
+    }
+
     const createResult = await this.client.session.create({
       body: {
         parentID: input.parentSessionID,
@@ -71,7 +75,7 @@ export class BackgroundManager {
     this.tasks.set(task.id, task)
     this.startPolling()
 
-    log("[background-agent] Launching task:", { taskId: task.id, sessionID })
+    log("[background-agent] Launching task:", { taskId: task.id, sessionID, agent: input.agent })
 
     this.client.session.promptAsync({
       path: { id: sessionID },
@@ -90,8 +94,15 @@ export class BackgroundManager {
       const existingTask = this.findBySession(sessionID)
       if (existingTask) {
         existingTask.status = "error"
-        existingTask.error = String(error)
+        const errorMessage = error instanceof Error ? error.message : String(error)
+        if (errorMessage.includes("agent.name") || errorMessage.includes("undefined")) {
+          existingTask.error = `Agent "${input.agent}" not found. Make sure the agent is registered in your opencode.json or provided by a plugin.`
+        } else {
+          existingTask.error = errorMessage
+        }
         existingTask.completedAt = new Date()
+        this.markForNotification(existingTask)
+        this.notifyParentSession(existingTask)
       }
     })
 
diff --git a/src/tools/background-task/tools.ts b/src/tools/background-task/tools.ts
index d9d45a1..57236ff 100644
--- a/src/tools/background-task/tools.ts
+++ b/src/tools/background-task/tools.ts
@@ -26,14 +26,18 @@ export function createBackgroundTask(manager: BackgroundManager) {
     args: {
       description: tool.schema.string().describe("Short task description (shown in status)"),
       prompt: tool.schema.string().describe("Full detailed prompt for the agent"),
-      agent: tool.schema.string().describe("Agent type to use (any agent allowed)"),
+      agent: tool.schema.string().describe("Agent type to use (any registered agent)"),
     },
     async execute(args: BackgroundTaskArgs, toolContext) {
+      if (!args.agent || args.agent.trim() === "") {
+        return `❌ Agent parameter is required. Please specify which agent to use (e.g., "explore", "librarian", "build", etc.)`
+      }
+
       try {
         const task = await manager.launch({
           description: args.description,
           prompt: args.prompt,
-          agent: args.agent,
+          agent: args.agent.trim(),
           parentSessionID: toolContext.sessionID,
           parentMessageID: toolContext.messageID,
         })
diff --git a/src/tools/call-omo-agent/tools.ts b/src/tools/call-omo-agent/tools.ts
index 2284bf1..e423fb6 100644
--- a/src/tools/call-omo-agent/tools.ts
+++ b/src/tools/call-omo-agent/tools.ts
@@ -114,17 +114,26 @@ async function executeSync(
   log(`[call_omo_agent] Sending prompt to session ${sessionID}`)
   log(`[call_omo_agent] Prompt text:`, args.prompt.substring(0, 100))
 
-  await ctx.client.session.prompt({
-    path: { id: sessionID },
-    body: {
-      agent: args.subagent_type,
-      tools: {
-        task: false,
-        call_omo_agent: false,
+  try {
+    await ctx.client.session.prompt({
+      path: { id: sessionID },
+      body: {
+        agent: args.subagent_type,
+        tools: {
+          task: false,
+          call_omo_agent: false,
+        },
+        parts: [{ type: "text", text: args.prompt }],
       },
-      parts: [{ type: "text", text: args.prompt }],
-    },
-  })
+    })
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    log(`[call_omo_agent] Prompt error:`, errorMessage)
+    if (errorMessage.includes("agent.name") || errorMessage.includes("undefined")) {
+      return `Error: Agent "${args.subagent_type}" not found. Make sure the agent is registered in your opencode.json or provided by a plugin.\n\n<task_metadata>\nsession_id: ${sessionID}\n</task_metadata>`
+    }
+    return `Error: Failed to send prompt: ${errorMessage}\n\n<task_metadata>\nsession_id: ${sessionID}\n</task_metadata>`
+  }
 
   log(`[call_omo_agent] Prompt sent, fetching messages...`)