@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/services/remote-signing-service.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Remote signing service. Private keys stay on the host;
+ * sandboxed agents submit unsigned tx → policy check → sign → return.
+ */
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import type { SandboxAuditLog } from "../security/audit-log.ts";
+import { type PolicyDecision, type SigningPolicy, type SigningRequest } from "./signing-policy.ts";
+import type { TeeEvidenceProvider } from "./tee-evidence.ts";
+import type { TeeEvidencePolicy } from "./tee-policy.ts";
+export interface SignerBackend {
+    getAddress(): Promise<string>;
+    signMessage(message: string): Promise<string>;
+    signTransaction(tx: UnsignedTransaction): Promise<string>;
+}
+export interface UnsignedTransaction {
+    to: string;
+    value: string;
+    data: string;
+    chainId: number;
+    nonce?: number;
+    gasLimit?: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+}
+export interface SigningResult {
+    success: boolean;
+    signature?: string;
+    error?: string;
+    policyDecision: PolicyDecision;
+    humanConfirmed: boolean;
+}
+export interface PendingApproval {
+    requestId: string;
+    request: SigningRequest;
+    decision: PolicyDecision;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface RemoteSigningServiceConfig {
+    signer: SignerBackend;
+    policy?: SigningPolicy;
+    auditLog?: SandboxAuditLog;
+    approvalTimeoutMs?: number;
+}
+export declare class RemoteSigningService {
+    private signer;
+    private policyEvaluator;
+    private auditLog?;
+    private pendingApprovals;
+    private approvalTimeoutMs;
+    constructor(config: RemoteSigningServiceConfig);
+    getAddress(): Promise<string>;
+    submitSigningRequest(request: SigningRequest): Promise<SigningResult>;
+    approveRequest(requestId: string): Promise<SigningResult>;
+    rejectRequest(requestId: string): boolean;
+    getPendingApprovals(): PendingApproval[];
+    updatePolicy(policy: SigningPolicy): void;
+    getPolicy(): SigningPolicy;
+    private executeSign;
+}
+export interface TeeGatedRemoteSigningConfig {
+    /** Inner signer that actually holds/uses the key (e.g. VaultSignerBackend). */
+    signer: SignerBackend;
+    /**
+     * TEE evidence policy resolved at boot (`TeeBootGate.policy`). When the
+     * policy requires trusted evidence, the signer is wrapped in
+     * `TeeSignerBackend` so every sign re-collects and re-evaluates evidence.
+     * When undefined or not required, no attestation is required — the inner
+     * signer is used directly (inert, normal behavior).
+     */
+    teePolicy?: TeeEvidencePolicy;
+    /** Evidence provider for per-sign re-attestation. Required when teePolicy.required. */
+    evidenceProvider?: TeeEvidenceProvider;
+    policy?: SigningPolicy;
+    auditLog?: SandboxAuditLog;
+    approvalTimeoutMs?: number;
+}
+/**
+ * Build a `RemoteSigningService` whose signer is gated on the TEE boot-gate
+ * state and (when a TEE policy requires it) re-attests on every sign.
+ *
+ * Fail-closed: if `teeBootGateBlocksSecrets()` is true (a required gate whose
+ * evidence was not trusted at boot), this refuses to construct the service so
+ * no signing path can come online. When the boot gate is inert (no TEE
+ * configured / not required), construction proceeds and signing behaves
+ * exactly as it did before TEE gating — no attestation requirement.
+ */
+export declare function createTeeGatedRemoteSigningService(config: TeeGatedRemoteSigningConfig): RemoteSigningService;
+/**
+ * elizaOS runtime service wrapper exposing a TEE-gated `RemoteSigningService`
+ * to the host↔guest capability bridge (plan §4.3). The host can request a
+ * signature via `runtime.getService("remote-signing")`, but the key never
+ * leaves the domain and every sign re-attests when a TEE policy requires it.
+ *
+ * Activation is the caller's responsibility: the boot path constructs and
+ * registers this ONLY when remote signing is explicitly enabled. The service
+ * is never started by the runtime's plugin auto-discovery.
+ */
+export declare class RemoteSigningRuntimeService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private signing;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    stop(): Promise<void>;
+    /** Attach the built signing service. Called once by the boot path. */
+    attach(signing: RemoteSigningService): void;
+    /** The active signing service, or undefined before boot attaches it. */
+    get service(): RemoteSigningService | undefined;
+}
+//# sourceMappingURL=remote-signing-service.d.ts.map

package/services/remote-signing-service.d.ts.map

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

package/services/remote-signing-service.js

