@fungi.computer/shiitake-extensions 0.0.1 → 0.1.0

package/dist/loop/contract.js

@@ -1,4 +1,3 @@
-import { historySchema } from "../internal/history.js";
 import { ExtensionId } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
 import { CatalogStep } from "../internal/catalog.js";
@@ -11,19 +10,26 @@ const Prompt = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.ch
 const RequestId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(200)));
 /** A named cron cadence evaluated in one IANA time zone. */
 export const LoopCron = Schema.Struct({
+    /** Cron expression for the fixed cadence. */
     expression: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256))),
+    /** IANA time zone in which the expression is evaluated. */
     timeZone: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128))),
 });
 /** One Session's loop as every client sees it. */
 export const Loop = Schema.Struct({
+    /** Identity of the loop whose occurrences are being tracked. */
     loopId: Schema.String,
+    /** Whether a person or the model started this loop. */
     origin: Schema.Literals(["human", "model"]),
+    /** Configured expiry timestamp, or null when absent. */
     expiresAt: Schema.NullOr(Schema.Int),
     /** Original instruction repeated for every occurrence. */
     prompt: Prompt,
+    /** Whether the model or a fixed cron cadence schedules occurrences. */
     mode: Schema.Literals(["self_paced", "fixed_interval"]),
     /** Cadence of a fixed-interval loop; null when the model paces it. */
     cron: Schema.NullOr(LoopCron),
+    /** Current loop lifecycle state. */
     state: Schema.Literals([
         "active",
         "paused",
@@ -41,9 +47,13 @@ export const Loop = Schema.Struct({
     lastError: Schema.NullOr(Schema.String),
 });
 const StartResult = Schema.Struct({
+    /** Newly started loop. */
     loop: Loop,
+    /** Admission receipt for the start command. */
     accepted: Schema.Struct({
+        /** Successful admission discriminator. */
         status: Schema.Literal("accepted"),
+        /** Identity of the accepted start command. */
         commandId: Schema.String,
     }),
 });
@@ -54,41 +64,99 @@ const StartResult = Schema.Struct({
  */
 export const LoopCommandInput = Schema.Union([
     Schema.Struct({
+        /** Select the loop-starting control. */
         action: Schema.Literal("start"),
+        /** Human prompt text, optionally prefixed with an interval. */
         text: Prompt,
+        /** Idempotency key for this start command. */
         requestId: RequestId,
     }),
     Schema.Struct({
+        /** Select an existing-loop control or open new-loop entry. */
         action: Schema.Literals(["status", "pause", "resume", "stop", "new"]),
     }),
     Schema.Struct({}),
 ]);
 /** Loop's contract: Session-scope controls and one projection slot. */
 export const LoopProjection = Schema.Struct({
-    loop: Schema.NullOr(Loop),
-    history: historySchema(Loop),
+    /** Loop currently visible to Session clients. */
+    loop: Loop,
 });
+/** Session-owned loop controls and their visible state. */
 export const loopContract = {
+    /** Stable extension identity. */
     id: ExtensionId.make("botanical-session-loop"),
+    /** Loop operations admitted by the Session owner. */
     commands: {
-        loop: { scope: "session", input: LoopCommandInput, output: CatalogStep },
+        /** Open or answer the human loop controls. */
+        loop: {
+            /** The Session owns this loop. */
+            scope: "session",
+            /** Decode the selected human action. */
+            input: LoopCommandInput,
+            /** Return the server-owned conversation step. */
+            output: CatalogStep,
+        },
+        /** Start a loop whose next occurrence is chosen by the model. */
         startSelfPaced: {
+            /** The Session owns this loop. */
             scope: "session",
-            input: Schema.Struct({ prompt: Prompt, requestId: RequestId }),
+            /** Decode the repeated prompt and command identity. */
+            input: Schema.Struct({
+                /** Instruction repeated on every occurrence. */
+                prompt: Prompt,
+                /** Idempotency key for the start command. */
+                requestId: RequestId,
+            }),
+            /** Return the loop and admission receipt. */
             output: StartResult,
         },
+        /** Start a loop with a fixed cron cadence. */
         startFixedInterval: {
+            /** The Session owns this loop. */
             scope: "session",
+            /** Decode the prompt, cadence and command identity. */
             input: Schema.Struct({
+                /** Instruction repeated on every occurrence. */
                 prompt: Prompt,
+                /** Idempotency key for the start command. */
                 requestId: RequestId,
                 ...LoopCron.fields,
             }),
+            /** Return the loop and admission receipt. */
             output: StartResult,
         },
-        pause: { scope: "session", input: Schema.Struct({}), output: Loop },
-        resume: { scope: "session", input: Schema.Struct({}), output: Loop },
-        stop: { scope: "session", input: Schema.Struct({}), output: Loop },
+        /** Suspend the current loop. */
+        pause: {
+            /** The Session owns this loop. */
+            scope: "session",
+            /** No additional arguments are required. */
+            input: Schema.Struct({}),
+            /** Return the paused loop. */
+            output: Loop,
+        },
+        /** Resume the current paused loop. */
+        resume: {
+            /** The Session owns this loop. */
+            scope: "session",
+            /** No additional arguments are required. */
+            input: Schema.Struct({}),
+            /** Return the resumed loop. */
+            output: Loop,
+        },
+        /** Stop future occurrences of the current loop. */
+        stop: {
+            /** The Session owns this loop. */
+            scope: "session",
+            /** No additional arguments are required. */
+            input: Schema.Struct({}),
+            /** Return the stopped loop. */
+            output: Loop,
+        },
+    },
+    /** Current loop visible to Session clients. */
+    projection: {
+        /** Decoder for projected loop state. */
+        schema: LoopProjection,
     },
-    projection: { schema: LoopProjection },
 };

package/dist/loop/host.d.ts

@@ -1,4 +1,5 @@
 import { type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
 /** The commands this extension advertises to every client. */
 export declare const loopCatalog: import("@fungi.computer/shiitake/extensions").Json;
+/** Durable Session loop implementation with prompts, controls and scheduled occurrences. */
 export declare const loopExtension: RosteredExtensionV0;

package/dist/loop/host.js

@@ -1,4 +1,3 @@
-import { appendHistory, emptyHistory, historySchema, } from "../internal/history.js";
 import { Mycelium } from "@fungi.computer/mycelium";
 import { defineCollection, defineExtension, ExtensionCommandError, ExtensionStop, } from "@fungi.computer/shiitake/extensions";
 import * as Cause from "effect/Cause";
@@ -12,14 +11,19 @@ import { z } from "zod";
 import { ask, catalog, done, freshRequestId } from "../internal/catalog.js";
 import { nextOccurrence } from "../internal/cron.js";
 import { Loop, LoopCommandInput, loopContract } from "./contract.js";
+/** The rules the model follows; the describe page and a live loop's prompt share them. */
+const rules = "You may start loops yourself; one live loop per Session. schedule_next is allowed only in the active self-paced loop's own run, clamped to 60–3600 seconds. Omitting it ends that loop. stop works in any Session run. Human pause/resume/stop and Esc remain user controls.";
 /** Hashed prose and policy: every constant loop reads comes from here. */
 const config = {
     minDelaySeconds: 60,
     maxDelaySeconds: 3_600,
     fixedLifetimeMs: 7 * 24 * 60 * 60 * 1_000,
     promptLimit: 1_024,
-    guide: "Session loop tools in execute: loop.get({}), loop.start({prompt,cadence}), loop.schedule_next({delaySeconds,reason}), loop.stop({reason}). You may start loops yourself; one live loop per Session. Find them with forage.search({query:'loop'}) or 'schedule' and forage.describe. schedule_next is allowed only in the active self-paced loop's own run, clamped to 60–3600 seconds. Omitting it ends that loop. stop works in any Session run. Human pause/resume/stop and Esc remain user controls.",
-    moduleDescription: "Session loop control and schedule tools. Start, get or stop a loop from any Session run; schedule_next requires the self-paced loop's current run.",
+    idle: "Recurring or scheduled work? forage.describe({path:'loop'}) first.",
+    guide: "Session loop tools: loop.get, loop.start, loop.schedule_next, loop.stop. " +
+        rules,
+    moduleDescription: "Session loop tools: get({}), start({prompt,cadence}), schedule_next({delaySeconds,reason}), stop({reason}). " +
+        rules,
     scheduleDescription: "Schedule the original loop prompt after this run settles successfully. delaySeconds is clamped between 60 and 3600. The reason is stored as why now and does not change the loop prompt. Do not call this when the loop should end.",
 };
 /** One Session's durable loop row. */
@@ -36,7 +40,6 @@ const LoopRow = Schema.Struct({
     })),
 });
 const collections = {
-    history: defineCollection(Schema.Struct({ sessionId: Schema.String, history: historySchema(Loop) }), { key: (row) => row.sessionId }),
     loops: defineCollection(LoopRow, {
         key: (loop) => loop.sessionId,
         index: (loop) => loop.state,
@@ -62,19 +65,6 @@ function projected(row) {
 }
 function commitLoop(ctx, row) {
     return Effect.gen(function* () {
-        const previous = Option.getOrUndefined(yield* ctx.state.loops.get(row.sessionId));
-        if (previous?.state !== row.state &&
-            (row.state === "active" ||
-                row.state === "finished" ||
-                row.state === "cancelled" ||
-                row.state === "failed")) {
-            const history = Option.getOrUndefined(yield* ctx.state.history.get(row.sessionId))
-                ?.history ?? emptyHistory();
-            yield* ctx.state.history.put({
-                sessionId: row.sessionId,
-                history: appendHistory(history, projected(row), row.commandId || null, yield* Clock.currentTimeMillis),
-            });
-        }
         yield* ctx.state.loops.put(row);
     });
 }
@@ -582,6 +572,7 @@ export const loopCatalog = catalog([
         },
     },
 ]);
+/** Durable Session loop implementation with prompts, controls and scheduled occurrences. */
 export const loopExtension = defineExtension({
     id: loopContract.id,
     version: "3.0.0",
@@ -592,13 +583,13 @@ export const loopExtension = defineExtension({
     prompt: (ctx, { sessionId }) => ctx.state.loops.get(sessionId).pipe(Effect.map((found) => [
         {
             name: "loop",
-            text: (ctx.config.guide +
-                "\n" +
-                (Option.isSome(found)
-                    ? loopLine(projected(found.value)) +
-                        "; nextDueAt=" +
-                        String(found.value.nextDueAt)
-                    : "No current loop.")).slice(0, ctx.config.promptLimit),
+            text: Option.isSome(found)
+                ? (ctx.config.guide +
+                    "\n" +
+                    loopLine(projected(found.value)) +
+                    "; nextDueAt=" +
+                    String(found.value.nextDueAt)).slice(0, ctx.config.promptLimit)
+                : ctx.config.idle,
         },
     ])),
     catalog: loopCatalog,
@@ -606,13 +597,9 @@ export const loopExtension = defineExtension({
         schema: loopContract.projection.schema,
         read: (ctx, sessionId) => {
             const loop = Option.getOrUndefined(ctx.state.loops.peek(sessionId));
-            const history = Option.getOrUndefined(ctx.state.history.peek(sessionId))?.history;
-            return loop === undefined && history === undefined
+            return loop === undefined
                 ? Option.none()
-                : Option.some({
-                    loop: loop === undefined ? null : projected(loop),
-                    history: history ?? emptyHistory(),
-                });
+                : Option.some({ loop: projected(loop) });
         },
     },
     hooks: {

package/dist/plan/client.d.ts

@@ -6,7 +6,7 @@ import { type ClientContributionV1 } from "@fungi.computer/shiitake/client-entry
 declare const _default: Readonly<{
     protocol: "shiitake.client/v1";
     id: import("@fungi.computer/shiitake/extensions").ExtensionId;
-    correlatedPrompts?: "note";
+    promptPresentation?: "footer";
     attach?: (context: import("@fungi.computer/shiitake/client-entry").ClientExtensionContextV1) => import("effect/Effect").Effect<void, Error, import("effect/Scope").Scope>;
     contribute?: (slot: import("@fungi.computer/shiitake").ExtensionSlotV0 | undefined) => ClientContributionV1;
 }>;

package/dist/plan/contract.d.ts

@@ -4,31 +4,47 @@ import * as Schema from "effect/Schema";
  * steps means no plan: replacing it with an empty checklist clears it.
  */
 export declare const Plan: Schema.Struct<{
+    /** Optional explanation for this checklist replacement. */
     readonly explanation: Schema.optionalKey<Schema.String>;
+    /** Ordered checklist; an empty array clears the plan. */
     readonly steps: Schema.$Array<Schema.Struct<{
+        /** Work described by this checklist step. */
         readonly step: Schema.String;
+        /** Current progress state of the step. */
         readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
     }>>;
 }>;
+/** Checklist replacement that permits at most one in-progress step. */
 export declare const PlanInput: Schema.Struct<{
+    /** Optional explanation for this checklist replacement. */
     readonly explanation: Schema.optionalKey<Schema.String>;
+    /** Ordered checklist; an empty array clears the plan. */
     readonly steps: Schema.$Array<Schema.Struct<{
+        /** Work described by this checklist step. */
         readonly step: Schema.String;
+        /** Current progress state of the step. */
         readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
     }>>;
 }>;
+/** One Session's ordered checklist and optional explanation. */
 export type Plan = Schema.Schema.Type<typeof Plan>;
 /** Open work remains: some step is not completed. Cleared and finished plans are closed. */
 export declare function planIsOpen(plan: Plan): boolean;
 /** The current checklist and every committed replacement, clears included. */
 export declare const PlanProjection: Schema.Struct<{
+    /** Latest checklist replacement. */
     readonly plan: Schema.Struct<{
+        /** Optional explanation for this checklist replacement. */
         readonly explanation: Schema.optionalKey<Schema.String>;
+        /** Ordered checklist; an empty array clears the plan. */
         readonly steps: Schema.$Array<Schema.Struct<{
+            /** Work described by this checklist step. */
             readonly step: Schema.String;
+            /** Current progress state of the step. */
             readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
         }>>;
     }>;
+    /** Committed replacements, including explicit clears. */
     readonly history: Schema.Struct<{
         readonly nextSequence: Schema.Int;
         readonly omitted: Schema.Int;
@@ -55,28 +71,45 @@ export declare const PlanProjection: Schema.Struct<{
 }>;
 /** Arguments of the human `/plan` command: a bare call views, `clear` empties it. */
 export declare const PlanCommandInput: Schema.Union<readonly [Schema.Struct<{
+    /** Clear the checklist instead of viewing it. */
     readonly action: Schema.Literal<"clear">;
 }>, Schema.Struct<{}>]>;
+/** Session-owned human plan control and checklist projection. */
 export declare const planContract: {
+    /** Stable extension identity. */
     id: string & import("effect/Brand").Brand<"ExtensionId">;
+    /** Human checklist controls. */
     commands: {
+        /** View or clear the current checklist. */
         plan: {
+            /** The Session owns the checklist. */
             scope: "session";
+            /** Decode the selected human control. */
             input: Schema.Union<readonly [Schema.Struct<{
+                /** Clear the checklist instead of viewing it. */
                 readonly action: Schema.Literal<"clear">;
             }>, Schema.Struct<{}>]>;
+            /** Return the server-owned conversation step. */
             output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
     };
+    /** Current checklist and its replacement history. */
     projection: {
+        /** Decoder for visible plan state. */
         schema: Schema.Struct<{
+            /** Latest checklist replacement. */
             readonly plan: Schema.Struct<{
+                /** Optional explanation for this checklist replacement. */
                 readonly explanation: Schema.optionalKey<Schema.String>;
+                /** Ordered checklist; an empty array clears the plan. */
                 readonly steps: Schema.$Array<Schema.Struct<{
+                    /** Work described by this checklist step. */
                     readonly step: Schema.String;
+                    /** Current progress state of the step. */
                     readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
                 }>>;
             }>;
+            /** Committed replacements, including explicit clears. */
             readonly history: Schema.Struct<{
                 readonly nextSequence: Schema.Int;
                 readonly omitted: Schema.Int;

package/dist/plan/contract.js

@@ -7,12 +7,17 @@ import { CatalogStep } from "../internal/catalog.js";
  * steps means no plan: replacing it with an empty checklist clears it.
  */
 export const Plan = Schema.Struct({
+    /** Optional explanation for this checklist replacement. */
     explanation: Schema.optionalKey(Schema.String.pipe(Schema.check(Schema.isMaxLength(2_000)))),
+    /** Ordered checklist; an empty array clears the plan. */
     steps: Schema.Array(Schema.Struct({
+        /** Work described by this checklist step. */
         step: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(500))),
+        /** Current progress state of the step. */
         status: Schema.Literals(["pending", "in_progress", "completed"]),
     })).pipe(Schema.check(Schema.isMaxLength(50))),
 });
+/** Checklist replacement that permits at most one in-progress step. */
 export const PlanInput = Plan.pipe(Schema.check(Schema.makeFilter((plan) => plan.steps.filter((step) => step.status === "in_progress").length <=
     1 || "At most one plan step may be in progress")));
 /** Open work remains: some step is not completed. Cleared and finished plans are closed. */
@@ -21,18 +26,38 @@ export function planIsOpen(plan) {
 }
 /** The current checklist and every committed replacement, clears included. */
 export const PlanProjection = Schema.Struct({
+    /** Latest checklist replacement. */
     plan: Plan,
+    /** Committed replacements, including explicit clears. */
     history: historySchema(Plan),
 });
 /** Arguments of the human `/plan` command: a bare call views, `clear` empties it. */
 export const PlanCommandInput = Schema.Union([
-    Schema.Struct({ action: Schema.Literal("clear") }),
+    Schema.Struct({
+        /** Clear the checklist instead of viewing it. */
+        action: Schema.Literal("clear"),
+    }),
     Schema.Struct({}),
 ]);
+/** Session-owned human plan control and checklist projection. */
 export const planContract = {
+    /** Stable extension identity. */
     id: ExtensionId.make("botanical-session-plan"),
+    /** Human checklist controls. */
     commands: {
-        plan: { scope: "session", input: PlanCommandInput, output: CatalogStep },
+        /** View or clear the current checklist. */
+        plan: {
+            /** The Session owns the checklist. */
+            scope: "session",
+            /** Decode the selected human control. */
+            input: PlanCommandInput,
+            /** Return the server-owned conversation step. */
+            output: CatalogStep,
+        },
+    },
+    /** Current checklist and its replacement history. */
+    projection: {
+        /** Decoder for visible plan state. */
+        schema: PlanProjection,
     },
-    projection: { schema: PlanProjection },
 };

package/dist/plan/host.js

@@ -8,9 +8,14 @@ import * as Schema from "effect/Schema";
 import { z } from "zod";
 import { catalog, done } from "../internal/catalog.js";
 import { Plan, PlanInput, planContract, planIsOpen } from "./contract.js";
+/** The rules the model follows; the describe page and an open plan's prompt share them. */
+const rules = "Use it for multi-step work, with at most one in-progress step; replace the whole plan on each update, and pass steps:[] to clear a plan that no longer applies. A completed checklist is not proof of goal completion.";
 const config = Object.freeze({
     promptLimit: 2_000,
-    guide: "Session checklist tool in execute: plan.update_plan({explanation?,steps:[{step,status:'pending'|'in_progress'|'completed'}]}). Find it with forage.search({query:'plan'}) and forage.describe. Use it for multi-step work, with at most one in-progress step; replace the whole plan on each update, and pass steps:[] to clear a plan that no longer applies. A completed checklist is not proof of goal completion.",
+    idle: "Multi-step work? forage.describe({path:'plan'}) first.",
+    moduleDescription: "Session checklist tool: update_plan({explanation?,steps:[{step,status:'pending'|'in_progress'|'completed'}]}). " +
+        rules,
+    guide: "Session checklist tool: plan.update_plan. " + rules,
 });
 const collections = {
     history: defineCollection(Schema.Struct({ sessionId: Schema.String, history: historySchema(Plan) }), { key: (row) => row.sessionId }),
@@ -93,17 +98,17 @@ export const planExtension = defineExtension({
     prompt: (ctx, { sessionId }) => ctx.state.plans.get(sessionId).pipe(Effect.map((found) => [
         {
             name: "plan",
-            text: (ctx.config.guide +
-                "\n" +
-                (Option.isSome(found) && found.value.plan.steps.length > 0
-                    ? JSON.stringify(found.value.plan)
-                    : "No current plan.")).slice(0, ctx.config.promptLimit),
+            text: Option.isSome(found) && found.value.plan.steps.length > 0
+                ? (ctx.config.guide +
+                    "\n" +
+                    JSON.stringify(found.value.plan)).slice(0, ctx.config.promptLimit)
+                : ctx.config.idle,
         },
     ])),
     tools: (ctx, { sessionId, workId }) => Effect.succeed(Option.some(Mycelium.module({
         id: "botanical.session-plan",
         name: "plan",
-        description: "Session checklist planning tools.",
+        description: ctx.config.moduleDescription,
         operations: {
             update_plan: Mycelium.operation({
                 replay: "safe",

package/dist/question/client.d.ts

@@ -3,7 +3,7 @@ import { type ClientContributionV1 } from "@fungi.computer/shiitake/client-entry
 declare const _default: Readonly<{
     protocol: "shiitake.client/v1";
     id: import("@fungi.computer/shiitake/extensions").ExtensionId;
-    correlatedPrompts?: "note";
+    promptPresentation?: "footer";
     attach?: (context: import("@fungi.computer/shiitake/client-entry").ClientExtensionContextV1) => import("effect/Effect").Effect<void, Error, import("effect/Scope").Scope>;
     contribute?: (slot: import("@fungi.computer/shiitake").ExtensionSlotV0 | undefined) => ClientContributionV1;
 }>;