@fabric-harness/sdk 0.6.1 → 0.8.0

package/dist/suspending-sandbox.js

@@ -0,0 +1,156 @@
+import { FabricError } from './error.js';
+/**
+ * Decorator that adds idle-based auto-suspend to any `SandboxEnv` whose
+ * underlying implementation supports `suspend()` / `resume()`. If the inner
+ * env doesn't implement them, the decorator is a no-op pass-through (the
+ * idle timer never fires anything).
+ *
+ * The decorator tracks a `lastAccessAt` timestamp on every operation. After
+ * `idleSuspendMs` elapses without activity, it calls `inner.suspend()`. The
+ * next operation transparently calls `inner.resume()` first (unless
+ * `autoResumeOnAccess: false`).
+ *
+ * `cleanup()` cancels the idle timer.
+ */
+export class SuspendingSandboxEnv {
+    inner;
+    cwd;
+    capabilities;
+    suspended = false;
+    idleTimer;
+    inFlight = 0;
+    idleMs;
+    autoResume;
+    constructor(inner, options) {
+        this.inner = inner;
+        this.idleMs = options.idleSuspendMs;
+        this.autoResume = options.autoResumeOnAccess !== false;
+        this.cwd = inner.cwd;
+        if (inner.capabilities) {
+            this.capabilities = {
+                ...inner.capabilities,
+                suspend: typeof inner.suspend === 'function',
+                resume: typeof inner.resume === 'function',
+            };
+        }
+    }
+    resolvePath(path) { return this.inner.resolvePath(path); }
+    async exec(command, options) {
+        return this.access(() => this.inner.exec(command, options));
+    }
+    async readFile(path) { return this.access(() => this.inner.readFile(path)); }
+    async readFileBuffer(path) { return this.access(() => this.inner.readFileBuffer(path)); }
+    async writeFile(path, content) { await this.access(() => this.inner.writeFile(path, content)); }
+    async stat(path) { return this.access(() => this.inner.stat(path)); }
+    async readdir(path) { return this.access(() => this.inner.readdir(path)); }
+    async exists(path) { return this.access(() => this.inner.exists(path)); }
+    async mkdir(path, options) { await this.access(() => this.inner.mkdir(path, options)); }
+    async rm(path, options) { await this.access(() => this.inner.rm(path, options)); }
+    async snapshot() {
+        const snapshot = this.inner.snapshot;
+        if (!snapshot)
+            throw new FabricError({ code: 'SANDBOX_UNAVAILABLE', message: 'Sandbox does not support snapshots.' });
+        return this.access(() => snapshot.call(this.inner));
+    }
+    async restore(snapshot) {
+        const restore = this.inner.restore;
+        if (!restore)
+            throw new FabricError({ code: 'SANDBOX_UNAVAILABLE', message: 'Sandbox does not support restore.' });
+        await this.access(() => restore.call(this.inner, snapshot));
+    }
+    async fork(snapshot) {
+        const fork = this.inner.fork;
+        if (!fork)
+            throw new FabricError({ code: 'SANDBOX_UNAVAILABLE', message: 'Sandbox does not support fork.' });
+        return this.access(() => fork.call(this.inner, snapshot));
+    }
+    async suspend() {
+        if (typeof this.inner.suspend !== 'function')
+            return;
+        this.cancelIdleTimer();
+        if (!this.suspended) {
+            await this.inner.suspend();
+            this.suspended = true;
+        }
+    }
+    async resume() {
+        if (typeof this.inner.resume !== 'function')
+            return;
+        if (this.suspended) {
+            await this.inner.resume();
+            this.suspended = false;
+        }
+        this.scheduleIdleTimer();
+    }
+    async cleanup() {
+        this.cancelIdleTimer();
+        await this.inner.cleanup();
+    }
+    /** True when the sandbox is currently suspended (for tests / introspection). */
+    get isSuspended() { return this.suspended; }
+    async access(operation) {
+        this.cancelIdleTimer();
+        if (this.suspended) {
+            if (!this.autoResume) {
+                throw new FabricError({
+                    code: 'SANDBOX_UNAVAILABLE',
+                    message: 'Sandbox is suspended; pass autoResumeOnAccess: true (default) or call resume() before use.',
+                    retryable: true,
+                });
+            }
+            if (typeof this.inner.resume !== 'function') {
+                throw new FabricError({
+                    code: 'SANDBOX_UNAVAILABLE',
+                    message: 'Sandbox is suspended but the underlying backend does not support resume().',
+                });
+            }
+            await this.inner.resume();
+            this.suspended = false;
+        }
+        this.inFlight += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.inFlight -= 1;
+            // Only restart the idle timer once nothing is in flight, so multiple
+            // concurrent operations don't suspend mid-flight.
+            if (this.inFlight === 0)
+                this.scheduleIdleTimer();
+        }
+    }
+    scheduleIdleTimer() {
+        const suspend = this.inner.suspend;
+        if (!suspend)
+            return;
+        this.cancelIdleTimer();
+        const timer = setTimeout(() => {
+            // Best-effort suspend; swallow errors so a failing provider doesn't crash the process.
+            void suspend.call(this.inner).then(() => { this.suspended = true; }).catch(() => undefined);
+        }, this.idleMs);
+        // Don't keep the event loop alive just for the suspend timer.
+        if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function') {
+            timer.unref();
+        }
+        this.idleTimer = timer;
+    }
+    cancelIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = undefined;
+        }
+    }
+}
+/**
+ * Wrap any `SandboxEnv` with idle-based auto-suspend. Returns the inner env
+ * unchanged when `idleSuspendMs` is undefined or the inner env doesn't
+ * implement `suspend()`.
+ */
+export function withIdleSuspend(inner, options) {
+    if (!options?.idleSuspendMs || options.idleSuspendMs <= 0)
+        return inner;
+    if (typeof inner.suspend !== 'function')
+        return inner;
+    return new SuspendingSandboxEnv(inner, options);
+}
+//# sourceMappingURL=suspending-sandbox.js.map

package/dist/suspending-sandbox.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabric-harness/sdk",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Headless TypeScript framework for building durable, deployable autonomous agents — core SDK.",
   "license": "Apache-2.0",
   "author": "Fabric",