@fungi.computer/shiitake-extensions 0.4.0 → 0.6.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.
@@ -181,7 +180,10 @@ reason; the host can resume it without inventing a separate background loop.
 
 ## API reference and examples
 
-This package documents contracts beside source and has no generated API command.
+The [generated API reference](docs/api/README.md) follows the public
+entrypoints. Run `pnpm --dir packages/shiitake-extensions run docs:write` from
+the repository root after changing them, then
+`pnpm --dir packages/shiitake-extensions run docs` to check consistency.
 [package.json](package.json) owns these exported subpaths:
 
 | Entry                                          | Source                                                                                                    |
@@ -197,6 +199,8 @@ This package documents contracts beside source and has no generated API command.
 | `/subagents/client`                            | [Subagents client entry](src/subagents/client.ts).                                                        |
 | `/goal/client`, `/loop/client`, `/plan/client` | Client entries for [Goal](src/goal/client.ts), [Loop](src/loop/client.ts) and [Plan](src/plan/client.ts). |
 | `/roster`                                      | [Product roster and grants](src/roster.ts).                                                               |
+| `/schedules`                                   | [Schema-only schedule pages, targets and receipts](src/schedules.ts).                                     |
+| `/schedules/client`                            | [Native schedule reads and controls](src/schedules/client.ts).                                            |
 
 [Loop tests](test/loop.test.ts) exercise scheduling and mid-run pause.
 [Almanac tests](test/almanac.test.ts) exercise admission and retry.
@@ -204,6 +208,15 @@ This package documents contracts beside source and has no generated API command.
 These fixtures use the actual extension definitions on Shiitake with fake
 models.
 
+### Schedule consumers
+
+Use `/schedules` for schedule schemas and types in an App bundle. It imports the
+retained Almanac and Loop data schemas, not their native invocation clients.
+Native host integrations use `/schedules/client` for `readAgentSchedulePage`,
+`controlAgentSchedule` and `controlAgentScheduleWithContent` on an already
+admitted Agent owner. These helpers own no admission policy, store or scheduler.
+Reading and management remain separately admitted by the host.
+
 ## Home
 
 The host creates `homeExtension({ computers })`, where `computers.read()`

package/dist/almanac/contract.d.ts

@@ -1,32 +1,5 @@
 import * as Schema from "effect/Schema";
-/** One durable schedule as every caller sees it. */
-export declare const Schedule: Schema.Struct<{
-    /** Caller-chosen schedule identity. */
-    readonly id: Schema.String;
-    /** Session that receives each scheduled prompt. */
-    readonly sessionId: Schema.String;
-    /** Original prompt submitted to the destination Session. */
-    readonly prompt: Schema.String;
-    /** Cron expression and zone for a recurring schedule; null for one-shot. */
-    readonly cron: Schema.NullOr<Schema.Struct<{
-        /** Cron expression used to calculate occurrences. */
-        readonly expression: Schema.String;
-        /** IANA time zone in which the expression is evaluated. */
-        readonly timeZone: Schema.String;
-    }>>;
-    /** The occurrence that fires next (or fired last, once finished). */
-    readonly nextDueAt: Schema.Int;
-    /** Current scheduling lifecycle state. */
-    readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-    /** Latest command admitted for this schedule. */
-    readonly lastCommandId: Schema.NullOr<Schema.String>;
-    /** Why the current occurrence has not been admitted yet, if it failed. */
-    readonly lastError: Schema.NullOr<Schema.String>;
-    /** Consecutive failed admissions of the current occurrence. */
-    readonly attempt: Schema.Int;
-}>;
-/** One durable schedule. */
-export type Schedule = Schema.Schema.Type<typeof Schedule>;
+export { Schedule } from "./schema.js";
 /** Almanac's contract: agent-scope schedule CRUD, no Session projection. */
 export declare const almanacContract: {
     /** Stable extension identity. */
@@ -50,28 +23,17 @@ export declare const almanacContract: {
             }>;
             /** Return the created durable schedule. */
             readonly output: Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>;
         };
@@ -94,28 +56,17 @@ export declare const almanacContract: {
             }>;
             /** Return the created durable schedule. */
             readonly output: Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>;
         };
@@ -130,28 +81,17 @@ export declare const almanacContract: {
             }>;
             /** Decode the schedule or its absence. */
             readonly output: Schema.NullOr<Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>>;
         };
@@ -161,35 +101,22 @@ export declare const almanacContract: {
             readonly scope: "agent";
             /** Decode pagination arguments. */
             readonly input: Schema.Struct<{
-                /** Exclusive schedule cursor. */
                 readonly after: Schema.optionalKey<Schema.String>;
-                /** Maximum number of schedules returned. */
                 readonly limit: Schema.optionalKey<Schema.Int>;
             }>;
             /** Decode the returned schedule rows. */
             readonly output: Schema.$Array<Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>>;
         };
