@fungi.computer/shiitake-extensions 0.0.2 → 0.1.1

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.

package/docs/api/roster/conversation-agents.md

@@ -0,0 +1,80 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / roster/conversation-agents
+
+# roster/conversation-agents
+
+## Functions
+
+### assertOrdinaryAgentCreation()
+
+```ts
+function assertOrdinaryAgentCreation(input): void;
+```
+
+Host-pack creation admission; attachments/model selection retain their own
+owners.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                    |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`   | `Readonly`\<\{ `requestId`: `string`; `name?`: `string`; `model?`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`; \}; `extensions?`: readonly `string`[]; \}\> |
+
+#### Returns
+
+`void`
+
+---
+
+### createConversationAgents()
+
+```ts
+function createConversationAgents(storage): object;
+```
+
+This host's own record of the Agents each conversation created or sent accepted
+work to, written as its Agent-control directory accepts them (Wiki:
+agent-runtime-tools-and-clients, read-only sub-agent view). It feeds the footer
+only; it owns no relationship and grants nothing.
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `storage` | `WatchdogSqliteOwner` |
+
+#### Returns
+
+| Name          | Type                                                                     | Description                                                                                                                                     |
+| ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recording()` | (`parentSessionId`, `directory`) => `AgentControlDirectory`              | Bind acceptance recording to this conversation's existing directory. One conversation's directory: its accepted creates and sends are recorded. |
+| `control()`   | (`directoryFor`) => `CapabilitySource`                                   | Agent-control tools bound to the conversation that acquires them.                                                                               |
+| `source()`    | (`directory`) => [`SubagentSource`](../subagents/host.md#subagentsource) | The footer rows for one conversation; archived and unknown Agents leave it.                                                                     |
+
+---
+
+### oysterAgentExtensions()
+
+```ts
+function oysterAgentExtensions(source): object;
+```
+
+Both hosts compose the ordinary roster and its read-only created-Agent footer.
+
+#### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `source`  | [`SubagentSource`](../subagents/host.md#subagentsource) |
+
+#### Returns
+
+| Name     | Type                                                                                                                                          | Description                                                  |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `roster` | `RosteredExtensionV0`[]                                                                                                                       | Ordinary extensions plus the read-only created-Agent footer. |
+| `grants` | `Readonly`\<\{ `id`: `string` & `Brand`\<`"ExtensionId"`\>; `capabilities`: readonly `ExtensionCapabilityV0`[]; `grantKey?`: `string`; \}\>[] | Host grants corresponding to the composed extension roster.  |

package/docs/api/roster.md

@@ -0,0 +1,40 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](README.md) / roster
+
+# roster
+
+## Variables
+
+### botanicalAgentExtensions
+
+```ts
+const botanicalAgentExtensions: ExtensionRosterV0;
+```
+
+Botanical's product roster with explicit grants. Hub and Local pass this same
+value; a stranger host passes its own (or an empty) roster.
+
+## Functions
+
+### botanicalExtensionsWithSkills()
+
+```ts
+function botanicalExtensionsWithSkills(source): ExtensionRosterV0;
+```
+
+A host with a SkillSource grants read-only skill discovery for its own runs.
+
+#### Parameters
+
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `source`  | [`SkillSource`](skills/source.md#skillsource) |
+
+#### Returns
+
+`ExtensionRosterV0`

package/docs/api/skills/host.md

@@ -0,0 +1,39 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / skills/host
+
+# skills/host
+
+## Variables
+
+### skillsGrant
+
+```ts
+const skillsGrant: ExtensionGrantV0;
+```
+
+Host admission for skill discovery prompts, load tools and human controls.
+
+## Functions
+
+### skillsExtension()
+
+```ts
+function skillsExtension(__namedParameters): RosteredExtensionV0;
+```
+
+Skills use only the generic prompt and run-tools doors; the host owns files.
+
+#### Parameters
+
+| Parameter           | Type                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `__namedParameters` | `Readonly`\<\{ `source`: [`SkillSource`](source.md#skillsource); \}\> |
+
+#### Returns
+
+`RosteredExtensionV0`

package/docs/api/skills/source.md

@@ -0,0 +1,104 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / skills/source
+
+# skills/source
+
+## Type Aliases
+
+### SkillOrigin
+
+```ts
+type SkillOrigin =
+  | Readonly<{
+      kind: "project" | "personal";
+    }>
+  | Readonly<{
+      kind: "extension";
+      extensionId: string;
+    }>;
+```
+
+Where a skill folder came from: the work itself, the person, or an installed
+extension.
+
+---
+
+### SkillDescription
+
+```ts
+type SkillDescription = Readonly<{
+  name: string;
+  description: string;
+  location: string;
+  origin: SkillOrigin;
+  displayLocation: string;
+}>;
+```
+
+Host-owned discovery metadata; bodies are loaded only through skill.load.
+
+---
+
+### SkillDiagnostic
+
+```ts
+type SkillDiagnostic = Readonly<{
+  path: string;
+  reason:
+    | "invalid"
+    | "collision"
+    | "unavailable"
+    | "bound"
+    | "warning"
+    | "skipped"
+    | "empty";
+  message: string;
+  cause: unknown;
+}>;
+```
+
+Safe discovery explanation, with the original cause kept separately for redacted
+logs.
+
+---
+
+### SkillCatalog
+
+```ts
+type SkillCatalog = Readonly<{
+  skills: readonly SkillDescription[];
+  diagnostics: readonly SkillDiagnostic[];
+}>;
+```
+
+Discovered skill descriptions and diagnostics from the same scan.
+
+---
+
+### SkillSource
+
+```ts
+type SkillSource = Readonly<{
+  catalog: (signal) => Promise<SkillCatalog>;
+  read: (
+    name,
+    file,
+    signal,
+  ) => Promise<
+    Readonly<{
+      name: string;
+      file: string;
+      content: string;
+      baseDirectory: string;
+      supportingFiles: readonly string[];
+    }>
+  >;
+}>;
+```
+
+Read-only host port. The host owns frontmatter, discovery and containment.

package/docs/api/subagents/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) / subagents/client
+
+# subagents/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;
+}>;
+```
+
+One footer row per sub-agent; opening a row shows its conversation beside this
+one.

