@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/source-runtime.js

@@ -0,0 +1,162 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import { z } from "zod";
+import { compileSurface, } from "./compiler.js";
+import { MyceliumDefinitionError, MyceliumSourceError, } from "./errors.js";
+import { createExecuteDoor } from "./execute-tool.js";
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+const maximumCapabilitySources = 128;
+const sourceIdSchema = z.string().min(1).max(160);
+const sourceSnapshotSchema = z.object({
+    version: z.string().min(1).max(160),
+    modules: z.array(z.unknown()),
+});
+const maximumCandidateModules = 1_000;
+function validateSources(input) {
+    if (input.length > maximumCapabilitySources) {
+        throw new MyceliumDefinitionError("Capability source count exceeds bound");
+    }
+    const sources = [...input].sort((left, right) => compareCodeUnits(left.id, right.id));
+    const ids = new Set();
+    for (const source of sources) {
+        if (!sourceIdSchema.safeParse(source.id).success) {
+            throw new MyceliumDefinitionError("Capability source id must be non-empty and bounded");
+        }
+        if (ids.has(source.id)) {
+            throw new MyceliumDefinitionError(`Duplicate capability source id: ${source.id}`);
+        }
+        ids.add(source.id);
+    }
+    return sources;
+}
+function validateCandidateModuleCount(count) {
+    if (count > maximumCandidateModules) {
+        throw new MyceliumDefinitionError("Candidate module count exceeds bound");
+    }
+}
+function validateSourceSnapshot(snapshot, existingModuleCount) {
+    const parsed = sourceSnapshotSchema.safeParse(snapshot);
+    if (!parsed.success) {
+        throw new MyceliumDefinitionError("Capability source snapshot must have a non-empty bounded version");
+    }
+    validateCandidateModuleCount(existingModuleCount + parsed.data.modules.length);
+}
+function acquireSourceIntoScope(source, candidateScope, cleanupFailures, invalidate, session) {
+    return Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        const release = (acquired) => Effect.tryPromise({
+            try: () => acquired.release(),
+            catch: () => new MyceliumSourceError(source.id, "release"),
+        }).pipe(Effect.catch((failure) => Effect.sync(() => {
+            cleanupFailures.push(failure);
+        })));
+        const state = yield* Effect.try({
+            try: () => {
+                const controller = new AbortController();
+                return {
+                    controller,
+                    outcome: source
+                        .acquire(session === undefined
+                        ? { signal: controller.signal, invalidate }
+                        : { signal: controller.signal, invalidate, session })
+                        .then((acquired) => Exit.succeed(acquired), () => Exit.fail(new MyceliumSourceError(source.id, "acquire"))),
+                };
+            },
+            catch: () => new MyceliumSourceError(source.id, "acquire"),
+        });
+        yield* Scope.addFinalizer(candidateScope, Effect.promise(() => state.outcome).pipe(Effect.flatMap((outcome) => Exit.isSuccess(outcome) ? release(outcome.value) : Effect.void)));
+        const outcome = yield* restore(Effect.promise(() => state.outcome)).pipe(Effect.onInterrupt(() => Effect.sync(() => {
+            state.controller.abort();
+        })));
+        if (Exit.isFailure(outcome)) {
+            return yield* Effect.failCause(outcome.cause);
+        }
+        return outcome.value;
+    }));
+}
+/** Acquire one complete candidate attempt without mutating installed state. */
+function acquireCandidateAttempt(options) {
+    return Effect.gen(function* () {
+        const sources = yield* Effect.try({
+            try: () => validateSources(options.sources),
+            catch: (cause) => cause instanceof MyceliumDefinitionError
+                ? cause
+                : new MyceliumDefinitionError("Capability sources are invalid"),
+        });
+        yield* Effect.try({
+            try: () => {
+                validateCandidateModuleCount(options.modules.length);
+            },
+            catch: (cause) => cause instanceof MyceliumDefinitionError
+                ? cause
+                : new MyceliumDefinitionError("Static capability modules are invalid"),
+        });
+        const candidateScope = yield* Scope.make();
+        const cleanupFailures = [];
+        let stale = false;
+        const modules = [...options.modules];
+        const sourceFrames = [];
+        const acquireAll = Effect.gen(function* () {
+            for (const source of sources) {
+                const acquired = yield* acquireSourceIntoScope(source, candidateScope, cleanupFailures, () => {
+                    stale = true;
+                }, options.session);
+                yield* Effect.try({
+                    try: () => {
+                        validateSourceSnapshot(acquired.snapshot, modules.length);
+                    },
+                    catch: (cause) => cause instanceof MyceliumDefinitionError
+                        ? cause
+                        : new MyceliumDefinitionError("Capability source snapshot is invalid"),
+                });
+                modules.push(...acquired.snapshot.modules);
+                sourceFrames.push({
+                    id: source.id,
+                    version: acquired.snapshot.version,
+                });
+            }
+            const compiled = options.precompiled ??
+                (yield* Effect.try({
+                    try: () => compileSurface(modules, sourceFrames),
+                    catch: (cause) => cause instanceof MyceliumDefinitionError
+                        ? cause
+                        : new MyceliumDefinitionError("Capability compilation failed"),
+                }));
+            const backingWork = options.backingWork.createGroup();
+            const executeDoor = createExecuteDoor(compiled.operations, compiled.catalog, options.sandbox, backingWork, compiled.moduleAliases, compiled.namespacePaths, options.session?.sessionId ?? null, options.access);
+            let closed = false;
+            const close = () => Effect.gen(function* () {
+                if (!closed) {
+                    closed = true;
+                    yield* backingWork.awaitIdle;
+                    yield* Scope.close(candidateScope, Exit.void);
+                }
+                const cleanupFailure = cleanupFailures[0];
+                if (cleanupFailure !== undefined)
+                    yield* Effect.fail(cleanupFailure);
+            });
+            return Object.freeze({
+                compiled,
+                executeDoor,
+                isStale: () => stale,
+                close,
+            });
+        });
+        return yield* acquireAll.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Scope.close(candidateScope, exit)));
+    });
+}
+const maximumCandidateAttempts = 2;
+/** Acquire one non-stale candidate or fail after one bounded retry. */
+export function acquireSourceCandidate(options) {
+    return Effect.gen(function* () {
+        for (let attempt = 0; attempt < maximumCandidateAttempts; attempt += 1) {
+            const candidate = yield* acquireCandidateAttempt(options);
+            if (!candidate.isStale())
+                return candidate;
+            yield* candidate.close();
+        }
+        return yield* Effect.fail(new MyceliumSourceError(undefined, "stale"));
+    });
+}

