Skip to content

Commit 5ca2d71

Browse files
Hamza-Abiliholny
andcommitted
fix(plugin): expose session form replies to server plugins
SessionDomain omitted form, so server plugins could receive form events but had no supported way to answer or cancel a question. This adds a four-method form surface (list, get, reply, cancel) to the Promise and Effect session domains, bridges it through Form.Service in the plugin host with the server's session-ownership check, wires the Promise adapter, and adds a regression test that settles a Form.ask request through the plugin surface. Create is intentionally left out of this change: #51108 is about answering forms, and plugin-created forms need the client metadata.kind contract. The form methods resolve the session through Session.Service before touching Form.Service, matching the HTTP form route's session lookup (including the "global" MCP elicitation escape hatch), so callers can distinguish an unknown session from an empty form list. Docs explain that form.list returns every pending form kind, that question answers use the form's field keys (q0, q1, ...), and that multiselect answers are string arrays. Port of #51142 to current dev; original implementation by @holny. Fixes #51108 Co-authored-by: holny <[email protected]>
1 parent 1341387 commit 5ca2d71

8 files changed

Lines changed: 227 additions & 4 deletions

File tree

‎packages/core/src/plugin/host.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { AISDK } from "../aisdk.js"
1212
import { Command } from "../command.js"
1313
import { Credential } from "../credential.js"
1414
import { Bus } from "../bus.js"
15+
import { Form } from "../form.js"
1516
import { Integration } from "../integration.js"
1617
import { KV } from "../kv.js"
1718
import { Location } from "../location.js"
@@ -74,6 +75,7 @@ export const make = Effect.fn("PluginHost.make")(function* (
7475
const permission = yield* Permission.Service
7576
const hooks = yield* PluginHooks.Service
7677
const sessions = yield* Session.Service
78+
const forms = yield* Form.Service
7779
const instructionEntries = yield* InstructionEntry.Service
7880
const persistentPty = yield* PersistentPty.Service
7981
const locations = yield* LocationServiceMap.Service
@@ -117,6 +119,20 @@ export const make = Effect.fn("PluginHost.make")(function* (
117119
}).pipe(Effect.provide(locations.get(ref)), Effect.orDie),
118120
)
119121

122+
const decodeSessionID = Schema.decodeUnknownEffect(Session.ID)
123+
const requireSession = (sessionID: string) =>
124+
sessionID === "global"
125+
? Effect.void
126+
: decodeSessionID(sessionID).pipe(Effect.flatMap((id) => sessions.get(id)))
127+
128+
const requireOwnedForm = (sessionID: string, formID: Form.ID) =>
129+
Effect.gen(function* () {
130+
yield* requireSession(sessionID)
131+
const info = yield* forms.get(formID)
132+
if (info.sessionID !== sessionID) return yield* new Form.NotFoundError({ id: formID })
133+
return info
134+
})
135+
120136
// Keep the instance graph's inferred types independent of Session handles.
121137
const context: Plugin.Context = {
122138
app,
@@ -605,6 +621,25 @@ export const make = Effect.fn("PluginHost.make")(function* (
605621
.pipe(Effect.map((interrupted) => ({ interrupted }))),
606622
wait: (input) => sessions.wait(input.sessionID),
607623
context: (input) => sessions.context(input.sessionID),
624+
form: {
625+
list: (input) =>
626+
Effect.gen(function* () {
627+
yield* requireSession(input.sessionID)
628+
return yield* forms.list({ sessionID: input.sessionID })
629+
}),
630+
get: (input) =>
631+
requireOwnedForm(input.sessionID, input.formID).pipe(
632+
Effect.flatMap((info) => Effect.map(forms.state(input.formID), (state) => ({ ...info, state }))),
633+
),
634+
reply: (input) =>
635+
requireOwnedForm(input.sessionID, input.formID).pipe(
636+
Effect.andThen(forms.reply({ id: input.formID, answer: input.answer })),
637+
),
638+
cancel: (input) =>
639+
requireOwnedForm(input.sessionID, input.formID).pipe(
640+
Effect.andThen(forms.cancel(input.formID, { message: input.message })),
641+
),
642+
},
608643
instructions: {
609644
entry: {
610645
list: Effect.fn(function* (input) {
@@ -636,6 +671,7 @@ export const requirements = LayerNode.group([
636671
Model.node,
637672
Command.node,
638673
Bus.node,
674+
Form.node,
639675
Integration.node,
640676
KV.node,
641677
Mcp.node,

‎packages/core/test/plugin/host.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,12 @@ export function host(overrides: Overrides = {}): Plugin.Context {
190190
interrupt: overrides.session?.interrupt ?? (() => Effect.die("unused session.interrupt")),
191191
wait: overrides.session?.wait ?? (() => Effect.die("unused session.wait")),
192192
context: overrides.session?.context ?? (() => Effect.die("unused session.context")),
193+
form: overrides.session?.form ?? {
194+
list: () => Effect.die("unused session.form.list"),
195+
get: () => Effect.die("unused session.form.get"),
196+
reply: () => Effect.die("unused session.form.reply"),
197+
cancel: () => Effect.die("unused session.form.cancel"),
198+
},
193199
instructions: overrides.session?.instructions ?? {
194200
entry: {
195201
list: () => Effect.die("unused session.instructions.entry.list"),
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
import { expect } from "bun:test"
2+
import { Form } from "@opencode/core/form"
3+
import { Plugin } from "@opencode/core/plugin"
4+
import { PluginHost } from "@opencode/core/plugin/host"
5+
import { PluginPromise } from "@opencode/core/plugin/promise"
6+
import { Session } from "@opencode/core/session"
7+
import { Effect, Fiber } from "effect"
8+
import { testEffect } from "../lib/effect"
9+
import { PluginTestLayer } from "./fixture"
10+
11+
const it = testEffect(PluginTestLayer)
12+
13+
const fields = [
14+
{
15+
key: "choice",
16+
type: "string",
17+
title: "Choice",
18+
options: [
19+
{ value: "yes", label: "Yes" },
20+
{ value: "no", label: "No" },
21+
],
22+
custom: true,
23+
},
24+
] satisfies Form.Fields
25+
26+
it.live("Effect plugins can list, get, reply to, and cancel session forms", () =>
27+
Effect.gen(function* () {
28+
const plugins = yield* Plugin.Service
29+
const forms = yield* Form.Service
30+
const context = yield* PluginHost.make(plugins)
31+
const session = yield* context.session.create({ title: "Forms" })
32+
const other = yield* context.session.create({ title: "Other" })
33+
34+
const form = yield* forms.create({ sessionID: session.id, title: "Deploy?", fields })
35+
expect(yield* context.session.form.list({ sessionID: session.id })).toEqual([form])
36+
expect(yield* context.session.form.get({ sessionID: session.id, formID: form.id })).toMatchObject({
37+
id: form.id,
38+
state: { status: "pending" },
39+
})
40+
41+
for (const operation of [
42+
context.session.form.get({ sessionID: other.id, formID: form.id }),
43+
context.session.form.reply({ sessionID: other.id, formID: form.id, answer: { choice: "yes" } }),
44+
context.session.form.cancel({ sessionID: other.id, formID: form.id }),
45+
]) {
46+
expect(yield* operation.pipe(Effect.flip)).toMatchObject({
47+
_tag: "Form.NotFoundError",
48+
id: form.id,
49+
})
50+
}
51+
52+
const missing = Session.ID.create()
53+
for (const operation of [
54+
context.session.form.list({ sessionID: missing }),
55+
context.session.form.get({ sessionID: missing, formID: form.id }),
56+
context.session.form.reply({ sessionID: missing, formID: form.id, answer: { choice: "yes" } }),
57+
context.session.form.cancel({ sessionID: missing, formID: form.id }),
58+
]) {
59+
expect(yield* operation.pipe(Effect.flip)).toMatchObject({
60+
_tag: "Session.NotFoundError",
61+
sessionID: missing,
62+
})
63+
}
64+
65+
yield* context.session.form.reply({ sessionID: session.id, formID: form.id, answer: { choice: "yes" } })
66+
expect(yield* context.session.form.list({ sessionID: session.id })).toEqual([])
67+
expect(yield* context.session.form.get({ sessionID: session.id, formID: form.id })).toMatchObject({
68+
state: { status: "answered", answer: { choice: "yes" } },
69+
})
70+
71+
const cancelled = yield* forms.create({ sessionID: session.id, title: "Cancel?", fields })
72+
yield* context.session.form.cancel({ sessionID: session.id, formID: cancelled.id, message: "not needed" })
73+
expect(yield* context.session.form.get({ sessionID: session.id, formID: cancelled.id })).toMatchObject({
74+
state: { status: "cancelled", message: "not needed" },
75+
})
76+
}),
77+
)
78+
79+
it.live("Effect plugins settle a form started by Form.ask", () =>
80+
Effect.gen(function* () {
81+
const plugins = yield* Plugin.Service
82+
const forms = yield* Form.Service
83+
const context = yield* PluginHost.make(plugins)
84+
const session = yield* context.session.create({ title: "Forms" })
85+
86+
const fiber = yield* forms
87+
.ask({ sessionID: session.id, title: "Deploy?", fields })
88+
.pipe(Effect.forkChild({ startImmediately: true }))
89+
const pending = yield* context.session.form.list({ sessionID: session.id })
90+
expect(pending).toHaveLength(1)
91+
yield* context.session.form.reply({
92+
sessionID: session.id,
93+
formID: pending[0].id,
94+
answer: { choice: "yes" },
95+
})
96+
expect(yield* Fiber.join(fiber)).toMatchObject({
97+
status: "answered",
98+
answer: { choice: "yes" },
99+
})
100+
}),
101+
)
102+
103+
it.live("Promise plugins can list, reply to, and cancel session forms through the adapter", () =>
104+
Effect.gen(function* () {
105+
const plugins = yield* Plugin.Service
106+
const forms = yield* Form.Service
107+
const context = yield* PluginHost.make(plugins)
108+
const session = yield* context.session.create({ title: "Forms" })
109+
const form = yield* forms.create({ sessionID: session.id, title: "Deploy?", fields })
110+
const cancelled = yield* forms.create({ sessionID: session.id, title: "Cancel?", fields })
111+
112+
yield* PluginPromise.fromPromise({
113+
id: "test.session-form",
114+
async setup(ctx) {
115+
const pending = await ctx.session.form.list({ sessionID: session.id })
116+
expect(pending.map((item) => item.id).sort()).toEqual([form.id, cancelled.id].sort())
117+
await ctx.session.form.reply({ sessionID: session.id, formID: form.id, answer: { choice: "yes" } })
118+
expect(await ctx.session.form.get({ sessionID: session.id, formID: form.id })).toMatchObject({
119+
state: { status: "answered", answer: { choice: "yes" } },
120+
})
121+
await ctx.session.form.cancel({ sessionID: session.id, formID: cancelled.id, message: "not needed" })
122+
expect(await ctx.session.form.get({ sessionID: session.id, formID: cancelled.id })).toMatchObject({
123+
state: { status: "cancelled", message: "not needed" },
124+
})
125+
},
126+
}).effect(context)
127+
}),
128+
)

‎packages/plugin/src/effect/session.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,5 +213,6 @@ export type SessionDomain = Pick<
213213
| "context"
214214
> &
215215
Pick<ExperimentalSessionApi<unknown>, "wait" | "instructions"> & {
216+
readonly form: Pick<SessionApi<unknown>["form"], "list" | "get" | "reply" | "cancel">
216217
readonly hook: ModelHooks<SessionHooks>
217218
}

‎packages/plugin/src/promise/adapter.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -617,6 +617,12 @@ export function fromPromise(plugin: Plugin) {
617617
move: adaptApiMethod(SessionEndpoints["session.move"], host.session.move),
618618
wait: adaptApiMethod(SessionEndpoints["session.wait"], host.session.wait),
619619
context: adaptApiMethod(SessionEndpoints["session.context"], host.session.context),
620+
form: {
621+
list: adaptApiMethod(SessionEndpoints["session.form.list"], host.session.form.list),
622+
get: adaptApiMethod(SessionEndpoints["session.form.get"], host.session.form.get),
623+
reply: adaptApiMethod(SessionEndpoints["session.form.reply"], host.session.form.reply),
624+
cancel: adaptApiMethod(SessionEndpoints["session.form.cancel"], host.session.form.cancel),
625+
},
620626
instructions: {
621627
entry: {
622628
list: adaptApiMethod(

‎packages/plugin/src/promise/session.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,5 +213,6 @@ export type SessionDomain = Pick<
213213
| "context"
214214
> &
215215
Pick<ExperimentalSessionApi, "wait" | "instructions"> & {
216+
readonly form: Pick<SessionApi["form"], "list" | "get" | "reply" | "cancel">
216217
readonly hook: ModelHooks<SessionHooks>
217218
}

‎services/www/src/docs/content/build/plugins/effect.mdx‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -875,10 +875,30 @@ effect: (ctx) =>
875875
}),
876876
```
877877

878+
Answer `question` tool forms from an external system. A form appears when the agent asks a question; replying settles
879+
it and unblocks the turn. `list` returns every pending form kind, so filter `metadata.kind === "question"` when
880+
answering questions. Answers are keyed by the form's field keys (`q0`, `q1`, … for the built-in `question` tool);
881+
multiselect fields take an array of strings. Forms are scoped to the plugin's current location. Use `get` to inspect
882+
the current state, and `cancel` to dismiss a form; a cancel message is surfaced to the model as question feedback.
883+
884+
```ts
885+
effect: (ctx) =>
886+
Effect.gen(function* () {
887+
// `sessionID` is the session that owns the form.
888+
const pending = yield* ctx.session.form.list({ sessionID }).pipe(Effect.orDie)
889+
const form = pending.find((item) => item.metadata?.kind === "question")
890+
if (!form) return
891+
const detail = yield* ctx.session.form.get({ sessionID, formID: form.id }).pipe(Effect.orDie)
892+
if (detail.state.status !== "pending") return
893+
yield* ctx.session.form.reply({ sessionID, formID: form.id, answer: { q0: "yes" } }).pipe(Effect.orDie)
894+
}),
895+
```
896+
878897
Schemas: [`Session.Info`](/api#schema-Session.Info), [`Model.Ref`](/api#schema-Model.Ref),
879898
[`Session.Inbox.User`](/api#schema-Session.Inbox.User),
880899
[`Session.Inbox.Synthetic`](/api#schema-Session.Inbox.Synthetic),
881-
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info).
900+
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info), [`Form.Info`](/api#schema-Form.Info),
901+
[`Form.Detail`](/api#schema-Form.Detail).
882902

883903
```ts
884904
type SessionDomain = Pick<
@@ -900,7 +920,9 @@ type SessionDomain = Pick<
900920
| "wait"
901921
| "context"
902922
| "instructions"
903-
>
923+
> & {
924+
readonly form: Pick<SessionApi<unknown>["form"], "list" | "get" | "reply" | "cancel">
925+
}
904926
```
905927
906928
### Skills

‎services/www/src/docs/content/build/plugins/server.mdx‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -802,7 +802,7 @@ await ctx.session.command({ sessionID, name: "review", text: "--staged" })
802802
const synthetic = await ctx.session.synthetic({ sessionID, text: "Deployment completed" })
803803
```
804804

805-
Rename, interrupt, or wait for a session.
805+
Update, interrupt, or wait for a session.
806806

807807
```ts
808808
await ctx.session.update({ sessionID, title: "Review" })
@@ -831,11 +831,28 @@ const entries = await ctx.session.instructions.entry.list({ sessionID })
831831
await ctx.session.instructions.entry.remove({ sessionID, key: "deploy-target" })
832832
```
833833

834+
Answer `question` tool forms from an external system. A form appears when the agent asks a question; replying settles
835+
it and unblocks the turn. `list` returns every pending form kind, so filter `metadata.kind === "question"` when
836+
answering questions. Answers are keyed by the form's field keys (`q0`, `q1`, … for the built-in `question` tool);
837+
multiselect fields take an array of strings. Forms are scoped to the plugin's current location. Use `get` to inspect
838+
the current state, and `cancel` to dismiss a form; a cancel message is surfaced to the model as question feedback.
839+
840+
```ts
841+
// `sessionID` is the session that owns the form.
842+
const pending = await ctx.session.form.list({ sessionID })
843+
const form = pending.find((item) => item.metadata?.kind === "question")
844+
if (!form) return
845+
const detail = await ctx.session.form.get({ sessionID, formID: form.id })
846+
if (detail.state.status !== "pending") return
847+
await ctx.session.form.reply({ sessionID, formID: form.id, answer: { q0: "yes" } })
848+
```
849+
834850
#### Reference
835851

836852
Schemas: [`Session.Info`](/api#schema-Session.Info), [`Model.Ref`](/api#schema-Model.Ref),
837853
[`Session.Inbox.User`](/api#schema-Session.Inbox.User), [`Session.Inbox.Synthetic`](/api#schema-Session.Inbox.Synthetic),
838-
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info)
854+
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info), [`Form.Info`](/api#schema-Form.Info),
855+
[`Form.Detail`](/api#schema-Form.Detail)
839856

840857
```ts
841858
interface SessionContext {
@@ -853,6 +870,12 @@ interface SessionContext {
853870
remove(input: ExperimentalSessionInstructionsEntryRemoveInput, requestOptions?: RequestOptions): Promise<void>
854871
}
855872
}
873+
form: {
874+
list(input: SessionFormListInput, requestOptions?: RequestOptions): Promise<readonly FormInfo[]>
875+
get(input: SessionFormGetInput, requestOptions?: RequestOptions): Promise<FormDetail>
876+
reply(input: SessionFormReplyInput, requestOptions?: RequestOptions): Promise<void>
877+
cancel(input: SessionFormCancelInput, requestOptions?: RequestOptions): Promise<void>
878+
}
856879
switchAgent(input: SessionSwitchAgentInput, requestOptions?: RequestOptions): Promise<void>
857880
switchModel(input: SessionSwitchModelInput, requestOptions?: RequestOptions): Promise<void>
858881
update(input: SessionUpdateInput, requestOptions?: RequestOptions): Promise<void>

0 commit comments

Comments
 (0)