@theia/ai-ide 1.76.0-next.7 → 1.76.0

package/src/common/user-interaction-tool.spec.ts

@@ -15,205 +15,256 @@
 // *****************************************************************************
 
 import { expect } from 'chai';
-import { buildDiffLabel, parseUserInteractionArgs, parseUserInteractionInput } from './user-interaction-tool';
+import { UserInteractionArgs, buildDiffLabel, parseUserInteractionArgs, parseUserInteractionInput } from './user-interaction-tool';
+
+function expectRejected(input: string | undefined): string {
+    const result = parseUserInteractionArgs(input);
+    expect(result.ok, `expected a rejection but got: ${JSON.stringify(result)}`).to.be.false;
+    return (result as { ok: false, error: string }).error;
+}
+
+function expectAccepted(input: string): UserInteractionArgs {
+    const result = parseUserInteractionArgs(input);
+    expect(result.ok, `expected acceptance but got: ${JSON.stringify(result)}`).to.be.true;
+    return (result as { ok: true, args: UserInteractionArgs }).args;
+}
 
 describe('parseUserInteractionArgs', () => {
-    it('should return undefined for undefined input', () => {
-        expect(parseUserInteractionArgs(undefined)).to.be.undefined;
-    });
 
-    it('should return undefined for invalid JSON', () => {
-        expect(parseUserInteractionArgs('not json')).to.be.undefined;
-    });
+    describe('rejecting malformed arguments', () => {
 
-    it('should return undefined when interactions is missing', () => {
-        const input = JSON.stringify({ foo: 'bar' });
-        expect(parseUserInteractionArgs(input)).to.be.undefined;
-    });
+        it('should reject undefined input', () => {
+            expect(expectRejected(undefined)).to.match(/no arguments/i);
+        });
 
-    it('should return undefined when interactions is not an array', () => {
-        const input = JSON.stringify({ interactions: 'nope' });
-        expect(parseUserInteractionArgs(input)).to.be.undefined;
-    });
+        it('should reject input that is not valid JSON', () => {
+            expect(expectRejected('not json')).to.match(/valid JSON/i);
+        });
 
-    it('should return undefined when no step is valid', () => {
-        const input = JSON.stringify({ interactions: [{ foo: 'bar' }, { title: 1 }] });
-        expect(parseUserInteractionArgs(input)).to.be.undefined;
-    });
+        it('should reject arguments without an interactions property', () => {
+            expect(expectRejected(JSON.stringify({ foo: 'bar' }))).to.match(/"interactions" must be an array of step objects/);
+        });
 
-    it('should drop steps that are missing title or message', () => {
-        const input = JSON.stringify({
-            interactions: [
-                { title: 'Valid', message: 'Hello' },
-                { title: 'No message' },
-                { message: 'No title' }
-            ]
+        it('should reject a JSON-encoded argument blob and name the received type', () => {
+            const error = expectRejected(JSON.stringify('{"interactions":[{"title":"T","message":"M"}]}'));
+            expect(error).to.match(/arguments must be an object with an "interactions" array, received string/i);
+            expect(error).to.match(/do not JSON-encode nested values/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result).to.not.be.undefined;
-        expect(result!.interactions).to.have.length(1);
-        expect(result!.interactions[0].title).to.equal('Valid');
-    });
 
-    it('should accept a step without options (informational)', () => {
-        const input = JSON.stringify({
-            interactions: [{ title: 'Info', message: 'Just so you know' }]
+        it('should reject a top-level array', () => {
+            expect(expectRejected('[]')).to.match(/arguments must be an object with an "interactions" array, received array/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result).to.not.be.undefined;
-        expect(result!.interactions[0].options).to.be.undefined;
-    });
 
-    it('should filter out invalid options within a step', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ text: 'A', value: 'a' }, { bad: true }, { text: 'B', value: 'b' }]
-            }]
+        it('should reject top-level null', () => {
+            expect(expectRejected('null')).to.match(/arguments must be an object with an "interactions" array, received null/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].options).to.have.length(2);
-    });
 
-    it('should drop options array if no options are valid', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ bad: true }]
-            }]
+        it('should reject a JSON-encoded interactions string and name the received type', () => {
+            const error = expectRejected(JSON.stringify({ interactions: '[{"title":"T","message":"M"}]' }));
+            expect(error).to.match(/"interactions" must be an array of step objects, received string/);
+            expect(error).to.match(/do not JSON-encode nested values/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].options).to.be.undefined;
-    });
 
-    it('should normalize singular link into a links array on a step', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ text: 'A', value: 'a' }],
-                link: { ref: 'src/index.ts' }
-            }]
+        it('should reject an empty interactions array', () => {
+            expect(expectRejected(JSON.stringify({ interactions: [] }))).to.match(/at least one step/);
+        });
+
+        it('should reject a step that is missing its message, naming the step position', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ title: 'Valid', message: 'Hello' }, { title: 'No message' }]
+            }));
+            expect(error).to.match(/step 2: "title" and "message" are required strings/i);
+        });
+
+        it('should reject a step that is missing its title, naming the step position', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ message: 'No title' }]
+            }));
+            expect(error).to.match(/step 1: "title" and "message" are required strings/i);
+        });
+
+        it('should reject a step whose options are a JSON-encoded string', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ title: 'Apply fix?', message: 'M', options: '[{"text":"Yes","value":"yes"}]' }]
+            }));
+            expect(error).to.match(/step 1: "options" must be an array of \{text, value\} objects, received string/i);
+            expect(error).to.match(/do not JSON-encode nested values/i);
+        });
+
+        it('should reject a step when a single option is malformed, even though others are valid', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    options: [{ text: 'A', value: 'a' }, { label: 'B', value: 'b' }, { text: 'C', value: 'c' }]
+                }]
+            }));
+            expect(error).to.match(/step 1, option 2: "text" and "value" are required strings/i);
+        });
+
+        it('should reject options given as an object rather than an array', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ title: 'T', message: 'M', options: { text: 'Yes', value: 'yes' } }]
+            }));
+            expect(error).to.match(/step 1: "options" must be an array of \{text, value\} objects, received object/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links).to.deep.equal([{ ref: 'src/index.ts' }]);
-    });
 
