mycelium

Import

Import

import * as api from "@fungi.computer/mycelium";

Exports

Kind	Export	Description
Cclass	MyceliumDefinitionError	A capability declaration could not form one coherent installed surface.
Cclass	MyceliumClosedError	An operation attempted to use a closed Mycelium runtime.
Cclass	MyceliumSourceError	A capability source failed at its bounded host boundary.
Cclass	InvalidOperationInput	Untrusted operation input failed the operation’s declared input schema.
Cclass	InvalidOperationOutput	An operation’s result failed its declared output schema.
Ttype alias	Access	What one operation does: read observes, write changes something.
Ttype alias	ToolPolicy	An author’s labels for one operation or direct tool.
Ttype alias	Grant	The access a host grants one module.
Ttype alias	Grants	A host’s grants, keyed by module id. An unnamed module uses defaultGrant unless it is required, in which case missing authority is refused.
Ttype alias	AccessLabel	The labels an operation or direct tool carries, as its author declared them.
Ttype alias	AccessContext	The Session a runtime serves; null for a session-free host.
Ttype alias	ConfirmRequest	One call the host is asked to approve before it runs.
Ttype alias	AccessRefusalReason	Why a call was refused before it ran.
Ttype alias	AccessRefusal	The ordinary result a refused call returns in place of running.
Ttype alias	AccessOptions	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. Native hosts own durable approval policy for admitted writes; explicit author confirmation still uses this port.
Ttype alias	LabelledTool	A Mule tool that carries its author’s access labels outside execute.
Ttype alias	CapabilitySession	Session on whose behalf one runtime acquires its capability projections.
Ttype alias	CapabilitySourceContext	Context supplied while acquiring one current capability projection.
Ttype alias	CapabilitySourceSnapshot	Bounded current projection returned by one capability source.
Ttype alias	CapabilitySourceAcquisition	Acquired source projection and the cleanup that owns its live adapter.
Ttype alias	CapabilitySource	Promise-shaped host boundary for one versioned capability projection.
Ttype alias	MyceliumSourcePhase	Lifecycle phase in which a capability source failed.
Ttype alias	MyceliumError	Closed failure vocabulary for the first Mycelium runtime slice.
Ttype alias	ExecutionOptions	Host execution limits plus the reserved, host-only admission contract.
Ttype alias	CollectedImage	A single image collected during an execute run.
Ttype alias	ExecutionImages	The collector as one execution’s operations see it: push only.
Ttype alias	InvocationContext	The only context an operation callback may observe.
Ttype alias	MyceliumOptions	Inputs used to construct the Promise-facing runtime.
Ttype alias	AcquireOptions	Cancellation options for one Promise-facing lease acquisition.
Ttype alias	Lease	One immutable Promise-facing capability revision.
Ttype alias	Runtime	Warm Promise-facing lifecycle for acquiring immutable run leases.
Ttype alias	OperationDefinition	Declaration for one operation behind the execute door. input and output may be Effect schemas (encoded as JSON) or any Standard Schema with Standard JSON Schema, such as Zod 4.
Ttype alias	ModuleDefinition	Declaration for one stable module and its related operations.
Ttype alias	MyceliumApi	Public convenience namespace contract.
Ttype alias	OperationSchemaIssue	One Standard Schema issue.
Ttype alias	OperationSchemaResult	Standard Schema validation result.
Ttype alias	StandardOperationSchema	Any Standard Schema that also implements Standard JSON Schema, such as a Zod 4 schema. Mycelium validates with validate and describes the operation to the model with jsonSchema.
Ttype alias	OperationSchema	Schema for one operation’s input or output: an Effect schema (exchanged as its canonical JSON codec, Schema.toCodecJson), or any Standard Schema with Standard JSON Schema such as Zod 4.
Ttype alias	OperationRegistration	Opaque handle for one schema-described operation.
Ttype alias	ModuleRegistration	Opaque handle for one namespaced capability module.
Ttype alias	GateDecision	A gate’s verdict for one call: run the operation, or return value instead.
Ttype alias	OperationGate	Asked before every call of a gated module’s operations.
Ttype alias	SandboxAdmissionOptions	Host-owned admission inputs; never part of guest execute arguments.
Ttype alias	SandboxAdmissionPolicy	Captured once per runtime and shared across backing-work groups.
Ttype alias	SandboxFailureEvent	Full operator diagnostics, excluded from model conversation and default reads.
constconstant	ToolAccessSchema	What one operation does, declared by its author as a fixed fact: read observes, write changes something. An unlabelled operation is write.
constconstant	ToolConfirmSchema	Whether the author asks that a person approve each call first.
constconstant	ToolPolicySchema	An author’s labels for one operation or direct tool: the one definition both the TypeScript type and the registration-time parse derive from.
constconstant	GrantSchema	The access a host grants one module: write allows every operation, read allows only read operations, none allows nothing.
constconstant	MAX_EXECUTION_IMAGES	Maximum number of out-of-band images retained for one execution.
constconstant	Mycelium	Schema-described authoring and Promise-facing runtime construction.
constconstant	SandboxFailureEventSchema	Shared structural grammar for durable operator facts and client inspection.
fnfunction	normalizeSandboxAdmissionPolicy()	Validate host policy and resolve defaults from a platform-owned core observation.

