feat(mcp): ask an app's form questions in the task chat and send the answer back (MCP elicitation) (#21466)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents use connected MCP apps through the tool gateway.
> - An MCP app can ask the person a question in the middle of a tool
call (MCP elicitation). There are two kinds: a form, or a link to open.
> - Today a form question is a dead end:
> - A 2026-07-28 server's form `input_required` stops with "needs
information Paperclip can't collect yet".
> - An older server's `elicitation/create` makes a card, but the answer
is never sent back, and the server waits on an open stream.
> - Paperclip does not declare form support, so compliant servers never
ask.
> - This pull request shows the question as a card in the task chat. The
card names the app, and only a person can answer it. When the person
answers, the agent wakes. The agent's repeated call sends the answer to
the app exactly once, for both protocol eras.
> - The benefit: apps that need a choice or a detail from the person now
finish their work. Restarts lose nothing, and no call is left waiting.

## Linked Issues or Issue Description

Refs #21140 (stateless MCP client; this PR closes its "form elicitation"
follow-up). Refs #21263 (MCP Tasks; this PR shares its card code). Refs
#21389 (MCP Tasks follow-ups: the card answer validation item).

**Is your feature request related to a problem?**
When a connected MCP app asks the person a form question during a tool
call, the call stops and cannot continue. A 2026-07-28 server gets a
"needs input" error. An older server gets a card whose answer never
reaches it.

**Describe the solution you'd like**
Show the question in the task chat. Let a person answer, skip, or leave
it. Wake the agent when the question is resolved. Send the answer on the
agent's repeated call, once, with the server's exact state.

**Describe alternatives you've considered**
Holding the tool call open until the person answers. We rejected this:
it holds a stream and a run slot, and it does not survive deploys or
restarts. The plan (`doc/plans/2026-11-13-mcp-elicitation.md`) records
nine design decisions with their alternatives.

## What Changed

- **Plan:** `doc/plans/2026-11-13-mcp-elicitation.md` covers the spec,
the inventory, the decisions, the journey, tests, and risks.
- **New module `server/src/services/mcp-elicitation.ts`.** It is the
single mapping for direct calls and MCP Tasks:
- It turns each spec form field into a real card field: text with
defaults, number, yes/no, single choice (`enum` and `oneOf`), and
multiple choice (`items.enum` and `items.anyOf`).
  - It turns card answers back into typed `content`.
- Answered sends `accept`. Skip sends `decline`. Withdrawn, closed, or
expired sends `cancel`.
- It refuses forms that ask for passwords, keys, tokens, card numbers,
or one-time codes.
  - It keeps app text plain, so links in it are not clickable.
- It seals `requestState` with AES-256-GCM, bound to the company and
connection.
- **New table `tool_mcp_elicitations`** (migration 0479). It is
company-scoped, with one row per question round. It holds a keyed call
identity, the sealed state, the questions and their cards, a claim time,
and a 24-hour expiry.
- **Gateway, stateless servers:**
  - Paperclip declares `elicitation: {form, url}` on task tool calls.
- A form-only `input_required` saves the round, makes the cards, and
stops with a wait message.
- A repeated call before the person answers stops again without
contacting the app.
- After the answer, the repeated call claims the round and sends
`inputResponses` and the exact `requestState`, once.
- A failed send releases the claim. A crash mid-send lets the claim
lapse.
- **Gateway, older servers:**
  - Paperclip declares form support at `initialize`.
  - The first question gets `cancel` at once, so the server never waits.
- When the same question (same words and schema) arrives on the repeated
call, Paperclip answers it from the card.
- **Gateway, mixed rounds and retries:**
  - A form beside a URL step shows the link first.
- A repeated call that stopped for a question runs again in the same
run. It is no longer replayed by the per-run idempotency key.
- **Cards:** the title is "*App* needs your input". The resolver policy
is `human_only`. "Send to *App*" sends the answer. A user comment does
not supersede the card.
- **Activity log:** new events `tool_gateway.elicitation_sent`,
`tool_gateway.elicitation_refused`, and
`tool_gateway.elicitation_expired`. They record the action only, never
the values.
- **MCP Tasks:** task cards use the same mapping and gain the app name,
real fields, and `human_only`. A secret or an unsupported form stays
unsupported.
- **Storybook:** `Tasks and conversations/Questions and approvals/MCP
App Questions` has five states: Asking, Answered, Skipped, Expired, and
TwoQuestions. The fixtures are generated from the server mapper's
output.
- **Docs:** `doc/connections/MCP-ELICITATION.md` (linked from the
README) is new. `MCP-PROTOCOL-VERSIONS.md` and `MCP-TASKS.md` are
updated.

## Verification

- `server/src/__tests__/mcp-elicitation.test.ts` has 16 tests. They pass
on the branch.
- **Red/green:** 9 of the 9 gateway tests fail with master's
`tool-gateway.ts` and `mcp-http.ts`. The 7 pure unit tests cover the new
module.
- The tests use a fake 2026-07-28 server and a fake 2025-06-18 server
that asks over the open stream and waits for the reply.
- Covered: answer, skip (`decline`), withdraw (`cancel`), two questions
at once, a restart while waiting, a crash mid-send, another company with
the same app and arguments, expiry, a refused password field, an agent
that tries to answer (rejected), and capabilities.
- Existing suites: `mcp-tasks`, `mcp-protocol-versions`,
`tool-gateway-service`, `tool-gateway`, and `remote-mcp-connectors`. See
the results comment below.
- Storybook: the five stories render in headless Chromium, and the play
tests pass. The only console errors are the 404s from the backend-less
API calls that every story makes.
- `tsc --noEmit` is clean for `server` and `ui`. `node
scripts/storybook-catalog.mjs` passes.

## Risks

- **Older servers may start asking questions.** Declaring form support
at `initialize` can make older servers ask where they did not before.
Mitigation: the first question always gets `cancel` at once, so no call
hangs, and the agent gets a clear next step.
- **Per-call cost.** Each 2026-07-28 HTTP tool call in a task makes one
indexed lookup for a waiting round. Nothing is added before the first
token or to agent boot.
- **Migration.** One additive table with no backfill, so it is safe to
apply online.
- **Changed Tasks behavior.** A task card that is withdrawn or closed
now sends `cancel` instead of `decline`, as the spec defines. A skipped
card still sends `decline`.
- **Stale cards.** Expiry is checked only when the agent calls again. A
card can sit past 24 hours until the next call. Then it is withdrawn and
the app asks again.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use
(shell, file edits, headless browser), with extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-13 19:46:56 -06:00
1 parent 4879a146fb
commit a4c570aede
20 files changed
+3030 -218

No files matched your search

