@fungi.computer/parakeet 0.0.0-stage → 0.1.0

package/dist/session-commands.js

@@ -0,0 +1,259 @@
+import { nanoid } from "@fungi.computer/cairn";
+import { ShiitakeError } from "@fungi.computer/shiitake";
+import { z } from "zod";
+import { buildDurableTimeline } from "./core/build-timeline.js";
+import { sessionActivityStatus, sessionViewState, } from "./core/session-view-state.js";
+/** A choice prompt holds at most 256 options; the default read already bounds this. */
+const maxForkOptions = 200;
+const queueArguments = z.discriminatedUnion("action", [
+    z.strictObject({ action: z.literal("list") }),
+    z.strictObject({ action: z.literal("editLast") }),
+]);
+const queueArgumentsSchema = z
+    .record(z.string(), z.json())
+    .parse(structuredClone(z.toJSONSchema(queueArguments)));
+/** The owner's bound for one user-set Session title, in code points. */
+const maxTitleLength = 120;
+const nameArguments = z
+    .strictObject({ title: z.string() })
+    .optional()
+    .transform((value) => value?.title.trim().replaceAll(/\s+/gu, " ") ?? "");
+/** The owner's bound for one compaction focus, in UTF-16 units. */
+const maxCompactionInstructions = 4_096;
+const compactArguments = z
+    .strictObject({ instructions: z.string() })
+    .optional()
+    .transform((value) => value?.instructions.trim() ?? "");
+/** Tell the human, when one is present, and return the same text. */
+function tell(interaction, message) {
+    interaction?.notify({ type: "info", message });
+    return message;
+}
+/** Contribute the shared Session command vocabulary to one Whistle host. */
+export function contributeSessionCommands(commands, session, options) {
+    const unavailable = (name) => {
+        throw new Error(`${name} is unavailable in this host.`);
+    };
+    const contribution = {
+        sourceId: options.sourceId,
+        namespace: options.namespace,
+        commands: [
+            {
+                id: "session",
+                title: "Session status",
+                category: "Advanced",
+                projections: {
+                    help: { order: 1 },
+                    palette: { order: 1 },
+                    slash: { aliases: ["session"], order: 1 },
+                },
+                handler: async ({ interaction }) => {
+                    const snapshot = await session.read();
+                    return tell(interaction, `Session ${snapshot.sessionId} is ${sessionActivityStatus(sessionViewState(snapshot))}; ${String(snapshot.pending.prompts.length)} queued prompt${snapshot.pending.prompts.length === 1 ? "" : "s"}.`);
+                },
+            },
+            {
+                id: "queue",
+                title: "Queued prompts",
+                category: "Advanced",
+                projections: {
+                    help: { order: 3 },
+                    palette: { order: 3 },
+                    slash: {
+                        aliases: ["queue"],
+                        order: 3,
+                        arguments: {
+                            hint: "list | edit-last",
+                            words: [
+                                {
+                                    word: "list",
+                                    description: "List accepted queued prompts",
+                                    arguments: { action: "list" },
+                                },
+                                {
+                                    word: "edit-last",
+                                    description: "Return the last queued prompt to the composer",
+                                    arguments: { action: "editLast" },
+                                },
+                            ],
+                        },
+                    },
+                },
+                action: { inputSchema: queueArgumentsSchema },
+                handler: async ({ arguments: rawArguments, interaction, }) => {
+                    const args = queueArguments.safeParse(rawArguments ?? { action: "list" });
+                    if (!args.success)
+                        throw new Error("/queue requires list or editLast.");
+                    const snapshot = await session.read();
+                    if (args.data.action === "list") {
+                        const prompts = snapshot.pending.prompts;
+                        const settled = snapshot.terminals.map((terminal) => `${terminal.outcome} · ${terminal.commandId}`);
+                        tell(interaction, prompts.length === 0 && settled.length === 0
+                            ? "No queued prompts."
+                            : [
+                                ...prompts.map((prompt, index) => `${String(index + 1)}. queued · accepted: ${prompt.text}`),
+                                ...settled,
+                                ...(snapshot.pending.hasMore === true
+                                    ? ["More accepted prompts are waiting outside this view."]
+                                    : []),
+                            ].join("\n"));
+                        return;
+                    }
+                    if (snapshot.pending.hasMore === true)
+                        throw new Error("The queue view is incomplete; refresh it before editing the last prompt.");
+                    const prompt = [...snapshot.pending.prompts]
+                        .reverse()
+                        .find((candidate) => candidate.delivery === "followUp");
+                    if (prompt === undefined)
+                        throw new Error("There is no queued follow-up to edit.");
+                    if (session.cancel === undefined)
+                        throw new Error("Queue editing is unavailable in this host.");
+                    if (options.onEditQueued === undefined)
+                        throw new Error("Editing queued prompts is unavailable in this host.");
+                    if (options.canEditQueued?.() === false)
+                        throw new Error("Clear or submit the current draft before editing a queued prompt.");
+                    const withdrawn = await session.cancel({
+                        commandId: prompt.commandId,
+                        onlyIfPending: true,
+                    });
+                    if (withdrawn.status === "too_late")
+                        throw new Error("That queued prompt has already started; it can no longer be edited.");
+                    options.onEditQueued(prompt.text);
+                    tell(interaction, "Queued prompt returned to the composer for editing.");
+                },
+            },
+            {
+                id: "resume",
+                title: "Resume a conversation",
+                category: "Conversation",
+                projections: {
+                    help: { order: 5 },
+                    palette: { order: 5 },
+                    slash: { aliases: ["resume"], order: 5 },
+                },
+                handler: async () => {
+                    if (!options.sessionResumeAvailable ||
+                        options.sessionResume === undefined) {
+                        unavailable("/resume");
+                        return;
+                    }
+                    await options.sessionResume();
+                },
+            },
+            {
+                id: "fork",
+                title: "Fork conversation",
+                category: "Conversation",
+                projections: {
+                    help: { order: 7 },
+                    palette: { order: 7 },
+                    slash: { aliases: ["fork"], order: 7 },
+                },
+                handler: async ({ interaction }) => {
+                    if (!options.forkAvailable || options.onForked === undefined) {
+                        unavailable("/fork");
+                        return;
+                    }
+                    const snapshot = await session.read();
+                    if (sessionActivityStatus(sessionViewState(snapshot)) !== "idle")
+                        throw new Error("Wait for the current run to finish, then fork.");
+                    const candidates = buildDurableTimeline(snapshot.messages ?? [], snapshot.compactions ?? []).items.filter((item) => item.kind === "user_message");
+                    if (candidates.length === 0)
+                        throw new Error("No messages to fork from.");
+                    if (interaction === undefined)
+                        throw new Error("Forking a Session needs a person.");
+                    const ordered = [...candidates].reverse().slice(0, maxForkOptions);
+                    const answer = await interaction.prompt({
+                        type: "choice",
+                        message: "Fork from message",
+                        options: ordered.map((item) => ({
+                            value: item.id,
+                            label: item.text.slice(0, 100) || "(empty message)",
+                        })),
+                    });
+                    let forked;
+                    try {
+                        forked = await session.command({ type: "fork", entryId: answer });
+                    }
+                    catch (error) {
+                        if (error instanceof ShiitakeError) {
+                            if (error.boundary === "runtime" && error.cause === "conflict")
+                                throw new Error("Wait for the current run to finish, then fork.", { cause: error });
+                            if (error.boundary === "store" && error.cause === "unavailable")
+                                throw new Error("That message is no longer available to fork from.", { cause: error });
+                            if (error.boundary === "runtime" && error.cause === "rejected")
+                                throw new Error("This Session is bound to a channel and cannot be forked.", { cause: error });
+                        }
+                        throw error;
+                    }
+                    await options.onForked(forked.sessionId);
+                    tell(interaction, "Forked into a new Session.");
+                },
+            },
+            {
+                id: "compact",
+                title: "Compact conversation",
+                category: "Conversation",
+                description: "Summarize older context now; optional text sets its focus",
+                projections: {
+                    help: { order: 8 },
+                    palette: { order: 8 },
+                    slash: {
+                        aliases: ["compact"],
+                        order: 8,
+                        arguments: {
+                            hint: "[instructions]",
+                            text: { field: "instructions", arguments: {} },
+                        },
+                    },
+                },
+                handler: async ({ arguments: input, interaction, }) => {
+                    const parsed = compactArguments.safeParse(input);
+                    if (!parsed.success)
+                        throw new Error("Use /compact, or /compact <what to focus on>.");
+                    const instructions = parsed.data;
+                    if (instructions.length > maxCompactionInstructions)
+                        throw new Error(`Compaction instructions are at most ${String(maxCompactionInstructions)} characters.`);
+                    // One request id per invocation; the owner replays a retried one.
+                    await session.command(instructions.length === 0
+                        ? { type: "compact", requestId: nanoid() }
+                        : { type: "compact", requestId: nanoid(), instructions });
+                    return tell(interaction, "Compaction queued; it runs after any current work.");
+                },
+            },
+            {
+                id: "name",
+                title: "Name conversation",
+                category: "Conversation",
+                description: "Set the conversation title; no text restores it",
+                projections: {
+                    help: { order: 9 },
+                    palette: { order: 9 },
+                    slash: {
+                        aliases: ["name"],
+                        order: 9,
+                        arguments: {
+                            hint: "[title]",
+                            text: { field: "title", arguments: {} },
+                        },
+                    },
+                },
+                handler: async ({ arguments: input, interaction, }) => {
+                    const parsed = nameArguments.safeParse(input);
+                    if (!parsed.success)
+                        throw new Error("Use /name <title>, or /name to clear it.");
+                    const text = parsed.data;
+                    if (Array.from(text).length > maxTitleLength)
+                        throw new Error(`A conversation title is at most ${String(maxTitleLength)} characters.`);
+                    const title = text.length === 0 ? null : text;
+                    await session.command({ type: "title", title });
+                    await options.onTitled?.(title);
+                    return tell(interaction, title === null
+                        ? "Conversation title cleared; it follows the first prompt again."
+                        : `Conversation named "${title}".`);
+                },
+            },
+        ],
+    };
+    return commands.contribute(contribution);
+}

