@fungi.computer/parakeet 0.0.0-stage → 0.1.0

package/dist/core/assistant-visibility.d.ts

@@ -0,0 +1,3 @@
+import type { AssistantMessageItem } from "../store/types.js";
+/** One rule for whether an assistant row has content either renderer shows. */
+export declare function assistantMessageVisible(item: AssistantMessageItem): boolean;

package/dist/core/assistant-visibility.js

@@ -0,0 +1,4 @@
+/** One rule for whether an assistant row has content either renderer shows. */
+export function assistantMessageVisible(item) {
+    return item.text.trim() !== "" || (item.thinking?.trim() ?? "") !== "";
+}

package/dist/core/author-labels.d.ts

@@ -0,0 +1,16 @@
+import type { SessionMessage } from "@fungi.computer/shiitake/client";
+/** Who wrote a timeline line, as the host chose to show them. */
+export type ParakeetAuthor = Readonly<{
+    /** A stable identity that tells two same-named authors apart. */
+    id: string;
+    /** The name shown beside the line. */
+    name: string;
+}>;
+/**
+ * The host's reading of a message's opaque metadata: the author to show, or
+ * none. Parakeet never interprets metadata itself.
+ */
+export type ParakeetAuthorOf = (meta: SessionMessage["meta"]) => ParakeetAuthor | undefined;
+/** The default reading: metadata names no author Parakeet can show. */
+export declare const noAuthor: ParakeetAuthorOf;
+export declare function authorDisplayNames(authors: readonly ParakeetAuthor[]): ReadonlyMap<string, string>;

package/dist/core/author-labels.js

@@ -0,0 +1,16 @@
+/** The default reading: metadata names no author Parakeet can show. */
+export const noAuthor = () => undefined;
+export function authorDisplayNames(authors) {
+    const identities = new Map();
+    for (const { id, name } of authors) {
+        const known = identities.get(name) ?? new Set();
+        known.add(id);
+        identities.set(name, known);
+    }
+    return new Map(authors.map(({ id, name }) => [
+        id,
+        (identities.get(name)?.size ?? 0) > 1
+            ? `${name} · ${id.slice(-6)}`
+            : name,
+    ]));
+}

package/dist/core/build-timeline.d.ts

@@ -0,0 +1,36 @@
+import { type ParakeetAuthorOf } from "./author-labels.js";
+import type { SessionActivity, SessionCompactionMarker, SessionCompactionNotice, SessionMessage, SessionPendingPrompt, SessionProgress } from "@fungi.computer/shiitake/client";
+import type { LocalPromptAdmission, TimelineItem } from "../store/types.js";
+export type TimelineProjection = Readonly<{
+    items: readonly TimelineItem[];
+    model?: Readonly<{
+        model: string;
+        provider: string;
+    }>;
+    usage?: Readonly<{
+        cost: number;
+        tokens: number;
+    }>;
+}>;
+/**
+ * The client request identity of a prompt this composer submitted, by its
+ * owner-issued command, so one row keeps its identity from submit to durable.
+ */
+export type PromptRequestIdOf = (commandId: string) => string | undefined;
+export type DurableTimelineProjection = TimelineProjection & Readonly<{
+    completedMessageIds: ReadonlySet<string>;
+    commandIds: ReadonlySet<string>;
+    commandAnchors: ReadonlyMap<string, string>;
+}>;
+/**
+ * Project one durable Session revision into timeline rows, folding consecutive
+ * tool calls into groups. `compactions` places one divider row immediately
+ * before the message it marks; `notices` places a short row at a compaction
+ * that changed nothing. The model's own context is unaffected by this purely
+ * client-side projection.
+ */
+export declare function buildDurableTimeline(messages: readonly SessionMessage[], compactions?: readonly SessionCompactionMarker[], activity?: SessionActivity, authorOf?: ParakeetAuthorOf, requestIdOf?: PromptRequestIdOf, notices?: readonly SessionCompactionNotice[]): DurableTimelineProjection;
+/** Project replaceable live work without copying settled history. */
+export declare function buildTimelineTail(durable: DurableTimelineProjection, progress: SessionProgress | null, queued: readonly SessionPendingPrompt[], admissions?: readonly LocalPromptAdmission[], authorOf?: ParakeetAuthorOf, requestIdOf?: PromptRequestIdOf): readonly TimelineItem[];
+/** Overlay live progress and an optimistic prompt over stable durable rows. */
+export declare function buildTimeline(durable: DurableTimelineProjection, progress: SessionProgress | null, queued: readonly SessionPendingPrompt[], admissions?: readonly LocalPromptAdmission[]): TimelineProjection;

