Merge agent and mode into one (sst#1689)

The concept of mode has been deprecated, there is now only the agent field in the config.

An agent can be cycled through as your primary agent with <tab> or you can spawn a subagent by @ mentioning it. if you include a description of when to use it, the primary agent will try to automatically use it

Full docs here: https://opencode.ai/docs/agents/

Author: thdxr

.opencode/agent/docs.md

@@ -0,0 +1,12 @@
+---
+description: You MUST use this agent when writing documentation
+---
+
+You are an expert technical documentation writer
+
+You are not verbose
+
+Every chunk of text should be followed by an example or something besides text
+to look at.
+
+Chunks of text should not be more than 2 sentences long.

.opencode/agent/example-driven-docs-writer.md

@@ -38,6 +38,13 @@
     "@openauthjs/openauth": "0.4.3",
     "@opencode-ai/plugin": "workspace:*",
     "@opencode-ai/sdk": "workspace:*",
+    "@opentelemetry/auto-instrumentations-node": "0.62.0",
+    "@opentelemetry/exporter-jaeger": "2.0.1",
+    "@opentelemetry/exporter-otlp-http": "0.26.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.203.0",
+    "@opentelemetry/instrumentation-fetch": "0.203.0",
+    "@opentelemetry/sdk-node": "0.203.0",
+    "@opentelemetry/sdk-trace-node": "2.0.1",
     "@standard-schema/spec": "1.0.0",
     "@zip.js/zip.js": "2.7.62",
     "ai": "catalog:",

bun.lock

@@ -10,20 +10,24 @@ export namespace Agent {
   export const Info = z
     .object({
       name: z.string(),
+      description: z.string().optional(),
+      mode: z.union([z.literal("subagent"), z.literal("primary"), z.literal("all")]),
+      topP: z.number().optional(),
+      temperature: z.number().optional(),
       model: z
         .object({
           modelID: z.string(),
           providerID: z.string(),
         })
         .optional(),
-      description: z.string(),
       prompt: z.string().optional(),
       tools: z.record(z.boolean()),
     })
     .openapi({
       ref: "Agent",
     })
   export type Info = z.infer<typeof Info>
+
   const state = App.state("agent", async () => {
     const cfg = await Config.get()
     const result: Record<string, Info> = {
@@ -35,6 +39,21 @@ export namespace Agent {
           todoread: false,
           todowrite: false,
         },
+        mode: "subagent",
+      },
+      build: {
+        name: "build",
+        tools: {},
+        mode: "primary",
+      },
+      plan: {
+        name: "plan",
+        tools: {
+          write: false,
+          edit: false,
+          patch: false,
+        },
+        mode: "primary",
       },
     }
     for (const [key, value] of Object.entries(cfg.agent ?? {})) {
@@ -46,21 +65,20 @@ export namespace Agent {
       if (!item)
         item = result[key] = {
           name: key,
-          description: "",
-          tools: {
-            todowrite: false,
-            todoread: false,
-          },
+          mode: "all",
+          tools: {},
         }
-      const model = value.model ?? cfg.model
-      if (model) item.model = Provider.parseModel(model)
+      if (value.model) item.model = Provider.parseModel(value.model)
       if (value.prompt) item.prompt = value.prompt
       if (value.tools)
         item.tools = {
           ...item.tools,
           ...value.tools,
         }
       if (value.description) item.description = value.description
+      if (value.temperature != undefined) item.temperature = value.temperature
+      if (value.top_p != undefined) item.topP = value.top_p
+      if (value.mode) item.mode = value.mode
     }
     return result
   })

packages/opencode/package.json

@@ -641,7 +641,7 @@ export const GithubRunCommand = cmd({
           messageID: Identifier.ascending("message"),
           providerID,
           modelID,
-          mode: "build",
+          agent: "build",
           parts: [
             {
               id: Identifier.ascending("part"),

packages/opencode/src/agent/agent.ts

@@ -8,8 +8,8 @@ import { Flag } from "../../flag/flag"
 import { Config } from "../../config/config"
 import { bootstrap } from "../bootstrap"
 import { MessageV2 } from "../../session/message-v2"
-import { Mode } from "../../session/mode"
 import { Identifier } from "../../id/id"
+import { Agent } from "../../agent/agent"
 
 const TOOL: Record<string, [string, string]> = {
   todowrite: ["Todo", UI.Style.TEXT_WARNING_BOLD],
@@ -54,9 +54,9 @@ export const RunCommand = cmd({
         alias: ["m"],
         describe: "model to use in the format of provider/model",
       })
-      .option("mode", {
+      .option("agent", {
         type: "string",
-        describe: "mode to use",
+        describe: "agent to use",
       })
   },
   handler: async (args) => {
@@ -103,8 +103,19 @@ export const RunCommand = cmd({
       }
       UI.empty()
 
-      const mode = args.mode ? await Mode.get(args.mode) : await Mode.list().then((x) => x[0])
-      const { providerID, modelID } = args.model ? Provider.parseModel(args.model) : mode.model ?? await Provider.defaultModel()
+      const agent = await (async () => {
+        if (args.agent) return Agent.get(args.agent)
+        const build = Agent.get("build")
+        if (build) return build
+        return Agent.list().then((x) => x[0])
+      })()
+
+      const { providerID, modelID } = await (() => {
+        if (args.model) return Provider.parseModel(args.model)
+        if (agent.model) return agent.model
+        return Provider.defaultModel()
+      })()
+
       UI.println(UI.Style.TEXT_NORMAL_BOLD + "@ ", UI.Style.TEXT_NORMAL + `${providerID}/${modelID}`)
       UI.empty()
 
@@ -157,14 +168,17 @@ export const RunCommand = cmd({
         UI.error(err)
       })
 
-
       const messageID = Identifier.ascending("message")
       const result = await Session.chat({
         sessionID: session.id,
         messageID,
-        providerID,
-        modelID,
-        mode: mode.name,
+        ...(agent.model
+          ? agent.model
+          : {
+              providerID,
+              modelID,
+            }),
+        agent: agent.name,
         parts: [
           {
             id: Identifier.ascending("part"),

packages/opencode/src/cli/cmd/github.ts

@@ -11,8 +11,8 @@ import { Config } from "../../config/config"
 import { Bus } from "../../bus"
 import { Log } from "../../util/log"
 import { FileWatcher } from "../../file/watch"
-import { Mode } from "../../session/mode"
 import { Ide } from "../../ide"
+import { Agent } from "../../agent/agent"
 
 declare global {
   const OPENCODE_TUI_PATH: string
@@ -115,7 +115,7 @@ export const TuiCommand = cmd({
             CGO_ENABLED: "0",
             OPENCODE_SERVER: server.url.toString(),
             OPENCODE_APP_INFO: JSON.stringify(app),
-            OPENCODE_MODES: JSON.stringify(await Mode.list()),
+            OPENCODE_AGENTS: JSON.stringify(await Agent.list()),
           },
           onExit: () => {
             server.stop()

packages/opencode/src/cli/cmd/run.ts

@@ -83,7 +83,7 @@ export namespace Config {
         ...md.data,
         prompt: md.content.trim(),
       }
-      const parsed = Mode.safeParse(config)
+      const parsed = Agent.safeParse(config)
       if (parsed.success) {
         result.mode = mergeDeep(result.mode, {
           [config.name]: parsed.data,
@@ -92,6 +92,15 @@ export namespace Config {
       }
       throw new InvalidError({ path: item }, { cause: parsed.error })
     }
+    // Migrate deprecated mode field to agent field
+    for (const [name, mode] of Object.entries(result.mode)) {
+      result.agent = mergeDeep(result.agent ?? {}, {
+        [name]: {
+          ...mode,
+          mode: "primary" as const,
+        },
+      })
+    }
 
     result.plugin = result.plugin || []
     result.plugin.push(
@@ -108,6 +117,12 @@ export namespace Config {
     if (result.keybinds?.messages_revert && !result.keybinds.messages_undo) {
       result.keybinds.messages_undo = result.keybinds.messages_revert
     }
+    if (result.keybinds?.switch_mode && !result.keybinds.switch_agent) {
+      result.keybinds.switch_agent = result.keybinds.switch_mode
+    }
+    if (result.keybinds?.switch_mode_reverse && !result.keybinds.switch_agent_reverse) {
+      result.keybinds.switch_agent_reverse = result.keybinds.switch_mode_reverse
+    }
 
     if (!result.username) {
       const os = await import("os")
@@ -149,32 +164,34 @@ export namespace Config {
   export const Mcp = z.discriminatedUnion("type", [McpLocal, McpRemote])
   export type Mcp = z.infer<typeof Mcp>
 
-  export const Mode = z
+  export const Agent = z
     .object({
       model: z.string().optional(),
       temperature: z.number().optional(),
       top_p: z.number().optional(),
       prompt: z.string().optional(),
       tools: z.record(z.string(), z.boolean()).optional(),
       disable: z.boolean().optional(),
+      description: z.string().optional().describe("Description of when to use the agent"),
+      mode: z.union([z.literal("subagent"), z.literal("primary"), z.literal("all")]).optional(),
     })
     .openapi({
-      ref: "ModeConfig",
+      ref: "AgentConfig",
     })
-  export type Mode = z.infer<typeof Mode>
-
-  export const Agent = Mode.extend({
-    description: z.string(),
-  }).openapi({
-    ref: "AgentConfig",
-  })
+  export type Agent = z.infer<typeof Agent>
 
   export const Keybinds = z
     .object({
       leader: z.string().optional().default("ctrl+x").describe("Leader key for keybind combinations"),
       app_help: z.string().optional().default("<leader>h").describe("Show help dialog"),
-      switch_mode: z.string().optional().default("tab").describe("Next mode"),
-      switch_mode_reverse: z.string().optional().default("shift+tab").describe("Previous Mode"),
+      switch_mode: z.string().optional().default("none").describe("@deprecated use switch_agent. Next mode"),
+      switch_mode_reverse: z
+        .string()
+        .optional()
+        .default("none")
+        .describe("@deprecated use switch_agent_reverse. Previous mode"),
+      switch_agent: z.string().optional().default("tab").describe("Next agent"),
+      switch_agent_reverse: z.string().optional().default("shift+tab").describe("Previous agent"),
       editor_open: z.string().optional().default("<leader>e").describe("Open external editor"),
       session_export: z.string().optional().default("<leader>x").describe("Export session to editor"),
       session_new: z.string().optional().default("<leader>n").describe("Create a new session"),
@@ -257,19 +274,21 @@ export namespace Config {
         .describe("Custom username to display in conversations instead of system username"),
       mode: z
         .object({
-          build: Mode.optional(),
-          plan: Mode.optional(),
+          build: Agent.optional(),
+          plan: Agent.optional(),
         })
-        .catchall(Mode)
+        .catchall(Agent)
         .optional()
-        .describe("Modes configuration, see https://opencode.ai/docs/modes"),
+        .describe("@deprecated Use `agent` field instead."),
       agent: z
         .object({
+          plan: Agent.optional(),
+          build: Agent.optional(),
           general: Agent.optional(),
         })
         .catchall(Agent)
         .optional()
-        .describe("Modes configuration, see https://opencode.ai/docs/modes"),
+        .describe("Agent configuration, see https://opencode.ai/docs/agent"),
       provider: z
         .record(
           ModelsDev.Provider.partial()

packages/opencode/src/cli/cmd/tui.ts

@@ -1,4 +1,6 @@
 import "zod-openapi/extend"
+import { Trace } from "./trace"
+Trace.init()
 import yargs from "yargs"
 import { hideBin } from "yargs/helpers"
 import { RunCommand } from "./cli/cmd/run"
@@ -18,9 +20,6 @@ import { DebugCommand } from "./cli/cmd/debug"
 import { StatsCommand } from "./cli/cmd/stats"
 import { McpCommand } from "./cli/cmd/mcp"
 import { GithubCommand } from "./cli/cmd/github"
-import { Trace } from "./trace"
-
-Trace.init()
 
 const cancel = new AbortController()