@@ -204,28 +131,17 @@ export declare const almanacContract: {
             }>;
             /** Return its updated state. */
             readonly output: Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>;
         };
@@ -240,28 +156,17 @@ export declare const almanacContract: {
             }>;
             /** Return its updated state. */
             readonly output: Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>;
         };
@@ -276,28 +181,17 @@ export declare const almanacContract: {
             }>;
             /** Return its updated state. */
             readonly output: Schema.Struct<{
-                /** Caller-chosen schedule identity. */
                 readonly id: Schema.String;
-                /** Session that receives each scheduled prompt. */
                 readonly sessionId: Schema.String;
-                /** Original prompt submitted to the destination Session. */
                 readonly prompt: Schema.String;
-                /** Cron expression and zone for a recurring schedule; null for one-shot. */
                 readonly cron: Schema.NullOr<Schema.Struct<{
-                    /** Cron expression used to calculate occurrences. */
                     readonly expression: Schema.String;
-                    /** IANA time zone in which the expression is evaluated. */
                     readonly timeZone: Schema.String;
                 }>>;
-                /** The occurrence that fires next (or fired last, once finished). */
                 readonly nextDueAt: Schema.Int;
-                /** Current scheduling lifecycle state. */
                 readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
-                /** Latest command admitted for this schedule. */
                 readonly lastCommandId: Schema.NullOr<Schema.String>;
-                /** Why the current occurrence has not been admitted yet, if it failed. */
                 readonly lastError: Schema.NullOr<Schema.String>;
-                /** Consecutive failed admissions of the current occurrence. */
                 readonly attempt: Schema.Int;
             }>;
         };

package/dist/almanac/contract.js

@@ -1,44 +1,13 @@
 import { ExtensionId } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
+import { Prompt, SessionId } from "../internal/schedule-fields.js";
+import { ScheduleId, Instant, CronExpression, TimeZone, Schedule, ScheduleListInput, } from "./schema.js";
+export { Schedule } from "./schema.js";
 /**
  * Almanac: durable one-shot and cron schedules that send ordinary Session
  * prompts. This contract is shared by the server extension and its clients;
  * its schemas are the only decoders of Almanac values.
  */
-/** Caller-chosen schedule identity; also its create idempotency key. */
-const ScheduleId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(200)), Schema.check(Schema.isPattern(/^[A-Za-z0-9._:-]+$/u)));
-const SessionId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
-/** Human prompt grammar; the admission door re-checks the exact byte bound. */
-const Prompt = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256 * 1024)));
-const Instant = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
-const CronExpression = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
-const TimeZone = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128)));
-/** One durable schedule as every caller sees it. */
-export const Schedule = Schema.Struct({
-    /** Caller-chosen schedule identity. */
-    id: ScheduleId,
-    /** Session that receives each scheduled prompt. */
-    sessionId: SessionId,
-    /** Original prompt submitted to the destination Session. */
-    prompt: Prompt,
-    /** Cron expression and zone for a recurring schedule; null for one-shot. */
-    cron: Schema.NullOr(Schema.Struct({
-        /** Cron expression used to calculate occurrences. */
-        expression: CronExpression,
-        /** IANA time zone in which the expression is evaluated. */
-        timeZone: TimeZone,
-    })),
-    /** The occurrence that fires next (or fired last, once finished). */
-    nextDueAt: Instant,
-    /** Current scheduling lifecycle state. */
-    state: Schema.Literals(["active", "paused", "cancelled", "finished"]),
-    /** Latest command admitted for this schedule. */
-    lastCommandId: Schema.NullOr(Schema.String),
-    /** Why the current occurrence has not been admitted yet, if it failed. */
-    lastError: Schema.NullOr(Schema.String),
-    /** Consecutive failed admissions of the current occurrence. */
-    attempt: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
-});
 const ScheduleRef = Schema.Struct({
     /** Existing schedule targeted by the command. */
     scheduleId: ScheduleId,
@@ -101,12 +70,7 @@ export const almanacContract = {
             /** Read from the Agent's schedule collection. */
             scope: "agent",
             /** Decode pagination arguments. */
-            input: Schema.Struct({
-                /** Exclusive schedule cursor. */
-                after: Schema.optionalKey(ScheduleId),
-                /** Maximum number of schedules returned. */
-                limit: Schema.optionalKey(Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 64 })))),
-            }),
+            input: ScheduleListInput,
             /** Decode the returned schedule rows. */
             output: Schema.Array(Schedule),
         },

package/dist/almanac/schema.d.ts

