@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/docs/api/index.md

@@ -0,0 +1,1081 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / index
+
+# index
+
+## Classes
+
+### MyceliumDefinitionError
+
+A capability declaration could not form one coherent installed surface.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MyceliumDefinitionError(message): MyceliumDefinitionError;
+```
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `message` | `string` |
+
+###### Returns
+
+[`MyceliumDefinitionError`](#myceliumdefinitionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "invalid_definition" = invalidDefinitionCode;
+```
+
+Stable machine-readable failure code.
+
+---
+
+### MyceliumClosedError
+
+An operation attempted to use a closed Mycelium runtime.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MyceliumClosedError(message?): MyceliumClosedError;
+```
+
+###### Parameters
+
+| Parameter | Type     | Default value                  |
+| --------- | -------- | ------------------------------ |
+| `message` | `string` | `"Mycelium runtime is closed"` |
+
+###### Returns
+
+[`MyceliumClosedError`](#myceliumclosederror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "runtime_closed" = runtimeClosedCode;
+```
+
+Stable machine-readable failure code.
+
+---
+
+### MyceliumSourceError
+
+A capability source failed at its bounded host boundary.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MyceliumSourceError(sourceId, phase): MyceliumSourceError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                          | Description                                                         |
+| ---------- | --------------------------------------------- | ------------------------------------------------------------------- |
+| `sourceId` | `string` \| `undefined`                       | Stable identity of the source, absent for whole-candidate failures. |
+| `phase`    | [`MyceliumSourcePhase`](#myceliumsourcephase) | Lifecycle phase that could not settle.                              |
+
+###### Returns
+
+[`MyceliumSourceError`](#myceliumsourceerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "source_failure" = sourceFailureCode;
+```
+
+Stable machine-readable failure code.
+
+##### sourceId
+
+```ts
+readonly sourceId: string | undefined;
+```
+
+Stable identity of the source, absent for whole-candidate failures.
+
+##### phase
+
+```ts
+readonly phase: MyceliumSourcePhase;
+```
+
+Lifecycle phase that could not settle.
+
+---
+
+### InvalidOperationInput
+
+Untrusted operation input failed the operation's declared input schema.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+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`](#invalidoperationinput)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### issues
+
+```ts
+readonly issues: readonly Readonly<{
+  message: string;
+  path?: readonly (
+     | PropertyKey
+     | Readonly<{
+     key: PropertyKey;
+  }>)[];
+}>[];
+```
+
+Schema issues, formatted for the model by the execute door.
+
+---
+
+### InvalidOperationOutput
+
+An operation's result failed its declared output schema.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+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`](#invalidoperationoutput)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### issues
+
+```ts
+readonly issues: readonly Readonly<{
+  message: string;
+  path?: readonly (
+     | PropertyKey
+     | Readonly<{
+     key: PropertyKey;
+  }>)[];
+}>[];
+```
+
+Schema issues, kept for operators; never shown to the model.
+
+## Type Aliases
+
+### Access
+
+```ts
+type Access = typeof ToolAccessSchema.Type;
+```
+
+What one operation does: `read` observes, `write` changes something.
+
+---
+
+### ToolPolicy
+
+```ts
+type ToolPolicy = typeof ToolPolicySchema.Type;
+```
+
+An author's labels for one operation or direct tool.
+
+---
+
+### Grant
+
+```ts
+type Grant = typeof GrantSchema.Type;
+```
+
+The access a host grants one module.
+
+---
+
+### Grants
+
+```ts
+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.
+
+---
+
+### AccessLabel
+
+```ts
+type AccessLabel = Readonly<{
+  module: string;
+  operation: string;
+  access: Access;
+  confirm: boolean;
+}>;
+```
+
+The labels an operation or direct tool carries, as its author declared them.
+
+---
+
+### AccessContext
+
+```ts
+type AccessContext = Readonly<{
+  sessionId: string | null;
+}>;
+```
+
+The Session a runtime serves; null for a session-free host.
+
+---
+
+### ConfirmRequest
+
+```ts
+type ConfirmRequest = Readonly<
+  Omit<AccessLabel, "confirm"> & AccessContext & object
+>;
+```
+
+One call the host is asked to approve before it runs.
+
+---
+
+### AccessRefusalReason
+
+```ts
+type AccessRefusalReason =
+  "not-granted" | "read-only" | "confirmation-unavailable" | "declined";
+```
+
+Why a call was refused before it ran.
+
+---
+
+### AccessRefusal
+
+```ts
+type AccessRefusal = Readonly<{
+  refused: true;
+  module: string;
+  operation: string;
+  reason: AccessRefusalReason;
+  message: string;
+}>;
+```
+
+The ordinary result a refused call returns in place of running.
+
+---
+
+### AccessOptions
+
+```ts
+type AccessOptions = Readonly<{
+  defaultGrant?: Grant;
+  grants?: Grants;
+  required?: readonly string[];
+  sessionGrants?: (context) => Grants;
+  beforeCall?: (signal) => Promise<void>;
+  confirmWrites?: boolean;
+  approvedWrites?: (context) => readonly string[];
+  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 and require approval for writes.
+
+---
+
+### LabelledTool
+
+```ts
+type LabelledTool = MuleTool &
+  Readonly<{
+    module: string;
+    access?: Access;
+    confirm?: boolean;
+  }>;
+```
+
+A Mule tool that carries its author's access labels outside execute.
+
+---
+
+### CapabilitySession
+
+```ts
+type CapabilitySession = Readonly<{
+  sessionId: string;
+  commandId?: string;
+  meta?: typeof Schema.Json.Type;
+}>;
+```
+
+Session on whose behalf one runtime acquires its capability projections.
+
+---
+
+### CapabilitySourceContext
+
+```ts
+type CapabilitySourceContext = Readonly<{
+  session?: CapabilitySession;
+  signal: AbortSignal;
+  invalidate: () => void;
+}>;
+```
+
+Context supplied while acquiring one current capability projection.
+
+---
+
+### CapabilitySourceSnapshot
+
+```ts
+type CapabilitySourceSnapshot = Readonly<{
+  version: string;
+  modules: readonly ModuleRegistration[];
+}>;
+```
+
+Bounded current projection returned by one capability source.
+
+---
+
+### CapabilitySourceAcquisition
+
+```ts
+type CapabilitySourceAcquisition = Readonly<{
+  snapshot: CapabilitySourceSnapshot;
+  release: () => Promise<void>;
+}>;
+```
+
+Acquired source projection and the cleanup that owns its live adapter.
+
+---
+
+### CapabilitySource
+
+```ts
+type CapabilitySource = Readonly<{
+  id: string;
+  acquire: (context) => Promise<CapabilitySourceAcquisition>;
+}>;
+```
+
+Promise-shaped host boundary for one versioned capability projection.
+
+---
+
+### MyceliumSourcePhase
+
+```ts
+type MyceliumSourcePhase = "acquire" | "release" | "stale";
+```
+
+Lifecycle phase in which a capability source failed.
+
+---
+
+### MyceliumError
+
+```ts
+type MyceliumError =
+  | MyceliumClosedError
+  | MyceliumDefinitionError
+  | MyceliumSourceError
+  | SandboxFailure;
+```
+
+Closed failure vocabulary for the first Mycelium runtime slice.
+
+---
+
+### ExecutionOptions
+
+```ts
+type ExecutionOptions = Readonly<{
+  timeoutMs?: number;
+  abortGraceMs?: number;
+}>;
+```
+
+Host-selectable execution limits; neither budget can be disabled.
+
+---
+
+### CollectedImage
+
+```ts
+type CollectedImage = Readonly<{
+  data: string;
+  mimeType: "image/jpeg" | "image/png" | "image/webp";
+  path: string;
+  bytes: number;
+}>;
+```
+
+A single image collected during an execute run.
+
+---
+
+### ExecutionImages
+
+```ts
+type ExecutionImages = Readonly<{
+  push: (image) => string;
+}>;
+```
+
+The collector as one execution's operations see it: push only.
+
+---
+
+### InvocationContext
+
+```ts
+type InvocationContext = Readonly<{
+  executionId: string;
+  toolCallId?: string;
+  toolCallCode?: string;
+  deadlineAt: number | null;
+  signal: AbortSignal;
+  images?: ExecutionImages;
+}>;
+```
+
+The only context an operation callback may observe.
+
+---
+
+### MyceliumOptions
+
+```ts
+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.
+
+---
+
+### AcquireOptions
+
+```ts
+type AcquireOptions = Readonly<{
+  signal?: AbortSignal;
+}>;
+```
+
+Cancellation options for one Promise-facing lease acquisition.
+
+---
+
+### Lease
+
+```ts
+type Lease = Readonly<{
+  revision: string;
+  catalog: ForageCatalog;
+  executeTool: MuleTool;
+  tools: readonly MuleTool[];
+  release: () => Promise<void>;
+}>;
+```
+
+One immutable Promise-facing capability revision.
+
+---
+
+### Runtime
+
+```ts
+type Runtime = Readonly<{
+  acquire: (options?) => Promise<Lease>;
+  close: () => Promise<void>;
+}>;
+```
+
+Warm Promise-facing lifecycle for acquiring immutable run leases.
+
+---
+
+### OperationDefinition
+
+```ts
+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`            |
+
+---
+
+### ModuleDefinition
+
+```ts
+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.
+
+---
+
+### MyceliumApi
+
+```ts
+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.
+
+---
+
+### OperationSchemaIssue
+
+```ts
+type OperationSchemaIssue = Readonly<{
+  message: string;
+  path?: readonly (
+    | PropertyKey
+    | Readonly<{
+        key: PropertyKey;
+      }>
+  )[];
+}>;
+```
+
+One Standard Schema issue.
+
+---
+
+### OperationSchemaResult
+
+```ts
+type OperationSchemaResult<T> =
+  | Readonly<{
+      value: T;
+      issues?: undefined;
+    }>
+  | Readonly<{
+      issues: readonly OperationSchemaIssue[];
+    }>;
+```
+
+Standard Schema validation result.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### StandardOperationSchema
+
+```ts
+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`            |
+
+---
+
+### OperationSchema
+
+```ts
+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`            |
+
+---
+
+### OperationRegistration
+
+```ts
+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`    |
+
+---
+
+### ModuleRegistration
+
+```ts
+type ModuleRegistration = Readonly<{
+  [moduleBrand]: true;
+}>;
+```
+
+Opaque handle for one namespaced capability module.
+
+---
+
+### GateDecision
+
+```ts
+type GateDecision =
+  | Readonly<{
+      kind: "allow";
+    }>
+  | Readonly<{
+      kind: "refuse";
+      value: MyceliumJsonValue;
+    }>;
+```
+
+A gate's verdict for one call: run the operation, or return `value` instead.
+
+---
+
+### OperationGate
+
+```ts
+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`](#invocationcontext); \}\> |
+
+#### Returns
+
+\| [`GateDecision`](#gatedecision) \|
+`Promise`\<[`GateDecision`](#gatedecision)\>
+
+---
+
+### SandboxFailureEvent
+
+```ts
+type SandboxFailureEvent = typeof SandboxFailureEventSchema.Type;
+```
+
+Full operator diagnostics, excluded from model conversation and default reads.
+
+## Variables
+
+### ToolAccessSchema
+
+```ts
+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`.
+
+---
+
+### ToolConfirmSchema
+
+```ts
+const ToolConfirmSchema: Boolean = Schema.Boolean;
+```
+
+Whether the author asks that a person approve each call first.
+
+---
+
+### ToolPolicySchema
+
+```ts
+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.
+
+---
+
+### GrantSchema
+
+```ts
+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\_IMAGES
+
+```ts
+const MAX_EXECUTION_IMAGES: 8 = 8;
+```
+
+Maximum number of out-of-band images retained for one execution.
+
+---
+
+### Mycelium
+
+```ts
+const Mycelium: MyceliumApi;
+```
+
+Schema-described authoring and Promise-facing runtime construction.
+
+---
+
+### SandboxFailureEventSchema
+
+```ts
+const SandboxFailureEventSchema: Struct<{
+  kind: Literal<"sandbox_failure">;
+  ref: String;
+  executionId: String;
+  adapter: String;
+  buildSha: NullOr<String>;
+  tag: Literals<
+    readonly [
+      "SourceInvalid",
+      "GuestThrew",
+      "DeadlineExceeded",
+      "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.
+
+## References
+
+### sandboxFailure
+
+Re-exports [sandboxFailure](sandbox-boundary.md#sandboxfailure)
+
+---
+
+### isSandboxFailure
+
+Re-exports [isSandboxFailure](sandbox-boundary.md#issandboxfailure)
+
+---
+
+### sandboxOperatorValue
+
+Re-exports [sandboxOperatorValue](sandbox-boundary.md#sandboxoperatorvalue)
+
+---
+
+### MyceliumJsonValue
+
+Re-exports [MyceliumJsonValue](sandbox.md#myceliumjsonvalue)
+
+---
+
+### SandboxValue
+
+Re-exports [SandboxValue](sandbox.md#sandboxvalue)
+
+---
+
+### SandboxBinding
+
+Re-exports [SandboxBinding](sandbox.md#sandboxbinding)
+
+---
+
+### SandboxRequest
+
+Re-exports [SandboxRequest](sandbox.md#sandboxrequest)
+
+---
+
+### Sandbox
+
+Re-exports [Sandbox](sandbox.md#sandbox)
+
+---
+
+### SourceInvalid
+
+Re-exports [SourceInvalid](sandbox-failure.md#sourceinvalid)
+
+---
+
+### GuestThrew
+
+Re-exports [GuestThrew](sandbox-failure.md#guestthrew)
+
+---
+
+### DeadlineExceeded
+
+Re-exports [DeadlineExceeded](sandbox-failure.md#deadlineexceeded)
+
+---
+
+### Cancelled
+
+Re-exports [Cancelled](sandbox-failure.md#cancelled)
+
+---
+
+### DispatchLost
+
+Re-exports [DispatchLost](sandbox-failure.md#dispatchlost)
+
+---
+
+### SandboxCrashed
+
+Re-exports [SandboxCrashed](sandbox-failure.md#sandboxcrashed)
+
+---
+
+### BadResponse
+
+Re-exports [BadResponse](sandbox-failure.md#badresponse)
+
+---
+
+### ResultTooLarge
+
+Re-exports [ResultTooLarge](sandbox-failure.md#resulttoolarge)
+
+---
+
+### ResultNotJson
+
+Re-exports [ResultNotJson](sandbox-failure.md#resultnotjson)
+
+---
+
+### CapabilityFailed
+
+Re-exports [CapabilityFailed](sandbox-failure.md#capabilityfailed)
+
+---
+
+### Unknown
+
+Re-exports [Unknown](sandbox-failure.md#unknown)
+
+---
+
+### sandboxFailureMessage
+
+Re-exports [sandboxFailureMessage](sandbox-failure.md#sandboxfailuremessage)
+
+---
+
+### SandboxFailure
+
+Re-exports [SandboxFailure](sandbox-failure.md#sandboxfailure)
+
+---
+
+### CapabilityDiagnostic
+
+Re-exports [CapabilityDiagnostic](sandbox-failure.md#capabilitydiagnostic)
+
+---
+
+### CapabilityFailureFields
+
+Re-exports [CapabilityFailureFields](sandbox-failure.md#capabilityfailurefields)