@cybernetyx1/atlasflow-runtime 0.1.0

package/dist/chunk-S7RZJMCF.js

@@ -0,0 +1,47 @@
+// src/command.ts
+function defineCommand(name, execute) {
+  return { name, execute: normalizeCommandExecutor(execute) };
+}
+function normalizeCommandExecutor(execute) {
+  return async (args, signal) => {
+    try {
+      const raw = await execute(args, signal);
+      if (raw == null) return { stdout: "", stderr: "", exitCode: 0 };
+      if (typeof raw === "string") return { stdout: raw, stderr: "", exitCode: 0 };
+      return {
+        stdout: raw.stdout ?? "",
+        stderr: raw.stderr ?? "",
+        exitCode: raw.exitCode ?? 0
+      };
+    } catch (err) {
+      const e = err;
+      return {
+        stdout: typeof e.stdout === "string" ? e.stdout : "",
+        stderr: typeof e.stderr === "string" ? e.stderr : err instanceof Error ? err.message : String(err),
+        exitCode: typeof e.code === "number" ? e.code : 1
+      };
+    }
+  };
+}
+function mergeCommands(defaults, perCall) {
+  if (!defaults?.length) return perCall ?? [];
+  if (!perCall?.length) return defaults;
+  const byName = /* @__PURE__ */ new Map();
+  for (const command of defaults) byName.set(command.name, command);
+  for (const command of perCall) byName.set(command.name, command);
+  return [...byName.values()];
+}
+async function createScopedSessionEnv(env, commands) {
+  if (!commands.length) return env;
+  if (env.scope) return env.scope({ commands });
+  throw new Error(
+    "Cannot use commands: this sandbox does not support scoped command execution. Use the default virtual sandbox or a connector that implements SessionEnv.scope()."
+  );
+}
+
+export {
+  defineCommand,
+  normalizeCommandExecutor,
+  mergeCommands,
+  createScopedSessionEnv
+};

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,109 @@
+import { DurableObject } from 'cloudflare:workers';
+export { d as defineCommand } from '../command-kxrqWIH7.js';
+import { S as SessionData, R as RunRecord, a as RunStatus, A as AtlasEvent, b as StreamCreateOptions, D as DurableStreamRecord, c as StreamAppendOptions, d as DurableStreamMessage, e as DurableStreamProducerTuple, f as StreamProducerAppendResult, g as StreamProducerCloseResult, h as DurableStreamSubscriptionCreateInput, i as DurableStreamSubscriptionResult, j as DurableStreamSubscriptionRecord, k as DurableStreamSubscriptionClaim, l as DurableStreamSubscriptionAckInput, m as DurableStreamSubscriptionStreamInfo, P as PersistenceAdapter } from '../index-UFTgKRK4.js';
+
+interface CloudflareExecutionContextLike {
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+interface CloudflareFiberLike {
+    stash?: (value: unknown) => void | Promise<void>;
+}
+interface CloudflareAgentDurabilityLike {
+    runFiber?: <T>(name: string, run: (fiber?: CloudflareFiberLike) => T | Promise<T>) => T | Promise<T>;
+    keepAliveWhile?: <T>(run: () => T | Promise<T>) => T | Promise<T>;
+}
+interface CloudflareDurabilityOptions {
+    /**
+     * A Cloudflare Agents SDK Durable Object instance. When it exposes
+     * `runFiber`, AtlasFlow uses it for interruption-aware execution.
+     */
+    agentInstance?: CloudflareAgentDurabilityLike | null;
+    /** The Worker execution context used by plain Worker routes. */
+    executionCtx?: CloudflareExecutionContextLike | null;
+    /** Stable name for the registered fiber. A generated request name is used when omitted. */
+    fiberName?: string;
+    /** Optional metadata written to the fiber snapshot before user code runs. */
+    stash?: unknown | ((fiberName: string) => unknown);
+    /** Throw instead of falling back when `runFiber` is unavailable. */
+    requireFiber?: boolean;
+}
+interface CloudflareDurabilityCapabilities {
+    runFiber: boolean;
+    keepAliveWhile: boolean;
+    waitUntil: boolean;
+}
+declare function cloudflareDurabilityCapabilities(options: CloudflareDurabilityOptions): CloudflareDurabilityCapabilities;
+declare function hasCloudflareFiber(agentInstance: unknown): agentInstance is Required<Pick<CloudflareAgentDurabilityLike, "runFiber">>;
+declare function runWithCloudflareDurability<T>(options: CloudflareDurabilityOptions, run: () => T | Promise<T>): Promise<T>;
+
+/**
+ * Cloudflare Durable Object persistence.
+ *
+ * `AtlasFlowStore` is a Durable Object whose transactional storage backs the
+ * same PersistenceAdapter the rest of the runtime uses (via `kvAdapter`). The
+ * Worker talks to it through `durableObjectAdapter(env.ATLAS_STORE)`, giving
+ * agents durable sessions and run records across requests and restarts.
+ *
+ * This module imports `cloudflare:workers`, so it only loads on the Workers
+ * runtime — Node consumers never import `@cybernetyx1/atlasflow-runtime/cloudflare`.
+ */
+
+type RunFilter = {
+    status?: RunStatus;
+    agent?: string;
+    limit?: number;
+};
+declare class AtlasFlowStore extends DurableObject {
+    #private;
+    sessionGet(key: string): Promise<SessionData | null>;
+    sessionPut(key: string, data: SessionData): Promise<void>;
+    sessionDelete(key: string): Promise<void>;
+    runCreate(record: RunRecord): Promise<void>;
+    runUpdate(runId: string, patch: Partial<RunRecord>): Promise<void>;
+    runGet(runId: string): Promise<RunRecord | null>;
+    runList(filter?: RunFilter): Promise<RunRecord[]>;
+    runClaimLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    runClaimQueued(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    runHeartbeatLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    runReleaseLease(runId: string, owner: string): Promise<void>;
+    runAppendEvent(runId: string, event: AtlasEvent): Promise<void>;
+    runEvents(runId: string): Promise<AtlasEvent[]>;
+    runEventCount(runId: string): Promise<number>;
+    streamCreate(path: string, opts?: StreamCreateOptions): Promise<{
+        record: DurableStreamRecord;
+        created: boolean;
+    }>;
+    streamGet(path: string): Promise<DurableStreamRecord | null>;
+    streamDelete(path: string): Promise<boolean>;
+    streamAppend(path: string, data: Uint8Array, opts: StreamAppendOptions): Promise<{
+        record: DurableStreamRecord;
+        message: DurableStreamMessage;
+    } | null>;
+    streamAppendWithProducer(path: string, data: Uint8Array, opts: StreamAppendOptions & {
+        producer: DurableStreamProducerTuple;
+    }): Promise<StreamProducerAppendResult | null>;
+    streamClose(path: string): Promise<DurableStreamRecord | null>;
+    streamCloseWithProducer(path: string, producer: DurableStreamProducerTuple): Promise<StreamProducerCloseResult | null>;
+    streamMessages(path: string): Promise<DurableStreamMessage[]>;
+    subscriptionCreateOrConfirm(id: string, input: DurableStreamSubscriptionCreateInput): Promise<DurableStreamSubscriptionResult<{
+        subscription: DurableStreamSubscriptionRecord;
+        created: boolean;
+    }>>;
+    subscriptionGet(id: string): Promise<DurableStreamSubscriptionRecord | null>;
+    subscriptionDelete(id: string): Promise<boolean>;
+    subscriptionAddExplicitStreams(id: string, streams: string[]): Promise<boolean>;
+    subscriptionRemoveExplicitStream(id: string, streamPath: string): Promise<boolean>;
+    subscriptionNotifyStreamAppend(streamPath: string, message?: DurableStreamMessage): Promise<void>;
+    subscriptionNotifyStreamDelete(streamPath: string): Promise<void>;
+    subscriptionClaim(id: string, worker: string): Promise<DurableStreamSubscriptionResult<DurableStreamSubscriptionClaim>>;
+    subscriptionAck(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<{
+        ok: true;
+        nextWake: boolean;
+    }>>;
+    subscriptionRelease(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<void>>;
+    subscriptionStreamInfos(subscription: DurableStreamSubscriptionRecord): Promise<DurableStreamSubscriptionStreamInfo[]>;
+}
+/** Build a PersistenceAdapter that proxies to the AtlasFlowStore Durable Object. */
+declare function durableObjectAdapter(namespace: DurableObjectNamespace, name?: string): PersistenceAdapter;
+
+export { AtlasFlowStore, type CloudflareAgentDurabilityLike, type CloudflareDurabilityCapabilities, type CloudflareDurabilityOptions, type CloudflareExecutionContextLike, type CloudflareFiberLike, cloudflareDurabilityCapabilities, durableObjectAdapter, hasCloudflareFiber, runWithCloudflareDurability };

package/dist/cloudflare/index.js

@@ -0,0 +1,212 @@
+import {
+  kvAdapter
+} from "../chunk-M4JW76IL.js";
+import {
+  defineCommand
+} from "../chunk-S7RZJMCF.js";
+
+// src/cloudflare/index.ts
+import { DurableObject } from "cloudflare:workers";
+
+// src/cloudflare/durability.ts
+function cloudflareDurabilityCapabilities(options) {
+  return {
+    runFiber: typeof options.agentInstance?.runFiber === "function",
+    keepAliveWhile: typeof options.agentInstance?.keepAliveWhile === "function",
+    waitUntil: typeof options.executionCtx?.waitUntil === "function"
+  };
+}
+function hasCloudflareFiber(agentInstance) {
+  return typeof agentInstance?.runFiber === "function";
+}
+async function runWithCloudflareDurability(options, run) {
+  const fiberName = options.fiberName ?? defaultFiberName();
+  const agentInstance = options.agentInstance;
+  if (typeof agentInstance?.runFiber === "function") {
+    return agentInstance.runFiber(fiberName, async (fiber) => {
+      if (options.stash !== void 0 && fiber?.stash) {
+        const value = typeof options.stash === "function" ? options.stash(fiberName) : options.stash;
+        await fiber.stash(value);
+      }
+      return run();
+    });
+  }
+  if (options.requireFiber) {
+    throw new Error(
+      "Cloudflare Agents SDK runFiber() is required for this operation. Pass an Agents SDK instance or disable requireFiber to allow keepAliveWhile()/waitUntil fallback."
+    );
+  }
+  if (typeof agentInstance?.keepAliveWhile === "function") {
+    return agentInstance.keepAliveWhile(run);
+  }
+  const promise = Promise.resolve().then(run);
+  try {
+    options.executionCtx?.waitUntil?.(promise);
+  } catch {
+  }
+  return promise;
+}
+function defaultFiberName() {
+  const cryptoLike = globalThis.crypto;
+  const randomUUID = cryptoLike?.randomUUID;
+  const id = typeof randomUUID === "function" ? randomUUID.call(cryptoLike) : `${Date.now()}:${Math.random().toString(16).slice(2)}`;
+  return `atlasflow:request:${id}`;
+}
+
+// src/cloudflare/index.ts
+var AtlasFlowStore = class extends DurableObject {
+  #adapter = kvAdapter(this.ctx.storage);
+  sessionGet(key) {
+    return this.#adapter.sessions.get(key);
+  }
+  sessionPut(key, data) {
+    return this.#adapter.sessions.put(key, data);
+  }
+  sessionDelete(key) {
+    return this.#adapter.sessions.delete(key);
+  }
+  runCreate(record) {
+    return this.#adapter.runs.create(record);
+  }
+  runUpdate(runId, patch) {
+    return this.#adapter.runs.update(runId, patch);
+  }
+  runGet(runId) {
+    return this.#adapter.runs.get(runId);
+  }
+  runList(filter) {
+    return this.#adapter.runs.list(filter);
+  }
+  runClaimLease(runId, owner, now, ttlMs) {
+    return this.#adapter.runs.claimLease(runId, owner, now, ttlMs);
+  }
+  runClaimQueued(runId, owner, now, ttlMs) {
+    return this.#adapter.runs.claimQueued(runId, owner, now, ttlMs);
+  }
+  runHeartbeatLease(runId, owner, now, ttlMs) {
+    return this.#adapter.runs.heartbeatLease(runId, owner, now, ttlMs);
+  }
+  runReleaseLease(runId, owner) {
+    return this.#adapter.runs.releaseLease(runId, owner);
+  }
+  runAppendEvent(runId, event) {
+    return this.#adapter.runs.appendEvent(runId, event);
+  }
+  runEvents(runId) {
+    return this.#adapter.runs.events(runId);
+  }
+  runEventCount(runId) {
+    return this.#adapter.runs.eventCount?.(runId) ?? this.#adapter.runs.events(runId).then((e) => e.length);
+  }
+  streamCreate(path, opts) {
+    return this.#adapter.streams.create(path, opts);
+  }
+  streamGet(path) {
+    return this.#adapter.streams.get(path);
+  }
+  streamDelete(path) {
+    return this.#adapter.streams.delete(path);
+  }
+  streamAppend(path, data, opts) {
+    return this.#adapter.streams.append(path, data, opts);
+  }
+  streamAppendWithProducer(path, data, opts) {
+    return this.#adapter.streams.appendWithProducer(path, data, opts);
+  }
+  streamClose(path) {
+    return this.#adapter.streams.close(path);
+  }
+  streamCloseWithProducer(path, producer) {
+    return this.#adapter.streams.closeWithProducer(path, producer);
+  }
+  streamMessages(path) {
+    return this.#adapter.streams.messages(path);
+  }
+  subscriptionCreateOrConfirm(id, input) {
+    return this.#adapter.subscriptions.createOrConfirm(id, input);
+  }
+  subscriptionGet(id) {
+    return this.#adapter.subscriptions.get(id);
+  }
+  subscriptionDelete(id) {
+    return this.#adapter.subscriptions.delete(id);
+  }
+  subscriptionAddExplicitStreams(id, streams) {
+    return this.#adapter.subscriptions.addExplicitStreams(id, streams);
+  }
+  subscriptionRemoveExplicitStream(id, streamPath) {
+    return this.#adapter.subscriptions.removeExplicitStream(id, streamPath);
+  }
+  subscriptionNotifyStreamAppend(streamPath, message) {
+    return this.#adapter.subscriptions.notifyStreamAppend(streamPath, message);
+  }
+  subscriptionNotifyStreamDelete(streamPath) {
+    return this.#adapter.subscriptions.notifyStreamDelete(streamPath);
+  }
+  subscriptionClaim(id, worker) {
+    return this.#adapter.subscriptions.claim(id, worker);
+  }
+  subscriptionAck(id, token, input) {
+    return this.#adapter.subscriptions.ack(id, token, input);
+  }
+  subscriptionRelease(id, token, input) {
+    return this.#adapter.subscriptions.release(id, token, input);
+  }
+  subscriptionStreamInfos(subscription) {
+    return this.#adapter.subscriptions.streamInfos(subscription);
+  }
+};
+function durableObjectAdapter(namespace, name = "atlasflow") {
+  const stub = () => namespace.get(namespace.idFromName(name));
+  return {
+    sessions: {
+      get: (k) => stub().sessionGet(k),
+      put: (k, d) => stub().sessionPut(k, d),
+      delete: (k) => stub().sessionDelete(k)
+    },
+    runs: {
+      create: (r) => stub().runCreate(r),
+      update: (id, p) => stub().runUpdate(id, p),
+      get: (id) => stub().runGet(id),
+      list: (f) => stub().runList(f),
+      claimLease: (id, owner, now, ttlMs) => stub().runClaimLease(id, owner, now, ttlMs),
+      claimQueued: (id, owner, now, ttlMs) => stub().runClaimQueued(id, owner, now, ttlMs),
+      heartbeatLease: (id, owner, now, ttlMs) => stub().runHeartbeatLease(id, owner, now, ttlMs),
+      releaseLease: (id, owner) => stub().runReleaseLease(id, owner),
+      appendEvent: (id, e) => stub().runAppendEvent(id, e),
+      events: (id) => stub().runEvents(id),
+      eventCount: (id) => stub().runEventCount(id)
+    },
+    streams: {
+      create: (path, opts) => stub().streamCreate(path, opts),
+      get: (path) => stub().streamGet(path),
+      delete: (path) => stub().streamDelete(path),
+      append: (path, data, opts) => stub().streamAppend(path, data, opts),
+      appendWithProducer: (path, data, opts) => stub().streamAppendWithProducer(path, data, opts),
+      close: (path) => stub().streamClose(path),
+      closeWithProducer: (path, producer) => stub().streamCloseWithProducer(path, producer),
+      messages: (path) => stub().streamMessages(path)
+    },
+    subscriptions: {
+      createOrConfirm: (id, input) => stub().subscriptionCreateOrConfirm(id, input),
+      get: (id) => stub().subscriptionGet(id),
+      delete: (id) => stub().subscriptionDelete(id),
+      addExplicitStreams: (id, streams) => stub().subscriptionAddExplicitStreams(id, streams),
+      removeExplicitStream: (id, streamPath) => stub().subscriptionRemoveExplicitStream(id, streamPath),
+      notifyStreamAppend: (streamPath, message) => stub().subscriptionNotifyStreamAppend(streamPath, message),
+      notifyStreamDelete: (streamPath) => stub().subscriptionNotifyStreamDelete(streamPath),
+      claim: (id, worker) => stub().subscriptionClaim(id, worker),
+      ack: (id, token, input) => stub().subscriptionAck(id, token, input),
+      release: (id, token, input) => stub().subscriptionRelease(id, token, input),
+      streamInfos: (subscription) => stub().subscriptionStreamInfos(subscription)
+    }
+  };
+}
+export {
+  AtlasFlowStore,
+  cloudflareDurabilityCapabilities,
+  defineCommand,
+  durableObjectAdapter,
+  hasCloudflareFiber,
+  runWithCloudflareDurability
+};

package/dist/command-kxrqWIH7.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Sandbox interfaces. A SandboxFactory creates a SessionEnv — a filesystem +
+ * shell from some provider. The agent never names a vendor. AtlasFs is the
+ * ergonomic wrapper exposed on harness/session `.fs`.
+ */
+
+interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface FileStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    size: number;
+    mtimeMs: number;
+}
+interface SessionEnv {
+    exec(command: string, options?: ExecOptions): Promise<ShellResult>;
+    /**
+     * Create an operation-scoped environment with extra host-implemented
+     * commands registered only for that operation. Sandboxes that cannot
+     * isolate command grants should leave this undefined.
+     */
+    scope?(options?: {
+        commands?: Command[];
+    }): Promise<SessionEnv>;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    stat(path: string): Promise<FileStat>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    cwd: string;
+    resolvePath(path: string): string;
+    /**
+     * Release whatever backs this environment (container, VM, temp dir). The
+     * runtime calls this when the invocation ends — connectors that provision
+     * remote infrastructure MUST implement it or every run leaks a billed box.
+     */
+    dispose?(): Promise<void>;
+}
+type SandboxHttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+interface SandboxEnvHeaderRef {
+    env: string;
+    prefix?: string;
+    required?: boolean;
+}
+type SandboxHeaderValue = string | SandboxEnvHeaderRef;
+interface SandboxAllowedUrl {
+    url: string;
+    /**
+     * Headers applied by the host-side fetch boundary. Use sandboxHeaderFromEnv()
+     * for credentials so secrets are never present in the sandbox process env.
+     */
+    headers?: Record<string, SandboxHeaderValue>;
+}
+type SandboxAllowedUrlEntry = string | SandboxAllowedUrl;
+interface SandboxNetworkPolicy {
+    allowedUrlPrefixes?: SandboxAllowedUrlEntry[];
+    allowedMethods?: SandboxHttpMethod[];
+    dangerouslyAllowFullInternetAccess?: boolean;
+    maxRedirects?: number;
+    timeoutMs?: number;
+    maxResponseSize?: number;
+    denyPrivateRanges?: boolean;
+    /** Test-only DNS resolver hook passed through to supported sandbox providers. */
+    _dnsResolve?: (hostname: string) => Promise<Array<{
+        address: string;
+        family: number;
+    }>>;
+}
+interface ResolvedSandboxAllowedUrl {
+    url: string;
+    transform?: Array<{
+        headers: Record<string, string>;
+    }>;
+}
+interface ResolvedSandboxNetworkPolicy extends Omit<SandboxNetworkPolicy, "allowedUrlPrefixes"> {
+    allowedUrlPrefixes?: Array<string | ResolvedSandboxAllowedUrl>;
+}
+declare function sandboxHeaderFromEnv(env: string, options?: {
+    prefix?: string;
+    required?: boolean;
+}): SandboxEnvHeaderRef;
+declare function resolveSandboxNetworkPolicy(policy: SandboxNetworkPolicy | undefined, env?: Record<string, unknown>): ResolvedSandboxNetworkPolicy | undefined;
+interface SandboxFactory {
+    createSessionEnv(options: {
+        id: string;
+        cwd?: string;
+        env?: Record<string, unknown>;
+    }): Promise<SessionEnv>;
+}
+interface SandboxSessionContext {
+    id: string;
+    cwd?: string;
+    env?: Record<string, unknown>;
+}
+interface SandboxLifecycleDefinition {
+    /** Provider selected for this sandbox. Use a function for simple local/provider cascade logic. */
+    factory: SandboxFactory | ((ctx: SandboxSessionContext) => SandboxFactory);
+    /** Runs once for this factory instance before the first session is created. */
+    bootstrap?: (ctx: SandboxSessionContext) => void | Promise<void>;
+    /** Runs for every session after the provider creates its environment. */
+    onSession?: (env: SessionEnv, ctx: SandboxSessionContext) => void | Promise<void>;
+    /** Runs when each session is disposed, after the provider environment is disposed. */
+    cleanup?: (ctx: SandboxSessionContext) => void | Promise<void>;
+}
+interface SandboxCascadeProvider {
+    /** Human-readable provider name used in failure messages. */
+    name: string;
+    /**
+     * Provider factory, or a resolver that can return undefined to skip this
+     * provider for the current session (for example when an env var is absent).
+     */
+    factory: SandboxFactory | ((ctx: SandboxSessionContext) => SandboxFactory | undefined | Promise<SandboxFactory | undefined>);
+    /** Optional predicate for provider availability. false means "skip", not failure. */
+    when?: (ctx: SandboxSessionContext) => boolean | Promise<boolean>;
+}
+type SandboxCascadeEntry = SandboxFactory | SandboxCascadeProvider;
+declare function defineSandbox(input: SandboxFactory | SandboxLifecycleDefinition): SandboxFactory;
+declare function sandboxCascade(entries: SandboxCascadeEntry[]): SandboxFactory;
+declare function isSandboxFactory(value: unknown): value is SandboxFactory;
+interface AtlasFs {
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    stat(path: string): Promise<FileStat>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+}
+declare function makeFs(env: SessionEnv): AtlasFs;
+/**
+ * Shared implementation of the AtlasFs.writeFile parent-creation guarantee.
+ * Adapters should route writes through this helper when their backing filesystem
+ * does not already create missing parent directories.
+ */
+declare function writeFileCreatingParents(write: () => Promise<void>, mkdirParent: () => Promise<unknown>): Promise<void>;
+declare function createCwdSessionEnv(parentEnv: SessionEnv, cwd: string): SessionEnv;
+/**
+ * Design note: a base class so connectors only implement what
+ * differs. Subclasses provide exec/read/write/stat/readdir/mkdir/rm; exists()
+ * and path resolution are handled here.
+ */
+declare abstract class BaseSandboxEnv implements SessionEnv {
+    abstract cwd: string;
+    abstract exec(command: string, options?: ExecOptions): Promise<ShellResult>;
+    abstract readFile(path: string): Promise<string>;
+    abstract readFileBuffer(path: string): Promise<Uint8Array>;
+    abstract writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    abstract stat(path: string): Promise<FileStat>;
+    abstract readdir(path: string): Promise<string[]>;
+    abstract mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    abstract rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    resolvePath(path: string): string;
+}
+
+type CommandExecutorResult = ShellResult | {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+} | string | void;
+type CommandExecutor = (args: string[], signal?: AbortSignal) => CommandExecutorResult | Promise<CommandExecutorResult>;
+/**
+ * A host-implemented command that can be granted to a just-bash-backed
+ * operation without exposing its secrets to the sandbox environment.
+ */
+interface Command {
+    name: string;
+    execute(args: string[], signal?: AbortSignal): Promise<ShellResult>;
+}
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+declare function normalizeCommandExecutor(execute: CommandExecutor): Command["execute"];
+declare function mergeCommands(defaults: Command[] | undefined, perCall: Command[] | undefined): Command[];
+declare function createScopedSessionEnv(env: SessionEnv, commands: Command[]): Promise<SessionEnv>;
+
+export { type AtlasFs as A, BaseSandboxEnv as B, type Command as C, writeFileCreatingParents as D, type ExecOptions as E, type FileStat as F, type ResolvedSandboxAllowedUrl as R, type SandboxNetworkPolicy as S, type CommandExecutor as a, type SandboxFactory as b, type SessionEnv as c, defineCommand as d, type ShellResult as e, type CommandExecutorResult as f, type ResolvedSandboxNetworkPolicy as g, type SandboxAllowedUrl as h, type SandboxAllowedUrlEntry as i, type SandboxCascadeEntry as j, type SandboxCascadeProvider as k, type SandboxEnvHeaderRef as l, type SandboxHeaderValue as m, type SandboxHttpMethod as n, type SandboxLifecycleDefinition as o, type SandboxSessionContext as p, createCwdSessionEnv as q, createScopedSessionEnv as r, defineSandbox as s, isSandboxFactory as t, makeFs as u, mergeCommands as v, normalizeCommandExecutor as w, resolveSandboxNetworkPolicy as x, sandboxCascade as y, sandboxHeaderFromEnv as z };