@@ -0,0 +1,41 @@
+import * as Schema from "effect/Schema";
+/** Caller-chosen schedule identity; also its create idempotency key. */
+export declare const ScheduleId: Schema.String;
+export declare const Instant: Schema.Int;
+export declare const CronExpression: Schema.String;
+export declare const TimeZone: Schema.String;
+/** One durable schedule as every caller sees it. */
+export declare const Schedule: Schema.Struct<{
+    /** Caller-chosen schedule identity. */
+    readonly id: Schema.String;
+    /** Session that receives each scheduled prompt. */
+    readonly sessionId: Schema.String;
+    /** Original prompt submitted to the destination Session. */
+    readonly prompt: Schema.String;
+    /** Cron expression and zone for a recurring schedule; null for one-shot. */
+    readonly cron: Schema.NullOr<Schema.Struct<{
+        /** Cron expression used to calculate occurrences. */
+        readonly expression: Schema.String;
+        /** IANA time zone in which the expression is evaluated. */
+        readonly timeZone: Schema.String;
+    }>>;
+    /** The occurrence that fires next (or fired last, once finished). */
+    readonly nextDueAt: Schema.Int;
+    /** Current scheduling lifecycle state. */
+    readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+    /** Latest command admitted for this schedule. */
+    readonly lastCommandId: Schema.NullOr<Schema.String>;
+    /** Why the current occurrence has not been admitted yet, if it failed. */
+    readonly lastError: Schema.NullOr<Schema.String>;
+    /** Consecutive failed admissions of the current occurrence. */
+    readonly attempt: Schema.Int;
+}>;
+/** One durable schedule. */
+export type Schedule = Schema.Schema.Type<typeof Schedule>;
+/** Native bounded Almanac page grammar, also used by shared continuations. */
+export declare const ScheduleListInput: Schema.Struct<{
+    /** Exclusive schedule cursor. */
+    readonly after: Schema.optionalKey<Schema.String>;
+    /** Maximum number of schedules returned. */
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;

package/dist/almanac/schema.js

@@ -0,0 +1,40 @@
+import * as Schema from "effect/Schema";
+import { Prompt, SessionId } from "../internal/schedule-fields.js";
+/** Caller-chosen schedule identity; also its create idempotency key. */
+export const ScheduleId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(200)), Schema.check(Schema.isPattern(/^[A-Za-z0-9._:-]+$/u)));
+export const Instant = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+export const CronExpression = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
+export const TimeZone = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128)));
+/** One durable schedule as every caller sees it. */
+export const Schedule = Schema.Struct({
+    /** Caller-chosen schedule identity. */
+    id: ScheduleId,
+    /** Session that receives each scheduled prompt. */
+    sessionId: SessionId,
+    /** Original prompt submitted to the destination Session. */
+    prompt: Prompt,
+    /** Cron expression and zone for a recurring schedule; null for one-shot. */
+    cron: Schema.NullOr(Schema.Struct({
+        /** Cron expression used to calculate occurrences. */
+        expression: CronExpression,
+        /** IANA time zone in which the expression is evaluated. */
+        timeZone: TimeZone,
+    })),
+    /** The occurrence that fires next (or fired last, once finished). */
+    nextDueAt: Instant,
+    /** Current scheduling lifecycle state. */
+    state: Schema.Literals(["active", "paused", "cancelled", "finished"]),
+    /** Latest command admitted for this schedule. */
+    lastCommandId: Schema.NullOr(Schema.String),
+    /** Why the current occurrence has not been admitted yet, if it failed. */
+    lastError: Schema.NullOr(Schema.String),
+    /** Consecutive failed admissions of the current occurrence. */
+    attempt: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+});
+/** Native bounded Almanac page grammar, also used by shared continuations. */
+export const ScheduleListInput = Schema.Struct({
+    /** Exclusive schedule cursor. */
+    after: Schema.optionalKey(ScheduleId),
+    /** Maximum number of schedules returned. */
+    limit: Schema.optionalKey(Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 64 })))),
+});

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/internal/schedule-fields.d.ts

@@ -0,0 +1,5 @@
+import * as Schema from "effect/Schema";
+/** Native Session address shared by Almanac and Loop inputs and rows. */
+export declare const SessionId: Schema.String;
+/** Human prompt grammar; the admission door re-checks the exact byte bound. */
+export declare const Prompt: Schema.String;

package/dist/internal/schedule-fields.js

@@ -0,0 +1,5 @@
+import * as Schema from "effect/Schema";
+/** Native Session address shared by Almanac and Loop inputs and rows. */
+export const SessionId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
+/** Human prompt grammar; the admission door re-checks the exact byte bound. */
+export const Prompt = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256 * 1024)));