Files
PaperClipAI/server/src/__tests__/mcp-elicitation.test.ts
T
DottaandClaude Opus 5.5 a4c570aede 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>
2026-11-13 19:46:56 -06:00

697 lines
49 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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);
});
});