@@ -1124,6 +1124,34 @@ describe("issue thread interaction routes", () => {
expect(mockHeartbeatService.wakeup).not.toHaveBeenCalled();
});
it.each([
["an app's question (MCP elicitation)", "mcp-elicit:round-1:abc", 1],
["an ordinary question", "agent-question-1", 0],
] as const)("wakes the assignee when a person skips %s, so the app receives the decline", async (_name, idempotencyKey, wakes) => {
mockInteractionService.skipInteraction.mockResolvedValue({
id: "interaction-skip",
companyId: "company-1",
issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
kind: "ask_user_questions",
status: "cancelled",
continuationPolicy: "wake_assignee",
idempotencyKey,
sourceCommentId: null,
sourceRunId: RUN_2,
payload: { version: 1, questions: [] },
result: { version: 1, answers: [], outcome: "skipped" },
});
const app = await createApp();
const res = await request(app)
.post("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/interactions/interaction-skip/skip")
.send({});
expect(res.status).toBe(200);
expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(wakes);
if (wakes) expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(ASSIGNEE_AGENT_ID, expect.anything());
});
it("submits item verdicts and emits one continuation wake with resolved item ids", async () => {
const app = await createApp();
@@ -0,0 +1,696 @@
import { randomUUID } from "node:crypto";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import {
activityLog,
agents,
approvals,
toolActionRequests,
companies,
companyMemberships,
createDb,
heartbeatRuns,
issues,
issueThreadInteractions,
projects,
toolConnections,
toolInvocations,
toolMcpElicitations,
} from "@paperclipai/db";
import { and, eq } from "drizzle-orm";
import { paperclipQuestionSetPayloadSchema } from "@paperclipai/shared";
import { forgetMcpHttpSessions, MCP_MODERN_PROTOCOL_VERSION, mcpClientCapabilities, mcpHttpRequestInit } from "../services/mcp-http.js";
import {
buildElicitationQuestionSet,
elicitationContent,
elicitationQuestionHash,
elicitationResponseForCard,
elicitationSensitiveFields,
openElicitationState,
sealElicitationState,
} from "../services/mcp-elicitation.js";
import { mcpInputRequiredPending } from "../services/tool-gateway.js";
import { mcpInputRequired } from "../services/mcp-http.js";
import { createToolGatewayService } from "../services/tool-gateway.js";
import { toolAccessService } from "../services/tool-access.js";
import { issueThreadInteractionService } from "../services/issue-thread-interactions.js";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
const META_VERSION = "io.modelcontextprotocol/protocolVersion";
const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
/** Every spec form type (SEP-1330 enums, SEP-1034 defaults). */
const TICKET_SCHEMA = {
type: "object",
required: ["title", "priority"],
properties: {
title: { type: "string", title: "Ticket title", minLength: 3, maxLength: 80, default: "Untitled" },
contact: { type: "string", format: "email", title: "Contact email" },
priority: { type: "string", title: "Priority", oneOf: [{ const: "p1", title: "Urgent" }, { const: "p2", title: "Normal" }], default: "p2" },
team: { type: "string", title: "Team", enum: ["ops", "eng"] },
labels: { type: "array", title: "Labels", minItems: 1, maxItems: 2, items: { anyOf: [{ const: "bug", title: "Bug" }, { const: "ux", title: "UX" }, { const: "perf", title: "Speed" }] }, default: ["bug"] },
tags: { type: "array", title: "Tags", items: { type: "string", enum: ["a", "b"] } },
urgent: { type: "boolean", title: "Page someone?", default: false },
count: { type: "integer", title: "How many?", minimum: 1, maximum: 5, default: 1 },
budget: { type: "number", title: "Budget" },
},
};
describe("MCP form elicitation mapping", () => {
it("maps every spec field type to a real card field, with defaults", () => {
const built = buildElicitationQuestionSet({ appName: "Linear", request: { message: "Tell us about the ticket", requestedSchema: TICKET_SCHEMA } });
expect(built.ok).toBe(true);
if (!built.ok) return;
// The card passes the same validation every question card does.
expect(paperclipQuestionSetPayloadSchema.safeParse(built.questionSet).success).toBe(true);
expect(built.questionSet).toMatchObject({ title: "Linear needs your input", description: "Tell us about the ticket", submitLabel: "Send to Linear" });
const byId = Object.fromEntries(built.questionSet.questions.map((question) => [question.id, question]));
expect(byId.title).toMatchObject({ answerMode: "text", required: true, initialText: "Untitled", textValidation: { minLength: 3, maxLength: 80 } });
// The question form checks only fixed-width patterns: an email is a hint, a date is checked.
expect(byId.contact).toMatchObject({ answerMode: "text", required: false, helpText: "An email address." });
expect(byId.contact).not.toHaveProperty("textValidation");
expect(buildElicitationQuestionSet({ appName: "A", request: { message: "m", requestedSchema: { properties: { d: { type: "string", format: "date" } } } } }))
.toMatchObject({ ok: true, questionSet: { questions: [{ textValidation: { pattern: "^\\d\\d\\d\\d-\\d\\d-\\d\\d$" } }] } });
expect(byId.priority).toMatchObject({ answerMode: "single_select", options: [{ label: "Urgent" }, { label: "Normal", recommended: true }] });
expect(byId.team).toMatchObject({ answerMode: "single_select", options: [{ label: "ops" }, { label: "eng" }] });
expect(byId.labels).toMatchObject({ answerMode: "multi_select", helpText: "Choose at least 1. Choose at most 2.", options: [{ label: "Bug", recommended: true }, { label: "UX" }, { label: "Speed" }] });
expect(byId.tags).toMatchObject({ answerMode: "multi_select" });
expect(byId.urgent).toMatchObject({ answerMode: "single_select", options: [{ label: "Yes" }, { label: "No", recommended: true }] });
expect(byId.count).toMatchObject({ answerMode: "text", initialText: "1", textValidation: { inputType: "integer", minimum: 1, maximum: 5 } });
expect(byId.budget).toMatchObject({ answerMode: "text", textValidation: { inputType: "number" } });
});
it("turns card answers back into typed content on the provider's schema", () => {
const request = { message: "m", requestedSchema: TICKET_SCHEMA };
const content = elicitationContent(request, { answers: [
{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: " Login broken " },
{ questionId: "priority", optionIds: ["choice_1"] },
{ questionId: "labels", optionIds: ["choice_1", "choice_3"] },
{ questionId: "urgent", optionIds: ["choice_1"] },
{ questionId: "count", optionIds: [], otherText: "3" },
{ questionId: "budget", optionIds: [], otherText: "12.5" },
] });
expect(content).toEqual({ title: "Login broken", priority: "p1", labels: ["bug", "perf"], urgent: true, count: 3, budget: 12.5 });
});
it("answers accept, decline (skipped), or cancel (anything else ending the card)", () => {
const request = { message: "Continue?", requestedSchema: { type: "object", properties: {} } };
expect(elicitationResponseForCard(request, { status: "pending", result: null })).toBeNull();
expect(elicitationResponseForCard(request, { status: "answered", result: { version: 1, answers: [{ questionId: "continue", optionIds: ["continue"] }] } }))
.toEqual({ action: "accept", content: {} });
expect(elicitationResponseForCard(request, { status: "cancelled", result: { version: 1, answers: [], outcome: "skipped" } })).toEqual({ action: "decline" });
expect(elicitationResponseForCard(request, { status: "cancelled", result: { version: 1, answers: [], outcome: "withdrawn" } })).toEqual({ action: "cancel" });
expect(elicitationResponseForCard(request, { status: "expired", result: null })).toEqual({ action: "cancel" });
});
it("reads a card saved before typed fields (an MCP Task waiting across the upgrade)", () => {
const request = { message: "m", requestedSchema: { type: "object", properties: {
workspace: { enum: ["ops", "engineering"] }, page: { type: "boolean" }, count: { type: "integer" },
} } };
const payload = { version: 1, questions: [
{ id: "workspace", prompt: "workspace", selectionMode: "single", options: [{ id: "ops", label: "ops" }, { id: "engineering", label: "engineering" }] },
{ id: "page", prompt: "page", selectionMode: "single", options: [{ id: "answer", label: "Provide answer" }] },
{ id: "count", prompt: "count", selectionMode: "single", options: [{ id: "answer", label: "Provide answer" }] },
] };
const result = { version: 1, answers: [
{ questionId: "workspace", optionIds: ["engineering"] },
{ questionId: "page", optionIds: [], otherText: "yes" },
{ questionId: "count", optionIds: [], otherText: "4" },
] };
expect(elicitationResponseForCard(request, { status: "answered", result, payload }))
.toEqual({ action: "accept", content: { workspace: "engineering", page: true, count: 4 } });
});
it("refuses forms that ask for secrets, and shapes outside the spec", () => {
expect(elicitationSensitiveFields({ properties: { password: { type: "string" } } })).toEqual(["password"]);
expect(elicitationSensitiveFields({ properties: { key: { type: "string", title: "Your API key" } } })).toEqual(["key"]);
expect(elicitationSensitiveFields({ properties: { code: { type: "string", description: "The one-time code we texted you" } } })).toEqual(["code"]);
expect(elicitationSensitiveFields({ properties: { x: { type: "string", format: "password" } } })).toEqual(["x"]);
expect(elicitationSensitiveFields({ properties: { name: { type: "string" }, max_tokens: { type: "integer" } } })).toEqual([]);
const ask = (requestedSchema: Record<string, unknown>) => buildElicitationQuestionSet({ appName: "App", request: { message: "m", requestedSchema } });
expect(ask({ properties: { card_number: { type: "string" } } })).toEqual({ ok: false, reason: "sensitive", fields: ["card_number"] });
// The message itself asking for a secret is refused, whatever the field is called.
expect(buildElicitationQuestionSet({ appName: "App", request: { message: "Type your account password in the notes field", requestedSchema: { properties: { notes: { type: "string" } } } } }))
.toEqual({ ok: false, reason: "sensitive", fields: ["message"] });
expect(buildElicitationQuestionSet({ appName: "App", request: { message: "How many tokens should the summary use?", requestedSchema: { properties: { n: { type: "integer" } } } } }).ok).toBe(true);
expect(ask({ properties: { nested: { type: "object", properties: {} } } })).toEqual({ ok: false, reason: "unsupported" });
expect(ask({ properties: { list: { type: "array", items: { type: "string" } } } })).toEqual({ ok: false, reason: "unsupported" });
expect(ask({ properties: Object.fromEntries(Array.from({ length: 11 }, (_, index) => [`f${index}`, { type: "string" }])) })).toEqual({ ok: false, reason: "unsupported" });
});
it("keeps provider text plain: no clickable links, no markup", () => {
const built = buildElicitationQuestionSet({ appName: "App", request: { message: "Open [this](https://evil.example.com) or <b>https://x.example.com</b>", requestedSchema: { properties: {} } } });
expect(built.ok && built.questionSet.description).toBe("Open [this] (https:​//evil.example.com) or bhttps:​//x.example.com/b");
});
it("seals the server's state to the company and connection that received it", () => {
const scope = { companyId: "c1", connectionId: "k1" };
const sealed = sealElicitationState("secret", scope, "opaque-state");
expect(sealed).not.toContain("opaque-state");
expect(openElicitationState("secret", scope, sealed)).toBe("opaque-state");
expect(openElicitationState("secret", { ...scope, companyId: "c2" }, sealed)).toBeNull();
expect(openElicitationState("other", scope, sealed)).toBeNull();
});
it("identifies a question by its words and schema, not key order", () => {
expect(elicitationQuestionHash({ message: "m", requestedSchema: { a: 1, b: { c: 2, d: 3 } } }))
.toBe(elicitationQuestionHash({ message: "m", requestedSchema: { b: { d: 3, c: 2 }, a: 1 } }));
expect(elicitationQuestionHash({ message: "m", requestedSchema: {} })).not.toBe(elicitationQuestionHash({ message: "n", requestedSchema: {} }));
});
it("declares form questions only where a person can answer them", () => {
expect(mcpClientCapabilities(MCP_MODERN_PROTOCOL_VERSION).elicitation).toEqual({ url: {} });
expect(mcpClientCapabilities(MCP_MODERN_PROTOCOL_VERSION, { elicitationForm: true }).elicitation).toEqual({ form: {}, url: {} });
expect(mcpClientCapabilities("2025-11-25", { elicitationForm: true }).elicitation).toEqual({ form: {}, url: {} });
expect(mcpClientCapabilities("2025-06-18", { elicitationForm: true }).elicitation).toEqual({});
expect(mcpClientCapabilities("2025-03-26", { elicitationForm: true })).not.toHaveProperty("elicitation");
// Older stdio sessions keep what they had.
expect(mcpClientCapabilities("2025-11-25")).not.toHaveProperty("elicitation");
const body = JSON.parse(mcpHttpRequestInit({ "MCP-Protocol-Version": MCP_MODERN_PROTOCOL_VERSION }, { id: 1, method: "tools/call", params: { name: "x" } }, { elicitationForm: true }).body);
expect(body.params._meta[META_CAPABILITIES].elicitation).toEqual({ form: {}, url: {} });
});
it("shows the link first when a round mixes a link and a form, and never claims consent", () => {
const mixed = mcpInputRequiredPending(mcpInputRequired({ resultType: "input_required", requestState: "s", inputRequests: {
consent: { method: "elicitation/create", params: { mode: "url", message: "Approve", url: "https://auth.example.com/consent" } },
name: { method: "elicitation/create", params: { message: "Name?", requestedSchema: { type: "object", properties: {} } } },
} })!);
expect(mixed).toMatchObject({ answerable: true, upstreamPending: { links: [{ url: "https://auth.example.com/consent" }] } });
expect(mixed).not.toHaveProperty("retryState");
});
});
type Recorded = { method: string; headers: Headers; body: Record<string, any> };
/** A stateless (2026-07-28) server whose tools ask the person questions. */
function askingServer() {
const requests: Recorded[] = [];
let refuseAnswers = 0;
const respond = (id: unknown, result: Record<string, unknown>) => Response.json({ jsonrpc: "2.0", id, result: { resultType: "complete", ...result } });
const form = (message: string, requestedSchema: Record<string, unknown>) => ({ method: "elicitation/create", params: { mode: "form", message, requestedSchema } });
const handle = async (_url: string, init: RequestInit): Promise<Response> => {
if ((init.method ?? "GET").toUpperCase() !== "POST") return new Response(null, { status: 404 });
const body = JSON.parse(String(init.body));
requests.push({ method: body.method, headers: new Headers(init.headers), body });
if (body.params?._meta?.[META_VERSION] !== MCP_MODERN_PROTOCOL_VERSION) return Response.json({ jsonrpc: "2.0", id: body.id, error: { code: -32020, message: "metadata" } }, { status: 400 });
if (body.method === "server/discover") return respond(body.id, { supportedVersions: [MCP_MODERN_PROTOCOL_VERSION], capabilities: { tools: {} } });
if (body.method === "tools/list") {
return respond(body.id, { tools: ["create_ticket", "two_questions", "ask_secret", "two_rounds"].map((name) => ({ name, description: name, inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint: true } })) });
}
if (body.method !== "tools/call") return Response.json({ jsonrpc: "2.0", id: body.id, error: { code: -32601, message: "nope" } });
const { name, inputResponses, requestState } = body.params;
if (inputResponses && refuseAnswers > 0) { refuseAnswers -= 1; return new Response(null, { status: 503 }); }
if (name === "two_rounds" && inputResponses?.first) {
return respond(body.id, { resultType: "input_required", requestState: "round-2", inputRequests: { second: form("And the due date?", { type: "object", properties: { due: { type: "string", format: "date" } }, required: ["due"] }) } });
}
if (name === "two_rounds" && !inputResponses) {
return respond(body.id, { resultType: "input_required", requestState: "round-1", inputRequests: { first: form("Which team?", { type: "object", properties: { team: { type: "string", enum: ["ops", "eng"] } }, required: ["team"] }) } });
}
if (inputResponses) return respond(body.id, { content: [{ type: "text", text: JSON.stringify({ inputResponses, requestState: requestState ?? null }) }] });
if (name === "create_ticket") {
return respond(body.id, { resultType: "input_required", requestState: `state-for-${body.params.arguments?.ref ?? "none"}`, inputRequests: { details: form("Tell us about the ticket", TICKET_SCHEMA) } });
}
if (name === "two_questions") {
return respond(body.id, { resultType: "input_required", requestState: "two-state", inputRequests: {
who: form("Who should own it?", { type: "object", properties: { owner: { type: "string", title: "Owner" } }, required: ["owner"] }),
go: form("Ship it now?", { type: "object", properties: {} }),
} });
}
return respond(body.id, { resultType: "input_required", inputRequests: { secret: form("Sign in", { type: "object", properties: { password: { type: "string" } } }) } });
};
return { requests, handle, calls: () => requests.filter((request) => request.method === "tools/call"), refuseNextAnswer: () => { refuseAnswers = 1; } };
}
/**
* A 2025-06-18 server with a session that asks over the open tools/call stream
* and waits for the client's reply before it finishes, like the SDK servers.
* It asks its questions in turn and stops at the first one not accepted.
*/
function legacyAskingServer(options: { questions?: Array<{ message: string; key: string; values: string[]; askAgainIf?: string }>; refuseReplies?: number } = {}) {
const requests: Recorded[] = [];
const replies: Array<Record<string, any>> = [];
const questions = options.questions ?? [{ message: "Which team?", key: "team", values: ["ops", "eng"] }];
let refuseReplies = options.refuseReplies ?? 0;
let sessions = 0;
let asks = 0;
const waiting = new Map<string, (reply: Record<string, any>) => void>();
const sse = (message: unknown) => new TextEncoder().encode(`data: ${JSON.stringify(message)}\n\n`);
const handle = async (_url: string, init: RequestInit): Promise<Response> => {
if ((init.method ?? "GET").toUpperCase() !== "POST") return new Response(null, { status: 404 });
const body = JSON.parse(String(init.body));
const headers = new Headers(init.headers);
requests.push({ method: body.method ?? "(reply)", headers, body });
if (body.method === "initialize") {
return Response.json({ jsonrpc: "2.0", id: body.id, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "legacy", version: "1" } } },
{ headers: { "Mcp-Session-Id": `legacy-${++sessions}` } });
}
if (!headers.get("mcp-session-id")) return Response.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: "Bad Request: No valid session ID provided" } }, { status: 400 });
if (body.method === "notifications/initialized") return new Response(null, { status: 202 });
if (!body.method && body.id) {
if (refuseReplies > 0) { refuseReplies -= 1; return new Response(null, { status: 500 }); }
replies.push(body);
waiting.get(String(body.id))?.(body);
return new Response(null, { status: 202 });
}
if (body.method === "tools/list") return Response.json({ jsonrpc: "2.0", id: body.id, result: { tools: [{ name: "create_ticket", description: "x", inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint: true } }] } });
if (body.method === "tools/call") {
const stream = new ReadableStream<Uint8Array>({
async start(controller) {
const answers: unknown[] = [];
for (const question of questions) {
const askId = `ask-${++asks}`;
const reply = new Promise<Record<string, any>>((resolve) => waiting.set(askId, resolve));
controller.enqueue(sse({ jsonrpc: "2.0", id: askId, method: "elicitation/create", params: { message: question.message,
requestedSchema: { type: "object", properties: { [question.key]: { type: "string", enum: question.values } }, required: [question.key] } } }));
let answer = await reply;
if (answer.result?.action !== "accept") { controller.close(); return; }
// The app asks the same question again to have the answer corrected.
if (question.askAgainIf !== undefined && answer.result.content?.[question.key] === question.askAgainIf) {
const againId = `ask-${++asks}`;
const again = new Promise<Record<string, any>>((resolve) => waiting.set(againId, resolve));
controller.enqueue(sse({ jsonrpc: "2.0", id: againId, method: "elicitation/create", params: { message: question.message,
requestedSchema: { type: "object", properties: { [question.key]: { type: "string", enum: question.values } }, required: [question.key] } } }));
answer = await again;
if (answer.result?.action !== "accept") { controller.close(); return; }
}
answers.push(answer.result);
}
const text = answers.length === 1 ? `answer: ${JSON.stringify(answers[0])}` : `answers: ${JSON.stringify(answers)}`;
controller.enqueue(sse({ jsonrpc: "2.0", id: body.id, result: { content: [{ type: "text", text }] } }));
controller.close();
},
});
return new Response(stream, { headers: { "content-type": "text/event-stream" } });
}
return Response.json({ jsonrpc: "2.0", id: body.id, error: { code: -32601, message: "Method not found" } });
};
return { requests, replies, handle, calls: () => requests.filter((request) => request.method === "tools/call"), refuseNextReply: () => { refuseReplies = 1; } };
}
const support = await getEmbeddedPostgresTestSupport();
(support.supported ? describe : describe.skip)("MCP form elicitation end to end", () => {
const actor = { actorType: "user" as const, actorId: "mcp-elicitation-user", actorSource: "local_implicit" as const };
let fixture: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
let db: ReturnType<typeof createDb>;
let keyDir: string;
beforeAll(async () => {
keyDir = await mkdtemp(join(tmpdir(), "mcp-elicitation-secrets-"));
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key"));
fixture = await startEmbeddedPostgresTestDatabase("mcp-elicitation-");
db = createDb(fixture.connectionString);
}, 30_000);
afterAll(async () => {
await fixture?.cleanup();
vi.unstubAllEnvs();
if (keyDir) await rm(keyDir, { recursive: true, force: true });
});
async function setup(handle: (url: string, init: RequestInit) => Promise<Response>, input: { askFirst?: string[] } = {}) {
const [org] = await db.insert(companies).values({ name: `Elicit ${randomUUID()}`, issuePrefix: `E${randomUUID().slice(0, 5)}` }).returning();
await db.insert(companyMemberships).values({ companyId: org!.id, principalType: "user", principalId: actor.actorId, status: "active", membershipRole: "admin" });
const [agent] = await db.insert(agents).values({ companyId: org!.id, name: "Ticket agent", role: "engineer", adapterType: "process", adapterConfig: {}, runtimeConfig: {} }).returning();
const [project] = await db.insert(projects).values({ companyId: org!.id, name: "Tickets" }).returning();
const [issue] = await db.insert(issues).values({ companyId: org!.id, projectId: project!.id, title: "File the bug", status: "in_progress", assigneeAgentId: agent!.id }).returning();
const [run] = await db.insert(heartbeatRuns).values({ companyId: org!.id, agentId: agent!.id, invocationSource: "assignment", status: "running", contextSnapshot: { issueId: issue!.id, projectId: project!.id } }).returning();
const options = { deploymentMode: "local_trusted" as const, deploymentExposure: "private" as const,
remoteHttpEndpointLookup: async () => [{ address: "8.8.8.8", family: 4 as const }], remoteHttpRequest: handle };
const service = toolAccessService(db, options);
const connected = await service.connectGalleryApp(org!.id, { link: `https://ask-${randomUUID().slice(0, 8)}.example.com/mcp`, name: "Tracker" }, actor);
await service.finishGalleryAppConnection(org!.id, connected.connectionId, {
enabledCatalogEntryIds: connected.catalog.map((entry) => entry.id),
askFirstCatalogEntryIds: connected.catalog.filter((entry) => input.askFirst?.includes(entry.toolName)).map((entry) => entry.id), access: "all_agents",
}, actor);
const gatewayOptions = { ...options, toolActionSigningSecret: "elicitation-signing-key" };
let gateway = createToolGatewayService(db, gatewayOptions);
let session = await gateway.createSession({ companyId: org!.id, agentId: agent!.id, runId: run!.id });
const names = (await gateway.listToolsForSession(session.token)).map((tool) => tool.name);
const toolName = (name: string) => names.find((candidate) => candidate.endsWith(`:${name.replace(/_/g, "-")}`))!;
const call = (name: string, parameters: Record<string, unknown> = { ref: "main" }, extra: { idempotencyKey?: string; tenant?: string } = {}) =>
gateway.executeTool({ sessionToken: session.token, tool: toolName(name), parameters, timeoutMs: 5_000,
idempotencyKey: extra.idempotencyKey, ...(extra.tenant ? { callerHeaders: { "x-tenant-id": extra.tenant } } : {}) });
const cards = () => db.select().from(issueThreadInteractions)
.where(and(eq(issueThreadInteractions.companyId, org!.id), eq(issueThreadInteractions.issueId, issue!.id)))
.orderBy(issueThreadInteractions.createdAt);
const interactions = issueThreadInteractionService(db);
const answer = (cardId: string, answers: Array<{ questionId: string; optionIds: string[]; otherText?: string }>) =>
interactions.answerQuestions({ id: issue!.id, companyId: org!.id }, cardId, { answers }, { userId: actor.actorId });
const skip = (cardId: string) => interactions.skipInteraction({ id: issue!.id, companyId: org!.id }, cardId, {}, { userId: actor.actorId });
const rounds = () => db.select().from(toolMcpElicitations).where(eq(toolMcpElicitations.companyId, org!.id));
return {
org: org!, agent: agent!, issue: issue!, run: run!, connected, call, cards, answer, skip, rounds, interactions,
gateway: () => gateway,
/** A call from another run of the agent on the same task, with its own session. */
callerInAnotherRun: async () => {
const [other] = await db.insert(heartbeatRuns).values({ companyId: org!.id, agentId: agent!.id, invocationSource: "assignment", status: "running", contextSnapshot: { issueId: issue!.id } }).returning();
const otherSession = await gateway.createSession({ companyId: org!.id, agentId: agent!.id, runId: other!.id });
return (name: string, parameters: Record<string, unknown>) =>
gateway.executeTool({ sessionToken: otherSession.token, tool: toolName(name), parameters, timeoutMs: 5_000 });
},
/** The agent's next run on the task (a woken agent). */
nextRun: async () => {
const [next] = await db.insert(heartbeatRuns).values({ companyId: org!.id, agentId: agent!.id, invocationSource: "assignment", status: "running", contextSnapshot: { issueId: issue!.id } }).returning();
session = await gateway.createSession({ companyId: org!.id, agentId: agent!.id, runId: next!.id });
},
/** A new process: only the database survives. */
restart: async () => {
forgetMcpHttpSessions(connected.connectionId);
gateway = createToolGatewayService(db, gatewayOptions);
session = await gateway.createSession({ companyId: org!.id, agentId: agent!.id, runId: run!.id });
},
};
}
it("puts a stateless server's form on a human-only card and sends the answer with the exact state on the repeated call", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
const first = await ctx.call("create_ticket").catch((error) => error);
expect(first).toMatchObject({ reasonCode: "elicitation_required", message: expect.stringContaining("Tracker asked a question") });
expect(server.calls()[0]!.body.params._meta[META_CAPABILITIES].elicitation).toEqual({ form: {}, url: {} });
const [card] = await ctx.cards();
expect(card).toMatchObject({ kind: "ask_user_questions", status: "pending", title: "Tracker needs your input", requestedResolverPolicy: "human_only" });
expect(card!.payload).toMatchObject({ questionSet: { description: "Tell us about the ticket", submitLabel: "Send to Tracker" } });
const [round] = await ctx.rounds();
expect(round).toMatchObject({ status: "waiting", era: "modern", issueId: ctx.issue.id });
// The server's state is never stored readable.
expect(round!.sealedRequestState).not.toContain("state-for-main");
const [invocation] = await db.select().from(toolInvocations).where(eq(toolInvocations.id, round!.invocationId));
expect(invocation).toMatchObject({ status: "awaiting_approval", errorCode: "elicitation_required" });
// Repeating before anyone answers waits again and never reaches the app.
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
expect(server.calls()).toHaveLength(1);
// An agent can't answer its own tool's question.
await expect(ctx.interactions.answerQuestions({ id: ctx.issue.id, companyId: ctx.org.id }, card!.id,
{ answers: [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Nope" }] }, { agentId: ctx.agent.id, runId: ctx.run.id }))
.rejects.toBeTruthy();
await ctx.answer(card!.id, [
{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Login broken" },
{ questionId: "priority", optionIds: ["choice_1"] },
{ questionId: "labels", optionIds: ["choice_2"] },
{ questionId: "count", optionIds: ["paperclip_text_answer"], otherText: "2" },
]);
const done = await ctx.call("create_ticket");
expect(done).toMatchObject({ status: "completed" });
const retried = server.calls()[1]!;
expect(retried.body.id).not.toBe(server.calls()[0]!.body.id);
expect(retried.body.params.requestState).toBe("state-for-main");
expect(retried.body.params.inputResponses).toEqual({ details: { action: "accept", content: { title: "Login broken", priority: "p1", labels: ["ux"], count: 2 } } });
expect((await ctx.rounds())[0]).toMatchObject({ status: "sent" });
// Sent once: the same call in a later run is a fresh call.
await ctx.nextRun();
await ctx.call("create_ticket").catch(() => undefined);
expect(server.calls()[2]!.body.params).not.toHaveProperty("inputResponses");
const logged = await db.select().from(activityLog).where(and(eq(activityLog.companyId, ctx.org.id), eq(activityLog.action, "tool_gateway.elicitation_sent")));
expect(logged).toHaveLength(1);
// Which kind of answer went back, never the words.
expect(JSON.stringify(logged[0]!.details)).not.toContain("Login broken");
expect(logged[0]!.details).toMatchObject({ responses: ["accept"] });
});
it("sends decline when the person skips, and survives a restart while waiting", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "skip" }).catch(() => undefined);
const [card] = await ctx.cards();
await ctx.restart();
await ctx.skip(card!.id);
await ctx.call("create_ticket", { ref: "skip" });
expect(server.calls()[1]!.body.params).toMatchObject({ requestState: "state-for-skip", inputResponses: { details: { action: "decline" } } });
});
it("asks two questions at once and sends both answers in one repeated call", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
expect(await ctx.call("two_questions").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required", details: { interactionIds: [expect.any(String), expect.any(String)] } });
const [owner, go] = await ctx.cards();
await ctx.answer(owner!.id, [{ questionId: "owner", optionIds: ["paperclip_text_answer"], otherText: "Ada" }]);
// One answered, one still waiting: no send.
expect(await ctx.call("two_questions").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
expect(server.calls()).toHaveLength(1);
await ctx.interactions.withdrawInteraction({ id: ctx.issue.id, companyId: ctx.org.id }, go!.id, {}, { userId: actor.actorId }).catch(async () => {
await db.update(issueThreadInteractions).set({ status: "cancelled", result: { version: 1, answers: [], outcome: "withdrawn" } }).where(eq(issueThreadInteractions.id, go!.id));
});
await ctx.call("two_questions");
expect(server.calls()[1]!.body.params).toMatchObject({
requestState: "two-state",
inputResponses: { who: { action: "accept", content: { owner: "Ada" } }, go: { action: "cancel" } },
});
});
it("refuses a form asking for a password: no card, a clear reason for the agent", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
expect(await ctx.call("ask_secret").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_sensitive_refused", message: expect.stringContaining("secure link") });
expect(await ctx.cards()).toHaveLength(0);
expect(await ctx.rounds()).toHaveLength(0);
});
it("reclaims a send interrupted by a crash, and never lets another company collect the round", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "crash" }).catch(() => undefined);
const [card] = await ctx.cards();
await ctx.answer(card!.id, [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "After crash" }, { questionId: "priority", optionIds: ["choice_2"] }]);
// A process died mid-send: the claim is held but its time has passed.
const [round] = await ctx.rounds();
await db.update(toolMcpElicitations).set({ claimedUntil: new Date(Date.now() - 1_000) }).where(eq(toolMcpElicitations.id, round!.id));
// Another company with the same app and arguments starts its own call.
const other = await setup(server.handle);
await other.call("create_ticket", { ref: "crash" }).catch(() => undefined);
expect(server.calls().at(-1)!.body.params).not.toHaveProperty("inputResponses");
await ctx.restart();
await ctx.call("create_ticket", { ref: "crash" });
expect(server.calls().at(-1)!.body.params).toMatchObject({ requestState: "state-for-crash", inputResponses: { details: { action: "accept", content: { title: "After crash", priority: "p2" } } } });
});
it("withdraws an expired round's card and starts the call over", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "late" }).catch(() => undefined);
await db.update(toolMcpElicitations).set({ expiresAt: new Date(Date.now() - 1_000) }).where(eq(toolMcpElicitations.companyId, ctx.org.id));
expect(await ctx.call("create_ticket", { ref: "late" }).catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
expect(server.calls()[1]!.body.params).not.toHaveProperty("inputResponses");
const [stale, fresh] = await ctx.cards();
expect(stale!.status).not.toBe("pending");
expect(fresh!.status).toBe("pending");
expect((await ctx.rounds()).map((round) => round.status).sort()).toEqual(["expired", "waiting"]);
});
it("answers an older server's question: cancel at once the first time, then the person's answer on the repeated call", async () => {
const server = legacyAskingServer();
const ctx = await setup(server.handle);
// The listing session only reads: it declares no questions.
expect(server.requests.find((request) => request.method === "initialize")!.body.params.capabilities).not.toHaveProperty("elicitation");
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
// The tool call's own session asked for 2025-11-25, which knows form and URL questions.
const initialize = server.requests.filter((request) => request.method === "initialize").at(-1)!;
expect(initialize.body.params.capabilities.elicitation).toEqual({ form: {}, url: {} });
// The server was never left waiting.
expect(server.replies.map((reply) => reply.result)).toEqual([{ action: "cancel" }]);
const [card] = await ctx.cards();
expect(card).toMatchObject({ title: "Tracker needs your input", requestedResolverPolicy: "human_only" });
await ctx.answer(card!.id, [{ questionId: "team", optionIds: ["choice_2"] }]);
const done = await ctx.call("create_ticket");
expect(done).toMatchObject({ status: "completed", result: { content: 'answer: {"action":"accept","content":{"team":"eng"}}' } });
expect(server.replies.map((reply) => reply.result)).toEqual([{ action: "cancel" }, { action: "accept", content: { team: "eng" } }]);
expect((await ctx.rounds())[0]).toMatchObject({ era: "legacy", status: "sent" });
// Spent: the same call in a later run asks again.
await ctx.nextRun();
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
expect(await ctx.cards()).toHaveLength(2);
});
it("never lets one forwarded tenant collect another tenant's answers", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
const [connection] = await db.select().from(toolConnections).where(eq(toolConnections.id, ctx.connected.connectionId));
await db.update(toolConnections).set({ config: { ...connection!.config, headerPolicy: { passthrough: { allow: ["x-tenant-id"] } } } })
.where(eq(toolConnections.id, ctx.connected.connectionId));
await ctx.call("create_ticket", { ref: "t" }, { tenant: "acme" }).catch(() => undefined);
const [card] = await ctx.cards();
await ctx.answer(card!.id, [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Acme only" }, { questionId: "priority", optionIds: ["choice_1"] }]);
await ctx.call("create_ticket", { ref: "t" }, { tenant: "globex" }).catch(() => undefined);
const globex = server.calls().at(-1)!;
expect(globex.headers.get("x-tenant-id")).toBe("globex");
expect(globex.body.params).not.toHaveProperty("inputResponses");
await ctx.call("create_ticket", { ref: "t" }, { tenant: "acme" });
const acme = server.calls().at(-1)!;
expect(acme.headers.get("x-tenant-id")).toBe("acme");
expect(acme.body.params.inputResponses).toMatchObject({ details: { action: "accept", content: { title: "Acme only" } } });
});
it("makes a missing card again under the same key when the process stopped before showing it", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "lost" }).catch(() => undefined);
const [round] = await ctx.rounds();
// The round was saved, but its card never reached the task.
await db.delete(issueThreadInteractions).where(eq(issueThreadInteractions.issueId, ctx.issue.id));
expect(await ctx.call("create_ticket", { ref: "lost" }).catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
expect(server.calls()).toHaveLength(1);
const [card] = await ctx.cards();
expect(card).toMatchObject({ idempotencyKey: round!.questions[0]!.cardKey, status: "pending" });
await ctx.answer(card!.id, [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Recovered" }, { questionId: "priority", optionIds: ["choice_2"] }]);
await ctx.call("create_ticket", { ref: "lost" });
expect(server.calls()[1]!.body.params.inputResponses).toMatchObject({ details: { action: "accept", content: { title: "Recovered" } } });
});
it("runs a keyed retry again only for the same request", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "a" }, { idempotencyKey: "ticket-key" }).catch(() => undefined);
const other = await ctx.call("create_ticket", { ref: "b" }, { idempotencyKey: "ticket-key" }).catch((error) => error);
expect(other).not.toMatchObject({ status: "completed" });
expect(server.calls()).toHaveLength(1);
expect((await ctx.rounds())[0]).toMatchObject({ status: "waiting" });
});
it("keeps an older server's answer when the server refuses the reply", async () => {
const server = legacyAskingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket").catch(() => undefined);
const [card] = await ctx.cards();
await ctx.answer(card!.id, [{ questionId: "team", optionIds: ["choice_1"] }]);
server.refuseNextReply();
await ctx.nextRun();
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "mcp_remote_status" });
// Not spent and not held: the next call sends it again.
expect((await ctx.rounds())[0]).toMatchObject({ status: "waiting", claimedUntil: null });
await ctx.nextRun();
expect(await ctx.call("create_ticket")).toMatchObject({ status: "completed", result: { content: 'answer: {"action":"accept","content":{"team":"ops"}}' } });
expect((await ctx.rounds())[0]).toMatchObject({ status: "sent" });
});
it("keeps an older server's earlier answers until the whole call finishes", async () => {
const server = legacyAskingServer({ questions: [
{ message: "Which team?", key: "team", values: ["ops", "eng"] },
{ message: "Which size?", key: "size", values: ["s", "m"] },
] });
const ctx = await setup(server.handle);
await ctx.call("create_ticket").catch(() => undefined);
const [teamCard] = await ctx.cards();
await ctx.answer(teamCard!.id, [{ questionId: "team", optionIds: ["choice_2"] }]);
await ctx.nextRun();
// The team answer goes back, then the app asks its second question.
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
const [, sizeCard] = await ctx.cards();
await ctx.answer(sizeCard!.id, [{ questionId: "size", optionIds: ["choice_1"] }]);
await ctx.nextRun();
const done = await ctx.call("create_ticket");
expect(done).toMatchObject({ status: "completed", result: { content: 'answers: [{"action":"accept","content":{"team":"eng"}},{"action":"accept","content":{"size":"s"}}]' } });
// Nobody was asked the first question twice.
expect(await ctx.cards()).toHaveLength(2);
expect((await ctx.rounds()).map((round) => round.status)).toEqual(["sent", "sent"]);
});
it("sends the answer again in the same run after the app failed to take it", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "flaky" }).catch(() => undefined);
const [card] = await ctx.cards();
await ctx.answer(card!.id, [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Second try" }, { questionId: "priority", optionIds: ["choice_1"] }]);
server.refuseNextAnswer();
expect(await ctx.call("create_ticket", { ref: "flaky" }).catch((error) => error)).toMatchObject({ reasonCode: "mcp_remote_status" });
// Same run, same request: not a replay of the failure; the answer goes out again.
expect(await ctx.call("create_ticket", { ref: "flaky" })).toMatchObject({ status: "completed" });
expect(server.calls()).toHaveLength(3);
expect(server.calls()[2]!.body.params.inputResponses).toMatchObject({ details: { action: "accept", content: { title: "Second try" } } });
expect((await ctx.rounds())[0]).toMatchObject({ status: "sent" });
});
it("shows one card when two matching calls ask at the same time", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
const first = await ctx.callerInAnotherRun();
const second = await ctx.callerInAnotherRun();
const results = await Promise.all([
first("create_ticket", { ref: "race" }).catch((error) => error),
second("create_ticket", { ref: "race" }).catch((error) => error),
]);
for (const result of results) expect(result).toMatchObject({ reasonCode: "elicitation_required" });
expect(await ctx.cards()).toHaveLength(1);
expect((await ctx.rounds()).filter((round) => round.status === "waiting")).toHaveLength(1);
});
it("continues a stateless app's follow-up question after the first answer", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("two_rounds").catch(() => undefined);
const [first] = await ctx.cards();
await ctx.answer(first!.id, [{ questionId: "team", optionIds: ["choice_2"] }]);
expect(await ctx.call("two_rounds").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
// The first round is spent and the follow-up is saved; nothing is lost between them.
expect((await ctx.rounds()).map((round) => round.status).sort()).toEqual(["sent", "waiting"]);
const [, second] = await ctx.cards();
await ctx.answer(second!.id, [{ questionId: "due", optionIds: ["paperclip_text_answer"], otherText: "2026-12-01" }]);
await ctx.call("two_rounds");
expect(server.calls().at(-1)!.body.params).toMatchObject({ requestState: "round-2", inputResponses: { second: { action: "accept", content: { due: "2026-12-01" } } } });
});
it("asks again on a fresh card when an older app repeats a question to correct the answer", async () => {
const server = legacyAskingServer({ questions: [{ message: "Which team?", key: "team", values: ["ops", "eng"], askAgainIf: "ops" }] });
const ctx = await setup(server.handle);
await ctx.call("create_ticket").catch(() => undefined);
const [first] = await ctx.cards();
await ctx.answer(first!.id, [{ questionId: "team", optionIds: ["choice_1"] }]);
await ctx.nextRun();
// The app takes "ops", then asks again: a second card, not a stall.
expect(await ctx.call("create_ticket").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
const cards = await ctx.cards();
expect(cards).toHaveLength(2);
await ctx.answer(cards[1]!.id, [{ questionId: "team", optionIds: ["choice_2"] }]);
await ctx.nextRun();
expect(await ctx.call("create_ticket")).toMatchObject({ status: "completed", result: { content: 'answer: {"action":"accept","content":{"team":"eng"}}' } });
});
it("advances to a follow-up question even when the task is at its open-question limit", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("two_rounds").catch(() => undefined);
const [round] = await ctx.rounds();
// Nine other questions are waiting on the task: ten in all, the limit.
await db.insert(toolMcpElicitations).values(Array.from({ length: 9 }, (_, index) => ({
...round!, id: randomUUID(), callIdentity: `other-call-${index}`, dedupeKey: `other-${index}`, createdAt: new Date(), updatedAt: new Date(),
})));
const [first] = await ctx.cards();
await ctx.answer(first!.id, [{ questionId: "team", optionIds: ["choice_1"] }]);
expect(await ctx.call("two_rounds").catch((error) => error)).toMatchObject({ reasonCode: "elicitation_required" });
// The answered round made room for its own follow-up.
expect(await ctx.cards()).toHaveLength(2);
expect((await ctx.rounds()).filter((row) => row.status === "waiting")).toHaveLength(10);
});
it("keeps an approved action's approval while its question waits, and sends the answer without asking again", async () => {
const server = askingServer();
const ctx = await setup(server.handle, { askFirst: ["create_ticket"] });
await expect(ctx.call("create_ticket", { ref: "approved" })).rejects.toMatchObject({ reasonCode: "approval_required" });
const [pending] = await db.select().from(toolActionRequests).where(eq(toolActionRequests.companyId, ctx.org.id));
if (pending!.approvalId) await db.update(approvals).set({ status: "approved", decidedByUserId: actor.actorId, decidedAt: new Date() }).where(eq(approvals.id, pending!.approvalId));
// The approved execution reaches the app, which asks a question.
await ctx.gateway().approveActionRequest({ companyId: ctx.org.id, actionRequestId: pending!.id, actor: { userId: actor.actorId } }).catch((error) => error);
expect(server.calls()).toHaveLength(1);
const [request] = await db.select().from(toolActionRequests).where(eq(toolActionRequests.id, pending!.id));
expect(request).toMatchObject({ status: "approved" });
const card = (await ctx.cards()).find((candidate) => candidate.kind === "ask_user_questions")!;
await ctx.answer(card.id, [{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Approved and answered" }, { questionId: "priority", optionIds: ["choice_1"] }]);
// The repeated call continues the approved action: no second approval, the answer goes out.
// An approved action's continuation is reported with its result (status "replayed").
const done = await ctx.call("create_ticket", { ref: "approved" });
expect(JSON.stringify(done.result)).toContain("Approved and answered");
expect(server.calls()).toHaveLength(2);
expect(server.calls()[1]!.body.params.inputResponses).toMatchObject({ details: { action: "accept", content: { title: "Approved and answered" } } });
});
it("marks an app's question card so skipping it wakes the agent (route test: issue-thread-interaction-routes)", async () => {
const server = askingServer();
const ctx = await setup(server.handle);
await ctx.call("create_ticket", { ref: "skip-wake" }).catch(() => undefined);
const [card] = await ctx.cards();
const { isAppQuestionCardKey } = await import("../services/mcp-elicitation.js");
expect(isAppQuestionCardKey(card!.idempotencyKey)).toBe(true);
});
});
@@ -504,6 +504,8 @@ const support = await getEmbeddedPostgresTestSupport();
forgetMcpHttpSessions(connected.connectionId);
expect(await call("lookup")).toMatchObject({ decision: "allowed", result: { data: { isError: false } } });
expect(legacy.methods()).toEqual(["tools/call", "initialize", "notifications/initialized", "tools/call"]);
// The fallback opens the tool call's own session, which can answer form questions (2025-06-18: `{}`).
expect(legacy.requests.find((request) => request.method === "initialize")!.body.params.capabilities.elicitation).toEqual({});
expect(await savedConfig()).toMatchObject({ mcpProtocolVersion: "2025-06-18" });
});
@@ -3080,14 +3080,17 @@ describeEmbeddedPostgres("tool gateway service", () => {
status: "pending",
issueId: session.issueId,
});
// The card names the app, only people answer it, and the provider's
// enum becomes a real choice (see MCP-ELICITATION.md).
expect(interaction).toMatchObject({ requestedResolverPolicy: "human_only", title: expect.stringMatching(/needs your input$/) });
expect(interaction.payload).toMatchObject({
title: "Which workspace should be used?",
questionSet: { description: "Which workspace should be used?" },
questions: [
{
id: "workspace",
prompt: "Workspace",
required: true,
options: [{ id: "ops", label: "ops" }, { id: "engineering", label: "engineering" }],
options: [{ id: "choice_1", label: "ops" }, { id: "choice_2", label: "engineering" }],
},
],
});