@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/docs/api/mcp.md

@@ -0,0 +1,239 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / mcp
+
+# mcp
+
+## Type Aliases
+
+### McpPrincipal
+
+```ts
+type McpPrincipal =
+  | Readonly<{
+      actor: Extract<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+      role: "owner" | "member";
+    }>
+  | Readonly<{
+      actor: Exclude<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+    }>;
+```
+
+Authenticated credential identity, scoped by its host. Never a bearer token.
+
+---
+
+### McpCatalogSnapshot
+
+```ts
+type McpCatalogSnapshot = Readonly<{
+  instructions: string;
+  sources: readonly CapabilitySource[];
+  grants: Grants;
+  approvedWrites?: readonly string[];
+}>;
+```
+
+Current installed capabilities and explicit grants for one admitted principal.
+
+---
+
+### McpAuthentication
+
+```ts
+type McpAuthentication =
+  | Readonly<{
+      kind: "admitted";
+      principal: McpPrincipal;
+    }>
+  | Readonly<{
+      kind: "refused";
+      status: 401 | 403 | 404 | 429;
+      retryAfter?: number;
+    }>;
+```
+
+Admission is required on every HTTP request, including notifications.
+
+---
+
+### McpToolCall
+
+```ts
+type McpToolCall = Readonly<{
+  id: string;
+  name: string;
+  arguments: ToolCall["arguments"];
+}>;
+```
+
+A JSON tool call submitted to the host's execution owner.
+
+---
+
+### McpExecutionContext
+
+```ts
+type McpExecutionContext = Readonly<{
+  signal: AbortSignal;
+  onPart?: (part) => Promise<void>;
+  access: Pick<AccessOptions, "confirm"> &
+    Readonly<{
+      confirmWrites: true;
+      beforeCall: (signal) => Promise<void>;
+    }>;
+}>;
+```
+
+Request-scoped hooks carried into the same Mycelium runtime as hosted tools.
+
+---
+
+### McpCatalogSession
+
+```ts
+type McpCatalogSession = Readonly<{
+  id: string;
+  principal: McpPrincipal;
+  refresh: () => Promise<void>;
+  describe: () => Promise<{
+    instructions: string;
+    tools: readonly MuleTool["descriptor"][];
+  }>;
+  call: (call, context) => Promise<MuleToolResult>;
+  disconnect: () => Promise<void>;
+}>;
+```
+
+A principal-bound catalog and its existing execution owner.
+
+---
+
+### McpCatalogProvider
+
+```ts
+type McpCatalogProvider = Readonly<{
+  open: (principal, input) => Promise<McpCatalogSession | null>;
+  resume: (principal, id) => Promise<McpCatalogSession | null>;
+}>;
+```
+
+Host catalog adapter. All lookups and acquisitions are principal-bound.
+
+---
+
+### Mcp
+
+```ts
+type Mcp = Readonly<{
+  handleRequest: (request) => Promise<Response>;
+  close: () => Promise<void>;
+}>;
+```
+
+HTTP MCP lifecycle. Closing transport streams preserves host-owned Sessions.
+
+---
+
+### McpSessionMetadata
+
+```ts
+type McpSessionMetadata = Readonly<{
+  id: string;
+  principal: McpPrincipal;
+}>;
+```
+
+Durable connection identity, without credentials or live execution callbacks.
+
+---
+
+### McpPersistence
+
+```ts
+type McpPersistence = Readonly<{
+  eventStore: (sessionId) => EventStore;
+  initialized: (id, session) => Promise<void>;
+  closed: (id, session) => Promise<void>;
+}>;
+```
+
+SDK-supported persistence; live protocol callbacks are never reconstructed.
+
+## Functions
+
+### sameMcpPrincipal()
+
+```ts
+function sameMcpPrincipal(left, right): boolean;
+```
+
+Compare complete admitted identities, including a canonical member's role.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `left`    | [`McpPrincipal`](#mcpprincipal) |
+| `right`   | [`McpPrincipal`](#mcpprincipal) |
+
+#### Returns
+
+`boolean`
+
+---
+
+### createMcpCatalog()
+
+```ts
+function createMcpCatalog(options): McpCatalogProvider;
+```
+
+Adapt principal-scoped capability sources and a sandbox to the shared MCP
+server. Connections are process-local. Durable hosts supply their own catalog
+provider.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                               |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `load`: (`principal`) => `Promise`\<[`McpCatalogSnapshot`](#mcpcatalogsnapshot)\>; `sandbox`: [`Sandbox`](sandbox.md#sandbox); \}\> |
+
+#### Returns
+
+[`McpCatalogProvider`](#mcpcatalogprovider)
+
+---
+
+### createMcp()
+
+```ts
+function createMcp(options): Mcp;
+```
+
+Serve the host's principal-bound Mycelium catalog through one MCP
+implementation.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `catalog`: [`McpCatalogProvider`](#mcpcatalogprovider); `authenticate`: (`request`) => `Promise`\<[`McpAuthentication`](#mcpauthentication)\>; `persistence?`: [`McpPersistence`](#mcppersistence); \}\> |
+
+#### Returns
+
+[`Mcp`](#mcp)

package/docs/api/remote.md

@@ -0,0 +1,108 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / remote
+
+# remote
+
+## Type Aliases
+
+### RemoteOperationDescriptor
+
+```ts
+type RemoteOperationDescriptor = Readonly<{
+  replay: "safe" | "unsafe";
+  description?: string;
+  input: MyceliumJsonValue;
+  output: MyceliumJsonValue | null;
+}>;
+```
+
+One operation's model-facing contract with its schemas as JSON Schema.
+
+---
+
+### RemoteModuleDescriptor
+
+```ts
+type RemoteModuleDescriptor = Readonly<{
+  description?: string;
+  operations: Readonly<Record<string, RemoteOperationDescriptor>>;
+}>;
+```
+
+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.
+
+## Functions
+
+### describeModule()
+
+```ts
+function describeModule(registration): RemoteModuleDescriptor;
+```
+
+Project one module's callable surface; unrepresentable schemas throw.
+
+#### Parameters
+
+| Parameter      | Type                                                |
+| -------------- | --------------------------------------------------- |
+| `registration` | [`ModuleRegistration`](index.md#moduleregistration) |
+
+#### Returns
+
+[`RemoteModuleDescriptor`](#remotemoduledescriptor)
+
+---
+
+### invokeModuleOperation()
+
+```ts
+function invokeModuleOperation(
+  registration,
+  path,
+  input,
+  context,
+): Promise<JSONType>;
+```
+
+Run one described operation through its own input and output schemas.
+
+#### Parameters
+
+| Parameter      | Type                                                |
+| -------------- | --------------------------------------------------- |
+| `registration` | [`ModuleRegistration`](index.md#moduleregistration) |
+| `path`         | `string`                                            |
+| `input`        | `unknown`                                           |
+| `context`      | [`InvocationContext`](index.md#invocationcontext)   |
+
+#### Returns
+
+`Promise`\<`JSONType`\>
+
+---
+
+### remoteModule()
+
+```ts
+function remoteModule(options): ModuleRegistration;
+```
+
+Rebuild a described module on the host side. Each operation parses its input and
+output against the described JSON Schema, then forwards to `invoke`.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options` | `Readonly`\<\{ `id`: `string`; `name`: `string`; `descriptor`: [`RemoteModuleDescriptor`](#remotemoduledescriptor); `invoke`: (`path`, `input`, `context`) => `Promise`\<[`MyceliumJsonValue`](sandbox.md#myceliumjsonvalue)\>; \}\> |
+
+#### Returns
+
+[`ModuleRegistration`](index.md#moduleregistration)

package/docs/api/sandbox-boundary.md

@@ -0,0 +1,325 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / sandbox-boundary
+
+# sandbox-boundary
+
+## Type Aliases
+
+### SandboxBindingInput
+
+```ts
+type SandboxBindingInput = MyceliumJsonValue | undefined;
+```
+
+JSON argument or the SDK's explicit absence of an argument.
+
+---
+
+### SandboxOperationBindings
+
+```ts
+type SandboxOperationBindings = Readonly<
+  Record<
+    string,
+    Readonly<Record<string, (input) => Promise<MyceliumJsonValue>>>
+  >
+>;
+```
+
+Host operation callbacks after decoding JSON or an absent RPC argument.
+
+## Functions
+
+### isSandboxFailure()
+
+```ts
+function isSandboxFailure(cause): cause is SandboxFailure;
+```
+
+Admit only errors constructed by the sandbox owner, using the maintained
+decoder.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cause`   | `unknown` |
+
+#### Returns
+
+`cause is SandboxFailure`
+
+---
+
+### sandboxFailure()
+
+```ts
+function sandboxFailure(cause): SandboxFailure;
+```
+
+Foreign throws stay private until an owner admits a diagnostic.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cause`   | `unknown` |
+
+#### Returns
+
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure)
+
+---
+
+### sandboxValueKind()
+
+```ts
+function sandboxValueKind(value): string;
+```
+
+Label a rejected JSON value without caller-owned reflection.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+#### Returns
+
+`string`
+
+---
+
+### sandboxBindingInput()
+
+```ts
+function sandboxBindingInput(value): SandboxBindingInput;
+```
+
+Decode the RPC argument before any capability callback observes it.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+#### Returns
+
+[`SandboxBindingInput`](#sandboxbindinginput)
+
+---
+
+### sandboxOperatorValue()
+
+```ts
+function sandboxOperatorValue(cause): JSONType;
+```
+
+Full operator representation, including nested errors, aggregates and cycles.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cause`   | `unknown` |
+
+#### Returns
+
+`JSONType`
+
+---
+
+### sandboxGuestFailure()
+
+```ts
+function sandboxGuestFailure(cause, bindings?): GuestThrew;
+```
+
+Decode the engine's guest-owned diagnostic once; renderers receive typed fields.
+
+#### Parameters
+
+| Parameter  | Type                                                                                                                  |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| `cause`    | `unknown`                                                                                                             |
+| `bindings` | `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`SandboxBinding`](sandbox.md#sandboxbinding)\>\>\>\> |
+
+#### Returns
+
+[`GuestThrew`](sandbox-failure.md#guestthrew)
+
+---
+
+### sandboxTransportMessage()
+
+```ts
+function sandboxTransportMessage(failure, ref): string;
+```
+
+Error.message is the SDK's wire carrier; only this safe, bounded envelope
+crosses it.
+
+#### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `failure` | [`SandboxFailure`](sandbox-failure.md#sandboxfailure) |
+| `ref`     | `string`                                              |
+
+#### Returns
+
+`string`
+
+---
+
+### recoverSandboxFailure()
+
+```ts
+function recoverSandboxFailure(failure, failures): SandboxFailure;
+```
+
+Recovery uses the decoded identity, never a match against diagnostic text.
+
+#### Parameters
+
+| Parameter  | Type                                                                             |
+| ---------- | -------------------------------------------------------------------------------- |
+| `failure`  | [`SandboxFailure`](sandbox-failure.md#sandboxfailure)                            |
+| `failures` | `ReadonlyMap`\<`string`, [`SandboxFailure`](sandbox-failure.md#sandboxfailure)\> |
+
+#### Returns
+
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure)
+
+---
+
+### sandboxExecutorFailure()
+
+```ts
+function sandboxExecutorFailure(cause, limitMs, elapsedMs): SandboxFailure;
+```
+
+Decode Codemode's documented error carrier before adapters choose a failure.
+
+#### Parameters
+
+| Parameter   | Type      |
+| ----------- | --------- |
+| `cause`     | `unknown` |
+| `limitMs`   | `number`  |
+| `elapsedMs` | `number`  |
+
+#### Returns
+
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure)
+
+---
+
+### sandboxTransportErrno()
+
+```ts
+function sandboxTransportErrno(cause): string | undefined;
+```
+
+Decode a transport-owned errno without reflecting on a foreign throw in
+adapters.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cause`   | `unknown` |
+
+#### Returns
+
+`string` \| `undefined`
+
+---
+
+### sandboxSourceError()
+
+```ts
+function sandboxSourceError(cause):
+  | Readonly<{
+      pos: number;
+    }>
+  | undefined;
+```
+
+Admit Acorn's documented offset from a syntax exception at this boundary.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cause`   | `unknown` |
+
+#### Returns
+
+\| `Readonly`\<\{ `pos`: `number`; \}\> \| `undefined`
+
+---
+
+### sandboxCapabilityFailure()
+
+```ts
+function sandboxCapabilityFailure(
+  cause,
+  namespace,
+  operation,
+  admitted?,
+): SandboxFailure;
+```
+
+Capability owners supply an admission schema; decoding and foreign fallback stay
+here.
+
+#### Parameters
+
+| Parameter   | Type                                                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cause`     | `unknown`                                                                                                                                            |
+| `namespace` | `string`                                                                                                                                             |
+| `operation` | `string`                                                                                                                                             |
+| `admitted`  | `ZodType`\<`Readonly`\<\{ `kind`: `"Files"` \| `"Forage"` \| `"InvalidInput"` \| `"Unavailable"` \| `"OperationFailed"`; `message`: `string`; \}\>\> |
+
+#### Returns
+
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure)
+
+---
+
+### sandboxBindingBoundary()
+
+```ts
+function sandboxBindingBoundary(bindings): Readonly<{
+  bindings: SandboxRequest["bindings"];
+  capture: (failure) => string;
+  recover: (failure) => SandboxFailure;
+  returnedFailure: (value) => SandboxFailure | undefined;
+}>;
+```
+
+One boundary owns RPC decoding, safe transport and invocation-scoped recovery.
+
+#### Parameters
+
+| Parameter  | Type                                                    |
+| ---------- | ------------------------------------------------------- |
+| `bindings` | [`SandboxOperationBindings`](#sandboxoperationbindings) |
+
+#### Returns
+
+`Readonly`\<\{ `bindings`:
+[`SandboxRequest`](sandbox.md#sandboxrequest)\[`"bindings"`\]; `capture`:
+(`failure`) => `string`; `recover`: (`failure`) =>
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure); `returnedFailure`:
+(`value`) => [`SandboxFailure`](sandbox-failure.md#sandboxfailure) \|
+`undefined`; \}\>