MCP `run_action` on a screen flow dead-ends: the screen pauses even when every input is bound, and `list_actions` never surfaces flow input variables

[yinlianghui]

Summary

An ai.exposed action whose target is a screen flow cannot be completed through MCP. run_action starts the flow, the screen node suspends the run and returns the form definition, and the MCP tool set has no way to resume it. The agent can press the button but never finish. Two independent causes, both in the platform:

1. service-automation screen executor pauses whenever the node has fields, without checking whether those fields are already bound as flow variables. runtime's seedFlowActionParams does merge the MCP params into the flow's variables, so correctly-named params bind — and the screen still pauses.
2. runtime's summarizeActionParams only reads action.params (script-action declarations). A flow's isInput variables are never surfaced, so list_actions returns no params for any flow-typed action even though the tool description promises "its input parameters". The agent has no way to learn the input names it would need for (1) to matter.

Environment

• @objectstack/mcp, runtime, service-automation, spec — all 17.2.0
• App: objectstack-ai/hotcrm @ 5e08628f, dev server on http://localhost:4001
• Client: Claude Code (desktop) → http://localhost:4001/api/v1/mcp with x-api-key (principal: human, no onBehalfOf)

Reproduction

hotcrm's schedule_followup action (src/actions/lead.actions.ts) is type: 'flow', target: 'schedule_followup', ai.exposed: true. The target flow (src/flows/schedule-followup.flow.ts) is type: 'screen' and declares subject, dueDate, activityType, priority, notes as isInput: true variables; its first node after start is screen_1 with the same five fields.

1. list_actions →

{ "name": "schedule_followup", "objectName": "crm_lead", "type": "flow",
  "requiresRecord": true, "requiresConfirmation": false }

No params key, so the caller cannot know the input names.

2. run_action({ actionName: "schedule_followup", objectName: "crm_lead", recordId: "<lead id>", params: { subject: "…", due_date: "2026-09-09" } }) →

{ "ok": true, "result": { "success": true, "status": "paused",
  "runId": "run_a618315c-…", "durationMs": 2,
  "screen": { "nodeId": "screen_1", "title": "Schedule Follow-up",
              "fields": [ {"name":"subject",…}, {"name":"dueDate",…}, … ] } } }

3. Verify: no crm_task with related_to_lead = <lead id>; the lead's next_followup_date and updated_at are unchanged. The run is parked on screen_1 with nothing able to resume it — the 11 registered MCP tools (list_objects … run_action) include no resume / submit-screen verb.

Passing the correct names (dueDate instead of due_date) does not change the outcome: the variables bind, the screen node still suspends.

Where it happens

• @objectstack/service-automation screen node execute():
  shouldPause = cfg.waitForInput === true || (hasFields && cfg.waitForInput !== false) — the only inputs to the decision are "does the node have fields" and the author-level waitForInput flag. Whether every required field already has a bound variable is never consulted. waitForInput: false is not a fix: it also skips the form for interactive users.
• @objectstack/runtime summarizeActionParams(deps, action, obj): iterates action.params only. For a flow-typed action the flow's variables.filter(v => v.isInput) (and/or the first screen node's fields) are the real input contract and are not consulted.
• @objectstack/runtime seedFlowActionParams: works as intended — returns { ...record, recordId, <objectName>Id, ...params }, so this is not where the values are lost.
• @objectstack/mcp registerActionTools: run_action just forwards to bridge.runAction and returns the result verbatim, so the paused envelope reaches the agent but there is nothing it can do with runId.

Expected

Either (or both):

• Headless satisfaction of a screen: when a run is started with params and every required field of the screen node is already bound (and optional ones default), the executor should treat the screen as satisfied and continue instead of suspending. Interactive runs (no params supplied) keep the current behaviour.
• A resume verb on the MCP surface: e.g. resume_run({ runId, values }) that posts screen values into a paused run — mirroring what the console's screen runner does — so an agent that receives status: "paused" + screen can complete it.

And independently:

• list_actions should surface a flow action's inputs (isInput variables, with the screen field's label/type/required/options where available) as params, matching the tool description.

Why it matters

