@fungi.computer/shiitake-extensions 0.0.2 → 0.1.1

package/dist/loop/host.js

@@ -1,5 +1,4 @@
-import { appendHistory, emptyHistory, historySchema, } from "../internal/history.js";
-import { Mycelium } from "@fungi.computer/mycelium";
+import { CapabilityFailed, Mycelium, } from "@fungi.computer/mycelium";
 import { defineCollection, defineExtension, ExtensionCommandError, ExtensionStop, } from "@fungi.computer/shiitake/extensions";
 import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
@@ -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. Failed loop ticks retry with backoff; loop.get shows consecutiveFailures, lastError, and nextDueAt. 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. */
@@ -34,9 +38,9 @@ const LoopRow = Schema.Struct({
         delaySeconds: Schema.Number,
         reason: Schema.String,
     })),
+    consecutiveFailures: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)), Schema.withDecodingDefaultKey(Effect.succeed(0))),
 });
 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,
@@ -58,23 +62,11 @@ function projected(row) {
         reason: row.reason,
         nextDueAt: row.nextDueAt,
         lastError: row.lastError,
+        consecutiveFailures: row.consecutiveFailures,
     };
 }
 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);
     });
 }
@@ -137,6 +129,7 @@ function start(ctx, sessionId, input, cron, origin = "human") {
             lastError: null,
             startRequestId: input.requestId,
             requested: null,
+            consecutiveFailures: 0,
         };
         const stored = cron === null
             ? row
