@sensigo/realm-cli 0.1.0

package/dist/agent/gate-intent-interpreter.d.ts

@@ -0,0 +1,29 @@
+import type { LlmProvider } from './llm-provider.js';
+/** Structured output from LLM interpretation of a gate reply. */
+export interface GateInterpretation {
+    /** One of the allowed gate choices, or 'unclear' when intent cannot be determined. */
+    choice: string | 'unclear';
+    /** Confidence in the interpretation. */
+    confidence: 'high' | 'medium' | 'low';
+    /** Brief explanation of the interpretation reasoning. */
+    reason: string;
+}
+export interface InterpretGateIntentOptions {
+    /** Raw message text from the Slack thread. */
+    userMessage: string;
+    /** The gate's valid choices (e.g. ['send', 'reject']). */
+    allowedChoices: string[];
+    /** Name of the gate step for context. */
+    gateStepName: string;
+    /** Optional headline from the gate preview — provides brief context without overwhelming the prompt. */
+    previewSummary?: string;
+    /** LLM provider to use — same instance configured for the agent run. */
+    llmClient: LlmProvider;
+}
+/**
+ * Asks the LLM to interpret a human's Slack reply as one of the allowed gate choices.
+ * Returns a structured interpretation with confidence level and reasoning.
+ * The LLM is solely responsible for understanding intent — no hardcoded synonyms.
+ */
+export declare function interpretGateIntent(options: InterpretGateIntentOptions): Promise<GateInterpretation>;
+//# sourceMappingURL=gate-intent-interpreter.d.ts.map

package/dist/agent/gate-intent-interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-intent-interpreter.d.ts","sourceRoot":"","sources":["../../src/agent/gate-intent-interpreter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,wCAAwC;IACxC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,SAAS,EAAE,WAAW,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAiC7B"}

package/dist/agent/gate-intent-interpreter.js

@@ -0,0 +1,33 @@
+/**
+ * Asks the LLM to interpret a human's Slack reply as one of the allowed gate choices.
+ * Returns a structured interpretation with confidence level and reasoning.
+ * The LLM is solely responsible for understanding intent — no hardcoded synonyms.
+ */
+export async function interpretGateIntent(options) {
+    const { userMessage, allowedChoices, gateStepName, previewSummary, llmClient } = options;
+    const contextLine = previewSummary !== undefined ? `\nGate context: ${previewSummary}` : '';
+    const choiceList = allowedChoices.map((c) => `"${c}"`).join(', ');
+    const prompt = `You are interpreting a Slack message from a human reviewer responding to a workflow gate.\n` +
+        `Gate step: "${gateStepName}"${contextLine}\n` +
+        `Allowed choices: ${allowedChoices.join(', ')}\n\n` +
+        `Message: "${userMessage}"\n\n` +
+        `Determine which choice the user intends. Return JSON with:\n` +
+        `- "choice": one of [${choiceList}, "unclear"]\n` +
+        `- "confidence": "high", "medium", or "low"\n` +
+        `- "reason": brief explanation of your interpretation`;
+    const schema = {
+        type: 'object',
+        required: ['choice', 'confidence', 'reason'],
+        properties: {
+            choice: { type: 'string' },
+            confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+            reason: { type: 'string' },
+        },
+    };
+    const result = await llmClient.callStep(prompt, schema);
+    const choice = result['choice'] ?? 'unclear';
+    const confidence = result['confidence'] ?? 'low';
+    const reason = result['reason'] ?? '';
+    return { choice, confidence, reason };
+}
+//# sourceMappingURL=gate-intent-interpreter.js.map

