@sensigo/realm-mcp 0.1.0

package/dist/tools/append-trace.js

@@ -0,0 +1,125 @@
+// append-trace.ts — append_trace MCP tool for incremental mid-step trace ingestion.
+import { z } from 'zod';
+import { JsonWorkflowStore, JsonFileStore, WorkflowError, buildPreExecutionErrorEnvelope, } from '@sensigo/realm';
+import { traceEntrySchema } from './execute-step.js';
+/**
+ * Business logic for the append_trace tool.
+ * Buffers trace entries to the WAL for (runId, stepId). Entries are merged with
+ * any entries submitted at execute_step finalization.
+ *
+ * Throws WorkflowError for all error conditions. Callers (typically
+ * registerAppendTrace) catch and convert to ResponseEnvelope.
+ */
+export async function handleAppendTrace(args, stores) {
+    const workflowStore = stores?.workflowStore ?? new JsonWorkflowStore();
+    const runStore = stores?.runStore ?? new JsonFileStore();
+    const traceBufferStore = stores?.traceBufferStore;
+    // 1. Load the run. Throws STATE_RUN_NOT_FOUND if missing.
+    const run = await runStore.get(args.run_id);
+    // 2. Load the workflow definition.
+    const definition = await workflowStore.get(run.workflow_id);
+    // 3. Find the step in the definition.
+    const stepDef = definition.steps[args.step_id];
+    if (stepDef === undefined) {
+        throw new WorkflowError(`Step '${args.step_id}' not found in workflow '${run.workflow_id}'.`, {
+            code: 'STEP_NOT_FOUND',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { step_id: args.step_id, workflow_id: run.workflow_id, run_version: run.version },
+        });
+    }
+    // 4. Check step type — only agent steps support append_trace.
+    if (stepDef.execution !== 'agent') {
+        throw new WorkflowError(`Step '${args.step_id}' is not an agent step (execution: '${stepDef.execution}').`, {
+            code: 'STATE_STEP_NOT_ELIGIBLE',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { step_id: args.step_id, step_type: stepDef.execution, run_version: run.version },
+        });
+    }
+    // 5. Check step eligibility — must not be completed, failed, or in-progress.
+    if (run.completed_steps.includes(args.step_id) || run.failed_steps.includes(args.step_id)) {
+        throw new WorkflowError(`Step '${args.step_id}' has already been claimed (completed or failed).`, {
+            code: 'STATE_STEP_NOT_ELIGIBLE',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { step_id: args.step_id, step_state: 'already_claimed', run_version: run.version },
+        });
+    }
+    if (run.in_progress_steps.includes(args.step_id)) {
+        throw new WorkflowError(`Step '${args.step_id}' is currently being executed by execute_step.`, {
+            code: 'STATE_STEP_NOT_ELIGIBLE',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { step_id: args.step_id, step_state: 'in_progress', run_version: run.version },
+        });
+    }
+    // Steps 6 + 7: Require buffer store for any append_trace operation.
+    if (traceBufferStore === undefined) {
+        throw new WorkflowError('No trace buffer store configured', {
+            code: 'ENGINE_INTERNAL',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+        });
+    }
+    // 6. Empty entries — return current buffer state without writing.
+    if (args.entries.length === 0) {
+        const result = await traceBufferStore.append(args.run_id, args.step_id, []);
+        return { status: 'ok', ...result };
+    }
+    // 7. Append entries to the buffer.
+    const result = await traceBufferStore.append(args.run_id, args.step_id, args.entries);
+    return { status: 'ok', ...result };
+}
+/** Registers the append_trace MCP tool on the server. */
+export function registerAppendTrace(server, opts) {
+    server.tool('append_trace', [
+        'Submit trace entries incrementally during an agent step, before calling execute_step.',
+        'Entries are buffered and merged with any entries submitted at execute_step finalization.',
+        'Delivery is best-effort: entries are durable after this call returns but are not canonical until execute_step completes.',
+        'Only valid for agent steps that have not yet been claimed (before execute_step is called).',
+    ].join(' '), {
+        run_id: z.string(),
+        step_id: z.string(),
+        entries: z.array(traceEntrySchema),
+    }, async (args) => {
+        try {
+            const result = await handleAppendTrace(args, opts);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            const workflowErr = err instanceof WorkflowError
+                ? err
+                : new WorkflowError(err instanceof Error ? err.message : String(err), {
+                    code: 'ENGINE_INTERNAL',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                });
+            const runVersion = typeof workflowErr.details['run_version'] === 'number'
+                ? workflowErr.details['run_version']
+                : 0;
+            const contextHint = workflowErr.code === 'STATE_RUN_NOT_FOUND'
+                ? `Run '${args.run_id}' not found.`
+                : workflowErr.code === 'STEP_NOT_FOUND'
+                    ? `Step '${args.step_id}' not found in the workflow.`
+                    : workflowErr.code === 'STATE_STEP_NOT_ELIGIBLE'
+                        ? `Step '${args.step_id}' is not eligible for trace buffering.`
+                        : workflowErr.code === 'BUFFER_FULL'
+                            ? `Trace buffer is full for step '${args.step_id}'.`
+                            : `An error occurred during append_trace for run '${args.run_id}'.`;
+            const envelope = buildPreExecutionErrorEnvelope('append_trace', args.run_id, runVersion, workflowErr, contextHint);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
+            };
+        }
+    });
+}
+//# sourceMappingURL=append-trace.js.map

