@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/hosted.md

@@ -0,0 +1,382 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / hosted
+
+# hosted
+
+## Type Aliases
+
+### HostedRun
+
+```ts
+type HostedRun = z.output<typeof hostedRunSchema>;
+```
+
+A parsed [hostedRunSchema](#hostedrunschema) value.
+
+---
+
+### HostedPromptInput
+
+```ts
+type HostedPromptInput = z.output<typeof hostedPromptInputSchema>;
+```
+
+A parsed [hostedPromptInputSchema](#hostedpromptinputschema) value.
+
+---
+
+### HostedPromptOutput
+
+```ts
+type HostedPromptOutput = z.output<typeof hostedPromptOutputSchema>;
+```
+
+A parsed [hostedPromptOutputSchema](#hostedpromptoutputschema) value.
+
+---
+
+### HostedModuleDescriptor
+
+```ts
+type HostedModuleDescriptor = z.output<typeof hostedModuleDescriptorSchema>;
+```
+
+A parsed [hostedModuleDescriptorSchema](#hostedmoduledescriptorschema) value.
+
+---
+
+### HostedToolsInput
+
+```ts
+type HostedToolsInput = z.output<typeof hostedToolsInputSchema>;
+```
+
+A parsed [hostedToolsInputSchema](#hostedtoolsinputschema) value.
+
+---
+
+### HostedToolsOutput
+
+```ts
+type HostedToolsOutput = z.output<typeof hostedToolsOutputSchema>;
+```
+
+A parsed [hostedToolsOutputSchema](#hostedtoolsoutputschema) value.
+
+---
+
+### HostedCallInput
+
+```ts
+type HostedCallInput = z.output<typeof hostedCallInputSchema>;
+```
+
+A parsed [hostedCallInputSchema](#hostedcallinputschema) value.
+
+---
+
+### HostedCallOutput
+
+```ts
+type HostedCallOutput = z.output<typeof hostedCallOutputSchema>;
+```
+
+A parsed [hostedCallOutputSchema](#hostedcalloutputschema) value.
+
+---
+
+### HostedAgentExtension
+
+```ts
+type HostedAgentExtension = Readonly<{
+  manifest: ExtensionManifestV0;
+  prompt: (input) => Promise<HostedPromptOutput>;
+  tools: (input) => Promise<HostedToolsOutput>;
+  call: (input) => Promise<HostedCallOutput>;
+}>;
+```
+
+The guest side of one hosted extension. Inputs are already parsed by the App
+method door with the schemas above; outputs are bounded here.
+
+## Variables
+
+### agentExtensionMethodNames
+
+```ts
+const agentExtensionMethodNames: Readonly<{
+  prompt: "agentExtensionPrompt";
+  tools: "agentExtensionTools";
+  call: "agentExtensionCall";
+}>;
+```
+
+App method names a hosted extension's backend serves.
+
+---
+
+### hostedExtensionCapabilities
+
+```ts
+const hostedExtensionCapabilities: readonly ExtensionCapabilityV0[];
+```
+
+Capabilities a hosted extension may request in this protocol version.
+
+---
+
+### hostedRunSchema
+
+```ts
+const hostedRunSchema: ZodObject<
+  {
+    sessionId: ZodString;
+    workId: ZodString;
+    origin: ZodNullable<
+      ZodObject<
+        {
+          extensionId: ZodString;
+          correlation: ZodNullable<ZodString>;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+The run a hosted call is made for; the host derives it, never the model.
+
+---
+
+### hostedPromptInputSchema
+
+```ts
+const hostedPromptInputSchema: ZodObject<
+  {
+    run: ZodObject<
+      {
+        sessionId: ZodString;
+        workId: ZodString;
+        origin: ZodNullable<
+          ZodObject<
+            {
+              extensionId: ZodString;
+              correlation: ZodNullable<ZodString>;
+            },
+            $strict
+          >
+        >;
+      },
+      $strict
+    >;
+  },
+  $strict
+>;
+```
+
+`agentExtensionPrompt` input: the run whose model request needs sections.
+
+---
+
+### hostedPromptOutputSchema
+
+```ts
+const hostedPromptOutputSchema: ZodObject<
+  {
+    sections: ZodArray<
+      ZodObject<
+        {
+          name: ZodString;
+          text: ZodString;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+`agentExtensionPrompt` output: at most 16 named sections of at most 8 KiB each.
+
+---
+
+### hostedModuleDescriptorSchema
+
+```ts
+const hostedModuleDescriptorSchema: ZodObject<
+  {
+    description: ZodOptional<ZodString>;
+    operations: ZodRecord<
+      ZodString,
+      ZodObject<
+        {
+          replay: ZodEnum<{
+            unsafe: "unsafe";
+            safe: "safe";
+          }>;
+          description: ZodOptional<ZodString>;
+          input: ZodJSONSchema;
+          output: ZodNullable<ZodJSONSchema>;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+A run's tool module as at most 64 dotted operations with bounded JSON Schemas.
+
+---
+
+### hostedToolsInputSchema
+
+```ts
+const hostedToolsInputSchema: ZodObject<
+  {
+    run: ZodObject<
+      {
+        sessionId: ZodString;
+        workId: ZodString;
+        origin: ZodNullable<
+          ZodObject<
+            {
+              extensionId: ZodString;
+              correlation: ZodNullable<ZodString>;
+            },
+            $strict
+          >
+        >;
+      },
+      $strict
+    >;
+  },
+  $strict
+> = hostedPromptInputSchema;
+```
+
+`agentExtensionTools` input: the run the tools are captured for.
+
+---
+
+### hostedToolsOutputSchema
+
+```ts
+const hostedToolsOutputSchema: ZodObject<
+  {
+    module: ZodNullable<
+      ZodObject<
+        {
+          description: ZodOptional<ZodString>;
+          operations: ZodRecord<
+            ZodString,
+            ZodObject<
+              {
+                replay: ZodEnum<{
+                  unsafe: "unsafe";
+                  safe: "safe";
+                }>;
+                description: ZodOptional<ZodString>;
+                input: ZodJSONSchema;
+                output: ZodNullable<ZodJSONSchema>;
+              },
+              $strict
+            >
+          >;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+`agentExtensionTools` output: the run's module, or null when it has none.
+
+---
+
+### hostedCallInputSchema
+
+```ts
+const hostedCallInputSchema: ZodObject<
+  {
+    run: ZodObject<
+      {
+        sessionId: ZodString;
+        workId: ZodString;
+        origin: ZodNullable<
+          ZodObject<
+            {
+              extensionId: ZodString;
+              correlation: ZodNullable<ZodString>;
+            },
+            $strict
+          >
+        >;
+      },
+      $strict
+    >;
+    operation: ZodString;
+    input: ZodJSONSchema;
+    invocation: ZodObject<
+      {
+        executionId: ZodString;
+        toolCallId: ZodOptional<ZodString>;
+        deadlineAt: ZodNullable<ZodNumber>;
+      },
+      $strict
+    >;
+  },
+  $strict
+>;
+```
+
+`agentExtensionCall` input: one operation, its input, and the host's call
+identity.
+
+---
+
+### hostedCallOutputSchema
+
+```ts
+const hostedCallOutputSchema: ZodObject<
+  {
+    value: ZodJSONSchema;
+  },
+  $strict
+>;
+```
+
+`agentExtensionCall` output: the operation's JSON result.
+
+## Functions
+
+### hostAgentExtension()
+
+```ts
+function hostAgentExtension(rostered): HostedAgentExtension;
+```
+
+Serve one extension's prompt sections and tools to a remote Agent. Throws when
+the extension requests a capability hosting does not provide yet, so a build
+fails instead of silently dropping it.
+
+#### Parameters
+
+| Parameter  | Type                                                       |
+| ---------- | ---------------------------------------------------------- |
+| `rostered` | [`RosteredExtensionV0`](extensions.md#rosteredextensionv0) |
+
+#### Returns
+
+[`HostedAgentExtension`](#hostedagentextension)

package/docs/api/http.md

@@ -0,0 +1,111 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / http
+
+# http
+
+## Type Aliases
+
+### ShiitakeHttpEnv
+
+```ts
+type ShiitakeHttpEnv = object;
+```
+
+Hono variables Shiitake's routes read. Only the host's own middleware sets
+`shiitakeMeta`; no request body can, because every body schema is closed.
+
+#### Properties
+
+##### Variables
+
+```ts
+Variables: object;
+```
+
+###### shiitakeMeta
+
+```ts
+shiitakeMeta: Json | undefined;
+```
+
+Opaque host metadata for prompts and operator lines on this request.
+
+---
+
+### ShiitakeSessionResolver
+
+```ts
+type ShiitakeSessionResolver = (
+  sessionId,
+  meta,
+) => Promise<ShiitakeSession> | ShiitakeSession;
+```
+
+Resolve one addressed Session for Shiitake's HTTP transport. `meta` is what the
+host's middleware attached to this request; a host that attaches none may ignore
+it.
+
+#### Parameters
+
+| Parameter   | Type                                        |
+| ----------- | ------------------------------------------- |
+| `sessionId` | `string`                                    |
+| `meta`      | [`Json`](extensions.md#json) \| `undefined` |
+
+#### Returns
+
+\| `Promise`\<[`ShiitakeSession`](client.md#shiitakesession)\> \|
+[`ShiitakeSession`](client.md#shiitakesession)
+
+## Functions
+
+### createShiitakeHttpRoutes()
+
+```ts
+function createShiitakeHttpRoutes(
+  resolveSession,
+  listSessions,
+  createSession,
+  deleteSession,
+  resolveExtensions,
+): Hono<
+  ShiitakeHttpEnv,
+  object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object &
+    object,
+  "/",
+  "/sessions/:sessionId/events"
+>;
+```
+
+Build Shiitake's typed HTTP routes around an existing Session owner.
+
+#### Parameters
+
+| Parameter           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveSession`    | [`ShiitakeSessionResolver`](#shiitakesessionresolver)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `listSessions`      | (`after?`) => `Promise`\<`Readonly`\<\{ `sessions`: readonly [`SessionSummaryRow`](client.md#sessionsummaryrow)[]; `next`: `string` \| `undefined`; \}\>\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `createSession`     | (`requestId`) => `Promise`\<`string`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `deleteSession`     | (`sessionId`) => `Promise`\<`boolean`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `resolveExtensions` | () => \| `Readonly`\<\{ `list`: () => `Promise`\<readonly `Readonly`\<\{ `id`: `string`; `version`: `string`; `revision`: `string`; `status`: `"running"` \| `"stopped"`; `reason`: `string` \| `null`; `stoppedAt`: `number` \| `null`; \}\>[]\>; `resume`: (`extensionId`) => `Promise`\<`Readonly`\<\{ `id`: `string`; `version`: `string`; `revision`: `string`; `status`: `"running"` \| `"stopped"`; `reason`: `string` \| `null`; `stoppedAt`: `number` \| `null`; \}\>\>; `call`: (`extensionId`, `command`, `input`) => `Promise`\<[`Json`](extensions.md#json)\>; \}\> \| `Promise`\<`Readonly`\<\{ `list`: () => `Promise`\<readonly `Readonly`\<\{ `id`: `string`; `version`: `string`; `revision`: `string`; `status`: ... \| ...; `reason`: ... \| ...; `stoppedAt`: ... \| ...; \}\>[]\>; `resume`: (`extensionId`) => `Promise`\<`Readonly`\<\{ `id`: `string`; `version`: `string`; `revision`: `string`; `status`: `"running"` \| `"stopped"`; `reason`: `string` \| `null`; `stoppedAt`: `number` \| `null`; \}\>\>; `call`: (`extensionId`, `command`, `input`) => `Promise`\<[`Json`](extensions.md#json)\>; \}\>\> |
+
+#### Returns
+
+`Hono`\<[`ShiitakeHttpEnv`](#shiitakehttpenv), `object` & `object` & `object` &
+`object` & `object` & `object` & `object` & `object` & `object` & `object` &
+`object` & `object`, `"/"`, `"/sessions/:sessionId/events"`\>