@@ -0,0 +1,264 @@
+/**
+ * Remote signing service. Private keys stay on the host;
+ * sandboxed agents submit unsigned tx → policy check → sign → return.
+ */
+import { logger, Service } from "@elizaos/core";
+import { SigningPolicyEvaluator, } from "./signing-policy.js";
+import { teeBootGateBlocksSecrets } from "./tee-boot-gate-state.js";
+import { TeeSignerBackend } from "./tee-signer-backend.js";
+export class RemoteSigningService {
+    signer;
+    policyEvaluator;
+    auditLog;
+    pendingApprovals = new Map();
+    approvalTimeoutMs;
+    constructor(config) {
+        this.signer = config.signer;
+        this.policyEvaluator = new SigningPolicyEvaluator(config.policy);
+        this.auditLog = config.auditLog;
+        this.approvalTimeoutMs = config.approvalTimeoutMs ?? 5 * 60 * 1000;
+    }
+    async getAddress() {
+        return this.signer.getAddress();
+    }
+    async submitSigningRequest(request) {
+        // Evaluate policy
+        const decision = this.policyEvaluator.evaluate(request);
+        this.auditLog?.record({
+            type: "signing_request_submitted",
+            summary: `Sign request ${request.requestId}: chain=${request.chainId} to=${request.to} value=${request.value}`,
+            metadata: {
+                requestId: request.requestId,
+                chainId: request.chainId,
+                to: request.to,
+                value: request.value,
+                allowed: decision.allowed,
+                reason: decision.reason,
+            },
+            severity: "info",
+        });
+        if (!decision.allowed) {
+            this.auditLog?.record({
+                type: "signing_request_rejected",
+                summary: `Rejected: ${decision.reason}`,
+                metadata: {
+                    requestId: request.requestId,
+                    matchedRule: decision.matchedRule,
+                },
+                severity: "warn",
+            });
+            return {
+                success: false,
+                error: decision.reason,
+                policyDecision: decision,
+                humanConfirmed: false,
+            };
+        }
+        // Check if human confirmation is required
+        if (decision.requiresHumanConfirmation) {
+            const approval = {
+                requestId: request.requestId,
+                request,
+                decision,
+                createdAt: Date.now(),
+                expiresAt: Date.now() + this.approvalTimeoutMs,
+            };
+            this.pendingApprovals.set(request.requestId, approval);
+            return {
+                success: false,
+                error: "Human confirmation required. Use approve endpoint.",
+                policyDecision: decision,
+                humanConfirmed: false,
+            };
+        }
+        // Sign the transaction
+        return this.executeSign(request, decision, false);
+    }
+    async approveRequest(requestId) {
+        const approval = this.pendingApprovals.get(requestId);
+        if (!approval) {
+            return {
+                success: false,
+                error: "No pending approval found for this request ID",
+                policyDecision: {
+                    allowed: false,
+                    reason: "Approval not found",
+                    requiresHumanConfirmation: false,
+                    matchedRule: "approval_not_found",
+                },
+                humanConfirmed: false,
+            };
+        }
+        // Check expiration
+        if (Date.now() > approval.expiresAt) {
+            this.pendingApprovals.delete(requestId);
+            return {
+                success: false,
+                error: "Approval expired",
+                policyDecision: approval.decision,
+                humanConfirmed: false,
+            };
+        }
+        this.pendingApprovals.delete(requestId);
+        return this.executeSign(approval.request, approval.decision, true);
+    }
+    rejectRequest(requestId) {
+        const existed = this.pendingApprovals.has(requestId);
+        this.pendingApprovals.delete(requestId);
+        if (existed) {
+            this.auditLog?.record({
+                type: "signing_request_rejected",
+                summary: `Human rejected request ${requestId}`,
+                metadata: { requestId },
+                severity: "info",
+            });
+        }
+        return existed;
+    }
+    getPendingApprovals() {
+        // Clean expired
+        const now = Date.now();
+        for (const [id, approval] of this.pendingApprovals) {
+            if (now > approval.expiresAt) {
+                this.pendingApprovals.delete(id);
+            }
+        }
+        return [...this.pendingApprovals.values()];
+    }
+    updatePolicy(policy) {
+        this.policyEvaluator.updatePolicy(policy);
+        this.auditLog?.record({
+            type: "policy_decision",
+            summary: "Signing policy updated",
+            severity: "warn",
+        });
+    }
+    getPolicy() {
+        return this.policyEvaluator.getPolicy();
+    }
+    async executeSign(request, decision, humanConfirmed) {
+        try {
+            const unsigned = {
+                to: request.to,
+                value: request.value,
+                data: request.data,
+                chainId: request.chainId,
+                nonce: request.nonce,
+                gasLimit: request.gasLimit,
+            };
+            if (request.maxFeePerGas !== undefined) {
+                unsigned.maxFeePerGas = request.maxFeePerGas;
+            }
+            if (request.maxPriorityFeePerGas !== undefined) {
+                unsigned.maxPriorityFeePerGas = request.maxPriorityFeePerGas;
+            }
+            const signedTx = await this.signer.signTransaction(unsigned);
+            // Record for replay protection and rate limiting
+            this.policyEvaluator.recordRequest(request.requestId);
+            this.auditLog?.record({
+                type: "signing_request_approved",
+                summary: `Signed request ${request.requestId}: chain=${request.chainId} to=${request.to}`,
+                metadata: {
+                    requestId: request.requestId,
+                    chainId: request.chainId,
+                    to: request.to,
+                    humanConfirmed,
+                },
+                severity: "info",
+            });
+            return {
+                success: true,
+                signature: signedTx,
+                policyDecision: decision,
+                humanConfirmed,
+            };
+        }
+        catch (err) {
+            const errorMsg = String(err);
+            this.auditLog?.record({
+                type: "signing_request_rejected",
+                summary: `Signing failed for ${request.requestId}: ${errorMsg}`,
+                metadata: {
+                    requestId: request.requestId,
+                    error: errorMsg,
+                },
+                severity: "error",
+            });
+            return {
+                success: false,
+                error: `Signing failed: ${errorMsg}`,
+                policyDecision: decision,
+                humanConfirmed,
+            };
+        }
+    }
+}
+/**
+ * Build a `RemoteSigningService` whose signer is gated on the TEE boot-gate
+ * state and (when a TEE policy requires it) re-attests on every sign.
+ *
+ * Fail-closed: if `teeBootGateBlocksSecrets()` is true (a required gate whose
+ * evidence was not trusted at boot), this refuses to construct the service so
+ * no signing path can come online. When the boot gate is inert (no TEE
+ * configured / not required), construction proceeds and signing behaves
+ * exactly as it did before TEE gating — no attestation requirement.
+ */
+export function createTeeGatedRemoteSigningService(config) {
+    if (teeBootGateBlocksSecrets()) {
+        throw new Error("[RemoteSigning] Refusing to construct remote signing service: TEE boot gate blocks secrets (evidence not trusted).");
+    }
+    const requiresAttestation = config.teePolicy?.required === true;
+    let signer = config.signer;
+    if (requiresAttestation) {
+        if (!config.evidenceProvider) {
+            throw new Error("[RemoteSigning] TEE policy requires evidence but no evidenceProvider was supplied.");
+        }
+        signer = new TeeSignerBackend({
+            signer: config.signer,
+            evidenceProvider: config.evidenceProvider,
+            policy: config.teePolicy,
+            onDecision: (decision) => {
+                if (!decision.trusted) {
+                    logger.warn({ reason: decision.reason, detail: decision.detail }, "[RemoteSigning] Per-sign TEE re-attestation rejected evidence.");
+                }
+            },
+        });
+    }
+    return new RemoteSigningService({
+        signer,
+        ...(config.policy ? { policy: config.policy } : {}),
+        ...(config.auditLog ? { auditLog: config.auditLog } : {}),
+        ...(config.approvalTimeoutMs !== undefined
+            ? { approvalTimeoutMs: config.approvalTimeoutMs }
+            : {}),
+    });
+}
+/**
+ * elizaOS runtime service wrapper exposing a TEE-gated `RemoteSigningService`
+ * to the host↔guest capability bridge (plan §4.3). The host can request a
+ * signature via `runtime.getService("remote-signing")`, but the key never
+ * leaves the domain and every sign re-attests when a TEE policy requires it.
+ *
+ * Activation is the caller's responsibility: the boot path constructs and
+ * registers this ONLY when remote signing is explicitly enabled. The service
+ * is never started by the runtime's plugin auto-discovery.
+ */
+export class RemoteSigningRuntimeService extends Service {
+    static serviceType = "remote-signing";
+    capabilityDescription = "TEE-gated remote transaction signing for the host↔guest capability bridge";
+    signing;
+    static async start(runtime) {
+        return new RemoteSigningRuntimeService(runtime);
+    }
+    async stop() {
+        this.signing = undefined;
+    }
+    /** Attach the built signing service. Called once by the boot path. */
+    attach(signing) {
+        this.signing = signing;
+    }
+    /** The active signing service, or undefined before boot attaches it. */
+    get service() {
+        return this.signing;
+    }
+}