package/dist/testing.d.ts

@@ -0,0 +1,11 @@
+import type { Sandbox, SandboxRequest, SandboxValue } from "./index.js";
+/** A test callback receives the admitted bindings and cancellation. */
+export type DirectSandboxCallback = (bindings: SandboxRequest["bindings"], signal: AbortSignal) => Promise<SandboxValue>;
+/**
+ * Dispatch a known-binding callback directly in this process. NOT isolation:
+ * submitted code is ignored, and the callback retains all host privileges.
+ * Use only trusted tests and examples, never model-authored code execution.
+ */
+export declare function directSandbox(callback: DirectSandboxCallback): Sandbox;
+/** A test transport that always refuses execution with the supplied message. */
+export declare function rejectingSandbox(message: string): Sandbox;

package/dist/testing.js

@@ -0,0 +1,19 @@
+/**
+ * Dispatch a known-binding callback directly in this process. NOT isolation:
+ * submitted code is ignored, and the callback retains all host privileges.
+ * Use only trusted tests and examples, never model-authored code execution.
+ */
+export function directSandbox(callback) {
+    return {
+        execute: async (request, signal) => {
+            signal.throwIfAborted();
+            const result = await callback(request.bindings, signal);
+            signal.throwIfAborted();
+            return result;
+        },
+    };
+}
+/** A test transport that always refuses execution with the supplied message. */
+export function rejectingSandbox(message) {
+    return directSandbox(() => Promise.reject(new Error(message)));
+}