MyceliumDefinitionErrorCclass

A capability declaration could not form one coherent installed surface.

Extends

• Error

Constructors

Constructor

Signature

new MyceliumDefinitionError(message): MyceliumDefinitionError;

Parameters

Parameter	Type
message	string

Returns

MyceliumDefinitionError

Overrides

Signature

Error.constructor;

Properties

code

Signature

readonly code: "invalid_definition" = invalidDefinitionCode;

Stable machine-readable failure code.

---

MyceliumClosedErrorCclass

An operation attempted to use a closed Mycelium runtime.

Extends

• Error

Constructors

Constructor

Signature

new MyceliumClosedError(message?): MyceliumClosedError;

Parameters

Parameter	Type	Default value
message	string	"Mycelium runtime is closed"

Returns

MyceliumClosedError

Overrides

Signature

Error.constructor;

Properties

code

Signature

readonly code: "runtime_closed" = runtimeClosedCode;

Stable machine-readable failure code.

---

MyceliumSourceErrorCclass

A capability source failed at its bounded host boundary.

Extends

• Error

Constructors

Constructor

Signature

new MyceliumSourceError(sourceId, phase): MyceliumSourceError;

Parameters

Parameter	Type	Description
sourceId	string | undefined	Stable identity of the source, absent for whole-candidate failures.
phase	MyceliumSourcePhase	Lifecycle phase that could not settle.

Returns

MyceliumSourceError

Overrides

Signature

Error.constructor;

Properties

code

Signature

readonly code: "source_failure" = sourceFailureCode;

Stable machine-readable failure code.

sourceId

Signature

readonly sourceId: string | undefined;

Stable identity of the source, absent for whole-candidate failures.

phase

Signature

readonly phase: MyceliumSourcePhase;

Lifecycle phase that could not settle.

---

InvalidOperationInputCclass

Untrusted operation input failed the operation’s declared input schema.

Extends

• Error

Constructors

Constructor

Signature

new InvalidOperationInput(issues): InvalidOperationInput;

Parameters

Parameter	Type	Description
issues	readonly Readonly<{ message: string; path?: readonly ( | PropertyKey | Readonly<{ key: PropertyKey; }>)[]; }>[]	Schema issues, formatted for the model by the execute door.

Returns

InvalidOperationInput

Overrides

Signature

Error.constructor;

Properties

issues

Signature

readonly issues: readonly Readonly<{
  message: string;
  path?: readonly (
     | PropertyKey
     | Readonly<{
     key: PropertyKey;
  }>)[];
}>[];

