SESSION CALLBACKS

PROBLEM

You send a prompt from your phone and lock it. The phone only hears from OpenCode while the app is open, so you never find out when the agent finishes or is stuck waiting on you.

FIX

The prompt carries a callback URL. When the turn finishes, fails or needs your answer, OpenCode posts to that URL, and whatever is listening there sends the push.

9:41 NEEDS YOU PROMPT + URL OPENCODE IDLE CALLBACK OFF POST CALLBACK URL ANY HTTPS ENDPOINT PUSH

IN CODE

A sketch against dev: two new files and three small edits, no migration.

packages/schema/src/session-callback.tsNEW
export * as SessionCallback from "./session-callback.js"

import { Schema } from "effect"
import { optional } from "./schema.js"

export const Type = Schema.Literals([
  "turn.completed",
  "turn.failed",
  "turn.interrupted",
  "input.requested",
])

export const Request = Schema.Struct({
  url: Schema.String,
  scope: Schema.Literals(["turn", "session"]).pipe(optional),
  events: Schema.Array(Type).pipe(optional),
  secret: Schema.String.pipe(optional),
}).annotate({ identifier: "Session.Callback.Request" })
packages/protocol/src/groups/session.tsEDIT
HttpApiEndpoint.post("session.prompt", "/api/session/:sessionID/prompt", {
  payload: Schema.Struct({
    …
    ...PromptInput.Prompt.fields,
    delivery: SessionInbox.Delivery.pipe(Schema.optional),
    resume: Schema.Boolean.pipe(Schema.optional),
+   callback: SessionCallback.Request.pipe(Schema.optional),
  }),
packages/core/src/session/session.tsEDIT
+ const callbacks = yield* SessionCallback.Service
…
const admitted = yield* Effect.gen(function* () { … })
+ // Arm before waking, so a fast turn can't finish first.
+ if (input.callback) yield* callbacks.arm(sessionID, input.callback)
if (input.resume !== false) yield* execution.wake(sessionID)
return admitted
packages/core/src/session/callback.tsNEW
export * as SessionCallback from "./callback.js"

const key = (sessionID: SessionSchema.ID, scope: "turn" | "session") =>
  `session-callback:${sessionID}:${scope}`

const layer = Layer.effect(
  Service,
  Effect.gen(function* () {
    const bus = yield* Bus.Service
    const kv = yield* KV.Service
    const store = yield* SessionStore.Service
    const http = HttpClient.filterStatusOk(yield* HttpClient.HttpClient)
    const fibers = yield* Scope.Scope

    // In KV, outside message history, so it survives a restart.
    const arm = Effect.fn("SessionCallback.arm")(function* (
      sessionID: SessionSchema.ID,
      request: Request,
    ) {
      yield* kv.set(key(sessionID, request.scope ?? "turn"), request)
    })

    // Standard Webhooks headers. Never blocks or fails the turn.
    const deliver = (callback: Request, body: Body) =>
      HttpClientRequest.post(callback.url).pipe(
        HttpClientRequest.setHeaders(headers(body, callback.secret)),
        HttpClientRequest.bodyJson(body),
        Effect.flatMap(http.execute),
        Effect.timeout("10 seconds"),
        Effect.retry({
          times: 2,
          schedule: Schedule.exponential("5 seconds", 6), // 5 s, 30 s
        }),
        Effect.catch((error) => Effect.logWarning("callback failed", { error })),
        Effect.forkIn(fibers),
      )

    yield* bus
      .subscribe([
        SessionEvent.Settled, // #59258: waits for background subagents
        SessionEvent.Execution.Failed,
        SessionEvent.Execution.Interrupted,
        Permission.Event.Asked,
        Form.Event.Created,
      ])
      .pipe(
        Stream.runForEach((event) =>
          Effect.gen(function* () {
            const type = callbackType(event) // undefined for shutdowns
            if (!type) return
            // Subagent questions go to the root; subagent turns never post.
            const sessionID = yield* target(store, event, type)
            if (!sessionID) return
            for (const scope of ["turn", "session"] as const) {
              const callback = decode(yield* kv.get(key(sessionID, scope)))
              if (!callback || !wants(callback, type)) continue
              // A turn callback fires on its outcome once, then disarms.
              if (scope === "turn" && type !== "input.requested")
                yield* kv.remove(key(sessionID, scope))
              yield* deliver(callback, yield* body(store, event, type))
            }
          }),
        ),
        Effect.forkScoped({ startImmediately: true }),
      )

    return Service.of({ arm })
  }),
)

export const node = makeGlobalNode({
  service: Service,
  layer,
  deps: [Bus.node, KV.node, SessionStore.node, httpClient],
})
packages/server/src/routes.tsEDIT
  SessionRestart.node,
+ SessionCallback.node,
  Workspace.node,

WHAT THE URL GETS

POST https://example.com/cbJSON
webhook-id: evt_01JD…        // same on every retry
webhook-signature: v1,…      // only with a secret

{
  "type": "input.requested",
  "id": "evt_01JD…",
  "sessionID": "ses_…",
  "title": "Fix login redirect",
  "summary": "Allow edit to src/auth.ts?"
}

OPEN QUESTIONS

  1. KV entries, or a small session_callback table with a migration?
  2. Land on session.settled (#59258), or ship on session.execution.succeeded first?
  3. How does a client turn the session scope off: callback: null on PATCH /session/:id, or a DELETE route?
  4. Allow private and LAN URLs? A client that can prompt can already run shell, so blocking them adds no safety.