package/dist/core/build-timeline.js

@@ -0,0 +1,328 @@
+import { noAuthor, } from "./author-labels.js";
+import { completedMessageIds } from "./session-projection.js";
+import { ToolArgumentsSchema } from "./tool-contract.js";
+import { assistantMessageVisible } from "./assistant-visibility.js";
+import { groupToolCalls } from "./tool-groups.js";
+function orderedSources(messages, compactions, notices) {
+    const sources = [
+        ...messages.map((message) => ({
+            sequence: message.sequence,
+            tie: 1,
+            kind: "message",
+            message,
+        })),
+        ...compactions.map((marker) => ({
+            sequence: marker.sequence,
+            tie: 0,
+            kind: "marker",
+            marker,
+        })),
+        ...notices.map((notice) => ({
+            sequence: notice.sequence,
+            tie: 2,
+            kind: "notice",
+            notice,
+        })),
+    ];
+    return sources.sort((left, right) => left.sequence - right.sequence || left.tie - right.tie);
+}
+const noRequestId = () => undefined;
+/** Carry a local prompt's request identity onto its owner-reported row. */
+function withRequestId(item, requestId) {
+    return requestId === undefined ? item : { ...item, requestId };
+}
+function userText(content) {
+    return Array.isArray(content)
+        ? content
+            .flatMap((part) => (part.type === "text" ? [part.text] : []))
+            .join("\n")
+        : content;
+}
+function toolItem(call, startedAt) {
+    return {
+        args: ToolArgumentsSchema.parse(call.arguments),
+        id: call.id,
+        kind: "tool",
+        name: call.name,
+        startedAt,
+        status: "unknown",
+    };
+}
+function progressItem(progress) {
+    const base = {
+        id: progress.messageId,
+        kind: "assistant_message",
+        pending: true,
+        text: progress.text,
+    };
+    return progress.thinking === ""
+        ? base
+        : { ...base, thinking: progress.thinking };
+}
+function collectAssistantBlocks(value) {
+    const text = [];
+    const thinking = [];
+    const tools = [];
+    for (const block of value.content) {
+        if (block.type === "text")
+            text.push(block.text);
+        if (block.type === "thinking")
+            thinking.push(block.thinking);
+        if (block.type === "toolCall")
+            tools.push(toolItem(block, value.timestamp));
+    }
+    return { text, thinking, tools };
+}
+function assistantMessageItem(id, value, blocks) {
+    if (blocks.text.length === 0 &&
+        blocks.thinking.length === 0 &&
+        blocks.tools.length > 0)
+        return undefined;
+    const item = {
+        id,
+        isError: value.stopReason === "error" || value.stopReason === "aborted",
+        kind: "assistant_message",
+        pending: false,
+        at: value.timestamp,
+        text: blocks.text.length === 0
+            ? value.stopReason === "error"
+                ? "This run couldn’t finish."
+                : value.stopReason === "aborted"
+                    ? "The run was cancelled."
+                    : ""
+            : blocks.text.join(""),
+        usage: {
+            cost: value.usage.cost.total,
+            tokens: value.usage.totalTokens,
+        },
+    };
+    return blocks.thinking.length === 0
+        ? item
+        : { ...item, thinking: blocks.thinking.join("\n") };
+}
+function projectAssistant(id, value, author) {
+    const blocks = collectAssistantBlocks(value);
+    const message = assistantMessageItem(id, value, blocks);
+    return {
+        items: message === undefined
+            ? blocks.tools
+            : [{ ...message, author }, ...blocks.tools],
+        model: { model: value.model, provider: value.provider },
+        usage: { cost: value.usage.cost.total, tokens: value.usage.totalTokens },
+    };
+}
+function appendAssistant(items, toolIndexes, assistant) {
+    for (const item of assistant.items) {
+        if (item.kind === "tool")
+            toolIndexes.set(item.id, items.length);
+        items.push(item);
+    }
+}
+function completeTool(items, toolIndexes, value) {
+    const toolIndex = toolIndexes.get(value.toolCallId);
+    if (toolIndex === undefined)
+        return;
+    const tool = items[toolIndex];
+    if (tool?.kind !== "tool")
+        return;
+    items[toolIndex] = {
+        ...tool,
+        result: value,
+        status: value.isError ? "error" : "completed",
+    };
+}
+/**
+ * Project one durable Session revision into timeline rows, folding consecutive
+ * tool calls into groups. `compactions` places one divider row immediately
+ * before the message it marks; `notices` places a short row at a compaction
+ * that changed nothing. The model's own context is unaffected by this purely
+ * client-side projection.
+ */
+export function buildDurableTimeline(messages, compactions = [], activity, authorOf = noAuthor, requestIdOf = noRequestId, notices = []) {
+    const items = [];
+    const toolIndexes = new Map();
+    const commandIds = new Set();
+    const itemCommands = new Map();
+    let model;
+    let tokens = 0;
+    let cost = 0;
+    for (const source of orderedSources(messages, compactions, notices)) {
+        if (source.kind === "marker") {
+            items.push({
+                id: source.marker.id,
+                kind: "compaction_divider",
+                at: source.marker.at,
+                tokensBefore: source.marker.tokensBefore,
+                tokensAfter: source.marker.tokensAfter,
+            });
+            continue;
+        }
+        if (source.kind === "notice") {
+            items.push({
+                id: source.notice.id,
+                kind: "compaction_notice",
+                at: source.notice.at,
+                trigger: source.notice.trigger,
+                result: source.notice.result,
+                diagnostic: source.notice.diagnostic,
+            });
+            continue;
+        }
+        const message = source.message;
+        const value = message.value;
+        if (message.commandId !== null)
+            commandIds.add(message.commandId);
+        const firstItem = items.length;
+        switch (value.role) {
+            case "user": {
+                const commandId = message.commandId ?? message.id;
+                const confirmed = {
+                    id: message.id,
+                    kind: "user_message",
+                    commandId,
+                    status: "confirmed",
+                    at: value.timestamp,
+                    text: userText(value.content),
+                    author: authorOf(message.meta),
+                    origin: message.origin,
+                };
+                items.push(withRequestId(confirmed, requestIdOf(commandId)));
+                break;
+            }
+            case "assistant": {
+                const assistant = projectAssistant(message.id, value, authorOf(message.meta));
+                model = assistant.model;
+                tokens += assistant.usage.tokens;
+                cost += assistant.usage.cost;
+                appendAssistant(items, toolIndexes, assistant);
+                break;
+            }
+            case "toolResult":
+                completeTool(items, toolIndexes, value);
+                if (message.commandId !== null) {
+                    const commands = itemCommands.get(value.toolCallId) ?? new Set();
+                    commands.add(message.commandId);
+                    itemCommands.set(value.toolCallId, commands);
+                }
+                break;
+        }
+        if (message.commandId !== null) {
+            for (const item of items.slice(firstItem))
+                itemCommands.set(item.id, new Set([message.commandId]));
+        }
+    }
+    // A durable call without a result is not evidence that it still runs.
+    // Only the current command's last matching call can borrow live tool activity.
+    const queue = activity?.queue;
+    if (queue?.state === "running" && activity?.activeTool !== null) {
+        let currentCommand = false;
+        let toolIndex = -1;
+        for (let index = 0; index < items.length; index++) {
+            const item = items[index];
+            if (item?.kind === "user_message") {
+                currentCommand = item.commandId === queue.commandId;
+                if (currentCommand)
+                    toolIndex = -1;
+            }
+            if (currentCommand &&
+                item?.kind === "tool" &&
+                item.status === "unknown" &&
+                item.name === activity?.activeTool)
+                toolIndex = index;
+        }
+        const active = items[toolIndex];
+        if (active?.kind === "tool")
+            items[toolIndex] = { ...active, status: "running" };
+    }
+    const grouped = groupToolCalls(items);
+    const commandAnchors = new Map();
+    for (const row of grouped) {
+        if (row.kind === "assistant_message" && !assistantMessageVisible(row))
+            continue;
+        const members = row.kind === "tool_group" ? row.tools : [row];
+        for (const member of members)
+            for (const command of itemCommands.get(member.id) ?? [])
+                commandAnchors.set(command, row.id);
+    }
+    const base = {
+        commandAnchors,
+        completedMessageIds: completedMessageIds(messages),
+        items: grouped,
+        commandIds,
+    };
+    return model === undefined
+        ? base
+        : { ...base, model, usage: { cost, tokens } };
+}
+/** Project replaceable live work without copying settled history. */
+export function buildTimelineTail(durable, progress, queued, admissions = [], authorOf = noAuthor, requestIdOf = noRequestId) {
+    const visibleProgress = progress === null ||
+        durable.completedMessageIds.has(progress.messageId) ||
+        (progress.text === "" && progress.thinking === "")
+        ? undefined
+        : progress;
+    if (admissions.length === 0 &&
+        visibleProgress === undefined &&
+        queued.length === 0)
+        return [];
+    const items = [];
+    const queuedCommandIds = new Set(queued.map(({ commandId }) => commandId));
+    for (const prompt of queued) {
+        if (durable.commandIds.has(prompt.commandId))
+            continue;
+        const waiting = {
+            id: prompt.commandId,
+            kind: "user_message",
+            commandId: prompt.commandId,
+            status: "queued",
+            delivery: prompt.delivery,
+            text: prompt.text,
+            origin: prompt.origin,
+            author: authorOf(prompt.meta),
+        };
+        items.push(withRequestId(waiting, requestIdOf(prompt.commandId)));
+    }
+    for (const admission of admissions) {
+        if (admission.commandId !== undefined &&
+            (queuedCommandIds.has(admission.commandId) ||
+                durable.commandIds.has(admission.commandId)))
+            continue;
+        const baseItem = {
+            id: admission.requestId,
+            kind: "user_message",
+            requestId: admission.requestId,
+            status: admission.status === "failed"
+                ? "failed"
+                : admission.status === "accepted"
+                    ? "accepted"
+                    : "pending",
+            delivery: admission.delivery,
+            text: admission.content,
+        };
+        const commandItem = admission.commandId === undefined
+            ? baseItem
+            : { ...baseItem, commandId: admission.commandId };
+        const item = admission.error === undefined
+            ? commandItem
+            : { ...commandItem, error: admission.error };
+        items.push(item);
+    }
+    // Group only unresolved input; settled history and live progress keep their
+    // places. Filtering preserves the owner's order within each delivery group.
+    return [
+        ...(visibleProgress === undefined ? [] : [progressItem(visibleProgress)]),
+        ...items.filter((item) => item.status !== "failed" && item.delivery === "steer"),
+        ...items.filter((item) => item.status !== "failed" && item.delivery === "followUp"),
+        ...items.filter((item) => item.status === "failed"),
+    ];
+}
+/** Overlay live progress and an optimistic prompt over stable durable rows. */
+export function buildTimeline(durable, progress, queued, admissions = []) {
+    const tail = buildTimelineTail(durable, progress, queued, admissions);
+    if (tail.length === 0)
+        return durable;
+    const items = [...durable.items, ...tail];
+    if (durable.model === undefined || durable.usage === undefined)
+        return { items };
+    return { items, model: durable.model, usage: durable.usage };
+}

