@fungi.computer/shiitake-extensions 0.4.0 → 0.6.0

package/dist/loop/contract.d.ts

@@ -1,45 +1,5 @@
 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;
-    /** The model's stated reason for the next self-paced occurrence. */
-    readonly reason: Schema.NullOr<Schema.String>;
-    /** When the next occurrence is due, if one is scheduled. */
-    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>;
+export { Loop, LoopCron } from "./schema.js";
 /**
  * Arguments of the human `/loop` command. `start` carries the typed text:
  * `<prompt>` paces itself, `<N>m <prompt>` or `<N>h <prompt>` runs on an
@@ -62,43 +22,149 @@ export declare const LoopCommandInput: Schema.Union<readonly [Schema.Struct<{
 export declare const LoopProjection: 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;
-        /** The model's stated reason for the next self-paced occurrence. */
         readonly reason: Schema.NullOr<Schema.String>;
-        /** When the next occurrence is due, if one is scheduled. */
         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;
     }>;
 }>;
-/** Session-owned loop controls and their visible state. */
+/** Session-owned current-Loop controls and Agent-scoped identified-Loop controls. */
 export declare const loopContract: {
     /** Stable extension identity. */
     readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
-    /** Loop operations admitted by the Session owner. */
+    /** Loop operations admitted by their Agent or Session owner. */
     readonly commands: {
+        /** Read an Agent's bounded Loop page, including each destination Session. */
+        readonly list: {
+            /** The Agent owns the collection of its Sessions' Loops. */
+            readonly scope: "agent";
+            /** Page strictly after a Session identity, in identity order. */
+            readonly input: Schema.Struct<{
+                readonly after: Schema.optionalKey<Schema.String>;
+                readonly limit: Schema.optionalKey<Schema.Int>;
+            }>;
+            /** Public Loop values with Session targets, never private scheduling state. */
+            readonly output: Schema.$Array<Schema.Struct<{
+                /** Session that owns this identified Loop. */
+                readonly sessionId: Schema.String;
+                readonly loopId: Schema.String;
+                readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                readonly expiresAt: Schema.NullOr<Schema.Int>;
+                readonly prompt: Schema.String;
+                readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+                readonly commandId: Schema.String;
+                readonly reason: Schema.NullOr<Schema.String>;
+                readonly nextDueAt: Schema.NullOr<Schema.Int>;
+                readonly lastError: Schema.NullOr<Schema.String>;
+                readonly consecutiveFailures: Schema.Int;
+            }>>;
+        };
+        /** Pause an identified Loop; refuse a stale target after replacement. */
+        readonly pauseLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            readonly scope: "agent";
+            /** The listed Session and Loop identities must both still match. */
+            readonly input: Schema.Struct<{
+                /** Session containing the identified Loop. */
+                readonly sessionId: Schema.String;
+                /** Exact Loop identity, not whichever Loop later replaces it. */
+                readonly loopId: Schema.String;
+            }>;
+            /** Return the paused Loop without cancelling accepted work. */
+            readonly output: Schema.Struct<{
+                readonly loopId: Schema.String;
+                readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                readonly expiresAt: Schema.NullOr<Schema.Int>;
+                readonly prompt: Schema.String;
+                readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+                readonly commandId: Schema.String;
+                readonly reason: Schema.NullOr<Schema.String>;
+                readonly nextDueAt: Schema.NullOr<Schema.Int>;
+                readonly lastError: Schema.NullOr<Schema.String>;
+                readonly consecutiveFailures: Schema.Int;
+            }>;
+        };
+        /** Resume an identified Loop; refuse a stale target after replacement. */
+        readonly resumeLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            readonly scope: "agent";
+            /** The listed Session and Loop identities must both still match. */
+            readonly input: Schema.Struct<{
+                /** Session containing the identified Loop. */
+                readonly sessionId: Schema.String;
+                /** Exact Loop identity, not whichever Loop later replaces it. */
+                readonly loopId: Schema.String;
+            }>;
+            /** Return the resumed Loop without changing accepted work. */
+            readonly output: Schema.Struct<{
+                readonly loopId: Schema.String;
+                readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                readonly expiresAt: Schema.NullOr<Schema.Int>;
+                readonly prompt: Schema.String;
+                readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+                readonly commandId: Schema.String;
+                readonly reason: Schema.NullOr<Schema.String>;
+                readonly nextDueAt: Schema.NullOr<Schema.Int>;
+                readonly lastError: Schema.NullOr<Schema.String>;
+                readonly consecutiveFailures: Schema.Int;
+            }>;
+        };
+        /** Cancel an identified Loop's future occurrences, retaining accepted work. */
+        readonly stopLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            readonly scope: "agent";
+            /** The listed Session and Loop identities must both still match. */
+            readonly input: Schema.Struct<{
+                /** Session containing the identified Loop. */
+                readonly sessionId: Schema.String;
+                /** Exact Loop identity, not whichever Loop later replaces it. */
+                readonly loopId: Schema.String;
+            }>;
+            /** Return the cancelled Loop; its Session and history remain. */
+            readonly output: Schema.Struct<{
+                readonly loopId: Schema.String;
+                readonly origin: Schema.Literals<readonly ["human", "model"]>;
+                readonly expiresAt: Schema.NullOr<Schema.Int>;
+                readonly prompt: Schema.String;
+                readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+                readonly commandId: Schema.String;
+                readonly reason: Schema.NullOr<Schema.String>;
+                readonly nextDueAt: Schema.NullOr<Schema.Int>;
+                readonly lastError: Schema.NullOr<Schema.String>;
+                readonly consecutiveFailures: Schema.Int;
+            }>;
+        };
         /** Open or answer the human loop controls. */
         readonly loop: {
             /** The Session owns this loop. */
@@ -135,34 +201,20 @@ export declare const loopContract: {
             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;
-                    /** The model's stated reason for the next self-paced occurrence. */
                     readonly reason: Schema.NullOr<Schema.String>;
-                    /** When the next occurrence is due, if one is scheduled. */
                     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. */
@@ -180,9 +232,7 @@ export declare const loopContract: {
             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;
@@ -193,34 +243,20 @@ export declare const loopContract: {
             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;
-                    /** The model's stated reason for the next self-paced occurrence. */
                     readonly reason: Schema.NullOr<Schema.String>;
-                    /** When the next occurrence is due, if one is scheduled. */
                     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. */
@@ -240,34 +276,20 @@ export declare const loopContract: {
             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;
-                /** The model's stated reason for the next self-paced occurrence. */
                 readonly reason: Schema.NullOr<Schema.String>;
-                /** When the next occurrence is due, if one is scheduled. */
                 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;
             }>;
         };
@@ -279,34 +301,20 @@ export declare const loopContract: {
             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;
-                /** The model's stated reason for the next self-paced occurrence. */
                 readonly reason: Schema.NullOr<Schema.String>;
-                /** When the next occurrence is due, if one is scheduled. */
                 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;
             }>;
         };
@@ -318,34 +326,20 @@ export declare const loopContract: {
             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;
-                /** The model's stated reason for the next self-paced occurrence. */
                 readonly reason: Schema.NullOr<Schema.String>;
-                /** When the next occurrence is due, if one is scheduled. */
                 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;
             }>;
         };
@@ -356,34 +350,20 @@ export declare const loopContract: {
         readonly schema: 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;
-                /** The model's stated reason for the next self-paced occurrence. */
                 readonly reason: Schema.NullOr<Schema.String>;
-                /** When the next occurrence is due, if one is scheduled. */
                 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;
             }>;
         }>;

