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

package/dist/almanac/host.js

@@ -0,0 +1,171 @@
+import { defineCollection, defineExtension, ExtensionCommandError, } from "@fungi.computer/shiitake/extensions";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Option from "effect/Option";
+import { afterAdmitted, afterRefused, cancelled, occurrenceKey, paused, resumed, settled, } from "@fungi.computer/almanac";
+import { nextOccurrence } from "../internal/cron.js";
+import { almanacContract, Schedule } from "./contract.js";
+/** Hashed policy: every constant Almanac reads comes from here. */
+const config = {
+    /** First retry delay after a failed occurrence admission. */
+    retryBaseMs: 30_000,
+    /** Longest retry delay; one poisoned schedule never blocks the others. */
+    retryMaxMs: 3_600_000,
+};
+const collections = {
+    schedules: defineCollection(Schedule, {
+        key: (schedule) => schedule.id,
+        index: (schedule) => schedule.state,
+    }),
+};
+function rejected(reason, message) {
+    return new ExtensionCommandError({ reason, message });
+}
+function requireSchedule(ctx, id) {
+    return ctx.state.schedules.get(id).pipe(Effect.flatMap(Option.match({
+        onNone: () => Effect.fail(rejected("not_found", "Almanac schedule does not exist")),
+        onSome: Effect.succeed,
+    })));
+}
+function sameSchedule(left, right) {
+    return (left.sessionId === right.sessionId &&
+        left.prompt === right.prompt &&
+        left.cron?.expression === right.cron?.expression &&
+        left.cron?.timeZone === right.cron?.timeZone &&
+        (left.cron !== null || left.nextDueAt === right.nextDueAt));
+}
+/** Create or replay one schedule; its request id is its identity. */
+function create(ctx, schedule) {
+    return Effect.gen(function* () {
+        const existing = yield* ctx.state.schedules.get(schedule.id);
+        if (Option.isSome(existing)) {
+            if (sameSchedule(existing.value, schedule))
+                return existing.value;
+            return yield* Effect.fail(rejected("conflict", "Schedule id is already used by another schedule"));
+        }
+        yield* ctx.state.schedules.put(schedule);
+        yield* ctx.timers.set(schedule.id, schedule.nextDueAt);
+        return schedule;
+    });
+}
+/**
+ * Send the due occurrence through the door. The occurrence request id is
+ * `id:occurrenceAt`, so a retried admission replays instead of duplicating.
+ * A refused admission is this schedule's own visible state: it records the
+ * error and backs off; it never stops Almanac or delays other schedules.
+ */
+function fire(ctx, id, now) {
+    return Effect.gen(function* () {
+        const found = yield* ctx.state.schedules.get(id);
+        if (Option.isNone(found) || found.value.state !== "active")
+            return;
+        const schedule = found.value;
+        const admitted = yield* Effect.result(ctx.send({
+            sessionId: schedule.sessionId,
+            requireExistingSession: schedule.lastCommandId !== null,
+            when: "now",
+            correlation: schedule.id,
+            prompt: {
+                text: schedule.prompt,
+                requestId: occurrenceKey(schedule),
+                delivery: "followUp",
+            },
+        }));
+        if (Result.isFailure(admitted) || admitted.success._tag === "NotReady") {
+            const refused = afterRefused(schedule, now, Result.isFailure(admitted)
+                ? admitted.failure.message
+                : "Session did not accept the occurrence", { baseMs: config.retryBaseMs, maxMs: config.retryMaxMs });
+            yield* ctx.state.schedules.put(refused.schedule);
+            yield* ctx.timers.set(schedule.id, refused.retryAt);
+            return;
+        }
+        const next = afterAdmitted({ ...schedule, lastCommandId: admitted.success.commandId }, now);
+        yield* ctx.state.schedules.put(next);
+        if (next.state === "active")
+            yield* ctx.timers.set(schedule.id, next.nextDueAt);
+    });
+}
+/** Botanical's Almanac on Shiitake timers and the one admission door. */
+export const almanacExtension = defineExtension({
+    id: almanacContract.id,
+    version: "1.1.0",
+})
+    .config(config)
+    .state({ version: 1, migrations: {}, collections })
+    .define({
+    hooks: { onTimer: (ctx, timer) => fire(ctx, timer.key, timer.firedAt) },
+    commands: {
+        specs: almanacContract.commands,
+        handlers: (ctx) => ({
+            createOneShot: ({ input }) => create(ctx, {
+                id: input.requestId,
+                sessionId: input.sessionId,
+                prompt: input.prompt,
+                cron: null,
+                nextDueAt: input.dueAt,
+                state: "active",
+                lastCommandId: null,
+                lastError: null,
+                attempt: 0,
+            }),
+            createRecurring: ({ input }) => Effect.gen(function* () {
+                const cron = {
+                    expression: input.expression,
+                    timeZone: input.timeZone,
+                };
+                const now = yield* Clock.currentTimeMillis;
+                return yield* create(ctx, {
+                    id: input.requestId,
+                    sessionId: input.sessionId,
+                    prompt: input.prompt,
+                    cron,
+                    nextDueAt: yield* nextOccurrence(cron, now),
+                    state: "active",
+                    lastCommandId: null,
+                    lastError: null,
+                    attempt: 0,
+                });
+            }),
+            read: ({ input }) => ctx.state.schedules
+                .get(input.scheduleId)
+                .pipe(Effect.map(Option.getOrNull)),
+            list: ({ input }) => ctx.state.schedules.page({
+                after: input.after,
+                limit: input.limit ?? 64,
+            }),
+            pause: ({ input }) => Effect.gen(function* () {
+                const schedule = yield* requireSchedule(ctx, input.scheduleId);
+                if (settled(schedule))
+                    return yield* Effect.fail(rejected("conflict", "A settled schedule cannot be paused"));
+                const next = paused(schedule);
+                yield* ctx.state.schedules.put(next);
+                yield* ctx.timers.cancel(schedule.id);
+                return next;
+            }),
+            resume: ({ input }) => Effect.gen(function* () {
+                const schedule = yield* requireSchedule(ctx, input.scheduleId);
+                if (settled(schedule))
+                    return yield* Effect.fail(rejected("conflict", "A settled schedule cannot be resumed"));
+                const now = yield* Clock.currentTimeMillis;
+                // A human resume is the retry: it clears the failure and skips
+                // recurring occurrences missed while paused.
+                const back = resumed(schedule, now);
+                if (Result.isFailure(back))
+                    return yield* Effect.fail(rejected("invalid", back.failure.message));
+                yield* ctx.state.schedules.put(back.success);
+                yield* ctx.timers.set(schedule.id, back.success.nextDueAt);
+                return back.success;
+            }),
+            cancel: ({ input }) => Effect.gen(function* () {
+                const schedule = yield* requireSchedule(ctx, input.scheduleId);
+                if (settled(schedule))
+                    return schedule;
+                const next = cancelled(schedule);
+                yield* ctx.state.schedules.put(next);
+                yield* ctx.timers.cancel(schedule.id);
+                return next;
+            }),
+        }),
+    },
+});

