@fungi.computer/shiitake-extensions 0.4.0 → 0.5.0

package/README.md

@@ -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.

package/dist/goal/host.js

@@ -208,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

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. */

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,14 @@ 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)
+            : stopLoop(ctx, target.sessionId)));
+}
 function cronForInterval(value, unit) {
     if (unit === "m" || unit === "min")
         return value > 59 ? undefined : `0 */${String(value)} * * * *`;
@@ -662,6 +677,14 @@ export const loopExtension = defineExtension({
     commands: {
         specs: loopContract.commands,
         handlers: (ctx) => ({
+            pauseLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "pause"),
+            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/roster/conversation-agents.d.ts

@@ -6,14 +6,24 @@ import type { SubagentSource } from "../subagents/host.js";
 /** Host-pack creation admission; attachments/model selection retain their own owners. */
 export declare function assertOrdinaryAgentCreation(input: Parameters<NonNullable<AgentControlDirectory["create"]>>[0]): void;
 /** The directory a conversation sends through; opening a recipient only needs its Sessions' extension doors. */
-type SendingDirectory = Omit<AgentControlDirectory, "open"> & Readonly<{
+export type SendingDirectory = Omit<AgentControlDirectory, "open"> & Readonly<{
+    /** Open the recipient's Session extension door for goal adoption. */
     open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
+        /** Recipient Agent with a Session extension door. */
         agent: Readonly<{
+            /** Address a recipient Session without loading its conversation. */
             session: (sessionId: string) => Pick<ShiitakeSession, "extension">;
         }>;
+        /** Release the acquired recipient without stopping its work. */
         release: () => Promise<void>;
     }>>;
 }>;
+/** Adopt the first accepted turn once, even when the sender was offline at delivery. */
+export declare function adoptDelegatedGoal(session: Pick<ShiitakeSession, "extension">, input: Readonly<{
+    text: string;
+    goal: string | false | undefined;
+    commandId: string;
+}>): Promise<void>;
 /**
  * This host's own record of the Agents each conversation created or sent
  * accepted work to, written as its Agent-control directory accepts them
@@ -35,4 +45,3 @@ export declare function oysterAgentExtensions(source: SubagentSource): Readonly<
     roster: readonly import("@fungi.computer/shiitake").RosteredExtensionV0[];
     grants: readonly import("@fungi.computer/shiitake").ExtensionGrantV0[];
 }>;
-export {};

package/dist/roster/conversation-agents.js

@@ -37,6 +37,18 @@ function laneObjective(text, goal) {
         .map((line) => line.trim())
         .find((line) => line !== "") ?? text.trim()).slice(0, 4_000);
 }
+/** Adopt the first accepted turn once, even when the sender was offline at delivery. */
+export async function adoptDelegatedGoal(session, input) {
+    if (input.goal === false)
+        return;
+    await bindSessionExtension(session, goalContract).call("set", {
+        objective: laneObjective(input.text, input.goal),
+        expectedRevision: null,
+        requestId: `lane-goal:${input.commandId}`,
+        // The delegated prompt is already admitted; never enqueue it twice.
+        adoptCommandId: input.commandId,
+    });
+}
 /**
  * This host's own record of the Agents each conversation created or sent
  * accepted work to, written as its Agent-control directory accepts them
@@ -99,12 +111,10 @@ export function createConversationAgents(storage) {
                             sessionId !== undefined) {
                             const opened = await directory.open(task.agentId, signal);
                             try {
-                                await bindSessionExtension(opened.agent.session(sessionId), goalContract).call("set", {
-                                    objective: laneObjective(task.text, task.goal),
-                                    expectedRevision: null,
-                                    requestId: `lane-goal:${accepted.commandId}`,
-                                    // The send is the lane's first turn; never repeat it.
-                                    adoptCommandId: accepted.commandId,
+                                await adoptDelegatedGoal(opened.agent.session(sessionId), {
+                                    text: task.text,
+                                    goal: task.goal,
+                                    commandId: accepted.commandId,
                                 });
                             }
                             finally {

package/dist/schedules.d.ts

@@ -0,0 +1,178 @@
+import type { ShiitakeAgent } from "@fungi.computer/shiitake";
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+/** Exclusive native key within one Agent's Almanac-then-Loop traversal. */
+export declare const agentScheduleCursorSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    kind: z.ZodUnion<readonly [z.ZodLiteral<"almanac">, z.ZodLiteral<"loop">]>;
+    after: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One bounded read; a full native page conservatively carries continuation. */
+export declare const agentScheduleListInputSchema: z.ZodObject<{
+    after: z.ZodOptional<z.ZodObject<{
+        agentId: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"almanac">, z.ZodLiteral<"loop">]>;
+        after: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** Content-bearing read projection, decoded by the retained native contracts. */
+export declare const agentScheduleRowSchema: Schema.Union<readonly [Schema.Struct<{
+    /** Agent that owns this Almanac schedule. */
+    readonly agentId: Schema.String;
+    /** Identifies the native Almanac schedule representation. */
+    readonly kind: Schema.Literal<"almanac">;
+    /** Retained Almanac row, including its instruction and lifecycle state. */
+    readonly schedule: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly sessionId: Schema.String;
+        readonly prompt: Schema.String;
+        readonly cron: Schema.NullOr<Schema.Struct<{
+            readonly expression: Schema.String;
+            readonly timeZone: Schema.String;
+        }>>;
+        readonly nextDueAt: Schema.Int;
+        readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+        readonly lastCommandId: Schema.NullOr<Schema.String>;
+        readonly lastError: Schema.NullOr<Schema.String>;
+        readonly attempt: Schema.Int;
+    }>;
+}>, Schema.Struct<{
+    /** Agent that owns this Session's Loop. */
+    readonly agentId: Schema.String;
+    /** Identifies the native Loop representation. */
+    readonly kind: Schema.Literal<"loop">;
+    /** Retained Loop row with the Session identity used to address its owner. */
+    readonly schedule: Schema.Struct<{
+        /** Session containing this exact 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;
+    }>;
+}>]>;
+/** One Agent's retained schedule, including its native content. */
+export type AgentScheduleRow = typeof agentScheduleRowSchema.Type;
+/** Exact listed identity; a Loop target never selects its later replacement. */
+export declare const agentScheduleTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"almanac">;
+    agentId: z.ZodString;
+    scheduleId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"loop">;
+    agentId: z.ZodString;
+    sessionId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    loopId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strict>], "kind">;
+/** Identity to admit before acquiring the corresponding Agent owner. */
+export type AgentScheduleTarget = z.output<typeof agentScheduleTargetSchema>;
+/** A bounded content-bearing page; owner failures reject rather than look empty. */
+export declare const agentSchedulePageSchema: Schema.Struct<{
+    /** At most 64 retained rows, ordered Almanac first and then Loop. */
+    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        /** Agent that owns this Almanac schedule. */
+        readonly agentId: Schema.String;
+        /** Identifies the native Almanac schedule representation. */
+        readonly kind: Schema.Literal<"almanac">;
+        /** Retained Almanac row, including its instruction and lifecycle state. */
+        readonly schedule: Schema.Struct<{
+            readonly id: Schema.String;
+            readonly sessionId: Schema.String;
+            readonly prompt: Schema.String;
+            readonly cron: Schema.NullOr<Schema.Struct<{
+                readonly expression: Schema.String;
+                readonly timeZone: Schema.String;
+            }>>;
+            readonly nextDueAt: Schema.Int;
+            readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+            readonly lastCommandId: Schema.NullOr<Schema.String>;
+            readonly lastError: Schema.NullOr<Schema.String>;
+            readonly attempt: Schema.Int;
+        }>;
+    }>, Schema.Struct<{
+        /** Agent that owns this Session's Loop. */
+        readonly agentId: Schema.String;
+        /** Identifies the native Loop representation. */
+        readonly kind: Schema.Literal<"loop">;
+        /** Retained Loop row with the Session identity used to address its owner. */
+        readonly schedule: Schema.Struct<{
+            /** Session containing this exact 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;
+        }>;
+    }>]>>;
+    /** Exclusive continuation on a full page, or null when both kinds are exhausted. */
+    readonly next: Schema.NullOr<Schema.Struct<{
+        /** Agent whose traversal the next request must continue. */
+        readonly agentId: Schema.String;
+        /** Native owner to continue within that Agent. */
+        readonly kind: Schema.Literals<readonly ["almanac", "loop"]>;
+        /** Exclusive schedule ID or Session ID; absent starts the native kind. */
+        readonly after: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+/** One Agent's page, with no directory fan-out or availability policy. */
+export type AgentSchedulePage = typeof agentSchedulePageSchema.Type;
+/** Manage-only result: exact target and native state, never prompt or history. */
+export declare const agentScheduleControlReceiptSchema: Schema.Union<readonly [Schema.Struct<{
+    /** Agent whose Almanac owner completed the transition. */
+    readonly agentId: Schema.String;
+    /** Identifies the controlled native Almanac schedule. */
+    readonly kind: Schema.Literal<"almanac">;
+    /** Identity of the schedule that was paused or cancelled. */
+    readonly scheduleId: Schema.String;
+    /** Native lifecycle state returned after the transition. */
+    readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+}>, Schema.Struct<{
+    /** Agent whose Loop owner completed the transition. */
+    readonly agentId: Schema.String;
+    /** Identifies the controlled native Loop. */
+    readonly kind: Schema.Literal<"loop">;
+    /** Session containing the controlled Loop. */
+    readonly sessionId: Schema.String;
+    /** Exact Loop identity checked by the native transition. */
+    readonly loopId: Schema.String;
+    /** Native lifecycle state returned after the transition. */
+    readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+}>]>;
+/** Content-free acknowledgement of the native owner's completed transition. */
+export type AgentScheduleControlReceipt = typeof agentScheduleControlReceiptSchema.Type;
+/**
+ * Read one already-admitted Agent, without scanning Sessions or draining pages.
+ * The caller owns Agent, home and resource authorization and the owner's lifetime.
+ */
+export declare function readAgentSchedulePage(agentId: string, owner: Pick<ShiitakeAgent, "extensions">, input?: z.input<typeof agentScheduleListInputSchema>): Promise<AgentSchedulePage>;
+/**
+ * Explicit content-returning control for callers admitted to both read and manage.
+ * In particular, private Local retains its native-row reply. The supplied owner
+ * must already be admitted for target.agentId; this helper grants no authority.
+ */
+export declare function controlAgentScheduleWithContent(owner: Pick<ShiitakeAgent, "extensions">, input: AgentScheduleTarget, action: "pause" | "delete"): Promise<AgentScheduleRow>;
+/** Control an already-admitted owner; manage-only callers receive no read content. */
+export declare function controlAgentSchedule(owner: Pick<ShiitakeAgent, "extensions">, target: AgentScheduleTarget, action: "pause" | "delete"): Promise<AgentScheduleControlReceipt>;