@fungi.computer/shiitake-extensions 0.2.0 → 0.4.0

package/dist/roster/conversation-agents.d.ts

@@ -1,31 +1,38 @@
 import { type AgentControlDirectory } from "@fungi.computer/shiitake/agent-control";
 import type { CapabilitySource } from "@fungi.computer/mycelium";
+import { type ShiitakeSession } from "@fungi.computer/shiitake/client";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
-import { type SubagentSource } from "../subagents/host.js";
+import type { SubagentSource } from "../subagents/host.js";
 /** Host-pack creation admission; attachments/model selection retain their own owners. */
 export declare function assertOrdinaryAgentCreation(input: Parameters<NonNullable<AgentControlDirectory["create"]>>[0]): void;
+/** The directory a conversation sends through; opening a recipient only needs its Sessions' extension doors. */
+type SendingDirectory = Omit<AgentControlDirectory, "open"> & Readonly<{
+    open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
+        agent: Readonly<{
+            session: (sessionId: string) => Pick<ShiitakeSession, "extension">;
+        }>;
+        release: () => Promise<void>;
+    }>>;
+}>;
 /**
  * This host's own record of the Agents each conversation created or sent
  * accepted work to, written as its Agent-control directory accepts them
- * (Wiki: agent-runtime-tools-and-clients, read-only sub-agent view). It feeds
- * the footer only; it owns no relationship and grants nothing.
+ * (Wiki: agent-runtime-tools-and-clients, read-only sub-agent view). Accepted
+ * child command receipts are separately reconciled against their owner's
+ * settlement records for the parent's goal guard. Neither record grants
+ * authority over a child.
  */
 export declare function createConversationAgents(storage: WatchdogSqliteOwner): {
     /** Bind acceptance recording to this conversation's existing directory. */
-    recording: (parentSessionId: string | undefined, directory: AgentControlDirectory) => AgentControlDirectory;
+    recording: <Directory extends SendingDirectory>(parentSessionId: string | undefined, directory: Directory) => Directory;
     /** Agent-control tools bound to the conversation that acquires them. */
     control: (directoryFor: (parentSessionId: string | undefined) => AgentControlDirectory) => CapabilitySource;
     /** The footer rows for one conversation; archived and unknown Agents leave it. */
-    source: (directory: Pick<AgentControlDirectory, "list" | "open">) => SubagentSource;
+    source: (directory: Pick<AgentControlDirectory, "list"> & Pick<SubagentSource, "open">) => SubagentSource;
 };
 /** Both hosts compose the ordinary roster and its read-only created-Agent footer. */
-export declare function oysterAgentExtensions(source: SubagentSource): {
-    /** Ordinary extensions plus the read-only created-Agent footer. */
-    roster: import("@fungi.computer/shiitake").RosteredExtensionV0[];
-    /** Host grants corresponding to the composed extension roster. */
-    grants: Readonly<{
-        id: import("@fungi.computer/shiitake/extensions").ExtensionId;
-        capabilities: readonly import("@fungi.computer/shiitake").ExtensionCapabilityV0[];
-        grantKey?: string;
-    }>[];
-};
+export declare function oysterAgentExtensions(source: SubagentSource): Readonly<{
+    roster: readonly import("@fungi.computer/shiitake").RosteredExtensionV0[];
+    grants: readonly import("@fungi.computer/shiitake").ExtensionGrantV0[];
+}>;
+export {};

package/dist/roster/conversation-agents.js

@@ -1,7 +1,9 @@
 import { AgentCreateRefused, createAgentControlSource, } from "@fungi.computer/shiitake/agent-control";