package/dist/core/client-actions.d.ts

@@ -0,0 +1,35 @@
+import type { ClientContributionV1 } from "@fungi.computer/shiitake/client-entry";
+import { type WhistleRuntime } from "@fungi.computer/whistle";
+import type { ParakeetInteractions } from "../commands/interactions.js";
+import type { ClientContribution } from "./client-contributions.js";
+/** Action state belongs to the selected Session, never the rendered row. */
+export type ClientActionState = Readonly<{
+    /** The same advertised intent is already in flight. */
+    pending: boolean;
+    /** Visible execution failure; cleared when this intent is retried. */
+    error?: string;
+}>;
+/** Run admitted row intents through the ordinary advertised Whistle commands. */
+export declare function createClientActions(options: Readonly<{
+    contributions: () => readonly ClientContribution[];
+    online: () => boolean;
+    commands: Pick<WhistleRuntime, "execute">;
+    interactions: ParakeetInteractions;
+}>): {
+    snapshot: () => ReadonlyMap<{
+        readonly label: string;
+        readonly id: string;
+        readonly input?: {
+            readonly [x: string]: import("effect/Schema").Json;
+        } | undefined;
+    }, Readonly<{
+        /** The same advertised intent is already in flight. */
+        pending: boolean;
+        /** Visible execution failure; cleared when this intent is retried. */
+        error?: string;
+    }>>;
+    refresh: () => void;
+    subscribe: (listener: () => void) => () => void;
+    execute: (entryId: string, action: NonNullable<ClientContributionV1["waiting"]>["cancel"], waiting?: boolean) => Promise<void>;
+    dispose: () => void;
+};

