@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/remote.d.ts

@@ -0,0 +1,33 @@
+import type { InvocationContext, MyceliumJsonValue, SandboxValue } from "./index.js";
+import { type ModuleRegistration } from "./registration.js";
+/** One operation's model-facing contract with its schemas as JSON Schema. */
+export type RemoteOperationDescriptor = Readonly<{
+    replay: "safe" | "unsafe";
+    description?: string | undefined;
+    input: MyceliumJsonValue;
+    /** Absent when the operation declares no output schema. */
+    output: MyceliumJsonValue | null;
+}>;
+/**
+ * A module's operations keyed by their dotted path below the module, for a
+ * host that runs the module in another isolate. Identity, alias and placement
+ * stay the host's decision; this carries only what the model may call.
+ */
+export type RemoteModuleDescriptor = Readonly<{
+    description?: string | undefined;
+    operations: Readonly<Record<string, RemoteOperationDescriptor>>;
+}>;
+/** Project one module's callable surface; unrepresentable schemas throw. */
+export declare function describeModule(registration: ModuleRegistration): RemoteModuleDescriptor;
+/** Run one described operation through its own input and output schemas. */
+export declare function invokeModuleOperation(registration: ModuleRegistration, path: string, input: SandboxValue, context: InvocationContext): Promise<MyceliumJsonValue>;
+/**
+ * Rebuild a described module on the host side. Each operation parses its input
+ * and output against the described JSON Schema, then forwards to `invoke`.
+ */
+export declare function remoteModule(options: Readonly<{
+    id: string;
+    name: string;
+    descriptor: RemoteModuleDescriptor;
+    invoke: (path: string, input: MyceliumJsonValue, context: InvocationContext) => Promise<MyceliumJsonValue>;
+}>): ModuleRegistration;

package/dist/remote.js

