@fungi.computer/parakeet 0.0.0-stage → 0.1.0

package/dist/core/session-query.js

@@ -0,0 +1,187 @@
+import { experimental_streamedQuery, infiniteQueryOptions, queryOptions, QueryObserver, } from "@tanstack/react-query";
+import { applySessionFrame } from "./session-projection.js";
+import { reportFailure } from "../lib/failure.js";
+const emptyProjection = Object.freeze({
+    observation: "connecting",
+    snapshot: undefined,
+    latestPrompt: undefined,
+});
+// A watch starts with a bounded page, but its update frames keep arriving for
+// the lifetime of the client. Refresh from the owner before that page becomes
+// an ever-growing in-memory transcript. The smaller read leaves room for a
+// burst of frames without reading on every tool result.
+const LIVE_HISTORY_LIMIT = 200;
+const LIVE_HISTORY_REFRESH_AT = 400;
+function latestPrompt(messages, previous) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.value.role !== "user" || message.commandId === null)
+            continue;
+        const content = message.value.content;
+        const text = Array.isArray(content)
+            ? content
+                .flatMap((part) => (part.type === "text" ? [part.text] : []))
+                .join("\n")
+            : content;
+        return [message.commandId, text];
+    }
+    return previous;
+}
+async function* observeSession(session, signal) {
+    yield { kind: "opening" };
+    const watch = await session.watch({ limit: LIVE_HISTORY_LIMIT });
+    let closing;
+    const close = () => {
+        closing ??= watch.close();
+        return closing;
+    };
+    const onAbort = () => {
+        // The generator finalizer collects this same promise; observe it immediately.
+        void close().catch((cause) => {
+            reportFailure("close aborted Session watch", cause);
+        });
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (signal.aborted)
+            return;
+        let snapshot = watch.snapshot;
+        yield { kind: "snapshot", value: snapshot };
+        for await (const frame of watch.changes) {
+            snapshot = applySessionFrame(snapshot, frame);
+            if (snapshot.messages.length > LIVE_HISTORY_REFRESH_AT) {
+                snapshot = await session.read({ limit: LIVE_HISTORY_LIMIT });
+                yield { kind: "snapshot", value: snapshot };
+            }
+            else {
+                yield { kind: "frame", value: frame };
+            }
+        }
+        throw new Error("Session watch ended; current activity is unavailable");
+    }
+    catch (error) {
+        if (!signal.aborted)
+            throw error;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        await close();
+    }
+}
+function reduceObservation(projection, observation) {
+    if (observation.kind === "opening")
+        return { ...projection, observation: "connecting" };
+    if (observation.kind === "snapshot")
+        return {
+            observation: "live",
+            snapshot: observation.value,
+            latestPrompt: latestPrompt(observation.value.messages, projection.latestPrompt),
+        };
+    if (projection.snapshot === undefined)
+        return observation.value.kind === "reset"
+            ? {
+                observation: "live",
+                snapshot: observation.value.baseline,
+                latestPrompt: latestPrompt(observation.value.baseline.messages),
+            }
+            : projection;
+    const snapshot = applySessionFrame(projection.snapshot, observation.value);
+    return {
+        observation: "live",
+        snapshot,
+        latestPrompt: latestPrompt(snapshot.messages, projection.latestPrompt),
+    };
+}
+/** One shared TanStack observation keyed by Shiitake's logical Session address. */
+export function sessionQueryOptions(session) {
+    const queryKey = ["shiitake-session", session.address];
+    return queryOptions({
+        queryKey,
+        queryFn: experimental_streamedQuery({
+            streamFn: ({ signal }) => observeSession(session, signal),
+            reducer: reduceObservation,
+            initialValue: emptyProjection,
+            refetchMode: "append",
+        }),
+        refetchOnMount: "always",
+        retry: false,
+        staleTime: Number.POSITIVE_INFINITY,
+    });
+}
+/** Seed the shared observation with a bounded read before its watch mounts. */
+export function seedSessionQuery(queryClient, session, snapshot) {
+    queryClient.setQueryData(sessionQueryOptions(session).queryKey, {
+        observation: "connecting",
+        snapshot,
+        latestPrompt: latestPrompt(snapshot.messages),
+    });
+}
+/** Borrow activity from the existing cache without starting another watch. */
+export function subscribeSessionActivity(queryClient, session, listener) {
+    const observer = new QueryObserver(queryClient, {
+        ...sessionQueryOptions(session),
+        enabled: false,
+    });
+    const report = (result) => {
+        const snapshot = result.data?.snapshot;
+        listener(result.isError ||
+            result.data?.observation !== "live" ||
+            snapshot === undefined
+            ? "unknown"
+            : snapshot.activity.queue.state === "idle"
+                ? "idle"
+                : "working");
+    };
+    const unsubscribe = observer.subscribe(report);
+    report(observer.getCurrentResult());
+    return unsubscribe;
+}
+/** Shared, demand-loaded history; the live watch remains a separate small tail. */
+export function sessionHistoryQueryOptions(session, before = null) {
+    const initialPageParam = {
+        before,
+        newerBefore: [],
+        newerOverflow: false,
+    };
+    return infiniteQueryOptions({
+        queryKey: ["shiitake-session-history", session.address],
+        initialPageParam,
+        queryFn: async ({ pageParam, signal }) => {
+            if (pageParam.before === null)
+                throw new Error("Session has no older history cursor");
+            const page = await session.read({ before: pageParam.before, limit: 100 });
+            signal.throwIfAborted();
+            return page;
+        },
+        getNextPageParam: (last, _pages, cursor) => {
+            if (last.oldestCursor === null || last.oldestCursor === undefined)
+                return undefined;
+            const newerBefore = cursor.before === null
+                ? cursor.newerBefore
+                : [...cursor.newerBefore, cursor.before];
+            return {
+                before: last.oldestCursor,
+                newerBefore: newerBefore.slice(-2048),
+                newerOverflow: cursor.newerOverflow || newerBefore.length > 2048,
+            };
+        },
+        getPreviousPageParam: (_first, _pages, cursor) => {
+            const before = cursor.newerBefore.at(-1);
+            return before === undefined
+                ? undefined
+                : {
+                    before,
+                    newerBefore: cursor.newerBefore.slice(0, -1),
+                    newerOverflow: cursor.newerOverflow,
+                };
+        },
+        select: (data) => ({
+            pages: data.pages,
+            newerOverflow: data.pageParams[0]?.newerOverflow ?? false,
+        }),
+        maxPages: 4,
+        enabled: false,
+        retry: false,
+        staleTime: Number.POSITIVE_INFINITY,
+    });
+}

