@fungi.computer/shiitake-extensions 0.3.0 → 0.5.0

package/README.md

@@ -65,16 +65,16 @@ helper borrows the Agent. Its owner closes it when the host's lifetime ends.
 
 ## Core concepts
 
-| Extension | Ownership and behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Ask       | Up to four open decisions per Session. The model asks or withdraws; humans answer or decline. A live waiter receives the answer, while a parked question resumes through one follow-up.                                                                                                                                                                                                                                                                                                                                          |
-| Goal      | One live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools, from any later turn of its Session; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it; a tool-less goal turn while a sub-agent command is live waits instead. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history. |
-| Loop      | One repeated prompt per Session. It runs on a fixed cron cadence or lets its own active run request the next occurrence. Commands start, pause, resume and stop it.                                                                                                                                                                                                                                                                                                                                                              |
-| Plan      | One checklist per Session. `plan.update_plan` replaces it whole, with at most one step in progress and at most 50 steps; `steps: []` clears it. The human clears it with `/plan clear` or the footer row's Clear plan action, through the same owner. `/plan` opens the full checklist in the footer; updates keep only the current step and progress visible, and a finished or cleared plan leaves the footer while its history stays in state.                                                                                |
-| Almanac   | Agent-scope one-shot or recurring schedules. Each schedule targets a Session and tracks admission, retry and its next due time.                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Skills    | Host-supplied, read-only skill discovery. Metadata enters the prompt; `skill.load` reads a skill body or supporting file; `/skills` lists them.                                                                                                                                                                                                                                                                                                                                                                                  |
-| Home      | Agent-scope choice of an attached Computer. Each run captures its scoped file tools and current attachment choice.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Subagents | A read-only footer view: one row per Agent this Session sent work to or created, with its live status (working, waiting on you, idle, failed, unavailable). A row opens that Agent's conversation, and `/agents` collapses the rows to one summary row and expands them again. It owns no relationship and no durable state.                                                                                                                                                                                                     |
+| Extension | Ownership and behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ask       | Up to four open decisions per Session. The model asks or withdraws; humans answer or decline. A live waiter receives the answer, while a parked question resumes through one follow-up. On Local, an Ask raised during work another Agent sent waits on that sender first: it always parks, reads `waiting on <name>` instead of needing a person, and rides the child's reply to the sender as `waiting_on_you`. Only that sender's Session can answer it with `agents.answer`, or pass it to a person with `agents.escalate`; a person may always answer. An Ask the sender neither answers nor escalates goes to a person when the sender's turn ends, or after fifteen minutes. Hub sends every Ask to a person. |
+| Goal      | One live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools, from any later turn of its Session; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it; a tool-less goal turn while a sub-agent command is live waits instead. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history.                                                                                                                                                                                     |
+| Loop      | One repeated prompt per Session. It runs on a fixed cron cadence or lets its own active run request the next occurrence. Commands start, pause, resume and stop it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Plan      | One checklist per Session. `plan.update_plan` replaces it whole, with at most one step in progress and at most 50 steps; `steps: []` clears it. The human clears it with `/plan clear` or the footer row's Clear plan action, through the same owner. `/plan` opens the full checklist in the footer; updates keep only the current step and progress visible, and a finished or cleared plan leaves the footer while its history stays in state.                                                                                                                                                                                                                                                                    |
+| Almanac   | Agent-scope one-shot or recurring schedules. Each schedule targets a Session and tracks admission, retry and its next due time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Skills    | Host-supplied, read-only skill discovery. Metadata enters the prompt; `skill.load` reads a skill body or supporting file; `/skills` lists them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Home      | Agent-scope choice of an attached Computer. Each run captures its scoped file tools and current attachment choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Subagents | A footer view: one row per Agent this Session sent work to or created, with its live status (working, waiting on an Agent, needs you, idle, failed, unavailable). A row opens that Agent's conversation, a question that needs a person can be answered from its row, and `/agents` collapses the rows to one summary row and expands them again. It owns no relationship and no durable state.                                                                                                                                                                                                                                                                                                                      |
 
 An active Goal is quiet system context on every run. Continuation instructions
 apply only to runs admitted by Goal with its continuation correlation; human