+import { bindSessionExtension, } from "@fungi.computer/shiitake/client";
+import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { botanicalAgentExtensions } from "../roster.js";
-import { subagentsExtension, subagentsGrant, } from "../subagents/host.js";
+import { botanicalAgentExtensions, botanicalExtensionsWithSubagents, } from "../roster.js";
+import { goalContract } from "../goal/contract.js";
 /** Host-pack creation admission; attachments/model selection retain their own owners. */
 export function assertOrdinaryAgentCreation(input) {
     if (input.model !== undefined)
@@ -14,11 +16,34 @@ const conversationAgentRow = Schema.Struct({
     agent_id: Schema.String,
     session_id: Schema.NullOr(Schema.String),
 });
+const delegatedCommandRow = Schema.Struct({
+    parent_session_id: Schema.String,
+    agent_id: Schema.String,
+    session_id: Schema.String,
+    command_id: Schema.String,
+    at: Schema.Number,
+});
+/** Private safety ceilings for command-status polling; not a delegation policy. */
+const maxWatchedCommands = 64;
+const pollMs = 2_000;
+const maxWatchMs = 30 * 60_000;
+/** The objective of a delegated lane: the named goal, else the send's first line. */
+function laneObjective(text, goal) {
+    const named = goal?.trim();
+    if (named !== undefined && named !== "")
+        return named;
+    return (text
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line !== "") ?? text.trim()).slice(0, 4_000);
+}
 /**
  * This host's own record of the Agents each conversation created or sent
  * accepted work to, written as its Agent-control directory accepts them
- * (Wiki: agent-runtime-tools-and-clients, read-only sub-agent view). It feeds
- * the footer only; it owns no relationship and grants nothing.
+ * (Wiki: agent-runtime-tools-and-clients, read-only sub-agent view). Accepted
+ * child command receipts are separately reconciled against their owner's
+ * settlement records for the parent's goal guard. Neither record grants
+ * authority over a child.
  */
 export function createConversationAgents(storage) {
     // Composing a host does no storage I/O; the first record or read prepares it.
@@ -27,6 +52,7 @@ export function createConversationAgents(storage) {
         if (!prepared) {
             storage.sql.exec("CREATE TABLE IF NOT EXISTS oyster_conversation_agents (parent_session_id TEXT NOT NULL, agent_id TEXT NOT NULL, session_id TEXT, at INTEGER NOT NULL, PRIMARY KEY (parent_session_id, agent_id)) STRICT");
             storage.sql.exec("CREATE INDEX IF NOT EXISTS idx_oyster_conversation_agents_parent ON oyster_conversation_agents(parent_session_id, at)");
+            storage.sql.exec("CREATE TABLE IF NOT EXISTS oyster_delegated_commands (parent_session_id TEXT NOT NULL, agent_id TEXT NOT NULL, session_id TEXT NOT NULL, command_id TEXT NOT NULL PRIMARY KEY, at INTEGER NOT NULL) STRICT");
             prepared = true;
         }
         return storage.sql;
@@ -36,8 +62,12 @@ export function createConversationAgents(storage) {
         sql().exec("INSERT OR IGNORE INTO oyster_conversation_agents(parent_session_id, agent_id, session_id, at) VALUES (?, ?, NULL, ?)", parentSessionId, agentId, Date.now());
     }
     /** A send may not know its Session until the recipient accepts it. */
-    function sent(parentSessionId, agentId, sessionId) {
+    function sent(parentSessionId, agentId, sessionId, commandId) {
         sql().exec("INSERT INTO oyster_conversation_agents(parent_session_id, agent_id, session_id, at) VALUES (?, ?, ?, ?) ON CONFLICT(parent_session_id, agent_id) DO UPDATE SET session_id = excluded.session_id, at = excluded.at", parentSessionId, agentId, sessionId ?? null, Date.now());
+        if (sessionId !== undefined) {
+            sql().exec("INSERT OR REPLACE INTO oyster_delegated_commands(parent_session_id, agent_id, session_id, command_id, at) VALUES (?, ?, ?, ?, ?)", parentSessionId, agentId, sessionId, commandId, Date.now());
+            sql().exec("DELETE FROM oyster_delegated_commands WHERE command_id NOT IN (SELECT command_id FROM oyster_delegated_commands ORDER BY at DESC LIMIT ?)", maxWatchedCommands);
+        }
     }
     /** One conversation's directory: its accepted creates and sends are recorded. */
     function recording(parentSessionId, directory) {
@@ -57,7 +87,31 @@ export function createConversationAgents(storage) {
                 ...recorded,
                 send: async (task, sourceSessionId, signal, invocation) => {
                     const accepted = await send(task, sourceSessionId, signal, invocation);
-                    sent(sourceSessionId, task.agentId, task.sessionId);
+                    if (accepted.status === "accepted") {
+                        const sessionId = accepted.sessionId ?? task.sessionId;
+                        sent(sourceSessionId, task.agentId, sessionId, accepted.commandId);
+                        // A send that opens a new Session puts it under a goal, so the
+                        // lane keeps working until it reports complete or blocked. A
+                        // retry replays the same request id, so the goal is set once.
+                        if (task.delivery === "followUp" &&
+                            task.sessionId === undefined &&
+                            task.goal !== false &&
+                            sessionId !== undefined) {
+                            const opened = await directory.open(task.agentId, signal);
+                            try {
+                                await bindSessionExtension(opened.agent.session(sessionId), goalContract).call("set", {
+                                    objective: laneObjective(task.text, task.goal),
+                                    expectedRevision: null,
+                                    requestId: `lane-goal:${accepted.commandId}`,
+                                    // The send is the lane's first turn; never repeat it.
+                                    adoptCommandId: accepted.commandId,
+                                });
+                            }
+                            finally {
+                                await opened.release();
+                            }
+                        }
+                    }
                     return accepted;
                 },
             };
@@ -75,40 +129,110 @@ export function createConversationAgents(storage) {
             },
         }),
         /** The footer rows for one conversation; archived and unknown Agents leave it. */
-        source: (directory) => ({
-            read: async (sessionId, limit) => {
-                const rows = sql()
-                    .exec("SELECT agent_id, session_id FROM oyster_conversation_agents WHERE parent_session_id = ? ORDER BY at DESC, agent_id", sessionId)
-                    .toArray()
-                    .map((row) => Schema.decodeUnknownSync(conversationAgentRow)(row));
-                const known = new Map((await directory.list(new AbortController().signal)).map((agent) => [
-                    agent.agentId,
-                    agent.name,
-                ]));
-                const agents = rows.flatMap((row) => {
-                    const name = known.get(row.agent_id);
-                    return name === undefined
-                        ? []
-                        : [{ agentId: row.agent_id, name, sessionId: row.session_id }];
-                });
-                return {
-                    agents: agents.slice(0, limit),
-                    more: Math.max(0, agents.length - limit),
+        source: (directory) => {
+            const polling = new Set();
+            const signal = new AbortController().signal;
+            function poll(commandId) {
+                if (polling.has(commandId) || polling.size >= maxWatchedCommands)
+                    return;
+                polling.add(commandId);
+                const check = async () => {
+                    let raw;
+                    try {
+                        raw = sql()
+                            .exec("SELECT parent_session_id, agent_id, session_id, command_id, at FROM oyster_delegated_commands WHERE command_id = ?", commandId)
+                            .toArray()[0];
+                    }
+                    catch (cause) {
+                        // The host's store was closed; no orphan poller may keep using it.
+                        Effect.runFork(Effect.logError("subagents.command-store-read", cause));
+                        polling.delete(commandId);
+                        return;
+                    }
+                    if (raw === undefined) {
+                        polling.delete(commandId);
+                        return;
+                    }
+                    const row = Schema.decodeUnknownSync(delegatedCommandRow)(raw);
+                    // An unobservable command cannot justify an indefinite live wait.
+                    if (Date.now() - row.at >= maxWatchMs) {
+                        sql().exec("DELETE FROM oyster_delegated_commands WHERE command_id = ?", commandId);
+                        polling.delete(commandId);
+                        return;
+                    }
+                    try {
+                        const opened = await directory.open(row.agent_id, signal);
+                        let settled;
+                        try {
+                            settled = await opened.agent
+                                .session(row.session_id)
+                                .readSettlement(commandId, {
+                                timeoutMs: 0,
+                                signal,
+                            });
+                        }
+                        finally {
+                            await opened.release();
+                        }
+                        if (settled !== undefined) {
+                            sql().exec("DELETE FROM oyster_delegated_commands WHERE command_id = ?", commandId);
+                            polling.delete(commandId);
+                            return;
+                        }
+                    }
+                    catch (cause) {
+                        // An unreadable child is not proof of live work; do not hold the guard.
+                        Effect.runFork(Effect.logError("subagents.command-status", cause));
+                        try {
+                            sql().exec("DELETE FROM oyster_delegated_commands WHERE command_id = ?", commandId);
+                        }
+                        catch (closed) {
+                            // Host teardown closed storage while the remote read was pending.
+                            Effect.runFork(Effect.logError("subagents.command-store-closed", closed));
+                        }
+                        polling.delete(commandId);
+                        return;
+                    }
+                    setTimeout(() => void check(), pollMs);
                 };
-            },
-            open: directory.open,
-        }),
+                void check();
+            }
+            return {
+                // Polling is demand-driven: only a parent whose goal asks about its
+                // live children watches their receipts, including ones recorded
+                // before a restart. Composing a host or sending mail does no polling.
+                hasLiveChildCommand: (sessionId) => {
+                    const live = sql()
+                        .exec("SELECT command_id FROM oyster_delegated_commands WHERE parent_session_id = ? AND at > ? ORDER BY at DESC LIMIT ?", sessionId, Date.now() - maxWatchMs, maxWatchedCommands)
+                        .toArray()
+                        .map((row) => Schema.decodeUnknownSync(Schema.Struct({ command_id: Schema.String }))(row).command_id);
+                    for (const commandId of live)
+                        poll(commandId);
+                    return live.length > 0;
+                },
+                read: async (sessionId, limit) => {
+                    const rows = sql()
+                        .exec("SELECT agent_id, session_id FROM oyster_conversation_agents WHERE parent_session_id = ? ORDER BY at DESC, agent_id", sessionId)
+                        .toArray()
+                        .map((row) => Schema.decodeUnknownSync(conversationAgentRow)(row));
+                    const known = new Map((await directory.list(new AbortController().signal)).map((agent) => [agent.agentId, agent.name]));
+                    const agents = rows.flatMap((row) => {
+                        const name = known.get(row.agent_id);
+                        return name === undefined
+                            ? []
+                            : [{ agentId: row.agent_id, name, sessionId: row.session_id }];
+                    });
+                    return {
+                        agents: agents.slice(0, limit),
+                        more: Math.max(0, agents.length - limit),
+                    };
+                },
+                open: directory.open,
+            };
+        },
     };
 }
 /** Both hosts compose the ordinary roster and its read-only created-Agent footer. */
 export function oysterAgentExtensions(source) {
-    return {
-        /** Ordinary extensions plus the read-only created-Agent footer. */
-        roster: [
-            ...botanicalAgentExtensions.roster,
-            subagentsExtension({ source }),
-        ],
-        /** Host grants corresponding to the composed extension roster. */
-        grants: [...botanicalAgentExtensions.grants, subagentsGrant],
-    };
+    return botanicalExtensionsWithSubagents(botanicalAgentExtensions, source);
 }

package/dist/roster.d.ts

@@ -1,9 +1,15 @@
 import type { ExtensionRosterV0 } from "@fungi.computer/shiitake/extensions";
 import type { SkillSource } from "./skills/source.js";
+import { type SubagentSource } from "./subagents/host.js";
 /**
- * Botanical's product roster with explicit grants. Hub and Local pass this
- * same value; a stranger host passes its own (or an empty) roster.
+ * Botanical's shared roster with explicit grants. Local composes its
+ * sender-routing question extension through `botanicalExtensionsWithSkills`;
+ * hosts without that Local capability send every Ask to a person.
  */
 export declare const botanicalAgentExtensions: ExtensionRosterV0;
+/** Compose the goal and footer over one source; an absent goal is a wiring error. */
+export declare function botanicalExtensionsWithSubagents(base: ExtensionRosterV0, source: SubagentSource): ExtensionRosterV0;
 /** A host with a SkillSource grants read-only skill discovery for its own runs. */
 export declare function botanicalExtensionsWithSkills(source: SkillSource): ExtensionRosterV0;
+/** Route Asks to the Agent that sent the work, only in a host that owns the Local answer door. */
+export declare function botanicalExtensionsWithSenderRouting(): ExtensionRosterV0;

package/dist/roster.js

@@ -1,17 +1,19 @@
 import { almanacContract } from "./almanac/contract.js";
 import { almanacExtension } from "./almanac/host.js";
 import { questionContract } from "./question/contract.js";
-import { questionExtension } from "./question/host.js";
+import { localQuestionExtension, questionExtension } from "./question/host.js";
 import { goalContract } from "./goal/contract.js";
-import { goalExtension } from "./goal/host.js";
+import { goalExtension, goalExtensionFor } from "./goal/host.js";
 import { loopContract } from "./loop/contract.js";
 import { loopExtension } from "./loop/host.js";
 import { planContract } from "./plan/contract.js";
 import { planExtension } from "./plan/host.js";
 import { skillsExtension, skillsGrant } from "./skills/host.js";
+import { subagentsExtension, subagentsGrant, } from "./subagents/host.js";
 /**
- * Botanical's product roster with explicit grants. Hub and Local pass this
- * same value; a stranger host passes its own (or an empty) roster.
+ * Botanical's shared roster with explicit grants. Local composes its
+ * sender-routing question extension through `botanicalExtensionsWithSkills`;
+ * hosts without that Local capability send every Ask to a person.
  */
 export const botanicalAgentExtensions = Object.freeze({
     roster: Object.freeze([
@@ -42,6 +44,7 @@ export const botanicalAgentExtensions = Object.freeze({
                 "state",
                 "settled",
                 "send",
+                "timers",
                 "commands",
                 "projection",
                 "run_tools",
@@ -72,10 +75,34 @@ export const botanicalAgentExtensions = Object.freeze({
         },
     ]),
 });
+/** Compose the goal and footer over one source; an absent goal is a wiring error. */
+export function botanicalExtensionsWithSubagents(base, source) {
+    if (!base.roster.some((extension) => extension.manifest.id === goalContract.id))
+        throw new Error("Cannot attach sub-agents without the goal extension");
+    return {
+        roster: [
+            ...base.roster.map((extension) => extension.manifest.id === goalContract.id
+                ? goalExtensionFor(source)
+                : extension),
+            subagentsExtension({ source }),
+        ],
+        grants: [...base.grants, subagentsGrant],
+    };
+}
 /** A host with a SkillSource grants read-only skill discovery for its own runs. */
 export function botanicalExtensionsWithSkills(source) {
+    const local = botanicalExtensionsWithSenderRouting();
+    return {
+        roster: [...local.roster, skillsExtension({ source })],
+        grants: [...local.grants, skillsGrant],
+    };
+}
+/** Route Asks to the Agent that sent the work, only in a host that owns the Local answer door. */
+export function botanicalExtensionsWithSenderRouting() {
     return {
-        roster: [...botanicalAgentExtensions.roster, skillsExtension({ source })],
-        grants: [...botanicalAgentExtensions.grants, skillsGrant],
+        ...botanicalAgentExtensions,
+        roster: botanicalAgentExtensions.roster.map((extension) => extension.manifest.id === questionContract.id
+            ? localQuestionExtension
+            : extension),
     };
 }

package/dist/skills/host.js

@@ -130,11 +130,29 @@ function skillsStep(found, name) {
         });
     return ask({
         type: "choice",
-        message: `${String(found.skills.length)} ${found.skills.length === 1 ? "skill" : "skills"} discovered${skipped}`,
+        message: `Skills (${String(found.skills.length)})`,
+        summary: reasons.length === 0
+            ? undefined
+            : `${String(reasons.length)} ${reasons.length === 1 ? "skill was" : "skills were"} not loaded. Details shows why.`,
+        details: [
+            ...reasons
+                .slice(0, config.maximumListedDiagnostics)
+                .map((diagnostic) => ({
+                label: diagnostic.reason,
+                value: `${diagnostic.message} (${diagnostic.path})`,
+            })),
+            ...found.skills.map((skill) => ({
+                label: skill.name,
+                value: skill.location,
+            })),
+        ].slice(0, 24),
         options: found.skills.map((skill) => ({
             value: skill.name,
             label: skill.name,
-            description: skill.location,
+            description: skill.description
+                .replace(/\s+/gu, " ")
+                .trim()
+                .slice(0, 100),
         })),
     }, {}, "name");
 }

package/dist/subagents/client.js

@@ -2,32 +2,64 @@ import { defineClientEntry, } from "@fungi.computer/shiitake/client-entry";
 import { subagentsContract, } from "./contract.js";
 const presentation = {
     working: { label: "working", tone: "running", status: "info" },
-    waiting: { label: "waiting on you", tone: "attention", status: "warning" },
+    waiting_on_agent: { label: "waiting", tone: "muted", status: "neutral" },
+    needs_you: { label: "needs you", tone: "attention", status: "warning" },
     idle: { label: "idle", tone: "settled", status: "success" },
     failed: { label: "failed", tone: "error", status: "error" },
     unavailable: { label: "unavailable", tone: "muted", status: "neutral" },
 };
+/** "waiting on Shiitake": the Agent a calm child waits on, never "you". */
+function label(agent) {
+    return agent.state === "waiting_on_agent"
+        ? `waiting on ${agent.waitingOn ?? "its parent"}`
+        : presentation[agent.state].label;
+}
 function row(agent) {
     const shown = presentation[agent.state];
     const base = {
         id: agent.agentId,
-        title: `${agent.name} · ${shown.label}`,
+        title: `${agent.name} · ${label(agent)}`,
         tone: shown.tone,
-        status: { label: shown.label, tone: shown.status },
+        status: { label: label(agent), tone: shown.status },
     };
-    const detailed = agent.attention === undefined ? base : { ...base, detail: agent.attention };
+    // The question itself, so a person can decide without opening the child.
+    const asked = agent.ask?.questions[0]?.question;
+    const text = asked ?? agent.attention;
+    const detailed = text === undefined ? base : { ...base, detail: text.slice(0, 200) };
     // An Agent created but never messaged has no conversation to open yet.
-    return agent.sessionId === null
-        ? { ...detailed, detail: agent.attention ?? "not messaged yet" }
-        : {
-            ...detailed,
-            open: {
-                params: [
-                    { key: "agent", value: agent.agentId },
-                    { key: "session", value: agent.sessionId },
-                ],
-            },
-        };
+    if (agent.sessionId === null)
+        return { ...detailed, detail: agent.attention ?? "not messaged yet" };
+    const opened = {
+        ...detailed,
+        open: {
+            params: [
+                { key: "agent", value: agent.agentId },
+                { key: "session", value: agent.sessionId },
+            ],
+        },
+    };
+    if (agent.ask === undefined)
+        return opened;
+    const answer = {
+        id: "answerChild",
+        label: "Answer",
+        input: {
+            agentId: agent.agentId,
+            sessionId: agent.sessionId,
+            askId: agent.ask.askId,
+        },
+    };
+    // A question offers the one Answer action, calm or not: a person may always
+    // answer, and the first answer wins. Only a question that needs the person
+    // takes over the composer.
+    return {
+        ...opened,
+        actions: [
+            agent.state === "needs_you"
+                ? { ...answer, awaiting: "question" }
+                : answer,
+        ],
+    };
 }
 /**
  * One summary row while the footer is collapsed: how
@@ -36,12 +68,24 @@ function row(agent) {
  */
 function summary(view) {
     const count = (state) => view.agents.filter((agent) => agent.state === state).length;
-    const counts = ["working", "waiting", "failed", "unavailable"]
-        .map((state) => [state, count(state)])
-        .filter(([, n]) => n > 0)
-        .map(([state, n]) => `${String(n)} ${presentation[state].label}`);
+    const calm = view.agents.filter((agent) => agent.state === "waiting_on_agent");
+    // Calm children name who they wait on; only needs-you children are amber.
+    const waiting = [
+        ...new Set(calm.map((agent) => agent.waitingOn ?? "its parent")),
+    ].map((name) => `${String(calm.filter((agent) => (agent.waitingOn ?? "its parent") === name).length)} waiting on ${name}`);
+    const counts = [
+        ...["working"]
+            .map((state) => [state, count(state)])
+            .filter(([, n]) => n > 0)
+            .map(([state, n]) => `${String(n)} ${presentation[state].label}`),
+        ...waiting,
+        ...["needs_you", "failed", "unavailable"]
+            .map((state) => [state, count(state)])
+            .filter(([, n]) => n > 0)
+            .map(([state, n]) => `${String(n)} ${presentation[state].label}`),
+    ];
     const total = view.agents.length + view.more;
-    const tone = count("waiting") > 0
+    const tone = count("needs_you") > 0
         ? "attention"
         : count("failed") > 0
             ? "error"