package/dist/core/session-view-state.d.ts

@@ -0,0 +1,66 @@
+import type { AgentRunningWork, SessionCompactionTrigger, SessionSnapshot } from "@fungi.computer/shiitake/client";
+/**
+ * What a person's readout of one Session says, decided from Shiitake's raw
+ * activity facts. Shiitake publishes facts; this module owns their meaning.
+ */
+export type SessionViewState = Readonly<{
+    /** Current activity presented to the person. */
+    kind: "idle" | "waiting_for_you" | "thinking" | "responding";
+}> | Readonly<{
+    /** Cancellation is waiting for current work to settle. */
+    kind: "cancelling";
+}> | Readonly<{
+    /** A compaction is running now, started by this trigger. */
+    kind: "compacting";
+    /** What started it: the user, the context threshold, or an overflow. */
+    trigger: SessionCompactionTrigger;
+}>
+/**
+ * The Session's accepted work has not started in the Agent. Cancelling
+ * `queuedCommandId` with `onlyIfPending` withdraws the wait, or reports
+ * `too_late` once the work has started.
+ */
+ | Readonly<{
+    /** Accepted work is waiting in the Agent queue. */
+    kind: "queued";
+    /** Exact command that can be withdrawn before it starts. */
+    queuedCommandId: string;
+    /** Live work occupying the executor, or null while awaiting the host. */
+    runningWork: AgentRunningWork | null;
+}> | Readonly<{
+    /** Provider retry is scheduled. */
+    kind: "retrying";
+    /** Current retry attempt. */
+    attempt: number;
+    /** Maximum attempts allowed by the run policy. */
+    maxAttempts: number;
+    /** Bounded reason suitable for presentation. */
+    cause: string;
+    /** Scheduled retry time, in milliseconds since the epoch. */
+    nextRetryAt: number;
+}> | Readonly<{
+    /** One tool is running. */
+    kind: "running_tool";
+    /** Name of the active tool. */
+    tool: string;
+}> | Readonly<{
+    /** The latest terminal failed or was interrupted. */
+    kind: "error";
+    /** Bounded terminal diagnostic suitable for presentation. */
+    cause: string;
+}>;
+/** The facts a view state is decided from. */
+export type SessionViewFacts = Pick<SessionSnapshot, "activity" | "terminals" | "progress">;
+/** Coarse activity of a Session, for composer gating. */
+export type SessionActivityStatus = "cancelling" | "idle" | "queued" | "retrying" | "streaming" | "thinking";
+/** Decide a Session's view state from its activity, terminals and progress. */
+export declare function sessionViewState(facts: SessionViewFacts): SessionViewState;
+export declare function sameRunningWork(left: AgentRunningWork | null, right: AgentRunningWork | null): boolean;
+/** Explain a queued Session using its owner's executor fact. */
+export declare function queuedSessionLabel(state: Extract<SessionViewState, {
+    kind: "queued";
+}>): string;
+/** Whether two view states say the same thing, so a readout can stay stable. */
+export declare function sameSessionViewState(left: SessionViewState, right: SessionViewState): boolean;
+/** Coarse activity for a view state: what the composer gates on. */
+export declare function sessionActivityStatus(view: SessionViewState): SessionActivityStatus;