package/docs/api/subagents/contract.md

@@ -0,0 +1,131 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / subagents/contract
+
+# subagents/contract
+
+## Type Aliases
+
+### SubagentState
+
+```ts
+type SubagentState = typeof SubagentState.Type;
+```
+
+Display state of one created Agent's conversation.
+
+---
+
+### Subagent
+
+```ts
+type Subagent = typeof Subagent.Type;
+```
+
+Decoded footer row for a created Agent.
+
+---
+
+### SubagentsProjection
+
+```ts
+type SubagentsProjection = typeof SubagentsProjection.Type;
+```
+
+Decoded list and expansion state projected into the footer.
+
+## Variables
+
+### maximumSubagents
+
+```ts
+const maximumSubagents: 16 = 16;
+```
+
+The most Agents one conversation's footer lists; the rest are counted.
+
+---
+
+### SubagentState
+
+```ts
+const SubagentState: Literals<
+  readonly ["working", "waiting", "idle", "failed", "unavailable"]
+>;
+```
+
+What the human sees for one ordinary created Agent. `waiting` is any open
+attention on its conversation (a question or a tool approval); `unavailable`
+means its status could not be read, and is never shown as idle.
+
+---
+
+### Subagent
+
+```ts
+const Subagent: Struct<{
+  agentId: String;
+  name: String;
+  sessionId: NullOr<String>;
+  state: Literals<
+    readonly ["working", "waiting", "idle", "failed", "unavailable"]
+  >;
+  attention: optionalKey<String>;
+}>;
+```
+
+A footer row for an ordinary Agent created by this Agent, never merely sent
+work.
+
+---
+
+### SubagentsProjection
+
+```ts
+const SubagentsProjection: Struct<{
+  agents: $Array<
+    Struct<{
+      agentId: String;
+      name: String;
+      sessionId: NullOr<String>;
+      state: Literals<
+        readonly ["working", "waiting", "idle", "failed", "unavailable"]
+      >;
+      attention: optionalKey<String>;
+    }>
+  >;
+  more: Int;
+  expanded: Boolean;
+}>;
+```
+
+This Agent's created Agents and how many are not listed. `expanded` is whether
+the footer lists each one; a person toggles it with `/agents`, and a collapsed
+footer keeps one summary row.
+
+---
+
+### subagentsContract
+
+```ts
+const subagentsContract: object;
+```
+
+Created-Agent footer control and its visible 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 footer controls.                                                 |
+| `commands.agents`                             | `object`                                                                                                                                                                                                                                                                                                                | -                     | Toggle the created-Agent footer between expanded and summarized views. |
+| `commands.agents.scope`                       | `"session"`                                                                                                                                                                                                                                                                                                             | `"session"`           | The Session owns its footer view.                                      |
+| `commands.agents.input`                       | `Struct`\<\{ \}\>                                                                                                                                                                                                                                                                                                       | -                     | No additional arguments are required.                                  |
+| `commands.agents.output`                      | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\>                                                                                                                                                                                                                                                             | `CatalogStep`         | Return the server-owned human control step.                            |
+| <a id="property-projection"></a> `projection` | `object`                                                                                                                                                                                                                                                                                                                | -                     | Footer rows and expansion state.                                       |
+| `projection.schema`                           | `Struct`\<\{ `agents`: `$Array`\<`Struct`\<\{ `agentId`: `String`; `name`: `String`; `sessionId`: `NullOr`\<`String`\>; `state`: `Literals`\<readonly \[`"working"`, `"waiting"`, `"idle"`, `"failed"`, `"unavailable"`\]\>; `attention`: `optionalKey`\<`String`\>; \}\>\>; `more`: `Int`; `expanded`: `Boolean`; \}\> | `SubagentsProjection` | Decoder for the projected footer.                                      |

