@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/internal/execution-lifecycle.js

@@ -0,0 +1,328 @@
+import { sandboxFailure, isSandboxFailure, sandboxOperatorValue, sandboxValueKind, } from "../sandbox-boundary.js";
+import { sandboxBuildSha } from "#build-identity";
+import * as Metric from "effect/Metric";
+import { referenceSandboxFailure, DeadlineExceeded, Cancelled, ResultTooLarge, ResultNotJson, CapabilityFailed, } 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 { z } from "zod";
+import { InvalidOperationInput, MyceliumDefinitionError, } from "../errors.js";
+const jsonValueSchema = z.json();
+const jsonScalarSchema = z.union([
+    z.null(),
+    z.string(),
+    z.boolean(),
+    z.number(),
+]);
+const jsonRecordSchema = z.record(z.string(), z.unknown());
+const executionOptionsSchema = z
+    .object({
+    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));
+};
+export function normalizeExecutionPolicy(value) {
+    const parsed = executionOptionsSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new MyceliumDefinitionError("Execution policy is invalid");
+    }
+    return Object.freeze({
+        timeoutMs: parsed.data?.timeoutMs ?? 180_000,
+        abortGraceMs: parsed.data?.abortGraceMs ?? 5_000,
+    });
+}
+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;
+                        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,
+            });
+        },
+    });
+}
+function normalizeJson(value, depth = 0) {
+    if (depth > maximumJsonDepth) {
+        throw new Error("JSON value exceeds the nesting bound");
+    }
+    const scalar = jsonScalarSchema.safeParse(value);
+    if (scalar.success)
+        return scalar.data;
+    if (Array.isArray(value))
+        return value.map((item) => normalizeJson(item, depth + 1));
+    const record = jsonRecordSchema.safeParse(value);
+    if (!record.success)
+        throw record.error;
+    return Object.fromEntries(Object.entries(record.data)
+        .filter(([, item]) => item !== undefined)
+        .map(([key, item]) => [key, normalizeJson(item, depth + 1)]));
+}
+function jsonValue(value) {
+    return jsonValueSchema.parse(normalizeJson(value));
+}
+function serializeSandboxValue(value) {
+    const text = JSON.stringify(jsonValue(value));
+    const size = utf8.encode(text).byteLength;
+    if (size > maximumSerializedJsonBytes) {
+        throw new ResultTooLarge({ size });
+    }
+    return Object.freeze({ text });
+}
+function guardedBindings(raw, admit) {
+    return Object.freeze(Object.fromEntries(Object.entries(raw).map(([namespace, operations]) => [
+        namespace,
+        Object.freeze(Object.fromEntries(Object.entries(operations).map(([name, operation]) => [
+            name,
+            async (input) => {
+                admit();
+                try {
+                    return jsonValue(await operation(input));
+                }
+                catch (cause) {
+                    if (isSandboxFailure(cause))
+                        throw cause;
+                    if (cause instanceof ForageError)
+                        throw new CapabilityFailed({
+                            namespace,
+                            operation: name,
+                            cause: { kind: "Forage", message: cause.message },
+                            rawCause: cause,
+                        });
+                    if (cause instanceof InvalidOperationInput)
+                        throw new CapabilityFailed({
+                            namespace,
+                            operation: name,
+                            cause: {
+                                kind: "InvalidInput",
+                                message: `Invalid operation input: ${z.prettifyError({ issues: cause.issues })}; use forage.describe`,
+                            },
+                            rawCause: cause,
+                        });
+                    // Capability owners/adapters may admit their own typed diagnostics (Files, etc.).
+                    throw cause;
+                }
+            },
+        ]))),
+    ])));
+}
+function waitForAbort(signal) {
+    return Effect.callback((resume) => {
+        const onAbort = resume.bind(undefined, Effect.void);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+        return Effect.sync(signal.removeEventListener.bind(signal, "abort", onAbort));
+    });
+}
+function forwardAbort(source, onAbort) {
+    if (source === undefined)
+        return () => undefined;
+    const forward = onAbort.bind(undefined);
+    if (source.aborted) {
+        forward();
+        return () => undefined;
+    }
+    source.addEventListener("abort", forward, { once: true });
+    return source.removeEventListener.bind(source, "abort", forward);
+}
+function executionFailure(cancellation, timeoutMs, elapsedMs) {
+    return cancellation === "deadline_exceeded"
+        ? new DeadlineExceeded({ limitMs: timeoutMs, elapsedMs: elapsedMs ?? 0 })
+        : new Cancelled({ by: "caller" });
+}
+/** Wall time since `startedAt`, read through Effect's Clock so tests using TestClock stay deterministic. */
+function elapsedSince(startedAt) {
+    return Clock.currentTimeMillis.pipe(Effect.map((now) => now - startedAt));
+}
+export function runExecution(request) {
+    return Clock.currentTimeMillis.pipe(Effect.flatMap((startedAt) => Effect.suspend(() => {
+        const executionId = request.executionId;
+        const controller = new AbortController();
+        let cancellation;
+        const cancel = (phase) => {
+            if (cancellation === undefined) {
+                cancellation = phase;
+                controller.abort();
+            }
+        };
+        const admit = () => {
+            if (controller.signal.aborted)
+                throw executionFailure(cancellation, request.policy.timeoutMs);
+        };
+        const detachCaller = forwardAbort(request.callerSignal, () => {
+            cancel("cancelled");
+        });
+        const invocation = {
+            executionId,
+            deadlineAt: startedAt + request.policy.timeoutMs,
+            signal: controller.signal,
+            images: request.images,
+        };
+        if (request.toolCallId !== undefined)
+            Object.assign(invocation, { toolCallId: request.toolCallId });
+        const context = Object.freeze(invocation);
+        const sandboxExecution = Effect.suspend(() => {
+            if (controller.signal.aborted)
+                return elapsedSince(startedAt).pipe(Effect.flatMap((elapsedMs) => Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs))));
+            return request.sandbox
+                .execute(Object.freeze({
+                executionId,
+                code: request.code,
+                timeoutMs: request.policy.timeoutMs,
+                bindings: guardedBindings(request.createBindings(context), admit),
+                // B3c (adr-guest-code-broker addendum): `buildGuestBindings`
+                // classifies every compiled alias by its STABLE MODULE ID,
+                // never its Team-chosen alias, so the sandbox needs both of
+                // these to reach a retained operation at all.
+                modules: request.modules,
+                namespacePaths: request.namespacePaths,
+                sessionId: request.sessionId,
+            }), controller.signal)
+                .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"
+                ? new DeadlineExceeded({
+                    limitMs: request.policy.timeoutMs,
+                    elapsedMs: request.policy.timeoutMs,
+                    acknowledged: false,
+                })
+                : new Cancelled({ by: "caller", acknowledged: false })),
+        }));
+        let child;
+        let reported = false;
+        const reportFailure = (cause) => {
+            reported = true;
+            return elapsedSince(startedAt).pipe(Effect.flatMap((elapsedMs) => {
+                const normalized = sandboxFailure(cause);
+                const timed = normalized instanceof DeadlineExceeded
+                    ? new DeadlineExceeded({
+                        limitMs: normalized.limitMs,
+                        elapsedMs,
+                        acknowledged: normalized.acknowledged,
+                    })
+                    : normalized;
+                const failure = referenceSandboxFailure(timed, executionId);
+                const fields = z
+                    .record(z.string(), z.json())
+                    .parse(sandboxOperatorValue(timed));
+                fields.ref = executionId;
+                const event = {
+                    kind: "sandbox_failure",
+                    ref: executionId,
+                    executionId,
+                    adapter: request.sandbox.adapter ?? "effect",
+                    buildSha: request.sandbox.buildSha ?? sandboxBuildSha(),
+                    tag: failure._tag,
+                    fields,
+                    healthAlert: failure._tag === "Unknown",
+                };
+                const report = Effect.suspend(() => request.sandbox.onFailure?.(event) ?? Effect.void);
+                return Effect.logError("sandbox_failure", event).pipe(Effect.annotateLogs({
+                    executionId,
+                    ref: executionId,
+                    adapter: event.adapter,
+                    tag: event.tag,
+                    buildSha: event.buildSha,
+                }), Effect.andThen(failure._tag === "Unknown"
+                    ? Metric.update(Metric.withAttributes(Metric.counter("sandbox_unknown"), { adapter: event.adapter }), 1).pipe(Effect.andThen(Effect.logError("sandbox_health_alert").pipe(Effect.annotateLogs({
+                        ref: executionId,
+                        adapter: event.adapter,
+                    }))))
+                    : Effect.void), Effect.andThen(report.pipe(Effect.catchCause((reportCause) => Effect.logError("sandbox_failure_record_failed", reportCause)))), Effect.as(failure));
+            }));
+        };
+        const run = Effect.gen(function* () {
+            if (controller.signal.aborted) {
+                const elapsedMs = yield* elapsedSince(startedAt);
+                return yield* Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs));
+            }
+            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" })))));
+            if (first.kind === "settled") {
+                return yield* Effect.matchCauseEffectEager(first.exit, {
+                    onFailure: (cause) => 
+                    // A cancellation or deadline was already decided before this
+                    // fiber settled: the sandbox's own failure is very likely a
+                    // side effect of that abort tearing it down (e.g. a rejected
+                    // in-flight fetch once disposal starts), not independent
+                    // signal. Report the actionable cancellation cause instead of
+                    // whatever generic failure teardown produced.
+                    cancellation === undefined
+                        ? Effect.failCause(cause)
+                        : elapsedSince(startedAt).pipe(Effect.flatMap((elapsedMs) => Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs)))),
+                    onSuccess: (value) => Effect.try({
+                        try: () => serializeSandboxValue(value),
+                        catch: (cause) => isSandboxFailure(cause)
+                            ? cause
+                            : new ResultNotJson({
+                                kind: sandboxValueKind(value),
+                                rawCause: cause,
+                            }),
+                    }),
+                });
+            }
+            if (first.kind === "deadline")
+                cancel("deadline_exceeded");
+            const elapsedMs = yield* elapsedSince(startedAt);
+            return yield* interruptBacking(child).pipe(Effect.andThen(Effect.fail(executionFailure(cancellation, request.policy.timeoutMs, elapsedMs))));
+        }).pipe(Effect.onInterrupt(() => {
+            cancel("cancelled");
+            const cleanup = child === undefined
+                ? Effect.void
+                : Fiber.interrupt(child).pipe(Effect.timeoutOption(request.policy.abortGraceMs), Effect.asVoid);
+            return cleanup.pipe(Effect.andThen(Effect.suspend(() => reported
+                ? Effect.void
+                : reportFailure(new Cancelled({ by: "operator" })).pipe(Effect.asVoid))));
+        }));
+        return run.pipe(Effect.catch((cause) => reportFailure(cause).pipe(Effect.flatMap(Effect.fail))), Effect.ensuring(Effect.sync(detachCaller)));
+    })));
+}