package/dist/core/session-view-state.js

@@ -0,0 +1,114 @@
+const retryCauseLimit = 160;
+const errorCauseLimit = 200;
+function collapsed(text, limit) {
+    return text.replace(/\s+/gu, " ").trim().slice(0, limit);
+}
+function idleViewState({ activity, terminals, }) {
+    let terminal;
+    for (const candidate of terminals)
+        if (terminal === undefined || candidate.sequence > terminal.sequence)
+            terminal = candidate;
+    if (terminal === undefined)
+        return { kind: "idle" };
+    // A later model choice acknowledges the failed run while leaving its
+    // diagnostic and terminal in history for inspection.
+    if (activity.lastModelChoiceSequence !== null &&
+        activity.lastModelChoiceSequence > terminal.sequence)
+        return { kind: "waiting_for_you" };
+    if (terminal.outcome === "failed" || terminal.outcome === "interrupted")
+        return {
+            kind: "error",
+            cause: collapsed(terminal.diagnostic ??
+                (terminal.outcome === "interrupted"
+                    ? "Run was interrupted"
+                    : "Run failed without a diagnostic"), errorCauseLimit),
+        };
+    return { kind: "waiting_for_you" };
+}
+/** Decide a Session's view state from its activity, terminals and progress. */
+export function sessionViewState(facts) {
+    const { activity, progress } = facts;
+    const { queue } = activity;
+    if (queue.state === "idle")
+        return idleViewState(facts);
+    if (activity.cancellationRequested)
+        return { kind: "cancelling" };
+    if (queue.state === "queued")
+        return {
+            kind: "queued",
+            queuedCommandId: queue.commandId,
+            runningWork: queue.runningWork,
+        };
+    if (activity.compaction !== null)
+        return { kind: "compacting", trigger: activity.compaction.trigger };
+    if (activity.retry !== null)
+        return {
+            kind: "retrying",
+            attempt: activity.retry.attempt,
+            maxAttempts: activity.retry.maxAttempts,
+            cause: collapsed(activity.retry.errorMessage, retryCauseLimit),
+            nextRetryAt: activity.retry.scheduledAt + activity.retry.delayMs,
+        };
+    if (activity.activeTool !== null)
+        return { kind: "running_tool", tool: activity.activeTool };
+    return {
+        kind: progress === null || progress.text === "" ? "thinking" : "responding",
+    };
+}
+export function sameRunningWork(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    if (left.kind === "session" && right.kind === "session")
+        return (left.sessionId === right.sessionId && left.commandId === right.commandId);
+    if (left.kind === "host" && right.kind === "host")
+        return left.lane === right.lane && left.jobId === right.jobId;
+    return false;
+}
+/** Explain a queued Session using its owner's executor fact. */
+export function queuedSessionLabel(state) {
+    const work = state.runningWork;
+    if (work === null)
+        return "Queued for host";
+    return work.kind === "session"
+        ? `Waiting for Session ${collapsed(work.sessionId, 256)}`
+        : `Waiting for host job ${collapsed(work.lane, 256)} · ${collapsed(work.jobId, 256)}`;
+}
+/** Whether two view states say the same thing, so a readout can stay stable. */
+export function sameSessionViewState(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === "queued" && right.kind === "queued")
+        return (left.queuedCommandId === right.queuedCommandId &&
+            sameRunningWork(left.runningWork, right.runningWork));
+    if (left.kind === "running_tool" && right.kind === "running_tool")
+        return left.tool === right.tool;
+    if (left.kind === "compacting" && right.kind === "compacting")
+        return left.trigger === right.trigger;
+    if (left.kind === "retrying" && right.kind === "retrying")
+        return (left.attempt === right.attempt &&
+            left.maxAttempts === right.maxAttempts &&
+            left.cause === right.cause &&
+            left.nextRetryAt === right.nextRetryAt);
+    if (left.kind === "error" && right.kind === "error")
+        return left.cause === right.cause;
+    return true;
+}
+/** Coarse activity for a view state: what the composer gates on. */
+export function sessionActivityStatus(view) {
+    switch (view.kind) {
+        case "cancelling":
+        case "queued":
+        case "retrying":
+            return view.kind;
+        case "responding":
+            return "streaming";
+        case "thinking":
+        case "running_tool":
+        case "compacting":
+            return "thinking";
+        case "idle":
+        case "waiting_for_you":
+        case "error":
+            return "idle";
+    }
+}