package/dist/tools/append-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-trace.js","sourceRoot":"","sources":["../../src/tools/append-trace.ts"],"names":[],"mappings":"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"}

package/dist/tools/create-workflow.d.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonWorkflowStore, JsonFileStore, type ResponseEnvelope } from '@sensigo/realm';
+import { type HandleRunStores } from './start-run.js';
+export interface CreateWorkflowStep {
+    id: string;
+    description: string;
+    depends_on?: string[];
+    input_schema?: Record<string, unknown>;
+    timeout_seconds?: number;
+}
+export interface CreateWorkflowArgs {
+    steps: CreateWorkflowStep[];
+    metadata?: {
+        name?: string;
+        task_description?: string;
+        model?: string;
+        agent?: string;
+    };
+}
+/**
+ * Business logic for the create_workflow tool.
+ * Validates steps, derives a workflow ID, registers the definition, and starts a run.
+ */
+export declare function handleCreateWorkflow(args: CreateWorkflowArgs, stores?: {
+    workflowStore?: JsonWorkflowStore;
+    runStore?: JsonFileStore;
+}): Promise<ResponseEnvelope>;
+/** Registers the create_workflow MCP tool on the server. */
+export declare function registerCreateWorkflow(server: McpServer, opts?: HandleRunStores): void;
+//# sourceMappingURL=create-workflow.d.ts.map

package/dist/tools/create-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-workflow.d.ts","sourceRoot":"","sources":["../../src/tools/create-workflow.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACL,iBAAiB,EACjB,aAAa,EAIb,KAAK,gBAAgB,EAGtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAyKD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAE,GACvE,OAAO,CAAC,gBAAgB,CAAC,CAyB3B;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAmEtF"}

package/dist/tools/create-workflow.js