package/dist/loop/contract.js

@@ -1,53 +1,15 @@
 import { ExtensionId } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
 import { CatalogStep } from "../internal/catalog.js";
+import { Prompt, SessionId } from "../internal/schedule-fields.js";
+import { LoopCron, Loop, LoopListInput } from "./schema.js";
+export { Loop, LoopCron } from "./schema.js";
 /**
  * Session loop: one repeated prompt per Session, either paced by the model
  * (`schedule_next`) or by a fixed cron cadence. Shared by the server
  * extension and every client; its schemas are the one decoder.
  */
-const Prompt = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256 * 1024)));
 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",
-        "finished",
-        "failed",
-        "cancelled",
-    ]),
-    /** Latest accepted command associated with this loop. */
-    commandId: Schema.String,
-    /** The model's stated reason for the next self-paced occurrence. */
-    reason: Schema.NullOr(Schema.String),
-    /** When the next occurrence is due, if one is scheduled. */
-    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,
@@ -93,12 +55,58 @@ export const LoopProjection = Schema.Struct({
     /** Loop currently visible to Session clients. */
     loop: Loop,
 });
-/** Session-owned loop controls and their visible state. */
+const LoopTarget = Schema.Struct({
+    /** Session containing the identified Loop. */
+    sessionId: SessionId,
+    /** Exact Loop identity, not whichever Loop later replaces it. */
+    loopId: Loop.fields.loopId,
+});
+/** Session-owned current-Loop controls and Agent-scoped identified-Loop controls. */
 export const loopContract = {
     /** Stable extension identity. */
     id: ExtensionId.make("botanical-session-loop"),
-    /** Loop operations admitted by the Session owner. */
+    /** Loop operations admitted by their Agent or Session owner. */
     commands: {
+        /** Read an Agent's bounded Loop page, including each destination Session. */
+        list: {
+            /** The Agent owns the collection of its Sessions' Loops. */
+            scope: "agent",
+            /** Page strictly after a Session identity, in identity order. */
+            input: LoopListInput,
+            /** Public Loop values with Session targets, never private scheduling state. */
+            output: Schema.Array(Schema.Struct({
+                ...Loop.fields,
+                /** Session that owns this identified Loop. */
+                sessionId: SessionId,
+            })).pipe(Schema.check(Schema.isMaxLength(64))),
+        },
+        /** Pause an identified Loop; refuse a stale target after replacement. */
+        pauseLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            scope: "agent",
+            /** The listed Session and Loop identities must both still match. */
+            input: LoopTarget,
+            /** Return the paused Loop without cancelling accepted work. */
+            output: Loop,
+        },
+        /** Resume an identified Loop; refuse a stale target after replacement. */
+        resumeLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            scope: "agent",
+            /** The listed Session and Loop identities must both still match. */
+            input: LoopTarget,
+            /** Return the resumed Loop without changing accepted work. */
+            output: Loop,
+        },
+        /** Cancel an identified Loop's future occurrences, retaining accepted work. */
+        stopLoop: {
+            /** The Agent owns the identified Loop and its Session. */
+            scope: "agent",
+            /** The listed Session and Loop identities must both still match. */
+            input: LoopTarget,
+            /** Return the cancelled Loop; its Session and history remain. */
+            output: Loop,
+        },
         /** Open or answer the human loop controls. */
         loop: {
             /** The Session owns this loop. */

package/dist/loop/host.js

@@ -281,6 +281,13 @@ function fire(ctx, sessionId, dueAt, now) {
                 delivery: "followUp",
             },
         }));