package/dist/agent/gate-intent-interpreter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-intent-interpreter.js","sourceRoot":"","sources":["../../src/agent/gate-intent-interpreter.ts"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC;IAEnC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEzF,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5F,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAElE,MAAM,MAAM,GACV,6FAA6F;QAC7F,eAAe,YAAY,IAAI,WAAW,IAAI;QAC9C,oBAAoB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;QACnD,aAAa,WAAW,OAAO;QAC/B,8DAA8D;QAC9D,uBAAuB,UAAU,gBAAgB;QACjD,8CAA8C;QAC9C,sDAAsD,CAAC;IAEzD,MAAM,MAAM,GAAG;QACb,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC;QAC5C,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE;YAC/D,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC3B;KACF,CAAC;IAEF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExD,MAAM,MAAM,GAAI,MAAM,CAAC,QAAQ,CAAwB,IAAI,SAAS,CAAC;IACrE,MAAM,UAAU,GAAI,MAAM,CAAC,YAAY,CAA2C,IAAI,KAAK,CAAC;IAC5F,MAAM,MAAM,GAAI,MAAM,CAAC,QAAQ,CAAwB,IAAI,EAAE,CAAC;IAE9D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { LlmProvider, ToolCapableLlmProvider } from './providers/llm-provider.js';
+export type { ProviderCapabilities } from './providers/llm-provider.js';
+export type { ToolExecutor, StepWithToolsResult, ToolCallRecord, McpServerConfig, } from './mcp/mcp-extensions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAClF,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,yBAAyB,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,4 @@
+// Public agent interface surface for @sensigo/realm-cli/agent.
+// Custom provider authors implement LlmProvider or ToolCapableLlmProvider against these types.
+export { LlmProvider, ToolCapableLlmProvider } from './providers/llm-provider.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+FAA+F;AAC/F,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/agent/llm-provider.d.ts

