feat(server): /exec endpoint for AI callback from scripts via child session

Scripts can delegate decisions to the LLM by POSTing a prompt. A fresh child
session is created for each call so token context never accumulates. Supports
structured JSON output, file attachments, model override, custom system prompt,
and live streaming. The parent session inherits the last-used model by default.

Author: micuintus

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

@@ -1503,10 +1503,13 @@ function ToolPart(props: { last: boolean; part: ToolPart; message: AssistantMess
   const ctx = use()
   const sync = useSync()
 
-  // Hide tool if showDetails is false and tool completed successfully
+  // Hide tool if showDetails is false and tool completed successfully.
+  // Task and status parts are always visible — they show subagent summaries
+  // and display-only messages that the user expects to see.
   const shouldHide = createMemo(() => {
     if (ctx.showDetails()) return false
     if (props.part.state.status !== "completed") return false
+    if (props.part.tool === "task" || props.part.tool === "status") return false
     return true
   })
 

packages/opencode/src/server/routes/session.ts

@@ -27,32 +27,28 @@ import { ToolRegistry } from "../../tool/registry"
 
 const log = Log.create({ service: "server" })
 
-/** Walk parent session messages backwards to find the model used in the last user message. */
-async function resolveModel(sessionID: SessionID) {
-  const msgs = await Session.messages({ sessionID })
-  for (let i = msgs.length - 1; i >= 0; i--) {
-    const info = msgs[i].info
-    if (info.role === "user" && info.model) return info.model
-  }
-}
-
 /** Create an emitter for external ToolPart updates (no-op when messageID is absent). */
 function emitter(opts: { sessionID: SessionID; messageID?: string; tool: string }) {
   const mid = opts.messageID ? MessageID.make(opts.messageID) : undefined
   const pid = mid ? PartID.ascending() : undefined
-  const fn = (state: z.infer<typeof MessageV2.ToolState>) =>
-    mid && pid
-      ? Session.updatePart({
-          id: pid,
-          messageID: mid,
-          sessionID: opts.sessionID,
-          type: "tool" as const,
-          tool: opts.tool,
-          callID: pid,
-          external: true,
-          state,
-        })
-      : undefined
+  const fn = (state: z.infer<typeof MessageV2.ToolState>): Promise<void> => {
+    if (!(mid && pid)) return Promise.resolve()
+    return Session.updatePart({
+      id: pid,
+      messageID: mid,
+      sessionID: opts.sessionID,
+      type: "tool" as const,
+      tool: opts.tool,
+      callID: pid,
+      external: true,
+      state,
+    }).then(
+      () => {},
+      (err) => {
+        log.warn("external part update failed", { tool: opts.tool, error: err })
+      },
+    )
+  }
   return { mid, pid, fn }
 }
 
@@ -1126,15 +1122,14 @@ export const SessionRoutes = lazy(() =>
           abort: c.req.raw.signal,
           messages: [] as MessageV2.WithParts[],
           metadata(val: { title?: string; metadata?: Record<string, unknown> }) {
-            emit
-              .fn({
-                status: "running",
-                input: body.args,
-                title: val.title,
-                metadata: val.metadata,
-                time: { start: t0 },
-              })
-              ?.catch(() => {})
+            // fire-and-forget — emitter already logs on rejection
+            void emit.fn({
+              status: "running",
+              input: body.args,
+              title: val.title,
+              metadata: val.metadata,
+              time: { start: t0 },
+            })
           },
           async ask(req: Omit<Permission.Request, "id" | "sessionID" | "tool">) {
             await Permission.ask({
@@ -1304,17 +1299,18 @@ export const SessionRoutes = lazy(() =>
           const timer = setInterval(() => stream.write("\x00OC_KEEPALIVE\x00").catch(() => {}), 15_000)
 
           try {
+            const parts: Parameters<typeof SessionPrompt.prompt>[0]["parts"] = [
+              { type: "text", text: body.prompt },
+              ...(body.files ?? []).map((f) => ({
+                type: "file" as const,
+                mime: f.mime,
+                url: f.url,
+                filename: f.filename,
+              })),
+            ]
             const msg = await SessionPrompt.prompt({
               sessionID: child.id,
-              parts: [
-                { type: "text", text: body.prompt },
-                ...(body.files ?? []).map((f) => ({
-                  type: "file" as const,
-                  mime: f.mime,
-                  url: f.url,
-                  filename: f.filename,
-                })),
-              ],
+              parts,
               system: body.system,
               agent: body.agent,
               model,
@@ -1351,54 +1347,5 @@ export const SessionRoutes = lazy(() =>
           }
         })
       },
-    )
-    // Todo CRUD — create and bulk update
-    .post(
-      "/:sessionID/todo",
-      describeRoute({
-        summary: "Create session todo",
-        operationId: "session.todo.create",
-        responses: {
-          200: {
-            description: "Updated todo list",
-            content: { "application/json": { schema: resolver(Todo.Info.array()) } },
-          },
-          ...errors(400, 404),
-        },
-      }),
-      validator("param", z.object({ sessionID: SessionID.zod })),
-      validator("json", Todo.Info),
-      async (c) => {
-        const sessionID = c.req.valid("param").sessionID
-        await Session.get(sessionID)
-        const todo = c.req.valid("json")
-        const existing = await Todo.get(sessionID)
-        const todos = [...existing, todo]
-        await Todo.update({ sessionID, todos })
-        return c.json(todos)
-      },
-    )
-    .put(
-      "/:sessionID/todo",
-      describeRoute({
-        summary: "Update session todos",
-        operationId: "session.todo.update",
-        responses: {
-          200: {
-            description: "Updated todo list",
-            content: { "application/json": { schema: resolver(Todo.Info.array()) } },
-          },
-          ...errors(400, 404),
-        },
-      }),
-      validator("param", z.object({ sessionID: SessionID.zod })),
-      validator("json", z.object({ todos: Todo.Info.array() })),
-      async (c) => {
-        const sessionID = c.req.valid("param").sessionID
-        await Session.get(sessionID)
-        const body = c.req.valid("json")
-        await Todo.update({ sessionID, todos: body.todos })
-        return c.json(body.todos)
-      },
     ),
 )

packages/opencode/test/cli/tui/tool-part-visibility.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "bun:test"
+import { readFileSync } from "fs"
+import { resolve } from "path"
+
+const src = readFileSync(resolve(import.meta.dir, "../../../src/cli/cmd/tui/routes/session/index.tsx"), "utf-8")
+
+describe("ToolPart shouldHide visibility logic", () => {
+  // Regression: shouldHide hid ALL completed tool parts, including external
+  // task/status parts created by `oc check` / `oc status`. Because the
+  // running→completed transition can arrive within a single render batch,
+  // these parts were invisible before the user could see them.
+  // The fix exempts tool types "task" and "status" from auto-hiding.
+
+  test("shouldHide block exempts task and status tool types", () => {
+    // Find the shouldHide memo body
+    const match = src.match(/const shouldHide = createMemo\(\(\) => \{([\s\S]*?)\}\)/)
+    expect(match).not.toBeNull()
+    const body = match![1]
+    expect(body).toContain('"task"')
+    expect(body).toContain('"status"')
+    // The exemption must return false (not hidden) for those types
+    expect(body).toMatch(/props\.part\.tool === "task".*return false|return false.*props\.part\.tool === "task"/s)
+  })
+
+  test("shouldHide exemption covers both task and status in one guard", () => {
+    // Both types should appear together in a single conditional so neither
+    // can be removed without the other being noticed.
+    const match = src.match(
+      /props\.part\.tool === "task"[^;]*props\.part\.tool === "status"|props\.part\.tool === "status"[^;]*props\.part\.tool === "task"/,
+    )
+    expect(match).not.toBeNull()
+  })
+})

packages/opencode/test/server/emitter-type.test.ts

@@ -0,0 +1,47 @@
+import { describe, test, expect } from "bun:test"
+import { readFileSync } from "fs"
+import { resolve } from "path"
+
+describe("session routes emitter type safety", () => {
+  const src = readFileSync(resolve(import.meta.dir, "../../src/server/routes/session.ts"), "utf-8")
+
+  // Regression: the emitter fn returned `Promise<T> | undefined` with
+  // `.catch(() => undefined as any)`. Callers had to use optional chaining
+  // (`?.catch`) and the `as any` cast disabled type checking on the return.
+  // The fix makes fn always return `Promise<void>` for consistent await.
+  test("emitter fn always returns Promise<void>", () => {
+    // Must not contain the old `as any` cast pattern
+    expect(src).not.toContain("undefined as any")
+
+    // The fn signature should declare Promise<void> return type
+    const sig = src.match(/const fn = \(state:[^)]*\):\s*Promise<void>/)
+    expect(sig).not.toBeNull()
+  })
+
+  test("emitter fn uses Promise.resolve for no-op path (not undefined)", () => {
+    // The no-op branch must return Promise.resolve() not undefined
+    expect(src).toContain("Promise.resolve()")
+  })
+
+  // Regression: emitter rejection handler was `() => {}` which silently
+  // swallowed errors. External ToolPart updates could fail without any
+  // indication. The fix logs the error via the route-level logger.
+  test("emitter fn logs errors instead of silently swallowing", () => {
+    // The rejection handler must reference log.warn (not be empty)
+    expect(src).toMatch(/\.then\(\s*\(\) => \{\},\s*\(err\)/)
+    expect(src).toContain('log.warn("external part update failed"')
+  })
+
+  // Regression: emit.fn() was called without `void` prefix in synchronous
+  // callbacks (Bus subscriber, metadata callback). The returned Promise was
+  // neither awaited nor voided, causing unhandled rejection if updatePart failed.
+  test("fire-and-forget emit.fn calls use void prefix", () => {
+    // The PartDelta subscriber must use `void emit.fn(`
+    const delta = src.match(/Bus\.subscribe\(MessageV2\.Event\.PartDelta[\s\S]*?void emit\.fn\(/)
+    expect(delta).not.toBeNull()
+
+    // The metadata callback must use `void emit.fn(`
+    const meta = src.match(/metadata\([^)]*\)\s*\{[^}]*void emit\.fn\(/)
+    expect(meta).not.toBeNull()
+  })
+})

packages/opencode/test/server/session-naming.test.ts

@@ -0,0 +1,22 @@
+import { describe, test, expect } from "bun:test"
+import { readFileSync } from "fs"
+import { resolve } from "path"
+
+describe("session routes naming conventions", () => {
+  // Regression: the /exec endpoint used `sessionID` (uppercase D) in metadata
+  // objects, but the TUI Task component and the built-in TaskTool both read
+  // `metadata.sessionId` (lowercase d). The mismatch silently broke child-session
+  // click navigation and sync. This test ensures the correct lowercase key is
+  // always used inside metadata literals.
+  test("exec metadata uses sessionId (lowercase d) not sessionID (uppercase D)", () => {
+    const src = readFileSync(resolve(import.meta.dir, "../../src/server/routes/session.ts"), "utf-8")
+
+    // Must not find uppercase-D form inside a metadata object literal
+    const upper = [...src.matchAll(/metadata:\s*\{[^}]*sessionID\b/g)]
+    expect(upper.length).toBe(0)
+
+    // Must find the correct lowercase-d form (currently 3 occurrences in /exec)
+    const lower = [...src.matchAll(/metadata:\s*\{[^}]*sessionId\b/g)]
+    expect(lower.length).toBeGreaterThan(0)
+  })
+})

packages/opencode/test/session/message-v2.test.ts

@@ -1448,7 +1448,7 @@ describe("session.message-v2.ToolPart.external", () => {
   const pid = PartID.ascending()
   const mid = MessageID.ascending()
 
-  function toolPart(ext?: boolean) {
+  function make(ext?: boolean) {
     return {
       id: pid,
       sessionID,
@@ -1469,19 +1469,19 @@ describe("session.message-v2.ToolPart.external", () => {
   }
 
   test("schema accepts external: true", () => {
-    const result = MessageV2.ToolPart.safeParse(toolPart(true))
+    const result = MessageV2.ToolPart.safeParse(make(true))
     expect(result.success).toBe(true)
     if (result.success) expect(result.data.external).toBe(true)
   })
 
   test("schema accepts external: false", () => {
-    const result = MessageV2.ToolPart.safeParse(toolPart(false))
+    const result = MessageV2.ToolPart.safeParse(make(false))
     expect(result.success).toBe(true)
     if (result.success) expect(result.data.external).toBe(false)
   })
 
   test("schema accepts missing external field (undefined)", () => {
-    const result = MessageV2.ToolPart.safeParse(toolPart())
+    const result = MessageV2.ToolPart.safeParse(make())
     expect(result.success).toBe(true)
     if (result.success) expect(result.data.external).toBeUndefined()
   })