@http-forge/core 0.4.6 → 0.4.8

package/dist/infrastructure/auth/oauth2-token-manager.d.ts

@@ -14,9 +14,9 @@
  * is injected via IExternalBrowserService and ISecretStore interfaces.
  */
 import { IEnvironmentConfigService } from '../../types/environment-config';
-import { IHttpRequestService } from '../http/interfaces';
 import { IExternalBrowserService, ISecretStore } from '../../types/platform';
 import { OAuth2Config } from '../../types/types';
+import { IHttpRequestService } from '../http/interfaces';
 import { IOAuth2TokenManager, TokenCacheKey, TokenInfo } from './interfaces';
 export declare class OAuth2TokenManager implements IOAuth2TokenManager {
     private readonly secretStore;

package/dist/infrastructure/config/config-service.d.ts

@@ -66,6 +66,7 @@ export declare class ConfigService implements IConfigService {
     getSuitesPath(): string;
     getModulePaths(): string[];
     getScriptScope(): 'shared' | 'isolated';
+    getScriptTimeout(): number;
     getWorkspacePath(): string;
     reload(): void;
     configExists(): boolean;

package/dist/infrastructure/config/config.interface.d.ts

@@ -44,6 +44,12 @@ export interface ScriptsConfig {
      *   must pass through pm.variables / pm.environment / pm.globals.
      */
     scope?: 'shared' | 'isolated';
+    /**
+     * Per-script timeout in milliseconds (default 5000). Bounds both the synchronous
+     * script CPU guard and the async event-loop drain budget (pending setTimeout /
+     * un-awaited Promises) that the runner waits on before advancing to the next request.
+     */
+    timeout?: number;
 }
 /**
  * Runner configuration
@@ -212,6 +218,8 @@ export interface IConfigService {
     getModulePaths(): string[];
     /** Get the script scope mode ('shared' default, or 'isolated' for Postman parity) */
     getScriptScope(): 'shared' | 'isolated';
+    /** Get the per-script timeout in milliseconds (default 5000) */
+    getScriptTimeout(): number;
     /** Get the workspace root path */
     getWorkspacePath(): string;
     /** Reload configuration from disk */

package/dist/infrastructure/environment/variable-interpolator.d.ts

@@ -37,10 +37,19 @@ export interface VariableResolverConfig {
  */
 export declare class VariableResolver {
     private readonly allVariables;
+    /**
+     * Maximum nesting depth for recursive {{var}} resolution.
+     * Postman-compatible cap that guards against reference cycles
+     * (e.g. a -> {{b}}, b -> {{a}}).
+     */
+    private static readonly MAX_RESOLUTION_DEPTH;
     constructor(config: VariableResolverConfig);
     /**
      * Resolve variables in a string ({{varName}} syntax)
-     * Uses the full 5-step pipeline with optional escaping for quoted strings
+     * Uses the full 5-step pipeline with optional escaping for quoted strings.
+     * Nested references — a variable whose value itself contains {{...}} — are
+     * resolved recursively (Postman-style) by repeating the substitution until
+     * the string stabilizes or the depth cap is reached.
      */
     resolveString(str: string, escape?: boolean): string;
     /**
@@ -48,6 +57,20 @@ export declare class VariableResolver {
      * Extra variables take highest precedence
      */
     resolveStringWithExtra(str: string, extraVariables: Record<string, string>, escape?: boolean): string;
+    /**
+     * Repeatedly apply a single substitution pass until the result stops changing
+     * (fixed point) or the nesting depth cap is hit. This resolves variable values
+     * that themselves contain {{...}} references. Undefined tokens are left as-is,
+     * so a pass that resolves nothing produces no change and terminates the loop;
+     * the depth cap guards against reference cycles (a -> {{b}}, b -> {{a}}).
+     */
+    private resolveUntilStable;
+    /**
+     * Single substitution pass over a string using the 5-step pipeline.
+     * With escaping enabled, resolved values are escaped for their surrounding
+     * quote context.
+     */
+    private resolveSinglePass;
     /**
      * Resolve variables in an object recursively
      */

package/dist/infrastructure/execution/request-executor.d.ts

@@ -62,6 +62,7 @@ export declare class RequestExecutor {
         forgeRoot?: string;
         scriptExecutor?: IScriptExecutor;
         scriptScope?: 'shared' | 'isolated';
+        scriptTimeout?: number;
     });
     /**
      * Execute a request with full pipeline

package/dist/infrastructure/script/async-drain.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Async Drain — Postman-compatible event-loop draining for script sandboxes
+ *
+ * Postman/Newman keep a script's sandbox alive after its synchronous body returns,
+ * pumping the event loop until all pending timers (`setTimeout`/`setInterval`) and
+ * microtasks (un-awaited Promises) have settled — bounded by a script timeout. Only
+ * then does the runner advance, committing any variable mutations made by those late
+ * callbacks so the next request can see them.
+ *
+ * This module provides an instrumented timer set plus a `drain()` loop that replicates
+ * that behavior. The timers wrap the real Node timers, track outstanding handles, and
+ * swallow errors thrown inside deferred callbacks (reporting them as non-fatal) so a
+ * late failure never rejects the surrounding request — matching Postman, where such
+ * callbacks run on a later tick outside the script's try/catch.
+ */
+/** Sandbox-facing timer functions, drop-in replacements for the Node globals. */
+export interface SandboxTimers {
+    setTimeout: (handler: (...args: any[]) => void, timeout?: number, ...args: any[]) => any;
+    clearTimeout: (handle: any) => void;
+    setInterval: (handler: (...args: any[]) => void, timeout?: number, ...args: any[]) => any;
+    clearInterval: (handle: any) => void;
+}
+/** Result of a drain operation. */
+export interface DrainResult {
+    /** True if the timeout cap was hit while timers were still pending. */
+    timedOut: boolean;
+    /** Approximate wall-clock time spent draining, in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * A registry of instrumented timers bound to a single script session.
+ */
+export interface TimerRegistry {
+    /** Timer functions to expose inside the VM sandbox. */
+    readonly timers: SandboxTimers;
+    /** Number of timers still pending (not yet fired or cleared, or active intervals). */
+    pendingCount(): number;
+    /** Cancel every outstanding timer. Used at the drain cap and on dispose. */
+    clearAll(): void;
+    /**
+     * Pump the event loop until no timers are pending (and a final microtask flush
+     * yields nothing new) or until `timeoutMs` of wall-clock time elapses, whichever
+     * comes first. On timeout, all remaining timers are force-cleared.
+     */
+    drain(timeoutMs: number): Promise<DrainResult>;
+}
+/**
+ * Create a timer registry whose deferred-callback errors are routed to `onTimerError`.
+ *
+ * @param onTimerError Invoked (never throws) when a timer callback throws. The error is
+ *                     swallowed relative to the request so the run continues.
+ */
+export declare function createTimerRegistry(onTimerError: (error: unknown) => void): TimerRegistry;

package/dist/infrastructure/script/interfaces.d.ts

@@ -49,6 +49,7 @@ export interface ResponseContext {
     status: number;
     statusText: string;
     headers: Record<string, string>;
+    /** Raw response body string (Postman-compatible). Parse on demand via response.json(). */
     body: any;
     cookies?: Record<string, string>;
     responseTime?: number;

package/dist/infrastructure/script/request-script-session.d.ts

@@ -8,16 +8,22 @@
  * This matches Postman's behavior for per-request script execution.
  */
 import * as vm from 'vm';
+import { SandboxTimers } from './async-drain';
 import { CommonScriptContext, IRequestScriptSession, PostResponseScriptResult, PreRequestScriptContext, PreRequestScriptResult, ResponseContext } from './interfaces';
 /**
  * Dependencies injected from ScriptExecutor
  * Interface Segregation: Only the methods needed by the session
  */
 export interface SessionDependencies {
-    createVM: (ctx: any, scriptConsole: any) => vm.Context;
+    createVM: (ctx: any, scriptConsole: any, timers?: SandboxTimers) => vm.Context;
     createCommonContext: (context: CommonScriptContext, eventName: 'prerequest' | 'test') => any;
     /** When true, each script level runs in its own scope (Postman-compatible). */
     isolateScripts?: boolean;
+    /**
+     * Per-script timeout in milliseconds. Bounds BOTH the synchronous VM CPU guard and
+     * the async event-loop drain budget (pending timers / un-awaited Promises).
+     */
+    scriptTimeoutMs?: number;
 }
 /**
  * Request Script Session Implementation
@@ -43,6 +49,7 @@ export declare class RequestScriptSession implements IRequestScriptSession {
     private _nextRequest;
     private _skipRequest;
     private _visualizerData;
+    private readonly timerRegistry;
     constructor(deps: SessionDependencies, initialContext: PreRequestScriptContext);
     /**
      * Initialize the shared VM context
@@ -57,6 +64,19 @@ export declare class RequestScriptSession implements IRequestScriptSession {
      * Maps HTTP Forge body types to Postman modes for script API compatibility
      */
     private createRequestObject;
+    /**
+     * Inject the legacy (pre-`pm.*`) Postman/Newman sandbox globals into the VM context.
+     *
+     * Older Postman scripts (and many Newman-exported collections) rely on bare globals
+     * that the modern `pm.*` sandbox no longer injects. Evaluating them (e.g. `request.name`,
+     * `responseCode.code`, `tv4.validate(...)`) otherwise throws `ReferenceError`.
+     *
+     * Available in BOTH phases: `request`, `environment`, `globals`, `data`, `iteration`.
+     * Available in the TEST phase only: `responseBody`, `responseCode`, `responseHeaders`,
+     * `responseTime`, `responseCookies`, `tests`, plus `postman.getResponseHeader()` /
+     * `postman.getResponseCookie()`.
+     */
+    private injectLegacyGlobals;
     /**
      * Execute pre-request scripts in the shared session
      */

package/dist/infrastructure/script/script-executor.d.ts

@@ -23,8 +23,9 @@ export declare class ScriptExecutor implements IScriptExecutor {
     private readonly httpService?;
     private readonly secretRegistry?;
     private readonly scopeMode;
+    private readonly scriptTimeoutMs;
     private readonly moduleLoader;
-    constructor(httpService?: IHttpRequestService | undefined, modulePaths?: string[], secretRegistry?: SecretResolverRegistry | undefined, scopeMode?: 'shared' | 'isolated');
+    constructor(httpService?: IHttpRequestService | undefined, modulePaths?: string[], secretRegistry?: SecretResolverRegistry | undefined, scopeMode?: 'shared' | 'isolated', scriptTimeoutMs?: number);
     /**
      * Create a request execution session
      * Factory method implementing IScriptExecutor
@@ -33,6 +34,10 @@ export declare class ScriptExecutor implements IScriptExecutor {
     /**
      * Create VM context with sandbox configuration
      * Returns a context object that can be used with vm.runInContext()
+     *
+     * @param timers Optional instrumented timer set. When provided, the sandbox uses
+     *               these instead of the Node globals so the session can track and
+     *               drain pending timers (Postman-compatible async behavior).
      */
     private createVM;
     /**

package/dist/infrastructure/script/script-factories.d.ts

@@ -22,6 +22,7 @@ export interface ScriptResponse {
     code: number;
     statusText: string;
     headers: Record<string, string>;
+    /** Raw response body string (Postman-compatible). Use json() to parse, text() for the string. */
     body: any;
     cookies: Record<string, string>;
     responseTime?: number;

package/dist/runtime/mcp-tool-name.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared MCP tool-name encoding / decoding.
+ *
+ * MCP tool names must stay under Anthropic's 128-character limit. HTTP Forge
+ * IDs embed the human-readable entity name (up to ~100 chars each), so a raw
+ * tool name like `request__<collectionId>__<requestId>` can exceed 240 chars
+ * and be rejected by the model provider.
+ *
+ * To stay short we put a deterministic short hash token (not the raw ID) in the
+ * tool name, and resolve a call back to the real entity by hashing the current
+ * collections / requests / folders / suites and matching. A raw-value fallback
+ * keeps any previously-listed long names working after the upgrade.
+ *
+ * IDs are NOT changed — they remain the stable external references used by
+ * suites, result filenames, and history. Only the tool *name* is shortened.
+ *
+ * The model selects a tool by its *description* (which still contains the
+ * human-readable names), so an opaque short name does not affect tool choice.
+ */
+/** Deterministic short token for an ID or folder path (12 hex chars). */
+export declare function mcpToolToken(value: string): string;
+export type McpToolKind = 'request' | 'collection' | 'folder' | 'suite';
+export declare function buildRequestToolName(prefix: string, collectionId: string, requestId: string): string;
+export declare function buildCollectionToolName(prefix: string, collectionId: string): string;
+export declare function buildFolderToolName(prefix: string, collectionId: string, folderPath: string): string;
+export declare function buildSuiteToolName(prefix: string, suiteId: string): string;
+export interface ParsedMcpToolName {
+    kind: McpToolKind;
+    tokens: string[];
+}
+/** Parse a tool name (prefix already stripped) into its kind + token segments. */
+export declare function parseMcpToolName(name: string): ParsedMcpToolName;
+/**
+ * Resolve a token back to one of `candidates` by matching its hash token, or
+ * (legacy fallback) the raw candidate value itself.
+ */
+export declare function resolveToken(token: string, candidates: readonly string[]): string | undefined;
+/**
+ * Resolve a folder token to a folder path. Adds a base64url legacy fallback for
+ * folder tool names emitted before hashing (which embedded base64url(path)).
+ */
+export declare function resolveFolderToken(token: string, folderPaths: readonly string[]): string | undefined;
+export declare function buildRequestToolDescription(method: string, requestName: string, collectionName: string, folderPath: string): string;
+export declare function buildCollectionToolDescription(collectionName: string, requestCount: number): string;
+export declare function buildFolderToolDescription(folderPath: string, collectionName: string, requestCount: number): string;
+export declare function buildSuiteToolDescription(suiteName: string, requestCount: number, iterations: number): string;

package/dist/runtime/mcp-tool-schemas.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared MCP tool input schemas.
+ *
+ * Both MCP server implementations (the embeddable core runtime and the VS Code
+ * extension) expose the same tools, so they must advertise identical input
+ * schemas. Keeping these in one place prevents the two sides from drifting
+ * (e.g. the extension previously omitted `iterations`/`delay`/`include` for
+ * collection and folder runs even though its executor supported them).
+ */
+export declare const REQUEST_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly environment: {
+            readonly type: "string";
+            readonly description: "Environment name to use (defaults to the currently selected environment)";
+        };
+        readonly variables: {
+            readonly type: "object";
+            readonly description: "Extra variables to inject — merged with environment variables, {{name}} syntax";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly headers: {
+            readonly type: "object";
+            readonly description: "Override or add request headers";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly query: {
+            readonly type: "object";
+            readonly description: "Override query parameters";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly body: {
+            readonly type: "string";
+            readonly description: "Replace the request body (JSON string). Omit to use the saved body.";
+        };
+        readonly include: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["headers", "cookies", "tests", "consoleOutput", "report"];
+            };
+            readonly description: "Extra fields to include in the response (default: status, ok, body, allPassed)";
+        };
+    };
+};
+export declare const COLLECTION_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly environment: {
+            readonly type: "string";
+            readonly description: "Environment name to use";
+        };
+        readonly variables: {
+            readonly type: "object";
+            readonly description: "Extra variables injected into every request";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly iterations: {
+            readonly type: "number";
+            readonly description: "Number of iterations (default: 1)";
+        };
+        readonly stopOnError: {
+            readonly type: "boolean";
+            readonly description: "Stop on first failure";
+        };
+        readonly delay: {
+            readonly type: "number";
+            readonly description: "Delay between requests in ms";
+        };
+        readonly include: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["perRequest", "failedOnly", "consoleOutput", "report"];
+            };
+            readonly description: "Result detail level";
+        };
+    };
+};
+export declare const FOLDER_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly environment: {
+            readonly type: "string";
+            readonly description: "Environment name to use";
+        };
+        readonly variables: {
+            readonly type: "object";
+            readonly description: "Extra variables injected into every request";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly iterations: {
+            readonly type: "number";
+            readonly description: "Number of iterations (default: 1)";
+        };
+        readonly stopOnError: {
+            readonly type: "boolean";
+            readonly description: "Stop on first failure";
+        };
+        readonly delay: {
+            readonly type: "number";
+            readonly description: "Delay between requests in ms";
+        };
+        readonly recursive: {
+            readonly type: "boolean";
+            readonly description: "Include requests in nested subfolders (default: true)";
+        };
+        readonly include: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["perRequest", "failedOnly", "consoleOutput", "report"];
+            };
+            readonly description: "Result detail level";
+        };
+    };
+};
+export declare const SUITE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly environment: {
+            readonly type: "string";
+            readonly description: "Environment name to use";
+        };
+        readonly iterations: {
+            readonly type: "number";
+            readonly description: "Number of iterations (overrides suite default)";
+        };
+        readonly stopOnError: {
+            readonly type: "boolean";
+            readonly description: "Stop on first failure";
+        };
+        readonly delay: {
+            readonly type: "number";
+            readonly description: "Delay between requests in ms";
+        };
+        readonly variables: {
+            readonly type: "object";
+            readonly description: "Extra variables injected into every request";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly requestFilter: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Run only requests whose names match one of these strings (case-insensitive)";
+        };
+        readonly include: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["perRequest", "failedOnly", "consoleOutput", "report"];
+            };
+            readonly description: "Result detail level (default: summary + failedRequests)";
+        };
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@http-forge/core",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Headless HTTP testing engine with Postman collection support, dynamic variables, and script-based automation.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",