@fungi.computer/parakeet 0.0.1 → 0.2.0

package/README.md

@@ -126,17 +126,56 @@ It owns parsing, completion, stable request identities and interaction state.
 The browser and terminal render the same questions, choices and notices.
 `/model` and `/thinking` use that interaction path.
 
+`ParakeetProvider` accepts `onToast` for transient command information. The host
+renders it through its existing toast owner: the terminal's shared toast
+viewport or Grove's `ui.showToast`. `ParakeetInteractions.toast` and
+`subscribeToasts` expose the same renderer-neutral seam. Ordinary first-success
+echoes are silent, including after a dialog completes. Progress, questions and
+handoffs remain in their interaction while active; failures retain their retry
+or attention UI rather than expiring as information.
+
+After Try again, a final information or success notice stays in that
+interaction's existing result row until Done/close, without an extra toast. A
+producer that supplies no completion notice does not gain a fabricated result.
+
 Account commands are provider-neutral. The host's account owner and policy
 decide which login methods are available. The presentation layer does not gain a
 credential store or make an advertised command authorized.
 
+Queued timeline rows offer Cancel through
+`useTimeline().cancelQueued(commandId)`. The row disappears immediately while
+the existing Session owner decides the pending-only cancellation. This never
+stops the running turn or restores text to the composer. TooLate or an
+unconfirmed response produces a warning and restores any row still reported as
+queued; an accepted response stays hidden through stale queued snapshots until
+the owner projection catches up. Only one queued gesture waits for its owner at
+a time, and switching conversations discards its presentation state. Recall
+remains a separate restore-to-composer gesture.
+
 The composer reconciles optimistic prompts with owner facts by request identity.
-Retrying a failed admission preserves its request identity. Retrying failed or
-interrupted durable work submits a new request identity. Failed observation
-shows connection failure; reconnecting does not prove pending work failed or
-resubmit it automatically. Typed command errors remain visible and retryable.
-The host remains responsible for the Session transport, current permissions and
-operator diagnostics.
+Submitting clears the draft immediately and adds a faded pending message.
+Acceptance restores normal emphasis; owner-queued messages remain faded. If
+admission fails, the exact submitted text returns to the composer and the host
+receives an error toast. Any newer draft stays first, followed by a blank line
+and the restored text; acceptance never clears newer typing. An uncertain
+admission retains its request identity while the owner resolves it. An accepted
+resolution confirms the admitted command or recorded entry; only confirmed
+withdrawal restores the draft and permits retry with a new request identity,
+because the old identity is durably fenced. Retrying failed or interrupted
+durable work also submits a new request identity, preserving the failed prompt's
+text and image cargo, including image-only prompts after live-page eviction. It
+does not consume a newer unsent draft. Failed observation shows connection
+failure; reconnecting does not prove pending work failed or resubmit it
+automatically. Typed command errors remain visible and retryable. The host
+remains responsible for the Session transport, current permissions and operator
+diagnostics.
+
+An owner's accepted withdrawal receipt can name a run-free recorded entry:
+`receipt.commandId === message.id` even though `message.commandId === null`.
+That receipt confirms durable recording, not cancellation or model admission. A
+translating host retains the original composer identity in its durable metadata
+and projects it as `messages[].requestId` or `pending.prompts[].requestId`; its
+internal admission key is not that identity.
 
 ## API and examples
 

package/dist/account-commands.js

@@ -91,17 +91,13 @@ export async function signInProvider(owner, provider, interaction, request = {})
         type: "progress",
         message: `Signing in to ${provider.name}…`,
     });