package/dist/core/tool-contract.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { SessionMessage } from "@fungi.computer/shiitake/client";
+/** Exact JSON argument object carried by a Pi tool call into Parakeet. */
+export declare const ToolArgumentsSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+/** Pi content used to derive tool arguments. */
+export type ParakeetAssistantPart = Extract<SessionMessage["value"], {
+    role: "assistant";
+}>["content"][number];
+/**
+ * Pi's JSON argument object after the maintained Zod boundary parser.
+ * @useDeclaredType
+ */
+export type ToolArguments = Extract<ParakeetAssistantPart, {
+    type: "toolCall";
+}>["arguments"];

package/dist/core/tool-contract.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+/** Exact JSON argument object carried by a Pi tool call into Parakeet. */
+export const ToolArgumentsSchema = z.record(z.string(), z.json());

package/dist/core/tool-groups.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectedItem, TimelineItem, ToolGroupItem, ToolItem } from "../store/types.js";
+import { type ToolCallView } from "./tool-view.js";
+/** Build one group from a non-empty run of consecutive calls. */
+export declare function toolGroup(tools: readonly [ToolItem, ...ToolItem[]]): ToolGroupItem;
+/**
+ * Fold a stretch of tool work into one group. User rows and rendered assistant
+ * content end the stretch; invisible assistant rows can span it.
+ */
+export declare function groupToolCalls(items: readonly ProjectedItem[]): TimelineItem[];
+/** View-only open/closed state shared by the browser and terminal renderers. */
+export type ToolDisclosureState = Readonly<{
+    /**
+     * `default` follows each row's default; `expanded` and `collapsed` are the
+     * terminal's global details toggle and override defaults.
+     */
+    mode: "collapsed" | "default" | "expanded";
+    /** Explicit reader choices by group or call id; they win over the mode. */
+    overrides: ReadonlyMap<string, boolean>;
+}>;
+/** Defaults only, with no reader choices. */
+export declare const initialToolDisclosure: ToolDisclosureState;
+/** Active and failed groups show every call; clean history retains a visible tail. */
+export declare function toolGroupDefaultOpen(group: ToolGroupItem): boolean;
+/** Even a folded group shows recent calls, rather than hiding all tool work. */
+export declare function visibleToolCalls(group: ToolGroupItem, open: boolean): readonly ToolCallView[];
+/** A failed call opens by default so its error is visible. */
+export declare function toolCallDefaultOpen(call: ToolCallView): boolean;
+/** Whether a group or call is currently open. */
+export declare function disclosureOpen(state: ToolDisclosureState, id: string, defaultOpen: boolean): boolean;
+/** Flip one group or call, recording the reader's explicit choice. */
+export declare function toggleDisclosure(state: ToolDisclosureState, id: string, defaultOpen: boolean): ToolDisclosureState;
+/**
+ * Expand everything, or collapse everything when the reader has expanded
+ * anything. Either way individual choices are cleared.
+ */
+export declare function toggleAllDisclosure(state: ToolDisclosureState): ToolDisclosureState;

package/dist/core/tool-groups.js