Schema issues, formatted for the model by the execute door.

---

InvalidOperationOutputCclass

An operation’s result failed its declared output schema.

Extends

• Error

Constructors

Constructor

Signature

new InvalidOperationOutput(issues): InvalidOperationOutput;

Parameters

Parameter	Type	Description
issues	readonly Readonly<{ message: string; path?: readonly ( | PropertyKey | Readonly<{ key: PropertyKey; }>)[]; }>[]	Schema issues, kept for operators; never shown to the model.

Returns

InvalidOperationOutput

Overrides

Signature

Error.constructor;

Properties

issues

Signature

readonly issues: readonly Readonly<{
  message: string;
  path?: readonly (
     | PropertyKey
     | Readonly<{
     key: PropertyKey;
  }>)[];
}>[];

Schema issues, kept for operators; never shown to the model.

AccessTtype alias

Signature

type Access = typeof ToolAccessSchema.Type;

What one operation does: read observes, write changes something.

---

ToolPolicyTtype alias

Signature

type ToolPolicy = typeof ToolPolicySchema.Type;

An author’s labels for one operation or direct tool.

---

GrantTtype alias

Signature

type Grant = typeof GrantSchema.Type;

The access a host grants one module.

---

GrantsTtype alias

Signature

type Grants = Readonly<Record<string, Grant>>;

A host’s grants, keyed by module id. An unnamed module uses defaultGrant unless it is required, in which case missing authority is refused.

---

AccessLabelTtype alias

Signature

type AccessLabel = Readonly<{
  module: string;
  operation: string;
  access: Access;
  confirm: boolean;
}>;

The labels an operation or direct tool carries, as its author declared them.

---

AccessContextTtype alias

Signature

type AccessContext = Readonly<{
  sessionId: string | null;
}>;

The Session a runtime serves; null for a session-free host.

---

ConfirmRequestTtype alias

Signature

type ConfirmRequest = Readonly<
  Omit<AccessLabel, "confirm"> & AccessContext & object
>;

One call the host is asked to approve before it runs.

---

AccessRefusalReasonTtype alias

Signature

type AccessRefusalReason =
  "not-granted" | "read-only" | "confirmation-unavailable" | "declined";

Why a call was refused before it ran.

---

AccessRefusalTtype alias

Signature

type AccessRefusal = Readonly<{
  refused: true;
  module: string;
  operation: string;
  reason: AccessRefusalReason;
  message: string;
}>;

The ordinary result a refused call returns in place of running.

---

AccessOptionsTtype alias

Signature

type AccessOptions = Readonly<{
  defaultGrant?: Grant;
  grants?: Grants;
  required?: readonly string[];
  sessionGrants?: (context) => Grants;
  beforeCall?: (signal) => Promise<void>;
  confirmWrites?: boolean;
  confirm?: (request, signal) => Promise<boolean>;
  onRefused?: (refusal, context) => void;
}>;

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. Native hosts own durable approval policy for admitted writes; explicit author confirmation still uses this port.

---

LabelledToolTtype alias

Signature

type LabelledTool = MuleTool &
  Readonly<{
    module: string;
    access?: Access;
    confirm?: boolean;
  }>;

A Mule tool that carries its author’s access labels outside execute.

---

CapabilitySessionTtype alias

Signature

type CapabilitySession = Readonly<{
  sessionId: string;
  commandId?: string;
  meta?: typeof Schema.Json.Type;
}>;

Session on whose behalf one runtime acquires its capability projections.

---

CapabilitySourceContextTtype alias

Signature

type CapabilitySourceContext = Readonly<{
  session?: CapabilitySession;
  signal: AbortSignal;
  invalidate: () => void;
}>;

Context supplied while acquiring one current capability projection.

---

CapabilitySourceSnapshotTtype alias

Signature

type CapabilitySourceSnapshot = Readonly<{
  version: string;
  modules: readonly ModuleRegistration[];
}>;

Bounded current projection returned by one capability source.

