@fungi.computer/parakeet 0.4.0 → 0.6.0

package/dist/conversation.js

@@ -9,6 +9,7 @@ import { atom, createStore, } from "jotai/vanilla";
 import { atomWithInfiniteQuery, atomWithMutation, atomWithQuery, } from "jotai-tanstack-query";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore, } from "react";
 import { buildDurableTimeline, buildTimelineTail, } from "./core/build-timeline.js";
+import { overlayToolOutput } from "./core/tool-groups.js";
 import { mergeCompactionNotices, mergeCompactions, mergeMessages, } from "./core/session-projection.js";
 import { sessionHistoryQueryOptions, sessionQueryOptions, } from "./core/session-query.js";
 import { sameSessionViewState, sessionActivityStatus, sessionViewState, } from "./core/session-view-state.js";
@@ -66,7 +67,7 @@ function composerStatus(snapshot, admissions, failure) {
         return status;
     if (failure !== undefined || view.kind === "error")
         return "error";
-    if (admissions.some(({ status: state }) => state === "accepted"))
+    if (admissions.some(({ status: state }) => state === "accepted" || state === "queued-local"))
         return "queued";
     if (admissions.some(({ status: state }) => state === "admitting"))
         return "sending";
@@ -100,12 +101,15 @@ function acquireDraftStorage(supplied) {
         const browser = globalThis;
         const storage = browser.localStorage;
         return storage === undefined
-            ? { status: "unavailable" }
+            ? {
+                status: "unavailable",
+                cause: new Error("Browser draft storage is unavailable"),
+            }
             : { status: "available", storage };
     }
-    catch {
+    catch (cause) {
         // An opaque-origin sandbox denies even reading the browser's getter.
-        return { status: "unavailable" };
+        return { status: "unavailable", cause };
     }
 }
 function createConversationAtoms(session, queryClient, authorOf, interactions, draftStorage, draftScope, contributions, shown) {
@@ -113,13 +117,14 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
     const saved = journal.read();
     let mounted = false;
     const timers = new Map();
-    const recoveryReasons = new Map(saved.pending.map(({ requestId }) => [
-        requestId,
-        "Closed before confirmation",
-    ]));
+    const recoveryReasons = new Map();
+    for (const pending of saved.pending)
+        if (pending.status === "admitting")
+            recoveryReasons.set(pending.requestId, "Closed before confirmation");
     const recovering = new Set();
     const queryAtom = atomWithQuery(() => sessionQueryOptions(session), () => queryClient);
     const snapshotAtom = atom((get) => get(queryAtom).data?.snapshot);
+    const lastReplyAtAtom = atom((get) => get(queryAtom).data?.lastReplyAt);
     const pinnedHistoryAtom = atom(undefined);
     const historyBeforeAtom = atom((get) => (get(pinnedHistoryAtom) ?? get(snapshotAtom))?.oldestCursor ?? null);
     const historyAtom = atomWithInfiniteQuery((get) => sessionHistoryQueryOptions(session, get(historyBeforeAtom)), () => queryClient);
@@ -279,10 +284,7 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
     const recallStateAtom = atom({ kind: "idle" });
     let recallOwner;
     const draftRevisionAtom = atom(0);
-    const rawAdmissionsAtom = atom(saved.pending.map((pending) => ({
-        ...pending,
-        status: "admitting",
-    })));
+    const rawAdmissionsAtom = atom(saved.pending);
     const persistAtom = atom(null, (get, _set, state) => {
         // Unavailable storage is session-only, not a pretend durable journal.
         // A supplied adapter's write failures still refuse durable operations.
@@ -299,16 +301,19 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
             recall: state?.recall === null
                 ? undefined
                 : (state?.recall ?? get(recallReservationAtom)),
-            pending: (state?.admissions ?? get(rawAdmissionsAtom))
-                .filter(({ status }) => status === "admitting")
-                .map(({ requestId, content, submittedDraft, delivery, images, restoreDraft, }) => ({
-                requestId,
-                content,
-                submittedDraft,
-                delivery,
-                images,
-                restoreDraft,
-            })),
+            pending: (state?.admissions ?? get(rawAdmissionsAtom)).flatMap(({ status, requestId, content, submittedDraft, delivery, images, restoreDraft, }) => status === "admitting" || status === "queued-local"
+                ? [
+                    {
+                        status,
+                        requestId,
+                        content,
+                        submittedDraft,
+                        delivery,
+                        images,
+                        restoreDraft,
+                    },
+                ]
+                : []),
         });
     });
     const recallAtom = atom(null, (get, set) => {
@@ -436,6 +441,24 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
         set(draftAtom, value);
         set(admissionErrorAtom, undefined);
     });