package/dist/session.d.ts

@@ -0,0 +1,24 @@
+import type { ShiitakeSession, Accepted, CancelResult, ForkedSession, PromptCommand, CompactCommand, CancelCommand, AbortCommand, BranchCommand, OperatorCommand, TitleCommand, ForkCommand, SessionCommand } from "@fungi.computer/shiitake/client";
+/** A prompt may be recorded for a human without admitting Agent work. */
+export type ParakeetPromptResult = Accepted | Readonly<{
+    /** The owner stored this prompt without starting Agent work. */
+    status: "recorded";
+}>;
+/** Session commands preserve their owner results, including held visitor lines. */
+export type ParakeetSessionCommand = {
+    /** Admit Agent work or record a prompt held for a human reply. */
+    (input: PromptCommand | CompactCommand): Promise<ParakeetPromptResult>;
+    /** Cancel the named queued or running command. */
+    (input: CancelCommand): Promise<CancelResult>;
+    /** Forward an owner-supported Session control command. */
+    (input: AbortCommand | BranchCommand | OperatorCommand | TitleCommand): Promise<undefined>;
+    /** Return the owner-issued address of a forked Session. */
+    (input: ForkCommand): Promise<ForkedSession>;
+    /** Dispatch a typed command without inventing an admission result. */
+    (input: SessionCommand): Promise<ParakeetPromptResult | CancelResult | ForkedSession | undefined>;
+};
+/** The exact Shiitake operations consumed by the retained conversation UI. */
+export type ParakeetSession = Readonly<Pick<ShiitakeSession, "address" | "extension" | "read" | "watch"> & {
+    /** Submit commands through this Session's admitted owner boundary. */
+    command: ParakeetSessionCommand;
+}>;

