@sensigo/realm-mcp 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @sensigo/realm-mcp
+
+`@sensigo/realm-mcp` — the Realm MCP server. Exposes 7 workflow tools over stdio or HTTP for AI agent connections (VS Code Copilot, Cursor, Claude, and any MCP-compatible agent).
+
+## Installation
+
+```
+# Standalone binary (for AI agent MCP config)
+npm install -g @sensigo/realm-mcp
+
+# Embedded library (for custom application integration)
+npm install @sensigo/realm-mcp
+```
+
+## Usage — Standalone MCP server
+
+Add `realm-mcp` to your MCP client configuration (VS Code, Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "realm": {
+      "command": "realm-mcp"
+    }
+  }
+}
+```
+
+Requires workflows to be registered first via `realm workflow register`.
+
+## Usage — Embedded MCP server
+
+Create and connect a Realm MCP server inside your own application using any MCP-compatible transport.
+
+```ts
+import { createRealmMcpServer } from '@sensigo/realm-mcp';
+// StdioServerTransport comes from the MCP SDK, not from @sensigo/realm-mcp
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = createRealmMcpServer(); // options?: RealmMcpServerOptions
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## API Reference
+
+| Symbol                             | Description                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `createRealmMcpServer(options?)`   | Creates the MCP server with all 7 tools pre-registered. Returns `McpServer`.    |
+| `createDefaultRegistry()`          | Returns an `ExtensionRegistry` pre-populated with built-in adapters.            |
+| `generateProtocol(workflow)`       | Generates a structured protocol description for a workflow.                     |
+| `RealmMcpServerOptions`            | Type — optional config: `registry?`, `secrets?`, `workflowStore?`, `runStore?`. |
+| `WorkflowProtocol`, `ProtocolStep` | Types — output shape of `generateProtocol`.                                     |
+
+## MCP tools exposed
+
+- `list_workflows` — list registered workflows
+- `get_workflow_protocol` — get step-by-step protocol for a workflow
+- `start_run` — start a new workflow run
+- `execute_step` — submit agent output for a step and advance the run
+- `submit_human_response` — resolve a human gate
+- `get_run_state` — check current run state
+- `create_workflow` — dynamically register and start a workflow in one call
+
+## Full documentation
+
+Full documentation: https://github.com/sensigo-hq/realm

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createRealmMcpServer, createDefaultRegistry } from './server.js';
+export type { RealmMcpServerOptions } from './server.js';
+export { generateProtocol } from './protocol/generator.js';
+export type { WorkflowProtocol, ProtocolStep } from './protocol/generator.js';
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC9E,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// @sensigo/realm-mcp — MCP server for AI agent connections
+export { createRealmMcpServer, createDefaultRegistry } from './server.js';
+export { generateProtocol } from './protocol/generator.js';
+export const VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/json-trace-buffer-store.d.ts

@@ -0,0 +1,17 @@
+import { type TraceBufferStore, type BufferedEntry, type AppendResult } from '@sensigo/realm';
+import type { AgentTraceEntry } from '@sensigo/realm';
+/**
+ * File-based TraceBufferStore that persists WAL entries to JSONL files on disk.
+ * WAL file path: <runsDir>/trace-buffer-<runId>-<base64url(stepId)>.jsonl
+ */
+export declare class JsonTraceBufferStore implements TraceBufferStore {
+    private readonly runsDir;
+    constructor(runsDir: string);
+    private walPath;
+    private readWal;
+    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    read(runId: string, stepId: string): Promise<BufferedEntry[]>;
+    delete(runId: string, stepId: string): Promise<void>;
+    deleteAllForRun(runId: string): Promise<void>;
+}
+//# sourceMappingURL=json-trace-buffer-store.d.ts.map

package/dist/json-trace-buffer-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-trace-buffer-store.d.ts","sourceRoot":"","sources":["../src/json-trace-buffer-store.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EAMlB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAStD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,MAAM;IAI3B,OAAO,CAAC,OAAO;YAKD,OAAO;IAqBf,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IA6ExF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAcpD"}

package/dist/json-trace-buffer-store.js