package/dist/goal/client.d.ts

@@ -0,0 +1,10 @@
+import { type ClientContributionV1 } from "@fungi.computer/shiitake/client-entry";
+/** Product copy and controls belong to Goal; every host renders plain rows. */
+declare const _default: Readonly<{
+    protocol: "shiitake.client/v1";
+    id: import("@fungi.computer/shiitake/extensions").ExtensionId;
+    correlatedPrompts?: "note";
+    attach?: (context: import("@fungi.computer/shiitake/client-entry").ClientExtensionContextV1) => import("effect/Effect").Effect<void, Error, import("effect/Scope").Scope>;
+    contribute?: (slot: import("@fungi.computer/shiitake").ExtensionSlotV0 | undefined) => ClientContributionV1;
+}>;
+export default _default;

package/dist/goal/client.js

@@ -0,0 +1,88 @@
+import { defineClientEntry, } from "@fungi.computer/shiitake/client-entry";
+import { goalContract } from "./contract.js";
+const tone = (goal) => goal.state === "blocked"
+    ? "error"
+    : goal.state === "complete"
+        ? "settled"
+        : goal.state === "paused"
+            ? "muted"
+            : "running";
+/** Product copy and controls belong to Goal; every host renders plain rows. */
+export default defineClientEntry(goalContract, {
+    correlatedPrompts: "note",
+    contribute: (view) => {
+        if (view.status !== "running" || view.value === null)
+            return {
+                chips: [],
+                panel: [],
+                timeline: { cells: [], omitted: 0 },
+                waiting: null,
+            };
+        const { goal, history } = view.value;
+        const panel = [];
+        if (goal !== null) {
+            const row = {
+                id: "goal",
+                title: goal.objective,
+                detail: `Goal · ${goal.state}`,
+                tone: tone(goal),
+            };
+            panel.push(goal.state === "active" || goal.state === "paused"
+                ? {
+                    ...row,
+                    actions: [
+                        {
+                            id: "goal",
+                            label: goal.state === "active" ? "Pause goal" : "Resume goal",
+                            input: {
+                                action: goal.state === "active" ? "pause" : "resume",
+                            },
+                        },
+                    ],
+                }
+                : row);
+            if (goal.stopReason !== null)
+                panel.push({
+                    id: "reason",
+                    title: goal.stopReason.slice(0, 4096),
+                    tone: "attention",
+                });
+        }
+        return {
+            chips: goal === null
+                ? []
+                : [
+                    {
+                        id: "goal",
+                        order: 1,
+                        row: {
+                            id: "goal",
+                            title: `Goal ${goal.state}${goal.stopReason?.startsWith("Stalled:") ? ": stalled" : ""}`,
+                            tone: tone(goal),
+                        },
+                    },
+                ],
+            panel,
+            timeline: {
+                omitted: history.omitted,
+                cells: history.events.map(({ event, ...cell }) => ({
+                    ...cell,
+                    rows: [
+                        { id: "state", title: `Goal ${event.state}`, tone: tone(event) },
+                        { id: "objective", title: event.objective },
+                        ...(event.stopReason === null
+                            ? []
+                            : [
+                                {
+                                    id: "reason",
+                                    title: event.stopReason.slice(0, 4096),
+                                    tone: tone(event),
+                                },
+                            ]),
+                    ],
+                })),
+            },
+            waiting: null,
+        };
+    },
+});