package/dist/session.js

@@ -0,0 +1 @@
+export {};

package/dist/store/types.d.ts

@@ -0,0 +1,163 @@
+import type { ParakeetAuthor } from "../core/author-labels.js";
+import type { PromptDelivery, SessionCompactionTrigger, SessionMessage } from "@fungi.computer/shiitake/client";
+import type { ToolArguments } from "../core/tool-contract.js";
+import type { ToolCallView } from "../core/tool-view.js";
+/** Exact Pi tool result joined to its tool call by the timeline projection. */
+export type ToolResultMessage = Extract<SessionMessage["value"], {
+    role: "toolResult";
+}>;
+/** One user prompt projected into the conversation timeline. */
+export type UserMessageItem = Readonly<{
+    /** The author the host read from the message metadata, apart from its text. */
+    author?: ParakeetAuthor | undefined;
+    /** Durable extension producer, separate from host author attribution. */
+    origin?: SessionMessage["origin"];
+    /** Stable rendered-item identity. */
+    id: string;
+    /** User-message timeline discriminator. */
+    kind: "user_message";
+    /**
+     * Client identity of a prompt this composer submitted. It stays the same from
+     * submit through queued to durable, so renderers key the row by it; it also
+     * names a failed admission to retry or dismiss.
+     */
+    requestId?: string;
+    /** Owner-issued work identity once the prompt is admitted. */
+    commandId?: string;
+    /**
+     * Whether admission is pending/accepted, the owner reports queued, or it
+     * failed/settled. Only `confirmed` means the Agent has taken the prompt.
+     */
+    status: "pending" | "accepted" | "queued" | "failed" | "confirmed";
+    /** Delivery intent while this accepted input waits for consumption. */
+    delivery?: PromptDelivery;
+    /** Admission failure presented by the headless composer. */
+    error?: string;
+    /** When the prompt was sent, in milliseconds since the epoch, once known. */
+    at?: number;
+    /** Prompt text. */
+    text: string;
+}>;
+/** One locally submitted prompt before the Session projection catches up. */
+export type LocalPromptAdmission = Readonly<{
+    /** Caller idempotency key, retained across retries. */
+    requestId: string;
+    /** Owner-issued identity after successful admission. */
+    commandId?: string;
+    /** Prompt content sent to the Session. */
+    content: string;
+    /** Existing Session delivery intent. */
+    delivery: PromptDelivery;
+    /** Current local admission result. */
+    status: "admitting" | "accepted" | "failed";
+    /** User-presentable admission error when status is failed. */
+    error?: string;
+}>;
+/** One assistant message projected from exact stored Pi content. */
+export type AssistantMessageItem = Readonly<{
+    /** The author of a human reply carried as assistant text, as the host read it. */
+    author?: ParakeetAuthor | undefined;
+    /** Stable rendered-item identity. */
+    id: string;
+    /** Assistant-message timeline discriminator. */
+    kind: "assistant_message";
+    /** Whether the assistant message terminated with an error. */
+    isError?: boolean;
+    /** Whether replaceable progress is still contributing to this message. */
+    pending: boolean;
+    /** When the reply was written, in milliseconds since the epoch, once known. */
+    at?: number;
+    /** Assistant-visible response text. */
+    text: string;
+    /** Assistant reasoning text, when supplied by the model. */
+    thinking?: string;
+    /** Usage carried by the exact assistant message. */
+    usage?: Readonly<{
+        /** Provider cost of this assistant message. */
+        cost: number;
+        /** Tokens consumed by this assistant message. */
+        tokens: number;
+    }>;
+}>;
+/** One Pi tool call joined with its corresponding tool result. */
+export type ToolItem = Readonly<{
+    /** Canonically parsed JSON arguments supplied to the tool. */
+    args: Readonly<ToolArguments>;
+    /** Stable tool-call identity. */
+    id: string;
+    /** Tool timeline discriminator. */
+    kind: "tool";
+    /** Pi tool name. */
+    name: string;
+    /** Exact joined Pi tool result, when one has completed. */
+    result?: ToolResultMessage;
+    /** Timestamp of the assistant message that issued the call. */
+    startedAt?: number;
+    /** Owner-confirmed activity or result; unknown when neither is available. */
+    status: "completed" | "error" | "running" | "unknown";
+}>;
+/**
+ * One maximal run of consecutive tool calls between conversation rows. A lone
+ * call is a group of one. Grouping is computed once by the headless projection.
+ */
+export type ToolGroupItem = Readonly<{
+    /** Running call whose live line the collapsed header shows. */
+    active?: ToolCallView | undefined;
+    /** Renderer-neutral view of each call, in call order. */
+    calls: readonly ToolCallView[];
+    /** First call to last result, once no call is running. */
+    durationMs?: number | undefined;
+    /** Calls whose joined result reports an error. */
+    failedCount: number;
+    /** Stable identity derived from the first call, kept as calls append. */
+    id: string;
+    /** Tool-group timeline discriminator. */
+    kind: "tool_group";
+    /** `running` for owner-confirmed work; unknown when a result is unavailable. */
+    status: "completed" | "error" | "running" | "unknown";
+    /** One-line summary from typed kinds, e.g. `Read 3 files, ran 2 commands`. */
+    summary: string;
+    /** Exact joined calls, in call order. */
+    tools: readonly ToolItem[];
+}>;
+/**
+ * One compaction boundary rendered as a divider: a full-width rule with a
+ * short label, never a chat bubble. Everything above it was summarized away;
+ * the agent's live context starts at the row immediately below it.
+ * @inline
+ */
+export type CompactionDividerItem = Readonly<{
+    /** Stable rendered-item identity, from the durable compaction entry. */
+    id: string;
+    /** Compaction-divider timeline discriminator. */
+    kind: "compaction_divider";
+    /** When the compaction ran, in milliseconds since the epoch. */
+    at: number;
+    /** Estimated context tokens the compaction started from. */
+    tokensBefore: number;
+    /** Estimated context tokens right after it; null for older compactions. */
+    tokensAfter: number | null;
+}>;
+/**
+ * A compaction that changed nothing, rendered as a short notice at its own
+ * place in the timeline: never a chat bubble, never a context edit.
+ * @inline
+ */
+export type CompactionNoticeItem = Readonly<{
+    /** Stable rendered-item identity, from the durable notice entry. */
+    id: string;
+    /** Compaction-notice timeline discriminator. */
+    kind: "compaction_notice";
+    /** When it was recorded, in milliseconds since the epoch. */
+    at: number;
+    /** What started it: the user, the context threshold, or an overflow. */
+    trigger: SessionCompactionTrigger;
+    /** What the compaction did: nothing to summarize, or a failure. */
+    result: "nothing_to_compact" | "failed";
+    /** A failure's bounded reason; null for "nothing to compact". */
+    diagnostic: string | null;
+}>;
+/** Stable row grammar rendered by Parakeet's timeline. */
+export type TimelineItem = AssistantMessageItem | CompactionDividerItem | CompactionNoticeItem | ToolGroupItem | UserMessageItem;
+/** Projection-internal rows before consecutive calls are grouped. */
+export type ProjectedItem = AssistantMessageItem | CompactionDividerItem | CompactionNoticeItem | ToolItem | UserMessageItem;

package/dist/store/types.js

@@ -0,0 +1 @@
+export {};