-    it('should accept a links array with multiple entries', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ text: 'A', value: 'a' }],
-                links: [
-                    { ref: 'src/a.ts' },
-                    { ref: 'src/old.ts', rightRef: 'src/new.ts' }
+        it('should reject plain string options and name the received type', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ title: 'T', message: 'M', options: ['Yes', 'No'] }]
+            }));
+            expect(error).to.match(/step 1, option 1: "text" and "value" are required strings, received string/i);
+            expect(error).to.match(/do not JSON-encode nested values/i);
+        });
+
+        it('should reject a JSON-encoded links string', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [{ title: 'T', message: 'M', links: '[{"ref":"a.ts"}]' }]
+            }));
+            expect(error).to.match(/step 1: "links" must be an array of link objects, received string/i);
+            expect(error).to.match(/do not JSON-encode nested values/i);
+        });
+
+        it('should report the offending option position within the offending step', () => {
+            const error = expectRejected(JSON.stringify({
+                interactions: [
+                    { title: 'Fine', message: 'M', options: [{ text: 'A', value: 'a' }] },
+                    { title: 'Broken', message: 'M', options: [{ text: 'A', value: 'a' }, { text: 'B' }] }
                 ]
-            }]
+            }));
+            expect(error).to.match(/step 2, option 2: "text" and "value" are required strings/i);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links).to.have.length(2);
     });
 
-    it('should filter out invalid links from a step', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ text: 'A', value: 'a' }],
-                links: [
-                    { ref: 'src/a.ts' },
-                    { noRef: true },
-                    { ref: '' }
+    describe('accepting well-formed arguments', () => {
+
+        it('should accept a step without options (informational)', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{ title: 'Info', message: 'Just so you know' }]
+            }));
+            expect(args.interactions[0].options).to.be.undefined;
+        });
+
+        it('should accept an explicitly empty options array as informational', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{ title: 'Info', message: 'Just so you know', options: [] }]
+            }));
+            expect(args.interactions[0].options).to.be.undefined;
+        });
+
+        it('should accept multiple steps in order', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [
+                    { title: 'Overview', message: 'PR summary' },
+                    { title: 'Area 1', message: 'finding', options: [{ text: 'OK', value: 'approve' }] },
+                    { title: 'Area 2', message: 'no findings' }
                 ]
-            }]
+            }));
+            expect(args.interactions).to.have.length(3);
+            expect(args.interactions[1].options).to.have.length(1);
+            expect(args.interactions[2].options).to.be.undefined;
+        });
+
+        it('should preserve buttonLabel and description in options', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    options: [{ text: 'Confirm changes', value: 'confirm', description: 'Applies the patch', buttonLabel: '✅ Confirm' }]
+                }]
+            }));
+            expect(args.interactions[0].options![0].buttonLabel).to.equal('✅ Confirm');
+            expect(args.interactions[0].options![0].description).to.equal('Applies the patch');
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links).to.have.length(1);
     });
 
