@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/execute-tool.js

@@ -0,0 +1,163 @@
+import { isSandboxFailure } from "./sandbox-boundary.js";
+import { ResultTooLarge, sandboxFailureMessage } from "./sandbox-failure.js";
+import { nanoid } from "@fungi.computer/cairn";
+import { forageDescribeInput, forageSearchInput, forageListInput, } from "@fungi.computer/forage";
+import { Type, } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { checkAccess } from "./access.js";
+import { normalizeExecutionPolicy, runExecution, } from "./internal/execution-lifecycle.js";
+import { ImageCollector } from "./image-collector.js";
+import { InvalidOperationInput } from "./errors.js";
+/** The one outer Mule input authority for the Mycelium execute door. */
+const ExecuteInputSchema = Schema.Struct({ code: Schema.String });
+const executeDescription = "Run async JavaScript in the sandbox. To enumerate all available operations, use forage.list({limit:50}) and follow nextCursor until null; optionally filter by namespace. Use await forage.search({ query: ... }) with short operation keywords, such as read or shell. Search matches operation names and descriptions; if no results match, retry with one relevant keyword. Then use await forage.describe({ path: ... }) to inspect the input before calling an operation. Describe known paths directly. For multiline shell commands, put the command in a JavaScript template literal, for example const command = `pwd\\nprintf done`; a physical newline inside a double-quoted JavaScript string is invalid source. Code is evaluated as JavaScript before shell commands run: if a shell command needs a backslash, write it doubled in the JavaScript string (for example, `\\\\(` passes `\\(` to the shell; `\\(` becomes `(`). For file edits, prefer Files operations when available. Explicitly return the final value. For shell or process results, inspect status, exitCode, and stderr when present before treating the operation as successful. Each execute call runs in a fresh sandbox: no variable, function, or other global survives from a previous call, so redefine any helpers you need every time, or persist state to a file and read it back instead.";
+/** One bound operation: its labels are checked against the host's grants first. */
+function guardedInvoke(entry, context, access, sessionId) {
+    const label = {
+        module: entry.grantKey,
+        operation: entry.name,
+        access: entry.operation.access,
+        confirm: entry.operation.confirm,
+    };
+    return async (input) => {
+        const refused = await checkAccess(access, { sessionId }, label, input, context.signal);
+        return refused ?? (await entry.operation.invoke(input, context));
+    };
+}
+function operationBindings(operations, context, access, sessionId) {
+    const groups = new Map();
+    for (const entry of operations) {
+        const namespace = entry.namespace;
+        const operationName = entry.name;
+        const group = groups.get(namespace) ??
+            new Map();
+        group.set(operationName, guardedInvoke(entry, context, access, sessionId));
+        groups.set(namespace, group);
+    }
+    return Object.freeze(Object.fromEntries([...groups].map(([namespace, operations]) => [
+        namespace,
+        Object.freeze(Object.fromEntries(operations)),
+    ])));
+}
+/** Parse a built-in Forage request; a bad request is the model's invalid input. */
+function forageRequest(schema, input) {
+    const request = schema.safeParse(input);
+    if (!request.success)
+        throw new InvalidOperationInput(request.error.issues);
+    return request.data;
+}
+function forageBindings(catalog) {
+    return Object.freeze({
+        list: (input) => Promise.resolve().then(() => catalog.list(forageRequest(forageListInput, input))),
+        describe: (input) => Promise.resolve().then(() => catalog.describe(forageRequest(forageDescribeInput, input))),
+        search: (input) => Promise.resolve().then(() => catalog.search(forageRequest(forageSearchInput, input))),
+    });
+}
+function bindings(operations, catalog, context, access, sessionId) {
+    return Object.freeze({
+        ...operationBindings(operations, context, access, sessionId),
+        forage: forageBindings(catalog),
+    });
+}
+/** Construct one execute door over a stable compiled surface and sandbox adapter. */
+export function createExecuteDoor(operations, catalog, sandbox, backingWork, modules, namespacePaths, sessionId, access) {
+    const policy = sandbox.execution ?? normalizeExecutionPolicy(undefined);
+    const imageCollector = new ImageCollector();
+    const run = (executionId, code, signal, toolCallId) => runExecution({
+        executionId,
+        toolCallId,
+        images: Object.freeze({
+            push: (image) => imageCollector.push(executionId, image),
+        }),
+        code,
+        callerSignal: signal,
+        policy,
+        sandbox,
+        backingWork,
+        createBindings: (context) => bindings(operations, catalog, Object.freeze({ ...context, toolCallCode: code }), access, sessionId),
+        modules,
+        namespacePaths,
+        sessionId,
+    });
+    /** Run one execution, then clear whatever images it collected. */
+    const execute = (code, signal) => Effect.suspend(() => {
+        const executionId = nanoid();
+        return run(executionId, code, signal).pipe(Effect.ensuring(Effect.sync(() => {
+            imageCollector.dispose(executionId);
+        })));
+    });
+    /**
+     * The Mule projection: after the run, drain the collector once and append
+     * its images after the text, on the oversized-result path too.
+     */
+    const executeTerminal = (code, toolCallId) => Effect.suspend(() => {
+        const executionId = nanoid();
+        const drain = () => imageCollector.drain(executionId);
+        return run(executionId, code, undefined, toolCallId).pipe(Effect.matchEffect({
+            onSuccess: (value) => Effect.succeed(terminal({ text: value.text, isError: false }, drain())),
+            onFailure: (error) => {
+                const images = drain();
+                return error instanceof ResultTooLarge && images.length > 0
+                    ? Effect.succeed(terminal({ text: sandboxFailureMessage(error), isError: true }, images))
+                    : Effect.fail(toMuleError(error));
+            },
+        }), Effect.ensuring(Effect.sync(() => {
+            imageCollector.dispose(executionId);
+        })));
+    });
+    const effectTool = {
+        // Guest JavaScript can invoke mutating operations, even when some bindings
+        // declare safe reads. Mule must never blindly replay this whole program.
+        replay: "unsafe",
+        descriptor: {
+            name: "execute",
+            description: executeDescription,
+            parameters: Type.Object({ code: Type.String() }, { additionalProperties: false }),
+        },
+        prepare: (call) => Schema.decodeUnknownEffect(ExecuteInputSchema)(call.arguments).pipe(Effect.map(({ code }) => ({
+            execute: () => Stream.fromEffect(executeTerminal(code, call.id)),
+        })), Effect.mapError(() => ({ message: "Invalid execute arguments" }))),
+    };
+    return Object.freeze({ effectTool, execute });
+}
+/**
+ * Project one finished run into Mule's only terminal part. Each collected
+ * image becomes an {@link ImageContent} part after the text, the same
+ * `MuleToolResult.content` every other tool result uses; its path, size and
+ * type go into `details`.
+ */
+function terminal(head, collected) {
+    const images = collected.map((image) => ({
+        type: "image",
+        data: image.data,
+        mimeType: image.mimeType,
+    }));
+    const content = [
+        { type: "text", text: head.text },
+        ...images,
+    ];
+    if (collected.length === 0)
+        return { type: "result", result: { content, isError: head.isError } };
+    const details = {
+        images: collected.map((image) => ({
+            bytes: image.bytes,
+            mimeType: image.mimeType,
+            path: image.path,
+        })),
+    };
+    return {
+        type: "result",
+        result: { content, details, isError: head.isError },
+    };
+}
+function toMuleError(error) {
+    return {
+        _tag: "MuleError",
+        phase: "tool",
+        message: isSandboxFailure(error)
+            ? sandboxFailureMessage(error)
+            : error.message,
+    };
+}

