@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/backend-definition.md

@@ -0,0 +1,215 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / backend-definition
+
+# backend-definition
+
+## Type Aliases
+
+### AppSendBudgetRefusal
+
+```ts
+type AppSendBudgetRefusal = z.output<typeof appSendBudgetRefusalSchema>;
+```
+
+A declined Session send, with how long to wait before retrying.
+
+---
+
+### MethodPolicy
+
+```ts
+type MethodPolicy = Readonly<{
+  description: string;
+  effect: "read" | "write" | "external";
+  requires: readonly AppCapabilityId[];
+  hidden?: true;
+  anonymous?: true;
+  pending?: true;
+}>;
+```
+
+A method's schemas own both its TypeScript contract and JSON boundary.
+
+---
+
+### AppBackendMethod
+
+```ts
+type AppBackendMethod<Context> = Readonly<{
+  policy: MethodPolicy;
+  input: z.ZodType;
+  output: z.ZodType;
+  call: (input, context, caller) => Promise<WhistleJsonValue>;
+}>;
+```
+
+Prepared method export consumed by the backend and its build.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Context`      | `void`       |
+
+---
+
+### AppBackendClass
+
+```ts
+type AppBackendClass = (...args) => object & object;
+```
+
+Typed backend export shared by a build and its runtime method admission.
+
+#### Type Declaration
+
+| Name        | Type     |
+| ----------- | -------- |
+| `prototype` | `object` |
+
+---
+
+### AppBackendDefinition
+
+```ts
+type AppBackendDefinition<Context> = Readonly<{
+  methods: Readonly<Record<string, AppBackendMethod<Context>>>;
+  sync?: Readonly<{
+    method: string;
+  }>;
+  gills?: readonly AppBackendGill[];
+  gill: (input, context, caller) => Promise<GillReply>;
+  toolFamily?: AppApi["toolFamily"];
+  events?: Readonly<
+    Record<
+      string,
+      Readonly<{
+        description: string;
+        payload: z.ZodType;
+      }>
+    >
+  >;
+  implement: <C>(implementation) => C;
+  call: (method, input, context, caller) => Promise<WhistleJsonValue>;
+}>;
+```
+
+A backend's full generated API: its declared methods, the facet installer, and
+runtime dispatch by method name.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Context`      | `void`       |
+
+## Variables
+
+### appEventEmitResultSchema
+
+```ts
+const appEventEmitResultSchema: ZodUndefined;
+```
+
+EVENTS.emit acknowledges delivery with native void, not a JSON value.
+
+---
+
+### appSendBudgetRefusalSchema
+
+```ts
+const appSendBudgetRefusalSchema: ZodObject<
+  {
+    error: ZodLiteral<"send_budget_exceeded">;
+    retryAfterMs: ZodNumber;
+  },
+  $strict
+>;
+```
+
+App-originated Session send refusal; retry advice is a duration, not a
+timestamp.
+
+## Functions
+
+### defineAppMethod()
+
+```ts
+function defineAppMethod<I, O, Context>(method): AppBackendMethod<Context>;
+```
+
+Define a typed method once; neither discovery nor builds execute its handler.
+
+#### Type Parameters
+
+| Type Parameter                                                                               | Default type |
+| -------------------------------------------------------------------------------------------- | ------------ |
+| `I` _extends_ `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> | -            |
+| `O` _extends_ `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> | -            |
+| `Context`                                                                                    | `void`       |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `method`  | `Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `anonymous?`: `true`; `pending?`: `true`; \}\> & \{ input: I; output: O; \} & (\{ pending: true; handler: (input: output\<I\>, context: Context, caller: \{ computerId: string \| null; actor: \{ kind: "member"; memberId: string; \} \| \{ ...; \} \| \{ ...; \}; ... 5 more ...; idempotencyKey?: string \| undefined; \}) =\> Readonly\<...\> \| ... 1 more ... \| Promise\<...\>; \} \| \{ ...; \}) |
+
+#### Returns
+
+[`AppBackendMethod`](#appbackendmethod)\<`Context`\>
+
+---
+
+### defineAppBackend()
+
+```ts
+function defineAppBackend<Context>(options): AppBackendDefinition<Context>;
+```
+
+Generate the API from the method exports; callers cannot supply a second
+catalog.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Context`      | `void`       |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `methods`: `Readonly`\<`Record`\<`string`, [`AppBackendMethod`](#appbackendmethod)\<`Context`\>\>\>; `events?`: [`AppBackendDefinition`](#appbackenddefinition)\<`Context`\>\[`"events"`\]; `gills?`: readonly [`AppBackendGill`](gills.md#appbackendgill)[]; `sync?`: [`AppBackendDefinition`](#appbackenddefinition)\<`Context`\>\[`"sync"`\]; `toolFamily?`: [`AppBackendDefinition`](#appbackenddefinition)\<`Context`\>\[`"toolFamily"`\]; \}\> |
+
+#### Returns
+
+[`AppBackendDefinition`](#appbackenddefinition)\<`Context`\>
+
+## References
+
+### AppBackendGill
+
+Re-exports [AppBackendGill](gills.md#appbackendgill)
+
+---
+
+### pending
+
+Re-exports [pending](index.md#pending-1)
+
+---
+
+### pendingSchema
+
+Re-exports [pendingSchema](index.md#pendingschema)
+
+---
+
+### Pending
+
+Re-exports [Pending](index.md#pending)

package/docs/api/backend.md

@@ -0,0 +1,269 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / backend
+
+# backend
+
+## Classes
+
+### AppMethodRefusal
+
+An App method's declared domain refusal. A handler throws it to decline a call;
+the generated method boundary returns it as a typed
+[AppMethodReply](#appmethodreply) instead of an execution failure. Its message
+is caller-facing App copy, so it must not carry private data.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AppMethodRefusal(code, message): AppMethodRefusal;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                             |
+| --------- | -------------------------------------------------------------------------------- |
+| `code`    | `"unavailable"` \| `"invalid"` \| `"conflict"` \| `"forbidden"` \| `"not_found"` |
+| `message` | `string`                                                                         |
+
+###### Returns
+
+[`AppMethodRefusal`](#appmethodrefusal)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "unavailable" | "invalid" | "conflict" | "forbidden" | "not_found";
+```
+
+## Type Aliases
+
+### AppMethodRefusalCode
+
+```ts
+type AppMethodRefusalCode = (typeof appMethodRefusalCodes)[number];
+```
+
+One of [appMethodRefusalCodes](#appmethodrefusalcodes).
+
+---
+
+### AppMethodRefusedReply
+
+```ts
+type AppMethodRefusedReply = z.output<typeof appMethodRefusedReplySchema>;
+```
+
+A decoded [appMethodRefusedReplySchema](#appmethodrefusedreplyschema) value.
+
+---
+
+### AppMethodReply
+
+```ts
+type AppMethodReply =
+  | Readonly<{
+      kind: "ok";
+      value: WhistleJsonValue;
+    }>
+  | AppMethodRefusedReply;
+```
+
+A decoded [appMethodReplySchema](#appmethodreplyschema) value; the result is
+read-only JSON.
+
+## Variables
+
+### appBackendRefusalSchema
+
+```ts
+const appBackendRefusalSchema: ZodObject<
+  {
+    error: ZodLiteral<"App execution unavailable">;
+    reason: ZodEnum<{
+      exec_isolation_required: "exec_isolation_required";
+      execution_not_admitted: "execution_not_admitted";
+      artifact_unavailable: "artifact_unavailable";
+    }>;
+  },
+  $strict
+>;
+```
+
+Closed host refusal vocabulary. Private backend messages never reach callers.
+
+---
+
+### appBackend
+
+```ts
+const appBackend: CapabilityContract<{
+  request: Promise<WhistleJsonValue>;
+}>;
+```
+
+Invoke this App's admitted backend. The App defines its JSON request/result.
+
+---
+
+### appMethods
+
+```ts
+const appMethods: CapabilityContract<{
+  call: Promise<WhistleJsonValue>;
+}>;
+```
+
+Call one of this App's declared, typed methods through its host. Unlike
+`appBackend`, the host knows which method is called, so it can apply the
+method's declared effect (for example, allow only `read` methods to a visitor of
+a public App).
+
+---
+
+### appBackendActorHeader
+
+```ts
+const appBackendActorHeader: "X-Agar-Actor-Id" = "X-Agar-Actor-Id";
+```
+
+The admitting host overwrites this header from its authenticated principal. App
+request bodies and incoming browser headers never supply this identity.
+
+---
+
+### appBackendComputerHeader
+
+```ts
+const appBackendComputerHeader: "X-Agar-Computer-Id" = "X-Agar-Computer-Id";
+```
+
+The admitting host overwrites this header with the Computer it has verified the
+caller is admitted to use for this invocation, or omits it when no Computer is
+bound to the call. App request bodies and incoming browser headers never supply
+this identity: a backend that needs a Computer scope must read it from here,
+never from its own request body.
+
+---
+
+### appMethodRefusalCodes
+
+```ts
+const appMethodRefusalCodes: readonly [
+  "invalid",
+  "forbidden",
+  "not_found",
+  "conflict",
+  "unavailable",
+];
+```
+
+The closed vocabulary an App method may refuse with. Each code names one
+caller-visible outcome; the host owns how it is presented (see
+[appMethodRefusalStatus](#appmethodrefusalstatus)).
+
+---
+
+### appMethodRefusalStatus
+
+```ts
+const appMethodRefusalStatus: object;
+```
+
+HTTP status for each refusal code, shared by every host and App route.
+
+#### Type Declaration
+
+| Name                                            | Type  | Default value |
+| ----------------------------------------------- | ----- | ------------- |
+| <a id="property-invalid"></a> `invalid`         | `400` | `400`         |
+| <a id="property-forbidden"></a> `forbidden`     | `403` | `403`         |
+| <a id="property-not_found"></a> `not_found`     | `404` | `404`         |
+| <a id="property-conflict"></a> `conflict`       | `409` | `409`         |
+| <a id="property-unavailable"></a> `unavailable` | `503` | `503`         |
+
+---
+
+### maxAppMethodRefusalMessage
+
+```ts
+const maxAppMethodRefusalMessage: 500 = 500;
+```
+
+Bound on the App-authored refusal message that reaches callers.
+
+---
+
+### appMethodRefusedReplySchema
+
+```ts
+const appMethodRefusedReplySchema: ZodObject<
+  {
+    kind: ZodLiteral<"refused">;
+    code: ZodEnum<{
+      unavailable: "unavailable";
+      invalid: "invalid";
+      conflict: "conflict";
+      forbidden: "forbidden";
+      not_found: "not_found";
+    }>;
+    message: ZodString;
+  },
+  $strict
+>;
+```
+
+A refused call as it crosses the generated method boundary.
+
+---
+
+### appMethodReplySchema
+
+```ts
+const appMethodReplySchema: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        kind: ZodLiteral<"ok">;
+        value: ZodJSONSchema;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        kind: ZodLiteral<"refused">;
+        code: ZodEnum<{
+          unavailable: "unavailable";
+          invalid: "invalid";
+          conflict: "conflict";
+          forbidden: "forbidden";
+          not_found: "not_found";
+        }>;
+        message: ZodString;
+      },
+      $strict
+    >,
+  ],
+  "kind"
+>;
+```
+
+Every generated App method RPC answers with exactly one of these.

package/docs/api/errors.md

@@ -0,0 +1,169 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / errors
+
+# errors
+
+## Classes
+
+### AppError
+
+The SDK's one typed failure. Carries a closed `code` naming the failure kind and
+an explicit `retryable` verdict, instead of leaving callers to guess either from
+the message or exception shape.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AppError(message, options): AppError;
+```
+
+###### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `message` | `string`                              |
+| `options` | [`AppErrorOptions`](#apperroroptions) |
+
+###### Returns
+
+[`AppError`](#apperror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: AppErrorCode;
+```
+
+##### retryable
+
+```ts
+readonly retryable: boolean;
+```
+
+## Type Aliases
+
+### AppErrorCode
+
+```ts
+type AppErrorCode =
+  | "CANCELLED"
+  | "CAPABILITY_DENIED"
+  | "CAPABILITY_REVOKED"
+  | "COMMAND_NOT_DECLARED"
+  | "CONFLICT"
+  | "DISCONNECTED"
+  | "FILE_TOO_LARGE"
+  | "HOST_FAILURE"
+  | "IDENTITY"
+  | "INSUFFICIENT_CREDIT"
+  | "INVALID_ARGUMENT"
+  | "PROTOCOL"
+  | "SAFETY_FILTER_REFUSED"
+  | "SELECTION_CHANGED"
+  | "TIMEOUT";
+```
+
+The closed set of reasons an AppError can state; every SDK and host-reported
+failure is tagged with exactly one of these codes.
+
+---
+
+### AppErrorOptions
+
+```ts
+type AppErrorOptions = object;
+```
+
+Required construction options for an AppError.
+
+#### Properties
+
+##### cause?
+
+```ts
+readonly optional cause?: unknown;
+```
+
+##### code
+
+```ts
+readonly code: AppErrorCode;
+```
+
+##### retryable
+
+```ts
+readonly retryable: boolean;
+```
+
+Every error states retry truth explicitly; absence is not a verdict.
+
+---
+
+### ErrorCopy
+
+```ts
+type ErrorCopy = Readonly<{
+  title: string;
+  message: string;
+}>;
+```
+
+Trusted presentation copy; overrides never change recovery or retry policy.
+
+---
+
+### ErrorDescription
+
+```ts
+type ErrorDescription = ErrorCopy &
+  Readonly<{
+    retryable: boolean;
+    action?: "grant" | "retry" | "reconnect" | "billing";
+  }>;
+```
+
+Recovery hints are for the caller's UI, never an instruction to retry
+automatically.
+
+## Functions
+
+### describeAppError()
+
+```ts
+function describeAppError(cause, overrides?): ErrorDescription;
+```
+
+Describe an SDK-decoded failure without exposing exception or request data. The
+error owner retains retry truth. Grant and reconnect hints describe
+prerequisites, so they can accompany a non-retryable operation.
+
+#### Parameters
+
+| Parameter    | Type                                                                                                                  |
+| ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `cause`      | `unknown`                                                                                                             |
+| `overrides?` | `Partial`\<`Record`\<[`AppErrorCode`](#apperrorcode), `Readonly`\<\{ `title`: `string`; `message`: `string`; \}\>\>\> |
+
+#### Returns
+
+[`ErrorDescription`](#errordescription)