@fungi.computer/mycelium 0.1.0 → 0.2.1

package/README.md

@@ -102,6 +102,33 @@ Access checks and authorization gates run before the operation. Product
 membership, resource ownership and final external access checks remain host
 responsibilities.
 
+Each `execute` call runs in a fresh sandbox, not a REPL: no variable, function
+or global survives between calls. Redefine helpers in every call, or persist
+state to a file and read it back.
+
+### Operation identity within execute
+
+Every registered-operation call receives a frozen `InvocationContext` with a
+zero-based `operationOrdinal`. One counter spans all registered methods and
+modules in an execute. Allocation happens synchronously when the binding is
+called, before asynchronous admission or operation work, so sequential calls and
+concurrently started calls have distinct positions. Forage's built-in discovery
+helpers do not consume registered-operation positions.
+
+The counter resets for each execute attempt. Replaying the same bound-call
+sequence gives the same ordinals even though `executionId` is fresh. A host that
+needs effect deduplication combines its stored Session and command identities
+with `toolCallId` and `operationOrdinal`; an ordinal alone is not a globally
+unique identity. Different call sequences are not promised identical positions,
+and the effect owner must still compare the intended operation and payload on
+replay. This metadata grants neither authority nor permission to replay unsafe
+work.
+
+Direct `invokeModuleOperation` callers supply their own context; outside an
+execute there is no enclosing call sequence, so `operationOrdinal` may be
+absent, just as `toolCallId` may be absent. A host requiring execute identity
+must refuse a write with missing identity rather than invent a fallback.
+
 ## Access labels and grants
 
 Each operation's author labels what it does: `access: "read"` observes,
@@ -193,6 +220,44 @@ bounded `sandboxFailureMessage` projection with a reference. The host receives
 operator evidence through `onSandboxFailure` and the existing reporting path.
 Preserve that evidence without sending host diagnostics to the guest.
 
+### Sandbox admission
+
+The host-only `execution` options accept `sandboxCapacity` (a positive safe
+integer) and `admissionWaitMs` (an integer from 1 to 900,000 milliseconds,
+default 5,000). Guests still submit only `code`. An omitted capacity derives
+from available cores, clamped to 2..32; hosts without a portable core
+observation use 2. Node captures its affinity-aware core count once per runtime
+through `node:os.availableParallelism()`, behind a platform-conditional module
+outside the Workers import graph. Explicit valid capacity overrides bypass
+observation and are not clamped, including values above 32.
+
+`normalizeSandboxAdmissionPolicy(options, availableCores?)` validates and
+resolves these host facts. It does not reserve a slot or start a sandbox. Both
+public runtime facades validate and capture the policy when the runtime opens.
+
+Admission belongs to the existing runtime-wide backing-work tracker, not each
+lease, group, or revision. A full pool waits until a slot opens or the earlier
+of the admission-wait deadline and the **original invocation deadline**.
+Admission-wait expiry yields `SandboxBusy`, stable code `sandbox-busy`, with
+safe `capacity` and `waitedMs` facts; the submitted program has not run.
+Invocation-deadline expiry remains `DeadlineExceeded`, including when both
+deadlines coincide. Caller cancellation remains `Cancelled`. Queueing does not
+restart the execution timeout. No automatic replay is authorized.
+
+The runtime uses one maintained Effect semaphore across source revisions and
+interruptible deadline APIs. Queued work is registered before waiting.
+Cancellation removes queued work; no expired/cancelled waiter may start later. A
+permit remains owned until actual backing settlement, including after an
+unacknowledged abort. Waiting does not hold the lifecycle/revision gate needed
+for release or close.
+
+`SandboxBusy` is admitted by the existing owned-error decoder, safe transport,
+host wire and operator-event grammar; it is contention, not an `Unknown` health
+alert. The execute tool retains its safe typed cause and an actionable coded
+message without changing Mule's error contract. Unrelated foreign failures stay
+`Unknown`: do not classify diagnostic prose, unwrap arbitrary cause chains, or
+mislabel an arbitrary adapter `AbortError` as caller-authorized cancellation.
+
 An Effect host with a Promise sandbox uses `fromTypedSandbox`, which waits for
 that Promise to settle when interrupted. The concrete sandbox and broker decide
 how backing work is stopped. Hosts supply the Worker Loader binding and