@@ -112,9 +112,8 @@ paused and `null` while active. The closed kinds are `person`, `blocked`,
 text, never a discriminator. Only blocked/stalled goals emit `goal-blocked` or
 `goal-stalled` attention, kept out of the main inbox with `inbox: false`.
 Questions and these two Goal kinds ask for a person in Herdr activity;
-person-paused, cancelled and failed goals do not. State version 6 discards
-disposable preview Goal rows from versions 4 and 5 rather than reading the
-superseded representation.
+person-paused, cancelled and failed goals do not. The current Goal state is
+version 7. Superseded preview Goal rows are not migrated to this representation.
 
 Loop tools are offered in every run. `loop.get`, `loop.start` and `loop.stop`
 work from any run of the Session, and the model may start a loop itself.
@@ -269,9 +268,14 @@ expands the footer rows, per Session and in memory).
 `source.read(sessionId, limit)` returns the Agents that Session sent work to or
 created, newest first, with a count of the rest; `source.open` is the host's
 existing Agent access. Each child's status is its owner's own Session state:
-`running` is working, any open attention (a question or a tool approval) is
-waiting on you, `done` is idle and `errored` is failed. A child whose state
-cannot be read is unavailable, never idle.
+`running` is working, `done` is idle and `errored` is failed. Attention that
+waits on a person (a question, or an approval an extension raises) is
+`needs you`; a question that waits on the Agent that sent the work is
+`waiting on <name>`, calm until it is escalated, and counted apart in the
+collapsed summary, which is amber only when a child needs a person. A
+`needs you` question carries its text and one Answer action that runs the
+question's own answer conversation. A child whose state cannot be read is
+unavailable, never idle.
 
 Rows refresh when a watcher reads the parent Session and they are at least a
 second old. While a row is working or waiting, they poll every five seconds

package/dist/goal/contract.d.ts

