@sensigo/realm-mcp 0.1.0

package/dist/tools/get-run-state.js

@@ -0,0 +1,63 @@
+// get-run-state tool — returns the current state summary of a run.
+import { z } from 'zod';
+import { JsonFileStore, WorkflowError, resolvePreExecutionAgentAction, } from '@sensigo/realm';
+/**
+ * Business logic for the get_run_state tool.
+ * Returns a structured summary of the run without the full evidence array.
+ */
+export async function handleGetRunState(args, stores) {
+    const runStore = stores?.runStore ?? new JsonFileStore();
+    const run = await runStore.get(args.run_id);
+    return {
+        run_id: run.id,
+        workflow_id: run.workflow_id,
+        run_phase: run.run_phase,
+        terminal_state: run.terminal_state,
+        completed_steps: run.completed_steps,
+        in_progress_steps: run.in_progress_steps,
+        failed_steps: run.failed_steps,
+        skipped_steps: run.skipped_steps,
+        pending_gate: run.pending_gate,
+        evidence_count: run.evidence.length,
+        last_step: run.evidence.at(-1)?.step_id ?? null,
+        created_at: run.created_at,
+        updated_at: run.updated_at,
+        params: run.params,
+    };
+}
+/** Registers the get_run_state MCP tool on the server. */
+export function registerGetRunState(server, opts) {
+    server.tool('get_run_state', 'Get the current state summary of a workflow run.', { run_id: z.string() }, async (args) => {
+        try {
+            const result = await handleGetRunState(args, opts);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            const agentAction = err instanceof WorkflowError ? resolvePreExecutionAgentAction(err) : 'report_to_user';
+            const message = err instanceof Error ? err.message : String(err);
+            const contextHint = err instanceof WorkflowError && err.code === 'STATE_RUN_NOT_FOUND'
+                ? `Run '${args.run_id}' not found.`
+                : `An error occurred while loading run state.`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            command: 'get_run_state',
+                            run_id: args.run_id,
+                            status: 'error',
+                            data: {},
+                            evidence: [],
+                            warnings: [],
+                            errors: [message],
+                            agent_action: agentAction,
+                            context_hint: contextHint,
+                            next_actions: [],
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=get-run-state.js.map

package/dist/tools/get-run-state.js.map

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

package/dist/tools/get-workflow-protocol.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type WorkflowProtocol } from '../protocol/generator.js';
+import type { HandleStores } from './list-workflows.js';
+/**
+ * Business logic for the get_workflow_protocol tool.
+ * Returns the full agent protocol for the specified workflow.
+ */
+export declare function handleGetWorkflowProtocol(args: {
+    workflow_id: string;
+}, stores?: HandleStores): Promise<WorkflowProtocol>;
+/** Registers the get_workflow_protocol MCP tool on the server. */
+export declare function registerGetWorkflowProtocol(server: McpServer, opts?: HandleStores): void;
+//# sourceMappingURL=get-workflow-protocol.d.ts.map

package/dist/tools/get-workflow-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-workflow-protocol.d.ts","sourceRoot":"","sources":["../../src/tools/get-workflow-protocol.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,EAC7B,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAI3B;AAED,kEAAkE;AAClE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAkBxF"}

package/dist/tools/get-workflow-protocol.js

@@ -0,0 +1,30 @@
+// get-workflow-protocol tool — returns the agent protocol for a workflow.
+import { z } from 'zod';
+import { JsonWorkflowStore, WorkflowError } from '@sensigo/realm';
+import { generateProtocol } from '../protocol/generator.js';
+/**
+ * Business logic for the get_workflow_protocol tool.
+ * Returns the full agent protocol for the specified workflow.
+ */
+export async function handleGetWorkflowProtocol(args, stores) {
+    const store = stores?.workflowStore ?? new JsonWorkflowStore();
+    const definition = await store.get(args.workflow_id);
+    return generateProtocol(definition);
+}
+/** Registers the get_workflow_protocol MCP tool on the server. */
+export function registerGetWorkflowProtocol(server, opts) {
+    server.tool('get_workflow_protocol', 'Get the full agent protocol briefing for a registered workflow.', { workflow_id: z.string() }, async (args) => {
+        try {
+            const result = await handleGetWorkflowProtocol(args, opts);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof WorkflowError ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=get-workflow-protocol.js.map

package/dist/tools/get-workflow-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-workflow-protocol.js","sourceRoot":"","sources":["../../src/tools/get-workflow-protocol.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAyB,MAAM,0BAA0B,CAAC;AAGnF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAA6B,EAC7B,MAAqB;IAErB,MAAM,KAAK,GAAG,MAAM,EAAE,aAAa,IAAI,IAAI,iBAAiB,EAAE,CAAC;IAC/D,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO,gBAAgB,CAAC,UAAU,CAAC,CAAC;AACtC,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,2BAA2B,CAAC,MAAiB,EAAE,IAAmB;IAChF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,iEAAiE,EACjE,EAAE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAC3B,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACzF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;gBAC/D,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/list-workflows.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonWorkflowStore } from '@sensigo/realm';
+export interface HandleStores {
+    workflowStore?: JsonWorkflowStore;
+}
+/**
+ * Business logic for the list_workflows tool.
+ * Returns a summary of all registered workflows.
+ */
+export declare function handleListWorkflows(stores?: HandleStores): Promise<{
+    workflows: Array<{
+        id: string;
+        name: string;
+        version: number;
+    }>;
+    hint: string;
+}>;
+/** Registers the list_workflows MCP tool on the server. */
+export declare function registerListWorkflows(server: McpServer, opts?: HandleStores): void;
+//# sourceMappingURL=list-workflows.d.ts.map

package/dist/tools/list-workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-workflows.d.ts","sourceRoot":"","sources":["../../src/tools/list-workflows.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAO5F;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAKlF"}

package/dist/tools/list-workflows.js

@@ -0,0 +1,21 @@
+import { JsonWorkflowStore } from '@sensigo/realm';
+/**
+ * Business logic for the list_workflows tool.
+ * Returns a summary of all registered workflows.
+ */
+export async function handleListWorkflows(stores) {
+    const store = stores?.workflowStore ?? new JsonWorkflowStore();
+    const workflows = await store.list();
+    return {
+        workflows: workflows.map((w) => ({ id: w.id, name: w.name, version: w.version })),
+        hint: 'Call get_workflow_protocol with a workflow_id before calling start_run. If no workflow matches your task, use create_workflow to define and start your own plan.',
+    };
+}
+/** Registers the list_workflows MCP tool on the server. */
+export function registerListWorkflows(server, opts) {
+    server.tool('list_workflows', 'List all registered Realm workflows.', async () => {
+        const result = await handleListWorkflows(opts);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=list-workflows.js.map

package/dist/tools/list-workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-workflows.js","sourceRoot":"","sources":["../../src/tools/list-workflows.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMnD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAqB;IAErB,MAAM,KAAK,GAAG,MAAM,EAAE,aAAa,IAAI,IAAI,iBAAiB,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACrC,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACjF,IAAI,EAAE,kKAAkK;KACzK,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,IAAmB;IAC1E,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,sCAAsC,EAAE,KAAK,IAAI,EAAE;QAC/E,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC/C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACzF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/start-run.d.ts

@@ -0,0 +1,26 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonWorkflowStore, JsonFileStore, type ResponseEnvelope, type TraceBufferStore, ExtensionRegistry } from '@sensigo/realm';
+export interface HandleRunStores {
+    runStore?: JsonFileStore;
+    workflowStore?: JsonWorkflowStore;
+    /** Extension registry for resolving service adapters and step handlers. */
+    registry?: ExtensionRegistry;
+    /** Resolved secrets for use by service adapters. */
+    secrets?: Record<string, string>;
+    /** Trace buffer store for incremental WAL-based trace ingestion (B-lite). */
+    traceBufferStore?: TraceBufferStore;
+}
+/**
+ * Business logic for the start_run tool.
+ * Creates a run and immediately chains through any leading auto steps.
+ */
+export declare function handleStartRun(args: {
+    workflow_id: string;
+    params?: Record<string, unknown>;
+}, stores?: HandleRunStores): Promise<ResponseEnvelope>;
+/** Registers the start_run MCP tool on the server. */
+export declare function registerStartRun(server: McpServer, opts?: {
+    registry?: import('@sensigo/realm').ExtensionRegistry;
+    secrets?: Record<string, string>;
+}): void;
+//# sourceMappingURL=start-run.d.ts.map

package/dist/tools/start-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-run.d.ts","sourceRoot":"","sources":["../../src/tools/start-run.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACL,iBAAiB,EACjB,aAAa,EAOb,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAKD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC/D,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAwC3B;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,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;CAClC,GACA,IAAI,CAqDN"}

package/dist/tools/start-run.js

@@ -0,0 +1,90 @@
+// start-run tool — creates a new run and chains through initial auto steps.
+import { z } from 'zod';
+import { JsonWorkflowStore, JsonFileStore, executeChain, buildNextActions, findEligibleSteps, WorkflowError, buildPreExecutionErrorEnvelope, } from '@sensigo/realm';
+// Fallback dispatcher for agent steps and auto steps without a registry entry.
+const passthroughDispatcher = async () => ({});
+/**
+ * Business logic for the start_run tool.
+ * Creates a run and immediately chains through any leading auto steps.
+ */
+export async function handleStartRun(args, stores) {
+    const workflowStore = stores?.workflowStore ?? new JsonWorkflowStore();
+    const runStore = stores?.runStore ?? new JsonFileStore();
+    const definition = await workflowStore.get(args.workflow_id);
+    const params = args.params ?? {};
+    const run = await runStore.create({
+        workflowId: definition.id,
+        workflowVersion: definition.version,
+        params,
+    });
+    const eligible = findEligibleSteps(definition, run);
+    const firstAutoStep = eligible.find((name) => definition.steps[name]?.execution === 'auto');
+    if (firstAutoStep !== undefined) {
+        const result = await executeChain(runStore, definition, {
+            runId: run.id,
+            command: firstAutoStep,
+            input: params,
+            dispatcher: passthroughDispatcher,
+            ...(stores?.registry !== undefined ? { registry: stores.registry } : {}),
+            ...(stores?.secrets !== undefined ? { secrets: stores.secrets } : {}),
+        });
+        return { ...result, run_id: run.id, data: {}, evidence: [] };
+    }
+    const nextActions = buildNextActions(definition, run);
+    return {
+        command: 'start_run',
+        run_id: run.id,
+        run_version: run.version,
+        status: 'ok',
+        data: {},
+        evidence: [],
+        warnings: [],
+        errors: [],
+        context_hint: `Run '${run.id}' created for workflow '${definition.id}'.`,
+        next_actions: nextActions,
+    };
+}
+/** Registers the start_run MCP tool on the server. */
+export function registerStartRun(server, opts) {
+    server.tool('start_run', 'Create a new workflow run and chain through initial auto steps.', {
+        workflow_id: z.string(),
+        params: z.record(z.unknown()).optional().default({}),
+    }, async (args) => {
+        try {
+            const result = await handleStartRun(args, opts);
+            // Override command to 'start_run': MCP callers invoked start_run, not
+            // the first auto step that executeChain may have executed.
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ...result, command: 'start_run' }, 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 '${args.workflow_id}' not found.`
+                : `An error occurred before the run could be started.`;
+            const envelope = buildPreExecutionErrorEnvelope('start_run', '', 0, workflowErr, contextHint);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(envelope, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=start-run.js.map

package/dist/tools/start-run.js.map

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

package/dist/tools/submit-human-response.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ResponseEnvelope } from '@sensigo/realm';
+import type { HandleRunStores } from './start-run.js';
+/**
+ * Business logic for the submit_human_response tool.
+ * Validates the gate_id and choice, then advances the run past the gate.
+ */
+export declare function handleSubmitHumanResponse(args: {
+    run_id: string;
+    gate_id: string;
+    choice: string;
+}, stores?: HandleRunStores): Promise<ResponseEnvelope>;
+/** Registers the submit_human_response MCP tool on the server. */
+export declare function registerSubmitHumanResponse(server: McpServer, opts?: HandleRunStores): void;
+//# sourceMappingURL=submit-human-response.d.ts.map

package/dist/tools/submit-human-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-human-response.d.ts","sourceRoot":"","sources":["../../src/tools/submit-human-response.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzD,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAW3B;AAED,kEAAkE;AAClE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAsD3F"}

package/dist/tools/submit-human-response.js

@@ -0,0 +1,63 @@
+// submit-human-response tool — advances a gate-waiting run with a human choice.
+import { z } from 'zod';
+import { JsonWorkflowStore, JsonFileStore, submitHumanResponse, WorkflowError, buildPreExecutionErrorEnvelope, } from '@sensigo/realm';
+/**
+ * Business logic for the submit_human_response tool.
+ * Validates the gate_id and choice, then advances the run past the gate.
+ */
+export async function handleSubmitHumanResponse(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);
+    return submitHumanResponse(runStore, definition, {
+        runId: args.run_id,
+        gateId: args.gate_id,
+        choice: args.choice,
+    });
+}
+/** Registers the submit_human_response MCP tool on the server. */
+export function registerSubmitHumanResponse(server, opts) {
+    server.tool('submit_human_response', "Advance a gate-waiting run by submitting the human's choice.", {
+        run_id: z.string(),
+        gate_id: z.string(),
+        choice: z.string(),
+    }, async (args) => {
+        try {
+            const result = await handleSubmitHumanResponse(args, opts);
+            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 gate response could be submitted.`;
+            const envelope = buildPreExecutionErrorEnvelope('submit_human_response', args.run_id, 0, workflowErr, contextHint);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(envelope, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=submit-human-response.js.map

package/dist/tools/submit-human-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-human-response.js","sourceRoot":"","sources":["../../src/tools/submit-human-response.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,8BAA8B,GAE/B,MAAM,gBAAgB,CAAC;AAGxB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAAyD,EACzD,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;IAE5D,OAAO,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE;QAC/C,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,MAAM,EAAE,IAAI,CAAC,OAAO;QACpB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,2BAA2B,CAAC,MAAiB,EAAE,IAAsB;IACnF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,8DAA8D,EAC9D;QACE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;KACnB,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3D,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;qBACrE;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,WAAW,GACf,GAAG,YAAY,aAAa;gBAC1B,CAAC,CAAC,GAAG;gBACL,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;oBAClE,IAAI,EAAE,iBAAiB;oBACvB,QAAQ,EAAE,QAAQ;oBAClB,WAAW,EAAE,MAAM;oBACnB,SAAS,EAAE,KAAK;iBACjB,CAAC,CAAC;YACT,MAAM,WAAW,GACf,WAAW,CAAC,IAAI,KAAK,0BAA0B;gBAC7C,CAAC,CAAC,gCAAgC,IAAI,CAAC,MAAM,cAAc;gBAC3D,CAAC,CAAC,WAAW,CAAC,IAAI,KAAK,qBAAqB;oBAC1C,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,cAAc;oBACnC,CAAC,CAAC,4DAA4D,CAAC;YACrE,MAAM,QAAQ,GAAqB,8BAA8B,CAC/D,uBAAuB,EACvB,IAAI,CAAC,MAAM,EACX,CAAC,EACD,WAAW,EACX,WAAW,CACZ,CAAC;YACF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;qBACxC;iBACF;aACF,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sensigo/realm-mcp",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "MCP server for Realm — exposes 7 tools for AI agent connections over stdio or HTTP.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sensigo-hq/realm.git"
+  },
+  "homepage": "https://github.com/sensigo-hq/realm#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "agent-workflow",
+    "workflow",
+    "typescript"
+  ],
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "realm-mcp": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@sensigo/realm": "^0.1.0",
+    "zod": "^3.25.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}