@@ -0,0 +1,128 @@
+// json-trace-buffer-store.ts — File-based TraceBufferStore using JSONL WAL files.
+import { existsSync } from 'node:fs';
+import { readFile, appendFile, unlink, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import lockfile from 'proper-lockfile';
+import { normalizeEntryForBuffer, BUFFER_LIMIT_COUNT, BUFFER_LIMIT_BYTES, FINAL_LIMIT_ENTRIES, FINAL_LIMIT_BYTES, } from '@sensigo/realm';
+import { WorkflowError } from '@sensigo/realm';
+/**
+ * File-based TraceBufferStore that persists WAL entries to JSONL files on disk.
+ * WAL file path: <runsDir>/trace-buffer-<runId>-<base64url(stepId)>.jsonl
+ */
+export class JsonTraceBufferStore {
+    runsDir;
+    constructor(runsDir) {
+        this.runsDir = runsDir;
+    }
+    walPath(runId, stepId) {
+        const safeStepId = Buffer.from(stepId).toString('base64url');
+        return join(this.runsDir, `trace-buffer-${runId}-${safeStepId}.jsonl`);
+    }
+    async readWal(walPath) {
+        if (!existsSync(walPath)) {
+            return { count: 0, bytes: 0, lines: [] };
+        }
+        try {
+            const content = await readFile(walPath, 'utf8');
+            const lines = content
+                .split('\n')
+                .filter((l) => l.trim().length > 0)
+                .map((l) => JSON.parse(l));
+            const count = lines.reduce((acc, l) => acc + l.entries.length, 0);
+            const bytes = Buffer.byteLength(content);
+            return { count, bytes, lines };
+        }
+        catch {
+            // Treat corrupted WAL as empty.
+            return { count: 0, bytes: 0, lines: [] };
+        }
+    }
+    async append(runId, stepId, entries) {
+        const walPath = this.walPath(runId, stepId);
+        if (entries.length === 0) {
+            const { count, bytes } = await this.readWal(walPath);
+            return {
+                buffer_count: count,
+                buffer_bytes: bytes,
+                limit_count: BUFFER_LIMIT_COUNT,
+                limit_bytes: BUFFER_LIMIT_BYTES,
+                final_limit_entries: FINAL_LIMIT_ENTRIES,
+                final_limit_bytes: FINAL_LIMIT_BYTES,
+            };
+        }
+        // Acquire lock (realpath: false because file may not yet exist).
+        // Create a placeholder file if needed so proper-lockfile has a target.
+        if (!existsSync(walPath)) {
+            await appendFile(walPath, '');
+        }
+        let release;
+        try {
+            release = await lockfile.lock(walPath, { retries: 10, stale: 5000, realpath: false });
+            const { count: existingCount, bytes: existingBytes } = await this.readWal(walPath);
+            const normalized = entries
+                .map((e) => normalizeEntryForBuffer(e))
+                .filter((e) => e !== null);
+            if (normalized.length === 0) {
+                return {
+                    buffer_count: existingCount,
+                    buffer_bytes: existingBytes,
+                    limit_count: BUFFER_LIMIT_COUNT,
+                    limit_bytes: BUFFER_LIMIT_BYTES,
+                    final_limit_entries: FINAL_LIMIT_ENTRIES,
+                    final_limit_bytes: FINAL_LIMIT_BYTES,
+                };
+            }
+            const newLine = JSON.stringify({ ts: Date.now(), entries: normalized });
+            const newBytes = Buffer.byteLength(newLine + '\n');
+            if (existingCount + normalized.length > BUFFER_LIMIT_COUNT ||
+                existingBytes + newBytes > BUFFER_LIMIT_BYTES) {
+                throw new WorkflowError('Trace buffer full for step', {
+                    code: 'BUFFER_FULL',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                    details: { buffer_count: existingCount, buffer_bytes: existingBytes },
+                });
+            }
+            await appendFile(walPath, newLine + '\n', 'utf8');
+            const updatedCount = existingCount + normalized.length;
+            const updatedBytes = existingBytes + newBytes;
+            return {
+                buffer_count: updatedCount,
+                buffer_bytes: updatedBytes,
+                limit_count: BUFFER_LIMIT_COUNT,
+                limit_bytes: BUFFER_LIMIT_BYTES,
+                final_limit_entries: FINAL_LIMIT_ENTRIES,
+                final_limit_bytes: FINAL_LIMIT_BYTES,
+            };
+        }
+        finally {
+            if (release !== undefined) {
+                await release();
+            }
+        }
+    }
+    async read(runId, stepId) {
+        const walPath = this.walPath(runId, stepId);
+        const { lines } = await this.readWal(walPath);
+        return lines.flatMap((line) => line.entries.map((entry) => ({ ...entry, _internalTs: line.ts })));
+    }
+    async delete(runId, stepId) {
+        const walPath = this.walPath(runId, stepId);
+        await unlink(walPath).catch(() => { });
+    }
+    async deleteAllForRun(runId) {
+        const prefix = `trace-buffer-${runId}-`;
+        let files;
+        try {
+            files = await readdir(this.runsDir);
+        }
+        catch {
+            return;
+        }
+        await Promise.all(files
+            .filter((f) => f.startsWith(prefix) && f.endsWith('.jsonl'))
+            .map((f) => unlink(join(this.runsDir, f)).catch(() => { })));
+    }
+}
+//# sourceMappingURL=json-trace-buffer-store.js.map

package/dist/json-trace-buffer-store.js.map

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

package/dist/protocol/generator.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowDefinition, JsonSchema } from '@sensigo/realm';
+export interface ProtocolStepGate {
+    choices: string[];
+}
+export interface ProtocolStep {
+    id: string;
+    description: string;
+    execution: string;
+    /** Plain-English description of the agent's role at this step. */
+    agent_involvement: string;
+    input_schema?: JsonSchema;
+    /** Step-level instructions for the agent, if defined. */
+    instructions?: string;
+    /** Present when the step may open a human gate. */
+    possible_gate?: ProtocolStepGate;
+    /** Step IDs this step depends on before it becomes eligible. */
+    depends_on?: string[];
+    /** Specialist profile instructions for the agent at this step. Present when the step
+     *  declares agent_profile and the profile was resolved at register time. */
+    agent_profile_instructions?: string;
+}
+export interface WorkflowProtocol {
+    workflow_id: string;
+    name: string;
+    params_schema?: JsonSchema;
+    steps: ProtocolStep[];
+    /** e.g. "2 of 4 steps require agent action. 2 are handled automatically." */
+    agent_steps_summary: string;
+    rules: string[];
+    error_handling: Record<string, string>;
+    quick_start: string;
+}
+/**
+ * Generates the full agent protocol briefing from a WorkflowDefinition.
+ */
+export declare function generateProtocol(definition: WorkflowDefinition): WorkflowProtocol;
+//# sourceMappingURL=generator.d.ts.map

