@fungi.computer/mycelium 0.2.3 → 0.3.1

package/README.md

@@ -10,9 +10,10 @@ when the run ends. You can also execute a known operation without a model.
 npm install @fungi.computer/mycelium
 ```
 
-The package ships ESM only and depends on Zod, Effect, `acorn`,
-[Cairn](../cairn/README.md), [Forage](../forage/README.md), and
-[Mule](../mule/README.md) at runtime, all installed automatically. The root
+The package ships ESM only. Runtime dependencies include Zod, Effect, `acorn`,
+Cloudflare Code Mode, the MCP server SDK, [Cairn](../cairn/README.md),
+[Forage](../forage/README.md), [Mule](../mule/README.md) and
+[Puffball](../puffball/README.md), all installed automatically. The root
 entrypoint is the Promise host facade. `@fungi.computer/mycelium/effect`
 supplies the scoped Effect API. Both produce an Effect-native Mule tool. The
 `./sandbox-guest`, `./sandbox-wire`, `./sandbox-failure`, `./sandbox-boundary`,
@@ -223,17 +224,21 @@ 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.
+integer) and `admissionWaitMs` (an integer from 1 to 900,000 milliseconds). By
+default, admission waits for the invocation's `timeoutMs` budget (180,000
+milliseconds when omitted), rather than failing after five seconds. An explicit
+host wait remains bounded by the original invocation deadline. 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.
+resolves these host facts, using 180,000 milliseconds when no wait is supplied.
+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

package/dist/effect.d.ts

@@ -10,6 +10,7 @@ import type { CapabilitySession, CapabilitySource, ModuleRegistration, Sandbox a
 import type { AccessOptions, LabelledTool } from "./access.js";
 export type { CapabilitySession, CapabilitySource, ModuleRegistration, SandboxBinding, SandboxRequest, };
 export type { ExecutionOptions } from "./execute-tool.js";
+export { forageDiscoveryInstructions } from "./execute-tool.js";
 export type { Access, AccessContext, AccessLabel, AccessOptions, AccessRefusal, AccessRefusalReason, ConfirmRequest, Grant, Grants, LabelledTool, ToolPolicy, } from "./access.js";
 /**
  * Effect-native host seam for sandbox execution.

package/dist/effect.js

@@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
 import * as Scope from "effect/Scope";
 import {} from "./sandbox-failure.js";
 import { openCoreRuntime } from "./runtime.js";
+export { forageDiscoveryInstructions } from "./execute-tool.js";
 /**
  * Adapt a Promise-shaped sandbox to the Effect seam. This is Mycelium's one
  * Promise sandbox conversion: interruption waits for the host Promise to

package/dist/execute-tool.d.ts

@@ -7,6 +7,8 @@ import { type BackingWorkGroup, type SerializedSandboxValue } from "./internal/e
 import { type MyceliumError } from "./errors.js";
 import type { EffectSandbox } from "./runtime.js";
 import type { SandboxAdmissionOptions } from "./sandbox-admission.js";
+/** Shared discovery scope for hosts offering Mycelium's execute tool. */
+export declare const forageDiscoveryInstructions = "Inside execute, call forage.search, forage.list or forage.describe to discover operations and inspect their inputs. forage is available only there, not as a separate tool.";
 /** Host execution limits plus the reserved, host-only admission contract. */
 export type ExecutionOptions = Readonly<{
     /** Total execution deadline in milliseconds. */

package/dist/execute-tool.js

@@ -14,7 +14,10 @@ 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. 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.';
+/** Shared discovery scope for hosts offering Mycelium's execute tool. */
+export const forageDiscoveryInstructions = "Inside execute, call forage.search, forage.list or forage.describe to discover operations and inspect their inputs. forage is available only there, not as a separate tool.";
+const executeDescription = `${forageDiscoveryInstructions} ` +
+    '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 = {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { sandboxFailure, isSandboxFailure, sandboxOperatorValue, } from "./sandb
 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";
+import type { Sandbox } from "./sandbox.js";
 export type { MyceliumJsonValue, SandboxValue, SandboxBinding, SandboxRequest, Sandbox, } from "./sandbox.js";
 import type * as Schema from "effect/Schema";
 import type { OperationSchema } from "./operation-schema.js";
@@ -143,13 +143,13 @@ export type MyceliumApi = Readonly<{
     /**
      * Declare one schema-described operation behind the execute door. An Effect
      * output schema encodes the result to JSON; otherwise the result must
-     * already be a JSON value.
+     * already be a JSON value, which may be readonly.
      */
     operation: {
         <I, O>(definition: OperationDefinition<I, O> & {
             readonly output: Schema.Codec<O, unknown>;
         }): OperationRegistration<I, O>;
-        <I, O extends MyceliumJsonValue>(definition: OperationDefinition<I, O>): OperationRegistration<I, O>;
+        <I, O extends Schema.Json>(definition: OperationDefinition<I, O>): OperationRegistration<I, O>;
     };
     /** Open the Promise-shaped facade over Mycelium's Effect runtime. */
     make: (options: MyceliumOptions) => Promise<Runtime>;

package/dist/internal/execution-lifecycle.js

@@ -32,12 +32,13 @@ export function normalizeExecutionPolicy(value) {
     if (!parsed.success) {
         throw new MyceliumDefinitionError("Execution policy is invalid");
     }
+    const timeoutMs = parsed.data?.timeoutMs ?? 180_000;
     return Object.freeze({
-        timeoutMs: parsed.data?.timeoutMs ?? 180_000,
+        timeoutMs,
         abortGraceMs: parsed.data?.abortGraceMs ?? 5_000,
         ...normalizeSandboxAdmissionPolicy({
             sandboxCapacity: parsed.data?.sandboxCapacity,
-            admissionWaitMs: parsed.data?.admissionWaitMs,
+            admissionWaitMs: parsed.data?.admissionWaitMs ?? timeoutMs,
         }, parsed.data?.sandboxCapacity === undefined
             ? availableHostCores()
             : undefined),

package/dist/output-collector.js

@@ -2,6 +2,8 @@ import * as Effect from "effect/Effect";
 import * as Queue from "effect/Queue";
 import * as Stream from "effect/Stream";
 const capacity = 8192;
+// Bound temporary decoded text and raw context even for a single huge write.
+const decodeCapacity = capacity * 4;
 const encoder = new TextEncoder();
 // fatal: false is the existing default; Cloudflare's type requires the field.
 const decoder = () => new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
@@ -9,11 +11,11 @@ const decoder = () => new TextDecoder("utf-8", { ignoreBOM: true, fatal: false }
 export class OutputCollector {
     wake;
     #producers = {
-        stdout: { decoder: decoder(), pendingBytes: 0 },
-        stderr: { decoder: decoder(), pendingBytes: 0 },
+        stdout: { decoder: decoder(), pending: new Uint8Array(0) },
+        stderr: { decoder: decoder(), pending: new Uint8Array(0) },
     };
     #probe = decoder();
-    // One bounded ring of complete decoder emissions. No UTF-8 slicing/parser.
+    // One bounded ring of decoded chunks. TextDecoder owns every UTF-8 boundary.
     #parts = Array.from({ length: capacity }, () => undefined);
     #head = 0;
     #size = 0;
@@ -35,28 +37,34 @@ export class OutputCollector {
             return;
         const producer = this.#producers[stream];
         this.#totalBytes += bytes.length;
-        // Byte-sized decoder inputs let each retained emission carry its exact raw
-        // cost, even when malformed input expands to replacement characters.
-        for (let i = 0; i < bytes.length; i++) {
-            const byte = bytes.subarray(i, i + 1);
-            producer.pendingBytes++;
-            const text = producer.decoder.decode(byte, { stream: true });
-            if (text.length === 0)
-                continue;
-            // A decoder may emit a replacement for a prior incomplete sequence while
-            // buffering the current byte as the start of the next scalar. Ask the
-            // maintained decoder, rather than duplicating UTF-8 byte grammar.
-            const pending = producer.pendingBytes > 1 &&
-                this.#probe.decode(byte, { stream: true }).length === 0
-                ? 1
-                : 0;
-            this.#probe.decode();
-            this.#append(text, producer.pendingBytes - pending);
-            producer.pendingBytes = pending;
+        for (let offset = 0; offset < bytes.length; offset += decodeCapacity) {
+            const chunk = bytes.subarray(offset, offset + decodeCapacity);
+            const text = producer.decoder.decode(chunk, { stream: true });
+            const raw = new Uint8Array(producer.pending.length + chunk.length);
+            raw.set(producer.pending);
+            raw.set(chunk, producer.pending.length);
+            const pending = this.#pendingLength(raw);
+            producer.pending = raw.slice(raw.length - pending);
+            this.#append(text, raw.length - pending, raw);
         }
         this.#dirty = true;
         Queue.offerUnsafe(this.wake, undefined);
     }
+    #decodePrefix(raw, length) {
+        const text = this.#probe.decode(raw.subarray(0, length), { stream: true });
+        this.#probe.decode();
+        return text;
+    }
+    #pendingLength(raw) {
+        // UTF-8 has at most three incomplete bytes. Ask the maintained decoder
+        // which suffix is still incomplete; do not inspect UTF-8 byte patterns.
+        for (let length = 1; length <= Math.min(3, raw.length); length++) {
+            const suffix = raw.subarray(raw.length - length);
+            if (this.#decodePrefix(suffix, suffix.length).length === 0)
+                return length;
+        }
+        return 0;
+    }
     #evict() {
         const part = this.#parts[this.#head];
         if (part === undefined)
@@ -68,11 +76,56 @@ export class OutputCollector {
         this.#newlines -= part.newlines;
         this.#droppedBytes += part.rawBytes;
     }
-    #append(text, rawBytes) {
+    #trimHead(part, textBytes, newlines) {
+        const raw = part.raw;
+        if (raw === null) {
+            this.#evict();
+            return;
+        }
+        // Find the first decoder emission that pays both clipping debts. A native
+        // decode can emit replacement + ASCII together, or emit a replacement
+        // while buffering the next scalar. Keep those same emission boundaries.
+        const enough = (length) => {
+            const prefix = this.#decodePrefix(raw, length);
+            return (encoder.encode(prefix).length >= textBytes &&
+                prefix.split("\n").length - 1 >= newlines);
+        };
+        let high = Math.min(raw.length, Math.max(4, textBytes));
+        while (high < raw.length && !enough(high))
+            high = Math.min(raw.length, high * 2);
+        let low = 0;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (enough(middle))
+                high = middle;
+            else
+                low = middle + 1;
+        }
+        const prefix = this.#decodePrefix(raw, low);
+        if (prefix.length === part.text.length) {
+            this.#evict();
+            return;
+        }
+        const cut = low - this.#pendingLength(raw.subarray(0, low));
+        const removedBytes = encoder.encode(prefix).length;
+        const removedLines = prefix.split("\n").length - 1;
+        part.raw = raw.slice(cut);
+        // Decode the bounded remainder anew so a sliced string cannot retain the
+        // larger temporary chunk. raw.slice also releases its original buffer.
+        part.text = this.#decodePrefix(part.raw, part.raw.length);
+        part.rawBytes -= cut;
+        part.textBytes -= removedBytes;
+        part.newlines -= removedLines;
+        this.#textBytes -= removedBytes;
+        this.#newlines -= removedLines;
+        this.#droppedBytes += cut;
+    }
+    #append(text, rawBytes, raw) {
         if (text.length === 0)
             return;
         const part = {
             text,
+            raw,
             rawBytes,
             textBytes: encoder.encode(text).length,
             newlines: text.split("\n").length - 1,
@@ -83,8 +136,17 @@ export class OutputCollector {
         this.#size++;
         this.#textBytes += part.textBytes;
         this.#newlines += part.newlines;
-        while (this.#textBytes > capacity || this.#newlines >= 200)
-            this.#evict();
+        while (this.#textBytes > capacity || this.#newlines >= 200) {
+            const head = this.#parts[this.#head];
+            if (head === undefined)
+                throw new Error("Missing output ring entry");
+            const bytesToDrop = Math.max(0, this.#textBytes - capacity);
+            const linesToDrop = Math.max(0, this.#newlines - 199);
+            if (head.textBytes <= bytesToDrop || head.newlines < linesToDrop)
+                this.#evict();
+            else
+                this.#trimHead(head, bytesToDrop, linesToDrop);
+        }
     }
     snapshot() {
         let tail = "";
@@ -121,8 +183,8 @@ export class OutputCollector {
         this.#closed = true;
         for (const producer of [this.#producers.stdout, this.#producers.stderr]) {
             const text = producer.decoder.decode();
-            this.#append(text, producer.pendingBytes);
-            producer.pendingBytes = 0;
+            this.#append(text, producer.pending.length, null);
+            producer.pending = new Uint8Array(0);
             if (text.length > 0)
                 this.#dirty = true;
         }
@@ -139,7 +201,7 @@ export class OutputCollector {
         this.#dirty = false;
         for (const producer of [this.#producers.stdout, this.#producers.stderr]) {
             producer.decoder.decode();
-            producer.pendingBytes = 0;
+            producer.pending = new Uint8Array(0);
         }
     }
 }

package/dist/runtime.js

@@ -50,12 +50,16 @@ export function openCoreRuntime(options) {
             onFailure: options.onSandboxFailure,
             execution,
         });
-        const staticSurface = yield* Effect.try({
-            try: () => compileSurface(options.modules),
-            catch: (cause) => cause instanceof MyceliumDefinitionError
-                ? cause
-                : new MyceliumDefinitionError("Capability compilation failed"),
-        });
+        // A source-only runtime has no static definitions to validate. Its empty
+        // surface would be discarded; acquisition compiles the captured modules.
+        const staticSurface = options.modules.length === 0 && options.sources.length > 0
+            ? undefined
+            : 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,
@@ -67,7 +71,7 @@ export function openCoreRuntime(options) {
         let installed;
         const liveRevisions = new Set();
         let closed = false;
-        if (options.sources.length === 0) {
+        if (options.sources.length === 0 && staticSurface !== undefined) {
             const candidate = yield* acquireSourceCandidate({
                 ...options,
                 sandbox,

package/dist/sandbox-admission.js

@@ -16,6 +16,6 @@ export function normalizeSandboxAdmissionPolicy(options, availableCores) {
     }
     return Object.freeze({
         capacity: parsed.data.sandboxCapacity ?? Math.min(32, Math.max(2, cores.data)),
-        waitMs: parsed.data.admissionWaitMs ?? 5_000,
+        waitMs: parsed.data.admissionWaitMs ?? 180_000,
     });
 }

package/docs/api/effect.md

@@ -77,6 +77,17 @@ type Runtime = Readonly<{
 
 Warm Effect lifecycle for acquiring scope-owned run leases.
 
+## Variables
+
+### forageDiscoveryInstructions
+
+```ts
+const forageDiscoveryInstructions: "Inside execute, call forage.search, forage.list or forage.describe to discover operations and inspect their inputs. forage is available only there, not as a separate tool." =
+  "Inside execute, call forage.search, forage.list or forage.describe to discover operations and inspect their inputs. forage is available only there, not as a separate tool.";
+```
+
+Shared discovery scope for hosts offering Mycelium's execute tool.
+
 ## Functions
 
 ### fromTypedSandbox()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mycelium",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native scoped capability lifecycle with a Zod-authored execute door",
   "type": "module",
@@ -79,9 +79,9 @@
   ],
   "dependencies": {
     "@fungi.computer/cairn": "0.1.0",
-    "@fungi.computer/forage": "0.2.0",
+    "@fungi.computer/forage": "0.2.2",
     "@fungi.computer/mule": "0.2.1",
-    "@fungi.computer/puffball": "0.2.0",
+    "@fungi.computer/puffball": "0.4.0",
     "effect": "4.0.2",
     "zod": "4.4.3",
     "acorn": "8.18.0",