+    const setImagesAtom = atom(null, (get, set, images) => {
+        const next = images === undefined || images.length === 0 ? undefined : images;
+        try {
+            set(persistAtom, {
+                draftPayload: { images: next, delivery: get(draftDeliveryAtom) },
+            });
+        }
+        catch (cause) {
+            reportFailure("save draft images", cause);
+            interactions.toast({
+                variant: "error",
+                message: `Images not saved: ${errorMessage(cause)}`,
+            });
+        }
+        set(draftImagesAtom, next);
+        set(draftRevisionAtom, (revision) => revision + 1);
+        set(admissionErrorAtom, undefined);
+    });
     /** Consume only the exact draft a command submitted. */
     const clearSubmittedDraftAtom = atom(null, (get, set, submitted) => {
         if (get(draftRevisionAtom) !== submitted.revision ||
@@ -516,7 +539,9 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
             hasMoreHistory: get(hasMoreHistoryAtom),
             hasNewerHistory: get(hasNewerHistoryAtom),
             loadingOlderHistory: get(loadingOlderHistoryAtom),
-            settled: durable.items,
+            settled: overlayToolOutput(durable.items, get(toolActivityAtom) === undefined
+                ? []
+                : (get(snapshotAtom)?.toolOutput ?? [])),
             tail: get(tailAtom),
         };
         return durable.model === undefined || durable.usage === undefined
@@ -616,6 +641,10 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
             set(draftDeliveryAtom, undefined);
             set(setDraftAtom, "");
         }
+        // The offline prompt is saved alongside the draft. Await a fresh owner
+        // baseline before attempting admission.
+        if (admission.status === "queued-local")
+            return;
         const prompt = {
             type: "prompt",
             text: admission.content,
@@ -730,6 +759,20 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
     const maintainRecoveryAtom = atom(null, (get, set) => {
         const observation = get(observationAtom).status;
         const admissions = get(rawAdmissionsAtom);
+        if (observation === "live") {
+            if (get(admissionErrorAtom) === "offline_queue_full")
+                set(admissionErrorAtom, undefined);
+            const queued = admissions.find(({ status }) => status === "queued-local");
+            if (queued !== undefined) {
+                const sending = {
+                    ...queued,
+                    status: "admitting",
+                };
+                set(rawAdmissionsAtom, (current) => current.map((candidate) => candidate.requestId === queued.requestId ? sending : candidate));
+                // Preserve the idempotent request id when reconnect admits the prompt.
+                set(dispatchAdmissionAtom, { admission: sending, consumeDraft: false });
+            }
+        }
         for (const [id, timer] of timers) {
             if (!admissions.some(({ requestId, status }) => requestId === id && status === "admitting")) {
                 clearTimeout(timer);
@@ -774,6 +817,12 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
             return;
         const admissions = get(admissionsAtom);
         const unresolved = admissions.filter(({ status }) => status !== "failed");
+        const offline = get(observationAtom).status !== "live";
+        if (offline &&
+            unresolved.some(({ status }) => status === "queued-local")) {
+            set(admissionErrorAtom, "offline_queue_full");
+            return;
+        }
         if (unresolved.length >= MAX_UNRESOLVED_LOCAL_ADMISSIONS) {
             set(admissionErrorAtom, "queue_full");
             return;
@@ -785,7 +834,7 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
             requestId: nanoid(),
             submittedDraft: draft,
             restoreDraft: true,
-            status: "admitting",
+            status: offline ? "queued-local" : "admitting",
         };
         set(rawAdmissionsAtom, [...admissions, admission]);
         set(latestSubmissionIdAtom, admission.requestId);
@@ -991,6 +1040,7 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
         jumpToLatestAtom,
         loadOlderHistoryAtom,
         loadNewerHistoryAtom,
+        lastReplyAtAtom,
         observationAtom,
         observedCommandIdsAtom,
         rawAdmissionsAtom,
@@ -1002,6 +1052,7 @@ function createConversationAtoms(session, queryClient, authorOf, interactions, d
         reconnectAtom,
         retryAtom,
         setDraftAtom,
+        setImagesAtom,
         sendAtom,
         snapshotAtom,
         statusAtom,
@@ -1080,11 +1131,8 @@ export function ParakeetProvider({ children, session, clients = noClients, inter
     }, [scope, onToast]);
     useEffect(() => {
         if (acquiredDraftStorage.status === "unavailable")
-            scope.interactions.report({
-                tone: "info",
-                message: "Drafts are session-only because browser storage is unavailable. They will be lost when this conversation closes.",
-            });
-    }, [scope, acquiredDraftStorage]);
+            reportFailure("acquire draft storage", acquiredDraftStorage.cause);
+    }, [acquiredDraftStorage]);
     useEffect(() => {
         const reconcile = () => {
             scope.store.set(scope.atoms.reconcileQueuedCancellationAtom);
@@ -1180,6 +1228,7 @@ export function useComposer() {
     const failure = useStoreAtom(atoms.failureAtom);
     const admissionError = useStoreAtom(atoms.admissionErrorAtom);
     const setDraft = useStoreSetter(atoms.setDraftAtom);
+    const setImages = useStoreSetter(atoms.setImagesAtom);
     const checkpointDraft = useStoreSetter(atoms.checkpointDraftAtom);
     const send = useStoreSetter(atoms.sendAtom);
     const submitCommand = useStoreSetter(atoms.submitCommandAtom);
@@ -1202,6 +1251,7 @@ export function useComposer() {
         retry: retryLatest,
         send,
         setDraft,
+        setImages,
         submitCommand,
     }), [
         admissionError,
@@ -1216,6 +1266,7 @@ export function useComposer() {
         retryLatest,
         send,
         setDraft,
+        setImages,
         submitCommand,
     ]);
 }
@@ -1250,6 +1301,10 @@ export function useStatus() {
         viewState,
     }), [commandId, context, observation, reconnect, status, viewState]);
 }
+/** Time of the last delivered watch snapshot or frame, not an SSE comment. */
+export function useLastSessionReplyAt() {
+    return useStoreAtom(useConversationScope().atoms.lastReplyAtAtom);
+}
 /** Presentation admitted once from the selected Session's already observed slots. */
 export function useClientContributions() {
     return useStoreAtom(useConversationScope().contributions);

package/dist/core/approval-decision.d.ts

@@ -0,0 +1,198 @@
+import type { WhistleInteraction } from "@fungi.computer/whistle";
+/** The ledger facts an approval card reads; the approvals ledger's own view satisfies it. */
+export type ApprovalFacts = Readonly<{
+    /** The durable record. */
+    record: Readonly<{
+        /** Identity of the record. */
+        recordId: string;
+        /** Changes whenever the record does; an answer names the revision it saw. */
+        revision: number;
+        /** Who asked. */
+        requester: Readonly<{
+            /** Name shown for the requesting Agent. */
+            displayName: string;
+            /** The Agent, when one asked. */
+            agentId: string | null;
+            /** The Session, when one asked. */
+            sessionId: string | null;
+            /** The principal that holds the request. */
+            principalId: string;
+        }>;
+        /** The tool's module. */
+        module: string;
+        /** The tool's operation. */
+        operation: string;
+        /** Whether the tool writes inside Fungi or reaches outside it. */
+        access: string;
+        /** What the tool would be given, as the ledger describes it. */
+        description: Readonly<{
+            /** Size of the input in bytes. */
+            inputBytes: number;
+            /** Digest of the input. */
+            inputSha256: string;
+        }>;
+        /** Whether the effect can be undone. */
+        reversibility: string;
+        /** When the request lapses. */
+        expiresAt: number;
+    }>;
+    /** The holder may answer it. */
+    canAnswer: boolean;
+}>;
+/** What the host knows about a command the Agent asked to run outside the sandbox. */
+export type ApprovalReview = Readonly<{
+    /** The command line. */
+    command: string;
+    /** Where it would run. */
+    cwd: string;
+    /** Why the Agent says it needs it. */
+    justification: string;
+    /** A direct program, or shell text. */
+    form: "direct" | "shell";
+    /** A command, or an extension install. */
+    kind: "exec" | "extension-install";
+    /** The program and its arguments, when direct. */
+    argv?: readonly string[];
+    /** The command words an Always-allow rule would match. */
+    prefix?: readonly string[];
+    /** A warning shown when no rule is offered. */
+    warning?: string;
+    /** Everything an Always-allow rule would cover. */
+    alwaysAllowCoverage?: string;
+    /** Why no Always-allow rule is offered. */
+    alwaysAllowUnavailableReason?: string;
+    /** What a reusable rule risks. */
+    risk?: Readonly<{
+        /** The risk in one sentence, named once above the confirmation. */
+        summary: string;
+        /** The risk in full, shown under Details. */
+        detail: string;
+    }>;
+}>;
+/** One labelled value in a card's facts or details. */
+export type ApprovalEntry = Readonly<{
+    /** What the value is. */
+    label: string;
+    /** The value. */
+    value: string;
+}>;
+/** The words an approval prompt carries above its choices. */
+export type ApprovalContent = Readonly<{
+    /** The title. */
+    title: string;
+    /** One sentence under it. */
+    summary?: string | undefined;
+    /** Short labelled lines. */
+    facts?: readonly ApprovalEntry[] | undefined;
+    /** Long text, when the command is too long for a title. */
+    body?: string | undefined;
+    /** A short name for `body`. */
+    bodyLabel?: string | undefined;
+    /** Everything else, shown on demand. */
+    details?: readonly ApprovalEntry[] | undefined;
+}>;
+/** Everything one approval shows, and what Always allow would confirm. */
+export type ApprovalCard = Readonly<{
+    /** The first prompt's words. */
+    content: ApprovalContent;
+    /** The Always-allow choice, when a rule is offered. */
+    always?: string | undefined;
+    /** What the Always-allow confirmation says. */
+    confirmation?: (ApprovalContent & {
+        /** The rule's coverage, whole. */
+        body: string;
+    }) | undefined;
+    /** The risk named above the confirmation, once. */
+    confirmWarning?: string | undefined;
+    /** The confirming choice. */
+    confirmYes?: string | undefined;
+}>;
+/**
+ * The words of one approval. A connected tool gets its effect; a command the
+ * Agent wants to run outside the sandbox gets its folder, reason and rule.
+ * `home` shortens paths inside it to `~`; `now` dates the expiry.
+ */
+export declare function approvalCardCopy(view: ApprovalFacts, review: ApprovalReview | undefined, options: Readonly<{
+    width: number;
+    home: string;
+    now: number;
+}>): ApprovalCard;
+/** What an answer was refused for, in words for the person. */
+export declare function approvalRefusal(reason: string, decision: "approve" | "deny" | "always-allow"): string;
+/** What the person decided. */
+export type ApprovalDecision = "approve" | "deny" | "always-allow";
+/** A decision, pinned to the revision the person saw. */
+export type ApprovalAnswerInput = Readonly<{
+    /** The record being answered. */
+    recordId: string;
+    /** Approve once, deny, or approve and keep a rule. */
+    decision: ApprovalDecision;
+    /** The revision on screen; a changed record refuses the answer. */
+    expectedRevision: number;
+    /** Why it was denied, when the person said. */
+    denialNote?: string;
+}>;
+/** How the owner took an answer; a refusal names its reason. */
+export type ApprovalAnswerResult = Readonly<{
+    /** `refused`, or whatever else the owner calls an accepted answer. */
+    kind: string;
+    /** Why it was refused. */
+    reason?: string;
+}>;
+/** Where approvals come from and where answers go. */
+export type ApprovalSource = Readonly<{
+    /** The record being shown, when there is one. */
+    snapshot: () => ApprovalFacts | undefined;
+    /** Observe the record changing. */
+    subscribe: (listener: () => void) => () => void;
+    /** What the host knows about the command, for an escape review. */
+    review?: ApprovalReview | undefined;
+    /** Answer it; a refusal names its reason. */
+    answer: (input: ApprovalAnswerInput) => Promise<ApprovalAnswerResult>;
+    /** Let the whole family of this tool through from now on, where the surface can. */
+    family?: Readonly<{
+        /** The choice's name. */
+        label: string;
+        /** Turn the rule on; false when it was refused. */
+        enable: () => Promise<boolean>;
+    }> | undefined;
+}>;
+/** The answer was sent. */
+export type ApprovalAnswered = Readonly<{
+    /** Discriminant. */
+    kind: "answered";
+}>;
+/** The answer was refused, or could not be sent. */
+export type ApprovalRefused = Readonly<{
+    /** Discriminant. */
+    kind: "refused";
+    /** What to tell the person. */
+    message: string;
+}>;
+/** The record changed or went away before an answer was sent. */
+export type ApprovalAbandoned = Readonly<{
+    /** Discriminant. */
+    kind: "abandoned";
+}>;
+/** How asking ended. */
+export type ApprovalOutcome = ApprovalAnswered | ApprovalRefused | ApprovalAbandoned;
+/**
+ * Ask the person about one approval through a conversation's decision
+ * prompts, then send the answer. Nothing is sent until Enter answers, Always
+ * allow and the family rule each need a second, separate confirmation whose
+ * default is Back, and an
+ * answer is only sent while the record is still the one that was shown.
+ */
+export declare function askApproval(interaction: WhistleInteraction, input: Readonly<{
+    view: ApprovalFacts;
+    source: ApprovalSource;
+    home: string;
+    width: number;
+    now: number;
+    /** The longest denial note. */
+    noteLimit: number;
+    /** The record on screen is still the current one. */
+    stillCurrent: () => boolean;
+    /** An error reached the person as a refusal; report its cause. */
+    onFailure: (cause: unknown) => void;
+}>): Promise<ApprovalOutcome>;