package/dist/workers/index.d.ts

@@ -0,0 +1,9 @@
+import type { Sandbox } from "@fungi.computer/mycelium";
+/** The Worker Loader binding Codemode runs guests on. */
+export type CodemodeLoader = WorkerLoader;
+/** Local development facts supplied by the host, never by guest code. */
+export type CodemodeSandboxOptions = Readonly<{
+    localDevUnenforcedLimits?: readonly ("cpu" | "memory" | "output" | "cancel")[];
+}>;
+/** Construct a network-isolated Codemode sandbox over a Worker Loader. */
+export declare function createCodemodeSandbox(loader: CodemodeLoader, adapter?: string, options?: CodemodeSandboxOptions): Sandbox;

package/dist/workers/index.js

@@ -0,0 +1,90 @@
+/**
+ * A Mycelium sandbox over Cloudflare Codemode: each `execute` call runs the
+ * model's program in a fresh Dynamic Worker (Worker Loader) with no network,
+ * and the bound operations are its only way out. For Workers hosts.
+ */
+import { DynamicWorkerExecutor, normalizeCode } from "@cloudflare/codemode";
+import { BadResponse, Cancelled, DispatchLost, SourceInvalid, } from "@fungi.computer/mycelium/sandbox-failure";
+import { sandboxBindingNames, sandboxGuestProgram, sandboxGuestResultSchema, sandboxProviderOperationName, submittedSourceLocation, } from "@fungi.computer/mycelium/sandbox-guest";
+import { isSandboxFailure, sandboxBindingBoundary, sandboxExecutorFailure, sandboxGuestFailure, } from "@fungi.computer/mycelium/sandbox-boundary";
+const unenforcedLimitMessages = {
+    cpu: "CPU limits are not enforced in local dev",
+    memory: "Memory limits are not enforced in local dev",
+    output: "Output limits are not enforced in local dev",
+    cancel: "Cancellation limits are not enforced in local dev",
+};
+const reportedUnenforcedLimits = new Set();
+/** Construct a network-isolated Codemode sandbox over a Worker Loader. */
+export function createCodemodeSandbox(loader, adapter = "codemode-workerd", options = {}) {
+    for (const limit of options.localDevUnenforcedLimits ?? []) {
+        const message = unenforcedLimitMessages[limit];
+        if (!reportedUnenforcedLimits.has(message)) {
+            reportedUnenforcedLimits.add(message);
+            console.warn(message);
+        }
+    }
+    return {
+        adapter,
+        async execute(request, signal) {
+            const startedAt = Date.now();
+            try {
+                signal.throwIfAborted();
+                const normalized = normalizeCode(request.code);
+                const location = submittedSourceLocation(normalized, request.code);
+                if (location !== null)
+                    throw new SourceInvalid(location);
+                const boundary = sandboxBindingBoundary(request.bindings);
+                const withCpuBudget = (definition) => ({
+                    ...definition,
+                    limits: {
+                        ...definition.limits,
+                        cpuMs: Math.min(request.timeoutMs, definition.limits?.cpuMs ?? request.timeoutMs),
+                    },
+                });
+                const executor = new DynamicWorkerExecutor({
+                    loader: {
+                        load: (definition) => loader.load(withCpuBudget(definition)),
+                        get: (name, getCode) => loader.get(name, async () => withCpuBudget(await getCode())),
+                    },
+                    timeout: request.timeoutMs,
+                    globalOutbound: null,
+                });
+                // Codemode has no cancellation API; keep its promise until it settles
+                // so Mycelium owns the cancellation grace.
+                const output = await executor.execute(sandboxGuestProgram(normalized, sandboxBindingNames(boundary.bindings), request.namespacePaths, sandboxProviderOperationName), Object.entries(boundary.bindings).map(([name, operations]) => ({
+                    name,
+                    fns: Object.fromEntries(Object.entries(operations).map(([operation, binding]) => [
+                        sandboxProviderOperationName(operation),
+                        binding,
+                    ])),
+                })));
+                signal.throwIfAborted();
+                if (output.error !== undefined)
+                    throw sandboxExecutorFailure(output.error, request.timeoutMs, Date.now() - startedAt);
+                const decoded = sandboxGuestResultSchema.safeParse(output.result);
+                if (!decoded.success)
+                    throw new BadResponse({
+                        reason: "invalid guest envelope",
+                        rawCause: decoded.error,
+                    });
+                if (!decoded.data.ok)
+                    throw boundary.recover(sandboxGuestFailure(decoded.data.error, request.bindings));
+                const returned = boundary.returnedFailure(decoded.data.value);
+                if (returned !== undefined)
+                    throw returned;
+                return decoded.data.value;
+            }
+            catch (cause) {
+                if (signal.aborted)
+                    throw new Cancelled({ by: "caller" });
+                if (isSandboxFailure(cause))
+                    throw cause;
+                throw new DispatchLost({
+                    elapsedMs: Date.now() - startedAt,
+                    transport: adapter,
+                    rawCause: cause,
+                });
+            }
+        },
+    };
+}