-    it('should ignore invalid rightRef placeholders and keep multi-step file links', () => {
-        const emptyRightRefPlaceholder = {
-            path: '',
-            gitRef: '',
-            line: 0,
-            empty: false,
-            label: ''
-        };
-        const input = JSON.stringify({
-            interactions: ['README.md', 'package.json', 'CONTRIBUTING.md'].map((path, index) => ({
-                title: `File link: ${path}`,
-                message: 'Open the file link.',
-                links: [{
-                    ref: { path, gitRef: '', line: 1, empty: false, label: '' },
-                    rightRef: emptyRightRefPlaceholder,
-                    label: `Open ${path}`,
-                    autoOpen: index === 0
+    describe('links remain leniently filtered', () => {
+
+        it('should normalize a singular link into a links array on a step', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    options: [{ text: 'A', value: 'a' }],
+                    link: { ref: 'src/index.ts' }
                 }]
-            }))
+            }));
+            expect(args.interactions[0].links).to.deep.equal([{ ref: 'src/index.ts' }]);
         });
 
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions.map(step => step.links![0])).to.deep.equal([
-            { ref: { path: 'README.md', line: 1 }, label: 'Open README.md', autoOpen: true },
-            { ref: { path: 'package.json', line: 1 }, label: 'Open package.json', autoOpen: false },
-            { ref: { path: 'CONTRIBUTING.md', line: 1 }, label: 'Open CONTRIBUTING.md', autoOpen: false }
-        ]);
-    });
+        it('should accept a links array with multiple entries', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    links: [{ ref: 'a.ts' }, { ref: 'b.ts', label: 'B' }]
+                }]
+            }));
+            expect(args.interactions[0].links).to.have.length(2);
+        });
 
-    it('should accept multiple steps in order', () => {
-        const input = JSON.stringify({
-            interactions: [
-                { title: 'Overview', message: 'PR summary' },
-                { title: 'Area 1', message: 'finding', options: [{ text: 'OK', value: 'approve' }] },
-                { title: 'Area 2', message: 'no findings' }
-            ]
+        it('should drop invalid links from a step without rejecting the step', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    links: [{ ref: 'a.ts' }, { nope: true }, { ref: 42 }]
+                }]
+            }));
+            expect(args.interactions[0].links).to.have.length(1);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions).to.have.length(3);
-        expect(result!.interactions[1].options).to.have.length(1);
-        expect(result!.interactions[2].options).to.be.undefined;
-    });
 
-    it('should preserve buttonLabel in options', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                options: [{ text: 'Confirm changes', value: 'confirm', buttonLabel: '✅ Confirm' }]
-            }]
+        it('should ignore invalid rightRef placeholders and keep multi-step file links', () => {
+            const emptyRightRefPlaceholder = {
+                path: '',
+                gitRef: '',
+                line: 0,
+                empty: false,
+                label: ''
+            };
+            const args = expectAccepted(JSON.stringify({
+                interactions: ['README.md', 'package.json', 'CONTRIBUTING.md'].map((path, index) => ({
+                    title: `File link: ${path}`,
+                    message: 'Open the file link.',
+                    links: [{
+                        ref: { path, gitRef: '', line: 1, empty: false, label: '' },
+                        rightRef: emptyRightRefPlaceholder,
+                        label: `Open ${path}`,
+                        autoOpen: index === 0
+                    }]
+                }))
+            }));
+            expect(args.interactions.map(step => step.links![0])).to.deep.equal([
+                { ref: { path: 'README.md', line: 1 }, label: 'Open README.md', autoOpen: true },
+                { ref: { path: 'package.json', line: 1 }, label: 'Open package.json', autoOpen: false },
+                { ref: { path: 'CONTRIBUTING.md', line: 1 }, label: 'Open CONTRIBUTING.md', autoOpen: false }
+            ]);
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].options![0].buttonLabel).to.equal('✅ Confirm');
-    });
 
-    it('should reject step links with empty path in object ref', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                links: [{ ref: { path: '' } }]
-            }]
+        it('should drop a link whose object ref has an empty path', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    links: [{ ref: { path: '' } }]
+                }]
+            }));
+            expect(args.interactions[0].links).to.be.undefined;
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links).to.be.undefined;
-    });
 
-    it('should accept step links with EmptyContentRef', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                links: [{ ref: { empty: true, label: 'New file' } }]
-            }]
+        it('should accept step links with EmptyContentRef', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    links: [{ ref: { empty: true, label: 'New file' } }]
+                }]
+            }));
+            expect(args.interactions[0].links![0].ref).to.deep.equal({ empty: true, label: 'New file' });
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links![0].ref).to.deep.equal({ empty: true, label: 'New file' });
-    });
 