package/dist/goal/contract.d.ts

@@ -0,0 +1,172 @@
+import * as Schema from "effect/Schema";
+/**
+ * Session goal: one durable objective per Session that Shiitake keeps
+ * working toward until the model reports it complete or blocked. Shared by
+ * the server extension and every client; its schemas are the one decoder.
+ */
+/** A goal objective: stored exactly as sent, never blank. */
+export declare const Objective: Schema.String;
+export declare const GoalReason: Schema.String;
+/** The committed goal every client sees; provisional terminals stay private. */
+export declare const Goal: Schema.Struct<{
+    /** Owner-issued revision that guards an explicit replacement. */
+    readonly revision: Schema.String;
+    readonly objective: Schema.String;
+    readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+    /** Why continuation stopped (for example failed work); a resume retries. */
+    readonly stopReason: Schema.NullOr<Schema.String>;
+}>;
+/** The committed goal every client sees. */
+export type Goal = Schema.Schema.Type<typeof Goal>;
+/**
+ * Arguments of the human `/goal` command. A bare call opens the controls; each
+ * reply is a catalog step, so the conversation stays on the server.
+ */
+export declare const GoalCommandInput: Schema.Union<readonly [Schema.Struct<{
+    readonly action: Schema.Literal<"set">;
+    readonly objective: Schema.String;
+    readonly requestId: Schema.String;
+    /** The revision the human confirmed replacing, when they confirmed one. */
+    readonly expectedRevision: Schema.optional<Schema.NullOr<Schema.String>>;
+    /** The human's answer to "replace the current goal?". */
+    readonly confirmed: Schema.optional<Schema.Boolean>;
+}>, Schema.Struct<{
+    readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear"]>;
+}>, Schema.Struct<{}>]>;
+/** Goal's contract: Session-scope human controls and one projection slot. */
+export declare const GoalProjection: Schema.Struct<{
+    readonly goal: Schema.NullOr<Schema.Struct<{
+        /** Owner-issued revision that guards an explicit replacement. */
+        readonly revision: Schema.String;
+        readonly objective: Schema.String;
+        readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+        /** Why continuation stopped (for example failed work); a resume retries. */
+        readonly stopReason: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly history: Schema.Struct<{
+        readonly nextSequence: Schema.Int;
+        readonly omitted: Schema.Int;
+        readonly events: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly sequence: Schema.Int;
+            readonly at: Schema.Int;
+            readonly commandId: Schema.NullOr<Schema.String>;
+            readonly event: Schema.Codec<{
+                readonly revision: string;
+                readonly objective: string;
+                readonly state: "active" | "paused" | "complete" | "blocked";
+                readonly stopReason: string | null;
+            }, {
+                readonly revision: string;
+                readonly objective: string;
+                readonly state: "active" | "paused" | "complete" | "blocked";
+                readonly stopReason: string | null;
+            }, never, never>;
+        }>>;
+    }>;
+}>;
+export declare const goalContract: {
+    readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
+    readonly commands: {
+        readonly goal: {
+            readonly scope: "session";
+            readonly input: Schema.Union<readonly [Schema.Struct<{
+                readonly action: Schema.Literal<"set">;
+                readonly objective: Schema.String;
+                readonly requestId: Schema.String;
+                /** The revision the human confirmed replacing, when they confirmed one. */
+                readonly expectedRevision: Schema.optional<Schema.NullOr<Schema.String>>;
+                /** The human's answer to "replace the current goal?". */
+                readonly confirmed: Schema.optional<Schema.Boolean>;
+            }>, Schema.Struct<{
+                readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear"]>;
+            }>, Schema.Struct<{}>]>;
+            readonly output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
+        };
+        readonly pause: {
+            readonly scope: "session";
+            readonly input: Schema.Struct<{}>;
+            readonly output: Schema.Struct<{
+                /** Owner-issued revision that guards an explicit replacement. */
+                readonly revision: Schema.String;
+                readonly objective: Schema.String;
+                readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+                /** Why continuation stopped (for example failed work); a resume retries. */
+                readonly stopReason: Schema.NullOr<Schema.String>;
+            }>;
+        };
+        readonly resume: {
+            readonly scope: "session";
+            readonly input: Schema.Struct<{}>;
+            readonly output: Schema.Struct<{
+                /** Owner-issued revision that guards an explicit replacement. */
+                readonly revision: Schema.String;
+                readonly objective: Schema.String;
+                readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+                /** Why continuation stopped (for example failed work); a resume retries. */
+                readonly stopReason: Schema.NullOr<Schema.String>;
+            }>;
+        };
+        readonly clear: {
+            readonly scope: "session";
+            readonly input: Schema.Struct<{}>;
+            readonly output: Schema.Struct<{}>;
+        };
+        readonly set: {
+            readonly scope: "session";
+            readonly input: Schema.Struct<{
+                readonly objective: Schema.String;
+                /** The revision the user saw, or null when they saw no goal. */
+                readonly expectedRevision: Schema.NullOr<Schema.String>;
+                readonly requestId: Schema.String;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly goal: Schema.Struct<{
+                    /** Owner-issued revision that guards an explicit replacement. */
+                    readonly revision: Schema.String;
+                    readonly objective: Schema.String;
+                    readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+                    /** Why continuation stopped (for example failed work); a resume retries. */
+                    readonly stopReason: Schema.NullOr<Schema.String>;
+                }>;
+                readonly accepted: Schema.Struct<{
+                    readonly status: Schema.Literal<"accepted">;
+                    readonly commandId: Schema.String;
+                }>;
+            }>;
+        };
+    };
+    readonly projection: {
+        readonly schema: Schema.Struct<{
+            readonly goal: Schema.NullOr<Schema.Struct<{
+                /** Owner-issued revision that guards an explicit replacement. */
+                readonly revision: Schema.String;
+                readonly objective: Schema.String;
+                readonly state: Schema.Literals<readonly ["active", "paused", "complete", "blocked"]>;
+                /** Why continuation stopped (for example failed work); a resume retries. */
+                readonly stopReason: Schema.NullOr<Schema.String>;
+            }>>;
+            readonly history: Schema.Struct<{
+                readonly nextSequence: Schema.Int;
+                readonly omitted: Schema.Int;
+                readonly events: Schema.$Array<Schema.Struct<{
+                    readonly id: Schema.String;
+                    readonly sequence: Schema.Int;
+                    readonly at: Schema.Int;
+                    readonly commandId: Schema.NullOr<Schema.String>;
+                    readonly event: Schema.Codec<{
+                        readonly revision: string;
+                        readonly objective: string;
+                        readonly state: "active" | "paused" | "complete" | "blocked";
+                        readonly stopReason: string | null;
+                    }, {
+                        readonly revision: string;
+                        readonly objective: string;
+                        readonly state: "active" | "paused" | "complete" | "blocked";
+                        readonly stopReason: string | null;
+                    }, never, never>;
+                }>>;
+            }>;
+        }>;
+    };
+};