---

CapabilitySourceAcquisitionTtype alias

Signature

type CapabilitySourceAcquisition = Readonly<{
  snapshot: CapabilitySourceSnapshot;
  release: () => Promise<void>;
}>;

Acquired source projection and the cleanup that owns its live adapter.

---

CapabilitySourceTtype alias

Signature

type CapabilitySource = Readonly<{
  id: string;
  acquire: (context) => Promise<CapabilitySourceAcquisition>;
}>;

Promise-shaped host boundary for one versioned capability projection.

---

MyceliumSourcePhaseTtype alias

Signature

type MyceliumSourcePhase = "acquire" | "release" | "stale";

Lifecycle phase in which a capability source failed.

---

MyceliumErrorTtype alias

Signature

type MyceliumError =
  | MyceliumClosedError
  | MyceliumDefinitionError
  | MyceliumSourceError
  | SandboxFailure;

Closed failure vocabulary for the first Mycelium runtime slice.

---

ExecutionOptionsTtype alias

Signature

type ExecutionOptions = Readonly<{
  timeoutMs?: number;
  abortGraceMs?: number;
}> &
  SandboxAdmissionOptions;

Host execution limits plus the reserved, host-only admission contract.

---

CollectedImageTtype alias

Signature

type CollectedImage = Readonly<{
  data: string;
  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
  path: string;
  bytes: number;
}>;

A single image collected during an execute run.

---

ExecutionImagesTtype alias

Signature

type ExecutionImages = Readonly<{
  push: (image) => string;
}>;

The collector as one execution’s operations see it: push only.

---

InvocationContextTtype alias

Signature

type InvocationContext = Readonly<{
  executionId: string;
  toolCallId?: string;
  operationOrdinal?: number;
  toolCallCode?: string;
  deadlineAt: number | null;
  signal: AbortSignal;
  images?: ExecutionImages;
  output?: Readonly<{
    write: (stream, bytes) => void;
  }>;
}>;

The only context an operation callback may observe.

---

MyceliumOptionsTtype alias

Signature

type MyceliumOptions = Readonly<{
  modules?: readonly ModuleRegistration[];
  sources?: readonly CapabilitySource[];
  session?: CapabilitySession;
  execution?: ExecutionOptions;
  sandbox: Sandbox;
  onSandboxFailure?: (event) => Promise<void>;
  tools?: readonly LabelledTool[];
  access?: AccessOptions;
}>;

Inputs used to construct the Promise-facing runtime.

---

AcquireOptionsTtype alias

Signature

type AcquireOptions = Readonly<{
  signal?: AbortSignal;
}>;

Cancellation options for one Promise-facing lease acquisition.

---

LeaseTtype alias

Signature

type Lease = Readonly<{
  revision: string;
  catalog: ForageCatalog;
  executeTool: MuleTool;
  tools: readonly MuleTool[];
  release: () => Promise<void>;
}>;

One immutable Promise-facing capability revision.

---

RuntimeTtype alias

Signature

type Runtime = Readonly<{
  acquire: (options?) => Promise<Lease>;
  close: () => Promise<void>;
}>;

Warm Promise-facing lifecycle for acquiring immutable run leases.

---

OperationDefinitionTtype alias

Signature

type OperationDefinition<I, O> = Readonly<{
  replay?: "safe" | "unsafe";
  access?: Access;
  confirm?: boolean;
  description?: string;
  input: OperationSchema<I>;
  output?: OperationSchema<O>;
  execute: (input, context) => Promise<O>;
}>;

Declaration for one operation behind the execute door. input and output may be Effect schemas (encoded as JSON) or any Standard Schema with Standard JSON Schema, such as Zod 4.

Type Parameters

Type Parameter
I
O

---

ModuleDefinitionTtype alias

Signature

type ModuleDefinition = Readonly<{
  id: string;
  name?: string;
  namespace?: readonly string[];
  description?: string;
  operations: Readonly<
    Record<string, OperationRegistration | ModuleRegistration>
  >;
}>;