@@ -0,0 +1,151 @@
+import { assistantMessageVisible } from "./assistant-visibility.js";
+import { toolCallView } from "./tool-view.js";
+const nouns = {
+    code: ["ran", "script", "scripts"],
+    command: ["ran", "command", "commands"],
+    edit: ["edited", "file", "files"],
+    other: ["called", "tool", "tools"],
+    read: ["read", "file", "files"],
+    search: ["searched", "pattern", "patterns"],
+};
+/**
+ * One-line summary from typed kinds, in first-seen order:
+ * `Read 3 files, ran 2 commands, edited 1 file`. Files count distinct paths.
+ */
+function summarizeToolCalls(calls) {
+    const counts = new Map();
+    for (const call of calls) {
+        const entry = counts.get(call.kind) ?? { calls: 0, paths: new Set() };
+        entry.calls += 1;
+        for (const path of call.paths)
+            entry.paths.add(path);
+        counts.set(call.kind, entry);
+    }
+    // Map iteration keeps first-seen order.
+    const phrases = [...counts].map(([kind, entry]) => {
+        const [verb, singular, plural] = nouns[kind];
+        const countsFiles = kind === "read" || kind === "edit";
+        const count = countsFiles && entry.paths.size > 0 ? entry.paths.size : entry.calls;
+        return `${verb} ${String(count)} ${count === 1 ? singular : plural}`;
+    });
+    const text = phrases.join(", ");
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+function groupStatus(calls) {
+    if (calls.some((call) => call.status === "running"))
+        return "running";
+    if (calls.some((call) => call.status === "error"))
+        return "error";
+    if (calls.some((call) => call.status === "unknown"))
+        return "unknown";
+    return "completed";
+}
+function groupDuration(tools) {
+    let start;
+    let end;
+    for (const tool of tools) {
+        if (tool.startedAt !== undefined)
+            start = Math.min(start ?? tool.startedAt, tool.startedAt);
+        if (tool.result !== undefined)
+            end = Math.max(end ?? tool.result.timestamp, tool.result.timestamp);
+    }
+    return start === undefined || end === undefined
+        ? undefined
+        : Math.max(0, end - start);
+}
+/** Build one group from a non-empty run of consecutive calls. */
+export function toolGroup(tools) {
+    const calls = tools.map(toolCallView);
+    const status = groupStatus(calls);
+    const active = [...calls].reverse().find((call) => call.status === "running");
+    return {
+        active,
+        calls,
+        durationMs: status === "running" ? undefined : groupDuration(tools),
+        failedCount: calls.filter((call) => call.status === "error").length,
+        id: `tools:${tools[0].id}`,
+        kind: "tool_group",
+        status,
+        summary: calls.length === 1 && calls[0] !== undefined
+            ? `${calls[0].verb} ${calls[0].label}`
+            : summarizeToolCalls(calls),
+        tools,
+    };
+}
+/**
+ * Fold a stretch of tool work into one group. User rows and rendered assistant
+ * content end the stretch; invisible assistant rows can span it.
+ */
+export function groupToolCalls(items) {
+    const rows = [];
+    let run = [];
+    let nontextRows = [];
+    const flush = () => {
+        const [first, ...rest] = run;
+        if (first !== undefined)
+            rows.push(toolGroup([first, ...rest]));
+        rows.push(...nontextRows);
+        run = [];
+        nontextRows = [];
+    };
+    for (const item of items) {
+        if (item.kind === "tool") {
+            run.push(item);
+            continue;
+        }
+        if (item.kind === "assistant_message" &&
+            !assistantMessageVisible(item) &&
+            run.length > 0) {
+            nontextRows.push(item);
+            continue;
+        }
+        flush();
+        rows.push(item);
+    }
+    flush();
+    return rows;
+}
+/** Defaults only, with no reader choices. */
+export const initialToolDisclosure = Object.freeze({
+    mode: "default",
+    overrides: new Map(),
+});
+/** Active and failed groups show every call; clean history retains a visible tail. */
+export function toolGroupDefaultOpen(group) {
+    return group.status !== "completed";
+}
+/** Even a folded group shows recent calls, rather than hiding all tool work. */
+export function visibleToolCalls(group, open) {
+    return open ? group.calls : group.calls.slice(-3);
+}
+/** A failed call opens by default so its error is visible. */
+export function toolCallDefaultOpen(call) {
+    return call.status === "error";
+}
+/** Whether a group or call is currently open. */
+export function disclosureOpen(state, id, defaultOpen) {
+    const override = state.overrides.get(id);
+    if (override !== undefined)
+        return override;
+    if (state.mode === "default")
+        return defaultOpen;
+    return state.mode === "expanded";
+}
+/** Flip one group or call, recording the reader's explicit choice. */
+export function toggleDisclosure(state, id, defaultOpen) {
+    const overrides = new Map(state.overrides);
+    overrides.set(id, !disclosureOpen(state, id, defaultOpen));
+    return { ...state, overrides };
+}
+/**
+ * Expand everything, or collapse everything when the reader has expanded
+ * anything. Either way individual choices are cleared.
+ */
+export function toggleAllDisclosure(state) {
+    const anyOpen = state.mode === "expanded" ||
+        [...state.overrides.values()].some((open) => open);
+    return {
+        mode: anyOpen ? "collapsed" : "expanded",
+        overrides: new Map(),
+    };
+}