@@ -0,0 +1,126 @@
+import { jsonSchemaToZod } from "@fungi.computer/forage";
+import { z } from "zod";
+import { MyceliumDefinitionError } from "./errors.js";
+import { defineModule, defineOperation, isModuleRegistration, readModule, readOperation, } from "./registration.js";
+function operationsOf(registration) {
+    const stored = readModule(registration);
+    if (stored === undefined)
+        throw new MyceliumDefinitionError("Unknown module registration");
+    const operations = new Map();
+    const visit = (handles, prefix) => {
+        for (const [name, handle] of Object.entries(handles)) {
+            if (isModuleRegistration(handle)) {
+                const child = readModule(handle);
+                if (child === undefined)
+                    throw new MyceliumDefinitionError("Unknown child module registration");
+                visit(child.operations, [...prefix, name, ...child.namespace]);
+                continue;
+            }
+            const operation = readOperation(handle);
+            if (operation === undefined)
+                throw new MyceliumDefinitionError(`Unknown operation registration: ${name}`);
+            operations.set([...prefix, name].join("."), operation);
+        }
+    };
+    visit(stored.operations, []);
+    return operations;
+}
+/** Project one module's callable surface; unrepresentable schemas throw. */
+export function describeModule(registration) {
+    const stored = readModule(registration);
+    if (stored === undefined)
+        throw new MyceliumDefinitionError("Unknown module registration");
+    const operations = {};
+    for (const [path, operation] of operationsOf(registration)) {
+        const input = z.json().parse(operation.input["~standard"].jsonSchema.input({
+            target: "draft-2020-12",
+        }));
+        const output = operation.output === undefined
+            ? null
+            : z.json().parse(operation.output["~standard"].jsonSchema.output({
+                target: "draft-2020-12",
+            }));
+        operations[path] =
+            operation.description === undefined
+                ? { replay: operation.replay, input, output }
+                : {
+                    replay: operation.replay,
+                    description: operation.description,
+                    input,
+                    output,
+                };
+    }
+    return stored.description === undefined
+        ? { operations }
+        : { description: stored.description, operations };
+}
+/** Run one described operation through its own input and output schemas. */
+export function invokeModuleOperation(registration, path, input, context) {
+    const operation = operationsOf(registration).get(path);
+    if (operation === undefined)
+        return Promise.reject(new MyceliumDefinitionError(`Unknown remote operation: ${path}`));
+    return operation
+        .invoke(input, context)
+        .then((value) => z.json().parse(value));
+}
+/**
+ * Rebuild a described module on the host side. Each operation parses its input
+ * and output against the described JSON Schema, then forwards to `invoke`.
+ */
+export function remoteModule(options) {
+    const root = new Map();
+    for (const [path, operation] of Object.entries(options.descriptor.operations)) {
+        const segments = path.split(".");
+        const leaf = segments.pop();
+        if (leaf === undefined)
+            throw new MyceliumDefinitionError("Empty remote operation path");
+        let node = root;
+        for (const segment of segments) {
+            const next = node.get(segment) ??
+                new Map();
+            if (!(next instanceof Map))
+                throw new MyceliumDefinitionError(`Remote operation path collides with an operation: ${path}`);
+            node.set(segment, next);
+            node = next;
+        }
+        if (node.has(leaf))
+            throw new MyceliumDefinitionError(`Duplicate remote operation path: ${path}`);
+        node.set(leaf, operation);
+    }
+    const build = (tree, prefix) => Object.fromEntries([...tree].map(([name, entry]) => {
+        const path = [...prefix, name];
+        if (entry instanceof Map)
+            return [
+                name,
+                defineModule({
+                    id: `${options.id}.${path.join(".")}`,
+                    name,
+                    operations: build(entry, path),
+                }),
+            ];
+        const output = entry.output === null
+            ? undefined
+            : z.intersection(jsonSchemaToZod(entry.output), z.json());
+        const forward = (value, context) => options.invoke(path.join("."), value, context);
+        const base = {
+            replay: entry.replay,
+            input: z.intersection(jsonSchemaToZod(entry.input), z.json()),
+            execute: forward,
+        };
+        const described = entry.description === undefined
+            ? base
+            : { ...base, description: entry.description };
+        return [
+            name,
+            defineOperation(output === undefined ? described : { ...described, output }),
+        ];
+    }));
+    return defineModule(options.descriptor.description === undefined
+        ? { id: options.id, name: options.name, operations: build(root, []) }
+        : {
+            id: options.id,
+            name: options.name,
+            description: options.descriptor.description,
+            operations: build(root, []),
+        });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,51 @@
+import type { SandboxFailureEvent } from "./sandbox-failure-event.js";
+import type { SandboxFailure } from "./sandbox-failure.js";
+import type { MuleTool } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import type { CapabilitySession, CapabilitySource } from "./capability-source.js";
+import { type CompiledSurface } from "./compiler.js";
+import { type MyceliumError } from "./errors.js";
+import type { ExecutionOptions } from "./execute-tool.js";
+import type { ExecuteDoor } from "./execute-tool.js";
+import type { ExecutionPolicy } from "./internal/execution-lifecycle.js";
+import type { SandboxRequest, SandboxValue } from "./index.js";
+import type { ModuleRegistration } from "./registration.js";
+import { type AccessOptions, type LabelledTool } from "./access.js";
+/** Effect-native host seam for sandbox execution. */
+export type EffectSandbox = Readonly<{
+    readonly adapter?: string | undefined;
+    readonly buildSha?: string | undefined;
+    readonly onFailure?: ((event: SandboxFailureEvent) => Effect.Effect<void>) | undefined;
+    readonly execute: (request: SandboxRequest, signal: AbortSignal) => Effect.Effect<SandboxValue, SandboxFailure>;
+    /** Effective policy injected by the canonical runtime before compilation. */
+    readonly execution?: ExecutionPolicy;
+}>;
+/** Inputs consumed by the canonical runtime core. */
+export type CoreOptions = Readonly<{
+    readonly modules: readonly ModuleRegistration[];
+    readonly sources: readonly CapabilitySource[];
+    readonly session?: CapabilitySession | undefined;
+    readonly execution?: ExecutionOptions | undefined;
+    readonly sandbox: EffectSandbox;
+    readonly onSandboxFailure?: ((event: SandboxFailureEvent) => Effect.Effect<void>) | undefined;
+    readonly tools: readonly LabelledTool[];
+    readonly access: AccessOptions;
+}>;
+/** Internal lease carrying the stable surface and its Effect execute door. */
+export type CoreLease = Readonly<{
+    readonly revision: string;
+    readonly catalog: CompiledSurface["catalog"];
+    readonly executeDoor: ExecuteDoor;
+    readonly effectExecuteTool: MuleTool;
+    /** Labelled direct tools, each behind the runtime's access check. */
+    readonly tools: readonly MuleTool[];
+    readonly release: () => Effect.Effect<void, MyceliumError>;
+}>;
+/** Canonical scoped runtime used by both public lifecycle projections. */
+export type CoreRuntime = Readonly<{
+    readonly acquire: () => Effect.Effect<CoreLease, MyceliumError, Scope.Scope>;
+    readonly close: () => Effect.Effect<void, MyceliumError>;
+}>;
+/** Construct the single Effect-owned lifecycle implementation. */
+export declare function openCoreRuntime(options: CoreOptions): Effect.Effect<CoreRuntime, MyceliumError, Scope.Scope>;

package/dist/runtime.js

@@ -0,0 +1,159 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Semaphore from "effect/Semaphore";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import { compileSurface } from "./compiler.js";
+import { MyceliumClosedError, MyceliumDefinitionError, } from "./errors.js";
+import { createBackingWorkTracker, normalizeExecutionPolicy, } from "./internal/execution-lifecycle.js";
+import { guardTool } from "./access.js";
+import { acquireSourceCandidate, } from "./source-runtime.js";
+import { claimThenSettle } from "./semaphore-transition.js";
+function finishCleanup(installed, liveRevisions) {
+    // A failed revision stays live, so a repeated close reports its retained
+    // cleanup failure instead of a fresh success.
+    return Effect.uninterruptible(installed.candidate.close().pipe(Effect.matchEffect({
+        onFailure: (failure) => Deferred.fail(installed.settled, failure).pipe(Effect.andThen(Effect.fail(failure))),
+        onSuccess: () => Deferred.succeed(installed.settled, undefined).pipe(Effect.andThen(Effect.sync(() => {
+            liveRevisions.delete(installed);
+        }))),
+    })));
+}
+function settleClosePlan(plan, liveRevisions) {
+    return plan.runCleanup
+        ? finishCleanup(plan.installed, liveRevisions)
+        : Deferred.await(plan.installed.settled);
+}
+function settleClosePlans(plans, liveRevisions) {
+    return Effect.all(plans.map((plan) => settleClosePlan(plan, liveRevisions).pipe(Effect.exit)), { concurrency: "unbounded" }).pipe(Effect.flatMap((exits) => {
+        const failure = exits.find(Exit.isFailure);
+        return failure === undefined
+            ? Effect.void
+            : Effect.failCause(failure.cause);
+    }));
+}
+/** Construct the single Effect-owned lifecycle implementation. */
+export function openCoreRuntime(options) {
+    return Effect.gen(function* () {
+        const gate = yield* Semaphore.make(1);
+        const backingWork = createBackingWorkTracker();
+        const execution = yield* Effect.try({
+            try: () => normalizeExecutionPolicy(options.execution),
+            catch: (cause) => cause instanceof MyceliumDefinitionError
+                ? cause
+                : new MyceliumDefinitionError("Execution policy is invalid"),
+        });
+        const sandbox = Object.freeze({
+            execute: options.sandbox.execute,
+            adapter: options.sandbox.adapter,
+            buildSha: options.sandbox.buildSha,
+            onFailure: options.onSandboxFailure,
+            execution,
+        });
+        const staticSurface = yield* Effect.try({
+            try: () => compileSurface(options.modules),
+            catch: (cause) => cause instanceof MyceliumDefinitionError
+                ? cause
+                : new MyceliumDefinitionError("Capability compilation failed"),
+        });
+        const tools = yield* Effect.try({
+            try: () => Object.freeze(options.tools.map((tool) => guardTool(tool, options.access, {
+                sessionId: options.session?.sessionId ?? null,
+            }))),
+            catch: (cause) => cause instanceof MyceliumDefinitionError
+                ? cause
+                : new MyceliumDefinitionError("Direct tool labels are invalid"),
+        });
+        let installed;
+        const liveRevisions = new Set();
+        let closed = false;
+        if (options.sources.length === 0) {
+            const candidate = yield* acquireSourceCandidate({
+                ...options,
+                sandbox,
+                backingWork,
+                precompiled: staticSurface,
+            });
+            const initial = {
+                candidate,
+                settled: yield* Deferred.make(),
+                leases: 0,
+                retired: false,
+                closing: false,
+            };
+            installed = initial;
+            liveRevisions.add(initial);
+        }
+        const close = () => claimThenSettle(gate, () => {
+            closed = true;
+            return [...liveRevisions].map((revision) => {
+                revision.retired = true;
+                const runCleanup = revision.leases === 0 && !revision.closing;
+                if (runCleanup)
+                    revision.closing = true;
+                return { installed: revision, runCleanup };
+            });
+        }, (plans) => settleClosePlans(plans, liveRevisions));
+        yield* Effect.addFinalizer(() => close().pipe(Effect.orDie));
+        const acquire = () => gate.withPermits(1)(Effect.gen(function* () {
+            if (closed) {
+                return yield* Effect.fail(new MyceliumClosedError());
+            }
+            if (installed === undefined || installed.candidate.isStale()) {
+                const candidate = yield* acquireSourceCandidate({
+                    ...options,
+                    sandbox,
+                    backingWork,
+                });
+                const previous = installed;
+                const replacement = {
+                    candidate,
+                    settled: yield* Deferred.make(),
+                    leases: 0,
+                    retired: false,
+                    closing: false,
+                };
+                installed = replacement;
+                liveRevisions.add(replacement);
+                if (previous !== undefined) {
+                    previous.retired = true;
+                    if (previous.leases === 0 && !previous.closing) {
+                        previous.closing = true;
+                        yield* finishCleanup(previous, liveRevisions);
+                    }
+                }
+            }
+            const owned = installed;
+            owned.leases += 1;
+            // Undefined while held; afterwards, whether this release began cleanup.
+            let releaseCleanup;
+            const release = () => claimThenSettle(gate, () => {
+                // A retry awaits the cleanup this lease began, if any.
+                if (releaseCleanup !== undefined) {
+                    return releaseCleanup
+                        ? { installed: owned, runCleanup: false }
+                        : undefined;
+                }
+                owned.leases -= 1;
+                releaseCleanup =
+                    owned.retired && owned.leases === 0 && !owned.closing;
+                if (!releaseCleanup)
+                    return undefined;
+                owned.closing = true;
+                return { installed: owned, runCleanup: true };
+            }, (plan) => plan === undefined
+                ? Effect.void
+                : settleClosePlan(plan, liveRevisions));
+            yield* Effect.addFinalizer(() => release().pipe(Effect.orDie));
+            return Object.freeze({
+                revision: owned.candidate.compiled.revision,
+                catalog: owned.candidate.compiled.catalog,
+                executeDoor: owned.candidate.executeDoor,
+                effectExecuteTool: owned.candidate.executeDoor.effectTool,
+                tools,
+                release,
+            });
+        }));
+        return Object.freeze({ acquire, close });
+    });
+}

package/dist/sandbox-boundary.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { MyceliumJsonValue, SandboxRequest, SandboxValue } from "./sandbox.js";
+import { GuestThrew, type SandboxFailure, type CapabilityDiagnostic } from "./sandbox-failure.js";
+/** Admit only errors constructed by the sandbox owner, using the maintained decoder. */
+export declare function isSandboxFailure(cause: unknown): cause is SandboxFailure;
+/** Foreign throws stay private until an owner admits a diagnostic. */
+export declare function sandboxFailure(cause: unknown): SandboxFailure;
+/** Label a rejected JSON value without caller-owned reflection. */
+export declare function sandboxValueKind(value: SandboxValue): string;
+/** JSON argument or the SDK's explicit absence of an argument. */
+export type SandboxBindingInput = MyceliumJsonValue | undefined;
+/** Decode the RPC argument before any capability callback observes it. */
+export declare function sandboxBindingInput(value: SandboxValue): SandboxBindingInput;
+/** Full operator representation, including nested errors, aggregates and cycles. */
+export declare function sandboxOperatorValue(cause: unknown): z.core.util.JSONType;
+/** Decode the engine's guest-owned diagnostic once; renderers receive typed fields. */
+export declare function sandboxGuestFailure(cause: unknown, bindings?: SandboxRequest["bindings"]): GuestThrew;
+/** Error.message is the SDK's wire carrier; only this safe, bounded envelope crosses it. */
+export declare function sandboxTransportMessage(failure: SandboxFailure, ref: string): string;
+/** Recovery uses the decoded identity, never a match against diagnostic text. */
+export declare function recoverSandboxFailure(failure: SandboxFailure, failures: ReadonlyMap<string, SandboxFailure>): SandboxFailure;
+/** Decode Codemode's documented error carrier before adapters choose a failure. */
+export declare function sandboxExecutorFailure(cause: unknown, limitMs: number, elapsedMs: number): SandboxFailure;
+/** Decode a transport-owned errno without reflecting on a foreign throw in adapters. */
+export declare function sandboxTransportErrno(cause: unknown): string | undefined;
+/** Admit Acorn's documented offset from a syntax exception at this boundary. */
+export declare function sandboxSourceError(cause: unknown): Readonly<{
+    pos: number;
+}> | undefined;
+/** Capability owners supply an admission schema; decoding and foreign fallback stay here. */
+export declare function sandboxCapabilityFailure(cause: unknown, namespace: string, operation: string, admitted?: z.ZodType<CapabilityDiagnostic>): SandboxFailure;
+/** Host operation callbacks after decoding JSON or an absent RPC argument. */
+export type SandboxOperationBindings = Readonly<Record<string, Readonly<Record<string, (input: SandboxBindingInput) => Promise<MyceliumJsonValue>>>>>;
+/** One boundary owns RPC decoding, safe transport and invocation-scoped recovery. */
+export declare function sandboxBindingBoundary(bindings: SandboxOperationBindings): Readonly<{
+    /** Guest-visible callbacks with validated inputs and safe error carriers. */
+    bindings: SandboxRequest["bindings"];
+    /** Retain one typed provider refusal and return its safe guest carrier. */
+    capture: (failure: SandboxFailure) => string;
+    /** Restore an invocation-owned typed error from its exact wire envelope. */
+    recover: (failure: SandboxFailure) => SandboxFailure;
+    /** Decode a provider error deliberately returned by guest code. */
+    returnedFailure: (value: SandboxValue) => SandboxFailure | undefined;
+}>;