+        // The Agent owner will pause this loop after flipping its archive flag.
+        // If this timer wins that short interval, keep the loop resumable instead
+        // of treating an intentional archive refusal as a permanent failed run.
+        if (Result.isFailure(admitted) && admitted.failure.reason === "archived") {
+            yield* arm(ctx, { ...loop, lastError: admitted.failure.message }, now + 30_000);
+            return yield* ctx.observe(sessionId);
+        }
         if (Result.isFailure(admitted) || admitted.success._tag === "NotReady") {
             yield* commitLoop(ctx, {
                 ...loop,
@@ -493,6 +500,16 @@ function stopLoop(ctx, sessionId, reason) {
         return projected(stopped);
     });
 }
+/** Match and mutate within the same extension command transaction. */
+function controlIdentifiedLoop(ctx, target, action) {
+    return requireLoop(ctx, target.sessionId).pipe(Effect.flatMap((loop) => loop.loopId !== target.loopId
+        ? Effect.fail(conflict("Session loop has been replaced"))
+        : action === "pause"
+            ? pauseLoop(ctx, target.sessionId)
+            : action === "resume"
+                ? resumeLoop(ctx, target.sessionId)
+                : stopLoop(ctx, target.sessionId)));
+}
 function cronForInterval(value, unit) {
     if (unit === "m" || unit === "min")
         return value > 59 ? undefined : `0 */${String(value)} * * * *`;
@@ -662,6 +679,15 @@ export const loopExtension = defineExtension({
     commands: {
         specs: loopContract.commands,
         handlers: (ctx) => ({
+            pauseLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "pause"),
+            resumeLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "resume"),
+            stopLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "stop"),
+            list: ({ input }) => ctx.state.loops
+                .page({ after: input.after, limit: input.limit ?? 64 })
+                .pipe(Effect.map((rows) => rows.map((row) => ({
+                ...projected(row),
+                sessionId: row.sessionId,
+            })))),
             startSelfPaced: ({ sessionId, input }) => start(ctx, sessionId, input, null),
             startFixedInterval: ({ sessionId, input }) => start(ctx, sessionId, input, {
                 expression: input.expression,

package/dist/loop/schema.d.ts

@@ -0,0 +1,49 @@
+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;
+    /** The model's stated reason for the next self-paced occurrence. */
+    readonly reason: Schema.NullOr<Schema.String>;
+    /** When the next occurrence is due, if one is scheduled. */
+    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>;
+/** Native bounded Loop page grammar, also used by shared continuations. */
+export declare const LoopListInput: Schema.Struct<{
+    /** Exclusive Session cursor. */
+    readonly after: Schema.optionalKey<Schema.String>;
+    /** Maximum number of Loop rows to read. */
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;