-    it('should accept step links with EmptyContentRef as rightRef', () => {
-        const input = JSON.stringify({
-            interactions: [{
-                title: 'T', message: 'M',
-                links: [{ ref: 'src/old.ts', rightRef: { empty: true } }]
-            }]
+        it('should accept step links with EmptyContentRef as rightRef', () => {
+            const args = expectAccepted(JSON.stringify({
+                interactions: [{
+                    title: 'T', message: 'M',
+                    links: [{ ref: 'src/old.ts', rightRef: { empty: true } }]
+                }]
+            }));
+            expect(args.interactions[0].links![0].rightRef).to.deep.equal({ empty: true });
         });
-        const result = parseUserInteractionArgs(input);
-        expect(result!.interactions[0].links![0].rightRef).to.deep.equal({ empty: true });
     });
 });
 
@@ -241,6 +292,11 @@ describe('parseUserInteractionInput', () => {
         expect(parseUserInteractionInput(input).title).to.equal('Streaming Title');
     });
 
+    it('should extract a partial title from JSON truncated mid-title', () => {
+        const input = '{"interactions":[{"title":"Streaming ti';
+        expect(parseUserInteractionInput(input)).to.deep.equal({ title: 'Streaming ti', stepCount: 0 });
+    });
+
     it('should return empty title from incomplete JSON without title field', () => {
         const input = '{"interactions": [{"message": "no title here';
         expect(parseUserInteractionInput(input).title).to.equal('');

package/src/common/user-interaction-tool.ts

@@ -155,50 +155,104 @@ export function parseUserInteractionResult(raw: unknown): UserInteractionResult
     return obj as unknown as UserInteractionResult;
 }
 
-export function parseUserInteractionArgs(args: string | undefined): UserInteractionArgs | undefined {
+/**
+ * Outcome of validating the raw `userInteraction` tool arguments.
+ *
+ * Validation is strict for anything that determines whether — and how — the user is asked
+ * (`interactions`, each step, and each option), because silently discarding those turns a
+ * decision step into an auto-completed informational one and skips the confirmation gate.
+ * Individual `links` stay lenient, because they are decoration: an unresolvable link should
+ * not discard the surrounding findings. The `links` container itself is still strict, since a
+ * JSON-encoded list drops every link at once and leaves the step without the content it is
+ * about — the same failure as a JSON-encoded `options` list, not an unresolvable entry.
+ */
+export type UserInteractionValidation =
+    | { ok: true, args: UserInteractionArgs }
+    | { ok: false, error: string };
+
+type StepValidation =
+    | { ok: true, step: UserInteractionStep }
+    | { ok: false, error: string };
+
+type OptionsValidation =
+    | { ok: true, options?: UserInteractionOption[] }
+    | { ok: false, error: string };
+
+const JSON_ENCODING_HINT = 'Do not JSON-encode nested values - pass real arrays and objects.';
+
+function describeType(value: unknown): string {
+    // eslint-disable-next-line no-null/no-null
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+
+/**
+ * Describe the received type, adding the JSON-encoding hint when a string was received where
+ * a structured value was expected - by far the most common way agents get these arguments wrong.
+ */
+function describeReceived(value: unknown): string {
+    const type = describeType(value);
+    return type === 'string' ? `${type}. ${JSON_ENCODING_HINT}` : `${type}.`;
+}
+
+export function parseUserInteractionArgs(args: string | undefined): UserInteractionValidation {
     if (!args) {
-        return undefined;
+        return { ok: false, error: 'No arguments were provided.' };
     }
+    let parsed: unknown;
     try {
-        const parsed = JSON.parse(args);
-        if (!Array.isArray(parsed.interactions)) {
-            return undefined;
-        }
-        const validSteps = parsed.interactions
-            .map(parseStep)
-            .filter((step: UserInteractionStep | undefined): step is UserInteractionStep => step !== undefined);
-        if (validSteps.length === 0) {
-            return undefined;
-        }
-        return { interactions: validSteps };
+        parsed = JSON.parse(args);
     } catch {
-        return undefined;
+        return { ok: false, error: 'Arguments are not valid JSON.' };
     }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, error: `Arguments must be an object with an "interactions" array, received ${describeReceived(parsed)}` };
+    }
+    const interactions = (parsed as Record<string, unknown>).interactions;
+    if (!Array.isArray(interactions)) {
+        return { ok: false, error: `"interactions" must be an array of step objects, received ${describeReceived(interactions)}` };
+    }
+    if (interactions.length === 0) {
+        return { ok: false, error: '"interactions" must contain at least one step.' };
+    }
+    const steps: UserInteractionStep[] = [];
+    for (let index = 0; index < interactions.length; index++) {
+        const step = parseStep(interactions[index], index + 1);
+        if (!step.ok) {
+            return step;
+        }
+        steps.push(step.step);
+    }
+    return { ok: true, args: { interactions: steps } };
 }
 
-function parseStep(raw: unknown): UserInteractionStep | undefined {
-    if (!raw || typeof raw !== 'object') {
-        return undefined;
+function parseStep(raw: unknown, position: number): StepValidation {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, error: `Step ${position}: expected a step object, received ${describeReceived(raw)}` };
     }
     const obj = raw as Record<string, unknown>;
     if (typeof obj.title !== 'string' || typeof obj.message !== 'string') {
-        return undefined;
+        return { ok: false, error: `Step ${position}: "title" and "message" are required strings.` };
     }
-    let options: UserInteractionOption[] | undefined;
-    if (Array.isArray(obj.options)) {
-        const validOptions = obj.options.filter(
-            (opt: unknown) => !!opt && typeof opt === 'object'
-                && typeof (opt as Record<string, unknown>).text === 'string'
-                && typeof (opt as Record<string, unknown>).value === 'string'
-        ) as UserInteractionOption[];
-        options = validOptions.length > 0 ? validOptions : undefined;
+    const options = parseOptions(obj.options, position);
+    if (!options.ok) {
+        return options;
     }
     let links: UserInteractionLink[] | undefined;
-    if (Array.isArray(obj.links)) {
-        const filtered = obj.links
+    // eslint-disable-next-line no-null/no-null
+    const rawLinks = obj.links === null ? undefined : obj.links;
+    if (Array.isArray(rawLinks)) {
+        const filtered = rawLinks
             .map(normalizeUserInteractionLink)
             .filter((link: UserInteractionLink | undefined): link is UserInteractionLink => link !== undefined);
         links = filtered.length > 0 ? filtered : undefined;
+    } else if (rawLinks !== undefined) {
+        return { ok: false, error: `Step ${position}: "links" must be an array of link objects, received ${describeReceived(rawLinks)}` };
     } else {
         const link = normalizeUserInteractionLink(obj.link);
         if (link) {
@@ -206,13 +260,54 @@ function parseStep(raw: unknown): UserInteractionStep | undefined {
         }
     }
     return {
-        title: obj.title,
-        message: obj.message,
-        options,
-        links
+        ok: true,
+        step: {
+            title: obj.title,
+            message: obj.message,
+            options: options.options,
+            links
+        }
     };
 }
 
+/**
+ * Validate a step's `options`. An absent or explicitly empty list means the step is
+ * informational; anything else must be a fully well-formed array, since a partially
+ * dropped option would silently offer the user a different choice than the agent intended.
+ */
+function parseOptions(raw: unknown, stepPosition: number): OptionsValidation {
+    // eslint-disable-next-line no-null/no-null
+    if (raw === undefined || raw === null) {
+        return { ok: true, options: undefined };
+    }
+    if (!Array.isArray(raw)) {
+        return {
+            ok: false,
+            error: `Step ${stepPosition}: "options" must be an array of {text, value} objects, received ${describeReceived(raw)}`
+        };
+    }
+    const options: UserInteractionOption[] = [];
+    for (let index = 0; index < raw.length; index++) {
+        const candidate = raw[index];
+        const obj = candidate as Record<string, unknown> | undefined;
+        if (!obj || typeof obj !== 'object' || Array.isArray(obj) || typeof obj.text !== 'string' || typeof obj.value !== 'string') {
+            return {
+                ok: false,
+                error: `Step ${stepPosition}, option ${index + 1}: "text" and "value" are required strings, received ${describeReceived(candidate)}`
+            };
+        }
+        const option: UserInteractionOption = { text: obj.text, value: obj.value };
+        if (typeof obj.description === 'string') {
+            option.description = obj.description;
+        }
+        if (typeof obj.buttonLabel === 'string') {
+            option.buttonLabel = obj.buttonLabel;
+        }
+        options.push(option);
+    }
+    return { ok: true, options: options.length > 0 ? options : undefined };
+}
+
 function normalizeContentRef(ref: unknown): ContentRef | undefined {
     if (typeof ref === 'string') {
         return ref.length > 0 ? ref : undefined;