package/dist/protocol/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/protocol/generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;gFAC4E;IAC5E,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAuBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,GAAG,gBAAgB,CA+FjF"}

package/dist/protocol/generator.js

@@ -0,0 +1,99 @@
+const DEFAULT_RULES = [
+    'Follow the next_action instruction in each response exactly.',
+    "When you receive status 'confirm_required', read gate.agent_hint for instructions, present gate.display to the user verbatim, wait for their response, then call submit_human_response with their choice and the gate_id.",
+    'Do NOT auto-confirm any human gate. The user must decide.',
+    'Do NOT ask the user for permission between steps unless the system tells you to.',
+];
+const ERROR_HANDLING = {
+    provide_input: 'The engine rejected your input. Read the error details — they tell you exactly what was wrong. Fix the input and call the step again.',
+    report_to_user: 'Something failed that you cannot fix automatically. Show the error message to the user and wait for their guidance.',
+    resolve_precondition: 'A prerequisite step has not completed. The error includes which precondition failed and what step to call. Follow the suggestion.',
+    stop: 'A critical error occurred. Report it to the user and do not attempt any further steps.',
+    wait_for_human: 'An external service is unavailable and cannot be retried automatically (e.g. network unreachable, upstream server error). Show the error to the user and wait for them to confirm the issue is resolved — the run cannot continue until the external dependency is back.',
+    wait_and_proceed: 'The upstream service returned a rate-limit response. retry_after in the envelope gives the number of seconds to wait. After that delay, follow next_actions without human involvement — the step has already failed; if a recovery branch exists it will appear in next_actions. This action only appears when engine-level retry is not configured for the step; when retry is configured, the engine retries internally and surfaces STEP_RETRY_EXHAUSTED (report_to_user) on exhaustion.',
+};
+/**
+ * Generates the full agent protocol briefing from a WorkflowDefinition.
+ */
+export function generateProtocol(definition) {
+    const steps = [];
+    let agentStepCount = 0;
+    let autoStepCount = 0;
+    for (const [id, step] of Object.entries(definition.steps)) {
+        const hasGate = step.trust === 'human_confirmed' || step.trust === 'human_reviewed';
+        let agent_involvement;
+        let possible_gate;
+        if (step.execution === 'auto' && !hasGate) {
+            agent_involvement = 'none — engine handles this automatically';
+            autoStepCount++;
+        }
+        else if (step.execution === 'auto' && hasGate) {
+            agent_involvement =
+                'YOU will receive `status: confirm_required` after this step runs — the engine executes it automatically, then opens a gate. Read `gate.agent_hint` for presentation instructions, present `gate.display` to the user verbatim, collect their choice from `gate.response_spec.choices`, and call `submit_human_response`.';
+            possible_gate = { choices: ['approve', 'reject'] };
+            autoStepCount++;
+        }
+        else if (step.execution === 'agent' && !hasGate) {
+            agent_involvement = `YOU execute this step. Call execute_step with command '${id}' and the required params.`;
+            // If an immediate downstream auto+gate step depends only on this step, warn the
+            // agent that they will receive confirm_required rather than ok after submitting.
+            const immediateGateStep = Object.entries(definition.steps).find(([, s]) => s.execution === 'auto' &&
+                (s.trust === 'human_confirmed' || s.trust === 'human_reviewed') &&
+                Array.isArray(s.depends_on) &&
+                s.depends_on.length === 1 &&
+                s.depends_on[0] === id);
+            if (immediateGateStep !== undefined) {
+                agent_involvement += ` After you submit, you will receive status: confirm_required directly in response to this call — the engine runs '${immediateGateStep[0]}' automatically before returning.`;
+            }
+            agentStepCount++;
+        }
+        else {
+            // execution === 'agent' with gate
+            agent_involvement = `YOU execute this step. Call execute_step with command '${id}'. The engine will run your dispatcher, then pause for human confirmation of your output.`;
+            possible_gate = { choices: ['approve', 'reject'] };
+            agentStepCount++;
+        }
+        const protocolStep = {
+            id,
+            description: step.description,
+            execution: step.execution,
+            agent_involvement,
+        };
+        if (step.input_schema !== undefined) {
+            protocolStep.input_schema = step.input_schema;
+        }
+        if (step.instructions !== undefined) {
+            protocolStep.instructions = step.instructions;
+        }
+        if (possible_gate !== undefined) {
+            protocolStep.possible_gate = possible_gate;
+        }
+        if (step.depends_on !== undefined && step.depends_on.length > 0) {
+            protocolStep.depends_on = step.depends_on;
+        }
+        const profile = step.agent_profile;
+        if (profile !== undefined && definition.resolved_profiles?.[profile] !== undefined) {
+            protocolStep.agent_profile_instructions = definition.resolved_profiles[profile].content;
+        }
+        steps.push(protocolStep);
+    }
+    const totalSteps = steps.length;
+    const agent_steps_summary = `${agentStepCount} of ${totalSteps} steps require agent action. ${autoStepCount} are handled automatically.`;
+    const rules = definition.protocol?.rules ?? DEFAULT_RULES;
+    const quick_start = definition.protocol?.quick_start ??
+        `Call start_run with workflow_id '${definition.id}'. ${agentStepCount > 0 ? `The engine will run auto steps automatically and return control at the first step requiring agent action.` : `The engine handles all steps automatically.`} Follow the next_action in each response until the workflow completes.`;
+    const protocol = {
+        workflow_id: definition.id,
+        name: definition.name,
+        steps,
+        agent_steps_summary,
+        rules,
+        error_handling: ERROR_HANDLING,
+        quick_start,
+    };
+    if (definition.params_schema !== undefined) {
+        protocol.params_schema = definition.params_schema;
+    }
+    return protocol;
+}
+//# sourceMappingURL=generator.js.map