@@ -0,0 +1,228 @@
+// create-workflow.ts — Mode 2: agent creates and registers a workflow at runtime, then starts a run.
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { JsonWorkflowStore, WorkflowError, resolvePreExecutionAgentAction, CURRENT_WORKFLOW_SCHEMA_VERSION, } from '@sensigo/realm';
+import { handleStartRun } from './start-run.js';
+function makeErrorEnvelope(errors) {
+    return {
+        command: 'create_workflow',
+        run_id: '',
+        run_version: 0,
+        status: 'error',
+        data: {},
+        evidence: [],
+        warnings: [],
+        errors,
+        agent_action: 'provide_input',
+        context_hint: 'Invalid create_workflow input. Fix the errors and retry.',
+        next_actions: [],
+    };
+}
+/** Validates all submitted steps. Returns collected error strings (empty = valid). */
+function validateArgs(args) {
+    const errors = [];
+    if (args.steps.length === 0) {
+        errors.push('steps must contain at least one step');
+        return errors;
+    }
+    // Rule 7: agent_profile is not supported on dynamic workflows.
+    for (const step of args.steps) {
+        if ('agent_profile' in step) {
+            errors.push(`Step '${step.id}': agent_profile is not supported on dynamically-created workflows. Use realm register with a YAML workflow file for profile-based execution.`);
+        }
+    }
+    // Rule 2: step IDs must be unique.
+    const seenIds = new Set();
+    for (const step of args.steps) {
+        if (seenIds.has(step.id)) {
+            errors.push(`Duplicate step id: '${step.id}'`);
+        }
+        seenIds.add(step.id);
+    }
+    // Rule 3: step IDs must be non-empty with no spaces.
+    for (const step of args.steps) {
+        if (step.id.trim() === '' || step.id.includes(' ')) {
+            errors.push(`Step id '${step.id}' is invalid: must be a non-empty string with no spaces`);
+        }
+    }
+    // Rule 4: descriptions must be non-empty.
+    for (const step of args.steps) {
+        if (step.description.trim() === '') {
+            errors.push(`Step '${step.id}': description must be non-empty`);
+        }
+    }
+    // Rule 5: timeout_seconds must be a positive integer if present.
+    for (const step of args.steps) {
+        if (step.timeout_seconds !== undefined) {
+            if (!Number.isInteger(step.timeout_seconds) || step.timeout_seconds <= 0) {
+                errors.push(`Step '${step.id}': timeout_seconds must be a positive integer`);
+            }
+        }
+    }
+    // Rule 6: depends_on validation.
+    const allIds = new Set(args.steps.map((s) => s.id));
+    const stepPositions = new Map();
+    args.steps.forEach((s, i) => stepPositions.set(s.id, i));
+    for (const step of args.steps) {
+        if (step.depends_on !== undefined) {
+            if (step.depends_on.length > 1) {
+                errors.push(`Step '${step.id}': depends_on supports at most one predecessor (this engine is linear)`);
+            }
+            for (const ref of step.depends_on) {
+                if (!allIds.has(ref)) {
+                    errors.push(`Step '${step.id}': depends_on references unknown step '${ref}'`);
+                }
+                else {
+                    const refPos = stepPositions.get(ref);
+                    const myPos = stepPositions.get(step.id);
+                    if (refPos >= myPos) {
+                        errors.push(`Step '${step.id}': depends_on must reference a step that appears earlier in the list`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Derives a deterministic workflow ID from a slug of the optional name and a
+ * 16-hex-char SHA-256 prefix of the definition content (excluding the `id`
+ * field to avoid circular dependency). Identical definition content always
+ * produces the same ID, making `create_workflow` retries idempotent with the
+ * existing file-overwrite semantics of `JsonWorkflowStore.register`.
+ */
+function deriveWorkflowId(name, definitionWithoutId) {
+    const hash = createHash('sha256')
+        .update(JSON.stringify(definitionWithoutId))
+        .digest('hex')
+        .slice(0, 16);
+    if (name !== undefined && name.trim() !== '') {
+        const slug = name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        return `${slug}-${hash}`;
+    }
+    return `dynamic-${hash}`;
+}
+/** Builds a linear WorkflowDefinition from the submitted steps. */
+function buildWorkflowDefinition(workflowId, args) {
+    const { steps, metadata } = args;
+    const stepsRecord = {};
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const prevStepId = i === 0 ? undefined : steps[i - 1].id;
+        const stepDef = {
+            description: step.description,
+            execution: 'agent',
+            depends_on: prevStepId !== undefined ? [prevStepId] : [],
+        };
+        if (step.input_schema !== undefined) {
+            stepDef.input_schema = step.input_schema;
+        }
+        if (step.timeout_seconds !== undefined) {
+            stepDef.timeout_seconds = step.timeout_seconds;
+        }
+        stepsRecord[step.id] = stepDef;
+    }
+    const definition = {
+        id: workflowId,
+        name: metadata?.name ?? 'Dynamic Workflow',
+        version: 1,
+        schema_version: CURRENT_WORKFLOW_SCHEMA_VERSION,
+        steps: stepsRecord,
+    };
+    if (metadata?.task_description !== undefined) {
+        definition.protocol = { quick_start: metadata.task_description };
+    }
+    definition.origin = 'agent';
+    if (metadata?.model !== undefined) {
+        definition.model = metadata.model;
+    }
+    if (metadata?.agent !== undefined) {
+        definition.agent = metadata.agent;
+    }
+    return definition;
+}
+/**
+ * Business logic for the create_workflow tool.
+ * Validates steps, derives a workflow ID, registers the definition, and starts a run.
+ */
+export async function handleCreateWorkflow(args, stores) {
+    const errors = validateArgs(args);
+    if (errors.length > 0) {
+        return makeErrorEnvelope(errors);
+    }
+    const workflowStore = stores?.workflowStore ?? new JsonWorkflowStore();
+    // Build the definition body first (with a placeholder id that is excluded from the hash).
+    const definitionBody = buildWorkflowDefinition('__placeholder__', args);
+    // Hash all content except the id to derive a stable, deterministic id.
+    const { id: _placeholderId, ...definitionWithoutId } = definitionBody;
+    const workflowId = deriveWorkflowId(args.metadata?.name, definitionWithoutId);
+    const definition = { ...definitionBody, id: workflowId };
+    await workflowStore.register(definition);
+    const result = await handleStartRun({ workflow_id: workflowId, params: {} }, {
+        workflowStore,
+        ...(stores?.runStore !== undefined ? { runStore: stores.runStore } : {}),
+    });
+    return { ...result, command: 'create_workflow', data: { workflow_id: workflowId } };
+}
+/** Registers the create_workflow MCP tool on the server. */
+export function registerCreateWorkflow(server, opts) {
+    const stepSchema = z
+        .object({
+        id: z.string(),
+        description: z.string(),
+        depends_on: z.array(z.string()).optional(),
+        input_schema: z.record(z.unknown()).optional(),
+        timeout_seconds: z.number().optional(),
+    })
+        .passthrough();
+    server.tool('create_workflow', 'Create a dynamic Realm workflow at runtime and immediately start a run. Use this when you have a multi-step task and want to track your own execution plan. Returns next_action pointing at your first step — proceed with execute_step as normal.', {
+        steps: z.array(stepSchema).min(1),
+        metadata: z
+            .object({
+            name: z.string().optional(),
+            task_description: z.string().optional(),
+            model: z.string().optional(),
+            agent: z.string().optional(),
+        })
+            .optional(),
+    }, async (args) => {
+        try {
+            const result = await handleCreateWorkflow(args, opts);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ...result, command: 'create_workflow' }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const agentAction = err instanceof WorkflowError ? resolvePreExecutionAgentAction(err) : 'report_to_user';
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            command: 'create_workflow',
+                            run_id: '',
+                            status: 'error',
+                            data: {},
+                            evidence: [],
+                            warnings: [],
+                            errors: [message],
+                            agent_action: agentAction,
+                            context_hint: 'An error occurred before the workflow could be registered or the run could be started.',
+                            next_actions: [],
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=create-workflow.js.map

package/dist/tools/create-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-workflow.js","sourceRoot":"","sources":["../../src/tools/create-workflow.ts"],"names":[],"mappings":"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"}

package/dist/tools/execute-step.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ResponseEnvelope, type AgentTraceEntry } from '@sensigo/realm';
+import type { HandleRunStores } from './start-run.js';
+/** Zod schema for a single agent trace entry submitted to execute_step or append_trace. */
+export declare const traceEntrySchema: z.ZodObject<{
+    event: z.ZodString;
+    timestamp: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, "strip", z.ZodTypeAny, {
+    event: string;
+    timestamp?: string | undefined;
+    data?: Record<string, string | number | boolean | null> | undefined;
+}, {
+    event: string;
+    timestamp?: string | undefined;
+    data?: Record<string, string | number | boolean | null> | undefined;
+}>;
+/**
+ * Business logic for the execute_step tool.
+ * Validates eligibility, claims the step, and records the agent's params as step output.
+ */
+export declare function handleExecuteStep(args: {
+    run_id: string;
+    command: string;
+    params?: Record<string, unknown>;
+    trace?: AgentTraceEntry[] | undefined;
+}, stores?: HandleRunStores): Promise<ResponseEnvelope>;
+/**
+ * MCP-layer wrapper around handleExecuteStep.
+ * Returns the tool content format used by the MCP server (content array with text JSON).
+ * Exported for direct testing of the MCP response shape.
+ */
+export declare function handleExecuteStepTool(args: {
+    run_id: string;
+    command: string;
+    params?: Record<string, unknown>;
+    trace?: AgentTraceEntry[] | undefined;
+}, stores?: HandleRunStores): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/** Registers the execute_step MCP tool on the server. */
+export declare function registerExecuteStep(server: McpServer, opts?: {
+    registry?: import('@sensigo/realm').ExtensionRegistry;
+    secrets?: Record<string, string>;
+    traceBufferStore?: import('@sensigo/realm').TraceBufferStore;
+}): void;
+//# sourceMappingURL=execute-step.d.ts.map

package/dist/tools/execute-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-step.d.ts","sourceRoot":"","sources":["../../src/tools/execute-step.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAOL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AASH;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;CACvC,EACD,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAqB3B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;CACvC,EACD,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA2C7D;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,IAAI,CAAC,EAAE;IACL,QAAQ,CAAC,EAAE,OAAO,gBAAgB,EAAE,iBAAiB,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,gBAAgB,EAAE,gBAAgB,CAAC;CAC9D,GACA,IAAI,CAcN"}

package/dist/tools/execute-step.js

@@ -0,0 +1,91 @@
+// execute-step tool — executes a named step in a workflow run.
+import { z } from 'zod';
+import { JsonWorkflowStore, JsonFileStore, executeChain, WorkflowError, buildPreExecutionErrorEnvelope, } from '@sensigo/realm';
+/** Zod schema for a single agent trace entry submitted to execute_step or append_trace. */
+export const traceEntrySchema = z.object({
+    event: z.string(),
+    timestamp: z.string().optional(),
+    data: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+});
+// For agent steps, the agent's params represent their work output. The dispatcher
+// passes them through as the step output recorded in evidence.
+const makeParamsDispatcher = (params) => async () => params;
+/**
+ * Business logic for the execute_step tool.
+ * Validates eligibility, claims the step, and records the agent's params as step output.
+ */
+export async function handleExecuteStep(args, stores) {
+    const workflowStore = stores?.workflowStore ?? new JsonWorkflowStore();
+    const runStore = stores?.runStore ?? new JsonFileStore();
+    const run = await runStore.get(args.run_id);
+    const definition = await workflowStore.get(run.workflow_id);
+    const params = args.params ?? {};
+    return executeChain(runStore, definition, {
+        runId: args.run_id,
+        command: args.command,
+        input: params,
+        dispatcher: makeParamsDispatcher(params),
+        ...(stores?.registry !== undefined ? { registry: stores.registry } : {}),
+        ...(stores?.secrets !== undefined ? { secrets: stores.secrets } : {}),
+        // trace is a top-level execute_step field — never embedded in params.
+        ...(args.trace !== undefined ? { trace: args.trace } : {}),
+        // Pass WAL buffer store so execution loop can merge and clean up the WAL.
+        ...(stores?.traceBufferStore !== undefined
+            ? { traceBufferStore: stores.traceBufferStore }
+            : {}),
+    });
+}
+/**
+ * MCP-layer wrapper around handleExecuteStep.
+ * Returns the tool content format used by the MCP server (content array with text JSON).
+ * Exported for direct testing of the MCP response shape.
+ */
+export async function handleExecuteStepTool(args, stores) {
+    try {
+        const result = await handleExecuteStep(args, stores);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ ...result, data: {}, evidence: [] }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const workflowErr = err instanceof WorkflowError
+            ? err
+            : new WorkflowError(err instanceof Error ? err.message : String(err), {
+                code: 'ENGINE_INTERNAL',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        const contextHint = workflowErr.code === 'STATE_WORKFLOW_NOT_FOUND'
+            ? `Workflow definition for run '${args.run_id}' not found.`
+            : workflowErr.code === 'STATE_RUN_NOT_FOUND'
+                ? `Run '${args.run_id}' not found.`
+                : `An error occurred before step '${args.command}' could begin.`;
+        const envelope = buildPreExecutionErrorEnvelope(args.command, args.run_id, 0, workflowErr, contextHint);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(envelope, null, 2),
+                },
+            ],
+        };
+    }
+}
+/** Registers the execute_step MCP tool on the server. */
+export function registerExecuteStep(server, opts) {
+    server.tool('execute_step', 'Execute a workflow step. For agent steps, pass your output in params.', {
+        run_id: z.string(),
+        command: z.string(),
+        params: z.record(z.unknown()).optional().default({}),
+        trace: z.array(traceEntrySchema).optional(),
+    }, async (args) => {
+        return handleExecuteStepTool(args, opts);
+    });
+}
+//# sourceMappingURL=execute-step.js.map

package/dist/tools/execute-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-step.js","sourceRoot":"","sources":["../../src/tools/execute-step.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,8BAA8B,GAI/B,MAAM,gBAAgB,CAAC;AAGxB,2FAA2F;AAC3F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACpF,CAAC,CAAC;AAEH,kFAAkF;AAClF,+DAA+D;AAC/D,MAAM,oBAAoB,GACxB,CAAC,MAA+B,EAAkB,EAAE,CACpD,KAAK,IAAI,EAAE,CACT,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAKC,EACD,MAAwB;IAExB,MAAM,aAAa,GAAG,MAAM,EAAE,aAAa,IAAI,IAAI,iBAAiB,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,IAAI,aAAa,EAAE,CAAC;IACzD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IAEjC,OAAO,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE;QACxC,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,MAAM;QACb,UAAU,EAAE,oBAAoB,CAAC,MAAM,CAAC;QACxC,GAAG,CAAC,MAAM,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,sEAAsE;QACtE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,0EAA0E;QAC1E,GAAG,CAAC,MAAM,EAAE,gBAAgB,KAAK,SAAS;YACxC,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE;YAC/C,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,IAKC,EACD,MAAwB;IAExB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;iBACrE;aACF;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,WAAW,GACf,GAAG,YAAY,aAAa;YAC1B,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBAClE,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACT,MAAM,WAAW,GACf,WAAW,CAAC,IAAI,KAAK,0BAA0B;YAC7C,CAAC,CAAC,gCAAgC,IAAI,CAAC,MAAM,cAAc;YAC3D,CAAC,CAAC,WAAW,CAAC,IAAI,KAAK,qBAAqB;gBAC1C,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,cAAc;gBACnC,CAAC,CAAC,kCAAkC,IAAI,CAAC,OAAO,gBAAgB,CAAC;QACvE,MAAM,QAAQ,GAAqB,8BAA8B,CAC/D,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,MAAM,EACX,CAAC,EACD,WAAW,EACX,WAAW,CACZ,CAAC;QACF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,IAIC;IAED,MAAM,CAAC,IAAI,CACT,cAAc,EACd,uEAAuE,EACvE;QACE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;KAC5C,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-run-state.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonFileStore, type RunPhase } from '@sensigo/realm';
+export interface HandleRunStateStores {
+    runStore?: JsonFileStore;
+}
+export interface RunStateSummary {
+    run_id: string;
+    workflow_id: string;
+    run_phase: RunPhase;
+    terminal_state: boolean;
+    completed_steps: string[];
+    in_progress_steps: string[];
+    failed_steps: string[];
+    skipped_steps: string[];
+    pending_gate: import('@sensigo/realm').PendingGate | undefined;
+    evidence_count: number;
+    last_step: string | null;
+    created_at: string;
+    updated_at: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Business logic for the get_run_state tool.
+ * Returns a structured summary of the run without the full evidence array.
+ */
+export declare function handleGetRunState(args: {
+    run_id: string;
+}, stores?: HandleRunStateStores): Promise<RunStateSummary>;
+/** Registers the get_run_state MCP tool on the server. */
+export declare function registerGetRunState(server: McpServer, opts?: HandleRunStateStores): void;
+//# sourceMappingURL=get-run-state.d.ts.map

package/dist/tools/get-run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-run-state.d.ts","sourceRoot":"","sources":["../../src/tools/get-run-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACL,aAAa,EAGb,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,QAAQ,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,OAAO,gBAAgB,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EACxB,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAoB1B;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,IAAI,CA2CxF"}