@fungi.computer/shiitake-extensions 0.0.1 → 0.1.0

package/dist/subagents/contract.js

@@ -1,10 +1,11 @@
-import { ExtensionId } from "@fungi.computer/shiitake/extensions";
+import { ExtensionId, } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
+import { CatalogStep } from "../internal/catalog.js";
 const identity = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 /** The most Agents one conversation's footer lists; the rest are counted. */
 export const maximumSubagents = 16;
 /**
- * What the human sees for one sub-agent. `waiting` is any open attention on
+ * 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.
  */
@@ -15,24 +16,53 @@ export const SubagentState = Schema.Literals([
     "failed",
     "unavailable",
 ]);
-/** One Agent this conversation sent work to or created. */
+/** A footer row for an ordinary Agent created by this Agent, never merely sent work. */
 export const Subagent = Schema.Struct({
+    /** Identity of the created Agent. */
     agentId: identity,
+    /** Display name of the created Agent. */
     name: identity,
-    /** The conversation this one last addressed; null when never messaged. */
+    /** Its latest conversation; null when it has none. */
     sessionId: Schema.NullOr(identity),
+    /** Observed conversation state, including unreadable status. */
     state: SubagentState,
     /** The child's own summary of what waits on the human, when waiting. */
     attention: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(200))),
 });
-/** This conversation's sub-agents, newest first, and how many are not listed. */
+/**
+ * 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.
+ */
 export const SubagentsProjection = Schema.Struct({
+    /** Created Agents currently listed in the footer. */
     agents: Schema.Array(Subagent).check(Schema.isMaxLength(maximumSubagents)),
+    /** Additional created Agents not included in the visible rows. */
     more: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    /** Whether individual rows are expanded instead of summarized. */
+    expanded: Schema.Boolean,
 });
-/** A read-only view: no commands, one projection slot. */
+/** The human `/agents` command: a bare call expands or collapses the footer rows. */
+const commands = {
+    /** Toggle the created-Agent footer between expanded and summarized views. */
+    agents: {
+        /** The Session owns its footer view. */
+        scope: "session",
+        /** No additional arguments are required. */
+        input: Schema.Struct({}),
+        /** Return the server-owned human control step. */
+        output: CatalogStep,
+    },
+};
+/** Created-Agent footer control and its visible projection. */
 export const subagentsContract = {
+    /** Stable extension identity. */
     id: ExtensionId.make("botanical-session-subagents"),
-    commands: {},
-    projection: { schema: SubagentsProjection },
+    /** Human footer controls. */
+    commands,
+    /** Footer rows and expansion state. */
+    projection: {
+        /** Decoder for the projected footer. */
+        schema: SubagentsProjection,
+    },
 };

package/dist/subagents/host.d.ts

@@ -1,30 +1,40 @@
 import type { ShiitakeAgent, ShiitakeSession } from "@fungi.computer/shiitake";
 import { type ExtensionGrantV0, type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
-/** One Agent the host recorded this Session sending work to or creating. */
+/** A footer row for an ordinary Agent created by the current Agent. */
 export type SubagentRecord = Readonly<{
+    /** Identity of the ordinary created Agent. */
     agentId: string;
+    /** Display name supplied by the host. */
     name: string;
-    /** The conversation it last addressed; null when it was only created. */
+    /** A host-selected conversation; null asks the view to read its latest one. */
     sessionId: string | null;
 }>;
 /** The two owner reads a status needs from one child Agent. */
 export type SubagentAgent = Readonly<{
+    /** Read the child's owner-ordered conversation summaries. */
     listSessions: ShiitakeAgent["listSessions"];
+    /** Open the read-only view of a selected child conversation. */
     session: (sessionId: string) => Pick<ShiitakeSession, "read">;
 }>;
 /**
- * The host's read-only facts. `read` returns this Session's sub-agents,
- * newest first and at most `limit`, with a count of the rest; `open` is the
+ * 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.
  */
 export type SubagentSource = Readonly<{
+    /** Read a bounded list of this conversation's created Agents. */
     read: (sessionId: string, limit: number) => Promise<Readonly<{
+        /** Created Agents included in this page. */
         agents: readonly SubagentRecord[];
+        /** Additional created Agents not included in this page. */
         more: number;
     }>>;
+    /** Acquire existing owner access for one child Agent. */
     open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
+        /** Read-only Agent access held by this acquisition. */
         agent: SubagentAgent;
+        /** Release this acquisition without stopping the Agent's work. */
         release: () => Promise<void>;
     }>>;
 }>;
