@fungi.computer/shiitake-extensions 0.0.2 → 0.1.0

package/docs/api/plan/client.md

@@ -0,0 +1,26 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / plan/client
+
+# plan/client
+
+## Variables
+
+### default
+
+```ts
+default: Readonly<{
+  protocol: "shiitake.client/v1";
+  id: string & Brand<"ExtensionId">;
+  promptPresentation?: "footer";
+  attach?: (context) => Effect<void, Error, Scope>;
+  contribute?: (slot) => object;
+}>;
+```
+
+Only an open plan occupies the footer, where it is inspectable and clearable; a
+finished or cleared plan hides while its committed history stays in state.

package/docs/api/plan/contract.md

@@ -0,0 +1,163 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / plan/contract
+
+# plan/contract
+
+## Type Aliases
+
+### Plan
+
+```ts
+type Plan = Schema.Schema.Type<typeof Plan>;
+```
+
+One Session's ordered checklist and optional explanation.
+
+## Variables
+
+### Plan
+
+```ts
+const Plan: Struct<{
+  explanation: optionalKey<String>;
+  steps: $Array<
+    Struct<{
+      step: String;
+      status: Literals<readonly ["pending", "in_progress", "completed"]>;
+    }>
+  >;
+}>;
+```
+
+One Session's replaceable checklist, independent of goals and loops. No steps
+means no plan: replacing it with an empty checklist clears it.
+
+---
+
+### PlanInput
+
+```ts
+const PlanInput: Struct<{
+  explanation: optionalKey<String>;
+  steps: $Array<
+    Struct<{
+      step: String;
+      status: Literals<readonly ["pending", "in_progress", "completed"]>;
+    }>
+  >;
+}>;
+```
+
+Checklist replacement that permits at most one in-progress step.
+
+---
+
+### PlanProjection
+
+```ts
+const PlanProjection: Struct<{
+  plan: Struct<{
+    explanation: optionalKey<String>;
+    steps: $Array<
+      Struct<{
+        step: String;
+        status: Literals<readonly ["pending", "in_progress", "completed"]>;
+      }>
+    >;
+  }>;
+  history: Struct<{
+    nextSequence: Int;
+    omitted: Int;
+    events: $Array<
+      Struct<{
+        id: String;
+        sequence: Int;
+        at: Int;
+        commandId: NullOr<String>;
+        event: Codec<
+          {
+            explanation?: string;
+            steps: readonly object[];
+          },
+          {
+            explanation?: string;
+            steps: readonly object[];
+          },
+          never,
+          never
+        >;
+      }>
+    >;
+  }>;
+}>;
+```
+
+The current checklist and every committed replacement, clears included.
+
+---
+
+### PlanCommandInput
+
+```ts
+const PlanCommandInput: Union<
+  readonly [
+    Struct<{
+      action: Literal<"clear">;
+    }>,
+    Struct<{}>,
+  ]
+>;
+```
+
+Arguments of the human `/plan` command: a bare call views, `clear` empties it.
+
+---
+
+### planContract
+
+```ts
+const planContract: object;
+```
+
+Session-owned human plan control and checklist projection.
+
+#### Type Declaration
+
+| Name                                          | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default value      | Description                                    |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------- |
+| <a id="property-id"></a> `id`                 | `string` & `Brand`\<`"ExtensionId"`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                  | Stable extension identity.                     |
+| <a id="property-commands"></a> `commands`     | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                  | Human checklist controls.                      |
+| `commands.plan`                               | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                  | View or clear the current checklist.           |
+| `commands.plan.scope`                         | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"session"`        | The Session owns the checklist.                |
+| `commands.plan.input`                         | `Union`\<readonly \[`Struct`\<\{ `action`: `Literal`\<`"clear"`\>; \}\>, `Struct`\<\{ \}\>\]\>                                                                                                                                                                                                                                                                                                                                                                                                                                    | `PlanCommandInput` | Decode the selected human control.             |
+| `commands.plan.output`                        | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `CatalogStep`      | Return the server-owned conversation step.     |
+| <a id="property-projection"></a> `projection` | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                  | Current checklist and its replacement history. |
+| `projection.schema`                           | `Struct`\<\{ `plan`: `Struct`\<\{ `explanation`: `optionalKey`\<`String`\>; `steps`: `$Array`\<`Struct`\<\{ `step`: `String`; `status`: `Literals`\<readonly \[..., ..., ...\]\>; \}\>\>; \}\>; `history`: `Struct`\<\{ `nextSequence`: `Int`; `omitted`: `Int`; `events`: `$Array`\<`Struct`\<\{ `id`: `String`; `sequence`: `Int`; `at`: `Int`; `commandId`: `NullOr`\<`String`\>; `event`: `Codec`\<\{ `explanation?`: ...; `steps`: ...; \}, \{ `explanation?`: ...; `steps`: ...; \}, `never`, `never`\>; \}\>\>; \}\>; \}\> | `PlanProjection`   | Decoder for visible plan state.                |
+
+## Functions
+
+### planIsOpen()
+
+```ts
+function planIsOpen(plan): boolean;
+```
+
+Open work remains: some step is not completed. Cleared and finished plans are
+closed.
+
+#### Parameters
+
+| Parameter           | Type                                                          | Description                                          |
+| ------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `plan`              | \{ `explanation?`: `string`; `steps`: readonly `object`[]; \} | -                                                    |
+| `plan.explanation?` | `string`                                                      | Optional explanation for this checklist replacement. |
+| `plan.steps`        | readonly `object`[]                                           | Ordered checklist; an empty array clears the plan.   |
+
+#### Returns
+
+`boolean`

package/docs/api/plan/host.md

@@ -0,0 +1,19 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / plan/host
+
+# plan/host
+
+## Variables
+
+### planExtension
+
+```ts
+const planExtension: RosteredExtensionV0;
+```
+
+Durable plan owner: replace, project and advertise through core's granted doors.

package/docs/api/question/client.md

@@ -0,0 +1,25 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / question/client
+
+# question/client
+
+## Variables
+
+### default
+
+```ts
+default: Readonly<{
+  protocol: "shiitake.client/v1";
+  id: string & Brand<"ExtensionId">;
+  promptPresentation?: "footer";
+  attach?: (context) => Effect<void, Error, Scope>;
+  contribute?: (slot) => object;
+}>;
+```
+
+Pending decisions use the existing footer rows and advertised answer flow.

package/docs/api/question/contract.md

@@ -0,0 +1,377 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / question/contract
+
+# question/contract
+
+## Type Aliases
+
+### Question
+
+```ts
+type Question = Schema.Schema.Type<typeof Question>;
+```
+
+One decoded decision question.
+
+---
+
+### OpenAsk
+
+```ts
+type OpenAsk = Schema.Schema.Type<typeof OpenAsk>;
+```
+
+One live or parked ask visible to Session clients.
+
+---
+
+### Answers
+
+```ts
+type Answers = Schema.Schema.Type<typeof Answers>;
+```
+
+Decoded answers indexed by question identity.
+
+---
+
+### AnswerInput
+
+```ts
+type AnswerInput = Schema.Schema.Type<typeof AnswerInput>;
+```
+
+Decoded human answer submission.
+
+---
+
+### DeclineInput
+
+```ts
+type DeclineInput = Schema.Schema.Type<typeof DeclineInput>;
+```
+
+Decoded human decline submission.
+
+---
+
+### HumanResult
+
+```ts
+type HumanResult = Schema.Schema.Type<typeof HumanResult>;
+```
+
+Decoded outcome of a human answer or decline.
+
+## Variables
+
+### Question
+
+```ts
+const Question: Struct<{
+  id: String;
+  header: String;
+  question: String;
+  options: $Array<
+    Struct<{
+      label: String;
+      description: String;
+    }>
+  >;
+  multiple: optionalKey<Boolean>;
+}>;
+```
+
+A decision question: first option is recommended, free text belongs to the host.
+
+---
+
+### Questions
+
+```ts
+const Questions: $Array<
+  Struct<{
+    id: String;
+    header: String;
+    question: String;
+    options: $Array<
+      Struct<{
+        label: String;
+        description: String;
+      }>
+    >;
+    multiple: optionalKey<Boolean>;
+  }>
+>;
+```
+
+Bounded question set with distinct question identities.
+
+---
+
+### OpenAsk
+
+```ts
+const OpenAsk: Struct<{
+  askId: String;
+  questions: $Array<
+    Struct<{
+      id: String;
+      header: String;
+      question: String;
+      options: $Array<
+        Struct<{
+          label: String;
+          description: String;
+        }>
+      >;
+      multiple: optionalKey<Boolean>;
+    }>
+  >;
+  status: Literals<readonly ["live", "parked"]>;
+  createdAt: Number;
+  expiresAt: NullOr<Number>;
+}>;
+```
+
+The complete question data shared by ordinary Session clients.
+
+---
+
+### AskProjection
+
+```ts
+const AskProjection: Struct<{
+  asks: $Array<Struct<{
+     askId: String;
+     questions: $Array<Struct<{
+        id: String;
+        header: String;
+        question: String;
+        options: $Array<Struct<{
+           label: ...;
+           description: ...;
+        }>>;
+        multiple: optionalKey<Boolean>;
+     }>>;
+     status: Literals<readonly ["live", "parked"]>;
+     createdAt: Number;
+     expiresAt: NullOr<Number>;
+  }>>;
+}>;
+```
+
+Bounded set of open asks projected into the Session.
+
+---
+
+### RequestId
+
+```ts
+const RequestId: String;
+```
+
+Stable identity for a human command and its retry.
+
+---
+
+### Answers
+
+```ts
+const Answers: $Record<
+  String,
+  Struct<{
+    selected: $Array<String>;
+    text: optionalKey<String>;
+  }>
+>;
+```
+
+Answers keyed by question id, with selected choices and optional free text.
+
+---
+
+### AnswerInput
+
+```ts
+const AnswerInput: Struct<{
+  askId: String;
+  requestId: String;
+  answers: $Record<
+    String,
+    Struct<{
+      selected: $Array<String>;
+      text: optionalKey<String>;
+    }>
+  >;
+}>;
+```
+
+Idempotent human submission of a complete answer set.
+
+---
+
+### DeclineInput
+
+```ts
+const DeclineInput: Struct<{
+  askId: String;
+  requestId: String;
+  note: optionalKey<String>;
+}>;
+```
+
+Idempotent human refusal to answer an ask.
+
+---
+
+### ClosedStatus
+
+```ts
+const ClosedStatus: Literals<
+  readonly [
+    "answered",
+    "declined",
+    "withdrawn",
+    "expired",
+    "cancelled",
+    "undeliverable",
+  ]
+>;
+```
+
+Terminal question outcomes, shared by human replies and model withdrawal.
+
+---
+
+### HumanResult
+
+```ts
+const HumanResult: Union<
+  readonly [
+    Struct<{
+      result: Literal<"accepted">;
+      via: Literals<readonly ["in_turn", "follow_up"]>;
+    }>,
+    Struct<{
+      result: Literal<"closed">;
+      status: Literals<
+        readonly [
+          "answered",
+          "declined",
+          "withdrawn",
+          "expired",
+          "cancelled",
+          "undeliverable",
+        ]
+      >;
+    }>,
+    Struct<{
+      result: Literal<"not_found">;
+    }>,
+  ]
+>;
+```
+
+Admission, already-closed state, or absence returned to a human reply.
+
+---
+
+### AnswerFlowInput
+
+```ts
+const AnswerFlowInput: Union<
+  readonly [
+    Struct<{
+      askId: String;
+      requestId: String;
+      index: Number;
+      answers: $Record<
+        String,
+        Struct<{
+          selected: $Array<String>;
+          text: optionalKey<String>;
+        }>
+      >;
+      stage: Literal<"multiple">;
+      selection: String;
+    }>,
+    Struct<{
+      askId: String;
+      requestId: String;
+      index: Number;
+      answers: $Record<
+        String,
+        Struct<{
+          selected: $Array<String>;
+          text: optionalKey<String>;
+        }>
+      >;
+      stage: Literal<"selection">;
+      selection: String;
+    }>,
+    Struct<{
+      askId: String;
+      requestId: String;
+      index: Number;
+      answers: $Record<
+        String,
+        Struct<{
+          selected: $Array<String>;
+          text: optionalKey<String>;
+        }>
+      >;
+      stage: Literal<"text">;
+      selected: $Array<String>;
+      text: String;
+    }>,
+    Struct<{
+      askId: String;
+    }>,
+    Struct<{}>,
+  ]
+>;
+```
+
+The ordinary /answer conversation carries its draft between typed steps.
+
+---
+
+### questionContract
+
+```ts
+const questionContract: object;
+```
+
+Human reads and the ordinary projection slot; model operations belong to the
+host.
+
+#### Type Declaration
+
+| Name                                          | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Default value     | Description                                            |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------ |
+| <a id="property-id"></a> `id`                 | `string` & `Brand`\<`"ExtensionId"`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                 | Stable extension identity.                             |
+| <a id="property-commands"></a> `commands`     | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Human question controls admitted by the Session owner. |
+| `commands.answerFlow`                         | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Advance the server-owned answer conversation.          |
+| `commands.answerFlow.scope`                   | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"session"`       | The Session owns its asks and replies.                 |
+| `commands.answerFlow.input`                   | `Union`\<readonly \[`Struct`\<\{ `askId`: `String`; `requestId`: `String`; `index`: `Number`; `answers`: `$Record`\<`String`, `Struct`\<\{ `selected`: `$Array`\<...\>; `text`: `optionalKey`\<...\>; \}\>\>; `stage`: `Literal`\<`"multiple"`\>; `selection`: `String`; \}\>, `Struct`\<\{ `askId`: `String`; `requestId`: `String`; `index`: `Number`; `answers`: `$Record`\<`String`, `Struct`\<\{ `selected`: `$Array`\<...\>; `text`: `optionalKey`\<...\>; \}\>\>; `stage`: `Literal`\<`"selection"`\>; `selection`: `String`; \}\>, `Struct`\<\{ `askId`: `String`; `requestId`: `String`; `index`: `Number`; `answers`: `$Record`\<`String`, `Struct`\<\{ `selected`: `$Array`\<...\>; `text`: `optionalKey`\<...\>; \}\>\>; `stage`: `Literal`\<`"text"`\>; `selected`: `$Array`\<`String`\>; `text`: `String`; \}\>, `Struct`\<\{ `askId`: `String`; \}\>, `Struct`\<\{ \}\>\]\> | `AnswerFlowInput` | Decode the current answer-draft step.                  |
+| `commands.answerFlow.output`                  | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `CatalogStep`     | Return the next human conversation step.               |
+| `commands.answer`                             | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Submit a person's completed answers.                   |
+| `commands.answer.scope`                       | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"session"`       | The Session owns this ask.                             |
+| `commands.answer.input`                       | `Struct`\<\{ `askId`: `String`; `requestId`: `String`; `answers`: `$Record`\<`String`, `Struct`\<\{ `selected`: `$Array`\<`String`\>; `text`: `optionalKey`\<`String`\>; \}\>\>; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `AnswerInput`     | Decode the answer submission.                          |
+| `commands.answer.output`                      | `Union`\<readonly \[`Struct`\<\{ `result`: `Literal`\<`"accepted"`\>; `via`: `Literals`\<readonly \[`"in_turn"`, `"follow_up"`\]\>; \}\>, `Struct`\<\{ `result`: `Literal`\<`"closed"`\>; `status`: `Literals`\<readonly \[`"answered"`, `"declined"`, `"withdrawn"`, `"expired"`, `"cancelled"`, `"undeliverable"`\]\>; \}\>, `Struct`\<\{ `result`: `Literal`\<`"not_found"`\>; \}\>\]\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `HumanResult`     | Return admission or the ask's terminal state.          |
+| `commands.decline`                            | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Decline an ask with an optional note.                  |
+| `commands.decline.scope`                      | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"session"`       | The Session owns this ask.                             |
+| `commands.decline.input`                      | `Struct`\<\{ `askId`: `String`; `requestId`: `String`; `note`: `optionalKey`\<`String`\>; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `DeclineInput`    | Decode the decline submission.                         |
+| `commands.decline.output`                     | `Union`\<readonly \[`Struct`\<\{ `result`: `Literal`\<`"accepted"`\>; `via`: `Literals`\<readonly \[`"in_turn"`, `"follow_up"`\]\>; \}\>, `Struct`\<\{ `result`: `Literal`\<`"closed"`\>; `status`: `Literals`\<readonly \[`"answered"`, `"declined"`, `"withdrawn"`, `"expired"`, `"cancelled"`, `"undeliverable"`\]\>; \}\>, `Struct`\<\{ `result`: `Literal`\<`"not_found"`\>; \}\>\]\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `HumanResult`     | Return admission or the ask's terminal state.          |
+| `commands.list`                               | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Read the Session's open asks.                          |
+| `commands.list.scope`                         | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"session"`       | The Session owns the ask collection.                   |
+| `commands.list.input`                         | `Struct`\<\{ \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                 | No additional arguments are required.                  |
+| `commands.list.output`                        | `Struct`\<\{ `asks`: `$Array`\<`Struct`\<\{ `askId`: `String`; `questions`: `$Array`\<`Struct`\<\{ `id`: ...; `header`: ...; `question`: ...; `options`: ...; `multiple`: ...; \}\>\>; `status`: `Literals`\<readonly \[`"live"`, `"parked"`\]\>; `createdAt`: `Number`; `expiresAt`: `NullOr`\<`Number`\>; \}\>\>; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `AskProjection`   | Decode the currently visible asks.                     |
+| <a id="property-projection"></a> `projection` | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                 | Open asks visible to Session clients.                  |
+| `projection.schema`                           | `Struct`\<\{ `asks`: `$Array`\<`Struct`\<\{ `askId`: `String`; `questions`: `$Array`\<`Struct`\<\{ `id`: `String`; `header`: `String`; `question`: `String`; `options`: `$Array`\<...\>; `multiple`: `optionalKey`\<...\>; \}\>\>; `status`: `Literals`\<readonly \[`"live"`, `"parked"`\]\>; `createdAt`: `Number`; `expiresAt`: `NullOr`\<`Number`\>; \}\>\>; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `AskProjection`   | Decoder for projected asks.                            |

package/docs/api/question/host.md

@@ -0,0 +1,19 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / question/host
+
+# question/host
+
+## Variables
+
+### questionExtension
+
+```ts
+const questionExtension: RosteredExtensionV0;
+```
+
+One durable question owner over the ordinary extension doors.