-    await owner.login(request.option === undefined
+    await interaction.run(() => owner.login(request.option === undefined
         ? { providerId: provider.id, method: method.kind }
         : {
             providerId: provider.id,
             method: method.kind,
             option: request.option,
-        }, interaction);
-    interaction.notify({
-        type: "success",
-        message: `Signed in to ${provider.name}.`,
-    });
+        }, interaction));
 }
 async function signOutProvider(owner, provider, interaction) {
     const confirmed = await interaction.prompt({
@@ -112,11 +108,7 @@ async function signOutProvider(owner, provider, interaction) {
     });
     if (!confirmed)
         return;
-    await owner.logout(provider.id, interaction);
-    interaction.notify({
-        type: "success",
-        message: `Signed out of ${provider.name}.`,
-    });
+    await interaction.run(() => owner.logout(provider.id, interaction));
 }
 /** Cancelling a sign-in is an ordinary ending, not a failure. */
 async function unlessCancelled(interaction, work) {

package/dist/commands/advertised.d.ts

@@ -1,6 +1,7 @@
 import type { SessionExtensionSlots } from "@fungi.computer/shiitake/client";
 import type { WhistleRuntime } from "@fungi.computer/whistle";
 import type { ParakeetSession } from "../session.js";
+import type { ClientContribution } from "../core/client-contributions.js";
 /** Why one advertised catalog could not become commands. */
 export type AdvertisedCatalogError = Readonly<{
     /** The extension that advertised it. */
@@ -19,5 +20,6 @@ export type AdvertisedCommands = Readonly<{
  * Turn each running extension's advertised `whistle.catalog/v1` catalog into
  * Whistle commands that call that extension's own door. The client names no
  * command: a new extension's catalog appears as new commands.
+ * @param contributions - Current admitted panels that own unanswered prompts.
  */
-export declare function advertisedCommands(runtime: Pick<WhistleRuntime, "contribute">, session: Pick<ParakeetSession, "extension">, onInspect?: (entryId: string, commandId: string) => void): AdvertisedCommands;
+export declare function advertisedCommands(runtime: Pick<WhistleRuntime, "contribute">, session: Pick<ParakeetSession, "extension">, contributions: () => readonly ClientContribution[], onInspect?: (entryId: string, commandId: string) => void): AdvertisedCommands;

package/dist/commands/advertised.js

@@ -1,5 +1,5 @@
 import * as Schema from "effect/Schema";
-import { catalogCommands, parseCatalog } from "@fungi.computer/whistle/catalog";
+import { catalogCommands, parseCatalog, parseCatalogStep, } from "@fungi.computer/whistle/catalog";
 const cancelled = Schema.is(Schema.Struct({ cancelled: Schema.Literal(true) }));
 /** A bare invocation views; one carrying action arguments (`/plan clear`) acts. */
 const bare = Schema.is(Schema.UndefinedOr(Schema.Record(Schema.String, Schema.Never)));
@@ -7,9 +7,28 @@ const bare = Schema.is(Schema.UndefinedOr(Schema.Record(Schema.String, Schema.Ne
  * Turn each running extension's advertised `whistle.catalog/v1` catalog into
  * Whistle commands that call that extension's own door. The client names no
  * command: a new extension's catalog appears as new commands.
+ * @param contributions - Current admitted panels that own unanswered prompts.
  */
-export function advertisedCommands(runtime, session, onInspect) {
+export function advertisedCommands(runtime, session, contributions, onInspect) {
     const live = new Map();
+    const panelActions = (id, command) => contributions()
+        .find((entry) => entry.entryId === id)
+        ?.value.panel.flatMap((row) => row.actions ?? [])
+        .filter((action) => action.id === command) ?? [];
+    const intent = (action) => JSON.stringify([action.id, action.input ?? {}]);
+    // A prompt borrows its panel intent, not the entire backend operation.
+    // Once answered, its pending response must retain its ordinary lifetime.
+    const prompts = new Set();
+    const refreshPrompts = () => {
+        for (const prompt of prompts) {
+            const visible = new Set(panelActions(prompt.entryId, prompt.commandId).map(intent));
+            if (live.has(prompt.entryId) &&
+                prompt.intents.every((id) => visible.has(id)))
+                continue;
+            prompt.execution.withdrawn = true;
+            prompt.controller.abort();
+        }
+    };
     const withdraw = (id) => {
         live.get(id)?.lease.dispose();
         live.delete(id);
@@ -31,7 +50,8 @@ export function advertisedCommands(runtime, session, onInspect) {
                 withdraw(id);
                 try {
                     const address = session.extension(id);
-                    const commands = catalogCommands(parseCatalog(slot.catalog), (command, args) => address.call(command, args));
+                    const catalog = parseCatalog(slot.catalog);
+                    const commands = catalogCommands(catalog, (command, args) => address.call(command, args));
                     live.set(id, {
                         catalog: encoded,
                         lease: runtime.contribute({
@@ -40,7 +60,70 @@ export function advertisedCommands(runtime, session, onInspect) {
                             commands: commands.map((command) => ({
                                 ...command,
                                 handler: async (input) => {
-                                    const result = await command.handler(input);
+                                    const actions = panelActions(id, command.id);
+                                    const execution = {
+                                        intents: actions.map(intent),
+                                        withdrawn: false,
+                                    };
+                                    // Invocation-local closures retain admitted identities only.
+                                    // A caller may share its signal and pass secret arguments.
+                                    const scopedCommand = catalogCommands(catalog, async (name, args) => {
+                                        const reply = await address.call(name, args);
+                                        const step = parseCatalogStep(reply);
+                                        if (step.type === "prompt") {
+                                            const selected = actions.filter((action) => Object.entries(action.input ?? {}).every(([key, value]) => JSON.stringify(Object.hasOwn(step.next.arguments, key)
+                                                ? step.next.arguments[key]
+                                                : args[key]) === JSON.stringify(value)));
+                                            // Before selection, a chooser borrows all its candidates.
+                                            execution.intents = (selected.length > 0 ? selected : actions).map(intent);
+                                        }
+                                        return reply;
+                                    }).find((candidate) => candidate.id === command.id);
+                                    if (scopedCommand === undefined)
+                                        throw new Error("The advertised command is unavailable");
+                                    let scoped = input;
+                                    const interaction = input.interaction;
+                                    if (interaction !== undefined) {
+                                        const bound = {
+                                            ...interaction,
+                                            prompt: (request, options) => {
+                                                const prompt = {
+                                                    entryId: id,
+                                                    commandId: command.id,
+                                                    intents: execution.intents,
+                                                    execution,
+                                                    controller: new AbortController(),
+                                                };
+                                                prompts.add(prompt);
+                                                refreshPrompts();
+                                                return interaction
+                                                    .prompt(request, {
+                                                    signal: options?.signal === undefined
+                                                        ? prompt.controller.signal
+                                                        : AbortSignal.any([
+                                                            options.signal,
+                                                            prompt.controller.signal,
+                                                        ]),
+                                                })
+                                                    .finally(() => prompts.delete(prompt));
+                                            },
+                                        };
+                                        scoped = { ...scoped, interaction: bound };
+                                    }
+                                    let result;
+                                    try {
+                                        result = await scopedCommand.handler(scoped);
+                                    }
+                                    catch (cause) {
+                                        if (execution.withdrawn)
+                                            return { cancelled: true };
+                                        throw cause;
+                                    }
+                                    finally {
+                                        for (const prompt of prompts)
+                                            if (prompt.execution === execution)
+                                                prompts.delete(prompt);
+                                    }
                                     if (input.origin !== "agent" &&
                                         bare(input.arguments) &&
                                         !cancelled(result) &&
@@ -62,11 +145,13 @@ export function advertisedCommands(runtime, session, onInspect) {
                     });
                 }
             }
+            refreshPrompts();
             return errors;
         },
         dispose: () => {
             for (const id of live.keys())
                 withdraw(id);
+            refreshPrompts();
         },
     };
 }

package/dist/commands/builtins.js

@@ -49,7 +49,7 @@ export function parakeetBuiltinCommands(runtime, options) {
             category: "Advanced",
             projections: {
                 help: { order: -2 },
-                slash: { aliases: ["keys"], order: -2 },
+                slash: { aliases: ["keys"], order: -2, consumesDraft: true },
             },
             handler: async (input) => {
                 const keys = keyBindings(runtime.snapshot());

package/dist/commands/interactions.d.ts

@@ -6,13 +6,24 @@ export type ParakeetOpenInteraction = Readonly<{
     key: number;
     /** The renderer-neutral interaction store to draw. */
     host: WhistleInteractionHost;
-    /** Run the same command again with the same input. */
-    retry: () => void;
 }>;
-/** A one-line result shown beside the composer instead of a dialog. */
+/**
+ * An attention item shown beside the composer until it is resolved: something
+ * failed or waits on the person. Everything else is a toast.
+ */
 export type ParakeetNotice = Readonly<{
     /** How to color it. */
-    tone: "info" | "success" | "error";
+    tone: "info" | "error";
+    /** What happened. */
+    message: string;
+}>;
+/**
+ * A transient message a renderer shows as a toast. A command's confirmation of
+ * what the person just did is never one: it is an echo and is not announced.
+ */
+export type ParakeetToast = Readonly<{
+    /** How to color it. */
+    variant: "info" | "warning" | "error";
     /** What happened. */
     message: string;
 }>;
@@ -27,7 +38,7 @@ export type ParakeetInteractionState = Readonly<{
         /** Stable identity of the panel row being inspected. */
         rowId: string;
     }> | undefined;
-    /** The latest one-line result. */
+    /** The latest attention item: it stays until the person resolves it. */
     notice?: ParakeetNotice | undefined;
 }>;
 /** Parakeet's command conversation store, shared by every renderer. */
@@ -40,8 +51,12 @@ export type ParakeetInteractions = Readonly<{
     close: () => void;
     /** Open or dismiss an admitted panel inspection without starting a command. */
     inspect: (inspection: ParakeetInteractionState["inspection"]) => void;
-    /** Replace or clear the one-line notice, starting a new command turn. */
+    /** Replace or clear the attention notice, starting a new command turn. */
     report: (notice: ParakeetNotice | undefined) => void;
+    /** Announce a transient message to every toast subscriber. */
+    toast: (toast: ParakeetToast) => void;
+    /** Receive transient messages; the renderer decides how to show them. */
+    subscribeToasts: (listener: (toast: ParakeetToast) => void) => () => void;
     /** Become the runtime's presenter until the returned disposer runs. */
     attach: (present: WhistleRuntime["present"]) => () => void;
     /** How the most recent interaction ended; a dismissal is not a failure to report. */
@@ -50,6 +65,6 @@ export type ParakeetInteractions = Readonly<{
 /**
  * Own how commands talk to the human. An interaction opens only when it asks
  * a question, hands off to a URL or shows progress; a command that just
- * reports a result leaves a one-line notice instead of a dialog.
+ * reports information emits a toast; ordinary success echoes are silent.
  */
 export declare function createParakeetInteractions(): ParakeetInteractions;

package/dist/commands/interactions.js

@@ -2,13 +2,23 @@ import { createWhistleInteractionHost, } from "@fungi.computer/whistle/interacti
 /**
  * Own how commands talk to the human. An interaction opens only when it asks
  * a question, hands off to a URL or shows progress; a command that just
- * reports a result leaves a one-line notice instead of a dialog.
+ * reports information emits a toast; ordinary success echoes are silent.
  */
 export function createParakeetInteractions() {
     let state = {};
     let sequence = 0;
     let lastEnd;
     const listeners = new Set();
+    const toastListeners = new Set();
+    const toast = (next) => {
+        for (const listener of toastListeners)
+            listener(next);
+    };
+    /** Information is a toast; a success only echoes what the person did. */
+    const announce = (message) => {
+        if (message.type === "info")
+            toast({ variant: "info", message: message.message });
+    };
     const publish = (next) => {
         state = next;
         for (const listener of listeners)
@@ -18,9 +28,10 @@ export function createParakeetInteractions() {
         if (state.open?.key === key)
             publish({ ...state, open: undefined });
     };
-    const presenter = ({ title, retry }) => {
+    const presenter = ({ title }) => {
         const key = ++sequence;
         let shown = false;
+        let hadRetryableFailure = false;
         const host = createWhistleInteractionHost({
             title,
             onEnd: (end) => {
@@ -32,35 +43,41 @@ export function createParakeetInteractions() {
                             ...state,
                             notice: { tone: "error", message: end.message },
                         });
-                    else if (message !== undefined && message.type !== "progress")
-                        publish({
-                            ...state,
-                            notice: {
-                                tone: message.type === "success" ? "success" : "info",
-                                message: message.message,
-                            },
-                        });
+                    else if (message !== undefined)
+                        announce(message);
                     return;
                 }
-                const lingers = end.status === "failed" ||
-                    (end.status === "handled" &&
-                        message !== undefined &&
-                        message.type !== "progress");
-                if (!lingers)
+                // A retried result stays in the same notice row until Done. A
+                // progress-only ending is not a completion notice to manufacture.
+                if (end.status === "handled" &&
+                    hadRetryableFailure &&
+                    message !== undefined &&
+                    message.type !== "progress")
+                    return;
+                const closing = host.snapshot().closing;
+                if (end.status === "cancelled" && closing !== undefined)
+                    announce(closing);
+                if (end.status === "handled" && message !== undefined)
+                    announce(message);
+                // Failed interactions retain their failure UI; ordinary results never
+                // leave a dialog behind just to confirm the completed action.
+                if (end.status !== "failed")
                     closeKey(key);
             },
         });
         const unsubscribe = host.subscribe(() => {
+            const current = host.snapshot();
+            if (current.retryable)
+                hadRetryableFailure = true;
             if (shown)
                 return;
-            const current = host.snapshot();
             if (current.prompt === undefined &&
                 current.handoff === undefined &&
                 current.message?.type !== "progress")
                 return;
             shown = true;
             const previous = state.open;
-            publish({ ...state, open: { key, host, retry }, notice: undefined });
+            publish({ ...state, open: { key, host }, notice: undefined });
             previous?.host.cancel();
         });
         const session = host.begin();
@@ -95,6 +112,13 @@ export function createParakeetInteractions() {
             lastEnd = undefined;
             publish({ ...state, notice });
         },
+        toast,
+        subscribeToasts: (listener) => {
+            toastListeners.add(listener);
+            return () => {
+                toastListeners.delete(listener);
+            };
+        },
         attach: (present) => present(presenter),
         lastEnd: () => lastEnd,
     };

package/dist/commands/run.d.ts

@@ -6,6 +6,7 @@ export declare function isCancelledOutcome(outcome: WhistleExecutionOutcome): bo
 /**
  * Run one composer draft: a prompt goes to `send`, a `/command` runs through
  * Whistle. A grammar that asks for a request id keeps the same id across
- * retries of the same draft until the command is handled.
+ * retries of the same draft until the command is handled. A slash projection
+ * can request draft consumption before dispatch, including while a dialog is open.
  */
-export declare function runSlashDraft(draft: string, commands: SlashRuntime, send: () => void, origin: WhistleExecutionOrigin): Promise<WhistleExecutionOutcome | undefined>;
+export declare function runSlashDraft(draft: string, commands: SlashRuntime, send: () => void, origin: WhistleExecutionOrigin, consumeDraft?: () => void): Promise<WhistleExecutionOutcome | undefined>;

package/dist/commands/run.js

@@ -12,9 +12,10 @@ export function isCancelledOutcome(outcome) {
 /**
  * Run one composer draft: a prompt goes to `send`, a `/command` runs through
  * Whistle. A grammar that asks for a request id keeps the same id across
- * retries of the same draft until the command is handled.
+ * retries of the same draft until the command is handled. A slash projection
+ * can request draft consumption before dispatch, including while a dialog is open.
  */
-export async function runSlashDraft(draft, commands, send, origin) {
+export async function runSlashDraft(draft, commands, send, origin, consumeDraft) {
     const parsed = parseSlashDraft(slashRegistry(commands.snapshot()), draft);
     if (parsed.kind === "prompt") {
         send();
@@ -26,6 +27,8 @@ export async function runSlashDraft(draft, commands, send, origin) {
             error: { code: "invalid_arguments", message: parsed.message },
         };
     const { command, requestIdField } = parsed;
+    if (command.consumesDraft && command.availability.status === "available")
+        consumeDraft?.();
     if (parsed.arguments === undefined)
         return commands.execute(command.commandId, { origin });
     if (requestIdField === undefined)

package/dist/commands/slash.d.ts

@@ -5,6 +5,8 @@ export type SlashCommand = Readonly<{
     alias: string;
     /** Canonical Whistle command identity. */
     commandId: string;
+    /** Consume this draft on dispatch, including for a dialog or refusal. */
+    consumesDraft?: boolean | undefined;
     /** Human-facing title. */
     title: string;
     /** Optional longer explanation. */

package/dist/commands/slash.js

@@ -1,12 +1,10 @@
 /** Human key labels from Whistle bindings, with the platform's modifier name. */
 export function keyLabel(binding, mac = /Mac|iPhone|iPad/u.test(globalThis.navigator.userAgent)) {
+    if (binding.startsWith("<leader>"))
+        return `Ctrl K ${binding.slice("<leader>".length)}`;
     return binding
         .split(" ")
-        .map((chord, index) => {
-        if (chord === "<leader>")
-            return "Ctrl K";
-        if (index > 0 && binding.startsWith("<leader> "))
-            return chord;
+        .map((chord) => {
         const parts = chord
             .split("+")
             .map((part) => part === "mod"
@@ -38,6 +36,7 @@ export function slashRegistry(snapshot) {
         category: row.category,
         order: row.order,
         grammar: row.arguments,
+        consumesDraft: row.consumesDraft,
         keys: keys.get(row.commandId) ?? [],
         availability: row.availability,
     }));
@@ -135,6 +134,7 @@ function rank(entries, text, query, order) {
         text(left.entry).localeCompare(text(right.entry)))
         .map(({ entry, match }) => ({ entry, indices: match.indices }));
 }
+const commonAliases = ["help", "login", "model"];
 /** Rank completions for one draft; renderers draw exactly these rows. */
 export function completeSlash(registry, draft, options = {}) {
     if (!draft.startsWith("/") || draft.includes("\n"))
@@ -144,11 +144,17 @@ export function completeSlash(registry, draft, options = {}) {
         const query = draft.slice(1);
         const items = rank(registry.filter((command) => command.availability.status === "available" &&
             (query.length === 0
-                ? command.category === (options.idleCategory ?? "Conversation")
+                ? command.category === (options.idleCategory ?? "Conversation") ||
+                    commonAliases.includes(command.alias)
                 : command.category !== "Advanced" ||
                     command.alias
                         .toLocaleLowerCase()
-                        .startsWith(query.toLocaleLowerCase()))), (command) => command.alias, query, (command) => command.order).map(({ entry, indices }) => ({
+                        .startsWith(query.toLocaleLowerCase()))), (command) => command.alias, query, (command) => {
+            const common = commonAliases.indexOf(command.alias);
+            return query.length === 0 && common >= 0
+                ? common - commonAliases.length
+                : command.order;
+        }).map(({ entry, indices }) => ({
             command: entry,
             label: `/${entry.alias}`,
             matches: indices.map((index) => index + 1),

package/dist/commands/use-slash-commands.js

@@ -70,7 +70,7 @@ export function useSlashCommands(options) {
             lease.dispose();
         };
     }, [commands, enabled, store, hasCommandPalette]);
-    const advertised = useMemo(() => advertisedCommands(commands, session, (entryId, commandId) => {
+    const advertised = useMemo(() => advertisedCommands(commands, session, () => contributionsRef.current, (entryId, commandId) => {
         const row = contributionsRef.current
             .find((entry) => entry.entryId === entryId)
             ?.value.panel.find((row) => row.inspection?.commandId === commandId);
@@ -91,7 +91,7 @@ export function useSlashCommands(options) {
                 tone: "error",
                 message: `${error.extensionId} commands are unavailable: ${error.message}`,
             });
-    }, [advertised, enabled, slots, store]);
+    }, [advertised, enabled, slots, contributions, store]);
     const registry = useMemo(() => slashRegistry(snapshot), [snapshot]);
     const [dismissed, setDismissed] = useState();
     const [highlighted, setHighlighted] = useState({ draft: "", index: 0 });
@@ -123,9 +123,9 @@ export function useSlashCommands(options) {
         store.report(undefined);
         setDismissed(submitted);
         void current
-            .submitCommand((captured) => runSlashDraft(captured, commands, () => {
+            .submitCommand((captured, consumeDraft) => runSlashDraft(captured, commands, () => {
             current.send(delivery);
-        }, origin))
+        }, origin, consumeDraft))
             .then((outcome) => {
             const message = failureMessage(outcome);
             if (message !== undefined &&

package/dist/components/AgentHead.d.ts

@@ -2,26 +2,23 @@ import type { Avatar } from "@fungi.computer/sprite/avatar";
 /** What the head is doing: at rest, working something out, or talking. */
 export type AgentHeadActivity = "idle" | "thinking" | "speaking";
 /**
- * An Agent's head at avatar size. Renders the Agent's own avatar when given
- * one; otherwise the pre-avatar seeded mushroom cap, byte-identical to
- * before avatars existed. The letter shows until a frame is ready. It holds
- * still unless `thinking` or `speaking`: an idle head whose render style is
- * "plain" and already has a cached still frame for its look never mounts a
- * live canvas, so a long rail is not a wall of animation. A render style
- * other than "plain" is a CSS filter over the live canvas, not part of the
- * captured pixels, so a styled head always stays live.
+ * An Agent's head at avatar size, drawn from the Agent's own avatar (a
+ * property of the Agent record, never of a conversation). The letter shows
+ * until a frame is ready. The live
+ * canvas stays mounted and is paused unless `thinking` or `speaking`, so an
+ * idle head shows its real look without animating.
  */
 export declare const AgentHead: import("react").NamedExoticComponent<{
+    /** External animation clock in milliseconds; omitted uses live motion. */
+    timeMs?: number;
     /** Motion presented by the head; defaults to idle. */
     activity?: AgentHeadActivity;
-    /** The Agent's stored avatar; omitted or `null` falls back to the seed. */
-    avatar?: Avatar | null;
+    /** The Agent's avatar, from its Agent record. */
+    avatar: Avatar;
     /** Host classes applied to the head container. */
     className?: string;
     /** The name whose first letter stands in until a frame is ready. */
     name: string;
-    /** Stable identity that picks the fallback cap colour. */
-    seed: string;
     /** Width and height in pixels. */
     size?: number;
 }>;