@interf/compiler 0.9.3 → 0.9.5

package/dist/packages/local-service/action-definitions.js

@@ -0,0 +1,1148 @@
+import { z } from "zod";
+export const ActionValueIdPattern = /^[a-z0-9][a-z0-9-]{0,79}$/;
+export const ActionValueIdSchema = z.string().trim().regex(ActionValueIdPattern, "Use lowercase letters, numbers, and dashes.");
+export const OptionalActionValueIdSchema = z.string().trim().refine((value) => value === "" || ActionValueIdPattern.test(value), "Use lowercase letters, numbers, and dashes.");
+export const SourceReadinessCheckActionValueSchema = z.object({
+    question: z.string().trim().min(1),
+    answer: z.string().trim().optional(),
+}).strict();
+export const PreparationSetupActionValuesSchema = z.object({
+    name: ActionValueIdSchema,
+    path: z.string().trim().min(1, "Source Folder is required."),
+    about: z.string().trim().min(1, "Agent work is required."),
+    method: OptionalActionValueIdSchema.optional(),
+    checks: z.array(SourceReadinessCheckActionValueSchema).optional(),
+    max_attempts: z.number().int().min(1).max(5).optional(),
+    max_loops: z.number().int().min(1).max(3).optional(),
+    readiness_notes: z.string().trim().optional(),
+    prepare_after_setup: z.boolean().optional(),
+    setup_mode: z.enum(["create", "select-method"]).optional(),
+}).strict();
+export const MethodAuthoringActionValuesSchema = z.object({
+    method_id: ActionValueIdSchema.optional(),
+    base_method_id: ActionValueIdSchema.optional(),
+    reference_method_id: ActionValueIdSchema.optional(),
+    label: z.string().trim().optional(),
+    hint: z.string().trim().optional(),
+    task_prompt: z.string().trim().min(1, "Agent work is required."),
+    portable_output: z.string().trim().optional(),
+    readiness_notes: z.string().trim().optional(),
+}).strict();
+export const INTERF_SERVICE_ACTIONS = {
+    createPreparation: {
+        id: "create-preparation",
+        serviceAction: "preparation-setup",
+        title: "Create Preparation",
+        description: "Save a Source Folder and agent job as a Preparation.",
+    },
+    runPreparation: {
+        id: "prepare-run",
+        serviceAction: "compile",
+        title: "Run Preparation",
+        description: "Build portable context for a saved Preparation.",
+    },
+    selectMethod: {
+        id: "select-method",
+        serviceAction: "preparation-setup",
+        title: "Select Method",
+        description: "Save the Method a Preparation should use for future prepare runs.",
+    },
+    createMethod: {
+        id: "create-method",
+        serviceAction: "method-authoring",
+        title: "Create Method",
+        description: "Draft a reusable local Method for an agent-work pattern.",
+    },
+    methodChange: {
+        id: "method-change",
+        serviceAction: "method-change",
+        title: "Method Change",
+        description: "Modify, duplicate, or remove an existing Method.",
+    },
+    preparationChange: {
+        id: "preparation-change",
+        serviceAction: "preparation-change",
+        title: "Preparation Change",
+        description: "Modify, duplicate, or remove an existing Preparation.",
+    },
+    confirmAction: {
+        id: "confirm-action",
+        serviceAction: "action-proposal",
+        title: "Send Request",
+        description: "Confirm the typed Interf service request before it runs.",
+    },
+    checkReadiness: {
+        id: "check-readiness",
+        serviceAction: "test",
+        title: "Check Readiness",
+        description: "Run saved readiness checks against this Preparation.",
+    },
+    draftReadinessChecks: {
+        id: "draft-readiness-checks",
+        serviceAction: "readiness-check-draft",
+        title: "Draft Readiness Checks",
+        description: "Ask the configured local executor to draft saved readiness checks.",
+    },
+    improvePreparation: {
+        id: "improve-preparation",
+        serviceAction: "method-improvement",
+        title: "Improve Preparation",
+        description: "Use readiness evidence to improve the Method for this Preparation.",
+    },
+};
+function optionalLine(label, value) {
+    const trimmed = value?.trim();
+    return trimmed ? `${label}: ${trimmed}` : null;
+}
+export function methodAuthoringTaskPrompt(values) {
+    return [
+        `Agent work: ${values.task_prompt}`,
+        optionalLine("Portable-context output", values.portable_output),
+        optionalLine("Readiness checks", values.readiness_notes),
+    ].filter((line) => Boolean(line)).join("\n");
+}
+const requiredActionText = (field) => z.string().trim().min(1, `${field} is required.`);
+const optionalActionText = z.string().trim();
+const actionIdField = (field) => requiredActionText(field).regex(ActionValueIdPattern, `${field} must use lowercase letters, numbers, and dashes.`);
+const optionalActionIdField = (field) => optionalActionText.refine((value) => value === "" || ActionValueIdPattern.test(value), `${field} must use lowercase letters, numbers, and dashes.`);
+export function packageSchemaFieldErrors(result, pathMap) {
+    if (result.success)
+        return {};
+    const errors = {};
+    for (const issue of result.error.issues) {
+        const path = issue.path.join(".");
+        const key = pathMap[path] ?? pathMap[issue.path.at(-1)?.toString() ?? ""] ?? "";
+        if (key && !errors[key])
+            errors[key] = issue.message;
+    }
+    return errors;
+}
+export function slugForActionId(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 72)
+        .replace(/-+$/g, "");
+    return slug || "preparation";
+}
+export function uniqueActionId(seed, usedIds) {
+    const base = slugForActionId(seed);
+    if (!usedIds.has(base))
+        return base;
+    for (let index = 2; index < 100; index += 1) {
+        const candidate = `${base}-${index}`;
+        if (!usedIds.has(candidate))
+            return candidate;
+    }
+    return `${base}-${Date.now().toString(36)}`;
+}
+export function titleFromActionId(value) {
+    return value
+        .split("-")
+        .filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join(" ");
+}
+export function maybeActionValue(value) {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function inputValue(values, key) {
+    return values[key] ?? "";
+}
+export function methodChoiceOptions(methods) {
+    const seen = new Set();
+    const options = [];
+    for (const method of [{ id: "interf-default", label: "interf-default" }, ...methods]) {
+        if (seen.has(method.id))
+            continue;
+        seen.add(method.id);
+        options.push({ label: method.label ?? method.id, value: method.id });
+    }
+    return options;
+}
+export function methodTaskPromptFromInput(values) {
+    const parsed = MethodAuthoringActionValuesSchema.safeParse(values);
+    if (parsed.success)
+        return methodAuthoringTaskPrompt(parsed.data);
+    const taskPrompt = inputValue(values, "task_prompt");
+    const portableOutput = inputValue(values, "portable_output");
+    const readinessNotes = inputValue(values, "readiness_notes");
+    return [
+        `Agent work: ${taskPrompt}`,
+        maybeActionValue(portableOutput) ? `Portable-context output: ${portableOutput}` : null,
+        maybeActionValue(readinessNotes) ? `Readiness checks: ${readinessNotes}` : null,
+    ].filter((line) => Boolean(line)).join("\n");
+}
+function createPreparationSchema(existingNames) {
+    return z.object({
+        name: actionIdField("Preparation name"),
+        path: requiredActionText("Source Folder"),
+        about: requiredActionText("Agent work"),
+        method: optionalActionIdField("Method"),
+        readiness_notes: optionalActionText,
+    }).strict().superRefine((values, ctx) => {
+        if (existingNames.has(values.name)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["name"],
+                message: "A Preparation with this name already exists.",
+            });
+        }
+    });
+}
+function prepareRunSchema() {
+    return z.object({
+        preparation: actionIdField("Preparation"),
+        method: optionalActionIdField("Method"),
+        about: optionalActionText,
+        source_folder_path: optionalActionText,
+    }).strict();
+}
+function selectMethodSchema() {
+    return z.object({
+        name: actionIdField("Preparation"),
+        path: requiredActionText("Source Folder"),
+        about: requiredActionText("Agent work"),
+        current_method: optionalActionIdField("Current Method"),
+        method: optionalActionIdField("Method"),
+    }).strict();
+}
+function methodAuthoringSchema(existingMethodIds) {
+    return z.object({
+        method_id: optionalActionIdField("Method id"),
+        label: optionalActionText,
+        hint: optionalActionText,
+        task_prompt: requiredActionText("Agent work"),
+        portable_output: optionalActionText,
+        readiness_notes: optionalActionText,
+    }).strict().superRefine((values, ctx) => {
+        const explicitMethodId = maybeActionValue(values.method_id ?? "");
+        if (explicitMethodId && existingMethodIds.has(explicitMethodId)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["method_id"],
+                message: "A Method with this id already exists.",
+            });
+        }
+    });
+}
+function methodChangeSchema(action, methodId, existingMethodIds) {
+    const base = {
+        action: requiredActionText("Action"),
+        method: actionIdField("Method"),
+        preparation: optionalActionIdField("Preparation"),
+    };
+    if (action === "modify") {
+        return z.object({
+            ...base,
+            change_request: requiredActionText("Requested change"),
+            label: optionalActionText,
+            hint: optionalActionText,
+        }).strict();
+    }
+    if (action === "duplicate") {
+        return z.object({
+            ...base,
+            new_method_id: actionIdField("New Method id"),
+        }).strict().superRefine((values, ctx) => {
+            if (existingMethodIds.has(values.new_method_id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["new_method_id"],
+                    message: "A Method with this id already exists.",
+                });
+            }
+        });
+    }
+    return z.object({
+        ...base,
+        confirmation: requiredActionText("Confirmation").refine((value) => value === methodId, `Type ${methodId} to confirm.`),
+    }).strict();
+}
+function preparationChangeSchema(action, preparation, existingNames) {
+    const base = {
+        action: requiredActionText("Action"),
+        preparation: actionIdField("Preparation"),
+    };
+    if (action === "modify") {
+        return z.object({
+            ...base,
+            name: actionIdField("Preparation id"),
+            path: requiredActionText("Source Folder"),
+            about: requiredActionText("Agent work"),
+            method: optionalActionIdField("Method"),
+        }).strict().superRefine((values, ctx) => {
+            if (values.name !== preparation && existingNames.has(values.name)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["name"],
+                    message: "A Preparation with this name already exists.",
+                });
+            }
+        });
+    }
+    if (action === "duplicate") {
+        return z.object({
+            ...base,
+            name: actionIdField("New Preparation id"),
+            path: requiredActionText("Source Folder"),
+            about: requiredActionText("Agent work"),
+            method: optionalActionIdField("Method"),
+        }).strict().superRefine((values, ctx) => {
+            if (existingNames.has(values.name)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["name"],
+                    message: "A Preparation with this name already exists.",
+                });
+            }
+        });
+    }
+    return z.object({
+        ...base,
+        confirmation: requiredActionText("Confirmation").refine((value) => value === preparation, `Type ${preparation} to confirm.`),
+    }).strict();
+}
+function conciseSummary(value, fallback) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return fallback;
+    const sentence = normalized.match(/^.{24,180}?(?:[.!?](?:\s|$)|$)/)?.[0]?.trim() ?? normalized;
+    return sentence.length > 180 ? `${sentence.slice(0, 177).trim()}...` : sentence;
+}
+function normalizedMethodActionValues(values, existingMethodIds, defaultSeed) {
+    const explicitMethodId = maybeActionValue(inputValue(values, "method_id"));
+    const taskPrompt = inputValue(values, "task_prompt").trim();
+    const methodId = explicitMethodId ?? uniqueActionId(taskPrompt || defaultSeed || "custom-method", existingMethodIds);
+    const output = maybeActionValue(inputValue(values, "portable_output"));
+    return {
+        ...values,
+        method_id: methodId,
+        label: maybeActionValue(inputValue(values, "label")) ?? titleFromActionId(methodId),
+        hint: maybeActionValue(inputValue(values, "hint")) ?? conciseSummary(output ?? taskPrompt, "Reusable Method for preparing source files."),
+        task_prompt: taskPrompt,
+    };
+}
+function createPreparationActionValues(values) {
+    const method = inputValue(values, "method");
+    const readinessNotes = inputValue(values, "readiness_notes");
+    return {
+        name: inputValue(values, "name"),
+        path: inputValue(values, "path"),
+        about: inputValue(values, "about"),
+        prepare_after_setup: true,
+        ...(maybeActionValue(method) ? { method } : {}),
+        ...(maybeActionValue(readinessNotes) ? { readiness_notes: readinessNotes } : {}),
+    };
+}
+function selectMethodActionValues(values) {
+    return {
+        name: inputValue(values, "name"),
+        path: inputValue(values, "path"),
+        about: inputValue(values, "about"),
+        method: maybeActionValue(inputValue(values, "method")) ?? "interf-default",
+        prepare_after_setup: false,
+        setup_mode: "select-method",
+    };
+}
+export function preparationSetupRequestFromActionValues(input) {
+    const values = PreparationSetupActionValuesSchema.parse(input);
+    return {
+        prepare_after_setup: values.prepare_after_setup ?? false,
+        setup_mode: values.setup_mode === "select-method" ? "select-method" : "create",
+        preparation: {
+            name: values.name,
+            path: values.path,
+            about: values.about,
+            method: values.method && values.method.length > 0 ? values.method : "interf-default",
+            checks: values.checks ?? [],
+            ...(typeof values.max_attempts === "number" ? { max_attempts: values.max_attempts } : {}),
+            ...(typeof values.max_loops === "number" ? { max_loops: values.max_loops } : {}),
+        },
+    };
+}
+export function methodAuthoringRequestFromActionValues(input, context) {
+    const values = MethodAuthoringActionValuesSchema.parse(input);
+    const methodId = values.method_id;
+    if (!methodId) {
+        throw new Error("Method id is required.");
+    }
+    const taskPrompt = methodAuthoringTaskPrompt(values);
+    return {
+        ...(context.preparation ? { preparation: context.preparation } : {}),
+        source_folder_path: context.sourceFolderPath,
+        ...(values.base_method_id ? { base_method_id: values.base_method_id } : {}),
+        ...(values.reference_method_id ? { reference_method_id: values.reference_method_id } : {}),
+        method_id: methodId,
+        label: values.label ?? titleFromActionId(methodId),
+        hint: values.hint ?? conciseSummary(values.portable_output ?? values.task_prompt, "Reusable Method for preparing source files."),
+        task_prompt: taskPrompt,
+        checks: context.checks ?? [],
+    };
+}
+export function methodImprovementActionValues(options) {
+    const readinessNotes = (options.checks ?? [])
+        .map((check) => check.question)
+        .filter((question) => question.trim().length > 0)
+        .join("\n");
+    return {
+        method_id: options.methodId,
+        reference_method_id: options.methodId,
+        ...(maybeActionValue(options.label ?? "") ? { label: options.label } : {}),
+        ...(maybeActionValue(options.hint ?? "") ? { hint: options.hint } : {}),
+        task_prompt: `Improve Method ${options.methodId} using the latest readiness evidence for Preparation ${options.preparationName}.`,
+        ...(maybeActionValue(readinessNotes) ? { readiness_notes: readinessNotes } : {}),
+    };
+}
+function methodAuthoringActionValues(values) {
+    const methodId = inputValue(values, "method_id");
+    const label = inputValue(values, "label");
+    const hint = inputValue(values, "hint");
+    const portableOutput = inputValue(values, "portable_output");
+    const readinessNotes = inputValue(values, "readiness_notes");
+    return {
+        ...(maybeActionValue(methodId) ? { method_id: methodId } : {}),
+        ...(maybeActionValue(label) ? { label } : {}),
+        ...(maybeActionValue(hint) ? { hint } : {}),
+        task_prompt: inputValue(values, "task_prompt"),
+        ...(maybeActionValue(portableOutput) ? { portable_output: portableOutput } : {}),
+        ...(maybeActionValue(readinessNotes) ? { readiness_notes: readinessNotes } : {}),
+    };
+}
+function methodChangeActionValues(action, values) {
+    if (action === "modify") {
+        const methodId = inputValue(values, "method");
+        return {
+            method_id: methodId,
+            reference_method_id: methodId,
+            ...(maybeActionValue(inputValue(values, "label")) ? { label: inputValue(values, "label") } : {}),
+            ...(maybeActionValue(inputValue(values, "hint")) ? { hint: inputValue(values, "hint") } : {}),
+            task_prompt: [
+                `Modify Method ${methodId}.`,
+                inputValue(values, "change_request"),
+            ].filter(Boolean).join("\n"),
+        };
+    }
+    if (action === "duplicate") {
+        const newMethodId = inputValue(values, "new_method_id");
+        return {
+            action_type: "method-change",
+            operation: "duplicate",
+            method: inputValue(values, "method"),
+            new_method_id: newMethodId,
+            label: titleFromActionId(newMethodId),
+            hint: `Duplicate of ${inputValue(values, "method")}`,
+        };
+    }
+    return {
+        action_type: "method-change",
+        operation: "remove",
+        method: inputValue(values, "method"),
+        confirmation: inputValue(values, "confirmation"),
+    };
+}
+function duplicatePreparationActionValues(values) {
+    const method = inputValue(values, "method");
+    return {
+        name: inputValue(values, "name"),
+        path: inputValue(values, "path"),
+        about: inputValue(values, "about"),
+        prepare_after_setup: false,
+        setup_mode: "create",
+        ...(maybeActionValue(method) ? { method } : {}),
+    };
+}
+function preparationChangeActionValues(action, values) {
+    if (action === "modify" || action === "duplicate")
+        return duplicatePreparationActionValues(values);
+    return {
+        action_type: "preparation-change",
+        operation: "remove",
+        preparation: inputValue(values, "preparation"),
+        confirmation: inputValue(values, "confirmation"),
+    };
+}
+export function buildCreatePreparationActionDefinition(context) {
+    const existingNames = new Set(context.existingNames);
+    const name = uniqueActionId(context.suggestedName, existingNames);
+    return {
+        id: INTERF_SERVICE_ACTIONS.createPreparation.id,
+        title: INTERF_SERVICE_ACTIONS.createPreparation.title,
+        description: "Describe the agent job. Interf saves the Preparation through the local service and starts its first prepare run.",
+        submitLabel: "Confirm",
+        initialValues: {
+            name,
+            path: context.sourcePath,
+            about: "",
+            method: "interf-default",
+            readiness_notes: "",
+        },
+        schema: createPreparationSchema(existingNames),
+        validateRequest: (values) => packageSchemaFieldErrors(PreparationSetupActionValuesSchema.safeParse(createPreparationActionValues(values)), {
+            name: "name",
+            path: "path",
+            about: "about",
+            method: "method",
+        }),
+        valuesPreview: createPreparationActionValues,
+        buildDraft: (values) => {
+            const actionValues = createPreparationActionValues(values);
+            const method = inputValue(values, "method");
+            const readinessNotes = inputValue(values, "readiness_notes");
+            return {
+                preparation: inputValue(values, "name"),
+                values: actionValues,
+                message: [
+                    `Create Preparation ${inputValue(values, "name")}.`,
+                    `Agent work: ${inputValue(values, "about")}`,
+                    maybeActionValue(method) ? `Method: ${method}` : null,
+                    maybeActionValue(readinessNotes) ? `Readiness checks: ${readinessNotes}` : null,
+                    `Source folder: ${inputValue(values, "path")}`,
+                    "Use the attached typed action input as the source of truth.",
+                ].filter((line) => Boolean(line)).join("\n"),
+            };
+        },
+        fields: [
+            {
+                name: "about",
+                label: "Agent job",
+                type: "textarea",
+                rows: 4,
+                help: "The concrete work this prepared folder should enable.",
+                context: "Saved as the Preparation intent and sent as typed action input.",
+                placeholder: "Example: Analyze every report chart, extract annual take-up by location, and produce a source data file plus markdown summary.",
+            },
+            {
+                name: "method",
+                label: "Method",
+                type: "select",
+                help: "How Interf should build portable context for this Preparation.",
+                context: "Saved as the Method selected for this Preparation.",
+                options: methodChoiceOptions(context.methods),
+            },
+            {
+                name: "readiness_notes",
+                label: "Ready when",
+                type: "textarea",
+                rows: 3,
+                help: "Concrete checks that prove the prepared context is good enough.",
+                context: "Used as guidance when Interf proposes Preparation-level readiness checks.",
+                placeholder: "Example: Every output is source-backed, complete for the requested locations, and precise enough to verify.",
+            },
+            {
+                name: "name",
+                label: "Preparation id",
+                type: "text",
+                advanced: true,
+                help: "Auto-generated for the CLI and portable-context folder. Change only if needed.",
+                context: "Used in the CLI, saved on the Preparation, and used for the portable-context folder name.",
+                placeholder: name,
+            },
+        ],
+    };
+}
+export function buildPrepareRunActionDefinition(context) {
+    return {
+        id: INTERF_SERVICE_ACTIONS.runPreparation.id,
+        title: INTERF_SERVICE_ACTIONS.runPreparation.title,
+        description: "Build portable context for this Preparation. Interf will run the saved Method against the source folder and record a visible run.",
+        submitLabel: "Run",
+        initialValues: {
+            preparation: context.name,
+            method: context.methodId,
+            about: context.about,
+            source_folder_path: context.sourceFolderPath,
+        },
+        schema: prepareRunSchema(),
+        valuesPreview: (values) => ({
+            action_type: INTERF_SERVICE_ACTIONS.runPreparation.serviceAction,
+            preparation: inputValue(values, "preparation"),
+            method: inputValue(values, "method"),
+            source_folder_path: inputValue(values, "source_folder_path"),
+            about: inputValue(values, "about"),
+        }),
+        buildDraft: (values) => ({
+            preparation: inputValue(values, "preparation"),
+            values: {
+                action_type: INTERF_SERVICE_ACTIONS.runPreparation.serviceAction,
+                preparation: inputValue(values, "preparation"),
+                ...(maybeActionValue(inputValue(values, "method")) ? { method: inputValue(values, "method") } : {}),
+            },
+            message: [
+                `Run Preparation ${inputValue(values, "preparation")}.`,
+                maybeActionValue(inputValue(values, "method")) ? `Method: ${inputValue(values, "method")}` : null,
+                maybeActionValue(inputValue(values, "about")) ? `Agent work: ${inputValue(values, "about")}` : null,
+                "Build portable context from the saved Source Folder and selected Method.",
+                "Use the attached typed action input as the source of truth.",
+            ].filter((line) => Boolean(line)).join("\n"),
+        }),
+        fields: [
+            {
+                name: "preparation",
+                label: "Preparation",
+                type: "text",
+                readOnly: true,
+                help: "The saved Preparation that will be built.",
+                context: "Sent as the compile target.",
+            },
+            {
+                name: "method",
+                label: "Method",
+                type: "text",
+                readOnly: true,
+                help: "The Method Interf will run for this Preparation.",
+                context: "Sent as the compile Method override.",
+            },
+            {
+                name: "about",
+                label: "Agent job",
+                type: "textarea",
+                readOnly: true,
+                advanced: true,
+                help: "The work this Preparation is meant to support.",
+                context: "Preserved as context for the prepare-run proposal.",
+                placeholder: "No saved job description.",
+            },
+            {
+                name: "source_folder_path",
+                label: "Source Folder",
+                type: "text",
+                readOnly: true,
+                advanced: true,
+                help: "The local folder Interf will read.",
+                context: "Resolved from the saved Preparation.",
+            },
+        ],
+    };
+}
+export function buildPrepareRunActionDraft(context) {
+    const definition = buildPrepareRunActionDefinition(context);
+    return definition.buildDraft(definition.initialValues);
+}
+export function buildSelectMethodActionDefinition(context) {
+    const actionValues = (values) => ({
+        ...selectMethodActionValues(values),
+        checks: context.checks ?? [],
+        ...(typeof context.maxAttempts === "number" ? { max_attempts: context.maxAttempts } : {}),
+        ...(typeof context.maxLoops === "number" ? { max_loops: context.maxLoops } : {}),
+    });
+    return {
+        id: INTERF_SERVICE_ACTIONS.selectMethod.id,
+        title: INTERF_SERVICE_ACTIONS.selectMethod.title,
+        description: "Choose which Method this Preparation uses for future prepare runs. This saves the selection without running prepare.",
+        submitLabel: "Confirm",
+        initialValues: {
+            name: context.name,
+            path: context.sourceFolderPath,
+            about: context.about,
+            current_method: context.currentMethodId,
+            method: context.currentMethodId || "interf-default",
+        },
+        schema: selectMethodSchema(),
+        validateRequest: (values) => packageSchemaFieldErrors(PreparationSetupActionValuesSchema.safeParse(actionValues(values)), {
+            name: "name",
+            path: "path",
+            about: "about",
+            method: "method",
+        }),
+        valuesPreview: actionValues,
+        buildDraft: (values) => ({
+            preparation: inputValue(values, "name"),
+            values: actionValues(values),
+            message: [
+                `Select Method ${inputValue(values, "method") || "interf-default"} for Preparation ${inputValue(values, "name")}.`,
+                "Save the selected Method. Do not run prepare yet.",
+                "Use the attached typed action input as the source of truth.",
+            ].join("\n"),
+        }),
+        fields: [
+            {
+                name: "method",
+                label: "Method",
+                type: "select",
+                help: "The Method future prepare runs should use.",
+                context: "Saved on the existing Preparation.",
+                options: methodChoiceOptions(context.methods),
+            },
+            {
+                name: "current_method",
+                label: "Current Method",
+                type: "text",
+                readOnly: true,
+                help: "The Method currently saved for this Preparation.",
+                context: "Shown so the change is explicit before approval.",
+            },
+            {
+                name: "name",
+                label: "Preparation",
+                type: "text",
+                readOnly: true,
+                advanced: true,
+                help: "The Preparation whose Method selection will be updated.",
+                context: "Sent with the setup action.",
+            },
+            {
+                name: "about",
+                label: "Agent job",
+                type: "textarea",
+                readOnly: true,
+                advanced: true,
+                help: "The saved job intent for this Preparation.",
+                context: "Preserved while updating the selected Method.",
+            },
+            {
+                name: "path",
+                label: "Source Folder",
+                type: "text",
+                readOnly: true,
+                advanced: true,
+                help: "The saved Source Folder path.",
+                context: "Preserved while updating the selected Method.",
+            },
+        ],
+    };
+}
+export function buildCreateMethodActionDefinition(context) {
+    const existingMethodIds = new Set(context.existingMethodIds);
+    const defaultSeed = context.defaultPreparation ? `${context.defaultPreparation}-method` : context.suggestedMethodId;
+    const methodId = uniqueActionId(defaultSeed, existingMethodIds);
+    const label = titleFromActionId(methodId);
+    return {
+        id: INTERF_SERVICE_ACTIONS.createMethod.id,
+        title: INTERF_SERVICE_ACTIONS.createMethod.title,
+        description: "Describe the reusable job this Method should make possible. Interf will generate the stable Method metadata unless you override it.",
+        submitLabel: "Send Request",
+        initialValues: {
+            method_id: "",
+            label: "",
+            hint: "",
+            task_prompt: "",
+            portable_output: "",
+            readiness_notes: "",
+        },
+        normalizeValues: (values) => normalizedMethodActionValues(values, existingMethodIds, defaultSeed),
+        schema: methodAuthoringSchema(existingMethodIds),
+        validateRequest: (values) => packageSchemaFieldErrors(MethodAuthoringActionValuesSchema.safeParse(methodAuthoringActionValues(values)), {
+            method_id: "method_id",
+            label: "label",
+            hint: "hint",
+            task_prompt: "task_prompt",
+            portable_output: "portable_output",
+            readiness_notes: "readiness_notes",
+        }),
+        valuesPreview: (values) => ({
+            method_id: inputValue(values, "method_id"),
+            label: inputValue(values, "label"),
+            hint: inputValue(values, "hint"),
+            task_prompt: methodTaskPromptFromInput(values),
+        }),
+        buildDraft: (values) => ({
+            preparation: context.defaultPreparation,
+            values: methodAuthoringActionValues(values),
+            message: [
+                `Create Method ${inputValue(values, "method_id")}${context.defaultPreparation ? ` for Preparation ${context.defaultPreparation}` : ""}.`,
+                `Label: ${inputValue(values, "label")}`,
+                `Summary: ${inputValue(values, "hint")}`,
+                methodTaskPromptFromInput(values),
+                "Use the attached typed action input as the Method authoring request.",
+            ].join("\n"),
+        }),
+        fields: [
+            {
+                name: "task_prompt",
+                label: "Agent work",
+                type: "textarea",
+                rows: 4,
+                help: "The reusable job this Method should make possible for agents.",
+                context: "Used as the main Method-authoring instruction.",
+                placeholder: "Example: Analyze every report chart, extract annual take-up by location, and produce a source data file plus markdown summary.",
+            },
+            {
+                name: "portable_output",
+                label: "Portable-context output",
+                type: "textarea",
+                rows: 3,
+                help: "Files, sections, or evidence agents should receive in portable context.",
+                context: "Guides the Method output shape and stage artifact plan.",
+                placeholder: "Describe the files or sections agents should receive.",
+            },
+            {
+                name: "readiness_notes",
+                label: "Readiness guidance",
+                type: "textarea",
+                rows: 3,
+                help: "What a Preparation using this Method should be able to prove.",
+                context: "Guides Preparation-level readiness checks. Method acceptance criteria stay separate.",
+                placeholder: "Describe the evidence that should make a Preparation ready.",
+            },
+            {
+                name: "method_id",
+                label: "Method id",
+                type: "text",
+                advanced: true,
+                help: "Optional. Leave blank and Interf generates a stable id from the job.",
+                context: "Saved under the Workspace methods folder and referenced by Preparations.",
+                placeholder: methodId,
+            },
+            {
+                name: "label",
+                label: "Label",
+                type: "text",
+                advanced: true,
+                help: "Optional readable name people can choose later.",
+                context: "Shown in the UI and sent to the local agent while drafting the Method.",
+                placeholder: label,
+            },
+            {
+                name: "hint",
+                label: "Summary",
+                type: "textarea",
+                advanced: true,
+                rows: 2,
+                help: "Optional short description. Interf derives one from the job if left blank.",
+                context: "Gives the local agent quick context before it drafts stages and outputs.",
+                placeholder: "Prepare charts, tables, and cited findings for analyst agents.",
+            },
+        ],
+    };
+}
+export function buildMethodChangeActionDefinition(context) {
+    const existingMethodIds = new Set(context.existingMethodIds);
+    const actionLabel = titleFromActionId(context.action);
+    const newMethodId = context.action === "duplicate"
+        ? uniqueActionId(`${context.methodId}-copy`, existingMethodIds)
+        : "";
+    const initialValues = {
+        action: `method-${context.action}`,
+        method: context.methodId,
+        preparation: context.preparation,
+        ...(context.action === "modify" ? { change_request: "", label: context.label ?? "", hint: context.hint ?? "" } : {}),
+        ...(context.action === "duplicate" ? { new_method_id: newMethodId } : {}),
+        ...(context.action === "remove" ? { confirmation: "" } : {}),
+    };
+    const actionValues = (values) => methodChangeActionValues(context.action, values);
+    const messageFor = (values) => {
+        if (context.action === "modify") {
+            return [
+                `Modify Method ${inputValue(values, "method")}.`,
+                `Requested change: ${inputValue(values, "change_request")}`,
+                "Use the attached typed Method-authoring input as the source of truth.",
+            ].join("\n");
+        }
+        if (context.action === "duplicate") {
+            return [
+                `Duplicate Method ${inputValue(values, "method")} as ${inputValue(values, "new_method_id")}.`,
+                "Use the attached typed Method change input as the source of truth.",
+            ].join("\n");
+        }
+        return [
+            `Remove Method ${inputValue(values, "method")}.`,
+            "The user typed the Method id to confirm removal.",
+            "Use the attached typed Method change input as the source of truth.",
+        ].join("\n");
+    };
+    const fields = [
+        {
+            name: "method",
+            label: "Method",
+            type: "text",
+            readOnly: true,
+            help: "The Method this request targets.",
+            context: "Sent as the Method change target.",
+        },
+        {
+            name: "change_request",
+            label: context.action === "duplicate" ? "Requested difference" : "Requested change",
+            type: "textarea",
+            rows: 4,
+            advanced: context.action === "remove",
+            help: context.action === "duplicate"
+                ? "What should be different in the duplicate Method."
+                : "What should change in the existing Method.",
+            context: "Sent as the human-authored Method change request.",
+            placeholder: "Describe the concrete change Interf should make.",
+        },
+        {
+            name: "new_method_id",
+            label: "New Method id",
+            type: "text",
+            advanced: context.action !== "duplicate",
+            help: "Stable id for the duplicated Method.",
+            context: "Used as the target Method id for the duplicate request.",
+            placeholder: newMethodId,
+        },
+        {
+            name: "confirmation",
+            label: "Confirm removal",
+            type: "text",
+            advanced: context.action !== "remove",
+            help: `Type ${context.methodId} to confirm this removal request.`,
+            context: "Prevents accidental destructive Method requests.",
+            placeholder: context.methodId,
+        },
+        {
+            name: "label",
+            label: "Label",
+            type: "text",
+            advanced: true,
+            help: "Readable Method name to keep while modifying this Method.",
+            context: "Sent to the Method-authoring run.",
+            placeholder: context.label ?? context.methodId,
+        },
+        {
+            name: "hint",
+            label: "Summary",
+            type: "textarea",
+            rows: 2,
+            advanced: true,
+            help: "Short Method summary to keep while modifying this Method.",
+            context: "Sent to the Method-authoring run.",
+            placeholder: context.hint ?? "Reusable Method for preparing source folders.",
+        },
+        {
+            name: "preparation",
+            label: "Preparation",
+            type: "text",
+            readOnly: true,
+            advanced: true,
+            help: "A related Preparation used as context for this request.",
+            context: "Sent with the proposal request when available.",
+            placeholder: "No Preparation selected",
+        },
+    ];
+    return {
+        id: `${INTERF_SERVICE_ACTIONS.methodChange.id}-${context.action}`,
+        title: `${actionLabel} Method`,
+        description: context.action === "remove"
+            ? "Confirm the Method removal request. Interf will reject removal while any saved Preparation still uses it."
+            : context.action === "duplicate"
+                ? "Duplicate this Method through the local Interf service."
+                : "Describe the change and Interf will run a visible Method draft job.",
+        submitLabel: context.action === "modify" ? "Send Request" : "Confirm",
+        initialValues,
+        schema: methodChangeSchema(context.action, context.methodId, existingMethodIds),
+        valuesPreview: actionValues,
+        buildDraft: (values) => ({
+            preparation: inputValue(values, "preparation"),
+            values: actionValues(values),
+            message: messageFor(values),
+        }),
+        fields: fields.filter((field) => {
+            if (field.name === "change_request")
+                return context.action === "modify";
+            if (field.name === "new_method_id")
+                return context.action === "duplicate";
+            if (field.name === "confirmation")
+                return context.action === "remove";
+            if (field.name === "label" || field.name === "hint")
+                return context.action === "modify";
+            return true;
+        }),
+    };
+}
+export function buildPreparationChangeActionDefinition(context) {
+    const existingNames = new Set(context.existingNames);
+    const actionLabel = titleFromActionId(context.action);
+    const duplicateName = context.action === "duplicate"
+        ? uniqueActionId(`${context.preparation}-copy`, existingNames)
+        : "";
+    const initialValues = {
+        action: `preparation-${context.action}`,
+        preparation: context.preparation,
+        ...(context.action === "modify" || context.action === "duplicate"
+            ? {
+                name: context.action === "duplicate" ? duplicateName : context.preparation,
+                path: context.sourceFolderPath,
+                about: context.about ?? "",
+                method: context.methodId ?? "interf-default",
+            }
+            : {}),
+        ...(context.action === "remove" ? { confirmation: "" } : {}),
+    };
+    const actionValues = (values) => preparationChangeActionValues(context.action, values);
+    const messageFor = (values) => {
+        if (context.action === "modify") {
+            return [
+                `Modify Preparation ${inputValue(values, "preparation")}.`,
+                `Agent work: ${inputValue(values, "about")}`,
+                maybeActionValue(inputValue(values, "method")) ? `Method: ${inputValue(values, "method")}` : null,
+                `Source folder: ${inputValue(values, "path")}`,
+                "Use the attached typed Preparation setup input as the source of truth.",
+            ].filter((line) => Boolean(line)).join("\n");
+        }
+        if (context.action === "duplicate") {
+            return [
+                `Duplicate Preparation ${inputValue(values, "preparation")} as ${inputValue(values, "name")}.`,
+                `Agent work: ${inputValue(values, "about")}`,
+                maybeActionValue(inputValue(values, "method")) ? `Method: ${inputValue(values, "method")}` : null,
+                `Source folder: ${inputValue(values, "path")}`,
+                "Use the attached typed Preparation setup input as the source of truth.",
+            ].filter((line) => Boolean(line)).join("\n");
+        }
+        return [
+            `Remove Preparation ${inputValue(values, "preparation")}.`,
+            "The user typed the Preparation id to confirm removal.",
+            "Use the attached typed Preparation change input as the source of truth.",
+        ].join("\n");
+    };
+    const fields = [
+        {
+            name: "preparation",
+            label: "Preparation",
+            type: "text",
+            readOnly: true,
+            help: "The saved Preparation this request targets.",
+            context: "Sent as the Preparation target.",
+        },
+        {
+            name: "name",
+            label: context.action === "duplicate" ? "New Preparation id" : "Preparation id",
+            type: "text",
+            readOnly: context.action === "modify",
+            help: context.action === "duplicate"
+                ? "Stable id for the duplicated Preparation."
+                : "Stable id for this Preparation.",
+            context: "Saved as the Preparation name.",
+            placeholder: duplicateName || context.preparation,
+        },
+        {
+            name: "about",
+            label: "Agent job",
+            type: "textarea",
+            rows: 4,
+            help: "The concrete work this Preparation should support.",
+            context: "Saved as the Preparation intent.",
+            placeholder: "Describe the agent job.",
+        },
+        {
+            name: "method",
+            label: "Method",
+            type: "text",
+            help: "The Method future prepare runs should use.",
+            context: "Saved on this Preparation.",
+            placeholder: "interf-default",
+        },
+        {
+            name: "path",
+            label: "Source Folder",
+            type: "text",
+            readOnly: true,
+            advanced: context.action === "modify",
+            help: "The Source Folder for this Preparation.",
+            context: "Saved on this Preparation.",
+        },
+        {
+            name: "confirmation",
+            label: "Confirm removal",
+            type: "text",
+            help: `Type ${context.preparation} to confirm this removal request.`,
+            context: "Prevents accidental destructive Preparation requests.",
+            placeholder: context.preparation,
+        },
+    ];
+    return {
+        id: `${INTERF_SERVICE_ACTIONS.preparationChange.id}-${context.action}`,
+        title: `${actionLabel} Preparation`,
+        description: context.action === "remove"
+            ? "Confirm the Preparation removal request before Interf removes it from the saved config."
+            : context.action === "duplicate"
+                ? "Describe the new Preparation created from this saved Source Folder."
+                : "Update the saved Preparation fields through the local Interf service.",
+        submitLabel: "Confirm",
+        initialValues,
+        schema: preparationChangeSchema(context.action, context.preparation, existingNames),
+        validateRequest: context.action === "modify" || context.action === "duplicate"
+            ? (values) => packageSchemaFieldErrors(PreparationSetupActionValuesSchema.safeParse(duplicatePreparationActionValues(values)), {
+                name: "name",
+                path: "path",
+                about: "about",
+                method: "method",
+            })
+            : undefined,
+        valuesPreview: actionValues,
+        buildDraft: (values) => ({
+            preparation: inputValue(values, "preparation"),
+            values: actionValues(values),
+            message: messageFor(values),
+        }),
+        fields: fields.filter((field) => {
+            if (field.name === "name" || field.name === "about" || field.name === "method" || field.name === "path")
+                return context.action === "modify" || context.action === "duplicate";
+            if (field.name === "confirmation")
+                return context.action === "remove";
+            return true;
+        }),
+    };
+}
+export function buildConfirmActionDefinition(draft) {
+    return {
+        id: INTERF_SERVICE_ACTIONS.confirmAction.id,
+        title: INTERF_SERVICE_ACTIONS.confirmAction.title,
+        description: "This request will be sent to the local Interf service to create an approval proposal.",
+        submitLabel: "Send Request",
+        initialValues: {
+            preparation: draft.preparation,
+            message: draft.message,
+        },
+        schema: z.object({
+            preparation: optionalActionText,
+            message: requiredActionText("Action"),
+        }).strict(),
+        valuesPreview: () => draft.values ?? { message: draft.message },
+        buildDraft: () => ({ ...draft, confirmed: true }),
+        fields: [
+            {
+                name: "preparation",
+                label: "Preparation",
+                type: "text",
+                readOnly: true,
+                help: "The Preparation this action targets.",
+                context: "Sent with the proposal request.",
+                placeholder: "No Preparation selected",
+            },
+            {
+                name: "message",
+                label: "Request to Interf service",
+                type: "textarea",
+                readOnly: true,
+                rows: 5,
+                help: "Interf sends this request with typed values so the local service can propose the concrete action.",
+                context: "Sent to the local Interf service together with typed action values when available.",
+            },
+        ],
+    };
+}
+export function buildReadinessActionDraft(options) {
+    if (options.action === "check") {
+        return {
+            preparation: options.preparation,
+            message: `Check readiness for ${options.preparation}.`,
+            values: {
+                action_type: INTERF_SERVICE_ACTIONS.checkReadiness.serviceAction,
+                preparation: options.preparation,
+                mode: "both",
+            },
+        };
+    }
+    if (options.action === "draft-checks") {
+        return {
+            preparation: options.preparation,
+            message: `Draft readiness checks for ${options.preparation}.`,
+            values: {
+                action_type: INTERF_SERVICE_ACTIONS.draftReadinessChecks.serviceAction,
+                preparation: options.preparation,
+            },
+        };
+    }
+    return {
+        preparation: options.preparation,
+        message: `Improve ${options.preparation} using the latest readiness evidence.`,
+        values: {
+            action_type: INTERF_SERVICE_ACTIONS.improvePreparation.serviceAction,
+            ...(options.methodId ? { method: options.methodId } : {}),
+            preparation: options.preparation,
+        },
+    };
+}