@@ -160,6 +153,8 @@ function requireLoop(ctx, sessionId) {
 }
 /** Where a resumed loop picks up: its cadence, or its recorded next instant. */
 function resumeAt(loop, now) {
+    if (loop.consecutiveFailures > 0)
+        return Effect.succeed(loop.nextDueAt === null ? null : Math.max(now, loop.nextDueAt));
     return loop.cron === null
         ? Effect.succeed(loop.nextDueAt)
         : nextOccurrence(loop.cron, now);
@@ -175,6 +170,27 @@ function settle(ctx, run) {
             return;
         if (run.workId !== loop.commandId)
             return;
+        if (run.outcome === "failed") {
+            const consecutiveFailures = Math.min(Number.MAX_SAFE_INTEGER, loop.consecutiveFailures + 1);
+            const backoffExponent = Math.min(consecutiveFailures - 1, 5);
+            const delayMs = Math.min(15 * 60_000, 30_000 * 2 ** backoffExponent);
+            const now = yield* Clock.currentTimeMillis;
+            const dueAt = now + delayMs;
+            const retry = {
+                ...loop,
+                state: loop.state,
+                requested: null,
+                reason: null,
+                nextDueAt: dueAt,
+                lastError: "Loop work ended with outcome failed.",
+                consecutiveFailures,
+            };
+            if (loop.state === "paused")
+                yield* commitLoop(ctx, retry);
+            else
+                yield* arm(ctx, retry, dueAt);
+            return yield* ctx.observe(loop.sessionId);
+        }
         if (run.outcome !== "completed" || run.terminal !== "completed") {
             yield* ctx.timers.cancel(loop.sessionId);
             yield* commitLoop(ctx, {
@@ -186,12 +202,22 @@ function settle(ctx, run) {
                 lastError: run.outcome === "completed"
                     ? "Completed loop work has no exact terminal."
                     : `Loop work ended with outcome ${run.outcome}.`,
+                consecutiveFailures: loop.consecutiveFailures,
             });
             return yield* ctx.observe(loop.sessionId);
         }
         // A fixed interval loop's cadence is armed independently of its runs.
-        if (loop.mode === "fixed_interval")
+        if (loop.mode === "fixed_interval") {
+            if (loop.consecutiveFailures !== 0 || loop.lastError !== null) {
+                yield* commitLoop(ctx, {
+                    ...loop,
+                    consecutiveFailures: 0,
+                    lastError: null,
+                });
+                yield* ctx.observe(loop.sessionId);
+            }
             return;
+        }
         // Omitting schedule_next during the run ends a self-paced loop.
         if (loop.requested?.workId !== run.workId) {
             yield* commitLoop(ctx, {
@@ -199,6 +225,8 @@ function settle(ctx, run) {
                 state: "finished",
                 reason: "no next wake requested",
                 nextDueAt: null,
+                lastError: null,
+                consecutiveFailures: 0,
             });
             return yield* ctx.observe(loop.sessionId);
         }
@@ -208,6 +236,8 @@ function settle(ctx, run) {
             reason: loop.requested.reason,
             requested: null,
             nextDueAt: now + loop.requested.delaySeconds * 1_000,
+            lastError: null,
+            consecutiveFailures: 0,
         };
         // A paused loop keeps the instant; resume arms it.
         if (loop.state === "paused")
@@ -283,17 +313,24 @@ function fire(ctx, sessionId, dueAt, now) {
         yield* ctx.observe(sessionId);
     });
 }
-/** Run one tool transaction and surface its failure to the model as an Error. */
-function toolCall(ctx, body) {
+/** Run one tool transaction and preserve its owner-admitted diagnostic. */
+function toolCall(ctx, operation, body) {
     return Effect.runPromiseExit(ctx.transact(body)).then((exit) => {
         if (Exit.isSuccess(exit))
             return exit.value;
         const failure = Cause.squash(exit.cause);
-        return Promise.reject(new Error(failure instanceof ExtensionStop
-            ? failure.reason
-            : failure instanceof Error
-                ? failure.message
-                : "Loop tool failed"));
+        return Promise.reject(new CapabilityFailed({
+            namespace: "loop",
+            operation,
+            cause: {
+                kind: "OperationFailed",
+                message: failure instanceof ExtensionStop
+                    ? failure.reason
+                    : failure instanceof Error
+                        ? failure.message
+                        : "Loop tool failed",
+            },
+        }));
     });
 }
 // Mycelium's maintained operation interface takes Zod for model-tool I/O.
@@ -315,6 +352,7 @@ const toolLoop = z.strictObject({
     reason: z.string().nullable(),
     nextDueAt: z.number().nullable(),
     lastError: z.string().nullable(),
+    consecutiveFailures: z.number().int().nonnegative(),
 });
 /** The self-paced `schedule_next` tool for exactly the loop's current run. */
 function loopModule(ctx, sessionId, workId) {
@@ -328,7 +366,7 @@ function loopModule(ctx, sessionId, workId) {
                 description: "Get the current Session loop and its next scheduled wake.",
                 input: z.strictObject({}),
                 output: toolLoop.nullable(),
-                execute: () => toolCall(ctx, ctx.state.loops
+                execute: () => toolCall(ctx, "get", ctx.state.loops
                     .get(sessionId)
                     .pipe(Effect.map((found) => Option.isSome(found) ? projected(found.value) : null))),
             }),
@@ -353,7 +391,7 @@ function loopModule(ctx, sessionId, workId) {
                     ]),
                 }),
                 output: toolLoop,
-                execute: ({ prompt, cadence }) => toolCall(ctx, Effect.gen(function* () {
+                execute: ({ prompt, cadence }) => toolCall(ctx, "start", Effect.gen(function* () {
                     const requestId = yield* freshRequestId;
                     const cron = cadence.kind === "self_paced"
                         ? null
@@ -372,7 +410,7 @@ function loopModule(ctx, sessionId, workId) {
                 description: "Stop this Session's loop from any run, with a visible reason. Cancel its next scheduled wake.",
                 input: z.strictObject({ reason: z.string().trim().min(1).max(1_000) }),
                 output: toolLoop,
-                execute: ({ reason }) => toolCall(ctx, stopLoop(ctx, sessionId, reason)),
+                execute: ({ reason }) => toolCall(ctx, "stop", stopLoop(ctx, sessionId, reason)),
             }),
             schedule_next: Mycelium.operation({
                 replay: "unsafe",
@@ -383,13 +421,16 @@ function loopModule(ctx, sessionId, workId) {
                     dueAt: z.number(),
                     reason: z.string().min(1).max(4_000),
                 }),
-                execute: ({ delaySeconds, reason }) => toolCall(ctx, Effect.gen(function* () {
+                execute: ({ delaySeconds, reason }) => toolCall(ctx, "schedule_next", Effect.gen(function* () {
                     const found = yield* ctx.state.loops.get(sessionId);
-                    if (Option.isNone(found) ||
-                        found.value.state !== "active" ||
+                    if (Option.isNone(found))
+                        return yield* Effect.fail(conflict("schedule_next only works inside this loop's own tick run"));
+                    if (found.value.state === "failed")
+                        return yield* Effect.fail(conflict("loop is failed; start a new one with loop.start"));
+                    if (found.value.state !== "active" ||
                         found.value.mode !== "self_paced" ||
                         found.value.commandId !== workId)
-                        return yield* Effect.fail(conflict("Loop work guard is stale"));
+                        return yield* Effect.fail(conflict("schedule_next only works inside this loop's own tick run"));
                     const clamped = Math.max(ctx.config.minDelaySeconds, Math.min(ctx.config.maxDelaySeconds, delaySeconds));
                     yield* commitLoop(ctx, {
                         ...found.value,
@@ -582,23 +623,27 @@ 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",
+    version: "4.0.0",
 })
     .config(config)
-    .state({ version: 3, migrations: {}, collections })
+    .state({
+    version: 3,
+    collections,
+})
     .define({
     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 +651,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;
 }>;