@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/README.md

@@ -0,0 +1,26 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/shiitake**
+
+---
+
+# @fungi.computer/shiitake
+
+## Modules
+
+| Module                                  | Description |
+| --------------------------------------- | ----------- |
+| [agar-extension](agar-extension.md)     | -           |
+| [agent-control](agent-control.md)       | -           |
+| [client-entry](client-entry.md)         | -           |
+| [client](client.md)                     | -           |
+| [cloudflare](cloudflare.md)             | -           |
+| [effect](effect.md)                     | -           |
+| [extensions](extensions.md)             | -           |
+| [fleet](fleet.md)                       | -           |
+| [hosted](hosted.md)                     | -           |
+| [http](http.md)                         | -           |
+| [index](index.md)                       | -           |
+| [model-preference](model-preference.md) | -           |
+| [node](node.md)                         | -           |
+| [testing](testing.md)                   | -           |

package/docs/api/agar-extension.md

@@ -0,0 +1,40 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / agar-extension
+
+# agar-extension
+
+## Functions
+
+### agentExtensionMethods()
+
+```ts
+function agentExtensionMethods<Context>(
+  extension,
+): Readonly<Record<string, AppBackendMethod<Context>>>;
+```
+
+Serve one Shiitake extension from this App backend. Spread the result into
+`defineAppBackend({ methods })`; the build writes the three methods into the
+Release's API, which is how a Release declares itself an Agent extension. An
+extension requesting a capability hosting lacks fails here, at build.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Context`      | `void`       |
+
+#### Parameters
+
+| Parameter   | Type                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `extension` | [`RosteredExtensionV0`](extensions.md#rosteredextensionv0) |
+
+#### Returns
+
+`Readonly`\<`Record`\<`string`, `AppBackendMethod`\<`Context`\>\>\>

package/docs/api/agent-control.md

@@ -0,0 +1,151 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / agent-control
+
+# agent-control
+
+## Type Aliases
+
+### AgentControlAgent
+
+```ts
+type AgentControlAgent = Readonly<{
+  agentId: string;
+  name: string;
+}>;
+```
+
+One existing Agent visible within the caller's authorized project or Team.
+
+---
+
+### AgentControlModel
+
+```ts
+type AgentControlModel = Readonly<{
+  address: string;
+  name: string;
+}>;
+```
+
+One host-offered model usable as an Agent's create or setModel choice.
+
+---
+
+### AgentDelegationInput
+
+```ts
+type AgentDelegationInput = Readonly<{
+  agentId: string;
+  sessionId: string;
+  text: string;
+}>;
+```
+
+One host-authorized delegation, with the caller Session supplied by acquisition.
+
+---
+
+### AgentDelegationInvocation
+
+```ts
+type AgentDelegationInvocation = Readonly<{
+  toolCallId: string;
+  sendIndex: number;
+  commandId?: string;
+  meta?: CapabilitySession["meta"];
+  toolCallCode?: string;
+}>;
+```
+
+Host-only identity and admitted command metadata for one delegated send.
+
+---
+
+### AgentControlDirectory
+
+```ts
+type AgentControlDirectory = Readonly<{
+  list: (signal) => Promise<readonly AgentControlAgent[]>;
+  send?: (input, sourceSessionId, signal, invocation?) => Promise<Accepted>;
+  create?: (input, signal, invoker?) => Promise<AgentControlAgent>;
+  setModel?: (input, signal) => Promise<void>;
+  models?: (signal) => Promise<readonly AgentControlModel[]>;
+  checkModel?: (input, signal) => Promise<void>;
+  open: (
+    agentId,
+    signal,
+  ) => Promise<
+    Readonly<{
+      agent: ShiitakeAgent;
+      release: () => Promise<void>;
+    }>
+  >;
+}>;
+```
+
+Host-owned discovery and per-operation access to ordinary Agents.
+
+## Functions
+
+### waitForAgentTerminal()
+
+```ts
+function waitForAgentTerminal(
+  session,
+  commandId,
+  timeoutMs,
+  signal,
+  startedAt?,
+): Promise<
+  Readonly<{
+    commandId: string;
+    outcome: "completed" | "failed" | "cancelled" | "interrupted";
+    sequence: number;
+    diagnostic: string | null;
+    meta?: Json;
+  }>
+>;
+```
+
+Observe one durable terminal; timeout or abort closes observation, not the work.
+
+#### Parameters
+
+| Parameter   | Type                                           |
+| ----------- | ---------------------------------------------- |
+| `session`   | [`ShiitakeSession`](client.md#shiitakesession) |
+| `commandId` | `string`                                       |
+| `timeoutMs` | `number`                                       |
+| `signal`    | `AbortSignal`                                  |
+| `startedAt` | `number`                                       |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `commandId`: `string`; `outcome`: `"completed"` \|
+`"failed"` \| `"cancelled"` \| `"interrupted"`; `sequence`: `number`;
+`diagnostic`: `string` \| `null`; `meta?`: [`Json`](extensions.md#json); \}\>\>
+
+---
+
+### createAgentControlSource()
+
+```ts
+function createAgentControlSource(directory): CapabilitySource;
+```
+
+Compose one authorized Agent-control projection for a single run lease.
+
+#### Parameters
+
+| Parameter   | Type                                              |
+| ----------- | ------------------------------------------------- |
+| `directory` | [`AgentControlDirectory`](#agentcontroldirectory) |
+
+#### Returns
+
+`CapabilitySource`

package/docs/api/client-entry.md

@@ -0,0 +1,344 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / client-entry
+
+# client-entry
+
+## Type Aliases
+
+### ClientChipV1
+
+```ts
+type ClientChipV1 = typeof clientChipSchemaV1.Type;
+```
+
+An admitted, display-only status chip.
+
+---
+
+### ClientTimelineCellV1
+
+```ts
+type ClientTimelineCellV1 = typeof clientTimelineCellSchemaV1.Type;
+```
+
+An admitted committed event with its producer identity and anchor.
+
+---
+
+### ClientContributionV1
+
+```ts
+type ClientContributionV1 = typeof clientContributionSchemaV1.Type;
+```
+
+The closed V1 presentation grammar returned by a client entry.
+
+---
+
+### ClientExtensionContextV1
+
+```ts
+type ClientExtensionContextV1 = Readonly<{
+  activity: AsyncIterable<ClientActivityV0>;
+  signal: AbortSignal;
+  onError: (error) => void;
+}>;
+```
+
+Borrowed latest-value activity; each iterator subscribes separately.
+
+---
+
+### ClientEntryV1
+
+```ts
+type ClientEntryV1 = Readonly<{
+  protocol: "shiitake.client/v1";
+  id: ExtensionId;
+  correlatedPrompts?: "note";
+  attach?: (context) => Effect.Effect<void, Error, Scope.Scope>;
+  contribute?: (slot) => ClientContributionV1;
+}>;
+```
+
+Installed client protocol; projection decoding remains inside the author
+closure.
+
+---
+
+### ClientActivityV0
+
+```ts
+type ClientActivityV0 = "idle" | "working" | "blocked" | "unknown";
+```
+
+Activity already observed by the client, never an execution authority.
+
+## Variables
+
+### clientChipSchemaV1
+
+```ts
+const clientChipSchemaV1: Struct<{
+  id: String;
+  order: Number;
+  row: Struct<{
+    id: String;
+    title: String;
+    detail: optional<String>;
+    tone: optional<
+      Literals<readonly ["attention", "running", "error", "settled", "muted"]>
+    >;
+    status: optional<
+      Struct<{
+        label: String;
+        tone: Literals<
+          readonly [
+            "neutral",
+            "primary",
+            "secondary",
+            "accent",
+            "success",
+            "info",
+            "warning",
+            "error",
+          ]
+        >;
+      }>
+    >;
+    open: optional<
+      Struct<{
+        params: $Array<
+          Struct<{
+            key: String;
+            value: String;
+          }>
+        >;
+      }>
+    >;
+  }>;
+  compact: optional<String>;
+}>;
+```
+
+One display-only status chip; order is local to the entry.
+
+---
+
+### clientTimelineCellSchemaV1
+
+```ts
+const clientTimelineCellSchemaV1: Struct<{
+  id: String;
+  sequence: Int;
+  at: Int;
+  commandId: NullOr<String>;
+  rows: $Array<Struct<{
+     id: String;
+     title: String;
+     detail: optional<String>;
+     tone: optional<Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
+     status: optional<Struct<{
+        label: String;
+        tone: Literals<readonly ["neutral", "primary", "secondary", "accent", "success", "info", "warning", "error"]>;
+     }>>;
+     open: optional<Struct<{
+        params: $Array<Struct<{
+           key: ...;
+           value: ...;
+        }>>;
+     }>>;
+     actions: optional<$Array<Struct<{
+        id: String;
+        label: String;
+        input: optional<$Record<..., ...>>;
+     }>>>;
+  }>>;
+}>;
+```
+
+One committed presentation event anchored to its real command, if any.
+
+---
+
+### clientContributionSchemaV1
+
+```ts
+const clientContributionSchemaV1: Struct<{
+  chips: $Array<Struct<{
+     id: String;
+     order: Number;
+     row: Struct<{
+        id: String;
+        title: String;
+        detail: optional<String>;
+        tone: optional<Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
+        status: optional<Struct<{
+           label: String;
+           tone: Literals<...>;
+        }>>;
+        open: optional<Struct<{
+           params: $Array<...>;
+        }>>;
+     }>;
+     compact: optional<String>;
+  }>>;
+  panel: $Array<Struct<{
+     id: String;
+     title: String;
+     detail: optional<String>;
+     tone: optional<Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
+     status: optional<Struct<{
+        label: String;
+        tone: Literals<readonly ["neutral", "primary", "secondary", "accent", "success", "info", "warning", "error"]>;
+     }>>;
+     open: optional<Struct<{
+        params: $Array<Struct<{
+           key: ...;
+           value: ...;
+        }>>;
+     }>>;
+     actions: optional<$Array<Struct<{
+        id: String;
+        label: String;
+        input: optional<$Record<..., ...>>;
+     }>>>;
+     inspection: optionalKey<Struct<{
+        commandId: String;
+        title: String;
+        rows: $Array<Struct<{
+           id: ...;
+           title: ...;
+           detail: ...;
+           tone: ...;
+           status: ...;
+           open: ...;
+        }>>;
+     }>>;
+  }>>;
+  timeline: Struct<{
+     cells: $Array<Struct<{
+        id: String;
+        sequence: Int;
+        at: Int;
+        commandId: NullOr<String>;
+        rows: $Array<Struct<{
+           id: String;
+           title: String;
+           detail: optional<...>;
+           tone: optional<...>;
+           status: optional<...>;
+           open: optional<...>;
+           actions: optional<...>;
+        }>>;
+     }>>;
+     omitted: Int;
+  }>;
+  waiting: NullOr<Struct<{
+     summary: String;
+     cancel: Struct<{
+        id: String;
+        label: String;
+        input: optional<$Record<String, Codec<Json, Json, never, never>>>;
+     }>;
+  }>>;
+}>;
+```
+
+Closed, bounded presentation data shared by every renderer.
+
+---
+
+### parseClientEntryV1
+
+```ts
+const parseClientEntryV1: (
+  input,
+  options?,
+) => Readonly<{
+  protocol: "shiitake.client/v1";
+  id: string & Brand<"ExtensionId">;
+  correlatedPrompts?: "note";
+  attach?: (context) => Effect<void, Error, Scope>;
+  contribute?: (slot) => object;
+}> = decodeEntry;
+```
+
+Admit exactly V1; installed executable code is not sandboxed.
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `input`    | `unknown`      |
+| `options?` | `ParseOptions` |
+
+#### Returns
+
+`Readonly`\<\{ `protocol`: `"shiitake.client/v1"`; `id`: `string` &
+`Brand`\<`"ExtensionId"`\>; `correlatedPrompts?`: `"note"`; `attach?`:
+(`context`) => `Effect`\<`void`, `Error`, `Scope`\>; `contribute?`: (`slot`) =>
+`object`; \}\>
+
+## Functions
+
+### defineClientEntry()
+
+```ts
+function defineClientEntry<C, P, PI>(contract, client): ClientEntryV1;
+```
+
+One typed author seam, usable with ordinary async attachment code.
+
+#### Type Parameters
+
+| Type Parameter                                                                                                                                                          |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `C` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<\{ `scope`: `"session"` \| `"agent"`; `input`: `Codec`\<`unknown`\>; `output`: `Codec`\<`unknown`\>; \}\>\>\> |
+| `P`                                                                                                                                                                     |
+| `PI`                                                                                                                                                                    |
+
+#### Parameters
+
+| Parameter  | Type                                                                                                                                                                                                                                                                                               |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contract` | [`ExtensionContractV0`](extensions.md#extensioncontractv0)\<`C`, `P`, `PI`\>                                                                                                                                                                                                                       |
+| `client`   | `Readonly`\<\{ `correlatedPrompts?`: [`ClientEntryV1`](#cliententryv1)\[`"correlatedPrompts"`\]; `attach?`: (`context`) => \| `void` \| `Promise`\<`void`\> \| `Effect.Effect`\<`void`, `Error`, `Scope.Scope`\>; `contribute?`: (`view`) => [`ClientContributionV1`](#clientcontributionv1); \}\> |
+
+#### Returns
+
+[`ClientEntryV1`](#cliententryv1)
+
+---
+
+### viewExtension()
+
+```ts
+function viewExtension<C, P, PI>(contract, slot): ExtensionViewV0<P>;
+```
+
+Decode one observed slot using its owning contract's projection.
+
+#### Type Parameters
+
+| Type Parameter                                                                                                                                                          |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `C` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<\{ `scope`: `"session"` \| `"agent"`; `input`: `Codec`\<`unknown`\>; `output`: `Codec`\<`unknown`\>; \}\>\>\> |
+| `P`                                                                                                                                                                     |
+| `PI`                                                                                                                                                                    |
+
+#### Parameters
+
+| Parameter  | Type                                                                         |
+| ---------- | ---------------------------------------------------------------------------- |
+| `contract` | [`ExtensionContractV0`](extensions.md#extensioncontractv0)\<`C`, `P`, `PI`\> |
+| `slot`     | [`ExtensionSlotV0`](extensions.md#extensionslotv0) \| `undefined`            |
+
+#### Returns
+
+[`ExtensionViewV0`](client.md#extensionviewv0)\<`P`\>