@@ -287,13 +352,11 @@ grants. The MCP server independently checks the stored principal. The Session's
 `call` must carry `McpExecutionContext.access` into its ordinary Mycelium
 execution, including direct tools, without persisting request callbacks.
 
-MCP execution requires approval for every write-level operation not covered by
-the catalog snapshot's `approvedWrites`, including unlabelled operations. Read
-operations retain their declared confirmation policy. `approvedWrites` names
-granted modules whose writes a person already approved for that principal; it is
-read from the current snapshot at each call, and an operation labelled `confirm`
-still asks. Form elicitation runs before the operation, and authority is
-refreshed again after acceptance; missing or declined approval refuses
+MCP does not force confirmation for every write. The host's durable approval
+owner decides whether a write applies, waits for approval or is denied; the
+catalog's grants remain authority ceilings, not approval decisions. Explicit
+operation-level confirmation labels still use form elicitation and refresh
+authority after acceptance. Missing or declined explicit confirmation refuses
 execution. The server supports MCP `2025-11-25` Streamable HTTP so an approval
 can suspend the existing execution without replaying already-completed
 operations. Approval requests contain the module, operation and access label,

package/dist/access.d.ts

@@ -65,7 +65,8 @@ export type AccessRefusal = Readonly<{
  * Host-supplied access data and the one way to ask a person. Every field is
  * optional: hosted defaults allow unnamed modules, and no `confirm` means an
  * operation requiring approval is refused, never run unasked. MCP catalogs
- * explicitly default unnamed modules to none and require approval for writes.
+ * explicitly default unnamed modules to none. Native hosts own durable approval
+ * policy for admitted writes; explicit author confirmation still uses this port.
  */
 export type AccessOptions = Readonly<{
     /** Grant for unnamed modules; MCP catalogs use none. Defaults to write for hosted callers. */
@@ -87,12 +88,6 @@ export type AccessOptions = Readonly<{
     beforeCall?: (signal: AbortSignal) => Promise<void>;
     /** Require approval for every write, including operations without an explicit confirm label. */
     confirmWrites?: boolean;
-    /**
-     * Read, at every call, the module ids whose writes a person already
-     * approved for this caller. Such a write needs no per-call `confirm`; an
-     * operation its author labelled `confirm` still asks, and grants still apply.
-     */
-    approvedWrites?: (context: AccessContext) => readonly string[];
     /** Ask a person to approve one call; resolve true to run it. */
     confirm?: ((request: ConfirmRequest, signal: AbortSignal) => Promise<boolean>) | undefined;
     /** Operator-only observer of every refusal; never changes the decision. */

package/dist/access.js

@@ -100,9 +100,6 @@ async function decide(options, context, label, input, signal) {
     if (!label.confirm &&
         !(options.confirmWrites === true && label.access !== "read"))
         return undefined;
-    if (!label.confirm &&
-        options.approvedWrites?.(context).includes(label.module) === true)
-        return undefined;
     if (options.confirm === undefined)
         return refusal("confirmation-unavailable", label);
     const approved = await options.confirm({

package/dist/execute-tool.d.ts

@@ -6,13 +6,14 @@ import type { CompiledOperation } from "./compiler.js";
 import { type BackingWorkGroup, type SerializedSandboxValue } from "./internal/execution-lifecycle.js";
 import { type MyceliumError } from "./errors.js";
 import type { EffectSandbox } from "./runtime.js";
-/** Host-selectable execution limits; neither budget can be disabled. */
+import type { SandboxAdmissionOptions } from "./sandbox-admission.js";
+/** Host execution limits plus the reserved, host-only admission contract. */
 export type ExecutionOptions = Readonly<{
     /** Total execution deadline in milliseconds. */
     timeoutMs?: number;
     /** Maximum acknowledgement wait after cancellation in milliseconds. */
     abortGraceMs?: number;
-}>;
+}> & SandboxAdmissionOptions;
 /** The Effect-owned execute implementation shared by both public projections. */
 export type ExecuteDoor = Readonly<{
     readonly effectTool: MuleTool;

package/dist/execute-tool.js

@@ -1,18 +1,20 @@
 import { isSandboxFailure } from "./sandbox-boundary.js";
-import { ResultTooLarge, sandboxFailureMessage } from "./sandbox-failure.js";
+import { ResultTooLarge, SandboxBusy, 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 Fiber from "effect/Fiber";
 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 { OutputCollector } from "./output-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.";
+const executeDescription = 'Run async JavaScript in the sandbox. Each call is a fresh sandbox, not a REPL: nothing survives between calls, so redefine helpers or persist state to a file. Never shadow injected module names with local bindings. Find operations with await forage.search({ query }) using one short keyword such as read or shell, or page them all with forage.list({limit:50}), optionally by namespace, until nextCursor is null. Inspect input with await forage.describe({ path }) before calling; describe known paths directly. Call an operation as await env.<path>({ ... }) with the exact dotted path, for example await env.computers.local.exec({ command: "pwd" }); a bare computers.local.exec is not defined. Put multiline shell commands in a template literal. Code is JavaScript first, so double each backslash the shell needs (`\\\\(` passes `\\(`; `\\(` becomes `(`). For file edits, prefer Files operations when available. Explicitly return the final value. Before treating a shell or process result as success, check status, exitCode and stderr.';
 /** One bound operation: its labels are checked against the host's grants first. */
 function guardedInvoke(entry, context, access, sessionId) {
     const label = {
@@ -27,13 +29,19 @@ function guardedInvoke(entry, context, access, sessionId) {
     };
 }
 function operationBindings(operations, context, access, sessionId) {
+    // One counter per execute, shared by every bound method. Allocate before
+    // awaiting access or operation work, not in asynchronous completion order.
+    let nextOperationOrdinal = 0;
     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));
+        group.set(operationName, (input) => guardedInvoke(entry, Object.freeze({
+            ...context,
+            operationOrdinal: nextOperationOrdinal++,
+        }), access, sessionId)(input));
         groups.set(namespace, group);
     }
     return Object.freeze(Object.fromEntries([...groups].map(([namespace, operations]) => [
@@ -65,9 +73,10 @@ function bindings(operations, catalog, context, access, sessionId) {
 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({
+    const run = (executionId, code, signal, toolCallId, output) => runExecution({
         executionId,
         toolCallId,
+        output,
         images: Object.freeze({
             push: (image) => imageCollector.push(executionId, image),
         }),
@@ -92,10 +101,10 @@ export function createExecuteDoor(operations, catalog, sandbox, backingWork, mod
      * 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 executeTerminal = (code, toolCallId, output) => Effect.suspend(() => {
         const executionId = nanoid();
         const drain = () => imageCollector.drain(executionId);
-        return run(executionId, code, undefined, toolCallId).pipe(Effect.matchEffect({
+        return run(executionId, code, undefined, toolCallId, output).pipe(Effect.matchEffect({
             onSuccess: (value) => Effect.succeed(terminal({ text: value.text, isError: false }, drain())),
             onFailure: (error) => {
                 const images = drain();
@@ -117,7 +126,26 @@ export function createExecuteDoor(operations, catalog, sandbox, backingWork, mod
             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)),
+            execute: () => Stream.unwrap(Effect.gen(function* () {
+                const collector = yield* OutputCollector.make();
+                yield* Effect.addFinalizer(() => Effect.sync(() => {
+                    collector.dispose();
+                }));
+                // Start execution in this stream's scope before starting readers:
+                // admission/deadlines must not wait for an output subscriber.
+                const execution = yield* Effect.forkScoped(executeTerminal(code, call.id, {
+                    write: (stream, bytes) => {
+                        collector.write(stream, bytes);
+                    },
+                }), { startImmediately: true });
+                return Stream.merge(collector.updates, Stream.fromEffect(Fiber.await(execution)).pipe(Stream.flatMap((exit) => {
+                    const finalOutput = collector.finish();
+                    // Observe completion as data so diagnostics precede either
+                    // outcome. Re-yield the original Exit (including its Cause);
+                    // Mule alone projects failures into error terminal results.
+                    return Stream.concat(Stream.fromIterable(finalOutput === undefined ? [] : [finalOutput]), Stream.fromEffect(exit));
+                })), { haltStrategy: "right" }).pipe(Stream.takeUntil((part) => part.type === "result"));
+            })),
         })), Effect.mapError(() => ({ message: "Invalid execute arguments" }))),
     };
     return Object.freeze({ effectTool, execute });
@@ -126,7 +154,7 @@ export function createExecuteDoor(operations, catalog, sandbox, backingWork, mod
  * 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`.
+ * type go into application `data`, separate from the model content.
  */
 function terminal(head, collected) {
     const images = collected.map((image) => ({
@@ -140,7 +168,7 @@ function terminal(head, collected) {
     ];
     if (collected.length === 0)
         return { type: "result", result: { content, isError: head.isError } };
-    const details = {
+    const data = {
         images: collected.map((image) => ({
             bytes: image.bytes,
             mimeType: image.mimeType,
@@ -149,15 +177,16 @@ function terminal(head, collected) {
     };
     return {
         type: "result",
-        result: { content, details, isError: head.isError },
+        result: { content, data, isError: head.isError },
     };
 }
 function toMuleError(error) {
-    return {
+    const result = {
         _tag: "MuleError",
         phase: "tool",
         message: isSandboxFailure(error)
             ? sandboxFailureMessage(error)
             : error.message,
     };
+    return error instanceof SandboxBusy ? { ...result, cause: error } : result;
 }

package/dist/image-collector.d.ts

@@ -18,7 +18,7 @@ export type CollectedImage = Readonly<{
     /** Base64-encoded image bytes. */
     data: string;
     /** MIME type of the collected image. */
-    mimeType: "image/jpeg" | "image/png" | "image/webp";
+    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
     /** Path the image was read from. */
     path: string;
     /** Byte length of the collected image payload. */

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { sandboxFailure, isSandboxFailure, sandboxOperatorValue, } from "./sandbox-boundary.js";
 import type { ForageCatalog } from "@fungi.computer/forage";
+export { normalizeSandboxAdmissionPolicy, type SandboxAdmissionOptions, type SandboxAdmissionPolicy, } from "./sandbox-admission.js";
 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";
@@ -13,7 +14,7 @@ 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 { SourceInvalid, GuestThrew, DeadlineExceeded, SandboxBusy, 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";
@@ -27,6 +28,13 @@ export type InvocationContext = Readonly<{
     executionId: string;
     /** Enclosing model tool call; absent for direct operation/execute calls. */
     toolCallId?: string;
+    /**
+     * Zero-based registered-operation call position within this execute.
+     * Assigned before asynchronous admission, across all methods and modules.
+     * Replaying the same call sequence produces the same positions. Absent
+     * outside execute-bound invocation; not an authorization or replay grant.
+     */
+    operationOrdinal?: number;
     /** Enclosing sandbox program supplied by the host; never an operation argument. */
     toolCallCode?: string;
     /** Absolute epoch-millisecond execute deadline; null for direct calls outside execute. */
@@ -40,6 +48,11 @@ export type InvocationContext = Readonly<{
      * where no tool result would carry the image.
      */
     images?: ExecutionImages;
+    /** Process-local stdout/stderr tail sink; absent outside an execute tool run. */
+    output?: Readonly<{
+        /** Append raw bytes to the execution-owned bounded stdout/stderr tail. */
+        write: (stream: "stdout" | "stderr", bytes: Uint8Array) => void;
+    }>;
 }>;
 /** Inputs used to construct the Promise-facing runtime. */
 export type MyceliumOptions = Readonly<{

package/dist/index.js

@@ -1,8 +1,9 @@
 export { sandboxFailure, isSandboxFailure, sandboxOperatorValue, } from "./sandbox-boundary.js";
+export { normalizeSandboxAdmissionPolicy, } from "./sandbox-admission.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 { SourceInvalid, GuestThrew, DeadlineExceeded, SandboxBusy, 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";

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

@@ -2,7 +2,7 @@ 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,
+// condition) -- a literal Node process (apps/exec,
 // 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"`;

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

@@ -1,12 +1,13 @@
 import { type SandboxFailure } from "../sandbox-failure.js";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
+import { type SandboxAdmissionPolicy } from "../sandbox-admission.js";
 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<{
+export type ExecutionPolicy = SandboxAdmissionPolicy & Readonly<{
     readonly timeoutMs: number;
     readonly abortGraceMs: number;
 }>;
@@ -18,7 +19,7 @@ export type BackingWorkTracker = Readonly<{
     readonly createGroup: () => BackingWorkGroup;
 }>;
 export declare function normalizeExecutionPolicy(value: ExecutionOptions | undefined): ExecutionPolicy;
-export declare function createBackingWorkTracker(): BackingWorkTracker;
+export declare function createBackingWorkTracker(capacity: number): Effect.Effect<BackingWorkTracker>;
 export type SerializedSandboxValue = Readonly<{
     readonly text: string;
 }>;
@@ -29,6 +30,7 @@ export type ExecutionLifecycleRequest = Readonly<{
     readonly executionId: string;
     /** This run's slot in the door's collector, exposed through the context. */
     readonly images: ExecutionImages;
+    readonly output?: InvocationContext["output"];
     readonly code: string;
     readonly callerSignal: AbortSignal | undefined;
     readonly policy: ExecutionPolicy;

package/dist/internal/execution-lifecycle.js

@@ -1,27 +1,28 @@
 import { sandboxFailure, isSandboxFailure, sandboxOperatorValue, sandboxValueKind, } from "../sandbox-boundary.js";
 import { sandboxBuildSha } from "#build-identity";
+import { availableHostCores } from "#host-cores";
 import * as Metric from "effect/Metric";
-import { referenceSandboxFailure, DeadlineExceeded, Cancelled, ResultTooLarge, ResultNotJson, CapabilityFailed, } from "../sandbox-failure.js";
+import { referenceSandboxFailure, DeadlineExceeded, Cancelled, ResultTooLarge, ResultNotJson, CapabilityFailed, SandboxBusy, } from "../sandbox-failure.js";
 import { ForageError } from "@fungi.computer/forage";
 import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
+import * as Semaphore from "effect/Semaphore";
 import { z } from "zod";
+import { normalizeSandboxAdmissionPolicy, sandboxAdmissionOptionsSchema, } from "../sandbox-admission.js";
 import { InvalidOperationInput, MyceliumDefinitionError, } from "../errors.js";
 const jsonValueSchema = z.json();
 const jsonScalarSchema = z.lazy(() => z.union([z.null(), z.string(), z.boolean(), z.number()]));
 const jsonRecordSchema = z.lazy(() => z.record(z.string(), z.unknown()));
-const executionOptionsSchema = z.lazy(() => z
-    .object({
+const executionOptionsSchema = z.lazy(() => sandboxAdmissionOptionsSchema
+    .extend({
     timeoutMs: z.number().int().min(1).max(900_000).optional(),
     abortGraceMs: z.number().int().min(1).max(30_000).optional(),
 })
-    .strict()
     .optional());
 const maximumJsonDepth = 64;
 const maximumSerializedJsonBytes = 256 * 1024;
-const maximumBackingExecutions = 8;
 const utf8 = new TextEncoder();
 const resumeIdle = (notify) => {
     notify(Effect.succeed(undefined));
@@ -34,50 +35,44 @@ export function normalizeExecutionPolicy(value) {
     return Object.freeze({
         timeoutMs: parsed.data?.timeoutMs ?? 180_000,
         abortGraceMs: parsed.data?.abortGraceMs ?? 5_000,
+        ...normalizeSandboxAdmissionPolicy({
+            sandboxCapacity: parsed.data?.sandboxCapacity,
+            admissionWaitMs: parsed.data?.admissionWaitMs,
+        }, parsed.data?.sandboxCapacity === undefined
+            ? availableHostCores()
+            : undefined),
     });
 }
-export function createBackingWorkTracker() {
-    let active = 0;
-    return Object.freeze({
-        createGroup: () => {
-            let groupActive = 0;
-            const waiters = new Set();
-            const awaitIdle = Effect.callback((resume) => {
-                if (groupActive === 0) {
-                    resume(Effect.succeed(undefined));
-                    return Effect.sync(() => undefined);
-                }
-                waiters.add(resume);
-                return Effect.sync(() => waiters.delete(resume));
-            });
-            return Object.freeze({
-                start: (effect) => Effect.uninterruptibleMask((restore) => Effect.sync(() => {
-                    if (active >= maximumBackingExecutions)
-                        return false;
-                    active += 1;
-                    groupActive += 1;
-                    return true;
-                }).pipe(Effect.flatMap((reserved) => reserved
-                    ? Effect.forkDetach(restore(effect).pipe(Effect.ensuring(Effect.sync(() => {
-                        active -= 1;
+export function createBackingWorkTracker(capacity) {
+    return Effect.gen(function* () {
+        const permits = yield* Semaphore.make(capacity);
+        return Object.freeze({
+            createGroup: () => {
+                let groupActive = 0;
+                const waiters = new Set();
+                const awaitIdle = Effect.callback((resume) => {
+                    if (groupActive === 0) {
+                        resume(Effect.succeed(undefined));
+                        return Effect.sync(() => undefined);
+                    }
+                    waiters.add(resume);
+                    return Effect.sync(() => waiters.delete(resume));
+                });
+                return Object.freeze({
+                    start: (effect) => Effect.uninterruptibleMask((restore) => Effect.sync(() => {
+                        groupActive += 1;
+                    }).pipe(Effect.andThen(Effect.forkDetach(restore(permits.withPermits(1)(effect)).pipe(Effect.ensuring(Effect.sync(() => {
                         groupActive -= 1;
                         if (groupActive === 0) {
                             const pending = [...waiters];
                             waiters.clear();
                             pending.forEach(resumeIdle);
                         }
-                    }))))
-                    : Effect.fail(new CapabilityFailed({
-                        namespace: "execute",
-                        operation: "admission",
-                        cause: {
-                            kind: "Unavailable",
-                            message: "Sandbox execution capacity unavailable",
-                        },
-                    }))))),
-                awaitIdle,
-            });
-        },
+                    }))))))),
+                    awaitIdle,
+                });
+            },
+        });
     });
 }
 function normalizeJson(value, depth = 0) {
@@ -178,13 +173,25 @@ export function runExecution(request) {
     return Clock.currentTimeMillis.pipe(Effect.flatMap((startedAt) => Effect.suspend(() => {
         const executionId = request.executionId;
         const controller = new AbortController();
+        let queuedAt = startedAt;
+        let admission = {
+            kind: "waiting",
+        };
         let cancellation;
         const cancel = (phase) => {
-            if (cancellation === undefined) {
+            if (cancellation === undefined && admission.kind !== "refused") {
                 cancellation = phase;
                 controller.abort();
             }
         };
+        const refuseAdmission = (now) => {
+            const failure = new SandboxBusy({
+                capacity: request.policy.capacity,
+                waitedMs: Math.max(0, now - queuedAt),
+            });
+            admission = { kind: "refused", failure };
+            return failure;
+        };
         const admit = () => {
             if (controller.signal.aborted)
                 throw executionFailure(cancellation, request.policy.timeoutMs);
@@ -192,18 +199,28 @@ export function runExecution(request) {
         const detachCaller = forwardAbort(request.callerSignal, () => {
             cancel("cancelled");
         });
+        const deadlineAt = startedAt + request.policy.timeoutMs;
         const invocation = {
             executionId,
-            deadlineAt: startedAt + request.policy.timeoutMs,
+            deadlineAt,
             signal: controller.signal,
             images: request.images,
         };
         if (request.toolCallId !== undefined)
             Object.assign(invocation, { toolCallId: request.toolCallId });
+        if (request.output !== undefined)
+            Object.assign(invocation, { output: request.output });
         const context = Object.freeze(invocation);
-        const sandboxExecution = Effect.suspend(() => {
+        const sandboxExecution = Effect.suspend(() => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => {
+            if (admission.kind === "refused")
+                return Effect.fail(admission.failure);
+            if (now >= deadlineAt)
+                cancel("deadline_exceeded");
             if (controller.signal.aborted)
                 return elapsedSince(startedAt).pipe(Effect.flatMap((elapsedMs) => Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs))));
+            if (now >= queuedAt + request.policy.waitMs)
+                return Effect.fail(refuseAdmission(now));
+            admission = { kind: "admitted" };
             return request.sandbox
                 .execute(Object.freeze({
                 executionId,
@@ -221,7 +238,7 @@ export function runExecution(request) {
                 .pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
                 ? Effect.failCause(cause)
                 : Effect.fail(sandboxFailure(Cause.squash(cause)))));
-        });
+        })));
         const interruptBacking = (child) => Fiber.interrupt(child).pipe(Effect.timeoutOrElse({
             duration: request.policy.abortGraceMs,
             orElse: () => Effect.fail(cancellation === "deadline_exceeded"
@@ -280,8 +297,39 @@ export function runExecution(request) {
                 const elapsedMs = yield* elapsedSince(startedAt);
                 return yield* Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs));
             }
+            queuedAt = yield* Clock.currentTimeMillis;
             child = yield* request.backingWork.start(sandboxExecution);
-            const first = yield* Effect.raceFirst(Fiber.await(child).pipe(Effect.map((exit) => Object.freeze({ kind: "settled", exit }))), Effect.raceFirst(Effect.sleep(request.policy.timeoutMs).pipe(Effect.as(Object.freeze({ kind: "deadline" }))), waitForAbort(controller.signal).pipe(Effect.as(Object.freeze({ kind: "cancelled" })))));
+            const now = yield* Clock.currentTimeMillis;
+            const capacityWait = Effect.sleep(Math.max(0, queuedAt + request.policy.waitMs - now)).pipe(Effect.andThen(Clock.currentTimeMillis), Effect.flatMap((at) => {
+                if (admission.kind === "admitted")
+                    return Effect.never;
+                if (admission.kind === "refused")
+                    return Effect.succeed({
+                        kind: "busy",
+                        failure: admission.failure,
+                    });
+                if (controller.signal.aborted)
+                    return Effect.succeed({ kind: "cancelled" });
+                if (at >= deadlineAt) {
+                    cancel("deadline_exceeded");
+                    return Effect.succeed({ kind: "deadline" });
+                }
+                return Effect.succeed({
+                    kind: "busy",
+                    failure: refuseAdmission(at),
+                });
+            }));
+            const first = yield* Effect.raceFirst(Fiber.await(child).pipe(Effect.map((exit) => Object.freeze({ kind: "settled", exit }))), Effect.raceFirst(Effect.sleep(Math.max(0, deadlineAt - now)).pipe(Effect.andThen(Effect.sync(() => {
+                cancel("deadline_exceeded");
+                return Object.freeze({ kind: "deadline" });
+            }))), Effect.raceFirst(waitForAbort(controller.signal).pipe(Effect.as(Object.freeze({ kind: "cancelled" }))), capacityWait)));
+            const refusal = admission.kind === "refused"
+                ? admission.failure
+                : first.kind === "busy"
+                    ? first.failure
+                    : undefined;
+            if (refusal !== undefined)
+                return yield* interruptBacking(child).pipe(Effect.andThen(Effect.fail(refusal)));
             if (first.kind === "settled") {
                 return yield* Effect.matchCauseEffectEager(first.exit, {
                     onFailure: (cause) => 

package/dist/internal/host-cores.d.ts

@@ -0,0 +1,2 @@
+/** Workers and browser hosts have no portable core observation. */
+export declare function availableHostCores(): number | undefined;

package/dist/internal/host-cores.js

@@ -0,0 +1,4 @@
+/** Workers and browser hosts have no portable core observation. */
+export function availableHostCores() {
+    return undefined;
+}

package/dist/internal/host-cores.node.d.ts

@@ -0,0 +1,2 @@
+/** Node's maintained, affinity-aware observation; captured by runtime policy. */
+export declare function availableHostCores(): number;