@@ -224,6 +224,12 @@ export declare const goalContract: {
                 readonly expectedRevision: Schema.NullOr<Schema.String>;
                 /** Idempotency key for this setting command. */
                 readonly requestId: Schema.String;
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                readonly adoptCommandId: Schema.optionalKey<Schema.String>;
             }>;
             /** Return the goal and its admission receipt. */
             readonly output: Schema.Struct<{

package/dist/goal/contract.js

@@ -154,6 +154,12 @@ export const goalContract = {
                 expectedRevision: Schema.NullOr(Schema.String),
                 /** Idempotency key for this setting command. */
                 requestId: RequestId,
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                adoptCommandId: Schema.optionalKey(RequestId),
             }),
             /** Return the goal and its admission receipt. */
             output: Schema.Struct({

package/dist/goal/host.js

@@ -14,14 +14,18 @@ import { clearConfirmation, goalMenuPrompt, replaceConfirmation, } from "./promp
 const rules = "You may start a goal yourself when none is current. Before marking complete audit every requirement against evidence; complete only after actual achievement. Block only after the same external impasse for three consecutive goal turns; a blocked goal stays paused until it is resumed. You may complete, block, clear or resume a goal that paused on its own (stalled, blocked or failed work); a goal a person paused or stopped you may only complete, and only a person clears a live goal. Human pause/resume/clear remain human controls. Use plan.update_plan for multi-step work when available.";
 /** Hashed prose and policy: every constant goal reads comes from here. */
 const config = {
-    continuation: "Continue working toward the current goal described in the goal section. Find goal.get_goal and goal.update_goal with forage.search({query:'goal'}) and forage.describe. Audit every requirement against evidence before goal.update_goal({status:'complete', reason}). If the same external blocker persists for three goal turns, report blocked with a reason. Check for progress rather than repeating yourself.",
-    moduleDescription: "Session goal tools: create_goal({objective}), get_goal({}), update_goal({status:'complete'|'blocked'|'clear'|'resume', reason}). " +
+    continuation: "Continue working toward the current goal described in the goal section. Find goal.get_goal and goal.update_goal with forage.search({query:'goal'}) and forage.describe. Audit every requirement against evidence before goal.update_goal({status:'complete', reason}). If the same external blocker persists for three goal turns, report blocked with a reason. Check for progress rather than repeating yourself. If there is nothing to do until something outside this turn happens (a child's reply, a person, the train, main), call goal.wait({reason, fallbackMinutes}) and end the turn instead of polling.",
+    moduleDescription: "Session goal tools: create_goal({objective}), get_goal({}), update_goal({status:'complete'|'blocked'|'clear'|'resume', reason}), wait({reason, fallbackMinutes}). " +
         rules,
-    createDescription: "Create a Session goal, including autonomously. Fails while a goal is active or paused; a finished goal is history.",
+    createDescription: "Create a Session goal, including autonomously. Fails while a goal is active or paused; a finished goal is history. After update_goal complete (or clear on a paused goal) in this same run, it queues the replacement, which takes over when this run settles.",
     getDescription: "Read the current goal. A requested terminal state remains provisional until successful settlement.",
     updateDescription: "Request complete only after actual achievement, or blocked only after the same external impasse for three consecutive goal turns; both also work on a paused goal, and settlement commits the request. Complete ends the goal; blocked pauses it for a person. clear abandons a paused goal with your reason. resume reactivates a paused goal now. A goal a person paused or stopped accepts only complete.",
     waitCheckMs: 60_000,
+    waitDescription: "Say the goal is waiting on something outside this turn, then end the turn. The goal stays active and admits no goal turn and no stall count until another run in this Session settles (a child's reply, a person's message, a loop tick) or fallbackMinutes (default 20, 1 to 60) pass. Use it instead of polling.",
+    waitDefaultMinutes: 20,
+    waitMaxMinutes: 60,
     waitingSummary: "Waiting on sub-agent",
+    waitingOnSummary: "Waiting",
     promptLimit: 1_024,
     stallTurns: 3,
     stallReason: "Stalled: no progress for 3 turns",
@@ -61,6 +65,17 @@ const GoalRow = Schema.Struct({
         reason: GoalReason,
     })),
     stalledTurns: Schema.Int,
+    /**
+     * The goal waits on something outside its turns. `until` is null while the
+     * requesting run is still running; its settlement fixes the fallback instant.
+     */
+    waiting: Schema.optionalKey(Schema.NullOr(Schema.Struct({
+        reason: GoalReason,
+        fallbackMs: Schema.Int,
+        until: Schema.NullOr(Schema.Int),
+    }))),
+    /** A replacement objective queued after this run's complete or clear. */
+    successor: Schema.optionalKey(Schema.NullOr(Objective)),
     /** Request that set this revision; its retry replays. */
     revisionRequestId: Schema.String,
     /** Latest work whose settlement advances this goal. */
@@ -127,6 +142,8 @@ function paused(goal, kind, detail) {
         state: "paused",
         pauseCause: { kind, detail },
         pending: null,
+        waiting: null,
+        successor: null,
     };
 }
 /**
@@ -167,6 +184,7 @@ function changeActivity(ctx, sessionId, target) {
                 state: "active",
                 pauseCause: null,
                 stalledTurns: 0,
+                waiting: null,
             }
             : paused(goal, "person", null);
         yield* commitGoal(ctx, changed);
@@ -190,7 +208,9 @@ function continueIfIdle(ctx, goal, requestId) {
     })
         .pipe(Effect.map((admitted) => admitted._tag === "Accepted"
         ? { ...goal, trackedWorkId: admitted.commandId }
-        : goal), Effect.catchTag("AdmissionError", (error) => Effect.succeed(paused(goal, "failed", error.message))));
+        : goal), Effect.catchTag("AdmissionError", (error) => error.reason === "archived"
+        ? Clock.currentTimeMillis.pipe(Effect.flatMap((now) => ctx.timers.set(waitTimerKey(goal.sessionId), now + ctx.config.waitCheckMs)), Effect.as(goal))
+        : Effect.succeed(paused(goal, "failed", error.message))));
 }
 /**
  * Advance one Session's goal from one settled run. Any successful run in
@@ -225,26 +245,77 @@ function settle(ctx, run, subagents) {
             yield* commitGoal(ctx, paused(goal, "no-terminal", ctx.config.noTerminalReason));
             return yield* ctx.observe(run.sessionId);
         }
-        const waitingForChild = run.toolCalls === 0 &&
-            subagents?.hasLiveChildCommand(run.sessionId) === true &&
-            run.origin?.extensionId === goalContract.id;
+        const goalTurn = run.origin?.extensionId === goalContract.id;
+        // A live child command or a question or approval a person has yet to
+        // answer is a legitimate wait, whether or not this turn polled.
+        const waitingForChild = goalTurn &&
+            (subagents?.hasLiveChildCommand(run.sessionId) === true ||
+                (yield* ctx.attention.awaitsPerson(run.sessionId)));
+        const waiting = goal.waiting ?? null;
+        // The run that called goal.wait fixes the fallback instant as it settles.
+        const requested = waiting !== null &&
+            waiting.until === null &&
+            run.workId === goal.trackedWorkId;
+        // Any other run that settles while a wait is armed wakes the goal.
+        const woken = waiting !== null && waiting.until !== null;
         const tracked = {
             ...goal,
             trackedWorkId: run.workId,
-            stalledTurns: run.origin?.extensionId === goalContract.id &&
-                run.origin.correlation === goal.revision
-                ? run.toolCalls === 0
-                    ? goal.stalledTurns + 1
-                    : 0
-                : 0,
+            stalledTurns: requested
+                ? goal.stalledTurns
+                : run.origin?.extensionId === goalContract.id &&
+                    run.origin.correlation === goal.revision
+                    ? run.toolCalls === 0
+                        ? goal.stalledTurns + 1
+                        : 0
+                    : 0,
         };
         const pending = goal.trackedWorkId === run.workId ? goal.pending : null;
-        if (pending?.state === "complete")
-            yield* finishGoal(ctx, tracked, "achieved", pending.reason);
-        else if (pending?.state === "cleared")
-            yield* finishGoal(ctx, tracked, "cleared", pending.reason);
+        if (pending?.state === "complete" || pending?.state === "cleared") {
+            yield* ctx.timers.cancel(waitTimerKey(run.sessionId));
+            yield* finishGoal(ctx, tracked, pending.state === "complete" ? "achieved" : "cleared", pending.reason);
+            if (goal.successor != null) {
+                const next = {
+                    sessionId: run.sessionId,
+                    objective: goal.successor,
+                    state: "active",
+                    startedAt: yield* Clock.currentTimeMillis,
+                    pending: null,
+                    stalledTurns: 0,
+                    revision: `run:${run.workId}`,
+                    revisionRequestId: `run:${run.workId}`,
+                    trackedWorkId: run.workId,
+                    pauseCause: null,
+                    waiting: null,
+                    successor: null,
+                };
+                yield* commitGoal(ctx, yield* continueIfIdle(ctx, next, `goal-continue:${run.workId}`));
+            }
+        }
         else if (pending?.state === "blocked")
             yield* commitGoal(ctx, paused(tracked, "blocked", pending.reason));
+        else if (goal.state === "active" && requested) {
+            // goal.wait: no continuation and no stall; the next settled run or the
+            // fallback timer wakes the goal.
+            const now = yield* Clock.currentTimeMillis;
+            const until = now + waiting.fallbackMs;
+            yield* commitGoal(ctx, {
+                ...tracked,
+                waiting: { ...waiting, until },
+            });
+            yield* ctx.attention.set(run.sessionId, {
+                id: "waiting-goal",
+                kind: "goal-waiting",
+                inbox: false,
+                summary: `${ctx.config.waitingOnSummary}: ${waiting.reason}`.slice(0, 200),
+                since: now,
+            });
+            yield* ctx.timers.set(waitTimerKey(run.sessionId), until);
+        }
+        else if (goal.state === "active" && woken) {
+            yield* ctx.timers.cancel(waitTimerKey(run.sessionId));
+            yield* commitGoal(ctx, yield* continueIfIdle(ctx, { ...tracked, waiting: null }, `goal-continue:${run.workId}`));
+        }
         else if (goal.state === "active" &&
             !waitingForChild &&
             tracked.stalledTurns >= ctx.config.stallTurns)
@@ -288,7 +359,15 @@ function recheckWaiting(ctx, timer, subagents) {
         const found = yield* ctx.state.goals.get(sessionId);
         if (Option.isNone(found) || found.value.state !== "active")
             return;
-        if (subagents?.hasLiveChildCommand(sessionId) === true)
+        const armed = found.value.waiting ?? null;
+        if (armed !== null) {
+            // goal.wait's fallback: a re-armed wait ignores a stale firing.
+            if (armed.until === null || armed.until > timer.firedAt)
+                return;
+            return yield* commitGoal(ctx, yield* continueIfIdle(ctx, { ...found.value, waiting: null, stalledTurns: 0 }, `goal-wait:${found.value.trackedWorkId}`)).pipe(Effect.andThen(ctx.observe(sessionId)));
+        }
+        if (subagents?.hasLiveChildCommand(sessionId) === true ||
+            (yield* ctx.attention.awaitsPerson(sessionId)))
             return yield* ctx.timers.set(timer.key, timer.firedAt + ctx.config.waitCheckMs);
         yield* commitGoal(ctx, yield* continueIfIdle(ctx, found.value, `goal-wait:${found.value.trackedWorkId}`));
         yield* ctx.observe(sessionId);
@@ -349,8 +428,21 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                 }),
                 execute: ({ objective }) => toolCall(ctx, "create_goal", Effect.gen(function* () {
                     const decoded = yield* Schema.decodeUnknownEffect(Objective)(objective).pipe(Effect.mapError(() => conflict("Goal objective is invalid")));
-                    if (Option.isSome(yield* ctx.state.goals.get(sessionId)))
-                        return yield* Effect.fail(conflict("A Session goal is already active or paused; only a person replaces it"));
+                    const existing = yield* ctx.state.goals.get(sessionId);
+                    if (Option.isSome(existing)) {
+                        // A goal this run already finished (complete, or clear of a
+                        // paused one) hands over to the replacement at settlement.
+                        const retiring = existing.value.trackedWorkId === workId &&
+                            (existing.value.pending?.state === "complete" ||
+                                existing.value.pending?.state === "cleared");
+                        if (!retiring)
+                            return yield* Effect.fail(conflict("A Session goal is already active or paused; complete it first, or only a person replaces it"));
+                        yield* ctx.state.goals.put({
+                            ...existing.value,
+                            successor: decoded,
+                        });
+                        return { objective: decoded, state: "active" };
+                    }
                     yield* commitGoal(ctx, {
                         sessionId,
                         objective: decoded,
@@ -362,6 +454,8 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                         revisionRequestId: `run:${workId}`,
                         trackedWorkId: workId,
                         pauseCause: null,
+                        waiting: null,
+                        successor: null,
                     });
                     yield* ctx.observe(sessionId);
                     return { objective: decoded, state: "active" };
@@ -389,6 +483,50 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                             null,
                     }))),
             }),
+            wait: Mycelium.operation({
+                replay: "unsafe",
+                description: ctx.config.waitDescription,
+                input: z.strictObject({
+                    reason: z.string().min(1).max(1_000),
+                    fallbackMinutes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(ctx.config.waitMaxMinutes)
+                        .optional(),
+                }),
+                output: z.strictObject({
+                    objective: toolObjective,
+                    state: z.literal("active"),
+                    reason: z.string(),
+                    fallbackMinutes: z.number().int(),
+                }),
+                execute: ({ reason, fallbackMinutes }) => toolCall(ctx, "wait", Effect.gen(function* () {
+                    const decoded = yield* Schema.decodeUnknownEffect(GoalReason)(reason).pipe(Effect.mapError(() => conflict("Wait reason is invalid")));
+                    const goal = yield* currentGoal;
+                    if (goal.state !== "active")
+                        return yield* Effect.fail(conflict("Only an active Session goal can wait"));
+                    if (goal.pending != null)
+                        return yield* Effect.fail(conflict("This run already requested a goal terminal"));
+                    const minutes = fallbackMinutes ?? ctx.config.waitDefaultMinutes;
+                    yield* ctx.state.goals.put({
+                        ...goal,
+                        // This run's settlement starts the wait.
+                        trackedWorkId: workId,
+                        waiting: {
+                            reason: decoded,
+                            fallbackMs: minutes * 60_000,
+                            until: null,
+                        },
+                    });
+                    return {
+                        objective: goal.objective,
+                        state: "active",
+                        reason: decoded,
+                        fallbackMinutes: minutes,
+                    };
+                })),
+            }),
             update_goal: Mycelium.operation({
                 replay: "unsafe",
                 description: ctx.config.updateDescription,
@@ -474,15 +612,22 @@ function setGoal(ctx, sessionId, input) {
         const retried = current?.revisionRequestId === input.requestId;
         if (!retried && (current?.revision ?? null) !== input.expectedRevision)
             return yield* Effect.fail(conflict("Session goal changed; read it before replacing it"));
-        const admitted = yield* ctx.send({
-            sessionId,
-            when: "now",
-            prompt: {
-                text: input.objective,
-                requestId: input.requestId,
-                delivery: "followUp",
-            },
-        });
+        // Adopted work already carries the objective; anything else admits it.
+        const admitted = input.adoptCommandId === undefined
+            ? yield* ctx.send({
+                sessionId,
+                when: "now",
+                prompt: {
+                    text: input.objective,
+                    requestId: input.requestId,
+                    delivery: "followUp",
+                },
+            })
+            : {
+                _tag: "Accepted",
+                commandId: input.adoptCommandId,
+                delivery: retried ? "replay" : "new",
+            };
         if (admitted._tag !== "Accepted")
             return yield* Effect.fail(conflict("Session goal was not admitted"));
         const accepted = {
@@ -511,10 +656,17 @@ function setGoal(ctx, sessionId, input) {
             revisionRequestId: input.requestId,
             trackedWorkId: admitted.commandId,
             pauseCause: null,
+            waiting: null,
+            successor: null,
         };
-        yield* commitGoal(ctx, row);
+        // Adopted work that already settled left the Session idle: start the
+        // first goal turn now. Otherwise its settlement does.
+        const started = input.adoptCommandId === undefined
+            ? row
+            : yield* continueIfIdle(ctx, row, `goal-adopt:${input.requestId}`);
+        yield* commitGoal(ctx, started);
         yield* ctx.observe(sessionId);
-        return { goal: committed(row), accepted };
+        return { goal: committed(started), accepted };
     });
 }
 /** The one-line state the model prompt and attention summaries carry. */

package/dist/loop/contract.d.ts

@@ -93,12 +93,146 @@ export declare const LoopProjection: Schema.Struct<{
         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<{
+                /** Exclusive Session cursor. */
+                readonly after: Schema.optionalKey<Schema.String>;
+                /** Maximum number of Loop rows to read. */
+                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;
+                /** 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;
+            }>>;
+        };
+        /** 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<{
+                /** 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;
+            }>;
+        };
+        /** 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<{
+                /** 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;
+            }>;
+        };
         /** Open or answer the human loop controls. */
         readonly loop: {
             /** The Session owns this loop. */

package/dist/loop/contract.js

@@ -8,6 +8,7 @@ import { CatalogStep } from "../internal/catalog.js";
  */
 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)));
+const SessionId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
 /** A named cron cadence evaluated in one IANA time zone. */
 export const LoopCron = Schema.Struct({
     /** Cron expression for the fixed cadence. */
@@ -93,12 +94,54 @@ 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: Schema.Struct({
+                /** Exclusive Session cursor. */
+                after: Schema.optionalKey(SessionId),
+                /** Maximum number of Loop rows to read. */
+                limit: Schema.optionalKey(Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 64 })))),
+            }),
+            /** 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,
+        },
+        /** 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. */