@fungi.computer/shiitake-extensions 0.0.1 → 0.1.0

package/dist/goal/client.js

@@ -1,15 +1,68 @@
 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. */
+/** One footer line: the full objective stays in the row's detail. */
+const summary = (text) => {
+    const line = text.replace(/\s+/gu, " ").trim();
+    return line.length <= 80 ? line : `${line.slice(0, 79)}…`;
+};
+/** The local wall-clock time a goal started, as 14:02. */
+const clockTime = (epochMillis) => {
+    const at = new Date(epochMillis);
+    return `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+};
+/**
+ * The one footer row for a live or paused goal, with its one control. The
+ * line itself says why a goal paused, so every host shows it without opening
+ * the row; the detail keeps an objective the line had to shorten.
+ */
+function currentRow(goal) {
+    const active = goal.state === "active";
+    const status = active
+        ? `Pursuing goal since ${clockTime(goal.startedAt)}`
+        : "Goal paused (/goal resume)";
+    const reason = !active && goal.pauseCause?.detail != null
+        ? [summary(goal.pauseCause.detail)]
+        : [];
+    const row = {
+        id: "goal",
+        title: [status, summary(goal.objective), ...reason].join(" · "),
+        tone: active ? "running" : "muted",
+        actions: [
+            {
+                id: "goal",
+                label: active ? "Pause goal" : "Resume goal",
+                input: { action: active ? "pause" : "resume" },
+            },
+        ],
+    };
+    return summary(goal.objective) === goal.objective
+        ? row
+        : { ...row, detail: goal.objective.slice(0, 1024) };
+}
+/** One chat line at the Session position committed when the goal ended. */
+function endedCell(ended) {
+    const line = {
+        id: "goal-ended",
+        title: `${ended.outcome === "achieved" ? "Goal achieved" : "Goal cleared"} · ${summary(ended.objective)}`,
+        tone: ended.outcome === "achieved" ? "settled" : "muted",
+    };
+    // An achieved goal keeps the model's evidence as the line's detail.
+    const row = ended.reason === null ? line : { ...line, detail: ended.reason };
+    return {
+        id: String(ended.sequence),
+        sequence: ended.sequence,
+        at: ended.endedAt,
+        commandId: null,
+        afterSequence: ended.afterSequence,
+        rows: [row],
+    };
+}
+/**
+ * Product copy and controls belong to Goal; every host renders plain rows.
+ * The footer shows only a live or paused goal; finished goals are chat lines.
+ */
 export default defineClientEntry(goalContract, {
-    correlatedPrompts: "note",
+    promptPresentation: "footer",
     contribute: (view) => {
         if (view.status !== "running" || view.value === null)
             return {
@@ -18,70 +71,11 @@ export default defineClientEntry(goalContract, {
                 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",
-                });
-        }
+        const { goal, ended, omitted } = view.value;
         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),
-                                },
-                            ]),
-                    ],
-                })),
-            },
+            chips: [],
+            panel: goal === null ? [] : [currentRow(goal)],
+            timeline: { cells: ended.map(endedCell), omitted },
             waiting: null,
         };
     },

package/dist/goal/contract.d.ts

@@ -1,172 +1,289 @@
 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.
+ * working toward until the model reports it achieved or a person clears it.
+ * Only a live or paused goal is current; a finished goal is history. 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;
+/** Nonblank explanation recorded when a goal is achieved. */
 export declare const GoalReason: Schema.String;
-/** The committed goal every client sees; provisional terminals stay private. */
+/** Why work paused, independent of the words shown to a person. */
+export declare const GoalPauseCause: Schema.Struct<{
+    /** Typed origin of the pause. */
+    readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+    /** Additional explanation, or null when no detail was supplied. */
+    readonly detail: Schema.NullOr<Schema.String>;
+}>;
+/** Typed pause cause and optional explanation. */
+export type GoalPauseCause = Schema.Schema.Type<typeof GoalPauseCause>;
+/** The current 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;
+    /** Objective being pursued by this Session. */
     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>;
+    /** Live, or paused until a person resumes it (a blocked goal is paused). */
+    readonly state: Schema.Literals<readonly ["active", "paused"]>;
+    /** When this goal was set, in epoch milliseconds. */
+    readonly startedAt: Schema.Int;
+    /** A typed cause while paused; null while active. */
+    readonly pauseCause: Schema.NullOr<Schema.Struct<{
+        /** Typed origin of the pause. */
+        readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+        /** Additional explanation, or null when no detail was supplied. */
+        readonly detail: Schema.NullOr<Schema.String>;
+    }>>;
 }>;
-/** The committed goal every client sees. */
+/** The current goal every client sees. */
 export type Goal = Schema.Schema.Type<typeof Goal>;
+/** One finished goal: history only, never current. */
+export declare const EndedGoal: Schema.Struct<{
+    /** Per-Session order of endings, starting at 1. */
+    readonly sequence: Schema.Int;
+    /** Objective that finished or was cleared. */
+    readonly objective: Schema.String;
+    /** Whether the model achieved the goal or a person cleared it. */
+    readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
+    /** The model's evidence for an achieved goal; null when cleared. */
+    readonly reason: Schema.NullOr<Schema.String>;
+    /** Completion time in epoch milliseconds. */
+    readonly endedAt: Schema.Int;
+    /** Committed Session position when this goal ended; zero before any entry. */
+    readonly afterSequence: Schema.Int;
+}>;
+/** One finished goal. */
+export type EndedGoal = Schema.Schema.Type<typeof EndedGoal>;
+/** How many finished goals a Session keeps for its chat lines. */
+export declare const endedGoalLimit = 16;
 /**
  * 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<{
+    /** Select the explicit goal-setting action. */
     readonly action: Schema.Literal<"set">;
+    /** New objective supplied by the person. */
     readonly objective: Schema.String;
+    /** Idempotency key for setting this objective. */
     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<{
+    /** Select an existing-goal control. */
     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<{
+    /** The live or paused goal, or null when none is current. */
     readonly goal: Schema.NullOr<Schema.Struct<{
         /** Owner-issued revision that guards an explicit replacement. */
         readonly revision: Schema.String;
+        /** Objective being pursued by this Session. */
         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>;
+        /** Live, or paused until a person resumes it (a blocked goal is paused). */
+        readonly state: Schema.Literals<readonly ["active", "paused"]>;
+        /** When this goal was set, in epoch milliseconds. */
+        readonly startedAt: Schema.Int;
+        /** A typed cause while paused; null while active. */
+        readonly pauseCause: Schema.NullOr<Schema.Struct<{
+            /** Typed origin of the pause. */
+            readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+            /** Additional explanation, or null when no detail was supplied. */
+            readonly detail: Schema.NullOr<Schema.String>;
         }>>;
-    }>;
+    }>>;
+    /** The newest finished goals, oldest first. */
+    readonly ended: Schema.$Array<Schema.Struct<{
+        /** Per-Session order of endings, starting at 1. */
+        readonly sequence: Schema.Int;
+        /** Objective that finished or was cleared. */
+        readonly objective: Schema.String;
+        /** Whether the model achieved the goal or a person cleared it. */
+        readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
+        /** The model's evidence for an achieved goal; null when cleared. */
+        readonly reason: Schema.NullOr<Schema.String>;
+        /** Completion time in epoch milliseconds. */
+        readonly endedAt: Schema.Int;
+        /** Committed Session position when this goal ended; zero before any entry. */
+        readonly afterSequence: Schema.Int;
+    }>>;
+    /** Finished goals older than `ended` that this Session no longer keeps. */
+    readonly omitted: Schema.Int;
 }>;
+/** Session-owned goal controls and their visible projection. */
 export declare const goalContract: {
+    /** Stable extension identity. */
     readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
+    /** Goal commands admitted by the Session owner. */
     readonly commands: {
+        /** Open or answer the human goal controls. */
         readonly goal: {
+            /** The Session owns this goal. */
             readonly scope: "session";
+            /** Decode the control action. */
             readonly input: Schema.Union<readonly [Schema.Struct<{
+                /** Select the explicit goal-setting action. */
                 readonly action: Schema.Literal<"set">;
+                /** New objective supplied by the person. */
                 readonly objective: Schema.String;
+                /** Idempotency key for setting this objective. */
                 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<{
+                /** Select an existing-goal control. */
                 readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear"]>;
             }>, Schema.Struct<{}>]>;
+            /** Return the server-owned conversation step. */
             readonly output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
+        /** Pause work on the current goal. */
         readonly pause: {
+            /** The Session owns this goal. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Return the paused goal. */
             readonly output: Schema.Struct<{
                 /** Owner-issued revision that guards an explicit replacement. */
                 readonly revision: Schema.String;
+                /** Objective being pursued by this Session. */
                 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>;
+                /** Live, or paused until a person resumes it (a blocked goal is paused). */
+                readonly state: Schema.Literals<readonly ["active", "paused"]>;
+                /** When this goal was set, in epoch milliseconds. */
+                readonly startedAt: Schema.Int;
+                /** A typed cause while paused; null while active. */
+                readonly pauseCause: Schema.NullOr<Schema.Struct<{
+                    /** Typed origin of the pause. */
+                    readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+                    /** Additional explanation, or null when no detail was supplied. */
+                    readonly detail: Schema.NullOr<Schema.String>;
+                }>>;
             }>;
         };
+        /** Resume work on a paused goal. */
         readonly resume: {
+            /** The Session owns this goal. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Return the active goal. */
             readonly output: Schema.Struct<{
                 /** Owner-issued revision that guards an explicit replacement. */
                 readonly revision: Schema.String;
+                /** Objective being pursued by this Session. */
                 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>;
+                /** Live, or paused until a person resumes it (a blocked goal is paused). */
+                readonly state: Schema.Literals<readonly ["active", "paused"]>;
+                /** When this goal was set, in epoch milliseconds. */
+                readonly startedAt: Schema.Int;
+                /** A typed cause while paused; null while active. */
+                readonly pauseCause: Schema.NullOr<Schema.Struct<{
+                    /** Typed origin of the pause. */
+                    readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+                    /** Additional explanation, or null when no detail was supplied. */
+                    readonly detail: Schema.NullOr<Schema.String>;
+                }>>;
             }>;
         };
+        /** Clear the current objective. */
         readonly clear: {
+            /** The Session owns this goal. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** A successful clear has no result fields. */
             readonly output: Schema.Struct<{}>;
         };
+        /** Set an objective against the revision the person saw. */
         readonly set: {
+            /** The Session owns this goal. */
             readonly scope: "session";
+            /** Decode the new objective and replacement fence. */
             readonly input: Schema.Struct<{
+                /** New objective to pursue. */
                 readonly objective: Schema.String;
                 /** The revision the user saw, or null when they saw no goal. */
                 readonly expectedRevision: Schema.NullOr<Schema.String>;
+                /** Idempotency key for this setting command. */
                 readonly requestId: Schema.String;
             }>;
+            /** Return the goal and its admission receipt. */
             readonly output: Schema.Struct<{
+                /** Newly current goal. */
                 readonly goal: Schema.Struct<{
                     /** Owner-issued revision that guards an explicit replacement. */
                     readonly revision: Schema.String;
+                    /** Objective being pursued by this Session. */
                     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>;
+                    /** Live, or paused until a person resumes it (a blocked goal is paused). */
+                    readonly state: Schema.Literals<readonly ["active", "paused"]>;
+                    /** When this goal was set, in epoch milliseconds. */
+                    readonly startedAt: Schema.Int;
+                    /** A typed cause while paused; null while active. */
+                    readonly pauseCause: Schema.NullOr<Schema.Struct<{
+                        /** Typed origin of the pause. */
+                        readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+                        /** Additional explanation, or null when no detail was supplied. */
+                        readonly detail: Schema.NullOr<Schema.String>;
+                    }>>;
                 }>;
+                /** Receipt for the accepted setting command. */
                 readonly accepted: Schema.Struct<{
+                    /** Successful admission discriminator. */
                     readonly status: Schema.Literal<"accepted">;
+                    /** Identity of the admitted command. */
                     readonly commandId: Schema.String;
                 }>;
             }>;
         };
     };
+    /** Current and ended goals visible to clients. */
     readonly projection: {
+        /** Decoder for the goal projection. */
         readonly schema: Schema.Struct<{
+            /** The live or paused goal, or null when none is current. */
             readonly goal: Schema.NullOr<Schema.Struct<{
                 /** Owner-issued revision that guards an explicit replacement. */
                 readonly revision: Schema.String;
+                /** Objective being pursued by this Session. */
                 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>;
+                /** Live, or paused until a person resumes it (a blocked goal is paused). */
+                readonly state: Schema.Literals<readonly ["active", "paused"]>;
+                /** When this goal was set, in epoch milliseconds. */
+                readonly startedAt: Schema.Int;
+                /** A typed cause while paused; null while active. */
+                readonly pauseCause: Schema.NullOr<Schema.Struct<{
+                    /** Typed origin of the pause. */
+                    readonly kind: Schema.Literals<readonly ["person", "blocked", "stalled", "cancelled", "failed", "no-terminal"]>;
+                    /** Additional explanation, or null when no detail was supplied. */
+                    readonly detail: Schema.NullOr<Schema.String>;
                 }>>;
-            }>;
+            }>>;
+            /** The newest finished goals, oldest first. */
+            readonly ended: Schema.$Array<Schema.Struct<{
+                /** Per-Session order of endings, starting at 1. */
+                readonly sequence: Schema.Int;
+                /** Objective that finished or was cleared. */
+                readonly objective: Schema.String;
+                /** Whether the model achieved the goal or a person cleared it. */
+                readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
+                /** The model's evidence for an achieved goal; null when cleared. */
+                readonly reason: Schema.NullOr<Schema.String>;
+                /** Completion time in epoch milliseconds. */
+                readonly endedAt: Schema.Int;
+                /** Committed Session position when this goal ended; zero before any entry. */
+                readonly afterSequence: Schema.Int;
+            }>>;
+            /** Finished goals older than `ended` that this Session no longer keeps. */
+            readonly omitted: Schema.Int;
         }>;
     };
 };