@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/cloudflare.md

@@ -0,0 +1,500 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / cloudflare
+
+# cloudflare
+
+## Classes
+
+### `abstract` ShiitakeOwner
+
+Owns runtime opening, HTTP/ACP transport, inbox observation and alarm recovery.
+
+#### Type Parameters
+
+| Type Parameter                                                          | Default type                                          |
+| ----------------------------------------------------------------------- | ----------------------------------------------------- |
+| `Env`                                                                   | -                                                     |
+| `State` _extends_ [`CloudflareShiitakeState`](#cloudflareshiitakestate) | [`CloudflareShiitakeState`](#cloudflareshiitakestate) |
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ShiitakeOwner<Env, State>(ctx, env): ShiitakeOwner<Env, State>;
+```
+
+###### Parameters
+
+| Parameter | Type    |
+| --------- | ------- |
+| `ctx`     | `State` |
+| `env`     | `Env`   |
+
+###### Returns
+
+[`ShiitakeOwner`](#abstract-shiitakeowner)\<`Env`, `State`\>
+
+#### Methods
+
+##### shiitake()
+
+```ts
+shiitake(): Promise<CloudflareShiitake>;
+```
+
+Borrow this owner's runtime directly; only the host owns its lifetime.
+
+###### Returns
+
+`Promise`\<[`CloudflareShiitake`](#cloudflareshiitake)\>
+
+##### abortActiveSessions()
+
+```ts
+abortActiveSessions(): Promise<void>;
+```
+
+Stop live execution without constructing a cold owner's runtime.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### closeShiitake()
+
+```ts
+closeShiitake(): Promise<void>;
+```
+
+Close owned resources before storage erasure; a cold owner has none.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### readInboxChanges()
+
+```ts
+readInboxChanges(after, limit): Promise<Readonly<{
+  rows: readonly (
+     | SessionSummaryRow
+     | Readonly<{
+     sessionId: string;
+     deleted: true;
+  }>)[];
+  through: number;
+  latest: number;
+}>>;
+```
+
+Bounded strict-after read of this Agent's changed inbox rows.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `after`   | `number` |
+| `limit`   | `number` |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `rows`: readonly ( \|
+[`SessionSummaryRow`](client.md#sessionsummaryrow) \| `Readonly`\<\{
+`sessionId`: `string`; `deleted`: `true`; \}\>)[]; `through`: `number`;
+`latest`: `number`; \}\>\>
+
+##### readInboxRevision()
+
+```ts
+readInboxRevision(): number;
+```
+
+Latest inbox revision; read only after the owner has opened.
+
+###### Returns
+
+`number`
+
+##### pruneInboxTombstones()
+
+```ts
+pruneInboxTombstones(through): void;
+```
+
+Prune deletion deltas after every current member inbox has acknowledged them.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `through` | `number` |
+
+###### Returns
+
+`void`
+
+##### wakeRuntime()
+
+```ts
+wakeRuntime(): Promise<void>;
+```
+
+Persist a wake and run one reconciliation pass, including host work.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### alarm()
+
+```ts
+alarm(): Promise<void>;
+```
+
+Native alarms reconstruct the owner without an incoming user request. A
+construction or wake failure must not strand the claimed work on platform alarm
+retries: it is caught, logged, and explicitly re-armed with bounded backoff
+instead.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### fetch()
+
+```ts
+fetch(request): Promise<Response>;
+```
+
+Serve one request through Shiitake's whole HTTP surface.
+
+###### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `request` | `Request` |
+
+###### Returns
+
+`Promise`\<`Response`\>
+
+---
+
+### `abstract` ShiitakeDO
+
+Native Cloudflare entry points; all runtime lifetime belongs to the owner.
+
+#### Extends
+
+- `DurableObject`\<`Env`\>
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Env`          |
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ShiitakeDO<Env>(ctx, env): ShiitakeDO<Env>;
+```
+
+###### Parameters
+
+| Parameter | Type                 |
+| --------- | -------------------- |
+| `ctx`     | `DurableObjectState` |
+| `env`     | `Env`                |
+
+###### Returns
+
+[`ShiitakeDO`](#abstract-shiitakedo)\<`Env`\>
+
+###### Inherited from
+
+```ts
+DurableObject<Env>.constructor
+```
+
+#### Methods
+
+##### alarm()
+
+```ts
+alarm(): Promise<void>;
+```
+
+Reconcile due runtime and host work through the owner.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Overrides
+
+```ts
+DurableObject.alarm;
+```
+
+##### fetch()
+
+```ts
+fetch(request): Promise<Response>;
+```
+
+Route an authenticated client request through the owner.
+
+###### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `request` | `Request` |
+
+###### Returns
+
+`Promise`\<`Response`\>
+
+###### Overrides
+
+```ts
+DurableObject.fetch;
+```
+
+## Type Aliases
+
+### CloudflareShiitakeState
+
+```ts
+type CloudflareShiitakeState = Readonly<{
+  storage: SqliteOwner &
+    Pick<DurableObjectStorage, "getAlarm" | "setAlarm" | "deleteAlarm"> &
+    object;
+  waitUntil: (task) => void;
+}>;
+```
+
+Native Durable Object capabilities used by the Cloudflare adapter.
+
+---
+
+### CloudflareShiitakeTools
+
+```ts
+type CloudflareShiitakeTools = Readonly<{
+  modules?: readonly ModuleRegistration[];
+  sources?: readonly CapabilitySource[];
+  sandbox: Sandbox;
+  access?: ToolAccess;
+}>;
+```
+
+Non-empty Mycelium capabilities supplied by a Cloudflare host.
+
+---
+
+### CloudflareHostWork
+
+```ts
+type CloudflareHostWork = Readonly<{
+  pending: () => Readonly<{
+    due: boolean;
+    nextWakeAt: number | null;
+  }>;
+  run: () => Promise<void>;
+}>;
+```
+
+Durable host work that shares Shiitake's one native alarm, such as a host-owned
+delivery outbox. Shiitake never interprets it.
+
+---
+
+### CloudflareHostJobs
+
+```ts
+type CloudflareHostJobs = Readonly<{
+  lane: string;
+  open: (runtime) => Readonly<{
+    execute: (job) => Promise<WatchdogExecutionDecision>;
+  }>;
+}>;
+```
+
+Host jobs use a separate slot in Shiitake's one Watchdog and native alarm.
+
+---
+
+### CloudflareShiitakeAcpServer
+
+```ts
+type CloudflareShiitakeAcpServer = Readonly<{
+  handleRequest: (request, meta) => Promise<Response>;
+}>;
+```
+
+ACP's maintained transport, supplied by the host without a package cycle.
+
+---
+
+### CloudflareShiitakeOptions
+
+```ts
+type CloudflareShiitakeOptions = Readonly<{
+  meta?: HostMetaOptions;
+  model: ModelSource;
+  instructions: InstructionSource;
+  tools?: readonly [] | CloudflareShiitakeTools;
+  storageBudget?: StorageBudget;
+  compaction?: CompactionOptions;
+  extensions: ExtensionRosterV0;
+  initialize?: (agent) => Promise<void>;
+  hostWork?: readonly CloudflareHostWork[];
+  hostJobs?: CloudflareHostJobs;
+  mailRoom?: BirdDogEffect;
+  browser?: (sessionId) => BrowserHost;
+  acp?: (agent) => Promise<CloudflareShiitakeAcpServer>;
+}>;
+```
+
+Cloudflare host inputs; the model owner resolves one frozen run selection.
+
+---
+
+### CloudflareShiitake
+
+```ts
+type CloudflareShiitake = ShiitakeOwnerAgent &
+  Readonly<{
+    readSettlement: (
+      sessionId,
+      commandId,
+    ) => Promise<CommandSettlement | undefined>;
+    acceptMail: (mail, meta?, reply?) => Promise<Accepted>;
+    alarm: () => Promise<void>;
+    activeSessions: () => Promise<readonly string[]>;
+    abortActive: () => Promise<void>;
+    browser: Readonly<{
+      fetch: (request) => Promise<Response>;
+      clear: () => Promise<void>;
+    }>;
+  }>;
+```
+
+Cloudflare host lifecycle; alarm forwarding stays outside the neutral client.
+
+---
+
+### BrowserHost
+
+```ts
+type BrowserHost = Readonly<{
+  modules: readonly ModuleRegistration[];
+  fetch: (request) => Promise<Response>;
+}>;
+```
+
+The maintained browser transport and its Session-bound tool descriptors.
+
+---
+
+### SessionInboxChanges
+
+```ts
+type SessionInboxChanges = Readonly<{
+  rows: readonly (
+    | SessionSummaryRow
+    | Readonly<{
+        sessionId: string;
+        deleted: true;
+      }>
+  )[];
+  through: number;
+  latest: number;
+}>;
+```
+
+Revisioned Session inbox changes after one owner revision, oldest first.
+
+## Functions
+
+### deliverSessionGrantsToStorage()
+
+```ts
+function deliverSessionGrantsToStorage(
+  storage,
+  sessionId,
+  delivery,
+): GrantsDeliveryResult;
+```
+
+Deliver one Session's grants into a Cloudflare owner's own storage,
+synchronously, whether or not its runtime is open; the very next tool call reads
+it. A plain function, not a Durable Object method, so no other Durable Object
+can call it over RPC: only code running inside the owner, holding its storage,
+delivers grants.
+
+#### Parameters
+
+| Parameter   | Type                                        |
+| ----------- | ------------------------------------------- |
+| `storage`   | [`SqliteOwner`](index.md#sqliteowner)       |
+| `sessionId` | `string`                                    |
+| `delivery`  | [`GrantsDelivery`](index.md#grantsdelivery) |
+
+#### Returns
+
+[`GrantsDeliveryResult`](index.md#grantsdeliveryresult)
+
+---
+
+### makeCloudflareShiitake()
+
+```ts
+function makeCloudflareShiitake(state, options): Promise<CloudflareShiitake>;
+```
+
+Construct Shiitake over one Durable Object's SQLite and lifetime.
+
+#### Parameters
+
+| Parameter | Type                                                      |
+| --------- | --------------------------------------------------------- |
+| `state`   | [`CloudflareShiitakeState`](#cloudflareshiitakestate)     |
+| `options` | [`CloudflareShiitakeOptions`](#cloudflareshiitakeoptions) |
+
+#### Returns
+
+`Promise`\<[`CloudflareShiitake`](#cloudflareshiitake)\>
+
+## References
+
+### GrantsDelivery
+
+Re-exports [GrantsDelivery](index.md#grantsdelivery)
+
+---
+
+### GrantsDeliveryResult
+
+Re-exports [GrantsDeliveryResult](index.md#grantsdeliveryresult)
+
+---
+
+### ShiitakeOwnerAgent
+
+Re-exports [ShiitakeOwnerAgent](index.md#shiitakeowneragent)
+
+---
+
+### ToolAccess
+
+Re-exports [ToolAccess](index.md#toolaccess)