@@ -0,0 +1,46 @@
+import type { ToolDefinition, ToolExecutor, StepWithToolsResult } from './mcp-types.js';
+/**
+ * Describes the optional feature set that an LLM provider supports.
+ * Custom providers can override {@link LlmProvider.capabilities} to declare
+ * features beyond the universal baseline.
+ */
+export interface ProviderCapabilities {
+    /**
+     * Whether this provider sends `response_format: { type: 'json_object' }` in API requests.
+     * When false, JSON compliance is enforced through system prompt instruction and retry only.
+     * This is the universal baseline — all providers work without json_object mode.
+     */
+    jsonMode: boolean;
+}
+/**
+ * Abstract base class for LLM providers used by realm agent.
+ * Extend this class to implement a custom provider.
+ */
+export declare abstract class LlmProvider {
+    /** Call the LLM with a step prompt and return a JSON object. */
+    abstract callStep(prompt: string, inputSchema?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Returns the capability set for this provider instance. */
+    capabilities(): ProviderCapabilities;
+}
+/**
+ * Extended abstract class for providers that support the agentic tool-calling loop.
+ * Extend this class if your provider can drive tool-enabled workflow steps.
+ */
+export declare abstract class ToolCapableLlmProvider extends LlmProvider {
+    abstract callStepWithTools(prompt: string, tools: ToolDefinition[], executor: ToolExecutor, options: {
+        inputSchema?: Record<string, unknown>;
+        maxToolCalls?: number;
+        toolTimeoutMs?: number;
+    }): Promise<StepWithToolsResult>;
+}
+/**
+ * Returns true if the provider supports the agentic tool-calling loop.
+ */
+export declare function isToolCapable(provider: LlmProvider): provider is ToolCapableLlmProvider;
+export type ProviderName = 'openai' | 'anthropic';
+/**
+ * Resolves the correct LLM provider from environment and CLI flags.
+ * Throws if no API key is found or the specified package is not installed.
+ */
+export declare function resolveProvider(providerFlag: ProviderName | undefined, modelFlag: string | undefined, baseUrlFlag?: string): Promise<LlmProvider>;
+//# sourceMappingURL=llm-provider.d.ts.map

package/dist/agent/llm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider.d.ts","sourceRoot":"","sources":["../../src/agent/llm-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAExF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,8BAAsB,WAAW;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,6DAA6D;IAC7D,YAAY,IAAI,oBAAoB;CAGrC;AAED;;;GAGG;AACH,8BAAsB,sBAAuB,SAAQ,WAAW;IAC9D,QAAQ,CAAC,iBAAiB,CACxB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,mBAAmB,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,sBAAsB,CAEvF;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CAkCtB"}

package/dist/agent/llm-provider.js

@@ -0,0 +1,55 @@
+/**
+ * Abstract base class for LLM providers used by realm agent.
+ * Extend this class to implement a custom provider.
+ */
+export class LlmProvider {
+    /** Returns the capability set for this provider instance. */
+    capabilities() {
+        return { jsonMode: false };
+    }
+}
+/**
+ * Extended abstract class for providers that support the agentic tool-calling loop.
+ * Extend this class if your provider can drive tool-enabled workflow steps.
+ */
+export class ToolCapableLlmProvider extends LlmProvider {
+}
+/**
+ * Returns true if the provider supports the agentic tool-calling loop.
+ */
+export function isToolCapable(provider) {
+    return provider instanceof ToolCapableLlmProvider;
+}
+/**
+ * Resolves the correct LLM provider from environment and CLI flags.
+ * Throws if no API key is found or the specified package is not installed.
+ */
+export async function resolveProvider(providerFlag, modelFlag, baseUrlFlag) {
+    const hasOpenAI = process.env['OPENAI_API_KEY'] !== undefined;
+    const hasAnthropic = process.env['ANTHROPIC_API_KEY'] !== undefined;
+    if (!hasOpenAI && !hasAnthropic) {
+        throw new Error('realm agent requires an LLM API key. Set OPENAI_API_KEY or ANTHROPIC_API_KEY.');
+    }
+    const provider = providerFlag ?? (hasOpenAI ? 'openai' : 'anthropic');
+    if (baseUrlFlag !== undefined && provider === 'anthropic') {
+        throw new Error('--base-url is only supported with --provider openai (or OpenAI-compatible endpoints). ' +
+            'For Anthropic, configure the endpoint via the ANTHROPIC_BASE_URL environment variable.');
+    }
+    if (provider === 'openai') {
+        // Match o1, o1-mini, o1-preview, o3, o3-mini, o4-mini, etc. The user has
+        // explicitly declared the model name, so matching on name is the correct
+        // signal here — not an internal allowlist.
+        const REASONING_MODELS = /^o[1-4](-|$)/i;
+        if (modelFlag !== undefined && REASONING_MODELS.test(modelFlag)) {
+            const { OpenAIReasoningProvider } = await import('./openai-reasoning-provider.js');
+            return new OpenAIReasoningProvider(modelFlag);
+        }
+        const { OpenAIProvider } = await import('./openai-provider.js');
+        return new OpenAIProvider(modelFlag ?? 'gpt-4o', baseUrlFlag);
+    }
+    else {
+        const { AnthropicProvider } = await import('./anthropic-provider.js');
+        return new AnthropicProvider(modelFlag ?? 'claude-sonnet-4-5');
+    }
+}
+//# sourceMappingURL=llm-provider.js.map

package/dist/agent/llm-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider.js","sourceRoot":"","sources":["../../src/agent/llm-provider.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,OAAgB,WAAW;IAO/B,6DAA6D;IAC7D,YAAY;QACV,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAgB,sBAAuB,SAAQ,WAAW;CAW/D;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAqB;IACjD,OAAO,QAAQ,YAAY,sBAAsB,CAAC;AACpD,CAAC;AAID;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,YAAsC,EACtC,SAA6B,EAC7B,WAAoB;IAEpB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,SAAS,CAAC;IAC9D,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,SAAS,CAAC;IAEpE,IAAI,CAAC,SAAS,IAAI,CAAC,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAEtE,IAAI,WAAW,KAAK,SAAS,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,wFAAwF;YACtF,wFAAwF,CAC3F,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,yEAAyE;QACzE,yEAAyE;QACzE,2CAA2C;QAC3C,MAAM,gBAAgB,GAAG,eAAe,CAAC;QACzC,IAAI,SAAS,KAAK,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC;YACnF,OAAO,IAAI,uBAAuB,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAChE,OAAO,IAAI,cAAc,CAAC,SAAS,IAAI,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtE,OAAO,IAAI,iBAAiB,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;IACjE,CAAC;AACH,CAAC"}

package/dist/agent/mcp/mcp-client.d.ts

@@ -0,0 +1,18 @@
+import { Client } from '@modelcontextprotocol/sdk/client';
+import type { McpClient as IMcpClient, McpServerConfig, McpTool } from './mcp-extensions.js';
+export declare class McpClient implements IMcpClient {
+    private readonly _servers;
+    private readonly _clients;
+    constructor(servers: McpServerConfig[], signal?: AbortSignal);
+    /**
+     * Creates and connects an SDK Client for the given config.
+     * Override in tests to inject an in-process transport and avoid spawning real subprocesses.
+     */
+    protected _createClient(config: McpServerConfig, expandedEnv: Record<string, string>): Promise<Client>;
+    connect(serverId: string): Promise<void>;
+    getTools(serverId: string, allowList: string[]): Promise<McpTool[]>;
+    call(serverId: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    disconnect(): Promise<void>;
+    private _expandEnv;
+}
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/agent/mcp/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../../../src/agent/mcp/mcp-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAG1D,OAAO,KAAK,EAAE,SAAS,IAAI,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE7F,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW;IAc5D;;;OAGG;cACa,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,MAAM,CAAC;IAqBZ,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAanE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAMzF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,OAAO,CAAC,UAAU;CAmBnB"}

package/dist/agent/mcp/mcp-client.js

@@ -0,0 +1,108 @@
+// mcp-client.ts — Manages stdio MCP server subprocess lifecycles.
+// This is the only file in the codebase that imports @modelcontextprotocol/sdk directly.
+import { Client } from '@modelcontextprotocol/sdk/client';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { WorkflowError } from '@sensigo/realm';
+export class McpClient {
+    _servers;
+    _clients = new Map();
+    constructor(servers, signal) {
+        this._servers = new Map(servers.map((s) => [s.id, s]));
+        if (signal) {
+            // Register unconditionally — a signal that fires before first connect must still trigger cleanup.
+            signal.addEventListener('abort', () => {
+                void this.disconnect();
+            }, { once: true });
+        }
+    }
+    /**
+     * Creates and connects an SDK Client for the given config.
+     * Override in tests to inject an in-process transport and avoid spawning real subprocesses.
+     */
+    async _createClient(config, expandedEnv) {
+        const params = {
+            command: config.command ?? '',
+            ...(config.args !== undefined ? { args: config.args } : {}),
+            ...(Object.keys(expandedEnv).length > 0 ? { env: expandedEnv } : {}),
+        };
+        const transport = new StdioClientTransport(params);
+        const client = new Client({ name: 'realm-agent', version: '0.1.0' });
+        try {
+            await client.connect(transport);
+        }
+        catch (e) {
+            throw new WorkflowError(`MCP server '${config.id}': connection failed: ${String(e)}`, {
+                code: 'MCP_CONNECTION_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        return client;
+    }
+    async connect(serverId) {
+        if (this._clients.has(serverId))
+            return;
+        const config = this._servers.get(serverId);
+        if (!config) {
+            throw new WorkflowError(`MCP server '${serverId}' is not configured`, {
+                code: 'MCP_CONNECTION_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        const expandedEnv = this._expandEnv(serverId, config);
+        const client = await this._createClient(config, expandedEnv);
+        // Idempotency check after await — guards against concurrent connect() calls.
+        if (!this._clients.has(serverId)) {
+            this._clients.set(serverId, client);
+        }
+        else {
+            void client.close();
+        }
+    }
+    async getTools(serverId, allowList) {
+        await this.connect(serverId);
+        const client = this._clients.get(serverId);
+        const result = await client.listTools();
+        const tools = result.tools.map((t) => ({
+            name: t.name,
+            description: t.description ?? '',
+            inputSchema: t.inputSchema,
+        }));
+        if (allowList.length === 0)
+            return tools;
+        return tools.filter((t) => allowList.includes(t.name));
+    }
+    async call(serverId, toolName, args) {
+        await this.connect(serverId);
+        const client = this._clients.get(serverId);
+        return client.callTool({ name: toolName, arguments: args });
+    }
+    async disconnect() {
+        const clients = [...this._clients.values()];
+        this._clients.clear();
+        await Promise.allSettled(clients.map((c) => c.close()));
+    }
+    _expandEnv(serverId, config) {
+        const expanded = {};
+        for (const [key, value] of Object.entries(config.env ?? {})) {
+            const result = value.replace(/\$\{([^}]+)\}/g, (_match, varName) => {
+                const v = process.env[varName];
+                if (v === undefined) {
+                    throw new WorkflowError(`MCP server '${serverId}': env var ${varName} is not set`, {
+                        code: 'MCP_CONNECTION_FAILED',
+                        category: 'ENGINE',
+                        agentAction: 'stop',
+                        retryable: false,
+                    });
+                }
+                return v;
+            });
+            expanded[key] = result;
+        }
+        return expanded;
+    }
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/agent/mcp/mcp-client.js.map

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

package/dist/agent/mcp/mcp-extensions.d.ts

@@ -0,0 +1,40 @@
+import type { ToolCallRecord, McpServerConfig } from '@sensigo/realm';
+export type { ToolCallRecord, McpServerConfig };
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolDefinition {
+    id: string;
+    serverId: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export type ToolExecutor = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface StepWithToolsResult {
+    output: Record<string, unknown>;
+    toolCalls: ToolCallRecord[];
+}
+export interface McpClient {
+    /**
+     * Lazily connects to a server on first call. Idempotent.
+     * stdio failures throw WorkflowError(MCP_CONNECTION_FAILED, stop).
+     */
+    connect(serverId: string): Promise<void>;
+    /**
+     * Returns tools from the specified server, filtered to the allow-list.
+     * Triggers lazy-connect on first call — the subprocess may spawn here.
+     */
+    getTools(serverId: string, allowList: string[]): Promise<McpTool[]>;
+    /** Execute a tool on the specified server. */
+    call(serverId: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Shut down all server connections. Idempotent — safe to call multiple times.
+     * Must be called in finally blocks.
+     * If constructed with an AbortSignal, also called automatically on abort.
+     */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=mcp-extensions.d.ts.map

package/dist/agent/mcp/mcp-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-extensions.d.ts","sourceRoot":"","sources":["../../../src/agent/mcp/mcp-extensions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAGhD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAGD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAGD,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAGjG,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,cAAc,EAAE,CAAC;CAE7B;AAGD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACpE,8CAA8C;IAC9C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1F;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/agent/mcp/mcp-extensions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mcp-extensions.js.map

package/dist/agent/mcp/mcp-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-extensions.js","sourceRoot":"","sources":["../../../src/agent/mcp/mcp-extensions.ts"],"names":[],"mappings":""}

package/dist/agent/mcp-client.d.ts

@@ -0,0 +1,18 @@
+import { Client } from '@modelcontextprotocol/sdk/client';
+import type { McpClient as IMcpClient, McpServerConfig, McpTool } from './mcp-types.js';
+export declare class McpClient implements IMcpClient {
+    private readonly _servers;
+    private readonly _clients;
+    constructor(servers: McpServerConfig[], signal?: AbortSignal);
+    /**
+     * Creates and connects an SDK Client for the given config.
+     * Override in tests to inject an in-process transport and avoid spawning real subprocesses.
+     */
+    protected _createClient(config: McpServerConfig, expandedEnv: Record<string, string>): Promise<Client>;
+    connect(serverId: string): Promise<void>;
+    getTools(serverId: string, allowList: string[]): Promise<McpTool[]>;
+    call(serverId: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    disconnect(): Promise<void>;
+    private _expandEnv;
+}
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/agent/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../../src/agent/mcp-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAG1D,OAAO,KAAK,EAAE,SAAS,IAAI,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAExF,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW;IAc5D;;;OAGG;cACa,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,MAAM,CAAC;IAqBZ,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAanE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAMzF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,OAAO,CAAC,UAAU;CAmBnB"}

package/dist/agent/mcp-client.js

@@ -0,0 +1,108 @@
+// mcp-client.ts — Manages stdio MCP server subprocess lifecycles.
+// This is the only file in the codebase that imports @modelcontextprotocol/sdk directly.
+import { Client } from '@modelcontextprotocol/sdk/client';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { WorkflowError } from '@sensigo/realm';
+export class McpClient {
+    _servers;
+    _clients = new Map();
+    constructor(servers, signal) {
+        this._servers = new Map(servers.map((s) => [s.id, s]));
+        if (signal) {
+            // Register unconditionally — a signal that fires before first connect must still trigger cleanup.
+            signal.addEventListener('abort', () => {
+                void this.disconnect();
+            }, { once: true });
+        }
+    }
+    /**
+     * Creates and connects an SDK Client for the given config.
+     * Override in tests to inject an in-process transport and avoid spawning real subprocesses.
+     */
+    async _createClient(config, expandedEnv) {
+        const params = {
+            command: config.command ?? '',
+            ...(config.args !== undefined ? { args: config.args } : {}),
+            ...(Object.keys(expandedEnv).length > 0 ? { env: expandedEnv } : {}),
+        };
+        const transport = new StdioClientTransport(params);
+        const client = new Client({ name: 'realm-agent', version: '0.1.0' });
+        try {
+            await client.connect(transport);
+        }
+        catch (e) {
+            throw new WorkflowError(`MCP server '${config.id}': connection failed: ${String(e)}`, {
+                code: 'MCP_CONNECTION_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        return client;
+    }
+    async connect(serverId) {
+        if (this._clients.has(serverId))
+            return;
+        const config = this._servers.get(serverId);
+        if (!config) {
+            throw new WorkflowError(`MCP server '${serverId}' is not configured`, {
+                code: 'MCP_CONNECTION_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        const expandedEnv = this._expandEnv(serverId, config);
+        const client = await this._createClient(config, expandedEnv);
+        // Idempotency check after await — guards against concurrent connect() calls.
+        if (!this._clients.has(serverId)) {
+            this._clients.set(serverId, client);
+        }
+        else {
+            void client.close();
+        }
+    }
+    async getTools(serverId, allowList) {
+        await this.connect(serverId);
+        const client = this._clients.get(serverId);
+        const result = await client.listTools();
+        const tools = result.tools.map((t) => ({
+            name: t.name,
+            description: t.description ?? '',
+            inputSchema: t.inputSchema,
+        }));
+        if (allowList.length === 0)
+            return tools;
+        return tools.filter((t) => allowList.includes(t.name));
+    }
+    async call(serverId, toolName, args) {
+        await this.connect(serverId);
+        const client = this._clients.get(serverId);
+        return client.callTool({ name: toolName, arguments: args });
+    }
+    async disconnect() {
+        const clients = [...this._clients.values()];
+        this._clients.clear();
+        await Promise.allSettled(clients.map((c) => c.close()));
+    }
+    _expandEnv(serverId, config) {
+        const expanded = {};
+        for (const [key, value] of Object.entries(config.env ?? {})) {
+            const result = value.replace(/\$\{([^}]+)\}/g, (_match, varName) => {
+                const v = process.env[varName];
+                if (v === undefined) {
+                    throw new WorkflowError(`MCP server '${serverId}': env var ${varName} is not set`, {
+                        code: 'MCP_CONNECTION_FAILED',
+                        category: 'ENGINE',
+                        agentAction: 'stop',
+                        retryable: false,
+                    });
+                }
+                return v;
+            });
+            expanded[key] = result;
+        }
+        return expanded;
+    }
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/agent/mcp-client.js.map

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

package/dist/agent/mcp-types.d.ts

@@ -0,0 +1,40 @@
+import type { ToolCallRecord, McpServerConfig } from '@sensigo/realm';
+export type { ToolCallRecord, McpServerConfig };
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolDefinition {
+    id: string;
+    serverId: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export type ToolExecutor = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface StepWithToolsResult {
+    output: Record<string, unknown>;
+    toolCalls: ToolCallRecord[];
+}
+export interface McpClient {
+    /**
+     * Lazily connects to a server on first call. Idempotent.
+     * stdio failures throw WorkflowError(MCP_CONNECTION_FAILED, stop).
+     */
+    connect(serverId: string): Promise<void>;
+    /**
+     * Returns tools from the specified server, filtered to the allow-list.
+     * Triggers lazy-connect on first call — the subprocess may spawn here.
+     */
+    getTools(serverId: string, allowList: string[]): Promise<McpTool[]>;
+    /** Execute a tool on the specified server. */
+    call(serverId: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Shut down all server connections. Idempotent — safe to call multiple times.
+     * Must be called in finally blocks.
+     * If constructed with an AbortSignal, also called automatically on abort.
+     */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=mcp-types.d.ts.map

package/dist/agent/mcp-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.d.ts","sourceRoot":"","sources":["../../src/agent/mcp-types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAGhD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAGD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAGD,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAGjG,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,cAAc,EAAE,CAAC;CAE7B;AAGD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACpE,8CAA8C;IAC9C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1F;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/agent/mcp-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mcp-types.js.map

package/dist/agent/mcp-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.js","sourceRoot":"","sources":["../../src/agent/mcp-types.ts"],"names":[],"mappings":""}

package/dist/agent/openai-provider.d.ts

@@ -0,0 +1,30 @@
+import { ToolCapableLlmProvider, type ProviderCapabilities } from './llm-provider.js';
+import type { ToolDefinition, ToolExecutor, StepWithToolsResult } from './mcp-types.js';
+/**
+ * OpenAI LLM provider for realm agent.
+ * Uses the Chat Completions API. Sends `response_format: json_object` on native
+ * OpenAI endpoints; falls back to prompt-only JSON enforcement on compat endpoints
+ * behind `--base-url`. Retries once if the model returns non-JSON content.
+ */
+export declare class OpenAIProvider extends ToolCapableLlmProvider {
+    private readonly model;
+    private readonly baseUrl;
+    constructor(model: string, baseUrl?: string);
+    /**
+     * Native OpenAI endpoints have a well-defined, tested capability surface that includes
+     * json_object mode. Custom compat endpoints behind --base-url do not guarantee this feature.
+     * Default to prompt-only enforcement for any unknown endpoint.
+     */
+    capabilities(): ProviderCapabilities;
+    callStep(prompt: string, inputSchema?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Agentic loop for tool-capable steps. Executes tool calls serially (V1 constraint)
+     * until the model returns a final JSON answer or the tool call budget is exhausted.
+     */
+    callStepWithTools(prompt: string, tools: ToolDefinition[], executor: ToolExecutor, options: {
+        inputSchema?: Record<string, unknown>;
+        maxToolCalls?: number;
+        toolTimeoutMs?: number;
+    }): Promise<StepWithToolsResult>;
+}
+//# sourceMappingURL=openai-provider.d.ts.map

package/dist/agent/openai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.d.ts","sourceRoot":"","sources":["../../src/agent/openai-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAWxB;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,sBAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAM3C;;;;OAIG;IACH,YAAY,IAAI,oBAAoB;IAI9B,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA8DnC;;;OAGG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,mBAAmB,CAAC;CA0LhC"}