@fungi.computer/shiitake-extensions 0.0.1 → 0.1.0

package/dist/goal/host.js

@@ -1,26 +1,44 @@
-import * as Clock from "effect/Clock";
-import { appendHistory, emptyHistory, historySchema, } from "../internal/history.js";
 import { Mycelium } from "@fungi.computer/mycelium";
 import { defineCollection, defineExtension, ExtensionCommandError, ExtensionStop, } from "@fungi.computer/shiitake/extensions";
 import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import { z } from "zod";
 import { ask, catalog, declined, done, freshRequestId, } from "../internal/catalog.js";
-import { Goal, GoalCommandInput, goalContract, GoalReason, Objective, } from "./contract.js";
+import { EndedGoal, endedGoalLimit, Goal, GoalCommandInput, goalContract, GoalReason, Objective, } from "./contract.js";
+/** The rules the model follows; the describe page and an active goal's prompt share them. */
+const rules = "You may start a goal yourself when none is current. Before marking complete audit every requirement against evidence; complete only after actual achievement. Block only after the same external impasse for three consecutive goal turns; a blocked goal pauses until a person resumes it. Human pause/resume/clear remain human controls. Use plan.update_plan for multi-step work when available.";
 /** Hashed prose and policy: every constant goal reads comes from here. */
 const config = {
     continuation: "Continue working toward the current goal described in the goal section. Find goal.get_goal and goal.update_goal with forage.search({query:'goal'}) and forage.describe. Audit every requirement against evidence before goal.update_goal({status:'complete', reason}). If the same external blocker persists for three goal turns, report blocked with a reason. Check for progress rather than repeating yourself.",
-    moduleDescription: "Session goal coordination state. You may create goals autonomously; complete only after actual achievement; block only after the same external impasse for three consecutive goal turns.",
-    createDescription: "Create a Session goal, including autonomously. A replacement is allowed only after the current goal is complete.",
+    moduleDescription: "Session goal tools: create_goal({objective}), get_goal({}), update_goal({status:'complete'|'blocked', reason}). " +
+        rules,
+    createDescription: "Create a Session goal, including autonomously. Fails while a goal is active or paused; a finished goal is history.",
     getDescription: "Read the current goal. A requested terminal state remains provisional until successful settlement.",
-    updateDescription: "Request complete only after actual achievement, or blocked only after the same external impasse for three consecutive goal turns; settlement commits the request.",
+    updateDescription: "Request complete only after actual achievement, or blocked only after the same external impasse for three consecutive goal turns; settlement commits the request. Complete ends the goal; blocked pauses it for a person.",
     promptLimit: 1_024,
     stallTurns: 3,
-    stallReason: "Stalled: no progress for 3 turns. /goal resume to retry",
-    guide: "Session goal tools in execute: goal.create_goal({objective}), goal.get_goal({}), goal.update_goal({status:'complete'|'blocked', reason}). Find them with forage.search({query:'goal'}) and forage.describe. You may start a goal yourself. Before marking complete audit every requirement against evidence. Block only after the same external impasse for three consecutive goal turns. Human pause/resume/clear remain human controls. Use plan.update_plan for multi-step work when available.",
+    stallReason: "Stalled: no progress for 3 turns",
+    /** Why a goal paused when its tracked work did not complete. */
+    stoppedReasons: {
+        cancelled: "Stopped",
+        failed: "Goal work failed",
+        interrupted: "Goal work was interrupted",
+        outcome_unknown: "Goal work ended without a known outcome",
+    },
+    /** Why a live goal paused when another turn of its Session did not complete. */
+    otherStoppedReasons: {
+        failed: "The last turn failed",
+        interrupted: "The last turn was interrupted",
+        outcome_unknown: "The last turn ended without a known outcome",
+    },
+    noTerminalReason: "Goal work ended without a final reply",
+    idle: "Long-running objective? forage.describe({path:'goal'}) first.",
+    guide: "Session goal tools: goal.create_goal, goal.get_goal, goal.update_goal. " +
+        rules,
 };
 const promptEncoder = new TextEncoder();
 const promptDecoder = new TextDecoder();
@@ -30,47 +48,63 @@ function boundedPrompt(text, byteLimit) {
     const { written } = promptEncoder.encodeInto(text, bytes);
     return promptDecoder.decode(bytes.subarray(0, written));
 }