package/dist/internal/mcp-principal.d.ts

@@ -0,0 +1,14 @@
+import type { HostActor } from "@fungi.computer/puffball/app-method-runtime";
+/** Authenticated credential identity, scoped by its host. Never a bearer token. */
+export type McpPrincipal = Readonly<{
+    actor: Extract<HostActor, {
+        kind: "member";
+    }>;
+    role: "owner" | "member";
+}> | Readonly<{
+    actor: Exclude<HostActor, {
+        kind: "member";
+    }>;
+}>;
+/** Compare complete admitted identities, including a canonical member's role. */
+export declare function sameMcpPrincipal(left: McpPrincipal, right: McpPrincipal): boolean;

package/dist/internal/mcp-principal.js

@@ -0,0 +1,17 @@
+/** Compare complete admitted identities, including a canonical member's role. */
+export function sameMcpPrincipal(left, right) {
+    const actor = left.actor;
+    const other = right.actor;
+    switch (actor.kind) {
+        case "member":
+            return (other.kind === "member" &&
+                actor.memberId === other.memberId &&
+                "role" in left &&
+                "role" in right &&
+                left.role === right.role);
+        case "agent":
+            return other.kind === "agent" && actor.agentId === other.agentId;
+        case "team-key":
+            return other.kind === "team-key" && actor.keyId === other.keyId;
+    }
+}