package/docs/api/README.md

@@ -0,0 +1,25 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/mycelium**
+
+---
+
+# @fungi.computer/mycelium
+
+## Modules
+
+| Module                                          | Description |
+| ----------------------------------------------- | ----------- |
+| [define](define.md)                             | -           |
+| [effect](effect.md)                             | -           |
+| [index](index.md)                               | -           |
+| [mcp](mcp.md)                                   | -           |
+| [remote](remote.md)                             | -           |
+| [sandbox-boundary](sandbox-boundary.md)         | -           |
+| [sandbox-failure](sandbox-failure.md)           | -           |
+| [sandbox-guest](sandbox-guest.md)               | -           |
+| [sandbox-wire](sandbox-wire.md)                 | -           |
+| [sandbox](sandbox.md)                           | -           |
+| [semaphore-transition](semaphore-transition.md) | -           |
+| [testing](testing.md)                           | -           |
+| [workers](workers.md)                           | -           |

package/docs/api/define.md

@@ -0,0 +1,20 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / define
+
+# define
+
+## Variables
+
+### Mycelium
+
+```ts
+const Mycelium: Pick<MyceliumApi, "module" | "operation" | "gate">;
+```
+
+The authoring half of [MyceliumApi](index.md#myceliumapi); registrations are the
+same handles.

package/docs/api/effect.md

@@ -0,0 +1,245 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / effect
+
+# effect
+
+## Type Aliases
+
+### Sandbox
+
+```ts
+type Sandbox = Readonly<{
+  execute: (request, signal) => Effect.Effect<SandboxValue, SandboxFailure>;
+  adapter?: string;
+  buildSha?: string;
+}>;
+```
+
+Effect-native host seam for sandbox execution.
+
+Interrupting `execute` must not complete until the backing work has actually
+settled. Mycelium bounds that wait by the acknowledgement grace and reports
+`abort_unacknowledged` when it expires, keeping the work's source revision alive
+until it exits. A host with Promise-shaped work adapts it with
+[fromTypedSandbox](#fromtypedsandbox); `Effect.tryPromise` alone completes
+interruption without awaiting the Promise and so breaks that settlement law.
+
+---
+
+### MyceliumOptions
+
+```ts
+type MyceliumOptions = Readonly<{
+  modules?: readonly ModuleRegistration[];
+  sources?: readonly CapabilitySource[];
+  session?: CapabilitySession;
+  execution?: ExecutionOptions;
+  sandbox: Sandbox;
+  onSandboxFailure?: (event) => Effect.Effect<void>;
+  tools?: readonly LabelledTool[];
+  access?: AccessOptions;
+}>;
+```
+
+Inputs used to construct the canonical Effect runtime.
+
+---
+
+### Lease
+
+```ts
+type Lease = Readonly<{
+  revision: string;
+  catalog: ForageCatalog;
+  executeTool: MuleTool;
+  tools: readonly MuleTool[];
+  release: () => Effect.Effect<void, MyceliumError>;
+}>;
+```
+
+One immutable Effect-facing capability revision.
+
+---
+
+### Runtime
+
+```ts
+type Runtime = Readonly<{
+  acquire: () => Effect.Effect<Lease, MyceliumError, Scope.Scope>;
+  close: () => Effect.Effect<void, MyceliumError>;
+}>;
+```
+
+Warm Effect lifecycle for acquiring scope-owned run leases.
+
+## Functions
+
+### fromTypedSandbox()
+
+```ts
+function fromTypedSandbox(sandbox): Sandbox;
+```
+
+Adapt a Promise-shaped sandbox to the Effect seam. This is Mycelium's one
+Promise sandbox conversion: interruption waits for the host Promise to settle,
+while cancellation reaches the host through the abort signal.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `sandbox` | [`Sandbox`](sandbox.md#sandbox) |
+
+#### Returns
+
+[`Sandbox`](#sandbox)
+
+---
+
+### make()
+
+```ts
+function make(options): Effect<
+  Readonly<{
+    acquire: () => Effect<
+      Readonly<{
+        revision: string;
+        catalog: ForageCatalog;
+        executeTool: MuleTool;
+        tools: readonly MuleTool[];
+        release: () => Effect<void, MyceliumError>;
+      }>,
+      MyceliumError,
+      Scope
+    >;
+    close: () => Effect<void, MyceliumError>;
+  }>,
+  MyceliumError,
+  Scope
+>;
+```
+
+Construct the canonical scoped Effect runtime.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `options` | [`MyceliumOptions`](#myceliumoptions) |
+
+#### Returns
+
+`Effect`\<`Readonly`\<\{ `acquire`: () => `Effect`\<`Readonly`\<\{ `revision`:
+`string`; `catalog`: `ForageCatalog`; `executeTool`: `MuleTool`; `tools`:
+readonly `MuleTool`[]; `release`: () => `Effect`\<`void`,
+[`MyceliumError`](index.md#myceliumerror)\>; \}\>,
+[`MyceliumError`](index.md#myceliumerror), `Scope`\>; `close`: () =>
+`Effect`\<`void`, [`MyceliumError`](index.md#myceliumerror)\>; \}\>,
+[`MyceliumError`](index.md#myceliumerror), `Scope`\>
+
+## References
+
+### CapabilitySession
+
+Re-exports [CapabilitySession](index.md#capabilitysession)
+
+---
+
+### CapabilitySource
+
+Re-exports [CapabilitySource](index.md#capabilitysource)
+
+---
+
+### ModuleRegistration
+
+Re-exports [ModuleRegistration](index.md#moduleregistration)
+
+---
+
+### SandboxBinding
+
+Re-exports [SandboxBinding](sandbox.md#sandboxbinding)
+
+---
+
+### SandboxRequest
+
+Re-exports [SandboxRequest](sandbox.md#sandboxrequest)
+
+---
+
+### ExecutionOptions
+
+Re-exports [ExecutionOptions](index.md#executionoptions)
+
+---
+
+### Access
+
+Re-exports [Access](index.md#access)
+
+---
+
+### AccessContext
+
+Re-exports [AccessContext](index.md#accesscontext)
+
+---
+
+### AccessLabel
+
+Re-exports [AccessLabel](index.md#accesslabel)
+
+---
+
+### AccessOptions
+
+Re-exports [AccessOptions](index.md#accessoptions)
+
+---
+
+### AccessRefusal
+
+Re-exports [AccessRefusal](index.md#accessrefusal)
+
+---
+
+### AccessRefusalReason
+
+Re-exports [AccessRefusalReason](index.md#accessrefusalreason)
+
+---
+
+### ConfirmRequest
+
+Re-exports [ConfirmRequest](index.md#confirmrequest)
+
+---
+
+### Grant
+
+Re-exports [Grant](index.md#grant)
+
+---
+
+### Grants
+
+Re-exports [Grants](index.md#grants)
+
+---
+
+### LabelledTool
+
+Re-exports [LabelledTool](index.md#labelledtool)
+
+---
+
+### ToolPolicy
+
+Re-exports [ToolPolicy](index.md#toolpolicy)