Declaration for one stable module and its related operations.

---

MyceliumApiTtype alias

Signature

type MyceliumApi = Readonly<{
  module: (definition) => ModuleRegistration;
  operation: {
    <I, O>(definition): OperationRegistration<I, O>;
    <I, O>(definition): OperationRegistration<I, O>;
  };
  make: (options) => Promise<Runtime>;
  gate: (module, gate) => ModuleRegistration;
  grantAs: (module, grantKey) => ModuleRegistration;
}>;

Public convenience namespace contract.

---

OperationSchemaIssueTtype alias

Signature

type OperationSchemaIssue = Readonly<{
  message: string;
  path?: readonly (
    | PropertyKey
    | Readonly<{
        key: PropertyKey;
      }>
  )[];
}>;

One Standard Schema issue.

---

OperationSchemaResultTtype alias

Signature

type OperationSchemaResult<T> =
  | Readonly<{
      value: T;
      issues?: undefined;
    }>
  | Readonly<{
      issues: readonly OperationSchemaIssue[];
    }>;

Standard Schema validation result.

Type Parameters

Type Parameter
T

---

StandardOperationSchemaTtype alias

Signature

type StandardOperationSchema<T> = Readonly<{
  ~standard: Readonly<{
     validate: (value) =>
        | OperationSchemaResult<T>
       | Promise<OperationSchemaResult<T>>;
     jsonSchema: JsonSchemaSource["~standard"]["jsonSchema"];
  }>;
}>;

Any Standard Schema that also implements Standard JSON Schema, such as a Zod 4 schema. Mycelium validates with validate and describes the operation to the model with jsonSchema.

Type Parameters

Type Parameter
T

---

OperationSchemaTtype alias

Signature

type OperationSchema<T> = Schema.Codec<T, unknown> | StandardOperationSchema<T>;

Schema for one operation’s input or output: an Effect schema (exchanged as its canonical JSON codec, Schema.toCodecJson), or any Standard Schema with Standard JSON Schema such as Zod 4.

Type Parameters

Type Parameter
T

---

OperationRegistrationTtype alias

Signature

type OperationRegistration<I, O> = Readonly<{
  [operationBrand]: true;
  [operationTypes]?: Readonly<{
    input: I;
    output: O;
  }>;
}>;

Opaque handle for one schema-described operation.

Type Parameters

Type Parameter	Default type
I	unknown
O	unknown

---

ModuleRegistrationTtype alias

Signature

type ModuleRegistration = Readonly<{
  [moduleBrand]: true;
}>;

Opaque handle for one namespaced capability module.

---

GateDecisionTtype alias

Signature

type GateDecision =
  | Readonly<{
      kind: "allow";
    }>
  | Readonly<{
      kind: "refuse";
      value: MyceliumJsonValue;
    }>;

A gate’s verdict for one call: run the operation, or return value instead.

---

OperationGateTtype alias

Signature

type OperationGate = (call) => GateDecision | Promise<GateDecision>;

Asked before every call of a gated module’s operations.

Parameters

Parameter	Type
call	Readonly<{ operation: string; context: InvocationContext; }>

Returns

| GateDecision | Promise<GateDecision>

---

SandboxAdmissionOptionsTtype alias

Signature

type SandboxAdmissionOptions = Readonly<{
  sandboxCapacity?: number;
  admissionWaitMs?: number;
}>;

Host-owned admission inputs; never part of guest execute arguments.

---

SandboxAdmissionPolicyTtype alias

Signature

type SandboxAdmissionPolicy = Readonly<{
  capacity: number;
  waitMs: number;
}>;

Captured once per runtime and shared across backing-work groups.

---

SandboxFailureEventTtype alias

Signature

type SandboxFailureEvent = typeof SandboxFailureEventSchema.Type;

Full operator diagnostics, excluded from model conversation and default reads.

