test(#15705): pin the flow input contract on list_actions

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Author: claude

packages/runtime/src/action-flow-input-params.test.ts

@@ -0,0 +1,152 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `list_actions` publishes a FLOW action's input names (#15705).
+ *
+ * The MCP `list_actions` tool description promises each action's "input
+ * parameters", and `summarizeActionParams` delivered them by iterating
+ * `action.params` — the script-action declaration. A flow-typed action almost
+ * never declares `params`: its input contract is the target flow's `isInput`
+ * variables, which is what `seedDeclaredVariables` binds the caller's bag into.
+ * So every flow action listed with no `params` key at all, and an agent could
+ * see the action, could invoke it, and had no way to learn a single input name
+ * — the reported reproduction passed `due_date` where the flow declares
+ * `dueDate` because guessing was the only move available.
+ *
+ * Pinned here:
+ *
+ *  1. the inputs are published, in declaration order, with the collecting
+ *     screen field's `label` / `type` / `required` / `options` folded in;
+ *  2. a variable that is NOT `isInput` stays private — the listing publishes an
+ *     input contract, not the flow's internals;
+ *  3. an author's own `action.params` still WINS, so this can only fill a
+ *     silence and no existing listing changes shape;
+ *  4. every absence is inert: no flow, a flow with no variables, a non-flow
+ *     action — all answer exactly as they did before.
+ *
+ * `required` is read off the screen field alone. A flow variable has no
+ * `required` key, and inferring one from "declares no `defaultValue`" would
+ * invent a contract the author never wrote — the same reason the executor's
+ * satisfaction verdict one package over reads `required` from the field spec.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import {
+    summarizeAction,
+    summarizeActionParams,
+    summarizeFlowInputParams,
+} from './action-execution.js';
+
+const NO_DEPS: any = {};
+
+/** The card's specimen: `schedule_followup`, `type: 'flow'`, no declared params. */
+const FLOW_ACTION = {
+    name: 'schedule_followup',
+    label: 'Schedule Follow-up',
+    type: 'flow',
+    target: 'schedule_followup',
+    ai: { exposed: true },
+    locations: ['record_header'],
+};
+
+/**
+ * The target flow. `internal_cursor` is deliberately not an input, and
+ * `activityType` is collected on a SECOND screen — a wizard's later step is
+ * still part of the input contract.
+ */
+const FLOW = {
+    name: 'schedule_followup',
+    type: 'screen',
+    variables: [
+        { name: 'subject', type: 'text', isInput: true },
+        { name: 'dueDate', type: 'text', isInput: true },
+        { name: 'activityType', type: 'text', isInput: true },
+        { name: 'internal_cursor', type: 'number', isInput: false },
+    ],
+    nodes: [
+        { id: 'start', type: 'start' },
+        {
+            id: 'screen_1', type: 'screen',
+            config: {
+                fields: [
+                    { name: 'subject', label: 'Subject', type: 'text', required: true },
+                    { name: 'dueDate', label: 'Due date', type: 'date', required: true },
+                ],
+            },
+        },
+        {
+            id: 'screen_2', type: 'screen',
+            config: {
+                fields: [
+                    {
+                        name: 'activityType', label: 'Activity type', type: 'select',
+                        options: [{ value: 'call', label: 'Call' }, { value: 'email', label: 'Email' }],
+                    },
+                ],
+            },
+        },
+        { id: 'end', type: 'end' },
+    ],
+};
+
+describe('summarizeFlowInputParams (#15705)', () => {
+    it('publishes every isInput variable, in declaration order, enriched from its screen field', () => {
+        expect(summarizeFlowInputParams(NO_DEPS, FLOW)).toEqual([
+            { name: 'subject', type: 'string', required: true, description: 'Subject' },
+            { name: 'dueDate', type: 'string', required: true, description: 'Due date' },
+            {
+                name: 'activityType', type: 'string', required: false,
+                description: 'Activity type', enum: ['call', 'email'],
+            },
+        ]);
+    });
+
+    it('keeps a non-input variable private', () => {
+        const names = summarizeFlowInputParams(NO_DEPS, FLOW).map((p) => p.name);
+        expect(names).not.toContain('internal_cursor');
+    });
+
+    it('lists an input no screen collects — without the screen-only enrichments', () => {
+        const flow = { ...FLOW, variables: [{ name: 'silent', type: 'number', isInput: true }] };
+        expect(summarizeFlowInputParams(NO_DEPS, flow)).toEqual([
+            { name: 'silent', type: 'number', required: false },
+        ]);
+    });
+
+    it('is inert on every absence', () => {
+        expect(summarizeFlowInputParams(NO_DEPS, undefined)).toEqual([]);
+        expect(summarizeFlowInputParams(NO_DEPS, {})).toEqual([]);
+        expect(summarizeFlowInputParams(NO_DEPS, { variables: [] })).toEqual([]);
+        expect(summarizeFlowInputParams(NO_DEPS, { variables: [{ name: 'x', isInput: false }] })).toEqual([]);
+    });
+});
+
+describe('summarizeActionParams / summarizeAction fall back to the flow (#15705)', () => {
+    it('CONTROL — the reported shape: no flow resolved, no params key, exactly as before', () => {
+        expect(summarizeActionParams(NO_DEPS, FLOW_ACTION, undefined)).toEqual([]);
+        expect(summarizeAction(NO_DEPS, FLOW_ACTION, undefined, 'crm_lead')).not.toHaveProperty('params');
+    });
+
+    it('surfaces the flow inputs once the flow is resolved', () => {
+        const summary = summarizeAction(NO_DEPS, FLOW_ACTION, undefined, 'crm_lead', FLOW);
+        expect(summary.params.map((p: any) => p.name)).toEqual(['subject', 'dueDate', 'activityType']);
+        // The rest of the summary is untouched by this change.
+        expect(summary).toMatchObject({ name: 'schedule_followup', type: 'flow', requiresRecord: true });
+    });
+
+    it("CONTROL — an author's own declared params still win outright", () => {
+        const declaring = {
+            ...FLOW_ACTION,
+            params: [{ name: 'only_this', type: 'text', required: true, label: 'Only this' }],
+        };
+        const params = summarizeActionParams(NO_DEPS, declaring, undefined, FLOW);
+        expect(params.map((p: any) => p.name)).toEqual(['only_this']);
+    });
+
+    it('CONTROL — a non-flow action handed a flow is unchanged (the caller resolves none)', () => {
+        const script = { name: 'close_case', type: 'script', target: 'closeCase', locations: ['record_header'] };
+        expect(summarizeActionParams(NO_DEPS, script, undefined)).toEqual([]);
+        expect(summarizeAction(NO_DEPS, script, undefined, 'crm_case')).not.toHaveProperty('params');
+    });
+});

packages/runtime/src/mcp-list-actions-flow-params.test.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The WIRE half of #15705: `list_actions` asks the automation service for the
+ * flow behind a flow action, so the input names actually reach the agent.
+ *
+ * `summarizeActionParams`' own pins (`action-flow-input-params.test.ts`) prove
+ * the projection. They cannot prove anybody performs it: the bridge held only
+ * `Boolean(automationService)` and passed the summary no flow at all, so the
+ * projection would have sat unreachable behind a green unit suite — the exact
+ * "declared but nothing calls it" shape. This file pins the call.
+ *
+ * `getFlow` is OPTIONAL on `IAutomationService`, so the degradation is pinned
+ * too: a service that does not implement it, and a flow the registry does not
+ * hold, both answer exactly as the listing answered before this change.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { HttpDispatcher } from './http-dispatcher.js';
+
+/** The card's specimen, as an object-embedded declaration. */
+const FLOW_ACTION = {
+    name: 'schedule_followup',
+    label: 'Schedule Follow-up',
+    objectName: 'crm_lead',
+    type: 'flow',
+    target: 'schedule_followup',
+    locations: ['record_header'],
+    ai: { exposed: true, description: 'Schedule a follow-up task for this lead.' },
+};
+
+const FLOW = {
+    name: 'schedule_followup',
+    type: 'screen',
+    variables: [
+        { name: 'subject', type: 'text', isInput: true },
+        { name: 'dueDate', type: 'text', isInput: true },
+    ],
+    nodes: [
+        { id: 'start', type: 'start' },
+        {
+            id: 'screen_1', type: 'screen',
+            config: {
+                fields: [
+                    { name: 'subject', label: 'Subject', type: 'text', required: true },
+                    { name: 'dueDate', label: 'Due date', type: 'date', required: true },
+                ],
+            },
+        },
+    ],
+};
+
+function makeBridge(automation: any) {
+    const object = { name: 'crm_lead', label: 'Lead', fields: {}, actions: [FLOW_ACTION] };
+    const ql: any = {
+        executeAction: vi.fn(),
+        registry: { getObject: () => object },
+        find: vi.fn(async () => []),
+        insert: vi.fn(), update: vi.fn(), delete: vi.fn(),
+    };
+    const metadata: any = {
+        listObjects: vi.fn(async () => [object]),
+        getObject: vi.fn(async () => object),
+    };
+    const kernel: any = {
+        context: {
+            getService: (n: string) =>
+                n === 'objectql' || n === 'data' ? ql : n === 'metadata' ? metadata : n === 'automation' ? automation : null,
+        },
+    };
+    const dispatcher = new HttpDispatcher(kernel);
+    const ctx: any = {
+        request: {}, environmentId: 'platform',
+        executionContext: { userId: 'u1', systemPermissions: [] },
+    };
+    return (dispatcher as any).buildMcpBridge(ctx);
+}
+
+async function listed(automation: any) {
+    const actions = await makeBridge(automation).listActions();
+    return actions.find((a: any) => a.name === 'schedule_followup');
+}
+
+describe('list_actions surfaces a flow action’s inputs (#15705)', () => {
+    it('asks getFlow for the action’s target and publishes the flow’s inputs as params', async () => {
+        const getFlow = vi.fn(async () => FLOW);
+        const summary = await listed({ execute: vi.fn(), getFlow });
+        expect(getFlow).toHaveBeenCalledWith('schedule_followup');
+        expect(summary.params).toEqual([
+            { name: 'subject', type: 'string', required: true, description: 'Subject' },
+            { name: 'dueDate', type: 'string', required: true, description: 'Due date' },
+        ]);
+    });
+
+    it('CONTROL — the reported shape: a service with no getFlow lists exactly as before', async () => {
+        const summary = await listed({ execute: vi.fn() });
+        expect(summary).toBeDefined();
+        expect(summary).not.toHaveProperty('params');
+        expect(summary).toMatchObject({ name: 'schedule_followup', type: 'flow', requiresRecord: true });
+    });
+
+    it('CONTROL — a target the registry does not hold degrades to the same shape', async () => {
+        const summary = await listed({ execute: vi.fn(), getFlow: vi.fn(async () => null) });
+        expect(summary).not.toHaveProperty('params');
+    });
+
+    it('CONTROL — a getFlow that THROWS does not fail the listing', async () => {
+        const summary = await listed({
+            execute: vi.fn(),
+            getFlow: vi.fn(async () => { throw new Error('registry unavailable'); }),
+        });
+        expect(summary).toBeDefined();
+        expect(summary).not.toHaveProperty('params');
+    });
+});