package/services/research-task-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-task-executor.d.ts","sourceRoot":"","sources":["../../src/services/research-task-executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAK7E;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,WAAW,mEAC8C;IAElE,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO;IAKrD,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IAqIpE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5C"}

package/services/research-task-executor.js

@@ -0,0 +1,133 @@
+import { ModelType } from "@elizaos/core";
+const RESEARCH_PATTERNS = /\b(research|investigate|analyze|find out|look into|explore|summarize|compare|evaluate|review|study|assess)\b/i;
+/**
+ * Decomposes research questions into sub-questions, answers each via the
+ * runtime's LLM, and synthesizes a final report.
+ */
+export class ResearchTaskExecutor {
+    type = "research";
+    description = "Decomposes research questions and produces analysis artifacts";
+    canHandle(spec, _runtime) {
+        if (spec.type === "research")
+            return true;
+        return RESEARCH_PATTERNS.test(spec.description);
+    }
+    async execute(spec, runtime) {
+        const startTime = Date.now();
+        try {
+            try {
+                const researchResult = (await runtime.useModel(ModelType.RESEARCH, {
+                    input: spec.description,
+                    tools: [{ type: "web_search_preview" }],
+                    background: true,
+                    reasoningSummary: "auto",
+                }));
+                const output = typeof researchResult === "string"
+                    ? researchResult
+                    : (researchResult.text ?? "");
+                if (output.trim().length > 0) {
+                    return {
+                        taskId: spec.id,
+                        success: true,
+                        output,
+                        durationMs: Date.now() - startTime,
+                    };
+                }
+            }
+            catch {
+                // Fall through to the sequential synthesis path when the runtime
+                // does not expose a RESEARCH model or the provider rejects it.
+            }
+            // Step 1: Decompose the research question into sub-questions
+            const decomposition = await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: [
+                    "Decompose this research question into 3-5 focused sub-questions",
+                    "that can be answered independently:",
+                    "",
+                    spec.description,
+                    "",
+                    "Return each sub-question on its own line, one per line. No numbering, no bullets, no prose.",
+                ].join("\n"),
+            });
+            let subQuestions;
+            try {
+                // Parse line-delimited questions from the response.
+                // Strip markdown fences and numbering if the model adds them.
+                let raw = typeof decomposition === "string"
+                    ? decomposition
+                    : String(decomposition);
+                const fenceMatch = raw.match(/```(?:\w+)?\s*\n?([\s\S]*?)\n?\s*```/);
+                if (fenceMatch)
+                    raw = fenceMatch[1];
+                // Try line-based parsing first (preferred)
+                const lines = raw
+                    .split(/\r?\n/)
+                    .map((line) => line
+                    .replace(/^\s{0,32}(?:\d{1,8}[.)]\s{0,32}|-\s{0,32}|\*\s{0,32})/, "")
+                    .trim())
+                    .filter((line) => line.length > 0);
+                if (lines.length >= 2) {
+                    subQuestions = lines;
+                }
+                else {
+                    subQuestions = [spec.description];
+                }
+                if (subQuestions.length === 0)
+                    subQuestions = [spec.description];
+            }
+            catch {
+                subQuestions = [spec.description];
+            }
+            // Step 2: Answer each sub-question
+            const answers = [];
+            for (const question of subQuestions) {
+                const answer = await runtime.useModel(ModelType.TEXT_LARGE, {
+                    prompt: [
+                        "Answer this research question concisely but thoroughly:",
+                        "",
+                        question,
+                        "",
+                        `Context: This is part of a larger research task: "${spec.description}"`,
+                    ].join("\n"),
+                });
+                answers.push({
+                    question,
+                    answer: typeof answer === "string" ? answer : String(answer),
+                });
+            }
+            // Step 3: Synthesize into a final report
+            const findingsBlock = answers
+                .map((a, i) => `${i + 1}. Q: ${a.question}\n   A: ${a.answer}`)
+                .join("\n\n");
+            const synthesis = await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: [
+                    "Synthesize these research findings into a coherent report:",
+                    "",
+                    `Original question: ${spec.description}`,
+                    "",
+                    `Findings:\n${findingsBlock}`,
+                    "",
+                    "Provide a structured summary with key findings, conclusions, and any caveats.",
+                ].join("\n"),
+            });
+            const report = typeof synthesis === "string" ? synthesis : String(synthesis);
+            return {
+                taskId: spec.id,
+                success: true,
+                output: report,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                taskId: spec.id,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+    async abort(_taskId) {
+        // Research tasks are sequential LLM calls — no persistent process to abort.
+    }
+}