ToolAccessSchemaconstconstant

Signature

const ToolAccessSchema: Literals<readonly ["read", "write"]>;

What one operation does, declared by its author as a fixed fact: read observes, write changes something. An unlabelled operation is write.

---

ToolConfirmSchemaconstconstant

Signature

const ToolConfirmSchema: Boolean = Schema.Boolean;

Whether the author asks that a person approve each call first.

---

ToolPolicySchemaconstconstant

Signature

const ToolPolicySchema: Struct<{
  access: optional<Literals<readonly ["read", "write"]>>;
  confirm: optional<Boolean>;
}>;

An author’s labels for one operation or direct tool: the one definition both the TypeScript type and the registration-time parse derive from.

---

GrantSchemaconstconstant

Signature

const GrantSchema: Literals<readonly ["none", "read", "write"]>;

The access a host grants one module: write allows every operation, read allows only read operations, none allows nothing.

---

MAX_EXECUTION_IMAGESconstconstant

Signature

const MAX_EXECUTION_IMAGES: 8 = 8;

Maximum number of out-of-band images retained for one execution.

---

Myceliumconstconstant

Signature

const Mycelium: MyceliumApi;

Schema-described authoring and Promise-facing runtime construction.

---

SandboxFailureEventSchemaconstconstant

Signature

const SandboxFailureEventSchema: Struct<{
  kind: Literal<"sandbox_failure">;
  ref: String;
  executionId: String;
  adapter: String;
  buildSha: NullOr<String>;
  tag: Literals<
    readonly [
      "SourceInvalid",
      "GuestThrew",
      "DeadlineExceeded",
      "SandboxBusy",
      "Cancelled",
      "DispatchLost",
      "SandboxCrashed",
      "BadResponse",
      "ResultTooLarge",
      "ResultNotJson",
      "CapabilityFailed",
      "Unknown",
    ]
  >;
  fields: $Record<String, Codec<JSONType, JSONType, never, never>>;
  healthAlert: Boolean;
}>;

Shared structural grammar for durable operator facts and client inspection.

normalizeSandboxAdmissionPolicy()fnfunction

Signature

function normalizeSandboxAdmissionPolicy(
  options,
  availableCores?,
): SandboxAdmissionPolicy;

Validate host policy and resolve defaults from a platform-owned core observation.

Parameters

Parameter	Type
options	| Readonly<{ sandboxCapacity?: number; admissionWaitMs?: number; }> | undefined
availableCores?	number

Returns

SandboxAdmissionPolicy

References

sandboxFailure

Re-exports sandboxFailure

---

isSandboxFailure

Re-exports isSandboxFailure

---

sandboxOperatorValue

Re-exports sandboxOperatorValue

---

MyceliumJsonValue

Re-exports MyceliumJsonValue

---

SandboxValue

Re-exports SandboxValue

---

SandboxBinding

Re-exports SandboxBinding

---

SandboxRequest

Re-exports SandboxRequest

---

Sandbox

Re-exports Sandbox

---

SourceInvalid

Re-exports SourceInvalid

---

GuestThrew

Re-exports GuestThrew

---

DeadlineExceeded

Re-exports DeadlineExceeded

---

SandboxBusy

Re-exports SandboxBusy

---

Cancelled

Re-exports Cancelled

---

DispatchLost

Re-exports DispatchLost

---

SandboxCrashed

Re-exports SandboxCrashed

---

BadResponse

Re-exports BadResponse

---

ResultTooLarge

Re-exports ResultTooLarge

---

ResultNotJson

Re-exports ResultNotJson

---

CapabilityFailed

Re-exports CapabilityFailed

---

Unknown

Re-exports Unknown

---

sandboxFailureMessage

Re-exports sandboxFailureMessage

---

SandboxFailure

Re-exports SandboxFailure

---

CapabilityDiagnostic

Re-exports CapabilityDiagnostic

---

CapabilityFailureFields

Re-exports CapabilityFailureFields