package/dist/protocol/generator.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ExtensionRegistry, JsonWorkflowStore, JsonFileStore, createDefaultRegistry } from '@sensigo/realm';
+export interface RealmMcpServerOptions {
+    /** Extension registry for resolving service adapters and step handlers at runtime. */
+    registry?: ExtensionRegistry;
+    /** Resolved secrets to pass to adapter configs (e.g. API tokens). */
+    secrets?: Record<string, string>;
+    /** Pre-populated workflow store. When provided, tools use this instead of creating
+     *  a new JsonWorkflowStore() pointing at ~/.realm/workflows/. */
+    workflowStore?: JsonWorkflowStore;
+    /** Run store. When provided, tools use this instead of creating a new JsonFileStore(). */
+    runStore?: JsonFileStore;
+}
+/**
+ * Returns an ExtensionRegistry pre-populated with Realm's built-in adapters.
+ * `FileSystemAdapter` is registered under the name `'filesystem'`.
+ *
+ * Use this as a starting point when you need to add your own handlers or adapters on top:
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * registry.register('handler', 'my_handler', myHandler);
+ * const server = createRealmMcpServer({ workflowStore, registry });
+ * ```
+ *
+ * When no registry is passed to `createRealmMcpServer`, the engine uses built-in adapters
+ * automatically — you only need this if you are adding custom extensions.
+ */
+export { createDefaultRegistry };
+/**
+ * Creates and configures the Realm MCP server with all 7 workflow tools.
+ *
+ * When no `registry` is provided, `FileSystemAdapter` is pre-registered automatically
+ * under the name `filesystem`. Pass a custom `registry` to add your own handlers and
+ * adapters — when you do, include `FileSystemAdapter` explicitly if your workflows use it,
+ * or start from `createDefaultRegistry()` and add your extensions on top.
+ */
+export declare function createRealmMcpServer(options?: RealmMcpServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAWxB,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;qEACiE;IACjE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,SAAS,CA+B/E"}

package/dist/server.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// realm-mcp — MCP server exposing the Realm workflow engine to AI agents.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { JsonFileStore, createDefaultRegistry, } from '@sensigo/realm';
+import { JsonTraceBufferStore } from './json-trace-buffer-store.js';
+import { registerListWorkflows } from './tools/list-workflows.js';
+import { registerGetWorkflowProtocol } from './tools/get-workflow-protocol.js';
+import { registerStartRun } from './tools/start-run.js';
+import { registerExecuteStep } from './tools/execute-step.js';
+import { registerSubmitHumanResponse } from './tools/submit-human-response.js';
+import { registerGetRunState } from './tools/get-run-state.js';
+import { registerCreateWorkflow } from './tools/create-workflow.js';
+import { registerAppendTrace } from './tools/append-trace.js';
+/**
+ * Returns an ExtensionRegistry pre-populated with Realm's built-in adapters.
+ * `FileSystemAdapter` is registered under the name `'filesystem'`.
+ *
+ * Use this as a starting point when you need to add your own handlers or adapters on top:
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * registry.register('handler', 'my_handler', myHandler);
+ * const server = createRealmMcpServer({ workflowStore, registry });
+ * ```
+ *
+ * When no registry is passed to `createRealmMcpServer`, the engine uses built-in adapters
+ * automatically — you only need this if you are adding custom extensions.
+ */
+export { createDefaultRegistry };
+/**
+ * Creates and configures the Realm MCP server with all 7 workflow tools.
+ *
+ * When no `registry` is provided, `FileSystemAdapter` is pre-registered automatically
+ * under the name `filesystem`. Pass a custom `registry` to add your own handlers and
+ * adapters — when you do, include `FileSystemAdapter` explicitly if your workflows use it,
+ * or start from `createDefaultRegistry()` and add your extensions on top.
+ */
+export function createRealmMcpServer(options) {
+    const server = new McpServer({
+        name: 'realm',
+        version: '0.1.0',
+    });
+    // When no registry is provided, use the default registry that pre-registers built-in
+    // adapters. When a registry is provided, the caller is responsible for its contents.
+    const effectiveRegistry = options?.registry ?? createDefaultRegistry();
+    const effectiveOptions = { ...options, registry: effectiveRegistry };
+    // Shared trace buffer store: one instance used by both append_trace and execute_step so
+    // WAL entries written by append_trace are visible when execute_step finalizes the step.
+    const effectiveRunStore = options?.runStore ?? new JsonFileStore();
+    const traceBufferStore = new JsonTraceBufferStore(effectiveRunStore.runsDirPath);
+    registerListWorkflows(server, effectiveOptions);
+    registerGetWorkflowProtocol(server, effectiveOptions);
+    registerStartRun(server, effectiveOptions);
+    registerExecuteStep(server, { ...effectiveOptions, traceBufferStore });
+    registerSubmitHumanResponse(server, effectiveOptions);
+    registerGetRunState(server, effectiveOptions);
+    registerCreateWorkflow(server, effectiveOptions);
+    registerAppendTrace(server, {
+        runStore: effectiveRunStore,
+        ...(options?.workflowStore !== undefined ? { workflowStore: options.workflowStore } : {}),
+        traceBufferStore,
+    });
+    return server;
+}
+// Entry point: start the MCP server on stdio when run directly.
+if (process.argv[1] !== undefined &&
+    import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+    const server = createRealmMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA,0EAA0E;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAGL,aAAa,EACb,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAc9D;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA+B;IAClE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,qFAAqF;IACrF,qFAAqF;IACrF,MAAM,iBAAiB,GAAG,OAAO,EAAE,QAAQ,IAAI,qBAAqB,EAAE,CAAC;IAEvE,MAAM,gBAAgB,GAA0B,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAE5F,wFAAwF;IACxF,wFAAwF;IACxF,MAAM,iBAAiB,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI,aAAa,EAAE,CAAC;IACnE,MAAM,gBAAgB,GAAG,IAAI,oBAAoB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAEjF,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChD,2BAA2B,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACtD,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,mBAAmB,CAAC,MAAM,EAAE,EAAE,GAAG,gBAAgB,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACvE,2BAA2B,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACtD,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD,mBAAmB,CAAC,MAAM,EAAE;QAC1B,QAAQ,EAAE,iBAAiB;QAC3B,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,gBAAgB;KACjB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gEAAgE;AAChE,IACE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;IAC7B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAC7D,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools/append-trace.d.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonWorkflowStore, JsonFileStore, type AppendResult, type TraceBufferStore, type AgentTraceEntry } from '@sensigo/realm';
+export interface HandleAppendTraceStores {
+    runStore?: JsonFileStore;
+    workflowStore?: JsonWorkflowStore;
+    traceBufferStore?: TraceBufferStore;
+}
+export type AppendTraceOkResult = {
+    status: 'ok';
+} & AppendResult;
+/**
+ * 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 declare function handleAppendTrace(args: {
+    run_id: string;
+    step_id: string;
+    entries: AgentTraceEntry[];
+}, stores?: HandleAppendTraceStores): Promise<AppendTraceOkResult>;
+/** Registers the append_trace MCP tool on the server. */
+export declare function registerAppendTrace(server: McpServer, opts?: {
+    runStore?: JsonFileStore;
+    workflowStore?: JsonWorkflowStore;
+    traceBufferStore?: TraceBufferStore;
+}): void;
+//# sourceMappingURL=append-trace.d.ts.map

package/dist/tools/append-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-trace.d.ts","sourceRoot":"","sources":["../../src/tools/append-trace.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACL,iBAAiB,EACjB,aAAa,EAGb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,MAAM,mBAAmB,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,EACD,MAAM,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CA+E9B;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,IAAI,CAAC,EAAE;IACL,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC,GACA,IAAI,CAyDN"}