package/services/sandbox-engine.d.ts.map

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

package/services/sandbox-manager.d.ts

@@ -0,0 +1,132 @@
+/** Sandbox container lifecycle: create, exec, health check, teardown. */
+import { type SandboxEngineType } from "./sandbox-engine.ts";
+export type SandboxMode = "off" | "light" | "standard" | "max";
+export type SandboxState = "uninitialized" | "initializing" | "ready" | "degraded" | "stopping" | "stopped" | "recovering";
+export interface SandboxManagerConfig {
+    /** Sandbox mode. */
+    mode: SandboxMode;
+    /** Docker image for sandbox containers. */
+    image?: string;
+    /** Container name prefix. */
+    containerPrefix?: string;
+    /** Container workdir mount path. */
+    workdir?: string;
+    /** Run rootfs read-only. */
+    readOnlyRoot?: boolean;
+    /** Container network mode. */
+    network?: string;
+    /** Container user (uid:gid). */
+    user?: string;
+    /** Drop Linux capabilities. */
+    capDrop?: string[];
+    /** Environment variables for sandbox. */
+    env?: Record<string, string>;
+    /** Container memory limit. */
+    memory?: string;
+    /** Container CPU limit. */
+    cpus?: number;
+    /** PIDs limit. */
+    pidsLimit?: number;
+    /** Root directory for sandbox workspaces. */
+    workspaceRoot?: string;
+    /** Additional bind mounts. */
+    binds?: string[];
+    /** DNS servers. */
+    dns?: string[];
+    /** Container engine type: "docker", "apple-container", or "auto" (default). */
+    engineType?: SandboxEngineType;
+    /** Browser sandbox settings. */
+    browser?: {
+        enabled?: boolean;
+        image?: string;
+        cdpPort?: number;
+        vncPort?: number;
+        noVncPort?: number;
+        headless?: boolean;
+        enableNoVnc?: boolean;
+        autoStart?: boolean;
+        autoStartTimeoutMs?: number;
+    };
+}
+export interface SandboxExecOptions {
+    command: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+}
+export interface SandboxExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    executedInSandbox: boolean;
+}
+export interface SandboxRunOptions {
+    cmd: string;
+    args: readonly string[];
+    workdir?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+    /**
+     * Override sandbox image. Currently informational; the manager runs commands
+     * in the long-lived container provisioned at start(), not a per-call image.
+     */
+    image?: string;
+}
+export interface SandboxEvent {
+    timestamp: number;
+    type: "state_change" | "exec" | "exec_denied" | "container_start" | "container_stop" | "health_check" | "error";
+    detail: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+export declare class SandboxManager {
+    private state;
+    private config;
+    private engine;
+    private containerId;
+    private browserContainerId;
+    private eventLog;
+    private lifecycleQueue;
+    constructor(config: SandboxManagerConfig);
+    getState(): SandboxState;
+    /** The active container engine's type, for diagnostics/labeling. */
+    get engineType(): SandboxEngineType;
+    getMode(): SandboxMode;
+    getWorkspaceRoot(): string;
+    getContainerWorkspacePath(hostPath: string): string | null;
+    isReady(): boolean;
+    private resolveWorkspaceRoot;
+    private getMainContainerConfig;
+    private createMainContainer;
+    private cleanupContainer;
+    private setState;
+    private queueLifecycle;
+    start(): Promise<void>;
+    recover(): Promise<void>;
+    stop(): Promise<void>;
+    exec(options: SandboxExecOptions): Promise<SandboxExecResult>;
+    /**
+     * Argv-aware variant of {@link exec}. Builds a properly-quoted command
+     * string from `cmd` + `args` and forwards to the underlying engine. Use
+     * this from the shell-execution router so callers that already have
+     * argv-shaped requests don't have to re-quote and risk shell-injection
+     * mismatches.
+     */
+    run(options: SandboxRunOptions): Promise<SandboxExecResult>;
+    getBrowserCdpEndpoint(): string | null;
+    getBrowserWsEndpoint(): string | null;
+    getBrowserNoVncEndpoint(): string | null;
+    private createBrowserContainer;
+    private healthCheck;
+    private emitEvent;
+    getEventLog(): SandboxEvent[];
+    getStatus(): {
+        state: SandboxState;
+        mode: SandboxMode;
+        containerId: string | null;
+        browserContainerId: string | null;
+    };
+}
+//# sourceMappingURL=sandbox-manager.d.ts.map

package/services/sandbox-manager.d.ts.map

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