@fungi.computer/parakeet 0.4.0 → 0.6.0

package/dist/core/approval-decision.js

@@ -0,0 +1,291 @@
+const shorten = (value, width) => {
+    if (value.length <= width)
+        return value;
+    const left = Math.max(1, Math.floor((width - 1) / 2));
+    return `${value.slice(0, left)}…${value.slice(-(width - left - 1))}`;
+};
+const lead = (value, width) => value.length <= width ? value : `${value.slice(0, width - 1)}…`;
+const entries = (pairs) => pairs.map(([label, value]) => ({ label, value }));
+function recordDetails(view, now) {
+    const { record } = view;
+    const remaining = Math.max(0, record.expiresAt - now);
+    return [
+        [
+            "Agent",
+            `${record.requester.displayName} · ${record.requester.agentId ?? "none"}`,
+        ],
+        ["Session", record.requester.sessionId ?? "none"],
+        ["Requester", record.requester.principalId],
+        ["Request", `${record.module}.${record.operation} · ${record.access}`],
+        [
+            "Input",
+            `${record.description.inputBytes.toLocaleString()} bytes · SHA-256 ${record.description.inputSha256.slice(0, 8)}…${record.description.inputSha256.slice(-6)}`,
+        ],
+        [
+            "Expires",
+            `in ${String(Math.floor(remaining / 3_600_000))} h ${String(Math.floor((remaining % 3_600_000) / 60_000))} m`,
+        ],
+        ["Record", `${record.recordId} · revision ${String(record.revision)}`],
+    ];
+}
+function undoDetail(view) {
+    return [
+        "Undo",
+        view.record.reversibility === "irreversible-external"
+            ? "Can't be undone"
+            : "Can be undone",
+    ];
+}
+function connectedToolCard(view, now) {
+    const { record } = view;
+    return {
+        content: {
+            title: `Allow ${record.module} · ${record.operation}?`,
+            summary: `${record.requester.displayName} wants to use a connected tool.`,
+            facts: [
+                {
+                    label: "Effect",
+                    value: (record.access === "write"
+                        ? "Changes data in Fungi"
+                        : "Changes things outside Fungi") +
+                        (record.reversibility === "irreversible-external"
+                            ? " · can't be undone"
+                            : ""),
+                },
+            ],
+            details: entries([undoDetail(view), ...recordDetails(view, now)]),
+        },
+    };
+}
+function escapeCard(view, review, width, home, now) {
+    const prefix = review.prefix?.join(" ");
+    const offered = prefix !== undefined && review.alwaysAllowUnavailableReason === undefined;
+    const command = review.command;
+    const title = `Allow \`${command}\`?`.length <= width
+        ? `Allow \`${command}\`?`
+        : "Allow this command?";
+    const folder = review.cwd === home
+        ? "~"
+        : review.cwd.startsWith(`${home}/`)
+            ? `~${review.cwd.slice(home.length)}`
+            : review.cwd;
+    const reasonWidth = Math.max(8, (width - 8) * 2 - 2);
+    const reason = review.justification.length <= reasonWidth
+        ? `“${review.justification}”`
+        : `“${review.justification.slice(0, reasonWidth - 1)}…”`;
+    const facts = [
+        ["Folder", shorten(folder, Math.max(8, width - 10))],
+        ["Why", reason],
+    ];
+    if (review.kind === "extension-install")
+        facts.push([
+            "Note",
+            "Extensions run inside Fungi with access to every Agent.",
+        ]);
+    // The complete host-provided coverage stays in Details; the main card has a
+    // one-line preview so long Git option lists cannot displace the choices.
+    if (offered && review.alwaysAllowCoverage !== undefined)
+        facts.push([
+            "Scope",
+            lead(review.alwaysAllowCoverage, Math.max(8, width - 12)),
+        ]);
+    if (!offered && review.warning !== undefined)
+        facts.push(["Warning", review.warning]);
+    const always = !offered
+        ? undefined
+        : `Always allow “${shorten(prefix, Math.max(8, width - 5 - "Always allow “” in this project…".length))}” in this project…`;
+    const details = [["Command", command]];
+    if (review.argv !== undefined)
+        details.push(["Arguments", JSON.stringify(review.argv)]);
+    details.push(["Folder", review.cwd], ["Runs", "Outside the sandbox, as you"], undoDetail(view));
+    if (!offered && review.alwaysAllowUnavailableReason !== undefined)
+        details.push(["Rule", review.alwaysAllowUnavailableReason]);
+    else if (review.form === "shell")
+        details.push(["Rule", "Shell command: no Always-allow rule can match it."]);
+    else if (offered) {
+        details.push([
+            "Rule",
+            `“${prefix}” would match \`${prefix} …\` in this project`,
+        ]);
+        if (review.alwaysAllowCoverage !== undefined)
+            details.push(["Coverage", review.alwaysAllowCoverage]);
+        if (review.risk !== undefined)
+            details.push(["Risk", review.risk.detail]);
+    }
+    if (!offered && review.warning !== undefined)
+        // Details replace the preview by label; do not repeat the same
+        // once-only warning as a second "Risk" row.
+        details.push(["Warning", review.warning]);
+    details.push(...recordDetails(view, now));
+    return {
+        content: {
+            title,
+            body: title === "Allow this command?" ? command : undefined,
+            bodyLabel: title === "Allow this command?" ? "Command" : undefined,
+            summary: `${view.record.requester.displayName} wants to run this outside the sandbox, as you.`,
+            facts: entries(facts),
+            details: entries(details),
+        },
+        always: always === undefined ? undefined : lead(always, Math.max(12, width - 5)),
+        confirmation: !offered
+            ? undefined
+            : {
+                title: `Always allow “${prefix}” in this project?`,
+                body: lead(review.alwaysAllowCoverage ??
+                    `Any Workspace Agent here can then run \`${prefix} …\` without asking.`, Math.max(12, (width - 8) * 2 - 2)),
+            },
+        confirmWarning: offered ? review.risk?.summary : undefined,
+        confirmYes: !offered
+            ? undefined
+            : `Always allow “${prefix}” and run it now`,
+    };
+}
+/**
+ * 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 function approvalCardCopy(view, review, options) {
+    // A prompt's title is at most sixty characters.
+    const width = Math.min(options.width, 60);
+    return review === undefined
+        ? connectedToolCard(view, options.now)
+        : escapeCard(view, review, width, options.home, options.now);
+}
+/** What an answer was refused for, in words for the person. */
+export function approvalRefusal(reason, decision) {
+    switch (reason) {
+        case "stale-revision":
+        case "already-answered":
+            return "This request changed. Look again before answering.";
+        case "expired":
+            return "This request expired. Nothing ran.";
+        case "not-eligible":
+            if (decision === "always-allow")
+                return "Always allow isn't available for this command. Approve once or deny.";
+            break;
+        default:
+            break;
+    }
+    return `Couldn't answer (${reason}). Nothing ran.`;
+}
+const failureMessage = "Couldn't send your answer. It may not have been recorded.";
+/**
+ * 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 async function askApproval(interaction, input) {
+    const { view, source } = input;
+    const card = approvalCardCopy(view, source.review, {
+        width: input.width,
+        home: input.home,
+        now: input.now,
+    });
+    const record = view.record;
+    try {
+        let decision;
+        let denialNote;
+        let familyOn = false;
+        while (decision === undefined) {
+            const answer = await interaction.prompt({
+                type: "decision",
+                message: card.content.title,
+                summary: familyOn
+                    ? "Automatic approval is on for this family."
+                    : card.content.summary,
+                facts: card.content.facts?.map((fact) => ({ ...fact })),
+                body: card.content.body,
+                bodyLabel: card.content.bodyLabel,
+                details: card.content.details?.map((entry) => ({ ...entry })),
+                options: [
+                    { value: "approve", label: "Approve once" },
+                    ...(card.always === undefined
+                        ? []
+                        : [{ value: "always", label: card.always }]),
+                    ...(source.family === undefined || familyOn
+                        ? []
+                        : [{ value: "family", label: source.family.label }]),
+                    { value: "deny", label: "Deny" },
+                ],
+                other: {
+                    label: "Deny and say why…",
+                    placeholder: "A short reason for the Agent (optional)",
+                    maxLength: input.noteLimit,
+                    blank: "deny",
+                },
+            });
+            if (!input.stillCurrent())
+                return { kind: "abandoned" };
+            if (answer.text !== undefined) {
+                denialNote = answer.text.trim() || undefined;
+                decision = "deny";
+            }
+            else if (answer.selected[0] === "always") {
+                const confirmation = card.confirmation;
+                const confirmed = await interaction.prompt({
+                    type: "decision",
+                    message: confirmation?.title ?? card.content.title,
+                    summary: card.confirmWarning,
+                    body: confirmation?.body,
+                    options: [
+                        { value: "back", label: "Back" },
+                        { value: "always-allow", label: card.confirmYes ?? "Always allow" },
+                    ],
+                    escape: "back",
+                });
+                if (!input.stillCurrent())
+                    return { kind: "abandoned" };
+                if (confirmed.selected[0] === "always-allow")
+                    decision = "always-allow";
+            }
+            else if (answer.selected[0] === "family" &&
+                source.family !== undefined) {
+                // A standing rule, like Always allow: it needs its own confirmation.
+                const confirmed = await interaction.prompt({
+                    type: "decision",
+                    message: `${source.family.label}?`,
+                    summary: `Later ${record.module} requests that ${record.access === "write" ? "change data in Fungi" : "reach outside Fungi"} will run without asking.`,
+                    options: [
+                        { value: "back", label: "Back" },
+                        { value: "family", label: source.family.label },
+                    ],
+                    escape: "back",
+                });
+                if (!input.stillCurrent())
+                    return { kind: "abandoned" };
+                if (confirmed.selected[0] === "family") {
+                    familyOn = await source.family.enable();
+                    if (!input.stillCurrent())
+                        return { kind: "abandoned" };
+                }
+            }
+            else if (answer.selected[0] === "approve")
+                decision = "approve";
+            else if (answer.selected[0] === "deny")
+                decision = "deny";
+        }
+        const pinned = {
+            recordId: record.recordId,
+            decision,
+            expectedRevision: record.revision,
+        };
+        const result = await source.answer(denialNote === undefined ? pinned : { ...pinned, denialNote });
+        if (!input.stillCurrent())
+            return { kind: "abandoned" };
+        return result.kind === "refused"
+            ? {
+                kind: "refused",
+                message: approvalRefusal(result.reason ?? "unknown", decision),
+            }
+            : { kind: "answered" };
+    }
+    catch (cause) {
+        if (interaction.signal.aborted)
+            return { kind: "abandoned" };
+        input.onFailure(cause);
+        return { kind: "refused", message: failureMessage };
+    }
+}

package/dist/core/awaiting-answer.d.ts

@@ -0,0 +1,229 @@
+import type { WhistlePromptOf } from "@fungi.computer/whistle/wire";
+import type { WhistleInteractionHost } from "@fungi.computer/whistle/interaction";
+import type { KeyHint } from "../commands/hints.js";
+/** What the Agent needs from the person. */
+export type AwaitingKind = "question" | "approval";
+/**
+ * One decision waiting for the person. Its `host` is the renderer-neutral
+ * conversation that holds the current `decision` prompt and takes the answer.
+ */
+export type AwaitingItem = Readonly<{
+    /** Stable identity, kept while the item waits. */
+    key: string;
+    /** Question or tool approval; both share one queue. */
+    kind: AwaitingKind;
+    /** When it joined the queue; items stay in arrival order. */
+    arrivedAt: number;
+    /** The conversation to draw and answer. */
+    host: WhistleInteractionHost;
+}>;
+/** Which item the composer shows and where it stands among all of them. */
+export type AwaitingQueue = Readonly<{
+    /** Every waiting item in arrival order. */
+    items: readonly AwaitingItem[];
+    /** The first item not postponed with Later, in arrival order. */
+    current?: AwaitingItem | undefined;
+    /** One-based place of `current` among every waiting item. */
+    position: number;
+    /** Every waiting item, questions and approvals together. */
+    total: number;
+}>;
+/**
+ * Order the items by arrival and pick the one the composer shows. A postponed
+ * item leaves the composer but stays counted: it is the footer row.
+ */
+export declare function awaitingQueue(items: readonly AwaitingItem[], later: ReadonlySet<string>): AwaitingQueue;
+/**
+ * The item that owns the composer right now. An empty draft is taken over;
+ * a draft with text is never, unless the person asked for the decision.
+ */
+export declare function awaitingTakeover(awaiting: AwaitingQueue & Readonly<{
+    forced: boolean;
+}>, draft: string): AwaitingItem | undefined;
+/** The decision prompt both renderers draw. */
+export type DecisionPrompt = WhistlePromptOf<"decision">;
+/** Where one decision is in its short life. */
+export type DecisionPhase = "choose" | "other" | "confirm" | "sending" | "refused";
+/** Everything the reducer remembers about one decision prompt. */
+export type DecisionState = Readonly<{
+    /** Highlighted row: an option, or the Other row after the last option. */
+    highlight: number;
+    /** Option values toggled so far (multiple decisions only). */
+    toggled: ReadonlySet<string>;
+    /** Text typed on the Other row; kept when the person leaves the row. */
+    other: string;
+    /** What the person is doing now. */
+    phase: DecisionPhase;
+    /** Why the last answer came back, while `phase` is `refused`. */
+    refusal?: string | undefined;
+    /** The long text and details replace the rows. */
+    details: boolean;
+}>;
+/** What the person did, independent of which key or click did it. */
+export type DecisionIntent = Readonly<{
+    /** Step the highlight, wrapping at either end. */
+    type: "move";
+    /** Which way. */
+    delta: -1 | 1;
+}> | Readonly<{
+    /** Move the highlight to a numbered row; never answers. */
+    type: "pick";
+    /** One-based row number, the Other row last. */
+    number: number;
+}> | Readonly<{
+    /** Toggle the highlighted option of a multiple decision. */
+    type: "toggle";
+}> | Readonly<{
+    /** Replace the Other line's text, e.g. from a field. */
+    type: "type";
+    /** The whole text now. */
+    text: string;
+}> | Readonly<{
+    /** Add typed characters to the Other line and move onto it. */
+    type: "append";
+    /** The characters. */
+    text: string;
+}> | Readonly<{
+    /** Confirm: the one way to answer. */
+    type: "enter";
+}> | Readonly<{
+    /** Step back one level; from the option list it postpones the decision. */
+    type: "escape";
+}> | Readonly<{
+    /** Show or hide the long text and details. */
+    type: "details";
+}> | Readonly<{
+    /** The owner of the decision refused the answer. */
+    type: "refused";
+    /** Why, in words for the person. */
+    message: string;
+}>;
+/** What the owner of the decision must now do. */
+export type DecisionEffect = Readonly<{
+    /** Send this answer. */
+    type: "answer";
+    /** The option values picked. */
+    selected: string[];
+    /** What the person wrote on the Other line, if anything. */
+    text?: string;
+}> | Readonly<{
+    /** Postpone: leave the composer, stay waiting, answer nothing. */
+    type: "later";
+}> | Readonly<{
+    /** The reducer stepped back one level; nothing for the owner to do. */
+    type: "back";
+}>;
+/** The next state, and what the decision's owner must do about the intent. */
+export type DecisionOutcome = Readonly<{
+    /** The state to keep. */
+    state: DecisionState;
+    /** What the owner must do now, when anything. */
+    effect?: DecisionEffect;
+}>;
+/** The state a decision starts in. */
+export declare function initialDecisionState(): DecisionState;
+/**
+ * The one set of rules both renderers follow. Number keys only move the
+ * highlight, Enter is the only way to answer, and Esc steps back one level
+ * until it reaches the option list, where it postpones the decision.
+ */
+export declare function reduceDecision(state: DecisionState, intent: DecisionIntent, prompt: DecisionPrompt): DecisionOutcome;
+/** One drawn row of a decision. */
+export type DecisionRowView = Readonly<{
+    /** Position among the rows; the last one is Other. */
+    index: number;
+    /** An offered choice, or the always-present Other row. */
+    kind: "option" | "other";
+    /** The number, or `[x]` / `[ ]` for a multiple decision. */
+    marker: string;
+    /** The choice, or the Other row's label. */
+    label: string;
+    /** Why or what, shown for the highlighted row when space is short. */
+    description?: string | undefined;
+    /** The first choice is the recommended one. */
+    recommended: boolean;
+    /** The row the Enter key acts on. */
+    highlighted: boolean;
+    /** A multiple decision's pick, or Other with text. */
+    toggled: boolean;
+    /** Drawn in the error tone. */
+    destructive: boolean;
+    /** The row's words without its marker, for a renderer that draws the marker as a control. */
+    caption: string;
+    /** The whole row as one plain line, marker first; renderers must show it. */
+    text: string;
+}>;
+/** What both renderers must draw for one decision. */
+export type DecisionView = Readonly<{
+    /** Question or approval. */
+    kind: AwaitingKind;
+    /** Accessible name of the region, e.g. `Agent question 1 of 3`. */
+    label: string;
+    /** The prompt's title. */
+    title: string;
+    /** `1 of 3`, shown only when more than one decision waits. */
+    counter?: string | undefined;
+    /** One plain sentence under the title. */
+    summary?: string | undefined;
+    /** Short labelled lines under the summary, as `label  value`. */
+    facts: readonly Readonly<{
+        /** What the value is. */
+        label: string;
+        /** The value. */
+        value: string;
+    }>[];
+    /** Long text the person wrote or the Agent asked, cut by renderers. */
+    body?: string | undefined;
+    /** A short name for the body. */
+    bodyLabel?: string | undefined;
+    /** Everything else, shown on demand. */
+    details: readonly Readonly<{
+        /** What the value is. */
+        label: string;
+        /** The value. */
+        value: string;
+    }>[];
+    /** The long text and details replace the rows. */
+    detailsOpen: boolean;
+    /** The options in order, then the Other row. */
+    rows: readonly DecisionRowView[];
+    /** The Other row's field; absent when only the options are offered. */
+    other?: Readonly<{
+        /** The row's name, e.g. `Other…`. */
+        label: string;
+        /** Hint shown in the empty field. */
+        placeholder?: string | undefined;
+        /** What the person has written. */
+        text: string;
+        /** The person is typing on this row. */
+        focused: boolean;
+        /** The longest answer accepted. */
+        maxLength: number;
+    }> | undefined;
+    /** More than one option may be picked. */
+    multiple: boolean;
+    /** What the person is doing now. */
+    phase: DecisionPhase;
+    /** Whether Enter would send an answer now. */
+    canSend: boolean;
+    /** `Sending…` or the refusal, marked in words rather than colour alone. */
+    status?: Readonly<{
+        /** Plain or alarming. */
+        tone: "info" | "error";
+        /** The words. */
+        text: string;
+    }> | undefined;
+    /** Keys that work now, with Esc named for what it will do. */
+    hints: readonly KeyHint[];
+}>;
+/** Project a decision's state into the view every renderer draws. */
+export declare function decisionView(state: DecisionState, prompt: DecisionPrompt, context: Readonly<{
+    kind: AwaitingKind;
+    position: number;
+    total: number;
+}>): DecisionView;
+/**
+ * The plain strings a renderer must show for a view, in reading order. The
+ * lockstep tests hold every surface to this list.
+ */
+export declare function decisionViewText(view: DecisionView): readonly string[];