-/** One Session's durable goal row. */
+/** One Session's current goal row; a finished goal leaves this collection. */
 const GoalRow = Schema.Struct({
     ...Goal.fields,
     sessionId: Schema.String,
     /** A model-requested terminal, committed only by its run's success. */
-    pendingState: Schema.NullOr(Schema.Literals(["complete", "blocked"])),
-    pendingReason: Schema.NullOr(GoalReason),
+    pending: Schema.NullOr(Schema.Struct({
+        state: Schema.Literals(["complete", "blocked"]),
+        reason: GoalReason,
+    })),
     stalledTurns: Schema.Int,
     /** Request that set this revision; its retry replays. */
     revisionRequestId: Schema.String,
     /** Latest work whose settlement advances this goal. */
     trackedWorkId: Schema.String,
 });
+/** One Session's finished goals, newest last, and how many were dropped. */
+const EndingsRow = Schema.Struct({
+    sessionId: Schema.String,
+    ended: Schema.Array(EndedGoal).check(Schema.isMaxLength(endedGoalLimit)),
+    total: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+});
 const collections = {
-    history: defineCollection(Schema.Struct({ sessionId: Schema.String, history: historySchema(Goal) }), { key: (row) => row.sessionId }),
     goals: defineCollection(GoalRow, {
         key: (goal) => goal.sessionId,
         index: (goal) => goal.state,
     }),
+    endings: defineCollection(EndingsRow, {
+        key: (endings) => endings.sessionId,
+    }),
 };
 function committed(row) {
     return {
         revision: row.revision,
         objective: row.objective,
         state: row.state,
-        stopReason: row.stopReason,
+        startedAt: row.startedAt,
+        pauseCause: row.pauseCause,
     };
 }
 function commitGoal(ctx, row) {
     return Effect.gen(function* () {
-        const previous = Option.getOrUndefined(yield* ctx.state.goals.get(row.sessionId));
-        if ((row.state === "complete" || row.state === "blocked") &&
-            previous?.state !== row.state) {
-            const history = Option.getOrUndefined(yield* ctx.state.history.get(row.sessionId))
-                ?.history ?? emptyHistory();
-            yield* ctx.state.history.put({
-                sessionId: row.sessionId,
-                history: appendHistory(history, committed(row), row.trackedWorkId || null, yield* Clock.currentTimeMillis),
-            });
-        }
         yield* ctx.state.goals.put(row);
+        if (row.state === "paused" &&
+            (row.pauseCause?.kind === "blocked" || row.pauseCause?.kind === "stalled"))
+            yield* ctx.attention
+                .set(row.sessionId, {
+                id: "paused-goal",
+                kind: `goal-${row.pauseCause.kind}`,
+                inbox: false,
+                summary: goalLine(committed(row)).slice(0, 200),
+                since: yield* Clock.currentTimeMillis,
+            })
+                .pipe(Effect.catchTag("ExtensionStateError", (error) => error.reason === "session_absent"
+                ? Effect.void
+                : Effect.fail(error)));
+        else
+            yield* ctx.attention.clear(row.sessionId, "paused-goal");
     });
 }
 function conflict(message) {
@@ -82,15 +116,54 @@ function requireGoal(ctx, sessionId) {
         onSome: Effect.succeed,
     })));
 }