package/docs/api/subagents/host.md

@@ -0,0 +1,115 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / subagents/host
+
+# subagents/host
+
+## Type Aliases
+
+### SubagentRecord
+
+```ts
+type SubagentRecord = Readonly<{
+  agentId: string;
+  name: string;
+  sessionId: string | null;
+}>;
+```
+
+A footer row for an ordinary Agent created by the current Agent.
+
+---
+
+### SubagentAgent
+
+```ts
+type SubagentAgent = Readonly<{
+  listSessions: ShiitakeAgent["listSessions"];
+  session: (sessionId) => Pick<ShiitakeSession, "read">;
+}>;
+```
+
+The two owner reads a status needs from one child Agent.
+
+---
+
+### SubagentSource
+
+```ts
+type SubagentSource = Readonly<{
+  read: (
+    sessionId,
+    limit,
+  ) => Promise<
+    Readonly<{
+      agents: readonly SubagentRecord[];
+      more: number;
+    }>
+  >;
+  open: (
+    agentId,
+    signal,
+  ) => Promise<
+    Readonly<{
+      agent: SubagentAgent;
+      release: () => Promise<void>;
+    }>
+  >;
+}>;
+```
+
+The host's read-only facts. `read` returns ordinary created Agents, at most
+`limit`, with a count of the rest; `open` is the host's existing per-operation
+Agent access (an `AgentControlDirectory`'s `open` fits), and releasing it never
+stops the Agent's work.
+
+---
+
+### SubagentTiming
+
+```ts
+type SubagentTiming = Readonly<{
+  refreshMs: number;
+  pollMs: number;
+  interestMs: number;
+}>;
+```
+
+Private resource ceilings; none of them is product policy.
+
+## Variables
+
+### subagentsGrant
+
+```ts
+const subagentsGrant: ExtensionGrantV0;
+```
+
+Host admission for the read-only created-Agent footer and human toggle.
+
+## Functions
+
+### subagentsExtension()
+
+```ts
+function subagentsExtension(options): RosteredExtensionV0;
+```
+
+The read-only footer: ordinary Agents created by this Agent, one row each, with
+their live status. It owns neither relationships nor durable state; the Agent
+directory owns immutable creation attribution. Its one command, `/agents`, only
+expands or collapses the footer rows.
+
+#### Parameters
+
+| Parameter | Type                                                                                                               |
+| --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `options` | `Readonly`\<\{ `source`: [`SubagentSource`](#subagentsource); `timing?`: [`SubagentTiming`](#subagenttiming); \}\> |
+
+#### Returns
+
+`RosteredExtensionV0`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/shiitake-extensions",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "author": "Levi <levi@technomancy.dev>",
   "private": false,
   "description": "Botanical's product Shiitake extensions: goal, loop and Almanac on the generic extension surface",
@@ -46,6 +46,10 @@
       "types": "./dist/roster.d.ts",
       "import": "./dist/roster.js"
     },
+    "./roster/conversation-agents": {
+      "types": "./dist/roster/conversation-agents.d.ts",
+      "import": "./dist/roster/conversation-agents.js"
+    },
     "./plan": {
       "types": "./dist/plan/contract.d.ts",
       "import": "./dist/plan/contract.js"
@@ -97,20 +101,22 @@
   },
   "files": [
     "dist",
+    "docs/api",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@fungi.computer/almanac": "0.1.0",
-    "@fungi.computer/cairn": "0.0.1",
-    "@fungi.computer/knapsack": "0.1.0",
-    "@fungi.computer/mycelium": "0.1.0",
-    "@fungi.computer/shiitake": "0.2.0",
-    "@fungi.computer/whistle": "0.0.2",
+    "@fungi.computer/almanac": "0.2.0",
+    "@fungi.computer/cairn": "0.1.0",
+    "@fungi.computer/knapsack": "0.2.1",
+    "@fungi.computer/mycelium": "0.2.1",
+    "@fungi.computer/shiitake": "0.3.1",
+    "@fungi.computer/watchdog": "0.1.0",
+    "@fungi.computer/whistle": "0.1.0",
     "effect": "4.0.2",
     "papaparse": "5.7.0",
     "zod": "4.4.3",
-    "@fungi.computer/gills": "0.1.0"
+    "@fungi.computer/gills": "0.2.0"
   },
   "license": "MIT",
   "repository": {