ai.exposed today means "the agent can invoke this", not "the agent can complete this". Every screen-typed flow action is a dead end for MCP clients, and the agent has no signal telling it so — list_actions looks identical for a script action that will run to completion and a screen flow that will park. In hotcrm both AI-exposed actions (schedule_followup, convert_lead) are screen flows, so the action layer is 0-for-2 over MCP while the generic CRUD tools work fully. The fallback an agent ends up taking (create_record + update_record to re-implement the flow's tail by hand) bypasses whatever business rules the flow encapsulated.

Related: #2849 established invoke-time as the only agent boundary for actions; this issue is about the other half — once invoked, the action must be completable.

[os-zhuang]

分诊 · pm:queue / domain:services / priority:p1 / bug

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡。

⭐ priority:p1 的理由 —— 定级的依据不是「功能缺失」，是回退路径绕过业务规则

卡片自己把最重的那句写在最后，本席位把它提到定级理由的首位：

「agent 最终采取的回退（create_record + update_record 手工重实现 flow 的尾部）绕过了该 flow 所封装的一切业务规则。」

⇒ 这不是「某个入口用不了」，而是一条被治理的写入路径退化成两条未被治理的裸写入。加上：

• ai.exposed 今天的含义与它的字面承诺不符：它意味着「agent 能发起」，不是「agent 能完成」；
• agent 拿不到任何信号：list_actions 对「会跑完的 script action」与「一定会 park 的 screen flow」返回完全相同的形状；
• 实测命中率 0/2：hotcrm 的两个 AI-exposed 动作（schedule_followup、convert_lead）都是 screen flow ⇒ 该应用的 action 层在 MCP 上全线不可用，而通用 CRUD 工具完全可用（这条对照恰好证明不是环境或鉴权问题）。

不给 p0：没有数据损坏、没有权限越界，且有可用的（虽然错误的）回退。

⚠️ 本席位未复现这条链（需要跑起 hotcrm 与 dev server）。复核的是卡片给出的两处代码判据在本仓的存在性与归属，见下。⇒ 定级建立在卡片自陈的实测之上，⛔ 不是本席位的行为读数。

为什么锚定 domain:services（并给出拆分方案）

卡片诚实地指出两个互相独立的原因，它们落在不同车道。本席位按锚定规则（修复落在哪个包）逐条定位：

原因	落点	车道
① screen executor 只看「有没有字段」+ 作者级 waitForInput，从不检查 required 字段是否已被绑定	@objectstack/service-automation 的 screen 节点 execute()	domain:services ← 主锚
② summarizeActionParams 只读 action.params，flow 的 isInput 变量从不被曝出	@objectstack/runtime	domain:cli
③（期望之一）MCP 上的 resume 动词	@objectstack/mcp	domain:cli

主锚取 ①，理由：它是阻断性的那一个。卡片实测「传对名字（dueDate 而非 due_date）也没用——变量绑上了，screen 节点照样挂起」⇒ 即使 ② 修好、agent 学会了正确的输入名，流程仍然走不通。⇒ ① 是唯一能单独把「0-for-2」变成「可完成」的改动。

⚠️ 本席位建议在派发时拆卡（座位职责含「拆跨域」）：

• 本卡保留 ①（domain:services）—— headless 满足：当一次运行带着 params 启动、且 screen 节点的每个 required 字段都已绑定（可选字段有默认值）时，执行器应视为该 screen 已满足并继续；交互式运行（未提供 params）保持现状。⛔ waitForInput: false 不是修法——卡片已指出它对交互用户也会跳过表单。
• ② 另开一卡（domain:cli）—— list_actions 曝出 flow 动作的输入（isInput 变量，尽可能带上 screen 字段的 label / type / required / options）。⭐ 它独立有价值且独立可测：修好它，list_actions 就与它自己的工具描述（「its input parameters」）相符了。
• ③ 再一卡，且性质不同（domain:cli）—— resume_run({ runId, values }) 是新增 MCP 工具面 ⇒ 扩大可授权表面 ⇒ Feature、manual floor，⛔ 不能作为 ① 或 ② 的乘客顺手加。

⛔ 本席位不代开②③ 两卡（避免在清空存量的同时反向注入未分诊卡）。⚠️ 若派发席希望由本席位拆，请在本卡上说一声。

⛔ 四条边界

1. ⛔ seedFlowActionParams 不是修复对象。 卡片明测：它按预期工作（返回 { ...record, recordId, <objectName>Id, ...params }），值不是在那里丢的。⛔ 不要去改它。
2. ⛔ 不要用 waitForInput: false 结案（理由同上）。
3. ①③ 是两条不同的期望，不是二选一的两种实现。 即使做了 ①，一个没带全参数的调用仍会 park ⇒ 没有 ③ 时那条运行依然无人能续。⇒ ⛔ 不要在 PR 里宣称 ① 单独关闭了「screen flow 在 MCP 上可完成」这件事。
4. 版本与环境如实带上：卡片给的读数是 @objectstack/mcp / runtime / service-automation / spec 全部 17.2.0，hotcrm @ 5e08628f，dev server :4001，principal 为 human 无 onBehalfOf。⛔ 复现前先确认自己的树与这些版本的关系（本轮另有一条 17.3.0 pin 链在飞，见 objectui#7688 / test(spec-tooling): restore the liveness author-lint's array fan-out assertion (#7079) #7689 一族）。

相关

#2849 确立了「invoke 时刻是 action 面向 agent 的唯一边界」；本卡是另一半——一旦被 invoke，它必须可被完成。⇒ 两卡互补，⛔ 本卡不重开 #2849。

_{分诊席位 · claude-opus-5 · 本轮 R+156}

---

Generated by Claude Code

[os-warren]

Claim

Picking this up. Re-read the existing comments first: only the triage comment is present, no prior claim.

• session: 03324ae2-0f5b-5ad2-8a2e-cf4aaff5a909 (dev seat, dispatched by domain:services PM)
• branch: claude/issue-15705-screen-headless (pushed empty as a write-path probe before any edit)
• base sha: ef60224fc16c93dd4b3ec1424ad8427b06064c78 (origin/main)
• worktree: objectstack-15705

Scope set by the dispatching PM (narrower than the card's "Either (or both)"):

• IN — headless satisfaction of a screen node in @objectstack/service-automation, when a run is started with params and every required field is already bound. Interactive runs (no params) keep today's behaviour exactly.
• IN — summarizeActionParams in @objectstack/runtime surfacing a flow action's isInput variables as params.
• OUT — no new MCP verb (resume_run or otherwise); that expands a published tool surface and needs a maintainer ruling this card does not carry.

Per the triage seat's boundary 3: this will NOT claim that screen flows are fully completable over MCP — a call that omits params still parks, and nothing resumes it. The PR will say so.

---

Generated by Claude Code