reqon-dsl 0.3.0 → 0.4.0

package/dist/interpreter/pagination.js

@@ -167,7 +167,7 @@ export class CursorPaginationStrategy {
         }
         return {};
     }
-    extractResults(response, ctx) {
+    extractResults(response, _ctx) {
         if (!response || typeof response !== 'object') {
             return { items: [], hasMore: false };
         }
@@ -206,6 +206,12 @@ export class CursorPaginationStrategy {
  * Create the appropriate pagination strategy based on config
  */
 export function createPaginationStrategy(config) {
+    // A non-positive page size makes every page request the same offset and makes
+    // the `items.length >= pageSize` termination test always true, so pagination
+    // re-fetches page one until it hits the page cap. Reject it up front.
+    if (!Number.isFinite(config.pageSize) || config.pageSize < 1) {
+        throw new Error(`Pagination page size must be a positive integer, got ${config.pageSize}`);
+    }
     switch (config.type) {
         case 'offset':
             return new OffsetPaginationStrategy(config);

package/dist/interpreter/step-handlers/for-handler.d.ts

@@ -1,6 +1,7 @@
 import type { ForStep, ActionStep } from '../../ast/nodes.js';
 import type { StepHandler, StepHandlerDeps } from './types.js';
 import type { ExecutionContext } from '../context.js';
+import { QueueSignal } from '../signals.js';
 import type { DebugController, DebugSnapshot } from '../../debug/index.js';
 export interface ForHandlerDeps extends StepHandlerDeps {
     executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
@@ -17,6 +18,8 @@ export interface ForHandlerDeps extends StepHandlerDeps {
     }) => void;
     /** Optional callback to check for pause requests (called every N iterations) */
     checkPause?: () => Promise<void>;
+    /** Handle a `queue` directive raised within a loop item. */
+    handleQueue?: (signal: QueueSignal) => Promise<void>;
 }
 /**
  * Handles for...in...where iteration steps

package/dist/interpreter/step-handlers/for-handler.js

@@ -1,6 +1,7 @@
 import { evaluate } from '../evaluator.js';
 import { childContext, setVariable, getVariable } from '../context.js';
 import { StepError } from '../../errors/index.js';
+import { SkipSignal, QueueSignal } from '../signals.js';
 /** Heartbeat interval for loop iterations */
 const LOOP_HEARTBEAT_INTERVAL = 10;
 /**
@@ -110,9 +111,23 @@ export class ForHandler {
     async executeForItem(step, item) {
         const childCtx = childContext(this.deps.ctx);
         setVariable(childCtx, step.variable, item);
-        // Execute each inner step with child context
-        for (const innerStep of step.steps) {
-            await this.deps.executeStep(innerStep, this.deps.actionName, childCtx);
+        try {
+            // Execute each inner step with child context
+            for (const innerStep of step.steps) {
+                await this.deps.executeStep(innerStep, this.deps.actionName, childCtx);
+            }
+        }
+        catch (error) {
+            // `skip` skips the rest of this item's steps; the loop continues.
+            if (error instanceof SkipSignal) {
+                return;
+            }
+            // `queue` stashes the item and moves on to the next iteration.
+            if (error instanceof QueueSignal) {
+                await this.deps.handleQueue?.(error);
+                return;
+            }
+            throw error;
         }
     }
 }

package/dist/interpreter/step-handlers/match-handler.js

@@ -48,7 +48,9 @@ export class MatchHandler {
         // Execute steps
         if (matchedArm.steps) {
             // Debug pause point - before match arm body (step-into mode)
-            if (this.deps.debugController && this.deps.captureDebugSnapshot && this.deps.handleDebugCommand) {
+            if (this.deps.debugController &&
+                this.deps.captureDebugSnapshot &&
+                this.deps.handleDebugCommand) {
                 const location = {
                     action: this.deps.actionName,
                     stepIndex: -1, // Use -1 for match arms
@@ -79,10 +81,11 @@ export class MatchHandler {
                 throw new JumpSignal(flow.action, flow.then);
             case 'queue':
                 throw new QueueSignal(value, flow.target);
-            default:
+            default: {
                 // This should never happen if TypeScript is working correctly
                 const _exhaustive = flow;
                 throw new Error(`Unknown flow directive: ${_exhaustive.type}`);
+            }
         }
     }
 }

package/dist/interpreter/step-handlers/store-handler.d.ts

@@ -9,7 +9,11 @@ export declare class StoreHandler implements StepHandler<StoreStep> {
     constructor(deps: StepHandlerDeps);
     /**
      * Compute the storage key for a record based on step options.
-     * Uses the key expression if provided, otherwise falls back to record.id or a random key.
+     *
+     * Uses the key expression if provided, otherwise falls back to `record.id`.
+     * A missing or null/undefined key is an error: inventing a random key breaks
+     * dedup (re-runs duplicate everything), and stringifying undefined collapses
+     * every such record onto the literal key "undefined".
      */
     private getRecordKey;
     /**
@@ -19,5 +23,7 @@ export declare class StoreHandler implements StepHandler<StoreStep> {
     execute(step: StoreStep): Promise<void>;
     private storeMany;
     private storeOne;
+    /** True when the record should be merged into an existing one (deep upsert). */
+    private shouldMerge;
     private storeRecord;
 }

package/dist/interpreter/step-handlers/store-handler.js

@@ -11,13 +11,20 @@ export class StoreHandler {
     }
     /**
      * Compute the storage key for a record based on step options.
-     * Uses the key expression if provided, otherwise falls back to record.id or a random key.
+     *
+     * Uses the key expression if provided, otherwise falls back to `record.id`.
+     * A missing or null/undefined key is an error: inventing a random key breaks
+     * dedup (re-runs duplicate everything), and stringifying undefined collapses
+     * every such record onto the literal key "undefined".
      */
     getRecordKey(step, record) {
-        if (step.options.key) {
-            return String(evaluate(step.options.key, this.deps.ctx, record));
+        const raw = step.options.key ? evaluate(step.options.key, this.deps.ctx, record) : record.id;
+        if (raw === undefined || raw === null || raw === '') {
+            const which = step.options.key ? 'key expression' : "record 'id'";
+            throw new RuntimeError(`Cannot store to '${step.target}': ${which} is missing or empty. ` +
+                `Provide a 'key:' option that resolves to a stable, non-empty value.`, { line: 1, column: 1 }, undefined, { stepType: 'store' });
         }
-        return String(record.id ?? Math.random());
+        return String(raw);
     }
     /**
      * Emit a data.store event with operation metadata.
@@ -34,7 +41,9 @@ export class StoreHandler {
     async execute(step) {
         const store = this.deps.ctx.stores.get(step.target);
         if (!store) {
-            throw new RuntimeError(`Store not found: ${step.target}`, { line: 1, column: 1 }, undefined, { stepType: 'store' });
+            throw new RuntimeError(`Store not found: ${step.target}`, { line: 1, column: 1 }, undefined, {
+                stepType: 'store',
+            });
         }
         const source = evaluate(step.source, this.deps.ctx);
         if (Array.isArray(source)) {
@@ -45,18 +54,16 @@ export class StoreHandler {
         }
     }
     async storeMany(step, store, items) {
-        const operation = step.options.upsert ? 'upsert' : 'set';
+        const merge = this.shouldMerge(step);
+        const operation = merge ? 'upsert' : 'set';
         // Check if we can use bulk operations
-        const canBulkSet = store.bulkSet && !step.options.upsert;
-        const canBulkUpsert = store.bulkUpsert && step.options.upsert;
+        const canBulkSet = store.bulkSet && !merge;
+        const canBulkUpsert = store.bulkUpsert && merge;
         if (canBulkSet || canBulkUpsert) {
             const records = [];
             for (const item of items) {
                 const record = item;
                 const key = this.getRecordKey(step, record);
-                if (step.options.partial !== undefined) {
-                    record._partial = step.options.partial;
-                }
                 records.push({ key, value: record });
             }
             if (canBulkUpsert) {
@@ -78,17 +85,19 @@ export class StoreHandler {
     }
     async storeOne(step, store, record) {
         const key = this.getRecordKey(step, record);
-        const operation = step.options.upsert ? 'upsert' : 'set';
+        const operation = this.shouldMerge(step) ? 'upsert' : 'set';
         await this.storeRecord(step, store, record);
         this.deps.log(`Stored item to ${step.target}`);
         this.emitStoreEvent(step, operation, 1, key);
     }
+    /** True when the record should be merged into an existing one (deep upsert). */
+    shouldMerge(step) {
+        return step.options.upsert === true || step.options.partial === true;
+    }
     async storeRecord(step, store, record) {
         const key = this.getRecordKey(step, record);
-        if (step.options.partial !== undefined) {
-            record._partial = step.options.partial;
-        }
-        if (step.options.upsert) {
+        // Never mutate the caller's record or persist a storage-internal flag.
+        if (this.shouldMerge(step)) {
             await store.update(key, record);
         }
         else {

package/dist/interpreter/step-handlers/validate-handler.js

@@ -16,7 +16,10 @@ export class ValidateHandler {
             if (!result) {
                 const message = constraint.message ?? `Validation failed: ${JSON.stringify(constraint.condition)}`;
                 if (constraint.severity === 'error') {
-                    throw new ValidationError(message, { line: 1, column: 1 }, undefined, { constraint: JSON.stringify(constraint.condition), severity: 'error' });
+                    throw new ValidationError(message, { line: 1, column: 1 }, undefined, {
+                        constraint: JSON.stringify(constraint.condition),
+                        severity: 'error',
+                    });
                 }
                 else {
                     this.deps.log(`Warning: ${message}`);

package/dist/interpreter/step-handlers/webhook-handler.d.ts

@@ -36,4 +36,5 @@ export declare class WebhookHandler {
      * Execute the wait step
      */
     execute(step: WebhookStep): Promise<WebhookHandlerResult>;
+    private waitAndProcess;
 }

package/dist/interpreter/step-handlers/webhook-handler.js

@@ -44,7 +44,18 @@ export class WebhookHandler {
             webhookUrl,
             webhookPath: registration.path,
         };
-        // Wait for webhook events
+        // Wait for webhook events. The registration must be torn down on every
+        // exit path (timeout, filter throw, store failure, retry signal) or it
+        // leaks the server-side handle — hence the try/finally below.
+        try {
+            return await this.waitAndProcess(step, registration, webhookUrl, timeout, ctx, log, emit);
+        }
+        finally {
+            await webhookServer.unregister(registration.id);
+        }
+    }
+    async waitAndProcess(step, registration, webhookUrl, timeout, ctx, log, emit) {
+        const webhookServer = this.deps.webhookServer;
         const result = await webhookServer.waitForEvents(registration.id, timeout);
         if (result.timedOut) {
             log(`Webhook timeout: ${webhookUrl}`);
@@ -109,8 +120,7 @@ export class WebhookHandler {
             timedOut: result.timedOut ?? false,
             storedTo: step.storage?.target,
         });
-        // Clean up registration
-        await webhookServer.unregister(registration.id);
+        // Registration teardown happens in the caller's finally block.
         return {
             registration,
             events,

package/dist/interpreter/store-manager.d.ts

@@ -13,7 +13,7 @@ import type { StoreAdapter } from '../stores/types.js';
 export interface StoreManagerConfig {
     /** Custom store adapters by name */
     customStores?: Record<string, StoreAdapter>;
-    /** Development mode - use file stores instead of sql/nosql (default: true) */
+    /** Development mode - use file stores instead of sql/nosql (default: false) */
     developmentMode?: boolean;
     /** Base directory for file stores (default: '.reqon-data') */
     dataDir?: string;

package/dist/interpreter/store-manager.js

@@ -8,6 +8,7 @@
  * - Resolving store types for development/production modes
  */
 import { createStore, resolveStoreType } from '../stores/index.js';
+import { EXECUTION_DEFAULTS } from '../config/index.js';
 /**
  * Manages store initialization and provides access to store adapters.
  */
@@ -28,12 +29,15 @@ export class StoreManager {
             return;
         }
         // Use store factory to create appropriate adapter
-        const developmentMode = this.config.developmentMode ?? true;
+        const developmentMode = this.config.developmentMode ?? EXECUTION_DEFAULTS.DEVELOPMENT_MODE;
         const storeType = resolveStoreType(store.storeType, developmentMode);
         const adapter = createStore({
             type: storeType,
             name: store.target,
             baseDir: this.config.dataDir,
+            // In dev mode the type is already resolved to 'file'; this only matters
+            // if a raw sql/nosql type reaches the factory.
+            allowFileFallback: developmentMode,
         });
         ctx.stores.set(store.name, adapter);
         ctx.storeTypes.set(store.name, storeType);

package/dist/loader/index.js

@@ -59,9 +59,7 @@ async function loadMissionFile(filePath) {
  */
 async function loadMissionFolder(folderPath, options) {
     // Find root file - try extensions in order of preference
-    const extensionsToTry = options.extension
-        ? [options.extension]
-        : SUPPORTED_EXTENSIONS;
+    const extensionsToTry = options.extension ? [options.extension] : SUPPORTED_EXTENSIONS;
     let rootFilePath = null;
     let ext = null;
     for (const extension of extensionsToTry) {
@@ -77,9 +75,8 @@ async function loadMissionFolder(folderPath, options) {
         }
     }
     if (!rootFilePath || !ext) {
-        const tried = extensionsToTry.map(e => `mission${e}`).join(' or ');
-        throw new Error(`Mission folder must contain a root file (${tried}). ` +
-            `Not found in: ${folderPath}`);
+        const tried = extensionsToTry.map((e) => `mission${e}`).join(' or ');
+        throw new Error(`Mission folder must contain a root file (${tried}). ` + `Not found in: ${folderPath}`);
     }
     // Load root file
     const rootSource = await readFile(rootFilePath, 'utf-8');
@@ -87,7 +84,7 @@ async function loadMissionFolder(folderPath, options) {
     // Find all other action files in the folder (same extension as root)
     const rootFileName = basename(rootFilePath);
     const files = await readdir(folderPath);
-    const actionFiles = files.filter(f => f.endsWith(ext) && f !== rootFileName);
+    const actionFiles = files.filter((f) => f.endsWith(ext) && f !== rootFileName);
     const sourceFiles = [rootFilePath];
     const externalActions = [];
     // Parse each action file
@@ -169,7 +166,7 @@ function validatePipelineActions(program) {
     const mission = program.statements.find((s) => s.type === 'MissionDefinition');
     if (!mission)
         return;
-    const actionNames = new Set(mission.actions.map(a => a.name));
+    const actionNames = new Set(mission.actions.map((a) => a.name));
     for (const stage of mission.pipeline.stages) {
         const stageActions = stage.actions ?? (stage.action ? [stage.action] : []);
         for (const actionName of stageActions) {

package/dist/mcp/sandbox.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sandboxing helpers for the MCP server.
+ *
+ * The MCP server is driven by an LLM acting on untrusted input, so missions
+ * must not be able to reach the network/filesystem or escape the working
+ * directory unless the operator explicitly opts in.
+ */
+/**
+ * Resolve an untrusted path against a base working directory and assert the
+ * result stays inside it. Blocks `../` and absolute-path escapes.
+ *
+ * @throws if the resolved path escapes the working directory
+ */
+export declare function resolveWithinWorkingDir(workingDir: string, p: string): string;
+/**
+ * Decide the effective dryRun for an execution. Effects (real network/fs) are
+ * opt-in: when not allowed, force dryRun regardless of what the caller asked.
+ */
+export declare function resolveDryRun(allowEffects: boolean, requestedDryRun?: boolean): boolean;
+/** Default wall-clock budget for an untrusted mission execution. */
+export declare const DEFAULT_EXECUTION_TIMEOUT_MS = 30000;
+/** Thrown when an execution exceeds its allotted time budget. */
+export declare class ExecutionTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Race a promise against a timeout. An untrusted (LLM-supplied) mission could
+ * otherwise loop or hang forever (e.g. a long pause/wait) and wedge the server.
+ * On timeout the returned promise rejects with an {@link ExecutionTimeoutError};
+ * the underlying work may keep running, but the caller is no longer blocked.
+ *
+ * A non-positive or non-finite timeout disables the guard.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+/**
+ * Whether a store of the given type may be registered under the current effects
+ * policy. File-backed stores write to disk, which is an effect, so they require
+ * effects to be enabled. In-memory stores are always allowed.
+ */
+export declare function isStoreTypeAllowed(storeType: string | undefined, allowEffects: boolean): boolean;

package/dist/mcp/sandbox.js

@@ -0,0 +1,76 @@
+/**
+ * Sandboxing helpers for the MCP server.
+ *
+ * The MCP server is driven by an LLM acting on untrusted input, so missions
+ * must not be able to reach the network/filesystem or escape the working
+ * directory unless the operator explicitly opts in.
+ */
+import { resolve, sep } from 'node:path';
+/**
+ * Resolve an untrusted path against a base working directory and assert the
+ * result stays inside it. Blocks `../` and absolute-path escapes.
+ *
+ * @throws if the resolved path escapes the working directory
+ */
+export function resolveWithinWorkingDir(workingDir, p) {
+    const base = resolve(workingDir);
+    const resolved = resolve(base, p);
+    if (resolved !== base && !resolved.startsWith(base + sep)) {
+        throw new Error(`Path "${p}" escapes the working directory`);
+    }
+    return resolved;
+}
+/**
+ * Decide the effective dryRun for an execution. Effects (real network/fs) are
+ * opt-in: when not allowed, force dryRun regardless of what the caller asked.
+ */
+export function resolveDryRun(allowEffects, requestedDryRun) {
+    if (!allowEffects)
+        return true;
+    return requestedDryRun ?? false;
+}
+/** Default wall-clock budget for an untrusted mission execution. */
+export const DEFAULT_EXECUTION_TIMEOUT_MS = 30_000;
+/** Thrown when an execution exceeds its allotted time budget. */
+export class ExecutionTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Execution exceeded the ${timeoutMs}ms timeout`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'ExecutionTimeoutError';
+    }
+}
+/**
+ * Race a promise against a timeout. An untrusted (LLM-supplied) mission could
+ * otherwise loop or hang forever (e.g. a long pause/wait) and wedge the server.
+ * On timeout the returned promise rejects with an {@link ExecutionTimeoutError};
+ * the underlying work may keep running, but the caller is no longer blocked.
+ *
+ * A non-positive or non-finite timeout disables the guard.
+ */
+export function withTimeout(promise, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new ExecutionTimeoutError(timeoutMs)), timeoutMs);
+        // Don't let the timer keep the event loop alive on its own.
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * Whether a store of the given type may be registered under the current effects
+ * policy. File-backed stores write to disk, which is an effect, so they require
+ * effects to be enabled. In-memory stores are always allowed.
+ */
+export function isStoreTypeAllowed(storeType, allowEffects) {
+    if (storeType === 'file')
+        return allowEffects;
+    return true;
+}

package/dist/mcp/server.js

@@ -17,14 +17,41 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { resolveWithinWorkingDir as confinePath, resolveDryRun, withTimeout, isStoreTypeAllowed, DEFAULT_EXECUTION_TIMEOUT_MS, } from './sandbox.js';
 import { parse, execute, fromPath } from '../index.js';
-import { createStore, } from '../stores/index.js';
+import { createStore } from '../stores/index.js';
 // Global store registry for cross-execution access
 const storeRegistry = new Map();
-let serverConfig = {
+const serverConfig = {
     workingDirectory: process.cwd(),
     verbose: false,
+    allowEffects: false,
+    executionTimeoutMs: DEFAULT_EXECUTION_TIMEOUT_MS,
 };
+/**
+ * Resolve an untrusted path against the configured working directory and
+ * assert it stays inside it. Blocks `../` / absolute-path escapes.
+ */
+function resolveWithinWorkingDir(p) {
+    return confinePath(serverConfig.workingDirectory ?? process.cwd(), p);
+}
+// Argument schemas (validated against each tool's inputSchema via zod).
+const executeArgsSchema = z.object({
+    source: z.string(),
+    verbose: z.boolean().optional(),
+    dryRun: z.boolean().optional(),
+});
+const executeFileArgsSchema = z.object({
+    path: z.string(),
+    verbose: z.boolean().optional(),
+    dryRun: z.boolean().optional(),
+});
+const registerStoreArgsSchema = z.object({
+    name: z.string(),
+    type: z.enum(['memory', 'file']).optional(),
+    path: z.string().optional(),
+});
 /**
  * Format execution result for MCP response
  */
@@ -54,9 +81,12 @@ function formatExecutionResult(result) {
  * Create executor config
  */
 function createExecutorConfig(options) {
+    // Effects are opt-in at the server level. When disabled, force dryRun so an
+    // untrusted mission cannot reach the network or write to disk, regardless of
+    // what the caller requests.
     return {
         verbose: options?.verbose ?? serverConfig.verbose,
-        dryRun: options?.dryRun ?? false,
+        dryRun: resolveDryRun(serverConfig.allowEffects ?? false, options?.dryRun),
     };
 }
 // Define available tools
@@ -208,9 +238,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case 'reqon.execute': {
-                const { source, verbose, dryRun } = args;
+                const { source, verbose, dryRun } = executeArgsSchema.parse(args);
                 const config = createExecutorConfig({ verbose, dryRun });
-                const result = await execute(source, config);
+                const result = await withTimeout(execute(source, config), serverConfig.executionTimeoutMs ?? DEFAULT_EXECUTION_TIMEOUT_MS);
                 return {
                     content: [
                         {
@@ -221,9 +251,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'reqon.execute_file': {
-                const { path, verbose, dryRun } = args;
+                const { path, verbose, dryRun } = executeFileArgsSchema.parse(args);
+                const safePath = resolveWithinWorkingDir(path);
                 const config = createExecutorConfig({ verbose, dryRun });
-                const result = await fromPath(path, config);
+                const result = await withTimeout(fromPath(safePath, config), serverConfig.executionTimeoutMs ?? DEFAULT_EXECUTION_TIMEOUT_MS);
                 return {
                     content: [
                         {
@@ -308,7 +339,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'reqon.register_store': {
-                const { name, type = 'memory', path } = args;
+                const { name, type = 'memory', path } = registerStoreArgsSchema.parse(args);
                 if (storeRegistry.has(name)) {
                     return {
                         content: [
@@ -319,10 +350,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         ],
                     };
                 }
+                // A file-backed store writes to disk, which is an effect. Refuse to
+                // register one unless effects are explicitly enabled, so a sandboxed
+                // (dryRun) server can't be coaxed into persisting data.
+                if (!isStoreTypeAllowed(type, serverConfig.allowEffects ?? false)) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File-backed stores are disabled in sandboxed mode. Start the server with --allow-effects to register a "file" store, or use type "memory".`,
+                            },
+                        ],
+                    };
+                }
+                // Confine a file store's base directory to the working directory.
+                const baseDir = resolveWithinWorkingDir(path ?? '.reqon-data');
                 const store = createStore({
                     type,
                     name,
-                    baseDir: path ?? '.reqon-data',
+                    baseDir,
                 });
                 storeRegistry.set(name, store);
                 return {
@@ -436,11 +483,17 @@ async function main() {
             serverConfig.workingDirectory = args[++i];
             process.chdir(serverConfig.workingDirectory);
         }
+        if (args[i] === '--allow-effects') {
+            serverConfig.allowEffects = true;
+        }
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Log to stderr so it doesn't interfere with MCP protocol on stdout
     console.error('Reqon MCP Server running on stdio');
+    console.error(serverConfig.allowEffects
+        ? '  Effects ENABLED (--allow-effects): missions may make real network/filesystem calls.'
+        : '  Sandboxed: missions run in dryRun (no network/filesystem effects). Pass --allow-effects to enable.');
     if (serverConfig.verbose) {
         console.error(`  Working directory: ${serverConfig.workingDirectory}`);
     }

package/dist/oas/loader.d.ts

@@ -15,7 +15,19 @@ export interface OASSource {
     operations: Map<string, OASOperation>;
     schemas: Map<string, OpenAPIV3.SchemaObject>;
 }
-export declare function loadOAS(specPath: string, forceReload?: boolean): Promise<OASSource>;
+export interface LoadOASOptions {
+    /** Bypass the spec cache and re-parse. */
+    forceReload?: boolean;
+    /**
+     * Allow `$ref` pointers to external documents, including remote http(s)
+     * URLs. Off by default: an OAS spec is often untrusted input, and resolving
+     * external $refs lets the parser fetch arbitrary hosts/files — an SSRF and
+     * resource-exhaustion sink. When false, only internal `#/...` references are
+     * resolved; external ones are not fetched.
+     */
+    allowExternalRefs?: boolean;
+}
+export declare function loadOAS(specPath: string, optionsOrForceReload?: LoadOASOptions | boolean): Promise<OASSource>;
 export declare function resolveOperation(source: OASSource, operationId: string): OASOperation;
 export declare function getResponseSchema(source: OASSource, operationId: string, statusCode?: string): OpenAPIV3.SchemaObject | undefined;
 export declare function clearCache(): void;

package/dist/oas/loader.js

@@ -1,11 +1,18 @@
 import SwaggerParser from '@apidevtools/swagger-parser';
 // Cache loaded specs to avoid re-parsing
 const specCache = new Map();
-export async function loadOAS(specPath, forceReload = false) {
+export async function loadOAS(specPath, optionsOrForceReload = {}) {
+    // Back-compat: a bare boolean used to mean `forceReload`.
+    const options = typeof optionsOrForceReload === 'boolean'
+        ? { forceReload: optionsOrForceReload }
+        : optionsOrForceReload;
+    const { forceReload = false, allowExternalRefs = false } = options;
     if (!forceReload && specCache.has(specPath)) {
         return specCache.get(specPath);
     }
-    const api = await SwaggerParser.dereference(specPath);
+    // Default-deny external reference resolution to prevent SSRF / remote fetches.
+    const parserOptions = allowExternalRefs ? {} : { resolve: { external: false } };
+    const api = (await SwaggerParser.dereference(specPath, parserOptions));
     const baseUrl = extractBaseUrl(api);
     const operations = extractOperations(api);
     const schemas = extractSchemas(api);
@@ -20,10 +27,25 @@ export async function loadOAS(specPath, forceReload = false) {
 }
 function extractBaseUrl(spec) {
     if (spec.servers && spec.servers.length > 0) {
-        return spec.servers[0].url;
+        return resolveServerUrl(spec.servers[0]);
     }
     return '';
 }
+/**
+ * Resolve `{variable}` templating in a server URL using each variable's
+ * declared default. A template variable with no default is rejected rather
+ * than left raw (a raw `{var}` would otherwise be sent as part of request
+ * URLs).
+ */
+function resolveServerUrl(server) {
+    return server.url.replace(/\{([^{}]+)\}/g, (_match, name) => {
+        const variable = server.variables?.[name];
+        if (variable && variable.default !== undefined && variable.default !== '') {
+            return String(variable.default);
+        }
+        throw new Error(`OAS server URL variable '{${name}}' has no default value (in "${server.url}")`);
+    });
+}
 function extractOperations(spec) {
     const operations = new Map();
     if (!spec.paths)