@fungi.computer/shiitake-extensions 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# Shiitake product extensions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@fungi.computer/shiitake-extensions` supplies Fungi's questions, goals, loops,
+plans, Almanac schedules, skills and Home. Hub and Local choose the shared
+roster and explicitly grant its capabilities. Shiitake core supplies the generic
+extension API.
+
+## Set up
+
+This is a package for host and client maintainers. Use its exported subpaths
+from the configured workspace, not an invented npm install. From the repository
+root:
+
+```sh
+pnpm turbo:run run build --filter=@fungi.computer/shiitake-extensions
+```
+
+A host passes `botanicalAgentExtensions` as its Shiitake `extensions` option. It
+still supplies the SQLite owner, runtime wake, model and instruction sources and
+any tools sandbox. The roster does not supply provider credentials or resource
+permissions.
+
+A Local host uses `botanicalExtensionsWithSkills(source)` instead. The read-only
+`SkillSource` owns discovery and file access. `skillsExtension({source})` uses
+the `prompt`, `run_tools` and `commands` grants: metadata enters the prompt,
+while `skill.load({name, file?})` returns the body or a supporting file through
+the existing `execute` tool. It is a forage operation, not a top-level tool. The
+human `/skills` command lists each discovered skill beside its `SKILL.md` path,
+plus the reasons other entries were not loaded; choosing one shows its
+description. Commands run inside a synchronous core transaction, so `/skills`
+reads the latest discovery, taken at activation and before each model request.
+Empty catalogs say that no skills are installed; invalid entries report a
+redacted cause. Tool discovery summaries stay within Forage's metadata bounds
+and mark shortened listings; the prompt still lists every admitted skill. The
+Hub uses the shared roster without Skills and adds its own scoped Home
+extension.
+
+## Quick start: read the committed goal
+
+Illustrative: this helper receives an already open Agent with the product roster
+and reads the goal slot for one Session. A fresh Session has no goal value. The
+helper requests neither model work nor a goal mutation.
+
+```ts
+import {
+  bindSessionExtension,
+  type ShiitakeAgent,
+} from "@fungi.computer/shiitake/client";
+import { goalContract } from "@fungi.computer/shiitake-extensions/goal";
+import { botanicalAgentExtensions } from "@fungi.computer/shiitake-extensions/roster";
+
+export const extensions = botanicalAgentExtensions;
+
+export async function readGoal(agent: ShiitakeAgent) {
+  const session = agent.session("example-session");
+  const goal = bindSessionExtension(session, goalContract);
+  return goal.view(await session.read());
+}
+```
+
+The bound view distinguishes `unavailable`, `stopped` with a reason, and
+`running` with a value or `null`. Existing [goal tests](test/goal.test.ts) bind
+that same contract, read observed state, issue commands and close the owner. The
+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 objective per Session. The model creates, reads and completes it through `goal.*` tools; humans set, pause, resume or clear it. Three tool-less continuations pause it as stalled.                                                                                                                                                                                                                                                            |
+| 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. 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
+messages receive the Goal context without that directive. Both sections are
+bounded by UTF-8 bytes. Correlated Goal turns appear as compact transcript
+notes; other extensions keep their own display policy.
+
+Known limitation: Session forks copy transcript entries without their original
+command-admission rows. Inherited Goal turns therefore lose the extension-origin
+metadata used for compact notes and appear as ordinary message bubbles.
+
+Goal pause stops continuation, not already accepted work. Model-requested
+completion or blocking is provisional until successful settlement. Human
+replacement uses the observed revision to avoid replacing a newer goal.
+
+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.
+`loop.schedule_next` is accepted only in the active self-paced loop's own run;
+omitting it ends that loop. A fixed cadence uses the core timer and expires
+seven days after it starts. Almanac retries a failed admission per schedule, so
+one refused occurrence does not become another schedule's failure. Use the
+recorded error and the owner's resume command when recovering.
+
+The human `/goal`, `/loop` and `/plan` flows are advertised as
+`whistle.catalog/v1` catalogs. A compatible client renders the same server-owned
+interactions. A human command catalog, a per-run tool module and model tool
+discovery are separate contracts. Inspect the host's exposed tool catalog before
+relying on a model-facing operation.
+
+## State and lifetime
+
+### Question
+
+`question.ask` creates one to four decision questions. Its namespace is
+`question`, and its extension identity is `botanical-session-question`. Inspect
+`forage.describe({path: "question.ask"}).inputSchema` for the validated bounds,
+including the 12-character question header. A waiting call receives the human's
+answer in-turn; `mode: "continue"` parks it and returns its `askId`. The live
+wait leaves sixty seconds of the actual execute deadline and is capped at ten
+minutes. Pending steering also parks the question so Mule can deliver the steer.
+Each Session holds at most four open Asks, with one live Ask per run.
+
+Bind `questionContract` from `/question` with `bindSessionExtension` to read its
+decoded projection and call `list`, `answer` or `decline`. Human responses
+include an `askId` and a stable `requestId`. Reuse that request identity after
+an uncertain response: an exact retry returns its original receipt, while a
+changed payload conflicts. Answer every question with offered labels or nonempty
+free text. The model has no answer operation.
+
+The `/answer` catalog conversation selects a waiting Ask and collects an answer
+for each question. Multiple selections use comma-separated labels; quote a label
+that contains a comma. Every choice also permits free text.
+
+Optional `onExpire` specifies `afterMinutes` (5 through 10,080) and an action:
+`stop` explicitly tells the model not to proceed; `proceed_with_recommended`
+selects the first option of each question. A parked answer or expiry admits one
+self-contained follow-up. The Ask owner clears attention when it closes, and the
+live waiter and durable timer share the same expiry transition. Restart recovery
+reconciles committed answers before allowing another delivery. An in-turn answer
+retains its delivery receipt until Mule saves a successful tool outcome. If a
+crash loses that outcome and no re-ask receives it, settlement sends the answer
+once as a follow-up. A cancelled run suppresses that redelivery.
+
+Client cards, goal/loop attention policy and external notifications are separate
+contributions; the Ask owner alone does not provide those surfaces.
+
+### Owner transactions
+
+Collections are namespaced to the extension. Schema, version, migrations and
+configuration contribute to its revision. Settled hooks, timer hooks and command
+handlers commit through core transactions. They must finish synchronously and
+must not perform external I/O.
+
+Extensions send prompts through the accepted-command door and wake through core
+timers. An accepted prompt is queued work, not a finished model reply. Core owns
+replay cursors and publication after commit. A stopped extension exposes its
+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.
+[package.json](package.json) owns these exported subpaths:
+
+| Entry                                          | Source                                                                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `/goal`, `/goal/host`                          | [Goal contract](src/goal/contract.ts) and [definition](src/goal/host.ts).                                 |
+| `/loop`, `/loop/host`                          | [Loop contract](src/loop/contract.ts) and [definition](src/loop/host.ts).                                 |
+| `/almanac`, `/almanac/host`                    | [Schedule contract](src/almanac/contract.ts) and [definition](src/almanac/host.ts).                       |
+| `/home`, `/home/host`                          | [Home contract](src/home/contract.ts) and [definition](src/home/host.ts).                                 |
+| `/question`, `/question/host`                  | [Question contract](src/question/contract.ts) and [definition](src/question/host.ts).                     |
+| `/plan`, `/plan/host`                          | [Plan contract](src/plan/contract.ts) and [definition](src/plan/host.ts).                                 |
+| `/skills`, `/skills/source`                    | [Skills definition](src/skills/host.ts) and [host-owned source](src/skills/source.ts).                    |
+| `/subagents`, `/subagents/host`                | [Subagents contract](src/subagents/contract.ts) and [definition](src/subagents/host.ts).                  |
+| `/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).                                                               |
+
+[Loop tests](test/loop.test.ts) exercise scheduling and mid-run pause.
+[Almanac tests](test/almanac.test.ts) exercise admission and retry.
+[Catalog tests](test/catalog.test.ts) check the human interaction contracts.
+These fixtures use the actual extension definitions on Shiitake with fake
+models.
+
+## Home
+
+The host creates `homeExtension({ computers })`, where `computers.read()`
+synchronously returns the current attachments as `{ name, attachmentId, port }`.
+Each `port` is already scoped to that attachment by the host. Home never creates
+credentials or bypasses the host gate. Add the returned extension and its
+exported `homeGrant` (`state`, `files`, `prompt`, `projection`, `commands`).
+Home is composed by the host, not included in `botanicalAgentExtensions`. The
+Hub and demo add it with their own Computer ports and grants.
+
+Home records one Agent-scope attachment choice. With no recorded choice, a run
+adopts a sole attachment once. Zero or multiple attachments require a person to
+choose `/home <name>`. Removing the chosen attachment keeps the choice and
+offers no direct file tools until a person chooses again. Reordering attachments
+never changes Home. The Session command changes Agent state, so other Sessions
+see that choice on their next run.
+
+Each run captures its table, Home and prompt once. The tools are Knapsack's
+branded `read`, `list`, `glob` and `grep`, with `apply_patch` only when Home's
+port has a native patch engine. Bare paths and `computer://home/` use Home;
+`computer://<name>/` uses another captured attachment. Patches always use Home's
+native engine and path jail. Returned file identity stays owned by the scoped
+port. There is no Home model tool and no shared Files module.
+
+The Agent-scope `seed` command is an unadvertised host migration operation. It
+records an old attachment id only when no choice exists, including when that
+attachment is detached; subsequent seed calls cannot overwrite a human choice.
+Hosts keep the control door human/operator-authorized.
+[Home tests](test/home.test.ts) exercise selection, capture, detachment, routing
+and gating on real Shiitake.
+
+## Limits and errors
+
+A roster entry is not an external-resource grant. The host still admits each
+operation and owns its current Team, Computer and credential policy. A command
+conflict requires a fresh observation; retry an uncertain request with the same
+identity. A view with no goal is not evidence that a previous goal completed.
+Closing a client view does not pause the goal, stop a loop or cancel a schedule.
+
+## Contribute and license
+
+Add regressions beside the owning extension or catalog. From the root:
+
+```sh
+pnpm --dir packages/shiitake-extensions run test
+pnpm --dir packages/shiitake-extensions run typecheck
+```
+
+MIT. See [LICENSE](LICENSE).
+
+## TypeScript consumer dependencies
+
+Install `@modelcontextprotocol/sdk@1.25.2` alongside this package when compiling
+its complete public declarations. The shared provider SDK imports those types
+through an optional peer; the packed consumer supplies it explicitly. This does
+not require a provider account or make a provider call.
+
+## Subagents
+
+The host creates `subagentsExtension({ source })` and adds `subagentsGrant`
+(`projection` only). `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.
+
+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
+until nobody has read the parent for thirty seconds. Like Home, the extension is
+composed by the host, not included in `botanicalAgentExtensions`.
+
+## Packed consumer readiness
+
+Run `pnpm run build`, `pnpm run pack` and `pnpm run stranger` in this package.
+The maintained stranger proof installs only package tarballs into a fresh npm
+consumer, checks the exact shipped files, runs the public runtime fixture and
+compiles every JavaScript entrypoint with strict NodeNext and no library-check
+skip. This qualification does not publish npm releases or push a repository
+split.
+
+See [LICENSE](LICENSE) for the license and the package manifest for its public
+repository destination.

package/dist/almanac/contract.d.ts

@@ -0,0 +1,213 @@
+import * as Schema from "effect/Schema";
+/** One durable schedule as every caller sees it. */
+export declare const Schedule: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly prompt: Schema.String;
+    /** Cron expression and zone for a recurring schedule; null for one-shot. */
+    readonly cron: Schema.NullOr<Schema.Struct<{
+        readonly expression: Schema.String;
+        readonly timeZone: Schema.String;
+    }>>;
+    /** The occurrence that fires next (or fired last, once finished). */
+    readonly nextDueAt: Schema.Int;
+    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>;
+/** Almanac's contract: agent-scope schedule CRUD, no Session projection. */
+export declare const almanacContract: {
+    readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
+    readonly commands: {
+        readonly createOneShot: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly requestId: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                readonly dueAt: Schema.Int;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>;
+        };
+        readonly createRecurring: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly requestId: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                readonly expression: Schema.String;
+                readonly timeZone: Schema.String;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>;
+        };
+        readonly read: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly scheduleId: Schema.String;
+            }>;
+            readonly output: Schema.NullOr<Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>>;
+        };
+        readonly list: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly after: Schema.optionalKey<Schema.String>;
+                readonly limit: Schema.optionalKey<Schema.Int>;
+            }>;
+            readonly output: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>>;
+        };
+        readonly pause: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly scheduleId: Schema.String;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>;
+        };
+        readonly resume: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly scheduleId: Schema.String;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>;
+        };
+        readonly cancel: {
+            readonly scope: "agent";
+            readonly input: Schema.Struct<{
+                readonly scheduleId: Schema.String;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly id: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly prompt: Schema.String;
+                /** Cron expression and zone for a recurring schedule; null for one-shot. */
+                readonly cron: Schema.NullOr<Schema.Struct<{
+                    readonly expression: Schema.String;
+                    readonly timeZone: Schema.String;
+                }>>;
+                /** The occurrence that fires next (or fired last, once finished). */
+                readonly nextDueAt: Schema.Int;
+                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;
+            }>;
+        };
+    };
+    readonly projection: null;
+};

package/dist/almanac/contract.js

@@ -0,0 +1,77 @@
+import { ExtensionId } from "@fungi.computer/shiitake/extensions";
+import * as Schema from "effect/Schema";
+/**
+ * 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({
+    id: ScheduleId,
+    sessionId: SessionId,
+    prompt: Prompt,
+    /** Cron expression and zone for a recurring schedule; null for one-shot. */
+    cron: Schema.NullOr(Schema.Struct({ expression: CronExpression, timeZone: TimeZone })),
+    /** The occurrence that fires next (or fired last, once finished). */
+    nextDueAt: Instant,
+    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({ scheduleId: ScheduleId });
+/** Almanac's contract: agent-scope schedule CRUD, no Session projection. */
+export const almanacContract = {
+    id: ExtensionId.make("botanical-almanac"),
+    commands: {
+        createOneShot: {
+            scope: "agent",
+            input: Schema.Struct({
+                requestId: ScheduleId,
+                sessionId: SessionId,
+                prompt: Prompt,
+                dueAt: Instant,
+            }),
+            output: Schedule,
+        },
+        createRecurring: {
+            scope: "agent",
+            input: Schema.Struct({
+                requestId: ScheduleId,
+                sessionId: SessionId,
+                prompt: Prompt,
+                expression: CronExpression,
+                timeZone: TimeZone,
+            }),
+            output: Schedule,
+        },
+        read: {
+            scope: "agent",
+            input: ScheduleRef,
+            output: Schema.NullOr(Schedule),
+        },
+        list: {
+            scope: "agent",
+            input: Schema.Struct({
+                after: Schema.optionalKey(ScheduleId),
+                limit: Schema.optionalKey(Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 64 })))),
+            }),
+            output: Schema.Array(Schedule),
+        },
+        pause: { scope: "agent", input: ScheduleRef, output: Schedule },
+        resume: { scope: "agent", input: ScheduleRef, output: Schedule },
+        cancel: { scope: "agent", input: ScheduleRef, output: Schedule },
+    },
+    projection: null,
+};

package/dist/almanac/host.d.ts

@@ -0,0 +1,3 @@
+import { type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
+/** Botanical's Almanac on Shiitake timers and the one admission door. */
+export declare const almanacExtension: RosteredExtensionV0;