package/dist/goal/contract.js

@@ -0,0 +1,76 @@
+import { historySchema } from "../internal/history.js";
+import { ExtensionId } from "@fungi.computer/shiitake/extensions";
+import * as Schema from "effect/Schema";
+import { CatalogStep } from "../internal/catalog.js";
+/**
+ * Session goal: one durable objective per Session that Shiitake keeps
+ * working toward until the model reports it complete or blocked. Shared by
+ * the server extension and every client; its schemas are the one decoder.
+ */
+/** A goal objective: stored exactly as sent, never blank. */
+export const Objective = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(4_000)), Schema.check(Schema.isPattern(/\S/u, { message: "Goal objective is blank" })));
+export const GoalReason = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(1_000)), Schema.check(Schema.isPattern(/\S/u)));
+const RequestId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
+/** The committed goal every client sees; provisional terminals stay private. */
+export const Goal = Schema.Struct({
+    /** Owner-issued revision that guards an explicit replacement. */
+    revision: Schema.String,
+    objective: Objective,
+    state: Schema.Literals(["active", "paused", "complete", "blocked"]),
+    /** Why continuation stopped (for example failed work); a resume retries. */
+    stopReason: Schema.NullOr(Schema.String),
+});
+/**
+ * Arguments of the human `/goal` command. A bare call opens the controls; each
+ * reply is a catalog step, so the conversation stays on the server.
+ */
+export const GoalCommandInput = Schema.Union([
+    Schema.Struct({
+        action: Schema.Literal("set"),
+        objective: Objective,
+        requestId: RequestId,
+        /** The revision the human confirmed replacing, when they confirmed one. */
+        expectedRevision: Schema.optional(Schema.NullOr(Schema.String)),
+        /** The human's answer to "replace the current goal?". */
+        confirmed: Schema.optional(Schema.Boolean),
+    }),
+    Schema.Struct({
+        action: Schema.Literals(["pause", "resume", "replace", "clear"]),
+    }),
+    Schema.Struct({}),
+]);
+/** Goal's contract: Session-scope human controls and one projection slot. */
+export const GoalProjection = Schema.Struct({
+    goal: Schema.NullOr(Goal),
+    history: historySchema(Goal),
+});
+export const goalContract = {
+    id: ExtensionId.make("botanical-session-goal"),
+    commands: {
+        goal: { scope: "session", input: GoalCommandInput, output: CatalogStep },
+        pause: { scope: "session", input: Schema.Struct({}), output: Goal },
+        resume: { scope: "session", input: Schema.Struct({}), output: Goal },
+        clear: {
+            scope: "session",
+            input: Schema.Struct({}),
+            output: Schema.Struct({}),
+        },
+        set: {
+            scope: "session",
+            input: Schema.Struct({
+                objective: Objective,
+                /** The revision the user saw, or null when they saw no goal. */
+                expectedRevision: Schema.NullOr(Schema.String),
+                requestId: RequestId,
+            }),
+            output: Schema.Struct({
+                goal: Goal,
+                accepted: Schema.Struct({
+                    status: Schema.Literal("accepted"),
+                    commandId: Schema.String,
+                }),
+            }),
+        },
+    },
+    projection: { schema: GoalProjection },
+};

package/dist/goal/host.d.ts

@@ -0,0 +1,5 @@
+import { type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
+/** The commands this extension advertises to every client. */
+export declare const goalCatalog: import("@fungi.computer/shiitake/extensions").Json;
+/** Botanical's Session goal, driven only by settled runs. */
+export declare const goalExtension: RosteredExtensionV0;