@fungi.computer/shiitake-extensions 0.2.0 → 0.4.0

package/README.md

@@ -65,16 +65,16 @@ 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 live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history.                             |
-| 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, and `/agents` collapses the rows to one summary row and expands them again. It owns no relationship and no durable state.                                                                                                                      |
+| 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. On Local, an Ask raised during work another Agent sent waits on that sender first: it always parks, reads `waiting on <name>` instead of needing a person, and rides the child's reply to the sender as `waiting_on_you`. Only that sender's Session can answer it with `agents.answer`, or pass it to a person with `agents.escalate`; a person may always answer. An Ask the sender neither answers nor escalates goes to a person when the sender's turn ends, or after fifteen minutes. Hub sends every Ask to a person. |
+| Goal      | One live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools, from any later turn of its Session; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it; a tool-less goal turn while a sub-agent command is live waits instead. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history.                                                                                                                                                                                     |
+| 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 footer view: one row per Agent this Session sent work to or created, with its live status (working, waiting on an Agent, needs you, idle, failed, unavailable). A row opens that Agent's conversation, a question that needs a person can be answered from its row, and `/agents` collapses the rows to one summary row and expands them again. 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
@@ -90,14 +90,21 @@ 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; a blocked
-goal pauses and resumes like any paused goal. Only a live or paused goal asks
-before a replacement, which uses the observed revision to avoid replacing a
-newer goal; the replaced goal is recorded as cleared. When a runtime restart (a
-Hub deploy or eviction, a Local service restart) interrupts a goal turn, the
-turn resumes and the goal stays live. A live goal pauses when any turn of its
-Session fails, cannot resume or is stopped by a person (Esc), including the
-person's own messages ("The last turn failed"). A missing extension origin does
-not establish a human sender; mail and host admissions can also lack one.
+goal pauses and resumes like any paused goal. Each run's goal tools are fenced
+by the goal revision that run saw, so a later follow-up command (for example a
+parent's message to a sub-agent) can complete, block, clear or resume a goal
+that paused on its own; a goal a person paused or stopped accepts only
+completion from the model, and only a person clears a live goal. When a
+tool-less goal turn ends while a recorded sub-agent command is live, the goal
+raises `goal-waiting` attention and rechecks on a timer instead of counting a
+stall; it continues once the child settles or replies. Only a live or paused
+goal asks before a replacement, which uses the observed revision to avoid
+replacing a newer goal; the replaced goal is recorded as cleared. When a runtime
+restart (a Hub deploy or eviction, a Local service restart) interrupts a goal
+turn, the turn resumes and the goal stays live. A live goal pauses when any turn
+of its Session fails, cannot resume or is stopped by a person (Esc), including
+the person's own messages ("The last turn failed"). A missing extension origin
+does not establish a human sender; mail and host admissions can also lack one.
 
 Goal's shared wire and durable row use `pauseCause: { kind, detail }` while
 paused and `null` while active. The closed kinds are `person`, `blocked`,
@@ -262,9 +269,14 @@ expands the footer rows, per Session and in memory).
 `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.
+`running` is working, `done` is idle and `errored` is failed. Attention that
+waits on a person (a question, or an approval an extension raises) is
+`needs you`; a question that waits on the Agent that sent the work is
+`waiting on <name>`, calm until it is escalated, and counted apart in the
+collapsed summary, which is amber only when a child needs a person. A
+`needs you` question carries its text and one Answer action that runs the
+question's own answer conversation. 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

package/dist/goal/contract.d.ts

@@ -44,9 +44,12 @@ export declare const EndedGoal: Schema.Struct<{
     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. */
+    /** Whether the model achieved the goal or it was cleared. */
     readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
-    /** The model's evidence for an achieved goal; null when cleared. */
+    /**
+     * The model's evidence for an achieved goal, or its explanation for
+     * clearing its own paused goal; null when a person cleared it.
+     */
     readonly reason: Schema.NullOr<Schema.String>;
     /** Completion time in epoch milliseconds. */
     readonly endedAt: Schema.Int;
@@ -74,7 +77,9 @@ export declare const GoalCommandInput: Schema.Union<readonly [Schema.Struct<{
     readonly confirmed: Schema.optional<Schema.Boolean>;
 }>, Schema.Struct<{
     /** Select an existing-goal control. */
-    readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear"]>;
+    readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear", "clear-ask"]>;
+    /** The human's answer to "clear this goal?"; absent for a typed clear. */
+    readonly confirmed: Schema.optional<Schema.Boolean>;
 }>, Schema.Struct<{}>]>;
 /** Goal's contract: Session-scope human controls and one projection slot. */
 export declare const GoalProjection: Schema.Struct<{
@@ -102,9 +107,12 @@ export declare const GoalProjection: Schema.Struct<{
         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. */
+        /** Whether the model achieved the goal or it was cleared. */
         readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
-        /** The model's evidence for an achieved goal; null when cleared. */
+        /**
+         * The model's evidence for an achieved goal, or its explanation for
+         * clearing its own paused goal; null when a person cleared it.
+         */
         readonly reason: Schema.NullOr<Schema.String>;
         /** Completion time in epoch milliseconds. */
         readonly endedAt: Schema.Int;
@@ -138,7 +146,9 @@ export declare const goalContract: {
                 readonly confirmed: Schema.optional<Schema.Boolean>;
             }>, Schema.Struct<{
                 /** Select an existing-goal control. */
-                readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear"]>;
+                readonly action: Schema.Literals<readonly ["pause", "resume", "replace", "clear", "clear-ask"]>;
+                /** The human's answer to "clear this goal?"; absent for a typed clear. */
+                readonly confirmed: Schema.optional<Schema.Boolean>;
             }>, Schema.Struct<{}>]>;
             /** Return the server-owned conversation step. */
             readonly output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
@@ -214,6 +224,12 @@ export declare const goalContract: {
                 readonly expectedRevision: Schema.NullOr<Schema.String>;
                 /** Idempotency key for this setting command. */
                 readonly requestId: Schema.String;
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                readonly adoptCommandId: Schema.optionalKey<Schema.String>;
             }>;
             /** Return the goal and its admission receipt. */
             readonly output: Schema.Struct<{
@@ -273,9 +289,12 @@ export declare const goalContract: {
                 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. */
+                /** Whether the model achieved the goal or it was cleared. */
                 readonly outcome: Schema.Literals<readonly ["achieved", "cleared"]>;
-                /** The model's evidence for an achieved goal; null when cleared. */
+                /**
+                 * The model's evidence for an achieved goal, or its explanation for
+                 * clearing its own paused goal; null when a person cleared it.
+                 */
                 readonly reason: Schema.NullOr<Schema.String>;
                 /** Completion time in epoch milliseconds. */
                 readonly endedAt: Schema.Int;

package/dist/goal/contract.js

@@ -46,9 +46,12 @@ export const EndedGoal = Schema.Struct({
     sequence: Schema.Int.check(Schema.isGreaterThan(0)),
     /** Objective that finished or was cleared. */
     objective: Objective,
-    /** Whether the model achieved the goal or a person cleared it. */
+    /** Whether the model achieved the goal or it was cleared. */
     outcome: Schema.Literals(["achieved", "cleared"]),
-    /** The model's evidence for an achieved goal; null when cleared. */
+    /**
+     * The model's evidence for an achieved goal, or its explanation for
+     * clearing its own paused goal; null when a person cleared it.
+     */
     reason: Schema.NullOr(GoalReason),
     /** Completion time in epoch milliseconds. */
     endedAt: EpochMillis,
@@ -76,7 +79,15 @@ export const GoalCommandInput = Schema.Union([
     }),
     Schema.Struct({
         /** Select an existing-goal control. */
-        action: Schema.Literals(["pause", "resume", "replace", "clear"]),
+        action: Schema.Literals([
+            "pause",
+            "resume",
+            "replace",
+            "clear",
+            "clear-ask",
+        ]),
+        /** The human's answer to "clear this goal?"; absent for a typed clear. */
+        confirmed: Schema.optional(Schema.Boolean),
     }),
     Schema.Struct({}),
 ]);
@@ -143,6 +154,12 @@ export const goalContract = {
                 expectedRevision: Schema.NullOr(Schema.String),
                 /** Idempotency key for this setting command. */
                 requestId: RequestId,
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                adoptCommandId: Schema.optionalKey(RequestId),
             }),
             /** Return the goal and its admission receipt. */
             output: Schema.Struct({

package/dist/goal/host.d.ts

@@ -1,5 +1,8 @@
 import { type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
+import type { SubagentSource } from "../subagents/host.js";
 /** 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. */
+/** Botanical's Session goal; hosts with created-Agent facts include them in progress. */
+export declare function goalExtensionFor(subagents?: SubagentSource): RosteredExtensionV0;
+/** Ordinary roster when no created-Agent directory is available. */
 export declare const goalExtension: RosteredExtensionV0;