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" }],
},
],
});
+13
View File
@@ -1,4 +1,5 @@
import { assertAgentInteraction } from "../services/agent-interaction-policy.js";
import { isAppQuestionCardKey } from "../services/mcp-elicitation.js";
import { assertQueuedCommentInteractionDelivery, recheckQueuedCommentInteractionDelivery } from "../services/agent-interaction-delivery.js";
import { listStalledDependencies } from "../services/recovery/blocker-stall-wakeups.js";
import { confirmMcpAttachmentCleanup, recordMcpAttachmentCleanup, type McpAttachmentCleanup } from "../services/public-mcp/upload-cleanup.js";
@@ -19366,6 +19367,18 @@ export function issueRoutes(
// Skip intentionally does not enqueue an interaction continuation. A
// subsequent ordinary message uses the existing comment steering path.
// An app's question is the exception: skipping is the person's "no",
// which only reaches the app on the agent's next call, so wake it.
if (isAppQuestionCardKey(interaction.idempotencyKey)) {
await queueResolvedInteractionContinuationWakeup({
db,
heartbeat,
issue,
interaction,
actor,
source: "issue.interaction.skip",
});
}
res.json(interaction);
},
);
+365
View File
@@ -0,0 +1,365 @@
import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
import type { PaperclipQuestionSetPayload, PaperclipQuestionSetQuestion } from "@paperclipai/shared";
import { redactSensitiveText } from "../redaction.js";
/**
* MCP form elicitation (spec 2026-07-28, client/elicitation): the provider's
* question becomes a task-chat question card, and the person's answer on that
* card becomes the elicitation result. Used by direct tool calls (stateless
* `input_required` and older server-initiated `elicitation/create`) and by
* MCP Tasks, so every path shows the same card and sends the same answer.
*/
export type McpFormElicitation = {
message: string;
requestedSchema: Record<string, unknown> | null;
};
export type McpElicitationResponse =
| { action: "accept"; content: Record<string, unknown> }
| { action: "decline" }
| { action: "cancel" };
/** At most this many fields per question, and form questions per round. */
export const MCP_ELICITATION_MAX_FIELDS = 10;
export const MCP_ELICITATION_MAX_FORMS_PER_ROUND = 4;
const MAX_OPTIONS = 100;
type Built =
| { ok: true; questionSet: PaperclipQuestionSetPayload }
| { ok: false; reason: "sensitive"; fields: string[] }
| { ok: false; reason: "unsupported" };
function record(value: unknown): Record<string, unknown> | null {
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
}
function text(value: unknown): string | undefined {
return typeof value === "string" && value.trim() ? value.trim() : undefined;
}
/**
* Provider text is shown as plain words. Links in a form are not clickable
* (spec: Safe URL Handling), and secrets that slipped in are redacted.
*/
/** True for a card made from an app's question (direct or MCP Task), by its idempotency key. */
export function isAppQuestionCardKey(key: string | null | undefined): boolean {
return typeof key === "string" && (key.startsWith("mcp-elicit:") || key.startsWith("mcp-task-input:") || key.startsWith("mcp-elicitation:"));
}
export function elicitationPlainText(value: string, max: number): string {
return redactSensitiveText(value)
.replace(/[<>]/g, "")
.replace(/\]\(/g, "] (")
.replace(/:\/\//g, ":​//")
.slice(0, max);
}
// Secrets must go through a URL (spec: Form Mode Security). Matched on the
// field's name, title, and description.
const SENSITIVE_FIELD =
/pass(?:word|wd|code|phrase)|secret|api[\s_-]?key|(?:access|refresh|auth|bearer|session|api)[\s_-]?token|\btokens?\b|credential|private[\s_-]?key|card[\s_-]?(?:number|no\b)|\bcvv\b|\bcvc\b|security[\s_-]?code|\bssn\b|social[\s_-]?security|one[\s_-]?time[\s_-]?(?:code|password)|\botp\b|\b2fa\b|\bmfa\b/i;
// The same secrets, asked for in the form's own words ("type your password
// in the notes field"). A bare "token" is left out: in prose it is too common.
const SENSITIVE_MESSAGE =
/pass(?:word|wd|code|phrase)|secret|api[\s_-]?key|(?:access|refresh|auth|bearer|session|api)[\s_-]?token|credential|private[\s_-]?key|card[\s_-]?(?:number|no\b)|\bcvv\b|\bcvc\b|security[\s_-]?code|\bssn\b|social[\s_-]?security|one[\s_-]?time[\s_-]?(?:code|password)|\botp\b|\b2fa\b|\bmfa\b/i;
/** Field keys that ask for a secret; empty when the form is safe to show. */
export function elicitationSensitiveFields(schema: Record<string, unknown> | null): string[] {
const properties = record(schema?.properties) ?? {};
return Object.entries(properties).filter(([key, raw]) => {
const property = record(raw) ?? {};
if (property.format === "password" || property.writeOnly === true) return true;
return [key, property.title, property.description].some((value) => typeof value === "string" && SENSITIVE_FIELD.test(value));
}).map(([key]) => key);
}
type Choice = { value: unknown; label: string };
/** Enum choices from `enum`, `oneOf`/`anyOf` with `const`+`title` (SEP-1330). */
function choicesOf(schema: Record<string, unknown>): Choice[] | null {
if (Array.isArray(schema.enum)) {
const titles = Array.isArray(schema.enumNames) ? schema.enumNames : [];
return schema.enum.map((value, index) => ({ value, label: String(text(titles[index]) ?? value) }));
}
const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : null;
if (!variants) return null;
const choices: Choice[] = [];
for (const variant of variants) {
const entry = record(variant);
if (!entry || !("const" in entry)) return null;
choices.push({ value: entry.const, label: String(text(entry.title) ?? entry.const) });
}
return choices;
}
const primitive = (value: unknown) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
const optionId = (index: number) => `choice_${index + 1}`;
type Field = { key: string; property: Record<string, unknown>; question: PaperclipQuestionSetQuestion; choices?: Choice[]; kind: "text" | "number" | "integer" | "boolean" | "single" | "multi" };
// Patterns stay within the fixed-width subset the question form can check
// safely (no repetition), so an email is a hint and the app validates it.
const FORMAT_HINT: Record<string, { help: string; pattern?: string }> = {
email: { help: "An email address." },
uri: { help: "A web address." },
date: { help: "A date, like 2026-11-13.", pattern: "^\\d\\d\\d\\d-\\d\\d-\\d\\d$" },
"date-time": { help: "A date and time, like 2026-11-13T09:30:00Z." },
};
function fieldFor(key: string, raw: unknown, required: boolean): Field | null {
const property = record(raw);
if (!property) return null;
const prompt = elicitationPlainText(text(property.title) ?? key, 4000);
const description = text(property.description);
const help = (extra?: string) => {
const value = [description ? elicitationPlainText(description, 3000) : null, extra].filter(Boolean).join(" ");
return value ? { helpText: value.slice(0, 4000) } : {};
};
const base = { id: key.slice(0, 160), prompt, required };
const select = (choices: Choice[], multi: boolean, defaults: unknown[], extra?: string): Field | null => {
if (!choices.length || choices.length > MAX_OPTIONS || !choices.every((choice) => primitive(choice.value))) return null;
return {
key, property, choices, kind: multi ? "multi" : "single",
question: {
...base, ...help(extra), answerMode: multi ? "multi_select" : "single_select",
options: choices.map((choice, index) => ({
id: optionId(index), label: elicitationPlainText(choice.label, 1000) || `Option ${index + 1}`,
...(defaults.some((value) => value === choice.value) ? { recommended: true } : {}),
})),
},
};
};
const type = property.type;
if (type === "array") {
const items = record(property.items);
const choices = items ? choicesOf(items) : null;
if (!choices) return null;
const limits = [
typeof property.minItems === "number" ? `Choose at least ${property.minItems}.` : null,
typeof property.maxItems === "number" ? `Choose at most ${property.maxItems}.` : null,
].filter(Boolean).join(" ");
return select(choices, true, Array.isArray(property.default) ? property.default : [], limits || undefined);
}
const choices = choicesOf(property);
if (choices) return select(choices, false, property.default === undefined ? [] : [property.default]);
if (type === "boolean") {
return select([{ value: true, label: "Yes" }, { value: false, label: "No" }], false, property.default === undefined ? [] : [property.default]);
}
if (type === "number" || type === "integer") {
const minimum = typeof property.minimum === "number" && Number.isFinite(property.minimum) ? property.minimum : undefined;
const maximum = typeof property.maximum === "number" && Number.isFinite(property.maximum) ? property.maximum : undefined;
if (minimum !== undefined && maximum !== undefined && minimum > maximum) return null;
return {
key, property, kind: type,
question: {
...base, ...help(), answerMode: "text",
...(typeof property.default === "number" ? { initialText: String(property.default) } : {}),
textValidation: { inputType: type, ...(minimum !== undefined ? { minimum } : {}), ...(maximum !== undefined ? { maximum } : {}) },
},
};
}
if (type === "string" || type === undefined) {
const format = typeof property.format === "string" ? FORMAT_HINT[property.format] : undefined;
if (typeof property.format === "string" && !format) return null;
const minLength = Number.isInteger(property.minLength) && (property.minLength as number) >= 0 ? Math.min(property.minLength as number, 100_000) : undefined;
const maxLength = Number.isInteger(property.maxLength) && (property.maxLength as number) >= 0 ? Math.min(property.maxLength as number, 100_000) : undefined;
if (minLength !== undefined && maxLength !== undefined && minLength > maxLength) return null;
const validation = {
...(minLength !== undefined ? { minLength } : {}),
...(maxLength !== undefined ? { maxLength } : {}),
...(format?.pattern ? { pattern: format.pattern } : {}),
};
return {
key, property, kind: "text",
question: {
...base, ...help(format?.help), answerMode: "text",
...(typeof property.default === "string" ? { initialText: property.default.slice(0, 100_000) } : {}),
...(Object.keys(validation).length ? { textValidation: validation } : {}),
},
};
}
return null;
}
function fieldsOf(schema: Record<string, unknown> | null): Field[] | null {
if (schema && schema.type !== undefined && schema.type !== "object") return null;
const properties = record(schema?.properties) ?? {};
const entries = Object.entries(properties);
if (entries.length > MCP_ELICITATION_MAX_FIELDS) return null;
const required = new Set(Array.isArray(schema?.required) ? schema.required.filter((key): key is string => typeof key === "string") : []);
const fields: Field[] = [];
for (const [key, raw] of entries) {
const field = fieldFor(key, raw, required.has(key));
if (!field) return null;
fields.push(field);
}
return fields;
}
/** The single "Continue" choice a form with no fields becomes. */
const CONTINUE_QUESTION_ID = "continue";
/**
* The card for one form question, or why Paperclip will not show it. A form
* asking for a secret is refused before anything is shown; a schema outside
* the spec's flat primitive subset is refused rather than shown partly.
*/
export function buildElicitationQuestionSet(input: { appName: string; request: McpFormElicitation }): Built {
const sensitive = elicitationSensitiveFields(input.request.requestedSchema);
// A form whose message asks for a secret is refused too, whatever its fields are called.
if (SENSITIVE_MESSAGE.test(input.request.message)) sensitive.unshift("message");
if (sensitive.length) return { ok: false, reason: "sensitive", fields: sensitive };
const fields = fieldsOf(input.request.requestedSchema);
if (!fields) return { ok: false, reason: "unsupported" };
const appName = elicitationPlainText(input.appName, 120) || "The app";
const description = elicitationPlainText(input.request.message, 4000) || `${appName} needs more information to continue.`;
const questions: PaperclipQuestionSetQuestion[] = fields.length
? fields.map((field) => field.question)
: [{ id: CONTINUE_QUESTION_ID, prompt: description, required: true, answerMode: "single_select", options: [{ id: "continue", label: "Continue" }] }];
return {
ok: true,
questionSet: {
schema: "paperclip.question_set.v1",
title: `${appName} needs your input`,
description,
submitLabel: `Send to ${appName}`.slice(0, 200),
questions,
},
};
}
type CardState = { status: string; result: unknown; payload?: unknown };
/**
* The elicitation result for a resolved card, or null while it waits.
* Answered: `accept` with typed content. Skipped: `decline` (the person said
* no). Anything else that ended the card (withdrawn, task closed, expired,
* cancelled): `cancel`, since nobody made a choice.
*/
export function elicitationResponseForCard(request: McpFormElicitation, card: CardState | null | undefined): McpElicitationResponse | null {
if (!card || card.status === "pending") return null;
const result = record(card.result);
if (card.status === "answered" && result?.outcome === undefined) {
// A card saved before typed fields (an MCP Task waiting across the
// upgrade) keeps its own options; read it the way it was built.
const payload = record(card.payload);
const content = payload && !payload.questionSet && Array.isArray(payload.questions)
? legacyCardContent(request, payload.questions, result)
: elicitationContent(request, result);
return { action: "accept", content };
}
if (card.status === "cancelled" && result?.outcome === "skipped") return { action: "decline" };
return { action: "cancel" };
}
/** Map a person's card answers back onto the provider's schema, typed. */
export function elicitationContent(request: McpFormElicitation, result: unknown): Record<string, unknown> {
const answers = (Array.isArray(record(result)?.answers) ? record(result)!.answers as unknown[] : [])
.map(record).filter((answer): answer is Record<string, unknown> => Boolean(answer));
const fields = fieldsOf(request.requestedSchema) ?? [];
const content: Record<string, unknown> = {};
for (const field of fields) {
const answer = answers.find((candidate) => candidate.questionId === field.question.id);
if (!answer) continue;
const optionIds = Array.isArray(answer.optionIds) ? answer.optionIds.filter((id): id is string => typeof id === "string") : [];
const chosen = (field.choices ?? []).filter((_, index) => optionIds.includes(optionId(index))).map((choice) => choice.value);
const typed = typeof answer.otherText === "string" ? answer.otherText.trim() : "";
if (field.kind === "multi") { content[field.key] = chosen; continue; }
if (field.kind === "single" || field.kind === "boolean") { if (chosen.length) content[field.key] = chosen[0]; continue; }
if (!typed) continue;
if (field.kind === "number" || field.kind === "integer") {
const value = Number(typed);
if (Number.isFinite(value) && (field.kind === "number" || Number.isInteger(value))) content[field.key] = value;
continue;
}
content[field.key] = typed;
}
return content;
}
/**
* Answers on a card built before typed fields: enum choices were listed in
* the schema's order, and everything else was a written answer.
*/
function legacyCardContent(request: McpFormElicitation, storedQuestions: unknown[], result: unknown): Record<string, unknown> {
const answers = (Array.isArray(record(result)?.answers) ? record(result)!.answers as unknown[] : [])
.map(record).filter((answer): answer is Record<string, unknown> => Boolean(answer));
const properties = record(request.requestedSchema?.properties);
const textOf = (answer: Record<string, unknown> | undefined) => typeof answer?.otherText === "string" ? answer.otherText.trim() : "";
if (!properties || !Object.keys(properties).length) {
const text = textOf(answers.find((answer) => answer.questionId === "response"));
return text ? { response: text } : {};
}
const content: Record<string, unknown> = {};
for (const [key, raw] of Object.entries(properties).slice(0, MCP_ELICITATION_MAX_FIELDS)) {
const property = record(raw) ?? {};
const answer = answers.find((candidate) => candidate.questionId === key.slice(0, 120));
if (!answer) continue;
const enumValues = Array.isArray(property.enum) ? property.enum : [];
const stored = storedQuestions.map(record).find((question) => question?.id === key.slice(0, 120));
const options = Array.isArray(stored?.options) ? stored!.options.map(record) : [];
const optionIds = Array.isArray(answer.optionIds) ? answer.optionIds : [];
const index = options.findIndex((option) => typeof option?.id === "string" && optionIds.includes(option.id));
if (index >= 0 && index < enumValues.length) { content[key] = enumValues[index]; continue; }
const text = textOf(answer);
if (!text) continue;
if (property.type === "number" || property.type === "integer") {
const value = Number(text);
if (Number.isFinite(value) && (property.type === "number" || Number.isInteger(value))) content[key] = value;
} else if (property.type === "boolean") {
if (/^(true|yes|y|1)$/i.test(text)) content[key] = true;
else if (/^(false|no|n|0)$/i.test(text)) content[key] = false;
} else {
content[key] = text;
}
}
return content;
}
/** Identifies one question by its words and schema, for answering an older server's repeat. */
export function elicitationQuestionHash(request: McpFormElicitation): string {
const canonical = (value: unknown): unknown => Array.isArray(value)
? value.map(canonical)
: record(value) ? Object.fromEntries(Object.keys(value as object).sort().map((key) => [key, canonical((value as Record<string, unknown>)[key])])) : value;
return createHash("sha256").update(JSON.stringify(["paperclip:mcp-elicitation-question:v1", request.message, canonical(request.requestedSchema ?? {})])).digest("hex");
}
/** A form request from a stateless `inputRequests` entry or an older `elicitation/create` message. */
export function formElicitationOf(params: Record<string, unknown>): McpFormElicitation | null {
if (params.mode !== undefined && params.mode !== "form") return null;
return {
message: typeof params.message === "string" ? params.message : "",
requestedSchema: record(params.requestedSchema),
};
}
/*
* The server's requestState is opaque and may carry authority, so it is sealed
* at rest, bound to the company and connection that received it.
*/
const STATE_CONTEXT = "paperclip:mcp-elicitation-state:v1";
const stateKey = (secret: string) => Buffer.from(hkdfSync("sha256", secret, Buffer.alloc(0), STATE_CONTEXT, 32));
const stateAad = (scope: { companyId: string; connectionId: string }) => Buffer.from(JSON.stringify([STATE_CONTEXT, scope.companyId, scope.connectionId]));
export function sealElicitationState(secret: string, scope: { companyId: string; connectionId: string }, value: string): string {
const iv = randomBytes(12);
const cipher = createCipheriv("aes-256-gcm", stateKey(secret), iv);
cipher.setAAD(stateAad(scope));
const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
return `v1.${iv.toString("base64url")}.${ciphertext.toString("base64url")}.${cipher.getAuthTag().toString("base64url")}`;
}
export function openElicitationState(secret: string, scope: { companyId: string; connectionId: string }, sealed: string): string | null {
const [version, iv, ciphertext, tag] = sealed.split(".");
if (version !== "v1" || !iv || ciphertext === undefined || !tag) return null;
try {
const decipher = createDecipheriv("aes-256-gcm", stateKey(secret), Buffer.from(iv, "base64url"));
decipher.setAAD(stateAad(scope));
decipher.setAuthTag(Buffer.from(tag, "base64url"));
return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString("utf8");
} catch {
return null;
}
}
+25 -10
View File
@@ -54,16 +54,25 @@ export function isModernMcpProtocolVersion(version: unknown): version is string
* they may then return URL input requests, which Paperclip shows as a link.
* Legacy sessions keep the handshake capabilities they have always received.
*/
export function mcpClientCapabilities(protocolVersion: string, options: { declareTasks?: boolean } = {}): Record<string, unknown> {
export function mcpClientCapabilities(protocolVersion: string, options: { declareTasks?: boolean; elicitationForm?: boolean } = {}): Record<string, unknown> {
const version: string = protocolVersion;
// The skills and tasks extensions are defined against stateless MCP only.
// Tasks are declared only where Paperclip can wait on one: a provider tool
// call over HTTP and the task requests themselves (spec: per request).
return isModernMcpProtocolVersion(protocolVersion)
? { elicitation: { url: {} }, extensions: {
...MCP_APPS_CLIENT_CAPABILITY, ...MCP_SKILLS_CLIENT_CAPABILITY,
...(options.declareTasks ? { [MCP_TASKS_EXTENSION_ID]: {} } : {}),
} }
: { extensions: MCP_APPS_CLIENT_CAPABILITY };
// Form questions are declared only where a person can answer them: an HTTP
// tool call that belongs to a task, or an HTTP session (whose questions
// outside a task are answered "cancel" at once). See MCP-ELICITATION.md.
if (isModernMcpProtocolVersion(protocolVersion)) {
return { elicitation: options.elicitationForm ? { form: {}, url: {} } : { url: {} }, extensions: {
...MCP_APPS_CLIENT_CAPABILITY, ...MCP_SKILLS_CLIENT_CAPABILITY,
...(options.declareTasks ? { [MCP_TASKS_EXTENSION_ID]: {} } : {}),
} };
}
// 2025-06-18 knows only form questions (`{}`); 2025-11-25 added URL mode.
const legacyElicitation = !options.elicitationForm ? null
: version >= "2025-11-25" ? { form: {}, url: {} }
: version >= "2025-06-18" ? {} : null;
return { ...(legacyElicitation ? { elicitation: legacyElicitation } : {}), extensions: MCP_APPS_CLIENT_CAPABILITY };
}
/** Newest version both sides support, or null when there is none. */
@@ -200,7 +209,7 @@ export type McpJsonRpcRequest = { id?: string | number; method: string; params?:
export function mcpHttpRequestInit(
headers: Record<string, string> | undefined,
message: McpJsonRpcRequest,
options: { toolInputSchema?: unknown; declareTasks?: boolean } = {},
options: { toolInputSchema?: unknown; declareTasks?: boolean; elicitationForm?: boolean } = {},
): { method: "POST"; headers: Record<string, string>; body: string } {
const requestHeaders = mcpHttpRequestHeaders(headers);
const protocolVersion = mcpProtocolVersionOf(headers);
@@ -211,7 +220,7 @@ export function mcpHttpRequestInit(
_meta: {
...record(params._meta),
[META_PROTOCOL_VERSION]: protocolVersion,
[META_CLIENT_CAPABILITIES]: mcpClientCapabilities(protocolVersion, { declareTasks: options.declareTasks }),
[META_CLIENT_CAPABILITIES]: mcpClientCapabilities(protocolVersion, { declareTasks: options.declareTasks, elicitationForm: options.elicitationForm }),
[META_CLIENT_INFO]: MCP_CLIENT_INFO,
},
};
@@ -436,6 +445,12 @@ type McpInitializeInput = {
requestId: string;
/** Identifies the server (connection + endpoint) so its era is probed once. */
eraKey?: string;
/**
* Declare form questions at `initialize`. Only for sessions whose every
* request answers a server's `elicitation/create` (tool calls); a session
* that only reads must not invite a question it would leave waiting.
*/
elicitationForm?: boolean;
};
type DiscoverOutcome = { protocolVersion: string; capabilities?: Record<string, unknown> } | { legacy: true };
@@ -543,7 +558,7 @@ async function initializeLegacyMcpHttpSession(input: McpInitializeInput, request
method: "initialize",
params: {
protocolVersion: requestedVersion,
capabilities: mcpClientCapabilities(requestedVersion),
capabilities: mcpClientCapabilities(requestedVersion, { elicitationForm: input.elicitationForm }),
clientInfo: MCP_CLIENT_INFO,
},
}),
+571 -193
View File
@@ -77,7 +77,7 @@ import { getAppDefinitionForApplicationKey, isConnectorFeatureEnabled } from "@p
import { instanceSettingsService } from "./instance-settings.js";
import { redactSensitiveText } from "../redaction.js";
import { spawn } from "node:child_process";
import { createHash, randomBytes, randomUUID } from "node:crypto";
import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
import { isDeepStrictEqual } from "node:util";
import {
and,
@@ -87,6 +87,7 @@ import {
gt,
inArray,
isNull,
lt,
lte,
ne,
or,
@@ -125,6 +126,7 @@ import {
toolMcpGatewayTokens,
toolMcpSkills,
toolMcpTasks,
toolMcpElicitations,
toolPolicies,
toolProfileBindings,
toolProfileEntries,
@@ -202,6 +204,17 @@ import {
mcpHttpRequestHeaders,
parseMcpHttpResponseBody,
} from "./mcp-http.js";
import {
buildElicitationQuestionSet,
elicitationQuestionHash,
elicitationResponseForCard,
formElicitationOf,
MCP_ELICITATION_MAX_FORMS_PER_ROUND,
openElicitationState,
sealElicitationState,
type McpElicitationResponse,
type McpFormElicitation,
} from "./mcp-elicitation.js";
import {
projectedConnectionHeaders,
projectedConnectionToolArguments,
@@ -581,6 +594,9 @@ type RemoteHttpErrorEvidence = {
// that passes while they are recorded must not turn them into a timeout.
const REMOTE_TOOL_CALL_WORKFLOW_REASON_CODES = new Set([
"elicitation_required",
"elicitation_sensitive_refused",
"elicitation_unsupported",
"elicitation_limit_reached",
"provider_interaction_required",
"provider_input_required",
"provider_retry_requested",
@@ -699,7 +715,8 @@ const MCP_CACHEABLE_CONTEXT_METHODS = new Set(["resources/list", "resources/read
* person action is recorded, so claiming "accept" would assert consent nobody
* gave. The next call goes out fresh and the server, which tracks out-of-band
* steps itself, decides. A bare `requestState` (try again) is kept for the
* retry because it asserts nothing. Form, sampling, and roots are not collected yet.
* retry because it asserts nothing. Form questions in a task go to a person
* first (see askElicitationRound); sampling and roots are not collected.
*/
export function mcpInputRequiredPending(inputRequired: McpInputRequired): {
answerable: boolean;
@@ -709,7 +726,11 @@ export function mcpInputRequiredPending(inputRequired: McpInputRequired): {
} {
const links: ToolUpstreamPending["links"] = [];
let message: string | undefined;
let forms = 0;
for (const request of Object.values(inputRequired.inputRequests)) {
// A form beside a link waits: the link goes first, and the server asks
// for the form again on the next call (spec: re-ask for missing input).
if (request.method === "elicitation/create" && (request.params.mode === undefined || request.params.mode === "form")) { forms += 1; continue; }
if (request.method !== "elicitation/create" || request.params.mode !== "url") return { answerable: false };
const checked = checkOAuthEndpointUrl(request.params.url);
if (!checked.ok) return { answerable: false };
@@ -717,7 +738,7 @@ export function mcpInputRequiredPending(inputRequired: McpInputRequired): {
if (!message && typeof request.params.message === "string") message = redactSensitiveText(request.params.message).slice(0, 4000);
}
if (!links.length) {
return inputRequired.requestState ? { answerable: true, retryState: inputRequired.requestState } : { answerable: false };
return inputRequired.requestState && !forms ? { answerable: true, retryState: inputRequired.requestState } : { answerable: false };
}
// The link flow shows up to eight; more is a clear stop, never a partial step.
if (links.length > MCP_MAX_INPUT_LINKS) return { answerable: false };
@@ -6521,103 +6542,50 @@ export function createToolGatewayService(
return { message, requestedSchema, raw: candidate };
}
function enumOptions(
values: unknown[],
): Array<{ id: string; label: string }> {
return values.slice(0, 10).map((value, index) => {
const label =
typeof value === "string" ||
typeof value === "number" ||
typeof value === "boolean"
? String(value)
: `Option ${index + 1}`;
return {
id: slugSegment(label, `option-${index + 1}`).slice(0, 120),
label: label.slice(0, 120),
};
});
}
function elicitationQuestions(request: McpElicitationRequest) {
const schema = request.requestedSchema;
const properties = asRecord(schema?.properties);
const required = Array.isArray(schema?.required)
? new Set(
schema.required.filter(
(item): item is string => typeof item === "string",
),
)
: new Set<string>();
const questions: Array<{
id: string;
prompt: string;
helpText?: string | null;
selectionMode: "single" | "multi";
required?: boolean;
options: Array<{
id: string;
label: string;
description?: string | null;
}>;
}> = [];
if (properties) {
for (const [key, rawProperty] of Object.entries(properties)) {
if (questions.length >= 10) break;
const property = asRecord(rawProperty) ?? {};
const enumValues = Array.isArray(property.enum) ? property.enum : [];
const options =
enumValues.length > 0
? enumOptions(enumValues)
: [{ id: "answer", label: "Provide answer" }];
questions.push({
id: key.slice(0, 120),
prompt: (
stringValue(property.title) ??
stringValue(property.description) ??
key
).slice(0, 500),
helpText:
enumValues.length > 0
? null
: "Use Other to enter the requested value.",
selectionMode: "single",
required: required.has(key),
options,
});
}
/** The connection's name, as the person knows the app. */
async function elicitationAppName(companyId: string, connectionId: string | null | undefined, tool?: ToolGatewayDescriptor) {
const named = tool?.applicationDisplayName?.trim();
if (named) return named;
if (connectionId) {
const [connection] = await db.select({ name: toolConnections.name }).from(toolConnections)
.where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))).limit(1);
if (connection?.name.trim()) return connection.name.trim();
}
if (questions.length > 0) return questions;
return [
{
id: "response",
prompt: request.message.slice(0, 500),
helpText: "Use Other to enter the requested response.",
selectionMode: "single" as const,
required: true,
options: [{ id: "answer", label: "Provide response" }],
},
];
return "The app";
}
/** The question card a provider's input request becomes; answering it wakes the assignee. */
function createElicitationCard(input: {
companyId: string; issueId: string; agentId: string | null; toolName: string;
request: McpElicitationRequest; idempotencyKey: string;
/** Why a provider's form was not shown; the agent reads this, the person sees no card. */
function elicitationRefusedError(appName: string, built: { reason: "sensitive" | "unsupported" }, invocationId?: string) {
return built.reason === "sensitive"
? new ToolGatewayHttpError(409,
`${appName} asked for a password, key, or other secret in a form. Paperclip doesn't collect secrets that way, so nothing was shown. The app must ask for it through a secure link instead.`,
"elicitation_sensitive_refused", invocationId ? { invocationId } : undefined)
: new ToolGatewayHttpError(409,
`${appName} asked a question Paperclip can't show in the task chat. Complete this step in ${appName}, then try again.`,
"elicitation_unsupported", invocationId ? { invocationId } : undefined);
}
/**
* The question card a provider's form becomes. Only people answer it: an
* agent answering its own tool's question would consent on nobody's behalf.
* Answering wakes the assignee through the question-response outbox.
*/
async function createElicitationCard(input: {
companyId: string; issueId: string; agentId: string | null; appName: string;
request: McpFormElicitation; idempotencyKey: string;
}) {
const built = buildElicitationQuestionSet({ appName: input.appName, request: input.request });
if (!built.ok) throw elicitationRefusedError(input.appName, built);
return interactions.create(
{ id: input.issueId, companyId: input.companyId },
{
kind: "ask_user_questions",
idempotencyKey: input.idempotencyKey,
title: "Tool needs input",
summary: `${input.toolName} asked for more information before it can continue.`,
title: built.questionSet.title,
summary: built.questionSet.description,
continuationPolicy: "wake_assignee",
payload: {
version: 1,
title: input.request.message.slice(0, 240),
submitLabel: "Send response",
questions: elicitationQuestions(input.request),
},
resolverPolicy: "human_only",
payload: { version: 1, supersedeOnUserComment: false, questionSet: built.questionSet },
},
{ agentId: input.agentId },
// Each provider question is independent: a new one must never expire
@@ -6626,40 +6594,31 @@ export function createToolGatewayService(
);
}
async function requestElicitationForRecordedToolCall(input: {
session: ToolGatewaySession;
tool: ToolGatewayDescriptor;
invocationId: string;
request: McpElicitationRequest;
/** One card per provider input request; defaults to one per call. */
idempotencyKey?: string;
/** The name the card shows; a task's cards use one name on every path. */
cardToolName?: string;
/** What the agent reads while a person has the app's question. */
function elicitationWaitError(appName: string, details: Record<string, unknown>) {
return new ToolGatewayHttpError(
409,
`${appName} asked a question, and it is waiting for a person in the task chat. Paperclip wakes you when it is answered; then call this tool again with the same arguments to continue. Don't ask the question yourself.`,
"elicitation_required",
details,
);
}
async function markInvocationAwaitingElicitation(invocationId: string) {
await db.update(toolInvocations).set({
status: "awaiting_approval",
errorCode: "elicitation_required",
errorMessage: "The app asked a question; Paperclip put it in the task chat for a person to answer.",
updatedAt: new Date(),
}).where(eq(toolInvocations.id, invocationId));
}
/** Record that the call stopped for a person's answer, then end it. */
async function stopForElicitation(input: {
session: ToolGatewaySession; tool: ToolGatewayDescriptor; invocationId: string;
appName: string; interactionIds: string[]; requests: McpFormElicitation[];
}): Promise<never> {
if (!input.session.issueId) {
throw new ToolGatewayHttpError(
409,
"MCP elicitation is not supported for non-interactive gateway clients",
"elicitation_not_supported",
{ invocationId: input.invocationId, tool: input.tool.name },
);
}
const interaction = await createElicitationCard({
companyId: input.session.companyId, issueId: input.session.issueId, agentId: input.session.agentId,
toolName: input.cardToolName ?? input.tool.name, request: input.request,
idempotencyKey: input.idempotencyKey ?? `mcp-elicitation:${input.invocationId}`,
});
const now = new Date();
await db
.update(toolInvocations)
.set({
status: "awaiting_approval",
errorCode: "elicitation_required",
errorMessage:
"Remote MCP tool requested elicitation; Paperclip created an issue interaction for the response.",
updatedAt: now,
})
.where(eq(toolInvocations.id, input.invocationId));
await markInvocationAwaitingElicitation(input.invocationId);
await writeToolCallEvent({
invocationId: input.invocationId,
session: input.session,
@@ -6669,11 +6628,10 @@ export function createToolGatewayService(
policyDecision: "defer_runtime",
reasonCode: "elicitation_required",
metadata: {
interactionId: interaction.id,
elicitation: {
message: input.request.message,
requestedSchema: input.request.requestedSchema,
},
interactionId: input.interactionIds[0] ?? null,
interactionIds: input.interactionIds,
// The question's words and shape, never an answer.
elicitation: input.requests.map((request) => ({ message: request.message, requestedSchema: request.requestedSchema })),
},
tool: input.tool,
});
@@ -6686,23 +6644,332 @@ export function createToolGatewayService(
action: "tool_gateway.elicitation_requested",
details: {
invocationId: input.invocationId,
interactionId: interaction.id,
interactionId: input.interactionIds[0] ?? null,
interactionIds: input.interactionIds,
decision: "defer_runtime",
reasonCode: "elicitation_required",
tool: input.tool.name,
...toolAuditMetadata(input.tool),
},
});
throw new ToolGatewayHttpError(
409,
"MCP tool requested additional input",
"elicitation_required",
{
invocationId: input.invocationId,
interactionId: interaction.id,
tool: input.tool.name,
throw elicitationWaitError(input.appName, {
invocationId: input.invocationId,
interactionId: input.interactionIds[0] ?? null,
interactionIds: input.interactionIds,
tool: input.tool.name,
});
}
/**
* A provider question with no way to send an answer back (a vendor result
* shape, or an MCP Task's question shown inline). The card is shown and the
* call ends; answering wakes the agent.
*/
async function requestElicitationForRecordedToolCall(input: {
session: ToolGatewaySession;
tool: ToolGatewayDescriptor;
invocationId: string;
request: McpElicitationRequest;
/** One card per provider input request; defaults to one per call. */
idempotencyKey?: string;
connectionId?: string | null;
}): Promise<never> {
if (!input.session.issueId) {
throw new ToolGatewayHttpError(
409,
"MCP elicitation is not supported for non-interactive gateway clients",
"elicitation_not_supported",
{ invocationId: input.invocationId, tool: input.tool.name },
);
}
const appName = await elicitationAppName(input.session.companyId, input.connectionId ?? input.tool.connectionId, input.tool);
const interaction = await createElicitationCard({
companyId: input.session.companyId, issueId: input.session.issueId, agentId: input.session.agentId,
appName, request: input.request,
idempotencyKey: input.idempotencyKey ?? `mcp-elicitation:${input.invocationId}`,
});
return stopForElicitation({
session: input.session, tool: input.tool, invocationId: input.invocationId,
appName, interactionIds: [interaction.id], requests: [input.request],
});
}
/** How long a question round can wait for its answers before the call starts over. */
const MCP_ELICITATION_TTL_MS = 24 * 60 * 60_000;
/** Open question rounds per task; more is a clear stop, never a wall of cards. */
const MCP_ELICITATION_MAX_OPEN_ROUNDS = 10;
type McpElicitationRow = typeof toolMcpElicitations.$inferSelect;
type McpElicitationCall = {
session: ToolGatewaySession & { issueId: string };
tool: ToolGatewayDescriptor;
connectionId: string;
grantId: string;
/** Keyed identity of the call, including forwarded routing headers; only the same call collects its round. */
callIdentity: string;
/** Keyed identity of the full arguments, checked before a keyed retry runs again. */
argumentsIdentity: string;
appName: string;
};
const mcpElicitationScope = (row: Pick<McpElicitationRow, "companyId" | "connectionId">) => ({ companyId: row.companyId, connectionId: row.connectionId });
const mcpElicitationCallIdentity = (continuationKey: string, routingIdentity: string) =>
createHmac("sha256", mcpTaskSecret()).update("paperclip:mcp-elicitation-call:v1\0").update(continuationKey).update("\0").update(routingIdentity).digest("hex");
const mcpElicitationCardKey = (roundId: string, key: string) =>
`mcp-elicit:${roundId}:${createHash("sha256").update(key).digest("hex").slice(0, 32)}`;
/**
* Save a round of form questions, then put each on a card, then end the
* call. The round is saved first: a crash before a card exists is repaired
* on the next call, which makes the missing card under the same key.
* Forms are checked before anything is saved or shown.
*/
async function askElicitationRound(call: McpElicitationCall, input: {
invocationId: string;
era: "modern" | "legacy";
requestState: string | null;
forms: Array<{ key: string; request: McpFormElicitation }>;
/** An answered round this call just sent: spent in the same transaction that saves the next one. */
spend?: { row: McpElicitationRow; responses: Record<string, McpElicitationResponse> };
}): Promise<never> {
const { session } = call;
// The app already has the answered round's answers, even if this next one is refused.
const spendFirst = async () => { if (input.spend) await settleElicitationRound(input.spend.row, call, input.spend.responses, input.invocationId); };
for (const form of input.forms) {
const built = buildElicitationQuestionSet({ appName: call.appName, request: form.request });
if (!built.ok) {
await spendFirst();
await writeAudit({
session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId,
action: "tool_gateway.elicitation_refused",
details: {
invocationId: input.invocationId, tool: call.tool.name, reason: built.reason,
...(built.reason === "sensitive" ? { fields: built.fields.slice(0, 10) } : {}),
},
});
throw elicitationRefusedError(call.appName, built, input.invocationId);
}
}
if (input.forms.length > MCP_ELICITATION_MAX_FORMS_PER_ROUND) {
await spendFirst();
throw elicitationRefusedError(call.appName, { reason: "unsupported" }, input.invocationId);
}
const [open] = await db.select({ count: sql<number>`count(*)::int` }).from(toolMcpElicitations).where(and(
eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId),
eq(toolMcpElicitations.status, "waiting"), gt(toolMcpElicitations.expiresAt, new Date()),
// The answered round this one replaces is not counted: it is spent as this is saved.
...(input.spend ? [ne(toolMcpElicitations.id, input.spend.row.id)] : []),
));
if ((open?.count ?? 0) >= MCP_ELICITATION_MAX_OPEN_ROUNDS) {
await spendFirst();
throw new ToolGatewayHttpError(409,
`This task already has ${MCP_ELICITATION_MAX_OPEN_ROUNDS} app questions waiting for a person. Wait for those to be answered before trying again.`,
"elicitation_limit_reached", { invocationId: input.invocationId });
}
// One waiting round per call (per question for older servers, which ask
// one at a time): two matching calls at once share one set of cards.
const dedupeKey = createHash("sha256").update(JSON.stringify([
input.era, call.connectionId, call.grantId, call.callIdentity,
...(input.era === "legacy" ? input.forms.map((form) => elicitationQuestionHash(form.request)) : []),
])).digest("hex");
let row: McpElicitationRow | undefined;
for (let attempt = 0; attempt < 2 && !row; attempt += 1) {
const id = randomUUID();
const questions: McpElicitationRow["questions"] = input.forms.map((form) => ({
key: form.key, questionHash: elicitationQuestionHash(form.request), cardKey: mcpElicitationCardKey(id, form.key),
message: form.request.message, requestedSchema: form.request.requestedSchema,
}));
// The answered round is spent only together with saving the next one,
// so a stop between the two never loses the way to continue.
// If saving fails, the answered round is released, not left held, so the next call sends it again.
[row] = await db.transaction(async (tx) => {
if (input.spend && attempt === 0) {
await tx.update(toolMcpElicitations).set({ status: "sent", sentAt: new Date(), claimedUntil: null, updatedAt: new Date() })
.where(eq(toolMcpElicitations.id, input.spend.row.id));
}
return tx.insert(toolMcpElicitations).values({
id, companyId: session.companyId, issueId: session.issueId, agentId: session.agentId, runId: session.runId,
invocationId: input.invocationId, connectionId: call.connectionId, grantId: call.grantId,
catalogToolName: call.tool.name, callIdentity: call.callIdentity, argumentsIdentity: call.argumentsIdentity,
dedupeKey, era: input.era,
sealedRequestState: input.requestState === null ? null
: sealElicitationState(mcpTaskSecret(), { companyId: session.companyId, connectionId: call.connectionId }, input.requestState),
questions, status: "waiting", expiresAt: new Date(Date.now() + MCP_ELICITATION_TTL_MS),
}).onConflictDoNothing().returning();
}).catch(async (error: unknown) => {
if (input.spend) await releaseElicitationRound(input.spend.row).catch(() => undefined);
throw error;
});
if (input.spend && attempt === 0) await writeElicitationSentAudit(input.spend.row, call, input.spend.responses, input.invocationId);
if (row) break;
// Another matching call saved the round first: show its cards. An
// expired one is ended so this call can save a fresh round.
const [existing] = await db.select().from(toolMcpElicitations).where(and(
eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId),
eq(toolMcpElicitations.dedupeKey, dedupeKey), eq(toolMcpElicitations.status, "waiting"),
)).limit(1);
if (existing && existing.expiresAt > new Date()) row = existing;
else if (existing) await expireElicitationRound(existing, call);
}
if (!row) throw elicitationWaitError(call.appName, { invocationId: input.invocationId, tool: call.tool.name });
const cards = await ensureElicitationCards(row, call);
return stopForElicitation({
session, tool: call.tool, invocationId: input.invocationId, appName: call.appName,
interactionIds: cards.map((card) => card.id), requests: input.forms.map((form) => form.request),
});
}
/**
* The round's cards, found by their keys. A card that is missing (the
* process stopped between saving the round and showing it) is made now
* under the same key, so a question is never lost or shown twice.
*/
async function ensureElicitationCards(row: McpElicitationRow, call: McpElicitationCall) {
const keys = row.questions.map((question) => question.cardKey);
const found = keys.length ? await db.select({
id: issueThreadInteractions.id, idempotencyKey: issueThreadInteractions.idempotencyKey,
status: issueThreadInteractions.status, result: issueThreadInteractions.result, payload: issueThreadInteractions.payload,
}).from(issueThreadInteractions).where(and(
eq(issueThreadInteractions.companyId, row.companyId), eq(issueThreadInteractions.issueId, row.issueId),
inArray(issueThreadInteractions.idempotencyKey, keys),
)) : [];
const cards: Array<{ id: string; status: string; result: unknown; payload: unknown }> = [];
let made = false;
for (const question of row.questions) {
let card: { id: string; status: string; result: unknown; payload: unknown } | undefined =
found.find((candidate) => candidate.idempotencyKey === question.cardKey);
if (!card) {
const created = await createElicitationCard({
companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, appName: call.appName,
request: { message: question.message, requestedSchema: question.requestedSchema }, idempotencyKey: question.cardKey,
});
card = { id: created.id, status: created.status, result: created.result ?? null, payload: created.payload };
made = true;
}
cards.push(card);
}
if (made || row.questions.some((question, index) => question.interactionId !== cards[index]!.id)) {
const questions = row.questions.map((question, index) => ({ ...question, interactionId: cards[index]!.id }));
await db.update(toolMcpElicitations).set({ questions, updatedAt: new Date() }).where(eq(toolMcpElicitations.id, row.id));
row.questions = questions;
}
return cards;
}
/** The card's answer for each question of a round; null while any waits. */
async function elicitationRoundResponses(row: McpElicitationRow, call: McpElicitationCall) {
const cards = await ensureElicitationCards(row, call);
const responses: Record<string, McpElicitationResponse> = {};
for (const [index, question] of row.questions.entries()) {
const response = elicitationResponseForCard({ message: question.message, requestedSchema: question.requestedSchema }, cards[index]);
if (!response) return null;
responses[question.key] = response;
}
return responses;
}
/** End a round nobody answered in time; its cards are withdrawn so nobody answers a dead question. */
async function expireElicitationRound(row: McpElicitationRow, call: McpElicitationCall) {
const [expired] = await db.update(toolMcpElicitations).set({ status: "expired", claimedUntil: null, updatedAt: new Date() })
.where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting"))).returning({ id: toolMcpElicitations.id });
if (!expired) return;
for (const question of row.questions) {
if (!question.interactionId) continue;
await interactions.withdrawInteraction({ id: row.issueId, companyId: row.companyId }, question.interactionId,
{ reason: "The app's question expired before it was answered." }, { agentId: row.agentId, runId: call.session.runId })
.catch(() => undefined);
}
await writeAudit({
session: call.session, companyId: row.companyId, agentId: call.session.agentId, runId: call.session.runId, issueId: row.issueId,
action: "tool_gateway.elicitation_expired",
details: { roundId: row.id, invocationId: row.invocationId, tool: row.catalogToolName },
});
}
/**
* The waiting round for this exact call. Before every card is resolved the
* call stops again without contacting the app. Once they are, the round is
* claimed (so two repeated calls never both send) and its answers returned.
*/
async function collectElicitationRound(call: McpElicitationCall, input: {
invocationId: string; era: "modern" | "legacy"; questionHash?: string; claimMs: number;
}): Promise<{ row: McpElicitationRow; requestState: string | null; responses: Record<string, McpElicitationResponse> } | null> {
const { session } = call;
const rows = await db.select().from(toolMcpElicitations).where(and(
eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId),
eq(toolMcpElicitations.connectionId, call.connectionId), eq(toolMcpElicitations.grantId, call.grantId),
eq(toolMcpElicitations.callIdentity, call.callIdentity), eq(toolMcpElicitations.era, input.era),
eq(toolMcpElicitations.status, "waiting"),
)).orderBy(desc(toolMcpElicitations.createdAt)).limit(MCP_ELICITATION_MAX_OPEN_ROUNDS);
const now = new Date();
for (const row of rows) {
if (input.questionHash && !row.questions.some((question) => question.questionHash === input.questionHash)) continue;
if (row.expiresAt <= now) { await expireElicitationRound(row, call); continue; }
const responses = await elicitationRoundResponses(row, call);
if (!responses) {
await markInvocationAwaitingElicitation(input.invocationId);
throw elicitationWaitError(call.appName, {
invocationId: input.invocationId, interactionId: row.questions[0]?.interactionId ?? null,
interactionIds: row.questions.map((question) => question.interactionId).filter(Boolean), tool: call.tool.name,
});
}
const [claimed] = await db.update(toolMcpElicitations)
.set({ claimedUntil: new Date(Date.now() + input.claimMs), updatedAt: new Date() })
.where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting"),
or(isNull(toolMcpElicitations.claimedUntil), lt(toolMcpElicitations.claimedUntil, new Date()))))
.returning();
if (!claimed) {
// Another call is sending these answers right now.
await markInvocationAwaitingElicitation(input.invocationId);
throw elicitationWaitError(call.appName, { invocationId: input.invocationId, tool: call.tool.name });
}
const requestState = claimed.sealedRequestState === null ? null
: openElicitationState(mcpTaskSecret(), mcpElicitationScope(claimed), claimed.sealedRequestState);
if (claimed.sealedRequestState !== null && requestState === null) {
// Not readable here (a rotated secret): start over rather than send a guess.
await db.update(toolMcpElicitations).set({ status: "expired", claimedUntil: null, updatedAt: new Date() }).where(eq(toolMcpElicitations.id, claimed.id));
return null;
}
return { row: claimed, requestState, responses };
}
return null;
}
/** The round's answers reached the app and the call finished: it is spent. */
async function settleElicitationRound(row: McpElicitationRow, call: McpElicitationCall, responses: Record<string, McpElicitationResponse>, invocationId: string) {
await db.update(toolMcpElicitations).set({ status: "sent", sentAt: new Date(), claimedUntil: null, updatedAt: new Date() })
.where(eq(toolMcpElicitations.id, row.id));
await writeElicitationSentAudit(row, call, responses, invocationId);
}
async function writeElicitationSentAudit(row: McpElicitationRow, call: McpElicitationCall, responses: Record<string, McpElicitationResponse>, invocationId: string) {
await writeAudit({
session: call.session, companyId: row.companyId, agentId: call.session.agentId, runId: call.session.runId, issueId: row.issueId,
action: "tool_gateway.elicitation_sent",
details: {
roundId: row.id, invocationId, askedInvocationId: row.invocationId, tool: row.catalogToolName,
// Which kind of answer went back, never what the person wrote.
responses: Object.values(responses).map((response) => response.action),
},
);
});
}
/** The app did not finish with these answers: the next identical call uses them again. */
async function releaseElicitationRound(row: McpElicitationRow) {
await db.update(toolMcpElicitations).set({ claimedUntil: null, updatedAt: new Date() })
.where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting")));
}
/**
* A keyed retry of a call that stopped for an app's question runs again only
* when it is the same request: same tool and full arguments as the round.
*/
async function elicitationRetryMatches(companyId: string, invocationId: string, toolName: string, parameters: unknown) {
const [row] = await db.select({ id: toolMcpElicitations.id }).from(toolMcpElicitations).where(and(
eq(toolMcpElicitations.companyId, companyId), eq(toolMcpElicitations.invocationId, invocationId),
eq(toolMcpElicitations.catalogToolName, toolName), eq(toolMcpElicitations.argumentsIdentity, mcpTaskArgumentsIdentity(parameters)),
eq(toolMcpElicitations.status, "waiting"),
)).limit(1);
return Boolean(row);
}
function normalizeMcpContent(content: unknown): string {
@@ -7071,40 +7338,6 @@ export function createToolGatewayService(
return row.id;
}
/** Map a person's question-card answers back onto the provider's form schema. */
function elicitationContent(request: McpElicitationRequest, result: unknown): Record<string, unknown> {
const answers = (Array.isArray(asRecord(result)?.answers) ? asRecord(result)!.answers as unknown[] : [])
.map((answer) => asRecord(answer)).filter((answer): answer is Record<string, unknown> => Boolean(answer));
const textOf = (answer: Record<string, unknown> | undefined) => typeof answer?.otherText === "string" ? answer.otherText.trim() : "";
const properties = asRecord(request.requestedSchema?.properties);
if (!properties || Object.keys(properties).length === 0) {
const text = textOf(answers.find((answer) => answer.questionId === "response"));
return text ? { response: text } : {};
}
const content: Record<string, unknown> = {};
for (const [key, raw] of Object.entries(properties).slice(0, 10)) {
const property = asRecord(raw) ?? {};
const answer = answers.find((candidate) => candidate.questionId === key.slice(0, 120));
if (!answer) continue;
const enumValues = Array.isArray(property.enum) ? property.enum : [];
const optionIds = Array.isArray(answer.optionIds) ? answer.optionIds : [];
const index = enumOptions(enumValues).findIndex((option) => optionIds.includes(option.id));
if (index >= 0) { content[key] = enumValues[index]; continue; }
const text = textOf(answer);
if (!text) continue;
if (property.type === "number" || property.type === "integer") {
const value = Number(text);
if (Number.isFinite(value) && (property.type === "number" || Number.isInteger(value))) content[key] = value;
} else if (property.type === "boolean") {
if (/^(true|yes|y|1)$/i.test(text)) content[key] = true;
else if (/^(false|no|n|0)$/i.test(text)) content[key] = false;
} else {
content[key] = text;
}
}
return content;
}
type McpTaskInputPlan = {
/** Responses ready to send with tasks/update. */
responses: Record<string, unknown>;
@@ -7144,17 +7377,17 @@ export function createToolGatewayService(
raw: request.params,
},
};
const [card] = await db.select({ status: issueThreadInteractions.status, result: issueThreadInteractions.result })
// A secret or a shape the card can't show is never put on a card.
if (!buildElicitationQuestionSet({ appName: "app", request: form.request }).ok) return { ...plan, unsupported: true };
const [card] = await db.select({ status: issueThreadInteractions.status, result: issueThreadInteractions.result, payload: issueThreadInteractions.payload })
.from(issueThreadInteractions).where(and(
eq(issueThreadInteractions.companyId, row.companyId),
eq(issueThreadInteractions.issueId, row.issueId),
eq(issueThreadInteractions.idempotencyKey, mcpTaskInputKey(row, key)),
)).limit(1);
if (!card || card.status === "pending") { plan.waitingForm ??= { ...form, hasCard: Boolean(card) }; continue; }
const outcome = asRecord(card.result)?.outcome;
plan.responses[key] = card.status === "answered" && outcome === undefined
? { action: "accept", content: elicitationContent(form.request, card.result) }
: { action: "decline" };
const response = elicitationResponseForCard(form.request, card);
if (!response) { plan.waitingForm ??= { ...form, hasCard: Boolean(card) }; continue; }
plan.responses[key] = response;
}
if (plan.links.length > MCP_MAX_INPUT_LINKS) plan.unsupported = true;
return plan;
@@ -7278,7 +7511,8 @@ export function createToolGatewayService(
// A form counts as shown only once its card exists.
if (plan.waitingForm && !plan.waitingForm.hasCard && row.issueId) {
await createElicitationCard({
companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, toolName: row.catalogToolName,
companyId: row.companyId, issueId: row.issueId, agentId: row.agentId,
appName: await elicitationAppName(row.companyId, row.connectionId, wait.tool),
request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key),
});
}
@@ -7295,7 +7529,7 @@ export function createToolGatewayService(
await requestElicitationForRecordedToolCall({
session: wait.session, tool: wait.tool, invocationId: wait.invocationId,
request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key),
cardToolName: row.catalogToolName,
connectionId: row.connectionId,
});
}
}
@@ -7452,7 +7686,8 @@ export function createToolGatewayService(
: Infinity;
if (!plan.unsupported && plan.waitingForm && row.issueId && cardCount < MCP_TASK_MAX_CARDS) {
const card = await createElicitationCard({
companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, toolName: row.catalogToolName,
companyId: row.companyId, issueId: row.issueId, agentId: row.agentId,
appName: await elicitationAppName(row.companyId, row.connectionId),
request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key),
});
surfaced.add(plan.waitingForm.key);
@@ -7584,6 +7819,11 @@ export function createToolGatewayService(
// The cached MCP session this call used, so a failure resets only this
// identity's session and leaves other agents on the connection alone.
let mcpSession: { scope: string; headers: Record<string, string>; sessionId: string } | undefined;
// Answers to an app's question that this call is carrying back, until the app has them.
let elicitationClaim: Awaited<ReturnType<typeof collectElicitationRound>> = null;
// An older app may ask several questions in turn; each answer is spent
// only when the whole call finishes, so a later stop never loses one.
const legacyAnswered: Array<{ row: McpElicitationRow; responses: Record<string, McpElicitationResponse> }> = [];
try {
const dispatchRemote = async (target: string, init: RequestInit) => {
// Refresh can reduce consent. Recheck the selected grant after refreshing
@@ -7675,13 +7915,17 @@ export function createToolGatewayService(
if (isModernMcpProtocolVersion(knownVersion)) {
requestHeaders = { ...headers, "MCP-Protocol-Version": knownVersion };
} else if (connectionRequiresMcpSession(connection)) {
const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:${endpoint}`;
// Tool calls answer an older server's questions, so their session
// declares form questions; it is kept apart from sessions that only
// read (resources, prompts, listing), which declare none.
const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:elicit-form:${endpoint}`;
requestHeaders = await getMcpHttpSession({
scope,
send: sendForNegotiation,
headers,
requestId,
eraKey,
elicitationForm: true,
});
const sessionId = new Headers(requestHeaders).get("mcp-session-id");
if (sessionId) mcpSession = { scope, headers, sessionId };
@@ -7692,11 +7936,84 @@ export function createToolGatewayService(
// Tied to the server that issued the state: a changed URL starts fresh.
const continuationKey = `${connection.id}:${createHash("sha256").update(String(endpoint)).digest("hex")}:${grant.id}:${session.agentId}:${upstreamToolName}:${createHash("sha256").update(JSON.stringify(parameters ?? {})).digest("hex")}`;
const continuation = mcpContinuations.get(continuationKey);
// A person can answer the app's questions only when the call belongs to a task.
const elicitationCall: McpElicitationCall | null = session.issueId ? {
session: session as ToolGatewaySession & { issueId: string }, tool,
connectionId: connection.id, grantId: grant.id,
// Forwarded routing headers (such as a tenant) are part of the call:
// one tenant's answers never go out with another tenant's headers.
callIdentity: mcpElicitationCallIdentity(continuationKey, mcpTaskArgumentsIdentity(mcpTaskCallerHeaders(connection, callerHeaders))),
argumentsIdentity: mcpTaskArgumentsIdentity(parameters),
appName: tool.applicationDisplayName?.trim() || connection.name.trim() || "The app",
} : null;
// A question round this exact call left for a person (stateless MCP).
// Until every card is resolved the call stops again without contacting
// the app; then this call carries the answers and the app's exact state.
if (elicitationCall && isModernMcpProtocolVersion(mcpProtocolVersionOf(requestHeaders))) {
elicitationClaim = await collectElicitationRound(elicitationCall, { invocationId, era: "modern", claimMs: ms + 60_000 });
}
/**
* An older server asks over the open stream and waits for the reply.
* The first time, the question goes on a card and the server is told
* "cancel" at once, so it never hangs. When the person has answered,
* the same question on this same call is answered from the card, once.
*/
const answerLegacyElicitation = async (messageId: unknown, form: McpFormElicitation) => {
const respond = (result: McpElicitationResponse) => dispatchRemote(endpoint, {
method: "POST", headers: mcpHttpRequestHeaders(requestHeaders),
body: JSON.stringify({ jsonrpc: "2.0", id: messageId, result }),
});
const cancel = () => respond({ action: "cancel" }).catch(() => undefined);
if (!elicitationCall) {
await cancel();
throw new ToolGatewayHttpError(409, "MCP elicitation is not supported for non-interactive gateway clients",
"elicitation_not_supported", { invocationId, tool: tool.name });
}
const questionHash = elicitationQuestionHash(form);
// The app asks a question it already had an answer to in this call
// (to have it corrected, or a second time): that answer is spent and
// the person is asked again on a fresh card.
const earlier = legacyAnswered.findIndex((used) => used.row.questions.some((question) => question.questionHash === questionHash));
if (earlier >= 0) {
const [used] = legacyAnswered.splice(earlier, 1);
try {
await askElicitationRound(elicitationCall, { invocationId, era: "legacy", requestState: null, forms: [{ key: "question", request: form }], spend: used });
} finally {
await cancel();
}
}
let answered: Awaited<ReturnType<typeof collectElicitationRound>>;
try {
answered = await collectElicitationRound(elicitationCall, { invocationId, era: "legacy", questionHash, claimMs: ms + 60_000 });
} catch (error) {
await cancel();
throw error;
}
if (answered) {
const key = answered.row.questions.find((question) => question.questionHash === questionHash)!.key;
const response = answered.responses[key]!;
legacyAnswered.push({ row: answered.row, responses: { [key]: response } });
const delivered = await respond(response);
// An app that refused the reply never got the answer: keep it for the next call.
if (!delivered.ok) {
throw new ToolGatewayHttpError(502, `${elicitationCall.appName} did not accept the answer to its question. Try the call again.`,
"mcp_remote_status", { status: delivered.status, connectionId: connection.id, catalogEntryId: entry.id });
}
return;
}
try {
await askElicitationRound(elicitationCall, { invocationId, era: "legacy", requestState: null, forms: [{ key: "question", request: form }] });
} finally {
await cancel();
}
};
let callRequestId = requestId;
let callParams: Record<string, unknown> = {
name: upstreamToolName,
arguments: parameters,
...(continuation ? { requestState: continuation.requestState } : {}),
...(elicitationClaim
? { inputResponses: elicitationClaim.responses, ...(elicitationClaim.requestState !== null ? { requestState: elicitationClaim.requestState } : {}) }
: continuation ? { requestState: continuation.requestState } : {}),
};
// The guard runs inside this call and the connection is pinned to the
// address it approved, so an operator-supplied hostname cannot be rebound
@@ -7709,6 +8026,8 @@ export function createToolGatewayService(
toolInputSchema: entry.inputSchema ?? undefined,
// Paperclip can wait on a task here, durably (see waitForMcpTask).
declareTasks: tasksOn,
// A person can answer the app's form questions in the task chat.
elicitationForm: Boolean(elicitationCall),
}),
redirect: "manual",
signal: controller.signal,
@@ -7808,8 +8127,9 @@ export function createToolGatewayService(
if (isModernMcpProtocolVersion(retryVersion)) {
requestHeaders = { ...headers, "MCP-Protocol-Version": retryVersion };
} else {
const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:${endpoint}`;
requestHeaders = await getMcpHttpSession({ scope, send: sendForNegotiation, headers, requestId: `${requestId}-version`, eraKey });
// The same form-capable tool session as a first call (see above).
const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:elicit-form:${endpoint}`;
requestHeaders = await getMcpHttpSession({ scope, send: sendForNegotiation, headers, requestId: `${requestId}-version`, eraKey, elicitationForm: true });
const sessionId = new Headers(requestHeaders).get("mcp-session-id");
if (sessionId) mcpSession = { scope, headers, sessionId };
}
@@ -7938,8 +8258,12 @@ export function createToolGatewayService(
});
throw new ToolGatewayHttpError(409, "This tool needs authorization in the provider.", "provider_interaction_required", { upstreamPending: pending, invocationId });
}
const request = extractMcpElicitationRequest(message);
if (request) await requestElicitationForRecordedToolCall({ session, tool, invocationId, request });
const form = message.method === "elicitation/create" ? formElicitationOf(asRecord(message.params) ?? {}) : null;
if (form) await answerLegacyElicitation(message.id, form);
else {
const request = extractMcpElicitationRequest(message);
if (request) await requestElicitationForRecordedToolCall({ session, tool, invocationId, request });
}
},
}))
: await readBoundedRemoteResponse(response, (bytes) => {
@@ -7992,6 +8316,18 @@ export function createToolGatewayService(
// spent (a new input request saves its own below). A rejected attempt,
// such as a 401 before an OAuth refresh, keeps it for the explicit retry.
if (continuation) mcpContinuations.delete(continuationKey);
// The app answered this call. If it asks a new form round, the answered
// round is spent together with saving that one (askElicitationRound).
const nextInput = mcpInputRequired(asRecord(payloadRecord.result));
const asksNextForms = Boolean(nextInput && Object.values(nextInput.inputRequests).length
&& Object.values(nextInput.inputRequests).every((request) => request.method === "elicitation/create" && formElicitationOf(request.params)));
if (elicitationClaim && !asksNextForms) {
const sent = elicitationClaim;
elicitationClaim = null;
await settleElicitationRound(sent.row, elicitationCall!, sent.responses, invocationId);
}
// The older app finished the call: the answers it used are spent.
for (const used of legacyAnswered.splice(0)) await settleElicitationRound(used.row, elicitationCall!, used.responses, invocationId);
const upstreamPending = extractRemoteMcpPending(payloadRecord, String(connection.config.sourceTemplateKey ?? ""), entry.toolName);
if (upstreamPending) {
await retainUpstreamHandoff(invocationId, upstreamPending);
@@ -8042,6 +8378,18 @@ export function createToolGatewayService(
if (inputRequired) {
// Stateless servers ask for input by returning it as a result. The call
// is retried later, with the answers and the server's opaque state.
// Form questions alone go to a person in the task chat; the repeated
// call carries their answers (see collectElicitationRound).
const forms = Object.entries(inputRequired.inputRequests).flatMap(([key, request]) => {
const form = request.method === "elicitation/create" ? formElicitationOf(request.params) : null;
return form ? [{ key, request: form }] : [];
});
if (elicitationCall && forms.length && forms.length === Object.keys(inputRequired.inputRequests).length) {
const spend = elicitationClaim ?? undefined;
// From here the answered round is spent with the next one saved; never released.
elicitationClaim = null;
await askElicitationRound(elicitationCall, { invocationId, era: "modern", requestState: inputRequired.requestState, forms, spend });
}
const pending = mcpInputRequiredPending(inputRequired);
if (!pending.answerable) {
throw new ToolGatewayHttpError(
@@ -8091,6 +8439,9 @@ export function createToolGatewayService(
return { result, failureInstructions, headerSummary, execution };
}
} catch (error) {
// The app never got the answers this call carried: the next identical call sends them.
if (elicitationClaim) await releaseElicitationRound(elicitationClaim.row).catch(() => undefined);
for (const used of legacyAnswered.splice(0)) await releaseElicitationRound(used.row).catch(() => undefined);
execution.error = remoteHttpErrorEvidence(error);
execution.deadline = { timeoutMs: ms, aborted: controller.signal.aborted };
if (execution.response && execution.stream) execution.response.bodySizeBytes = execution.stream.bytesReceived;
@@ -9586,20 +9937,31 @@ export function createToolGatewayService(
};
}
/** Return a claimed approved action whose provider task is still running to approved, under the same claim. */
async function resumeApprovedActionForPendingTask(input: { actionRequestId: string; invocationId: string; claimUpdatedAt: Date; message: string }) {
/**
* Return a claimed approved action to approved, under the same claim, when
* its call stopped without finishing: the provider's task is still running,
* or the app asked the person a question. The next execution continues it
* (attaches to the task, or sends the answer) without asking for approval again.
*/
async function resumeApprovedActionForPendingTask(input: {
actionRequestId: string; invocationId: string; claimUpdatedAt: Date; message: string;
errorCode?: "provider_task_pending" | "elicitation_required";
}) {
const now = new Date();
const errorCode = input.errorCode ?? "provider_task_pending";
return db.transaction(async (tx) => {
const [invocation] = await tx.select({ status: toolInvocations.status }).from(toolInvocations)
.where(eq(toolInvocations.id, input.invocationId)).for("update").limit(1);
if (invocation?.status !== "executing") return false;
// A question stop already marked the invocation as waiting.
const resumable = invocation?.status === "executing" || (errorCode === "elicitation_required" && invocation?.status === "awaiting_approval");
if (!resumable) return false;
const [actionRequest] = await tx.select({ companyId: toolActionRequests.companyId, status: toolActionRequests.status, updatedAt: toolActionRequests.updatedAt })
.from(toolActionRequests).where(eq(toolActionRequests.id, input.actionRequestId)).for("update").limit(1);
if (actionRequest?.status !== "executing" || actionRequest.updatedAt.getTime() !== input.claimUpdatedAt.getTime()) return false;
await notifyToolReviewChange(tx, actionRequest.companyId);
await tx.update(toolInvocations).set({
status: "awaiting_approval", startedAt: null, errorCode: "provider_task_pending", errorMessage: input.message, updatedAt: now,
}).where(and(eq(toolInvocations.id, input.invocationId), eq(toolInvocations.status, "executing")));
status: "awaiting_approval", startedAt: null, errorCode, errorMessage: input.message, updatedAt: now,
}).where(and(eq(toolInvocations.id, input.invocationId), inArray(toolInvocations.status, ["executing", "awaiting_approval"])));
await tx.update(toolActionRequests).set({ status: "approved", updatedAt: now })
.where(and(eq(toolActionRequests.id, input.actionRequestId), eq(toolActionRequests.status, "executing"), eq(toolActionRequests.updatedAt, input.claimUpdatedAt)));
return true;
@@ -10173,6 +10535,12 @@ export function createToolGatewayService(
&& await resumeApprovedActionForPendingTask({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, message: error.message })) {
throw error;
}
// The app asked the person a question: keep the approval, so the
// repeated call carries the answer instead of failing the action.
if (error instanceof ToolGatewayHttpError && error.reasonCode === "elicitation_required"
&& await resumeApprovedActionForPendingTask({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, message: error.message, errorCode: "elicitation_required" })) {
throw error;
}
const { reasonCode } = await markApprovedActionFailed({
actionRequestId: claimed.id,
invocationId: invocation.id,
@@ -12885,7 +13253,17 @@ export function createToolGatewayService(
callerHeaders: input.callerHeaders,
})
: null;
const retryingMcpTask = Boolean(retryingMcpTaskRecordId);
// The same call repeated after the app asked a person a question runs
// again: it carries the answers back, or waits again without the app.
// An explicit key may name a different request: only the same tool
// and arguments as the saved question round run again.
const retryingElicitation = recorded.replayed && accessDecision.allowed && !retryingSlackRateLimit && !retryingGitHubPublication
&& !retryingMcpTaskRecordId && recorded.invocation.agentId === session.agentId
// Whatever the last attempt ended with (a failed send records its
// own error), a matching unsent round means the answer still has
// to reach the app.
&& await elicitationRetryMatches(session.companyId, recorded.invocation.id, tool.name, effectiveParameters);
const retryingMcpTask = Boolean(retryingMcpTaskRecordId) || retryingElicitation;
if (retryingGitHubPublication) {
// Invocation hashes describe shortened audit previews. The durable
// publication checks the complete saved request and current authority.