package/dist/core/client-actions.js

@@ -0,0 +1,128 @@
+import { WhistleActionError, } from "@fungi.computer/whistle";
+import { reportFailure } from "../lib/failure.js";
+function advertisedActions(entry) {
+    return [
+        ...entry.value.panel.flatMap((row) => row.actions ?? []),
+        ...entry.value.timeline.cells.flatMap((cell) => cell.rows.flatMap((row) => row.actions ?? [])),
+        ...(entry.value.waiting === null ? [] : [entry.value.waiting.cancel]),
+    ];
+}
+/** Run admitted row intents through the ordinary advertised Whistle commands. */
+export function createClientActions(options) {
+    const controller = new AbortController();
+    // Abort may change while the advertised command is awaiting its owner.
+    const retired = () => controller.signal.aborted;
+    const listeners = new Set();
+    let state = new Map();
+    // Admission decodes fresh row objects on a committed slot change. Pending
+    // work belongs to the advertised command intent, not that object's address.
+    const intents = new Map();
+    const key = (entryId, action) => JSON.stringify([entryId, action.id, action.input ?? {}]);
+    const refresh = () => {
+        if (retired())
+            return;
+        const current = new Map();
+        const visible = new Set();
+        for (const entry of options.contributions()) {
+            for (const action of advertisedActions(entry)) {
+                const id = key(entry.entryId, action);
+                visible.add(id);
+                const value = intents.get(id);
+                if (value !== undefined)
+                    current.set(action, value);
+            }
+        }
+        for (const [id, value] of intents)
+            if (!visible.has(id) && !value.pending)
+                intents.delete(id);
+        state = current;
+        for (const listener of listeners)
+            listener();
+    };
+    const publish = (id, next) => {
+        if (retired())
+            return;
+        intents.set(id, next);
+        refresh();
+    };
+    return {
+        snapshot: () => state,
+        refresh,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        execute: async (entryId, action, waiting = false) => {
+            const entry = options
+                .contributions()
+                .find((value) => value.entryId === entryId);
+            if (retired() ||
+                !options.online() ||
+                entry === undefined ||
+                !advertisedActions(entry).includes(action) ||
+                (waiting && entry.value.waiting?.cancel !== action))
+                return;
+            const intent = key(entryId, action);
+            if (intents.get(intent)?.pending)
+                return;
+            publish(intent, { pending: true });
+            const notificationOnly = {
+                signal: controller.signal,
+                prompt: () => Promise.reject(new WhistleActionError("client_waiting_prompt", "A waiting cancellation cannot request an answer")),
+                notify: (notice) => {
+                    if (retired())
+                        return;
+                    options.interactions.report({
+                        tone: notice.type === "success" ? "success" : "info",
+                        message: notice.type === "handoff"
+                            ? (notice.message ?? notice.url)
+                            : notice.message,
+                    });
+                },
+            };
+            let outcome;
+            try {
+                let input = {
+                    origin: "menu",
+                    signal: controller.signal,
+                };
+                if (action.input !== undefined)
+                    input = { ...input, arguments: action.input };
+                if (waiting)
+                    input = { ...input, interaction: notificationOnly };
+                outcome = await options.commands.execute(`${entryId}:${action.id}`, input);
+            }
+            catch (cause) {
+                reportFailure("client row command", cause);
+                if (retired())
+                    return;
+                const error = cause instanceof Error
+                    ? cause
+                    : new Error("Client row command failed", { cause });
+                publish(intent, { pending: false, error: error.message });
+                options.interactions.report({ tone: "error", message: error.message });
+                return;
+            }
+            if (retired())
+                return;
+            const error = outcome.status === "handled"
+                ? undefined
+                : outcome.status === "failed"
+                    ? outcome.error.message
+                    : outcome.status === "unavailable"
+                        ? outcome.reason
+                        : `Client row command ${outcome.status}`;
+            publish(intent, error === undefined ? { pending: false } : { pending: false, error });
+            if (error !== undefined)
+                options.interactions.report({ tone: "error", message: error });
+        },
+        dispose: () => {
+            controller.abort();
+            state = new Map();
+            intents.clear();
+            listeners.clear();
+        },
+    };
+}

package/dist/core/client-contributions.d.ts

@@ -0,0 +1,24 @@
+import { type ClientContributionV1, type ClientEntryV1 } from "@fungi.computer/shiitake/client-entry";
+import type { SessionExtensionSlots } from "@fungi.computer/shiitake/client";
+/** Decoded client data, still owned and ordered by its composition root. */
+export type ClientContribution = Readonly<{
+    /** Composition-root identity of the producing entry. */
+    entryId: string;
+    /** Strictly admitted presentation data for the current observed slot. */
+    value: ClientContributionV1;
+}>;
+/**
+ * The selected-Session evaluation owner. Feed existing observed slots here;
+ * renderers subscribe to admitted data and never evaluate an entry in render.
+ */
+export declare function createClientContributions(installed: readonly ClientEntryV1[], onError: (entryId: string, error: Error) => void): {
+    snapshot: () => readonly Readonly<{
+        /** Composition-root identity of the producing entry. */
+        entryId: string;
+        /** Strictly admitted presentation data for the current observed slot. */
+        value: ClientContributionV1;
+    }>[];
+    subscribe: (listener: () => void) => () => void;
+    update: (slots: SessionExtensionSlots) => void;
+    dispose: () => void;
+};