@hailer/mcp 1.3.21 → 1.3.32

package/dist/mcp/tools/function-fields.js

@@ -0,0 +1,717 @@
+"use strict";
+/**
+ * Function Fields tools.
+ *
+ * User-facing name: Function Fields. Backend endpoints still use Fast
+ * Functions naming in a few places; keep that wording out of MCP tool names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.functionFieldTools = exports.repairFunctionValuesTool = exports.saveFunctionFieldTool = exports.previewWorkflowFunctionEvaluationTool = exports.verifyWorkflowFunctionValuesTool = exports.assistFunctionFieldTool = exports.dryRunFunctionFieldTool = exports.explainFunctionFieldGraphTool = void 0;
+const zod_1 = require("zod");
+const tool_registry_1 = require("../tool-registry");
+const UserContextCache_1 = require("../UserContextCache");
+const response_builder_1 = require("../utils/response-builder");
+const logger_1 = require("../../lib/logger");
+const object_id_1 = require("../../lib/object-id");
+const logger = (0, logger_1.createLogger)({ component: 'function-fields-tools' });
+const nameFieldAliases = new Set(['name', 'nameField', '::name']);
+const validStatuses = [
+    'ok',
+    'ok_with_warnings',
+    'stale',
+    'missing',
+    'trusted_editable',
+    'blocked',
+    'evaluation_error',
+    'dependency_unverified',
+];
+const functionVariablesSchema = zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]);
+const optionalFunctionVariablesSchema = functionVariablesSchema.optional();
+const optionalRecordOrStringSchema = zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]).optional();
+function parseRecord(value, label, fallback = {}) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${label} must be a JSON object.`);
+    }
+    return parsed;
+}
+function hasOwnArg(args, key) {
+    return Object.prototype.hasOwnProperty.call(args, key);
+}
+function addIfPresent(update, key, value, shouldAdd) {
+    if (shouldAdd) {
+        update[key] = value;
+    }
+}
+function normalizeFunctionFieldId(fieldId) {
+    return nameFieldAliases.has(fieldId) ? 'name' : fieldId;
+}
+function isBackendResolvableFieldId(fieldId) {
+    return (0, object_id_1.isObjectId)(fieldId) || fieldId === 'name';
+}
+function resolveWorkflow(context, workflowIdOrKey) {
+    return (context.init.processes || []).find((workflow) => workflow._id === workflowIdOrKey || workflow.key === workflowIdOrKey);
+}
+function nameFieldEntry(workflow) {
+    return {
+        fieldId: 'name',
+        field: {
+            label: workflow.nameColumnText || 'Name',
+            type: 'text',
+            editable: workflow.nameEditable,
+            functionEnabled: workflow.nameFunctionEnabled,
+            function: workflow.nameFunction,
+            functionVariables: workflow.nameFunctionVariables,
+        },
+    };
+}
+function findFieldEntry(workflow, fieldIdOrKey, options = {}) {
+    const fieldId = normalizeFunctionFieldId(fieldIdOrKey);
+    if (fieldId === 'name') {
+        return nameFieldEntry(workflow);
+    }
+    const direct = workflow.fields?.[fieldIdOrKey];
+    if (direct) {
+        return { fieldId: fieldIdOrKey, field: direct };
+    }
+    for (const [candidateId, candidateField] of Object.entries(workflow.fields || {})) {
+        if (candidateField?.key === fieldIdOrKey) {
+            return { fieldId: candidateId, field: candidateField };
+        }
+    }
+    if (options.allowLegacyDataNameAlias && fieldIdOrKey === 'data') {
+        return nameFieldEntry(workflow);
+    }
+    return undefined;
+}
+function findWorkflowForField(context, fieldIdOrKey) {
+    const normalizedFieldId = normalizeFunctionFieldId(fieldIdOrKey);
+    const matches = (context.init.processes || []).filter((workflow) => normalizedFieldId === 'name' || !!findFieldEntry(workflow, fieldIdOrKey, { allowLegacyDataNameAlias: false }));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function resolveWorkflowAndField(context, workflowIdOrKey, fieldIdOrKey) {
+    const workflow = workflowIdOrKey ? resolveWorkflow(context, workflowIdOrKey) : findWorkflowForField(context, fieldIdOrKey);
+    if (!workflow) {
+        const normalizedFieldId = normalizeFunctionFieldId(fieldIdOrKey);
+        const matches = (context.init.processes || []).filter((candidate) => normalizedFieldId === 'name' || !!findFieldEntry(candidate, fieldIdOrKey, { allowLegacyDataNameAlias: false }));
+        return { fieldId: normalizedFieldId, ambiguous: matches.length > 1 };
+    }
+    const fieldEntry = findFieldEntry(workflow, fieldIdOrKey);
+    return {
+        workflow,
+        fieldId: fieldEntry?.fieldId || normalizeFunctionFieldId(fieldIdOrKey),
+        field: fieldEntry?.field,
+    };
+}
+function expectedOutputForFieldType(type) {
+    switch (type) {
+        case 'numeric':
+        case 'numericunit':
+            return 'number | null';
+        case 'date':
+        case 'time':
+        case 'datetime':
+            return 'millisecond timestamp number | null';
+        case 'daterange':
+        case 'timerange':
+        case 'datetimerange':
+            return '{ start: number, end: number } | null';
+        case 'users':
+        case 'teams':
+            return 'id string array | null';
+        case 'activitylink':
+        case 'country':
+            return 'id string or object shape | null';
+        default:
+            return 'non-empty string | null';
+    }
+}
+function toStringArray(value) {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value.map(item => String(item)) : [String(value)];
+}
+function findFieldAcrossWorkflows(context, fieldIdOrKey) {
+    for (const workflow of context.init.processes || []) {
+        const entry = findFieldEntry(workflow, fieldIdOrKey);
+        if (entry) {
+            return { workflow, fieldId: entry.fieldId, field: entry.field };
+        }
+    }
+    return {};
+}
+function dependencyDescriptions(context, workflow, functionVariables) {
+    return Object.entries(functionVariables).map(([name, rawDependency]) => {
+        if (Array.isArray(rawDependency)) {
+            return {
+                name,
+                description: 'Legacy stacked dependency configuration. Convert to in-code fallback before relying on the current Function Fields engine.',
+                source: 'legacy stacked dependency',
+                type: 'unknown',
+                shape: 'stacked',
+                relationType: 'stacked',
+                editable: false,
+                selector: rawDependency,
+            };
+        }
+        const dependency = rawDependency && typeof rawDependency === 'object' ? rawDependency : {};
+        const relationType = dependency.type || '';
+        const data = toStringArray(dependency.data);
+        let source = data.join(' -> ');
+        let field;
+        switch (relationType) {
+            case '=': {
+                const local = data[0] ? findFieldEntry(workflow, data[0]) : undefined;
+                field = local?.field;
+                source = field?.label ? `${field.label} (${local?.fieldId})` : source || 'same activity field';
+                break;
+            }
+            case '>': {
+                const link = data[0] ? findFieldEntry(workflow, data[0]) : undefined;
+                const target = data[1] ? findFieldAcrossWorkflows(context, data[1]) : {};
+                field = target.field;
+                const linkLabel = link?.field?.label || data[0] || 'linked activity';
+                const targetLabel = target.field?.label || data[1] || 'target field';
+                source = `${linkLabel} -> ${targetLabel}`;
+                break;
+            }
+            case '<': {
+                const remoteWorkflow = data[0] ? resolveWorkflow(context, data[0]) : undefined;
+                const remoteField = remoteWorkflow && data[1] ? findFieldEntry(remoteWorkflow, data[1]) : undefined;
+                field = remoteField?.field;
+                source = `${remoteWorkflow?.name || data[0] || 'linked-from workflow'} -> ${field?.label || data[1] || 'field'}`;
+                break;
+            }
+            case '?':
+                source = `static selector: ${data.join(' / ')}`;
+                break;
+            default:
+                break;
+        }
+        return {
+            name,
+            description: relationType === '<' ? 'Linked-from values are arrays.' : '',
+            source,
+            type: field?.type || 'unknown',
+            shape: relationType === '<' ? 'array' : 'scalar',
+            relationType,
+            editable: !!field?.editable,
+            selector: data.length ? data : null,
+        };
+    });
+}
+function repairEndpoint(scope, apply, force) {
+    const pathSegment = scope === 'activity' ? 'Path' : 'WorkflowPath';
+    if (!apply) {
+        return `v3.activity.repair${pathSegment}DryRun`;
+    }
+    if (force) {
+        return `v3.activity.forceRepair${pathSegment}`;
+    }
+    return `v3.activity.repair${pathSegment}`;
+}
+function extractEvaluationError(result, fieldId) {
+    const candidateFieldIds = new Set([fieldId]);
+    if (fieldId === 'name') {
+        candidateFieldIds.add('data');
+    }
+    if (fieldId === 'data') {
+        candidateFieldIds.add('name');
+    }
+    const evaluatedField = result?.activity?.fields?.find((field) => candidateFieldIds.has(field?.id) && field?.error);
+    if (evaluatedField?.error) {
+        return evaluatedField.error;
+    }
+    if (candidateFieldIds.has('name') && result?.activity?.nameError) {
+        return result.activity.nameError;
+    }
+    for (const candidateId of candidateFieldIds) {
+        const metaError = result?.meta?.fields?.[candidateId]?.error;
+        if (metaError) {
+            return metaError;
+        }
+    }
+    return result?.meta?.error || result?.error || null;
+}
+function workflowNotFoundResponse(workflowId) {
+    return (0, response_builder_1.errorResponse)(`Workflow not found: ${workflowId}`, 'Use describe_workflows to find the workflow ID or key, then retry.');
+}
+function fieldNotFoundResponse(fieldId, workflow) {
+    return (0, response_builder_1.errorResponse)(`Function Field target not found: ${fieldId}`, workflow ? `Workflow: ${workflow.name || workflow._id}` : 'Pass workflowId when the field ID/key is ambiguous.');
+}
+function unresolvedFieldKeyResponse(fieldId) {
+    return (0, response_builder_1.errorResponse)(`Cannot resolve field "${fieldId}" to a backend Function Field ID.`, 'Pass workflowId when using a field key, or pass a 24-character field ID. Use fieldId="name" for the workflow name Function Field.');
+}
+function resolveBackendFieldId(context, fieldIdOrKey, workflowIdOrKey) {
+    const resolved = resolveWorkflowAndField(context, workflowIdOrKey, fieldIdOrKey);
+    if (workflowIdOrKey && !resolved.workflow) {
+        return { response: workflowNotFoundResponse(workflowIdOrKey) };
+    }
+    if (resolved.ambiguous) {
+        return { response: fieldNotFoundResponse(fieldIdOrKey, resolved.workflow), ambiguous: true };
+    }
+    if (!resolved.field && !isBackendResolvableFieldId(resolved.fieldId)) {
+        return { response: unresolvedFieldKeyResponse(fieldIdOrKey), workflow: resolved.workflow };
+    }
+    return { fieldId: resolved.fieldId, workflow: resolved.workflow, field: resolved.field };
+}
+function resolveWorkflowFieldId(workflow, fieldIdOrKey) {
+    const entry = findFieldEntry(workflow, fieldIdOrKey);
+    const fieldId = entry?.fieldId || normalizeFunctionFieldId(fieldIdOrKey);
+    if (!entry && !isBackendResolvableFieldId(fieldId)) {
+        return { response: fieldNotFoundResponse(fieldIdOrKey, workflow) };
+    }
+    return { fieldId };
+}
+function resolveWorkflowFieldIds(workflow, fieldIdsOrKeys) {
+    const fieldIds = [];
+    for (const fieldIdOrKey of fieldIdsOrKeys) {
+        const resolved = resolveWorkflowFieldId(workflow, fieldIdOrKey);
+        if (resolved.response) {
+            return { response: resolved.response };
+        }
+        fieldIds.push(resolved.fieldId);
+    }
+    return { fieldIds: Array.from(new Set(fieldIds)) };
+}
+function resolveRepairScope(args) {
+    if (args.scope) {
+        return args.scope;
+    }
+    if (args.activityId && args.workflowId) {
+        return (0, response_builder_1.errorResponse)('Repair scope is required when both activityId and workflowId are provided.', 'Set scope="activity" for one activity path, or scope="workflow" for the whole workflow field.');
+    }
+    return args.activityId ? 'activity' : 'workflow';
+}
+async function executeActivityRepair(args, context) {
+    if (!args.activityId) {
+        return (0, response_builder_1.errorResponse)('activityId is required for activity-scoped repair.');
+    }
+    const resolvedField = resolveBackendFieldId(context, args.fieldId, args.workflowId);
+    if (resolvedField.response) {
+        return resolvedField.response;
+    }
+    const endpoint = repairEndpoint('activity', args.apply, args.force);
+    const result = await context.hailer.request(endpoint, [{
+            activityId: args.activityId,
+            fieldId: resolvedField.fieldId,
+            incomingMaxDepth: args.incomingMaxDepth,
+            outgoingMaxDepth: args.outgoingMaxDepth,
+            includeValues: args.includeValues,
+            propagateDependents: args.propagateDependents,
+            ...(args.apply ? { writeValues: true } : { force: args.force }),
+        }]);
+    return (0, response_builder_1.jsonResponse)(result, `Function Field repair result (${endpoint})`);
+}
+async function executeWorkflowRepair(args, context) {
+    if (!args.workflowId) {
+        return (0, response_builder_1.errorResponse)('workflowId is required for workflow-scoped repair.');
+    }
+    const workflow = resolveWorkflow(context, args.workflowId);
+    if (!workflow) {
+        return workflowNotFoundResponse(args.workflowId);
+    }
+    const resolvedField = resolveWorkflowFieldId(workflow, args.fieldId);
+    if (resolvedField.response) {
+        return resolvedField.response;
+    }
+    const endpoint = repairEndpoint('workflow', args.apply, args.force);
+    const result = await context.hailer.request(endpoint, [{
+            workflowId: workflow._id,
+            fieldId: resolvedField.fieldId,
+            incomingMaxDepth: args.incomingMaxDepth,
+            outgoingMaxDepth: args.outgoingMaxDepth,
+            includeValues: args.includeValues,
+            propagateDependents: args.propagateDependents,
+            limit: args.limit,
+            includeActivityResults: args.includeActivityResults,
+            ...(args.apply ? { writeValues: true } : { force: args.force }),
+        }]);
+    return (0, response_builder_1.jsonResponse)(result, `Function Field repair result (${endpoint})`);
+}
+const explainFunctionFieldGraphSchema = zod_1.z.object({
+    activityId: zod_1.z.string().min(1).describe('Representative activity ID for the graph root'),
+    fieldId: zod_1.z.string().min(1).describe('Field ID/key, or "name" for the workflow name Function Field'),
+    workflowId: zod_1.z.string().optional().describe('Optional workflow ID/key for resolving field keys before calling the Fast Functions backend'),
+    direction: zod_1.z.enum(['incoming', 'outgoing', 'both']).default('both').describe('Graph direction to inspect'),
+    graphMode: zod_1.z.enum(['runtime', 'configured']).default('runtime').describe('runtime = actual current engine behavior; configured = declared dependencies'),
+    maxDepth: zod_1.z.number().int().min(0).max(16).default(8).describe('Default depth when incoming/outgoing depths are omitted'),
+    incomingMaxDepth: zod_1.z.number().int().min(0).max(16).optional().describe('Incoming dependency depth'),
+    outgoingMaxDepth: zod_1.z.number().int().min(0).max(16).optional().describe('Outgoing dependent depth'),
+    includeValues: zod_1.z.boolean().default(false).describe('Include raw values in graph output. Keep false unless values are needed.'),
+    aiExplanation: zod_1.z.boolean().default(false).describe('Call the backend AI graph explainer instead of returning the deterministic graph'),
+});
+exports.explainFunctionFieldGraphTool = {
+    name: 'explain_function_field_graph',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Explain a Function Field dependency graph for one activity field. Read-only. Start with graphMode="runtime"; use "configured" for declared dependency/cycle questions.',
+    schema: explainFunctionFieldGraphSchema,
+    async execute(args, context) {
+        try {
+            const resolved = resolveBackendFieldId(context, args.fieldId, args.workflowId);
+            if (resolved.response) {
+                return resolved.response;
+            }
+            const fieldId = resolved.fieldId;
+            const endpoint = args.aiExplanation ? 'v3.activity.explainNode.assist' : 'v3.activity.explainNode';
+            const result = await context.hailer.request(endpoint, [{
+                    activityId: args.activityId,
+                    fieldId,
+                    direction: args.direction,
+                    graphMode: args.graphMode,
+                    maxDepth: args.maxDepth,
+                    incomingMaxDepth: args.incomingMaxDepth,
+                    outgoingMaxDepth: args.outgoingMaxDepth,
+                    includeValues: args.includeValues,
+                }]);
+            return (0, response_builder_1.jsonResponse)(result, `Function Field graph (${endpoint})`);
+        }
+        catch (error) {
+            logger.error('Failed to explain Function Field graph', error, { activityId: args.activityId, fieldId: args.fieldId });
+            return (0, response_builder_1.errorResponse)('Failed to explain Function Field graph', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const dryRunFunctionFieldSchema = zod_1.z.object({
+    activityId: zod_1.z.string().min(1).describe('Representative activity ID to evaluate against'),
+    fieldId: zod_1.z.string().min(1).describe('Field ID/key, or "name" for the workflow name Function Field'),
+    workflowId: zod_1.z.string().optional().describe('Workflow ID/key. Required when fieldId is a key or current saved code/dependencies should be reused.'),
+    code: zod_1.z.string().optional().describe('Function body to dry-run. If omitted, the saved Function Field code is used.'),
+    function: zod_1.z.string().optional().describe('Deprecated alias for code; accepted for stale clients.'),
+    functionVariables: optionalFunctionVariablesSchema.describe('Dependency configuration. If omitted, the saved functionVariables are used when workflowId/field can be resolved.'),
+    incomingMaxDepth: zod_1.z.number().int().min(0).max(16).default(16).describe('Incoming graph depth for resolving dependencies'),
+    evaluateIncomingNodes: zod_1.z.boolean().default(true).describe('Evaluate upstream Function Field nodes before this dry-run'),
+});
+exports.dryRunFunctionFieldTool = {
+    name: 'dry_run_function_field',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Dry-run current or proposed Function Field code on one activity via v2.activities.evaluate. Read-only; use before save_function_field.',
+    schema: dryRunFunctionFieldSchema,
+    async execute(args, context) {
+        try {
+            const resolved = resolveWorkflowAndField(context, args.workflowId, args.fieldId);
+            if (args.workflowId && !resolved.workflow) {
+                return workflowNotFoundResponse(args.workflowId);
+            }
+            const field = resolved.field;
+            const code = args.code ?? args.function ?? field?.function;
+            const hasExplicitVariables = hasOwnArg(args, 'functionVariables');
+            if (resolved.ambiguous && !(resolved.fieldId === 'name' && code && hasExplicitVariables)) {
+                return fieldNotFoundResponse(args.fieldId, resolved.workflow);
+            }
+            if (!code) {
+                return (0, response_builder_1.errorResponse)('Function Field code is required', 'Pass code, or pass workflowId + fieldId so the saved function body can be reused.');
+            }
+            if (!field && !hasExplicitVariables) {
+                return (0, response_builder_1.errorResponse)('Function Field dependencies are required.', 'Pass functionVariables explicitly, or pass workflowId + fieldId so saved Fast Functions dependencies can be resolved.');
+            }
+            const variables = hasExplicitVariables
+                ? parseRecord(args.functionVariables, 'functionVariables')
+                : parseRecord(field?.functionVariables, 'saved functionVariables', {});
+            if (!isBackendResolvableFieldId(resolved.fieldId)) {
+                return unresolvedFieldKeyResponse(args.fieldId);
+            }
+            const result = await context.hailer.request('v2.activities.evaluate', [
+                args.activityId,
+                resolved.fieldId,
+                code,
+                variables,
+                {
+                    incomingMaxDepth: args.incomingMaxDepth,
+                    evaluateIncomingNodes: args.evaluateIncomingNodes,
+                },
+            ]);
+            const evaluationError = extractEvaluationError(result, resolved.fieldId);
+            if (evaluationError) {
+                return (0, response_builder_1.errorResponse)('Function Field dry-run failed evaluation.', `${evaluationError}\n\nDry-run response:\n${JSON.stringify(result, null, 2)}`);
+            }
+            return (0, response_builder_1.jsonResponse)(result, 'Function Field dry-run result');
+        }
+        catch (error) {
+            logger.error('Function Field dry-run failed', error, { activityId: args.activityId, fieldId: args.fieldId });
+            return (0, response_builder_1.errorResponse)('Function Field dry-run failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const assistFunctionFieldSchema = zod_1.z.object({
+    mode: zod_1.z.enum(['generate', 'improve', 'explain']).describe('generate creates code, improve updates code, explain describes current code'),
+    instruction: zod_1.z.string().max(4000).default('').describe('User request or improvement goal'),
+    activityId: zod_1.z.string().min(1).describe('Representative activity ID'),
+    workflowId: zod_1.z.string().min(1).describe('Workflow ID/key for the Function Field'),
+    fieldId: zod_1.z.string().min(1).describe('Field ID/key, or "name" for the workflow name Function Field'),
+    code: zod_1.z.string().optional().describe('Current code. If omitted, saved code is used.'),
+    dependencies: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional().describe('Dependency descriptions. If omitted, they are derived from functionVariables.'),
+    functionVariables: optionalFunctionVariablesSchema.describe('Dependency configuration. If omitted, saved functionVariables are used.'),
+    currentEvaluation: optionalRecordOrStringSchema.describe('Optional dry-run result or evaluation context from dry_run_function_field'),
+    expectedOutput: zod_1.z.string().optional().describe('Expected output contract. If omitted, inferred from field type.'),
+});
+exports.assistFunctionFieldTool = {
+    name: 'assist_function_field',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Ask the backend Function Field assistant to generate, improve, or explain code. Read-only suggestion only; it never saves workflow config.',
+    schema: assistFunctionFieldSchema,
+    async execute(args, context) {
+        try {
+            const resolved = resolveWorkflowAndField(context, args.workflowId, args.fieldId);
+            if (!resolved.workflow) {
+                return workflowNotFoundResponse(args.workflowId);
+            }
+            if (!resolved.field) {
+                return fieldNotFoundResponse(args.fieldId, resolved.workflow);
+            }
+            const variables = hasOwnArg(args, 'functionVariables')
+                ? parseRecord(args.functionVariables, 'functionVariables')
+                : parseRecord(resolved.field.functionVariables, 'saved functionVariables', {});
+            const dependencies = args.dependencies || dependencyDescriptions(context, resolved.workflow, variables);
+            const code = args.code ?? resolved.field.function ?? '';
+            const result = await context.hailer.request('v3.activity.functionField.assist', [{
+                    mode: args.mode,
+                    instruction: args.instruction,
+                    code,
+                    activityId: args.activityId,
+                    workflow: {
+                        id: resolved.workflow._id,
+                        name: resolved.workflow.name,
+                    },
+                    field: {
+                        id: resolved.fieldId,
+                        label: resolved.field.label || resolved.fieldId,
+                        type: resolved.field.type || 'text',
+                        editable: !!resolved.field.editable,
+                        expectedOutput: args.expectedOutput || expectedOutputForFieldType(resolved.field.type),
+                    },
+                    dependencies,
+                    functionVariables: variables,
+                    currentEvaluation: parseRecord(args.currentEvaluation, 'currentEvaluation', {}),
+                }]);
+            return (0, response_builder_1.jsonResponse)(result, 'Function Field assistant result');
+        }
+        catch (error) {
+            logger.error('Function Field assistant failed', error, { workflowId: args.workflowId, fieldId: args.fieldId });
+            return (0, response_builder_1.errorResponse)('Function Field assistant failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const verifyWorkflowFunctionValuesSchema = zod_1.z.object({
+    workflowId: zod_1.z.string().min(1).describe('Workflow ID/key to verify'),
+    fieldId: zod_1.z.string().optional().describe('Single Function Field ID/key'),
+    fieldIds: zod_1.z.array(zod_1.z.string()).optional().describe('Function Field IDs/keys to verify'),
+    activityIds: zod_1.z.array(zod_1.z.string()).optional().describe('Optional activity IDs to scope the scan'),
+    incomingMaxDepth: zod_1.z.number().int().min(0).max(16).default(1),
+    mode: zod_1.z.enum(['runtime', 'forcePreview']).default('runtime'),
+    includeValues: zod_1.z.boolean().default(false),
+    includeResults: zod_1.z.boolean().default(true),
+    statuses: zod_1.z.array(zod_1.z.enum(validStatuses)).optional().describe('Filter returned statuses'),
+    limit: zod_1.z.number().int().min(1).max(100000).optional(),
+    maxNodes: zod_1.z.number().int().min(1).max(1000000).default(100000),
+});
+exports.verifyWorkflowFunctionValuesTool = {
+    name: 'verify_workflow_function_values',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Read-only scan for stored/computed Function Field drift in a workflow. Use before repair_function_values.',
+    schema: verifyWorkflowFunctionValuesSchema,
+    async execute(args, context) {
+        try {
+            const workflow = resolveWorkflow(context, args.workflowId);
+            if (!workflow) {
+                return workflowNotFoundResponse(args.workflowId);
+            }
+            const requestedFieldIds = Array.from(new Set([
+                ...(args.fieldIds || []),
+                ...(args.fieldId ? [args.fieldId] : []),
+            ]));
+            if (!requestedFieldIds.length) {
+                return (0, response_builder_1.errorResponse)('At least one fieldId or fieldIds entry is required.');
+            }
+            const resolvedFieldIds = resolveWorkflowFieldIds(workflow, requestedFieldIds);
+            if (resolvedFieldIds.response) {
+                return resolvedFieldIds.response;
+            }
+            const result = await context.hailer.request('v3.activity.verifyWorkflowValues', [{
+                    workflowId: workflow._id,
+                    fieldIds: resolvedFieldIds.fieldIds,
+                    activityIds: args.activityIds,
+                    incomingMaxDepth: args.incomingMaxDepth,
+                    mode: args.mode,
+                    includeValues: args.includeValues,
+                    includeResults: args.includeResults,
+                    statuses: args.statuses,
+                    limit: args.limit,
+                    maxNodes: args.maxNodes,
+                }]);
+            return (0, response_builder_1.jsonResponse)(result, 'Workflow Function Field verification result');
+        }
+        catch (error) {
+            logger.error('Workflow Function Field verification failed', error, { workflowId: args.workflowId });
+            return (0, response_builder_1.errorResponse)('Workflow Function Field verification failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const previewWorkflowFunctionEvaluationSchema = zod_1.z.object({
+    action: zod_1.z.enum(['start', 'logs']).optional().describe('start begins a preview run; logs polls a previous run. Defaults to logs when runId is present.'),
+    workflowId: zod_1.z.string().optional().describe('Workflow ID/key. Required for action=start.'),
+    fieldIds: zod_1.z.array(zod_1.z.string()).optional().describe('Optional Function Field IDs/keys to preview. Omit for all active Function Fields.'),
+    runId: zod_1.z.string().optional().describe('Run ID returned by action=start. Required for action=logs.'),
+    afterTs: zod_1.z.number().int().min(0).optional().describe('Only return logs newer than this timestamp'),
+    limit: zod_1.z.number().int().min(1).max(500).default(200).describe('Maximum log entries to return'),
+});
+exports.previewWorkflowFunctionEvaluationTool = {
+    name: 'preview_workflow_function_evaluation',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Start or poll a read-only workflow Function Field evaluation preview. This always uses apply=false and never writes values.',
+    schema: previewWorkflowFunctionEvaluationSchema,
+    async execute(args, context) {
+        try {
+            const action = args.action || (args.runId ? 'logs' : 'start');
+            if (action === 'logs' && !args.runId) {
+                return (0, response_builder_1.errorResponse)('runId is required when action="logs".');
+            }
+            if (action === 'logs') {
+                const result = await context.hailer.request('v3.activity.evaluateWorkflowFunctions.logs', [{
+                        runId: args.runId,
+                        afterTs: args.afterTs,
+                        limit: args.limit,
+                    }]);
+                return (0, response_builder_1.jsonResponse)(result, 'Workflow Function Field preview logs');
+            }
+            if (!args.workflowId) {
+                return (0, response_builder_1.errorResponse)('workflowId is required when action="start".');
+            }
+            const workflow = resolveWorkflow(context, args.workflowId);
+            if (!workflow) {
+                return workflowNotFoundResponse(args.workflowId);
+            }
+            const resolvedFieldIds = args.fieldIds ? resolveWorkflowFieldIds(workflow, args.fieldIds) : {};
+            if (resolvedFieldIds.response) {
+                return resolvedFieldIds.response;
+            }
+            const result = await context.hailer.request('v3.activity.evaluateWorkflowFunctions.start', [{
+                    processId: workflow._id,
+                    fieldIds: resolvedFieldIds.fieldIds,
+                    apply: false,
+                }]);
+            return (0, response_builder_1.jsonResponse)(result, 'Workflow Function Field preview started');
+        }
+        catch (error) {
+            logger.error('Workflow Function Field preview failed', error, { workflowId: args.workflowId, runId: args.runId });
+            return (0, response_builder_1.errorResponse)('Workflow Function Field preview failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const saveFunctionFieldSchema = zod_1.z.object({
+    workflowId: zod_1.z.string().min(1).describe('Workflow ID/key containing the Function Field'),
+    fieldId: zod_1.z.string().min(1).describe('Field ID/key, or "name" for the workflow name Function Field'),
+    code: zod_1.z.string().optional().describe('Function body to save'),
+    functionVariables: optionalFunctionVariablesSchema.describe('Dependency configuration to save'),
+    functionEnabled: zod_1.z.boolean().optional().describe('Enable or disable the Function Field'),
+    confirmWrite: zod_1.z.boolean().default(false).describe('Must be true only after the user explicitly asked to save Function Field configuration.'),
+});
+exports.saveFunctionFieldTool = {
+    name: 'save_function_field',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Write Function Field configuration with process.update_field/process.set_info. Requires confirmWrite=true after dry-run/validation and explicit user save intent.',
+    schema: saveFunctionFieldSchema,
+    async execute(args, context) {
+        try {
+            if (!args.confirmWrite) {
+                return (0, response_builder_1.errorResponse)('Write confirmation required.', 'Set confirmWrite=true only after the user explicitly asked to save Function Field configuration.');
+            }
+            const resolved = resolveWorkflowAndField(context, args.workflowId, args.fieldId);
+            if (!resolved.workflow) {
+                return workflowNotFoundResponse(args.workflowId);
+            }
+            if (!resolved.field) {
+                return fieldNotFoundResponse(args.fieldId, resolved.workflow);
+            }
+            const hasCode = hasOwnArg(args, 'code');
+            const hasVariables = hasOwnArg(args, 'functionVariables');
+            const hasEnabled = hasOwnArg(args, 'functionEnabled');
+            if (!hasCode && !hasVariables && !hasEnabled) {
+                return (0, response_builder_1.errorResponse)('Nothing to save.', 'Pass code, functionVariables, functionEnabled, or a combination.');
+            }
+            const variables = hasVariables ? parseRecord(args.functionVariables, 'functionVariables') : undefined;
+            const update = {};
+            if (resolved.fieldId === 'name') {
+                addIfPresent(update, 'nameFunction', args.code, hasCode);
+                addIfPresent(update, 'nameFunctionVariables', variables, hasVariables);
+                addIfPresent(update, 'nameFunctionEnabled', args.functionEnabled, hasEnabled);
+                await context.hailer.request('process.set_info', [resolved.workflow._id, update]);
+            }
+            if (resolved.fieldId !== 'name') {
+                addIfPresent(update, 'function', args.code, hasCode);
+                addIfPresent(update, 'functionVariables', variables, hasVariables);
+                addIfPresent(update, 'functionEnabled', args.functionEnabled, hasEnabled);
+                await context.hailer.request('process.update_field', [resolved.workflow._id, resolved.fieldId, update]);
+            }
+            UserContextCache_1.UserContextCache.clearContext(context.apiKey);
+            return (0, response_builder_1.jsonResponse)({
+                saved: true,
+                workflowId: resolved.workflow._id,
+                fieldId: resolved.fieldId,
+                updatedKeys: Object.keys(update),
+            }, 'Function Field configuration saved');
+        }
+        catch (error) {
+            logger.error('Function Field save failed', error, { workflowId: args.workflowId, fieldId: args.fieldId });
+            return (0, response_builder_1.errorResponse)('Function Field save failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+const repairFunctionValuesSchema = zod_1.z.object({
+    scope: zod_1.z.enum(['activity', 'workflow']).optional().describe('activity repairs one activity path; workflow repairs a field across active workflow activities'),
+    activityId: zod_1.z.string().optional().describe('Activity ID. Required for scope=activity.'),
+    workflowId: zod_1.z.string().optional().describe('Workflow ID/key. Required for scope=workflow.'),
+    fieldId: zod_1.z.string().min(1).describe('Function Field ID/key to repair'),
+    apply: zod_1.z.boolean().default(false).describe('false = dry-run/preview only; true = write repaired values'),
+    confirmWrite: zod_1.z.boolean().default(false).describe('Required with apply=true after explicit user repair/apply intent.'),
+    force: zod_1.z.boolean().default(false).describe('Force repair does not trust editable values as cycle breakers'),
+    incomingMaxDepth: zod_1.z.number().int().min(0).max(16).default(8),
+    outgoingMaxDepth: zod_1.z.number().int().min(0).max(16).default(8),
+    includeValues: zod_1.z.boolean().optional().describe('Include values in repair output. Defaults are backend-specific.'),
+    propagateDependents: zod_1.z.boolean().optional().describe('Also evaluate downstream dependents'),
+    limit: zod_1.z.number().int().min(1).max(10000).optional().describe('Workflow scope only: max activities to inspect'),
+    includeActivityResults: zod_1.z.boolean().optional().describe('Workflow scope only: include per-activity repair results'),
+});
+exports.repairFunctionValuesTool = {
+    name: 'repair_function_values',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Preview or apply Function Field value repairs. Defaults to dry-run. apply=true writes values and requires confirmWrite=true.',
+    schema: repairFunctionValuesSchema,
+    async execute(args, context) {
+        try {
+            if (args.apply && !args.confirmWrite) {
+                return (0, response_builder_1.errorResponse)('Write confirmation required.', 'Run with apply=false first, review the plan, then set apply=true and confirmWrite=true only after explicit user repair/apply intent.');
+            }
+            const scope = resolveRepairScope(args);
+            if (typeof scope !== 'string') {
+                return scope;
+            }
+            return await (scope === 'activity'
+                ? executeActivityRepair(args, context)
+                : executeWorkflowRepair(args, context));
+        }
+        catch (error) {
+            logger.error('Function Field repair failed', error, {
+                scope: args.scope,
+                activityId: args.activityId,
+                workflowId: args.workflowId,
+                fieldId: args.fieldId,
+            });
+            return (0, response_builder_1.errorResponse)('Function Field repair failed', error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+exports.functionFieldTools = [
+    exports.explainFunctionFieldGraphTool,
+    exports.dryRunFunctionFieldTool,
+    exports.assistFunctionFieldTool,
+    exports.verifyWorkflowFunctionValuesTool,
+    exports.previewWorkflowFunctionEvaluationTool,
+    exports.saveFunctionFieldTool,
+    exports.repairFunctionValuesTool,
+];
+//# sourceMappingURL=function-fields.js.map