@sensigo/realm-cli 0.1.0

package/dist/agent/providers/openai-provider.js

@@ -0,0 +1,253 @@
+// openai-provider.ts — OpenAI LLM provider implementation for realm agent.
+// Requires openai >= 4.0.0 as an optional peer dependency (npm install openai).
+import { WorkflowError } from '@sensigo/realm';
+import { ToolCapableLlmProvider } from './llm-provider.js';
+import { sanitizeError, serializeToolResult, parseNamespacedId, tryParseJson, validateSchema, rejectAfter, buildSystemPrompt, } from './agent-utils.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 class OpenAIProvider extends ToolCapableLlmProvider {
+    model;
+    baseUrl;
+    constructor(model, baseUrl) {
+        super();
+        this.model = model;
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * 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() {
+        return { jsonMode: this.baseUrl === undefined };
+    }
+    async callStep(prompt, inputSchema) {
+        // Dynamically import openai to keep it an optional peer dependency.
+        // Assigning the module specifier to a typed variable via 'string' makes TS
+        // treat it as Promise<any>, bypassing static module resolution at build time.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let mod;
+        try {
+            const moduleId = 'openai';
+            mod = await import(moduleId);
+        }
+        catch {
+            console.error('realm agent requires the openai package. Run: npm install openai');
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = new mod.default({
+            apiKey: process.env['OPENAI_API_KEY'],
+            ...(this.baseUrl !== undefined ? { baseURL: this.baseUrl } : {}),
+        });
+        const systemPrompt = buildSystemPrompt(inputSchema);
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: prompt },
+        ];
+        const makeRequest = async (msgs) => {
+            const opts = {
+                model: this.model,
+                messages: msgs,
+            };
+            if (this.capabilities().jsonMode) {
+                opts['response_format'] = { type: 'json_object' };
+            }
+            const response = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.chat.completions.create(opts);
+            return response.choices[0]?.message?.content ?? '';
+        };
+        const content = await makeRequest(messages);
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Retry once with an explicit reminder to return JSON.
+            const retryMessages = [
+                ...messages,
+                { role: 'assistant', content },
+                {
+                    role: 'user',
+                    content: 'Your previous response was not valid JSON. Respond with a JSON object only.',
+                },
+            ];
+            const retry = await makeRequest(retryMessages);
+            try {
+                return JSON.parse(retry);
+            }
+            catch {
+                throw new Error(`OpenAI returned non-JSON content after retry: ${retry.slice(0, 200)}`);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async callStepWithTools(prompt, tools, executor, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let mod;
+        try {
+            const moduleId = 'openai';
+            mod = await import(moduleId);
+        }
+        catch {
+            console.error('realm agent requires the openai package. Run: npm install openai');
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = new mod.default({
+            apiKey: process.env['OPENAI_API_KEY'],
+            ...(this.baseUrl !== undefined ? { baseURL: this.baseUrl } : {}),
+        });
+        const responseFormat = this.capabilities().jsonMode
+            ? { type: 'json_object' }
+            : undefined;
+        // toolIdMap: bareName → namespaced id, used to recover routing key from LLM responses.
+        // Collision guard: two MCP servers may not expose the same bare tool name in the same step.
+        const toolIdMap = new Map();
+        const openaiTools = [];
+        for (const tool of tools) {
+            if (toolIdMap.has(tool.name)) {
+                throw new Error(`invariant: duplicate bare tool name '${tool.name}' in toolIdMap — this should have been caught at toolDefs assembly in run-agent.ts`);
+            }
+            toolIdMap.set(tool.name, tool.id);
+            openaiTools.push({
+                type: 'function',
+                function: {
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.inputSchema,
+                },
+            });
+        }
+        const maxCalls = options.maxToolCalls ?? 20;
+        let tool_call_count = 0;
+        const tool_call_records = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const history = [
+            { role: 'system', content: buildSystemPrompt(options.inputSchema) },
+            { role: 'user', content: prompt },
+        ];
+        const buildMainCallOpts = () => {
+            const opts = { model: this.model, messages: history };
+            if (openaiTools.length > 0)
+                opts['tools'] = openaiTools;
+            if (responseFormat !== undefined)
+                opts['response_format'] = responseFormat;
+            return opts;
+        };
+        const buildFinalCallOpts = () => {
+            const opts = { model: this.model, messages: history };
+            if (responseFormat !== undefined)
+                opts['response_format'] = responseFormat;
+            return opts;
+        };
+        // Injects the over-budget message and calls the API without tools to produce a final answer.
+        const performFinalExtraction = async () => {
+            history.push({
+                role: 'user',
+                content: 'You have reached the maximum number of tool calls. Produce your final JSON answer now using only what you have already gathered. No further tool calls will be executed.',
+            });
+            const final = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.chat.completions.create(buildFinalCallOpts());
+            const text = final.choices[0].message.content ?? '';
+            const parsed = tryParseJson(text);
+            if (parsed && validateSchema(parsed, options.inputSchema)) {
+                return { output: parsed, toolCalls: tool_call_records };
+            }
+            throw new WorkflowError('max_tool_calls reached; final extraction failed', {
+                code: 'ENGINE_STEP_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        };
+        while (true) {
+            const response = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.chat.completions.create(buildMainCallOpts());
+            const message = response.choices[0].message;
+            if (message.tool_calls?.length) {
+                const batch = message.tool_calls;
+                history.push(message);
+                let budget_exhausted_mid_batch = false;
+                for (const tool of batch) {
+                    const llmToolCallId = tool.id; // captured verbatim — API returns 400 if echoed incorrectly
+                    if (tool_call_count >= maxCalls) {
+                        // Budget exhausted — must still answer every id in the assistant message.
+                        history.push({
+                            role: 'tool',
+                            tool_call_id: llmToolCallId,
+                            content: 'Error: tool call budget exhausted',
+                        });
+                        budget_exhausted_mid_batch = true;
+                        continue;
+                    }
+                    const originalId = toolIdMap.get(tool.function.name);
+                    const { serverId, toolName } = parseNamespacedId(originalId);
+                    const args = JSON.parse(tool.function.arguments || '{}');
+                    const start = Date.now();
+                    let resultContent;
+                    let record;
+                    try {
+                        const rawResult = await Promise.race([
+                            executor(originalId, args),
+                            rejectAfter(options.toolTimeoutMs ?? 30000),
+                        ]);
+                        const serialized = serializeToolResult(rawResult);
+                        record = {
+                            server_id: serverId,
+                            tool: toolName,
+                            args,
+                            result: serialized,
+                            duration_ms: Date.now() - start,
+                        };
+                        resultContent = serialized;
+                    }
+                    catch (err) {
+                        const sanitized = sanitizeError(err);
+                        const content = sanitized.length > 0 ? `Error: ${sanitized}` : 'Error: (redacted)';
+                        record = {
+                            server_id: serverId,
+                            tool: toolName,
+                            args,
+                            result: null,
+                            duration_ms: Date.now() - start,
+                            error: sanitized,
+                        };
+                        resultContent = content;
+                    }
+                    tool_call_records.push(record);
+                    tool_call_count++;
+                    history.push({ role: 'tool', tool_call_id: llmToolCallId, content: resultContent });
+                }
+                if (budget_exhausted_mid_batch || tool_call_count >= maxCalls) {
+                    return performFinalExtraction();
+                }
+            }
+            else {
+                // No tool calls — attempt to parse the final answer.
+                const text = message.content ?? '';
+                const parsed = tryParseJson(text);
+                if (parsed && validateSchema(parsed, options.inputSchema)) {
+                    return { output: parsed, toolCalls: tool_call_records };
+                }
+                // Schema mismatch — append correction message and continue the loop.
+                history.push({ role: 'assistant', content: text });
+                history.push({
+                    role: 'user',
+                    content: 'Your response did not match the required JSON schema. Try again.',
+                });
+                tool_call_count++; // schema correction consumes a slot
+                if (tool_call_count >= maxCalls) {
+                    return performFinalExtraction();
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=openai-provider.js.map

package/dist/agent/providers/openai-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.js","sourceRoot":"","sources":["../../../src/agent/providers/openai-provider.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAA6B,MAAM,mBAAmB,CAAC;AAOtF,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,sBAAsB;IACvC,KAAK,CAAS;IACd,OAAO,CAAqB;IAE7C,YAAY,KAAa,EAAE,OAAgB;QACzC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,MAAc,EACd,WAAqC;QAErC,oEAAoE;QACpE,2EAA2E;QAC3E,8EAA8E;QAC9E,8DAA8D;QAC9D,IAAI,GAAQ,CAAC;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAW,QAAQ,CAAC;YAClC,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,8DAA8D;QAC9D,MAAM,MAAM,GAAG,IAAK,GAAG,CAAC,OAAsD,CAAC;YAC7E,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACrC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;QAEH,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;QAEpD,MAAM,QAAQ,GAAc;YAC1B,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE;YACzC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;SAClC,CAAC;QAEF,MAAM,WAAW,GAAG,KAAK,EAAE,IAAe,EAAmB,EAAE;YAC7D,MAAM,IAAI,GAA4B;gBACpC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,IAAI;aACf,CAAC;YACF,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,CAAC;gBACjC,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;YACpD,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,8DAA8D;aACpF,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAA0D,CAAC,IAAI,CAAC,CAAC;YAC1F,OAAQ,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAA8B,IAAI,EAAE,CAAC;QAC7E,CAAC,CAAC;QAEF,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,uDAAuD;YACvD,MAAM,aAAa,GAAc;gBAC/B,GAAG,QAAQ;gBACX,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE;gBAC9B;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,6EAA6E;iBACvF;aACF,CAAC;YACF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;YAC/C,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAA4B,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,iDAAiD,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB,CACrB,MAAc,EACd,KAAuB,EACvB,QAAsB,EACtB,OAIC;QAED,8DAA8D;QAC9D,IAAI,GAAQ,CAAC;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAW,QAAQ,CAAC;YAClC,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,8DAA8D;QAC9D,MAAM,MAAM,GAAG,IAAK,GAAG,CAAC,OAAsD,CAAC;YAC7E,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACrC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,QAAQ;YACjD,CAAC,CAAE,EAAE,IAAI,EAAE,aAAa,EAAY;YACpC,CAAC,CAAC,SAAS,CAAC;QAEd,uFAAuF;QACvF,4FAA4F;QAC5F,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC5C,MAAM,WAAW,GAGZ,EAAE,CAAC;QACR,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACb,wCAAwC,IAAI,CAAC,IAAI,oFAAoF,CACtI,CAAC;YACJ,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAClC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,UAAU,EAAE,IAAI,CAAC,WAAW;iBAC7B;aACF,CAAC,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;QAC5C,IAAI,eAAe,GAAG,CAAC,CAAC;QACxB,MAAM,iBAAiB,GAAqB,EAAE,CAAC;QAE/C,8DAA8D;QAC9D,MAAM,OAAO,GAAU;YACrB,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE;YACnE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;SAClC,CAAC;QAEF,MAAM,iBAAiB,GAAG,GAA4B,EAAE;YACtD,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAC/E,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,WAAW,CAAC;YACxD,IAAI,cAAc,KAAK,SAAS;gBAAE,IAAI,CAAC,iBAAiB,CAAC,GAAG,cAAc,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,kBAAkB,GAAG,GAA4B,EAAE;YACvD,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAC/E,IAAI,cAAc,KAAK,SAAS;gBAAE,IAAI,CAAC,iBAAiB,CAAC,GAAG,cAAc,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QAEF,6FAA6F;QAC7F,MAAM,sBAAsB,GAAG,KAAK,IAAkC,EAAE;YACtE,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,MAAM;gBACZ,OAAO,EACL,0KAA0K;aAC7K,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,8DAA8D;aACjF,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAA0D,CACjF,kBAAkB,EAAE,CACrB,CAAC;YACF,MAAM,IAAI,GAAY,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAyB,IAAI,EAAE,CAAC;YAC/E,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;YAC1D,CAAC;YACD,MAAM,IAAI,aAAa,CAAC,iDAAiD,EAAE;gBACzE,IAAI,EAAE,oBAAoB;gBAC1B,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,MAAM,8DAA8D;aACpF,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAA0D,CACjF,iBAAiB,EAAE,CACpB,CAAC;YACF,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAGnC,CAAC;YAEF,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACtB,IAAI,0BAA0B,GAAG,KAAK,CAAC;gBAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,MAAM,aAAa,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,4DAA4D;oBAE3F,IAAI,eAAe,IAAI,QAAQ,EAAE,CAAC;wBAChC,0EAA0E;wBAC1E,OAAO,CAAC,IAAI,CAAC;4BACX,IAAI,EAAE,MAAM;4BACZ,YAAY,EAAE,aAAa;4BAC3B,OAAO,EAAE,mCAAmC;yBAC7C,CAAC,CAAC;wBACH,0BAA0B,GAAG,IAAI,CAAC;wBAClC,SAAS;oBACX,CAAC;oBAED,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAE,CAAC;oBACtD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;oBAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,IAAI,IAAI,CAA4B,CAAC;oBACpF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBAEzB,IAAI,aAAqB,CAAC;oBAC1B,IAAI,MAAsB,CAAC;oBAE3B,IAAI,CAAC;wBACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;4BACnC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;4BAC1B,WAAW,CAAC,OAAO,CAAC,aAAa,IAAI,KAAK,CAAC;yBAC5C,CAAC,CAAC;wBACH,MAAM,UAAU,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;wBAClD,MAAM,GAAG;4BACP,SAAS,EAAE,QAAQ;4BACnB,IAAI,EAAE,QAAQ;4BACd,IAAI;4BACJ,MAAM,EAAE,UAAU;4BAClB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;yBAChC,CAAC;wBACF,aAAa,GAAG,UAAU,CAAC;oBAC7B,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;wBACrC,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;wBACnF,MAAM,GAAG;4BACP,SAAS,EAAE,QAAQ;4BACnB,IAAI,EAAE,QAAQ;4BACd,IAAI;4BACJ,MAAM,EAAE,IAAI;4BACZ,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;4BAC/B,KAAK,EAAE,SAAS;yBACjB,CAAC;wBACF,aAAa,GAAG,OAAO,CAAC;oBAC1B,CAAC;oBAED,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAC/B,eAAe,EAAE,CAAC;oBAClB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;gBACtF,CAAC;gBAED,IAAI,0BAA0B,IAAI,eAAe,IAAI,QAAQ,EAAE,CAAC;oBAC9D,OAAO,sBAAsB,EAAE,CAAC;gBAClC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,qDAAqD;gBACrD,MAAM,IAAI,GAAY,OAAO,CAAC,OAAyB,IAAI,EAAE,CAAC;gBAC9D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;gBAClC,IAAI,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;gBAC1D,CAAC;gBACD,qEAAqE;gBACrE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnD,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,kEAAkE;iBAC5E,CAAC,CAAC;gBACH,eAAe,EAAE,CAAC,CAAC,oCAAoC;gBACvD,IAAI,eAAe,IAAI,QAAQ,EAAE,CAAC;oBAChC,OAAO,sBAAsB,EAAE,CAAC;gBAClC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,19 @@
+import { LlmProvider } from './llm-provider.js';
+/**
+ * OpenAI reasoning model provider for realm agent.
+ * Handles the o1-series (o1, o1-mini, o1-preview), which differ from standard chat completions:
+ * - No `response_format` parameter (JSON enforced via system prompt + retry).
+ * - System prompt content is folded into the first user message — the safe
+ *   universal approach for the full o1 lineage. (o1 originally rejected the
+ *   system role; later versions accept it as a developer role, but prepending
+ *   to the user message works uniformly across all revisions.)
+ * - Tool calling is not supported — this class extends LlmProvider, not
+ *   ToolCapableLlmProvider, so `isToolCapable` returns false for these instances.
+ *   o3 and later support tools and route to OpenAIProvider instead.
+ */
+export declare class OpenAIReasoningProvider extends LlmProvider {
+    private readonly model;
+    constructor(model: string);
+    callStep(prompt: string, inputSchema?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=openai-reasoning-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai-reasoning-provider.d.ts","sourceRoot":"","sources":["../../../src/agent/providers/openai-reasoning-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAchD;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,EAAE,MAAM;IAKnB,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;CAyDpC"}

package/dist/agent/providers/openai-reasoning-provider.js

@@ -0,0 +1,89 @@
+// openai-reasoning-provider.ts — OpenAI reasoning model provider (o1-series) for realm agent.
+// Extends LlmProvider (not ToolCapableLlmProvider) — o1-series models do not support the tools parameter.
+import { LlmProvider } from './llm-provider.js';
+import { buildSystemPrompt } from './agent-utils.js';
+/**
+ * Returns the max_completion_tokens for the given OpenAI reasoning model.
+ * For o1-series models this covers both reasoning tokens and visible output.
+ * Source: https://platform.openai.com/docs/models
+ */
+function resolveMaxCompletionTokens(model) {
+    if (/^o1-mini/i.test(model))
+        return 65536;
+    // o1, o1-preview, and any other o1 variant default to 32768.
+    return 32768;
+}
+/**
+ * OpenAI reasoning model provider for realm agent.
+ * Handles the o1-series (o1, o1-mini, o1-preview), which differ from standard chat completions:
+ * - No `response_format` parameter (JSON enforced via system prompt + retry).
+ * - System prompt content is folded into the first user message — the safe
+ *   universal approach for the full o1 lineage. (o1 originally rejected the
+ *   system role; later versions accept it as a developer role, but prepending
+ *   to the user message works uniformly across all revisions.)
+ * - Tool calling is not supported — this class extends LlmProvider, not
+ *   ToolCapableLlmProvider, so `isToolCapable` returns false for these instances.
+ *   o3 and later support tools and route to OpenAIProvider instead.
+ */
+export class OpenAIReasoningProvider extends LlmProvider {
+    model;
+    constructor(model) {
+        super();
+        this.model = model;
+    }
+    async callStep(prompt, inputSchema) {
+        // Dynamically import openai to keep it an optional peer dependency.
+        // Assigning the module specifier to a typed variable via 'string' makes TS
+        // treat it as Promise<any>, bypassing static module resolution at build time.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let mod;
+        try {
+            const moduleId = 'openai';
+            mod = await import(moduleId);
+        }
+        catch {
+            console.error('realm agent requires the openai package. Run: npm install openai');
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = new mod.default({
+            apiKey: process.env['OPENAI_API_KEY'],
+        });
+        // Fold system prompt into the user message — safe for all o1-series API revisions.
+        const systemPrompt = buildSystemPrompt(inputSchema);
+        const userContent = `${systemPrompt}\n\n${prompt}`;
+        const messages = [{ role: 'user', content: userContent }];
+        const makeRequest = async (msgs) => {
+            const response = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.chat.completions.create({
+                model: this.model,
+                max_completion_tokens: resolveMaxCompletionTokens(this.model),
+                messages: msgs,
+            });
+            return response.choices[0]?.message?.content ?? '';
+        };
+        const content = await makeRequest(messages);
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Retry once with an explicit reminder to return JSON.
+            const retryMessages = [
+                ...messages,
+                { role: 'assistant', content },
+                {
+                    role: 'user',
+                    content: 'Your previous response was not valid JSON. Respond with a JSON object only.',
+                },
+            ];
+            const retry = await makeRequest(retryMessages);
+            try {
+                return JSON.parse(retry);
+            }
+            catch {
+                throw new Error(`OpenAI returned non-JSON content after retry: ${retry.slice(0, 200)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=openai-reasoning-provider.js.map

package/dist/agent/providers/openai-reasoning-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-reasoning-provider.js","sourceRoot":"","sources":["../../../src/agent/providers/openai-reasoning-provider.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0GAA0G;AAC1G,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;GAIG;AACH,SAAS,0BAA0B,CAAC,KAAa;IAC/C,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,6DAA6D;IAC7D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,uBAAwB,SAAQ,WAAW;IACrC,KAAK,CAAS;IAE/B,YAAY,KAAa;QACvB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,MAAc,EACd,WAAqC;QAErC,oEAAoE;QACpE,2EAA2E;QAC3E,8EAA8E;QAC9E,8DAA8D;QAC9D,IAAI,GAAQ,CAAC;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAW,QAAQ,CAAC;YAClC,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,8DAA8D;QAC9D,MAAM,MAAM,GAAG,IAAK,GAAG,CAAC,OAAsD,CAAC;YAC7E,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;SACtC,CAAC,CAAC;QAEH,mFAAmF;QACnF,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,WAAW,GAAG,GAAG,YAAY,OAAO,MAAM,EAAE,CAAC;QAGnD,MAAM,QAAQ,GAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAErE,MAAM,WAAW,GAAG,KAAK,EAAE,IAAe,EAAmB,EAAE;YAC7D,MAAM,QAAQ,GAAG,MAAM,8DAA8D;aACpF,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAA0D,CAAC;gBAClF,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,qBAAqB,EAAE,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC;gBAC7D,QAAQ,EAAE,IAAI;aACf,CAAC,CAAC;YACH,OAAQ,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAA8B,IAAI,EAAE,CAAC;QAC7E,CAAC,CAAC;QAEF,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,uDAAuD;YACvD,MAAM,aAAa,GAAc;gBAC/B,GAAG,QAAQ;gBACX,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE;gBAC9B;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,6EAA6E;iBACvF;aACF,CAAC;YACF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;YAC/C,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAA4B,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,iDAAiD,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/agent/run-agent.d.ts

@@ -0,0 +1,50 @@
+import { type RunStore, type WorkflowDefinition, type PendingGate, type ExtensionRegistry, type McpServerConfig } from '@sensigo/realm';
+import type { WorkflowRegistrar } from '@sensigo/realm';
+import type { LlmProvider } from './providers/llm-provider.js';
+import type { McpClient } from './mcp/mcp-extensions.js';
+export type AgentRunResult = 'completed' | 'failed';
+export interface AgentDeps {
+    store: RunStore;
+    workflowStore: WorkflowRegistrar;
+    provider: LlmProvider;
+    registry: ExtensionRegistry;
+    /**
+     * When set, called for every pending gate. The handler is responsible for notifying
+     * the relevant channel and blocking until the gate resolves.
+     * Omit for terminal-only fallback (choices printed to terminal + store polling).
+     */
+    gateHandler?: (runId: string, gate: PendingGate) => Promise<void>;
+    /**
+     * Factory for creating an McpClient instance. Injected by tests for mock isolation.
+     * Defaults to constructing a real McpClient when absent.
+     */
+    mcpClientFactory?: (servers: McpServerConfig[], signal?: AbortSignal) => McpClient;
+}
+export interface AgentRunOptions {
+    /** Path to workflow.yaml file. Required when definition is not provided. */
+    workflowPath?: string;
+    /** Inline workflow definition — bypasses loadWorkflowFromFile when provided. */
+    definition?: WorkflowDefinition;
+    /**
+     * Attach to an existing run instead of creating a new one.
+     * When set, runAgent() skips deps.store.create() and uses this ID directly.
+     * Mutually exclusive with workflowPath — runAgent() throws if both are set.
+     */
+    existingRunId?: string;
+    params: Record<string, unknown>;
+    /** Poll interval in ms for the terminal-only fallback. Defaults to 3000. Lower values are useful in tests. */
+    pollIntervalMs?: number;
+    /**
+     * When true, persist the workflow definition to ~/.realm/workflows/ so that
+     * `realm run inspect` and `realm run list` can resolve it by ID.
+     * Defaults to false — realm agent does not register workflows as a side effect.
+     */
+    register?: boolean;
+}
+/**
+ * Runs a workflow to completion using the provided dependencies.
+ * Returns 'completed' when the run finishes normally; 'failed' otherwise.
+ * Throws on setup failures (e.g. workflow file not found, provider error).
+ */
+export declare function runAgent(deps: AgentDeps, options: AgentRunOptions): Promise<AgentRunResult>;
+//# sourceMappingURL=run-agent.d.ts.map

package/dist/agent/run-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../../src/agent/run-agent.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,yBAAyB,CAAC;AAGvF,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,aAAa,EAAE,iBAAiB,CAAC;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,SAAS,CAAC;CACpF;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,8GAA8G;IAC9G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0ED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuTjG"}