Skip to content

Commit bd6ec8e

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: anomalyco#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 anomalyco#51142 to current dev; original implementation by @holny. Fixes anomalyco#51108 Co-authored-by: holny <[email protected]>
1 parent 8f0bf22 commit bd6ec8e

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
@@ -13,6 +13,7 @@ import { AISDK } from "../aisdk.js"
1313
import { Command } from "../command.js"
1414
import { Credential } from "../credential.js"
1515
import { Bus } from "../bus.js"
16+
import { Form } from "../form.js"
1617
import { Integration } from "../integration.js"
1718
import { IntegrationConnection } from "../integration/connection.js"
1819
import { KV } from "../kv.js"
@@ -74,6 +75,7 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick<Interfa
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
@@ -124,6 +126,20 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick<Interfa
124126
).pipe(Effect.orDie),
125127
)
126128

129+
const decodeSessionID = Schema.decodeUnknownEffect(Session.ID)
130+
const requireSession = (sessionID: string) =>
131+
sessionID === "global"
132+
? Effect.void
133+
: decodeSessionID(sessionID).pipe(Effect.flatMap((id) => sessions.get(id)))
134+
135+
const requireOwnedForm = (sessionID: string, formID: Form.ID) =>
136+
Effect.gen(function* () {
137+
yield* requireSession(sessionID)
138+
const info = yield* forms.get(formID)
139+
if (info.sessionID !== sessionID) return yield* new Form.NotFoundError({ id: formID })
140+
return info
141+
})
142+
127143
// Keep the instance graph's inferred types independent of Session handles.
128144
const context: Plugin.Context = {
129145
app,
@@ -607,6 +623,25 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick<Interfa
607623
.pipe(Effect.map((interrupted) => ({ interrupted }))),
608624
wait: (input) => sessions.wait(input.sessionID),
609625
context: (input) => sessions.context(input.sessionID),
626+
form: {
627+
list: (input) =>
628+
Effect.gen(function* () {
629+
yield* requireSession(input.sessionID)
630+
return yield* forms.list({ sessionID: input.sessionID })
631+
}),
632+
get: (input) =>
633+
requireOwnedForm(input.sessionID, input.formID).pipe(
634+
Effect.flatMap((info) => Effect.map(forms.state(input.formID), (state) => ({ ...info, state }))),
635+
),
636+
reply: (input) =>
637+
requireOwnedForm(input.sessionID, input.formID).pipe(
638+
Effect.andThen(forms.reply({ id: input.formID, answer: input.answer })),
639+
),
640+
cancel: (input) =>
641+
requireOwnedForm(input.sessionID, input.formID).pipe(
642+
Effect.andThen(forms.cancel(input.formID, { message: input.message })),
643+
),
644+
},
610645
instructions: {
611646
entry: {
612647
list: Effect.fn(function* (input) {
@@ -639,6 +674,7 @@ export const requirements = LayerNode.group([
639674
Model.node,
640675
Command.node,
641676
Bus.node,
677+
Form.node,
642678
Integration.node,
643679
KV.node,
644680
Mcp.node,

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,12 @@ export function host(overrides: Overrides = {}): Plugin.Context {
194194
interrupt: overrides.session?.interrupt ?? (() => Effect.die("unused session.interrupt")),
195195
wait: overrides.session?.wait ?? (() => Effect.die("unused session.wait")),
196196
context: overrides.session?.context ?? (() => Effect.die("unused session.context")),
197+
form: overrides.session?.form ?? {
198+
list: () => Effect.die("unused session.form.list"),
199+
get: () => Effect.die("unused session.form.get"),
200+
reply: () => Effect.die("unused session.form.reply"),
201+
cancel: () => Effect.die("unused session.form.cancel"),
202+
},
197203
instructions: overrides.session?.instructions ?? {
198204
entry: {
199205
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, "test")
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, "test")
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, "test")
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
@@ -231,5 +231,6 @@ export type SessionDomain = Pick<
231231
| "context"
232232
> &
233233
Pick<ExperimentalSessionApi<unknown>, "wait" | "instructions"> & {
234+
readonly form: Pick<SessionApi<unknown>["form"], "list" | "get" | "reply" | "cancel">
234235
readonly hook: ModelHooks<SessionHooks>
235236
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -640,6 +640,12 @@ export function fromPromise(plugin: Plugin) {
640640
move: adaptApiMethod(SessionEndpoints["session.move"], host.session.move),
641641
wait: adaptApiMethod(SessionEndpoints["session.wait"], host.session.wait),
642642
context: adaptApiMethod(SessionEndpoints["session.context"], host.session.context),
643+
form: {
644+
list: adaptApiMethod(SessionEndpoints["session.form.list"], host.session.form.list),
645+
get: adaptApiMethod(SessionEndpoints["session.form.get"], host.session.form.get),
646+
reply: adaptApiMethod(SessionEndpoints["session.form.reply"], host.session.form.reply),
647+
cancel: adaptApiMethod(SessionEndpoints["session.form.cancel"], host.session.form.cancel),
648+
},
643649
instructions: {
644650
entry: {
645651
list: adaptApiMethod(

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,5 +231,6 @@ export type SessionDomain = Pick<
231231
| "context"
232232
> &
233233
Pick<ExperimentalSessionApi, "wait" | "instructions"> & {
234+
readonly form: Pick<SessionApi["form"], "list" | "get" | "reply" | "cancel">
234235
readonly hook: ModelHooks<SessionHooks>
235236
}

‎services/site/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/site/src/docs/content/build/plugins/server.mdx‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -805,7 +805,7 @@ const synthetic = await ctx.session.synthetic({ sessionID, text: "Deployment com
805805
`generate` returns the `text` along with the call's `tokens` and `cost`, in the same shape an assistant message
806806
reports them.
807807

808-
Rename, interrupt, or wait for a session.
808+
Update, interrupt, or wait for a session.
809809

810810
```ts
811811
await ctx.session.update({ sessionID, title: "Review" })
@@ -834,11 +834,28 @@ const entries = await ctx.session.instructions.entry.list({ sessionID })
834834
await ctx.session.instructions.entry.remove({ sessionID, key: "deploy-target" })
835835
```
836836

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

839855
Schemas: [`Session.Info`](/api#schema-Session.Info), [`Model.Ref`](/api#schema-Model.Ref),
840856
[`Session.Inbox.User`](/api#schema-Session.Inbox.User), [`Session.Inbox.Synthetic`](/api#schema-Session.Inbox.Synthetic),
841-
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info)
857+
[`InstructionEntry.Info`](/api#schema-InstructionEntry.Info), [`Form.Info`](/api#schema-Form.Info),
858+
[`Form.Detail`](/api#schema-Form.Detail)
842859

843860
```ts
844861
interface SessionContext {
@@ -856,6 +873,12 @@ interface SessionContext {
856873
remove(input: ExperimentalSessionInstructionsEntryRemoveInput, requestOptions?: RequestOptions): Promise<void>
857874
}
858875
}
876+
form: {
877+
list(input: SessionFormListInput, requestOptions?: RequestOptions): Promise<readonly FormInfo[]>
878+
get(input: SessionFormGetInput, requestOptions?: RequestOptions): Promise<FormDetail>
879+
reply(input: SessionFormReplyInput, requestOptions?: RequestOptions): Promise<void>
880+
cancel(input: SessionFormCancelInput, requestOptions?: RequestOptions): Promise<void>
881+
}
859882
switchAgent(input: SessionSwitchAgentInput, requestOptions?: RequestOptions): Promise<void>
860883
switchModel(input: SessionSwitchModelInput, requestOptions?: RequestOptions): Promise<void>
861884
update(input: SessionUpdateInput, requestOptions?: RequestOptions): Promise<void>

0 commit comments

Comments
 (0)