package/dist/mcp-catalog.d.ts

@@ -0,0 +1,23 @@
+import { type CapabilitySource, type Grants, type Sandbox } from "./index.js";
+import type { McpCatalogProvider, McpPrincipal } from "./mcp.js";
+/** Current installed capabilities and explicit grants for one admitted principal. */
+export type McpCatalogSnapshot = Readonly<{
+    instructions: string;
+    sources: readonly CapabilitySource[];
+    /** Every permitted module is named; an omitted module is refused. */
+    grants: Grants;
+    /**
+     * Granted modules whose writes a person already approved for this principal,
+     * such as an owner's stored approval of a key's App tools. Their writes run
+     * without a per-call elicitation; every other write still asks.
+     */
+    approvedWrites?: readonly string[];
+}>;
+/**
+ * Adapt principal-scoped capability sources and a sandbox to the shared MCP server.
+ * Connections are process-local. Durable hosts supply their own catalog provider.
+ */
+export declare function createMcpCatalog(options: Readonly<{
+    load: (principal: McpPrincipal) => Promise<McpCatalogSnapshot>;
+    sandbox: Sandbox;
+}>): McpCatalogProvider;

package/dist/mcp-catalog.js

@@ -0,0 +1,110 @@
+import { sameMcpPrincipal } from "./internal/mcp-principal.js";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { Mycelium, } from "./index.js";
+/**
+ * Adapt principal-scoped capability sources and a sandbox to the shared MCP server.
+ * Connections are process-local. Durable hosts supply their own catalog provider.
+ */
+export function createMcpCatalog(options) {
+    const sessions = new Map();
+    return {
+        open(principal, input) {
+            let principalSessions = 0;
+            for (const session of sessions.values()) {
+                if (sameMcpPrincipal(session.principal, principal))
+                    principalSessions++;
+            }
+            if (principalSessions >= input.maxOpenSessions)
+                return Promise.resolve(null);
+            let snapshot;
+            let requestedRefresh = 0;
+            let appliedRefresh = 0;
+            const refresh = async () => {
+                const revision = ++requestedRefresh;
+                const current = await options.load(principal);
+                // A slower, older storage read cannot restore authority after revocation.
+                if (revision > appliedRefresh) {
+                    snapshot = current;
+                    appliedRefresh = revision;
+                }
+            };
+            async function withLease(access, use) {
+                if (snapshot === undefined)
+                    throw new Error("MCP catalog was not acquired");
+                const acquired = snapshot;
+                const runtime = await Mycelium.make({
+                    sources: acquired.sources,
+                    session: { sessionId: input.id },
+                    sandbox: options.sandbox,
+                    access: {
+                        ...access,
+                        defaultGrant: "none",
+                        sessionGrants: () => snapshot?.grants ?? {},
+                        approvedWrites: () => snapshot?.approvedWrites ?? [],
+                    },
+                });
+                try {
+                    const lease = await runtime.acquire();
+                    try {
+                        return await use(lease, acquired);
+                    }
+                    finally {
+                        await lease.release();
+                    }
+                }
+                finally {
+                    await runtime.close();
+                }
+            }
+            const session = {
+                id: input.id,
+                principal,
+                refresh,
+                describe: () => withLease({}, (lease, acquired) => Promise.resolve({
+                    instructions: acquired.instructions,
+                    tools: [
+                        lease.executeTool.descriptor,
+                        ...lease.tools.map(({ descriptor }) => descriptor),
+                    ],
+                })),
+                call: (call, context) => withLease(context.access, async (lease) => {
+                    const tool = [lease.executeTool, ...lease.tools].find(({ descriptor }) => descriptor.name === call.name);
+                    if (tool === undefined)
+                        throw new Error("Unknown MCP tool");
+                    let result;
+                    await Effect.runPromise(Effect.gen(function* () {
+                        const prepared = yield* tool.prepare({
+                            type: "toolCall",
+                            ...call,
+                        });
+                        yield* prepared.execute().pipe(Stream.runForEach((part) => {
+                            if (part.type === "result") {
+                                result = part.result;
+                                return Effect.void;
+                            }
+                            return Effect.promise(async () => {
+                                await context.onPart?.(part);
+                            });
+                        }));
+                    }), { signal: context.signal });
+                    if (result === undefined)
+                        throw new Error("MCP tool returned no result");
+                    return result;
+                }),
+                disconnect: () => {
+                    sessions.delete(input.id);
+                    return Promise.resolve();
+                },
+            };
+            sessions.set(input.id, session);
+            return Promise.resolve(session);
+        },
+        resume(principal, id) {
+            const session = sessions.get(id);
+            return Promise.resolve(session !== undefined && sameMcpPrincipal(session.principal, principal)
+                ? session
+                : null);
+        },
+    };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,92 @@
+import { sameMcpPrincipal, type McpPrincipal } from "./internal/mcp-principal.js";
+export { sameMcpPrincipal, type McpPrincipal };
+export { createMcpCatalog, type McpCatalogSnapshot } from "./mcp-catalog.js";
+import type { MuleTool, MuleToolExecutionPart, MuleToolResult, ToolCall } from "@fungi.computer/mule/effect";
+import { type EventStore } from "@modelcontextprotocol/server";
+import type { AccessOptions } from "./access.js";
+/** Admission is required on every HTTP request, including notifications. */
+export type McpAuthentication = Readonly<{
+    kind: "admitted";
+    principal: McpPrincipal;
+}> | Readonly<{
+    kind: "refused";
+    status: 401 | 403 | 404 | 429;
+    retryAfter?: number;
+}>;
+/** A JSON tool call submitted to the host's execution owner. */
+export type McpToolCall = Readonly<{
+    id: string;
+    name: string;
+    arguments: ToolCall["arguments"];
+}>;
+/** Request-scoped hooks carried into the same Mycelium runtime as hosted tools. */
+export type McpExecutionContext = Readonly<{
+    signal: AbortSignal;
+    /** Forward non-terminal tool output through this request's progress channel. */
+    onPart?: (part: Exclude<MuleToolExecutionPart, {
+        type: "result";
+    }>) => Promise<void>;
+    /** Apply to Mycelium access options for this call only; never persist callbacks. */
+    access: Pick<AccessOptions, "confirm"> & Readonly<{
+        confirmWrites: true;
+        /** Recheck the open connection and refresh authority before each operation. */
+        beforeCall: (signal: AbortSignal) => Promise<void>;
+    }>;
+}>;
+/** A principal-bound catalog and its existing execution owner. */
+export type McpCatalogSession = Readonly<{
+    id: string;
+    principal: McpPrincipal;
+    /** Refresh current grants before listing, execution and after approval. */
+    refresh: () => Promise<void>;
+    /** Return the existing execution owner's current instructions and tool descriptors. */
+    describe: () => Promise<{
+        instructions: string;
+        tools: readonly MuleTool["descriptor"][];
+    }>;
+    /** Execute through Mycelium, applying context.access to operations and direct tools. */
+    call: (call: McpToolCall, context: McpExecutionContext) => Promise<MuleToolResult>;
+    /** Release the open connection; retained work belongs to the host. */
+    disconnect: () => Promise<void>;
+}>;
+/** Host catalog adapter. All lookups and acquisitions are principal-bound. */
+export type McpCatalogProvider = Readonly<{
+    /** Atomically reserve a connection, or return null at the supplied bound. */
+    open: (principal: McpPrincipal, input: Readonly<{
+        id: string;
+        title: string;
+        /** Maximum concurrent sessions for this admitted principal. */
+        maxOpenSessions: number;
+    }>) => Promise<McpCatalogSession | null>;
+    /** Return an open connection only; the MCP server also checks its principal. */
+    resume: (principal: McpPrincipal, id: string) => Promise<McpCatalogSession | null>;
+}>;
+/** HTTP MCP lifecycle. Closing transport streams preserves host-owned Sessions. */
+export type Mcp = Readonly<{
+    /** Authenticate and serve one MCP HTTP request. */
+    handleRequest: (request: Request) => Promise<Response>;
+    /** End transport streams and refuse new requests; retained Sessions belong to the catalog. */
+    close: () => Promise<void>;
+}>;
+/** Durable connection identity, without credentials or live execution callbacks. */
+export type McpSessionMetadata = Readonly<{
+    /** The host-owned catalog Session identity. */
+    id: string;
+    /** The complete admitted principal, including a member's role. */
+    principal: McpPrincipal;
+}>;
+/** SDK-supported persistence; live protocol callbacks are never reconstructed. */
+export type McpPersistence = Readonly<{
+    /** Supply the SDK's event storage for one host-owned catalog Session. */
+    eventStore: (sessionId: string) => EventStore;
+    /** Persist canonical metadata after the SDK allocates its protocol session ID. */
+    initialized: (id: string, session: McpSessionMetadata) => Promise<void>;
+    /** Expire SDK metadata and events when the SDK closes that session. */
+    closed: (id: string, session: McpSessionMetadata) => Promise<void>;
+}>;
+/** Serve the host's principal-bound Mycelium catalog through one MCP implementation. */
+export declare function createMcp(options: Readonly<{
+    catalog: McpCatalogProvider;
+    authenticate: (request: Request) => Promise<McpAuthentication>;
+    persistence?: McpPersistence;
+}>): Mcp;