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.
IN CODE
A sketch against dev: two new files and three small edits, no migration.
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" })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), }),
+ 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
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],
})SessionRestart.node, + SessionCallback.node, Workspace.node,
WHAT THE URL GETS
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
- KV entries, or a small
session_callbacktable with a migration? - Land on
session.settled(#59258), or ship onsession.execution.succeededfirst? - How does a client turn the session scope off:
callback: nullonPATCH /session/:id, or aDELETEroute? - Allow private and LAN URLs? A client that can prompt can already run shell, so blocking them adds no safety.