package/dist/image-collector.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Execution-scoped image collector, ported from the retained
+ * `@shiit/mycelium/execute` collector.
+ *
+ * Per-execution isolation for out-of-band image content: a connector
+ * operation (for example `images.view`) pushes one downsampled image through
+ * its `InvocationContext.images`, keyed by the execution's id. After the run,
+ * the execute tool drains the collector and appends the entries as
+ * `{ type: "image" }` content after the text: the same `MuleToolResult`
+ * content any other tool result carries, never a value the guest returns.
+ *
+ * - Per-execution isolation (the runtime's own execution id).
+ * - Bounded capacity per execution ({@link MAX_EXECUTION_IMAGES}).
+ * - In memory only: drained once, and cleared on dispose.
+ */
+/** A single image collected during an execute run. */
+export type CollectedImage = Readonly<{
+    /** Base64-encoded image bytes. */
+    data: string;
+    /** MIME type of the collected image. */
+    mimeType: "image/jpeg" | "image/png" | "image/webp";
+    /** Path the image was read from. */
+    path: string;
+    /** Byte length of the collected image payload. */
+    bytes: number;
+}>;
+/** The collector as one execution's operations see it: push only. */
+export type ExecutionImages = Readonly<{
+    /**
+     * Push one downsampled image and return its stable reference (`img_0`,
+     * `img_1`, ...) to surface as a text handle. Throws {@link CapabilityFailed}
+     * once the execution already holds the maximum.
+     */
+    push: (image: CollectedImage) => string;
+}>;
+/** Maximum number of out-of-band images retained for one execution. */
+export declare const MAX_EXECUTION_IMAGES = 8;
+export declare class ImageCollector {
+    #private;
+    constructor(maxPerExecution?: number);
+    /** Push one image for `executionId` and return its reference id. */
+    push(executionId: string, image: CollectedImage): string;
+    /** Drain every image for `executionId` in push order and forget them. */
+    drain(executionId: string): readonly CollectedImage[];
+    /** Discard any pending images for `executionId`; safe to call twice. */
+    dispose(executionId: string): void;
+}

package/dist/image-collector.js

@@ -0,0 +1,39 @@
+import { CapabilityFailed } from "./sandbox-failure.js";
+/** Maximum number of out-of-band images retained for one execution. */
+export const MAX_EXECUTION_IMAGES = 8;
+export class ImageCollector {
+    #byExecution = new Map();
+    #maxPerExecution;
+    constructor(maxPerExecution = MAX_EXECUTION_IMAGES) {
+        this.#maxPerExecution = maxPerExecution;
+    }
+    /** Push one image for `executionId` and return its reference id. */
+    push(executionId, image) {
+        const images = this.#byExecution.get(executionId) ?? [];
+        if (images.length >= this.#maxPerExecution)
+            throw new CapabilityFailed({
+                namespace: "execute",
+                operation: "images",
+                cause: {
+                    kind: "Unavailable",
+                    message: `Image collector cap reached for this execution (max ${String(this.#maxPerExecution)} images). Process images one at a time or write them to files.`,
+                },
+            });
+        const ref = `img_${String(images.length)}`;
+        images.push(Object.freeze({ ...image }));
+        this.#byExecution.set(executionId, images);
+        return ref;
+    }
+    /** Drain every image for `executionId` in push order and forget them. */
+    drain(executionId) {
+        const images = this.#byExecution.get(executionId);
+        if (images === undefined)
+            return [];
+        this.#byExecution.delete(executionId);
+        return images;
+    }
+    /** Discard any pending images for `executionId`; safe to call twice. */
+    dispose(executionId) {
+        this.#byExecution.delete(executionId);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+export { sandboxFailure, isSandboxFailure, sandboxOperatorValue, } from "./sandbox-boundary.js";
+import type { ForageCatalog } from "@fungi.computer/forage";
+import type { MuleTool } from "@fungi.computer/mule/effect";
+import type { Sandbox, MyceliumJsonValue } from "./sandbox.js";
+export type { MyceliumJsonValue, SandboxValue, SandboxBinding, SandboxRequest, Sandbox, } from "./sandbox.js";
+import type * as Schema from "effect/Schema";
+import type { OperationSchema } from "./operation-schema.js";
+import type { CapabilitySession, CapabilitySource } from "./capability-source.js";
+import type { SandboxFailureEvent } from "./sandbox-failure-event.js";
+import type { ExecutionImages } from "./image-collector.js";
+import type { ExecutionOptions } from "./execute-tool.js";
+import type { Access, AccessOptions, LabelledTool } from "./access.js";
+import { type ModuleRegistration, type OperationGate, type OperationRegistration } from "./registration.js";
+export type { CapabilitySession, CapabilitySource, CapabilitySourceAcquisition, CapabilitySourceContext, CapabilitySourceSnapshot, } from "./capability-source.js";
+export { InvalidOperationInput, InvalidOperationOutput, MyceliumClosedError, MyceliumDefinitionError, MyceliumSourceError, type MyceliumError, type MyceliumSourcePhase, } from "./errors.js";
+export { SourceInvalid, GuestThrew, DeadlineExceeded, Cancelled, DispatchLost, SandboxCrashed, BadResponse, ResultTooLarge, ResultNotJson, CapabilityFailed, Unknown, sandboxFailureMessage, type SandboxFailure, type CapabilityDiagnostic, type CapabilityFailureFields, } from "./sandbox-failure.js";
+export { SandboxFailureEventSchema, type SandboxFailureEvent, } from "./sandbox-failure-event.js";
+export type { ExecutionOptions } from "./execute-tool.js";
+export { GrantSchema, ToolAccessSchema, ToolConfirmSchema, ToolPolicySchema, } from "./access.js";
+export type { Access, AccessContext, AccessLabel, AccessOptions, AccessRefusal, AccessRefusalReason, ConfirmRequest, Grant, Grants, LabelledTool, ToolPolicy, } from "./access.js";
+export { MAX_EXECUTION_IMAGES, type CollectedImage, type ExecutionImages, } from "./image-collector.js";
+export type { OperationSchema, OperationSchemaIssue, OperationSchemaResult, StandardOperationSchema, } from "./operation-schema.js";
+export type { GateDecision, ModuleRegistration, OperationGate, OperationRegistration, } from "./registration.js";
+/** The only context an operation callback may observe. */
+export type InvocationContext = Readonly<{
+    /** Fresh identity for this invocation, independent from Mule's tool-call ID. */
+    executionId: string;
+    /** Enclosing model tool call; absent for direct operation/execute calls. */
+    toolCallId?: string;
+    /** Enclosing sandbox program supplied by the host; never an operation argument. */
+    toolCallCode?: string;
+    /** Absolute epoch-millisecond execute deadline; null for direct calls outside execute. */
+    deadlineAt: number | null;
+    /** Cooperative cancellation signal owned by the active Mule run. */
+    signal: AbortSignal;
+    /**
+     * This execution's image collector: an operation that lets the model look
+     * at an image pushes it here, and `execute` appends it as image content.
+     * Absent when a host invokes an operation directly, outside `execute`,
+     * where no tool result would carry the image.
+     */
+    images?: ExecutionImages;
+}>;
+/** Inputs used to construct the Promise-facing runtime. */
+export type MyceliumOptions = Readonly<{
+    /** Unordered module registrations compiled into one immutable revision. */
+    modules?: readonly ModuleRegistration[];
+    /** Versioned host projections reconciled into immutable revisions. */
+    sources?: readonly CapabilitySource[];
+    /** Session every source acquisition is made for; absent for session-free hosts. */
+    session?: CapabilitySession;
+    /** Bounded Mycelium-owned deadline and cancellation acknowledgement policy. */
+    execution?: ExecutionOptions;
+    /** Host-owned execution boundary for model-authored programs. */
+    sandbox: Sandbox;
+    /** Operator-only failure sink; never contributes a model message. */
+    onSandboxFailure?: (event: SandboxFailureEvent) => Promise<void>;
+    /** Labelled direct tools offered beside execute under the same access check. */
+    tools?: readonly LabelledTool[];
+    /** Host grants and approval, checked against each call's labels. */
+    access?: AccessOptions;
+}>;
+/** Cancellation options for one Promise-facing lease acquisition. */
+export type AcquireOptions = Readonly<{
+    /** Optional cancellation signal for lease acquisition. */
+    signal?: AbortSignal;
+}>;
+/** One immutable Promise-facing capability revision. */
+export type Lease = Readonly<{
+    /** Installed capability revision captured by this immutable lease. */
+    revision: string;
+    /** Bounded discovery catalog for the captured revision. */
+    catalog: ForageCatalog;
+    /** Single Mule tool that exposes discovery and scoped execution. */
+    executeTool: MuleTool;
+    /** The runtime's labelled direct tools, each behind the access check. */
+    tools: readonly MuleTool[];
+    /** Release the lease; safe to await more than once. */
+    release: () => Promise<void>;
+}>;
+/** Warm Promise-facing lifecycle for acquiring immutable run leases. */
+export type Runtime = Readonly<{
+    /** Acquire one immutable lease from the currently installed revision. */
+    acquire: (options?: AcquireOptions) => Promise<Lease>;
+    /** Stop new acquisition and await runtime-owned cleanup. */
+    close: () => Promise<void>;
+}>;
+/**
+ * Declaration for one operation behind the execute door. `input` and `output`
+ * may be Effect schemas (encoded as JSON) or any Standard Schema with
+ * Standard JSON Schema, such as Zod 4.
+ */
+export type OperationDefinition<I, O> = Readonly<{
+    /** Declaration for inventory; the enclosing model-facing execute tool remains unsafe. */
+    replay?: "safe" | "unsafe";
+    /**
+     * What this operation does: `read` observes, `write` changes something.
+     * A fixed fact the author owns; unlabelled is `write`. A host's `read`
+     * grant for this module runs only `read` operations.
+     */
+    access?: Access;
+    /** Ask a person to approve each call first; refused when no one can be asked. */
+    confirm?: boolean;
+    /** Bounded discovery text for the model. */
+    description?: string;
+    /** Schema that decodes untrusted operation input. */
+    input: OperationSchema<I>;
+    /** Optional schema that encodes (Effect) or validates (Standard) the result. */
+    output?: OperationSchema<O>;
+    /** Host implementation invoked only after input validation. */
+    execute: (input: I, context: InvocationContext) => Promise<O>;
+}>;
+/** Declaration for one stable module and its related operations. */
+export type ModuleDefinition = Readonly<{
+    /** Stable authority identity; independent from the model-facing alias. */
+    id: string;
+    /** Optional friendly name used to derive the model-facing alias. */
+    name?: string;
+    /** Parent namespaces in the guest environment, independent of authority identity. */
+    namespace?: readonly string[];
+    /** Bounded namespace instructions projected into Forage. */
+    description?: string;
+    /** Operations or child modules, keyed by a path segment or a dotted relative path such as `repos.list` (the guest calls it as `env.<module>.repos.list()`). A key that is both an operation and a namespace prefix is refused. */
+    operations: Readonly<Record<string, OperationRegistration | ModuleRegistration>>;
+}>;
+/** Public convenience namespace contract. */
+export type MyceliumApi = Readonly<{
+    /** Declare one namespaced collection of related operations. */
+    module: (definition: ModuleDefinition) => ModuleRegistration;
+    /**
+     * Declare one schema-described operation behind the execute door. An Effect
+     * output schema encodes the result to JSON; otherwise the result must
+     * already be a JSON value.
+     */
+    operation: {
+        <I, O>(definition: OperationDefinition<I, O> & {
+            readonly output: Schema.Codec<O, unknown>;
+        }): OperationRegistration<I, O>;
+        <I, O extends MyceliumJsonValue>(definition: OperationDefinition<I, O>): OperationRegistration<I, O>;
+    };
+    /** Open the Promise-shaped facade over Mycelium's Effect runtime. */
+    make: (options: MyceliumOptions) => Promise<Runtime>;
+    /** Put every operation of one module behind a host gate. */
+    gate: (module: ModuleRegistration, gate: OperationGate) => ModuleRegistration;
+    /** Look one module's grant up by `grantKey` instead of its id. */
+    grantAs: (module: ModuleRegistration, grantKey: string) => ModuleRegistration;
+}>;
+/** Schema-described authoring and Promise-facing runtime construction. */
+export declare const Mycelium: MyceliumApi;

package/dist/index.js

@@ -0,0 +1,22 @@
+export { sandboxFailure, isSandboxFailure, sandboxOperatorValue, } from "./sandbox-boundary.js";
+import { openPromiseRuntime } from "./promise-facade.js";
+import { defineModule, defineOperation, gateModule, grantModuleAs, } from "./registration.js";
+export { InvalidOperationInput, InvalidOperationOutput, MyceliumClosedError, MyceliumDefinitionError, MyceliumSourceError, } from "./errors.js";
+export { SourceInvalid, GuestThrew, DeadlineExceeded, Cancelled, DispatchLost, SandboxCrashed, BadResponse, ResultTooLarge, ResultNotJson, CapabilityFailed, Unknown, sandboxFailureMessage, } from "./sandbox-failure.js";
+export { SandboxFailureEventSchema, } from "./sandbox-failure-event.js";
+export { GrantSchema, ToolAccessSchema, ToolConfirmSchema, ToolPolicySchema, } from "./access.js";
+export { MAX_EXECUTION_IMAGES, } from "./image-collector.js";
+function operation(definition) {
+    return defineOperation(definition);
+}
+function module(definition) {
+    return defineModule(definition);
+}
+/** Schema-described authoring and Promise-facing runtime construction. */
+export const Mycelium = Object.freeze({
+    module,
+    operation,
+    make: openPromiseRuntime,
+    gate: gateModule,
+    grantAs: grantModuleAs,
+});

package/dist/internal/build-identity.d.ts

@@ -0,0 +1 @@
+export declare function sandboxBuildSha(): string | null;

package/dist/internal/build-identity.js

@@ -0,0 +1,15 @@
+// Platform-neutral default. Browser bundles (apps/demo, esbuild
+// `platform: "browser"`), Electron-renderer bundles
+// (electron-local-consumer-probe) and Workers bundles (apps/hub, wrangler)
+// all reach this module through execution-lifecycle.ts's `#build-identity`
+// internal import (package.json `imports`) and resolve to *this* file,
+// since none of those bundlers activate a `node` condition. This file must
+// never import `node:*` -- the real, Git-backed implementation lives in
+// build-identity.node.ts, which only a literal Node process (Node's own
+// resolver always activates the `node` condition) ever loads (2026-10-07
+// cache-hash-stability audit, S1 + the batch-368 gate failure it caused:
+// `Could not resolve "node:child_process"` while bundling
+// @fungi.computer/demo and electron-local-consumer-probe).
+export function sandboxBuildSha() {
+    return null;
+}

package/dist/internal/build-identity.node.d.ts

@@ -0,0 +1 @@
+export declare function sandboxBuildSha(): string | null;

package/dist/internal/build-identity.node.js

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+import { URL } from "node:url";
+// Node-only variant of build-identity.ts, selected only by the package's
+// `#build-identity` internal import (package.json `imports`, `node`
+// condition) -- a literal Node process (apps/exec, services/agent-host,
+// runtimes/local's non-bundled dist, this package's own tests) always
+// activates that condition; no bundler build target in this repo does
+// (demo and the Electron probe build with esbuild `platform: "browser"`;
+// Hub builds with wrangler/workerd), so this file's `node:child_process`
+// import never reaches a bundle that can't resolve it.
+//
+// Until 2026-10-07 the package build stamped execution-lifecycle.ts's
+// build-identity copy with the exact commit, and Turbo hashed that same
+// commit into the `build` task to avoid serving a stale stamp from cache.
+// That forced every commit to miss the cache for this package and the ~80
+// tasks across ~25 packages that depend on it (cache-hash-stability audit,
+// S1). The identity is read lazily instead: nothing calls this outside the
+// rare sandbox-failure path, so it costs a `git` call only when something
+// is actually tagging a failure, never at build, lint, typecheck or
+// ordinary test time, and the build output no longer depends on which
+// commit produced it. A source checkout without a reachable Git repository
+// (or a packed/registry install, which carries no `.git` at all) answers
+// `null`; `pnpm pack` stamps its own copy of this file with a literal
+// identity instead (package.json's `pack` script, scripts/stamp-build.mjs),
+// since a packed copy can't shell out to Git once installed.
+let cached;
+export function sandboxBuildSha() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        const candidate = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: new URL(".", import.meta.url),
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        cached = /^[0-9a-f]{40}$/u.test(candidate) ? candidate : null;
+    }
+    catch {
+        cached = null;
+    }
+    return cached;
+}

package/dist/internal/execution-lifecycle.d.ts

@@ -0,0 +1,44 @@
+import { type SandboxFailure } from "../sandbox-failure.js";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import type { ExecutionOptions } from "../execute-tool.js";
+import { type MyceliumError } from "../errors.js";
+import type { InvocationContext, SandboxValue } from "../index.js";
+import type { ExecutionImages } from "../image-collector.js";
+import type { EffectSandbox } from "../runtime.js";
+export type ExecutionPolicy = Readonly<{
+    readonly timeoutMs: number;
+    readonly abortGraceMs: number;
+}>;
+export type BackingWorkGroup = Readonly<{
+    readonly start: <A, E>(effect: Effect.Effect<A, E>) => Effect.Effect<Fiber.Fiber<A, E>, SandboxFailure>;
+    readonly awaitIdle: Effect.Effect<void>;
+}>;
+export type BackingWorkTracker = Readonly<{
+    readonly createGroup: () => BackingWorkGroup;
+}>;
+export declare function normalizeExecutionPolicy(value: ExecutionOptions | undefined): ExecutionPolicy;
+export declare function createBackingWorkTracker(): BackingWorkTracker;
+export type SerializedSandboxValue = Readonly<{
+    readonly text: string;
+}>;
+export type RawBindings = Readonly<Record<string, Readonly<Record<string, (input: SandboxValue) => Promise<SandboxValue>>>>>;
+export type ExecutionLifecycleRequest = Readonly<{
+    readonly toolCallId?: string | undefined;
+    /** This run's identity, minted by the execute door that drains its images. */
+    readonly executionId: string;
+    /** This run's slot in the door's collector, exposed through the context. */
+    readonly images: ExecutionImages;
+    readonly code: string;
+    readonly callerSignal: AbortSignal | undefined;
+    readonly policy: ExecutionPolicy;
+    readonly sandbox: EffectSandbox;
+    readonly backingWork: BackingWorkGroup;
+    readonly createBindings: (context: InvocationContext) => RawBindings;
+    /** Every bound execution alias mapped to its stable module id. */
+    readonly modules: Readonly<Record<string, string>>;
+    readonly namespacePaths: Readonly<Record<string, readonly string[]>>;
+    /** Stable Session identity for this run; null for session-free hosts. */
+    readonly sessionId: string | null;
+}>;
+export declare function runExecution(request: ExecutionLifecycleRequest): Effect.Effect<SerializedSandboxValue, MyceliumError>;