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

+127
View File
@@ -0,0 +1,127 @@
# MCP elicitation: an app's question, answered in the task chat
When a connected MCP app needs to ask the person something in the middle of a tool call, Paperclip handles it in five steps:
1. The question appears in the task chat as a card that names the app.
2. The agent's call stops with a message telling it to wait.
3. A person answers the card.
4. Answering wakes the agent.
5. The agent repeats the call with the same arguments, and Paperclip sends the answer to the app exactly once.
Nothing blocks while the person thinks, and nothing is held only in memory. A deploy or restart while a question waits loses nothing.
The design and its alternatives are in [`doc/plans/2026-11-13-mcp-elicitation.md`](../plans/2026-11-13-mcp-elicitation.md).
## What is supported
| App asks | Paperclip does |
| --- | --- |
| A form question, from a stateless (2026-07-28) server (`input_required`) | Shows a question card. The repeated call sends `inputResponses` together with the server's exact `requestState` |
| A form question, from an older (2025-06-18 / 2025-11-25) server (`elicitation/create` on the open stream) | Answers `cancel` at once, so the server never waits, and shows the card. When the same question arrives on the repeated call, Paperclip answers it from the card |
| A URL step (any version) | Shows the provider link, as before. Paperclip never claims the person's consent ([MCP-PROTOCOL-VERSIONS.md](./MCP-PROTOCOL-VERSIONS.md)) |
| A form beside a URL step | The link goes first. On the next call the app asks for the form again |
| A form question inside a background MCP Task | Shows the same card. The answer goes back with `tasks/update` ([MCP-TASKS.md](./MCP-TASKS.md)) |
| A password, key, token, card number or one-time code in a form | Refused. No card is shown, and the agent is told the app must use a secure link |
| A schema outside the spec, or a form with no task | Shows no card. The agent gets a clear reason |
## Capability
Paperclip declares `elicitation: { form: {}, url: {} }` in two places:
- **2026-07-28:** per request, only on HTTP `tools/call` requests that belong to a task, because that is where a person can answer.
- **Older HTTP sessions:** at `initialize`, only on the session that tool calls use, because that is the path that answers questions. Sessions that only read (resources, prompts, listing) declare none, so they are never asked a question they would leave waiting. A 2025-06-18 session gets `{}`, which means form only. Questions that arrive outside a task are answered `cancel` at once.
Stdio apps keep URL only.
## How the card works
- **Shows which app is asking.** The card's title is "*App* needs your input", using the connection's name. The app's message is shown as plain text: links are not clickable, and secrets are redacted.
- **Only people can answer** (`resolverPolicy: "human_only"`). An agent answering its own tool's question would be consent given on nobody's behalf.
- **Lets the person review before sending.** The form is the standard question form: fields can be edited, and nothing is sent until **Send to *App***. **Skip** declines.
- **Is checked on submit.** Required fields, lengths, number ranges and the date format are validated before the card is resolved. Email and web address show a hint and are checked by the app, because the form only checks fixed-width patterns.
- **Wakes the agent either way.** Answering wakes the agent through the question-response outbox. **Skip** on an app's question also wakes it (ordinary questions do not), because the decline only reaches the app on the agent's next call.
Each form field maps to one card field:
| Schema | Card field |
| --- | --- |
| `string` (`minLength`, `maxLength`, `default`) | Text. The default is filled in |
| `string` with `format` `email` / `date` / `date-time` / `uri` | Text with a hint. `date` is validated |
| `number`, `integer` (`minimum`, `maximum`, `default`) | Number field |
| `boolean` (`default`) | Yes / No. The default is marked as recommended |
| `enum`, or `oneOf` with `const` + `title` | Single choice. Titles are the labels |
| `array` with `items.enum` or `items.anyOf` (`minItems`, `maxItems`, `default`) | Multiple choice |
| No properties | One **Continue** choice |
Paperclip refuses the following shapes rather than showing part of the form:
- Nested objects.
- Arrays of anything but choices.
- Unknown formats.
- More than 10 fields.
- More than 100 choices.
- More than 4 form questions in one round.
## What goes back to the app
| The card | Sent |
| --- | --- |
| Answered | `{ action: "accept", content }`, with values typed to the schema (choices are sent as their `const`) |
| Skipped | `{ action: "decline" }` |
| Withdrawn, task closed, expired, or deleted | `{ action: "cancel" }` |
## What the agent sees
| Moment | Result |
| --- | --- |
| The app asks | `elicitation_required`: "*App* 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." |
| Repeated before every card is resolved | The same message. The app is not contacted |
| Repeated after | The app's own result for the answer, decline or cancel |
| A secret was asked for | `elicitation_sensitive_refused` |
| An unsupported form | `elicitation_unsupported` |
| 10 questions already waiting on the task | `elicitation_limit_reached` |
The agent never receives the person's answers from Paperclip, only the app's result. Within one run, a repeated side-effecting call normally replays the earlier result. A call that stopped for a question runs again instead.
## Storage and recovery
- **Table.** `tool_mcp_elicitations` holds one row per question round. It is company-scoped and records:
- The task, agent, run, connection and grant.
- A keyed call identity, covering endpoint, tool, arguments, grant, agent and any forwarded routing headers (such as a tenant). One tenant's answers never go out with another tenant's headers.
- The server's `requestState`, sealed with AES-256-GCM and bound to the company and connection.
- Each question's key, words, schema and card.
- **Answers.** Answers live only on the cards.
- **Saving.** The round is saved before its cards, and each card has a fixed key. If the process stops between the two, the next call makes the missing card under the same key, so no question is lost or shown twice.
- **Who can collect a round.** Only the identical call can collect it: same company, task, connection, grant, agent and call identity.
- **Older apps that ask several questions.** An answer is spent only when the app finishes the whole call. An app that asks Q1 and then Q2 gets Q1's answer again on the next call, without a second card. An app that refuses the reply (an HTTP error) keeps the answer for the next call.
- **Keyed retries.** A call with an unsent round runs again (instead of replaying its last result, even a failed send) only if it has the same tool and arguments as the saved round.
- **One round per call.** At most one waiting round exists per call (per question, for older servers), enforced by a unique index. Two matching calls at once share its cards.
- **Ask-first actions.** An approved action that stops for a question keeps its approval. The repeated call continues the same approved action and sends the answer, with no second approval.
- **Claims.** A repeated call claims the round before sending. If the process dies mid-send, the claim lapses after the tool timeout plus a minute, and the next call sends again. A failed send releases the claim at once.
- **Expiry.** Rounds expire after 24 hours, checked when the call is next made; no background poller is involved. Expired cards are withdrawn, so nobody answers a dead question, and the call starts over.
- **Activity log.** The log records `tool_gateway.elicitation_requested`, `tool_gateway.elicitation_sent` (the actions only, never values), `tool_gateway.elicitation_refused` (field names only) and `tool_gateway.elicitation_expired`. Answers are logged as `issue.thread_interaction_answered`.
## MCP Apps
A tool call made from an MCP App view runs in the task's session. Its questions appear in the same chat.
## Not supported yet
- Enforcing `minItems` and `maxItems` on the card. Today they show as help text, and the app checks them when the answer arrives.
- Sampling and roots requests.
- Form questions from stdio apps.
- Forms rendered inside an MCP App view.
- `input_required` on `resources/read` and `prompts/get`.
- Answers to the vendor `_meta.elicitation` result shape, which has no channel for them.
## Tests
`server/src/__tests__/mcp-elicitation.test.ts` covers the following:
- The schema mapping and answer typing.
- The sensitive-field refusal.
- Capabilities.
- A fake stateless server: answer, skip, two questions at once, restart while waiting, a crash mid-send, a second company, expiry, and an agent trying to answer.
- A fake 2025-06-18 server that asks over the open stream.
Stories: `Tasks and conversations/Questions and approvals/MCP App Questions`.
+9 -6
View File
@@ -102,10 +102,15 @@ stateless MCP) is probed again once.
agent, tool, and arguments) with a new JSON-RPC id. It survives an attempt
the server rejected (for example a `401` before a token refresh). The call
stops with `provider_retry_requested` so the agent retries.
- Form, sampling, or roots requests, or more than 8 links: the call stops
with `provider_input_required` and the message "This app needs information
Paperclip can't collect yet." Paperclip does not declare form, sampling,
or roots, so compliant servers should not send them.
- Form requests only, on a call that belongs to a task: a question card in
the task chat; the repeated call sends `inputResponses` and the exact
`requestState`. See [MCP-ELICITATION.md](./MCP-ELICITATION.md). Form
beside a URL request: the link goes first.
- Sampling or roots requests, form requests outside a task, or more than 8
links: the call stops with `provider_input_required` and the message
"This app needs information Paperclip can't collect yet." Paperclip
declares form only on task calls and never declares sampling or roots,
so compliant servers should not send them.
- `"input_required"` on a context read (`resources/read`, `prompts/get`) or a
stdio call stops with `provider_input_required`.
- Resource not found is `-32602` from modern servers and `-32002` from legacy
@@ -160,8 +165,6 @@ Tracked as follow-ups:
- Recording that a person finished a provider URL step, so Paperclip can
answer it with `accept` and the provider's `requestState`.
- Collecting form input requests (MRTR form elicitation) in the task chat and
answering them on the retry.
- Retrying a `requestState`-only result automatically instead of asking the
agent to retry.
- `subscriptions/listen` change notifications (cache invalidation relies on
+1 -3
View File
@@ -58,7 +58,7 @@ Paperclip polls, which the specification makes the default.
| Attach | A call with the same endpoint, tool, full arguments, grant, agent, task, and actor attaches to the undelivered task instead of sending `tools/call` again. So does a retry with the same idempotency key, including after a crash mid-wait; the same key with other arguments is refused and leaves the original retry intact. One holder at a time (a lease): a second simultaneous caller is told to call again. | `findAttachableMcpTask`, `mcpTaskForKeyedRetry`, `claimMcpTask` |
| Deliver | A completed task counts as delivered only once its result is recorded on the call. A crash in between leaves it collectable again. | `markMcpTaskDelivered` |
| Restart | Background work reads pending rows at startup and polls each at its next deadline, with each request bounded to 30 s. It rechecks the same access a live call needs (grant, audience, delegation). When a task settles, or asks a new question, after its run has ended, the assignee is woken once; the agent's repeated call collects the result or shows the question. | `pollDueMcpTasks`, `server/src/services/mcp-task-work.ts` |
| Input | URL requests show the provider link, as for a direct request; Paperclip never answers them for the person. Form requests become a question card on the task; only the person's answer is sent with `tasks/update`. Other requests (sampling, roots) stop with a clear "needs input" error. | `planMcpTaskInput` |
| Input | URL requests show the provider link, as for a direct request; Paperclip never answers them for the person. Form requests become a question card on the task, built and answered as in [MCP-ELICITATION.md](./MCP-ELICITATION.md) (human-only, typed fields; skip sends `decline`, other endings `cancel`); only the person's answer is sent with `tasks/update`. Other requests (sampling, roots) stop with a clear "needs input" error. | `planMcpTaskInput` |
| Cancel | Stopping the run sends `tasks/cancel` and marks the row cancelled. Closing the task or stopping its run does the same for a task in the background; a later call reports the cancellation and never revives it. A caller that only disconnects keeps the task. | `cancelMcpTaskRecord`, `mcpTaskStopReason` |
| Finish | `failed` becomes a tool error with the provider's message. An unknown task (`-32602`) or a passed TTL becomes a clear error telling the agent to run the action again. Nothing waits forever: every task stops being tracked after its TTL, and seven days after Paperclip first saw it at most. | `provider_task_failed`, `provider_task_expired` |
@@ -120,8 +120,6 @@ returns to approved, and its next execution attaches to the same task.
- Sampling and roots input requests.
- Showing a long-running provider action's progress (`statusMessage`) in the
task chat.
- Validating question-card answers against the provider's form schema (types,
required fields) and letting the person correct them before `tasks/update`.
## Tests
+4 -2
View File
@@ -19,8 +19,10 @@ MCP protocol versions (2026-07-28 stateless MCP and older handshake servers):
MCP extensions: [MCP Apps](./MCP-APPS.md) (interactive views in the task chat),
[MCP Skills](./MCP-SKILLS.md) (skills that connected apps publish, reviewed
by the board and delivered to agents), and [MCP Tasks](./MCP-TASKS.md) (long
provider calls that survive timeouts, restarts, and deploys).
by the board and delivered to agents), [MCP Tasks](./MCP-TASKS.md) (long
provider calls that survive timeouts, restarts, and deploys), and
[MCP elicitation](./MCP-ELICITATION.md) (an app's question to the person,
answered in the task chat).
Long-term memory: [Experimental memory connectors](./MEMORY.md).
+342
View File
@@ -0,0 +1,342 @@
# MCP elicitation: an app's question becomes a task-chat card, and the agent's next call carries the answer
Status: plan, 2026-11-13. Owner: the mcp-elicitation session. Builds on #21119 and #21266 (MCP Apps), #21140 (stateless 2026-07-28 client), #21219 (Skills over MCP) and #21263 (MCP Tasks).
## Summary
**Recommendation: the run yields while it waits.** When a connected MCP app asks the person a question in the middle of a tool call, Paperclip does four things:
1. It saves the question durably.
2. It shows the question as a question card in the task chat, titled with the app's name.
3. It tells the agent to wait.
4. When someone answers, it wakes the agent through the existing answer-delivery outbox.
The agent then calls the tool again with the same arguments, and Paperclip sends the answer to the app exactly once. Nothing blocks and nothing stays in memory, so a restart at any point leaves no stuck call.
The flow covers both protocol eras:
- **Stateless servers (2026-07-28)** return `input_required`. Paperclip repeats the call with `inputResponses` and the exact `requestState`.
- **Older servers (2025-06-18 and 2025-11-25)** send `elicitation/create` over an open stream.
- The first time, Paperclip answers `cancel` at once, so the server is never left hanging.
- Once the person answers, the repeated call answers the same question from the card.
Three rules hold across both eras:
- Only people can answer. Agents cannot.
- Forms that ask for passwords, keys or card numbers are refused and never shown.
- Choosing **Skip** sends `decline`. A withdrawn, closed or expired card sends `cancel`.
## Foreword
- **Context.** Today Paperclip handles only part of what an MCP app can ask:
- **URL requests** already become a provider link that the person opens.
- **Form questions from background MCP Tasks** already become a question card, and the answer goes back with `tasks/update`.
- **Need.** Every other form question is a dead end:
- A stateless server's form `input_required` ends in a "needs information Paperclip can't collect yet" error.
- An older server's `elicitation/create` creates a card, but nothing ever reads the answer back. The card key `mcp-elicitation:<invocationId>` is never looked up again, so the server asks again on every retry.
- Paperclip declares only `elicitation: { url: {} }`. A compliant stateless server therefore never asks a form question at all.
- **Task.** Make form elicitation work end to end in the task chat for both eras. The work must be restart-safe, company-scoped and logged in the activity log.
- **Object.** The document is organized as follows:
- §1: what the spec requires.
- §2: what exists today.
- §3: the nine design decisions.
- §4: the user journey.
- §5: tests.
- §6: risks and what is out of scope.
## 1. The spec: two transports carry one question model
Form and URL requests share one data model. Only the transport differs between eras.
### 1.1 Data model (client/elicitation, 2026-07-28)
- **Request.** `elicitation/create` has these parameters:
- `mode`: `"form"` (the default when omitted) or `"url"`.
- `message`: required.
- Form mode adds `requestedSchema`.
- URL mode adds `url` (and `elicitationId` on 2025-11-25).
- **Form schema.** A flat object whose properties are primitives:
- **string**: `minLength`, `maxLength`, and `format` (one of `email`, `uri`, `date`, `date-time`).
- **number / integer**: `minimum` and `maximum`.
- **boolean**.
- **Enums (SEP-1330):**
- Single select: `enum`, or `oneOf: [{const, title}]`.
- Multi select: `type: "array"` with `items.enum` or `items.anyOf: [{const, title}]`, plus `minItems` and `maxItems`.
- **Defaults:** every type may carry a `default` (SEP-1034), which clients SHOULD pre-fill.
- **Response.** One of three actions:
- `{ action: "accept", content }`.
- `{ action: "decline" }`: the person explicitly said no.
- `{ action: "cancel" }`: the request was dismissed with no choice made.
- For URL mode, `accept` carries no content. It means "the person agreed to open the link", not "the step is done".
- **Capability.** The client declares `elicitation: { form: {}, url: {} }`, per request on 2026-07-28 and at `initialize` on older versions. `{}` alone means form only. A server MUST NOT use a mode that the client did not declare.
### 1.2 Transport
- **2026-07-28 (stateless).** Multi round-trip requests replace server-initiated requests.
- On `tools/call`, `resources/read` or `prompts/get`, the server returns `resultType: "input_required"`. The result carries an `inputRequests` map (server-chosen keys) and/or an opaque `requestState`.
- The client builds every requested input, then retries the *same* request with a new JSON-RPC `id`. The retry carries `inputResponses` (same keys) and echoes `requestState` byte for byte. The client MUST NOT inspect or alter `requestState`, and MUST NOT reuse it on any other request.
- Retries may be delayed arbitrarily. Servers SHOULD re-ask for anything missing rather than fail.
- **2025-06-18 / 2025-11-25 (sessions).** The server sends a JSON-RPC request `elicitation/create` inside the open `tools/call` SSE stream. The client POSTs the JSON-RPC response while the stream stays open.
- In 2025-11-25, URL mode can also arrive as error `-32042` carrying `data.elicitations`.
### 1.3 Security rules Paperclip must meet
- **Sensitive data.** Servers MUST NOT request secrets through forms: passwords, API keys, tokens or payment credentials. Such requests MUST use URL mode.
- **Consent and identity.** Clients MUST:
- Show which server is asking.
- Offer clear decline and cancel options.
- Let the person review and edit a form before it is sent.
- Before opening a URL, show the full address and get consent.
- Clients SHOULD also validate answers against the schema.
- **Links.** Clients MUST NOT prefetch URLs. They SHOULD NOT render links inside form text as clickable.
## 2. Inventory: the pieces exist; the answer path does not
### 2.1 Gateway (`server/src/services/tool-gateway.ts`)
| Piece | Where | Today |
| --- | --- | --- |
| `extractMcpElicitationRequest` | `:6498` | Recognizes `elicitation/create` and vendor `_meta.elicitation` shapes |
| `elicitationQuestions` | `:6541` | Up to 10 properties. Enum becomes single select; everything else becomes "Provide answer" plus free text. Ignores type, format, default and multi select |
| `createElicitationCard` | `:6603` | `ask_user_questions` card titled "Tool needs input". No app name; resolver policy left at the default `anyone`, so agents may answer |
| `requestElicitationForRecordedToolCall` | `:6629` | Marks the invocation `awaiting_approval`, writes a call event and an audit entry, then throws 409 `elicitation_required` |
| Legacy stream `onRequest` | `:7928` | URL request: POSTs `cancel` and starts the link flow. Form request: creates a card and throws **without answering the server** |
| `mcpInputRequiredPending` | `:704` | URL-only rounds become the link flow; a bare `requestState` is kept in memory; **form rounds return `answerable: false`** |
| Modern `input_required` branch | `:8040` | A form round ends in `provider_input_required` ("can't collect yet") |
| `mcpContinuations` | `:1406` | In-memory `requestState` cache (lost on restart) |
| Capabilities (`server/src/services/mcp-http.ts:57`) | | Modern: `elicitation: { url: {} }`. Legacy: none |
### 2.2 MCP Tasks (#21263, `doc/connections/MCP-TASKS.md`)
- `planMcpTaskInput` (`:7125`) looks up the card by `mcp-task-input:<row>:<keyhash>`:
- Pending: wait.
- Answered with no `outcome`: `accept` with `elicitationContent`.
- Anything else: `decline`.
- The answer goes back with `tasks/update`.
- **This plan reuses its card builder and answer mapping and does not duplicate them.** Both move into one module so that Tasks cards gain the same fields and app name.
### 2.3 Question cards (`issue_thread_interactions`, kind `ask_user_questions`)
- **Shape.** The payload can carry a canonical `questionSet` (`packages/shared/src/types/issue.ts:1385`):
- `answerMode`: `single_select`, `multi_select` or `text`.
- `initialText` for defaults.
- `recommended` on options.
- `textValidation` with `minLength`, `maxLength`, `pattern`, `inputType` (number or integer), `minimum` and `maximum`.
- **Validation.** On submit, the server validates answers against the `questionSet` (`question-interaction-answers.ts:69`, 422 `invalid_question_response`).
- **Statuses.**
- Answered: `answered`.
- Skip: `cancelled` with `outcome: "skipped"`.
- Withdraw or close: `cancelled` with an outcome.
- Superseded: `expired`.
- Dismiss changes nothing.
- **Who may answer.** The respond route checks issue access, then the interaction's resolver policy (`issue-thread-interaction-resolution.ts`). `human_only` keeps agents out.
- **Wake on answer.** `answerQuestions` writes an `issue_question_response_deliveries` outbox row. The delivery worker wakes the assignee (`question-response-delivery.ts:1170`) with retries. The wake is durable.
- **UI.**
- `TaskChatInteractionCard` shows "Unanswered question" and opens `AskUserQuestionsCard` / `QuestionForm` above the composer.
- The header shows `interaction.title`.
- Text, number and integer fields with validation already exist.
### 2.4 Waiting on a person elsewhere
- **Native runtime requests** (`native-runtime/runtime-request-resolution-authority.ts`) hold a live harness turn open and fall back to a durable card.
- **Tool approvals** (`tool_action_requests`) yield the call. A later identical call collects the approval.
- Elicitation follows the approval pattern (yield, then collect), not the harness pattern. A remote HTTP call cannot be held across a restart.
## 3. Design decisions
Each decision states the chosen option first, then why.
### D1. Waiting: the run yields; the agent's repeat call collects the answer
- **Chosen.** The call ends at once with 409 `elicitation_required` and a plain message:
> "Linear asked a question in the task chat. Paperclip wakes you when it is answered. Then call this tool again with the same arguments. Don't ask the question yourself."
An answer wakes the assignee through the durable question-response outbox. A repeat call before every card is resolved returns the same message without contacting the app.
- **Why not block with a time limit?** Blocking would:
- Hold an HTTP stream and a run slot for minutes.
- Die on deploys and restarts.
- Need a second wake path anyway when the time limit passes.
Yielding reuses the outbox, which already survives restarts, and matches the approval pattern.
- **Recovery.** Everything the retry needs lives in Postgres:
- The `tool_mcp_elicitations` row, with `requestState` sealed.
- The cards.
A send is guarded by a lease (`claimed_at`). If the process dies mid-send, the next call reclaims the row once the lease is older than the tool timeout plus a margin. The answer is not lost and is not sent twice.
### D2. Who may answer: any person with access to the task, never an agent; the card names the app
- **Chosen.** `resolverPolicy: "human_only"` on every elicitation card. This applies to direct and Tasks questions alike.
- **Why not only the responsible user?** That person may be away, and other questions in the task chat already accept any member with access. Narrowing to one person would strand the run.
- **Why not agents?** Letting an agent answer its own tool's question defeats user consent.
- **Showing the app.**
- Card title: "*App name* needs your input". The app name comes from the connection's display name.
- Card description: the server's `message`, redacted, as plain text, so links are not clickable.
- Submit label: "Send to *App*".
- The person sees no raw IDs.
### D3. Mapping: every spec type becomes a real field; anything else is refused clearly
| Schema | Card field (`questionSet`) |
| --- | --- |
| `string` (+ `minLength`/`maxLength`) | `text` with those limits. `default` becomes `initialText` |
| `string` with `format` `email` / `date` / `date-time` / `uri` | `text` with a format hint. `pattern` for `email` and `date` |
| `number` / `integer` (+ `minimum`/`maximum`) | `text` with `inputType` and range. `default` becomes `initialText` |
| `boolean` | `single_select` Yes / No. `default` marks the recommended option |
| `enum`, `oneOf[{const,title}]` | `single_select`. Titles are labels; `default` is recommended |
| `array` of `items.enum` / `items.anyOf` | `multi_select`, with `minItems`/`maxItems` as help text |
| No properties | One `single_select` "Continue" option, sending `accept` with `{}` |
- **Answers back.** Answers map back to typed `content`: enum options return their `const` value, and numbers and booleans are typed.
- **Required fields.** Required follows `schema.required`.
- **Refused shapes.** Nested objects, arrays of non-enums, unknown types, more than 10 properties, more than 4 form requests in one round, or more than 100 options. Paperclip shows no card. The agent gets `elicitation_unsupported`:
> "*App* asked a question Paperclip can't show here. Complete this step in *App*, then try again."
A legacy server gets `cancel`. A stateless server needs no reply.
### D4. Sensitive fields: refuse, don't warn
- **Chosen.** If any field's name, title or description matches the secret pattern, the whole request is refused before a card exists. This covers password, passcode, secret, API key, access or refresh token, credential, private key, card number, CVV/CVC, SSN, one-time code and 2FA/MFA. A field marked `format: "password"` or `writeOnly` is refused the same way.
- **Why refuse rather than warn?** The spec forbids such forms. A warning still puts a secret into the task thread and the activity history, where it stays.
- **What happens on refusal.**
- The agent gets `elicitation_sensitive_refused`:
> "*App* asked for a password or key in a form. Paperclip doesn't collect secrets that way; the app must use a secure link."
- A legacy server gets `cancel`.
- The refusal is logged with field names only, never values.
### D5. What the agent sees
| Moment | Agent sees |
| --- | --- |
| Question asked | 409 `elicitation_required` with the wait-and-retry message, `interactionIds` |
| Retried too early | The same message. The app is not contacted |
| Answered, skipped or closed, then retried | The app's real result for `accept` / `decline` / `cancel` (the app decides what declining means) |
| App asks again | A new question; the cycle repeats |
| Round expired before an answer | The call goes out fresh, so the app asks again |
The agent never sees the answer values through Paperclip's message. Only the app's own result reaches it.
### D6. Persistence: one company-scoped table, sealed state, logged actions, 24-hour expiry
- **Table `tool_mcp_elicitations`.** One row per question round. Its columns:
- Scope: `company_id`, `issue_id`, `agent_id`, `run_id`, `connection_id`, `grant_id`, `invocation_id`.
- `call_identity`: an HMAC over endpoint, tool, arguments, grant and agent.
- `era`: `modern` or `legacy`.
- `sealed_request_state`: AES-256-GCM, bound to company and connection.
- `questions`: jsonb `[{key, questionHash, interactionId, mode}]`. It holds no answers; the card is the single source of truth.
- `status`: `waiting`, `sent`, `expired` or `refused`.
- Bookkeeping: `claimed_at`, `expires_at`, `created_at`, `updated_at`.
- **Lookups.** Every lookup filters by company, issue, connection, grant, agent and call identity.
- **Expiry.** Rows expire after 24 hours. Expiry is checked lazily on the next call, so no background poller is added (this follows the sleep-aware-worker rule). On expiry, pending cards are withdrawn through the interaction service, so nobody answers a dead question. The app's own `requestState` TTL is usually shorter; if the app rejects stale state, it SHOULD re-ask.
- **Cap.** At most 10 waiting rounds per task. Beyond that the call fails with "too many open questions" instead of spamming cards.
- **Activity log.** The log records these events:
- `tool_gateway.elicitation_requested` (exists).
- `tool_gateway.elicitation_sent`, with the actions only.
- `tool_gateway.elicitation_refused`.
- `tool_gateway.elicitation_expired`.
- The existing `issue.thread_interaction_answered`.
Answer values are never logged.
### D7. Retry semantics: stateless servers are fully supported; older servers are answered from the card
- **Stateless (2026-07-28).**
- Paperclip declares `elicitation: { form: {}, url: {} }` on HTTP `tools/call` when the call belongs to a task. That is the only place a card can be shown.
- **Form rounds.** On `input_required` with form requests, Paperclip saves the round and creates the cards, which ends the call.
- **The repeat call.** It finds the waiting round, checks that every card is resolved and claims the row. It then sends one `tools/call` with a new id, `inputResponses` for every key, and the unsealed `requestState`.
- **Mixed rounds.** If a round mixes URL and form requests, the URL link flow goes first and is not persisted. Paperclip never claims URL consent that nobody gave. The fresh call that follows lets the server re-ask for the form.
- **Bare `requestState`.** A round with only `requestState` keeps today's in-memory retry.
- **Legacy (2025-06-18 / 2025-11-25).** Paperclip declares `elicitation: { form: {}, url: {} }` at `initialize` (`{}` on 2025-06-18).
- **When a form `elicitation/create` arrives on the stream,** Paperclip computes `questionHash`, a hash of the message and the canonical schema.
- **If an answered, unsent round matches** this call identity and hash, Paperclip claims it, POSTs `accept` / `decline` / `cancel` and keeps reading the stream.
- **Otherwise** it saves a round, creates the card and POSTs `cancel`, so the server stops waiting. Then it ends the call with `elicitation_required`.
- **Why answer ahead from a saved card?** The person consented to that exact question for that exact call. Holding the stream open would break D1.
- **Never supported.** The vendor `_meta.elicitation` result shape keeps today's card-only behavior: it has no channel for answers.
### D8. Tasks interplay: one mapping, two transports
- The schema mapping, sensitive check, card builder and answer mapping move to `server/src/services/mcp-elicitation.ts`. MCP Tasks uses them unchanged in behavior, and its cards gain the app name, real fields and `human_only`.
- **With `enableMcpTasks` off,** `tools/call` never returns a task, and D7 handles every question.
- **With it on,**
- A task's own `input_required` keeps its `tasks/update` path.
- A non-task `input_required` uses D7.
- The two never share a card key: tasks use `mcp-task-input:`, direct calls use `mcp-elicit:`.
### D9. MCP Apps: a view's tool call asks in the same chat
A tool call triggered from an MCP App view already runs in the task's gateway session, so D7 applies unchanged:
- The card appears in the chat beside the view.
- The view's call receives the wait message.
- Answering wakes the agent, which repeats the call.
Out of scope: a form rendered inside the view.
## 4. User journey and UI states
1. **Asking.** The agent calls Linear's `create_issue`, and Linear asks "Which team should own this?" The task chat shows "Unanswered question". Opening it shows the form:
- Title: "Linear needs your input".
- The app's message as plain text.
- The fields.
- **Send to Linear** and **Skip**.
2. **Answered.** The receipt shows the answers. The agent wakes, repeats the call and posts the result.
3. **Declined.** The person chooses **Skip**. The receipt reads "Skipped". The app receives `decline`, and the agent reports what the app did.
4. **Expired.** If nobody answers for 24 hours and the agent repeats the call, the card is withdrawn and its receipt reads "Withdrawn". The app asks again on a new card.
5. **Failed.** If the app rejects the answer (for example, a stale state), the agent receives the app's error and explains it. If the app asked for a secret, no card appears; the agent explains that the app must use a secure link.
**Storybook.** `ui/storybook/stories/questions-and-approvals/mcp-elicitation-question-card.stories.tsx` covers these stories:
- Asking, with all field types.
- Answered.
- Skipped.
- Withdrawn or expired.
- Two questions at once.
The fixtures are generated from the server's own mapper output, so the stories show the real card.
## 5. Test plan (red on master, green on the branch)
| # | Test | Proves |
| --- | --- | --- |
| T1 | Fake 2026-07-28 server: `input_required` form produces a card and `elicitation_required`; answer, repeat the call, and the server receives `inputResponses` + exact `requestState` | D1, D7 modern |
| T2 | Same, with Skip producing `decline` and a withdrawn card producing `cancel` | D5 actions |
| T3 | Repeat before an answer: no upstream request | D1 |
| T4 | Two form keys in one round produce two cards; a single send carries both answers | Two questions at once |
| T5 | New gateway instance (simulated restart) between ask and repeat; a stale `claimed_at` is reclaimed | Restart-safe |
| T6 | Fake legacy server over SSE: first ask receives `cancel` immediately and gets a card; after the answer, the repeat call's stream receives `accept` + content | D7 legacy |
| T7 | A password field is refused: no card, `elicitation_sensitive_refused`, legacy receives `cancel` | D4 |
| T8 | Company B's session with the same tool and arguments does not collect company A's round; an agent actor cannot answer the card | Scope, permissions |
| T9 | Unit: every schema type maps and round-trips (SEP-1330 single/multi, titled/untitled, SEP-1034 defaults) | D3 |
| T10 | MCP Tasks suites stay green, and a Tasks card now has `human_only` and the app title | D8 |
| T11 | Capabilities: modern declares `form` only when the call has a task; legacy `initialize` declares form | D7 |
**Live demo.** A local fake 2026-07-28 server, connected as a custom remote MCP app in a dev instance. An agent calls it, the question appears in the task chat, the answer is submitted in the browser, and the agent finishes. This is recorded in the PR.
## 6. Risks and scope
- **Older servers that never asked may start asking.** Declaring form on `initialize` invites questions. Mitigation: the first ask is always answered `cancel` at once, so no call hangs, and the agent gets a clear next step.
- **Answer-ahead could answer a different intent.** It matches only the same task, connection, grant, agent, tool, arguments, message and schema, within 24 hours, once.
- **Stale cards.** Expiry is lazy. A card can sit unanswered past 24 hours until the agent next calls; answering it then just wakes the agent, which re-asks. This is acceptable without a poller.
- **Migration.** One additive table, with no backfill. It is online-safe.
**Out of scope (follow-ups):**
- Sampling and roots requests.
- Form elicitation from stdio apps (they keep URL only).
- Forms rendered inside an MCP App view.
- `resources/read` and `prompts/get` input rounds.
- The vendor `_meta.elicitation` answer path.
## Conclusion
The plan ships form elicitation for both MCP eras without blocking:
- The question becomes a named, human-only card.
- The answer travels on the agent's repeat call, sent once from durable state.
- Secrets and unsupported shapes are refused up front.
**Next:** build `mcp-elicitation.ts`, the table, the gateway wiring and the tests (T1–T11). Then add the stories and `doc/connections/MCP-ELICITATION.md`, and open the PR.
@@ -0,0 +1,30 @@
CREATE TABLE "tool_mcp_elicitations" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"issue_id" uuid NOT NULL,
"agent_id" uuid,
"run_id" uuid,
"invocation_id" uuid NOT NULL,
"connection_id" uuid NOT NULL,
"grant_id" uuid NOT NULL,
"catalog_tool_name" text NOT NULL,
"call_identity" text NOT NULL,
"era" text NOT NULL,
"sealed_request_state" text,
"questions" jsonb NOT NULL,
"arguments_identity" text NOT NULL,
"dedupe_key" text NOT NULL,
"status" text NOT NULL,
"claimed_until" timestamp with time zone,
"expires_at" timestamp with time zone NOT NULL,
"sent_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
ALTER TABLE "tool_mcp_elicitations" ADD CONSTRAINT "tool_mcp_elicitations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "tool_mcp_elicitations" ADD CONSTRAINT "tool_mcp_elicitations_invocation_id_tool_invocations_id_fk" FOREIGN KEY ("invocation_id") REFERENCES "public"."tool_invocations"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "tool_mcp_elicitations" ADD CONSTRAINT "tool_mcp_elicitations_connection_id_tool_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."tool_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
CREATE INDEX "tool_mcp_elicitations_call_idx" ON "tool_mcp_elicitations" USING btree ("company_id","issue_id","connection_id","call_identity","status");--> statement-breakpoint
CREATE INDEX "tool_mcp_elicitations_invocation_idx" ON "tool_mcp_elicitations" USING btree ("company_id","invocation_id");--> statement-breakpoint
CREATE UNIQUE INDEX "tool_mcp_elicitations_waiting_uq" ON "tool_mcp_elicitations" USING btree ("company_id","issue_id","dedupe_key") WHERE "tool_mcp_elicitations"."status" = 'waiting';
@@ -1,6 +1,6 @@
{
"id": "349cdd89-db04-4340-a5d3-3b877bf7227d",
"prevId": "d5d69127-12de-4281-9816-c20e013bfeb7",
"id": "ceaa38c4-681b-430e-9578-0854650d85b3",
"prevId": "8b353a38-62df-4834-be55-7e9ebefad5c5",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -18092,6 +18092,12 @@
"notNull": true,
"default": "'company'"
},
"system_purpose": {
"name": "system_purpose",
"type": "text",
"primaryKey": false,
"notNull": false
},
"owner_user_id": {
"name": "owner_user_id",
"type": "text",
@@ -35261,6 +35267,12 @@
"notNull": true,
"default": 1
},
"native_source_cursors": {
"name": "native_source_cursors",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"native_phase": {
"name": "native_phase",
"type": "text",
@@ -55947,6 +55959,153 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tailscale_connections": {
"name": "tailscale_connections",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"name": {
"name": "name",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true,
"default": "'pending'"
},
"secret_id": {
"name": "secret_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"credential_version": {
"name": "credential_version",
"type": "integer",
"primaryKey": false,
"notNull": false
},
"credential_hash": {
"name": "credential_hash",
"type": "text",
"primaryKey": false,
"notNull": false
},
"created_by_user_id": {
"name": "created_by_user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"oauth_state_hash": {
"name": "oauth_state_hash",
"type": "text",
"primaryKey": false,
"notNull": false
},
"oauth_expires_at": {
"name": "oauth_expires_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tailscale_connections_company_idx": {
"name": "tailscale_connections_company_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tailscale_connections_oauth_state_idx": {
"name": "tailscale_connections_oauth_state_idx",
"columns": [
{
"expression": "oauth_state_hash",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tailscale_connections_company_id_companies_id_fk": {
"name": "tailscale_connections_company_id_companies_id_fk",
"tableFrom": "tailscale_connections",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tailscale_connections_secret_id_company_secrets_id_fk": {
"name": "tailscale_connections_secret_id_company_secrets_id_fk",
"tableFrom": "tailscale_connections",
"tableTo": "company_secrets",
"columnsFrom": [
"secret_id"
],
"columnsTo": [
"id"
],
"onDelete": "no action",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_access_audit_events": {
"name": "tool_access_audit_events",
"schema": "",
@@ -59954,6 +60113,277 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_mcp_elicitations": {
"name": "tool_mcp_elicitations",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"issue_id": {
"name": "issue_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"agent_id": {
"name": "agent_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"run_id": {
"name": "run_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"invocation_id": {
"name": "invocation_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"grant_id": {
"name": "grant_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"catalog_tool_name": {
"name": "catalog_tool_name",
"type": "text",
"primaryKey": false,
"notNull": true
},
"call_identity": {
"name": "call_identity",
"type": "text",
"primaryKey": false,
"notNull": true
},
"era": {
"name": "era",
"type": "text",
"primaryKey": false,
"notNull": true
},
"sealed_request_state": {
"name": "sealed_request_state",
"type": "text",
"primaryKey": false,
"notNull": false
},
"questions": {
"name": "questions",
"type": "jsonb",
"primaryKey": false,
"notNull": true
},
"arguments_identity": {
"name": "arguments_identity",
"type": "text",
"primaryKey": false,
"notNull": true
},
"dedupe_key": {
"name": "dedupe_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"claimed_until": {
"name": "claimed_until",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"expires_at": {
"name": "expires_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true
},
"sent_at": {
"name": "sent_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tool_mcp_elicitations_call_idx": {
"name": "tool_mcp_elicitations_call_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "issue_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "call_identity",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "status",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_elicitations_invocation_idx": {
"name": "tool_mcp_elicitations_invocation_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "invocation_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_elicitations_waiting_uq": {
"name": "tool_mcp_elicitations_waiting_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "issue_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "dedupe_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"where": "\"tool_mcp_elicitations\".\"status\" = 'waiting'",
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_mcp_elicitations_company_id_companies_id_fk": {
"name": "tool_mcp_elicitations_company_id_companies_id_fk",
"tableFrom": "tool_mcp_elicitations",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_mcp_elicitations_invocation_id_tool_invocations_id_fk": {
"name": "tool_mcp_elicitations_invocation_id_tool_invocations_id_fk",
"tableFrom": "tool_mcp_elicitations",
"tableTo": "tool_invocations",
"columnsFrom": [
"invocation_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_mcp_elicitations_connection_id_tool_connections_id_fk": {
"name": "tool_mcp_elicitations_connection_id_tool_connections_id_fk",
"tableFrom": "tool_mcp_elicitations",
"tableTo": "tool_connections",
"columnsFrom": [
"connection_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_mcp_gateway_tokens": {
"name": "tool_mcp_gateway_tokens",
"schema": "",
+7
View File
@@ -3368,6 +3368,13 @@
"when": 1794604948355,
"tag": "0482_aberrant_rumiko_fujikawa",
"breakpoints": true
},
{
"idx": 483,
"version": "7",
"when": 1794611818460,
"tag": "0483_busy_tombstone",
"breakpoints": true
}
]
}
+1
View File
@@ -194,6 +194,7 @@ export {
toolMcpSkills,
toolMcpSkillFiles,
toolMcpTasks,
toolMcpElicitations,
toolActionRequests,
toolCallEvents,
toolRateLimitCounters,
+55
View File
@@ -966,6 +966,61 @@ export const toolMcpTasks = pgTable(
],
);
/**
* A provider's form question waiting on a person (MCP elicitation). One row per
* question round: a stateless server's `input_required` result, or one older
* server's `elicitation/create`. The question cards hold the answers; this row
* holds what the repeated call needs to send them back, exactly once.
*/
export const toolMcpElicitations = pgTable(
"tool_mcp_elicitations",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
issueId: uuid("issue_id").notNull(),
agentId: uuid("agent_id"),
runId: uuid("run_id"),
/** The call that was asked. */
invocationId: uuid("invocation_id").notNull().references(() => toolInvocations.id, { onDelete: "cascade" }),
connectionId: uuid("connection_id").notNull().references(() => toolConnections.id, { onDelete: "cascade" }),
/** Only the same grant's repeated call may send the answers. */
grantId: uuid("grant_id").notNull(),
catalogToolName: text("catalog_tool_name").notNull(),
/** Keyed identity of endpoint, tool, arguments, grant, and agent; only an identical call collects the round. */
callIdentity: text("call_identity").notNull(),
/** modern: a stateless input_required round. legacy: one server-initiated question. */
era: text("era").notNull(),
/** The server's opaque requestState, sealed (it may carry authority). */
sealedRequestState: text("sealed_request_state"),
/** One entry per form question: the server's key, its words and schema (shown on the card, never an answer), and its card. */
questions: jsonb("questions").$type<Array<{
key: string; questionHash: string;
/** The card's idempotency key: the round is saved before its cards, and a missing card is made again. */
cardKey: string;
interactionId?: string;
message: string; requestedSchema: Record<string, unknown> | null;
}>>().notNull(),
/** Keyed identity of the tool name and full arguments; a keyed retry runs again only for the same request. */
argumentsIdentity: text("arguments_identity").notNull(),
/** One waiting round per call (and per question, for older servers): matching calls at once share its cards. */
dedupeKey: text("dedupe_key").notNull(),
/** waiting | sent | expired */
status: text("status").notNull(),
/** A repeated call sending the answers holds the round until then. */
claimedUntil: timestamp("claimed_until", { withTimezone: true }),
expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
sentAt: timestamp("sent_at", { withTimezone: true }),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => [
index("tool_mcp_elicitations_call_idx").on(table.companyId, table.issueId, table.connectionId, table.callIdentity, table.status),
index("tool_mcp_elicitations_invocation_idx").on(table.companyId, table.invocationId),
uniqueIndex("tool_mcp_elicitations_waiting_uq").on(table.companyId, table.issueId, table.dedupeKey)
.where(sql`${table.status} = 'waiting'`),
],
);
/**
* Verified skill files, written only by the server after a size and SHA-256
* check and never changed in place. Rows are keyed by connection and digest,
@@ -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.
+218
View File
@@ -0,0 +1,218 @@
import { questionSetToAskUserQuestionsPayload, type AskUserQuestionsInteraction, type PaperclipQuestionSetPayload } from "@paperclipai/shared";
import { issueThreadInteractionFixtureMeta } from "./issueThreadInteractionFixtures";
/*
* Question cards an MCP app's form question becomes (MCP elicitation). The
* question sets are the exact output of the server's mapper
* (server/src/services/mcp-elicitation.ts, buildElicitationQuestionSet) for
* the schemas in doc/connections/MCP-ELICITATION.md, so these stories show
* the card people really see.
*/
/** Every spec field type: text with a default, titled single select, multi select, yes/no, integer. */
export const mcpTicketQuestionSet: PaperclipQuestionSetPayload = {
"schema": "paperclip.question_set.v1",
"title": "Linear needs your input",
"description": "Linear needs a few details to file this ticket.",
"submitLabel": "Send to Linear",
"questions": [
{
"id": "title",
"prompt": "Ticket title",
"required": true,
"answerMode": "text",
"initialText": "Login button does nothing",
"textValidation": {
"minLength": 3,
"maxLength": 80
}
},
{
"id": "priority",
"prompt": "Priority",
"required": true,
"answerMode": "single_select",
"options": [
{
"id": "choice_1",
"label": "Urgent"
},
{
"id": "choice_2",
"label": "Normal",
"recommended": true
},
{
"id": "choice_3",
"label": "Later"
}
]
},
{
"id": "labels",
"prompt": "Labels",
"required": false,
"helpText": "Choose at most 2.",
"answerMode": "multi_select",
"options": [
{
"id": "choice_1",
"label": "Bug",
"recommended": true
},
{
"id": "choice_2",
"label": "Design"
},
{
"id": "choice_3",
"label": "Speed"
}
]
},
{
"id": "page",
"prompt": "Page the on-call engineer?",
"required": false,
"answerMode": "single_select",
"options": [
{
"id": "choice_1",
"label": "Yes"
},
{
"id": "choice_2",
"label": "No",
"recommended": true
}
]
},
{
"id": "estimate",
"prompt": "Estimate (points)",
"required": false,
"answerMode": "text",
"textValidation": {
"inputType": "integer",
"minimum": 1,
"maximum": 8
}
}
]
};
/** A plain single-choice question. */
export const mcpTeamQuestionSet: PaperclipQuestionSetPayload = {
"schema": "paperclip.question_set.v1",
"title": "Linear needs your input",
"description": "Which team should own this?",
"submitLabel": "Send to Linear",
"questions": [
{
"id": "team",
"prompt": "Team",
"required": true,
"answerMode": "single_select",
"options": [
{
"id": "choice_1",
"label": "Platform"
},
{
"id": "choice_2",
"label": "Growth"
}
]
}
]
};
/** A form with no fields: the app asks to go ahead. */
export const mcpConfirmQuestionSet: PaperclipQuestionSetPayload = {
"schema": "paperclip.question_set.v1",
"title": "Linear needs your input",
"description": "Create the ticket now?",
"submitLabel": "Send to Linear",
"questions": [
{
"id": "continue",
"prompt": "Create the ticket now?",
"required": true,
"answerMode": "single_select",
"options": [
{
"id": "continue",
"label": "Continue"
}
]
}
]
};
function mcpQuestionCard(id: string, questionSet: PaperclipQuestionSetPayload, overrides: Partial<AskUserQuestionsInteraction> = {}): AskUserQuestionsInteraction {
return {
id,
companyId: issueThreadInteractionFixtureMeta.companyId,
issueId: issueThreadInteractionFixtureMeta.issueId,
kind: "ask_user_questions",
title: questionSet.title ?? null,
summary: questionSet.description ?? null,
status: "pending",
continuationPolicy: "wake_assignee",
createdByAgentId: "agent-codex",
createdByUserId: null,
resolvedByAgentId: null,
resolvedByUserId: null,
createdAt: new Date("2026-11-13T15:02:00.000Z"),
updatedAt: new Date("2026-11-13T15:02:00.000Z"),
resolvedAt: null,
payload: { ...questionSetToAskUserQuestionsPayload(questionSet), supersedeOnUserComment: false },
result: null,
...overrides,
} as AskUserQuestionsInteraction;
}
const resolvedAt = new Date("2026-11-13T15:06:00.000Z");
export const mcpAskingCard = mcpQuestionCard("mcp-elicit-asking", mcpTicketQuestionSet);
export const mcpAnsweredCard = mcpQuestionCard("mcp-elicit-answered", mcpTicketQuestionSet, {
status: "answered",
resolvedByUserId: issueThreadInteractionFixtureMeta.currentUserId,
resolvedAt,
updatedAt: resolvedAt,
result: {
version: 1,
answers: [
{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Login button does nothing on Safari" },
{ questionId: "priority", optionIds: ["choice_1"] },
{ questionId: "labels", optionIds: ["choice_1", "choice_3"] },
{ questionId: "page", optionIds: ["choice_2"] },
{ questionId: "estimate", optionIds: ["paperclip_text_answer"], otherText: "3" },
],
},
});
/** Skip sends "decline" to the app. */
export const mcpSkippedCard = mcpQuestionCard("mcp-elicit-skipped", mcpTeamQuestionSet, {
status: "cancelled",
resolvedByUserId: issueThreadInteractionFixtureMeta.currentUserId,
resolvedAt,
updatedAt: resolvedAt,
result: { version: 1, answers: [], outcome: "skipped" },
});
/** Nobody answered within a day: the card is withdrawn and the app is asked again. */
export const mcpExpiredCard = mcpQuestionCard("mcp-elicit-expired", mcpConfirmQuestionSet, {
status: "cancelled",
resolvedByAgentId: "agent-codex",
resolvedAt,
updatedAt: resolvedAt,
result: { version: 1, answers: [], outcome: "withdrawn", reason: "The app's question expired before it was answered." },
});
/** Two questions in one round: each is its own card, and both answers go back together. */
export const mcpTwoQuestionCards = [
mcpQuestionCard("mcp-elicit-two-a", mcpTeamQuestionSet),
mcpQuestionCard("mcp-elicit-two-b", mcpConfirmQuestionSet),
];
@@ -0,0 +1,99 @@
import { useState } from "react";
import type { Meta, StoryObj } from "@storybook/react-vite";
import { expect, userEvent, within } from "storybook/test";
import type { IssueThreadInteraction } from "@paperclipai/shared";
import { TaskChatInteractionCard } from "@/components/task-chat/TaskChatInteractionCard";
import { issueThreadInteractionFixtureMeta } from "@/fixtures/issueThreadInteractionFixtures";
import {
mcpAnsweredCard,
mcpAskingCard,
mcpExpiredCard,
mcpSkippedCard,
mcpTwoQuestionCards,
} from "@/fixtures/mcpElicitationFixtures";
import { storybookAgentMap } from "../../fixtures/paperclipData";
/**
* An MCP app asked the person a question in the middle of a tool call (MCP
* elicitation, doc/connections/MCP-ELICITATION.md). The card names the app,
* shows its message as plain text, and only people can answer it.
*/
function ElicitationCards({ interactions, presentation }: { interactions: IssueThreadInteraction[]; presentation: "takeover" | "timeline" }) {
const [sent, setSent] = useState<string[]>([]);
return (
<div className="mx-auto grid max-w-2xl gap-4 p-4">
{interactions.map((interaction) => (
<TaskChatInteractionCard
key={interaction.id}
item={{ id: `interaction:${interaction.id}`, kind: "interaction", interaction }}
presentation={presentation}
agentMap={storybookAgentMap}
currentUserId={issueThreadInteractionFixtureMeta.currentUserId}
onAcceptInteraction={async () => undefined}
onRejectInteraction={async () => undefined}
onSubmitInteractionAnswers={async () => { setSent((current) => [...current, interaction.id]); }}
onSubmitInteractionVerdicts={async () => undefined}
/>
))}
{sent.length ? <p className="text-sm text-muted-foreground" data-testid="sent">Sent to the app</p> : null}
</div>
);
}
const meta = {
id: "questions-and-approvals-mcp-elicitation-question-card",
title: "Tasks and conversations/Questions and approvals/MCP App Questions",
component: ElicitationCards,
parameters: {
layout: "fullscreen",
paperclip: {
"capabilities": [
"questions-and-approvals/questions"
],
"implementation": "production",
"boundary": "fixtures",
"notes": "Production question card with question sets produced by the server's MCP elicitation mapper. Sending answers back to the app, waking the agent, and the human-only rule are covered by server tests (server/src/__tests__/mcp-elicitation.test.ts)."
},
},
} satisfies Meta<typeof ElicitationCards>;
export default meta;
type Story = StoryObj<typeof meta>;
/** Asking: every spec field type, with the app's defaults filled in. */
export const Asking: Story = {
args: { interactions: [mcpAskingCard], presentation: "takeover" },
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await expect(await canvas.findByText("Linear needs your input")).toBeInTheDocument();
await expect(canvas.getByText("Linear needs a few details to file this ticket.")).toBeInTheDocument();
// The app's default is filled in and stays editable.
await expect(canvas.getByText("Login button does nothing")).toBeInTheDocument();
await expect(canvas.getByText("1 of 5")).toBeInTheDocument();
},
};
/** Answered: the receipt shows what went back to the app. */
export const Answered: Story = {
args: { interactions: [mcpAnsweredCard], presentation: "timeline" },
};
/** Skipped: the app was told the person declined. */
export const Skipped: Story = {
args: { interactions: [mcpSkippedCard], presentation: "timeline" },
};
/** Expired: nobody answered within a day, so the card was withdrawn and the app asks again. */
export const Expired: Story = {
args: { interactions: [mcpExpiredCard], presentation: "timeline" },
};
/** Two questions at once: each card is answered on its own; both answers go back together. */
export const TwoQuestions: Story = {
args: { interactions: mcpTwoQuestionCards, presentation: "takeover" },
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await expect(await canvas.findByText("Which team should own this?")).toBeInTheDocument();
await userEvent.click(canvas.getByRole("radio", { name: /Platform/ }));
},
};