pi-app-server 0.1.0

package/dist/extension-ui.js

@@ -0,0 +1,189 @@
+function isSelectResponse(r) {
+  return r.method === "select";
+}
+function isConfirmResponse(r) {
+  return r.method === "confirm";
+}
+function isInputResponse(r) {
+  return r.method === "input";
+}
+function isEditorResponse(r) {
+  return r.method === "editor";
+}
+const DEFAULT_MAX_PENDING_REQUESTS = 1e3;
+class ExtensionUIManager {
+  pendingRequests = /* @__PURE__ */ new Map();
+  defaultTimeoutMs;
+  maxPendingRequests;
+  rejectedCount = 0;
+  // Broadcast function - will be wired up in Phase 3
+  broadcast;
+  constructor(broadcast, defaultTimeoutMs = 6e4, maxPendingRequests = DEFAULT_MAX_PENDING_REQUESTS) {
+    this.broadcast = broadcast;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+    this.maxPendingRequests = maxPendingRequests;
+  }
+  /**
+   * Check if a new pending request would exceed the limit.
+   * Use this to check before calling createPendingRequest if you need to
+   * distinguish limit reached from other failure modes.
+   */
+  wouldExceedLimit() {
+    return this.pendingRequests.size >= this.maxPendingRequests;
+  }
+  /**
+   * Handle a UI request from an extension.
+   * This is called by our ExtensionUIContext implementation.
+   * Returns the requestId and a promise that resolves when client responds.
+   *
+   * Returns null if the pending request limit has been reached.
+   */
+  createPendingRequest(sessionId, method, requestData) {
+    if (this.pendingRequests.size >= this.maxPendingRequests) {
+      this.rejectedCount++;
+      console.error(
+        `[ExtensionUIManager] Pending request limit reached (${this.maxPendingRequests}), rejecting request for session ${sessionId}`
+      );
+      return null;
+    }
+    const requestId = this.generateRequestId(sessionId);
+    const timeoutMs = typeof requestData.timeout === "number" && Number.isFinite(requestData.timeout) && requestData.timeout > 0 ? requestData.timeout : this.defaultTimeoutMs;
+    const promise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const pending = this.pendingRequests.get(requestId);
+        if (!pending || pending.settled) return;
+        pending.settled = true;
+        this.pendingRequests.delete(requestId);
+        reject(new Error(`Extension UI request ${requestId} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      if (timeout.unref) {
+        timeout.unref();
+      }
+      this.pendingRequests.set(requestId, {
+        sessionId,
+        requestId,
+        method,
+        resolve,
+        reject,
+        timeout,
+        createdAt: /* @__PURE__ */ new Date(),
+        settled: false
+      });
+    });
+    return { requestId, promise };
+  }
+  /**
+   * Broadcast a UI request to clients.
+   */
+  broadcastUIRequest(sessionId, requestId, method, data) {
+    this.broadcast(sessionId, {
+      type: "extension_ui_request",
+      requestId,
+      method,
+      ...data
+    });
+  }
+  /**
+   * Handle a response from a client to a pending UI request.
+   * Returns true if the response was handled, false if no pending request found.
+   */
+  handleUIResponse(command) {
+    const pending = this.pendingRequests.get(command.requestId);
+    if (!pending) {
+      return {
+        success: false,
+        error: `No pending UI request with id ${command.requestId}`
+      };
+    }
+    if (pending.settled) {
+      return {
+        success: false,
+        error: `Request ${command.requestId} already settled`
+      };
+    }
+    if (pending.sessionId !== command.sessionId) {
+      return {
+        success: false,
+        error: `Session ID mismatch for request ${command.requestId}`
+      };
+    }
+    pending.settled = true;
+    clearTimeout(pending.timeout);
+    this.pendingRequests.delete(command.requestId);
+    pending.resolve(command.response);
+    return { success: true };
+  }
+  /**
+   * Get all pending requests for a session (for debugging/cleanup).
+   */
+  getPendingRequests(sessionId) {
+    const requests = [];
+    for (const pending of this.pendingRequests.values()) {
+      if (pending.sessionId === sessionId) {
+        requests.push(pending);
+      }
+    }
+    return requests;
+  }
+  /**
+   * Cancel all pending requests for a session (e.g., when session is deleted).
+   */
+  cancelSessionRequests(sessionId) {
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      if (pending.sessionId === sessionId && !pending.settled) {
+        pending.settled = true;
+        clearTimeout(pending.timeout);
+        pending.reject(new Error(`Session ${sessionId} was deleted`));
+        this.pendingRequests.delete(requestId);
+      }
+    }
+  }
+  /**
+   * Cancel a specific pending request (e.g., on abort signal).
+   */
+  cancelRequest(requestId) {
+    const pending = this.pendingRequests.get(requestId);
+    if (pending && !pending.settled) {
+      pending.settled = true;
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(`Request ${requestId} was cancelled`));
+      this.pendingRequests.delete(requestId);
+    }
+  }
+  /**
+   * Get count of pending requests (for monitoring).
+   */
+  getPendingCount() {
+    return this.pendingRequests.size;
+  }
+  /**
+   * Get full statistics about the manager (for monitoring).
+   */
+  getStats() {
+    return {
+      pendingCount: this.pendingRequests.size,
+      maxPendingRequests: this.maxPendingRequests,
+      rejectedCount: this.rejectedCount
+    };
+  }
+  /**
+   * Reset rejected count (for testing).
+   */
+  resetStats() {
+    this.rejectedCount = 0;
+  }
+  // ===========================================================================
+  // PRIVATE
+  // ===========================================================================
+  generateRequestId(sessionId) {
+    return `${sessionId}:${Date.now()}:${Math.random().toString(36).substring(2, 9)}`;
+  }
+}
+export {
+  ExtensionUIManager,
+  isConfirmResponse,
+  isEditorResponse,
+  isInputResponse,
+  isSelectResponse
+};
+//# sourceMappingURL=extension-ui.js.map

package/dist/extension-ui.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/extension-ui.ts"],
+  "sourcesContent": ["/**\n * Extension UI - tracks pending UI requests from extensions and routes responses.\n *\n * NOTE: Extension UI requests are NOT AgentSessionEvents. They come through\n * the ExtensionUIContext interface which must be provided when binding extensions.\n *\n * This module provides:\n * - Types for extension UI commands/responses\n * - ExtensionUIManager for tracking pending requests (used when we provide our own UIContext)\n *\n * Phase 3 will wire this up by providing a custom ExtensionUIContext to bindExtensions().\n */\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\nexport interface PendingUIRequest {\n  sessionId: string;\n  requestId: string;\n  method: ExtensionUIMethod;\n  resolve: (response: ExtensionUIResponseValue) => void;\n  reject: (error: Error) => void;\n  timeout: NodeJS.Timeout;\n  createdAt: Date;\n  /** Guard flag to prevent double-resolve on race between timeout and cancel */\n  settled: boolean;\n}\n\nexport type ExtensionUIMethod =\n  | \"select\"\n  | \"confirm\"\n  | \"input\"\n  | \"editor\"\n  | \"interview\"\n  | \"notify\"\n  | \"setStatus\"\n  | \"setWidget\"\n  | \"setTitle\";\n\nexport type ExtensionUIResponseValue =\n  | { method: \"select\"; value: string }\n  | { method: \"confirm\"; confirmed: boolean }\n  | { method: \"input\"; value: string }\n  | { method: \"editor\"; value: string }\n  | { method: \"interview\"; responses: Record<string, any> }\n  | { method: \"cancelled\" };\n\n// Type guards for response types\nexport function isSelectResponse(\n  r: ExtensionUIResponseValue\n): r is { method: \"select\"; value: string } {\n  return r.method === \"select\";\n}\n\nexport function isConfirmResponse(\n  r: ExtensionUIResponseValue\n): r is { method: \"confirm\"; confirmed: boolean } {\n  return r.method === \"confirm\";\n}\n\nexport function isInputResponse(\n  r: ExtensionUIResponseValue\n): r is { method: \"input\"; value: string } {\n  return r.method === \"input\";\n}\n\nexport function isEditorResponse(\n  r: ExtensionUIResponseValue\n): r is { method: \"editor\"; value: string } {\n  return r.method === \"editor\";\n}\n\n// Command from client to respond to UI request\nexport interface ExtensionUIResponseCommand {\n  id?: string;\n  sessionId: string;\n  type: \"extension_ui_response\";\n  requestId: string;\n  response: ExtensionUIResponseValue;\n}\n\n// =============================================================================\n// EXTENSION UI MANAGER\n// =============================================================================\n\n/** Default maximum pending UI requests per manager. */\nconst DEFAULT_MAX_PENDING_REQUESTS = 1000;\n\n/**\n * Statistics about the extension UI manager.\n */\nexport interface ExtensionUIManagerStats {\n  /** Current number of pending requests. */\n  pendingCount: number;\n  /** Maximum pending requests allowed. */\n  maxPendingRequests: number;\n  /** Total requests rejected due to limit. */\n  rejectedCount: number;\n}\n\nexport class ExtensionUIManager {\n  private pendingRequests = new Map<string, PendingUIRequest>();\n  private defaultTimeoutMs: number;\n  private maxPendingRequests: number;\n  private rejectedCount = 0;\n  // Broadcast function - will be wired up in Phase 3\n  private broadcast: (sessionId: string, event: any) => void;\n\n  constructor(\n    broadcast: (sessionId: string, event: any) => void,\n    defaultTimeoutMs: number = 60000,\n    maxPendingRequests: number = DEFAULT_MAX_PENDING_REQUESTS\n  ) {\n    this.broadcast = broadcast;\n    this.defaultTimeoutMs = defaultTimeoutMs;\n    this.maxPendingRequests = maxPendingRequests;\n  }\n\n  /**\n   * Check if a new pending request would exceed the limit.\n   * Use this to check before calling createPendingRequest if you need to\n   * distinguish limit reached from other failure modes.\n   */\n  wouldExceedLimit(): boolean {\n    return this.pendingRequests.size >= this.maxPendingRequests;\n  }\n\n  /**\n   * Handle a UI request from an extension.\n   * This is called by our ExtensionUIContext implementation.\n   * Returns the requestId and a promise that resolves when client responds.\n   *\n   * Returns null if the pending request limit has been reached.\n   */\n  createPendingRequest(\n    sessionId: string,\n    method: ExtensionUIMethod,\n    requestData: Record<string, any>\n  ): { requestId: string; promise: Promise<ExtensionUIResponseValue> } | null {\n    // Check pending request limit to prevent memory exhaustion\n    if (this.pendingRequests.size >= this.maxPendingRequests) {\n      this.rejectedCount++;\n      console.error(\n        `[ExtensionUIManager] Pending request limit reached (${this.maxPendingRequests}), rejecting request for session ${sessionId}`\n      );\n      return null;\n    }\n\n    const requestId = this.generateRequestId(sessionId);\n    const timeoutMs =\n      typeof requestData.timeout === \"number\" &&\n      Number.isFinite(requestData.timeout) &&\n      requestData.timeout > 0\n        ? requestData.timeout\n        : this.defaultTimeoutMs;\n\n    const promise = new Promise<ExtensionUIResponseValue>((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        const pending = this.pendingRequests.get(requestId);\n        if (!pending || pending.settled) return; // Guard against race\n        pending.settled = true;\n        this.pendingRequests.delete(requestId);\n        reject(new Error(`Extension UI request ${requestId} timed out after ${timeoutMs}ms`));\n      }, timeoutMs);\n\n      // Don't prevent process exit if waiting for UI response\n      if (timeout.unref) {\n        timeout.unref();\n      }\n\n      this.pendingRequests.set(requestId, {\n        sessionId,\n        requestId,\n        method,\n        resolve,\n        reject,\n        timeout,\n        createdAt: new Date(),\n        settled: false,\n      });\n    });\n\n    return { requestId, promise };\n  }\n\n  /**\n   * Broadcast a UI request to clients.\n   */\n  broadcastUIRequest(\n    sessionId: string,\n    requestId: string,\n    method: ExtensionUIMethod,\n    data: Record<string, any>\n  ): void {\n    this.broadcast(sessionId, {\n      type: \"extension_ui_request\",\n      requestId,\n      method,\n      ...data,\n    });\n  }\n\n  /**\n   * Handle a response from a client to a pending UI request.\n   * Returns true if the response was handled, false if no pending request found.\n   */\n  handleUIResponse(command: ExtensionUIResponseCommand): { success: boolean; error?: string } {\n    const pending = this.pendingRequests.get(command.requestId);\n\n    if (!pending) {\n      return {\n        success: false,\n        error: `No pending UI request with id ${command.requestId}`,\n      };\n    }\n\n    // Guard against race with timeout/cancel\n    if (pending.settled) {\n      return {\n        success: false,\n        error: `Request ${command.requestId} already settled`,\n      };\n    }\n\n    // Verify sessionId matches\n    if (pending.sessionId !== command.sessionId) {\n      return {\n        success: false,\n        error: `Session ID mismatch for request ${command.requestId}`,\n      };\n    }\n\n    // Mark as settled, clear timeout and remove from pending\n    pending.settled = true;\n    clearTimeout(pending.timeout);\n    this.pendingRequests.delete(command.requestId);\n\n    // Resolve the promise\n    pending.resolve(command.response);\n\n    return { success: true };\n  }\n\n  /**\n   * Get all pending requests for a session (for debugging/cleanup).\n   */\n  getPendingRequests(sessionId: string): PendingUIRequest[] {\n    const requests: PendingUIRequest[] = [];\n    for (const pending of this.pendingRequests.values()) {\n      if (pending.sessionId === sessionId) {\n        requests.push(pending);\n      }\n    }\n    return requests;\n  }\n\n  /**\n   * Cancel all pending requests for a session (e.g., when session is deleted).\n   */\n  cancelSessionRequests(sessionId: string): void {\n    for (const [requestId, pending] of this.pendingRequests.entries()) {\n      if (pending.sessionId === sessionId && !pending.settled) {\n        pending.settled = true;\n        clearTimeout(pending.timeout);\n        pending.reject(new Error(`Session ${sessionId} was deleted`));\n        this.pendingRequests.delete(requestId);\n      }\n    }\n  }\n\n  /**\n   * Cancel a specific pending request (e.g., on abort signal).\n   */\n  cancelRequest(requestId: string): void {\n    const pending = this.pendingRequests.get(requestId);\n    if (pending && !pending.settled) {\n      pending.settled = true;\n      clearTimeout(pending.timeout);\n      pending.reject(new Error(`Request ${requestId} was cancelled`));\n      this.pendingRequests.delete(requestId);\n    }\n  }\n\n  /**\n   * Get count of pending requests (for monitoring).\n   */\n  getPendingCount(): number {\n    return this.pendingRequests.size;\n  }\n\n  /**\n   * Get full statistics about the manager (for monitoring).\n   */\n  getStats(): ExtensionUIManagerStats {\n    return {\n      pendingCount: this.pendingRequests.size,\n      maxPendingRequests: this.maxPendingRequests,\n      rejectedCount: this.rejectedCount,\n    };\n  }\n\n  /**\n   * Reset rejected count (for testing).\n   */\n  resetStats(): void {\n    this.rejectedCount = 0;\n  }\n\n  // ===========================================================================\n  // PRIVATE\n  // ===========================================================================\n\n  private generateRequestId(sessionId: string): string {\n    return `${sessionId}:${Date.now()}:${Math.random().toString(36).substring(2, 9)}`;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/resource-governor.d.ts

@@ -0,0 +1,254 @@
+/**
+ * ResourceGovernor - Enforces all resource limits for pi-server.
+ *
+ * A single nexus point for:
+ * - Message size limits (prevents OOM)
+ * - Session limits (prevents resource exhaustion)
+ * - Rate limiting (prevents abuse)
+ * - Heartbeat tracking (enables zombie detection)
+ * - Connection limits (prevents DoS)
+ *
+ * Makes testing trivial (mock the governor).
+ */
+import type { MetricsEmitter } from "./metrics-emitter.js";
+export interface ResourceGovernorConfig {
+    /** Maximum concurrent sessions (default: 100) */
+    maxSessions: number;
+    /** Maximum message size in bytes (default: 10MB) */
+    maxMessageSizeBytes: number;
+    /** Maximum commands per minute per session (default: 100) */
+    maxCommandsPerMinute: number;
+    /** Maximum commands per minute globally across all sessions (default: 1000) */
+    maxGlobalCommandsPerMinute: number;
+    /** Maximum concurrent WebSocket connections (default: 1000) */
+    maxConnections: number;
+    /** Heartbeat interval in ms for zombie detection (default: 30000) */
+    heartbeatIntervalMs: number;
+    /** Time without heartbeat before session is considered zombie (default: 5 min) */
+    zombieTimeoutMs: number;
+    /** Maximum extension_ui_response commands per minute per session (default: 60) */
+    maxExtensionUIResponsePerMinute: number;
+    /** Maximum session lifetime in ms (0 = unlimited, default: 24 hours) */
+    maxSessionLifetimeMs: number;
+}
+export declare const DEFAULT_CONFIG: ResourceGovernorConfig;
+export interface GovernorMetrics {
+    sessionCount: number;
+    connectionCount: number;
+    totalCommandsExecuted: number;
+    commandsRejected: {
+        sessionLimit: number;
+        messageSize: number;
+        rateLimit: number;
+        globalRateLimit: number;
+        connectionLimit: number;
+        extensionUIResponseRateLimit: number;
+    };
+    zombieSessionsDetected: number;
+    zombieSessionsCleaned: number;
+    /** Count of double-unregister errors (session or connection unregistered twice) */
+    doubleUnregisterErrors: number;
+    rateLimitUsage: {
+        globalCount: number;
+        globalLimit: number;
+    };
+}
+export interface RejectionResult {
+    allowed: false;
+    reason: string;
+}
+export interface AllowResult {
+    allowed: true;
+}
+export type GovernorResult = AllowResult | RejectionResult;
+/**
+ * ResourceGovernor enforces resource limits for the server.
+ *
+ * Memory management:
+ * - Rate limit timestamps are cleaned up periodically via startPeriodicCleanup()
+ * - Session-specific data is cleaned up when sessions are deleted
+ * - Call cleanupStaleData() after deleting sessions
+ */
+export declare class ResourceGovernor {
+    private config;
+    private metrics?;
+    private sessionCount;
+    private connectionCount;
+    private commandTimestamps;
+    private globalCommandTimestamps;
+    private extensionUIResponseTimestamps;
+    private lastHeartbeat;
+    private sessionCreatedAt;
+    private totalCommandsExecuted;
+    private commandsRejected;
+    private zombieSessionsDetected;
+    private zombieSessionsCleaned;
+    private doubleUnregisterErrors;
+    /** Generation counter for unique rate limit entry IDs */
+    private generationCounter;
+    /** Periodic cleanup timer for stale timestamps */
+    private cleanupTimer;
+    constructor(config?: ResourceGovernorConfig, metrics?: MetricsEmitter | undefined);
+    /**
+     * Set the metrics emitter for monitoring.
+     * Can be called after construction to wire up metrics.
+     */
+    setMetrics(metrics: MetricsEmitter): void;
+    /**
+     * Increment generation counter and emit metric.
+     * Used for unique rate limit entry IDs and overflow monitoring.
+     */
+    private nextGeneration;
+    getConfig(): Readonly<ResourceGovernorConfig>;
+    /**
+     * Validate a session ID.
+     * Returns null if valid, or an error message if invalid.
+     */
+    validateSessionId(sessionId: string): string | null;
+    /**
+     * Validate a working directory path.
+     * Returns null if valid, or an error message if invalid.
+     */
+    validateCwd(cwd: string): string | null;
+    /**
+     * Atomically check and reserve a session slot.
+     * Returns true if slot was reserved, false if limit reached.
+     */
+    tryReserveSessionSlot(): boolean;
+    /**
+     * Release a reserved session slot (used if session creation fails after reservation).
+     * Tracks double-unregister as error metric instead of silently masking.
+     */
+    releaseSessionSlot(): void;
+    /**
+     * Check if a new session can be created.
+     * @deprecated Use tryReserveSessionSlot for atomic operation. Will be removed in v2.0.0.
+     */
+    canCreateSession(): GovernorResult;
+    /**
+     * Register a new session.
+     * @deprecated Use tryReserveSessionSlot for atomic operation. Will be removed in v2.0.0.
+     */
+    registerSession(sessionId: string): void;
+    /**
+     * Unregister a session. Call AFTER session is deleted.
+     * Also cleans up rate limit timestamps for this session.
+     */
+    unregisterSession(sessionId: string): void;
+    /**
+     * Get current session count.
+     */
+    getSessionCount(): number;
+    /**
+     * Check if a new connection can be accepted.
+     */
+    canAcceptConnection(): GovernorResult;
+    /**
+     * Register a new connection.
+     */
+    registerConnection(): void;
+    /**
+     * Unregister a connection.
+     * Tracks double-unregister as error metric instead of silently masking.
+     */
+    unregisterConnection(): void;
+    /**
+     * Get current connection count.
+     */
+    getConnectionCount(): number;
+    /**
+     * Check if a message of the given size can be accepted.
+     * Rejects negative sizes, NaN, and sizes exceeding the limit.
+     */
+    canAcceptMessage(sizeBytes: number): GovernorResult;
+    /**
+     * Check if a command can be executed for the given session.
+     * Implements sliding window rate limiting (both per-session and global).
+     *
+     * @returns The generation marker for refund, or rejection result
+     */
+    canExecuteCommand(sessionId: string): GovernorResult & {
+        generation?: number;
+    };
+    /**
+     * Refund a previously counted command (e.g. command failed before execution).
+     * Uses generation marker to ensure correct entry is removed.
+     */
+    refundCommand(sessionId: string, generation: number): void;
+    /**
+     * Get current rate limit usage for observability.
+     */
+    getRateLimitUsage(sessionId: string): {
+        session: number;
+        global: number;
+    };
+    /**
+     * Check if an extension_ui_response command can be executed for the given session.
+     * This is a separate, more restrictive rate limit to prevent abuse of UI responses.
+     */
+    canExecuteExtensionUIResponse(sessionId: string): GovernorResult;
+    /**
+     * Record a heartbeat for a session.
+     * Also tracks session creation time for lifetime enforcement.
+     */
+    recordHeartbeat(sessionId: string): void;
+    /**
+     * Get list of zombie session IDs.
+     *
+     * @param recordDetection Whether to increment zombie detection metrics.
+     */
+    getZombieSessions(recordDetection?: boolean): string[];
+    /**
+     * Clean up zombie sessions. Returns IDs of cleaned sessions.
+     * Call this periodically or when you want to force cleanup.
+     */
+    cleanupZombieSessions(): string[];
+    /**
+     * Get the last heartbeat time for a session.
+     */
+    getLastHeartbeat(sessionId: string): number | undefined;
+    /**
+     * Get current metrics for observability.
+     */
+    getMetrics(): GovernorMetrics;
+    /**
+     * Check if the server is healthy.
+     */
+    isHealthy(): {
+        healthy: boolean;
+        issues: string[];
+    };
+    /**
+     * Reset metrics (useful for testing).
+     */
+    resetMetrics(): void;
+    /**
+     * Clean up stale rate limit data.
+     * Also cleans extensionUIResponseTimestamps.
+     */
+    cleanupStaleTimestamps(): void;
+    /**
+     * Start periodic cleanup of stale timestamps.
+     * Call this during server startup to prevent memory leaks from inactive sessions.
+     * @param intervalMs Cleanup interval (default: 5 minutes)
+     */
+    startPeriodicCleanup(intervalMs?: number): void;
+    /**
+     * Stop periodic cleanup.
+     */
+    stopPeriodicCleanup(): void;
+    /**
+     * Clean up stale data for deleted sessions.
+     */
+    cleanupStaleData(activeSessionIds: Set<string>): void;
+    /**
+     * Get list of expired session IDs (exceeded maxSessionLifetimeMs).
+     * Returns empty array if maxSessionLifetimeMs is 0 (unlimited).
+     */
+    getExpiredSessions(): string[];
+    /**
+     * Get the creation time for a session.
+     */
+    getSessionCreatedAt(sessionId: string): number | undefined;
+}
+//# sourceMappingURL=resource-governor.d.ts.map

package/dist/resource-governor.d.ts.map

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