@agnt5/sdk 0.2.1

package/dist/retry-utils.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Retry and backoff utilities for durable execution.
+ *
+ * This module provides utilities for parsing retry policies, calculating backoff delays,
+ * and executing functions with retry logic.
+ */
+import type { RetryPolicy, BackoffPolicy, Context } from './types.js';
+/**
+ * Default retry policy configuration
+ */
+export declare const DEFAULT_RETRY_POLICY: Required<RetryPolicy>;
+/**
+ * Default backoff policy configuration
+ */
+export declare const DEFAULT_BACKOFF_POLICY: Required<BackoffPolicy>;
+/**
+ * Parse retry configuration from various forms.
+ *
+ * @param retries - Can be:
+ *   - number: max_attempts (e.g., 5)
+ *   - RetryPolicy: complete configuration
+ *   - undefined: use default
+ * @returns Complete RetryPolicy
+ *
+ * @example
+ * ```typescript
+ * parseRetryPolicy(5) // { maxAttempts: 5, initialIntervalMs: 1000, maxIntervalMs: 60000 }
+ * parseRetryPolicy({ maxAttempts: 3, initialIntervalMs: 2000 })
+ * parseRetryPolicy(undefined) // Uses defaults
+ * ```
+ */
+export declare function parseRetryPolicy(retries?: number | RetryPolicy): Required<RetryPolicy>;
+/**
+ * Parse backoff configuration from various forms.
+ *
+ * @param backoff - Can be:
+ *   - string: backoff type ("constant", "linear", "exponential")
+ *   - BackoffPolicy: complete configuration
+ *   - undefined: use default
+ * @returns Complete BackoffPolicy
+ *
+ * @example
+ * ```typescript
+ * parseBackoffPolicy('exponential') // { type: 'exponential', multiplier: 2.0 }
+ * parseBackoffPolicy({ type: 'linear', multiplier: 1.5 })
+ * parseBackoffPolicy(undefined) // Uses defaults
+ * ```
+ */
+export declare function parseBackoffPolicy(backoff?: string | BackoffPolicy): Required<BackoffPolicy>;
+/**
+ * Calculate backoff delay in milliseconds based on attempt number.
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param retryPolicy - Retry configuration
+ * @param backoffPolicy - Backoff configuration
+ * @param jitter - Add jitter to prevent thundering herd (default: true)
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff: 1s → 2s → 4s → 8s
+ * calculateBackoffDelay(0, policy, { type: 'exponential', multiplier: 2.0 }) // ~1000ms
+ * calculateBackoffDelay(1, policy, { type: 'exponential', multiplier: 2.0 }) // ~2000ms
+ * calculateBackoffDelay(2, policy, { type: 'exponential', multiplier: 2.0 }) // ~4000ms
+ *
+ * // With jitter (adds randomness ±25%)
+ * calculateBackoffDelay(1, policy, backoff, true) // ~1500ms - 2500ms
+ * ```
+ */
+export declare function calculateBackoffDelay(attempt: number, retryPolicy: Required<RetryPolicy>, backoffPolicy: Required<BackoffPolicy>, jitter?: boolean): number;
+/**
+ * Custom retry predicate function type.
+ * Return true to retry, false to abort.
+ */
+export type RetryPredicate = (error: Error, attempt: number) => boolean;
+/**
+ * Options for executeWithRetry
+ */
+export interface ExecuteWithRetryOptions {
+    /** Retry policy (attempts, intervals) */
+    retryPolicy?: number | RetryPolicy;
+    /** Backoff policy (type, multiplier) */
+    backoffPolicy?: string | BackoffPolicy;
+    /** Add jitter to backoff delays (default: true) */
+    jitter?: boolean;
+    /** Custom predicate to determine if retry should happen */
+    retryPredicate?: RetryPredicate;
+    /** Context for logging (optional) */
+    context?: Context;
+}
+/**
+ * Execute a function with retry logic.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns Result of successful execution
+ * @throws RetryError if all retry attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Simple retry with defaults (3 attempts, exponential backoff)
+ * const result = await executeWithRetry(async () => {
+ *   return await fetchData();
+ * });
+ *
+ * // Custom retry policy
+ * const result = await executeWithRetry(
+ *   async () => await processData(),
+ *   {
+ *     retryPolicy: { maxAttempts: 5, initialIntervalMs: 2000 },
+ *     backoffPolicy: 'linear',
+ *     jitter: true,
+ *   }
+ * );
+ *
+ * // With custom retry predicate
+ * const result = await executeWithRetry(
+ *   async () => await callAPI(),
+ *   {
+ *     retryPolicy: 3,
+ *     retryPredicate: (error, attempt) => {
+ *       // Only retry on network errors
+ *       return error.message.includes('ECONNREFUSED');
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function executeWithRetry<T>(fn: () => Promise<T>, options?: ExecuteWithRetryOptions): Promise<T>;
+/**
+ * Create a retry wrapper function for repeated use.
+ *
+ * @param options - Retry configuration options
+ * @returns Function that executes with retry logic
+ *
+ * @example
+ * ```typescript
+ * const retryableFetch = createRetryWrapper({
+ *   retryPolicy: 5,
+ *   backoffPolicy: 'exponential',
+ * });
+ *
+ * const data1 = await retryableFetch(() => fetch('/api/data1'));
+ * const data2 = await retryableFetch(() => fetch('/api/data2'));
+ * ```
+ */
+export declare function createRetryWrapper(options?: ExecuteWithRetryOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * Retry with timeout - execute with retry logic and overall timeout.
+ *
+ * @param fn - The async function to execute
+ * @param timeoutMs - Maximum time to spend retrying (in milliseconds)
+ * @param options - Retry configuration options
+ * @returns Result of successful execution
+ * @throws TimeoutError if timeout is exceeded
+ * @throws RetryError if all retry attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Retry for up to 30 seconds
+ * const result = await executeWithRetryAndTimeout(
+ *   async () => await processData(),
+ *   30000, // 30 seconds
+ *   { retryPolicy: 10 }
+ * );
+ * ```
+ */
+export declare function executeWithRetryAndTimeout<T>(fn: () => Promise<T>, timeoutMs: number, options?: ExecuteWithRetryOptions): Promise<T>;
+//# sourceMappingURL=retry-utils.d.ts.map

package/dist/retry-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-utils.d.ts","sourceRoot":"","sources":["../src/retry-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGtE;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAItD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAG1D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAqBtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC,CAwB5F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,EAClC,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,EACtC,MAAM,GAAE,OAAc,GACrB,MAAM,CA+BR;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACnC,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IACvC,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CA2DZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,uBAA4B,IACxD,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAGnD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CA0BZ"}

package/dist/retry-utils.js

@@ -0,0 +1,304 @@
+/**
+ * Retry and backoff utilities for durable execution.
+ *
+ * This module provides utilities for parsing retry policies, calculating backoff delays,
+ * and executing functions with retry logic.
+ */
+import { RetryError } from './errors.js';
+/**
+ * Default retry policy configuration
+ */
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    initialIntervalMs: 1000, // 1 second
+    maxIntervalMs: 60000, // 60 seconds
+};
+/**
+ * Default backoff policy configuration
+ */
+export const DEFAULT_BACKOFF_POLICY = {
+    type: 'exponential',
+    multiplier: 2.0,
+};
+/**
+ * Parse retry configuration from various forms.
+ *
+ * @param retries - Can be:
+ *   - number: max_attempts (e.g., 5)
+ *   - RetryPolicy: complete configuration
+ *   - undefined: use default
+ * @returns Complete RetryPolicy
+ *
+ * @example
+ * ```typescript
+ * parseRetryPolicy(5) // { maxAttempts: 5, initialIntervalMs: 1000, maxIntervalMs: 60000 }
+ * parseRetryPolicy({ maxAttempts: 3, initialIntervalMs: 2000 })
+ * parseRetryPolicy(undefined) // Uses defaults
+ * ```
+ */
+export function parseRetryPolicy(retries) {
+    if (retries === undefined || retries === null) {
+        return DEFAULT_RETRY_POLICY;
+    }
+    if (typeof retries === 'number') {
+        return {
+            ...DEFAULT_RETRY_POLICY,
+            maxAttempts: retries,
+        };
+    }
+    if (typeof retries === 'object') {
+        return {
+            maxAttempts: retries.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+            initialIntervalMs: retries.initialIntervalMs ?? DEFAULT_RETRY_POLICY.initialIntervalMs,
+            maxIntervalMs: retries.maxIntervalMs ?? DEFAULT_RETRY_POLICY.maxIntervalMs,
+        };
+    }
+    throw new TypeError(`retries must be number or RetryPolicy, got ${typeof retries}`);
+}
+/**
+ * Parse backoff configuration from various forms.
+ *
+ * @param backoff - Can be:
+ *   - string: backoff type ("constant", "linear", "exponential")
+ *   - BackoffPolicy: complete configuration
+ *   - undefined: use default
+ * @returns Complete BackoffPolicy
+ *
+ * @example
+ * ```typescript
+ * parseBackoffPolicy('exponential') // { type: 'exponential', multiplier: 2.0 }
+ * parseBackoffPolicy({ type: 'linear', multiplier: 1.5 })
+ * parseBackoffPolicy(undefined) // Uses defaults
+ * ```
+ */
+export function parseBackoffPolicy(backoff) {
+    if (backoff === undefined || backoff === null) {
+        return DEFAULT_BACKOFF_POLICY;
+    }
+    if (typeof backoff === 'string') {
+        const type = backoff.toLowerCase();
+        if (type !== 'constant' && type !== 'linear' && type !== 'exponential') {
+            throw new TypeError(`backoff type must be "constant", "linear", or "exponential", got "${backoff}"`);
+        }
+        return {
+            ...DEFAULT_BACKOFF_POLICY,
+            type,
+        };
+    }
+    if (typeof backoff === 'object') {
+        return {
+            type: backoff.type ?? DEFAULT_BACKOFF_POLICY.type,
+            multiplier: backoff.multiplier ?? DEFAULT_BACKOFF_POLICY.multiplier,
+        };
+    }
+    throw new TypeError(`backoff must be string or BackoffPolicy, got ${typeof backoff}`);
+}
+/**
+ * Calculate backoff delay in milliseconds based on attempt number.
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param retryPolicy - Retry configuration
+ * @param backoffPolicy - Backoff configuration
+ * @param jitter - Add jitter to prevent thundering herd (default: true)
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff: 1s → 2s → 4s → 8s
+ * calculateBackoffDelay(0, policy, { type: 'exponential', multiplier: 2.0 }) // ~1000ms
+ * calculateBackoffDelay(1, policy, { type: 'exponential', multiplier: 2.0 }) // ~2000ms
+ * calculateBackoffDelay(2, policy, { type: 'exponential', multiplier: 2.0 }) // ~4000ms
+ *
+ * // With jitter (adds randomness ±25%)
+ * calculateBackoffDelay(1, policy, backoff, true) // ~1500ms - 2500ms
+ * ```
+ */
+export function calculateBackoffDelay(attempt, retryPolicy, backoffPolicy, jitter = true) {
+    let delayMs;
+    switch (backoffPolicy.type) {
+        case 'constant':
+            delayMs = retryPolicy.initialIntervalMs;
+            break;
+        case 'linear':
+            delayMs = retryPolicy.initialIntervalMs * (attempt + 1);
+            break;
+        case 'exponential':
+            delayMs = retryPolicy.initialIntervalMs * Math.pow(backoffPolicy.multiplier, attempt);
+            break;
+        default:
+            throw new Error(`Unknown backoff type: ${backoffPolicy.type}`);
+    }
+    // Cap at max_interval_ms
+    delayMs = Math.min(delayMs, retryPolicy.maxIntervalMs);
+    // Add jitter (±25% randomness) to prevent thundering herd
+    if (jitter) {
+        const jitterFactor = 0.25;
+        const randomFactor = 1.0 + (Math.random() * 2.0 - 1.0) * jitterFactor;
+        delayMs = Math.floor(delayMs * randomFactor);
+    }
+    return delayMs;
+}
+/**
+ * Default retry predicate - always retry unless it's a specific non-retryable error
+ */
+const defaultRetryPredicate = (error, _attempt) => {
+    // Import here to avoid circular dependency
+    const errorName = error.constructor.name;
+    // Don't retry these errors
+    const nonRetryableErrors = [
+        'ValidationError',
+        'RunError',
+        'TimeoutError',
+        'AuthorizationError',
+    ];
+    return !nonRetryableErrors.includes(errorName);
+};
+/**
+ * Execute a function with retry logic.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns Result of successful execution
+ * @throws RetryError if all retry attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Simple retry with defaults (3 attempts, exponential backoff)
+ * const result = await executeWithRetry(async () => {
+ *   return await fetchData();
+ * });
+ *
+ * // Custom retry policy
+ * const result = await executeWithRetry(
+ *   async () => await processData(),
+ *   {
+ *     retryPolicy: { maxAttempts: 5, initialIntervalMs: 2000 },
+ *     backoffPolicy: 'linear',
+ *     jitter: true,
+ *   }
+ * );
+ *
+ * // With custom retry predicate
+ * const result = await executeWithRetry(
+ *   async () => await callAPI(),
+ *   {
+ *     retryPolicy: 3,
+ *     retryPredicate: (error, attempt) => {
+ *       // Only retry on network errors
+ *       return error.message.includes('ECONNREFUSED');
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export async function executeWithRetry(fn, options = {}) {
+    const retryPolicy = parseRetryPolicy(options.retryPolicy);
+    const backoffPolicy = parseBackoffPolicy(options.backoffPolicy);
+    const jitter = options.jitter ?? true;
+    const retryPredicate = options.retryPredicate ?? defaultRetryPredicate;
+    const context = options.context;
+    let lastError;
+    for (let attempt = 0; attempt < retryPolicy.maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            // Log error if context provided
+            if (context) {
+                context.logger.warn(`Execution failed (attempt ${attempt + 1}/${retryPolicy.maxAttempts}): ${lastError.message}`);
+            }
+            // Check if we should retry
+            const shouldRetry = retryPredicate(lastError, attempt);
+            if (!shouldRetry) {
+                if (context) {
+                    context.logger.error(`Non-retryable error encountered: ${lastError.message}`);
+                }
+                throw lastError;
+            }
+            // If this was the last attempt, throw RetryError
+            if (attempt === retryPolicy.maxAttempts - 1) {
+                throw new RetryError(`Execution failed after ${retryPolicy.maxAttempts} attempts: ${lastError.message}`, retryPolicy.maxAttempts, lastError);
+            }
+            // Calculate backoff delay
+            const delayMs = calculateBackoffDelay(attempt, retryPolicy, backoffPolicy, jitter);
+            if (context) {
+                context.logger.info(`Retrying in ${delayMs}ms...`);
+            }
+            // Wait before next attempt
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+    }
+    // Should never reach here, but for type safety
+    throw new RetryError(`Execution failed after ${retryPolicy.maxAttempts} attempts`, retryPolicy.maxAttempts, lastError);
+}
+/**
+ * Create a retry wrapper function for repeated use.
+ *
+ * @param options - Retry configuration options
+ * @returns Function that executes with retry logic
+ *
+ * @example
+ * ```typescript
+ * const retryableFetch = createRetryWrapper({
+ *   retryPolicy: 5,
+ *   backoffPolicy: 'exponential',
+ * });
+ *
+ * const data1 = await retryableFetch(() => fetch('/api/data1'));
+ * const data2 = await retryableFetch(() => fetch('/api/data2'));
+ * ```
+ */
+export function createRetryWrapper(options = {}) {
+    return async (fn) => {
+        return executeWithRetry(fn, options);
+    };
+}
+/**
+ * Retry with timeout - execute with retry logic and overall timeout.
+ *
+ * @param fn - The async function to execute
+ * @param timeoutMs - Maximum time to spend retrying (in milliseconds)
+ * @param options - Retry configuration options
+ * @returns Result of successful execution
+ * @throws TimeoutError if timeout is exceeded
+ * @throws RetryError if all retry attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Retry for up to 30 seconds
+ * const result = await executeWithRetryAndTimeout(
+ *   async () => await processData(),
+ *   30000, // 30 seconds
+ *   { retryPolicy: 10 }
+ * );
+ * ```
+ */
+export async function executeWithRetryAndTimeout(fn, timeoutMs, options = {}) {
+    const startTime = Date.now();
+    // Wrap the predicate to check timeout
+    const originalPredicate = options.retryPredicate ?? defaultRetryPredicate;
+    const timeoutPredicate = (error, attempt) => {
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= timeoutMs) {
+            return false; // Don't retry if timeout exceeded
+        }
+        return originalPredicate(error, attempt);
+    };
+    try {
+        return await executeWithRetry(fn, {
+            ...options,
+            retryPredicate: timeoutPredicate,
+        });
+    }
+    catch (error) {
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= timeoutMs) {
+            const { TimeoutError } = await import('./errors.js');
+            throw new TimeoutError(`Execution timed out after ${timeoutMs}ms`, timeoutMs, 'executeWithRetryAndTimeout');
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=retry-utils.js.map

package/dist/retry-utils.js.map

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

package/dist/sandbox.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Sandbox — secure code execution and file I/O.
+ *
+ * Wraps the native Rust sandbox bindings, supporting both remote (HTTP)
+ * and embedded (WASM) backends. The backend is selected automatically
+ * based on available configuration.
+ *
+ * @example
+ * ```ts
+ * import { Sandbox } from '@agnt5/sdk';
+ *
+ * const sandbox = new Sandbox({ endpoint: 'http://localhost:8080' });
+ * const result = await sandbox.executeCode('console.log("hello")', 'javascript');
+ * console.log(result.stdout); // "hello"
+ * ```
+ */
+export interface SandboxOptions {
+    /** Backend selection: "remote", "wasm", or "auto" (default). */
+    backend?: string;
+    /** HTTP endpoint for remote backend. */
+    endpoint?: string;
+    /** Sandbox instance ID. */
+    sandboxId?: string;
+    /** API key for remote auth. */
+    apiKey?: string;
+    /** Bearer token for remote auth. */
+    bearerToken?: string;
+    /** Request timeout in seconds (default: 300). */
+    timeoutSecs?: number;
+    /** Path to QuickJS WASI binary (for wasm backend). */
+    quickjsWasmPath?: string;
+}
+export interface ExecuteCodeResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    executionTimeMs: number;
+    error?: string;
+}
+export interface WriteFileResult {
+    success: boolean;
+    path: string;
+    size: number;
+    error?: string;
+}
+export interface ReadFileResult {
+    path: string;
+    content: Buffer;
+    size: number;
+    isDir: boolean;
+    error?: string;
+}
+export interface FileInfo {
+    name: string;
+    path: string;
+    size: number;
+    isDir: boolean;
+    mode: number;
+    modTime: number;
+}
+export interface ListFilesResult {
+    path: string;
+    total: number;
+    files: FileInfo[];
+    error?: string;
+}
+export interface HealthResult {
+    status: string;
+    sandboxId: string;
+    uptimeMs: number;
+    backendKind: string;
+    error?: string;
+}
+export interface SandboxCapabilities {
+    languages: string[];
+    supportsCommands: boolean;
+    supportsGit: boolean;
+    supportsPreviewUrl: boolean;
+    supportsStreaming: boolean;
+    supportsSnapshots: boolean;
+    hasNetworkAccess: boolean;
+}
+export declare class Sandbox {
+    private inner;
+    constructor(options?: SandboxOptions);
+    /** Active backend type ("remote" or "wasm"). */
+    get backend(): string;
+    /** Execute code in a sandboxed environment. */
+    executeCode(code: string, language?: string, timeoutMs?: number): Promise<ExecuteCodeResult>;
+    /** Write a file into the sandbox workspace. */
+    writeFile(path: string, content: Buffer | string): Promise<WriteFileResult>;
+    /** Read a file from the sandbox workspace. */
+    readFile(path: string): Promise<ReadFileResult>;
+    /** Delete a file or directory from the sandbox workspace. */
+    deleteFile(path: string, recursive?: boolean): Promise<boolean>;
+    /** List files in the sandbox workspace. */
+    listFiles(path?: string, recursive?: boolean): Promise<ListFilesResult>;
+    /** Check sandbox health and status. */
+    health(): Promise<HealthResult>;
+    /** Query sandbox capabilities (languages, features). */
+    capabilities(): SandboxCapabilities;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

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