@@ -37,12 +47,14 @@ export type SubagentTiming = Readonly<{
     /** Polling stops once no watcher has read the Session this long. */
     interestMs: number;
 }>;
+/** Host admission for the read-only created-Agent footer and human toggle. */
 export declare const subagentsGrant: ExtensionGrantV0;
 /**
- * The read-only sub-agent view: the Agents this conversation sent work to or
- * created, one row each, with their live status. It owns no relationship,
- * no durable state and no command; the collaboration App remains the only
- * relationship owner.
+ * 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.
  */
 export declare function subagentsExtension(options: Readonly<{
     source: SubagentSource;

package/dist/subagents/host.js

@@ -1,6 +1,7 @@
 import { defineExtension, } from "@fungi.computer/shiitake/extensions";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import { catalog, done } from "../internal/catalog.js";
 import { maximumSubagents, subagentsContract, } from "./contract.js";
 const defaultTiming = Object.freeze({
     refreshMs: 1_000,
@@ -11,9 +12,10 @@ const defaultTiming = Object.freeze({
 const cachedSessions = 64;
 /** Owner pages scanned for one child's row: 400 conversations. */
 const statusPages = 2;
+/** Host admission for the read-only created-Agent footer and human toggle. */
 export const subagentsGrant = {
     id: subagentsContract.id,
-    capabilities: ["projection"],
+    capabilities: ["projection", "commands"],
 };
 const settledState = {
     running: "working",
@@ -46,20 +48,23 @@ async function status(source, record, signal) {
     try {
         const opened = await source.open(record.agentId, signal);
         try {
-            if (record.sessionId === null)
+            const row = record.sessionId === null
+                ? (await opened.agent.listSessions()).sessions[0]
+                : await findSession(opened.agent, record.sessionId);
+            if (row === undefined && record.sessionId === null)
                 return { ...base, state: "idle" };
-            const row = await findSession(opened.agent, record.sessionId);
             if (row === undefined || row.state === "unavailable")
                 return { ...base, state: "unavailable" };
+            const selected = { ...base, sessionId: row.sessionId };
             if (row.state !== "needs_you")
-                return { ...base, state: settledState[row.state] };
+                return { ...selected, state: settledState[row.state] };
             const snapshot = await opened.agent
-                .session(record.sessionId)
+                .session(row.sessionId)
                 .read({ limit: 1 });
             const attention = snapshot.attention[0]?.summary;
             return attention === undefined
-                ? { ...base, state: "waiting" }
-                : { ...base, state: "waiting", attention };
+                ? { ...selected, state: "waiting" }
+                : { ...selected, state: "waiting", attention };
         }
         finally {
             await opened.release();
@@ -117,12 +122,21 @@ function createRoster(source, timing, publish) {
             }, timing.pollMs);
     }
     return {
+        /** Flip whether the footer lists the rows; undefined while there is nothing to list. */
+        toggle(sessionId) {
+            const entry = entries.get(sessionId);
+            if (entry?.value === undefined || entry.value.agents.length === 0)
+                return undefined;
+            entry.expanded = !entry.expanded;
+            return entry.expanded;
+        },
         read(sessionId) {
             const now = Date.now();
             let entry = entries.get(sessionId);
             if (entry === undefined) {
                 entry = {
                     value: undefined,
+                    expanded: false,
                     refreshedAt: Number.NEGATIVE_INFINITY,
                     readAt: now,
                     refreshing: false,
@@ -138,7 +152,9 @@ function createRoster(source, timing, publish) {
             entry.readAt = now;
             if (!entry.refreshing && now - entry.refreshedAt >= timing.refreshMs)
                 void refresh(sessionId, entry);
-            return entry.value;
+            return entry.value === undefined
+                ? undefined
+                : { ...entry.value, expanded: entry.expanded };
         },
         close() {
             lifetime.abort();
@@ -148,10 +164,11 @@ function createRoster(source, timing, publish) {
     };
 }
 /**
- * The read-only sub-agent view: the Agents this conversation sent work to or
- * created, one row each, with their live status. It owns no relationship,
- * no durable state and no command; the collaboration App remains the only
- * relationship owner.
+ * 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.
  */
 export function subagentsExtension(options) {
     const rosters = new WeakMap();
@@ -168,9 +185,38 @@ export function subagentsExtension(options) {
                 rosters.delete(ctx);
             })).pipe(Effect.asVoid),
         },
+        catalog: catalog([
+            {
+                id: "agents",
+                title: "Agents",
+                category: "Conversation",
+                description: "Show or hide this conversation's sub-agents",
+                projections: {
+                    help: { order: 6 },
+                    palette: { order: 6 },
+                    slash: { aliases: ["agents"], order: 6 },
+                },
+            },
+        ]),
         projection: {
             schema: subagentsContract.projection.schema,
             read: (ctx, sessionId) => Option.fromUndefinedOr(rosters.get(ctx)?.read(sessionId)),
         },
+        commands: {
+            specs: subagentsContract.commands,
+            handlers: (ctx) => ({
+                agents: ({ sessionId }) => Effect.gen(function* () {
+                    const expanded = rosters.get(ctx)?.toggle(sessionId);
+                    if (expanded === undefined)
+                        return done({
+                            type: "info",
+                            message: "This conversation has no sub-agents.",
+                        });
+                    yield* ctx.observe(sessionId);
+                    // The changed rows already show the result; don't echo the toggle.
+                    return { type: "done" };
+                }),
+            }),
+        },
     });
 }

package/docs/api/README.md

@@ -0,0 +1,35 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/shiitake-extensions**
+
+---
+
+# @fungi.computer/shiitake-extensions
+
+## Modules
+
+| Module                                                      | Description |
+| ----------------------------------------------------------- | ----------- |
+| [almanac/contract](almanac/contract.md)                     | -           |
+| [almanac/host](almanac/host.md)                             | -           |
+| [goal/client](goal/client.md)                               | -           |
+| [goal/contract](goal/contract.md)                           | -           |
+| [goal/host](goal/host.md)                                   | -           |
+| [home/contract](home/contract.md)                           | -           |
+| [home/host](home/host.md)                                   | -           |
+| [loop/client](loop/client.md)                               | -           |
+| [loop/contract](loop/contract.md)                           | -           |
+| [loop/host](loop/host.md)                                   | -           |
+| [plan/client](plan/client.md)                               | -           |
+| [plan/contract](plan/contract.md)                           | -           |
+| [plan/host](plan/host.md)                                   | -           |
+| [question/client](question/client.md)                       | -           |
+| [question/contract](question/contract.md)                   | -           |
+| [question/host](question/host.md)                           | -           |
+| [roster](roster.md)                                         | -           |
+| [roster/conversation-agents](roster/conversation-agents.md) | -           |
+| [skills/host](skills/host.md)                               | -           |
+| [skills/source](skills/source.md)                           | -           |
+| [subagents/client](subagents/client.md)                     | -           |
+| [subagents/contract](subagents/contract.md)                 | -           |
+| [subagents/host](subagents/host.md)                         | -           |

package/docs/api/almanac/contract.md

@@ -0,0 +1,90 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](../README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](../README.md) / almanac/contract
+
+# almanac/contract
+
+## Type Aliases
+
+### Schedule
+
+```ts
+type Schedule = Schema.Schema.Type<typeof Schedule>;
+```
+
+One durable schedule.
+
+## Variables
+
+### Schedule
+
+```ts
+const Schedule: Struct<{
+  id: String;
+  sessionId: String;
+  prompt: String;
+  cron: NullOr<
+    Struct<{
+      expression: String;
+      timeZone: String;
+    }>
+  >;
+  nextDueAt: Int;
+  state: Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+  lastCommandId: NullOr<String>;
+  lastError: NullOr<String>;
+  attempt: Int;
+}>;
+```
+
+One durable schedule as every caller sees it.
+
+---
+
+### almanacContract
+
+```ts
+const almanacContract: object;
+```
+
+Almanac's contract: agent-scope schedule CRUD, no Session 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`                                                                                                                                                                                                                                                                                                                                                                               | -             | Agent-scoped schedule operations.                            |
+| `commands.createOneShot`                      | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Create a schedule with one due occurrence.                   |
+| `commands.createOneShot.scope`                | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | The Agent owns the schedule collection.                      |
+| `commands.createOneShot.input`                | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `dueAt`: `Int`; \}\>                                                                                                                                                                                                                                                                                    | -             | Decode the caller's one-shot schedule request.               |
+| `commands.createOneShot.output`               | `Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>             | `Schedule`    | Return the created durable schedule.                         |
+| `commands.createRecurring`                    | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Create a recurring cron schedule.                            |
+| `commands.createRecurring.scope`              | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | The Agent owns the schedule collection.                      |
+| `commands.createRecurring.input`              | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `expression`: `String`; `timeZone`: `String`; \}\>                                                                                                                                                                                                                                                      | -             | Decode the caller's recurring schedule request.              |
+| `commands.createRecurring.output`             | `Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>             | `Schedule`    | Return the created durable schedule.                         |
+| `commands.read`                               | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Read one schedule, or null when absent.                      |
+| `commands.read.scope`                         | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | Read from the Agent's schedule collection.                   |
+| `commands.read.input`                         | `Struct`\<\{ `scheduleId`: `String`; \}\>                                                                                                                                                                                                                                                                                                                                              | `ScheduleRef` | Identify the schedule to read.                               |
+| `commands.read.output`                        | `NullOr`\<`Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>\> | -             | Decode the schedule or its absence.                          |
+| `commands.list`                               | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Read a bounded page of schedules after an optional identity. |
+| `commands.list.scope`                         | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | Read from the Agent's schedule collection.                   |
+| `commands.list.input`                         | `Struct`\<\{ `after`: `optionalKey`\<`String`\>; `limit`: `optionalKey`\<`Int`\>; \}\>                                                                                                                                                                                                                                                                                                 | -             | Decode pagination arguments.                                 |
+| `commands.list.output`                        | `$Array`\<`Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>\> | -             | Decode the returned schedule rows.                           |
+| `commands.pause`                              | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Suspend future occurrences of a schedule.                    |
+| `commands.pause.scope`                        | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | The Agent owns the schedule.                                 |
+| `commands.pause.input`                        | `Struct`\<\{ `scheduleId`: `String`; \}\>                                                                                                                                                                                                                                                                                                                                              | `ScheduleRef` | Identify the schedule to pause.                              |
+| `commands.pause.output`                       | `Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>             | `Schedule`    | Return its updated state.                                    |
+| `commands.resume`                             | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Restore a paused schedule to active scheduling.              |
+| `commands.resume.scope`                       | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | The Agent owns the schedule.                                 |
+| `commands.resume.input`                       | `Struct`\<\{ `scheduleId`: `String`; \}\>                                                                                                                                                                                                                                                                                                                                              | `ScheduleRef` | Identify the schedule to resume.                             |
+| `commands.resume.output`                      | `Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>             | `Schedule`    | Return its updated state.                                    |
+| `commands.cancel`                             | `object`                                                                                                                                                                                                                                                                                                                                                                               | -             | Cancel future occurrences of a schedule.                     |
+| `commands.cancel.scope`                       | `"agent"`                                                                                                                                                                                                                                                                                                                                                                              | `"agent"`     | The Agent owns the schedule.                                 |
+| `commands.cancel.input`                       | `Struct`\<\{ `scheduleId`: `String`; \}\>                                                                                                                                                                                                                                                                                                                                              | `ScheduleRef` | Identify the schedule to cancel.                             |
+| `commands.cancel.output`                      | `Struct`\<\{ `id`: `String`; `sessionId`: `String`; `prompt`: `String`; `cron`: `NullOr`\<`Struct`\<\{ `expression`: `String`; `timeZone`: `String`; \}\>\>; `nextDueAt`: `Int`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`, `"cancelled"`, `"finished"`\]\>; `lastCommandId`: `NullOr`\<`String`\>; `lastError`: `NullOr`\<`String`\>; `attempt`: `Int`; \}\>             | `Schedule`    | Return its updated state.                                    |
+| <a id="property-projection"></a> `projection` | `null`                                                                                                                                                                                                                                                                                                                                                                                 | `null`        | Almanac has no Session projection.                           |

package/docs/api/almanac/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) / almanac/host
+
+# almanac/host
+
+## Variables
+
+### almanacExtension
+
+```ts
+const almanacExtension: RosteredExtensionV0;
+```
+
+Botanical's Almanac on Shiitake timers and the one admission door.

package/docs/api/goal/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) / goal/client
+
+# goal/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;
+}>;
+```
+
+Product copy and controls belong to Goal; every host renders plain rows. The
+footer shows only a live or paused goal; finished goals are chat lines.