@fungi.computer/shiitake-extensions 0.0.2 → 0.1.1

package/dist/loop/contract.d.ts

@@ -1,22 +1,31 @@
 import * as Schema from "effect/Schema";
 /** A named cron cadence evaluated in one IANA time zone. */
 export declare const LoopCron: Schema.Struct<{
+    /** Cron expression for the fixed cadence. */
     readonly expression: Schema.String;
+    /** IANA time zone in which the expression is evaluated. */
     readonly timeZone: Schema.String;
 }>;
 /** One Session's loop as every client sees it. */
 export declare const Loop: Schema.Struct<{
+    /** Identity of the loop whose occurrences are being tracked. */
     readonly loopId: Schema.String;
+    /** Whether a person or the model started this loop. */
     readonly origin: Schema.Literals<readonly ["human", "model"]>;
+    /** Configured expiry timestamp, or null when absent. */
     readonly expiresAt: Schema.NullOr<Schema.Int>;
     /** Original instruction repeated for every occurrence. */
     readonly prompt: Schema.String;
+    /** Whether the model or a fixed cron cadence schedules occurrences. */
     readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
     /** Cadence of a fixed-interval loop; null when the model paces it. */
     readonly cron: Schema.NullOr<Schema.Struct<{
+        /** Cron expression for the fixed cadence. */
         readonly expression: Schema.String;
+        /** IANA time zone in which the expression is evaluated. */
         readonly timeZone: Schema.String;
     }>>;
+    /** Current loop lifecycle state. */
     readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
     /** Latest accepted command associated with this loop. */
     readonly commandId: Schema.String;
@@ -26,6 +35,8 @@ export declare const Loop: Schema.Struct<{
     readonly nextDueAt: Schema.NullOr<Schema.Int>;
     /** Visible explanation when loop work failed. */
     readonly lastError: Schema.NullOr<Schema.String>;
+    /** Consecutive failed work outcomes; successful work resets this to zero. */
+    readonly consecutiveFailures: Schema.Int;
 }>;
 /** One Session's loop. */
 export type Loop = Schema.Schema.Type<typeof Loop>;
@@ -35,26 +46,38 @@ export type Loop = Schema.Schema.Type<typeof Loop>;
  * interval. A bare call opens the controls.
  */
 export declare const LoopCommandInput: Schema.Union<readonly [Schema.Struct<{
+    /** Select the loop-starting control. */
     readonly action: Schema.Literal<"start">;
+    /** Human prompt text, optionally prefixed with an interval. */
     readonly text: Schema.String;
+    /** Idempotency key for this start command. */
     readonly requestId: Schema.String;
 }>, Schema.Struct<{
+    /** Select an existing-loop control or open new-loop entry. */
     readonly action: Schema.Literals<readonly ["status", "pause", "resume", "stop", "new"]>;
 }>, Schema.Struct<{}>]>;
 /** Loop's contract: Session-scope controls and one projection slot. */
 export declare const LoopProjection: Schema.Struct<{
-    readonly loop: Schema.NullOr<Schema.Struct<{
+    /** Loop currently visible to Session clients. */
+    readonly loop: Schema.Struct<{
+        /** Identity of the loop whose occurrences are being tracked. */
         readonly loopId: Schema.String;
+        /** Whether a person or the model started this loop. */
         readonly origin: Schema.Literals<readonly ["human", "model"]>;
+        /** Configured expiry timestamp, or null when absent. */
         readonly expiresAt: Schema.NullOr<Schema.Int>;
         /** Original instruction repeated for every occurrence. */
         readonly prompt: Schema.String;
+        /** Whether the model or a fixed cron cadence schedules occurrences. */
         readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
         /** Cadence of a fixed-interval loop; null when the model paces it. */
         readonly cron: Schema.NullOr<Schema.Struct<{
+            /** Cron expression for the fixed cadence. */
             readonly expression: Schema.String;
+            /** IANA time zone in which the expression is evaluated. */
             readonly timeZone: Schema.String;
         }>>;
+        /** Current loop lifecycle state. */
         readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
         /** Latest accepted command associated with this loop. */
         readonly commandId: Schema.String;
@@ -64,82 +87,68 @@ export declare const LoopProjection: Schema.Struct<{
         readonly nextDueAt: Schema.NullOr<Schema.Int>;
         /** Visible explanation when loop work failed. */
         readonly lastError: Schema.NullOr<Schema.String>;
-    }>>;
-    readonly history: Schema.Struct<{
-        readonly nextSequence: Schema.Int;
-        readonly omitted: Schema.Int;
-        readonly events: Schema.$Array<Schema.Struct<{
-            readonly id: Schema.String;
-            readonly sequence: Schema.Int;
-            readonly at: Schema.Int;
-            readonly commandId: Schema.NullOr<Schema.String>;
-            readonly event: Schema.Codec<{
-                readonly loopId: string;
-                readonly origin: "human" | "model";
-                readonly expiresAt: number | null;
-                readonly prompt: string;
-                readonly mode: "self_paced" | "fixed_interval";
-                readonly cron: {
-                    readonly expression: string;
-                    readonly timeZone: string;
-                } | null;
-                readonly state: "active" | "paused" | "cancelled" | "finished" | "failed";
-                readonly commandId: string;
-                readonly reason: string | null;
-                readonly nextDueAt: number | null;
-                readonly lastError: string | null;
-            }, {
-                readonly loopId: string;
-                readonly origin: "human" | "model";
-                readonly expiresAt: number | null;
-                readonly prompt: string;
-                readonly mode: "self_paced" | "fixed_interval";
-                readonly cron: {
-                    readonly expression: string;
-                    readonly timeZone: string;
-                } | null;
-                readonly state: "active" | "paused" | "cancelled" | "finished" | "failed";
-                readonly commandId: string;
-                readonly reason: string | null;
-                readonly nextDueAt: number | null;
-                readonly lastError: string | null;
-            }, never, never>;
-        }>>;
+        /** Consecutive failed work outcomes; successful work resets this to zero. */
+        readonly consecutiveFailures: Schema.Int;
     }>;
 }>;
+/** Session-owned loop controls and their visible state. */
 export declare const loopContract: {
+    /** Stable extension identity. */
     readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
+    /** Loop operations admitted by the Session owner. */
     readonly commands: {
+        /** Open or answer the human loop controls. */
         readonly loop: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** Decode the selected human action. */
             readonly input: Schema.Union<readonly [Schema.Struct<{
+                /** Select the loop-starting control. */
                 readonly action: Schema.Literal<"start">;
+                /** Human prompt text, optionally prefixed with an interval. */
                 readonly text: Schema.String;
+                /** Idempotency key for this start command. */
                 readonly requestId: Schema.String;
             }>, Schema.Struct<{
+                /** Select an existing-loop control or open new-loop entry. */
                 readonly action: Schema.Literals<readonly ["status", "pause", "resume", "stop", "new"]>;
             }>, Schema.Struct<{}>]>;
+            /** Return the server-owned conversation step. */
             readonly output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
+        /** Start a loop whose next occurrence is chosen by the model. */
         readonly startSelfPaced: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** Decode the repeated prompt and command identity. */
             readonly input: Schema.Struct<{
+                /** Instruction repeated on every occurrence. */
                 readonly prompt: Schema.String;
+                /** Idempotency key for the start command. */
                 readonly requestId: Schema.String;
             }>;
+            /** Return the loop and admission receipt. */
             readonly output: Schema.Struct<{
+                /** Newly started loop. */
                 readonly loop: Schema.Struct<{
+                    /** Identity of the loop whose occurrences are being tracked. */
                     readonly loopId: Schema.String;
+                    /** Whether a person or the model started this loop. */
                     readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                    /** Configured expiry timestamp, or null when absent. */
                     readonly expiresAt: Schema.NullOr<Schema.Int>;
                     /** Original instruction repeated for every occurrence. */
                     readonly prompt: Schema.String;
+                    /** Whether the model or a fixed cron cadence schedules occurrences. */
                     readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                     /** Cadence of a fixed-interval loop; null when the model paces it. */
                     readonly cron: Schema.NullOr<Schema.Struct<{
+                        /** Cron expression for the fixed cadence. */
                         readonly expression: Schema.String;
+                        /** IANA time zone in which the expression is evaluated. */
                         readonly timeZone: Schema.String;
                     }>>;
+                    /** Current loop lifecycle state. */
                     readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                     /** Latest accepted command associated with this loop. */
                     readonly commandId: Schema.String;
@@ -149,34 +158,55 @@ export declare const loopContract: {
                     readonly nextDueAt: Schema.NullOr<Schema.Int>;
                     /** Visible explanation when loop work failed. */
                     readonly lastError: Schema.NullOr<Schema.String>;
+                    /** Consecutive failed work outcomes; successful work resets this to zero. */
+                    readonly consecutiveFailures: Schema.Int;
                 }>;
+                /** Admission receipt for the start command. */
                 readonly accepted: Schema.Struct<{
+                    /** Successful admission discriminator. */
                     readonly status: Schema.Literal<"accepted">;
+                    /** Identity of the accepted start command. */
                     readonly commandId: Schema.String;
                 }>;
             }>;
         };
+        /** Start a loop with a fixed cron cadence. */
         readonly startFixedInterval: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** Decode the prompt, cadence and command identity. */
             readonly input: Schema.Struct<{
+                /** Cron expression for the fixed cadence. */
                 readonly expression: Schema.String;
+                /** IANA time zone in which the expression is evaluated. */
                 readonly timeZone: Schema.String;
+                /** Instruction repeated on every occurrence. */
                 readonly prompt: Schema.String;
+                /** Idempotency key for the start command. */
                 readonly requestId: Schema.String;
             }>;
+            /** Return the loop and admission receipt. */
             readonly output: Schema.Struct<{
+                /** Newly started loop. */
                 readonly loop: Schema.Struct<{
+                    /** Identity of the loop whose occurrences are being tracked. */
                     readonly loopId: Schema.String;
+                    /** Whether a person or the model started this loop. */
                     readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                    /** Configured expiry timestamp, or null when absent. */
                     readonly expiresAt: Schema.NullOr<Schema.Int>;
                     /** Original instruction repeated for every occurrence. */
                     readonly prompt: Schema.String;
+                    /** Whether the model or a fixed cron cadence schedules occurrences. */
                     readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                     /** Cadence of a fixed-interval loop; null when the model paces it. */
                     readonly cron: Schema.NullOr<Schema.Struct<{
+                        /** Cron expression for the fixed cadence. */
                         readonly expression: Schema.String;
+                        /** IANA time zone in which the expression is evaluated. */
                         readonly timeZone: Schema.String;
                     }>>;
+                    /** Current loop lifecycle state. */
                     readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                     /** Latest accepted command associated with this loop. */
                     readonly commandId: Schema.String;
@@ -186,28 +216,44 @@ export declare const loopContract: {
                     readonly nextDueAt: Schema.NullOr<Schema.Int>;
                     /** Visible explanation when loop work failed. */
                     readonly lastError: Schema.NullOr<Schema.String>;
+                    /** Consecutive failed work outcomes; successful work resets this to zero. */
+                    readonly consecutiveFailures: Schema.Int;
                 }>;
+                /** Admission receipt for the start command. */
                 readonly accepted: Schema.Struct<{
+                    /** Successful admission discriminator. */
                     readonly status: Schema.Literal<"accepted">;
+                    /** Identity of the accepted start command. */
                     readonly commandId: Schema.String;
                 }>;
             }>;
         };
+        /** Suspend the current loop. */
         readonly pause: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Return the paused loop. */
             readonly output: Schema.Struct<{
+                /** Identity of the loop whose occurrences are being tracked. */
                 readonly loopId: Schema.String;
+                /** Whether a person or the model started this loop. */
                 readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                /** Configured expiry timestamp, or null when absent. */
                 readonly expiresAt: Schema.NullOr<Schema.Int>;
                 /** Original instruction repeated for every occurrence. */
                 readonly prompt: Schema.String;
+                /** Whether the model or a fixed cron cadence schedules occurrences. */
                 readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                 /** Cadence of a fixed-interval loop; null when the model paces it. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
+                    /** Cron expression for the fixed cadence. */
                     readonly expression: Schema.String;
+                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
+                /** Current loop lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                 /** Latest accepted command associated with this loop. */
                 readonly commandId: Schema.String;
@@ -217,23 +263,36 @@ export declare const loopContract: {
                 readonly nextDueAt: Schema.NullOr<Schema.Int>;
                 /** Visible explanation when loop work failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
+                /** Consecutive failed work outcomes; successful work resets this to zero. */
+                readonly consecutiveFailures: Schema.Int;
             }>;
         };
+        /** Resume the current paused loop. */
         readonly resume: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Return the resumed loop. */
             readonly output: Schema.Struct<{
+                /** Identity of the loop whose occurrences are being tracked. */
                 readonly loopId: Schema.String;
+                /** Whether a person or the model started this loop. */
                 readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                /** Configured expiry timestamp, or null when absent. */
                 readonly expiresAt: Schema.NullOr<Schema.Int>;
                 /** Original instruction repeated for every occurrence. */
                 readonly prompt: Schema.String;
+                /** Whether the model or a fixed cron cadence schedules occurrences. */
                 readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                 /** Cadence of a fixed-interval loop; null when the model paces it. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
+                    /** Cron expression for the fixed cadence. */
                     readonly expression: Schema.String;
+                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
+                /** Current loop lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                 /** Latest accepted command associated with this loop. */
                 readonly commandId: Schema.String;
@@ -243,23 +302,36 @@ export declare const loopContract: {
                 readonly nextDueAt: Schema.NullOr<Schema.Int>;
                 /** Visible explanation when loop work failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
+                /** Consecutive failed work outcomes; successful work resets this to zero. */
+                readonly consecutiveFailures: Schema.Int;
             }>;
         };
+        /** Stop future occurrences of the current loop. */
         readonly stop: {
+            /** The Session owns this loop. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Return the stopped loop. */
             readonly output: Schema.Struct<{
+                /** Identity of the loop whose occurrences are being tracked. */
                 readonly loopId: Schema.String;
+                /** Whether a person or the model started this loop. */
                 readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                /** Configured expiry timestamp, or null when absent. */
                 readonly expiresAt: Schema.NullOr<Schema.Int>;
                 /** Original instruction repeated for every occurrence. */
                 readonly prompt: Schema.String;
+                /** Whether the model or a fixed cron cadence schedules occurrences. */
                 readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                 /** Cadence of a fixed-interval loop; null when the model paces it. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
+                    /** Cron expression for the fixed cadence. */
                     readonly expression: Schema.String;
+                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
+                /** Current loop lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                 /** Latest accepted command associated with this loop. */
                 readonly commandId: Schema.String;
@@ -269,23 +341,35 @@ export declare const loopContract: {
                 readonly nextDueAt: Schema.NullOr<Schema.Int>;
                 /** Visible explanation when loop work failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
+                /** Consecutive failed work outcomes; successful work resets this to zero. */
+                readonly consecutiveFailures: Schema.Int;
             }>;
         };
     };
+    /** Current loop visible to Session clients. */
     readonly projection: {
+        /** Decoder for projected loop state. */
         readonly schema: Schema.Struct<{
-            readonly loop: Schema.NullOr<Schema.Struct<{
+            /** Loop currently visible to Session clients. */
+            readonly loop: Schema.Struct<{
+                /** Identity of the loop whose occurrences are being tracked. */
                 readonly loopId: Schema.String;
+                /** Whether a person or the model started this loop. */
                 readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                /** Configured expiry timestamp, or null when absent. */
                 readonly expiresAt: Schema.NullOr<Schema.Int>;
                 /** Original instruction repeated for every occurrence. */
                 readonly prompt: Schema.String;
+                /** Whether the model or a fixed cron cadence schedules occurrences. */
                 readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
                 /** Cadence of a fixed-interval loop; null when the model paces it. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
+                    /** Cron expression for the fixed cadence. */
                     readonly expression: Schema.String;
+                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
+                /** Current loop lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
                 /** Latest accepted command associated with this loop. */
                 readonly commandId: Schema.String;
@@ -295,47 +379,8 @@ export declare const loopContract: {
                 readonly nextDueAt: Schema.NullOr<Schema.Int>;
                 /** Visible explanation when loop work failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-            }>>;
-            readonly history: Schema.Struct<{
-                readonly nextSequence: Schema.Int;
-                readonly omitted: Schema.Int;
-                readonly events: Schema.$Array<Schema.Struct<{
-                    readonly id: Schema.String;
-                    readonly sequence: Schema.Int;
-                    readonly at: Schema.Int;
-                    readonly commandId: Schema.NullOr<Schema.String>;
-                    readonly event: Schema.Codec<{
-                        readonly loopId: string;
-                        readonly origin: "human" | "model";
-                        readonly expiresAt: number | null;
-                        readonly prompt: string;
-                        readonly mode: "self_paced" | "fixed_interval";
-                        readonly cron: {
-                            readonly expression: string;
-                            readonly timeZone: string;
-                        } | null;
-                        readonly state: "active" | "paused" | "cancelled" | "finished" | "failed";
-                        readonly commandId: string;
-                        readonly reason: string | null;
-                        readonly nextDueAt: number | null;
-                        readonly lastError: string | null;
-                    }, {
-                        readonly loopId: string;
-                        readonly origin: "human" | "model";
-                        readonly expiresAt: number | null;
-                        readonly prompt: string;
-                        readonly mode: "self_paced" | "fixed_interval";
-                        readonly cron: {
-                            readonly expression: string;
-                            readonly timeZone: string;
-                        } | null;
-                        readonly state: "active" | "paused" | "cancelled" | "finished" | "failed";
-                        readonly commandId: string;
-                        readonly reason: string | null;
-                        readonly nextDueAt: number | null;
-                        readonly lastError: string | null;
-                    }, never, never>;
-                }>>;
+                /** Consecutive failed work outcomes; successful work resets this to zero. */
+                readonly consecutiveFailures: Schema.Int;
             }>;
         }>;
     };

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",
@@ -39,11 +45,17 @@ export const Loop = Schema.Struct({
     nextDueAt: Schema.NullOr(Schema.Int),
     /** Visible explanation when loop work failed. */
     lastError: Schema.NullOr(Schema.String),
+    /** Consecutive failed work outcomes; successful work resets this to zero. */
+    consecutiveFailures: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
 });
 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 +66,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;