-/** Pause or reactivate a nonterminal goal without touching admitted work. */
+/** Pause a goal with the reason a person will see; provisional terminals drop. */
+function paused(goal, kind, detail) {
+    return {
+        ...goal,
+        state: "paused",
+        pauseCause: { kind, detail },
+        pending: null,
+    };
+}
+/**
+ * Finish the current goal: it leaves the current slot and joins the
+ * Session's bounded history, which the chat shows as one line.
+ */
+function finishGoal(ctx, goal, outcome, reason) {
+    return Effect.gen(function* () {
+        const endedAt = yield* Clock.currentTimeMillis;
+        const afterSequence = yield* ctx.sessionPosition(goal.sessionId);
+        const previous = Option.getOrUndefined(yield* ctx.state.endings.get(goal.sessionId));
+        const total = (previous?.total ?? 0) + 1;
+        const ending = {
+            sequence: total,
+            objective: goal.objective,
+            outcome,
+            reason,
+            endedAt,
+            afterSequence,
+        };
+        yield* ctx.state.endings.put({
+            sessionId: goal.sessionId,
+            ended: [...(previous?.ended ?? []), ending].slice(-endedGoalLimit),
+            total,
+        });
+        yield* ctx.state.goals.remove(goal.sessionId);
+        yield* ctx.attention.clear(goal.sessionId, "paused-goal");
+    });
+}
+/** Pause or reactivate the current goal without touching admitted work. */
 function changeActivity(ctx, sessionId, target) {
     return Effect.gen(function* () {
         const goal = yield* requireGoal(ctx, sessionId);
-        if (goal.state === "complete" || goal.state === "blocked")
-            return yield* Effect.fail(conflict("A terminal Session goal cannot change activity"));
         const changed = target === "active"
-            ? { ...goal, state: "active", stopReason: null, stalledTurns: 0 }
-            : { ...goal, state: "paused" };
+            ? {
+                ...goal,
+                state: "active",
+                pauseCause: null,
+                stalledTurns: 0,
+            }
+            : paused(goal, "person", null);
         yield* commitGoal(ctx, changed);
         yield* ctx.observe(sessionId);
         return changed;
@@ -112,16 +185,17 @@ function continueIfIdle(ctx, goal, requestId) {
     })
         .pipe(Effect.map((admitted) => admitted._tag === "Accepted"
         ? { ...goal, trackedWorkId: admitted.commandId }
-        : goal), Effect.catchTag("AdmissionError", (error) => Effect.succeed({
-        ...goal,
-        state: "paused",
-        stopReason: error.message,
-    })));
+        : goal), Effect.catchTag("AdmissionError", (error) => Effect.succeed(paused(goal, "failed", error.message))));
 }
 /**
  * Advance one Session's goal from one settled run. Any successful run in
- * the Session becomes the tracked progress; failed tracked work is a visible
- * item-level stop that a human resume retries.
+ * the Session becomes the tracked progress. Tracked work that did not
+ * complete (Esc, failure, or a restart whose resumed turn could not finish),
+ * or any other turn of the Session that failed or was stopped while the goal
+ * was live,
+ * pauses the goal until a person resumes it; a turn a restart resumed
+ * settles here like any other, so the goal keeps going. An achieved goal
+ * finishes and leaves the current slot.
  */
 function settle(ctx, run) {
     return Effect.gen(function* () {
@@ -129,30 +203,26 @@ function settle(ctx, run) {
         if (Option.isNone(found))
             return;
         const goal = found.value;
-        if (goal.state !== "active" && goal.state !== "paused")
-            return;
         if (run.outcome !== "completed") {
-            if (run.workId !== goal.trackedWorkId)
+            const tracked = run.workId === goal.trackedWorkId;
+            if (!tracked && goal.state !== "active")
                 return;
-            yield* commitGoal(ctx, {
-                ...goal,
-                pendingState: null,
-                pendingReason: null,
-                stopReason: `Goal work ended ${run.outcome}`,
-            });
+            const cancelled = run.outcome === "cancelled";
+            // Esc stops a live goal even on another turn. Restart-resumed work never
+            // settles here; other failures pause the goal with their own display line.
+            const detail = tracked || cancelled
+                ? ctx.config.stoppedReasons[run.outcome]
+                : ctx.config.otherStoppedReasons[run.outcome];
+            yield* commitGoal(ctx, paused(goal, cancelled ? "cancelled" : "failed", detail));
             return yield* ctx.observe(run.sessionId);
         }
         if (run.terminal !== "completed") {
-            yield* commitGoal(ctx, {
-                ...goal,
-                stopReason: "Completed goal work has no exact terminal",
-            });
+            yield* commitGoal(ctx, paused(goal, "no-terminal", ctx.config.noTerminalReason));
             return yield* ctx.observe(run.sessionId);
         }
         const tracked = {
             ...goal,
             trackedWorkId: run.workId,
-            stopReason: null,
             stalledTurns: run.origin?.extensionId === goalContract.id &&
                 run.origin.correlation === goal.revision
                 ? run.toolCalls === 0
@@ -160,21 +230,14 @@ function settle(ctx, run) {
                     : 0
                 : goal.stalledTurns,
         };
-        if (goal.pendingState !== null && goal.trackedWorkId === run.workId)
-            yield* commitGoal(ctx, {
-                ...tracked,
-                state: goal.pendingState,
-                stopReason: goal.pendingReason,
-                pendingState: null,
-                pendingReason: null,
-            });
+        const pending = goal.trackedWorkId === run.workId ? goal.pending : null;
+        if (pending?.state === "complete")
+            yield* finishGoal(ctx, tracked, "achieved", pending.reason);
+        else if (pending?.state === "blocked")
+            yield* commitGoal(ctx, paused(tracked, "blocked", pending.reason));
         else if (goal.state === "active" &&
             tracked.stalledTurns >= ctx.config.stallTurns)
-            yield* commitGoal(ctx, {
-                ...tracked,
-                state: "paused",
-                stopReason: ctx.config.stallReason,
-            });
+            yield* commitGoal(ctx, paused(tracked, "stalled", ctx.config.stallReason));
         else if (goal.state === "active")
             yield* commitGoal(ctx, yield* continueIfIdle(ctx, tracked, `goal-continue:${run.workId}`));
         else
@@ -215,22 +278,19 @@ function goalModule(ctx, sessionId, workId) {
                 }),
                 execute: ({ objective }) => toolCall(ctx, Effect.gen(function* () {
                     const decoded = yield* Schema.decodeUnknownEffect(Objective)(objective).pipe(Effect.mapError(() => conflict("Goal objective is invalid")));
-                    const current = yield* ctx.state.goals.get(sessionId);
-                    if (Option.isSome(current) && current.value.state !== "complete")
-                        return yield* Effect.fail(conflict(current.value.state === "blocked"
-                            ? "A blocked Session goal cannot be replaced"
-                            : "A nonterminal Session goal already exists"));
+                    if (Option.isSome(yield* ctx.state.goals.get(sessionId)))
+                        return yield* Effect.fail(conflict("A Session goal is already active or paused; only a person replaces it"));
                     yield* commitGoal(ctx, {
                         sessionId,
                         objective: decoded,
                         state: "active",
-                        pendingState: null,
-                        pendingReason: null,
+                        startedAt: yield* Clock.currentTimeMillis,
+                        pending: null,
                         stalledTurns: 0,
                         revision: `run:${workId}`,
                         revisionRequestId: `run:${workId}`,
                         trackedWorkId: workId,
-                        stopReason: null,
+                        pauseCause: null,
                     });
                     yield* ctx.observe(sessionId);
                     return { objective: decoded, state: "active" };
@@ -244,7 +304,7 @@ function goalModule(ctx, sessionId, workId) {
                     z.strictObject({
                         objective: toolObjective,
                         state: toolState,
-                        stopReason: z.string().nullable(),
+                        reason: z.string().nullable(),
                     }),
                     z.null(),
                 ]),
@@ -252,8 +312,10 @@ function goalModule(ctx, sessionId, workId) {
                     ? null
                     : {
                         objective: found.value.objective,
-                        state: found.value.pendingState ?? found.value.state,
-                        stopReason: found.value.pendingReason ?? found.value.stopReason,
+                        state: found.value.pending?.state ?? found.value.state,
+                        reason: found.value.pending?.reason ??
+                            found.value.pauseCause?.detail ??
+                            null,
                     }))),
             }),
             update_goal: Mycelium.operation({
@@ -277,8 +339,7 @@ function goalModule(ctx, sessionId, workId) {
                         return yield* Effect.fail(conflict("Session goal work guard is stale"));
                     yield* commitGoal(ctx, {
                         ...found.value,
-                        pendingState: status,
-                        pendingReason: decoded,
+                        pending: { state: status, reason: decoded },
                     });
                     return {
                         objective: found.value.objective,
@@ -332,17 +393,20 @@ function setGoal(ctx, sessionId, input) {
                 return yield* Effect.fail(conflict("Session goal changed after this request was accepted"));
             return { goal: committed(current), accepted };
         }
+        // A replaced goal ends as cleared: history, never current.
+        if (current !== undefined && !retried)
+            yield* finishGoal(ctx, current, "cleared", null);
         const row = {
             sessionId,
             objective: input.objective,
             state: "active",
-            pendingState: null,
-            pendingReason: null,
+            startedAt: yield* Clock.currentTimeMillis,
+            pending: null,
             stalledTurns: 0,
             revision: `set:${input.requestId}`,
             revisionRequestId: input.requestId,
             trackedWorkId: admitted.commandId,
-            stopReason: null,
+            pauseCause: null,
         };
         yield* commitGoal(ctx, row);
         yield* ctx.observe(sessionId);
@@ -350,20 +414,27 @@ function setGoal(ctx, sessionId, input) {
     });
 }
 function goalLine(goal) {
-    const state = goal.state.charAt(0).toUpperCase() + goal.state.slice(1);
-    return goal.stopReason === null
-        ? `${state}: ${goal.objective}`
-        : `${state}: ${goal.objective} (${goal.stopReason})`;
+    if (goal.state === "active")
+        return `Pursuing goal: ${goal.objective}`;
+    return goal.pauseCause?.detail == null
+        ? `Goal paused: ${goal.objective}`
+        : `Goal paused: ${goal.objective} (${goal.pauseCause.detail})`;
 }
 const objectivePrompt = {
     type: "text",
     message: "What should this Session work toward?",
     placeholder: "Describe the finished result",
 };
+/** Clear the current goal into history; returns whether one was current. */
 function clearGoal(ctx, sessionId) {
-    return ctx.state.goals
-        .remove(sessionId)
-        .pipe(Effect.andThen(ctx.observe(sessionId)), Effect.as({}));
+    return Effect.gen(function* () {
+        const current = yield* ctx.state.goals.get(sessionId);
+        if (Option.isNone(current))
+            return false;
+        yield* finishGoal(ctx, current.value, "cleared", null);
+        yield* ctx.observe(sessionId);
+        return true;
+    });
 }
 /**
  * The human `/goal` conversation. Every step is decided here from the
@@ -376,30 +447,24 @@ function humanGoal(ctx, sessionId, input) {
             if (current === undefined)
                 return ask(objectivePrompt, { action: "set", requestId: yield* freshRequestId }, "objective");
             const goal = committed(current);
-            const options = goal.state === "active"
-                ? [{ value: "pause", label: "Pause goal" }]
-                : goal.state === "paused"
-                    ? [{ value: "resume", label: "Resume goal" }]
-                    : [];
             return ask({
                 type: "choice",
                 message: goalLine(goal),
                 options: [
-                    ...options,
+                    goal.state === "active"
+                        ? { value: "pause", label: "Pause goal" }
+                        : { value: "resume", label: "Resume goal" },
                     { value: "clear", label: "Clear goal" },
-                    {
-                        value: "replace",
-                        label: goal.state === "complete" || goal.state === "blocked"
-                            ? "Set a new goal"
-                            : "Replace goal",
-                    },
+                    { value: "replace", label: "Replace goal" },
                 ],
             }, {}, "action");
         }
         switch (input.action) {
             case "clear":
-                yield* clearGoal(ctx, sessionId);
-                return done({ type: "success", message: "Goal cleared." });
+                // The chat's ending line confirms a clear; only an empty one says so.
+                return (yield* clearGoal(ctx, sessionId))
+                    ? { type: "done" }
+                    : done({ type: "info", message: "No goal to clear." });
             case "pause":
                 yield* pauseGoal(ctx, sessionId);
                 return { type: "done" };
@@ -415,13 +480,14 @@ function humanGoal(ctx, sessionId, input) {
                 }, "objective");
             case "set": {
                 const retried = current?.revisionRequestId === input.requestId;
-                const replacing = current !== undefined && current.state !== "complete" && !retried;
+                // Only a live or paused goal is current, so only it asks first.
+                const replacing = current !== undefined && !retried;
                 if (replacing && input.confirmed === false)
                     return declined({ type: "info", message: "Kept the current goal." });
                 if (replacing && input.confirmed !== true)
                     return ask({
                         type: "confirmation",
-                        message: `Replace the current goal?\nCurrent: ${current.objective}\nNew: ${input.objective}`,
+                        message: `Replace the ${current.state === "active" ? "live" : "paused"} goal?\nCurrent: ${current.objective}\nNew: ${input.objective}`,
                         confirmLabel: "Replace and start",
                         cancelLabel: "Keep current goal",
                     }, {
@@ -486,18 +552,25 @@ export const goalCatalog = catalog([
 /** Botanical's Session goal, driven only by settled runs. */
 export const goalExtension = defineExtension({
     id: goalContract.id,
-    version: "4.1.0",
+    version: "7.0.0",
 })
     .config(config)
-    .state({ version: 4, migrations: {}, collections })
+    // A command anchor cannot be converted into a historical Session position.
+    // Old preview state must be republished separately, never guessed here.
+    .state({ version: 7, migrations: {}, collections })
     .define({
+    attention: true,
     prompt: (ctx, { sessionId, origin }) => Effect.gen(function* () {
         const goal = Option.getOrNull(yield* ctx.state.goals.get(sessionId));
-        const current = goal === null ? "No current goal." : goalLine(committed(goal));
+        const text = goal === null
+            ? ctx.config.idle
+            : (goal.state === "active" ? ctx.config.guide : ctx.config.idle) +
+                "\n" +
+                goalLine(committed(goal));
         return [
             {
                 name: "goal",
-                text: boundedPrompt(ctx.config.guide + "\n" + current, ctx.config.promptLimit),
+                text: boundedPrompt(text, ctx.config.promptLimit),
             },
             ...(goal?.state === "active" &&
                 origin?.extensionId === goalContract.id &&
@@ -516,13 +589,15 @@ export const goalExtension = defineExtension({
         schema: goalContract.projection.schema,
         read: (ctx, sessionId) => {
             const goal = Option.getOrUndefined(ctx.state.goals.peek(sessionId));
-            const history = Option.getOrUndefined(ctx.state.history.peek(sessionId))?.history;
-            return goal === undefined && history === undefined
-                ? Option.none()
-                : Option.some({
-                    goal: goal === undefined ? null : committed(goal),
-                    history: history ?? emptyHistory(),
-                });
+            const endings = Option.getOrUndefined(ctx.state.endings.peek(sessionId));
+            if (goal === undefined && endings === undefined)
+                return Option.none();
+            const ended = endings?.ended ?? [];
+            return Option.some({
+                goal: goal === undefined ? null : committed(goal),
+                ended,
+                omitted: (endings?.total ?? 0) - ended.length,
+            });
         },
     },
     hooks: {
@@ -535,7 +610,7 @@ export const goalExtension = defineExtension({
             goal: ({ sessionId, input }) => humanGoal(ctx, sessionId, input),
             pause: ({ sessionId }) => pauseGoal(ctx, sessionId),
             resume: ({ sessionId }) => resumeGoal(ctx, sessionId),
-            clear: ({ sessionId }) => clearGoal(ctx, sessionId),
+            clear: ({ sessionId }) => clearGoal(ctx, sessionId).pipe(Effect.as({})),
             set: ({ sessionId, input }) => setGoal(ctx, sessionId, input),
         }),
     },

package/dist/home/contract.d.ts

@@ -1,32 +1,50 @@
 import * as Schema from "effect/Schema";
 /** The Agent's recorded choice survives the chosen attachment being detached. */
 export declare const Home: Schema.Struct<{
+    /** Chosen Computer attachment, or null when no Home is selected. */
     readonly attachmentId: Schema.NullOr<Schema.String>;
 }>;
+/** Persisted Home selection for one Agent. */
 export type Home = Schema.Schema.Type<typeof Home>;
 /** Human selection changes Agent state; no model operation exposes this command. */
 export declare const homeContract: {
+    /** Stable extension identity. */
     id: string & import("effect/Brand").Brand<"ExtensionId">;
+    /** Human selection and initial seeding operations. */
     commands: {
+        /** Open Home controls or select an attachment by name. */
         home: {
+            /** Human controls are opened from a Session. */
             scope: "session";
+            /** Decode an optional attachment name. */
             input: Schema.Struct<{
+                /** Attachment name selected by the person. */
                 readonly name: Schema.optionalKey<Schema.String>;
             }>;
+            /** Return the server-owned conversation step. */
             output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
+        /** Seed the Agent's initial recorded Home choice. */
         seed: {
+            /** Home selection belongs to the Agent. */
             scope: "agent";
+            /** Decode the initial selection. */
             input: Schema.Struct<{
+                /** Chosen Computer attachment, or null when no Home is selected. */
                 readonly attachmentId: Schema.NullOr<Schema.String>;
             }>;
+            /** Report whether seeding changed the recorded choice. */
             output: Schema.Struct<{
+                /** Whether the initial choice was seeded. */
                 readonly seeded: Schema.Boolean;
             }>;
         };
     };
+    /** Recorded selection visible to clients, or no seeded state. */
     projection: {
+        /** Decoder for the optional Home state. */
         schema: Schema.NullOr<Schema.Struct<{
+            /** Chosen Computer attachment, or null when no Home is selected. */
             readonly attachmentId: Schema.NullOr<Schema.String>;
         }>>;
     };

package/dist/home/contract.js

@@ -4,22 +4,43 @@ import { CatalogStep } from "../internal/catalog.js";
 const attachmentId = Schema.String.pipe(Schema.check(Schema.isMinLength(1)));
 /** The Agent's recorded choice survives the chosen attachment being detached. */
 export const Home = Schema.Struct({
+    /** Chosen Computer attachment, or null when no Home is selected. */
     attachmentId: Schema.NullOr(attachmentId),
 });
 /** Human selection changes Agent state; no model operation exposes this command. */
 export const homeContract = {
+    /** Stable extension identity. */
     id: ExtensionId.make("botanical-home"),
+    /** Human selection and initial seeding operations. */
     commands: {
+        /** Open Home controls or select an attachment by name. */
         home: {
+            /** Human controls are opened from a Session. */
             scope: "session",
-            input: Schema.Struct({ name: Schema.optionalKey(Schema.String) }),
+            /** Decode an optional attachment name. */
+            input: Schema.Struct({
+                /** Attachment name selected by the person. */
+                name: Schema.optionalKey(Schema.String),
+            }),
+            /** Return the server-owned conversation step. */
             output: CatalogStep,
         },
+        /** Seed the Agent's initial recorded Home choice. */
         seed: {
+            /** Home selection belongs to the Agent. */
             scope: "agent",
+            /** Decode the initial selection. */
             input: Home,
-            output: Schema.Struct({ seeded: Schema.Boolean }),
+            /** Report whether seeding changed the recorded choice. */
+            output: Schema.Struct({
+                /** Whether the initial choice was seeded. */
+                seeded: Schema.Boolean,
+            }),
         },
     },
-    projection: { schema: Schema.NullOr(Home) },
+    /** Recorded selection visible to clients, or no seeded state. */
+    projection: {
+        /** Decoder for the optional Home state. */
+        schema: Schema.NullOr(Home),
+    },
 };

package/dist/home/host.d.ts

@@ -2,8 +2,11 @@ import { type FilesPort } from "@fungi.computer/knapsack";
 import { type ExtensionGrantV0, type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
 /** Already-scoped authority supplied by the host, never constructed by Home. */
 export type HomeComputer = Readonly<{
+    /** Attachment name offered to the person choosing Home. */
     name: string;
+    /** Stable identity stored by the Home selection. */
     attachmentId: string;
+    /** Already-scoped Files authority captured for this attachment. */
     port: FilesPort;
 }>;
 /** Hosts admit Home explicitly; no other extension receives the Files slot. */

package/dist/home/host.js

@@ -13,7 +13,7 @@ export const homeGrant = {
 };
 const config = {
     promptLimit: 4_000,
-    guide: "Home supplies read, list, glob and grep over your default Computer. Bare paths and computer://home/ use Home; computer://<name>/ uses that captured attachment. apply_patch, when offered, uses Home's native patch engine and path jail. Only a person changes Home with /home <name>; ask them when no Home is available.",
+    guide: "Home supplies read, list, glob and grep over your default Computer. Bare paths and computer://home/ use Home; computer://<name>/ uses that captured attachment. apply_patch, when offered, also works on Home. Only a person changes Home with /home <name>; ask them when no Home is available.",
 };
 const collections = {
     choice: defineCollection(Home, { key: () => "default" }),
@@ -79,7 +79,6 @@ export function homeExtension(options) {
                 return null;
             return Knapsack.files({
                 port: homeFilesRouting(new Map(computers.map(({ name, port }) => [name, port])), selected.port),
-                pathInstructions: "Bare paths and computer://home/ select Home. computer://<name>/ selects another captured attachment. apply_patch uses Home only.",
             }).tools;
         },
         prompt: (_ctx, run) => [